jordi-xml_struct 0.1.1

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.markdown

@@ -0,0 +1,34 @@
+Documentation pending. For now:
+
+# 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>
+
+    recipe = XMLStruct.new recipe_xml_shown_above
+
+    recipe.name                      => "bread"
+    recipe.title == "Basic bread"    => true
+
+    recipe.ingredients.is_a?(Array)  => true
+    recipe.ingredients.first.amount  => 8
+
+    recipe.instructions.easy?        => true
+
+    recipe.instructions.first.upcase => "MIX ALL INGREDIENTS TOGETHER."
+    recipe.instructions.steps.size   => 7
+

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run the unit tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'XMLStruct'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include 'README.markdown'
+  rdoc.rdoc_files.include 'lib/**/*.rb'
+end
+
+desc 'Measures test coverage using rcov'
+task :rcov do
+  rm_f 'coverage'
+  rm_f 'coverage.data'
+
+  rcov = %{ rcov --aggregate coverage.data --text-summary
+    --include lib
+    --exclude /Library/Ruby
+  }.strip!.gsub! /\s+/, ' '
+
+  system("#{rcov} --html #{Dir.glob('test/**/*_test.rb').join(' ')}")
+  system('open coverage/index.html') if PLATFORM['darwin']
+end

data/WHATSNEW

@@ -0,0 +1,3 @@
+* 0.1.1 (2008-10-10):
+  - First "release" ;)
+

data/lib/jordi-xml_struct.rb

@@ -0,0 +1 @@
+require 'xml_struct'

data/lib/xml_struct.rb

