Dir

An object of class Dir represents a directory in the underlying file system.

It consists mainly of:

• A string path, given when the object is created, that specifies a directory in the underlying file system; method path returns the path.

• A collection of string entry names, each of which is the name of a directory or file in the underlying file system; the entry names may be retrieved in an array-like fashion or in a stream-like fashion.

About the Examples

Some examples on this page use this simple file tree:

example/
├── config.h
├── lib/
│   ├── song/
│   │   └── karaoke.rb
│   └── song.rb
└── main.rb

Others use the file tree for the Ruby project itself.

Dir As Array-Like

A Dir object is in some ways array-like:

• It has instance methods children, each, and each_child.

• It includes module Enumerable.

Dir As Stream-Like

A Dir object is in some ways stream-like.

The stream is initially open for reading, but may be closed manually (using method close), and will be closed on block exit if created by Dir.open called with a block. The closed stream may not be further manipulated, and may not be reopened.

The stream has a position, which is the index of an entry in the directory:

• The initial position is zero (before the first entry).

• Method tell (aliased as pos) returns the position.

• Method pos= sets the position (but ignores a value outside the stream), and returns the position.

• Method seek is like pos=, but returns self (convenient for chaining).

• Method read, if not at end-of-stream, reads the next entry and increments the position; if at end-of-stream, does not increment the position.

• Method rewind sets the position to zero.

Examples (using the simple file tree):

dir = Dir.new('example') # => #<Dir:example>
dir.pos                  # => 0

dir.read # => "."
dir.read # => ".."
dir.read # => "config.h"
dir.read # => "lib"
dir.read # => "main.rb"
dir.pos  # => 5
dir.read # => nil
dir.pos  # => 5

dir.rewind # => #<Dir:example>
dir.pos    # => 0

dir.pos = 3 # => 3
dir.pos     # => 3

dir.seek(4) # => #<Dir:example>
dir.pos     # => 4

dir.close # => nil
dir.read  # Raises IOError.

What’s Here

First, what’s elsewhere. Class Dir:

• Inherits from class Object.

• Includes module Enumerable, which provides dozens of additional methods.

Here, class Dir provides methods that are useful for:

• Reading

• Setting

• Querying

• Iterating

• Other

Reading

• close: Closes the directory stream for self.

• pos=: Sets the position in the directory stream for self.

• read: Reads and returns the next entry in the directory stream for self.

• rewind: Sets the position in the directory stream for self to the first entry.

• seek: Sets the position in the directory stream for self the entry at the given offset.

Setting

• ::chdir: Changes the working directory of the current process to the given directory.

• ::chroot: Changes the file-system root for the current process to the given directory.

Querying

• ::[]: Same as ::glob without the ability to pass flags.

• ::children: Returns an array of names of the children (both files and directories) of the given directory, but not including . or ...

• ::empty?: Returns whether the given path is an empty directory.

• ::entries: Returns an array of names of the children (both files and directories) of the given directory, including . and ...

• ::exist?: Returns whether the given path is a directory.

• ::getwd (aliased as pwd): Returns the path to the current working directory.

• ::glob: Returns an array of file paths matching the given pattern and flags.

• ::home: Returns the home directory path for a given user or the current user.

• children: Returns an array of names of the children (both files and directories) of self, but not including . or ...

• fileno: Returns the integer file descriptor for self.

• path (aliased as to_path): Returns the path used to create self.

• tell (aliased as pos): Returns the integer position in the directory stream for self.

Iterating

• ::each_child: Calls the given block with each entry in the given directory, but not including . or ...

• ::foreach: Calls the given block with each entry in the given directory, including . and ...

• each: Calls the given block with each entry in self, including . and ...

• each_child: Calls the given block with each entry in self, but not including . or ...

Other

• ::mkdir: Creates a directory at the given path, with optional permissions.

• ::new: Returns a new Dir for the given path, with optional encoding.

• ::open: Same as ::new, but if a block is given, yields the Dir to the block, closing it upon block exit.

• ::unlink (aliased as ::delete and ::rmdir): Removes the given directory.

• inspect: Returns a string description of self.