Class Pathname
In: lib/pathname.rb
Parent: Object

Pathname

Pathname represents a pathname which locates a file in a filesystem. The pathname depends on OS: Unix, Windows, etc. Pathname library works with pathnames of local OS. However non-Unix pathnames are supported experimentally.

It does not represent the file itself. A Pathname can be relative or absolute. It‘s not until you try to reference the file that it even matters whether the file exists or not.

Pathname is immutable. It has no method for destructive update.

The value of this class is to manipulate file path information in a neater way than standard Ruby provides. The examples below demonstrate the difference. All functionality from File, FileTest, and some from Dir and FileUtils is included, in an unsurprising way. It is essentially a facade for all of these, and more.

Examples

Example 1: Using Pathname

  require 'pathname'
  p = Pathname.new("/usr/bin/ruby")
  size = p.size              # 27662
  isdir = p.directory?       # false
  dir  = p.dirname           # Pathname:/usr/bin
  base = p.basename          # Pathname:ruby
  dir, base = p.split        # [Pathname:/usr/bin, Pathname:ruby]
  data = p.read
  p.open { |f| _ }
  p.each_line { |line| _ }

Example 2: Using standard Ruby

  p = "/usr/bin/ruby"
  size = File.size(p)        # 27662
  isdir = File.directory?(p) # false
  dir  = File.dirname(p)     # "/usr/bin"
  base = File.basename(p)    # "ruby"
  dir, base = File.split(p)  # ["/usr/bin", "ruby"]
  data = File.read(p)
  File.open(p) { |f| _ }
  File.foreach(p) { |line| _ }

Example 3: Special features

  p1 = Pathname.new("/usr/lib")   # Pathname:/usr/lib
  p2 = p1 + "ruby/1.8"            # Pathname:/usr/lib/ruby/1.8
  p3 = p1.parent                  # Pathname:/usr
  p4 = p2.relative_path_from(p3)  # Pathname:lib/ruby/1.8
  pwd = Pathname.pwd              # Pathname:/home/gavin
  pwd.absolute?                   # true
  p5 = Pathname.new "."           # Pathname:.
  p5 = p5 + "music/../articles"   # Pathname:music/../articles
  p5.cleanpath                    # Pathname:articles
  p5.realpath                     # Pathname:/home/gavin/articles
  p5.children                     # [Pathname:/home/gavin/articles/linux, ...]

Breakdown of functionality

Core methods

These methods are effectively manipulating a String, because that‘s all a path is. Except for mountpoint?, children, and realpath, they don‘t access the filesystem.

File status predicate methods

These methods are a facade for FileTest:

  • blockdev?
  • chardev?
  • directory?
  • executable?
  • executable_real?
  • exist?
  • file?
  • grpowned?
  • owned?
  • pipe?
  • readable?
  • world_readable?
  • readable_real?
  • setgid?
  • setuid?
  • size
  • size?
  • socket?
  • sticky?
  • symlink?
  • writable?
  • world_writable?
  • writable_real?
  • zero?

File property and manipulation methods

These methods are a facade for File:

Directory methods

These methods are a facade for Dir:

IO

These methods are a facade for IO:

  • each_line(*args, &block)
  • read(*args)
  • readlines(*args)
  • sysopen(*args)

Utilities

These methods are a mixture of Find, FileUtils, and others:

Method documentation

As the above section shows, most of the methods in Pathname are facades. The documentation for these methods generally just says, for instance, "See FileTest.writable?", as you should be familiar with the original method anyway, and its documentation (e.g. through ri) will contain more information. In some cases, a brief description will follow.

Methods

Constants

