File class documentation

Hi,

I’ve been trying to learn about and use the ruby File class.

when I look at the documentation:

http://ruby-doc.org/core/classes/File.html

I cant see any mention that File < IO (it is a subclass and hence there
are
a whole load of useful methods)

viz:

http://ruby-doc.org/core/classes/IO.html

here… it DOES mention File as a subclass.

Am I doing something wrong or shouldnt the documentation be structured
to
list inherited methods… or maybe even the parent class would be a
start??

many many thanks for clearing this up for me :))

anyone? :slight_smile:

James O’Brien wrote:

I cant see any mention that File < IO (it is a subclass and hence there are
a whole load of useful methods)

FWIW,

$ ri File | head -n 1
File < IO

Hassan S. wrote:

$ ruby -v
ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0]
$ ri File | head -n 1
------------------------------------------------------------ Class: File
$ jruby --1.9 -S ri File | head -n 1
--------------------------------------------------- Class: File < Object
$

[ above from OS X (10.6.4) standard MRI Ruby and JRuby 1.5.0 ]

$ ruby -v
ruby 1.8.7 (2010-06-23 patchlevel 299) [x86_64-linux]
$ ri File | head -n 1
File < IO

On Wed, Jul 21, 2010 at 4:02 PM, Joel VanderWerf
[email protected] wrote:

FWIW,

$ ri File | head -n 1
File < IO

? in what environment?

$ ruby -v
ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0]
$ ri File | head -n 1
------------------------------------------------------------ Class: File
$ jruby --1.9 -S ri File | head -n 1
--------------------------------------------------- Class: File < Object
$

[ above from OS X (10.6.4) standard MRI Ruby and JRuby 1.5.0 ]

On Jul 21, 2010, at 1:39 , James O’Brien wrote:

Hi,

I’ve been trying to learn about and use the ruby File class.

when I look at the documentation:

class File - RDoc Documentation

I cant see any mention that File < IO (it is a subclass and hence there are
a whole load of useful methods)

Wow, that’s not helpful. That page looks nothing like my local HTML
documentation.

First sentence: “A File is an abstraction of any file object accessible
by the program and is closely associated with class IO. File includes
the methods of module FileTest as class methods, allowing you to write
(for example) File.exist?(“foo”).”

{dig dig}

Aha.

Don’t use the 1.8.6. core docs. At least not for File! Use at least the
1.8.7 ones.

On Wed, Jul 21, 2010 at 4:13 PM, Hassan S.
[email protected] wrote:

------------------------------------------------------------ Class: File
$ jruby --1.9 -S ri File | head -n 1
--------------------------------------------------- Class: File < Object

Heh, that makes no sense :slight_smile:

FWIW, we don’t ship ri docs for 1.8, so I’m not sure exactly where
this is coming from. Someone needs to hack a better single-file format
for rdoc; belching thousands of files to the filesystem and searching
them every time is pretty gross.

On the other hand, JRuby does have some interesting tweaks to ri:

~/projects/jruby âž” ri --java java.lang.String
----------------------------- Class: java.lang.String < java.lang.Object
(no description…)

Class methods:

 copyValueOf, format, valueOf

Instance methods:

 charAt, codePointAt, codePointBefore, codePointCount, compareTo,
 compareToIgnoreCase, concat, contains, contentEquals, endsWith,
 equals, equalsIgnoreCase, getBytes, getChars, getClass, hashCode,
 indexOf, intern, isEmpty, lastIndexOf, length, matches, notify,
 notifyAll, offsetByCodePoints, regionMatches, replace, replaceAll,
 replaceFirst, split, startsWith, subSequence, substring,
 toCharArray, toLowerCase, toString, toUpperCase, trim, wait
  • Charlie

On Wed, Jul 21, 2010 at 6:02 PM, Joel VanderWerf
[email protected] wrote:

James O’Brien wrote:

I cant see any mention that File < IO (it is a subclass and hence there
are
a whole load of useful methods)

