Project: Builder

Goal

Provide a simple way to create XML markup and data structures.

Classes

Builder::XmlMarkup

Generate XML markup notiation

Builder::XmlEvents

Generate XML events (i.e. SAX-like)

Notes

Usage

require 'rubygems'    
require_gem 'builder', '~> 3.0'

builder = Builder::XmlMarkup.new
xml = builder.person { |b| b.name("Jim"); b.phone("555-1234") }
xml #=> <person><name>Jim</name><phone>555-1234</phone></person>

or

require 'rubygems'    
require_gem 'builder'

builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
builder.person { |b| b.name("Jim"); b.phone("555-1234") }
#
# Prints:
# <person>
#   <name>Jim</name>
#   <phone>555-1234</phone>
# </person>

Compatibility

Version 3.0.0

Version 3 adds Ruby 1.9.2 compatibility.

Version 2.0.0 Compatibility Changes

Version 2.0.0 introduces automatically escaped attribute values for the first time. Versions prior to 2.0.0 did not insert escape characters into attribute values in the XML markup. This allowed attribute values to explicitly reference entities, which was occasionally used by a small number of developers. Since strings could always be explicitly escaped by hand, this was not a major restriction in functionality.

However, it did suprise most users of builder. Since the body text is normally escaped, everybody expected the attribute values to be escaped as well. Escaped attribute values were the number one support request on the 1.x Builder series.

Starting with Builder version 2.0.0, all attribute values expressed as strings will be processed and the appropriate characters will be escaped (e.g. “&” will be tranlated to “&amp;”). Attribute values that are expressed as Symbol values will not be processed for escaped characters and will be unchanged in output. (Yes, this probably counts as Symbol abuse, but the convention is convenient and flexible).

Example:

xml = Builder::XmlMarkup.new
xml.sample(:escaped=>"This&That", :unescaped=>:"Here&amp;There")
xml.target!  =>
  <sample escaped="This&amp;That" unescaped="Here&amp;There"/>

Version 1.0.0 Compatibility Changes

Version 1.0.0 introduces some changes that are not backwards compatible with earlier releases of builder. The main areas of incompatibility are:

Features

Contact

Author

Jim Weirich

Email

jim@weirichhouse.org

Home Page

onestepback.org

License

MIT Licence (www.opensource.org/licenses/mit-license.html)

[Validate]

Generated with the Darkfish Rdoc Generator 2.