builder 1.1.0

data/README

@@ -0,0 +1,79 @@
+= Project: Builder
+
+= Goal
+
+Provide a simple way to create XML markup and data structures.
+
+= Classes
+
+Builder::XmlMarkup:: Generate XML markup notiation
+Builder::XmlTree::   Generate an XML tree (i.e. DOM-like)  structure
+                     (not yet implemented). 
+Builder::XmlEvents:: Generate XML events (i.e. SAX-like)
+
+= Usage
+
+  require 'rubygems'	
+  require_gem 'builder', '>= 1.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 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
+
+= Contact
+
+Author::  Jim Weirich
+Email::   jim@weirichhouse.org
+Home Page:: http://onestepback.org
+License:: Open Source

data/Rakefile

@@ -0,0 +1,86 @@
+# Rakefile for rake        -*- ruby -*-
+
+# Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+
+PKG_VERSION = "1.1.0"
+
+SRC_RB = FileList['lib/**/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task"
+task :default => :test
+
+# Test Tasks ---------------------------------------------------------
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+# Create a task to build the RDOC documentation tree.
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html'
+  rdoc.title    = "Builder for Markup"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('lib/**/*.rb', '[A-Z]*')
+}
+
+# ====================================================================
+# Create a task that will package the Rake software into distributable
+# gem files.
+
+PKG_FILES = FileList[
+  'lib/**/*.rb', 
+  'test/**/*.rb',
+]
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'builder'
+    s.version = PKG_VERSION
+    s.summary = "Builders for MarkUp."
+    s.description = %{Simple builder classes for creating markup.}
+
+    s.files = PKG_FILES.to_a
+
+    s.require_path = 'lib'
+    s.autorequire = 'builder'
+
+    s.test_files = Dir['test/test*.rb']
+
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    s.rdoc_options <<
+      '--title' <<  'Builder -- Easy XML Building' <<
+      '--main' << 'README' <<
+      '--line-numbers'
+
+    s.author = "Jim Weirich"
+    s.email = "jim@weirichhouse.org"
+    s.homepage = "http://onestepback.org"
+  end
+
+  Rake::GemPackageTask.new(spec) do end
+end

data/lib/builder.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+require 'builder/xmlmarkup'
+require 'builder/xmlevents'

data/lib/builder/blankslate.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+#--
+# Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+module Builder
+
+  # BlankSlate provides an abstract base class with no predefined
+  # methods (except for <tt>\_\_send__</tt> and <tt>\_\_id__</tt>).
+  # BlankSlate is useful as a base class when writing classes that
+  # depend upon <tt>method_missing</tt> (e.g. dynamic proxies).
+  class BlankSlate
+    instance_methods.each { |m| undef_method m unless m =~ /^(__|instance_eval)/ }
+  end
+
+end

