XML module for more easily querying using XPath.

lib/oga.rb

@@ -16,6 +16,7 @@ if RUBY_PLATFORM == 'java'
 end
 #:nocov:
 
+require_relative 'oga/xml/querying'
 require_relative 'oga/xml/node'
 require_relative 'oga/xml/document'
 require_relative 'oga/xml/character_node'

lib/oga/xml/document.rb

@@ -13,6 +13,8 @@ module Oga
     #  @return [Oga::XML::XmlDeclaration]
     #
     class Document
+      include Querying
+
       attr_accessor :doctype, :xml_declaration
 
       ##

lib/oga/xml/element.rb

@@ -21,6 +21,8 @@ module Oga
     #  @return [Hash]
     #
     class Element < Node
+      include Querying
+
       attr_accessor :name, :namespace_name, :attributes, :namespaces
 
       ##

lib/oga/xml/querying.rb

@@ -0,0 +1,32 @@
+module Oga
+  module XML
+    ##
+    # The Querying module provides methods that make it easy to run XPath/CSS
+    # queries on XML documents/elements.
+    #
+    module Querying
+      ##
+      # Evaluates the given XPath expression.
+      #
+      # @param [String] expression The XPath expression to run.
+      # @param [Hash] variables Variables to bind.
+      # @see [Oga::XPath::Evaluator#initialize]
+      #
+      def xpath(expression, variables = {})
+        return XPath::Evaluator.new(self, variables).evaluate(expression)
+      end
+
+      ##
+      # Evaluates the given XPath expression and returns the first node in the
+      # set.
+      #
+      # @see [#xpath]
+      #
+      def at_xpath(*args)
+        result = xpath(*args)
+
+        return result.is_a?(XML::NodeSet) ? result.first : result
+      end
+    end # Querying
+  end # XML
+end # Oga