oga 0.1.3 → 0.2.0

data/lib/oga/xml/querying.rb

@@ -27,6 +27,30 @@ module Oga
 
         return result.is_a?(XML::NodeSet) ? result.first : result
       end
+
+      ##
+      # Evaluates the given CSS expression.
+      #
+      # @param [String] expression The CSS expression to run.
+      # @see [Oga::XPath::Evaluator#initialize]
+      #
+      def css(expression)
+        ast = CSS::Parser.new(expression).parse
+
+        return XPath::Evaluator.new(self).evaluate_ast(ast)
+      end
+
+      ##
+      # Evaluates the given CSS expression and returns the first node in the
+      # set.
+      #
+      # @see [#css]
+      #
+      def at_css(*args)
+        result = css(*args)
+
+        return result.is_a?(XML::NodeSet) ? result.first : result
+      end
     end # Querying
   end # XML
 end # Oga

data/lib/oga/xml/sax_parser.rb

@@ -37,6 +37,26 @@ module Oga
     # For information on the callback arguments see the documentation of the
     # corresponding methods in {Oga::XML::Parser}.
     #
+    # ## Element Callbacks
+    #
+    # The SAX parser changes the behaviour of both `on_element` and
+    # `after_element`. The latter in the regular parser only takes a
+    # {Oga::XML::Element} instance. In the SAX parser it will instead take a
+    # namespace name and the element name. This eases the process of figuring
+    # out what element a callback is associated with.
+    #
+    # An example:
+    #
+    #     class SaxHandler
+    #       def on_element(namespace, name, attrs = {})
+    #         # ...
+    #       end
+    #
+    #       def after_element(namespace, name)
+    #         puts name # => "foo", "bar", etc
+    #       end
+    #     end
+    #
     class SaxParser < Parser
       ##
       # @param [Object] handler The SAX handler to delegate callbacks to.
@@ -52,12 +72,46 @@ module Oga
       instance_methods.grep(/^(on_|after_)/).each do |method|
         eval <<-EOF, nil, __FILE__, __LINE__ + 1
         def #{method}(*args)
