YAML.rb includes a stream parser, which can read YAML from strings, files, and any type of IO. You can use YAML::load to read single documents, YAML::load_stream to read several documents at once, and YAML::load_documents to iterate through documents in a stream.

Loading a single document

Often you will want to load a single document, representing a single object, into a Ruby variable. The YAML::load method is designed to do just that. It takes either a String or an IO object and returns the first object in the document.

readme = YAML::load( File.open( 'README' ) )

Ex. 37: YAML::load Example

YAML::load is a very convenient function, as you can manipulate the YAML structure as a Ruby type. It flexes YAML's strength as a data serialization language. While an Object's to_yaml method exports it to YAML, the YAML::load method imports the Object back.

A YAML stream can contain more than one document. Often, you won't want to load the entire stream into memory. Rather, you'll want to load one document at a time. In Ruby, we use the YAML::load_documents method to iterate through documents.

For example, suppose we have a web server's log file, which is made up of several YAML documents in a stream:

Like YAML::load, YAML::load_documents is called with the IO object or String that you want to read from. You also must pass YAML::load_documents a Ruby proc for handling each document. The proc only receives one parameter: the current YAML document, loaded as a Ruby object. In the example above, we receive a Hash object for each document in the stream.

YAML::load_documents is the most efficient way to load streaming data. This applies as well to TCP sockets. Client/server applications which communcate in YAML can pass the TCPSocket object directly to YAML::load_documents for parsing a stream over TCP/IP.

Loading an entire stream

In some situations, you may choose to load an entire stream for modification and re-emission. The YAML::Stream object can hold many documents and contains a few function to add convenience to editing documents in the stream. To load an entire stream into a YAML::Stream object, use the YAML::load_stream method.

Like the other YAML load functions, YAML::load_stream requires an IO object or String as its parameter: