Ruby’s Pathname API

Ruby’s standard library is a treasure trove of useful classes, and the Pathname class is certainly one of them. Introduced in Ruby 1.9, Pathname represents a path on the file system, providing convenient access to functionality that is otherwise scattered across a handful of other classes like File, FileTest, and Dir.

Now that the life of Ruby 1.8 has officially come to an end, and 1.9 is nearing its fifth birthday, it’s high time to drop the legacy support and embrace the elegance and ease of use Pathname has to offer.

To show why Pathname was a much needed addition, let’s consider the more traditional way of manipulating path information. This is how we did things in the 1.8 days:

CONFIG_PATH = File.join(File.dirname(__FILE__), '..', 'config.yml')

Notice the use of class methods, a rare sight in a language where everything is an object. But what’s the alternative? The object-oriented thing-to-do would be to move the functionality closer to the data on which it operates. In this case, we’re simply manipulating strings, but it doesn’t really make sense to add join and dirname to String. A string is a far too generic a data type for such specific functionality.

Enter Pathname:

CONFIG_PATH = Pathname.new(__FILE__).dirname.join('..', 'config.yml')

By wrapping the string in a Pathname object, we get a clean API for manipulating the path. This code already looks a lot more like idiomatic Ruby. An important difference from Ruby’s vanilla strings is that Pathname instances are immutable. There are no methods that change the Pathname instance itself. Instead, all methods like dirname, join or basename return a new Pathname instance, leaving the existing instance unchanged.

The Pathname API

Methods on Pathname fall roughly into one of two categories: Either they simply manipulate the path string without accessing the file system, or they call out to the operating system to perform checks and operations on the file or directory itself. For the full list of eighty-something methods, you can check out the official Pathname API documentation. It’s worth noting that the docs are also available from a terminal through ri Pathname, or in irb with help 'Pathname'.

Let’s look at some methods you might find useful.

File Type and Permission Checks

pn = Pathname.new('/usr/bin/ruby')
pn.file?       # => true
pn.directory?  # => false

pn.absolute?   # => true
pn.relative?   # => false

pn.executable? # => true
pn.readable?   # => true
pn.writable?   # => false

pn.root?       # => false

Most of these correspond with methods on FileTest

File System Navigation and Querying

pn = Pathname.getwd # current working directory
pn.children   # => [ #<Pathname...>, ... ]
pn.each_child {|ch| ... }
pn = pn.parent

Pathname.glob('**/*.rb') # like Dir['**/*.rb'] but returns Pathnames

Pathname Manipulation

pn = Pathname.new('lib/mylib/awesome.rb')
pn.dirname                   # => #<Pathname:lib/mylib>
pn.basename                  # => #<Pathname:awesome.rb>
pn.extname                   # => ".rb"
pn.expand_path('/home/arne') # => #<Pathname:/home/arne/lib/mylib/awesome.rb>

Working with the Actual File

pn = Pathname.new(ENV['HOME']).join('.bashrc')
pn.size
pn.read
pn.open {|io| ... }
pn.each_line {|line| ... }
pn.rename('/tmp/foo')
pn.delete

Pathname() and to_path

There are two ways to create Pathname instances: through explicit construction as above, or through the Pathname() conversion method. While capitalized identifiers are typically reserved for classes and constants, Ruby has a number of built-in methods for converting arbitrary values to a specific type, named after the classes they convert to.

Array(1)                  # => [1]
Array(nil)                # => []
Array([1,2])              # => [1,2]
String(7)                 # => "7"
URI("http://example.com") # => #<URI::HTTP:0x1c0e URL:http://example.com>

These go hand in hand with a number of conversion hooks that objects can implement, like to_ary or to_str. Likewise, objects can implement to_path to indicate how they can be converted to a pathname. The pathname constructor is implemented in C for efficiency, but it would roughly translate to Ruby like this:

class Pathname
  def initialize(path)
    path = path.to_path if path.respond_to? :to_path
    @path = String(path)
  end
end

Say you are writing some scripts to help you manage your music collection. An AudioFile might look like this:

class AudioFile
  def initialize(path)
    @path = path
  end

  def to_path
    @path
  end

  # ...
end

Many built-in methods will wrap their file name arguments in a call to Pathname(), so you can pass in your AudioFile instance just the same.

af = AudioFile.new('...')
File.open(af) do |io|
  #...
end

When writing library code, reuse this pattern for maximum flexibility:

def read_configuration(config_file)
  parse_configuration(Pathname(config_file).read)
end

Now the caller of this code can pass in as config_file

• a string
• a Pathname
• an object that responds to to_path
• any object that can be converted with String()

Building a Music Collection Browser

To show how powerful and intuitive working with Pathname is, we’ll write a little API for browsing our music collection. The files are organized with songs grouped in directories per album, which are again grouped per artist. For example: ~/Music/Arsenal/Oyebo Soul/09_How Come.flacc.

We’re aiming for an easy to use API that looks like this:

mc = MusicCollection.new('~/Music') # => #<MusicCollection 'Music'>
mc.artists.first                    # => #<Artist 'Arsenal'>
mc.artists.first.albums.first       # => #<Album 'Oyebo Soul'>
mc.songs.count                      # => 120
mc.songs.first.path                 # => #<Pathname: ...>
mc.songs.first.play

The Song class is essentially our AudioFile class from above:

class Song
  attr_reader :path
  alias to_path path

  def initialize(path)
    @path = Pathname(path).expand_path
  end

  def name
    String(path.basename(path.extname))
  end

  def play(options = {})
    exec(options.fetch(:player, 'mplayer'), String(path))
    # OS X users can use player: '/usr/bin/afplay'
  end
end

We immediately call expand_path to normalize our input. This will expand ~ into the user’s home directory, and will resolve any relative file names (like . and ..). This way, we are sure to have an absolute file name.

Now we need to add classes for Album, Artist, and, finally, the MusicCollection itself. Since all of these are wrapper classes around a Pathname, we can pull the common plumbing into a base class.

class PathnameWrapper
  attr_reader :path
  alias to_path path

  def initialize(path)
    @path = Pathname(path).expand_path
  end

  def name
    # ...
  end

  def to_s
    # ...
  end
end

class Song < PathnameWrapper
  def play
    # ...
  end
end

Now we can add an Album and provide navigation methods back and forth. We will also add files and directories helpers to our base class, along with a to_proc class method. When passing in an object as a block with &, Ruby will use to_proc to find an implementation for the block. This way we get shorthand for typecasting all elements of a collection.

class PathnameWrapper
  # ...

  def directories
    path.children.select(&:directory?)
  end

  def files
    path.children.select(&:file?)
  end

  def self.to_proc
    ->(path) { new(path) }
  end
end

class Album < PathnameWrapper
  EXTENSIONS = %w[.flacc .m4a .mp3 .ogg .wav]

  def songs
    files.select do |file|
      EXTENSIONS.any? {|ext| ext == file.extname }
    end.map(&Song)
  end
end

class Song < PathnameWrapper
  # ...

  def album
    Album.new(path.dirname)
  end
end

To wrap things up we introduce Artist and MusicCollection.

class MusicCollection < PathnameWrapper
  def artists
    directories.map(&Artist)
  end

  def albums
    artists.flat_map(&:albums)
  end

  def songs
    albums.flat_map(&:songs)
  end
end

class Artist < PathnameWrapper
  def albums
    directories.map(&Album)
  end
end

class Album < PathnameWrapper
  # ...

  def artist
    Artist.new(path.dirname)
  end
end

class Song < PathnameWrapper
  # ...

  def artist
    album.artist
  end
end

Now we can browse back and forth between songs, albums, and artists.

This concludes the basics of our MusicCollection API, as well as our introduction to the Pathname class. Having a good grasp on Ruby’s standard library can help to make your code more elegant, correct, and concise. Here we’ve zoomed in on a single small component, highlighting its many uses. Go forward and use Pathname wisely.

Frequently Asked Questions (FAQs) about Ruby’s Pathname API