SEPARATOR_PAT = /[#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}]/
SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/

External Aliases

getwd -> pwd

Public Class methods

See Dir.getwd. Returns the current working directory as a Pathname.

[Source]

     # File lib/pathname.rb, line 962
962:   def Pathname.getwd() self.new(Dir.getwd) end

See Dir.glob. Returns or yields Pathname objects.

[Source]

     # File lib/pathname.rb, line 953
953:   def Pathname.glob(*args) # :yield: p
954:     if block_given?
955:       Dir.glob(*args) {|f| yield self.new(f) }
956:     else
957:       Dir.glob(*args).map {|f| self.new(f) }
958:     end
959:   end

Create a Pathname object from the given String (or String-like object). If path contains a NUL character (\0), an ArgumentError is raised.

[Source]

     # File lib/pathname.rb, line 210
210:   def initialize(path)
211:     path = path.__send__(TO_PATH) if path.respond_to? TO_PATH
212:     @path = path.dup
213: 
214:     if /\0/ =~ @path
215:       raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
216:     end
217: 
218:     self.taint if @path.tainted?
219:   end

Public Instance methods

Pathname#+ appends a pathname fragment to this one to produce a new Pathname object.

  p1 = Pathname.new("/usr")      # Pathname:/usr
  p2 = p1 + "bin/ruby"           # Pathname:/usr/bin/ruby
  p3 = p1 + "/etc/passwd"        # Pathname:/etc/passwd

This method doesn‘t access the file system; it is pure string manipulation.

[Source]

     # File lib/pathname.rb, line 602
602:   def +(other)
603:     other = Pathname.new(other) unless Pathname === other
604:     Pathname.new(plus(@path, other.to_s))
605:   end

Provides for comparing pathnames, case-sensitively.

[Source]

     # File lib/pathname.rb, line 238
238:   def <=>(other)
239:     return nil unless Pathname === other
240:     @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
241:   end

Compare this pathname with other. The comparison is string-based. Be aware that two different paths (foo.txt and ./foo.txt) can refer to the same file.

[Source]

     # File lib/pathname.rb, line 230
230:   def ==(other)
231:     return false unless Pathname === other
232:     other.to_s == @path
233:   end
===(other)

Alias for #==

TO_PATH()

Alias for to_s

Predicate method for testing whether a path is absolute. It returns true if the pathname begins with a slash.

[Source]

     # File lib/pathname.rb, line 510
510:   def absolute?
511:     !relative?
512:   end

Iterates over and yields a new Pathname object for each element in the given path in ascending order.

 Pathname.new('/path/to/some/file.rb').ascend {|v| p v}
    #<Pathname:/path/to/some/file.rb>
    #<Pathname:/path/to/some>
    #<Pathname:/path/to>
    #<Pathname:/path>
    #<Pathname:/>

 Pathname.new('path/to/some/file.rb').ascend {|v| p v}
    #<Pathname:path/to/some/file.rb>
    #<Pathname:path/to/some>
    #<Pathname:path/to>
    #<Pathname:path>

It doesn‘t access actual filesystem.

This method is available since 1.8.5.

[Source]

     # File lib/pathname.rb, line 582
582:   def ascend
583:     path = @path
584:     yield self
585:     while r = chop_basename(path)
586:       path, name = r
587:       break if path.empty?
588:       yield self.class.new(del_trailing_separator(path))
589:     end
590:   end

See File.atime. Returns last access time.

[Source]

     # File lib/pathname.rb, line 783
783:   def atime() File.atime(@path) end

See File.basename. Returns the last component of the path.

[Source]

     # File lib/pathname.rb, line 844
844:   def basename(*args) self.class.new(File.basename(@path, *args)) end

See FileTest.blockdev?.

[Source]

     # File lib/pathname.rb, line 878
878:   def blockdev?() FileTest.blockdev?(@path) end

See FileTest.chardev?.

[Source]

     # File lib/pathname.rb, line 881
881:   def chardev?() FileTest.chardev?(@path) end

Pathname#chdir is obsoleted at 1.8.1.

[Source]

     # File lib/pathname.rb, line 966
966:   def chdir(&block)
967:     warn "Pathname#chdir is obsoleted.  Use Dir.chdir."
968:     Dir.chdir(@path, &block)
969:   end

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.

For example:

  p = Pathname("/usr/lib/ruby/1.8")
  p.children
      # -> [ Pathname:/usr/lib/ruby/1.8/English.rb,
             Pathname:/usr/lib/ruby/1.8/Env.rb,
             Pathname:/usr/lib/ruby/1.8/abbrev.rb, ... ]
  p.children(false)
      # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]

Note that the result never contain the entries . and .. in the directory because they are not children.

This method has existed since 1.8.1.

[Source]

     # File lib/pathname.rb, line 689
689:   def children(with_directory=true)
690:     with_directory = false if @path == '.'
691:     result = []
692:     Dir.foreach(@path) {|e|
693:       next if e == '.' || e == '..'
694:       if with_directory
695:         result << self.class.new(File.join(@path, e))
696:       else
697:         result << self.class.new(e)
698:       end
699:     }
700:     result
701:   end

See File.chmod. Changes permissions.

[Source]

     # File lib/pathname.rb, line 792
792:   def chmod(mode) File.chmod(mode, @path) end

See File.chown. Change owner and group of file.

[Source]

     # File lib/pathname.rb, line 798
798:   def chown(owner, group) File.chown(owner, group, @path) end

Pathname#chroot is obsoleted at 1.8.1.

[Source]

     # File lib/pathname.rb, line 972
972:   def chroot
973:     warn "Pathname#chroot is obsoleted.  Use Dir.chroot."
974:     Dir.chroot(@path)
975:   end

Returns clean pathname of self with consecutive slashes and useless dots 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 .. entries than absolutely necessary, but without accessing the filesystem, this can‘t be avoided. See realpath.

[Source]

     # File lib/pathname.rb, line 327
327:   def cleanpath(consider_symlink=false)
328:     if consider_symlink
329:       cleanpath_conservative
330:     else
331:       cleanpath_aggressive
332:     end
333:   end

See File.ctime. Returns last (directory entry, not file) change time.

[Source]

     # File lib/pathname.rb, line 786
786:   def ctime() File.ctime(@path) end
delete()

Alias for unlink

Iterates over and yields a new Pathname object for each element in the given path in descending order.

 Pathname.new('/path/to/some/file.rb').descend {|v| p v}
    #<Pathname:/>
    #<Pathname:/path>
    #<Pathname:/path/to>
    #<Pathname:/path/to/some>
    #<Pathname:/path/to/some/file.rb>

 Pathname.new('path/to/some/file.rb').descend {|v| p v}
    #<Pathname:path>
    #<Pathname:path/to>
    #<Pathname:path/to/some>
    #<Pathname:path/to/some/file.rb>

It doesn‘t access actual filesystem.

This method is available since 1.8.5.

[Source]

     # File lib/pathname.rb, line 555
555:   def descend
556:     vs = []
557:     ascend {|v| vs << v }
558:     vs.reverse_each {|v| yield v }
559:     nil
560:   end

Pathname#dir_foreach is obsoleted at 1.8.1.

[Source]

     # File lib/pathname.rb, line 990
990:   def dir_foreach(*args, &block)
991:     warn "Pathname#dir_foreach is obsoleted.  Use Pathname#each_entry."
992:     each_entry(*args, &block)
993:   end

See FileTest.directory?.

[Source]

     # File lib/pathname.rb, line 896
896:   def directory?() FileTest.directory?(@path) end

See File.dirname. Returns all but the last component of the path.

[Source]

     # File lib/pathname.rb, line 847
847:   def dirname() self.class.new(File.dirname(@path)) end

Iterates over the entries (files and subdirectories) in the directory. It yields a Pathname object for each entry.

This method has existed since 1.8.1.

[Source]

     # File lib/pathname.rb, line 985
985:   def each_entry(&block) # :yield: p
986:     Dir.foreach(@path) {|f| yield self.class.new(f) }
987:   end

Iterates over each component of the path.

  Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
    # yields "usr", "bin", and "ruby".

[Source]

     # File lib/pathname.rb, line 529
529:   def each_filename # :yield: filename
530:     prefix, names = split_names(@path)
531:     names.each {|filename| yield filename }
532:     nil
533:   end

each_line iterates over the line in the file. It yields a String object for each line.

This method has existed since 1.8.1.

[Source]

     # File lib/pathname.rb, line 758
758:   def each_line(*args, &block) # :yield: line
759:     IO.foreach(@path, *args, &block)
760:   end

Return the entries (files and subdirectories) in the directory, each as a Pathname object.

[Source]

     # File lib/pathname.rb, line 979
979:   def entries() Dir.entries(@path).map {|f| self.class.new(f) } end
eql?(other)

Alias for #==

See FileTest.executable?.

[Source]

     # File lib/pathname.rb, line 884
884:   def executable?() FileTest.executable?(@path) end

See FileTest.executable_real?.

[Source]

     # File lib/pathname.rb, line 887
887:   def executable_real?() FileTest.executable_real?(@path) end

See FileTest.exist?.

[Source]

     # File lib/pathname.rb, line 890
890:   def exist?() FileTest.exist?(@path) end

See File.expand_path.

[Source]

     # File lib/pathname.rb, line 853
853:   def expand_path(*args) self.class.new(File.expand_path(@path, *args)) end

See File.extname. Returns the file‘s extension.

[Source]

     # File lib/pathname.rb, line 850
850:   def extname() File.extname(@path) end

See FileTest.file?.

[Source]

     # File lib/pathname.rb, line 899
899:   def file?() FileTest.file?(@path) end

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.

Since it is implemented by find.rb, Find.prune can be used to control the traverse.

If self is ., yielded pathnames begin with a filename in the current directory, not ./.

[Source]

      # File lib/pathname.rb, line 1019
1019:   def find(&block) # :yield: p
1020:     require 'find'
1021:     if @path == '.'
1022:       Find.find(@path) {|f| yield self.class.new(f.sub(%r{\A\./}, '')) }
1023:     else
1024:       Find.find(@path) {|f| yield self.class.new(f) }
1025:     end
1026:   end

See File.fnmatch. Return true if the receiver matches the given pattern.

[Source]

     # File lib/pathname.rb, line 805
805:   def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end

See File.fnmatch? (same as fnmatch).

[Source]

     # File lib/pathname.rb, line 808
808:   def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end

This method is obsoleted at 1.8.1. Use each_line or each_entry.

[Source]

      # File lib/pathname.rb, line 1063
1063:   def foreach(*args, &block)
1064:     warn "Pathname#foreach is obsoleted.  Use each_line or each_entry."
1065:     if FileTest.directory? @path
1066:       # For polymorphism between Dir.foreach and IO.foreach,
1067:       # Pathname#foreach doesn't yield Pathname object.
1068:       Dir.foreach(@path, *args, &block)
1069:     else
1070:       IO.foreach(@path, *args, &block)
1071:     end
1072:   end

Pathname#foreachline is obsoleted at 1.8.1. Use each_line.

[Source]

     # File lib/pathname.rb, line 763
763:   def foreachline(*args, &block)
764:     warn "Pathname#foreachline is obsoleted.  Use Pathname#each_line."
765:     each_line(*args, &block)
766:   end

[Source]

     # File lib/pathname.rb, line 221
221:   def freeze() super; @path.freeze; self end

See File.ftype. Returns "type" of file ("file", "directory", etc).

[Source]

     # File lib/pathname.rb, line 812
812:   def ftype() File.ftype(@path) end

See FileTest.grpowned?.

[Source]

     # File lib/pathname.rb, line 893
893:   def grpowned?() FileTest.grpowned?(@path) end

Pathname#join joins pathnames.

path0.join(path1, …, pathN) is the same as path0 + path1 + … + pathN.

[Source]

     # File lib/pathname.rb, line 655
655:   def join(*args)
656:     args.unshift self
657:     result = args.pop
658:     result = Pathname.new(result) unless Pathname === result
659:     return result if result.absolute?
660:     args.reverse_each {|arg|
661:       arg = Pathname.new(arg) unless Pathname === arg
662:       result = arg + result
663:       return result if result.absolute?
664:     }
665:     result
666:   end

See File.lchmod.

[Source]

     # File lib/pathname.rb, line 795
795:   def lchmod(mode) File.lchmod(mode, @path) end

See File.lchown.

[Source]

     # File lib/pathname.rb, line 801
801:   def lchown(owner, group) File.lchown(owner, group, @path) end

Pathname#link is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

[Source]

     # File lib/pathname.rb, line 861
861:   def link(old)
862:     warn 'Pathname#link is obsoleted.  Use Pathname#make_link.'
863:     File.link(old, @path)
864:   end

See File.lstat.

[Source]

     # File lib/pathname.rb, line 832
832:   def lstat() File.lstat(@path) end

See File.link. Creates a hard link.

