Class | Pathname |
In: |
lib/pathname.rb
|
Parent: | 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:
These methods are a facade for Dir:
These methods are a facade for IO:
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.
SEPARATOR_PAT | = | /[#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}]/ |
SEPARATOR_PAT | = | /#{Regexp.quote File::SEPARATOR}/ |
getwd | -> | pwd |
Create a Pathname object from the given String (or String-like object). If path contains a NUL character (\0), an ArgumentError is raised.
# File lib/pathname.rb, line 203 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 lib/pathname.rb, line 595 def +(other) other = Pathname.new(other) unless Pathname === other Pathname.new(plus(@path, other.to_s)) end
Provides for comparing pathnames, case-sensitively.
# File lib/pathname.rb, line 231 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 lib/pathname.rb, line 223 def ==(other) return false unless Pathname === other other.to_s == @path end
Predicate method for testing whether a path is absolute. It returns true if the pathname begins with a slash.
# File lib/pathname.rb, line 503 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 lib/pathname.rb, line 575 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 lib/pathname.rb, line 776 def atime() File.atime(@path) end
See File.basename. Returns the last component of the path.
# File lib/pathname.rb, line 837 def basename(*args) self.class.new(File.basename(@path, *args)) end
See FileTest.blockdev?.
# File lib/pathname.rb, line 871 def blockdev?() FileTest.blockdev?(@path) end
Pathname#chdir is obsoleted at 1.8.1.
# File lib/pathname.rb, line 959 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 lib/pathname.rb, line 682 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 lib/pathname.rb, line 785 def chmod(mode) File.chmod(mode, @path) end
See File.chown. Change owner and group of file.
# File lib/pathname.rb, line 791 def chown(owner, group) File.chown(owner, group, @path) end
Pathname#chroot is obsoleted at 1.8.1.
# File lib/pathname.rb, line 965 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 lib/pathname.rb, line 320 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 lib/pathname.rb, line 779 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 lib/pathname.rb, line 548 def descend vs = [] ascend {|v| vs << v } vs.reverse_each {|v| yield v } nil end
Pathname#dir_foreach is obsoleted at 1.8.1.
# File lib/pathname.rb, line 983 def dir_foreach(*args, &block) warn "Pathname#dir_foreach is obsoleted. Use Pathname#each_entry." each_entry(*args, &block) end
See FileTest.directory?.
# File lib/pathname.rb, line 889 def directory?() FileTest.directory?(@path) end
See File.dirname. Returns all but the last component of the path.
# File lib/pathname.rb, line 840 def dirname() self.class.new(File.dirname(@path)) end
Iterates over each component of the path.
Pathname.new("/usr/bin/ruby").each_filename {|filename| ... } # yields "usr", "bin", and "ruby".
# File lib/pathname.rb, line 522 def each_filename # :yield: filename prefix, names = split_names(@path) names.each {|filename| yield filename } nil end
See FileTest.executable?.
# File lib/pathname.rb, line 877 def executable?() FileTest.executable?(@path) end
See FileTest.executable_real?.
# File lib/pathname.rb, line 880 def executable_real?() FileTest.executable_real?(@path) end
See File.expand_path.
# File lib/pathname.rb, line 846 def expand_path(*args) self.class.new(File.expand_path(@path, *args)) end
See File.extname. Returns the file‘s extension.
# File lib/pathname.rb, line 843 def extname() File.extname(@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 lib/pathname.rb, line 1012 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 lib/pathname.rb, line 798 def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end
See File.fnmatch? (same as fnmatch).
# File lib/pathname.rb, line 801 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 lib/pathname.rb, line 1056 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
Pathname#foreachline is obsoleted at 1.8.1. Use each_line.
# File lib/pathname.rb, line 756 def foreachline(*args, &block) warn "Pathname#foreachline is obsoleted. Use Pathname#each_line." each_line(*args, &block) end
See File.ftype. Returns "type" of file ("file", "directory", etc).
# File lib/pathname.rb, line 805 def ftype() File.ftype(@path) end
See FileTest.grpowned?.
# File lib/pathname.rb, line 886 def grpowned?() FileTest.grpowned?(@path) end
Pathname#join joins pathnames.
path0.join(path1, …, pathN) is the same as path0 + path1 + … + pathN.
# File lib/pathname.rb, line 648 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 lib/pathname.rb, line 788 def lchmod(mode) File.lchmod(mode, @path) end
See File.lchown.
# File lib/pathname.rb, line 794 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.
# File lib/pathname.rb, line 854 def link(old) warn 'Pathname#link is obsoleted. Use Pathname#make_link.' File.link(old, @path) end
See File.symlink. Creates a symbolic link.
# File lib/pathname.rb, line 828 def make_symlink(old) File.symlink(old, @path) end
See FileUtils.mkpath. Creates a full path, including any intermediate directories that don‘t yet exist.
# File lib/pathname.rb, line 1026 def mkpath require 'fileutils' FileUtils.mkpath(@path) nil end
mountpoint? returns true if self points to a mountpoint.
# File lib/pathname.rb, line 479 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 lib/pathname.rb, line 782 def mtime() File.mtime(@path) end
See File.open. Opens the file for reading or writing.
# File lib/pathname.rb, line 811 def open(*args, &block) # :yield: file File.open(@path, *args, &block) end
See FileTest.readable?.
# File lib/pathname.rb, line 904 def readable?() FileTest.readable?(@path) end
See FileTest.readable_real?.
# File lib/pathname.rb, line 910 def readable_real?() FileTest.readable_real?(@path) end
See IO.readlines. Returns all the lines from the file.
# File lib/pathname.rb, line 766 def readlines(*args) IO.readlines(@path, *args) end
See File.readlink. Read symbolic link.
# File lib/pathname.rb, line 816 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 lib/pathname.rb, line 460 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 lib/pathname.rb, line 508 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 lib/pathname.rb, line 707 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 if dest_prefix != base_prefix raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}" end while !dest_names.empty? && !base_names.empty? && 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 lib/pathname.rb, line 819 def rename(to) File.rename(@path, to) end
See FileUtils.rm_r. Deletes a directory and all beneath it.
# File lib/pathname.rb, line 1033 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 lib/pathname.rb, line 497 def root? !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o =~ @path) end
See File.split. Returns the dirname and the basename in an Array.
# File lib/pathname.rb, line 850 def split() File.split(@path).map {|f| self.class.new(f) } end
See File.stat. Returns a File::Stat object.
# File lib/pathname.rb, line 822 def stat() File.stat(@path) end
Return a pathname which is substituted by String#sub.
# File lib/pathname.rb, line 253 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
Pathname#symlink is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.
# File lib/pathname.rb, line 861 def symlink(old) warn 'Pathname#symlink is obsoleted. Use Pathname#make_symlink.' File.symlink(old, @path) end
See IO.sysopen.
# File lib/pathname.rb, line 769 def sysopen(*args) IO.sysopen(@path, *args) end
See File.truncate. Truncate the file to length bytes.
# File lib/pathname.rb, line 831 def truncate(length) File.truncate(@path, length) end
Removes a file or directory, using File.unlink or Dir.unlink as necessary.
# File lib/pathname.rb, line 1046 def unlink() begin Dir.unlink @path rescue Errno::ENOTDIR File.unlink @path end end
See File.utime. Update the access and modification times.
# File lib/pathname.rb, line 834 def utime(atime, mtime) File.utime(atime, mtime, @path) end
See FileTest.world_readable?.
# File lib/pathname.rb, line 907 def world_readable?() FileTest.world_readable?(@path) end
See FileTest.world_writable?.
# File lib/pathname.rb, line 934 def world_writable?() FileTest.world_writable?(@path) end
See FileTest.writable?.
# File lib/pathname.rb, line 931 def writable?() FileTest.writable?(@path) end