Pathname

Pathname

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 <a href="/ruby/Pathname">Pathname</a>

  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:

• #find(&block)
• #mkpath
• #rmtree
• #unlink / #delete

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?&quot;, 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.