[Source]

     # File lib/pathname.rb, line 815
815:   def make_link(old) File.link(old, @path) end

See File.symlink. Creates a symbolic link.

[Source]

     # File lib/pathname.rb, line 835
835:   def make_symlink(old) File.symlink(old, @path) end

See Dir.mkdir. Create the referenced directory.

[Source]

     # File lib/pathname.rb, line 996
996:   def mkdir(*args) Dir.mkdir(@path, *args) end

See FileUtils.mkpath. Creates a full path, including any intermediate directories that don‘t yet exist.

[Source]

      # File lib/pathname.rb, line 1033
1033:   def mkpath
1034:     require 'fileutils'
1035:     FileUtils.mkpath(@path)
1036:     nil
1037:   end

mountpoint? returns true if self points to a mountpoint.

[Source]

     # File lib/pathname.rb, line 486
486:   def mountpoint?
487:     begin
488:       stat1 = self.lstat
489:       stat2 = self.parent.lstat
490:       stat1.dev == stat2.dev && stat1.ino == stat2.ino ||
491:         stat1.dev != stat2.dev
492:     rescue Errno::ENOENT
493:       false
494:     end
495:   end

See File.mtime. Returns last modification time.

[Source]

     # File lib/pathname.rb, line 789
789:   def mtime() File.mtime(@path) end

See File.open. Opens the file for reading or writing.

[Source]

     # File lib/pathname.rb, line 818
818:   def open(*args, &block) # :yield: file
819:     File.open(@path, *args, &block)
820:   end

See Dir.open.

[Source]

      # File lib/pathname.rb, line 1002
1002:   def opendir(&block) # :yield: dir
1003:     Dir.open(@path, &block)
1004:   end

See FileTest.owned?.

[Source]

     # File lib/pathname.rb, line 908
908:   def owned?() FileTest.owned?(@path) end

parent returns the parent directory.

This is same as self + ’..’.

[Source]

     # File lib/pathname.rb, line 481
481:   def parent
482:     self + '..'
483:   end

See FileTest.pipe?.

[Source]

     # File lib/pathname.rb, line 902
902:   def pipe?() FileTest.pipe?(@path) end

See IO.read. Returns all the bytes from the file, or the first N if specified.

[Source]

     # File lib/pathname.rb, line 770
770:   def read(*args) IO.read(@path, *args) end

See FileTest.readable?.

[Source]

     # File lib/pathname.rb, line 911
911:   def readable?() FileTest.readable?(@path) end

See FileTest.readable_real?.

[Source]

     # File lib/pathname.rb, line 917
917:   def readable_real?() FileTest.readable_real?(@path) end

See IO.readlines. Returns all the lines from the file.

[Source]

     # File lib/pathname.rb, line 773
773:   def readlines(*args) IO.readlines(@path, *args) end

See File.readlink. Read symbolic link.

[Source]

     # File lib/pathname.rb, line 823
823:   def readlink() self.class.new(File.readlink(@path)) end

Returns a real (absolute) pathname of self in the actual filesystem. The real pathname doesn‘t contain symlinks or useless dots.

No arguments should be given; the old behaviour is obsoleted.

[Source]

     # File lib/pathname.rb, line 467
467:   def realpath
468:     path = @path
469:     prefix, names = split_names(path)
470:     if prefix == ''
471:       prefix, names2 = split_names(Dir.pwd)
472:       names = names2 + names
473:     end
474:     prefix, *names = realpath_rec(prefix, names, {})
475:     self.class.new(prepend_prefix(prefix, File.join(*names)))
476:   end

The opposite of absolute?

[Source]

     # File lib/pathname.rb, line 515
515:   def relative?
516:     path = @path
517:     while r = chop_basename(path)
518:       path, basename = r
519:     end
520:     path == ''
521:   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.

relative_path_from doesn‘t access the filesystem. It assumes no symlinks.

ArgumentError is raised when it cannot find a relative path.

This method has existed since 1.8.1.

[Source]

     # File lib/pathname.rb, line 714
