sxrb 0.2.2 → 0.3.0

data/CHANGELOG

@@ -0,0 +1,14 @@
+08 Aug 2012 (ver. 0.3.0)
+  * New constructors are available
+  * Parsing rules can be now reused
+  * YARD Documentation
+
+07 Aug 2012 (ver. 0.2.2)
+  * Fixed gem dependencies
+
+06 Aug 2012 (ver. 0.2.0)
+  * Added file and IO inputs support
+  * Project is now continously tested with Travis
+
+05 Aug 2012 (ver. 0.1.0)
+  * Release!

data/lib/sxrb.rb

@@ -1,4 +1,5 @@
 require 'sxrb/parser'
 require 'sxrb/errors'
 
+# Main module of gem.
 module SXRB; end

data/lib/sxrb/callbacks.rb

@@ -2,17 +2,25 @@ require 'libxml'
 require 'sxrb/node'
 require 'sxrb/text_node'
 
-# This class provides callbacks for SAX API which are configured with sxrb DSL.
 
 module SXRB
+
+  # This class provides callbacks for SAX API which are configured with sxrb
+  # DSL. It's behavior is configured by DSL via Proxy class objects, and should
+  # not be used outside of this scope. Currently it has only been tested with
+  # LibXML implementation of SAX, but set of method that object needs to
+  # provide is defined by standard, so using it with different backend should
+  # be automatic.
   class Callbacks
     #include LibXML::XML::SaxParser::VerboseCallbacks
     include LibXML::XML::SaxParser::Callbacks
+    # @api private
     def initialize
       @stack = []
       @rules_map = Hash.new {|h,k| h[k] = Rules.new}
     end
 
+    # @api private
     def on_start_element_ns(name, attributes, prefix, uri, namespaces)
       Node.new(name, attributes, prefix, uri, namespaces).tap do |node|
         @stack.push(node)
@@ -22,6 +30,7 @@ module SXRB
       end
     end
 
+    # @api private
     def on_characters(chars)
       if @stack.last.is_a? TextNode
         @stack.last.append_text chars
@@ -34,6 +43,7 @@ module SXRB
       end
     end
 
+    # @api private
     def on_end_element_ns(name, prefix, uri)
       @stack.pop if @stack.last.is_a? TextNode
 
@@ -48,6 +58,7 @@ module SXRB
       end
     end
 
+    # @api private
     def add_callback(type, rule_path, &block)
       @rules_map[Regexp.new "^#{rule_path}$"].tap do |rules|
         rules.rules[type] = block
@@ -55,9 +66,7 @@ module SXRB
       end
     end
 
-    # options:
-    #   recursive
-    #
+    # @api private
     def add_rule(rule, rule_path, options)
       operator = options[:recursive] ? '.*' : ' '
       new_rule = rule_path + operator + rule
@@ -66,23 +75,28 @@ module SXRB
 
     private
 
+    # @api private
     def invoke_callback(type, *args)
       current_matching_rules.
         map {|value| value.rules[type]}.
         compact.each {|callback| callback.call(*args)}
     end
 
+    # @api private
     def current_matching_rules
       @rules_map.each_pair.
         select {|rule, value| current_rule_path =~ rule}.
         map {|rule, value| value}
     end
 
+    # @api private
     def current_rule_path
       @stack.map(&:name).join(' ')
     end
   end
 
+  # Internal class that is designed to keep rules of matching XML elements.
+  # @api private
   class Rules
     attr_accessor :rules, :recursive
     def initialize

data/lib/sxrb/errors.rb

@@ -1,3 +1,5 @@
 module SXRB
+  # SXRB::TagMismatchError is raised whenever parser encounters closing tag of
+  # never opened element.
   class TagMismatchError < StandardError; end
 end

data/lib/sxrb/node.rb

@@ -1,16 +1,27 @@
 module SXRB
+  # Node class is simple DOM-like element, which allows easy travesing through
+  # restricted part of document structure with #children and #parent methods.
   class Node < Struct.new(:name, :attributes, :prefix, :uri, :namespaces, :parent)
     attr_accessor :children
+    # Internal method used to build DOM-like structure.
+    # @api private
     def initialize(*args, &block)
       super(*args, &block)
       @children = []
     end
 
+    # Internal method used to build DOM-like structure.
+    # @api private
     def append(node)
       node.parent = self
       @children << node
     end
 
