The Basics

Serializing an object is to convert an object to a byte stream and either store that object for future loading, or sending to another program to be loaded there. There are several common ways to serialize objects in Ruby. The Marshal module is used less often than the other methods, but it's included in the standard library.

At the most basic level, marshaling an object can be as simple as saving an object to a file, and loading that object again the next time a script is run.

This can be particularly useful, as it's easy to save your program's state between executions.

First, saving (referred to as "dumping") an object. This is achieved by calling the Marshal::dump method. It takes a single argument, the object to be dumped. It returns a string, the serialized form of this object. Note that this string is not human-readable, it will contain non-ASCII characters. More on this aspect of Marshal later in the article.

Optionally, a second argument can be passed to Marshal::dump, an IO object (such as a file open for writing) for the object to be written to. If the serialized object is written to an IO object, it won't be returned as a string.

Next, loading an object. This is rather straightforward, Marshal::load takes an IO object as an argument and will load an object from the IO stream and return it. Optionally, if there are more than one marshaled objects in the IO object, you can pass a block to Marshal::load, which will be called for every marshaled object it finds in the IO.

The following code is a very simple example of how to use Marshal. At the beginning of the program, if a file called counter exists in the current directory, it will open it and load an object from it. This object will be a number, which will be incremented and then stored back in the file. This is a clone of a common "Hello World" PHP script, to implement a counter for a web page.

#!/usr/bin/env rubycounter = if File.exists?('counter') File.open('counter') do|file| Marshal.load(file) end else 0 endputs "Counter is currently at #{counter}"puts "incrementing to #{counter + 1}"counter += 1File.open('counter','w') do|file| Marshal.dump(counter, file)end

Marshal is not the perfect solution in all situations. It has a number of drawbacks and limitations.

Marshal stores objects in a binary format. This format is not transparent at all, only the Marshal code knows how to read and write this format. This means only Marshal should be reading and writing objects serialized with Marshal. The format is also subject to change, so even if you send a marshaled object to another program, it might not be able to read it.

This also means marshaled objects can't be edited by hand. Many people use things like YAML or XML for configuration files, simply unserializing them into their Ruby programs. This is not possible with Marshal, at least not without a separate script to unmarshal, allow editing, and re-marshal.

Not all objects can be marshaled. If the object to be marshaled contains a block, a binding (a reference to a particular part in a running Ruby program), or an IO object, it cannot be marshaled. Also, if an object contains singleton objects (objects whose type has been modified at runtime to add extra methods), it cannot be marshaled. You can get around this though, see the next page.

Before objects are marshaled, and after they've been loaded, Ruby will attempt to call marshal_dump and marshal_load on that object. This can be used to prevent unnecessary dumping of member variables, and to allow objects with un-marshalable objects to be marshaled. In the following example, a Log class stores the filename of a log file only. When it's unmarshaled, it will re-open this log file for appending.

#!/usr/bin/env rubyclass Logfile def initialize(filename) @filename = filename # This IO object can't be marshaled @io = File.open(filename,'w') end def marshal_dump log "Being marshaled" # Dump just the filename, leave the IO object alone @filename end def marshal_load(filename) @filename = filename @io = File.open(@filename, 'a'); log "Unmarshaled" end def log(message) @io.puts "#{Time.now}: #{message}" endendlogfile = if File.exists?('logfile') File.open('logfile') do|file| Marshal.load(file) end else Logfile.new('log.txt') endARGV.each do|message| logfile.log messageendFile.open('logfile','w') do|file| Marshal.dump(logfile, file)end