714:   def relative_path_from(base_directory)
715:     dest_directory = self.cleanpath.to_s
716:     base_directory = base_directory.cleanpath.to_s
717:     dest_prefix = dest_directory
718:     dest_names = []
719:     while r = chop_basename(dest_prefix)
720:       dest_prefix, basename = r
721:       dest_names.unshift basename if basename != '.'
722:     end
723:     base_prefix = base_directory
724:     base_names = []
725:     while r = chop_basename(base_prefix)
726:       base_prefix, basename = r
727:       base_names.unshift basename if basename != '.'
728:     end
729:     unless SAME_PATHS[dest_prefix, base_prefix]
730:       raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}"
731:     end
732:     while !dest_names.empty? &&
733:           !base_names.empty? &&
734:           SAME_PATHS[dest_names.first, base_names.first]
735:       dest_names.shift
736:       base_names.shift
737:     end
738:     if base_names.include? '..'
739:       raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
740:     end
741:     base_names.fill('..')
742:     relpath_names = base_names + dest_names
743:     if relpath_names.empty?
744:       Pathname.new('.')
745:     else
746:       Pathname.new(File.join(*relpath_names))
747:     end
748:   end

See File.rename. Rename the file.

[Source]

     # File lib/pathname.rb, line 826
826:   def rename(to) File.rename(@path, to) end

See Dir.rmdir. Remove the referenced directory.

[Source]

     # File lib/pathname.rb, line 999
999:   def rmdir() Dir.rmdir(@path) end

See FileUtils.rm_r. Deletes a directory and all beneath it.

[Source]

      # File lib/pathname.rb, line 1040
1040:   def rmtree
1041:     # The name "rmtree" is borrowed from File::Path of Perl.
1042:     # File::Path provides "mkpath" and "rmtree".
1043:     require 'fileutils'
1044:     FileUtils.rm_r(@path)
1045:     nil
1046:   end

root? is a predicate for root directories. I.e. it returns true if the pathname consists of consecutive slashes.

It doesn‘t access actual filesystem. So it may return false for some pathnames which points to roots such as /usr/...

[Source]

     # File lib/pathname.rb, line 504
504:   def root?
505:     !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o =~ @path)
506:   end

See FileTest.setgid?.

[Source]

     # File lib/pathname.rb, line 923
923:   def setgid?() FileTest.setgid?(@path) end

See FileTest.setuid?.

[Source]

     # File lib/pathname.rb, line 920
920:   def setuid?() FileTest.setuid?(@path) end

See FileTest.size.

[Source]

     # File lib/pathname.rb, line 926
926:   def size() FileTest.size(@path) end

See FileTest.size?.

[Source]

     # File lib/pathname.rb, line 929
929:   def size?() FileTest.size?(@path) end

See FileTest.socket?.

[Source]

     # File lib/pathname.rb, line 905
905:   def socket?() FileTest.socket?(@path) end

See File.split. Returns the dirname and the basename in an Array.

[Source]

     # File lib/pathname.rb, line 857
857:   def split() File.split(@path).map {|f| self.class.new(f) } end

See File.stat. Returns a File::Stat object.

[Source]

     # File lib/pathname.rb, line 829
829:   def stat() File.stat(@path) end

See FileTest.sticky?.

[Source]

     # File lib/pathname.rb, line 932
932:   def sticky?() FileTest.sticky?(@path) end

Return a pathname which is substituted by String#sub.

[Source]

     # File lib/pathname.rb, line 260
260:   def sub(pattern, *rest, &block)
261:     if block
262:       path = @path.sub(pattern, *rest) {|*args|
263:         begin
264:           old = Thread.current[:pathname_sub_matchdata]
265:           Thread.current[:pathname_sub_matchdata] = $~
266:           eval("$~ = Thread.current[:pathname_sub_matchdata]", block.binding)
267:         ensure
268:           Thread.current[:pathname_sub_matchdata] = old
269:         end
270:         yield(*args)
271:       }
272:     else
273:       path = @path.sub(pattern, *rest)
274:     end
275:     self.class.new(path)
276:   end

Pathname#symlink is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

[Source]

     # File lib/pathname.rb, line 868
868:   def symlink(old)
869:     warn 'Pathname#symlink is obsoleted.  Use Pathname#make_symlink.'
870:     File.symlink(old, @path)
871:   end

See FileTest.symlink?.