+
+    # Returns text content of a node (recursively), skipping all markup.
+    # @return [String]
+    #   Text content of this node and all it's descendants is returned,
+    #   concatenated.
     def content
       children.map {|child| child.is_a?(TextNode)? child.text : child.content}.flatten.join('')
     end

data/lib/sxrb/parser.rb

@@ -2,28 +2,90 @@ require 'sxrb/callbacks'
 require 'sxrb/proxy'
 
 module SXRB
+  # Main class of gem, which allows parsing XML data.
   class Parser
+    # Create parser object and parse provided input.
+    # @param [Filename, IO, String] input
+    #   Data stream to be parsed.
+    # @option opts [Symbol] :mode (:string)
+    #   Instructs SXRB how to treat input parameter. Possible values are:
+    #   :string, :file, :io. Please note, that in case of :file mode
+    #   input should be filename.
+    # @deprecated
+    #   This method should not be used anymore. In version 1.0 it will work
+    #   completely different so it is preferable to migrate to use parse_*
+    #   methods right now.
     def initialize(input, opts = {}, &block)
       raise ArgumentError.new("Block expected") if block.nil?
-      options = {:mode => :string}.merge(opts)
+      case opts[:mode]
+      when :file
+        self.class.parse_file(input, &block)
+      when :io
+        self.class.parse_io(input, &block)
+      else
+        self.class.parse_string(input, &block)
+      end
+    end
 
-      # Create parser according to options
+    # Define set of reusable rules for SXRB parser.
+    # @yield Proxy
+    #   See Proxy documentation for details on available methods and defining
+    #   rules.
+    # @return [Callbacks]
+    #   Set of rules which can be feeded to parse_* methods.
+    def self.define_rules(&block)
+      Callbacks.new.tap do |cb|
+        yield Proxy.new(cb)
+      end
+    end
 
-      parser = case options[:mode]
-               when :string
-                 LibXML::XML::SaxParser.string(input)
-               when :file
-                 LibXML::XML::SaxParser.file(input)
-               when :io
-                 LibXML::XML::SaxParser.io(input)
-               end
+    # Parse string containing XML.
+    # @param [String] string
+    #   Input string
+    # @param [optional, Callbacks] callbacks
+    #   Set of rules generated by define_rules.
+    # @yield [Proxy]
+    #   If callbacks parameter is not provided rules have to be defined directly in provided block.
+    # @return [nil]
+    def self.parse_string(string, callbacks = nil, &block)
+      raise ArgumentError unless !!callbacks ^ !!block
+      LibXML::XML::SaxParser.string(string).tap do |parser|
+	parser.callbacks = callbacks || define_rules(&block)
+	parser.parse
+      end
+      nil
+    end
 
-      callbacks = Callbacks.new.tap do |cb|
-        yield Proxy.new(cb)
+    # Parse file containing XML.
+    # @param [String] filename
+    #   Path to file to be parsed.
+    # @param [optional, Callbacks] callbacks
+    #   Set of rules generated by define_rules.
+    # @yield [Proxy]
+    #   If callbacks parameter is not provided rules have to be defined directly in provided block.
+    # @return [nil]
+    def self.parse_file(filename, callbacks = nil, &block)
+      raise ArgumentError unless !!callbacks ^ !!block
+      LibXML::XML::SaxParser.file(filename).tap do |parser|
+	parser.callbacks = callbacks || define_rules(&block)
+	parser.parse
       end
+    end
 
-      parser.callbacks = callbacks
-      parser.parse
+    # Parse IO containing XML.
+    # @param [IO] io
+    #   Path to stream to be parsed.
+    # @param [optional, Callbacks] callbacks
+    #   Set of rules generated by define_rules.
+    # @yield [Proxy]
+    #   If callbacks parameter is not provided rules have to be defined directly in provided block.
+    # @return [nil]
+    def self.parse_io(io, callbacks = nil, &block)
+      raise ArgumentError unless !!callbacks ^ !!block
+      LibXML::XML::SaxParser.io(io).tap do |parser|
+	parser.callbacks = callbacks || define_rules(&block)
+	parser.parse
+      end
     end
   end
 end

data/lib/sxrb/proxy.rb

@@ -1,18 +1,25 @@
 module SXRB
+  # Objects of Proxy class are part of SXRB DSL and their methods are meant to
+  # be used to define set of rules needed to parse XML document. They have no
+  # other meaning and should not be used outside of that scope.
+  # @api public
   class Proxy
+    # Proxy objects are generated by the SXRB itself, and are passed to blocks
+    # to be used as DSL. They should not be created in any other context.
+    # Implementation might change without prior notice.
+    #
     # @api private
     def initialize(callback_tree, current_path = '')
       @callback_tree = callback_tree
       @current_path = current_path
     end
 
-    # Defines child (a direct descendant) of an element defined in current.
-    # block.
-    # @param [String] *tags
+    # 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
+    #   block receives Proxy element representing matched elements.
     #
     # @return [nil]
     #
@@ -28,19 +35,19 @@ module SXRB
     end
 
     # Defines descendant of an element defined in current block.
-    # @param [String] *tags
+    # @param [String] tags
     #   names of tags that should be matched
     #
     # @yield [Proxy]
-    #   block receives Proxy element representing matched elements
+    #   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|
+    # @todo Add Regexp and other selectors support in addition to strings.
+    def descendant(*tags, &block)
+      tags.each do |tag|
         @callback_tree.add_rule(tag, @current_path, :recursive => true).tap do |new_path|
           block.call(Proxy.new(@callback_tree, new_path))
         end
@@ -49,21 +56,28 @@ module SXRB
 
     # Defines callback method invoked when matching element is completely
     # parsed.
-    # @yield [Node] block receives whole parsed element with children.
+    #
+    # @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.
+    # @return [nil]
+    #
+    # @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.
+    # @yield [Node]
+    #   block receives parsed node without any nested elements. All inline
+    #   attributes are available though.
     #
+    # @return [nil]
     # @api public
     def on_start(&block)
       @callback_tree.add_callback(:start, @current_path, &block)
@@ -72,8 +86,10 @@ module SXRB
     # 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.
+    # @yield [String]
+    #   block receives raw content of parsed data in form of string object.
+    #
+    # @return [nil]
     #
     # @api public
     def on_characters(&block)
@@ -82,9 +98,11 @@ module SXRB
 
     # 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.
+    # @yield [Node]
+    #   block receives parsed node without any nested elements. All inline
+    #   attributes are available though.
     #
+    # @return [nil]
     # @api public
     def on_end(&block)
       @callback_tree.add_callback(:end, @current_path, &block)

data/lib/sxrb/text_node.rb

@@ -1,13 +1,19 @@
 module SXRB
+  # Class representing special case of DOM nodes which contain only text, and
+  # don't represent any particular element.
   class TextNode < Node
+    # @api private
     def initialize(text)
       @text = text || ""
     end
 
+    # @api private
     def append_text(text)
       @text << text
     end
 
+    # Accessor for text data kept in TextNode object.
+    # @return [String]
     def text
       @text
     end

data/spec/parser_spec.rb

@@ -1,92 +1,125 @@
 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)
+  context 'constructors' do
+    it 'should fail when created without block' do
+      expect {
+	SXRB::Parser.new("<xmlstring/>")
+      }.to raise_error(ArgumentError)
+    end
+
+    it 'defined rules should be reusable' do
+      @handler = double('handler')
+      @handler.should_receive(:msg).twice
+      rules = SXRB::Parser.define_rules do |root|
+	root.child("el") do |el|
+	  el.on_element {@handler.msg}
+	end
+      end
+      SXRB::Parser.parse_string('<el></el>', rules)
+      SXRB::Parser.parse_string('<el></el>', rules)
+    end
   end
 
-  context 'callbacks' do
-    it 'should call defined start callback for child element' do
-      handler = double('handler')
-      handler.should_receive(:msg).once
+  context 'matchers' do
+    before(:each) do
+      @handler = double('handler')
+    end
 
+    it 'should call defined start callback for child element' do
+      @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
+          test_element.on_start {@handler.msg}
         end
       end
     end
 
     it 'should call defined end callback for child element' do
-      handler = double('handler')
-      handler.should_receive(:msg).once
-
+      @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
+          test_element.on_end {@handler.msg}
         end
       end
     end
 
     it 'should call defined characters callback for child element' do
-      handler = double('handler')
-      handler.should_receive(:msg).once
-
+      @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
+          test_element.on_characters {@handler.msg}
         end
       end
     end
 
 
     it 'should call defined element callback for child element' do
-      handler = double('handler')
-      handler.should_receive(:msg).once
-
+      @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
+          test_element.on_element {@handler.msg}
         end
       end
     end
 
     it 'should call defined element callback for child element only' do
-      handler = double('handler')
-      handler.should_receive(:msg).once
-
+      @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
+          test_element.on_element {@handler.msg}
         end
       end
     end
 
     it 'should call defined element callback for all descendants' do
-      handler = double('handler')
-      handler.should_receive(:msg).twice
-
+      @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
+          test_element.on_element {@handler.msg}
+        end
+      end
+    end
+
+    it 'should call callback for element regardless of nested elements' do
+      @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 {@handler.msg}
+        end
+      end
+    end
+
+    it 'should not invoke callback for child which isn\'t direct descendant' do
+      @handler.should_not_receive(:msg)
+      SXRB::Parser.new("<testelement><a>a-content</a></testelement>") do |xml|
+        xml.child 'a' do |a|
+          a.on_element {@handler.msg}
         end
       end
     end
 
+    it 'should not find element with non-matching name' do
+      @handler.should_not_receive(:msg)
+      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+        xml.child 'othername' do |test_element|
+          test_element.on_element {@handler.msg}
+        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 {@handler.msg}
+        end
+      end
+    end
+  end
+
+  context 'passed values' do
+
     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|
@@ -97,32 +130,51 @@ describe SXRB::Parser do
       end
     end
 
-    it 'should pass value properly to callback to on_element' do
-      SXRB::Parser.new("<testelement>content</testelement>") do |xml|
+    it 'should pass attributes properly to on_start callback' do
+      SXRB::Parser.new('<testelement foo="bar">content</testelement>') do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_start do |element|
+            element.attributes.should == {'foo' => 'bar'}
+          end
+        end
+      end
+    end
+
+    it 'should pass attributes properly to on_element callback' do
+      SXRB::Parser.new('<testelement foo="bar">content</testelement>') do |xml|
         xml.child 'testelement' do |test_element|
           test_element.on_element do |element|
-            element.children.first.text == 'content'
+            element.attributes.should == {'foo' => 'bar'}
           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'
+    it 'should pass attributes properly to on_end callback' do
+      SXRB::Parser.new('<testelement foo="bar">content</testelement>') do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_end do |element|
+            element.attributes.should == {'foo' => 'bar'}
           end
         end
       end
     end
 
-    it 'should find element by regexp' do
-      pending "feature not ready yet"
+    it 'should pass concatenated content' do
+      SXRB::Parser.new("<testelement><a>con</a>tent</testelement>") do |xml|
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            element.content == 'content'
+          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 /testel/ do |test_element|
-          test_element.on_element do |attrs, value|
-            value.should == 'content'
+        xml.child 'testelement' do |test_element|
+          test_element.on_element do |element|
+            element.content == 'content'
           end
         end
       end
@@ -133,20 +185,18 @@ describe SXRB::Parser do
         xml.child 'testelement' do |test_element|
           test_element.child 'a' do |a|
             a.on_element do |element|
-              element.children.first.text == 'a-content'
+              element.content == '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
+    it 'should pass nested elements content 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|
-            handler.msg
+          test_element.on_element do |node|
+            node.content.should == 'a-content'
           end
         end
       end
@@ -158,7 +208,7 @@ describe SXRB::Parser do
           test_element.on_element do |element|
             element.children.first.tap do |a|
               a.name.should == 'a'
-              a.children.first.text.should == 'a-content'
+              a.content.should == 'a-content'
             end
           end
         end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'sxrb'
+require 'rspec'
+require 'rspec/autorun'
+
+RSpec.configure do |config|
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sxrb
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-07 00:00:00.000000000 Z
+date: 2012-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: libxml-ruby
@@ -40,7 +40,9 @@ files:
 - lib/sxrb/errors.rb
 - lib/sxrb/proxy.rb
 - lib/sxrb.rb
+- CHANGELOG
 - spec/parser_spec.rb
+- spec/spec_helper.rb
 homepage: http://rubygems.org/gems/sxrb
 licenses:
 - MIT
@@ -68,4 +70,5 @@ specification_version: 3
 summary: Smart XML parser
 test_files:
 - spec/parser_spec.rb
+- spec/spec_helper.rb
 has_rdoc: