pathname2 1.6.0 → 1.6.1

data/CHANGES

@@ -1,3 +1,10 @@
+== 1.6.1 - 8-Nov-2008
+* Added the Pathname#[] method, which accepts an index, an index plus a
+  length, or a range, and returns appropriate the path element(s).
+* Refactoring the platform checking in the test suite to use rbconfig instead
+  of RUBY_PLATFORM.
+* More inline documentation examples.
+
 == 1.6.0 - 13-July-2008
 * The facade for ftools (and ftools itself) has been removed. The ftools
   library is deprecated in favor of FileUtils.

data/README

@@ -6,7 +6,7 @@
    * facade 1.0.0 or later (available on the RAA and as a gem)
    * windows-pr 0.5.1 or later (available on the RAA and as a gem)
    
-   The windows-pr package is only required on MS Windows.
+   The windows-pr library is only required on MS Windows.
    
 == Installation, pure Ruby
 === Manual Installation
@@ -67,15 +67,9 @@
      Pathname#clean("../a") returns "../a".  In this version, it returns "a".
      This affects other methods, such as Pathname#relative_path_from.
    * Accepts file urls and converts them to paths automatically, e.g.
-     file:///foo%20bar/baz becomes '/foo bar/baz'.
+     file:///foo%20bar/baz becomes '/foo/bar/baz'.
    * Adds a Kernel level +pn+ method as a shortcut.
    * Allows you to add paths together with the '/' operator.
-   
-== Differences between Unix platforms - C version
-   * On BSD systems, including OS X, the Pathname#realpath() method requires
-     that all components of a path *except the last* actually exist. Other
-     platforms require that the *entire* path actually exist. This is the
-     way the underlying realpath() C function works on these systems.
      
 == Method Priority
    Because there is some overlap in method names between File, Dir, and
@@ -86,19 +80,15 @@
    * FileUtils
    
    In other words, whichever of these defines a given method first is the
-   method that is used by the pathname2 package.
+   method that is used by the pathname2 library.
    
 == Known Issues
-   You cannot pass a frozen string to the constructor on Windows using the
-   pure Ruby version.  There is an unresolved issue with Win32API and frozen
-   objects.
-   
-   Pathname#glob is not yet implemented in the C version.
-   Pathname#find is not implemented properly in the C version.
-   
    In Ruby 1.8.3 and 1.8.4 you will see a failure in the test suite regarding
    'fu_world_writable?' from FileUtils.  You can ignore this.  That method is
    supposed to be private.  See ruby-core:7383.
+   
+   Any other issues should be reported on the project page at
+   http://www.rubyforge.org/projects/shards
 
 == Future Plans
    Suggestions welcome.
@@ -107,11 +97,10 @@
    Ruby's
 
 == Warranty
-   This package is provided "as is" and without any express or
+   This library is provided "as is" and without any express or
    implied warranties, including, without limitation, the implied
    warranties of merchantability and fitness for a particular purpose.
 
 == Author
    Daniel J. Berger
    djberg96 at gmail dot com
-   imperator on IRC (irc.freenode.net)

data/lib/pathname2.rb

@@ -60,6 +60,8 @@ class Pathname < String
 
    facade Dir, Dir.methods(false) - ['chdir','glob','foreach','mkdir','open']
 
+   private
+   
    alias :_plus_ :+ # Used to prevent infinite loops in some cases
    
    if Config::CONFIG['host_os'].match('mswin')
@@ -68,9 +70,14 @@ class Pathname < String
       include Windows::Error
       include Windows::Limits
    end
+   
+   public
 
-   VERSION = '1.6.0'
-   MAXPATH = 260
+   VERSION = '1.6.1'
+
+   if !defined? MAXPATH
+      MAXPATH = 1024
+   end
    
    # Creates and returns a new Pathname object.
    #
@@ -82,6 +89,13 @@ class Pathname < String
    # "file:///C:/Documents%20and%20Settings" will become
    # 'C:\Documents and Settings'.
    #
+   # Examples:
+   #
+   #   Pathname.new("/foo/bar/baz"
+   #   Pathname.new("foo")
+   #   Pathname.new("file:///foo/bar/baz")
+   #   Pathname.new("C:\\Documents and Settings\\snoopy")
+   #
    def initialize(path)
       if path.length > MAXPATH
          msg = "string too long.  maximum string length is " + MAXPATH.to_s
@@ -122,6 +136,12 @@ class Pathname < String
    # exists on your filesystem. If it doesn't, an error is raised. If a
    # circular symlink is encountered a system error will be raised.
    #
+   # Example:
+   #
+   #    Dir.pwd                      # => /usr/local
+   #    File.exists?('foo')          # => true
+   #    Pathname.new('foo').realpath # => /usr/local/foo
+   #
    def realpath
       File.stat(self) # Check to ensure that the path exists
 
@@ -147,6 +167,12 @@ class Pathname < String
    # the directory because they are not children.  Also note that this method
    # is *not* recursive.
    #
+   # Example:
+   #
+   # path = Pathname.new('/usr/bin')
+   # path.children        # => ['/usr/bin/ruby', '/usr/bin/perl', ...]
+   # path.children(false) # => ['ruby', 'perl', ...]
+   #
    def children(with_directory = true)
       with_directory = false if self == '.'
       result = []
@@ -163,8 +189,12 @@ class Pathname < String
 
    # Windows only
    #
-   # Removes the decoration from a path string.  For example,
-   # C:\Path\File[5].txt would become C:\Path\File.txt.  Non-destructive.
+   # Removes the decoration from a path string. Non-destructive.
+   # 
+   # Example:
+   #
+   # path = Pathname.new('C:\Path\File[5].txt')
+   # path.undecorate # => C:\Path\File.txt.
    #
    def undecorate
       unless @win
@@ -193,8 +223,12 @@ class Pathname < String
    
    # Windows only
    #
-   # Returns the short path for a long path name.  For example,
-   # C:\Program Files\Java would return C:\Progra~1\Java.
+   # Returns the short path for a long path name.
+   #
+   # Example:
+   # 
+   #    path = Pathname.new('C:\Program Files\Java')
+   #    path.short_path # => C:\Progra~1\Java.
    #
    def short_path
       unless @win
@@ -208,8 +242,12 @@ class Pathname < String
    
    # Windows only
    #
-   # Returns the long path for a long path name.  For example,
-   # C:\Progra~1\Java would return C:\Program Files\Java.
+   # Returns the long path for a long path name.
+   #
+   # Example:
+   #
+   #    path = Pathname.new('C:\Progra~1\Java')
+   #    path.long_path # => C:\Program Files\Java.
    #
    def long_path
       unless @win
@@ -223,13 +261,18 @@ class Pathname < String
    
    # Removes trailing slash, if present.  Non-destructive.
    #
+   # Example:
+   #
+   #    path = Pathname.new('/usr/local/')
+   #    path.pstrip # => '/usr/local'
+   #
    def pstrip
       str = self.dup
       if @win
          PathRemoveBackslash(str)
          str.strip!
       else
-         if str[-1].chr == @sep
+         if str.to_s[-1].chr == @sep
             str.strip!
             str.chop!
          end
@@ -237,14 +280,14 @@ class Pathname < String
       self.class.new(str)
    end
    
-   # Removes trailing slash, if present.  Destructive.
+   # Performs the substitution of Pathname#pstrip in place.
    #
    def pstrip!
       if @win
          PathRemoveBackslash(self)
          strip!
       else
-         if self[-1].chr == @sep
+         if self.to_s[-1].chr == @sep
             strip!
             chop!
          end
@@ -252,8 +295,12 @@ class Pathname < String
       self
    end
 
