kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

* ext/pathname/lib/pathname.rb: Documentation for Pathname.

Browse source 
* ext/pathname/pathname.c: ditto.
  [Bug #6947] [ruby-core:47354]



git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36950 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
zzak 2012-09-12 13:54:08 +00:00
parent 4893e6abab
commit b5c38622b1
3 changed files with 320 additions and 148 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -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> Mon Sep 10 10:19:34 2012 NAKAMURA Usaku <usa@ruby-lang.org>
* enc/depend: fixed wrong change in a part of r34802. * enc/depend: fixed wrong change in a part of r34802.

137
ext/pathname/lib/pathname.rb
View file

@ -8,8 +8,6 @@
# #
# For documentation, see class Pathname. # For documentation, see class Pathname.
# #
# <tt>pathname.rb</tt> is distributed with Ruby since 1.8.0.
#
require 'pathname.so' require 'pathname.so'
@ -29,7 +27,6 @@ class Pathname
proc {|a, b| a == b} proc {|a, b| a == b}
end end
# :startdoc:
if File::ALT_SEPARATOR if File::ALT_SEPARATOR
SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}" SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}"
@ -39,6 +36,8 @@ class Pathname
SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/ SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/
end end
# :startdoc:
# chop_basename(path) -> [pre-basename, basename] or nil # chop_basename(path) -> [pre-basename, basename] or nil
def chop_basename(path) def chop_basename(path)
base = File.basename(path) base = File.basename(path)
@ -78,9 +77,11 @@ class Pathname
# removed. The filesystem is not accessed. # removed. The filesystem is not accessed.
# #
# If +consider_symlink+ is +true+, then a more conservative algorithm is used # 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, # 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) def cleanpath(consider_symlink=false)
if consider_symlink if consider_symlink
@ -91,7 +92,7 @@ class Pathname
end 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. # Nothing more, nothing less.
# #
def cleanpath_aggressive def cleanpath_aggressive
@ -179,14 +180,14 @@ class Pathname
end end
private :cleanpath_conservative 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 def parent
self + '..' self + '..'
end end
# #mountpoint? returns +true+ if <tt>self</tt> points to a mountpoint. # Returns +true+ if +self+ points to a mountpoint.
def mountpoint? def mountpoint?
begin begin
stat1 = self.lstat stat1 = self.lstat
@ -199,10 +200,10 @@ class Pathname
end 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. # 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>. # pathnames which points to roots such as <tt>/usr/..</tt>.
# #
def root? def root?
@ -210,12 +211,31 @@ class Pathname
end end
# Predicate method for testing whether a path is absolute. # Predicate method for testing whether a path is absolute.
#
# It returns +true+ if the pathname begins with a slash. # 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? def absolute?
!relative? !relative?
end 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? def relative?
path = @path path = @path
while r = chop_basename(path) while r = chop_basename(path)
@ -230,6 +250,13 @@ class Pathname
# Pathname.new("/usr/bin/ruby").each_filename {|filename| ... } # Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
# # yields "usr", "bin", and "ruby". # # 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 def each_filename # :yield: filename
return to_enum(__method__) unless block_given? return to_enum(__method__) unless block_given?
_, names = split_names(@path) _, names = split_names(@path)
@ -253,9 +280,7 @@ class Pathname
# #<Pathname:path/to/some> # #<Pathname:path/to/some>
# #<Pathname:path/to/some/file.rb> # #<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 def descend
vs = [] vs = []
@ -280,9 +305,7 @@ class Pathname
# #<Pathname:path/to> # #<Pathname:path/to>
# #<Pathname:path> # #<Pathname:path>
# #
# It doesn't access actual filesystem. # It doesn't access the filesystem.
#
# This method is available since 1.8.5.
# #
def ascend def ascend
path = @path path = @path
@ -295,8 +318,7 @@ class Pathname
end end
# #
# Pathname#+ appends a pathname fragment to this one to produce a new Pathname # Appends a pathname fragment to +self+ to produce a new Pathname object.
# object.
# #
# p1 = Pathname.new("/usr") # Pathname:/usr # p1 = Pathname.new("/usr") # Pathname:/usr
# p2 = p1 + "bin/ruby" # Pathname:/usr/bin/ruby # p2 = p1 + "bin/ruby" # Pathname:/usr/bin/ruby
@ -352,10 +374,14 @@ class Pathname
private :plus 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 # path0 = Pathname.new("/usr") # Pathname:/usr
# <tt>path0 + path1 + ... + pathN</tt>. # 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) def join(*args)
args.unshift self args.unshift self
@ -372,10 +398,11 @@ class Pathname
# #
# Returns the children of the directory (files and subdirectories, not # Returns the children of the directory (files and subdirectories, not
# recursive) as an array of Pathname objects. By default, the returned # recursive) as an array of Pathname objects.
# pathnames will have enough information to access the files. If you set #
# +with_directory+ to +false+, then the returned pathnames will contain the # By default, the returned pathnames will have enough information to access
# filename only. # the files. If you set +with_directory+ to +false+, then the returned
# pathnames will contain the filename only.
# #
# For example: # For example:
# pn = Pathname("/usr/lib/ruby/1.8") # pn = Pathname("/usr/lib/ruby/1.8")
@ -386,11 +413,9 @@ class Pathname
# pn.children(false) # pn.children(false)
# # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ] # # -> [ 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. # the directory because they are not children.
# #
# This method has existed since 1.8.1.
#
def children(with_directory=true) def children(with_directory=true)
with_directory = false if @path == '.' with_directory = false if @path == '.'
result = [] result = []
@ -407,9 +432,14 @@ class Pathname
# Iterates over the children of the directory # Iterates over the children of the directory
# (files and subdirectories, not recursive). # (files and subdirectories, not recursive).
#
# It yields Pathname object for each child. # 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").each_child {|f| p f }
# #=> #<Pathname:/usr/local/share> # #=> #<Pathname:/usr/local/share>
@ -431,21 +461,26 @@ class Pathname
# # #<Pathname:src> # # #<Pathname:src>
# # #<Pathname:man> # # #<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) def each_child(with_directory=true, &b)
children(with_directory).each(&b) children(with_directory).each(&b)
end end
# #
# #relative_path_from returns a relative path from the argument to the # Returns a relative path from the given +base_directory+ to the receiver.
# receiver. If +self+ is absolute, the argument must be absolute too. If
# +self+ is relative, the argument must be relative too.
# #
# #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. # ArgumentError is raised when it cannot find a relative path.
# #
# This method has existed since 1.8.1.
#
def relative_path_from(base_directory) def relative_path_from(base_directory)
dest_directory = self.cleanpath.to_s dest_directory = self.cleanpath.to_s
base_directory = base_directory.cleanpath.to_s base_directory = base_directory.cleanpath.to_s
@ -486,16 +521,18 @@ end
class Pathname # * Find * class Pathname # * Find *
# #
# Pathname#find is an iterator to traverse a directory tree in a depth first # Iterates over the directory tree in a depth first manner, yielding a
# manner. It yields a Pathname for each file under "this" directory. # 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 # Since it is implemented by the standard library module Find, Find.prune can
# to control the traversal. # be used to control the traversal.
# #
# If +self+ is <tt>.</tt>, yielded pathnames begin with a filename in the # If +self+ is +.+, yielded pathnames begin with a filename in the
# current directory, not <tt>./</tt>. # current directory, not +./+.
#
# See Find.find
# #
def find # :yield: pathname def find # :yield: pathname
return to_enum(__method__) unless block_given? return to_enum(__method__) unless block_given?
@ -510,15 +547,19 @@ end
class Pathname # * FileUtils * class Pathname # * FileUtils *
# See <tt>FileUtils.mkpath</tt>. Creates a full path, including any # Creates a full path, including any intermediate directories that don't yet
# intermediate directories that don't yet exist. # exist.
#
# See FileUtils.mkpath and FileUtils.mkdir_p
def mkpath def mkpath
require 'fileutils' require 'fileutils'
FileUtils.mkpath(@path) FileUtils.mkpath(@path)
nil nil
end 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 def rmtree
# The name "rmtree" is borrowed from File::Path of Perl. # The name "rmtree" is borrowed from File::Path of Perl.
# File::Path provides "mkpath" and "rmtree". # File::Path provides "mkpath" and "rmtree".

