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:

···

On Wed, Jul 21, 2010 at 9:39 AM, James O'Brien <jeob32@gmail.com> 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)

viz:

class IO - RDoc Documentation

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 :))

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 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)

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

? 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 Wed, Jul 21, 2010 at 4:02 PM, Joel VanderWerf <joelvanderwerf@gmail.com> wrote:

FWIW,

$ ri File | head -n 1
File < IO

--
Hassan Schroeder ------------------------ hassan.schroeder@gmail.com
twitter: @hassan

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]

···

On Wed, Jul 21, 2010 at 6:02 PM, Joel VanderWerf <joelvanderwerf@gmail.com> 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

------------------------------------------------------------------------

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.

Hassan Schroeder wrote:

···

On Wed, Jul 21, 2010 at 4:02 PM, Joel VanderWerf > <joelvanderwerf@gmail.com> 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 ]

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

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...)

···

On Wed, Jul 21, 2010 at 4:13 PM, Hassan Schroeder <hassan.schroeder@gmail.com> wrote:

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

------------------------------------------------------------------------

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

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}

···

On Jul 21, 2010, at 23:03 , Eric Christopherson 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.

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

···

On Wed, Jul 21, 2010 at 11:03 PM, Eric Christopherson <echristopherson@gmail.com> 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??

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 Nutter <headius@headius.com> wrote:

On Wed, Jul 21, 2010 at 11:03 PM, Eric Christopherson > <echristopherson@gmail.com> 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