Ruby is a one of the most popular languages used on the web. We’ve recently started a new Session here on Nettuts+ that will introduce you to Ruby, as well as the great frameworks and tools that go along with Ruby development. Today, we’ll look at the Dir and File classes, and how we can use them to work with directories and files.

View Screencast

Directories

pwd

If you’ve done much work with the terminal (AKA command line, AKA shell), you’ll know that it has the notion of a current directory, called the working directory. This is the folder you are currently in. Whenever you type a command that uses a file, the working directory will be the first place your shell looks to find the file.

Ruby has a similar notion when executing code. It understands the OS’s folder structure, and has some helpful tools for working with it.

So, how do you find out what folder you’re ruby script thinks it is in?

Dir.pwd # "/Users/andrew/Documents" 

The pwd (print working directory) method on the Dir class gives us that information. If you’re in irb, your working directory will be—by default—the folder you started irb in. If you’re in a script, will be the location you’re calling the script from.

chdir

If you want to change the working directory, you can use the chdir method; pass it the path to the directory you want to move to:

Dir.chdir "Documents"

Dir.chdir "/users/andrew/Documents"

As you can see, the string parameter can be either an absolute or a relative path.

glob

If you’re looking for certain files within the working directory (Dir.pwd), you can get them by using the Dir.glob method. Pass that method a “glob”; that’s a search pattern that’s somewhere between a static string and a full regular expression. You can use an asterisk * as a wildcard, just as you might in the shell; you can use a double asterisk ** to match directories recursively. You can also use sets in square brackets as you would with regular expressions. If you need more, check out the full docs. Dir.glob with return an array … or, you can pass it a block and get each match one by on.

# Remember, this runs on the current directory
all_text_files = Dir.glob "*.txt"

Dir.glob("**/*.[a-z]") do |filename|
    # will match any file in any child directory with a single lower-case letter extension
end

new & open

Besides housing useful functions, you can also make an instance of the Dir class. You pass it the name of the directory you want to use; as with all functions that take a path, it can be absolute or relative.

reciepts = Dir.new "reciepts"
me = Dir.open "/users/andrew"

Both new and open return a Dir object; however, there’s another way to use open:

Dir.open "/users/andrew" do |dir|
    # use it here
end

This is a common convention with many classes in Ruby; instead of storing the Dir object in a variable, you can pass it to a block and use it from in there. It’s a pretty different style of coding that I haven’t seen in any other language, but it’s rather nice only you get used to it.

There’s a good chance that when you create a Dir object, you’ll want to work with the contents of it. There are a few ways to do that.

each

Assuming some_dir is Dir object,

some_dir.each do |file|
    # do something
end

You can use the each method on Dir objects to iterate over each file or directory that is inside it. Note that you’re not getting a File or Dir object; just a string with the name of it; if you want to do more, you’ll have to instantiate the appropriate object yourself.

entries

If you just want to see what’s inside a directory, you can use the entries property, to get an array of the contents:

some_dir.entries # [ ".", "..", "file_one.txt", "another_directory"]

As you’ll note above, the entires for a directory include ”.” and “..”, pointer it itself and its parent directory.

Files

Ruby also offers a helpful API for working with files.

absolute_path

When you’re working with files, you may find yourself wanting to get the absolute path of one. The File class offers exactly what you need:

File.absotule_path "plans.txt" # => "/users/andrew/Documents/plans.txt"

basename

But what about the other way around? You’ve got the absolute path, and you want just the filename? Instead, use basename

File.basename("/users/andrew/Documents/plans.txt") # => "plans.txt"

File.basename("/users/andrew/Documents/plans.txt", ".txt") # => "plans"

If you pass a second string parameter, the method will look for that string at the end of the file name, and remove it if it is there; this doesn’t have to be the file extension, but that’s the obvious main use for this.

delete

The obvious use of this is to delete the file you pass into the method:

File.delete "code.rb"

directory?

This is a useful one; say you’re each-ing over the entries of a Dir object, but you only want to deal with files. The File.directory? method will return true if the string parameter you pass to it is a directory, and false if it’s a file.

Dir.open(Dir.pwd).each do |filename|
    next if File.directory? filename

    # otherwise, process file
end

This snippet opens the current directory and passes a block to the each method. The each method passes the entries of directory one by one to the block. That first line inside the block may confuse you a bit if you’re not used to Ruby, but look at it carefully. The only part you aren’t familiar with is the next keyword, which skips the rest of the block and goes to the next iteration of it. So, we’re saying, “skip to the next entry if the entry we currently have is a directory. If it’s not a directory, we can do whatever we want to.

new & open

Making instances of the File class works just the same as with Dir; File.new returns a File object, while File.open can return it, or pass it to a block. You should also pass a second parameter, which decides how the file will be opened. Most of the time, you’ll probably use these:

• ”r” : read-only
• ”w” : write-only (overwrites anything in the file, if the file exists)
• “w+” : read and write (overwrites anything in the file, if the file exists)
• ”a” : write-only (starts at the end of the file, if the file exists)

So, what methods does an instance of File give you? Well, these methods actually come from the IO class, from which File inherits. Most of the time, you’ll be opening a file to read or write content from it, so let’s look at that functionality.

Reading

Before we get started, remember this: the way a file works, once a line has been read, it doens’t show up again; you’re working your way through the file. At any point, you can use the f.rewind method to go back to the beginning of the file.

If you want to just read the whole thing, you can do so with read.

f = File.open("sample.txt", "r") # assume this file for the next couple of snippets

f.read # => "something\nline 2\na third\nfour!\n5555\nsixy\nsevenly\neight" 

However, you’ll probably want to read one line at a time; to do that, use the method readline:

f.rewind # back at the beginning

f.readline # "something\n"

f.readline # "line 2\n"

f.readline # "a third\n"

You could also use the method gets instead of readline.

There’s also a readlines method, which returns an array in which the lines as entries:

f.rewind

f.readlines # => ["something\n", "line 2\n", "a third\n", "four!\n", "5555\n", "sixy\n", "sevenly\n", "eight"] 

Finally, you can use each, and pass a block to the method to work with each line, one by one

f.rewind

f.each do |line|
    puts line
end

Writing

For writing, you’ve got two options: write and puts. The main difference is that puts adds a line break to the end of your string, while write does not.

f = File.open("file.txt", "w+")

f.puts "first line"
f.write "second "
f.write "line"

f.rewind

f.readlines # => ["first line\n", "second line"]

Question for You

Well, that’s it for Ruby For Newbies, Lesson 7. There’s more to discover in the Dir and File classes; check out the docs for Dir, File, and IO for more (the IO class is where File inherits its instance methods from).

However, I’m curious about where you want this series to go from here: do you want to continue with the Ruby language, or do you want to move towards using Ruby on the web? Both directions will be valuable to you as a web developer, so voice your opinion in the comments!