-   # Splits a pathname into strings based on the path separator.  For example,
-   # "/foo/bar/baz" would return a three element array of ['foo','bar','baz'].
+   # Splits a pathname into strings based on the path separator.
+   #
+   # Examples:
+   #
+   #    Pathname.new('/usr/local/bin').to_a # => ['usr', 'local', 'bin']
+   #    Pathname.new('C:\WINNT\Fonts').to_a # => ['C:', 'WINNT', 'Fonts']
    #
    def to_a
       array = split(@sep) # Split string by path separator
@@ -263,16 +310,76 @@ class Pathname < String
    
    # Yields each component of the path name to a block.
    #
+   # Example:
+   #
+   #    Pathname.new('/usr/local/bin').each{ |element|
+   #       puts "Element: #{element}"
+   #    }
+   #
+   #    Yields 'usr', 'local', and 'bin', in turn
+   #
    def each
       to_a.each{ |element| yield element }
    end
+   
+   # Returns the path component at +index+, up to +length+ components, joined
+   # by the path separator. If the +index+ is a Range, then that is used
+   # instead and the +length+ is ignored.
+   #
+   # Keep in mind that on MS Windows the drive letter is the first element.
+   #
+   # Examples:
+   #
+   #    path = Pathname.new('/home/john/source/ruby')
+   #    path[0]    # => 'home'
+   #    path[1]    # => 'john'
+   #    path[0, 3] # => '/home/john/source'
+   #    path[0..1] # => '/home/john'
+   #
+   #    path = Pathname.new('C:/Documents and Settings/John/Source/Ruby')
+   #    path[0]    # => 'C:\'
+   #    path[1]    # => 'Documents and Settings'
+   #    path[0, 3] # => 'C:\Documents and Settings\John'
+   #    path[0..1] # => 'C:\Documents and Settings'
+   #
+   def [](index, length=nil)     
+      if index.is_a?(Fixnum)
+         if length
+            path = File.join(to_a[index, length])
+         else
+            path = to_a[index]
+         end
+      elsif index.is_a?(Range)
+         if length
+            warn 'Length argument ignored'
+         end
+         path = File.join(to_a[index])
+      else
+         raise TypeError, "Only Fixnums and Ranges allowed as first argument"
+      end
+      
+      if path && @win
+         path = path.tr("/", "\\")
+      end
+      
+      path
+   end
 
    # Yields each component of the path, concatenating the next component on
-   # each iteration, as a new Pathname object, starting with the root path.
+   # each iteration as a new Pathname object, starting with the root path.
+   #
+   # Example:
    #
-   # For example, if the path is "/foo/bar/baz", then "/" would be yielded
-   # on the first iteration, "/foo" on the second, "/foo/bar on the third and
-   # finally "/foo/bar/baz".
+   #    path = Pathname.new('/usr/local/bin')
+   #
+   #    path.descend{ |name|
+   #       puts name
+   #    }
+   #
+   #    First iteration  => '/'
+   #    Second iteration => '/usr'
+   #    Third iteration  => '/usr/local'
+   #    Fourth iteration => '/usr/local/bin'
    #
    def descend
       if root?
@@ -303,9 +410,18 @@ class Pathname < String
    # Yields the path, minus one component on each iteration, as a new
    # Pathname object, ending with the root path.
    #
-   # For example, if the path is "/foo/bar/baz", then "/foo/bar/baz" would
-   # be yielded on the first iteration, "/foo/bar" on the second, "/foo" on
-   # the third, and finally "/".
+   # Example:
+   #
+   #    path = Pathname.new('/usr/local/bin')
+   #
+   #    path.ascend{ |name|
+   #       puts name
+   #    }
+   #
+   #    First iteration  => '/usr/local/bin'
+   #    Second iteration => '/usr/local'
+   #    Third iteration  => '/usr'
+   #    Fourth iteration => '/'
    #
    def ascend
       if root?