325
ext/pathname/pathname.c
View file

@ -22,7 +22,7 @@ set_strpath(VALUE obj, VALUE val)
/* /*
* Create a Pathname object from the given String (or String-like object). * 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 static VALUE
path_initialize(VALUE self, VALUE arg) path_initialize(VALUE self, VALUE arg)
@ -46,6 +46,14 @@ path_initialize(VALUE self, VALUE arg)
return self; return self;
} }
/*
* call-seq:
* pathname.freeze -> obj
*
* Freezes this Pathname.
*
* See Object.freeze.
*/
static VALUE static VALUE
path_freeze(VALUE self) path_freeze(VALUE self)
{ {
@ -54,6 +62,14 @@ path_freeze(VALUE self)
return self; return self;
} }
/*
* call-seq:
* pathname.taint -> obj
*
* Taints this Pathname.
*
* See Object.taint.
*/
static VALUE static VALUE
path_taint(VALUE self) path_taint(VALUE self)
{ {
@ -62,6 +78,14 @@ path_taint(VALUE self)
return self; return self;
} }
/*
* call-seq:
* pathname.untaint -> obj
*
* Untaints this Pathname.
*
* See Object.untaint.
*/
static VALUE static VALUE
path_untaint(VALUE self) 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 static VALUE
path_cmp(VALUE self, VALUE other) path_cmp(VALUE self, VALUE other)
@ -153,6 +188,10 @@ path_inspect(VALUE self)
/* /*
* Return a pathname which is substituted by String#sub. * 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 static VALUE
path_sub(int argc, VALUE *argv, VALUE self) 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 * Return a pathname with +repl+ added as a suffix to the basename.
* <i>repl</i>.
* *
* 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 static VALUE
path_sub_ext(VALUE self, VALUE repl) path_sub_ext(VALUE self, VALUE repl)
@ -202,8 +243,10 @@ path_sub_ext(VALUE self, VALUE repl)
/* Facade for File */ /* Facade for File */
/* /*
* Returns the real (absolute) pathname of +self+ in the actual * Returns the real (absolute) pathname for +self+ in the actual
* filesystem not containing symlinks or useless dots. * filesystem.
*
* Does not contain symlinks or useless dots, +..+ and +.+.
* *
* All components of the pathname must exist when this method is * All components of the pathname must exist when this method is
* called. * called.
@ -220,7 +263,8 @@ path_realpath(int argc, VALUE *argv, VALUE self)
/* /*
* Returns the real (absolute) pathname of +self+ in the actual filesystem. * 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. * 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(sep, limit [, open_args]) {|line| block } -> nil
* pathname.each_line(...) -> an_enumerator * pathname.each_line(...) -> an_enumerator
* *
* #each_line iterates over the line in the file. It yields a String object * Iterates over each line in the file and yields a String object for each.
* for each line.
*
* This method is availabel since 1.8.1.
*/ */
static VALUE static VALUE
path_each_line(int argc, VALUE *argv, VALUE self) 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]]) -> string
* pathname.read([length [, offset]], open_args) -> string * pathname.read([length [, offset]], open_args) -> string
* *
* See <tt>IO.read</tt>. Returns all data from the file, or the first +N+ bytes * Returns all data from the file, or the first +N+ bytes if specified.
* if specified. *
* See IO.read.
* *
*/ */
static VALUE static VALUE
@ -286,8 +328,9 @@ path_read(int argc, VALUE *argv, VALUE self)
* call-seq: * call-seq:
* pathname.binread([length [, offset]]) -> string * pathname.binread([length [, offset]]) -> string
* *
* See <tt>IO.binread</tt>. Returns all the bytes from the file, or the first +N+ * Returns all the bytes from the file, or the first +N+ if specified.
* if specified. *
* See IO.binread.
* *
*/ */
static VALUE static VALUE
@ -307,7 +350,9 @@ path_binread(int argc, VALUE *argv, VALUE self)
* pathname.readlines(limit [, open_args]) -> array * pathname.readlines(limit [, open_args]) -> array
* pathname.readlines(sep, 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 static VALUE
@ -325,7 +370,7 @@ path_readlines(int argc, VALUE *argv, VALUE self)
* call-seq: * call-seq:
* pathname.sysopen([mode, [perm]]) -> fixnum * pathname.sysopen([mode, [perm]]) -> fixnum
* *
* See <tt>IO.sysopen</tt>. * See IO.sysopen.
* *
*/ */
static VALUE 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 static VALUE
path_atime(VALUE self) 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 static VALUE
path_ctime(VALUE self) 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 static VALUE
path_mtime(VALUE self) 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 static VALUE
path_chmod(VALUE self, VALUE mode) 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 static VALUE
path_lchmod(VALUE self, VALUE mode) 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 static VALUE
path_chown(VALUE self, VALUE owner, VALUE group) 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 static VALUE
path_lchown(VALUE self, VALUE owner, VALUE group) 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
* pathname.fnmatch?(pattern, [flags]) -> string * pathname.fnmatch?(pattern, [flags]) -> string
* *
* See <tt>File.fnmatch</tt>. Return +true+ if the receiver matches the given * Return +true+ if the receiver matches the given pattern.
* pattern. *
* See File.fnmatch.
*/ */
static VALUE static VALUE
path_fnmatch(int argc, VALUE *argv, VALUE self) 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", * call-seq:
* etc). * pathname.ftype -> string
*
* Returns "type" of file ("file", "directory", etc).
*
* See File.ftype.
*/ */
static VALUE static VALUE
path_ftype(VALUE self) path_ftype(VALUE self)
@ -435,7 +520,9 @@ path_ftype(VALUE self)
* call-seq: * call-seq:
* pathname.make_link(old) * 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 static VALUE
path_make_link(VALUE self, VALUE old) 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 static VALUE
path_open(int argc, VALUE *argv, VALUE self) 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 static VALUE
path_readlink(VALUE self) 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 static VALUE
path_rename(VALUE self, VALUE to) 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 static VALUE
path_stat(VALUE self) path_stat(VALUE self)
@ -492,7 +587,7 @@ path_stat(VALUE self)
} }
/* /*
* See <tt>File.lstat</tt>. * See File.lstat.
*/ */
static VALUE static VALUE
path_lstat(VALUE self) path_lstat(VALUE self)
@ -504,7 +599,9 @@ path_lstat(VALUE self)
* call-seq: * call-seq:
* pathname.make_symlink(old) * pathname.make_symlink(old)
* *
* See <tt>File.symlink</tt>. Creates a symbolic link. * Creates a symbolic link.
*
* See File.symlink.
*/ */
static VALUE static VALUE
path_make_symlink(VALUE self, VALUE old) 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 static VALUE
path_truncate(VALUE self, VALUE length) 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 static VALUE
path_utime(VALUE self, VALUE atime, VALUE mtime) 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 static VALUE
path_basename(int argc, VALUE *argv, VALUE self) 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 static VALUE
path_dirname(VALUE self) 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 static VALUE
path_extname(VALUE self) 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 static VALUE
path_expand_path(int argc, VALUE *argv, VALUE self) 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 static VALUE
path_split(VALUE self) path_split(VALUE self)
@ -599,7 +710,7 @@ path_split(VALUE self)
} }
/* /*
* See <tt>FileTest.blockdev?</tt>. * See FileTest.blockdev?.
*/ */
static VALUE static VALUE
path_blockdev_p(VALUE self) path_blockdev_p(VALUE self)
@ -608,7 +719,7 @@ path_blockdev_p(VALUE self)
} }
/* /*
* See <tt>FileTest.chardev?</tt>. * See FileTest.chardev?.
*/ */
static VALUE static VALUE
path_chardev_p(VALUE self) path_chardev_p(VALUE self)
@ -617,7 +728,7 @@ path_chardev_p(VALUE self)
} }
/* /*
* See <tt>FileTest.executable?</tt>. * See FileTest.executable?.
*/ */
static VALUE static VALUE
path_executable_p(VALUE self) 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 static VALUE
path_executable_real_p(VALUE self) 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 static VALUE
path_exist_p(VALUE self) path_exist_p(VALUE self)
@ -644,7 +755,7 @@ path_exist_p(VALUE self)
} }
/* /*
* See <tt>FileTest.grpowned?</tt>. * See FileTest.grpowned?.
*/ */
static VALUE static VALUE
path_grpowned_p(VALUE self) path_grpowned_p(VALUE self)
@ -653,7 +764,7 @@ path_grpowned_p(VALUE self)
} }
/* /*
* See <tt>FileTest.directory?</tt>. * See FileTest.directory?.
*/ */
static VALUE static VALUE
path_directory_p(VALUE self) path_directory_p(VALUE self)
@ -662,7 +773,7 @@ path_directory_p(VALUE self)
} }
/* /*
* See <tt>FileTest.file?</tt>. * See FileTest.file?.
*/ */
static VALUE static VALUE
path_file_p(VALUE self) path_file_p(VALUE self)
@ -671,7 +782,7 @@ path_file_p(VALUE self)
} }
/* /*
* See <tt>FileTest.pipe?</tt>. * See FileTest.pipe?.
*/ */
static VALUE static VALUE
path_pipe_p(VALUE self) path_pipe_p(VALUE self)
@ -680,7 +791,7 @@ path_pipe_p(VALUE self)
} }
/* /*
* See <tt>FileTest.socket?</tt>. * See FileTest.socket?.
*/ */
static VALUE static VALUE
path_socket_p(VALUE self) path_socket_p(VALUE self)
@ -689,7 +800,7 @@ path_socket_p(VALUE self)
} }
/* /*
* See <tt>FileTest.owned?</tt>. * See FileTest.owned?.
*/ */
static VALUE static VALUE
path_owned_p(VALUE self) path_owned_p(VALUE self)
@ -698,7 +809,7 @@ path_owned_p(VALUE self)
} }
/* /*
* See <tt>FileTest.readable?</tt>. * See FileTest.readable?.
*/ */
static VALUE static VALUE
path_readable_p(VALUE self) 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 static VALUE
path_world_readable_p(VALUE self) 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 static VALUE
path_readable_real_p(VALUE self) 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 static VALUE
path_setuid_p(VALUE self) path_setuid_p(VALUE self)
@ -734,7 +845,7 @@ path_setuid_p(VALUE self)
} }
/* /*
* See <tt>FileTest.setgid?</tt>. * See FileTest.setgid?.
*/ */
static VALUE static VALUE
path_setgid_p(VALUE self) path_setgid_p(VALUE self)
@ -743,7 +854,7 @@ path_setgid_p(VALUE self)
} }
/* /*
* See <tt>FileTest.size</tt>. * See FileTest.size.
*/ */
static VALUE static VALUE
path_size(VALUE self) path_size(VALUE self)
@ -752,7 +863,7 @@ path_size(VALUE self)
} }
/* /*
* See <tt>FileTest.size?</tt>. * See FileTest.size?.
*/ */
static VALUE static VALUE
path_size_p(VALUE self) path_size_p(VALUE self)
@ -761,7 +872,7 @@ path_size_p(VALUE self)
} }
/* /*
* See <tt>FileTest.sticky?</tt>. * See FileTest.sticky?.
*/ */
static VALUE static VALUE
path_sticky_p(VALUE self) path_sticky_p(VALUE self)
@ -770,7 +881,7 @@ path_sticky_p(VALUE self)
} }
/* /*
* See <tt>FileTest.symlink?</tt>. * See FileTest.symlink?.
*/ */
static VALUE static VALUE
path_symlink_p(VALUE self) path_symlink_p(VALUE self)
@ -779,7 +890,7 @@ path_symlink_p(VALUE self)
} }
/* /*
* See <tt>FileTest.writable?</tt>. * See FileTest.writable?.
*/ */
static VALUE static VALUE
path_writable_p(VALUE self) 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 static VALUE
path_world_writable_p(VALUE self) 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 static VALUE
path_writable_real_p(VALUE self) 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 static VALUE
path_zero_p(VALUE self) 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 static VALUE
path_s_glob(int argc, VALUE *argv, VALUE klass) 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 static VALUE
path_s_getwd(VALUE klass) 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 * Return the entries (files and subdirectories) in the directory, each as a
* Pathname object. * Pathname object.
* *
* The result contains just a filename which has no directory. * The results contains just the names in the directory, without any trailing
* * slashes or recursive look-up.
* 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.
* *
* pp Pathname.new('/usr/local').entries * pp Pathname.new('/usr/local').entries
* #=> [#<Pathname:share>, * #=> [#<Pathname:share>,
@ -883,6 +999,11 @@ path_s_getwd(VALUE klass)
* # #<Pathname:sbin>, * # #<Pathname:sbin>,
* # #<Pathname:src>] * # #<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 static VALUE
path_entries(VALUE self) 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 static VALUE
path_mkdir(int argc, VALUE *argv, VALUE self) 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 static VALUE
path_rmdir(VALUE self) 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 static VALUE
path_opendir(VALUE self) 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 * Iterates over the entries (files and subdirectories) in the directory,
* yields a Pathname object for each entry. * yielding a Pathname object for each entry.
*
* This method has available since 1.8.1.
*/ */
static VALUE static VALUE
path_each_entry(VALUE self) 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 * Removes a file or directory, using File.unlink if +self+ is a file, or
* <tt>Dir.unlink</tt> as necessary. * Dir.unlink as necessary.
*/ */
static VALUE static VALUE
path_unlink(VALUE self) path_unlink(VALUE self)
@ -982,9 +1107,7 @@ path_unlink(VALUE self)
} }
/* /*
* create a pathname object. * Creates a new Pathname object.
*
* This method is available since 1.8.5.
*/ */
static VALUE static VALUE
path_f_pathname(VALUE self, VALUE str) 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. * Pathname represents the name of a file or directory on the filesystem,
* The pathname depends on OS: Unix, Windows, etc. * but not the file itself.
* Pathname library works with pathnames of local OS. *
* However non-Unix pathnames are supported experimentally. * 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 * 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. * reference the file that it even matters whether the file exists or not.
* *
* Pathname is immutable. It has no method for destructive update. * 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 * way than standard Ruby provides. The examples below demonstrate the
* difference. *All* functionality from File, FileTest, and some from Dir and * difference.
* FileUtils is included, in an unsurprising way. It is essentially a facade for *
* all of these, and more. * *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 * == Examples
* *
@ -1058,8 +1183,8 @@ path_f_pathname(VALUE self, VALUE str)
* === Core methods * === Core methods
* *
* These methods are effectively manipulating a String, because that's * These methods are effectively manipulating a String, because that's
* all a path is. Except for #mountpoint?, #children, #each_child, * all a path is. None of these access the file system except for
* #realdirpath and #realpath, they don't access the filesystem. * #mountpoint?, #children, #each_child, #realdirpath and #realpath.
* *
* - + * - +
* - #join * - #join