oga 1.2.3-java → 1.3.0-java

data/lib/oga/xml/parser.rb

@@ -5,7 +5,6 @@ require 'll/setup'
 
 module Oga
 module XML
-##
 # DOM parser for both XML and HTML.
 #
 # This parser does not produce a dedicated AST, instead it emits XML nodes
@@ -186,11 +185,9 @@ class Parser < LL::Driver
     [:_rule_45, 1], # 45
   ].freeze
 
-  ##
   # Hash mapping token types and dedicated error labels.
   #
   # @return [Hash]
-  #
   TOKEN_ERROR_MAPPING = {
     :T_STRING         => 'string',
     :T_TEXT           => 'text',
@@ -215,11 +212,9 @@ class Parser < LL::Driver
     -1                => 'end of input'
   }
 
-  ##
   # @param [String|IO] data The input to parse.
   # @param [Hash] options
   # @see [Oga::XML::Lexer#initialize]
-  #
   def initialize(data, options = {})
     @data  = data
     @lexer = Lexer.new(data, options)
@@ -227,20 +222,16 @@ class Parser < LL::Driver
     reset
   end
 
-  ##
   # Resets the internal state of the parser.
-  #
   def reset
     @line = 1
 
     @lexer.reset
   end
 
-  ##
   # Yields the next token from the lexer.
   #
   # @yieldparam [Array]
-  #
   def each_token
     @lexer.advance do |type, value, line|
       @line = line if line
@@ -251,12 +242,10 @@ class Parser < LL::Driver
     yield [-1, -1]
   end
 
-  ##
   # @param [Fixnum] stack_type
   # @param [Fixnum] stack_value
   # @param [Symbol] token_type
   # @param [String] token_value
-  #
   def parser_error(stack_type, stack_value, token_type, token_value)
     case id_to_type(stack_type)
     when :rule
@@ -275,21 +264,17 @@ class Parser < LL::Driver
     raise LL::ParserError, message
   end
 
-  ##
   # @see [LL::Driver#parse]
-  #
   def parse
     retval = super
 
     reset
 
-    return retval
+    retval
   end
 
-  ##
   # @param [Array] children
   # @return [Oga::XML::Document]
-  #
   def on_document(children = [])
     document = Document.new(:type => @lexer.html? ? :html : :xml)
 
@@ -305,45 +290,35 @@ class Parser < LL::Driver
       end
     end
 
-    return document
+    document
   end
 
-  ##
   # @param [Hash] options
-  #
   def on_doctype(options = {})
-    return Doctype.new(options)
+    Doctype.new(options)
   end
 
-  ##
   # @param [String] text
   # @return [Oga::XML::Cdata]
-  #
   def on_cdata(text = nil)
-    return Cdata.new(:text => text)
+    Cdata.new(:text => text)
   end
 
-  ##
   # @param [String] text
   # @return [Oga::XML::Comment]
-  #
   def on_comment(text = nil)
-    return Comment.new(:text => text)
+    Comment.new(:text => text)
   end
 
-  ##
   # @param [String] name
   # @param [String] text
   # @return [Oga::XML::ProcessingInstruction]
-  #
   def on_proc_ins(name, text = nil)
-    return ProcessingInstruction.new(:name => name, :text => text)
+    ProcessingInstruction.new(:name => name, :text => text)
   end
 
-  ##
   # @param [Array] attributes
   # @return [Oga::XML::XmlDeclaration]
-  #
   def on_xml_decl(attributes = [])
     options = {}
 
@@ -351,23 +326,19 @@ class Parser < LL::Driver
       options[attr.name.to_sym] = attr.value
     end
 
-    return XmlDeclaration.new(options)
+    XmlDeclaration.new(options)
   end
 
-  ##
   # @param [String] text
   # @return [Oga::XML::Text]
-  #
   def on_text(text)
-    return Text.new(:text => text)
+    Text.new(:text => text)
   end
 
-  ##
   # @param [String] namespace
   # @param [String] name
   # @param [Hash] attributes
   # @return [Oga::XML::Element]
-  #
   def on_element(namespace, name, attributes = {})
     element = Element.new(
       :namespace_name => namespace,
@@ -375,47 +346,39 @@ class Parser < LL::Driver
       :attributes     => attributes
     )
 
-    return element
+    element
   end
 
-  ##
   # @param [Oga::XML::Element] element
   # @param [Array] children
   # @return [Oga::XML::Element]
-  #
   def on_element_children(element, children = [])
     element.children = children
 
-    return element
+    element
   end
 
-  ##
   # @param [Oga::XML::Element] element
   # @return [Oga::XML::Element]
-  #
   def after_element(element)
-    return element
+    element
   end
 
-  ##
   # @param [String] name
   # @param [String] ns_name
   # @param [String] value
   # @return [Oga::XML::Attribute]
-  #
   def on_attribute(name, ns_name = nil, value = nil)
-    return Attribute.new(
+    Attribute.new(
       :namespace_name => ns_name,
       :name           => name,
       :value          => value
     )
   end
 
-  ##
   # @param [Array] attrs
-  #
   def on_attributes(attrs)
-    return attrs
+    attrs
   end
 
   def _rule_0(val)

data/lib/oga/xml/processing_instruction.rb

@@ -1,34 +1,26 @@
 module Oga
   module XML
-    ##
     # Class used for storing information about a single processing instruction.
-    #
     class ProcessingInstruction < CharacterNode
       # @return [String]
       attr_accessor :name
 
-      ##
       # @param [Hash] options
       #
       # @option options [String] :name The name of the instruction.
       # @see [Oga::XML::CharacterNode#initialize]
-      #
       def initialize(options = {})
         super
 
         @name = options[:name]
       end
 
-      ##
       # @return [String]
-      #
       def to_xml
         "<?#{name}#{text}?>"
       end
 
-      ##
       # @return [String]
-      #
       def inspect
         "ProcessingInstruction(name: #{name.inspect} text: #{text.inspect})"
       end

data/lib/oga/xml/pull_parser.rb

@@ -1,6 +1,5 @@
 module Oga
   module XML
-    ##
     # The PullParser class can be used to parse an XML document incrementally
     # instead of parsing it as a whole. This results in lower memory usage and
     # potentially faster parsing times. The downside is that pull parsers are
@@ -18,7 +17,6 @@ module Oga
     #
     # This parses yields proper XML instances such as {Oga::XML::Element}.
     # Doctypes and XML declarations are ignored by this parser.
-    #
     class PullParser < Parser
       # @return [Oga::XML::Node]
       attr_reader :node
@@ -27,9 +25,7 @@ module Oga
       # @return [Array]
       attr_reader :nesting
 
-      ##
       # @return [Array]
-      #
       DISABLED_CALLBACKS = [
         :on_document,
         :on_doctype,
@@ -37,9 +33,7 @@ module Oga
         :on_element_children
       ]
 
-      ##
       # @return [Array]
-      #
       BLOCK_CALLBACKS = [
         :on_cdata,
         :on_comment,
@@ -47,11 +41,9 @@ module Oga
         :on_proc_ins
       ]
 
-      ##
       # Returns the shorthands that can be used for various node classes.
       #
       # @return [Hash]
-      #
       NODE_SHORTHANDS = {
         :text            => XML::Text,
         :node            => XML::Node,
@@ -62,9 +54,7 @@ module Oga
         :xml_declaration => XML::XmlDeclaration
       }
 
-      ##
       # @see Oga::XML::Parser#reset
-      #
       def reset
         super
 
@@ -73,11 +63,9 @@ module Oga
         @node    = nil
       end
 
-      ##
       # Parses the input and yields every node to the supplied block.
       #
       # @yieldparam [Oga::XML::Node]
-      #
       def parse(&block)
         @block = block
 
@@ -86,7 +74,6 @@ 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:
       #
@@ -120,7 +107,6 @@ module Oga
       #  returned by {Oga::XML::Node#node_type}.
       #
       # @param [Array] nesting The element name nesting to act upon.
-      #
       def on(type, nesting = [])
         if node.is_a?(NODE_SHORTHANDS[type])
           if nesting.empty? or nesting == self.nesting
@@ -149,9 +135,7 @@ module Oga
         EOF
       end
 
-      ##
       # @see Oga::XML::Parser#on_element
-      #
       def on_element(*args)
         @node = super
 
@@ -162,9 +146,7 @@ module Oga
         return
       end
 
-      ##
       # @see Oga::XML::Parser#on_element_children
-      #
       def after_element(*args)
         nesting.pop
 

data/lib/oga/xml/querying.rb

@@ -1,51 +1,90 @@
 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.
       #
+      # Querying a document:
+      #
+      #     document = Oga.parse_xml <<-EOF
+      #     <people>
+      #       <person age="25">Alice</person>
+      #     </people>
+      #     EOF
+      #
+      #     document.xpath('people/person')
+      #
+      # Querying an element:
+      #
+      #     element = document.at_xpath('people')
+      #
+      #     element.xpath('person')
+      #
+      # Using variable bindings:
+      #
+      #     document.xpath('people/person[@age = $age]', 'age' => 25)
+      #
       # @param [String] expression The XPath expression to run.
-      # @param [Hash] variables Variables to bind.
-      # @see [Oga::XPath::Evaluator#initialize]
       #
+      # @param [Hash] variables Variables to bind. The keys of this Hash should
+      #  be String values.
+      #
+      # @return [Oga::XML::NodeSet]
       def xpath(expression, variables = {})
-        XPath::Evaluator.new(self, variables).evaluate(expression)
+        ast   = XPath::Parser.parse_with_cache(expression)
+        block = XPath::Compiler.compile_with_cache(ast)
+
+        block.call(self, variables)
       end
 
-      ##
-      # Evaluates the given XPath expression and returns the first node in the
-      # set.
+      # Evaluates the XPath expression and returns the first matched node.
       #
-      # @see [#xpath]
+      # Querying a document:
+      #
+      #     document = Oga.parse_xml <<-EOF
+      #     <people>
+      #       <person age="25">Alice</person>
+      #     </people>
+      #     EOF
+      #
+      #     person = document.at_xpath('people/person')
       #
+      #     person.class # => Oga::XML::Element
+      #
+      # @see [#xpath]
+      # @return [Oga::XML::Node|Oga::XML::Attribute]
       def at_xpath(*args)
         result = xpath(*args)
 
         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]
+      # Querying a document:
+      #
+      #     document = Oga.parse_xml <<-EOF
+      #     <people>
+      #       <person age="25">Alice</person>
+      #     </people>
+      #     EOF
+      #
+      #     document.css('people person')
       #
+      # @param [String] expression The CSS expression to run.
+      # @return [Oga::XML::NodeSet]
       def css(expression)
-        ast = CSS::Parser.parse_with_cache(expression)
+        ast   = CSS::Parser.parse_with_cache(expression)
+        block = XPath::Compiler.compile_with_cache(ast)
 
-        XPath::Evaluator.new(self).evaluate_ast(ast)
+        block.call(self)
       end
 
-      ##
-      # Evaluates the given CSS expression and returns the first node in the
-      # set.
+      # Evaluates the CSS expression and returns the first matched node.
       #
       # @see [#css]
-      #
+      # @return [Oga::XML::Node|Oga::XML::Attribute]
       def at_css(*args)
         result = css(*args)