Pathname represents the name of a file or directory on the filesystem, but not the file itself.
The pathname depends on the Operating System: Unix, Windows, etc. This library works with pathnames of local OS, however non-Unix pathnames are supported experimentally.
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 goal 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.
Examples
Example 1: Using Pathname
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| _ }
Example 2: Using standard Ruby
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| _ }
Example 3: Special features
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, ...]
Breakdown of functionality
Core methods
These methods are effectively manipulating a String, because that’s all a path is. None of these access the file system except for mountpoint?, children, each_child, realdirpath and realpath.
-
+
File status predicate methods
These methods are a facade for FileTest:
File property and manipulation methods
These methods are a facade for File:
-
open(*args, &block)
Directory methods
These methods are a facade for Dir:
-
each_entry(&block)
IO
These methods are a facade for IO:
-
each_line(*args, &block)
Utilities
These methods are a mixture of Find, FileUtils, and others:
Method documentation
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.
static VALUE
path_s_getwd(VALUE klass)
{
VALUE str;
str = rb_funcall(rb_cDir, id_getwd, 0);
return rb_class_new_instance(1, &str, klass);
}
static VALUE
path_s_glob(int argc, VALUE *argv, VALUE klass)
{
VALUE args[3];
int n;
n = rb_scan_args(argc, argv, "12", &args[0], &args[1], &args[2]);
if (rb_block_given_p()) {
return rb_block_call_kw(rb_cDir, id_glob, n, args, s_glob_i, klass, RB_PASS_CALLED_KEYWORDS);
}
else {
VALUE ary;
long i;
ary = rb_funcallv_kw(rb_cDir, id_glob, n, args, RB_PASS_CALLED_KEYWORDS);
ary = rb_convert_type(ary, T_ARRAY, "Array", "to_ary");
for (i = 0; i < RARRAY_LEN(ary); i++) {
VALUE elt = RARRAY_AREF(ary, i);
elt = rb_class_new_instance(1, &elt, klass);
rb_ary_store(ary, i, elt);
}
return ary;
}
}
static VALUE
path_initialize(VALUE self, VALUE arg)
{
VALUE str;
if (RB_TYPE_P(arg, T_STRING)) {
str = arg;
}
else {
str = rb_check_funcall(arg, id_to_path, 0, NULL);
if (str == Qundef)
str = arg;
StringValue(str);
}
if (memchr(RSTRING_PTR(str), '\0', RSTRING_LEN(str)))
rb_raise(rb_eArgError, "pathname contains null byte");
str = rb_obj_dup(str);
set_strpath(self, str);
return self;
}
Create a Pathname object from the given String (or String-like object). If path contains a NULL character (\0), an ArgumentError is raised.
static VALUE
path_s_getwd(VALUE klass)
{
VALUE str;
str = rb_funcall(rb_cDir, id_getwd, 0);
return rb_class_new_instance(1, &str, klass);
}
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 352
def +(other)
other = Pathname.new(other) unless Pathname === other
Pathname.new(plus(@path, other.to_s))
end
Appends a pathname fragment to self 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 # / is aliased to +. p4 = p1 / "bin/ruby" # Pathname:/usr/bin/ruby p5 = p1 / "/etc/passwd" # Pathname:/etc/passwd
This method doesn’t access the file system; it is pure string manipulation.
static VALUE
path_cmp(VALUE self, VALUE other)
{
VALUE s1, s2;
char *p1, *p2;
char *e1, *e2;
if (!rb_obj_is_kind_of(other, rb_cPathname))
return Qnil;
s1 = get_strpath(self);
s2 = get_strpath(other);
p1 = RSTRING_PTR(s1);
p2 = RSTRING_PTR(s2);
e1 = p1 + RSTRING_LEN(s1);
e2 = p2 + RSTRING_LEN(s2);
while (p1 < e1 && p2 < e2) {
int c1, c2;
c1 = (unsigned char)*p1++;
c2 = (unsigned char)*p2++;
if (c1 == '/') c1 = '\0';
if (c2 == '/') c2 = '\0';
if (c1 != c2) {
if (c1 < c2)
return INT2FIX(-1);
else
return INT2FIX(1);
}
}
if (p1 < e1)
return INT2FIX(1);
if (p2 < e2)
return INT2FIX(-1);
return INT2FIX(0);
}
Provides a case-sensitive comparison operator for pathnames.
Pathname.new('/usr') <=> Pathname.new('/usr/bin') #=> -1 Pathname.new('/usr/bin') <=> Pathname.new('/usr/bin') #=> 0 Pathname.new('/usr/bin') <=> Pathname.new('/USR/BIN') #=> 1
It will return -1, 0 or 1 depending on the value of the left argument relative to the right argument. Or it will return nil if the arguments are not comparable.
static VALUE
path_eq(VALUE self, VALUE other)
{
if (!rb_obj_is_kind_of(other, rb_cPathname))
return Qfalse;
return rb_str_equal(get_strpath(self), get_strpath(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.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 231
def absolute?
ABSOLUTE_PATH.match? @path
end
Predicate method for testing whether a path is absolute.
It returns true if the pathname begins with a slash.
p = Pathname.new('/im/sure') p.absolute? #=> true p = Pathname.new('not/so/sure') p.absolute? #=> false
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 328
def ascend
return to_enum(__method__) unless block_given?
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
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>
Returns an Enumerator if no block was given.
enum = Pathname.new("/usr/bin/ruby").ascend
# ... do stuff ...
enum.each { |e| ... }
# yields Pathnames /usr/bin/ruby, /usr/bin, /usr, and /.
It doesn’t access the filesystem.
static VALUE
path_atime(VALUE self)
{
return rb_funcall(rb_cFile, id_atime, 1, get_strpath(self));
}
Returns the last access time for the file.
See File.atime.
static VALUE
path_basename(int argc, VALUE *argv, VALUE self)
{
VALUE str = get_strpath(self);
VALUE fext;
if (rb_scan_args(argc, argv, "01", &fext) == 0)
str = rb_funcall(rb_cFile, id_basename, 1, str);
else
str = rb_funcall(rb_cFile, id_basename, 2, str, fext);
return rb_class_new_instance(1, &str, rb_obj_class(self));
}
Returns the last component of the path.
See File.basename.
static VALUE
path_binread(int argc, VALUE *argv, VALUE self)
{
VALUE args[3];
int n;
args[0] = get_strpath(self);
n = rb_scan_args(argc, argv, "02", &args[1], &args[2]);
return rb_funcallv(rb_cFile, id_binread, 1+n, args);
}
Returns all the bytes from the file, or the first N if specified.
See File.binread.
static VALUE
path_binwrite(int argc, VALUE *argv, VALUE self)
{
VALUE args[4];
int n;
args[0] = get_strpath(self);
n = rb_scan_args(argc, argv, "03", &args[1], &args[2], &args[3]);
return rb_funcallv_kw(rb_cFile, id_binwrite, 1+n, args, RB_PASS_CALLED_KEYWORDS);
}
Writes contents to the file, opening it in binary mode.
See File.binwrite.
static VALUE
path_birthtime(VALUE self)
{
return rb_funcall(rb_cFile, id_birthtime, 1, get_strpath(self));
}
Returns the birth time for the file. If the platform doesn’t have birthtime, raises NotImplementedError.
See File.birthtime.
static VALUE
path_blockdev_p(VALUE self)
{
return rb_funcall(rb_mFileTest, id_blockdev_p, 1, get_strpath(self));
}
See FileTest.blockdev?.
static VALUE
path_chardev_p(VALUE self)
{
return rb_funcall(rb_mFileTest, id_chardev_p, 1, get_strpath(self));
}
See FileTest.chardev?.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 443
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 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.
static VALUE
path_chmod(VALUE self, VALUE mode)
{
return rb_funcall(rb_cFile, id_chmod, 2, mode, get_strpath(self));
}
Changes file permissions.
See File.chmod.
static VALUE
path_chown(VALUE self, VALUE owner, VALUE group)
{
return rb_funcall(rb_cFile, id_chown, 3, owner, group, get_strpath(self));
}
Change owner and group of the file.
See File.chown.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 92
def cleanpath(consider_symlink=false)
if consider_symlink
cleanpath_conservative
else
cleanpath_aggressive
end
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 Pathname#realpath.
static VALUE
path_ctime(VALUE self)
{
return rb_funcall(rb_cFile, id_ctime, 1, get_strpath(self));
}
Returns the last change time, using directory information, not the file itself.
See File.ctime.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 295
def descend
return to_enum(__method__) unless block_given?
vs = []
ascend {|v| vs << v }
vs.reverse_each {|v| yield v }
nil
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>
Returns an Enumerator if no block was given.
enum = Pathname.new("/usr/bin/ruby").descend
# ... do stuff ...
enum.each { |e| ... }
# yields Pathnames /, /usr, /usr/bin, and /usr/bin/ruby.
It doesn’t access the filesystem.
static VALUE
path_directory_p(VALUE self)
{
return rb_funcall(rb_mFileTest, id_directory_p, 1, get_strpath(self));
}
See FileTest.directory?.
static VALUE
path_dirname(VALUE self)
{
VALUE str = get_strpath(self);
str = rb_funcall(rb_cFile, id_dirname, 1, str);
return rb_class_new_instance(1, &str, rb_obj_class(self));
}
Returns all but the last component of the path.
See File.dirname.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 493
def each_child(with_directory=true, &b)
children(with_directory).each(&b)
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>
Note that the results never contain the entries . and .. in the directory because they are not children.
static VALUE
path_each_entry(VALUE self)
{
VALUE args[1];
args[0] = get_strpath(self);
return rb_block_call(rb_cDir, id_foreach, 1, args, each_entry_i, rb_obj_class(self));
}
Iterates over the entries (files and subdirectories) in the directory, yielding a Pathname object for each entry.
# File tmp/rubies/ruby-3.0.5/ext/pathname/lib/pathname.rb, line 263
def each_filename # :yield: filename
return to_enum(__method__) unless block_given?
_, names = split_names(@path)
names.each {|filename| yield filename }
nil
end
Iterates over each component of the path.
Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
# yields "usr", "bin", and "ruby".
Returns an Enumerator if no block was given.
enum = Pathname.new("/usr/bin/ruby").each_filename
# ... do stuff ...
enum.each { |e| ... }
# yields "usr", "bin", and "ruby".
static VALUE
path_each_line(int argc, VALUE *argv, VALUE self)
{
VALUE args[4];
int n;
args[0] = get_strpath(self);
n = rb_scan_args(argc, argv, "03", &args[1], &args[2], &args[3]);
if (rb_block_given_p()) {
return rb_block_call_kw(rb_cFile, id_foreach, 1+n, args, 0, 0, RB_PASS_CALLED_KEYWORDS);
}
else {
return rb_funcallv_kw(rb_cFile, id_foreach, 1+n, args, RB_PASS_CALLED_KEYWORDS);
}
}
Iterates over each line in the file and yields a String object for each.
static VALUE
path_empty_p(VALUE self)
{
VALUE path = get_strpath(self);
if (RTEST(rb_funcall(rb_mFileTest, id_directory_p, 1, path)))
return rb_funcall(rb_cDir, id_empty_p, 1, path);
else
return rb_funcall(rb_mFileTest, id_empty_p, 1, path);
}
Tests the file is empty.
See Dir#empty? and FileTest.empty?.
static VALUE
path_entries(VALUE self)
{
VALUE klass, str, ary;
long i;
klass = rb_obj_class(self);
str = get_strpath(self);
ary = rb_funcall(rb_cDir, id_entries, 1, str);
ary = rb_convert_type(ary, T_ARRAY, "Array", "to_ary");
for (i = 0; i < RARRAY_LEN(ary); i++) {
VALUE elt = RARRAY_AREF(ary, i);
elt = rb_class_new_instance(1, &elt, klass);
rb_ary_store(ary, i, elt);
}
return ary;
}
Return the entries (files and subdirectories) in the directory, each as a Pathname object.
The results contains just the names in the directory, without any trailing slashes or recursive look-up.
pp Pathname.new('/usr/local').entries #=> [#<Pathname:share>, # #<Pathname:lib>, # #<Pathname:..>, # #<Pathname:include>, # #<Pathname:etc>, # #<Pathname:bin>, # #<Pathname:man>, # #<Pathname:games>, # #<Pathname:.>, # #<Pathname:sbin>, # #<Pathname:src>]
The result may contain the current directory <.><..>