data/lib/builder/xmlbase.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+
+require 'builder/blankslate'
+
+module Builder
+
+  # Generic error for builder
+  class IllegalBlockError < RuntimeError; end
+
+  # XmlBase is a base class for building XML builders.  See
+  # Builder::XmlMarkup and Builder::XmlEvents for examples.
+  class XmlBase < BlankSlate
+
+    # Create an XML markup builder.
+    #
+    # out::     Object receiving the markup.  +out+ must respond to
+    #           <tt><<</tt>.
+    # indent::  Number of spaces used for indentation (0 implies no
+    #           indentation and no line breaks).
+    # initial:: Level of initial indentation.
+    #
+    def initialize(indent=0, initial=0)
+      @indent = indent
+      @level  = initial
+    end
+    
+    # Create a tag named +sym+.  Other than the first argument which
+    # is the tag name, the arguements are the same as the tags
+    # implemented via <tt>method_missing</tt>.
+    def tag!(sym, *args, &block)
+      self.__send__(sym, *args, &block)
+    end
+
+    # Create XML markup based on the name of the method.  This method
+    # is never invoked directly, but is called for each markup method
+    # in the markup block.
+    def method_missing(sym, *args, &block)
+      text = nil
+      attrs = nil
+      args.each do |arg|
+	case arg
+	when Hash
+	  attrs ||= {}
+	  attrs.merge!(arg)
+	else
+	  text ||= ''
+	  text << arg.to_s
+	end
+      end
+      if block
+	unless text.nil?
+	  raise ArgumentError, "XmlMarkup cannot mix a text argument with a block"
+	end
+	_capture_outer_self(block) if @self.nil?
+	_indent
+	_start_tag(sym, attrs)
+	_newline
+	_nested_structures(block)
+	_indent
+	_end_tag(sym)
+	_newline
+      elsif text.nil?
+	_indent
+	_start_tag(sym, attrs, true)
+	_newline
+      else
+	_indent
+	_start_tag(sym, attrs)
+	text! text
+	_end_tag(sym)
+	_newline
+      end
+      @target
+    end
+
+    # Append text to the output target.  Escape any markup.  May be
+    # used within the markup brakets as:
+    #
+    #   builder.p { br; text! "HI" }   #=>  <p><br/>HI</p>
+    def text!(text)
+      _text(_escape(text))
+    end
+    
+    # Append text to the output target without escaping any markup.
+    # May be used within the markup brakets as:
+    #
+    #   builder.p { |x| x << "<br/>HI" }   #=>  <p><br/>HI</p>
+    #
+    # This is useful when using non-builder enabled software that
+    # generates strings.  Just insert the string directly into the
+    # builder without changing the inserted markup.
+    #
+    # It is also useful for stacking builder objects.  Builders only
+    # use <tt><<</tt> to append to the target, so by supporting this
+    # method/operation builders can use oother builders as their
+    # targets.
+    def <<(text)
+      _text(text)
+    end
+    
+    # For some reason, nil? is sent to the XmlMarkup object.  If nil?
+    # is not defined and method_missing is invoked, some strange kind
+    # of recursion happens.  Since nil? won't ever be an XML tag, it
+    # is pretty safe to define it here.
+    def nil?
+      false
+    end
+
+    private
+    
+    def _escape(text)
+      text.
+	gsub(%r{&}, '&amp;').
+	gsub(%r{<}, '&lt;').
+	gsub(%r{>}, '&gt;')
+    end
+
+    def _capture_outer_self(block)
+      @self = eval("self", block)
+    end
+    
+    def _newline
+      return if @indent == 0
+      text! "\n"
+    end
+    
+    def _indent
+      return if @indent == 0 || @level == 0
+      text!(" " * (@level * @indent))
+    end
+    
+    def _nested_structures(block)
+      @level += 1
+      block.call(self)
+    ensure
+      @level -= 1
+    end
+  end
+end

data/lib/builder/xmlevents.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+require 'builder/xmlmarkup'
+
+module Builder
+
+  # Create a series of SAX-like XML events (e.g. start_tag, end_tag)
+  # from the markup code.  XmlEvent objects are used in a way similar
+  # to XmlMarkup objects, except that a series of events are generated
+  # and passed to a handler rather than generating character-based
+  # markup.
+  #
+  # Usage:
+  #   xe = Builder::XmlEvents.new(hander)
+  #   xe.title("HI")    # Sends start_tag/end_tag/text messages to the handler.
+  #
+  # Indentation may also be selected by providing value for the
+  # indentation size and initial indentation level.
+  #
+  #   xe = Builder::XmlEvents.new(handler, indent_size, initial_indent_level)
+  #
+  # == XML Event Handler
+  #
+  # The handler object must expect the following events.
+  #
+  # [<tt>start_tag(tag, attrs)</tt>]
+  #     Announces that a new tag has been found.  +tag+ is the name of
+  #     the tag and +attrs+ is a hash of attributes for the tag.
+  #
+  # [<tt>end_tag(tag)</tt>]
+  #     Announces that an end tag for +tag+ has been found.
+  #
+  # [<tt>text(text)</tt>]
+  #     Announces that a string of characters (+text+) has been found.
+  #     A series of characters may be broken up into more than one
+  #     +text+ call, so the client cannot assume that a single
+  #     callback contains all the text data.
+  #
+  class XmlEvents < XmlMarkup
+    def text!(text)
+      @target.text(text)
+    end
+
+    def _start_tag(sym, attrs, end_too=false)
+      @target.start_tag(sym, attrs)
+      _end_tag(sym) if end_too
+    end
+
+    def _end_tag(sym)
+      @target.end_tag(sym)
+    end
+  end
+
+end

data/lib/builder/xmlmarkup.rb

@@ -0,0 +1,260 @@
+#!/usr/bin/env ruby
+#--
+# Copyright 2004 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+# Provide a flexible and easy to use Builder for creating XML markup.
+# See XmlBuilder for usage details.
+
+require 'builder/xmlbase'
+
+module Builder
+
+  # Create XML markup easily.  All (well, almost all) methods sent to
+  # an XmlMarkup object will be translated to the equivalent XML
+  # markup.  Any method with a block will be treated as an XML markup
+  # tag with nested markup in the block.
+  #
+  # Examples will demonstrate this easier than words.  In the
+  # following, +xm+ is an +XmlMarkup+ object.
+  #
+  #   xm.em("emphasized")             # => <em>emphasized</em>
+  #   xm.em { xmm.b("emp & bold") }   # => <em><b>emph &amp; bold</b></em>
+  #   xm.a("A Link", "href"=>"http://onestepback.org")
+  #                                   # => <a href="http://onestepback.org">A Link</a>
+  #   xm.div { br }                    # => <div><br/></div>
+  #   xm.target("name"=>"compile", "option"=>"fast")
+  #                                   # => <target option="fast" name="compile"\>
+  #                                   # NOTE: order of attributes is not specified.
+  #
+  #   xm.instruct!                   # <?xml version="1.0" encoding="UTF-8"?>
+  #   xm.html {                      # <html>
+  #     xm.head {                    #   <head>
+  #       xm.title("History")        #     <title>History</title>
+  #     }                            #   </head>
+  #     xm.body {                    #   <body>
+  #       xm.comment! "HI"           #     <!-- HI -->
+  #       xm.h1("Header")            #     <h1>Header</h1>
+  #       xm.p("paragraph")          #     <p>paragraph</p>
+  #     }                            #   </body>
+  #   }                              # </html>
+  #
+  # == Notes:
+  #
+  # * The order that attributes are inserted in markup tags is
+  #   undefined. 
+  #
+  # * Sometimes you wish to insert text without enclosing tags.  Use
+  #   the <tt>text!</tt> method to accomplish this.
+  #
+  #   Example:
+  #
+  #     xm.div {                          # <div>
+  #       xm.text! "line"; xm.br          #   line<br/>
+  #       xm.text! "another line"; xmbr   #    another line<br/>
+  #     }                                 # </div>
+  #
+  # * The special XML characters <, >, and & are converted to &lt;,
+  #   &gt; and &amp; automatically.  Use the <tt><<</tt> operation to
+  #   insert text without modification.
+  #
+  # * Sometimes tags use special characters not allowed in ruby
+  #   identifiers.  Use the <tt>tag!</tt> method to handle these
+  #   cases.
+  #
+  #   Example:
+  #
+  #     xml.tag!("SOAP:Envelope") { ... }
+  #
+  #   will produce ...
+  #
+  #     <SOAP:Envelope> ... </SOAP:Envelope>"
+  #
+  #   <tt>tag!</tt> will also take text and attribute arguments (after
+  #   the tag name) like normal markup methods.
+  #   
+  # * XmlMarkup builds the markup in any object (called a _target_)
+  #   that accepts the <tt><<</tt> method.  If no target is given,
+  #   then XmlMarkup defaults to a string target.
+  # 
+  #   Examples:
+  #
+  #     xm = Builder::XmlMarkup.new
+  #     result = xm.title("yada")
+  #     # result is a string containing the markup.
+  #
+  #     buffer = ""
+  #     xm = Builder::XmlMarkup.new(buffer)
+  #     # The markup is appended to buffer (using <<)
+  #
+  #     xm = Builder::XmlMarkup.new(STDOUT)
+  #     # The markup is written to STDOUT (using <<)
+  #
+  #     xm = Builder::XmlMarkup.new
+  #     x2 = Builder::XmlMarkup.new(:target=>xm)
+  #     # Markup written to +x2+ will be send to +xm+.
+  #   
+  # * Indentation is enabled by providing the number of spaces to
+  #   indent for each level as a second argument to XmlBuilder.new.
+  #   Initial indentation may be specified using a third parameter.
+  #
+  #   Example:
+  #
+  #     xm = Builder.new(:ident=>2)
+  #     # xm will produce nicely formatted and indented XML.
+  #  
+  #     xm = Builder.new(:indent=>2, :margin=>4)
+  #     # xm will produce nicely formatted and indented XML with 2
+  #     # spaces per indent and an over all indentation level of 4.
+  #
+  #     builder = Builder::XmlMarkup.new(:target=>$stdout, :indent=>2)
+  #     builder.name { |b| b.first("Jim"); b.last("Weirich) }
+  #     # prints:
+  #     #     <name>
+  #     #       <first>Jim</first>
+  #     #       <last>Weirich</last>
+  #     #     </name>
+  #
+  # * The instance_eval implementation which forces self to refer to
+  #   the message receiver as self is now obsolete.  We now use normal
+  #   block calls to execute the markup block.  This means that all
+  #   markup methods must now be explicitly send to the xml builder.
+  #   For instance, instead of
+  #
+  #      xml.div { strong("text") }
+  #
+  #   you need to write:
+  #
+  #      xml.div { xml.strong("text") }
+  #
+  #   Although more verbose, the subtle change in semantics within the
+  #   block was found to be prone to error.  To make this change a
+  #   little less cumbersome, the markup block now gets the markup
+  #   object sent as an argument, allowing you to use a shorter alias
+  #   within the block.
+  #
+  #   For example:
+  #
+  #     xml_builder = Builder::XmlMarkup.new
+  #     xml_builder.div { |xml|
+  #       xml.stong("text")
+  #     }
+  #
+  class XmlMarkup < XmlBase
+
+    # Create an XML markup builder.  Parameters are specified by an
+    # option hash.
+    #
+    # :target=><em>target_object</em>::
+    #    Object receiving the markup.  +out+ must respond to the
+    #    <tt><<</tt> operator.  The default is a plain string target.
+    # :indent=><em>indentation</em>::
+    #    Number of spaces used for indentation.  The default is no
+    #    indentation and no line breaks.
+    # :margin=><em>initial_indentation_level</em>::
+    #    Amount of initial indentation (specified in levels, not
+    #    spaces).
+    #    
+    def initialize(options={})
+      indent = options[:indent] || 0
+      margin = options[:margin] || 0
+      super(indent, margin)
+      @target = options[:target] || ""
+    end
+    
+    # Return the target of the builder.
+    def target!
+      @target
+    end
+
+    def comment!(comment_text)
+      _ensure_no_block block_given?
+      _special("<!-- ", " -->", comment_text, nil)
+    end
+
+    # Insert an XML declaration into the XML markup.
+    #
+    # For example:
+    #
+    #   xml.declare! :element, :blah=>"yada"
+    #       # => <?xml blah="yada"?>
+    def declare!(inst, attrs={})
+      _ensure_no_block block_given?
+      _special("<!#{inst}", ">", nil, attrs)
+    end
+
+    # Insert a processing instruction into the XML markup.  E.g.
+    #
+    # For example:
+    #
+    #    xml.instruct!
+    #        #=> <?xml encoding="UTF-8" version="1.0"?>
+    #    xml.instruct! :aaa, :bbb=>"ccc"
+    #        #=> <?aaa bbb="ccc"?>
+    #
+    def instruct!(directive_tag=:xml, attrs={})
+      _ensure_no_block block_given?
+      if directive_tag == :xml
+	a = { :version=>"1.0", :encoding=>"UTF-8" }
+	attrs = a.merge attrs
+      end
+      _special("<?#{directive_tag}", "?>", nil, attrs)
+    end
+
+    private
+
+    # NOTE: All private methods of a builder object are prefixed when
+    # a "_" character to avoid possible conflict with XML tag names.
+
+    # Insert text directly in to the builder's target.
+    def _text(text)
+      @target << text
+    end
+    
+    # Insert special instruction. 
+    def _special(open, close, data=nil, attrs=nil)
+      _indent
+      @target << open
+      @target << data if data
+      _insert_attributes(attrs) if attrs
+      @target << close
+      _newline
+    end
+
+    # Start an XML tag.  If <tt>end_too</tt> is true, then the start
+    # tag is also the end tag (e.g.  <br/>
+    def _start_tag(sym, attrs, end_too=false)
+      @target << "<#{sym}"
+      _insert_attributes(attrs)
+      @target << "/" if end_too
+      @target << ">"
+    end
+    
+    # Insert an ending tag.
+    def _end_tag(sym)
+      @target << "</#{sym}>"
+    end
+
+    # Insert the attributes (given in the hash).
+    def _insert_attributes(attrs)
+      return if attrs.nil?
+      attrs.each do |k, v|
+	@target << %{ #{_escape(k.to_s)}="#{_escape(v.to_s)}"}
+      end
+    end
+
+    def _ensure_no_block(got_block)
+      if got_block
+	fail IllegalBlockError,
+	  "Blocks are not allowed on XML instructions"
+      end
+    end
+
+  end
+
+end

data/test/testmarkupbuilder.rb

@@ -0,0 +1,274 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'builder'
+require 'builder/xmlmarkup'
+
+class TestMarkup < Test::Unit::TestCase
+  def setup
+    @xm = Builder::XmlMarkup.new
+  end
+
+  def test_create
+    assert_not_nil @xm
+  end
+
+  def test_simple
+    @xm.simple
+    assert_equal "<simple/>", @xm.target!
+  end
+
+  def test_value
+    @xm.value("hi")
+    assert_equal "<value>hi</value>", @xm.target!
+  end
+
+  def test_nested
+    @xm.outer { |x| x.inner("x") }
+    assert_equal "<outer><inner>x</inner></outer>", @xm.target!
+  end
+
+  def test_attributes
+    @xm.ref(:id => 12)
+    assert_equal %{<ref id="12"/>}, @xm.target!
+  end
+
+  def test_multiple_attributes
+    @xm.ref(:id => 12, :name => "bill")
+    assert_match %r{^<ref( id="12"| name="bill"){2}/>$}, @xm.target!
+  end
+
+  def test_attributes_with_text
+    @xm.a("link", :href=>"http://onestepback.org")
+    assert_equal %{<a href="http://onestepback.org">link</a>}, @xm.target!
+  end
+  
+  def test_complex
+    @xm.body(:bg=>"#ffffff") { |x|
+      x.title("T", :style=>"red")
+    }
+    assert_equal %{<body bg="#ffffff"><title style="red">T</title></body>}, @xm.target!
+  end
+
+  def test_funky_symbol
+    @xm.tag!("non-ruby-token", :id=>1) { |x| x.ok }
+    assert_equal %{<non-ruby-token id="1"><ok/></non-ruby-token>}, @xm.target!
+  end
+
+  def test_no_explicit_marker
+    @xm.p { |x| x.b("HI") }
+    assert_equal "<p><b>HI</b></p>", @xm.target!
+  end
+
+  def test_reference_local_vars
+    n = 3
+    @xm.ol { |x| n.times { x.li(n) } }
+    assert_equal "<ol><li>3</li><li>3</li><li>3</li></ol>", @xm.target!
+  end
+
+  def test_reference_methods
+    @xm.title { |x| x.a { x.b(name) } }
+    assert_equal "<title><a><b>bob</b></a></title>", @xm.target!
+  end
+
+  def test_append_text
+    @xm.p { |x| x.br; x.text! "HI" }
+    assert_equal "<p><br/>HI</p>", @xm.target!    
+  end
+  
+  def test_ambiguous_markup
+    ex = assert_raises(ArgumentError) {
+      @xm.h1("data1") { b }
+    }
+    assert_match /\btext\b/, ex.message
+    assert_match /\bblock\b/, ex.message
+  end
+
+  def test_capitalized_method
+    @xm.P { |x| x.B("hi"); x.BR(); x.EM { x.text! "world" } }
+    assert_equal "<P><B>hi</B><BR/><EM>world</EM></P>", @xm.target!
+  end
+
+  def test_escaping
+    @xm.div("H&R"=>"<BLOCK>") { |x| x.text! "<hi>"; x.em("H&R Block") }
+    assert_equal %{<div H&amp;R="&lt;BLOCK&gt;">&lt;hi&gt;<em>H&amp;R Block</em></div>}, @xm.target!
+  end
+
+  def test_non_escaping
+    @xm.div("H&R"=>"<BLOCK>") { |x| x << "<h&i>"; x.em("H&R Block") }
+    assert_equal %{<div H&amp;R="&lt;BLOCK&gt;"><h&i><em>H&amp;R Block</em></div>}, @xm.target!
+  end
+
+  def test_return_value
+    str = @xm.x("men")
+    assert_equal @xm.target!, str
+  end
+
+  def test_stacked_builders
+    b = Builder::XmlMarkup.new( :target => @xm )
+    b.div { @xm.span { @xm.a("text", :href=>"ref") } }
+    assert_equal "<div><span><a href=\"ref\">text</a></span></div>", @xm.target!
+  end
+
+  def name
+    "bob"
+  end
+end
+
+class TestSpecialMarkup < Test::Unit::TestCase
+  def setup
+    @xm = Builder::XmlMarkup.new(:indent=>2)
+  end
+
+  def test_comment
+    @xm.comment!("COMMENT")
+    assert_equal "<!-- COMMENT -->\n", @xm.target!
+  end
+
+  def test_indented_comment
+    @xm.p { @xm.comment! "OK" }
+    assert_equal "<p>\n  <!-- OK -->\n</p>\n", @xm.target!
+  end
+
+  def test_declare
+    @xm.declare! :element, :x=>"AB"
+    assert_equal "<!element x=\"AB\">\n", @xm.target!
+  end
+
+  def test_indented_declare
+    @xm.p { @xm.declare! :element, :x=>"y" }
+    assert_equal "<p>\n  <!element x=\"y\">\n</p>\n", @xm.target!
+  end
+
+  def test_instruct
+    @xm.instruct! :abc, :version=>"0.9"
+    assert_equal "<?abc version=\"0.9\"?>\n", @xm.target!
+  end
+
+  def test_indented_instruct
+    @xm.p { @xm.instruct! :xml }
+    assert_match %r{<p>\n  <\?xml( version="1.0"| encoding="UTF-8"){2}\?>\n</p>\n},
+      @xm.target!
+  end
+
+  def test_instruct_without_attributes
+    @xm.instruct! :zz
+    assert_equal "<?zz?>\n", @xm.target!
+  end
+
+  def test_xml_instruct
+    @xm.instruct!
+    assert_match /^<\?xml( version="1.0"| encoding="UTF-8"){2}\?>$/, @xm.target!
+  end
+
+  def test_xml_instruct_with_overrides
+    @xm.instruct! :xml, :encoding=>"UCS-2"
+    assert_match /^<\?xml( version="1.0"| encoding="UCS-2"){2}\?>$/, @xm.target!
+  end
+
+  def test_no_blocks
+    assert_raises(Builder::IllegalBlockError) do
+      @xm.instruct! { |x| x.hi }
+    end
+    assert_raises(Builder::IllegalBlockError) do
+      @xm.declare!(:element) { |x| x.hi }
+    end
+    assert_raises(Builder::IllegalBlockError) do
+      @xm.comment!(:element) { |x| x.hi }
+    end
+  end
+end
+
+class TestIndentedXmlMarkup < Test::Unit::TestCase
+  def setup
+    @xm = Builder::XmlMarkup.new(:indent=>2)
+  end
+
+  def test_one_level
+    @xm.ol { |x| x.li "text" }
+    assert_equal "<ol>\n  <li>text</li>\n</ol>\n", @xm.target!
+  end
+
+  def test_two_levels
+    @xm.p { |x|
+      x.ol { x.li "text" }
+      x.br
+    }
+    assert_equal "<p>\n  <ol>\n    <li>text</li>\n  </ol>\n  <br/>\n</p>\n", @xm.target!
+  end
+
+  def test_initial_level
+    @xm = Builder::XmlMarkup.new(:indent=>2, :margin=>4)
+    @xm.name { |x| x.first("Jim") }
+    assert_equal "        <name>\n          <first>Jim</first>\n        </name>\n", @xm.target!
+  end
+
+  class TestXmlEvents < Test::Unit::TestCase
+    def setup
+      @handler = EventHandler.new
+      @xe = Builder::XmlEvents.new(:target=>@handler)
+    end
+
+    def test_simple
+      @xe.p
+      assert_equal [:start, :p, nil], @handler.events.shift
+      assert_equal [:end, :p], @handler.events.shift
+    end
+
+    def test_text
+      @xe.p("HI")
+      assert_equal [:start, :p, nil], @handler.events.shift
+      assert_equal [:text, "HI"], @handler.events.shift
+      assert_equal [:end, :p], @handler.events.shift
+    end
+
+    def test_attributes
+      @xe.p("id"=>"2")
+      ev = @handler.events.shift
+      assert_equal [:start, :p], ev[0,2]
+      assert_equal "2", ev[2]['id']
+      assert_equal [:end, :p], @handler.events.shift
+    end
+
+    def test_indented
+      @xe = Builder::XmlEvents.new(:indent=>2, :target=>@handler)
+      @xe.p { |x| x.b("HI") }
+      assert_equal [:start, :p, nil], @handler.events.shift
+      assert_equal "\n  ", pop_text
+      assert_equal [:start, :b, nil], @handler.events.shift
+      assert_equal "HI", pop_text
+      assert_equal [:end, :b], @handler.events.shift
+      assert_equal "\n", pop_text
+      assert_equal [:end, :p], @handler.events.shift
+    end
+
+    def pop_text
+      result = ''
+      while ! @handler.events.empty? && @handler.events[0][0] == :text
+	result << @handler.events[0][1]
+	@handler.events.shift
+      end
+      result
+    end
+
+    class EventHandler
+      attr_reader :events
+      def initialize
+	@events = []
+      end
+      
+      def start_tag(sym, attrs)
+	@events << [:start, sym, attrs]
+      end
+
+      def end_tag(sym)
+	@events << [:end, sym]
+      end
+
+      def text(txt)
+	@events << [:text, txt]
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.1
+specification_version: 1
+name: builder
+version: !ruby/object:Gem::Version 
+  version: 1.1.0
+date: 2004-10-16
+summary: Builders for MarkUp.
+require_paths: 
+  - lib
+author: Jim Weirich
+email: jim@weirichhouse.org
+homepage: http://onestepback.org
+rubyforge_project: 
+description: Simple builder classes for creating markup.
+autorequire: builder
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+files: 
+  - lib/builder.rb
+  - lib/builder/blankslate.rb
+  - lib/builder/xmlbase.rb
+  - lib/builder/xmlevents.rb
+  - lib/builder/xmlmarkup.rb
+  - test/testmarkupbuilder.rb
+  - README
+  - Rakefile
+test_files: 
+  - test/testmarkupbuilder.rb
+rdoc_options: 
+  - "--title"
+  - "Builder -- Easy XML Building"
+  - "--main"
+  - README
+  - "--line-numbers"
+extra_rdoc_files: 
+  - README
+  - Rakefile
+executables: []
+extensions: []
+requirements: []
+dependencies: []