-          @handler.#{method}(*args) if @handler.respond_to?(:#{method})
+          run_callback(:#{method}, *args)
 
           return
         end
         EOF
       end
+
+      ##
+      # Manually overwrite `on_element` so we can ensure that `after_element`
+      # always receives the namespace and name.
+      #
+      # @see [Oga::XML::Parser#on_element]
+      # @return [Array]
+      #
+      def on_element(namespace, name, attrs = {})
+        run_callback(:on_element, namespace, name, attrs)
+
+        return namespace, name
+      end
+
+      ##
+      # Manually overwrite `after_element` so it can take a namespace and name.
+      # This differs a bit from the regular `after_element` which only takes an
+      # {Oga::XML::Element} instance.
+      #
+      # @param [Array] namespace_with_name
+      #
+      def after_element(namespace_with_name)
+        run_callback(:after_element, *namespace_with_name)
+      end
+
+      private
+
+      ##
+      # @param [Symbol] method
+      # @param [Array] args
+      #
+      def run_callback(method, *args)
+        @handler.send(method, *args) if @handler.respond_to?(method)
+      end
     end # SaxParser
   end # XML
 end # Oga

data/lib/oga/xml/text.rb

@@ -5,7 +5,12 @@ module Oga
     # have any children, attributes and the likes; just text.
     #
     class Text < CharacterNode
-
+      ##
+      # @see [Oga::XML::CharacterNode#to_xml]
+      #
+      def to_xml
+        return Entities.encode(super)
+      end
     end # Text
   end # XML
 end # Oga

data/lib/oga/xpath/evaluator.rb

@@ -2,7 +2,7 @@ module Oga
   module XPath
     ##
     # The Evaluator class evaluates XPath expressions, either as a String or an
-    # AST of {Oga::XPath::Node} instances.
+    # AST of `AST::Node` instances.
     #
     # ## Thread Safety
     #
@@ -90,7 +90,7 @@ module Oga
       ##
       # Evaluates a pre-parsed XPath expression.
       #
-      # @param [Oga::XPath::Node] ast
+      # @param [AST::Node] ast
       # @return [Mixed]
       #
       def evaluate_ast(ast)
@@ -104,7 +104,7 @@ module Oga
       # dedicated handler method. Handler methods are called "on_X" where "X" is
       # the node type.
       #
-      # @param [Oga::XPath::Node] ast_node The XPath AST node to process.
+      # @param [AST::Node] ast_node The XPath AST node to process.
       #
       # @param [Oga::XML::NodeSet] context The context (a set of nodes) to
       #  evaluate an expression in.
@@ -120,7 +120,7 @@ module Oga
       ##
       # Processes an absolute XPath expression such as `/foo`.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -142,7 +142,7 @@ module Oga
       # `&&` / `and` operator. Whenever a path results in an empty node set the
       # evaluation is aborted immediately.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -163,28 +163,45 @@ module Oga
       end
 
       ##
-      # Processes a node test and optionally a predicate.
+      # Processes a node test.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
       def on_test(ast_node, context)
-        nodes       = XML::NodeSet.new
-        predicate   = ast_node.children[2]
-        xpath_index = 1
+        nodes = XML::NodeSet.new
 
         context.each do |xml_node|
-          next unless node_matches?(xml_node, ast_node)
+          nodes << xml_node if node_matches?(xml_node, ast_node)
+        end
+
+        return nodes
+      end
+
+      ##
+      # Processes a predicate.
+      #
+      # @param [AST::Node] ast_node
+      # @param [Oga::XML::NodeSet] context
+      # @return [Oga::XML::NodeSet]
+      #
+      def on_predicate(ast_node, context)
+        test, predicate = *ast_node
+        final_nodes     = XML::NodeSet.new
+
+        context.each do |context_node|
+          initial_nodes = process(test, XML::NodeSet.new([context_node]))
+          xpath_index   = 1
 
-          if predicate
-            retval = with_node_set(context) do
+          initial_nodes.each do |xml_node|
+            retval = with_node_set(initial_nodes) do
               process(predicate, XML::NodeSet.new([xml_node]))
             end
 
             # Numeric values are used as node set indexes.
             if retval.is_a?(Numeric)
-              nodes << xml_node if retval.to_i == xpath_index
+              final_nodes << xml_node if retval.to_i == xpath_index
 
             # Node sets, strings, booleans, etc
             elsif retval
@@ -192,16 +209,14 @@ module Oga
                 next
               end
 
-              nodes << xml_node
+              final_nodes << xml_node
             end
-          else
-            nodes << xml_node
-          end
 
-          xpath_index += 1
+            xpath_index += 1
+          end
         end
 
-        return nodes
+        return final_nodes
       end
 
       ##
@@ -209,7 +224,7 @@ module Oga
       # similar to {#process} except the handler names are "on_axis_X" with "X"
       # being the axis name.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -228,7 +243,7 @@ module Oga
       # Evaluation happens using a "short-circuit" mechanism. The moment a
       # matching node is found it is returned immediately.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -279,7 +294,7 @@ module Oga
       # (unlike some other methods which return the moment they find a matching
       # node).
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -299,7 +314,7 @@ module Oga
       # Evaluates the `child` axis. This axis simply takes all the child nodes
       # of the current context nodes.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -311,7 +326,7 @@ module Oga
       # Evaluates the `descendant` axis. This method processes child nodes until
       # the very end of the tree, no "short-circuiting" mechanism is used.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -319,12 +334,8 @@ module Oga
         nodes = XML::NodeSet.new
 
         context.each do |context_node|
-          context_node.children.each do |node|
-            nodes << node if node_matches?(node, ast_node)
-          end
-
           context_node.each_node do |node|
-            nodes << node if node_matches?(node, ast_node)
+            nodes.concat(process(ast_node, XML::NodeSet.new([node])))
           end
         end
 
@@ -334,7 +345,7 @@ module Oga
       ##
       # Evaluates the `descendant-or-self` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -349,17 +360,18 @@ module Oga
       ##
       # Evaluates the `following` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
       def on_axis_following(ast_node, context)
         nodes = XML::NodeSet.new
+        root  = root_node(@document)
 
         context.each do |context_node|
           check = false
 
-          @document.each_node do |doc_node|
+          root.each_node do |doc_node|
             # Skip child nodes of the current context node, compare all
             # following nodes.
             if doc_node == context_node
@@ -379,18 +391,19 @@ module Oga
       ##
       # Evaluates the `following-sibling` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
       def on_axis_following_sibling(ast_node, context)
         nodes = XML::NodeSet.new
+        root  = parent_node(@document)
 
         context.each do |context_node|
           check  = false
           parent = has_parent?(context_node) ? context_node.parent : nil
 
-          @document.each_node do |doc_node|
+          root.each_node do |doc_node|
             # Skip child nodes of the current context node, compare all
             # following nodes.
             if doc_node == context_node
@@ -416,7 +429,7 @@ module Oga
       ##
       # Evaluates the `parent` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -437,17 +450,18 @@ module Oga
       ##
       # Evaluates the `preceding` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
       def on_axis_preceding(ast_node, context)
         nodes = XML::NodeSet.new
+        root  = root_node(@document)
 
         context.each do |context_node|
           check = true
 
-          @document.each_node do |doc_node|
+          root.each_node do |doc_node|
             # Test everything *until* we hit the current context node.
             if doc_node == context_node
               break
@@ -463,18 +477,19 @@ module Oga
       ##
       # Evaluates the `preceding-sibling` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
       def on_axis_preceding_sibling(ast_node, context)
         nodes = XML::NodeSet.new
+        root  = parent_node(@document)
 
         context.each do |context_node|
           check  = true
           parent = has_parent?(context_node) ? context_node.parent : nil
 
-          @document.each_node do |doc_node|
+          root.each_node do |doc_node|
             # Test everything *until* we hit the current context node.
             if doc_node == context_node
               break
@@ -490,7 +505,7 @@ module Oga
       ##
       # Evaluates the `self` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -507,7 +522,7 @@ module Oga
       ##
       # Evaluates the `namespace` axis.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -531,7 +546,7 @@ module Oga
       ##
       # Dispatches node type matching to dedicated handlers.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -546,7 +561,7 @@ module Oga
       ##
       # Processes the `node` type matcher. This matcher matches all node types.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -554,7 +569,9 @@ module Oga
         nodes = XML::NodeSet.new
 
         context.each do |node|
-          nodes << node if node.is_a?(XML::Node)
+          if node.is_a?(XML::Node) or node.is_a?(XML::Document)
+            nodes << node
+          end
         end
 
         return nodes
@@ -563,7 +580,7 @@ module Oga
       ##
       # Processes the `text()` type test. This matches only text nodes.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -580,7 +597,7 @@ module Oga
       ##
       # Processes the `comment()` type test. This matches only comment nodes.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -598,7 +615,7 @@ module Oga
       # Processes the `processing-instruction()` type test. This matches only
       # processing-instruction nodes.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -616,7 +633,7 @@ module Oga
       # Processes the pipe (`|`) operator. This operator creates a union of two
       # sets.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -633,7 +650,7 @@ module Oga
       # evaluate to `true`. If the first expression evaluates to `false` the
       # right expression is ignored.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [TrueClass|FalseClass]
       #
@@ -650,7 +667,7 @@ module Oga
       # true, otherwise false is returned. If the first expression evaluates to
       # `true` the second expression is ignored.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [TrueClass|FalseClass]
       #
@@ -666,7 +683,7 @@ module Oga
       # This operator converts the left and right expressions to numbers and
       # adds them together.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -682,7 +699,7 @@ module Oga
       # This operator converts the left and right expressions to numbers and
       # divides the left number with the right number.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -698,7 +715,7 @@ module Oga
       # This operator converts the left and right expressions to numbers and
       # returns the modulo of the two numbers.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -714,7 +731,7 @@ module Oga
       # This operator converts the left and right expressions to numbers and
       # multiplies the left number with the right number.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -730,7 +747,7 @@ module Oga
       # This operator converts the left and right expressions to numbers and
       # subtracts the right number of the left number.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -749,7 +766,7 @@ module Oga
       # compared instead of the nodes themselves. That is, nodes with different
       # names but the same text are considered to be equal.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [TrueClass|FalseClass]
       #
@@ -863,7 +880,7 @@ module Oga
       # 2. A variable list of XPath function arguments, passed as individual
       #    Ruby method arguments.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Oga::XML::NodeSet]
       #
@@ -905,7 +922,7 @@ module Oga
       # of nodes in `expression` and returns the result as a float.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_count(context, expression)
@@ -933,7 +950,7 @@ module Oga
       # regardless of the current position.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Oga::XML::NodeSet]
       #
       def on_call_id(context, expression)
@@ -967,7 +984,7 @@ module Oga
       # * The first node in the supplied node set
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Oga::XML::NodeSet]
       #
       def on_call_local_name(context, expression = nil)
