XMLROCS 0.0.1

data/LICENSE

@@ -0,0 +1,28 @@
+
+Copyright (c) 2008, Andreas Meingast, <ameingast@gmail.com>, http://yomi.at
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, 
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright 
+      notice, this list of conditions and the following disclaimer in the 
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the person nor the names of its 
+      contributors may be used to endorse or promote products derived 
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -0,0 +1,207 @@
+= About
+
+XMLROCS is short for XML Ruby ObjeCtS. It is a library that allows to 
+map XML data to Ruby objects.
+
+XMLROCS is kind of a poor man's DOM. It provides basic access to attributes
+and child elements so you can comfortably work with XML data.
+Generally speaking, you can manipulate your XML data in true Ruby OO style.
+
+== Creating an XMLROC
+ 
+The following XML data will be used in the following examples:
+
+  xml = <<-EOS
+  <products name="Computers">
+    This is a mixed content for the following products:
+    <product id="2">Dell</product>
+    <product id="1">Acer</product>
+    <product id="3">Apple</product>
+    Another text.
+    <product id="4">HP</product>
+  </products>
+  EOS
+
+  o = XMLROCS::XMLNode.new :text => xml # => produces an XMLROC
+
+If you already have an REXML::Document flying arround you can do the following:
+
+  rexml_document =  REXML::Document.new(xml)
+  o = XMLROCS::XMLNode.new :root => rexml_document.root
+
+
+== Accessing and Modifiying Attributes
+
+All attributes are available via the []-operator. Attributenames are stored
+as symbols, so the []-operator behaves pretty much like a Hash with symbol-keys.
+Let's have a look at it:
+
+  o[:name] # => Computers
+  o[:i_m_not_there] # => nil
+
+You can also modify attributes:
+
+  o[:name] = o[:name].reverse # => sretupmoC
+
+which is pretty much equivalent to:
+
+  o[:name].reverse! # => sretupmoC
+
+The other way to handle attributes is to access the @attributes accessor, which
+acts as a hash with the following format:
+
+  { :atrribute_name => "attribute_value" }
+
+Just like with the []-operator you can also modify the accessor-variable.
+
+
+== Accessing and Modifiyng Children
+
+Children can be accessed via instance methods or the @children accessor.
+Just like the @attributes accessor, the @children accessor has the following 
+format:
+
+  { :child_name => [ XMLNode, ... ] }
+
+:child_name is the name of the tag of the child, while XMLNode is an array
+containing all children with the name.
+Still, this solution is mainly used for internal representation and it is
+pretty tedious to work with, because you _always_ have to handle the array,
+even when you know that there is only one child (probably garuanteed by some
+DTD or XSD).
+Instance methods solve this problem by ALWAYS returning a direct XMLNode. 
+If there are n > 1 children with the same name, the instance method will
+return the last (wrt to appearance in the XML data) element.
+You can access all children with the same name by appending a '!' 
+to the instance_method just like this:
+
+  o.tag_name! # => [ XMLNode, ... ]
+
+Some other examples:
+
+  # Determine the id of the Apple-product
+  o.product!.select { |x| x == "Apple" }.first[:id] # => "3"
+
+  # Determine the ids of all products whose name is not empty
+  o.product!.select { |x| not x.empty? } # => ["Dell", "Acer", "Apple", "HP"]
+
+  # Determine the name of the product with id == "3"
+  o.product!.select { |x| x[:id] == "3" }.first # => "Apple"
+
+  # produce a hashmap { id => productname }
+  o.product!.inject({}) { |h,x| h.merge({ x[:id] => x }) } # => {"1"=>"Acer", "2"=>"Dell", "3"=>"Apple", "4"=>"HP"}
+  
+  # sort by product id
+  o.product!.sort { |a,b| a[:id] <=> b[:id] } # => ["Acer", "Dell", "Apple", "HP"]
+
+  # get the last product (wrt order of appearance in the xml text)
+  o.product # => HP
+
+  # apply some changes and write back the xml
+  o.product!.each { |x| x[:id] = "#{x[:id].to_i * 10}" }
+  o.to_xml # => 
+  '<products name="Computers">
+     <product id="20">Dell</product>
+     <product id="10">Acer</product>
+     <product id="30" >Apple</product>
+     <product id="40">HP</product>
+  </products>'
+
+  o.product!.each { |x| x.set_text(x.reverse) }
+  o.to_xml # => 
+  '<products name="Computers">
+     <product id="20">lleD</product>
+     <product id="10">recA</product>
+     <product id="30">elppA</product>
+     <product id="40">PH</product>
+  </products>'
+
+== Appending and Removing Children and Attributes
+
+To add attributes, just add a new entry to the attributes accessor:
+
+  o[:short_name] = "comp" 
+  puts o.to_xml # => 
+  <products name="Computers"  short_name="comp">
+    ...
+  </products>
+
+To remove an attribute, you have to call the delete_attribute method
+
+  o.delete_attribute!(:short_name)
+  puts o.to_xml # => 
+  <products name="Computers">
+    ...
+  </products>
+
+
+To add children, call the << operator with an XMLNode as argument.
+
+  # create the child node
+  child = XMLROCS::XMLNode.new(:text => '<product id="5">Fujitsu</product>')
+  # add it to the o-node
+  o << child
+  puts o.product!.select { |x| x[:id] == "5" }.first # => Fujitsu
+
+To remove a child, call the >> operator with the childname as argument.
+You can also provide a block to provide a more fine-grained filter.
+The block will then be called with a child XMLNode as an argument.
+
+  # remove all children with id == "5"
+  o.>> { |child| child[:id] == "5" }
+
+Whenever you provide a block, you have to bind the >> operator to 
+the object, because of the lower precedence of the infix call.
+
+  # remove all product children with id == "5"
+  o.>>(:product) { |child| child[:id] == "5" }
+
+  # remove all children called :product
+  o >> :product
+
+== Walking over the XML-Tree Structure
+
+All iterating is done in Preorder, but you can override the default behaviour
+by setting the traversal accessor.
+
+Currently the library supports the following traversals:
+
+  o.traversal = :preorder # default
+  o.traversal = :inorder 
+  o.traversal = :postorder 
+
+You can inject the XML Tree with a left associative function, and map
+over the tree by calling map or map! which will not produce an Array but
+another XML Tree.
+
+== Aggregating
+
+This library does not provide direct support for XPath, but you can emulate
+it's behaviour with iterators and closures.
+
+Suppose you want to select all products whose id is smaller than 5. In
+XPath you probably would come up with something like this:
+
+  //[@id < 5]
+
+With XMLROCS there is no need for XPaths, because you can do the very same
+thing easily in Ruby:
+
+  o.select { |node| node[:id] && node[:id].to_i < 5 }
+
+Here's another one that builds an Array of all leafs:
+  
+  o.select { |node| node.leaf? }
+
+which is equivalent to:
+
+  o.select { |node| node.children.empty? }
+
+Here's another one. Select all nodes that have no attributes:
+
+  o.select { |node| node.attributes.empty? }
+
+It's actually quite handy, since your closure gets called on all children
+and the object itself and then selects which elements you want to keep.
+The big advandage here is, that you can actually do anything in the closure
+that Ruby can do.

data/TODO

@@ -0,0 +1,15 @@
+= TODO
+
+== Typing
+
+Introduce some kind of typing for text values, so you can say:
+
+  o = XMLROCS::XMLNode.new :text => some_text
+  o.type :child => Integer
+  o.type :child => { :attribute => Integer }
+  o.type :child => { :attribute => Array }
+  
+  
+== Performance
+
+The initialization of a whole XMLNode Tree is bad. Improve it.

data/lib/xmlrocs.rb

@@ -0,0 +1,327 @@
+#
+# Copyright (c) 2008, Andreas Meingast, <ameingast@gmail.com>, http://yomi.at
+# 
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+# 
+#     * Redistributions of source code must retain the above copyright notice, 
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright 
+#       notice, this list of conditions and the following disclaimer in the 
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of the person nor the names of its 
+#       contributors may be used to endorse or promote products derived 
+#       from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+require 'rexml/document'
+
+#
+# For more information, have a look at the README or the XMLNode class 
+# documentation.
+#
+module XMLROCS
+  
+  #
+  # Represents an XML Element. You can access and modify it's children
+  # and attributes.
+  #
+  # Each XMLNode has exactly one parent (that happens to be nil if the node
+  # is the root of the tree) and a (possibly empty) list of children.
+  #
+  # It also has a name (the name of the XML tag) that can be modified.
+  #
+  # You can compare two XMLNodes or an XMLNode and a String. When you provide
+  # a String, only the text value of the XMLNode is compared.
+  #
+  # You can enumerate the XMLNode Tree in the traversal-order defined
+  # in the @traversal accessor.
+  #
+  # For more information have a look at the README or instance method 
+  # documentation.
+  #
+  class XMLNode < String
+    include Comparable
+    include Enumerable
+
+    #
+    # Hash containing the children of the current Node. The Hash has the
+    # following
+    # structure:
+    #
+    #   { :childname => [ XMLNode, ... ] }
+    #
+    # You can either use the >> or << operators to modify children or use 
+    # this accessor directly. 
+    attr_reader :children
+    
+    #
+    # Hash containing the attributes of the current Node:
+    #
+    #   { :attribute_name => "Attribute" }
+    #
+    # Attributes can also be modified using this accessor.
+    attr_reader :attributes
+    
+    # 
+    # The parent of the current Node. The parent of the Root-Node is nil.
+    #
+    attr_reader :parent
+    
+    #
+    # The name of the current Node. 
+    #
+    # Example:
+    #   x = XMLNode.new :text => '<a></a>'
+    #   x.xmlname # => :a
+    #
+    attr_reader :xmlname
+    
+    #
+    # Defines the order in which the tree is traversed.
+    #
+    # The following traversals are suppported:
+    #   :preorder
+    #   :postorder
+    #   :inorder
+    #
+    attr_accessor :traversal
+    
+    #
+    # Create a new XMLNode
+    # You have to either provide an REXML::Element as options[:root] or
+    # plaintext xml data as options[:text]. Otherwise an ArgumentError will
+    # be thrown.
+    #
+    # Supported options:
+    #   :root       # => REXML::Element that will be traversed.
+    #   :text       # => XML plaintext that will be parsed by REXML and then
+    #                    traversed.
+    #   :nil        # => Will create a nil node. Useful if you need a global
+    #                    parent.
+    #   :traversal  # => The traversal order. See traversal.
+    #
+    def initialize(options = {})
+      xmlroot = if options[:root]
+        options[:root]
+      elsif options[:text]
+        REXML::Document.new(options[:text]).root
+      elsif options[:nil]
+        nil
+      end
+      raise(ArgumentError, "Undefined") if !xmlroot and !options[:nil]
+      @children, @attributes = {}, {}
+      @parent ,@traversal = options[:parent], options[:traversal] || :preorder
+      @xmlname = xmlroot ? xmlroot.name.to_sym : :NIL
+      set_text(xmlroot ? xmlroot.get_text.to_s : '')
+      if xmlroot 
+        xmlroot.attributes.each { |k,v| self[k.to_sym] = v }
+      
+        # this recursions makes the whole library slow. basically we have
+        # all information in xmlroot, so no recursive calls would be necessary
+        xmlroot.select { |e| e.class == REXML::Element }.each do |e| 
+          self << XMLNode.new({ :root => e, :parent => self })
+        end
+      end
+    end
+
+    # 
+    # Access attributes by name. Attributenames are stored as symbols.
+    #
+    def [](attribute)
+      @attributes[attribute]
+    end
+
+    #
+    # Modify attributes. Behaves like a Hash. Keys are symbols by convention, 
+    # values are XMLNode-objects.
+    #
+    def []=(attribute, value)
+      @attributes[attribute] = value
+    end
+    
+    #
+    # Delete attributes. attribute has to be a symbol with the name of the
+    # attribute you want to delete.
+    #
+    def delete_attribute!(attribute)
+      @attributes.delete(attribute)
+    end
+
+    #
+    # Append a child. child has to be an XMLNode or a String that contains
+    # the XML data in plaintext.
+    #
+    def <<(child)
+      return self << XMLROCS::XMLNode.new(:text => child) if is_real_string(child)
+      (@children[child.xmlname] = (@children[child.xmlname] || []) << child).last
+    end
+
+    # 
+    # Remove a child from the current XMLNode.
+    # Providing only a childname, it will delete all children with the given
+    # name.
+    # If you also provide a block, the block will be evaluated with each child
+    # as an argument and according to the return value of the call the child
+    # will be deleted or not (when the block returns true, the child will be
+    # deleted).
+    # If you provide a block you can optionally filter the children by
+    # providing a childname so only children with the given name will be
+    # evaluated.
+    #
+    def >>(childname = nil)
+      if block_given?
+        @children.select { |k,v| childname ? k == childname : true }.each do |k,v| 
+          v.reject! { |child| yield(child) }
+        end
+      else
+        @children.delete(childname)
+      end
+    end
+    
+    # 
+    # Returns an array of all XMLNodes in the order that is specified in the
+    # traversal accessor.
+    #
+    def all(name = nil)
+      name ? select { |x| x.xmlname == name } : traverse
+    end
+    
+    # 
+    # Maps a function over the XMLNode-tree and returns a new XMLNode-tree
+    # with the mapped values.
+    #
+    def map(&block)
+      dup.map!(&block)
+    end
+    
+    # 
+    # Maps a function over the current XMLNode-tree.
+    #
+    def map!(&block)  
+      traverse.map!(&block)
+      self
+    end
+     
+    #
+    # Iterates over the XMLNode-tree in the order that is specified in the
+    # traversal accessor.
+    #   
+    def each(&block)
+      traverse.each(&block)
+    end
+    
+    # 
+    # Deep-copies the Tree.
+    #
+    def dup
+      XMLROCS::XMLNode.new(:text => to_xml)
+    end
+
+    #
+    # If a tag is provided it checks if the child with the given name has 
+    # siblings.
+    # Otherwise it does the same for the current node.
+    #
+    def single?(tag = nil)
+      tag ? @children[tag].length == 1 : @parent.children[@xmlname].length == 1
+    end
+
+    # 
+    # If a tag is provided it checks if the child with the given name is a leaf.
+    # Otherwise it does the same for the current node.
+    #
+    def leaf?(tag = nil)
+      tag ? children[tag].all? { |x| x.leaf? } : children.empty?
+    end
+
+    # 
+    # Generates an array of all leafs in the order specified in the traversal 
+    # accessor.
+    #
+    def leafs
+      traverse.select { |x| x.leaf? }
+    end
+
+    # 
+    # Sets the text of the current node to text.
+    #
+    def set_text(text)
+      # special match for whitespace-only
+      return gsub!(self.to_s, "") if text =~ /^\s+$/
+      gsub!(self.to_s, text)
+    end
+
+    #
+    # Deep-compares to XMLNodes.
+    # 
+    def ==(other)
+      # pure string comparison
+      return super(other) if is_real_string(other)
+      return false unless other == self.to_s
+      [ [ self, other ], [ other, self ] ].each do |a,b|
+        a.children.each do |k,v| 
+          return false if !b.children.has_key?(k) or v != b.children[k]
+        end
+      end
+      true
+    end
+
+    # 
+    # Deep-transforms the current node into plaintext XML. If flat is true,
+    # all children will be omitted.
+    #
+    def to_xml(flat = false)
+      "<#{@xmlname} " + @attributes.map { |k,v| "#{k}=\"#{v}\" "}.join(" ") + ">" + 
+        (flat ? "" : (leaf? ? self.to_s : @children.values.flatten.map { |e| e.to_xml }.join)) + 
+      "</#{@xmlname}>"
+    end
+    
+    def method_missing(method, *args)
+      if method.to_s[-1] == 33 and @children.has_key?(real_method = method.to_s.chomp("!").to_sym)
+        return @children[real_method] 
+      end
+      return @children[method].last if @children.has_key?(method)
+      super(method, *args)
+    end
+
+    private
+    
+    def preorder
+      children.values.flatten.inject([self]) { |cur,child| cur + child.send(:preorder) }
+    end
+    
+    def inorder
+      preorder # FIXME
+    end
+    
+    def postorder
+      preorder # FIXME
+    end
+    
+    def traverse
+      self.send(@traversal)
+    end
+    
+    #
+    # helper method
+    #
+    def is_real_string(what)
+      what.is_a?(String) and !what.is_a?(XMLNode)
+    end
+  end
+end