Pathname

Inheritance: < 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.

Examples

Example 1: Using Pathname

  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| _ }

Example 2: Using standard Ruby

  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| _ }

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. Except for mountpoint?, children, and realpath, they don‘t access the filesystem.

+
join
parent
root?
absolute?
relative?
relative_path_from
each_filename
cleanpath
realpath
children
mountpoint?

File status predicate methods

These methods are a facade for FileTest:

blockdev?
chardev?
directory?
executable?
executable_real?
exist?
file?
grpowned?
owned?
pipe?
readable?
world_readable?
readable_real?
setgid?
setuid?
size
size?
socket?
sticky?
symlink?
writable?
world_writable?
writable_real?
zero?

File property and manipulation methods

These methods are a facade for File:

atime
ctime
mtime
chmod(mode)
lchmod(mode)
chown(owner, group)
lchown(owner, group)
fnmatch(pattern, *args)
fnmatch?(pattern, *args)
ftype
make_link(old)
open(*args, &block)
readlink
rename(to)
stat
lstat
make_symlink(old)
truncate(length)
utime(atime, mtime)
basename(*args)
dirname
extname
expand_path(*args)
split

Directory methods

These methods are a facade for Dir:

Pathname.glob(*args)
Pathname.getwd / Pathname.pwd
rmdir
entries
each_entry(&block)
mkdir(*args)
opendir(*args)

IO

These methods are a facade for IO:

each_line(*args, &block)
read(*args)
readlines(*args)
sysopen(*args)

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.

Constants