@@ -984,7 +1001,7 @@ module Oga
       # present.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Oga::XML::NodeSet]
       #
       def on_call_name(context, expression = nil)
@@ -1010,7 +1027,7 @@ module Oga
       # * The first node in the supplied node set
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Oga::XML::NodeSet]
       #
       def on_call_namespace_uri(context, expression = nil)
@@ -1034,7 +1051,7 @@ module Oga
       #  string(10) # => "10"
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [String]
       #
       def on_call_string(context, expression = nil)
@@ -1066,7 +1083,7 @@ module Oga
       #
       # @see [#on_call_string]
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_number(context, expression = nil)
@@ -1101,9 +1118,9 @@ module Oga
       # them. In case of node sets the text of the set is used.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] first
-      # @param [Oga::XPath::Node] second
-      # @param [Array<Oga::XPath::Node>] rest
+      # @param [AST::Node] first
+      # @param [AST::Node] second
+      # @param [Array<AST::Node>] rest
       #
       def on_call_concat(context, first, second, *rest)
         args   = [first, second] + rest
@@ -1126,8 +1143,8 @@ module Oga
       #  starts-with("hello world", "hello") # => true
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] haystack The string to search.
-      # @param [Oga::XPath::Node] needle The string to search for.
+      # @param [AST::Node] haystack The string to search.
+      # @param [AST::Node] needle The string to search for.
       # @return [TrueClass|FalseClass]
       #
       def on_call_starts_with(context, haystack, needle)
@@ -1148,8 +1165,8 @@ module Oga
       #  contains("hello world", "o w") # => true
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] haystack The string to search.
-      # @param [Oga::XPath::Node] needle The string to search for.
+      # @param [AST::Node] haystack The string to search.
+      # @param [AST::Node] needle The string to search for.
       # @return [String]
       #
       def on_call_contains(context, haystack, needle)
@@ -1170,8 +1187,8 @@ module Oga
       # This would return "2014" as it occurs before the first "-".
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] haystack The string to search.
-      # @param [Oga::XPath::Node] needle The string to search for.
+      # @param [AST::Node] haystack The string to search.
+      # @param [AST::Node] needle The string to search for.
       # @return [String]
       #
       def on_call_substring_before(context, haystack, needle)
@@ -1194,8 +1211,8 @@ module Oga
       # This would return "08-25" as it occurs after the first "-".
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] haystack The string to search.
-      # @param [Oga::XPath::Node] needle The string to search for.
+      # @param [AST::Node] haystack The string to search.
+      # @param [AST::Node] needle The string to search for.
       # @return [String]
       #
       def on_call_substring_after(context, haystack, needle)
@@ -1227,9 +1244,9 @@ module Oga
       #  substring(users/user/username, 5)
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] haystack
-      # @param [Oga::XPath::Node] start
-      # @param [Oga::XPath::Node] length
+      # @param [AST::Node] haystack
+      # @param [AST::Node] start
+      # @param [AST::Node] length
       # @return [String]
       #
       def on_call_substring(context, haystack, start, length = nil)
@@ -1255,7 +1272,7 @@ module Oga
       #
       # @see [#on_call_string]
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_string_length(context, expression = nil)
@@ -1273,7 +1290,7 @@ module Oga
       #  normalize-space(" fo  o    ") # => "fo o"
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [String]
       #
       def on_call_normalize_space(context, expression = nil)
@@ -1292,9 +1309,9 @@ module Oga
       #  translate("bar", "abc", "ABC") # => "BAr"
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] input
-      # @param [Oga::XPath::Node] find
-      # @param [Oga::XPath::Node] replace
+      # @param [AST::Node] input
+      # @param [AST::Node] find
+      # @param [AST::Node] replace
       # @return [String]
       #
       def on_call_translate(context, input, find, replace)
@@ -1325,7 +1342,7 @@ module Oga
       # The boolean `false` is returned for all other cases.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [TrueClass|FalseClass]
       #
       def on_call_boolean(context, expression)
