lib/pathname.rb

   1 #
   2 # = pathname.rb
   3 #
   4 # Object-Oriented Pathname Class
   5 #
   6 # Author:: Tanaka Akira <akr@m17n.org>
   7 # Documentation:: Author and Gavin Sinclair
   8 #
   9 # For documentation, see class Pathname.
  10 #
  11 # <tt>pathname.rb</tt> is distributed with Ruby since 1.8.0.
  12 #
  13
  14 #
  15 # == Pathname
  16 #
  17 # Pathname represents a pathname which locates a file in a filesystem.
  18 # The pathname depends on OS: Unix, Windows, etc.
  19 # Pathname library works with pathnames of local OS.
  20 # However non-Unix pathnames are supported experimentally.
  21 #
  22 # It does not represent the file itself.
  23 # A Pathname can be relative or absolute.  It's not until you try to
  24 # reference the file that it even matters whether the file exists or not.
  25 #
  26 # Pathname is immutable.  It has no method for destructive update.
  27 #
  28 # The value of this class is to manipulate file path information in a neater
  29 # way than standard Ruby provides.  The examples below demonstrate the
  30 # difference.  *All* functionality from File, FileTest, and some from Dir and
  31 # FileUtils is included, in an unsurprising way.  It is essentially a facade for
  32 # all of these, and more.
  33 #
  34 # == Examples
  35 #
  36 # === Example 1: Using Pathname
  37 #
  38 #   require 'pathname'
  39 #   p = Pathname.new("/usr/bin/ruby")
  40 #   size = p.size              # 27662
  41 #   isdir = p.directory?       # false
  42 #   dir  = p.dirname           # Pathname:/usr/bin
  43 #   base = p.basename          # Pathname:ruby
  44 #   dir, base = p.split        # [Pathname:/usr/bin, Pathname:ruby]
  45 #   data = p.read
  46 #   p.open { |f| _ }
  47 #   p.each_line { |line| _ }
  48 #
  49 # === Example 2: Using standard Ruby
  50 #
  51 #   p = "/usr/bin/ruby"
  52 #   size = File.size(p)        # 27662
  53 #   isdir = File.directory?(p) # false
  54 #   dir  = File.dirname(p)     # "/usr/bin"
  55 #   base = File.basename(p)    # "ruby"
  56 #   dir, base = File.split(p)  # ["/usr/bin", "ruby"]
  57 #   data = File.read(p)
  58 #   File.open(p) { |f| _ }
  59 #   File.foreach(p) { |line| _ }
  60 #
  61 # === Example 3: Special features
  62 #
  63 #   p1 = Pathname.new("/usr/lib")   # Pathname:/usr/lib
  64 #   p2 = p1 + "ruby/1.8"            # Pathname:/usr/lib/ruby/1.8
  65 #   p3 = p1.parent                  # Pathname:/usr
  66 #   p4 = p2.relative_path_from(p3)  # Pathname:lib/ruby/1.8
  67 #   pwd = Pathname.pwd              # Pathname:/home/gavin
  68 #   pwd.absolute?                   # true
  69 #   p5 = Pathname.new "."           # Pathname:.
  70 #   p5 = p5 + "music/../articles"   # Pathname:music/../articles
  71 #   p5.cleanpath                    # Pathname:articles
  72 #   p5.realpath                     # Pathname:/home/gavin/articles
  73 #   p5.children                     # [Pathname:/home/gavin/articles/linux, ...]
  74 #
  75 # == Breakdown of functionality
  76 #
  77 # === Core methods
  78 #
  79 # These methods are effectively manipulating a String, because that's all a path
  80 # is.  Except for #mountpoint?, #children, and #realpath, they don't access the
  81 # filesystem.
  82 #
  83 # - +
  84 # - #join
  85 # - #parent
  86 # - #root?
  87 # - #absolute?
  88 # - #relative?
  89 # - #relative_path_from
  90 # - #each_filename
  91 # - #cleanpath
  92 # - #realpath
  93 # - #children
  94 # - #mountpoint?
  95 #
  96 # === File status predicate methods
  97 #
  98 # These methods are a facade for FileTest:
  99 # - #blockdev?
 100 # - #chardev?
 101 # - #directory?
 102 # - #executable?
 103 # - #executable_real?
 104 # - #exist?
 105 # - #file?
 106 # - #grpowned?
 107 # - #owned?
 108 # - #pipe?
 109 # - #readable?
 110 # - #world_readable?
 111 # - #readable_real?
 112 # - #setgid?
 113 # - #setuid?
 114 # - #size
 115 # - #size?
 116 # - #socket?
 117 # - #sticky?
 118 # - #symlink?
 119 # - #writable?
 120 # - #world_writable?
 121 # - #writable_real?
 122 # - #zero?
 123 #
 124 # === File property and manipulation methods
 125 #
 126 # These methods are a facade for File:
 127 # - #atime
 128 # - #ctime
 129 # - #mtime
 130 # - #chmod(mode)
 131 # - #lchmod(mode)
 132 # - #chown(owner, group)
 133 # - #lchown(owner, group)
 134 # - #fnmatch(pattern, *args)
 135 # - #fnmatch?(pattern, *args)
 136 # - #ftype
 137 # - #make_link(old)
 138 # - #open(*args, &block)
 139 # - #readlink
 140 # - #rename(to)
 141 # - #stat
 142 # - #lstat
 143 # - #make_symlink(old)
 144 # - #truncate(length)
 145 # - #utime(atime, mtime)
 146 # - #basename(*args)
 147 # - #dirname
 148 # - #extname
 149 # - #expand_path(*args)
 150 # - #split
 151 #
 152 # === Directory methods
 153 #
 154 # These methods are a facade for Dir:
 155 # - Pathname.glob(*args)
 156 # - Pathname.getwd / Pathname.pwd
 157 # - #rmdir
 158 # - #entries
 159 # - #each_entry(&block)
 160 # - #mkdir(*args)
 161 # - #opendir(*args)
 162 #
 163 # === IO
 164 #
 165 # These methods are a facade for IO:
 166 # - #each_line(*args, &block)
 167 # - #read(*args)
 168 # - #readlines(*args)
 169 # - #sysopen(*args)
 170 #
 171 # === Utilities
 172 #
 173 # These methods are a mixture of Find, FileUtils, and others:
 174 # - #find(&block)
 175 # - #mkpath
 176 # - #rmtree
 177 # - #unlink / #delete
 178 #
 179 #
 180 # == Method documentation
 181 #
 182 # As the above section shows, most of the methods in Pathname are facades.  The
 183 # documentation for these methods generally just says, for instance, "See
 184 # FileTest.writable?", as you should be familiar with the original method
 185 # anyway, and its documentation (e.g. through +ri+) will contain more
 186 # information.  In some cases, a brief description will follow.
 187 #
 188 class Pathname
 189
 190   # :stopdoc:
 191   if RUBY_VERSION < "1.9"
 192     TO_PATH = :to_str
 193   else
 194     # to_path is implemented so Pathname objects are usable with File.open, etc.
 195     TO_PATH = :to_path
 196   end
 197   # :startdoc:
 198
 199   #
 200   # Create a Pathname object from the given String (or String-like object).
 201   # If +path+ contains a NUL character (<tt>\0</tt>), an ArgumentError is raised.
 202   #
 203   def initialize(path)
 204     path = path.__send__(TO_PATH) if path.respond_to? TO_PATH
 205     @path = path.dup
 206
 207     if /\0/ =~ @path
 208       raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
 209     end
 210
 211     self.taint if @path.tainted?
 212   end
 213
 214   def freeze() super; @path.freeze; self end
 215   def taint() super; @path.taint; self end
 216   def untaint() super; @path.untaint; self end
 217
 218   #
 219   # Compare this pathname with +other+.  The comparison is string-based.
 220   # Be aware that two different paths (<tt>foo.txt</tt> and <tt>./foo.txt</tt>)
 221   # can refer to the same file.
 222   #
 223   def ==(other)
 224     return false unless Pathname === other
 225     other.to_s == @path
 226   end
 227   alias === ==
 228   alias eql? ==
 229
 230   # Provides for comparing pathnames, case-sensitively.
 231   def <=>(other)
 232     return nil unless Pathname === other
 233     @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
 234   end
 235
 236   def hash # :nodoc:
 237     @path.hash
 238   end
 239
 240   # Return the path as a String.
 241   def to_s
 242     @path.dup
 243   end
 244
 245   # to_path is implemented so Pathname objects are usable with File.open, etc.
 246   alias_method TO_PATH, :to_s
 247
 248   def inspect # :nodoc:
 249     "#<#{self.class}:#{@path}>"
 250   end
 251
 252   # Return a pathname which is substituted by String#sub.
 253   def sub(pattern, *rest, &block)
 254     self.class.new(@path.sub(pattern, *rest, &block))
 255   end
 256
 257   if File::ALT_SEPARATOR
 258     SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}"
 259     SEPARATOR_PAT = /[#{SEPARATOR_LIST}]/
 260   else
 261     SEPARATOR_LIST = "#{Regexp.quote File::SEPARATOR}"
 262     SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/
 263   end
 264
 265   # Return a pathname which the extension of the basename is substituted by
 266   # <i>repl</i>.
 267   #
 268   # If self has no extension part, <i>repl</i> is appended.
 269   def sub_ext(repl)
 270     ext = File.extname(@path)
 271     self.class.new(@path.chomp(ext) + repl)
 272   end
 273
 274   # chop_basename(path) -> [pre-basename, basename] or nil
 275   def chop_basename(path)
 276     base = File.basename(path)
 277     if /\A#{SEPARATOR_PAT}?\z/ =~ base
 278       return nil
 279     else
 280       return path[0, path.rindex(base)], base
 281     end
 282   end
 283   private :chop_basename
 284
 285   # split_names(path) -> prefix, [name, ...]
 286   def split_names(path)
 287     names = []
 288     while r = chop_basename(path)
 289       path, basename = r
 290       names.unshift basename
 291     end
 292     return path, names
 293   end
 294   private :split_names
 295
 296   def prepend_prefix(prefix, relpath)
 297     if relpath.empty?
 298       File.dirname(prefix)
 299     elsif /#{SEPARATOR_PAT}/ =~ prefix
 300       prefix = File.dirname(prefix)
 301       prefix = File.join(prefix, "") if File.basename(prefix + 'a') != 'a'
 302       prefix + relpath
 303     else
 304       prefix + relpath
 305     end
 306   end
 307   private :prepend_prefix
 308
 309   # Returns clean pathname of +self+ with consecutive slashes and useless dots
 310   # removed.  The filesystem is not accessed.
 311   #
 312   # If +consider_symlink+ is +true+, then a more conservative algorithm is used
 313   # to avoid breaking symbolic linkages.  This may retain more <tt>..</tt>
 314   # entries than absolutely necessary, but without accessing the filesystem,
 315   # this can't be avoided.  See #realpath.
 316   #
 317   def cleanpath(consider_symlink=false)
 318     if consider_symlink
 319       cleanpath_conservative
 320     else
 321       cleanpath_aggressive
 322     end
 323   end
 324
 325   #
 326   # Clean the path simply by resolving and removing excess "." and ".." entries.
 327   # Nothing more, nothing less.
 328   #
 329   def cleanpath_aggressive
 330     path = @path
 331     names = []
 332     pre = path
 333     while r = chop_basename(pre)
 334       pre, base = r
 335       case base
 336       when '.'
 337       when '..'
 338         names.unshift base
 339       else
 340         if names[0] == '..'
 341           names.shift
 342         else
 343           names.unshift base
 344         end
 345       end
 346     end
 347     if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
 348       names.shift while names[0] == '..'
 349     end
 350     self.class.new(prepend_prefix(pre, File.join(*names)))
 351   end
 352   private :cleanpath_aggressive
 353
 354   # has_trailing_separator?(path) -> bool
 355   def has_trailing_separator?(path)
 356     if r = chop_basename(path)
 357       pre, basename = r
 358       pre.length + basename.length < path.length
 359     else
 360       false
 361     end
 362   end
 363   private :has_trailing_separator?
 364
 365   # add_trailing_separator(path) -> path
 366   def add_trailing_separator(path)
 367     if File.basename(path + 'a') == 'a'
 368       path
 369     else
 370       File.join(path, "") # xxx: Is File.join is appropriate to add separator?
 371     end
 372   end
 373   private :add_trailing_separator
 374
 375   def del_trailing_separator(path)
 376     if r = chop_basename(path)
 377       pre, basename = r
 378       pre + basename
 379     elsif /#{SEPARATOR_PAT}+\z/o =~ path
 380       $` + File.dirname(path)[/#{SEPARATOR_PAT}*\z/o]
 381     else
 382       path
 383     end
 384   end
 385   private :del_trailing_separator
 386
 387   def cleanpath_conservative
 388     path = @path
 389     names = []
 390     pre = path
 391     while r = chop_basename(pre)
 392       pre, base = r
 393       names.unshift base if base != '.'
 394     end
 395     if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
 396       names.shift while names[0] == '..'
 397     end
 398     if names.empty?
 399       self.class.new(File.dirname(pre))
 400     else
 401       if names.last != '..' && File.basename(path) == '.'
 402         names << '.'
 403       end
 404       result = prepend_prefix(pre, File.join(*names))
 405       if /\A(?:\.|\.\.)\z/ !~ names.last && has_trailing_separator?(path)
 406         self.class.new(add_trailing_separator(result))
 407       else
 408         self.class.new(result)
 409       end
 410     end
 411   end
 412   private :cleanpath_conservative
 413
 414   def realpath_rec(prefix, unresolved, h)
 415     resolved = []
 416     until unresolved.empty?
 417       n = unresolved.shift
 418       if n == '.'
 419         next
 420       elsif n == '..'
 421         resolved.pop
 422       else
 423         path = prepend_prefix(prefix, File.join(*(resolved + [n])))
 424         if h.include? path
 425           if h[path] == :resolving
 426             raise Errno::ELOOP.new(path)
 427           else
 428             prefix, *resolved = h[path]
 429           end
 430         else
 431           s = File.lstat(path)
 432           if s.symlink?
 433             h[path] = :resolving
 434             link_prefix, link_names = split_names(File.readlink(path))
 435             if link_prefix == ''
 436               prefix, *resolved = h[path] = realpath_rec(prefix, resolved + link_names, h)
 437             else
 438               prefix, *resolved = h[path] = realpath_rec(link_prefix, link_names, h)
 439             end
 440           else
 441             resolved << n
 442             h[path] = [prefix, *resolved]
 443           end
 444         end
 445       end
 446     end
 447     return prefix, *resolved
 448   end
 449   private :realpath_rec
 450
 451   #
 452   # Returns a real (absolute) pathname of +self+ in the actual filesystem.
 453   # The real pathname doesn't contain symlinks or useless dots.
 454   #
 455   # No arguments should be given; the old behaviour is *obsoleted*.
 456   #
 457   def realpath
 458     path = @path
 459     prefix, names = split_names(path)
 460     if prefix == ''
 461       prefix, names2 = split_names(Dir.pwd)
 462       names = names2 + names
 463     end
 464     prefix, *names = realpath_rec(prefix, names, {})
 465     self.class.new(prepend_prefix(prefix, File.join(*names)))
 466   end
 467
 468   # #parent returns the parent directory.
 469   #
 470   # This is same as <tt>self + '..'</tt>.
 471   def parent
 472     self + '..'
 473   end
 474
 475   # #mountpoint? returns +true+ if <tt>self</tt> points to a mountpoint.
 476   def mountpoint?
 477     begin
 478       stat1 = self.lstat
 479       stat2 = self.parent.lstat
 480       stat1.dev == stat2.dev && stat1.ino == stat2.ino ||
 481         stat1.dev != stat2.dev
 482     rescue Errno::ENOENT
 483       false
 484     end
 485   end
 486
 487   #
 488   # #root? is a predicate for root directories.  I.e. it returns +true+ if the
 489   # pathname consists of consecutive slashes.
 490   #
 491   # It doesn't access actual filesystem.  So it may return +false+ for some
 492   # pathnames which points to roots such as <tt>/usr/..</tt>.
 493   #
 494   def root?
 495     !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o =~ @path)
 496   end
 497
 498   # Predicate method for testing whether a path is absolute.
 499   # It returns +true+ if the pathname begins with a slash.
 500   def absolute?
 501     !relative?
 502   end
 503
 504   # The opposite of #absolute?
 505   def relative?
 506     path = @path
 507     while r = chop_basename(path)
 508       path, basename = r
 509     end
 510     path == ''
 511   end
 512
 513   #
 514   # Iterates over each component of the path.
 515   #
 516   #   Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
 517   #     # yields "usr", "bin", and "ruby".
 518   #
 519   def each_filename # :yield: filename
 520     prefix, names = split_names(@path)
 521     names.each {|filename| yield filename }
 522     nil
 523   end
 524
 525   # Iterates over and yields a new Pathname object
 526   # for each element in the given path in descending order.
 527   #
 528   #  Pathname.new('/path/to/some/file.rb').descend {|v| p v}
 529   #     #<Pathname:/>
 530   #     #<Pathname:/path>
 531   #     #<Pathname:/path/to>
 532   #     #<Pathname:/path/to/some>
 533   #     #<Pathname:/path/to/some/file.rb>
 534   #
 535   #  Pathname.new('path/to/some/file.rb').descend {|v| p v}
 536   #     #<Pathname:path>
 537   #     #<Pathname:path/to>
 538   #     #<Pathname:path/to/some>
 539   #     #<Pathname:path/to/some/file.rb>
 540   #
 541   # It doesn't access actual filesystem.
 542   #
 543   # This method is available since 1.8.5.
 544   #
 545   def descend
 546     vs = []
 547     ascend {|v| vs << v }
 548     vs.reverse_each {|v| yield v }
 549     nil
 550   end
 551
 552   # Iterates over and yields a new Pathname object
 553   # for each element in the given path in ascending order.
 554   #
 555   #  Pathname.new('/path/to/some/file.rb').ascend {|v| p v}
 556   #     #<Pathname:/path/to/some/file.rb>
 557   #     #<Pathname:/path/to/some>
 558   #     #<Pathname:/path/to>
 559   #     #<Pathname:/path>
 560   #     #<Pathname:/>
 561   #
 562   #  Pathname.new('path/to/some/file.rb').ascend {|v| p v}
 563   #     #<Pathname:path/to/some/file.rb>
 564   #     #<Pathname:path/to/some>
 565   #     #<Pathname:path/to>
 566   #     #<Pathname:path>
 567   #
 568   # It doesn't access actual filesystem.
 569   #
 570   # This method is available since 1.8.5.
 571   #
 572   def ascend
 573     path = @path
 574     yield self
 575     while r = chop_basename(path)
 576       path, name = r
 577       break if path.empty?
 578       yield self.class.new(del_trailing_separator(path))
 579     end
 580   end
 581
 582   #
 583   # Pathname#+ appends a pathname fragment to this one to produce a new Pathname
 584   # object.
 585   #
 586   #   p1 = Pathname.new("/usr")      # Pathname:/usr
 587   #   p2 = p1 + "bin/ruby"           # Pathname:/usr/bin/ruby
 588   #   p3 = p1 + "/etc/passwd"        # Pathname:/etc/passwd
 589   #
 590   # This method doesn't access the file system; it is pure string manipulation.
 591   #
 592   def +(other)
 593     other = Pathname.new(other) unless Pathname === other
 594     Pathname.new(plus(@path, other.to_s))
 595   end
 596
 597   def plus(path1, path2) # -> path
 598     prefix2 = path2
 599     index_list2 = []
 600     basename_list2 = []
 601     while r2 = chop_basename(prefix2)
 602       prefix2, basename2 = r2
 603       index_list2.unshift prefix2.length
 604       basename_list2.unshift basename2
 605     end
 606     return path2 if prefix2 != ''
 607     prefix1 = path1
 608     while true
 609       while !basename_list2.empty? && basename_list2.first == '.'
 610         index_list2.shift
 611         basename_list2.shift
 612       end
 613       break unless r1 = chop_basename(prefix1)
 614       prefix1, basename1 = r1
 615       next if basename1 == '.'
 616       if basename1 == '..' || basename_list2.empty? || basename_list2.first != '..'
 617         prefix1 = prefix1 + basename1
 618         break
 619       end
 620       index_list2.shift
 621       basename_list2.shift
 622     end
 623     r1 = chop_basename(prefix1)
 624     if !r1 && /#{SEPARATOR_PAT}/o =~ File.basename(prefix1)
 625       while !basename_list2.empty? && basename_list2.first == '..'
 626         index_list2.shift
 627         basename_list2.shift
 628       end
 629     end
 630     if !basename_list2.empty?
 631       suffix2 = path2[index_list2.first..-1]
 632       r1 ? File.join(prefix1, suffix2) : prefix1 + suffix2
 633     else
 634       r1 ? prefix1 : File.dirname(prefix1)
 635     end
 636   end
 637   private :plus
 638
 639   #
 640   # Pathname#join joins pathnames.
 641   #
 642   # <tt>path0.join(path1, ..., pathN)</tt> is the same as
 643   # <tt>path0 + path1 + ... + pathN</tt>.
 644   #
 645   def join(*args)
 646     args.unshift self
 647     result = args.pop
 648     result = Pathname.new(result) unless Pathname === result
 649     return result if result.absolute?
 650     args.reverse_each {|arg|
 651       arg = Pathname.new(arg) unless Pathname === arg
 652       result = arg + result
 653       return result if result.absolute?
 654     }
 655     result
 656   end
 657
 658   #
 659   # Returns the children of the directory (files and subdirectories, not
 660   # recursive) as an array of Pathname objects.  By default, the returned
 661   # pathnames will have enough information to access the files.  If you set
 662   # +with_directory+ to +false+, then the returned pathnames will contain the
 663   # filename only.
 664   #
 665   # For example:
 666   #   p = Pathname("/usr/lib/ruby/1.8")
 667   #   p.children
 668   #       # -> [ Pathname:/usr/lib/ruby/1.8/English.rb,
 669   #              Pathname:/usr/lib/ruby/1.8/Env.rb,
 670   #              Pathname:/usr/lib/ruby/1.8/abbrev.rb, ... ]
 671   #   p.children(false)
 672   #       # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]
 673   #
 674   # Note that the result never contain the entries <tt>.</tt> and <tt>..</tt> in
 675   # the directory because they are not children.
 676   #
 677   # This method has existed since 1.8.1.
 678   #
 679   def children(with_directory=true)
 680     with_directory = false if @path == '.'
 681     result = []
 682     Dir.foreach(@path) {|e|
 683       next if e == '.' || e == '..'
 684       if with_directory
 685         result << self.class.new(File.join(@path, e))
 686       else
 687         result << self.class.new(e)
 688       end
 689     }
 690     result
 691   end
 692
 693   #
 694   # #relative_path_from returns a relative path from the argument to the
 695   # receiver.  If +self+ is absolute, the argument must be absolute too.  If
 696   # +self+ is relative, the argument must be relative too.
 697   #
 698   # #relative_path_from doesn't access the filesystem.  It assumes no symlinks.
 699   #
 700   # ArgumentError is raised when it cannot find a relative path.
 701   #
 702   # This method has existed since 1.8.1.
 703   #
 704   def relative_path_from(base_directory)
 705     dest_directory = self.cleanpath.to_s
 706     base_directory = base_directory.cleanpath.to_s
 707     dest_prefix = dest_directory
 708     dest_names = []
 709     while r = chop_basename(dest_prefix)
 710       dest_prefix, basename = r
 711       dest_names.unshift basename if basename != '.'
 712     end
 713     base_prefix = base_directory
 714     base_names = []
 715     while r = chop_basename(base_prefix)
 716       base_prefix, basename = r
 717       base_names.unshift basename if basename != '.'
 718     end
 719     if dest_prefix != base_prefix
 720       raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}"
 721     end
 722     while !dest_names.empty? &&
 723           !base_names.empty? &&
 724           dest_names.first == base_names.first
 725       dest_names.shift
 726       base_names.shift
 727     end
 728     if base_names.include? '..'
 729       raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
 730     end
 731     base_names.fill('..')
 732     relpath_names = base_names + dest_names
 733     if relpath_names.empty?
 734       Pathname.new('.')
 735     else
 736       Pathname.new(File.join(*relpath_names))
 737     end
 738   end
 739 end
 740
 741 class Pathname    # * IO *
 742   #
 743   # #each_line iterates over the line in the file.  It yields a String object
 744   # for each line.
 745   #
 746   # This method has existed since 1.8.1.
 747   #
 748   def each_line(*args, &block) # :yield: line
 749     IO.foreach(@path, *args, &block)
 750   end
 751
 752   # Pathname#foreachline is *obsoleted* at 1.8.1.  Use #each_line.
 753   def foreachline(*args, &block)
 754     warn "Pathname#foreachline is obsoleted.  Use Pathname#each_line."
 755     each_line(*args, &block)
 756   end
 757
 758   # See <tt>IO.read</tt>.  Returns all the bytes from the file, or the first +N+
 759   # if specified.
 760   def read(*args) IO.read(@path, *args) end
 761
 762   # See <tt>IO.readlines</tt>.  Returns all the lines from the file.
 763   def readlines(*args) IO.readlines(@path, *args) end
 764
 765   # See <tt>IO.sysopen</tt>.
 766   def sysopen(*args) IO.sysopen(@path, *args) end
 767 end
 768
 769
 770 class Pathname    # * File *
 771
 772   # See <tt>File.atime</tt>.  Returns last access time.
 773   def atime() File.atime(@path) end
 774
 775   # See <tt>File.ctime</tt>.  Returns last (directory entry, not file) change time.
 776   def ctime() File.ctime(@path) end
 777
 778   # See <tt>File.mtime</tt>.  Returns last modification time.
 779   def mtime() File.mtime(@path) end
 780
 781   # See <tt>File.chmod</tt>.  Changes permissions.
 782   def chmod(mode) File.chmod(mode, @path) end
 783
 784   # See <tt>File.lchmod</tt>.
 785   def lchmod(mode) File.lchmod(mode, @path) end
 786
 787   # See <tt>File.chown</tt>.  Change owner and group of file.
 788   def chown(owner, group) File.chown(owner, group, @path) end
 789
 790   # See <tt>File.lchown</tt>.
 791   def lchown(owner, group) File.lchown(owner, group, @path) end
 792
 793   # See <tt>File.fnmatch</tt>.  Return +true+ if the receiver matches the given
 794   # pattern.
 795   def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end
 796
 797   # See <tt>File.fnmatch?</tt> (same as #fnmatch).
 798   def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end
 799
 800   # See <tt>File.ftype</tt>.  Returns "type" of file ("file", "directory",
 801   # etc).
 802   def ftype() File.ftype(@path) end
 803
 804   # See <tt>File.link</tt>.  Creates a hard link.
 805   def make_link(old) File.link(old, @path) end
 806
 807   # See <tt>File.open</tt>.  Opens the file for reading or writing.
 808   def open(*args, &block) # :yield: file
 809     File.open(@path, *args, &block)
 810   end
 811
 812   # See <tt>File.readlink</tt>.  Read symbolic link.
 813   def readlink() self.class.new(File.readlink(@path)) end
 814
 815   # See <tt>File.rename</tt>.  Rename the file.
 816   def rename(to) File.rename(@path, to) end
 817
 818   # See <tt>File.stat</tt>.  Returns a <tt>File::Stat</tt> object.
 819   def stat() File.stat(@path) end
 820
 821   # See <tt>File.lstat</tt>.
 822   def lstat() File.lstat(@path) end
 823
 824   # See <tt>File.symlink</tt>.  Creates a symbolic link.
 825   def make_symlink(old) File.symlink(old, @path) end
 826
 827   # See <tt>File.truncate</tt>.  Truncate the file to +length+ bytes.
 828   def truncate(length) File.truncate(@path, length) end
 829
 830   # See <tt>File.utime</tt>.  Update the access and modification times.
 831   def utime(atime, mtime) File.utime(atime, mtime, @path) end
 832
 833   # See <tt>File.basename</tt>.  Returns the last component of the path.
 834   def basename(*args) self.class.new(File.basename(@path, *args)) end
 835
 836   # See <tt>File.dirname</tt>.  Returns all but the last component of the path.
 837   def dirname() self.class.new(File.dirname(@path)) end
 838
 839   # See <tt>File.extname</tt>.  Returns the file's extension.
 840   def extname() File.extname(@path) end
 841
 842   # See <tt>File.expand_path</tt>.
 843   def expand_path(*args) self.class.new(File.expand_path(@path, *args)) end
 844
 845   # See <tt>File.split</tt>.  Returns the #dirname and the #basename in an
 846   # Array.
 847   def split() File.split(@path).map {|f| self.class.new(f) } end
 848
 849   # Pathname#link is confusing and *obsoleted* because the receiver/argument
 850   # order is inverted to corresponding system call.
 851   def link(old)
 852     warn 'Pathname#link is obsoleted.  Use Pathname#make_link.'
 853     File.link(old, @path)
 854   end
 855
 856   # Pathname#symlink is confusing and *obsoleted* because the receiver/argument
 857   # order is inverted to corresponding system call.
 858   def symlink(old)
 859     warn 'Pathname#symlink is obsoleted.  Use Pathname#make_symlink.'
 860     File.symlink(old, @path)
 861   end
 862 end
 863
 864
 865 class Pathname    # * FileTest *
 866
 867   # See <tt>FileTest.blockdev?</tt>.
 868   def blockdev?() FileTest.blockdev?(@path) end
 869
 870   # See <tt>FileTest.chardev?</tt>.
 871   def chardev?() FileTest.chardev?(@path) end
 872
 873   # See <tt>FileTest.executable?</tt>.
 874   def executable?() FileTest.executable?(@path) end
 875
 876   # See <tt>FileTest.executable_real?</tt>.
 877   def executable_real?() FileTest.executable_real?(@path) end
 878
 879   # See <tt>FileTest.exist?</tt>.
 880   def exist?() FileTest.exist?(@path) end
 881
 882   # See <tt>FileTest.grpowned?</tt>.
 883   def grpowned?() FileTest.grpowned?(@path) end
 884
 885   # See <tt>FileTest.directory?</tt>.
 886   def directory?() FileTest.directory?(@path) end
 887
 888   # See <tt>FileTest.file?</tt>.
 889   def file?() FileTest.file?(@path) end
 890
 891   # See <tt>FileTest.pipe?</tt>.
 892   def pipe?() FileTest.pipe?(@path) end
 893
 894   # See <tt>FileTest.socket?</tt>.
 895   def socket?() FileTest.socket?(@path) end
 896
 897   # See <tt>FileTest.owned?</tt>.
 898   def owned?() FileTest.owned?(@path) end
 899
 900   # See <tt>FileTest.readable?</tt>.
 901   def readable?() FileTest.readable?(@path) end
 902
 903   # See <tt>FileTest.world_readable?</tt>.
 904   def world_readable?() FileTest.world_readable?(@path) end
 905
 906   # See <tt>FileTest.readable_real?</tt>.
 907   def readable_real?() FileTest.readable_real?(@path) end
 908
 909   # See <tt>FileTest.setuid?</tt>.
 910   def setuid?() FileTest.setuid?(@path) end
 911
 912   # See <tt>FileTest.setgid?</tt>.
 913   def setgid?() FileTest.setgid?(@path) end
 914
 915   # See <tt>FileTest.size</tt>.
 916   def size() FileTest.size(@path) end
 917
 918   # See <tt>FileTest.size?</tt>.
 919   def size?() FileTest.size?(@path) end
 920
 921   # See <tt>FileTest.sticky?</tt>.
 922   def sticky?() FileTest.sticky?(@path) end
 923
 924   # See <tt>FileTest.symlink?</tt>.
 925   def symlink?() FileTest.symlink?(@path) end
 926
 927   # See <tt>FileTest.writable?</tt>.
 928   def writable?() FileTest.writable?(@path) end
 929
 930   # See <tt>FileTest.world_writable?</tt>.
 931   def world_writable?() FileTest.world_writable?(@path) end
 932
 933   # See <tt>FileTest.writable_real?</tt>.
 934   def writable_real?() FileTest.writable_real?(@path) end
 935
 936   # See <tt>FileTest.zero?</tt>.
 937   def zero?() FileTest.zero?(@path) end
 938 end
 939
 940
 941 class Pathname    # * Dir *
 942   # See <tt>Dir.glob</tt>.  Returns or yields Pathname objects.
 943   def Pathname.glob(*args) # :yield: p
 944     if block_given?
 945       Dir.glob(*args) {|f| yield self.new(f) }
 946     else
 947       Dir.glob(*args).map {|f| self.new(f) }
 948     end
 949   end
 950
 951   # See <tt>Dir.getwd</tt>.  Returns the current working directory as a Pathname.
 952   def Pathname.getwd() self.new(Dir.getwd) end
 953   class << self; alias pwd getwd end
 954
 955   # Pathname#chdir is *obsoleted* at 1.8.1.
 956   def chdir(&block)
 957     warn "Pathname#chdir is obsoleted.  Use Dir.chdir."
 958     Dir.chdir(@path, &block)
 959   end
 960
 961   # Pathname#chroot is *obsoleted* at 1.8.1.
 962   def chroot
 963     warn "Pathname#chroot is obsoleted.  Use Dir.chroot."
 964     Dir.chroot(@path)
 965   end
 966
 967   # Return the entries (files and subdirectories) in the directory, each as a
 968   # Pathname object.
 969   def entries() Dir.entries(@path).map {|f| self.class.new(f) } end
 970
 971   # Iterates over the entries (files and subdirectories) in the directory.  It
 972   # yields a Pathname object for each entry.
 973   #
 974   # This method has existed since 1.8.1.
 975   def each_entry(&block) # :yield: p
 976     Dir.foreach(@path) {|f| yield self.class.new(f) }
 977   end
 978
 979   # Pathname#dir_foreach is *obsoleted* at 1.8.1.
 980   def dir_foreach(*args, &block)
 981     warn "Pathname#dir_foreach is obsoleted.  Use Pathname#each_entry."
 982     each_entry(*args, &block)
 983   end
 984
 985   # See <tt>Dir.mkdir</tt>.  Create the referenced directory.
 986   def mkdir(*args) Dir.mkdir(@path, *args) end
 987
 988   # See <tt>Dir.rmdir</tt>.  Remove the referenced directory.
 989   def rmdir() Dir.rmdir(@path) end
 990
 991   # See <tt>Dir.open</tt>.
 992   def opendir(&block) # :yield: dir
 993     Dir.open(@path, &block)
 994   end
 995 end
 996
 997
 998 class Pathname    # * Find *
 999   #
1000   # Pathname#find is an iterator to traverse a directory tree in a depth first
1001   # manner.  It yields a Pathname for each file under "this" directory.
1002   #
1003   # Since it is implemented by <tt>find.rb</tt>, <tt>Find.prune</tt> can be used
1004   # to control the traverse.
1005   #
1006   # If +self+ is <tt>.</tt>, yielded pathnames begin with a filename in the
1007   # current directory, not <tt>./</tt>.
1008   #
1009   def find(&block) # :yield: p
1010     require 'find'
1011     if @path == '.'
1012       Find.find(@path) {|f| yield self.class.new(f.sub(%r{\A\./}, '')) }
1013     else
1014       Find.find(@path) {|f| yield self.class.new(f) }
1015     end
1016   end
1017 end
1018
1019
1020 class Pathname    # * FileUtils *
1021   # See <tt>FileUtils.mkpath</tt>.  Creates a full path, including any
1022   # intermediate directories that don't yet exist.
1023   def mkpath
1024     require 'fileutils'
1025     FileUtils.mkpath(@path)
1026     nil
1027   end
1028
1029   # See <tt>FileUtils.rm_r</tt>.  Deletes a directory and all beneath it.
1030   def rmtree
1031     # The name "rmtree" is borrowed from File::Path of Perl.
1032     # File::Path provides "mkpath" and "rmtree".
1033     require 'fileutils'
1034     FileUtils.rm_r(@path)
1035     nil
1036   end
1037 end
1038
1039
1040 class Pathname    # * mixed *
1041   # Removes a file or directory, using <tt>File.unlink</tt> or
1042   # <tt>Dir.unlink</tt> as necessary.
1043   def unlink()
1044     begin
1045       Dir.unlink @path
1046     rescue Errno::ENOTDIR
1047       File.unlink @path
1048     end
1049   end
1050   alias delete unlink
1051
1052   # This method is *obsoleted* at 1.8.1.  Use #each_line or #each_entry.
1053   def foreach(*args, &block)
1054     warn "Pathname#foreach is obsoleted.  Use each_line or each_entry."
1055     if FileTest.directory? @path
1056       # For polymorphism between Dir.foreach and IO.foreach,
1057       # Pathname#foreach doesn't yield Pathname object.
1058       Dir.foreach(@path, *args, &block)
1059     else
1060       IO.foreach(@path, *args, &block)
1061     end
1062   end
1063 end
1064
1065 module Kernel
1066   # create a pathname object.
1067   #
1068   # This method is available since 1.8.5.
1069   def Pathname(path) # :doc:
1070     Pathname.new(path)
1071   end
1072   private :Pathname
1073 end