[Source]

     # File lib/pathname.rb, line 935
935:   def symlink?() FileTest.symlink?(@path) end

See IO.sysopen.

[Source]

     # File lib/pathname.rb, line 776
776:   def sysopen(*args) IO.sysopen(@path, *args) end

[Source]

     # File lib/pathname.rb, line 222
222:   def taint() super; @path.taint; self end

Return the path as a String.

[Source]

     # File lib/pathname.rb, line 248
248:   def to_s
249:     @path.dup
250:   end

See File.truncate. Truncate the file to length bytes.

[Source]

     # File lib/pathname.rb, line 838
838:   def truncate(length) File.truncate(@path, length) end

Removes a file or directory, using File.unlink or Dir.unlink as necessary.

[Source]

      # File lib/pathname.rb, line 1053
1053:   def unlink()
1054:     begin
1055:       Dir.unlink @path
1056:     rescue Errno::ENOTDIR
1057:       File.unlink @path
1058:     end
1059:   end

[Source]

     # File lib/pathname.rb, line 223
223:   def untaint() super; @path.untaint; self end

See File.utime. Update the access and modification times.

[Source]

     # File lib/pathname.rb, line 841
841:   def utime(atime, mtime) File.utime(atime, mtime, @path) end

See FileTest.world_readable?.

[Source]

     # File lib/pathname.rb, line 914
914:   def world_readable?() FileTest.world_readable?(@path) end

See FileTest.world_writable?.

[Source]

     # File lib/pathname.rb, line 941
941:   def world_writable?() FileTest.world_writable?(@path) end

See FileTest.writable?.

[Source]

     # File lib/pathname.rb, line 938
938:   def writable?() FileTest.writable?(@path) end

See FileTest.writable_real?.

[Source]

     # File lib/pathname.rb, line 944
944:   def writable_real?() FileTest.writable_real?(@path) end

See FileTest.zero?.

[Source]

     # File lib/pathname.rb, line 947
947:   def zero?() FileTest.zero?(@path) end

Private Instance methods

add_trailing_separator(path) -> path

[Source]

     # File lib/pathname.rb, line 376
376:   def add_trailing_separator(path)
377:     if File.basename(path + 'a') == 'a'
378:       path
379:     else
380:       File.join(path, "") # xxx: Is File.join is appropriate to add separator?
381:     end
382:   end

chop_basename(path) -> [pre-basename, basename] or nil

[Source]

     # File lib/pathname.rb, line 285
285:   def chop_basename(path)
286:     base = File.basename(path)
287:     if /\A#{SEPARATOR_PAT}?\z/ =~ base
288:       return nil
289:     else
290:       return path[0, path.rindex(base)], base
291:     end
292:   end

Clean the path simply by resolving and removing excess "." and ".." entries. Nothing more, nothing less.

[Source]

     # File lib/pathname.rb, line 339
339:   def cleanpath_aggressive
340:     path = @path
341:     names = []
342:     pre = path
343:     while r = chop_basename(pre)
344:       pre, base = r
345:       case base
346:       when '.'
347:       when '..'
348:         names.unshift base
349:       else
350:         if names[0] == '..'
351:           names.shift
352:         else
353:           names.unshift base
354:         end
355:       end
356:     end
357:     if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
358:       names.shift while names[0] == '..'
359:     end
360:     self.class.new(prepend_prefix(pre, File.join(*names)))
361:   end

[Source]

     # File lib/pathname.rb, line 397
397:   def cleanpath_conservative
398:     path = @path
399:     names = []
400:     pre = path
401:     while r = chop_basename(pre)
402:       pre, base = r
403:       names.unshift base if base != '.'
404:     end
405:     if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
406:       names.shift while names[0] == '..'
407:     end
408:     if names.empty?
409:       self.class.new(File.dirname(pre))
410:     else
411:       if names.last != '..' && File.basename(path) == '.'
412:         names << '.'
413:       end
414:       result = prepend_prefix(pre, File.join(*names))
415:       if /\A(?:\.|\.\.)\z/ !~ names.last && has_trailing_separator?(path)
416:         self.class.new(add_trailing_separator(result))
417:       else
418:         self.class.new(result)
419:       end
420:     end
421:   end

[Source]

     # File lib/pathname.rb, line 385
385:   def del_trailing_separator(path)
386:     if r = chop_basename(path)
387:       pre, basename = r
388:       pre + basename
389:     elsif /#{SEPARATOR_PAT}+\z/o =~ path
390:       $` + File.dirname(path)[/#{SEPARATOR_PAT}*\z/o]
391:     else
392:       path
393:     end
394:   end

has_trailing_separator?(path) -> bool

[Source]

     # File lib/pathname.rb, line 365
365:   def has_trailing_separator?(path)
366:     if r = chop_basename(path)
367:       pre, basename = r
368:       pre.length + basename.length < path.length
369:     else
370:       false
371:     end
372:   end

[Source]

     # File lib/pathname.rb, line 607
607:   def plus(path1, path2) # -> path
608:     prefix2 = path2
609:     index_list2 = []
610:     basename_list2 = []
611:     while r2 = chop_basename(prefix2)
612:       prefix2, basename2 = r2
613:       index_list2.unshift prefix2.length
614:       basename_list2.unshift basename2
615:     end
616:     return path2 if prefix2 != ''
617:     prefix1 = path1
618:     while true
619:       while !basename_list2.empty? && basename_list2.first == '.'
620:         index_list2.shift
621:         basename_list2.shift
622:       end
623:       break unless r1 = chop_basename(prefix1)
624:       prefix1, basename1 = r1
625:       next if basename1 == '.'
626:       if basename1 == '..' || basename_list2.empty? || basename_list2.first != '..'
627:         prefix1 = prefix1 + basename1
628:         break
629:       end
630:       index_list2.shift
631:       basename_list2.shift
632:     end
633:     r1 = chop_basename(prefix1)
634:     if !r1 && /#{SEPARATOR_PAT}/o =~ File.basename(prefix1)
635:       while !basename_list2.empty? && basename_list2.first == '..'
636:         index_list2.shift
637:         basename_list2.shift
638:       end
639:     end
640:     if !basename_list2.empty?
641:       suffix2 = path2[index_list2.first..-1]
642:       r1 ? File.join(prefix1, suffix2) : prefix1 + suffix2
643:     else
644:       r1 ? prefix1 : File.dirname(prefix1)
645:     end
646:   end

[Source]

     # File lib/pathname.rb, line 306
306:   def prepend_prefix(prefix, relpath)
307:     if relpath.empty?
308:       File.dirname(prefix)
309:     elsif /#{SEPARATOR_PAT}/ =~ prefix
310:       prefix = File.dirname(prefix)
311:       prefix = File.join(prefix, "") if File.basename(prefix + 'a') != 'a'
312:       prefix + relpath
313:     else
314:       prefix + relpath
315:     end
316:   end

[Source]

     # File lib/pathname.rb, line 424
424:   def realpath_rec(prefix, unresolved, h)
425:     resolved = []
426:     until unresolved.empty?
427:       n = unresolved.shift
428:       if n == '.'
429:         next
430:       elsif n == '..'
431:         resolved.pop
432:       else
433:         path = prepend_prefix(prefix, File.join(*(resolved + [n])))
434:         if h.include? path
435:           if h[path] == :resolving
436:             raise Errno::ELOOP.new(path)
437:           else
438:             prefix, *resolved = h[path]
439:           end
440:         else
441:           s = File.lstat(path)
442:           if s.symlink?
443:             h[path] = :resolving
444:             link_prefix, link_names = split_names(File.readlink(path))
445:             if link_prefix == ''
446:               prefix, *resolved = h[path] = realpath_rec(prefix, resolved + link_names, h)
447:             else
448:               prefix, *resolved = h[path] = realpath_rec(link_prefix, link_names, h)
449:             end
450:           else
451:             resolved << n
452:             h[path] = [prefix, *resolved]
453:           end
454:         end
455:       end
456:     end
457:     return prefix, *resolved
458:   end

split_names(path) -> prefix, [name, …]

[Source]

     # File lib/pathname.rb, line 296
296:   def split_names(path)
297:     names = []
298:     while r = chop_basename(path)
299:       path, basename = r
300:       names.unshift basename
301:     end
302:     return path, names
303:   end

[Validate]