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' 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| _ }
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| _ }
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, 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 974 def Pathname.getwd() self.new(Dir.getwd) end
See Dir.glob
. Returns or yields Pathname objects.
# File pathname.rb, line 965 def Pathname.glob(*args) # :yield: p 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 210 def initialize(path) path = path.__send__(TO_PATH) if path.respond_to? TO_PATH @path = path.dup if /\0/ =~ @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 614 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 238 def <=>(other) return nil unless Pathname === other @path.tr('/', "\0") <=> other.to_s.tr('/', "\0") 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 230 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 521 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 594 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 795 def atime() File.atime(@path) end
See File.basename
. Returns the last component of the path.
# File pathname.rb, line 856 def basename(*args) self.class.new(File.basename(@path, *args)) end
See FileTest.blockdev?
.
# File pathname.rb, line 890 def blockdev?() FileTest.blockdev?(@path) end
See FileTest.chardev?
.
# File pathname.rb, line 893 def chardev?() FileTest.chardev?(@path) end
#chdir is obsoleted at 1.8.1.
# File pathname.rb, line 978 def chdir(&block) warn "Pathname#chdir is obsoleted. Use Dir.chdir." Dir.chdir(@path, &block) 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.
# File pathname.rb, line 701 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 804 def chmod(mode) File.chmod(mode, @path) end
See File.chown
. Change owner and group of file.
# File pathname.rb, line 810 def chown(owner, group) File.chown(owner, group, @path) end
#chroot is obsoleted at 1.8.1.
# File pathname.rb, line 984 def chroot warn "Pathname#chroot is obsoleted. Use Dir.chroot." Dir.chroot(@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 338 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 798 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 567 def descend vs = [] ascend {|v| vs << v } vs.reverse_each {|v| yield v } nil end
#dir_foreach is obsoleted at 1.8.1.
# File pathname.rb, line 1002 def dir_foreach(*args, &block) warn "Pathname#dir_foreach is obsoleted. Use Pathname#each_entry." each_entry(*args, &block) end
See FileTest.directory?
.
# File pathname.rb, line 908 def directory?() FileTest.directory?(@path) end
See File.dirname
. Returns all but the last component of the
path.
# File pathname.rb, line 859 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.
# File pathname.rb, line 997 def each_entry(&block) # :yield: p 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 540 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 991 def entries() Dir.entries(@path).map {|f| self.class.new(f) } end
See FileTest.executable?
.
# File pathname.rb, line 896 def executable?() FileTest.executable?(@path) end
See FileTest.executable_real?
.
# File pathname.rb, line 899 def executable_real?() FileTest.executable_real?(@path) end
See FileTest.exist?
.
# File pathname.rb, line 902 def exist?() FileTest.exist?(@path) end
See File.expand_path
.
# File pathname.rb, line 865 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 862 def extname() File.extname(@path) end
See FileTest.file?
.
# File pathname.rb, line 911 def file?() FileTest.file?(@path) 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 traverse.
If self
is .
, yielded pathnames begin with a
filename in the current directory, not ./
.
# File pathname.rb, line 1031 def find(&block) # :yield: p 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
See File.fnmatch
. Return true
if the receiver
matches the given pattern.
# File pathname.rb, line 817 def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end
See File.fnmatch?
(same as fnmatch).
# File pathname.rb, line 820 def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end
This method is obsoleted at 1.8.1. Use each_line or each_entry.
# File pathname.rb, line 1075 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 is obsoleted at 1.8.1. Use each_line.
# File pathname.rb, line 775 def foreachline(*args, &block) warn "Pathname#foreachline is obsoleted. Use Pathname#each_line." each_line(*args, &block) end
# File pathname.rb, line 221 def freeze() super; @path.freeze; self end
See File.ftype
. Returns “type” of file (“file”, “directory”,
etc).
# File pathname.rb, line 824 def ftype() File.ftype(@path) end
See FileTest.grpowned?
.
# File pathname.rb, line 905 def grpowned?() FileTest.grpowned?(@path) end
#join joins pathnames.
path0.join(path1, ..., pathN)
is the same as path0 +
path1 + ... + pathN
.
# File pathname.rb, line 667 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 807 def lchmod(mode) File.lchmod(mode, @path) end
See File.lchown
.
# File pathname.rb, line 813 def lchown(owner, group) File.lchown(owner, group, @path) end
#link is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.
# File pathname.rb, line 873 def link(old) warn 'Pathname#link is obsoleted. Use Pathname#make_link.' File.link(old, @path) end
See File.lstat
.
# File pathname.rb, line 844 def lstat() File.lstat(@path) end
See File.link
. Creates a hard link.
# File pathname.rb, line 827 def make_link(old) File.link(old, @path) end
See File.symlink
. Creates a symbolic link.
# File pathname.rb, line 847 def make_symlink(old) File.symlink(old, @path) end
See Dir.mkdir
. Create the referenced directory.
# File pathname.rb, line 1008 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 1045 def mkpath require 'fileutils' FileUtils.mkpath(@path) nil end
mountpoint? returns true
if self
points to a
mountpoint.
# File pathname.rb, line 497 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 801 def mtime() File.mtime(@path) end
See File.open
. Opens the file for reading or writing.
# File pathname.rb, line 830 def open(*args, &block) # :yield: file File.open(@path, *args, &block) end
See Dir.open
.
# File pathname.rb, line 1014 def opendir(&block) # :yield: dir Dir.open(@path, &block) end
See FileTest.owned?
.
# File pathname.rb, line 920 def owned?() FileTest.owned?(@path) end
parent returns the parent directory.
This is same as self + '..'
.
# File pathname.rb, line 492 def parent self + '..' end
See FileTest.pipe?
.
# File pathname.rb, line 914 def pipe?() FileTest.pipe?(@path) end
See IO.read
. Returns all the bytes from the file, or the
first N
if specified.
# File pathname.rb, line 782 def read(*args) IO.read(@path, *args) end
See FileTest.readable?
.
# File pathname.rb, line 923 def readable?() FileTest.readable?(@path) end
See FileTest.readable_real?
.
# File pathname.rb, line 929 def readable_real?() FileTest.readable_real?(@path) end
See IO.readlines
. Returns all the lines from the file.
# File pathname.rb, line 785 def readlines(*args) IO.readlines(@path, *args) end
See File.readlink
. Read symbolic link.
# File pathname.rb, line 835 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.
# File pathname.rb, line 478 def realpath path = @path prefix, names = split_names(path) if prefix == '' prefix, names2 = split_names(Dir.pwd) names = names2 + names end prefix, *names = realpath_rec(prefix, names, {}) self.class.new(prepend_prefix(prefix, File.join(*names))) end
The opposite of absolute?
# File pathname.rb, line 526 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 838 def rename(to) File.rename(@path, to) end
See Dir.rmdir
. Remove the referenced directory.
# File pathname.rb, line 1011 def rmdir() Dir.rmdir(@path) end
See FileUtils.rm_r
. Deletes a directory and all beneath it.
# File pathname.rb, line 1052 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 515 def root? !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o =~ @path) end
See FileTest.setgid?
.
# File pathname.rb, line 935 def setgid?() FileTest.setgid?(@path) end
See FileTest.setuid?
.
# File pathname.rb, line 932 def setuid?() FileTest.setuid?(@path) end
See FileTest.size
.
# File pathname.rb, line 938 def size() FileTest.size(@path) end
See FileTest.size?
.
# File pathname.rb, line 941 def size?() FileTest.size?(@path) end
See FileTest.socket?
.
# File pathname.rb, line 917 def socket?() FileTest.socket?(@path) end
See File.stat
. Returns a File::Stat
object.
# File pathname.rb, line 841 def stat() File.stat(@path) end
See FileTest.sticky?
.
# File pathname.rb, line 944 def sticky?() FileTest.sticky?(@path) end
Return a pathname which is substituted by String#sub.
# File pathname.rb, line 260 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 290 def sub_ext(repl) ext = File.extname(@path) self.class.new(@path.chomp(ext) + repl) end
#symlink is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.
# File pathname.rb, line 880 def symlink(old) warn 'Pathname#symlink is obsoleted. Use Pathname#make_symlink.' File.symlink(old, @path) end
See FileTest.symlink?
.
# File pathname.rb, line 947 def symlink?() FileTest.symlink?(@path) end
See IO.sysopen
.
# File pathname.rb, line 788 def sysopen(*args) IO.sysopen(@path, *args) end
# File pathname.rb, line 222 def taint() super; @path.taint; self end
Return the path as a String.
# File pathname.rb, line 248 def to_s @path.dup end
See File.truncate
. Truncate the file to length
bytes.
# File pathname.rb, line 850 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 1065 def unlink() begin Dir.unlink @path rescue Errno::ENOTDIR File.unlink @path end end
# File pathname.rb, line 223 def untaint() super; @path.untaint; self end
See File.utime
. Update the access and modification times.
# File pathname.rb, line 853 def utime(atime, mtime) File.utime(atime, mtime, @path) end
See FileTest.world_readable?
.
# File pathname.rb, line 926 def world_readable?() FileTest.world_readable?(@path) end
See FileTest.world_writable?
.
# File pathname.rb, line 953 def world_writable?() FileTest.world_writable?(@path) end
See FileTest.writable?
.
# File pathname.rb, line 950 def writable?() FileTest.writable?(@path) end