jordi-xml_struct 0.2.1 → 0.9.0

data/README.rdoc

@@ -0,0 +1,152 @@
+= XMLStruct
+
+(This is inspired by Python's +xml_objectify+)
+
+XMLStruct attempts to make the accessing of small, well-formed XML structures
+convenient, by using dot notation to represent both attributes and child
+elements whenever possible.
+
+XML parsing libraries (in general) have interfaces that are useful when
+one is using XML for its intended purpose, but cumbersome when one always
+sends the same XML structure, and always process all of it in the same
+way. This one aims to be a bit different.
+
+== Example usage
+
+  <recipe name="bread" prep_time="5 mins" cook_time="3 hours">
+    <title>Basic bread</title>
+    <ingredient amount="8" unit="dL">Flour</ingredient>
+    <ingredient amount="10" unit="grams">Yeast</ingredient>
+    <ingredient amount="4" unit="dL" state="warm">Water</ingredient>
+    <ingredient amount="1" unit="teaspoon">Salt</ingredient>
+    <instructions easy="yes" hard="false">
+      <step>Mix all ingredients together.</step>
+      <step>Knead thoroughly.</step>
+      <step>Cover with a cloth, and leave for one hour in warm room.</step>
+      <step>Knead again.</step>
+      <step>Place in a bread baking tin.</step>
+      <step>Cover with a cloth, and leave for one hour in warm room.</step>
+      <step>Bake in the oven at 180(degrees)C for 30 minutes.</step>
+    </instructions>
+  </recipe>
+
+  require 'xml_struct'
+  recipe = XMLStruct.new io_with_recipe_xml_shown_above
+
+  recipe.name                      => "bread"
+  recipe.title                     => "Basic bread"
+
+  recipe.ingredients.is_a?(Array)  => true
+  recipe.ingredients.first.amount  => "8" # Not a Fixnum. Too hard. :(
+
+  recipe.instructions.easy?        => true
+
+  recipe.instructions.first.upcase => "MIX ALL INGREDIENTS TOGETHER."
+  recipe.instructions.steps.size   => 7
+
+== Installation instructions
+
+    sudo gem install jordi-xml_struct --source http://gems.github.com
+
+== Motivation
+
+XML is an *extensible* markup language. It is extensible because it is
+meant to define markup languages for *any* type of document, so new tags
+are needed depending on the problem domain.
+
+Sometimes, however, XML ends up being used to solve a much simpler problem:
+the issue of passing a data-structure over the network, and/or between two
+different languages. Tools like +JSON+ or +YAML+ are a much better fit for
+this kind of job, but one doesn't always have that luxury.
+
+== Caveats
+
+The dot notation is used as follows. For the given file:
+
+  <outer id="root" name="foo">
+    <name>Outer Element</name>
+  </outer>
+
++outer.name+ is the +name+ *element*. Child elements are always looked up
+first, then attributes. To access the attribute in the case of ambiguity,
+use outer[:attr => 'name'].
+
++outer.id+ is really Object#id, because all of the object methods are
+preserved (this is on purpose). To access the attribute +id+, use
+outer[:attr => 'id'], or outer['id'] since there's no element/attribute
+ambiguity.
+
+== Features & Problems
+
+=== Collection auto-folding
+
+Similar to XmlSimple, XMLStruct folds same named elements at the same
+level. For example:
+
+    <student>
+      <name>Bob</name>
+      <course>Math</course>
+      <course>Biology</course>
+    </student>
+
+    student = XMLStruct.new(xml_file)
+
+    student.course.is_a? Array       => true
+    student.course.first == 'Math'   => true
+    student.course.last  == 'Biology => true
+
+=== Collection pluralization
+
+With the same file from the +Collection auto-folding+ section above, you
+also get this (courtesy of +ActiveSupport+'s +Inflector+):
+
+    student.courses.first == student.course.first => true
+
+=== Collection proxy
+
+  Sometimes, collections are expressed with a container element in XML:
+
+    <student>
+      <name>Bob</name>
+      <courses>
+        <course>Math</course>
+        <course>Biology</course>
+      </courses>
+    </student>
+
+In this case, since the container element +courses+ has no text element
+of its own, and it only has elements of one name under it, it delegates
+all methods it doesn't contain to the collection below, so you get:
+
+    student.courses.collect { |c| c.downcase.to_sym } => [:math, :biology]
+
+=== Question mark notation
+
+Strings that look like booleans are "booleanized" if called by their
+question mark names (such as +enabled?+)
+
+=== Adapters
+
+XMLStruct supports different adapters to do the actual XML parsing. It ships
+with +REXML+ and +Hpricot+ adapters. If +Hpricot+ is detected it gets used,
+otherwise +REXML+ is used as a fallback.
+
+=== Recursive
+
+The design of the adapters assumes parsing of the objects recursively. Deep
+files are bound to throw +SystemStackError+, but for the kinds of files I
+need to read, things are working fine so far. In any case, stream parsing
+is on the TODO list.
+
+=== Incomplete
+
+It most likely doesn't work with a ton of features of complex XML files. I
+will always try to accomodate those, as long as they don't make the basic
+usage more complex. As usual, patches welcome.
+
+== Legal
+
+Copyright (c) 2008 Jordi Bunster, released under the MIT license
+
+
+

data/WHATSNEW

@@ -1,3 +1,13 @@
+* 0.9.0 (2008-10-15):
+  - Added support for plug-able adapters
+  - Backported REXML code as an adapter, added Hpricot adapter
+  - Performance: XMLStruct now decorates objects lazily
+  - Performance: XMLStruct uses the Hpricot adapter if possible, otherwise
+    REXML as a fallback
+  - API Change: XMLStruct.new is mostly delegated to the adapter, and both
+    included adapters behave the same: a String is considered to be
+    XML data, anything else is probed for #read and then #to_s
+
 * 0.2.1 (2008-10-13):
   - Fixed a bug where attributes with dashes would crash the party
 

data/lib/xml_struct/adapters/hpricot.rb

@@ -0,0 +1,47 @@
+module XMLStruct::Adapters::Hpricot
+
+  # Can take a String of XML data, or anything that responds to
+  # either +read+ or +to_s+.
+  def self.new(duck)
+    case
+      when duck.is_a?(::Hpricot::Elem) : Element.new(duck)
+      when duck.is_a?(::String)        : new(::Hpricot::XML(duck).root)
+      when duck.respond_to?(:read)     : new(duck.read)
+      when duck.respond_to?(:to_s)     : new(duck.to_s)
+      else raise "Don't know how to deal with '#{duck.class}' object"
+    end
+  end
+
+  private ##################################################################
+
+  class Element # :nodoc:
+    attr_reader :raw, :name, :value, :attributes, :children
+
+    def text_value(raw)
+      raw.children.select do |e|
+        (e.class == ::Hpricot::Text) && !e.to_s.blank?
+      end.join.to_s
+    end
+
+    def cdata_value(raw)
+      raw.children.select do |e|
+        (e.class == ::Hpricot::CData) && !e.to_s.blank?
+      end.first.to_s
+    end
+
+    def initialize(xml)
+      @raw, @name, @attributes, @children = xml, xml.name, {}, []
+
+      @attributes = xml.attributes
+      xml.children.select { |e| e.elem? }.each do |e|
+        @children << self.class.new(e)
+      end
+
+      @value = case
+        when (not text_value(@raw).blank?)  : text_value(@raw)
+        when (not cdata_value(@raw).blank?) : cdata_value(@raw)
+        else ''
+      end
+    end
+  end
+end

data/lib/xml_struct/adapters/rexml.rb

@@ -0,0 +1,34 @@
+module XMLStruct::Adapters::REXML
+  require 'rexml/document'
+
+  # Can take a String of XML data, or anything that responds to
+  # either +read+ or +to_s+.
+  def self.new(duck)
+    case
+      when duck.is_a?(::REXML::Element) : Element.new(duck)
+      when duck.is_a?(::String)    : new(::REXML::Document.new(duck).root)
+      when duck.respond_to?(:read) : new(duck.read)
+      when duck.respond_to?(:to_s) : new(duck.to_s)
+      else raise "Don't know how to deal with '#{duck.class}' object"
+    end
+  end
+
+  private ##################################################################
+
+  class Element # :nodoc:
+    attr_reader :raw, :name, :value, :attributes, :children
+
+    def initialize(xml)
+      @raw, @name, @attributes, @children = xml, xml.name, {}, []
+
+      @attributes = xml.attributes
+      xml.each_element { |e| @children << self.class.new(e) }
+
+      @value = case
+        when (not xml.text.blank?)  : xml.text.to_s
+        when (xml.cdatas.size >= 1) : xml.cdatas.first.to_s
+        else ''
+      end
+    end
+  end
+end

data/lib/xml_struct/array_notation.rb

@@ -0,0 +1,44 @@
+module XMLStruct::ArrayNotation
+  # Array-bracket (+[]+) notation access to elements and attributes. Use
+  # when the element or attribute you need to reach is not reachable via dot
+  # notation (because it's not a valid method name, or because the method
+  # exists, such as +id+ or +class+).
+  #
+  # It also supports a hash key, which is used to reach attributes named
+  # the same as elements in the same depth level (which otherwise go first)
+  #
+  # All of this is a lot easier to explain by example:
+  #
+  #   <article id="main_article" author="j-random">
+  #     <author>J. Random Hacker</author>
+  #   </article>
+  #
+  #   article.id                 => 9314390            # Object#id
+  #   article[:id]               => "main_article"     # id attribute
+  #   article[:author]           => "J. Random Hacker" # <author> element
+  #   article[:attr => 'author'] => "j-random"         # author attribute
+  #
+  # Valid keys for the hash notation in the example above are +:attr+,
+  # +:attribute+, +:child+, and +:element+.
+  def [](name)
+    return @__target[name] if @__target && name.is_a?(Numeric)
+
+    unless name.is_a? Hash
+      key = name.to_sym
+
+      return @__children[key]   if @__children.has_key?(key)
+      return @__attributes[key] if @__attributes.has_key?(key)
+    end
+
+    raise 'one and only one key allowed' if name.size != 1
+
+    case (param = name.keys.first.to_sym)
+      when :element   : @__children[name.values.first.to_sym]
+      when :child     : @__children[name.values.first.to_sym]
+      when :attr      : @__attributes[name.values.first.to_sym]
+      when :attribute : @__attributes[name.values.first.to_sym]
+      else raise %{ Invalid key :#{param.to_s}.
+        Use one of :element, :child, :attr, or :attribute }.squish!
+    end
+  end
+end

data/lib/xml_struct/blankish_slate.rb

@@ -1,4 +1,4 @@
-class XMLStruct::BlankishSlate
+class XMLStruct::BlankishSlate # :nodoc:
 
   instance_methods.each do |m|
     undef_method m unless m =~ /^__/         ||

data/lib/xml_struct/collection_proxy.rb

@@ -1,10 +1,14 @@
-class XMLStruct::CollectionProxy < XMLStruct::BlankishSlate
+class XMLStruct::CollectionProxy < XMLStruct::BlankishSlate # :nodoc:
   def initialize(target)
     @__children, @__attributes, @__target = {}, {}, target
   end
 
+  private ##################################################################
+
   def method_missing(m, *a, &b) # :nodoc:
-    answer = __question_answer(m, *a, &b)
-    answer.nil? ? (@__target.__send__(m, *a, &b) if @__target) : answer
+    dp = __question_dispatch(m, *a, &b)
+    dp = __dot_notation_dispatch(m, *a, &b) if dp.nil?
+    dp = @__target.__send__(m, *a, &b) if @__target.respond_to?(m) && dp.nil?
+    dp
   end
 end

data/lib/xml_struct/default_adapter.rb

@@ -0,0 +1,15 @@
+module XMLStruct # :nodoc:
+  module Adapters # :nodoc:
+    ADAPTERS_PATH = File.join(File.dirname(__FILE__), 'adapters')
+
+    Default = begin
+      require 'hpricot'
+      require File.join(ADAPTERS_PATH, 'hpricot')
+      Hpricot
+    rescue LoadError
+      require File.join(ADAPTERS_PATH, 'rexml')
+      REXML
+    end
+  end
+end
+

data/lib/xml_struct/method_missing_dispatchers.rb

@@ -0,0 +1,43 @@
+module XMLStruct::MethodMissingDispatchers # :nodoc:
+
+  private ##################################################################
+
+  def __question_dispatch(meth, *args, &block)
+    return unless meth.to_s.match(/\?$/) && args.empty? && block.nil?
+
+    method_sans_question = meth.to_s.chomp('?').to_sym
+
+    if boolish = __send__(method_sans_question).downcase
+      bool = case
+        when %w[ true yes t y ].include?(boolish) : true
+        when %w[ false no f n ].include?(boolish) : false
+        else nil
+      end
+
+      unless bool.nil? # Fun, eh?
+        instance_eval %{ def #{meth}; #{bool ? 'true' : 'false'}; end }
+      end
+
+      bool
+    end
+  end
+
+  def __dot_notation_dispatch(meth, *args, &block)
+    return unless args.empty? && block.nil?
+
+    if @__children.has_key?(singular = meth.to_s.singularize.to_sym) &&
+          @__children[singular].is_a?(Array)
+
+      instance_eval %{ def #{meth}; @__children[%s|#{singular}|]; end }
+      @__children[singular]
+
+    elsif @__children.has_key?(meth)
+      instance_eval %{ def #{meth}; @__children[%s|#{meth}|]; end }
+      @__children[meth]
+
+    elsif @__attributes.has_key?(meth)
+      instance_eval %{ def #{meth}; @__attributes[%s|#{meth}|]; end }
+      @__attributes[meth]
+    end
+  end
+end

data/lib/xml_struct/string.rb

@@ -9,7 +9,7 @@ module XMLStruct::String
   # and returns accordingly. If not, just returns the string.
   def rb
     @__rb ||= case
-      when (self !~ /\S/)                          : nil
+      when (self !~ /\S/)                          : ''
       when match(/[a-zA-Z]/)                       : ::String.new(self)
       when match(/^[+-]?\d+$/)                     : self.to_i
       when match(/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/) : self.to_f
@@ -25,7 +25,11 @@ module XMLStruct::String
     (self !~ /\S/) && @__children.blank? && @__attributes.blank?
   end
 
+  private ##################################################################
+
   def method_missing(m, *a, &b) # :nodoc:
-    __question_answer(m, *a, &b)
+    dp = __question_dispatch(m, *a, &b)
+    dp = __dot_notation_dispatch(m, *a, &b) if dp.nil?
+    dp
   end
 end

data/lib/xml_struct.rb

@@ -1,53 +1,59 @@
 require 'rubygems'
 require 'activesupport'
-require 'rexml/document'
 
-module XMLStruct; end
+module XMLStruct
+
+  unless defined?(BASE_DIR) # Slow call
+    BASE_DIR = File.join(File.dirname(__FILE__), 'xml_struct')
+  end
 
-require File.join(File.dirname(__FILE__), 'xml_struct', 'blankish_slate')
-require File.join(File.dirname(__FILE__), 'xml_struct', 'collection_proxy')
-require File.join(File.dirname(__FILE__), 'xml_struct', 'string')
-require File.join(File.dirname(__FILE__), 'xml_struct', 'common_behaviours')
+  require File.join(BASE_DIR, 'default_adapter')
+  require File.join(BASE_DIR, 'method_missing_dispatchers')
+  require File.join(BASE_DIR, 'array_notation')
+  require File.join(BASE_DIR, 'blankish_slate')
+  require File.join(BASE_DIR, 'collection_proxy')
+  require File.join(BASE_DIR, 'string')
 
-module XMLStruct
+  def self.adapter=(adapter_module)
+    @adapter = adapter_module
+  end
+
+  def self.adapter
+    @adapter ||= Adapters::Default
+  end
 
   # Returns a String or Array object representing the given XML, decorated
   # with methods to access attributes and/or child elements.
   def self.new(duck)
     case duck
-      when ::String        : return new(File.open(duck))
-      when ::IO            : return new(REXML::Document.new(duck).root)
-      when REXML::Element  : return new_decorated_obj(duck)
-      when REXML::Elements : return duck.map { |dee| new_decorated_obj(dee) }
-      else raise "Don't know how to start from '#{duck.class}' object."
+      when adapter::Element : new_decorated_obj(duck)
+      when Array            : duck.map { |d| new_decorated_obj(d) }
+      else new adapter.new(duck)
     end
   end
 
-  # Takes any REXML::Element object, and converts it recursively into
+  private ##################################################################
+
+  # Takes any Element object, and converts it recursively into
   # the corresponding tree of decorated objects.
   def self.new_decorated_obj(xml)
-    obj = if xml.text.blank? &&
-             xml.elements.map { |e| e.name }.uniq.size == 1
+    obj = if xml.value.blank? &&
+             xml.children.collect { |e| e.name }.uniq.size == 1
 
-      CollectionProxy.new new(xml.elements)
+      CollectionProxy.new new(xml.children)
     else
-      case
-        when (not xml.text.blank?)  : xml.text.to_s
-        when (xml.cdatas.size >= 1) : xml.cdatas.first.to_s
-        else ''
-      end.extend String
+      xml.value.extend String # Teach our string to behave like XML
     end
 
     obj.instance_variable_set :@__raw_xml, xml
 
-    xml.each_element    { |child| add_child(obj, child.name, new(child)) }
+    xml.children.each   { |child| add_child(obj, child.name, new(child)) }
     xml.attributes.each { |name, value|  add_attribute(obj, name, value) }
 
-    obj.extend CommonBehaviours
+    # Let's teach our object some new tricks:
+    obj.extend(ArrayNotation).extend(MethodMissingDispatchers)
   end
 
-  private ##################################################################
-
   # Decorates the given object 'obj' with a method 'name' that returns the
   # given 'element'. If 'name' is already taken, takes care of the array
   # folding behaviour.
@@ -57,27 +63,9 @@ module XMLStruct
 
     children[key] = if children[key]
 
-      unless obj.respond_to?((plural_key = key.to_s.pluralize).to_sym)
-          begin
-            obj.instance_eval %{
-              def #{plural_key}; @__children[%s|#{key.to_s}|]; end }
-          rescue SyntaxError
-            nil
-          end
-      end
-
       children[key] = [ children[key] ] unless children[key].is_a? Array
       children[key] << element
     else
-      unless obj.respond_to? key
-        begin
-          obj.instance_eval %{
-            def #{key.to_s}; @__children[%s|#{key.to_s}|]; end }
-        rescue SyntaxError
-          nil
-        end
-      end
-
       element
     end
 
@@ -92,15 +80,6 @@ module XMLStruct
     attributes = obj.instance_variable_get :@__attributes
     attributes[(key = name.to_sym)] = attr_value.squish.extend String
 
-    unless obj.respond_to? key
-      begin
-        obj.instance_eval %{
-          def #{key.to_s}; @__attributes[%s|#{key.to_s}|]; end }
-      rescue SyntaxError
-        nil
-      end
-    end
-
     obj.instance_variable_set :@__attributes, attributes
     attr_value
   end