Name		Description
SEPARATOR_PAT	= /[#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}]/
SEPARATOR_PAT	= /#{Regexp.quote File::SEPARATOR}/

Aliases

Method	Alias	Description
getwd	→ pwd

Methods

Class

Visibility	Signature
public	getwd ()
public	glob (*args) {\|p\| ...}
public	new (path)

Instance

Visibility	Signature
public	+ (other)
public	<=> (other)
public	== (other)
public	=== (other)
public	TO_PATH ()
public	absolute? ()
public	ascend () {\|self\| ...}
public	atime ()
public	basename (*args)
public	blockdev? ()
public	chardev? ()
public	chdir (&block)
public	children (with_directory=true)
public	chmod (mode)
public	chown (owner, group)
public	chroot ()
public	cleanpath (consider_symlink=false)
public	ctime ()
public	delete ()
public	descend () {\|v\| ...}
public	dir_foreach (*args, &block)
public	directory? ()
public	dirname ()
public	each_entry () {\|p\| ...}
public	each_filename ( {\|filename\| ...}
public	each_line (*args) {\|line\| ...}
public	entries ()
public	eql? (other)
public	executable? ()
public	executable_real? ()
public	exist? ()
public	expand_path (*args)
public	extname ()
public	file? ()
public	find () {\|p\| ...}
public	fnmatch (pattern, *args)
public	fnmatch? (pattern, *args)
public	foreach (*args, &block)
public	foreachline (*args, &block)
public	freeze ()
public	ftype ()
public	grpowned? ()
public	join (*args)
public	lchmod (mode)
public	lchown (owner, group)
public	link (old)
public	lstat ()
public	make_link (old)
public	make_symlink (old)
public	mkdir (*args)
public	mkpath ()
public	mountpoint? ()
public	mtime ()
public	open (*args) {\|file\| ...}
public	opendir () {\|dir\| ...}
public	owned? ()
public	parent ()
public	pipe? ()
public	read (*args)
public	readable? ()
public	readable_real? ()
public	readlines (*args)
public	readlink ()
public	realpath ()
public	relative? ()
public	relative_path_from (base_directory)
public	rename (to)
public	rmdir ()
public	rmtree ()
public	root? ()
public	setgid? ()
public	setuid? ()
public	size ()
public	size? ()
public	socket? ()
public	split ()
public	stat ()
public	sticky? ()
public	sub (pattern, *rest, &block)
public	symlink (old)
public	symlink? ()
public	sysopen (*args)
public	taint ()
public	to_s ()
public	truncate (length)
public	unlink ()
public	untaint ()
public	utime (atime, mtime)
public	world_readable? ()
public	world_writable? ()
public	writable? ()
public	writable_real? ()
public	zero? ()

Class Method Detail

getwd()

See Dir.getwd. Returns the current working directory as a Pathname.

glob(*args) {|p| ...}

See Dir.glob. Returns or yields Pathname objects.

new(path)

Create a Pathname object from the given String (or String-like object). If path contains a NUL character (\0), an ArgumentError is raised.

Instance Method Detail

+(other)

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.

<=>(other)

Provides for comparing pathnames, case-sensitively.

==(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.

===(other)

Alias for #==

TO_PATH()

Alias for to_s

absolute?()

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

ascend() {|self| ...}

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.

atime()

See File.atime. Returns last access time.

basename(*args)

See File.basename. Returns the last component of the path.

blockdev?()

See FileTest.blockdev?.

chardev?()

See FileTest.chardev?.

chdir(&block)

Pathname#chdir is obsoleted at 1.8.1.

children(with_directory=true)

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.

chmod(mode)

See File.chmod. Changes permissions.

chown(owner, group)

See File.chown. Change owner and group of file.

chroot()

Pathname#chroot is obsoleted at 1.8.1.

cleanpath(consider_symlink=false)

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.

ctime()

See File.ctime. Returns last (directory entry, not file) change time.

delete()

Alias for unlink

descend() {|v| ...}

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.

dir_foreach(*args, &block)

Pathname#dir_foreach is obsoleted at 1.8.1.

directory?()

See FileTest.directory?.

dirname()

See File.dirname. Returns all but the last component of the path.

each_entry() {|p| ...}

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.

each_filename( {|filename| ...}

Iterates over each component of the path.

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

each_line(*args) {|line| ...}

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.

entries()

Return the entries (files and subdirectories) in the directory, each as a Pathname object.

eql?(other)

Alias for #==

executable?()

See FileTest.executable?.

executable_real?()

See FileTest.executable_real?.

exist?()

See FileTest.exist?.

expand_path(*args)

See File.expand_path.

extname()

See File.extname. Returns the file‘s extension.

file?()

See FileTest.file?.

find() {|p| ...}

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 ./.

fnmatch(pattern, *args)

See File.fnmatch. Return true if the receiver matches the given pattern.

fnmatch?(pattern, *args)

See File.fnmatch? (same as fnmatch).

foreach(*args, &block)

This method is obsoleted at 1.8.1. Use each_line or each_entry.

foreachline(*args, &block)

Pathname#foreachline is obsoleted at 1.8.1. Use each_line.

freeze()

ftype()

See File.ftype. Returns "type" of file ("file", "directory", etc).

grpowned?()

See FileTest.grpowned?.

join(*args)

Pathname#join joins pathnames.

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

lchmod(mode)

See File.lchmod.

lchown(owner, group)

See File.lchown.

link(old)

Pathname#link is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

lstat()

See File.lstat.

make_link(old)

See File.link. Creates a hard link.

make_symlink(old)

See File.symlink. Creates a symbolic link.

mkdir(*args)

See Dir.mkdir. Create the referenced directory.

mkpath()

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

mountpoint?()

mountpoint? returns true if self points to a mountpoint.

mtime()

See File.mtime. Returns last modification time.

open(*args) {|file| ...}

See File.open. Opens the file for reading or writing.

opendir() {|dir| ...}

See Dir.open.

owned?()

See FileTest.owned?.

parent()

parent returns the parent directory.

This is same as self + ’..’.

pipe?()

See FileTest.pipe?.

read(*args)

See IO.read. Returns all the bytes from the file, or the first N if specified.

readable?()

See FileTest.readable?.

readable_real?()

See FileTest.readable_real?.

readlines(*args)

See IO.readlines. Returns all the lines from the file.

readlink()

See File.readlink. Read symbolic link.

realpath()

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.

relative?()

The opposite of absolute?

relative_path_from(base_directory)

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.

rename(to)

See File.rename. Rename the file.

rmdir()

See Dir.rmdir. Remove the referenced directory.

rmtree()

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

root?()

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/...

setgid?()

See FileTest.setgid?.

setuid?()

See FileTest.setuid?.

size()

See FileTest.size.

size?()

See FileTest.size?.

socket?()

See FileTest.socket?.

split()

See File.split. Returns the dirname and the basename in an Array.

stat()

See File.stat. Returns a File::Stat object.

sticky?()

See FileTest.sticky?.

sub(pattern, *rest, &block)

Return a pathname which is substituted by String#sub.

symlink(old)

Pathname#symlink is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

symlink?()

See FileTest.symlink?.

sysopen(*args)

See IO.sysopen.

taint()

to_s()

Return the path as a String.

truncate(length)

See File.truncate. Truncate the file to length bytes.

unlink()

Removes a file or directory, using File.unlink or Dir.unlink as necessary.

untaint()

utime(atime, mtime)

See File.utime. Update the access and modification times.

world_readable?()

See FileTest.world_readable?.

world_writable?()

See FileTest.world_writable?.

writable?()

See FileTest.writable?.

writable_real?()

See FileTest.writable_real?.

zero?()

See FileTest.zero?.