diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | ext/pathname/lib/pathname.rb | 137 | ||||
| -rw-r--r-- | ext/pathname/pathname.c | 325 |
3 files changed, 320 insertions, 148 deletions
@@ -1,3 +1,9 @@ +Wed Sep 12 22:45::00 2012 Zachary Scott <zzak@ruby-lang.org> + + * ext/pathname/lib/pathname.rb: Documentation for Pathname. + * ext/pathname/pathname.c: ditto. + [Bug #6947] [ruby-core:47354] + Mon Sep 10 10:19:34 2012 NAKAMURA Usaku <usa@ruby-lang.org> * enc/depend: fixed wrong change in a part of r34802. diff --git a/ext/pathname/lib/pathname.rb b/ext/pathname/lib/pathname.rb index 4909c2dc23..fba1074320 100644 --- a/ext/pathname/lib/pathname.rb +++ b/ext/pathname/lib/pathname.rb @@ -8,8 +8,6 @@ # # For documentation, see class Pathname. # -# <tt>pathname.rb</tt> is distributed with Ruby since 1.8.0. -# require 'pathname.so' @@ -29,7 +27,6 @@ class Pathname proc {|a, b| a == b} end - # :startdoc: if File::ALT_SEPARATOR SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}" @@ -39,6 +36,8 @@ class Pathname SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/ end + # :startdoc: + # chop_basename(path) -> [pre-basename, basename] or nil def chop_basename(path) base = File.basename(path) @@ -78,9 +77,11 @@ class Pathname # removed. The filesystem is not accessed. # # If +consider_symlink+ is +true+, then a more conservative algorithm is used - # to avoid breaking symbolic linkages. This may retain more <tt>..</tt> + # to avoid breaking symbolic linkages. This may retain more +..+ # entries than absolutely necessary, but without accessing the filesystem, - # this can't be avoided. See #realpath. + # this can't be avoided. + # + # See Pathname#realpath. # def cleanpath(consider_symlink=false) if consider_symlink @@ -91,7 +92,7 @@ class Pathname end # - # Clean the path simply by resolving and removing excess "." and ".." entries. + # Clean the path simply by resolving and removing excess +.+ and +..+ entries. # Nothing more, nothing less. # def cleanpath_aggressive @@ -179,14 +180,14 @@ class Pathname end private :cleanpath_conservative - # #parent returns the parent directory. + # Returns the parent directory. # - # This is same as <tt>self + '..'</tt>. + # This is same as <code>self + '..'</code>. def parent self + '..' end - # #mountpoint? returns +true+ if <tt>self</tt> points to a mountpoint. + # Returns +true+ if +self+ points to a mountpoint. def mountpoint? begin stat1 = self.lstat @@ -199,10 +200,10 @@ class Pathname end # - # #root? is a predicate for root directories. I.e. it returns +true+ if the + # Predicate method for root directories. Returns +true+ if the # pathname consists of consecutive slashes. # - # It doesn't access actual filesystem. So it may return +false+ for some + # It doesn't access the filesystem. So it may return +false+ for some # pathnames which points to roots such as <tt>/usr/..</tt>. # def root? @@ -210,12 +211,31 @@ class Pathname end # Predicate method for testing whether a path is absolute. + # # It returns +true+ if the pathname begins with a slash. + # + # p = Pathname.new('/im/sure') + # p.absolute? + # #=> true + # + # p = Pathname.new('not/so/sure') + # p.absolute? + # #=> false def absolute? !relative? end - # The opposite of #absolute? + # The opposite of Pathname#absolute? + # + # It returns +false+ if the pathname begins with a slash. + # + # p = Pathname.new('/im/sure') + # p.relative? + # #=> false + # + # p = Pathname.new('not/so/sure') + # p.relative? + # #=> true def relative? path = @path while r = chop_basename(path) @@ -230,6 +250,13 @@ class Pathname # Pathname.new("/usr/bin/ruby").each_filename {|filename| ... } # # yields "usr", "bin", and "ruby". # + # Returns an Enumerator if no block was given. + # + # enum = Pathname.new("/usr/bin/ruby").each_filename + # # ... do stuff ... + # enum.each { |e| ... } + # # yields "usr", "bin", and "ruby". + # def each_filename # :yield: filename return to_enum(__method__) unless block_given? _, names = split_names(@path) @@ -253,9 +280,7 @@ class Pathname # #<Pathname:path/to/some> # #<Pathname:path/to/some/file.rb> # - # It doesn't access actual filesystem. - # - # This method is available since 1.8.5. + # It doesn't access the filesystem. # def descend vs = [] @@ -280,9 +305,7 @@ class Pathname # #<Pathname:path/to> # #<Pathname:path> # - # It doesn't access actual filesystem. - # - # This method is available since 1.8.5. + # It doesn't access the filesystem. # def ascend path = @path @@ -295,8 +318,7 @@ class Pathname end # - # Pathname#+ appends a pathname fragment to this one to produce a new Pathname - # object. + # Appends a pathname fragment to +self+ to produce a new Pathname object. # # p1 = Pathname.new("/usr") # Pathname:/usr # p2 = p1 + "bin/ruby" # Pathname:/usr/bin/ruby @@ -352,10 +374,14 @@ class Pathname private :plus # - # Pathname#join joins pathnames. + # Joins the given pathnames onto +self+ to create a new Pathname object. # - # <tt>path0.join(path1, ..., pathN)</tt> is the same as - # <tt>path0 + path1 + ... + pathN</tt>. + # path0 = Pathname.new("/usr") # Pathname:/usr + # path0 = path0.join("bin/ruby") # Pathname:/usr/bin/ruby + # # is the same as + # path1 = Pathname.new("/usr") + "bin/ruby" # Pathname:/usr/bin/ruby + # path0 == path1 + # #=> true # def join(*args) args.unshift self @@ -372,10 +398,11 @@ class Pathname # # Returns the children of the directory (files and subdirectories, not - # recursive) as an array of Pathname objects. By default, the returned - # pathnames will have enough information to access the files. If you set - # +with_directory+ to +false+, then the returned pathnames will contain the - # filename only. + # recursive) as an array of Pathname objects. + # + # By default, the returned pathnames will have enough information to access + # the files. If you set +with_directory+ to +false+, then the returned + # pathnames will contain the filename only. # # For example: # pn = Pathname("/usr/lib/ruby/1.8") @@ -386,11 +413,9 @@ class Pathname # pn.children(false) # # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ] # - # Note that the results never contain the entries <tt>.</tt> and <tt>..</tt> in + # Note that the results never contain the entries +.+ and +..+ in # the directory because they are not children. # - # This method has existed since 1.8.1. - # def children(with_directory=true) with_directory = false if @path == '.' result = [] @@ -407,9 +432,14 @@ class Pathname # Iterates over the children of the directory # (files and subdirectories, not recursive). + # # It yields Pathname object for each child. - # By default, the yielded pathnames will have enough information to access the files. - # If you set +with_directory+ to +false+, then the returned pathnames will contain the filename only. + # + # By default, the yielded pathnames will have enough information to access + # the files. + # + # If you set +with_directory+ to +false+, then the returned pathnames will + # contain the filename only. # # Pathname("/usr/local").each_child {|f| p f } # #=> #<Pathname:/usr/local/share> @@ -431,20 +461,25 @@ class Pathname # # #<Pathname:src> # # #<Pathname:man> # + # Note that the results never contain the entries +.+ and +..+ in + # the directory because they are not children. + # + # See Pathname#children + # def each_child(with_directory=true, &b) children(with_directory).each(&b) end # - # #relative_path_from returns a relative path from the argument to the - # receiver. If +self+ is absolute, the argument must be absolute too. If - # +self+ is relative, the argument must be relative too. + # Returns a relative path from the given +base_directory+ to the receiver. # - # #relative_path_from doesn't access the filesystem. It assumes no symlinks. + # If +self+ is absolute, then +base_directory+ must be absolute too. # - # ArgumentError is raised when it cannot find a relative path. + # If +self+ is relative, then +base_directory+ must be relative too. # - # This method has existed since 1.8.1. + # This method doesn't access the filesystem. It assumes no symlinks. + # + # ArgumentError is raised when it cannot find a relative path. # def relative_path_from(base_directory) dest_directory = self.cleanpath.to_s @@ -486,16 +521,18 @@ end class Pathname # * Find * # - # Pathname#find is an iterator to traverse a directory tree in a depth first - # manner. It yields a Pathname for each file under "this" directory. + # Iterates over the directory tree in a depth first manner, yielding a + # Pathname for each file under "this" directory. # - # Returns an enumerator if no block is given. + # Returns an Enumerator if no block is given. # - # Since it is implemented by <tt>find.rb</tt>, <tt>Find.prune</tt> can be used - # to control the traversal. + # Since it is implemented by the standard library module Find, Find.prune can + # be used to control the traversal. # - # If +self+ is <tt>.</tt>, yielded pathnames begin with a filename in the - # current directory, not <tt>./</tt>. + # If +self+ is +.+, yielded pathnames begin with a filename in the + # current directory, not +./+. + # + # See Find.find # def find # :yield: pathname return to_enum(__method__) unless block_given? @@ -510,15 +547,19 @@ end class Pathname # * FileUtils * - # See <tt>FileUtils.mkpath</tt>. Creates a full path, including any - # intermediate directories that don't yet exist. + # Creates a full path, including any intermediate directories that don't yet + # exist. + # + # See FileUtils.mkpath and FileUtils.mkdir_p def mkpath require 'fileutils' FileUtils.mkpath(@path) nil end - # See <tt>FileUtils.rm_r</tt>. Deletes a directory and all beneath it. + # Recursively deletes a directory, including all directories beneath it. + # + # See FileUtils.rm_r def rmtree # The name "rmtree" is borrowed from File::Path of Perl. # File::Path provides "mkpath" and "rmtree". diff --git a/ext/pathname/pathname.c b/ext/pathname/pathname.c index f890019cf9..dd1c5f8878 100644 --- a/ext/pathname/pathname.c +++ b/ext/pathname/pathname.c @@ -22,7 +22,7 @@ set_strpath(VALUE obj, VALUE val) /* * Create a Pathname object from the given String (or String-like object). - * If +path+ contains a NUL character (<tt>\0</tt>), an ArgumentError is raised. + * If +path+ contains a NULL character (<tt>\0</tt>), an ArgumentError is raised. */ static VALUE path_initialize(VALUE self, VALUE arg) @@ -46,6 +46,14 @@ path_initialize(VALUE self, VALUE arg) return self; } +/* + * call-seq: + * pathname.freeze -> obj + * + * Freezes this Pathname. + * + * See Object.freeze. + */ static VALUE path_freeze(VALUE self) { @@ -54,6 +62,14 @@ path_freeze(VALUE self) return self; } +/* + * call-seq: + * pathname.taint -> obj + * + * Taints this Pathname. + * + * See Object.taint. + */ static VALUE path_taint(VALUE self) { @@ -62,6 +78,14 @@ path_taint(VALUE self) return self; } +/* + * call-seq: + * pathname.untaint -> obj + * + * Untaints this Pathname. + * + * See Object.untaint. + */ static VALUE path_untaint(VALUE self) { @@ -84,7 +108,18 @@ path_eq(VALUE self, VALUE other) } /* - * Provides for comparing pathnames, case-sensitively. + * Provides a case-sensitive comparison operator for pathnames. + * + * Pathname.new('/usr') <=> Pathname.new('/usr/bin') + * #=> -1 + * Pathname.new('/usr/bin') <=> Pathname.new('/usr/bin') + * #=> 0 + * Pathname.new('/usr/bin') <=> Pathname.new('/USR/BIN') + * #=> 1 + * + * It will return +-1+, +0+ or +1+ depending on the value of the left argument + * relative to the right argument. Or it will return +nil+ if the arguments + * are not comparable. */ static VALUE path_cmp(VALUE self, VALUE other) @@ -153,6 +188,10 @@ path_inspect(VALUE self) /* * Return a pathname which is substituted by String#sub. + * + * path1 = Pathname.new('/usr/bin/perl') + * path1.sub('perl', 'ruby') + * #=> #<Pathname:/usr/bin/ruby> */ static VALUE path_sub(int argc, VALUE *argv, VALUE self) @@ -169,10 +208,12 @@ path_sub(int argc, VALUE *argv, VALUE self) } /* - * Return a pathname which the extension of the basename is substituted by - * <i>repl</i>. + * Return a pathname with +repl+ added as a suffix to the basename. * - * If self has no extension part, <i>repl</i> is appended. + * If self has no extension part, +repl+ is appended. + * + * Pathname.new('/usr/bin/shutdown').sub_ext('.rb') + * #=> #<Pathname:/usr/bin/shutdown.rb> */ static VALUE path_sub_ext(VALUE self, VALUE repl) @@ -202,8 +243,10 @@ path_sub_ext(VALUE self, VALUE repl) /* Facade for File */ /* - * Returns the real (absolute) pathname of +self+ in the actual - * filesystem not containing symlinks or useless dots. + * Returns the real (absolute) pathname for +self+ in the actual + * filesystem. + * + * Does not contain symlinks or useless dots, +..+ and +.+. * * All components of the pathname must exist when this method is * called. @@ -220,7 +263,8 @@ path_realpath(int argc, VALUE *argv, VALUE self) /* * Returns the real (absolute) pathname of +self+ in the actual filesystem. - * The real pathname doesn't contain symlinks or useless dots. + * + * Does not contain symlinks or useless dots, +..+ and +.+. * * The last component of the real pathname can be nonexistent. */ @@ -241,10 +285,7 @@ path_realdirpath(int argc, VALUE *argv, VALUE self) * pathname.each_line(sep, limit [, open_args]) {|line| block } -> nil * pathname.each_line(...) -> an_enumerator * - * #each_line iterates over the line in the file. It yields a String object - * for each line. - * - * This method is availabel since 1.8.1. + * Iterates over each line in the file and yields a String object for each. */ static VALUE path_each_line(int argc, VALUE *argv, VALUE self) @@ -267,8 +308,9 @@ path_each_line(int argc, VALUE *argv, VALUE self) * pathname.read([length [, offset]]) -> string * pathname.read([length [, offset]], open_args) -> string * - * See <tt>IO.read</tt>. Returns all data from the file, or the first +N+ bytes - * if specified. + * Returns all data from the file, or the first +N+ bytes if specified. + * + * See IO.read. * */ static VALUE @@ -286,8 +328,9 @@ path_read(int argc, VALUE *argv, VALUE self) * call-seq: * pathname.binread([length [, offset]]) -> string * - * See <tt>IO.binread</tt>. Returns all the bytes from the file, or the first +N+ - * if specified. + * Returns all the bytes from the file, or the first +N+ if specified. + * + * See IO.binread. * */ static VALUE @@ -307,7 +350,9 @@ path_binread(int argc, VALUE *argv, VALUE self) * pathname.readlines(limit [, open_args]) -> array * pathname.readlines(sep, limit [, open_args]) -> array * - * See <tt>IO.readlines</tt>. Returns all the lines from the file. + * Returns all the lines from the file. + * + * See IO.readlines. * */ static VALUE @@ -325,7 +370,7 @@ path_readlines(int argc, VALUE *argv, VALUE self) * call-seq: * pathname.sysopen([mode, [perm]]) -> fixnum * - * See <tt>IO.sysopen</tt>. + * See IO.sysopen. * */ static VALUE @@ -340,7 +385,12 @@ path_sysopen(int argc, VALUE *argv, VALUE self) } /* - * See <tt>File.atime</tt>. Returns last access time. + * call-seq: + * pathname.atime -> time + * + * Returns the last access time for the file. + * + * See File.atime. */ static VALUE path_atime(VALUE self) @@ -349,7 +399,12 @@ path_atime(VALUE self) } /* - * See <tt>File.ctime</tt>. Returns last (directory entry, not file) change time. + * call-seq: + * pathname.ctime -> time + * + * Returns the last change time, using directory information, not the file itself. + * + * See File.ctime. */ static VALUE path_ctime(VALUE self) @@ -358,7 +413,12 @@ path_ctime(VALUE self) } /* - * See <tt>File.mtime</tt>. Returns last modification time. + * call-seq: + * pathname.mtime -> time + * + * Returns the last modified time of the file. + * + * See File.mtime. */ static VALUE path_mtime(VALUE self) @@ -367,7 +427,12 @@ path_mtime(VALUE self) } /* - * See <tt>File.chmod</tt>. Changes permissions. + * call-seq: + * pathname.chmod -> integer + * + * Changes file permissions. + * + * See File.chmod. */ static VALUE path_chmod(VALUE self, VALUE mode) @@ -376,7 +441,12 @@ path_chmod(VALUE self, VALUE mode) } /* - * See <tt>File.lchmod</tt>. + * call-seq: + * pathname.lchmod -> integer + * + * Same as Pathname.chmod, but does not follow symbolic links. + * + * See File.lchmod. */ static VALUE path_lchmod(VALUE self, VALUE mode) @@ -385,7 +455,12 @@ path_lchmod(VALUE self, VALUE mode) } /* - * See <tt>File.chown</tt>. Change owner and group of file. + * call-seq: + * pathname.chown -> integer + * + * Change owner and group of the file. + * + * See File.chown. */ static VALUE path_chown(VALUE self, VALUE owner, VALUE group) @@ -394,7 +469,12 @@ path_chown(VALUE self, VALUE owner, VALUE group) } /* - * See <tt>File.lchown</tt>. + * call-seq: + * pathname.lchown -> integer + * + * Same as Pathname.chown, but does not follow symbolic links. + * + * See File.lchown. */ static VALUE path_lchown(VALUE self, VALUE owner, VALUE group) @@ -407,8 +487,9 @@ path_lchown(VALUE self, VALUE owner, VALUE group) * pathname.fnmatch(pattern, [flags]) -> string * pathname.fnmatch?(pattern, [flags]) -> string * - * See <tt>File.fnmatch</tt>. Return +true+ if the receiver matches the given - * pattern. + * Return +true+ if the receiver matches the given pattern. + * + * See File.fnmatch. */ static VALUE path_fnmatch(int argc, VALUE *argv, VALUE self) @@ -422,8 +503,12 @@ path_fnmatch(int argc, VALUE *argv, VALUE self) } /* - * See <tt>File.ftype</tt>. Returns "type" of file ("file", "directory", - * etc). + * call-seq: + * pathname.ftype -> string + * + * Returns "type" of file ("file", "directory", etc). + * + * See File.ftype. */ static VALUE path_ftype(VALUE self) @@ -435,7 +520,9 @@ path_ftype(VALUE self) * call-seq: * pathname.make_link(old) * - * See <tt>File.link</tt>. Creates a hard link at _pathname_. + * Creates a hard link at _pathname_. + * + * See File.link. */ static VALUE path_make_link(VALUE self, VALUE old) @@ -444,7 +531,9 @@ path_make_link(VALUE self, VALUE old) } /* - * See <tt>File.open</tt>. Opens the file for reading or writing. + * Opens the file for reading or writing. + * + * See File.open. */ static VALUE path_open(int argc, VALUE *argv, VALUE self) @@ -463,7 +552,9 @@ path_open(int argc, VALUE *argv, VALUE self) } /* - * See <tt>File.readlink</tt>. Read symbolic link. + * Read symbolic link. + * + * See File.readlink. */ static VALUE path_readlink(VALUE self) @@ -474,7 +565,9 @@ path_readlink(VALUE self) } /* - * See <tt>File.rename</tt>. Rename the file. + * Rename the file. + * + * See File.rename. */ static VALUE path_rename(VALUE self, VALUE to) @@ -483,7 +576,9 @@ path_rename(VALUE self, VALUE to) } /* - * See <tt>File.stat</tt>. Returns a <tt>File::Stat</tt> object. + * Returns a File::Stat object. + * + * See File.stat. */ static VALUE path_stat(VALUE self) @@ -492,7 +587,7 @@ path_stat(VALUE self) } /* - * See <tt>File.lstat</tt>. + * See File.lstat. */ static VALUE path_lstat(VALUE self) @@ -504,7 +599,9 @@ path_lstat(VALUE self) * call-seq: * pathname.make_symlink(old) * - * See <tt>File.symlink</tt>. Creates a symbolic link. + * Creates a symbolic link. + * + * See File.symlink. */ static VALUE path_make_symlink(VALUE self, VALUE old) @@ -513,7 +610,9 @@ path_make_symlink(VALUE self, VALUE old) } /* - * See <tt>File.truncate</tt>. Truncate the file to +length+ bytes. + * Truncates the file to +length+ bytes. + * + * See File.truncate. */ static VALUE path_truncate(VALUE self, VALUE length) @@ -522,7 +621,9 @@ path_truncate(VALUE self, VALUE length) } /* - * See <tt>File.utime</tt>. Update the access and modification times. + * Update the access and modification times of the file. + * + * See File.utime. */ static VALUE path_utime(VALUE self, VALUE atime, VALUE mtime) @@ -531,7 +632,9 @@ path_utime(VALUE self, VALUE atime, VALUE mtime) } /* - * See <tt>File.basename</tt>. Returns the last component of the path. + * Returns the last component of the path. + * + * See File.basename. */ static VALUE path_basename(int argc, VALUE *argv, VALUE self) @@ -546,7 +649,9 @@ path_basename(int argc, VALUE *argv, VALUE self) } /* - * See <tt>File.dirname</tt>. Returns all but the last component of the path. + * Returns all but the last component of the path. + * + * See File.dirname. */ static VALUE path_dirname(VALUE self) @@ -557,7 +662,9 @@ path_dirname(VALUE self) } /* - * See <tt>File.extname</tt>. Returns the file's extension. + * Returns the file's extension. + * + * See File.extname. */ static VALUE path_extname(VALUE self) @@ -567,7 +674,9 @@ path_extname(VALUE self) } /* - * See <tt>File.expand_path</tt>. + * Returns the absolute path for the file. + * + * See File.expand_path. */ static VALUE path_expand_path(int argc, VALUE *argv, VALUE self) @@ -582,7 +691,9 @@ path_expand_path(int argc, VALUE *argv, VALUE self) } /* - * See <tt>File.split</tt>. Returns the #dirname and the #basename in an Array. + * Returns the #dirname and the #basename in an Array. + * + * See File.split. */ static VALUE path_split(VALUE self) @@ -599,7 +710,7 @@ path_split(VALUE self) } /* - * See <tt>FileTest.blockdev?</tt>. + * See FileTest.blockdev?. */ static VALUE path_blockdev_p(VALUE self) @@ -608,7 +719,7 @@ path_blockdev_p(VALUE self) } /* - * See <tt>FileTest.chardev?</tt>. + * See FileTest.chardev?. */ static VALUE path_chardev_p(VALUE self) @@ -617,7 +728,7 @@ path_chardev_p(VALUE self) } /* - * See <tt>FileTest.executable?</tt>. + * See FileTest.executable?. */ static VALUE path_executable_p(VALUE self) @@ -626,7 +737,7 @@ path_executable_p(VALUE self) } /* - * See <tt>FileTest.executable_real?</tt>. + * See FileTest.executable_real?. */ static VALUE path_executable_real_p(VALUE self) @@ -635,7 +746,7 @@ path_executable_real_p(VALUE self) } /* - * See <tt>FileTest.exist?</tt>. + * See FileTest.exist?. */ static VALUE path_exist_p(VALUE self) @@ -644,7 +755,7 @@ path_exist_p(VALUE self) } /* - * See <tt>FileTest.grpowned?</tt>. + * See FileTest.grpowned?. */ static VALUE path_grpowned_p(VALUE self) @@ -653,7 +764,7 @@ path_grpowned_p(VALUE self) } /* - * See <tt>FileTest.directory?</tt>. + * See FileTest.directory?. */ static VALUE path_directory_p(VALUE self) @@ -662,7 +773,7 @@ path_directory_p(VALUE self) } /* - * See <tt>FileTest.file?</tt>. + * See FileTest.file?. */ static VALUE path_file_p(VALUE self) @@ -671,7 +782,7 @@ path_file_p(VALUE self) } /* - * See <tt>FileTest.pipe?</tt>. + * See FileTest.pipe?. */ static VALUE path_pipe_p(VALUE self) @@ -680,7 +791,7 @@ path_pipe_p(VALUE self) } /* - * See <tt>FileTest.socket?</tt>. + * See FileTest.socket?. */ static VALUE path_socket_p(VALUE self) @@ -689,7 +800,7 @@ path_socket_p(VALUE self) } /* - * See <tt>FileTest.owned?</tt>. + * See FileTest.owned?. */ static VALUE path_owned_p(VALUE self) @@ -698,7 +809,7 @@ path_owned_p(VALUE self) } /* - * See <tt>FileTest.readable?</tt>. + * See FileTest.readable?. */ static VALUE path_readable_p(VALUE self) @@ -707,7 +818,7 @@ path_readable_p(VALUE self) } /* - * See <tt>FileTest.world_readable?</tt>. + * See FileTest.world_readable?. */ static VALUE path_world_readable_p(VALUE self) @@ -716,7 +827,7 @@ path_world_readable_p(VALUE self) } /* - * See <tt>FileTest.readable_real?</tt>. + * See FileTest.readable_real?. */ static VALUE path_readable_real_p(VALUE self) @@ -725,7 +836,7 @@ path_readable_real_p(VALUE self) } /* - * See <tt>FileTest.setuid?</tt>. + * See FileTest.setuid?. */ static VALUE path_setuid_p(VALUE self) @@ -734,7 +845,7 @@ path_setuid_p(VALUE self) } /* - * See <tt>FileTest.setgid?</tt>. + * See FileTest.setgid?. */ static VALUE path_setgid_p(VALUE self) @@ -743,7 +854,7 @@ path_setgid_p(VALUE self) } /* - * See <tt>FileTest.size</tt>. + * See FileTest.size. */ static VALUE path_size(VALUE self) @@ -752,7 +863,7 @@ path_size(VALUE self) } /* - * See <tt>FileTest.size?</tt>. + * See FileTest.size?. */ static VALUE path_size_p(VALUE self) @@ -761,7 +872,7 @@ path_size_p(VALUE self) } /* - * See <tt>FileTest.sticky?</tt>. + * See FileTest.sticky?. */ static VALUE path_sticky_p(VALUE self) @@ -770,7 +881,7 @@ path_sticky_p(VALUE self) } /* - * See <tt>FileTest.symlink?</tt>. + * See FileTest.symlink?. */ static VALUE path_symlink_p(VALUE self) @@ -779,7 +890,7 @@ path_symlink_p(VALUE self) } /* - * See <tt>FileTest.writable?</tt>. + * See FileTest.writable?. */ static VALUE path_writable_p(VALUE self) @@ -788,7 +899,7 @@ path_writable_p(VALUE self) } /* - * See <tt>FileTest.world_writable?</tt>. + * See FileTest.world_writable?. */ static VALUE path_world_writable_p(VALUE self) @@ -797,7 +908,7 @@ path_world_writable_p(VALUE self) } /* - * See <tt>FileTest.writable_real?</tt>. + * See FileTest.writable_real?. */ static VALUE path_writable_real_p(VALUE self) @@ -806,7 +917,7 @@ path_writable_real_p(VALUE self) } /* - * See <tt>FileTest.zero?</tt>. + * See FileTest.zero?. */ static VALUE path_zero_p(VALUE self) @@ -821,7 +932,12 @@ glob_i(VALUE elt, VALUE klass, int argc, VALUE *argv) } /* - * See <tt>Dir.glob</tt>. Returns or yields Pathname objects. + * Returns or yields Pathname objects. + * + * Pathname.glob("config/*.rb") + * #=> [#<Pathname:config/environment.rb>, #<Pathname:config/routes.rb>, ..] + * + * See Dir.glob. */ static VALUE path_s_glob(int argc, VALUE *argv, VALUE klass) @@ -848,7 +964,12 @@ path_s_glob(int argc, VALUE *argv, VALUE klass) } /* - * See <tt>Dir.getwd</tt>. Returns the current working directory as a Pathname. + * Returns the current working directory as a Pathname. + * + * Pathname.getwd + * #=> #<Pathname:/home/zzak/projects/ruby> + * + * See Dir.getwd. */ static VALUE path_s_getwd(VALUE klass) @@ -862,13 +983,8 @@ path_s_getwd(VALUE klass) * Return the entries (files and subdirectories) in the directory, each as a * Pathname object. * - * The result contains just a filename which has no directory. - * - * The result may contain the current directory #<Pathname:.> and the parent - * directory #<Pathname:..>. - * - * If you don't want #<Pathname:.> and #<Pathname:..> and - * want directory, consider Pathname#children. + * The results contains just the names in the directory, without any trailing + * slashes or recursive look-up. * * pp Pathname.new('/usr/local').entries * #=> [#<Pathname:share>, @@ -883,6 +999,11 @@ path_s_getwd(VALUE klass) * # #<Pathname:sbin>, * # #<Pathname:src>] * + * The result may contain the current directory <code>#<Pathname:.></code> and + * the parent directory <code>#<Pathname:..></code>. + * + * If you don't want +.+ and +..+ and + * want directories, consider Pathname#children. */ static VALUE path_entries(VALUE self) @@ -902,7 +1023,9 @@ path_entries(VALUE self) } /* - * See <tt>Dir.mkdir</tt>. Create the referenced directory. + * Create the referenced directory. + * + * See Dir.mkdir. */ static VALUE path_mkdir(int argc, VALUE *argv, VALUE self) @@ -916,7 +1039,9 @@ path_mkdir(int argc, VALUE *argv, VALUE self) } /* - * See <tt>Dir.rmdir</tt>. Remove the referenced directory. + * Remove the referenced directory. + * + * See Dir.rmdir. */ static VALUE path_rmdir(VALUE self) @@ -925,7 +1050,9 @@ path_rmdir(VALUE self) } /* - * See <tt>Dir.open</tt>. + * Opens the referenced directory. + * + * See Dir.open. */ static VALUE path_opendir(VALUE self) @@ -943,10 +1070,8 @@ each_entry_i(VALUE elt, VALUE klass, int argc, VALUE *argv) } /* - * Iterates over the entries (files and subdirectories) in the directory. It - * yields a Pathname object for each entry. - * - * This method has available since 1.8.1. + * Iterates over the entries (files and subdirectories) in the directory, + * yielding a Pathname object for each entry. */ static VALUE path_each_entry(VALUE self) @@ -970,8 +1095,8 @@ unlink_rescue(VALUE str, VALUE errinfo) } /* - * Removes a file or directory, using <tt>File.unlink</tt> or - * <tt>Dir.unlink</tt> as necessary. + * Removes a file or directory, using File.unlink if +self+ is a file, or + * Dir.unlink as necessary. */ static VALUE path_unlink(VALUE self) @@ -982,9 +1107,7 @@ path_unlink(VALUE self) } /* - * create a pathname object. - * - * This method is available since 1.8.5. + * Creates a new Pathname object. */ static VALUE path_f_pathname(VALUE self, VALUE str) @@ -993,24 +1116,26 @@ path_f_pathname(VALUE self, VALUE str) } /* - * == Pathname * - * Pathname represents a pathname which locates a file in a filesystem. - * The pathname depends on OS: Unix, Windows, etc. - * Pathname library works with pathnames of local OS. - * However non-Unix pathnames are supported experimentally. + * Pathname represents the name of a file or directory on the filesystem, + * but not the file itself. + * + * The pathname depends on the Operating System: Unix, Windows, etc. + * This library works with pathnames of local OS, however non-Unix pathnames + * are supported experimentally. * - * It does not represent the file itself. * A Pathname can be relative or absolute. It's not until you try to * reference the file that it even matters whether the file exists or not. * * Pathname is immutable. It has no method for destructive update. * - * The value of this class is to manipulate file path information in a neater + * The goal of this class is to manipulate file path information in a neater * way than standard Ruby provides. The examples below demonstrate the - * difference. *All* functionality from File, FileTest, and some from Dir and - * FileUtils is included, in an unsurprising way. It is essentially a facade for - * all of these, and more. + * difference. + * + * *All* functionality from File, FileTest, and some from Dir and FileUtils is + * included, in an unsurprising way. It is essentially a facade for all of + * these, and more. * * == Examples * @@ -1058,8 +1183,8 @@ path_f_pathname(VALUE self, VALUE str) * === Core methods * * These methods are effectively manipulating a String, because that's - * all a path is. Except for #mountpoint?, #children, #each_child, - * #realdirpath and #realpath, they don't access the filesystem. + * all a path is. None of these access the file system except for + * #mountpoint?, #children, #each_child, #realdirpath and #realpath. * * - + * - #join |