ruby-changes:24898
From: zzak <ko1@a...>
Date: Wed, 12 Sep 2012 22:54:21 +0900 (JST)
Subject: [ruby-changes:24898] zzak:r36950 (trunk): * ext/pathname/lib/pathname.rb: Documentation for Pathname.
zzak 2012-09-12 22:54:08 +0900 (Wed, 12 Sep 2012) New Revision: 36950 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=36950 Log: * ext/pathname/lib/pathname.rb: Documentation for Pathname. * ext/pathname/pathname.c: ditto. [Bug #6947] [ruby-core:47354] Modified files: trunk/ChangeLog trunk/ext/pathname/lib/pathname.rb trunk/ext/pathname/pathname.c Index: ChangeLog =================================================================== --- ChangeLog (revision 36949) +++ ChangeLog (revision 36950) @@ -1,3 +1,9 @@ +Wed Sep 12 22:45::00 2012 Zachary Scott <zzak@r...> + + * 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@r...> * enc/depend: fixed wrong change in a part of r34802. Index: ext/pathname/lib/pathname.rb =================================================================== --- ext/pathname/lib/pathname.rb (revision 36949) +++ ext/pathname/lib/pathname.rb (revision 36950) @@ -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 @@ 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 @@ 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,10 +77,12 @@ # 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 cleanpath_conservative @@ -91,7 +92,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ # 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,10 +280,8 @@ # #<Pathname:path/to/some> # #<Pathname:path/to/some/file.rb> # - # It doesn't access actual filesystem. + # It doesn't access the filesystem. # - # This method is available since 1.8.5. - # def descend vs = [] ascend {|v| vs << v } @@ -280,10 +305,8 @@ # #<Pathname:path/to> # #<Pathname:path> # - # It doesn't access actual filesystem. + # It doesn't access the filesystem. # - # This method is available since 1.8.5. - # def ascend path = @path yield self @@ -295,8 +318,7 @@ 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 @@ 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,11 +398,12 @@ # # 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") # pn.children @@ -386,11 +413,9 @@ # 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,10 +432,15 @@ # 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> # # #<Pathname:/usr/local/bin> @@ -431,21 +461,26 @@ # # #<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. # + # If +self+ is relative, then +base_directory+ must be relative too. + # + # This method doesn't access the filesystem. It assumes no symlinks. + # # ArgumentError is raised when it cannot find a relative path. # - # This method has existed since 1.8.1. - # def relative_path_from(base_directory) dest_directory = self.cleanpath.to_s base_directory = base_directory.cleanpath.to_s @@ -486,17 +521,19 @@ 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? require 'find' @@ -510,15 +547,19 @@ 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". Index: ext/pathname/pathname.c =================================================================== --- ext/pathname/pathname.c (revision 36949) +++ ext/pathname/pathname.c (revision 36950) @@ -22,7 +22,7 @@ /* * 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 @@ return self; } +/* + * call-seq: + * pathname.freeze -> obj + * + * Freezes this Pathname. + * + * See Object.freeze. + */ static VALUE path_freeze(VALUE self) { @@ -54,6 +62,14 @@ return self; } +/* + * call-seq: + * pathname.taint -> obj + * + * Taints this Pathname. + * + * See Object.taint. + */ static VALUE path_taint(VALUE self) { @@ -62,6 +78,14 @@ return self; } +/* + * call-seq: + * pathname.untaint -> obj + * + * Untaints this Pathname. + * + * See Object.untaint. + */ static VALUE path_untaint(VALUE self) { @@ -84,7 +108,18 @@ } /* - * 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 @@ /* * 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 @@ } /* - * 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,9 +243,11 @@ /* 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,8 +263,9 @@ /* * 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. */ static VALUE @@ -241,10 +285,7 @@ * 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,9 +308,10 @@ * 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 path_read(int argc, VALUE *argv, VALUE self) @@ -286,9 +328,10 @@ * 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 path_binread(int argc, VALUE *argv, VALUE self) @@ -307,8 +350,10 @@ * 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 path_readlines(int argc, VALUE *argv, VALUE self) @@ -325,7 +370,7 @@ * call-seq: * pathname.sysopen([mode, [perm]]) -> fixnum * - * See <tt>IO.sysopen</tt>. + * See IO.sysopen. * */ static VALUE @@ -340,7 +385,12 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * 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 @@ * 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 @@ } /* - * 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 @@ * 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 @@ } /* - * 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 @@ } /* - * See <tt>File.readlink</tt>. Read symbolic link. + * Read symbolic link. + * + * See File.readlink. */ static VALUE path_readlink(VALUE self) @@ -474,7 +565,9 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * See <tt>File.lstat</tt>. + * See File.lstat. */ static VALUE path_lstat(VALUE self) @@ -504,7 +599,9 @@ * 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 @@ } /* - * 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 @@ } /* - * 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 @@ } /* - * See <tt>File.basename</tt>. Returns the last component of the path. (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/