jordi-xml-object 0.9.5

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Jordi Bunster <jordi@bunster.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,152 @@
+= XMLObject
+
+(This is inspired by Python's +xml_objectify+)
+
+XMLObject 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-object'
+  recipe = XMLObject.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-object --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, XMLObject folds same named elements at the same
+level. For example:
+
+    <student>
+      <name>Bob</name>
+      <course>Math</course>
+      <course>Biology</course>
+    </student>
+
+    student = XMLObject.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
+
+XMLObject 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/TODO

@@ -0,0 +1,3 @@
+* Make use of libxml if it's available, then fallback to REXML
+* Refactor so as to not do things recursively
+* Remove ActiveSupport dependency

data/WHATSNEW

@@ -0,0 +1,38 @@
+* 0.9.5 (2008-10-15):
+  - Project renamed to XMLObject, to match project name at Rubyforge.
+    The other names were taken. :(
+
+* 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
+
+* 0.2.0 (2008-10-13):
+  - Broke backwards compatibility
+  - XMLStruct.new now returns decorated String or Array objects, so that
+    access to elements, attributes, and "collection" values is consistent
+  - While Strings are no longer auto-typecast to float or int, they now
+    have, whenever possible, a question-mark form, which attemps to
+    returns booleans for strings like "Yes" and "false"
+  - XMLStruct.new can now take a filename or a file object
+  - Added more tests
+
+* 0.1.3 (2008-10-10):
+  - Switched tests to use test/spec
+  - Added XMLStruct#to_obj to return the corresponding Ruby object value
+  - Added XMLStruct#to_raw_xml to return the REXML object
+  - Added documentation on auto-typecasting behaviour caveat
+
+* 0.1.2 (2008-10-10):
+  - Documentation
+
+* 0.1.1 (2008-10-10):
+  - First "release" ;)

data/lib/jordi-xml-object.rb

@@ -0,0 +1 @@
+require 'xml-object'

data/lib/xml-object/adapters/hpricot.rb

@@ -0,0 +1,47 @@
+module XMLObject::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-object/adapters/rexml.rb

@@ -0,0 +1,34 @@
+module XMLObject::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-object/array_notation.rb

@@ -0,0 +1,44 @@
+module XMLObject::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-object/blankish_slate.rb

@@ -0,0 +1,9 @@
+class XMLObject::BlankishSlate # :nodoc:
+
+  instance_methods.each do |m|
+    undef_method m unless m =~ /^__/         ||
+                          m == 'respond_to?' ||
+                          m == 'extend'      ||
+                          m =~ /^instance_/
+  end
+end

data/lib/xml-object/collection_proxy.rb

@@ -0,0 +1,14 @@
+class XMLObject::CollectionProxy < XMLObject::BlankishSlate # :nodoc:
+  def initialize(target)
+    @__children, @__attributes, @__target = {}, {}, target
+  end
+
+  private ##################################################################
+
+  def method_missing(m, *a, &b) # :nodoc:
+    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-object/default_adapter.rb

@@ -0,0 +1,15 @@
+module XMLObject # :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-object/method_missing_dispatchers.rb

@@ -0,0 +1,43 @@
+module XMLObject::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-object/string.rb

@@ -0,0 +1,35 @@
+module XMLObject::String
+  def self.extended(obj) # :nodoc:
+    obj.instance_variable_set :@__children,   {}
+    obj.instance_variable_set :@__attributes, {}
+    obj
+  end
+
+  # Attempts to detect wether this String is really an integer or float,
+  # and returns accordingly. If not, just returns the string.
+  def rb
+    @__rb ||= case
+      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
+      else ::String.new(self)
+    end
+  end
+
+  # A decorated String is blank when it has a blank value, no child
+  # elements, and no attributes. For example:
+  #
+  #    <blank_element></blank_element>
+  def blank?
+    (self !~ /\S/) && @__children.blank? && @__attributes.blank?
+  end
+
+  private ##################################################################
+
+  def method_missing(m, *a, &b) # :nodoc:
+    dp = __question_dispatch(m, *a, &b)
+    dp = __dot_notation_dispatch(m, *a, &b) if dp.nil?
+    dp
+  end
+end

data/lib/xml-object.rb

@@ -0,0 +1,86 @@
+require 'rubygems'
+require 'activesupport'
+
+module XMLObject
+
+  unless defined?(BASE_DIR) # Slow call
+    BASE_DIR = File.join(File.dirname(__FILE__), 'xml-object')
+  end
+
+  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')
+
+  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 adapter::Element : new_decorated_obj(duck)
+      when Array            : duck.map { |d| new_decorated_obj(d) }
+      else new adapter.new(duck)
+    end
+  end
+
+  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.value.blank? &&
+             xml.children.collect { |e| e.name }.uniq.size == 1
+
+      CollectionProxy.new new(xml.children)
+    else
+      xml.value.extend String # Teach our string to behave like XML
+    end
+
+    obj.instance_variable_set :@__raw_xml, xml
+
+    xml.children.each   { |child| add_child(obj, child.name, new(child)) }
+    xml.attributes.each { |name, value|  add_attribute(obj, name, value) }
+
+    # Let's teach our object some new tricks:
+    obj.extend(ArrayNotation).extend(MethodMissingDispatchers)
+  end
+
+  # 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.
+  def self.add_child(obj, name, element)
+    key      = name.to_sym
+    children = obj.instance_variable_get :@__children
+
+    children[key] = if children[key]
+
+      children[key] = [ children[key] ] unless children[key].is_a? Array
+      children[key] << element
+    else
+      element
+    end
+
+    obj.instance_variable_set :@__children, children
+    element
+  end
+
+  # Decorates the given object 'obj' with a method 'name' that returns the
+  # given 'attr_value'.
+  def self.add_attribute(obj, name, attr_value) # :nodoc:
+
+    attributes = obj.instance_variable_get :@__attributes
+    attributes[(key = name.to_sym)] = attr_value.squish.extend String
+
+    obj.instance_variable_set :@__attributes, attributes
+    attr_value
+  end
+end

data/xml-object.gemspec

@@ -0,0 +1,43 @@
+Gem::Specification.new do |gem|
+  gem.add_dependency 'activesupport'
+
+  gem.name    = 'xml-object'
+  gem.version = '0.9.5'
+  gem.date    = '2008-10-15'
+
+  gem.author   = 'Jordi Bunster'
+  gem.email    = 'jordi@bunster.org'
+  gem.homepage = 'http://github.com/jordi/xml-object'
+
+  gem.summary     = "The Rubyista's way to do quick XML sit-ups"
+  gem.description = %{ XMLObject is a library for reading (not writing) XML.
+    It is particularly suited for cases where one is dealing with small
+    documents of a known structure. While not devoid of caveats, it does
+    have a very pleasant, idiomatic Ruby syntax. }.strip!.gsub! /\s+/, ' '
+
+  gem.files = %w[
+    MIT-LICENSE
+    README.rdoc
+    TODO
+    WHATSNEW
+    lib
+    lib/jordi-xml-object.rb
+    lib/xml-object
+    lib/xml-object/adapters
+    lib/xml-object/adapters/hpricot.rb
+    lib/xml-object/adapters/rexml.rb
+    lib/xml-object/array_notation.rb
+    lib/xml-object/blankish_slate.rb
+    lib/xml-object/collection_proxy.rb
+    lib/xml-object/default_adapter.rb
+    lib/xml-object/method_missing_dispatchers.rb
+    lib/xml-object/string.rb
+    lib/xml-object.rb
+    xml-object.gemspec
+  ]
+
+  gem.has_rdoc = !!(gem.extra_rdoc_files = %w[ README.rdoc ])
+  gem.rdoc_options << '--title' << 'XMLObject'   <<
+                      '--main'  << 'README.rdoc' <<
+                      '--inline-source'
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: jordi-xml-object
+version: !ruby/object:Gem::Version 
+  version: 0.9.5
+platform: ruby
+authors: 
+- Jordi Bunster
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-15 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: XMLObject is a library for reading (not writing) XML. It is particularly suited for cases where one is dealing with small documents of a known structure. While not devoid of caveats, it does have a very pleasant, idiomatic Ruby syntax.
+email: jordi@bunster.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- TODO
+- WHATSNEW
+- lib
+- lib/jordi-xml-object.rb
+- lib/xml-object
+- lib/xml-object/adapters
+- lib/xml-object/adapters/hpricot.rb
+- lib/xml-object/adapters/rexml.rb
+- lib/xml-object/array_notation.rb
+- lib/xml-object/blankish_slate.rb
+- lib/xml-object/collection_proxy.rb
+- lib/xml-object/default_adapter.rb
+- lib/xml-object/method_missing_dispatchers.rb
+- lib/xml-object/string.rb
+- lib/xml-object.rb
+- xml-object.gemspec
+has_rdoc: true
+homepage: http://github.com/jordi/xml-object
+post_install_message: 
+rdoc_options: 
+- --title
+- XMLObject
+- --main
+- README.rdoc
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: The Rubyista's way to do quick XML sit-ups
+test_files: []
+