Builder Ruby Library

Starting with version 2.0.0, all attribute values passed as Strings are automatically escaped (e.g., & becomes &).

If you need to include unescaped entities in an attribute value, pass the value as a Symbol instead of a String. This bypasses the escaping algorithm.

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

Builder provides two primary ways to generate XML:

1. Builder::XmlMarkup: Generates XML markup notation (the most common usage).
2. Builder::XmlEvents: Generates XML events (SAX-like).

When using XmlMarkup, nested tags must be called on the builder object itself. When using blocks, the builder object is passed as a parameter to the block, allowing you to use a short alias for nested markup.

xml_markup = Builder::XmlMarkup.new
# You must explicitly call the builder for nested tags:
xml_markup.div { |xml| xml.strong("text") }

To ensure Builder correctly translates UTF-8 characters into valid XML without encoding non-ASCII characters as entities, set the $KCODE variable to 'UTF8' and ensure the XML encoding is set to 'UTF-8' via instruct!.

$KCODE = 'UTF8'
xml = Builder::XmlMarkup.new
xml.instruct!(:xml, :encoding => "UTF-8")
xml.sample("Iñtërnâtiônàl")
# => "<sample>Iñtërnâtiônàl</sample>"

To use Builder to generate XML markup in a Ruby project, require rubygems and use require_gem to specify the version. You can then instantiate Builder::XmlMarkup to create XML strings or write directly to a target like STDOUT.

require 'rubygems'
require_gem 'builder', '~> 2.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>

When using Builder::XmlEvents, the handler object you provide must implement the following three methods to receive the generated events:

• start_tag(tag, attrs): Called when a new tag is found. tag is the name of the tag (Symbol), and attrs is a Hash of attributes for that tag.
• end_tag(tag): Called when an end tag for tag is found.
• text(text): Called when a string of characters is found. Note that a single logical block of text may be broken up into multiple text calls, so the handler should be prepared to handle fragmented text data.

class MyHandler
  def start_tag(tag, attrs)
    puts "Start: #{tag} with #{attrs}"
  end

  def end_tag(tag)
    puts "End: #{tag}"
  end

  def text(text)
    puts "Text: #{text}"
  end
end

xe = Builder::XmlEvents.new(MyHandler.new)
xe.title("Hello")

The XmlBase class (the foundation for Builder::XmlMarkup and Builder::XmlEvents) is used to create XML markup. When initializing, you can control indentation, the starting indentation level, and the character encoding.

Parameters:

• indent: Number of spaces used for indentation. Setting this to 0 disables indentation and line breaks.
• initial: The starting indentation level.
• encoding: The character encoding (defaults to 'utf-8').

Note: When encoding and $KCODE are set to 'utf-8', characters are not converted to character entities in the output stream.

# Example conceptual initialization
# (Actual usage typically involves subclasses like XmlMarkup)
builder = Builder::XmlBase.new(2, 0, 'utf-8')

You can configure Builder::XmlMarkup to output to a specific target (e.g., STDOUT) and set an indentation level using keyword arguments in the constructor.

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>

Builder supports several specialized XML constructs:

• Comments: Use comment!.
• Processing Instructions: Use instruct!. If the instruction is :xml, it defaults to version 1.0 and UTF-8 encoding.
• Entity Declarations: Use declare!.
  • Symbols are inserted without quotes.
  • Strings are inserted with double quotes.
  • You can nest declare! calls within a block to create internal DTD subsets.

# Comments
xml_markup.comment! "This is a comment"

# Processing Instructions
xml_markup.instruct! :xml, :version=>"1.0", :encoding=>"UTF-8"

# Entity Declarations
xml_markup.declare! :DOCTYPE, :chapter, :SYSTEM, "../dtds/chapter.dtd"

# Nested Declarations
xml_markup.declare! :DOCTYPE, :chapter do |x|
  x.declare! :ELEMENT, :chapter, :"(title,para+)"
end

To produce a namespace prefix, pass a symbol as the first argument to a tag call. Ensure there is a space before the colon in your code to correctly map to the prefix:tag format.

# Produces <SOAP:Envelope>...</SOAP:Envelope>
xml.SOAP :Envelope do
  # ...
end