Object
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.
require 'pathname' pn = Pathname.new("/usr/bin/ruby") size = pn.size # 27662 isdir = pn.directory? # false dir = pn.dirname # Pathname:/usr/bin base = pn.basename # Pathname:ruby dir, base = pn.split # [Pathname:/usr/bin, Pathname:ruby] data = pn.read pn.open { |f| _ } pn.each_line { |line| _ }
pn = "/usr/bin/ruby" size = File.size(pn) # 27662 isdir = File.directory?(pn) # false dir = File.dirname(pn) # "/usr/bin" base = File.basename(pn) # "ruby" dir, base = File.split(pn) # ["/usr/bin", "ruby"] data = File.read(pn) File.open(pn) { |f| _ } File.foreach(pn) { |line| _ }
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, ...]
These methods are effectively manipulating a String, because that’s all a path is. Except for mountpoint?, children, each_child, realdirpath and realpath, they don’t access the filesystem.
+
These methods are a facade for FileTest:
These methods are a facade for File:
chown(owner, group)
lchown(owner, group)
fnmatch(pattern, *args)
fnmatch?(pattern, *args)
open(*args, &block)
utime(atime, mtime)
These methods are a facade for Dir:
each_entry(&block)
These methods are a facade for IO:
each_line(*args, &block)
These methods are a mixture of Find, FileUtils, and others:
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.
See Dir.getwd. Returns the current working directory as a Pathname.
# File pathname.rb, line 958
def Pathname.getwd() self.new(Dir.getwd) end
See Dir.glob. Returns or yields Pathname objects.
# File pathname.rb, line 949
def Pathname.glob(*args) # :yield: pathname
if block_given?
Dir.glob(*args) {|f| yield self.new(f) }
else
Dir.glob(*args).map {|f| self.new(f) }
end
end
Create a Pathname object from the given String (or String-like object). If path contains a NUL character (\0), an ArgumentError is raised.
# File pathname.rb, line 213
def initialize(path)
path = path.__send__(TO_PATH) if path.respond_to? TO_PATH
@path = path.dup
if /\00// =~ @path
raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
end
self.taint if @path.tainted?
end
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 pathname.rb, line 584
def +(other)
other = Pathname.new(other) unless Pathname === other
Pathname.new(plus(@path, other.to_s))
end
Provides for comparing pathnames, case-sensitively.
# File pathname.rb, line 241
def <=>(other)
return nil unless Pathname === other
@path.tr('/', "\00"") <=> other.to_s.tr('/', "\00"")
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.
# File pathname.rb, line 233
def ==(other)
return false unless Pathname === other
other.to_s == @path
end
to_path is implemented so Pathname objects are usable with File.open, etc.
Predicate method for testing whether a path is absolute. It returns true if the pathname begins with a slash.
# File pathname.rb, line 491
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 pathname.rb, line 564
def ascend
path = @path
yield self
while r = chop_basename(path)
path, name = r
break if path.empty?
yield self.class.new(del_trailing_separator(path))
end
end
See File.atime. Returns last access time.
# File pathname.rb, line 793
def atime() File.atime(@path) end
See File.basename. Returns the last component of the path.
# File pathname.rb, line 854
def basename(*args) self.class.new(File.basename(@path, *args)) end
See IO.binread. Returns all the bytes from the file, or the first N if specified.
# File pathname.rb, line 780
def binread(*args) IO.binread(@path, *args) end
See FileTest.blockdev?.
# File pathname.rb, line 874
def blockdev?() FileTest.blockdev?(@path) end
See FileTest.chardev?.
# File pathname.rb, line 877
def chardev?() FileTest.chardev?(@path) 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 result never contain the entries . and .. in the directory because they are not children.
This method has existed since 1.8.1.
# File pathname.rb, line 671
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
See File.chmod. Changes permissions.
# File pathname.rb, line 802
def chmod(mode) File.chmod(mode, @path) end
See File.chown. Change owner and group of file.
# File pathname.rb, line 808
def chown(owner, group) File.chown(owner, group, @path) 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 pathname.rb, line 341
def cleanpath(consider_symlink=false)
if consider_symlink
cleanpath_conservative
else
cleanpath_aggressive
end
end
See File.ctime. Returns last (directory entry, not file) change time.
# File pathname.rb, line 796
def ctime() File.ctime(@path) 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 pathname.rb, line 537
def descend
vs = []
ascend {|v| vs << v }
vs.reverse_each {|v| yield v }
nil
end
See FileTest.directory?.
# File pathname.rb, line 892
def directory?() FileTest.directory?(@path) end
See File.dirname. Returns all but the last component of the path.
# File pathname.rb, line 857
def dirname() self.class.new(File.dirname(@path)) 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 pathname.rb, line 711
def each_child(with_directory=true, &b)
children(with_directory).each(&b)
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.
# File pathname.rb, line 969
def each_entry(&block) # :yield: pathname
Dir.foreach(@path) {|f| yield self.class.new(f) }
end
Iterates over each component of the path.
Pathname.new("/usr/bin/ruby").each_filename {|filename| ... } # yields "usr", "bin", and "ruby".
# File pathname.rb, line 510
def each_filename # :yield: filename
return to_enum(__method__) unless block_given?
prefix, names = split_names(@path)
names.each {|filename| yield filename }
nil
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.
# File pathname.rb, line 770
def each_line(*args, &block) # :yield: line
IO.foreach(@path, *args, &block)
end
Return the entries (files and subdirectories) in the directory, each as a Pathname object.
# File pathname.rb, line 963
def entries() Dir.entries(@path).map {|f| self.class.new(f) } end
See FileTest.executable?.
# File pathname.rb, line 880
def executable?() FileTest.executable?(@path) end
See FileTest.executable_real?.
# File pathname.rb, line 883
def executable_real?() FileTest.executable_real?(@path) end
See FileTest.exist?.
# File pathname.rb, line 886
def exist?() FileTest.exist?(@path) end
See File.expand_path.
# File pathname.rb, line 863
def expand_path(*args) self.class.new(File.expand_path(@path, *args)) end
See File.extname. Returns the file’s extension.
# File pathname.rb, line 860
def extname() File.extname(@path) end
See FileTest.file?.
# File pathname.rb, line 895
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 ./.
# File pathname.rb, line 997
def find(&block) # :yield: pathname
require 'find'
if @path == '.'
Find.find(@path) {|f| yield self.class.new(f.sub(%{\A\./}, '')) }
else
Find.find(@path) {|f| yield self.class.new(f) }
end
end
See File.fnmatch. Return true if the receiver matches the given pattern.
# File pathname.rb, line 815
def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end
See File.fnmatch? (same as fnmatch).
# File pathname.rb, line 818
def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end
# File pathname.rb, line 224
def freeze() super; @path.freeze; self end
See File.ftype. Returns “type” of file (“file”, “directory”, etc).
# File pathname.rb, line 822
def ftype() File.ftype(@path) end
See FileTest.grpowned?.
# File pathname.rb, line 889
def grpowned?() FileTest.grpowned?(@path) end
Pathname#join joins pathnames.
path0.join(path1, ..., pathN) is the same as path0 + path1 + ... + pathN.
# File pathname.rb, line 637
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 File.lchmod.
# File pathname.rb, line 805
def lchmod(mode) File.lchmod(mode, @path) end
See File.lchown.
# File pathname.rb, line 811
def lchown(owner, group) File.lchown(owner, group, @path) end
See File.lstat.
# File pathname.rb, line 842
def lstat() File.lstat(@path) end
See File.link. Creates a hard link.
# File pathname.rb, line 825
def make_link(old) File.link(old, @path) end
See File.symlink. Creates a symbolic link.
# File pathname.rb, line 845
def make_symlink(old) File.symlink(old, @path) end
See Dir.mkdir. Create the referenced directory.
# File pathname.rb, line 974
def mkdir(*args) Dir.mkdir(@path, *args) end
See FileUtils.mkpath. Creates a full path, including any intermediate directories that don’t yet exist.
# File pathname.rb, line 1011
def mkpath
require 'fileutils'
FileUtils.mkpath(@path)
nil
end
mountpoint? returns true if self points to a mountpoint.
# File pathname.rb, line 467
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
See File.mtime. Returns last modification time.
# File pathname.rb, line 799
def mtime() File.mtime(@path) end
See File.open. Opens the file for reading or writing.
# File pathname.rb, line 828
def open(*args, &block) # :yield: file
File.open(@path, *args, &block)
end
See Dir.open.
# File pathname.rb, line 980
def opendir(&block) # :yield: dir
Dir.open(@path, &block)
end
See FileTest.owned?.
# File pathname.rb, line 904
def owned?() FileTest.owned?(@path) end
parent returns the parent directory.
This is same as self + '..'.
# File pathname.rb, line 462
def parent
self + '..'
end
See FileTest.pipe?.
# File pathname.rb, line 898
def pipe?() FileTest.pipe?(@path) end
See IO.read. Returns all data from the file, or the first N bytes if specified.
# File pathname.rb, line 776
def read(*args) IO.read(@path, *args) end
See FileTest.readable?.
# File pathname.rb, line 907
def readable?() FileTest.readable?(@path) end
See FileTest.readable_real?.
# File pathname.rb, line 913
def readable_real?() FileTest.readable_real?(@path) end
See IO.readlines. Returns all the lines from the file.
# File pathname.rb, line 783
def readlines(*args) IO.readlines(@path, *args) end
See File.readlink. Read symbolic link.
# File pathname.rb, line 833
def readlink() self.class.new(File.readlink(@path)) end
Returns the real (absolute) pathname of self in the actual filesystem. The real pathname doesn’t contain symlinks or useless dots.
The last component of the real pathname can be nonexistent.
# File pathname.rb, line 455
def realdirpath(basedir=nil)
self.class.new(File.realdirpath(@path, basedir))
end
Returns the real (absolute) pathname of self in the actual filesystem not containing symlinks or useless dots.
All components of the pathname must exist when this method is called.
# File pathname.rb, line 445
def realpath(basedir=nil)
self.class.new(File.realpath(@path, basedir))
end
The opposite of absolute?
# File pathname.rb, line 496
def relative?
path = @path
while r = chop_basename(path)
path, basename = 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 pathname.rb, line 726
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 File.rename. Rename the file.
# File pathname.rb, line 836
def rename(to) File.rename(@path, to) end
See Dir.rmdir. Remove the referenced directory.
# File pathname.rb, line 977
def rmdir() Dir.rmdir(@path) end
See FileUtils.rm_r. Deletes a directory and all beneath it.
# File pathname.rb, line 1018
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 pathname.rb, line 485
def root?
!!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/ =~ @path)
end
See FileTest.setgid?.
# File pathname.rb, line 919
def setgid?() FileTest.setgid?(@path) end
See FileTest.setuid?.
# File pathname.rb, line 916
def setuid?() FileTest.setuid?(@path) end
See FileTest.size.
# File pathname.rb, line 922
def size() FileTest.size(@path) end
See FileTest.size?.
# File pathname.rb, line 925
def size?() FileTest.size?(@path) end
See FileTest.socket?.
# File pathname.rb, line 901
def socket?() FileTest.socket?(@path) end
See File.stat. Returns a File::Stat object.
# File pathname.rb, line 839
def stat() File.stat(@path) end
See FileTest.sticky?.
# File pathname.rb, line 928
def sticky?() FileTest.sticky?(@path) end
Return a pathname which is substituted by String#sub.
# File pathname.rb, line 263
def sub(pattern, *rest, &block)
if block
path = @path.sub(pattern, *rest) {|*args|
begin
old = Thread.current[:pathname_sub_matchdata]
Thread.current[:pathname_sub_matchdata] = $~
eval("$~ = Thread.current[:pathname_sub_matchdata]", block.binding)
ensure
Thread.current[:pathname_sub_matchdata] = old
end
yield(*args)
}
else
path = @path.sub(pattern, *rest)
end
self.class.new(path)
end
Return a pathname which the extension of the basename is substituted by repl.
If self has no extension part, repl is appended.
# File pathname.rb, line 293
def sub_ext(repl)
ext = File.extname(@path)
self.class.new(@path.chomp(ext) + repl)
end
See FileTest.symlink?.
# File pathname.rb, line 931
def symlink?() FileTest.symlink?(@path) end
See IO.sysopen.
# File pathname.rb, line 786
def sysopen(*args) IO.sysopen(@path, *args) end
# File pathname.rb, line 225
def taint() super; @path.taint; self end
Return the path as a String.
# File pathname.rb, line 251
def to_s
@path.dup
end
See File.truncate. Truncate the file to length bytes.
# File pathname.rb, line 848
def truncate(length) File.truncate(@path, length) end
Removes a file or directory, using File.unlink or Dir.unlink as necessary.
# File pathname.rb, line 1031
def unlink()
begin
Dir.unlink @path
rescue Errno::ENOTDIR
File.unlink @path
end
end
# File pathname.rb, line 226
def untaint() super; @path.untaint; self end
See File.utime. Update the access and modification times.
# File pathname.rb, line 851
def utime(atime, mtime) File.utime(atime, mtime, @path) end
See FileTest.world_readable?.
# File pathname.rb, line 910
def world_readable?() FileTest.world_readable?(@path) end
See FileTest.world_writable?.
# File pathname.rb, line 937
def world_writable?() FileTest.world_writable?(@path) end
See FileTest.writable?.
# File pathname.rb, line 934
def writable?() FileTest.writable?(@path) end