FWIW,

$ ri File | head -n 1
File < IO

James was referring to class File - RDoc Documentation ,
which indeed does not tell about inheritance from IO anywhere in it.
That page is for Ruby 1.8.6, although you wouldn’t know it by looking.
To add to the confusion, that page seems to be actually describing
ftools.rb, which adds methods to File; not the File class itself.

For me, under 1.9.1p429 (RubyInstaller) under Windows, ri File says only
this:

(begin)
------------------------------------------------------- Class: File < IO
[no description]

Class methods:

 binread

(end)

ri IO shows:
(begin)
More than one method matched your request. You can refine your
search by asking for information on one of:

TkItemConfigMethod::IGNORE_UNKNOWN_CONFIGURE_OPTION [gem
tk_as_gem-0.1.0]
TkItemConfigMethod::set_IGNORE_UNKNOWN_CONFIGURE_OPTION! [gem
tk_as_gem-0.1.0]
(end)

Is something missing from my Ruby installation? The online version at
http://ruby-doc.org/ruby-1.9/classes/File.html is quite detailed.

Jruby 1.5 ri shows detailed information for File and IO, although
again its page for File is about ftools.rb, and it doesn’t say File <
IO. I get this both on Windows and Mac OS X. Charles, you don’t know
where this is coming from??

Finally, even though the 1.8.7 doc at
Class: File (Ruby 1.8.7) seems to describe the
actual class, when I run ri File in Mac OS X using 1.8.7 I also get
the spiel about ftools.rb instead of File per se.

On Wed, Jul 21, 2010 at 11:03 PM, Eric C.
[email protected] wrote:

Jruby 1.5 ri shows detailed information for File and IO, although
again its page for File is about ftools.rb, and it doesn’t say File <
IO. I get this both on Windows and Mac OS X. Charles, you don’t know
where this is coming from??

I don’t :frowning:

We ship with a pregenerated set of ri docs from 1.8.7, and that’s it.
Unfortunately ri/rdoc seems to be especially fragile in the context of
multiple source locations, so it’s not clear whether we’re doing
something wrong or whether it’s just finding things in a different
order.

  • Charlie

FWIW, you can do something like this, but it’s not really what the OP
was looking for (this is the public methods of the RubyFile class we
use to implement File):

~ âž” ri --java org.jruby.RubyFile
--------------------------- Class: org.jruby.RubyFile < org.jruby.RubyIO
(no description…)

Class methods:

 absolute_path, atime, basename, chmod, chown, copy_stream,
 createBasicObjectClass, createFileClass, createIOClass,
 createObjectClass, ctime, dirname, expandUserPath, expand_path,
 extname, failIfDirectory, file, fnmatch, foreach, foreach19, ftype,
 getDirOrFileEntry, getFileEntry, getIOModes,
 getIOModesIntFromString, getNewFileno, get_path, join, lchmod,
 lchown, link, lstat, method_missing19, mtime, newIO, newInstance,
 obliterateProcess, open, path, pipe, popen, popen3, popen4,
 popenSpecial, print, putc, puts, read, read19, readlines, readlink,
 realdirpath, realpath, rename, restartSystemCall, select,
 select_static, singleton_method_added19,
 singleton_method_removed19, singleton_method_undefined19, split,
 stat, symlink, sysopen, truncate, truncate19, tryConvert, umask,
 unlink, utime

