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