class Pathname

pathname.rb

Object-Oriented Pathname Class

Author

Tanaka Akira <akr@m17n.org>

Documentation

Author and Gavin Sinclair

For documentation, see class Pathname.

A Pathname object contains a string directory path or filepath; it does not represent a corresponding actual file or directory – which in fact may or may not exist.

A Pathname object is immutable (except for method freeze).

A pathname may be relative or absolute:

Pathname.new('lib')            # => #<Pathname:lib>
Pathname.new('/usr/local/bin') # => #<Pathname:/usr/local/bin>

About the Examples

Many examples here use these variables:

# English text with newlines.
text = <<~EOT
  First line
  Second line

  Fourth line
  Fifth line
EOT

# Japanese text.
japanese = 'こんにちは'

# Binary data.
data = "\u9990\u9991\u9992\u9993\u9994"

# Text file.
File.write('t.txt', text)

# File with Japanese text.
File.write('t.ja', japanese)

# File with binary data.
f = File.new('t.dat', 'wb:UTF-16')
f.write(data)
f.close

Convenience Methods

The class provides all functionality from class File and module FileTest, along with some functionality from class Dir and module FileUtils.

Here’s an example string path and corresponding Pathname object:

path = 'lib/fileutils.rb'
pn = Pathname.new(path) # => #<Pathname:lib/fileutils.rb>

Each of these method pairs (Pathname vs. File) gives exactly the same result:

pn.size               # => 83777
File.size(path)       # => 83777

pn.directory?         # => false
File.directory?(path) # => false

pn.read.size          # => 81074
File.read(path).size# # => 81074

Each of these method pairs gives similar results, but each Pathname method returns a more versatile Pathname object, instead of a string:

pn.dirname          # => #<Pathname:lib>
File.dirname(path)  # => "lib"

pn.basename         # => #<Pathname:fileutils.rb>
File.basename(path) # => "fileutils.rb"

pn.split            # => [#<Pathname:lib>, #<Pathname:fileutils.rb>]
File.split(path)    # => ["lib", "fileutils.rb"]

Each of these methods takes a block:

pn.open do |file|
  p file
end
File.open(path) do |file|
  p file
end

The outputs for each:

#<File:lib/fileutils.rb (closed)>
#<File:lib/fileutils.rb (closed)>

Each of these methods takes a block:

pn.each_line do |line|
  p line
  break
end
File.foreach(path) do |line|
  p line
  break
end

The outputs for each:

"# frozen_string_literal: true\n"
"# frozen_string_literal: true\n"

More Methods

Here is a sampling of other available methods:

p1 = Pathname.new('/usr/lib')  # => #<Pathname:/usr/lib>
p1.absolute?                   # => true
p2 = p1 + 'ruby/4.0'           # => #<Pathname:/usr/lib/ruby/4.0>
p3 = p1.parent                 # => #<Pathname:/usr>
p4 = p2.relative_path_from(p3) # => #<Pathname:lib/ruby/4.0>
p4.absolute?                   # => false
p5 = Pathname.new('.')         # => #<Pathname:.>
p6 = p5 + 'usr/../var'         # => #<Pathname:usr/../var>
p6.cleanpath                   # => #<Pathname:var>
p6.realpath                    # => #<Pathname:/var>
p6.children.take(2)
# => [#<Pathname:usr/../var/local>, #<Pathname:usr/../var/spool>]

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:

Directory methods

These methods are a facade for Dir:

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

VERSION

The version string.