@@ -0,0 +1,147 @@
+require 'rubygems'
+require 'activesupport'
+require 'rexml/document'
+
+class XMLStruct
+
+  include Comparable
+
+  # Returns an XMLStruct object
+  def self.new(duck)
+    duck.is_a?(REXML::Element) ? super : new(REXML::Document.new(duck).root)
+  end
+
+  # Takes any REXML::Element object, and converts it recursively into
+  # the corresponding tree of XMLStruct objects
+  def initialize(raw)
+    @attributes, @children, @raw = {}, {}, raw
+    @value = __get_value_from_raw_element @raw
+
+    @raw.each_element    { |el|   __set_child el.name, self.class.new(el) }
+    @raw.attributes.each { |n, v| __set_attribute n, v                    }
+  end
+
+  # An XMLStruct is blank when it has a blank value, no child elements,
+  # and no attributes. For example:
+  #
+  #    <blank_element></blank_element>
+  def blank?
+    @value.blank? && @children.blank? && @attributes.blank?
+  end
+
+  # XMLStruct objects are compared according to their values
+  def <=>(other)
+    @value <=> other
+  end
+
+  # Array-notation access to elements and attributes. It comes handy 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 hash keys, which are useful to reach attributes named
+  # the same as elements in the same level (which are otherwise prioritized)
+  #
+  # All of this is a lot easier to exampling by example:
+  #
+  #   <article id="main_article" author="j-random">
+  #     <author>J. Random Hacker</author>
+  #   </article>
+  #
+  #   article.id                 => 9314390         # Object#id gets called
+  #   article[:id]               => "main_article"  # id attribute
+  #   article[:author]           => <XMLStruct ...> # <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)
+    unless name.is_a? Hash
+      return @children[name.to_sym]   if @children[name.to_sym]
+      return @attributes[name.to_sym] if @attributes[name.to_sym]
+    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
+
+  def method_missing(method, *args, &block) # :nodoc:
+
+    if method.to_s.match(/\?$/) && args.empty? && block.nil?
+      boolish = send(method.to_s.chomp('?').to_sym).to_s
+
+      %w[ true yes t y ].include? boolish.downcase
+
+    elsif @value.blank? && (@children.size == 1) &&
+      (single_child = @children.values.first).respond_to?(method)
+
+      single_child.send method, *args, &block
+    else
+      @value.send method, *args, &block
+    end
+  end
+
+  def inspect # :nodoc:
+    %{ #<#{self.class.to_s} value=#{@value.inspect} (#{@value.class.to_s})
+         attributes=[#{@attributes.keys.map(&:to_s).join(', ') }]
+         children=[#{@children.keys.map(&:to_s).join(', ')     }]> }.squish
+  end
+
+  private
+
+  def __set_child(name, element) # :nodoc:
+    key = name.to_sym
+
+    @children[key] = if @children[key]
+
+      unless respond_to?((plural_key = key.to_s.pluralize).to_sym)
+        instance_eval %{ def #{plural_key}; @children[:#{key.to_s}]; end }
+      end
+
+      @children[key] = [ @children[key] ] unless @children[key].is_a? Array
+      @children[key] << element
+    else
+      unless respond_to? key
+        instance_eval %{ def #{key.to_s}; @children[:#{key.to_s}]; end }
+      end
+
+      element
+    end
+  end
+
+  def __set_attribute(name, attribute) # :nodoc:
+    obj = __get_object_from_string(attribute)
+    @attributes[(key = name.to_sym)] = obj.is_a?(String) ? obj.squish : obj
+
+    unless respond_to? key
+      instance_eval %{ def #{key.to_s}; @attributes[:#{key.to_s}]; end }
+    end
+  end
+
+  def __get_value_from_raw_element(raw) # :nodoc:
+    str = case
+      when raw.has_text? && !raw.text.blank? : raw.text
+      else (raw.cdatas.first.to_s rescue '')
+    end
+
+    __get_object_from_string str
+  end
+
+  def __get_object_from_string(str) # :nodoc:
+    case
+      when str.blank?              : nil
+      when str.match(/[a-zA-Z]/)   : str
+      when str.match(/^[+-]?\d+$/) : str.to_i
+      when str.match(/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/) : str.to_f
+      else str
+    end
+  end
+end

data/test/samples/lorem.xml

@@ -0,0 +1,63 @@
+<!-- Invalid method name test -->
+<lorem id="root" name="ipsum dolor sit amet" _tempor="incididunt">
+
+  <_minim>veniam</_minim> <!-- Invalid method name test -->
+
+  <!-- unambiguous element/attribute access test -->
+  <sed do="eiusmod attributus">
+    <do>eiusmod elementus</do>
+  </sed>
+
+  <!-- Blank test -->
+  <ipsum></ipsum>
+  <dolor foo="bar"></dolor>
+  <sit><amet></amet></sit>
+  <ut>quis</ut>
+
+  <!-- To test the array folding feature, as well as the pluralization.
+       The attributes help test float, integer, and boolean recognition,
+       as well as method name clashing behaviour (id) -->
+  <consectetur id="1" capacity="2.13" enabled="yes"   />
+  <consectetur id="2" capacity="-1.9" enabled="No"    />
+  <consectetur id="3" capacity="13.0" enabled="True"  />
+  <consectetur id="4" capacity="0.00" enabled="false" />
+
+  <!-- Test boolean recognition -->
+  <brutus>true</brutus>
+
+  <consecteturs> <!-- To test that we can still reach this, even though
+                      the array of singular ones above will trap the call
+                      to this when using dot notation -->
+    <culpa>officia</culpa>
+  </consecteturs>
+
+  <cupidatats> <!-- Test for the empty element == single array child
+                    scenario, as well as date recognition -->
+    <cupidatat activated_at="2903-02-12">Aliqua</cupidatat>
+    <cupidatat activated_at="2903-02-13">Occaecat</cupidatat>
+    <cupidatat activated_at="2904-10-18">Cupidatat</cupidatat>
+    <cupidatat activated_at="2905-03-21">Mollit</cupidatat>
+  </cupidatats>
+
+  <!-- Non-empty element, should not be array proxy -->
+  <voluptate>
+    velit
+    <esse>cillum</esse>
+    <esse>cillum dolore</esse>
+  </voluptate>
+
+  <!-- Test for both text value and CDATA value -->
+  <ullamco>Laboris<![CDATA[nisi]]></ullamco>
+
+  <!-- Test for multiple CDATA values -->
+  <deserunt><![CDATA[mollit]]><![CDATA[anim]]></deserunt>
+
+  <!-- Test for whitespace preservation / squishing -->
+  <irure metadata="  
+    	dolor  ">  
+			reprehenderit  </irure>
+
+<!-- CDATA whitespace preservation test -->
+<![CDATA[	 foo
+]]>
+</lorem>

data/test/test_helper.rb

@@ -0,0 +1,37 @@
+require 'test/unit'
+require 'rubygems'
+
+begin
+  require 'redgreen'
+rescue LoadError
+  puts "Install the 'redgreen' gem to get color output"
+end
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'xml_struct')
+
+def xml_file(name_symbol)
+  File.open File.join(File.dirname(__FILE__), 'samples',
+    "#{name_symbol.to_s}.xml")
+end
+
+require 'digest/md5'
+{ :lorem => '6dc88e269000db3be599fca3367e2aa5' }.each do |file_key, md5|
+
+  unless Digest::MD5.hexdigest(xml_file(file_key).read) == md5
+    raise "Sample test file #{file_key.to_s}.xml doesn't match expected MD5"
+  end
+end
+
+class Test::Unit::TestCase
+  def self.should(do_stuff_that_is_true, &block)
+
+    object = to_s.split('Test').first
+    method = "test that #{object} should #{do_stuff_that_is_true}"
+
+    define_method(method.intern) { assert block.bind(self).call }
+  end
+
+  def debug
+    require 'ruby-debug'; debugger
+  end
+end

data/test/xml_struct_test.rb

@@ -0,0 +1,115 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class XMLStructTest < Test::Unit::TestCase
+
+  include RubyProf::Test if defined? RubyProf::Test
+
+  def setup
+    @lorem = XMLStruct.new xml_file(:lorem)
+  end
+
+  should 'be an XMLStruct' do
+    @lorem.is_a? XMLStruct
+  end
+
+  should 'be blank if devoid of children, attributes and value' do
+    @lorem.ipsum.blank?
+  end
+
+  should 'not be blank when value, children, or attributes are present' do
+    [ @lorem.dolor, @lorem.sit, @lorem.ut ].all? { |xr| not xr.blank? }
+  end
+
+  should 'allow access to attributes named like invalid methods' do
+    @lorem['_tempor'] == 'incididunt'
+  end
+
+  should 'allow access to elements named like invalid methods' do
+    @lorem['_minim'] == 'veniam'
+  end
+
+  should 'provide unambiguous access to elements named like attributes' do
+    @lorem.sed[:element => 'do'] == 'eiusmod elementus'
+  end
+
+  should 'provide unambiguous access to attributes named like elements' do
+    @lorem.sed[:attribute => 'do'] == 'eiusmod attributus'
+  end
+
+  should 'return elements first when using dot notation' do
+    @lorem.sed.do == @lorem.sed[:element => 'do']
+  end
+
+  should 'return elements first when using array notation and string key' do
+    @lorem.sed['do'] == @lorem.sed[:element => 'do']
+  end
+
+  should 'return elements first when using array notation and symbol key' do
+    @lorem.sed[:do] == @lorem.sed[:element => 'do']
+  end
+
+  should 'raise exception when unkown keys are used in hash-in-array mode' do
+    (@lorem[:foo => 'bar']; false) rescue true
+  end
+
+  should 'group multiple parallel namesake elements in arrays' do
+    @lorem.consectetur.is_a? Array
+  end
+
+  should 'make auto-grouped arrays accessible by their plural form' do
+    @lorem.consecteturs.equal? @lorem.consectetur
+  end
+
+  should 'allow explicit access to elements named like plural arrays' do
+    not @lorem.consecteturs.equal? @lorem[:element => 'consecteturs']
+  end
+
+  should 'convert integer-looking attribute strings to integers' do
+    @lorem.consecteturs.all? { |c| c[:attr => 'id'].is_a? Numeric }
+  end
+
+  should 'convert float-looking attribute strings to floats' do
+    @lorem.consecteturs.all? { |c| c.capacity.is_a? Float }
+  end
+
+  should 'convert bool-looking attribute strings to bools when asked' do
+    @lorem.consecteturs.all? { |c| c.enabled?.equal? !!(c.enabled?) }
+  end
+
+  should 'convert to bool correctly when asked' do
+    @lorem.consecteturs.first.enabled? == true &&
+    @lorem.consecteturs.last.enabled?  == false
+  end
+
+  should 'pass forth methods to single array child when empty valued' do
+    @lorem.cupidatats.slice(0).equal? @lorem.cupidatats.cupidatat.slice(0)
+  end
+
+  should 'not pass methods to single array child if not empty valued' do
+    not @lorem.voluptate.slice(0).equal? @lorem.voluptate.esse.slice(0)
+  end
+
+  should 'be valued as its text when text first and CDATA exist' do
+    @lorem.ullamco == 'Laboris'
+  end
+
+  should 'have the value of its first CDATA when multiple exist' do
+    @lorem.deserunt == 'mollit'
+  end
+
+  should 'squish whitespace in string attribute values' do
+    @lorem.irure.metadata == 'dolor'
+  end
+
+  should 'not squish whitespace in string element values' do
+    @lorem.irure == "  \n\t\t\treprehenderit  "
+  end
+
+  should 'not squish whitespace in CDATA values' do
+    @lorem == "\t foo\n"
+  end
+
+  should 'have a working inspect function' do
+    (@lorem.inspect.to_s.is_a? String; true) rescue false
+  end
+end

data/xml_struct.gemspec

@@ -0,0 +1,38 @@
+Gem::Specification.new do |s|
+  s.name        = 'xml_struct'
+  s.version     = '0.1.1'
+  s.date        = '2008-10-09'
+
+  s.author      = 'Jordi Bunster'
+  s.email       = 'jordi@bunster.org'
+  s.homepage    = 'http://github.com/jordi/xml_struct'
+
+  s.add_dependency 'activesupport', '>= 2.1.1'
+
+  s.summary     = "The Rubyista's way to do quick XML sit-ups"
+  s.description = %{ This 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.
+
+                     It is slow and not devoid of caveats, but has a very
+                     pleasant, Ruby-like syntax. }.strip!.gsub! /\s+/, ' '
+
+  s.test_files  = %w[ test
+                      test/samples
+                      test/samples/lorem.xml
+                      test/test_helper.rb
+                      test/xml_struct_test.rb ]
+
+  s.files       = %w[ MIT-LICENSE
+                      README.markdown
+                      Rakefile
+                      WHATSNEW
+                      lib
+                      lib/jordi-xml_struct.rb
+                      lib/xml_struct.rb
+                      xml_struct.gemspec ]
+
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w[ README.markdown        ]
+  s.rdoc_options     = %w[ --main README.markdown ]
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: jordi-xml_struct
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jordi Bunster
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-09 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: 2.1.1
+    version: 
+description: This 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. It is slow and not devoid of caveats, but has a very pleasant, Ruby-like syntax.
+email: jordi@bunster.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- MIT-LICENSE
+- README.markdown
+- Rakefile
+- WHATSNEW
+- lib
+- lib/jordi-xml_struct.rb
+- lib/xml_struct.rb
+- xml_struct.gemspec
+has_rdoc: true
+homepage: http://github.com/jordi/xml_struct
+post_install_message: 
+rdoc_options: 
+- --main
+- README.markdown
+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: 
+- test
+- test/samples
+- test/samples/lorem.xml
+- test/test_helper.rb
+- test/xml_struct_test.rb