class Pathname

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.

# File rake/lib/pathname.rb, line 307
def +(other)
  other = Pathname.new(other) unless Pathname === other
  Pathname.new(plus(@path, other.to_s))
end

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

# File rake/lib/pathname.rb, line 214
def absolute?
  !relative?
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.

# File rake/lib/pathname.rb, line 287
def ascend
  path = @path
  yield self
  while r = chop_basename(path)
    path, = r
    break if path.empty?
    yield self.class.new(del_trailing_separator(path))
  end
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:

pn = Pathname("/usr/lib/ruby/1.8")
pn.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, ... ]
pn.children(false)
    # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]

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

This method has existed since 1.8.1.

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

# File rake/lib/pathname.rb, line 85
def cleanpath(consider_symlink=false)
  if consider_symlink
    cleanpath_conservative
  else
    cleanpath_aggressive
  end
end

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.

# File rake/lib/pathname.rb, line 260
def descend
  vs = []
  ascend {|v| vs << v }
  vs.reverse_each {|v| yield v }
  nil
end

Iterates over the children of the directory (files and subdirectories, not recursive). It yields Pathname object for each child. By default, the yielded 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.

Pathname("/usr/local").each_child {|f| p f }
#=> #<Pathname:/usr/local/share>
#   #<Pathname:/usr/local/bin>
#   #<Pathname:/usr/local/games>
#   #<Pathname:/usr/local/lib>
#   #<Pathname:/usr/local/include>
#   #<Pathname:/usr/local/sbin>
#   #<Pathname:/usr/local/src>
#   #<Pathname:/usr/local/man>

Pathname("/usr/local").each_child(false) {|f| p f }
#=> #<Pathname:share>
#   #<Pathname:bin>
#   #<Pathname:games>
#   #<Pathname:lib>
#   #<Pathname:include>
#   #<Pathname:sbin>
#   #<Pathname:src>
#   #<Pathname:man>

# File rake/lib/pathname.rb, line 434
def each_child(with_directory=true, &b)
  children(with_directory).each(&b)
end

Iterates over each component of the path.

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

# File rake/lib/pathname.rb, line 233
def each_filename # :yield: filename
  return to_enum(__method__) unless block_given?
  _, names = split_names(@path)
  names.each {|filename| yield filename }
  nil
end

#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 traversal.

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

# File rake/lib/pathname.rb, line 498
def find(&block) # :yield: pathname
  require 'find'
  if @path == '.'
    Find.find(@path) {|f| yield self.class.new(f.sub(%r{\A\./}, '')) }
  else
    Find.find(@path) {|f| yield self.class.new(f) }
  end
end

#join joins pathnames.

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

# File rake/lib/pathname.rb, line 360
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

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

# File rake/lib/pathname.rb, line 512
def mkpath
  require 'fileutils'
  FileUtils.mkpath(@path)
  nil
end

mountpoint? returns true if self points to a mountpoint.

# File rake/lib/pathname.rb, line 190
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

parent returns the parent directory.

This is same as self + '..'.

# File rake/lib/pathname.rb, line 185
def parent
  self + '..'
end

The opposite of absolute?

# File rake/lib/pathname.rb, line 219
def relative?
  path = @path
  while r = chop_basename(path)
    path, = r
  end
  path == ''
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.

# File rake/lib/pathname.rb, line 449
def relative_path_from(base_directory)
  dest_directory = self.cleanpath.to_s
  base_directory = base_directory.cleanpath.to_s
  dest_prefix = dest_directory
  dest_names = []
  while r = chop_basename(dest_prefix)
    dest_prefix, basename = r
    dest_names.unshift basename if basename != '.'
  end
  base_prefix = base_directory
  base_names = []
  while r = chop_basename(base_prefix)
    base_prefix, basename = r
    base_names.unshift basename if basename != '.'
  end
  unless SAME_PATHS[dest_prefix, base_prefix]
    raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}"
  end
  while !dest_names.empty? &&
        !base_names.empty? &&
        SAME_PATHS[dest_names.first, base_names.first]
    dest_names.shift
    base_names.shift
  end
  if base_names.include? '..'
    raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
  end
  base_names.fill('..')
  relpath_names = base_names + dest_names
  if relpath_names.empty?
    Pathname.new('.')
  else
    Pathname.new(File.join(*relpath_names))
  end
end

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

# File rake/lib/pathname.rb, line 519
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? 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/...

# File rake/lib/pathname.rb, line 208
def root?
  !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/ =~ @path)
end