XML.com: Creating XML with Ruby and Builder

Creating XML with Ruby and Builder
by Michael Fitzgerald | Pages: 1, 2

Writing a Hash as XML Markup

Using Builder, the program favs.rb creates a hash called favorites and then writes it out as XML:

#!/usr/bin/ruby

require 'builder'

favorites = {
  'candy' => 'Neccos', 'novel' => 'Empire of the Sun', 'holiday' => 'Easter'
}

xml = Builder::XmlMarkup.new( :target => $stdout, :indent => 2 )

xml.instruct! :xml, :version => "1.1", :encoding => "US-ASCII"

xml.favorites do 
 favorites.each do | name, choice |
  xml.favorite( choice, :item => name )
 end
end

Run it with ruby favs.rb, or just as favs, and the output will be written as:

<?xml version="1.1" encoding="US-ASCII"?>
<favorites>
  <favorite item="candy">Neccos<favorite>
  <favorite item="holiday">Easter<favorite>
  <favorite item="novel">Empire of the Sun<favorite>
<favorites>

The top line of the code hints at where to find the Ruby interpreter (#!/usr/bin/ruby). The Builder library is loaded, and the favorites hash is defined with three name/value pairs. The Builder object xml is instantiated. The instruct! method creates an XML declaration with an explicit target and pseudo-attributes (although the document can pass as XML 1.0, I changed version to 1.1 in the method just to show how it is done).

A block is invoked on favorites (note that you can replace do-end with braces). For each pair in the hash, an element is written using the hash name as an attribute value, and the hash value (read in as the argument choice) as content for the element. As you can guess, using Builder in this way could help conveniently export large numbers of pairs to XML.

Creating a Valid XHTML Document

Finally, I'll touch on a few more methods and techniques for writing a valid XHTML document with Builder. Here is a program (xhtml.rb) that creates the document:

#!/usr/bin/ruby

require 'builder'

x = Builder::XmlMarkup.new(:target => $stdout, :indent => 1)

x.instruct!

x.declare! :DOCTYPE, :html, :PUBLIC, "-//W3C//DTD XHTML 1.0 Strict//EN", "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"

x.html( "xmlns" => "http://www.w3.org/1999/xhtml" ) { 

 x.head { 

  x.title "XHTML 1.0 example"  

  x.style( "type"=>text/css" ) { x.text! "h1 {font-family:tahoma,sans-serif;font-size:18pt;color:blue} body{font-family:georgia,serif}" 

  }

 }

 x.body {

  x.h1 "Hello from Builder"

  x.p "A Ruby library that facilitates the programatic generation of XML."

  x.p { |y| y <<"Methods of interest from <code<Builder::XmlMarkup</code> }

  x.ul {
    x.li "cdata!"
    x.li "comment!"
    x.li "declare!"
    x.li "instruct!"
    x.li "new"
  }

  x.p{ |y| y << "Methods of interest from "; x.code "Builder::XmlBase"; y << ":" }

  x.ul {
    x.li "<<"
    x.li "new"
    x.li "text!"
  }

 }

}

The declare! method produces a document type declaration for the strict XHTML 1.0 document type definition using symbols and strings. The style element specifies a type attribute and then uses the text! method to write a little CSS. This is an alternative to placing content in the first argument, as shown in this snippet:

x.style("h1 {font-family:tahoma,sans-serif;font-size:18pt;color:blue} body{font-
family:georgia,serif}", "type"=>"text/css" )

Probably the most interesting code are those lines that create paragraphs that have mixed content (embedded code elements with text). Both statements use the block argument |y| and then append text to it using the << method. The first one embeds tags in the text; the second creates the tag with code, separating statements with semicolons.

Builder is one of the most easy-to-use toolsets I've found to generate XML markup on the fly, in any language. Though I've only scratched the surface with some of its possible uses, I think, if you have been playing with the code along the way, you've got the basics down and you're ready to put Builder to work.