At some point, you will want your Ruby programs to talk to other programs. Usually, if your program is talking to another program, communication between them is done through an Application Programming Interface or API. Don't let that article scare you. An API is just a generic term for any interface which allows one program to either read data from another program or write data to another program. Or both!

One of the simplest interfaces two Ruby programs can share is a file. The first program will transform some of its objects into a string and then write those strings to a file. The second program will look for the file in a shared location (this is particularly easy if both programs are running on the same computer), read it, and turn the strings in the file back into Ruby objects. Take a look back at the Ruby Primer's I/O chapter if you need a refresher on Ruby's file libraries.

This basic concept (transferring data between programs) is essentially what we're referring to when we say "serializing". By turning our Ruby objects into strings we have made them serial: the objects are all lumped together as a string of chracters, one character after another. We've actually covered one method of serialization already: Object#to_s. In the exercise below, try to write a to_s method that produces a string from_s understands.

class CerealBox attr_accessor :ounces, :contains_toy def initialize(ounces, contains_toy) @ounces = ounces @contains_toy = contains_toy end def self.from_s(s) ounces = 0 contains_toy = false s.each_line do |field| value = field.split(":")[1].strip ounces = value.to_i if field.include?("ounces") contains_toy = to_boolean(value) if field.include?("contains_toy") end CerealBox.new(ounces, contains_toy) end def self.to_boolean(str) str == 'true' end def to_s "@ounces = #{@ounces}, @contains_toy = #{@contains_toy}" end end puts "example to_s: #{CerealBox.new(4, true).to_s}" # try this too! #puts "example from_s: #{CerealBox.from_s(CerealBox.new(10, false).to_s)}"

[reset] Need a hint? See the Solution

Hint

Note that `from_s` is using the `each_line` method. To insert a newline within a string, use the '\n' character literal.

Output Window

While that strategy does work, it's quite cumbersome. The from_s method is big, ugly, and fragile. Try sending it some invalid values! It won't be very happy. It's also not very generic; we would have to write a custom from_s method for every new class. Ugh! Let's not even think about that. Instead, let's move on to Ruby's built-in solution to this problem.

We want some way of automatically transforming any Ruby object into a serialized form. There are a number of serialization formats we could use. You may have heard of XML, json, or YAML. Ruby can produce any of these formats (they're all strings, by the way) but we'll specifically take a look at YAML since it's built right into the Ruby language. Here, YAML::dump and YAML::load do all the heavy lifting for us.

Example Code:

class Ogre def initialize(strength, speed) @strength = strength @speed = speed end # this is reminiscent of our old friend, CerealBox#from_s def self.deserialize(yaml_string) YAML::load(yaml_string) end # and this is a much-simplified version of our CerealBox#to_s def serialize YAML::dump(self) end # now we're free to define #to_s however we like! # ...which is great, because #to_s is for programmers to read, # not computers or users def to_s "Ogre: [strength = #{@strength}, speed = #{@speed}]" end end wendigo = Ogre.new(47, 3) yaml = wendigo.serialize puts "The yaml looks like this:" p yaml puts "It's just a boring old string: #{yaml.class}" puts "...and it's easy to change back: #{Ogre.deserialize(yaml)}" puts shrek = Ogre.new(62, 12) fiona = Ogre.new(66, 37) ogres = [shrek, fiona] puts "We can even serialize arrays! They're just another object. #{ogres}"

[reset] Need a hint? See the Solution

Hint

Output Window

Super cool, right? Much easier than the hand-made solution.

As you've probably noticed by now, the concept of transferring data between programs isn't limited to two different programs. The examples above were reading and writing their own serialized formats. Philosophically, if we write some Ruby objects to a file, close our program, then open our program later and read those same objects back, we're really transferring data between two programs: our program at time T and our program at time T+n... in the future! This is nothing special, really. It's the way your wordprocessor opens on Thursday a file you created on Monday. But it sounds fancier this way.

Let's use this concept to extend our Ogre example. As you could see from the Ogre class, YAML understands any Ruby object you throw at it. This means we don't need to put the YAML method calls in the Ogre class itself -- interacting with YAML can happen at a much higher level, like our save_game method below. Finish the exercise so that the game characters can be saved to disk and loaded later. To save a YAML string to disk, use the handy GameFile#write(yaml) and GameFile#read methods I've written for you. GameFile.new accepts one parameter, which should be a .yaml file.

class Ogre attr_accessor :strength, :speed, :smell def initialize(strength, speed, smell) @strength = strength @speed = speed @smell = smell end end class Dragon attr_accessor :strength, :speed, :color def initialize(strength, speed, color) @strength = strength @speed = speed @color = color end end class Fairy attr_accessor :strength, :speed, :intelligence def initialize(intelligence) @strength = 1 @speed = 42 @intelligence = intelligence end end def save_game(characters) # TODO: serialize a character hash of :ogres, :dragons, and :fairies end def load_game # TODO: return a deserialized hash of characters end

[reset] Need a hint? See the Solution

Hint

`GameFile.new(file)` will need to access the same file in both `save_game` and `load_game`.

Output Window