Instance methods:

 addBlockingThread, addFinalizer, anyToString, asJavaString,
 asString, atime, attachToObjectSpace, binmode, bytes, callInit,
 callMethod, callSuper, chars19, checkArrayType, checkCallMethod,
 checkStringType, checkStringType19, chmod, chown, close,
 close_read, close_write, closed_p, compareTo, convertToArray,
 convertToFloat, convertToHash, convertToInteger, convertToString,
 convertToType, copyInstanceVariablesInto,
 copySpecialInstanceVariables, ctime, ctl, dataGetStruct,
 dataGetStructChecked, dataWrapStruct, display, dup, each19,
 each_byte, each_byte19, each_char, each_char19, each_line,
 each_line19, eof_p, eql, eql_p, equal_p, equal_p19, equals,
 evalUnder, extend, external_encoding, fastGetInstanceVariable,
 fastGetInternalVariable, fastHasInstanceVariable,
 fastHasInternalVariable, fastSetInstanceVariable,
 fastSetInternalVariable, fcntl, fileno, flock, flush, freeze,
 frozen_p, fsync, getBlocking, getChannel, getClass,
 getDescriptorByFileno, getEncoding, getFlag, getHandler,
 getInStream, getInstanceVariable, getInstanceVariableList,
 getInstanceVariableNameList, getInstanceVariables,
 getInternalVariable, getInternalVariables, getJavaClass,
 getMetaClass, getNativeTypeIndex, getOpenFile, getOutStream,
 getPath, getRuntime, getSingletonClass, getType, getVariable,
 getVariableCount, getVariableList, getVariableNameList, getc,
 getline, gets, gets19, hasInstanceVariable, hasInternalVariable,
 hasVariables, hash, hashCode, hashyInspect, id, id_deprecated,
 infectBy, initialize, initialize19, initialize_copy, inspect,
 instance_eval, instance_eval19, instance_exec, instance_exec19,
 instance_of_p, instance_variable_defined_p, instance_variable_get,
 instance_variable_set, instance_variables, instance_variables19,
 internal_encoding, ioctl, isBuiltin, isClass, isClosed, isFalse,
 isFrozen, isImmediate, isModule, isNil, isTaint, isTrue,
 isUntrusted, kind_of_p, lchmod, lchown, lineno, lineno_set, lines,
 lstat, makeMetaClass, method, methods, methods19, mtime, nil_p,
 notify, notifyAll, op_append, op_binmode, op_cmp, op_eqq, op_equal,
 op_equal_19, op_match, op_match19, op_not, op_not_equal,
 op_not_match, path, pid, pos, pos_set, print, printf,
 private_methods, private_methods19, protected_methods,
 protected_methods19, public_methods, public_methods19, putc, puts,
 rbClone, read, read_nonblock, readchar, readline, readlines,
 readpartial, registerDescriptor, removeBlockingThread,
 removeFinalizers, removeInstanceVariable, removeInternalVariable,
 remove_instance_variable, reopen, respond_to_p, respond_to_p19,
 respondsTo, rewind, seek, send, send19, setFlag, setFrozen,
 setInstanceVariable, setInternalVariable, setMetaClass, setTaint,
 setUntrusted, setVariable, set_encoding, singletonMethods,
 singleton_methods, singleton_methods19, size, specificEval, stat,
 sync, syncVariables, sync_set, sysread, sysseek, syswrite, taint,
 tainted_p, toJava, toString, to_a, to_io, to_s, truncate, trust,
 tty_p, type, type_deprecated, ungetc, unregisterDescriptor,
 untaint, untrust, untrusted_p, wait, write, writeDataBuffered,
 write_nonblock

On Thu, Jul 22, 2010 at 1:47 AM, Charles Oliver N.

On Jul 21, 2010, at 23:03 , Eric C. wrote:

Finally, even though the 1.8.7 doc at
Class: File (Ruby 1.8.7) seems to describe the
actual class, when I run ri File in Mac OS X using 1.8.7 I also get
the spiel about ftools.rb instead of File per se.

Wow. So do I. That’s worse than useless. I never use the ri docs myself.
At some point or other, probably under OSX 10.4, I built a copy of Ruby
1.8.7, and put the HTML version of the documentation where I could find
it, and I always reference my local files for documentation.

I cannot tell you any more which build of 1.8.7 I used, since I deleted
the source directory some time after installing OSX 10.6. {shrug}