builder 1.1.0 → 1.2.0

data/README

@@ -7,14 +7,19 @@ 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)
 
+<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', '>= 1.0"
+  require_gem 'builder', '~> 1.2"
 
   builder = Builder::XmlMarkup.new
   xml = builder.person { |b| b.name("Jim"); b.phone("555-1234") }
@@ -71,9 +76,73 @@ incompatibility are:
     require_gem 'builder', "~> 0.0"   # Gets the old version
     require_gem 'builder', "~> 1.0"   # Gets the new version
 
+= New Features
+
+* XML Comments are now supported ...
+
+    xml_markup.comment! "This is a comment"
+      #=>  <!-- This is a comment -->
+
+* XML processing instructions are now 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"
+
+* 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 +intern+ method on a string to
+  convert it to a symbol.
+
+    xml_markup.declare! :ELEMENT, :chapter, "(title,para+)".intern
+      #=>  <!ELEMENT chapter (title,para+)>
+
+  Nested entity declarations are allowed.  For example:
+
+    @xml_markup.declare! :DOCTYPE, :chapter do |x|
+      x.declare! :ELEMENT, :chapter, "(title,para+)".intern
+      x.declare! :ELEMENT, :title, "(#PCDATA)".intern
+      x.declare! :ELEMENT, :para, "(#PCDATA)".intern
+    end
+
+    #=>
+
+    <!DOCTYPE chapter [
+      <!ELEMENT chapter (title,para+)>
+      <!ELEMENT title (#PCDATA)>
+      <!ELEMENT para (#PCDATA)>
+    ]>
+
+* Direct 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>")
+
 = Contact
 
-Author::  Jim Weirich
-Email::   jim@weirichhouse.org
-Home Page:: http://onestepback.org
-License:: Open Source
+Author::     Jim Weirich
+Email::      jim@weirichhouse.org
+Home Page::  http://onestepback.org
+License::     Open Source

data/Rakefile

@@ -17,7 +17,7 @@ rescue Exception
   nil
 end
 
-PKG_VERSION = "1.1.0"
+PKG_VERSION = "1.2.0"
 
 SRC_RB = FileList['lib/**/*.rb']
 

data/lib/builder/xmlbase.rb

@@ -13,7 +13,7 @@ module Builder
 
     # Create an XML markup builder.
     #
-    # out::     Object receiving the markup.  +out+ must respond to
+    # out::     Object receiving the markup.1  +out+ must respond to
     #           <tt><<</tt>.
     # indent::  Number of spaces used for indentation (0 implies no
     #           indentation and no line breaks).
@@ -37,6 +37,7 @@ module Builder
     def method_missing(sym, *args, &block)
       text = nil
       attrs = nil
+      sym = "#{sym}:#{args.shift}" if args.first.kind_of?(Symbol)
       args.each do |arg|
 	case arg
 	when Hash
@@ -101,7 +102,9 @@ module Builder
     # 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.
+    # is pretty safe to define it here. (Note: this is an example of
+    # cargo cult programming,
+    # cf. http://fishbowl.pastiche.org/2004/10/13/cargo_cult_programming).
     def nil?
       false
     end

data/lib/builder/xmlmarkup.rb

@@ -76,8 +76,20 @@ module Builder
   #     <SOAP:Envelope> ... </SOAP:Envelope>"
   #
   #   <tt>tag!</tt> will also take text and attribute arguments (after
-  #   the tag name) like normal markup methods.
+  #   the tag name) like normal markup methods.  (But see the next
+  #   bullet item for a better way to handle XML namespaces).
   #   
+  # * Direct 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>")
+  #
   # * 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.
@@ -181,11 +193,27 @@ module Builder
     #
     # For example:
     #
-    #   xml.declare! :element, :blah=>"yada"
-    #       # => <?xml blah="yada"?>
-    def declare!(inst, attrs={})
-      _ensure_no_block block_given?
-      _special("<!#{inst}", ">", nil, attrs)
+    #   xml.declare! :ELEMENT, :blah, "yada"
+    #       # => <!ELEMENT blah "yada">
+    def declare!(inst, *args, &block)
+      _indent
+      @target << "<!#{inst}"
+      args.each do |arg|
+	case arg
+	when String
+	  @target << %{ "#{arg}"}
+	when Symbol
+	  @target << " #{arg}"
+	end
+      end
+      if block_given?
+	@target << " ["
+	_newline
+	_nested_structures(block)
+	@target << "]"
+      end
+      @target << ">"
+      _newline
     end
 
     # Insert a processing instruction into the XML markup.  E.g.
@@ -244,7 +272,7 @@ module Builder
     def _insert_attributes(attrs)
       return if attrs.nil?
       attrs.each do |k, v|
-	@target << %{ #{_escape(k.to_s)}="#{_escape(v.to_s)}"}
+	@target << %{ #{k}="#{v}"}
       end
     end
 

data/test/testmarkupbuilder.rb

@@ -6,108 +6,108 @@ require 'builder/xmlmarkup'
 
 class TestMarkup < Test::Unit::TestCase
   def setup
-    @xm = Builder::XmlMarkup.new
+    @xml = Builder::XmlMarkup.new
   end
 
   def test_create
-    assert_not_nil @xm
+    assert_not_nil @xml
   end
 
   def test_simple
-    @xm.simple
-    assert_equal "<simple/>", @xm.target!
+    @xml.simple
+    assert_equal "<simple/>", @xml.target!
   end
 
   def test_value
-    @xm.value("hi")
-    assert_equal "<value>hi</value>", @xm.target!
+    @xml.value("hi")
+    assert_equal "<value>hi</value>", @xml.target!
   end
 
   def test_nested
-    @xm.outer { |x| x.inner("x") }
-    assert_equal "<outer><inner>x</inner></outer>", @xm.target!
+    @xml.outer { |x| x.inner("x") }
+    assert_equal "<outer><inner>x</inner></outer>", @xml.target!
   end
 
   def test_attributes
-    @xm.ref(:id => 12)
-    assert_equal %{<ref id="12"/>}, @xm.target!
+    @xml.ref(:id => 12)
+    assert_equal %{<ref id="12"/>}, @xml.target!
   end
 
   def test_multiple_attributes
-    @xm.ref(:id => 12, :name => "bill")
-    assert_match %r{^<ref( id="12"| name="bill"){2}/>$}, @xm.target!
+    @xml.ref(:id => 12, :name => "bill")
+    assert_match %r{^<ref( id="12"| name="bill"){2}/>$}, @xml.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!
+    @xml.a("link", :href=>"http://onestepback.org")
+    assert_equal %{<a href="http://onestepback.org">link</a>}, @xml.target!
   end
   
   def test_complex
-    @xm.body(:bg=>"#ffffff") { |x|
+    @xml.body(:bg=>"#ffffff") { |x|
       x.title("T", :style=>"red")
     }
-    assert_equal %{<body bg="#ffffff"><title style="red">T</title></body>}, @xm.target!
+    assert_equal %{<body bg="#ffffff"><title style="red">T</title></body>}, @xml.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!
+    @xml.tag!("non-ruby-token", :id=>1) { |x| x.ok }
+    assert_equal %{<non-ruby-token id="1"><ok/></non-ruby-token>}, @xml.target!
   end
 
   def test_no_explicit_marker
-    @xm.p { |x| x.b("HI") }
-    assert_equal "<p><b>HI</b></p>", @xm.target!
+    @xml.p { |x| x.b("HI") }
+    assert_equal "<p><b>HI</b></p>", @xml.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!
+    @xml.ol { |x| n.times { x.li(n) } }
+    assert_equal "<ol><li>3</li><li>3</li><li>3</li></ol>", @xml.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!
+    @xml.title { |x| x.a { x.b(name) } }
+    assert_equal "<title><a><b>bob</b></a></title>", @xml.target!
   end
 
   def test_append_text
-    @xm.p { |x| x.br; x.text! "HI" }
-    assert_equal "<p><br/>HI</p>", @xm.target!    
+    @xml.p { |x| x.br; x.text! "HI" }
+    assert_equal "<p><br/>HI</p>", @xml.target!    
   end
   
   def test_ambiguous_markup
     ex = assert_raises(ArgumentError) {
-      @xm.h1("data1") { b }
+      @xml.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!
+    @xml.P { |x| x.B("hi"); x.BR(); x.EM { x.text! "world" } }
+    assert_equal "<P><B>hi</B><BR/><EM>world</EM></P>", @xml.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!
+    @xml.div { |x| x.text! "<hi>"; x.em("H&R Block") }
+    assert_equal %{<div>&lt;hi&gt;<em>H&amp;R Block</em></div>}, @xml.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!
+    @xml.div("ns:xml"=>"&xml;") { |x| x << "<h&i>"; x.em("H&R Block") }
+    assert_equal %{<div ns:xml="&xml;"><h&i><em>H&amp;R Block</em></div>}, @xml.target!
   end
 
   def test_return_value
-    str = @xm.x("men")
-    assert_equal @xm.target!, str
+    str = @xml.x("men")
+    assert_equal @xml.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!
+    b = Builder::XmlMarkup.new( :target => @xml )
+    b.div { @xml.span { @xml.a("text", :href=>"ref") } }
+    assert_equal "<div><span><a href=\"ref\">text</a></span></div>", @xml.target!
   end
 
   def name
@@ -115,92 +115,172 @@ class TestMarkup < Test::Unit::TestCase
   end
 end
 
-class TestSpecialMarkup < Test::Unit::TestCase
+class TestNameSpaces < Test::Unit::TestCase
   def setup
-    @xm = Builder::XmlMarkup.new(:indent=>2)
+    @xml = Builder::XmlMarkup.new(:indent=>2)
+  end
+
+  def test_simple_name_spaces
+    @xml.rdf :RDF
+    assert_equal "<rdf:RDF/>\n", @xml.target!
+  end
+
+  def test_long
+    xml = Builder::XmlMarkup.new(:indent=>2)
+    xml.instruct!
+    xml.rdf :RDF, 
+      "xmlns:rdf" => "&rdf;",
+      "xmlns:rdfs" => "&rdfs;",
+      "xmlns:xsd" => "&xsd;",
+      "xmlns:owl" => "&owl;" do
+      xml.owl :Class, 'rdf:ID'=>'Bird' do
+	xml.rdfs :label, 'bird'
+	xml.rdfs :subClassOf do
+	  xml.owl :Restriction do
+	    xml.owl :onProperty, 'rdf:resource'=>'#wingspan'
+	    xml.owl :maxCardinality,1,'rdf:datatype'=>'&xsd;nonNegativeInteger'
+	  end
+	end
+      end
+    end
+    assert_match /^<\?xml/, xml.target!
+    assert_match /\n<rdf:RDF/m, xml.target!
+    assert_match /xmlns:rdf="&rdf;"/m, xml.target!
+    assert_match /<owl:Restriction>/m, xml.target!
   end
+  
+end
 
-  def test_comment
-    @xm.comment!("COMMENT")
-    assert_equal "<!-- COMMENT -->\n", @xm.target!
+class TestDeclarations < Test::Unit::TestCase
+  def setup
+    @xml = Builder::XmlMarkup.new(:indent=>2)
   end
 
-  def test_indented_comment
-    @xm.p { @xm.comment! "OK" }
-    assert_equal "<p>\n  <!-- OK -->\n</p>\n", @xm.target!
+  def test_declare
+    @xml.declare! :element
+    assert_equal "<!element>\n", @xml.target!
   end
 
-  def test_declare
-    @xm.declare! :element, :x=>"AB"
-    assert_equal "<!element x=\"AB\">\n", @xm.target!
+  def test_bare_arg
+    @xml.declare! :element, :arg
+    assert_equal"<!element arg>\n", @xml.target!
+  end
+
+  def test_string_arg
+    @xml.declare! :element, "string"
+    assert_equal"<!element \"string\">\n", @xml.target!
+  end
+
+  def test_mixed_args
+    @xml.declare! :element, :x, "y", :z, "-//OASIS//DTD DocBook XML//EN"
+    assert_equal "<!element x \"y\" z \"-//OASIS//DTD DocBook XML//EN\">\n", @xml.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!
+  def test_nested_declarations
+    @xml = Builder::XmlMarkup.new
+    @xml.declare! :DOCTYPE, :chapter do |x|
+      x.declare! :ELEMENT, :chapter, "(title,para+)".intern
+    end
+    assert_equal "<!DOCTYPE chapter [<!ELEMENT chapter (title,para+)>]>", @xml.target!
+  end
+
+  def test_nested_indented_declarations
+    @xml.declare! :DOCTYPE, :chapter do |x|
+      x.declare! :ELEMENT, :chapter, "(title,para+)".intern
+    end
+    assert_equal "<!DOCTYPE chapter [\n  <!ELEMENT chapter (title,para+)>\n]>\n", @xml.target!
+  end
+
+  def test_complex_declaration
+    @xml.declare! :DOCTYPE, :chapter do |x|
+      x.declare! :ELEMENT, :chapter, "(title,para+)".intern
+      x.declare! :ELEMENT, :title, "(#PCDATA)".intern
+      x.declare! :ELEMENT, :para, "(#PCDATA)".intern
+    end
+    expected = %{<!DOCTYPE chapter [
+  <!ELEMENT chapter (title,para+)>
+  <!ELEMENT title (#PCDATA)>
+  <!ELEMENT para (#PCDATA)>
+]>
+}
+    assert_equal expected, @xml.target!
+  end
+end
+
+
+class TestSpecialMarkup < Test::Unit::TestCase
+  def setup
+    @xml = Builder::XmlMarkup.new(:indent=>2)
+  end
+
+  def test_comment
+    @xml.comment!("COMMENT")
+    assert_equal "<!-- COMMENT -->\n", @xml.target!
+  end
+
+  def test_indented_comment
+    @xml.p { @xml.comment! "OK" }
+    assert_equal "<p>\n  <!-- OK -->\n</p>\n", @xml.target!
   end
 
   def test_instruct
-    @xm.instruct! :abc, :version=>"0.9"
-    assert_equal "<?abc version=\"0.9\"?>\n", @xm.target!
+    @xml.instruct! :abc, :version=>"0.9"
+    assert_equal "<?abc version=\"0.9\"?>\n", @xml.target!
   end
 
   def test_indented_instruct
-    @xm.p { @xm.instruct! :xml }
+    @xml.p { @xml.instruct! :xml }
     assert_match %r{<p>\n  <\?xml( version="1.0"| encoding="UTF-8"){2}\?>\n</p>\n},
-      @xm.target!
+      @xml.target!
   end
 
   def test_instruct_without_attributes
-    @xm.instruct! :zz
-    assert_equal "<?zz?>\n", @xm.target!
+    @xml.instruct! :zz
+    assert_equal "<?zz?>\n", @xml.target!
   end
 
   def test_xml_instruct
-    @xm.instruct!
-    assert_match /^<\?xml( version="1.0"| encoding="UTF-8"){2}\?>$/, @xm.target!
+    @xml.instruct!
+    assert_match /^<\?xml( version="1.0"| encoding="UTF-8"){2}\?>$/, @xml.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!
+    @xml.instruct! :xml, :encoding=>"UCS-2"
+    assert_match /^<\?xml( version="1.0"| encoding="UCS-2"){2}\?>$/, @xml.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 }
+      @xml.instruct! { |x| x.hi }
     end
     assert_raises(Builder::IllegalBlockError) do
-      @xm.comment!(:element) { |x| x.hi }
+      @xml.comment!(:element) { |x| x.hi }
     end
   end
 end
 
 class TestIndentedXmlMarkup < Test::Unit::TestCase
   def setup
-    @xm = Builder::XmlMarkup.new(:indent=>2)
+    @xml = 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!
+    @xml.ol { |x| x.li "text" }
+    assert_equal "<ol>\n  <li>text</li>\n</ol>\n", @xml.target!
   end
 
   def test_two_levels
-    @xm.p { |x|
+    @xml.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!
+    assert_equal "<p>\n  <ol>\n    <li>text</li>\n  </ol>\n  <br/>\n</p>\n", @xml.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!
+    @xml = Builder::XmlMarkup.new(:indent=>2, :margin=>4)
+    @xml.name { |x| x.first("Jim") }
+    assert_equal "        <name>\n          <first>Jim</first>\n        </name>\n", @xml.target!
   end
 
   class TestXmlEvents < Test::Unit::TestCase
@@ -231,8 +311,8 @@ class TestIndentedXmlMarkup < Test::Unit::TestCase
     end
 
     def test_indented
-      @xe = Builder::XmlEvents.new(:indent=>2, :target=>@handler)
-      @xe.p { |x| x.b("HI") }
+      @xml = Builder::XmlEvents.new(:indent=>2, :target=>@handler)
+      @xml.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

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.8.1
 specification_version: 1
 name: builder
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.2.0
 date: 2004-10-16
 summary: Builders for MarkUp.
 require_paths: 
@@ -27,10 +27,10 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 files: 
   - lib/builder.rb
-  - lib/builder/blankslate.rb
+  - lib/builder/xmlmarkup.rb
   - lib/builder/xmlbase.rb
+  - lib/builder/blankslate.rb
   - lib/builder/xmlevents.rb
-  - lib/builder/xmlmarkup.rb
   - test/testmarkupbuilder.rb
   - README
   - Rakefile