epath 0.1.1 → 0.2.0

data/README.md

@@ -1,6 +1,6 @@
 # Path - a Path manipulation library
 
-Path is a library to manage paths.  
+[Path](http://rubydoc.info/github/eregon/epath/master/Path) is a library to manage paths.  
 It is similar to Pathname, but has some extra goodness.  
 The method names are intended to be short and explicit, and avoid too much duplication like having 'name' or 'path' in the method name.
 
@@ -20,6 +20,8 @@ Also, using a path library like this avoid to remember in which class the functi
 
 ## API
 
+See the [Path](http://rubydoc.info/github/eregon/epath/master/Path) class documentation for details.
+
 All the useful methods of `File` (and so `IO`) and `Dir` should be included.  
 Most methods of `FileUtils` should be there too.
 
@@ -30,6 +32,11 @@ Path.new('/usr/bin')
 Path['/usr/bin']
 Path('/usr/bin') # unless NO_EPATH_GLOBAL_FUNCTION is defined
 
+Path.new('~myuser/path') # expanded if it begins with ~
+
+# Separators are replaced by / on systems having File::ALT_SEPARATOR
+Path.new('win\sepa\rator') # => #<Path win/sepa/rator>
+
 Path.new('/usr', 'bin')
 %w[foo bar].map(&Path) # => [Path('foo'), Path('bar')]
 ```
@@ -38,7 +45,8 @@ Path.new('/usr', 'bin')
 Path.file           # == Path(__FILE__).expand
 Path.dir            # == Path(File.dirname(__FILE__)).expand
 Path.relative(path) # == Path(File.expand_path("../#{path}", __FILE__))
-Path.home           # == Path(File.expand_path('~'))
+Path.home or Path.~ # == Path(File.expand_path('~'))
+Path.~(user)        # == Path(File.expand_path("~#{user}"))
 ```
 
 ### temporary
@@ -102,11 +110,12 @@ Path('/usr')/'bin'
 
 ### glob
 
-* entries: files under self, without . and ..
+* children: files under self, without . and ..
 * glob: relative glob to self, yield absolute paths
 
 ### structure
 
+* parent: parent directory (don't use #dirname more than once, use #parent instead)
 * ascend, ancestors: self and all the parent directories
 * descend: in the reverse order
 * backfind: ascends the parents until it finds the given path

data/lib/epath.rb

@@ -6,6 +6,7 @@ require 'tempfile'
 
 class Path
   class << self
+    # {Path} to the current file +Path(__FILE__)+.
     def file(from = nil)
       from ||= caller # this can not be moved as a default argument, JRuby optimizes it
                                      # v This : is there to define a group without capturing
@@ -13,23 +14,31 @@ class Path
     end
     alias :here :file
 
+    # {Path} to the directory of this file: +Path(__FILE__).dir+.
     def dir(from = nil)
       from ||= caller # this can not be moved as a default argument, JRuby optimizes it
       file(from).dir
     end
 
-    def home
-      new(Dir.respond_to?(:home) ? Dir.home : new("~").expand)
+    # {Path} relative to the directory of this file.
+    def relative(path, from = nil)
+      from ||= caller # this can not be moved as a default argument, JRuby optimizes it
+      new(path).expand dir(from)
     end
 
-    def relative(path)
-      new(path).expand dir(caller)
+    # A {Path} to the home directory of +user+ (defaults to the current user).
+    # The form with an argument (+user+) is not supported on Windows.
+    def ~(user = '')
+      new("~#{user}")
     end
+    alias :home :~
 
+    # Same as +Path.file.backfind(path)+. See {#backfind}.
     def backfind(path)
       file(caller).backfind(path)
     end
 
+    # @yieldparam [Path] tmpfile
     def tmpfile(basename = '', tmpdir = nil, options = nil)
       tempfile = Tempfile.new(basename, *[tmpdir, options].compact)
       file = new tempfile
@@ -37,14 +46,14 @@ class Path
         begin
           yield file
         ensure
-          tempfile.close
-          tempfile.unlink if file.exist?
+          tempfile.close!
         end
       end
       file
     end
     alias :tempfile :tmpfile
 
+    # @yieldparam [Path] tmpdir
     def tmpdir(prefix_suffix = nil, *rest)
       require 'tmpdir'
       dir = new Dir.mktmpdir(prefix_suffix, *rest)
@@ -58,6 +67,7 @@ class Path
       dir
     end
 
+    # @yieldparam [Path] tmpdir
     def tmpchdir(prefix_suffix = nil, *rest)
       tmpdir do |dir|
         dir.chdir do
@@ -67,19 +77,24 @@ class Path
     end
   end
 
-  alias :/ :+
-
-  alias :relative_to :relative_path_from
-  alias :% :relative_path_from
-
+  # Whether +self+ is inside +ancestor+, such that +ancestor+ is an ancestor of +self+.
+  # This is pure String manipulation. Paths should be absolute.
   def inside? ancestor
     @path == ancestor.to_s or @path.start_with?("#{ancestor}/")
   end
 
+  # The opposite of {#inside?}.
   def outside? ancestor
     !inside?(ancestor)
   end
 
+  # Ascends the parents until it finds the given +path+.
+  #
+  #   Path.backfind('lib') # => the lib folder
+  #
+  # It accepts an XPath-like context:
+  #
+  #   Path.backfind('.[.git]') # => the root of the repository
   def backfind(path)
     condition = path[/\[(.*)\]$/, 1] || ''
     path = $` unless condition.empty?

data/lib/epath/dir.rb

@@ -1,7 +1,10 @@
 class Path
   class << self
+    # @!group Directory
+
     # Returns or yields Path objects. See +Dir.glob+.
-    def glob(*args) # :yield: path
+    # @yieldparam [Path] path
+    def glob(*args)
       if block_given?
         Dir.glob(*args) { |f| yield new(f) }
       else
@@ -16,9 +19,22 @@ class Path
     alias :pwd :getwd
   end
 
+  # @!group Directory
+
   # Iterates over the entries (files and subdirectories) in the directory.
-  # It yields a Path object for each entry.
-  def each_entry(&block) # :yield: path
+  #
+  #   Path("/usr/local").each_entry { |entry| p entry } # =>
+  #   #<Path .>
+  #   #<Path ..>
+  #   #<Path lib>
+  #   #<Path share>
+  #   # ...
+  #
+  # @deprecated Use {#each_child} instead.
+  #   This method is deprecated since it is too low level and likely useless in Ruby.
+  #   But it is there for the sake of compatibility with Dir.foreach and Pathname#each_entry.
+  # @yieldparam [Path] entry
+  def each_entry(&block)
     Dir.foreach(@path) { |f| yield Path.new(f) }
   end
 
@@ -34,29 +50,33 @@ class Path
   end
 
   # See +Dir.open+.
-  def opendir(&block) # :yield: dir
+  # @yieldparam [Dir] dir
+  def opendir(&block)
     Dir.open(@path, &block)
   end
 
+  # Returns or yields Path objects. See +Dir.glob+.
+  # @yieldparam [Path] path
   def glob(pattern, flags = 0)
     Dir.glob(join(pattern), flags).map(&Path)
   end
 
-  # [DEPRECATED] Return the entries (files and subdirectories) in the directory.
+  # Return the entries (files and subdirectories) in the directory.
   # Each Path only contains the filename.
   # The result may contain the current directory #<Path .> and the parent directory #<Path ..>.
   #
-  # Path('/usr/local').entries
-  # # => [#<Path share>, #<Path lib>, #<Path .>, #<Path ..>, <Path bin>, ...]
-  #
-  # This method is deprecated, since it is too low level and likely useless in Ruby.
-  # But it is there for the sake of compatibility with Dir.entries (and Pathname#entries)
+  #   Path('/usr/local').entries
+  #   # => [#<Path share>, #<Path lib>, #<Path .>, #<Path ..>, <Path bin>, ...]
   #
-  # Use #children instead.
+  # @deprecated Use {#children} instead.
+  #   This method is deprecated since it is too low level and likely useless in Ruby.
+  #   But it is there for the sake of compatibility with Dir.entries (and Pathname#entries).
   def entries
     Dir.entries(@path).map(&Path)
   end
 
+  # Changes the current working directory of the process to self. See Dir.chdir.
+  # The recommended way to use it is to use the block form, or not use it all!
   def chdir(&block)
     Dir.chdir(@path, &block)
   end
@@ -92,9 +112,7 @@ class Path
     result
   end
 
-  # Iterates over the children of the directory
-  # (files and subdirectories, not recursive).
-  # It yields Path object for each child.
+  # Iterates over the children of the directory (files and subdirectories, not recursive).
   # By default, the yielded paths will have enough information to access the files.
   # If you set +with_directory+ to +false+, then the returned paths will contain the filename only.
   #
@@ -117,6 +135,8 @@ class Path
   #       #<Path sbin>
   #       #<Path src>
   #       #<Path man>
+  #
+  # @yieldparam [Path] child
   def each_child(with_directory=true, &b)
     children(with_directory).each(&b)
   end

data/lib/epath/file.rb

@@ -1,10 +1,13 @@
 class Path
+  # @!group File
+
   # Returns last access time. See +File.atime+.
   def atime
     File.atime(@path)
   end
 
-  # Returns last (directory entry, not file) change time. See +File.ctime+.
+  # Returns last change time (of the directory entry, not the file itself).
+  # See +File.ctime+.
   def ctime
     File.ctime(@path)
   end
@@ -14,17 +17,18 @@ class Path
     File.mtime(@path)
   end
 
-  # Changes permissions. See +File.chmod+.
+  # Changes permissions of +path+. See +File.chmod+.
   def chmod(mode) File.chmod(mode, @path) end
 
-  # See +File.lchmod+.
+  # Changes permissions of +path+, not following symlink. See +File.lchmod+.
   def lchmod(mode) File.lchmod(mode, @path) end
 
-  # Change owner and group of file. See +File.chown+.
+  # Changes the owner and group of the file. See +File.chown+.
   def chown(owner, group)
     File.chown(owner, group, @path)
   end
 
+  # Changes the owner and group of +path+, not following symlink.
   # See +File.lchown+.
   def lchown(owner, group)
     File.lchown(owner, group, @path)
@@ -44,28 +48,28 @@ class Path
     self
   end
 
-  # Read symbolic link. See +File.readlink+.
+  # Reads the symbolic link. See +File.readlink+.
   def readlink
     Path.new(File.readlink(@path))
   end
 
-  # Rename the file and returns the new Path. See +File.rename+.
+  # Renames the file and returns the new Path. See +File.rename+.
   def rename(to)
     File.rename(@path, to)
     Path(to)
   end
 
-  # Returns a +File::Stat+ object. See +File.stat+.
+  # Returns the stat of +path+ as a +File::Stat+ object. See +File.stat+.
   def stat
     File.stat(@path)
   end
 
-  # See +File.lstat+.
+  # Returns the stat of +path+ as a +File::Stat+ object, not following symlink. See +File.lstat+.
   def lstat
     File.lstat(@path)
   end
 
-  # See +File.size+.
+  # Returns the file size in bytes. See +File.size+.
   def size
     File.size(@path)
   end
@@ -79,17 +83,19 @@ class Path
     self
   end
 
-  # Truncate the file to +length+ bytes. See +File.truncate+.
+  # Truncates the file to +length+ bytes. See +File.truncate+.
   def truncate(length) File.truncate(@path, length) end
 
-  # Update the access and modification times. See +File.utime+.
+  # Updates the access and modification times. See +File.utime+.
   def utime(atime, mtime) File.utime(atime, mtime, @path) end
 
-  # See +File.expand_path+.
-  def expand_path(*args)
+  # Expands +path+, making it absolute.
+  # If the path is relative, it is expanded with the current working directory,
+  # unless +dir+ is given as an argument. See +File.expand_path+.
+  def expand(*args)
     Path.new(File.expand_path(@path, *args))
   end
-  alias :expand :expand_path
+  alias :expand_path :expand
 
   # Returns the real (absolute) path of +self+ in the actual
   # filesystem not containing symlinks or useless dots.

data/lib/epath/file_predicates.rb

@@ -1,6 +1,8 @@
 # All methods from FileTest and all predicates from File are included
 
 class Path
+  # @!group File predicates
+
   # See +File.blockdev?+.
   def blockdev?
     File.blockdev?(@path)
@@ -128,7 +130,7 @@ class Path
   end
 
   # See +File.zero?+.
-  # empty? is not defined in File/FileTest, but is is clearer
+  # empty? is not defined in File/FileTest, but is is clearer.
   def zero?
     File.zero?(@path)
   end

data/lib/epath/fileutils.rb

@@ -1,6 +1,8 @@
 require 'fileutils'
 
 class Path
+  # @!group File utilities
+
   # Creates a full path, including any intermediate directories that don't yet exist.
   # See +FileUtils.mkpath+.
   def mkpath
@@ -18,37 +20,96 @@ class Path
   end
   alias :rm_r :rmtree
 
+  # Removes the file using +FileUtils.rm+.
   def rm
     FileUtils.rm(@path)
     self
   end
 
+  # Removes the file, ignoring errors, using +FileUtils.rm_f+.
   def rm_f
     FileUtils.rm_f(@path)
     self
   end
+  alias :safe_unlink :rm_f
+
+  # Removes the file or directory recursively, using +FileUtils.rm_r+.
+  def rm_r
+    FileUtils.rm_r(@path)
+    self
+  end
 
+  # Removes the file or directory recursively, ignoring errors,
+  # using +FileUtils.rm_f+.
   def rm_rf
     FileUtils.rm_rf(@path)
     self
   end
 
+  # Copies the file to +to+. See +FileUtils.cp+.
   def cp(to)
-    FileUtils.cp(@path, to)
+    # TODO: remove :preserve when all implement it correctly (r31123)
+    FileUtils.cp(@path, to, :preserve => true)
   end
-  alias copy cp
+  alias :copy :cp
 
+  # Copies the file or directory recursively to the directory +to+.
+  # See +FileUtils.cp_r+.
   def cp_r(to)
     FileUtils.cp_r(@path, to)
   end
 
+  # Updates access and modification time or create an empty file.
   def touch
-    FileUtils.touch(@path)
+    if exist?
+      now = Time.now
+      File.utime(now, now, @path)
+    else
+      open('w') {}
+    end
     self
   end
 
+  # {#touch} preceded by +dir.+{#mkpath}.
   def touch!
-    dirname.mkpath
+    dir.mkpath
     touch
   end
+
+  # Moves +self+ to the +to+ directory.
+  def mv(to)
+    FileUtils.mv(@path, to)
+    to
+  end
+  alias :move :mv
+
+  # Install +file+ into +path+ (the "prefix", which should be a directory).
+  # If +file+ is not same as +path/file+, replaces it.
+  # See +FileUtils.install+ (arguments are swapped).
+  def install(file, options = {})
+    FileUtils.install(file, @path, options)
+  end
+
+  # Recusively changes permissions. See +FileUtils.chmod_R+ and +File.chmod+.
+  def chmod_r(mode)
+    FileUtils.chmod_R(mode, @path)
+  end
+
+  # Recusively changes owner and group. See +FileUtils.chown_R+ and +File.chown+.
+  def chown_r(owner, group)
+    FileUtils.chown_R(owner, group, @path)
+  end
+
+  # Whether the contents of +path+ and +file+ are identical.
+  # See +FileUtils.compare_file+.
+  def has_same_contents?(file)
+    FileUtils.compare_file(@path, file)
+  end
+
+  # Returns whether +self+ is newer than all +others+.
+  # Non-existent files are older than any file.
+  # See +FileUtils.uptodate?+.
+  def uptodate?(*others)
+    FileUtils.uptodate?(@path, others)
+  end
 end

data/lib/epath/find.rb

@@ -9,7 +9,9 @@ class Path
   #
   # If +self+ is +.+, yielded paths begin with a filename in the
   # current directory, not +./+.
-  def find # :yield: path
+  #
+  # @yieldparam [Path] path
+  def find
     return to_enum(__method__) unless block_given?
     require 'find'
     if @path == '.'

data/lib/epath/identity.rb

@@ -1,5 +1,8 @@
 class Path
   class << self
+    # @!group Identity
+
+    # Creates a new Path. See {#initialize}.
     def new(*args)
       if args.size == 1 and Path === args[0]
         args[0]
@@ -9,11 +12,16 @@ class Path
     end
     alias :[] :new
 
+    # A class constructor.
+    #
+    #   %w[foo bar].map(&Path) # == [Path('foo'), Path('bar')]
     def to_proc
       lambda { |path| new(path) }
     end
   end
 
+  # @!group Identity
+
   # Compare this path with +other+. The comparison is string-based.
   # Be aware that two different paths (+foo.txt+ and +./foo.txt+)
   # can refer to the same file.
@@ -28,11 +36,12 @@ class Path
     @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
   end
 
+  # The hash value of the +path+.
   def hash
     @path.hash
   end
 
-  # Return the path as a String.
+  # Returns the +path+ as a String.
   def to_s
     @path
   end
@@ -40,18 +49,22 @@ class Path
   # to_path is implemented so Path objects are usable with File.open, etc.
   alias :to_path :to_s
 
+  # to_str is implemented so Path objects are usable with File.open, etc in Ruby 1.8.
   alias :to_str :to_s if RUBY_VERSION < '1.9'
 
+  # Returns the +path+ as a Symbol.
   def to_sym
     @path.to_sym
   end
 
+  # A representation of the +path+.
   def inspect
     "#<Path #{@path}>"
   end
 end
 
 unless defined? NO_EPATH_GLOBAL_FUNCTION
+  # A shorthand method to create a {Path}. Same as {Path.new}.
   def Path(*args)
     Path.new(*args)
   end

data/lib/epath/implementation.rb

@@ -8,8 +8,12 @@ class Path
     lambda { |a,b| a == b }
   end
 
+  # Creates a new Path.
+  # If multiple arguments are given, they are joined with File.join.
+  # The path will have File::ALT_SEPARATOR replaced with '/' and
+  # if it begins with a '~', it will be expanded (using File.expand_path).
   def initialize(*parts)
-    path = parts.size > 1 ? File.join(parts) : parts.first
+    path = parts.size > 1 ? File.join(*parts) : parts.first
     @path = case path
     when Tempfile
       @_tmpfile = path # We would not want it to be GC'd
@@ -23,15 +27,24 @@ class Path
     init
   end
 
+  # YAML loading.
   def yaml_initialize(tag, ivars)
     @path = ivars['path']
     init
   end
 
+  # Psych loading.
+  def init_with(coder)
+    @path = coder['path']
+    init
+  end
+
+  # Marshal dumping.
   def marshal_dump
     @path
   end
 
+  # Marshal loading.
   def marshal_load path
     @path = path
     init
@@ -43,7 +56,7 @@ class Path
   # If +consider_symlink+ is +true+, then a more conservative algorithm is used
   # 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 {#realpath}.
   def cleanpath(consider_symlink=false)
     if consider_symlink
       cleanpath_conservative
@@ -53,34 +66,34 @@ class Path
   end
 
   # #parent returns the parent directory.
-  #
-  # This is same as <tt>self + '..'</tt>.
+  # This can be chained.
   def parent
-    self + '..'
+    self / '..'
   end
 
-  # Path#+ appends a path fragment to this one to produce a new Path.
+  # Path#/ appends a path fragment to this one to produce a new Path.
   #
-  #   p1 = Path.new("/usr")   # => #<Path /usr>
-  #   p2 = p1 + "bin/ruby"    # => #<Path /usr/bin/ruby>
-  #   p3 = p1 + "/etc/passwd" # => #<Path /etc/passwd>
+  #   p = Path.new("/usr")  # => #<Path /usr>
+  #   p / "bin/ruby"        # => #<Path /usr/bin/ruby>
+  #   p / "/etc/passwd"     # => #<Path /etc/passwd>
   #
   # This method doesn't access the file system, it is pure string manipulation.
-  def +(other)
+  def /(other)
     Path.new(plus(@path, other.to_s))
   end
+  alias :+ :/
 
   # Path#join joins paths.
   #
   # <tt>path0.join(path1, ..., pathN)</tt> is the same as
-  # <tt>path0 + path1 + ... + pathN</tt>.
+  # <tt>path0 / path1 / ... / pathN</tt>.
   def join(*args)
     args.unshift self
     result = Path.new(args.pop)
     return result if result.absolute?
     args.reverse_each { |arg|
       arg = Path.new(arg)
-      result = arg + result
+      result = arg / result
       return result if result.absolute?
     }
     result
@@ -126,6 +139,8 @@ class Path
       Path.new(*relpath_names)
     end
   end
+  alias :relative_to :relative_path_from
+  alias :% :relative_path_from
 
   # @private
   module Helpers
@@ -148,7 +163,7 @@ class Path
   private
 
   def init
-    validate(@path)
+    @path = validate(@path)
 
     taint if @path.tainted?
     @path.freeze
@@ -158,6 +173,8 @@ class Path
   def validate(path)
     raise ArgumentError, "path contains a null byte: #{path.inspect}" if path.include? "\0"
     path.gsub!(File::ALT_SEPARATOR, '/') if File::ALT_SEPARATOR
+    path = File.expand_path(path) if path.start_with? '~'
+    path
   end
 
   # chop_basename(path) -> [pre-basename, basename] or nil
@@ -211,8 +228,8 @@ class Path
     if r = chop_basename(path)
       pre, basename = r
       pre + basename
-    elsif /\/+\z/o =~ path
-      $` + File.dirname(path)[/\/*\z/o]
+    elsif %r{/+\z} =~ path
+      $` + File.dirname(path)[%r{/*\z}]
     else
       path
     end

data/lib/epath/io.rb

@@ -1,11 +1,15 @@
 class Path
+  # @!group IO
+
   # Opens the file for reading or writing. See +File.open+.
-  def open(*args, &block) # :yield: file
+  # @yieldparam [File] file
+  def open(*args, &block)
     File.open(@path, *args, &block)
   end
 
   # Iterates over the lines in the file. See +IO.foreach+.
-  def each_line(*args, &block) # :yield: line
+  # @yieldparam [String] line
+  def each_line(*args, &block)
     IO.foreach(@path, *args, &block)
   end
   alias :lines :each_line
@@ -37,6 +41,7 @@ class Path
   end
 
   if IO.respond_to? :write
+    # Writes +contents+ to +self+. See +IO.write+ or +IO#write+.
     def write(contents, *open_args)
       IO.write(@path, contents, *open_args)
     end
@@ -47,13 +52,14 @@ class Path
   end
 
   if IO.respond_to? :write and !RUBY_DESCRIPTION.start_with?('jruby')
+    # Appends +contents+ to +self+. See +IO.write+ or +IO#write+.
     def append(contents, open_args = {})
       open_args[:mode] = 'a'
       IO.write(@path, contents, open_args)
     end
   else
-    def append(contents, open_args = nil)
-      open('a') { |f| f.write(contents) }
+    def append(contents, *open_args)
+      open('a', *open_args) { |f| f.write(contents) }
     end
   end
 end

data/lib/epath/load.rb

@@ -1,4 +1,5 @@
 class Path
+  # @!group Loading
 
   # The list of loaders. See {Path.register_loader}.
   LOADERS = {}
@@ -7,6 +8,8 @@ class Path
   # for the given extensions (either with the leading dot or not)
   #
   #     Path.register_loader('.marshal') { |file| Marshal.load file.read }
+  #
+  # @yieldparam [Path] path
   def self.register_loader(*extensions, &loader)
     extensions.each { |ext|
       LOADERS[pure_ext(ext)] = loader
@@ -15,7 +18,7 @@ class Path
 
   # Path#load helps loading data from various files.
   # JSON and YAML loaders are provided by default.
-  # See Path.register_loader.
+  # See {Path.register_loader}.
   def load
     if LOADERS.key? ext
       LOADERS[ext].call(self)

data/lib/epath/parts.rb

@@ -1,4 +1,6 @@
 class Path
+  # @!group Path parts
+
   # Returns the last component of the path. See +File.basename+.
   def basename(*args)
     Path.new(File.basename(@path, *args))
@@ -9,18 +11,23 @@ class Path
     basename(extname)
   end
 
-  # Returns all but the last component of the path. See +File.dirname+.
+  # Returns all but the last component of the path.
+  #
+  # Don't chain this when the path is relative:
+  #     Path('.').dir # => #<Path .>
+  # Use #parent instead.
+  # See +File.dirname+.
   def dirname
     Path.new(File.dirname(@path))
   end
   alias :dir :dirname
 
-  # Returns the file's extension. See +File.extname+.
+  # Returns the extension, with a leading dot. See +File.extname+.
   def extname
     File.extname(@path)
   end
 
-  # extname without leading .
+  # {#extname} without leading dot.
   def ext
     ext = extname
     ext.empty? ? ext : ext[1..-1]
@@ -31,17 +38,31 @@ class Path
     File.split(@path).map(&Path)
   end
 
+  # Adds +ext+ as an extension to +path+.
+  # Handle both extensions with or without leading dot.
+  # No-op if +ext+ is +empty?+.
+  #
+  #   Path('file').add_extension('txt') # => #<Path file.txt>
   def add_extension(ext)
     return self if ext.empty?
     Path.new @path+dotted_ext(ext)
   end
   alias :add_ext :add_extension
 
+  # Removes the last extension of +path+.
+  #
+  #   Path('script.rb').without_extension # => #<Path script>
+  #   Path('archive.tar.gz').without_extension # => #<Path archive.tar>
   def without_extension
     Path.new @path[0..-extname.size-1]
   end
   alias :rm_ext :without_extension
 
+  # Replaces the last extension of +path+ with +ext+.
+  # Handle both extensions with or without leading dot.
+  # Removes last extension if +ext+ is +empty?+.
+  #
+  #   Path('main.c++').replace_extension('cc') # => #<Path main.cc>
   def replace_extension(ext)
     return without_extension if ext.empty?
     Path.new(@path[0..-extname.size-1] << dotted_ext(ext))
@@ -52,15 +73,16 @@ class Path
   #
   #   Path.new("/usr/bin/ruby").each_filename { |filename| ... }
   #     # yields "usr", "bin", and "ruby".
-  def each_filename # :yield: filename
+  #
+  # @yieldparam [String] filename
+  def each_filename
     return to_enum(__method__) unless block_given?
     _, names = split_names(@path)
     names.each { |filename| yield filename }
     nil
   end
 
-  # Iterates over and yields a new Path object
-  # for each element in the given path in descending order.
+  # Iterates over each element in the given path in descending order.
   #
   #  Path.new('/path/to/some/file.rb').descend { |v| p v }
   #     #<Path />
@@ -76,6 +98,7 @@ class Path
   #     #<Path path/to/some/file.rb>
   #
   # It doesn't access actual filesystem.
+  # @yieldparam [Path] path
   def descend
     return to_enum(:descend) unless block_given?
     vs = []
@@ -84,8 +107,7 @@ class Path
     nil
   end
 
-  # Iterates over and yields a new Path object
-  # for each element in the given path in ascending order.
+  # Iterates over each element in the given path in ascending order.
   #
   #  Path.new('/path/to/some/file.rb').ascend { |v| p v }
   #     #<Path /path/to/some/file.rb>
@@ -101,6 +123,7 @@ class Path
   #     #<Path path>
   #
   # It doesn't access actual filesystem.
+  # @yieldparam [Path] path
   def ascend
     return to_enum(:ascend) unless block_given?
     path = @path

data/lib/epath/predicates.rb

@@ -1,4 +1,6 @@
 class Path
+  # @!group Path predicates
+
   # Whether a path is absolute.
   def absolute?
     !relative?

data/lib/epath/require_tree.rb

@@ -1,4 +1,8 @@
 class Path
+  # @!group Requiring
+
+  # Requires all .rb files recursively (in alphabetic order)
+  # under +directory+ (or this file's directory if not given).
   def self.require_tree(directory = nil)
     if directory
       new(directory).require_tree
@@ -8,7 +12,11 @@ class Path
     end
   end
 
+  # @api private
+  # See {Path.require_tree}.
+  # It is not a real private method because {Path.require_tree}
+  # (so the {Path} class) needs to be able to call it.
   def require_tree(source = nil)
-    glob('**/*.rb').sort.each { |file| require file.expand(dir) unless file == source }
+    glob('**/*.rb').sort.each { |file| require file.expand(dir).to_s unless file == source }
   end
 end

data/lib/epath/version.rb

@@ -1,3 +1,5 @@
 class Path
-  VERSION = '0.1.1'
+  # The version of the gem.
+  # Set here to avoid duplication and allow introspection.
+  VERSION = '0.2.0'
 end

metadata

@@ -1,45 +1,38 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: epath
-version: !ruby/object:Gem::Version 
-  hash: 25
+version: !ruby/object:Gem::Version
+  version: 0.2.0
   prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
 platform: ruby
-authors: 
+authors:
 - eregon
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-03-18 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email: eregontp@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/epath/dir.rb
 - lib/epath/file.rb
 - lib/epath/file_dir.rb
@@ -60,37 +53,27 @@ files:
 - epath.gemspec
 homepage: https://github.com/eregon/epath
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: a Path manipulation library
 test_files: []
-
 has_rdoc: