Contextual pull parsing.

This adds the ability to more easily act upon specific node types and nestings
when using the pull parsing API.

A basic example of this API looks like the following (only including relevant
code):

    parser.parse do |node|
      parser.on(:element, %w{people person}) do
        people << {:name => nil, :age => nil}
      end

      parser.on(:text, %w{people person name}) do
        people.last[:name] = node.text
      end

      parser.on(:text, %w{people person age}) do
        people.last[:age] = node.text.to_i
      end
    end

This fixes #6.

lib/oga/xml/cdata.rb

@@ -12,6 +12,13 @@ module Oga
       def to_xml
         return "<![CDATA[#{text}]]>"
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :cdata
+      end
     end # Cdata
   end # XML
 end # Oga

lib/oga/xml/comment.rb

@@ -12,6 +12,13 @@ module Oga
       def to_xml
         return "<!--#{text}-->"
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :comment
+      end
     end # Comment
   end # XML
 end # Oga

lib/oga/xml/doctype.rb

@@ -73,6 +73,13 @@ module Oga
 #{spacing})
         EOF
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :doctype
+      end
     end # Doctype
   end # XML
 end # Oga

lib/oga/xml/element.rb

@@ -75,6 +75,13 @@ module Oga
 #{spacing}]
         EOF
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :element
+      end
     end # Element
   end # XML
 end # Oga

lib/oga/xml/node.rb

@@ -58,6 +58,13 @@ module Oga
       # @return [String]
       #
       def extra_inspect_data; end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :node
+      end
     end # Element
   end # XML
 end # Oga

lib/oga/xml/pull_parser.rb

@@ -75,6 +75,50 @@ module Oga
         return
       end
 
+      ##
+      # Calls the supplied block if the current node type and optionally the
+      # nesting match. This method allows you to write this:
+      #
+      #     parser.parse do |node|
+      #       parser.on(:text, %w{people person name}) do
+      #         puts node.text
+      #       end
+      #     end
+      #
+      # Instead of this:
+      #
+      #     parser.parse do |node|
+      #       if node.node_type == :text \
+      #       and parser.nesting == %w{people person name}
+      #         puts node.text
+      #       end
+      #     end
+      #
+      # When calling this method you can specify the following node types:
+      #
+      # * `:cdata`
+      # * `:comment`
+      # * `:element`
+      # * `:text`
+      #
+      # @example
+      #  parser.on(:element, %w{people person name}) do
+      #
+      #  end
+      #
+      # @param [Symbol] type The type of node to act upon. This is a symbol as
+      #  returned by {Oga::XML::Node#node_type}.
+      #
+      # @param [Array] nesting The element name nesting to act upon.
+      #
+      def on(type, nesting = [])
+        if node.node_type == type
+          if nesting.empty? or nesting == self.nesting
+            yield
+          end
+        end
+      end
+
       # eval is a heck of a lot faster than define_method on both Rubinius and
       # JRuby.
       DISABLED_CALLBACKS.each do |method|

lib/oga/xml/text.rb

@@ -24,6 +24,13 @@ module Oga
       def extra_inspect_data(indent)
         return "text: #{text.inspect}"
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :text
+      end
     end # Text
   end # XML
 end # Oga

lib/oga/xml/xml_declaration.rb

@@ -67,6 +67,13 @@ module Oga
 #{spacing})
         EOF
       end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :xml_decl
+      end
     end # XmlDeclaration
   end # XML
 end # Oga

spec/oga/xml/cdata_spec.rb

@@ -33,4 +33,10 @@ describe Oga::XML::Cdata do
       @instance.inspect.should == 'Cdata(text: "foo")'
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :cdata
+    end
+  end
 end

spec/oga/xml/comment_spec.rb

@@ -33,4 +33,10 @@ describe Oga::XML::Comment do
       @instance.inspect.should == 'Comment(text: "foo")'
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :comment
+    end
+  end
 end

spec/oga/xml/doctype_spec.rb

@@ -63,4 +63,10 @@ Doctype(
       EOF
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :doctype
+    end
+  end
 end

spec/oga/xml/element_spec.rb

@@ -80,4 +80,10 @@ Element(
       EOF
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :element
+    end
+  end
 end

spec/oga/xml/node_spec.rb

@@ -13,4 +13,10 @@ describe Oga::XML::Node do
       described_class.new.children.should == []
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :node
+    end
+  end
 end

spec/oga/xml/pull_parser/context_parsing_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Oga::XML::PullParser do
+  context '#on' do
+    before do
+      @parser = Oga::XML::PullParser.new('<a><b></b></a>')
+
+      @parser.stub(:node).and_return(Oga::XML::Text.new)
+    end
+
+    example 'do not yield if the node types do not match' do
+      expect { |b| @parser.on(:element, &b) }.to_not yield_control
+    end
+
+    example 'yield if the node type matches and the nesting is empty' do
+      expect { |b| @parser.on(:text, &b) }.to yield_control
+    end
+
+    example 'do not yield if the node type matches but the nesting does not' do
+      expect { |b| @parser.on(:text, %w{foo}, &b) }.to_not yield_control
+    end
+
+    example 'yield if the node type and the nesting matches' do
+      @parser.stub(:nesting).and_return(%w{a b})
+
+      expect { |b| @parser.on(:text, %w{a b}, &b) }.to yield_control
+    end
+  end
+end

spec/oga/xml/text_spec.rb

@@ -33,4 +33,10 @@ describe Oga::XML::Text do
       @instance.inspect.should == 'Text(text: "foo")'
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :text
+    end
+  end
 end

spec/oga/xml/xml_declaration_spec.rb

@@ -58,4 +58,10 @@ XmlDeclaration(
       EOF
     end
   end
+
+  context '#type' do
+    example 'return the type of the node' do
+      described_class.new.node_type.should == :xml_decl
+    end
+  end
 end