README

= 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)

<b>Notes</b>:: 

* An <tt>Builder::XmlTree</tt> class to generate XML tree
  (i.e. DOM-like) structures is also planned, but not yet implemented.
  Also, the events builder is currently lagging the markup builder in
  features.

== Usage

  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>

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 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:

* Keyword based arguments to +new+ (rather than positional based).  It
  was found that a developer would often like to specify indentation
  without providing an explicit target, or specify a target without
  indentation.  Keyword based arguments handle this situation nicely.

* Builder must now be an explicit target for markup tags.  Instead of
  writing

    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { strong("text") }

  you need to write

    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { xml_markup.strong("text") }

* The builder object is passed as a parameter to all nested markup
  blocks.  This allows you to create a short alias for the builder
  object that can be used within the block.  For example, the previous
  example can be written as:

    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { |xml| xml.strong("text") }

* If you have both a pre-1.0 and a post-1.0 gem of builder installed,
  you can choose which version to use through the RubyGems
  +require_gem+ facility.

    require_gem 'builder', "~> 0.0"   # Gets the old version
    require_gem 'builder', "~> 1.0"   # Gets the new version

== Features

* XML Comments are supported ...

    xml_markup.comment! "This is a comment"
      #=>  <!-- This is a comment -->

* XML processing instructions are supported ...

    xml_markup.instruct! :xml, :version=>"1.0", :encoding=>"UTF-8"
      #=>  <?xml version="1.0" encoding="UTF-8"?>
   
  If the processing instruction is omitted, it defaults to "xml".
  When the processing instruction is "xml", the defaults attributes
  are:
  
  <b>version</b>:: 1.0
  <b>encoding</b>:: "UTF-8"

  (NOTE: if the encoding is set to "UTF-8" and $KCODE is set to
  "UTF8", then Builder will emit UTF-8 encoded strings rather than
  encoding non-ASCII characters as entities.)

* XML entity declarations are now supported to a small degree.

    xml_markup.declare! :DOCTYPE, :chapter, :SYSTEM, "../dtds/chapter.dtd"
      #=>  <!DOCTYPE chapter SYSTEM "../dtds/chapter.dtd">

  The parameters to a declare! method must be either symbols or
  strings. Symbols are inserted without quotes, and strings are
  inserted with double quotes.  Attribute-like arguments in hashes are
  not allowed.

  If you need to have an argument to declare! be inserted without
  quotes, but the arguement does not conform to the typical Ruby
  syntax for symbols, then use the :"string" form to specify a symbol.

  For example:

    xml_markup.declare! :ELEMENT, :chapter, :"(title,para+)"
      #=>  <!ELEMENT chapter (title,para+)>

  Nested entity declarations are allowed.  For example:

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

    #=>

    <!DOCTYPE chapter [
      <!ELEMENT chapter (title,para+)>
      <!ELEMENT title (#PCDATA)>
      <!ELEMENT para (#PCDATA)>
    ]>

* Some support for XML namespaces is now available.  If the first
  argument to a tag call is a symbol, it will be joined to the tag to
  produce a namespace:tag combination.  It is easier to show this than
  describe it.

   xml.SOAP :Envelope do ... end

  Just put a space before the colon in a namespace to produce the
  right form for builder (e.g. "<tt>SOAP:Envelope</tt>" =>
  "<tt>xml.SOAP :Envelope</tt>")

* String attribute values are <em>now</em> escaped by default by
  Builder (<b>NOTE:</b> this is _new_ behavior as of version 2.0).

  However, occasionally you need to use entities in attribute values.
  Using a symbols (rather than a string) for an attribute value will
  cause Builder to not run its quoting/escaping algorithm on that
  particular value.

  (<b>Note:</b> The +escape_attrs+ option for builder is now
  obsolete).

  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"/>

* UTF-8 Support

  Builder correctly translates UTF-8 characters into valid XML.  (New
  in version 2.0.0).  Thanks to Sam Ruby for the translation code.

  Example:

    xml = Builder::Markup.new
    xml.sample("Iñtërnâtiônàl")
    xml.target!  =>
      "<sample>I&#241;t&#235;rn&#226;ti&#244;n&#224;l</sample>"

  You can get UTF-8 encoded output by making sure that the XML
  encoding is set to "UTF-8" and that the $KCODE variable is set to
  "UTF8".

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

== Contact

Author::     Jim Weirich
Email::      jim@weirichhouse.org
Home Page::  http://onestepback.org
License::    MIT Licence (http://www.opensource.org/licenses/mit-license.html)