saxaphone 0.3.1 → 0.4.0

data/lib/saxaphone/element.rb

@@ -8,36 +8,149 @@ module Saxaphone
     end
 
     class << self
+      # A block can be passed to <tt>setup</tt>,
+      # which is called after the element is initialized.
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     attr_accessor :foo
+      #     
+      #     setup do
+      #       self.foo = 'bar'
+      #     end
+      #   end
+      #
+      #  It is recommended to use setup rather than
+      #  overriding initialize.
+      # 
       def setup(&block)
         define_method(:setup, &block)
       end
 
+      # Define elements that should be stored as attributes:
+      # 
+      # WidgetElement < Saxaphone::Element
+      #   element_attributes %w(color price)
+      # end
+      # 
+      #   element = WidgetElement.parse %{
+      #     <widget>
+      #       <color>red</color>
+      #       <price>4.33</price>
+      #     </widget>
+      #   }
+      # 
+      # element.attributes # => {"color" => "red", "price" => "4.33"}
+      # 
       def element_attributes(element_names)
         element_names.each do |element_name|
           element_attribute(element_name)
         end
       end
 
+      # Define a single element that should be stored as an attribute.
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     element_attribute 'price'
+      #   end
+      # 
+      #   element = WidgetElement.parse %{
+      #     <widget>
+      #       <price>4.33</price>
+      #     </widget>
+      #   }
+      # 
+      #   element.attributes # => {"price" => "4.33"}
+      # 
+      # The name of the stored attribute can optionally be changed
+      # with the <tt>:as</tt> option:
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     element_attribute 'price', as: 'dollars'
+      #   end
+      # 
+      #   element = WidgetElement.parse %{
+      #     <widget>
+      #       <price>4.33</price>
+      #     </widget>
+      #   }
+      # 
+      #   element.attributes # => {"dollars" => "4.33"}
       def element_attribute(element_name, options = {})
-        converted_name = options.delete(:as) || element_name
-        logic = proc { |element| attributes[converted_name] = element.content }
-        element_handler = ElementHandler.new(@@base_class_name, logic)
+        converted_name = options.delete(:as)
 
-        element_handlers[element_name] = element_handler
+        has_element(element_name) do |element|
+          attributes[converted_name || element.name] = element.content
+        end
       end
 
+      # Define what to do for a particular child element. 
+      # After the element is parsed, it is passed to the block:
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     attr_accessor :cents
+      # 
+      #     has_element 'price' do |element|
+      #       self.cents = element.content.to_f * 100
+      #     end
+      #   end
+      # 
+      #   element = WidgetElement.parse %{
+      #     <widget>
+      #       <price>4.33</price>
+      #     </widget>
+      #   }
+      #   
+      #   element.cents # => 433.0
+      # 
+      # It is possible to define the class name that is used
+      # to parse the child element: 
+      # 
+      #   PriceElement < Saxaphone::Element
+      #     def cents
+      #       content.to_f * 100
+      #     end
+      #   end
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     attr_accessor :cents
+      # 
+      #     has_element 'price', 'PriceElement' do |element|
+      #       self.cents = element.cents
+      #     end
+      #   end
+      # 
+      #   The children elements can have children of their own,
+      #   and each uses has_element to define what to do.
+      # 
       def has_element(element_name, class_name = @@base_class_name, &block)
         element_handlers[element_name] = ElementHandler.new(class_name, block)
       end
 
+      # Define a white list of the attributes that are extracted
+      # from the XML element and stored in the attribute hash:
+      # 
+      #   WidgetElement < Saxaphone::Element
+      #     store_attributes 'name', 'color'
+      #   end
+      # 
+      #   element = WidgetElement.parse %{
+      #     <widget name="Acme" color="red" price="3.21">
+      #       ...
+      #     </widget>
+      #   }
+      # 
+      #   element.attributes # => {"name" => "Acme", "color" => "red"}
+      # 
+      # Notice that the "price" attribute is not stored.
+      # 
       def store_attributes(*attribute_names)
         @stored_attributes = attribute_names.flatten.to_set
       end
 
-      def element_handlers
-        @element_handlers ||= {}
+      def handler_for(element_name)
+        element_handlers[element_name] || element_handlers['*']
       end