@@ -349,6 +465,16 @@ class Pathname < String
    # to the drive letter, or the server and share path if the path is a
    # UNC path.
    #
+   # Examples:
+   #
+   #    Pathname.new('/usr/local').root       # => '/'
+   #    Pathname.new('lib')                   # => '.'
+   #
+   #    On MS Windows:
+   #
+   #    Pathname.new('C:\WINNT').root         # => 'C:'
+   #    Pathname.new('\\some\share\foo').root # => '\\some\share'
+   #
    def root
       dir = "."   
       if @win
@@ -366,6 +492,11 @@ class Pathname < String
 
    # Returns whether or not the path consists only of a root directory.
    #
+   # Examples:
+   #
+   #   Pathname.new('/').root?    # => true
+   #   Pathname.new('/foo').root? # => false
+   #
    def root?
       if @win
          PathIsRoot(self)
@@ -374,11 +505,16 @@ class Pathname < String
       end
    end
    
-   # Windows only
+   # MS Windows only
    #
    # Determines if the string is a valid Universal Naming Convention (UNC)
    # for a server and share path.
    #
+   # Examples:
+   #
+   #    Pathname.new("\\\\foo\\bar").unc?     # => true
+   #    Pathname.new('C:\Program Files').unc? # => false
+   #
    def unc?
       unless @win
          raise NotImplementedError, "not supported on this platform"
@@ -387,12 +523,14 @@ class Pathname < String
       PathIsUNC(self)
    end
    
-   # Windows only
+   # MS Windows only
    #
    # Returns the drive number that corresponds to the root, or nil if not
    # applicable.
    #
-   # For example, Pathname.new("C:\\foo").drive_number would return 2.
+   # Example:
+   #
+   #    Pathname.new("C:\\foo").drive_number # => 2
    #
    def drive_number
       unless @win
@@ -406,6 +544,15 @@ class Pathname < String
    # Compares two Pathname objects.  Note that Pathnames may only be compared
    # against other Pathnames, not strings.  Otherwise nil is returned.
    #
+   # Example:
+   #
+   #    path1 = Pathname.new('/usr/local')
+   #    path2 = Pathname.new('/usr/local')
+   #    path3 = Pathname.new('/usr/local/bin')
+   #
+   #    path1 <=> path2 # => 0
+   #    path1 <=> path3 # => -1
+   #
    def <=>(string)
       return nil unless string.kind_of?(Pathname)
       super
@@ -413,20 +560,33 @@ class Pathname < String
 
    # Returns the parent directory of the given path.
    #
+   # Example:
+   #
+   #    Pathname.new('/usr/local/bin').parent # => '/usr/local'
+   #
    def parent
       self + ".."
    end
 
    # 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.
+   # the argument must be relative too. For relative paths, this method
+   # an imaginary, common parent path.
    #
    # This method does not access the filesystem.  It assumes no symlinks.
    # You should only compare directories against directories, or files against
-   # files, or you may not get expected results.
+   # files, or you may get unexpected results.
    #
    # Raises an ArgumentError if it cannot find a relative path.
    #
+   # Examples:
+   #
+   #    path = Pathname.new('/usr/local/bin')
+   #    path.relative_path_from('/usr/bin') # => "../local/bin"
+   #
+   #    path = Pathname.new("C:\\WINNT\\Fonts")
+   #    path.relative_path_from("C:\\Program Files") # => "..\\WINNT\\Fonts"
+   #
    def relative_path_from(base)
       base = self.class.new(base) unless base.kind_of?(Pathname)
 
@@ -478,14 +638,15 @@ class Pathname < String
    # Adds two Pathname objects together, or a Pathname and a String.  It
    # also automatically cleans the Pathname.
    #
+   # Adding a root path to an existing path merely replaces the current
+   # path.  Adding '.' to an existing path does nothing.
+   #
    # Example:
+   #
    #    path1 = '/foo/bar'
    #    path2 = '../baz'
    #    path1 + path2 # '/foo/baz'
    #
-   # Adding a root path to an existing path merely replaces the current
-   # path.  Adding '.' to an existing path does nothing.
-   #
    def +(string)
       unless string.kind_of?(Pathname)
          string = self.class.new(string)
@@ -517,16 +678,27 @@ class Pathname < String
       
       self.class.new(new_string).clean
    end
+
    alias :/ :+
 
    # Returns whether or not the path is an absolute path.
    #
+   # Example:
+   #
+   #    Pathname.new('/usr/bin').absolute? # => true
+   #    Pathname.new('usr').absolute?      # => false
+   #
    def absolute?
       !relative?
    end
    
    # Returns whether or not the path is a relative path.
    #
+   # Example:
+   #
+   #    Pathname.new('/usr/bin').relative? # => true
+   #    Pathname.new('usr').relative?      # => false
+   #
    def relative?
       if @win
          PathIsRelative(self)
@@ -536,7 +708,12 @@ class Pathname < String
    end
 
    # Removes unnecessary '.' paths and ellides '..' paths appropriately.
-   # Non-destructive.
+   # This method is non-destructive.
+   #
+   # Example:
+   #
+   #    path = Pathname.new('/usr/./local/../bin')
+   #    path.clean # => '/usr/bin'
    #
    def clean
       return self if self.empty?
@@ -551,6 +728,7 @@ class Pathname < String
       end
 
       final = []
+
       to_a.each{ |element|
          next if element == "."
          final.push(element)
@@ -558,15 +736,18 @@ class Pathname < String
             2.times{ final.pop }
          end
       }
+
       final = final.join(@sep)
       final = root._plus_(final) if root != "."
       final = "." if final.empty?
+
       self.class.new(final)
    end
+
    alias :cleanpath :clean
    
-   # Removes unnecessary '.' paths and ellides '..' paths appropriately.
-   # Modifies the receiver in place.
+   # Identical to Pathname#clean, except that it modifies the receiver
+   # in place.
    #
    def clean!
       return self if self.empty?
@@ -580,6 +761,7 @@ class Pathname < String
       end
 
       final = []
+
       to_a.each{ |element|
          next if element == "."
          final.push(element)
@@ -587,13 +769,17 @@ class Pathname < String
             2.times{ final.pop }
          end
       }
+
       final = final.join(@sep)
       final = root + final if root != "."
       final = "." if final.empty?
       replace(self.class.new(final))
+
       self
    end
 
+   alias cleanpath! clean!
+
    #-- Find facade
 
    # Pathname#find is an iterator to traverse a directory tree in a depth first
@@ -874,7 +1060,3 @@ module Kernel
       instance_eval{ Pathname.new(yield) }
    end
 end
-
-if $0 == __FILE__
-   path = Pathname.new(Dir.pwd)
-end

data/test/test_pathname.rb

@@ -7,6 +7,8 @@
 ##############################################################################
 require 'pathname2'
 require 'test/unit'
+require 'rbconfig'
+include Config
 
 class MyPathname < Pathname; end
 
@@ -63,7 +65,7 @@ class TC_Pathname < Test::Unit::TestCase
    end
 
    def test_version
-      assert_equal('1.6.0', Pathname::VERSION)
+      assert_equal('1.6.1', Pathname::VERSION)
    end
 
    def test_file_url_path
@@ -75,7 +77,7 @@ class TC_Pathname < Test::Unit::TestCase
       assert_equal(@pwd, Pathname.new('.').realpath)
       assert_kind_of(Pathname, Pathname.new('/dev/stdin').realpath)
       assert(Pathname.new('/dev/stdin') != Pathname.new('/dev/stdin').realpath)
