rsxml 0.1.4 → 0.2.0

data/README.rdoc

@@ -1,6 +1,10 @@
 = rsxml
 
-A Ruby library to translate XML documents into an s-expression representation, and back again
+A Ruby library to translate XML documents into an s-expression representation, and back again, in the style of SXML : http://en.wikipedia.org/wiki/SXML
+
+Why would you want to do this ? Well, s-expressions can be == compared natively in Ruby, are easy to read
+and editors indent them nicely when embedded in code. These features make them very suitable for writing readable
+XML generation code and readable tests for XML generating code
 
 Rsxml represents XML documents as s-expressions thus :
 
@@ -17,14 +21,51 @@ It is easy to convert XML docuemnts to Rsxml representation and back again :
  Rsxml.to_rsxml(xml)
    => ["Foo", {"foofoo"=>"10"}, ["Bar", "barbar"]]
 
-If present, namespaces and namespace prefixes are retained :
+=== Namespaces
 
- xml = Rsxml.to_xml(["foo:foofoo", {"xmlns"=>"http://bar.com/bar", "xmlns:foo"=>"http://foo.com/foo", "foo:bar"=>1, "foo:baz"=>"baz"}])
-   => '<foo:foofoo foo:baz="baz" foo:bar="1" xmlns="http://bar.com/bar" xmlns:foo="http://foo.com/foo"></foo:foofoo>'
+XML namespaces are dealt with straightforwardly. When an XML document is converted to Rsxml, namespaces are preserved, and you can specify namespaces in an Rsxml structure in two ways
+* using QName prefixes and declarative attributes, exactly as with XML
+* using exploded QNames consisting of <tt>[local_name, prefix, uri]</tt> triples and <tt>[local_name, prefix]</tt> pairs
 
+=== Converting to Rsxml
 
- Rsxml.to_rsxml(xml)
-   => ["foo:foofoo", {"foo:baz"=>"baz", "foo:bar"=>"1", "xmlns:foo"=>"http://foo.com/foo", "xmlns"=>"http://bar.com/bar"}]
+When you convert an XML document to Rsxml you can choose either <tt>:xml</tt> or <tt>:exploded</tt> style
+
+==== <tt>:xml</tt> style
+
+In <tt>:xml</tt> style namespaces are declared using attributes, and namespaces are referenced using
+prefixed QNames, just as in XML
+
+ Rsxml.to_rsxml('<foo:foofoo xmlns:foo="http://foo.com/foo" foo:bar="barbar"/>', :style=>:xml)
+   => ["foo:foofoo", {"foo:bar"=>"barbar", "xmlns:foo"=>"http://foo.com/foo"}] 
+
+==== <tt>:exploded</tt> style
+
+In <tt>:exploded</tt> style namespaces are not declared using attributes, and QNames are specified
+using <tt>[local_name, prefix, uri]</tt> triples
+
+ Rsxml.to_rsxml('<foo:foofoo xmlns:foo="http://foo.com/foo" foo:bar="barbar"/>', :style=>:exploded)
+   => [["foofoo", "foo", "http://foo.com/foo"], {["bar", "foo", "http://foo.com/foo"]=>"barbar"}]
+
+=== Converting to XML
+
+Rsxml styles can be mixed, and unnecessary namespace references can be skipped for readability
+
+ Rsxml.to_xml([["foofoo", "foo", "http://foo.com/foo"], {"foo:bar"=>"1", ["baz", "foo"]=>"2"}])
+   => '<foo:foofoo foo:baz="2" foo:bar="1" xmlns:foo="http://foo.com/foo"></foo:foofoo>'
+
+=== Fragments
+
+XML Fragments, without proper namespace declarations, can be parsed by passing a Hash of namespace
+prefix bindings
+
+ Rsxml.to_rsxml('<foo:foofoo foo:bar="barbar"/>', :ns=>{"foo"=>"http://foo.com/foo"}, :style=>:xml)
+   => ["foo:foofoo", {"foo:bar"=>"barbar"}] 
+
+Fragments can be generated similarly :
+
+ Rsxml.to_xml(["foo:foofoo", {"foo:bar"=>"barbar"}], :ns=>{"foo"=>"http://foo.com/foo"})
+   => '<foo:foofoo foo:bar="barbar"></foo:foofoo>'
 
 == Install
 

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.2.0

