sxrb 0.2.1 → 0.2.2

data/lib/sxrb/proxy.rb

@@ -1,18 +1,44 @@
 module SXRB
   class Proxy
+    # @api private
     def initialize(callback_tree, current_path = '')
       @callback_tree = callback_tree
       @current_path = current_path
     end
 
-    def child(*args, &block)
-      args.each do |tag|
+    # Defines child (a direct descendant) of an element defined in current.
+    # block.
+    # @param [String] *tags
+    #   names of tags that should be matched
+    #
+    # @yield [Proxy]
+    #   block receives Proxy element representing matched elements
+    #
+    # @return [nil]
+    #
+    # @api public
+    #
+    # @todo Add Regexp and other selectors support in addition to Strings.
+    def child(*tags, &block)
+      tags.each do |tag|
         @callback_tree.add_rule(tag, @current_path, :recursive => false).tap do |new_path|
           block.call(Proxy.new(@callback_tree, new_path))
         end
       end
     end
 
+    # Defines descendant of an element defined in current block.
+    # @param [String] *tags
+    #   names of tags that should be matched
+    #
+    # @yield [Proxy]
+    #   block receives Proxy element representing matched elements
+    #
+    # @return [nil]
+    #
+    # @api public
+    #
+    # @todo Add Regexp and other selectors support in addition to Strings.
     def descendant(*args, &block)
       args.each do |tag|
         @callback_tree.add_rule(tag, @current_path, :recursive => true).tap do |new_path|
@@ -21,18 +47,45 @@ module SXRB
       end
     end
 
+    # Defines callback method invoked when matching element is completely
+    # parsed.
+    # @yield [Node] block receives whole parsed element with children.
+    #
+    # @api public
+    #
+    # @note `on_element` should not be used for items that are expected to have
+    # large node subtrees.
     def on_element(&block)
       @callback_tree.add_callback(:element, @current_path, &block)
     end
 
+    # Defines a callback that is invoked whenever start tag is encountered.
+    #
+    # @yield [Node] block receives parsed node without any nested elements. All
+    # inline attributes are available though.
+    #
+    # @api public
     def on_start(&block)
       @callback_tree.add_callback(:start, @current_path, &block)
     end
 
+    # Defines a callback that is invoked whenever anonymous text node within
+    # self is encountered.
+    #
+    # @yield [String] block receives raw content of parsed data in form of
+    # String object.
+    #
+    # @api public
     def on_characters(&block)
       @callback_tree.add_callback(:characters, @current_path, &block)
     end
 
+    # Defines a callback that is invoked whenever end tag is encountered.
+    #
+    # @yield [Node] block receives parsed node without any nested elements. All
+    # inline attributes are available though.
+    #
+    # @api public
     def on_end(&block)
       @callback_tree.add_callback(:end, @current_path, &block)
     end

data/spec/parser_spec.rb

@@ -0,0 +1,168 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe SXRB::Parser do
+  it 'should fail when created without block' do
+    expect {
+      SXRB::Parser.new("<xmlstring/>")
+    }.to raise_error(ArgumentError)
+  end
+
+  context 'callbacks' do
+    it 'should call defined start callback for child element' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_start do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should call defined end callback for child element' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_end do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should call defined characters callback for child element' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_characters do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+
+    it 'should call defined element callback for child element' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should call defined element callback for child element only' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+
+      SXRB::Parser.new("<testelement><testelement>content</testelement></testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should call defined element callback for all descendants' do
+      handler = double('handler')
+      handler.should_receive(:msg).twice
+
+      SXRB::Parser.new("<testelement><testelement>content</testelement></testelement>") do |xml|
+        xml.descendant 'testelement' do |test_element|
+          test_element.on_element do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should pass empty hash to callback when no attributes are given' do
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            element.attributes.should == {}
+          end
+        end
+      end
+    end
+
+    it 'should pass value properly to callback to on_element' do
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            element.children.first.text == 'content'
+          end
+        end
+      end
+    end
+
+    it 'should not find element with non-matching name' do
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'othername' do |test_element|
+          test_element.on_element do |attrs, value|
+            value.should == 'content'
+          end
+        end
+      end
+    end
+
+    it 'should find element by regexp' do
+      pending "feature not ready yet"
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child /testel/ do |test_element|
+          test_element.on_element do |attrs, value|
+            value.should == 'content'
+          end
+        end
+      end
+    end
+
+    it 'should find nested element' do
+      SXRB::Parser.new("<testelement><a>a-content</a></testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.child 'a' do |a|
+            a.on_element do |element|
+              element.children.first.text == 'a-content'
+            end
+          end
+        end
+      end
+    end
+
+    it 'should call callback for element regardless of nested elements' do
+      handler = double('handler')
+      handler.should_receive(:msg).once
+      SXRB::Parser.new("<testelement><a>a-content</a></testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            handler.msg
+          end
+        end
+      end
+    end
+
+    it 'should pass nested elements to on_element callback' do
+      SXRB::Parser.new("<testelement><a>a-content</a></testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            element.children.first.tap do |a|
+              a.name.should == 'a'
+              a.children.first.text.should == 'a-content'
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sxrb
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-06 00:00:00.000000000 Z
-dependencies: []
+date: 2012-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: libxml-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.3
 description: Robust XML parser that allows defining desired behavior with fancy DSL
 email: 
 executables: []
@@ -24,8 +40,10 @@ files:
 - lib/sxrb/errors.rb
 - lib/sxrb/proxy.rb
 - lib/sxrb.rb
+- spec/parser_spec.rb
 homepage: http://rubygems.org/gems/sxrb
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -48,5 +66,6 @@ rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: Smart XML parser
-test_files: []
+test_files:
+- spec/parser_spec.rb
 has_rdoc: