Class: Pathname

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

# File pathname.rb, line 769
  def Pathname.getwd() Pathname.new(Dir.getwd) end

glob(*args) {|p| ...}

See Dir.glob. Returns or yields Pathname objects.

[Source]

# File pathname.rb, line 760
  def Pathname.glob(*args) # :yield: p

    if block_given?
      Dir.glob(*args) {|f| yield Pathname.new(f) }
    else
      Dir.glob(*args).map {|f| Pathname.new(f) }
    end
  end

new(path)

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 pathname.rb, line 187
  def initialize(path)
    path = path.to_str if path.respond_to? :to_str
    @path = path.dup

    if /\0/ =~ @path
      raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
    end

    self.taint if @path.tainted?
  end

+(other)

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 pathname.rb, line 431
  def +(other)
    other = Pathname.new(other) unless Pathname === other

    return other if other.absolute?

    path1 = @path
    path2 = other.to_s
    while m2 = %r{\A\.\.(?:/+|\z)}.match(path2) and
          m1 = %r{(\A|/+)([^/]+)\z}.match(path1) and
          %r{\A(?:\.|\.\.)\z} !~ m1[2]
      path1 = m1[1].empty? ? '.' : '/' if (path1 = m1.pre_match).empty?
      path2 = '.' if (path2 = m2.post_match).empty?
    end
    if %r{\A/+\z} =~ path1
      while m2 = %r{\A\.\.(?:/+|\z)}.match(path2)
        path2 = '.' if (path2 = m2.post_match).empty?
      end
    end

    return Pathname.new(path2) if path1 == '.'
    return Pathname.new(path1) if path2 == '.'

    if %r{/\z} =~ path1
      Pathname.new(path1 + path2)
    else
      Pathname.new(path1 + '/' + path2)
    end
  end

<=>(other)

Provides for comparing pathnames, case-sensitively.

[Source]

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

==(other)

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 pathname.rb, line 207
  def ==(other)
    return false unless Pathname === other
    other.to_s == @path
  end

===(other)

Alias for #==

absolute?()

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

[Source]

# File pathname.rb, line 402
  def absolute?
    %r{\A/} =~ @path ? true : false
  end

atime()

See File.atime. Returns last access time.

[Source]

# File pathname.rb, line 596
  def atime() File.atime(@path) end

basename(*args)

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

[Source]

# File pathname.rb, line 657
  def basename(*args) Pathname.new(File.basename(@path, *args)) end

blockdev?()

See FileTest.blockdev?.

[Source]

# File pathname.rb, line 691
  def blockdev?() FileTest.blockdev?(@path) end

chardev?()

See FileTest.chardev?.

[Source]

# File pathname.rb, line 694
  def chardev?() FileTest.chardev?(@path) end

chdir(&block)

Pathname#chdir is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 773
  def chdir(&block)
    warn "Pathname#chdir is obsoleted.  Use Dir.chdir."
    Dir.chdir(@path, &block)
  end

children(with_directory=true)

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 pathname.rb, line 500
  def children(with_directory=true)
    with_directory = false if @path == '.'
    result = []
    Dir.foreach(@path) {|e|
      next if e == '.' || e == '..'
      if with_directory
        result << Pathname.new(File.join(@path, e))
      else
        result << Pathname.new(e)
      end
    }
    result
  end

chmod(mode)

See File.chmod. Changes permissions.

[Source]

# File pathname.rb, line 605
  def chmod(mode) File.chmod(mode, @path) end

chown(owner, group)

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

[Source]

# File pathname.rb, line 611
  def chown(owner, group) File.chown(owner, group, @path) end

chroot()

Pathname#chroot is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 779
  def chroot
    warn "Pathname#chroot is obsoleted.  Use Dir.chroot."
    Dir.chroot(@path)
  end

cleanpath(consider_symlink=false)

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 pathname.rb, line 245
  def cleanpath(consider_symlink=false)
    if consider_symlink
      cleanpath_conservative
    else
      cleanpath_aggressive
    end
  end

ctime()

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

[Source]

# File pathname.rb, line 599
  def ctime() File.ctime(@path) end

delete()

Alias for unlink

dir_foreach(*args, &block)

Pathname#dir_foreach is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 797
  def dir_foreach(*args, &block)
    warn "Pathname#dir_foreach is obsoleted.  Use Pathname#each_entry."
    each_entry(*args, &block)
  end

directory?()

See FileTest.directory?.

[Source]

# File pathname.rb, line 709
  def directory?() FileTest.directory?(@path) end

dirname()

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

[Source]

# File pathname.rb, line 660
  def dirname() Pathname.new(File.dirname(@path)) end

each_entry() {|p| ...}

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 pathname.rb, line 792
  def each_entry(&block) # :yield: p

    Dir.foreach(@path) {|f| yield Pathname.new(f) }
  end

each_filename( {|s| ...}

Iterates over each component of the path.

  Pathname.new("/usr/bin/ruby").each_filename
    # yields "usr", "bin", and "ruby".

[Source]

# File pathname.rb, line 417
  def each_filename # :yield: s

    @path.scan(%r{[^/]+}) { yield $& }
  end

each_line(*args) {|line| ...}

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 pathname.rb, line 571
  def each_line(*args, &block) # :yield: line

    IO.foreach(@path, *args, &block)
  end

entries()

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

[Source]

# File pathname.rb, line 786
  def entries() Dir.entries(@path).map {|f| Pathname.new(f) } end

eql?(other)

Alias for #==

executable?()

See FileTest.executable?.

[Source]

# File pathname.rb, line 697
  def executable?() FileTest.executable?(@path) end

executable_real?()

See FileTest.executable_real?.

[Source]

# File pathname.rb, line 700
  def executable_real?() FileTest.executable_real?(@path) end

exist?()

See FileTest.exist?.

[Source]

# File pathname.rb, line 703
  def exist?() FileTest.exist?(@path) end

expand_path(*args)

See File.expand_path.

[Source]

# File pathname.rb, line 666
  def expand_path(*args) Pathname.new(File.expand_path(@path, *args)) end

extname()

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

[Source]

# File pathname.rb, line 663
  def extname() File.extname(@path) end

file?()

See FileTest.file?.

[Source]

# File pathname.rb, line 712
  def file?() FileTest.file?(@path) end

find() {|p| ...}

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 pathname.rb, line 826
  def find(&block) # :yield: p

    require 'find'
    if @path == '.'
      Find.find(@path) {|f| yield Pathname.new(f.sub(%r{\A\./}, '')) }
    else
      Find.find(@path) {|f| yield Pathname.new(f) }
    end
  end

fnmatch(pattern, *args)

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

[Source]

# File pathname.rb, line 618
  def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end

fnmatch?(pattern, *args)

See File.fnmatch? (same as fnmatch).

[Source]

# File pathname.rb, line 621
  def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end

foreach(*args, &block)

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

[Source]

# File pathname.rb, line 870
  def foreach(*args, &block)
    warn "Pathname#foreach is obsoleted.  Use each_line or each_entry."
    if FileTest.directory? @path
      # For polymorphism between Dir.foreach and IO.foreach,

      # Pathname#foreach doesn't yield Pathname object.

      Dir.foreach(@path, *args, &block)
    else
      IO.foreach(@path, *args, &block)
    end
  end

foreachline(*args, &block)

Pathname#foreachline is obsoleted at 1.8.1. Use each_line.

[Source]

# File pathname.rb, line 576
  def foreachline(*args, &block)
    warn "Pathname#foreachline is obsoleted.  Use Pathname#each_line."
    each_line(*args, &block)
  end

freeze()

[Source]

# File pathname.rb, line 198
  def freeze() super; @path.freeze; self end

ftype()

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

[Source]

# File pathname.rb, line 625
  def ftype() File.ftype(@path) end

grpowned?()

See FileTest.grpowned?.

[Source]

# File pathname.rb, line 706
  def grpowned?() FileTest.grpowned?(@path) end

join(*args)

Pathname#join joins pathnames.

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

[Source]

# File pathname.rb, line 466
  def join(*args)
    args.unshift self
    result = args.pop
    result = Pathname.new(result) unless Pathname === result
    return result if result.absolute?
    args.reverse_each {|arg|
      arg = Pathname.new(arg) unless Pathname === arg
      result = arg + result
      return result if result.absolute?
    }
    result
  end

lchmod(mode)

See File.lchmod.

[Source]

# File pathname.rb, line 608
  def lchmod(mode) File.lchmod(mode, @path) end

lchown(owner, group)

See File.lchown.

[Source]

# File pathname.rb, line 614
  def lchown(owner, group) File.lchown(owner, group, @path) end

link(old)

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

[Source]

# File pathname.rb, line 674
  def link(old)
    warn 'Pathname#link is obsoleted.  Use Pathname#make_link.'
    File.link(old, @path)
  end

lstat()

See File.lstat.

[Source]

# File pathname.rb, line 645
  def lstat() File.lstat(@path) end

make_link(old)

See File.link. Creates a hard link.

[Source]

# File pathname.rb, line 628
  def make_link(old) File.link(old, @path) end

make_symlink(old)

See File.symlink. Creates a symbolic link.

[Source]

# File pathname.rb, line 648
  def make_symlink(old) File.symlink(old, @path) end

mkdir(*args)

See Dir.mkdir. Create the referenced directory.

[Source]

# File pathname.rb, line 803
  def mkdir(*args) Dir.mkdir(@path, *args) end

mkpath()

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

[Source]

# File pathname.rb, line 840
  def mkpath
    require 'fileutils'
    FileUtils.mkpath(@path)
    nil
  end

mountpoint?()

mountpoint? returns true if self points to a mountpoint.

[Source]

# File pathname.rb, line 378
  def mountpoint?
    begin
      stat1 = self.lstat
      stat2 = self.parent.lstat
      stat1.dev == stat2.dev && stat1.ino == stat2.ino ||
        stat1.dev != stat2.dev
    rescue Errno::ENOENT
      false
    end
  end

mtime()

See File.mtime. Returns last modification time.

[Source]

# File pathname.rb, line 602
  def mtime() File.mtime(@path) end

open(*args) {|file| ...}

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

[Source]

# File pathname.rb, line 631
  def open(*args, &block) # :yield: file

    File.open(@path, *args, &block)
  end

opendir() {|dir| ...}

See Dir.open.

[Source]

# File pathname.rb, line 809
  def opendir(&block) # :yield: dir

    Dir.open(@path, &block)
  end

owned?()

See FileTest.owned?.

[Source]

# File pathname.rb, line 721
  def owned?() FileTest.owned?(@path) end

parent()

parent returns the parent directory.

This is same as self + ’..’.

[Source]

# File pathname.rb, line 373
  def parent
    self + '..'
  end

pipe?()

See FileTest.pipe?.

[Source]

# File pathname.rb, line 715
  def pipe?() FileTest.pipe?(@path) end

read(*args)

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

[Source]

# File pathname.rb, line 583
  def read(*args) IO.read(@path, *args) end

readable?()

See FileTest.readable?.

[Source]

# File pathname.rb, line 724
  def readable?() FileTest.readable?(@path) end

readable_real?()

See FileTest.readable_real?.

[Source]

# File pathname.rb, line 727
  def readable_real?() FileTest.readable_real?(@path) end

readlines(*args)

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

[Source]

# File pathname.rb, line 586
  def readlines(*args) IO.readlines(@path, *args) end

readlink()

See File.readlink. Read symbolic link.

[Source]

# File pathname.rb, line 636
  def readlink() Pathname.new(File.readlink(@path)) end

realpath(*args)

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 pathname.rb, line 309
  def realpath(*args)
    unless args.empty?
      warn "The argument for Pathname#realpath is obsoleted."
    end
    force_absolute = args.fetch(0, true)

    if %r{\A/} =~ @path
      top = '/'
      unresolved = @path.scan(%r{[^/]+})
    elsif force_absolute
      # Although POSIX getcwd returns a pathname which contains no symlink,

      # 4.4BSD-Lite2 derived getcwd may return the environment variable $PWD

      # which may contain a symlink.

      # So the return value of Dir.pwd should be examined.

      top = '/'
      unresolved = Dir.pwd.scan(%r{[^/]+}) + @path.scan(%r{[^/]+})
    else
      top = ''
      unresolved = @path.scan(%r{[^/]+})
    end
    resolved = []

    until unresolved.empty?
      case unresolved.last
      when '.'
        unresolved.pop
      when '..'
        resolved.unshift unresolved.pop
      else
        loop_check = {}
        while (stat = File.lstat(path = top + unresolved.join('/'))).symlink?
          symlink_id = "#{stat.dev}:#{stat.ino}"
          raise Errno::ELOOP.new(path) if loop_check[symlink_id]
          loop_check[symlink_id] = true
          if %r{\A/} =~ (link = File.readlink(path))
            top = '/'
            unresolved = link.scan(%r{[^/]+})
          else
            unresolved[-1,1] = link.scan(%r{[^/]+})
          end
        end
        next if (filename = unresolved.pop) == '.'
        if filename != '..' && resolved.first == '..'
          resolved.shift
        else
          resolved.unshift filename
        end
      end
    end

    if top == '/'
      resolved.shift while resolved[0] == '..'
    end
    
    if resolved.empty?
      Pathname.new(top.empty? ? '.' : '/')
    else
      Pathname.new(top + resolved.join('/'))
    end
  end

relative?()

The opposite of absolute?

[Source]

# File pathname.rb, line 407
  def relative?
    !absolute?
  end

relative_path_from(base_directory)

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 pathname.rb, line 525
  def relative_path_from(base_directory)
    if self.absolute? != base_directory.absolute?
      raise ArgumentError,
        "relative path between absolute and relative path: #{self.inspect}, #{base_directory.inspect}"
    end

    dest = []
    self.cleanpath.each_filename {|f|
      next if f == '.'
      dest << f
    }

    base = []
    base_directory.cleanpath.each_filename {|f|
      next if f == '.'
      base << f
    }

    while !base.empty? && !dest.empty? && base[0] == dest[0]
      base.shift
      dest.shift
    end

    if base.include? '..'
      raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
    end

    base.fill '..'
    relpath = base + dest
    if relpath.empty?
      Pathname.new(".")
    else
      Pathname.new(relpath.join('/'))
    end
  end

rename(to)

See File.rename. Rename the file.

[Source]

# File pathname.rb, line 639
  def rename(to) File.rename(@path, to) end

rmdir()

See Dir.rmdir. Remove the referenced directory.

[Source]

# File pathname.rb, line 806
  def rmdir() Dir.rmdir(@path) end

rmtree()

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

[Source]

# File pathname.rb, line 847
  def rmtree
    # The name "rmtree" is borrowed from File::Path of Perl.

    # File::Path provides "mkpath" and "rmtree".

    require 'fileutils'
    FileUtils.rm_r(@path)
    nil
  end

root?()

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 pathname.rb, line 396
  def root?
    %r{\A/+\z} =~ @path ? true : false
  end

setgid?()

See FileTest.setgid?.

[Source]

# File pathname.rb, line 733
  def setgid?() FileTest.setgid?(@path) end

setuid?()

See FileTest.setuid?.

[Source]

# File pathname.rb, line 730
  def setuid?() FileTest.setuid?(@path) end

size()

See FileTest.size.

[Source]

# File pathname.rb, line 736
  def size() FileTest.size(@path) end

size?()

See FileTest.size?.

[Source]

# File pathname.rb, line 739
  def size?() FileTest.size?(@path) end

socket?()

See FileTest.socket?.

[Source]

# File pathname.rb, line 718
  def socket?() FileTest.socket?(@path) end

split()

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

[Source]

# File pathname.rb, line 670
  def split() File.split(@path).map {|f| Pathname.new(f) } end

stat()

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

[Source]

# File pathname.rb, line 642
  def stat() File.stat(@path) end

sticky?()

See FileTest.sticky?.

[Source]

# File pathname.rb, line 742
  def sticky?() FileTest.sticky?(@path) end

symlink(old)

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

[Source]

# File pathname.rb, line 681
  def symlink(old)
    warn 'Pathname#symlink is obsoleted.  Use Pathname#make_symlink.'
    File.symlink(old, @path)
  end

symlink?()

See FileTest.symlink?.

[Source]

# File pathname.rb, line 745
  def symlink?() FileTest.symlink?(@path) end

sysopen(*args)

See IO.sysopen.

[Source]

# File pathname.rb, line 589
  def sysopen(*args) IO.sysopen(@path, *args) end

taint()

[Source]

# File pathname.rb, line 199
  def taint() super; @path.taint; self end

to_s()

Return the path as a String.

[Source]

# File pathname.rb, line 225
  def to_s
    @path.dup
  end

to_str()

Alias for to_s

truncate(length)

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

[Source]

# File pathname.rb, line 651
  def truncate(length) File.truncate(@path, length) end

unlink()

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

[Source]

# File pathname.rb, line 860
  def unlink()
    if FileTest.directory? @path
      Dir.unlink @path
    else
      File.unlink @path
    end
  end

untaint()

[Source]

# File pathname.rb, line 200
  def untaint() super; @path.untaint; self end

utime(atime, mtime)

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

[Source]

# File pathname.rb, line 654
  def utime(atime, mtime) File.utime(atime, mtime, @path) end

writable?()

See FileTest.writable?.

[Source]

# File pathname.rb, line 748
  def writable?() FileTest.writable?(@path) end

writable_real?()

See FileTest.writable_real?.

[Source]

# File pathname.rb, line 751
  def writable_real?() FileTest.writable_real?(@path) end

zero?()

See FileTest.zero?.

[Source]

# File pathname.rb, line 754
  def zero?() FileTest.zero?(@path) end

Pathname

Examples

Example 1: Using Pathname

Example 2: Using standard Ruby

Example 3: Special features

Breakdown of functionality

Core methods

File status predicate methods

File property and manipulation methods

Directory methods

IO

Utilities

Method documentation

Methods

External Aliases

Public Class methods

Public Instance methods