@@ -1349,7 +1366,7 @@ module Oga
       # `true` then this function returns `false` instead.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [TrueClass|FalseClass]
       #
       def on_call_not(context, expression)
@@ -1361,7 +1378,7 @@ module Oga
       #
       # This function simply returns the boolean `true`.
       #
-      # @param [Oga::XPath::NodeSet] context
+      # @param [AST::NodeSet] context
       # @return [TrueClass]
       #
       def on_call_true(context)
@@ -1373,7 +1390,7 @@ module Oga
       #
       # This function simply returns the boolean `false`.
       #
-      # @param [Oga::XPath::NodeSet] context
+      # @param [AST::NodeSet] context
       # @return [FalseClass]
       #
       def on_call_false(context)
@@ -1391,7 +1408,7 @@ module Oga
       # such attribute).
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] language
+      # @param [AST::Node] language
       # @return [TrueClass|FalseClass]
       #
       def on_call_lang(context, language)
@@ -1425,7 +1442,7 @@ module Oga
       # Using the expression `sum(root/*)` the return value would be `3.0`.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_sum(context, expression)
@@ -1450,7 +1467,7 @@ module Oga
       # and then returns that number as a float.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_floor(context, expression)
@@ -1466,7 +1483,7 @@ module Oga
       # and then returns that number as a float.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_ceiling(context, expression)
@@ -1482,7 +1499,7 @@ module Oga
       # then returns that number as a float.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Float]
       #
       def on_call_round(context, expression)
@@ -1494,7 +1511,7 @@ module Oga
       ##
       # Processes an `(int)` node.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -1505,7 +1522,7 @@ module Oga
       ##
       # Processes an `(float)` node.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Float]
       #
@@ -1516,7 +1533,7 @@ module Oga
       ##
       # Processes a `(string)` node.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [String]
       #
@@ -1528,7 +1545,7 @@ module Oga
       # Processes a variable reference. If the variable is not defined an error
       # is raised.
       #
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @param [Oga::XML::NodeSet] context
       # @return [Mixed]
       # @raise [RuntimeError]
@@ -1548,7 +1565,7 @@ module Oga
       # in the supplied node set, or the first node in the current context.
       #
       # @param [Oga::XML::NodeSet] context
-      # @param [Oga::XPath::Node] expression
+      # @param [AST::Node] expression
       # @return [Oga::XML::Node]
       #
       def function_node(context, expression = nil)
@@ -1596,7 +1613,7 @@ module Oga
       end
 
       ##
-      # Checks if a given {Oga::XML::Node} instance matches a {Oga::XPath::Node}
+      # Checks if a given {Oga::XML::Node} instance matches a `AST::Node`
       # instance.
       #
       # This method can use both "test" and "type-test" nodes. In case of
@@ -1614,7 +1631,7 @@ module Oga
       # For both the name and namespace a wildcard (`*`) can be used.
       #
       # @param [Oga::XML::Node] xml_node
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @return [Oga::XML::NodeSet]
       #
       def node_matches?(xml_node, ast_node)
@@ -1645,7 +1662,7 @@ module Oga
 
       ##
       # @param [Oga::XML::Node] xml_node
-      # @param [Oga::XPath::Node] ast_node
+      # @param [AST::Node] ast_node
       # @return [TrueClass|FalseClass]
       #
       def type_matches?(xml_node, ast_node)
@@ -1744,6 +1761,26 @@ module Oga
       def current_node_set
         return @node_sets.last
       end
+
+      ##
+      # Returns the root node of `node`, or `node` itself if its a Document.
+      #
+      # @param [Oga::XML::Node|Oga::XML::Document] node
+      # @return [Oga::XML::Node|Oga::XML::Document]
+      #
+      def root_node(node)
+        return node.respond_to?(:root_node) ? node.root_node : node
+      end
+
+      ##
+      # Returns the parent node of `node`, or `node` itself if its a Document.
+      #
+      # @param [Oga::XML::Node|Oga::XML::Document] node
+      # @return [Oga::XML::Node|Oga::XML::Document]
+      #
+      def parent_node(node)
+        return node.respond_to?(:parent) ? node.parent : node
+      end
     end # Evaluator
   end # XPath
 end # Oga