summaryrefslogtreecommitdiff
path: root/ext/pathname/lib
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-09-12 13:54:08 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-09-12 13:54:08 +0000
commitb5c38622b191dbc0789bc613ad6042d49ec91743 (patch)
tree7ea899b979d8d2ea08511a23b46079513c2bbae0 /ext/pathname/lib
parent4893e6abab603b68f91920bd57410d120754e5f7 (diff)
* ext/pathname/lib/pathname.rb: Documentation for Pathname.
* 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
Diffstat (limited to 'ext/pathname/lib')
-rw-r--r--ext/pathname/lib/pathname.rb137
1 files changed, 89 insertions, 48 deletions
diff --git a/ext/pathname/lib/pathname.rb b/ext/pathname/lib/pathname.rb
index 4909c2d..fba1074 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".