data/lib/rsxml.rb

@@ -1,26 +1,36 @@
+$: << File.expand_path('../../lib', __FILE__)
+
 require 'nokogiri'
 require 'builder'
+require 'rsxml/util'
+require 'rsxml/namespace'
+require 'rsxml/visitor'
+require 'rsxml/sexp'
+require 'rsxml/xml'
 
 module Rsxml
+  class << self
+    include Util
+    attr_accessor :logger
+  end
+
   module_function
 
-  def check_opts(constraints, opts)
-    (opts||{}).each do |k,v|
-      raise "opt not permitted: #{k}" if !constraints.has_key?(k)
-      constraint = constraints[k]
-    end
+  def log
+    yield(logger) if logger
   end
 
+  TO_XML_OPTS = {:ns=>nil}
+
   # convert an Rsxml s-expression representation of an XML document to XML
   #  Rsxml.to_xml(["Foo", {"foofoo"=>"10"}, ["Bar", "barbar"] ["Baz"]])
   #   => '<Foo foofoo="10"><Bar>barbar</Bar><Baz></Baz></Foo>' 
-  def to_xml(rsxml, &transformer)
-    xml = Builder::XmlMarkup.new
-    Sexp.write_xml(xml, rsxml, &transformer)
-    xml.target!
+  def to_xml(rsxml, opts={})
+    opts = check_opts(TO_XML_OPTS, opts)
+    Sexp.traverse(rsxml, Visitor::WriteXmlVisitor.new, Visitor::Context.new(opts[:ns])).to_s
   end
 
-  TO_RSXML_OPTS = {:ns=>nil}
+  TO_RSXML_OPTS = {:ns=>nil}.merge(Visitor::BuildRsxmlVisitor::OPTS)
 
   # convert an XML string to an Rsxml s-expression representation
   #  Rsxml.to_rsxml('<Foo foofoo="10"><Bar>barbar</Bar><Baz></Baz></Foo>')
@@ -33,10 +43,10 @@ module Rsxml
   #  Rsxml.to_rsxml(fragment, {"foo"=>"http://foo.com/foo", ""=>"http://baz.com/baz"})
   #   => ["foo:Foo", {"foo:foofoo"=>"10", "xmlns:foo"=>"http://foo.com/foo", "xmlns"=>"http://baz.com/baz"}, ["Bar", "barbar"], ["Baz"]]
   def to_rsxml(doc, opts={})
-    check_opts(TO_RSXML_OPTS, opts)
-    doc = Xml.wrap_fragment(doc, opts[:ns])
+    opts = check_opts(TO_RSXML_OPTS, opts)
+    doc = Xml.wrap_fragment(doc, opts.delete(:ns))
     root = Xml.unwrap_fragment(Nokogiri::XML(doc).children.first)
-    Xml.read_xml(root, [])
+    Xml.traverse(root, Visitor::BuildRsxmlVisitor.new(opts)).sexp
   end
 
   # compare two documents in XML or Rsxml. returns +true+ if they are identical, and
@@ -47,140 +57,4 @@ module Rsxml
     Sexp.compare(sexp_a, sexp_b)
   end
 
-  module Sexp
-    module_function
-
-    def write_xml(xml, sexp, path="", &transformer)
-      tag, attrs, children = decompose_sexp(sexp)
-      
-      if transformer
-        txtag, txattrs = transformer.call(tag, attrs, path)
-      else
-        txtag, txattrs = [tag, attrs]
-      end
-      
-      cp = [path, tag].join("/")
-      xml.__send__(txtag, txattrs) do
-        children.each_with_index do |child, i|
-          if child.is_a?(Array)
-            write_xml(xml, child, "#{cp}[#{i}]", &transformer)
-          else
-            xml << child
-          end
-        end
-      end
-    end
-
-    def decompose_sexp(sexp)
-      raise "invalid rsxml: #{rsxml.inspect}" if sexp.length<1
-      tag = sexp[0].to_s
-      if sexp[1].is_a?(Hash)
-        attrs = sexp[1]
-        children = sexp[2..-1]
-      else
-        attrs = {}
-        children = sexp[1..-1]
-      end
-      [tag, attrs, children]
-    end
-
-    class ComparisonError < RuntimeError
-      attr_reader :path
-      def initialize(msg, path)
-        super("[#{path}]: #{msg}")
-        @path = path
-      end
-    end
-
-    def compare(sexpa, sexpb, path=nil)
-      taga, attrsa, childrena = decompose_sexp(sexpa)
-      tagb, attrsb, childrenb = decompose_sexp(sexpb)
-
-      raise ComparisonError.new("element names differ: '#{taga}', '#{tagb}'", path) if taga != tagb
-      raise ComparisonError.new("attributes differ", path) if attrsa != attrsb
-      raise ComparisonError.new("child cound differes", path) if childrena.length != childrenb.length
-
-      path = [path, taga].compact.join("/")
-      (0...childrena.length).each do |i|
-        if childrena[i].is_a?(Array) && childrenb[i].is_a?(Array)
-          compare(childrena[i], childrenb[i], path)
-        else
-          raise ComparisonError.new("content differs: '#{childrena[i]}', '#{childrenb[i]}'", path) if childrena[i] != childrenb[i]
-        end
-      end
-      true
-    end
-  end
-
-  module Xml
-    module_function
-
-    WRAP_ELEMENT = "RsxmlXmlWrapper"
-
-    def wrap_fragment(fragment, ns_prefixes)
-      return fragment if !ns_prefixes
-
-      ns_attrs = Hash[*ns_prefixes.map do |prefix,href|
-                        prefix = nil if prefix.to_s.length == 0
-                        [["xmlns", prefix].compact.join(":"), href]
-                      end.flatten]
-      xml = Builder::XmlMarkup.new
-      xml.__send__(WRAP_ELEMENT, ns_attrs) do
-        xml << fragment
-      end
-      xml.target!
-    end
-
-    def unwrap_fragment(node)
-      if node.name==WRAP_ELEMENT
-        node.children.first
-      else
-        node
-      end
-    end
-
-    def read_xml(node, ns_stack)
-      prefix = node.namespace.prefix if node.namespace
-      tag = node.name
-      ns_tag = [prefix,tag].compact.join(":")
-
-      attrs = read_attributes(node.attributes)
-      attrs = attrs.merge(namespace_attributes(node.namespaces, ns_stack))
-      attrs = nil if attrs.empty?
-
-      children = node.children.map do |child|
-        if child.text?
-          child.text
-        else
-          begin
-            ns_stack.push(node.namespaces)
-            read_xml(child, ns_stack)
-          ensure
-            ns_stack.pop
-          end
-        end
-      end
-
-      [ns_tag, attrs, *children].compact
-    end
-
-    def read_attributes(attrs)
-      Hash[*attrs.map do |n, attr|
-             prefix = attr.namespace.prefix if attr.namespace
-             name = attr.name
-             ns_name = [prefix,name].compact.join(":")
-             [ns_name, attr.value]
-           end.flatten]
-    end
-
-    def namespace_attributes(namespaces, ns_stack)
-      Hash[*namespaces.map do |prefix,href|
-             [prefix, href] if !find_namespace(prefix, ns_stack)
-           end.compact.flatten]
-    end
-
-    def find_namespace(prefix, ns_stack)
-      ns_stack.reverse.find{ |nsh| nsh.has_key?(prefix)}
-    end
-  end
 end

data/lib/rsxml/namespace.rb

@@ -0,0 +1,175 @@
+module Rsxml
+  module Namespace
+    module_function
+    
+    # compact all attribute QNames to Strings
+    def compact_attr_qnames(ns_stack, attrs)
+      Hash[attrs.map do |name,value|
+             [compact_qname(ns_stack, name), value]
+           end]
+    end
+
+    # explode attribute QNames to [LocalPart, prefix, URI] triples,
+    def explode_attr_qnames(ns_stack, attrs)
+      Hash[attrs.map do |name, value|
+             uq_name = explode_qname(ns_stack, name, true)
+             local_name, prefix, uri = uq_name
+             if !prefix || prefix==""
+               [local_name, value]
+             else
+               [uq_name, value]
+             end
+           end]
+    end
+
+    # produce a QName String from a [LocalPart, prefix, URI] triple
+    def compact_qname(ns_stack, name)
+      return name if name.is_a?(String)
+
+      local_part, prefix, uri = name
+      raise "invalid name: #{name}" if !prefix && uri
+      if prefix
+        if prefix!="xmlns"
+          ns = find_namespace_uri(ns_stack, prefix, uri)
+          raise "namespace prefix not bound to a namespace: '#{prefix}'" if ! ns
+        end
+        [prefix, local_part].map{|s| s.to_s unless s.to_s.empty?}.compact.join(':')
+      else
+        local_part
+      end
+    end
+
+    # split a QName into [LocalPart, prefix, URI] triple
+    def explode_qname(ns_stack, qname, attr=false)
+      if qname.is_a?(Array)
+        if qname.length>1 && !qname[1].nil?
+          return qname
+        elsif qname.length>1 && qname[1].nil? && !qname[2].nil?
+          raise "invalid name: #{qname.inspect}"
+        else
+          return qname[0]
+        end
+      end
+
+      local_part, prefix = split_qname(qname)
+      if prefix
+        if prefix=="xmlns" && attr
+          [local_part, prefix]
+        else
+          uri = find_namespace_uri(ns_stack, prefix)
+          raise "namespace prefix not bound: '#{prefix}'" if ! uri
+          [local_part, prefix, uri]
+        end
+      else
+        if attr
+          local_part
+        else
+          default_uri = find_namespace_uri(ns_stack, "")
+          if default_uri
+            [local_part, "", default_uri]
+          else
+            local_part
+          end
+        end
+      end
+    end
+
+    # split a qname String into a [local_part, prefix] pair
+    def split_qname(qname)
+      return qname if qname.is_a?(Array)
+
+      if qname =~ /^[^:]+:[^:]+$/
+        [*qname.split(':')].reverse
+      else
+        qname
+      end
+    end
+
+    # returns the namespace uri for a prefix, if declared in the stack
+    def find_namespace_uri(ns_stack, prefix, uri_check=nil)
+      tns = ns_stack.reverse.find{|ns| ns.has_key?(prefix)}
+      uri = tns[prefix] if tns
+      raise "prefix: '#{prefix}' is bound to uri: '#{uri}', but should be '#{uri_check}'" if uri_check && uri && uri!=uri_check
+      uri
+    end
+
+
+    # extract a Hash of {prefix=>uri} mappings declared in attributes
+    def extract_declared_namespace_bindings(attrs)
+      Hash[attrs.map do |name,value|
+             local_part, prefix, uri = split_qname(name)
+             if (prefix && prefix == "xmlns")
+               [local_part, value]
+             elsif (!prefix && local_part == "xmlns")
+               ["", value]
+             end
+           end.compact]
+    end
+
+    # extract a Hash of {prefix=>uri} mappings from exploded QName tag and attrs
+    def extract_explicit_namespace_bindings(tag, attrs)
+      tag_local_part, tag_prefix, tag_uri = tag
+      ns = {}
+      ns[tag_prefix] = tag_uri if tag_prefix && tag_uri
+
+      attrs.each do |name, value|
+        attr_local_part, attr_prefix, attr_uri = name
+        if attr_prefix && attr_uri
+          raise "bindings clash: '#{attr_prefix}'=>'#{ns[attr_prefix]}' , '#{attr_prefix}'=>'#{attr_uri}'" if ns.has_key?(attr_prefix) && ns[attr_prefix]!=attr_uri
+          ns[attr_prefix] = attr_uri
+        end
+      end
+      ns
+    end
+    
+    # figure out which explicit namespaces need declaring
+    #
+    # +ns_stack+ is the stack of namespace bindings
+    # +ns_explicit+ is the explicit refs for a tag
+    def undeclared_namespace_bindings(ns_stack, ns_explicit)
+      Hash[ns_explicit.map do |prefix,uri|
+             [prefix, uri] if !find_namespace_uri(ns_stack, prefix, uri)
+           end.compact]
+    end
+
+    # produce a Hash of namespace declaration attributes with exploded
+    # QNames, from 
+    # a Hash of namespace prefix bindings
+    def exploded_namespace_declarations(ns)
+      Hash[ns.map do |prefix, uri|
+             if prefix==""
+               ["xmlns", uri]
+             else
+               [[prefix, "xmlns"], uri]
+             end
+           end]
+    end
+
+    # merges two sets of namespace bindings, raising error on clash
+    def merge_namespace_bindings(ns1, ns2)
+      m = ns1.clone
+      ns2.each do |k,v|
+        raise "bindings clash: '#{k}'=>'#{m[k]}' , '#{k}'=>'#{v}'" if m.has_key?(k) && m[k]!=v
+        m[k]=v
+      end
+      m
+    end
+
+    # given the existing +ns_stack+ of ns bindings, a +tag+ and it's +attributes+,
+    # return a pair <tt>[ns_bindings, ns_additional_decls]</tt> containing
+    # ns bindings for the stack, and additional required (exploded) namespace 
+    # declarations to be added to the attributes
+    def namespace_bindings_declarations(ns_stack, tag, attrs)
+      ns_declared = extract_declared_namespace_bindings(attrs)
+      ns_explicit = extract_explicit_namespace_bindings(tag, attrs)
+      ns_undeclared = undeclared_namespace_bindings(ns_stack + [ns_declared], ns_explicit)
+      ns_bindings = merge_namespace_bindings(ns_declared, ns_undeclared)
+
+      # and declarations for undeclared namespaces
+      ns_additional_decls = exploded_namespace_declarations(ns_undeclared)
+      
+      [ns_bindings, ns_additional_decls]
+    end
+
+  end
+end

data/lib/rsxml/sexp.rb

@@ -0,0 +1,90 @@
+module Rsxml
+  module Sexp
+
+    module_function
+
+    # pre-order traversal of the sexp, calling methods on
+    # the visitor with each node
+    def traverse(sexp, visitor, context=Visitor::Context.new)
+      tag, attrs, children = decompose_sexp(sexp)
+      
+      ns_bindings, ns_additional_decls = Namespace::namespace_bindings_declarations(context.ns_stack, tag, attrs)
+
+      context.ns_stack.push(ns_bindings)
+
+      etag = Namespace::explode_qname(context.ns_stack, tag)
+      eattrs = Namespace::explode_attr_qnames(context.ns_stack, attrs)
+
+      eattrs = eattrs.merge(ns_additional_decls)
+
+      begin
+        visitor.tag(context, etag, eattrs) do
+          context.push_node([etag, eattrs])
+          begin
+            children.each_with_index do |child, i|
+              if child.is_a?(Array)
+                traverse(child, visitor, context)
+              else
+                visitor.text(context, child)
+                context.processed_node(child)
+              end
+            end
+          ensure
+            context.pop_node
+          end
+        end
+
+      ensure
+        context.ns_stack.pop
+      end
+
+      visitor
+    end
+
+    # decompose a sexp to a [tag, attrs, children] list
+    def decompose_sexp(sexp)
+      raise "invalid rsxml: #{rsxml.inspect}" if sexp.length<1
+      if sexp[0].is_a?(Array)
+        tag = sexp[0]
+      else
+        tag = sexp[0].to_s
+      end
+      if sexp[1].is_a?(Hash)
+        attrs = sexp[1]
+        children = sexp[2..-1]
+      else
+        attrs = {}
+        children = sexp[1..-1]
+      end
+      [tag, attrs, children]
+    end
+
+    class ComparisonError < RuntimeError
+      attr_reader :path
+      def initialize(msg, path)
+        super("[#{path}]: #{msg}")
+        @path = path
+      end
+    end
+
+    def compare(sexpa, sexpb, path=nil)
+      taga, attrsa, childrena = decompose_sexp(sexpa)
+      tagb, attrsb, childrenb = decompose_sexp(sexpb)
+
+      raise ComparisonError.new("element names differ: '#{taga}', '#{tagb}'", path) if taga != tagb
+      raise ComparisonError.new("attributes differ", path) if attrsa != attrsb
+      raise ComparisonError.new("child count differs", path) if childrena.length != childrenb.length
+
+      path = [path, taga].compact.join("/")
+      (0...childrena.length).each do |i|
+        if childrena[i].is_a?(Array) && childrenb[i].is_a?(Array)
+          compare(childrena[i], childrenb[i], path)
+        else
+          raise ComparisonError.new("content differs: '#{childrena[i]}', '#{childrenb[i]}'", path) if childrena[i] != childrenb[i]
+        end
+      end
+      true
+    end
+  end
+
+end