-      if RUBY_PLATFORM =~ /bsd|darwin|mac/i
+      if CONFIG['host_os'] =~ /bsd|darwin|mac/i
          assert_raises(Errno::ENOENT){ Pathname.new('../blahblah/bogus').realpath }
       else
          assert_raises(Errno::ENOENT){ Pathname.new('../bogus').realpath }
@@ -83,7 +85,7 @@ class TC_Pathname < Test::Unit::TestCase
    end
 
    def test_realpath_platform
-      case RUBY_PLATFORM
+      case CONFIG['host_os']
          when /linux/i
             path1 = '/dev/stdin'
             assert_equal('/dev/pts/0', Pathname.new(path1).realpath)
@@ -229,7 +231,6 @@ class TC_Pathname < Test::Unit::TestCase
             Dir.pwd + '/Rakefile',
             Dir.pwd + '/examples',
             Dir.pwd + '/ext',
-            Dir.pwd + '/install.rb',
             Dir.pwd + '/lib',
             Dir.pwd + '/pathname2.gemspec',
             Dir.pwd + '/test'
@@ -246,7 +247,7 @@ class TC_Pathname < Test::Unit::TestCase
       assert_equal(
          [
             'CHANGES', 'MANIFEST', 'README', 'Rakefile', 'examples', 'ext',
-            'install.rb', 'lib', 'pathname2.gemspec', 'test'
+            'lib', 'pathname2.gemspec', 'test'
          ],
          children.sort
       )

data/test/test_pathname_windows.rb

@@ -1,5 +1,5 @@
 ##########################################################################
-# tc_pathname_win.rb
+# test_pathname_win.rb
 #
 # MS Windows test suite for the Pathname class. To test explicitly
 # against the C extension pass the letter 'c' as an argument. You should
@@ -39,8 +39,28 @@ class TC_Pathname_MSWin < Test::Unit::TestCase
       @unc_array = []
    end
    
+   def test_aref_with_range
+      assert_equal("C:\\Program Files", @fpath[0..1])
+      assert_equal("C:\\Program Files\\Windows NT", @fpath[0..2])
+      assert_equal("Program Files\\Windows NT", @fpath[1..2])
+      assert_equal(@fpath, @fpath[0..-1])
+   end
+   
+   def test_aref_with_index_and_length
+      assert_equal("C:", @fpath[0,1])
+      assert_equal("C:\\Program Files", @fpath[0,2])
+      assert_equal("Program Files\\Windows NT", @fpath[1,2])
+   end
+   
+   def test_aref_with_index
+      assert_equal("C:", @fpath[0])
+      assert_equal("Program Files", @fpath[1])
+      assert_equal("Accessories", @fpath[-1])
+      assert_equal(nil, @fpath[10])
+   end
+
    def test_version
-      assert_equal("1.6.0", Pathname::VERSION)
+      assert_equal("1.6.1", Pathname::VERSION)
    end
 
    # Convenience method for test_plus
@@ -596,8 +616,8 @@ class TC_Pathname_MSWin < Test::Unit::TestCase
       
       assert_equal(
          [
-            "CHANGES","examples","ext","install.rb","lib",
-            "MANIFEST", "pathname2.gemspec", "Rakefile", "README", "test"
+            "CHANGES", "examples", "ext", "lib", "MANIFEST",
+            "pathname2.gemspec", "Rakefile", "README", "test"
          ],
          children
       )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: pathname2
 version: !ruby/object:Gem::Version 
-  version: 1.6.0
+  version: 1.6.1
 platform: ruby
 authors: 
 - Daniel J. Berger
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-15 00:00:00 -06:00
+date: 2008-11-08 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -36,12 +36,10 @@ files:
 - lib/pathname2.rb
 - CHANGES
 - MANIFEST
-- README
 - Rakefile
-- CVS
+- README
 - test/test_pathname.rb
 - test/test_pathname_windows.rb
-- test/CVS
 has_rdoc: true
 homepage: http://www.rubyforge.org/projects/shards
 post_install_message: