One of the most common kinds of IO is the reading and writing of files. The File class defines some utility methods (described below) that read the entire contents of a file with one call. Often, however, you will instead open a file to obtain a File object and then use IO methods to read from or write to the file.

Use File.open (or File.new) to open a file. The first argument is the name of the file. This is usually specified as a string, but in Ruby 1.9, you can use any object with a to_path method. Filenames are interpreted relative to the current working directory unless they are specified with an absolute path. Use forward slash characters to separate directories—Ruby automatically converts them into backslashes on Windows. The second argument to File.open is a short string that specifies how the file should be opened:

f = File.open("data.txt", "r")   # Open file data.txt for reading
out = File.open("out.txt", "w")  # Open file out.txt for writing

The second argument to File.open is a string that specifies the “file mode.” It must begin with one of the values in the following table. Add "b" to the mode string to prevent automatic line terminator conversion on Windows platforms. For text files, you may add the name of a character encoding to the mode string. For binary files, you should add ":binary" to the string. This is explained in Streams and Encodings.

File.open (but not File.new) may be followed by a block. If a block is provided, then File.open doesn’t return the File object but instead passes it to the block, and automatically closes it when the block exits. The return value of the block becomes the return value of File.open:

File.open("log.txt", "a") do |log|      # Open for appending
  log.puts("INFO: Logging a message")   # Output to the file
end                                     # Automatically closed

The Kernel method open works like File.open but is more flexible. If the filename begins with |, it is treated as an operating system command, and the returned stream is used for reading from and writing to that command process. This is platform-dependent, of course:

# How long has the server been up?
uptime = open("|uptime") {|f| f.gets }

If the open-uri library has been loaded, then open can also be used to read from http and ftp URLs as if they were files:

require "open-uri"                         # Required library
f = open("http://www.davidflanagan.com/")  # Webpage as a file
webpage = f.read                           # Read it as one big string
f.close                                    # Don't forget to close!

In Ruby 1.9, if the argument to open has a method named to_open, then that method is called and should return an opened IO object.

Another way to obtain an IO object is to use the stringio library to read from or write to a string:

require "stringio"
input = StringIO.open("now is the time")  # Read from this string
buffer = ""
output = StringIO.open(buffer, "w")       # Write into buffer

The StringIO class is not a subclass of IO, but it defines many of the same methods as IO does, and duck typing usually allows us to use a StringIO object in place of an IO object.

Ruby predefines a number of streams that can be used without being created or opened. The global constants STDIN, STDOUT, and STDERR are the standard input stream, the standard output stream, and the standard error stream, respectively. By default, these streams are connected to the user’s console or a terminal window of some sort. Depending on how your Ruby script is invoked, they may instead use a file, or even another process, as a source of input or a destination for output. Any Ruby program can read from standard input and write to standard output (for normal program output) or standard error (for error messages that should be seen even if the standard output is redirected to a file). The global variables $stdin, $stdout, and $stderr are initially set to the same values as the stream constants. Global functions like print and puts write to $stdout by default. If a script alters the value of this global variable, it will change the behavior of those methods. The true “standard output” will still be available through STDOUT, however.

Another predefined stream is ARGF, or $<. This stream has special behavior intended to make it simple to write scripts that read the files specified on the command line or from standard input. If there are command-line arguments to the Ruby script (in the ARGV or $* array), then the ARGF stream acts as if those files had been concatenated together and the single resulting file opened for reading. In order for this to work properly, a Ruby script that accepts command-line options other than filenames must first process those options and remove them from the ARGV array. If the ARGV array is empty, then ARGF is the same as STDIN. (See Input Functions for further details about the ARGF stream.)

Finally, the DATA stream is designed for reading text that appears after the end of your Ruby script. This works only if your script includes the token __END__ on a line by itself. That token marks the end of the program text. Any lines after the token may be read with the DATA stream.

IO defines a number of ways to read lines from a stream:

lines = ARGF.readlines         # Read all input, return an array of lines
line = DATA.readline           # Read one line from stream
print l while l = DATA.gets    # Read until gets returns nil, at EOF
DATA.each {|line| print line } # Iterate lines from stream until EOF
DATA.each_line                 # An alias for each
DATA.lines                     # An enumerator for each_line: Ruby 1.9

Here are some important notes on these line-reading methods. First, the readline and the gets method differ only in their handling of EOF (end-of-file: the condition that occurs when there is no more to read from a stream). gets returns nil if it is invoked on a stream at EOF. readline instead raises an EOFError. If you do not know how many lines to expect, use gets. If you expect another line (and it is an error if it is not there), then use readline. You can check whether a stream is already at EOF with the eof? method.

Second, gets and readline implicitly set the global variable $_ to the line of text they return. A number of global methods, such as print, use $_ if they are not explicitly passed an argument. Therefore, the while loop in the code above could be written more succinctly as:

print while DATA.gets

Relying on $_ is useful for short scripts, but in longer programs, it is better style to explicitly use variables to store the lines of input you’ve read.

Third, these methods are typically used for text (instead of binary) streams, and a “line” is defined as a sequence of bytes up to and including the default line terminator (newline on most platforms). The lines returned by these methods include the line terminator (although the last line in a file may not have one). Use String.chomp! to strip it off. The special global variable $/ holds the line terminator. You can set $/ to alter the default behavior of all the line-reading methods, or you can simply pass an alternate separator to any of the methods (including the each iterator). You might do this when reading comma-separated fields from a file, for example, or when reading a binary file that has some kind of “record separator” character. There are two special cases for the line terminator. If you specify nil, then the line-reading methods keep reading until EOF and return the entire contents of the stream as a single line. If you specify the empty string “” as the line terminator, then the line-reading methods read a paragraph at a time, looking for a blank line as the separator.

In Ruby 1.9, gets and readline accept an optional integer as the first argument or as the second after a separator string. If specified, this integer specifies the maximum number of bytes to read from the stream. This limit argument exists to prevent accidental reads of unexpectedly long lines, and these methods are exceptions to the previously cited rule; they return encoded character strings despite the fact that they have a limit argument measured in bytes.

Finally, the line-reading methods gets, readline, and the each iterator (and its each_line alias) keep track of the number of lines they’ve read. You can query the line number of the most recently read line with the lineno method, and you can set that line number with lineno= accessor. Note that lineno does not actually count the number of newlines in a file. It counts the number of times line-reading methods have been called, and may return different results if you use different line separator characters:

DATA.lineno = 0     # Start from line 0, even though data is at end of file
DATA.readline       # Read one line of data
DATA.lineno         # => 1
$.                  # => 1: magic global variable, implicitly set

IO defines three class methods for reading files without ever opening an IO stream. IO.read reads an entire file (or a portion of a file) and returns it as a single string. IO.readlines reads an entire named file into an array of lines. And IO.foreach iterates over the lines of a named file. In Ruby 1.9, you can pass a hash to these methods to specify the mode string and/or encoding of the file being read:

data = IO.read("data")                    # Read and return the entire file
data = IO.read("data", mode:"rb")         # Open with mode string "rb"
data = IO.read("data", encoding:"binary") # Read unencoded bytes
data = IO.read("data", 4, 2)              # Read 4 bytes starting at byte 2
data = IO.read("data", nil, 6)            # Read from byte 6 to end-of-file

# Read lines into an array
words = IO.readlines("/usr/share/dict/words")

# Read lines one at a time and initialize a hash
words = {}
IO.foreach("/usr/share/dict/words") {|w| words[w] = true}

In Ruby 1.9 you can use IO.copy_stream to read a file (or a portion) and write its content to a stream:

IO.copy_stream("/usr/share/dict/words", STDOUT) # Print the dictionary
IO.copy_stream("/usr/share/dict/words", STDOUT, 10, 100) # Print bytes 100-109

Although these class methods are defined by the IO class, they operate on named files, and it is also common to see them invoked as class methods of File: File.read, File.readlines, File.foreach, and File.copy_stream.

The IO class also defines an instance method named read, which is similar to the class method with the same name; with no arguments it reads text until the end of the stream and returns it as an encoded string:

# An alternative to text = File.read("data.txt")
f = File.open("data.txt")  # Open a file
text = f.read              # Read its contents as text
f.close                    # Close the file

The IO.read instance method can also be used with arguments to read a specified number of bytes from the stream. That use is described in the next section.

The IO class also defines methods for reading a stream one or more bytes or characters at a time, but these methods have changed substantially between Ruby 1.8 and Ruby 1.9 because Ruby’s definition of a character has changed.

In Ruby 1.8, bytes and characters are the same thing, and the getc and readchar methods read a single byte and return it as a Fixnum. Like gets, getc returns nil at EOF. And like readline, readchar raises EOFError if it is called at EOF.

In Ruby 1.9, getc and readchar have been modified to return a string of length 1 instead of a Fixnum. When reading from a stream with a multibyte encoding, these methods read as many bytes as necessary to read a complete character. If you want to read a string a byte at a time in Ruby 1.9, use the new methods getbyte and readbyte. getbyte is like getc and gets: it returns nil at EOF. And readbyte is like readchar and readline: it raises EOFError.

Programs (like parsers) that read a stream one character at a time sometimes need to push a single character back into the stream’s buffer, so that it will be returned by the next read call. They can do this with ungetc. This method expects a Fixnum in Ruby 1.8 and a single character string in Ruby 1.9. The character pushed back will be returned by the next call to getc or readchar:

f = File.open("data", "r:binary") # Open data file for binary reads 
c = f.getc                        # Read the first byte as an integer
f.ungetc(c)                       # Push that byte back
c = f.readchar                    # Read it back again

You can also iterate and enumerate the characters and bytes of a stream:

f.each_byte {|b| ... }      # Iterate through remaining bytes
f.bytes                     # An enumerator for each_byte: Ruby 1.9
f.each_char {|c} ...}       # Iterate characters: Ruby 1.9
f.chars                     # An enumerator for each_char: Ruby 1.9  

If you want to read more than one byte at a time, you have a choice of five methods, each with slightly different behavior:

Here is some example code you might use when reading a binary file:

f = File.open("data.bin", "rb:binary")  # No newline conversion, no encoding
magic = f.readbytes(4)       # First four bytes identify filetype
exit unless magic == "INTS"  # Magic number spells "INTS" (ASCII)
bytes = f.read               # Read the rest of the file
                             # Encoding is binary, so this is a byte string
data = bytes.unpack("i*")    # Convert bytes to an array of integers