-
+      
       def stored_attributes
         @stored_attributes ||= Set.new
       end
@@ -45,6 +158,11 @@ module Saxaphone
       def parse(xml)
         Saxaphone::Document.parse(xml, self)
       end
+
+      private
+        def element_handlers
+          @element_handlers ||= {}
+        end
     end
 
     attr_accessor :name, :content, :attributes
@@ -59,13 +177,13 @@ module Saxaphone
     end
 
     def add_element(element)
-      if element_handler = self.class.element_handlers[element.name]
+      if element_handler = self.class.handler_for(element.name)
         instance_exec(element, &element_handler.proc) if element_handler.proc
       end
     end
 
     def element_for(element_name)
-      if element_handler = self.class.element_handlers[element_name]
+      if element_handler = self.class.handler_for(element_name)
         Saxaphone::Util.constantize(element_handler.class_name)
       else
         Saxaphone::Element

data/test/element_test.rb

@@ -43,12 +43,42 @@ class Saxaphone::ElementTest < MiniTest::Spec
       element_attribute 'faz', as: 'baz'
     end
 
-    element.add_element(Saxaphone::Element.new('faz', 'value'))
+    element.add_element(Saxaphone::Element.new('faz', 'value1'))
+    element.add_element(Saxaphone::Element.new('foo', 'value2'))
 
-    assert_equal({'baz' => 'value'}, element.attributes)
+    assert_equal({'baz' => 'value1'}, element.attributes)
+  end
+
+  def test_element_attribute_with_any
+    element = define_element do
+      element_attribute 'faz', as: 'baz'
+      element_attribute '*'
+    end
+
+    element.add_element(Saxaphone::Element.new('faz', 'value1'))
+    element.add_element(Saxaphone::Element.new('foo', 'value2'))
+
+    assert_equal({'baz' => 'value1', 'foo' => 'value2'}, element.attributes)    
   end
 
   def test_has_element_with_block
+    element = define_element do
+      attr_accessor :child_content
+
+      has_element 'omg'  do |element|
+        self.child_content = element.content
+      end
+    end
+
+    child_element = element.element_for('omg').new('omg')    
+    child_element.content = 'weee'
+    element.add_element(child_element)
+
+    assert_kind_of Saxaphone::Element, child_element
+    assert_equal 'weee', element.child_content
+  end
+
+  def test_has_element_with_block_and_custom_element
     element = define_element do
       attr_accessor :child_special
 
@@ -58,14 +88,28 @@ class Saxaphone::ElementTest < MiniTest::Spec
     end
 
     child_element = element.element_for('omg').new('omg')
+    child_element.special = 'weee'
+    element.add_element(child_element)
     
     assert_kind_of TestChildElement, child_element
-    child_element.special = 'weee'
+    assert_equal 'weee', element.child_special
+  end
+
+  def test_has_element_with_any
+    element = define_element do
+      has_element '*'  do |element|
+        self.attributes[element.name.upcase] = element.content
+      end
+    end
+
+    child_element = element.element_for('faz').new('faz')
+    child_element.content = 'weee'
     element.add_element(child_element)
 
-    assert_equal 'weee', element.child_special
+    assert_kind_of Saxaphone::Element, child_element
+    assert_equal({'FAZ' => 'weee'}, element.attributes)
   end
-  
+
   def test_has_element_without_block
     element = define_element do
       has_element 'wtf', 'Saxaphone::ElementTest::TestChildElement'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saxaphone
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-18 00:00:00.000000000 -07:00
-default_executable: 
+date: 2011-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2162445820 !ruby/object:Gem::Requirement
+  requirement: &70201937138840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,7 +21,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2162445820
+  version_requirements: *70201937138840
 description: Use objects
 email: developer@matthewhiggins.com
 executables: []
@@ -40,7 +39,6 @@ files:
 - test/document_test.rb
 - test/element_test.rb
 - test/test_helper.rb
-has_rdoc: true
 homepage: http://github.com/matthuhiggins/saxaphone
 licenses: []
 post_install_message: 
@@ -61,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.5
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Object Oriented SAX Parsing