rubyjedi-oga 1.0.3

data/lib/oga/xml/processing_instruction.rb

@@ -0,0 +1,37 @@
+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
+    end # ProcessingInstruction
+  end # XML
+end # Oga

data/lib/oga/xml/pull_parser.rb

@@ -0,0 +1,175 @@
+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
+    # typically more difficult to use compared to DOM parsers.
+    #
+    # Basic parsing using this class works as following:
+    #
+    #     parser = Oga::XML::PullParser.new('... xml here ...')
+    #
+    #     parser.parse do |node|
+    #       if node.is_a?(Oga::XML::PullParser)
+    #
+    #       end
+    #     end
+    #
+    # 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
+
+      # Array containing the names of the currently nested elements.
+      # @return [Array]
+      attr_reader :nesting
+
+      ##
+      # @return [Array]
+      #
+      DISABLED_CALLBACKS = [
+        :on_document,
+        :on_doctype,
+        :on_xml_decl,
+        :on_element_children
+      ]
+
+      ##
+      # @return [Array]
+      #
+      BLOCK_CALLBACKS = [
+        :on_cdata,
+        :on_comment,
+        :on_text,
+        :on_proc_ins
+      ]
+
+      ##
+      # Returns the shorthands that can be used for various node classes.
+      #
+      # @return [Hash]
+      #
+      NODE_SHORTHANDS = {
+        :text            => XML::Text,
+        :node            => XML::Node,
+        :cdata           => XML::Cdata,
+        :element         => XML::Element,
+        :doctype         => XML::Doctype,
+        :comment         => XML::Comment,
+        :xml_declaration => XML::XmlDeclaration
+      }
+
+      ##
+      # @see Oga::XML::Parser#reset
+      #
+      def reset
+        super
+
+        @block   = nil
+        @nesting = []
+        @node    = nil
+      end
+
+      ##
+      # Parses the input and yields every node to the supplied block.
+      #
+      # @yieldparam [Oga::XML::Node]
+      #
+      def parse(&block)
+        @block = block
+
+        super
+
+        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.is_a?(Oga::XML::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.is_a?(NODE_SHORTHANDS[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|
+        eval <<-EOF, nil, __FILE__, __LINE__ + 1
+        def #{method}(*args)
+          return
+        end
+        EOF
+      end
+
+      BLOCK_CALLBACKS.each do |method|
+        eval <<-EOF, nil, __FILE__, __LINE__ + 1
+        def #{method}(*args)
+          @node = super
+          @block.call(@node)
+          return
+        end
+        EOF
+      end
+
+      ##
+      # @see Oga::XML::Parser#on_element
+      #
+      def on_element(*args)
+        @node = super
+
+        nesting << @node.name
+
+        @block.call(@node)
+
+        return
+      end
+
+      ##
+      # @see Oga::XML::Parser#on_element_children
+      #
+      def after_element(*args)
+        nesting.pop
+
+        return
+      end
+    end # PullParser
+  end # XML
+end # Oga

data/lib/oga/xml/querying.rb

@@ -0,0 +1,56 @@
+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 = {})
+        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)
+
+        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.parse_with_cache(expression)
+
+        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)
+
+        result.is_a?(XML::NodeSet) ? result.first : result
+      end
+    end # Querying
+  end # XML
+end # Oga

data/lib/oga/xml/sax_parser.rb

@@ -0,0 +1,192 @@
+module Oga
+  module XML
+    ##
+    # The SaxParser class provides the basic interface for writing custom SAX
+    # parsers. All callback methods defined in {Oga::XML::Parser} are delegated
+    # to a dedicated handler class.
+    #
+    # To write a custom handler for the SAX parser, create a class that
+    # implements one (or many) of the following callback methods:
+    #
+    # * `on_document`
+    # * `on_doctype`
+    # * `on_cdata`
+    # * `on_comment`
+    # * `on_proc_ins`
+    # * `on_xml_decl`
+    # * `on_text`
+    # * `on_element`
+    # * `on_element_children`
+    # * `on_attribute`
+    # * `on_attributes`
+    # * `after_element`
+    #
+    # For example:
+    #
+    #     class SaxHandler
+    #       def on_element(namespace, name, attrs = {})
+    #         puts name
+    #       end
+    #     end
+    #
+    # You can then use it as following:
+    #
+    #     handler = SaxHandler.new
+    #     parser  = Oga::XML::SaxParser.new(handler, '<foo />')
+    #
+    #     parser.parse
+    #
+    # 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
+    #
+    # ## Attributes
+    #
+    # Attributes returned by `on_attribute` are passed as an Hash as the 3rd
+    # argument of the `on_element` callback. The keys of this Hash are the
+    # attribute names (optionally prefixed by their namespace) and their values.
+    # You can overwrite `on_attribute` to control individual attributes and
+    # `on_attributes` to control the final set.
+    #
+    class SaxParser < Parser
+      ##
+      # @param [Object] handler The SAX handler to delegate callbacks to.
+      # @see [Oga::XML::Parser#initialize]
+      #
+      def initialize(handler, *args)
+        @handler = handler
+
+        super(*args)
+      end
+
+      # Delegate all callbacks to the handler object.
+      instance_methods.grep(/^(on_|after_)/).each do |method|
+        eval <<-EOF, nil, __FILE__, __LINE__ + 1
+        def #{method}(*args)
+          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)
+
+        [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)
+
+        return
+      end
+
+      ##
+      # Manually overwrite this method since for this one we _do_ want the
+      # return value so it can be passed to `on_element`.
+      #
+      # @see [Oga::XML::Parser#on_attribute]
+      #
+      def on_attribute(name, ns = nil, value = nil)
+        if @handler.respond_to?(:on_attribute)
+          return run_callback(:on_attribute, name, ns, value)
+        end
+
+        key = ns ? "#{ns}:#{name}" : name
+
+        if value
+          value = EntityDecoder.try_decode(value, @lexer.html?)
+        end
+
+        {key => value}
+      end
+
+      ##
+      # Merges the attributes together into a Hash.
+      #
+      # @param [Array] attrs
+      # @return [Hash]
+      #
+      def on_attributes(attrs)
+        if @handler.respond_to?(:on_attributes)
+          return run_callback(:on_attributes, attrs)
+        end
+
+        merged = {}
+
+        attrs.each do |pair|
+          # Hash#merge requires an extra allocation, this doesn't.
+          pair.each { |key, value| merged[key] = value }
+        end
+
+        merged
+      end
+
+      ##
+      # @param [String] text
+      #
+      def on_text(text)
+        if @handler.respond_to?(:on_text)
+          unless inside_literal_html?
+            text = EntityDecoder.try_decode(text, @lexer.html?)
+          end
+
+          run_callback(:on_text, text)
+        end
+
+        return
+      end
+
+      private
+
+      ##
+      # @return [TrueClass|FalseClass]
+      #
+      def inside_literal_html?
+        @lexer.html_script? || @lexer.html_style?
+      end
+
+      ##
+      # @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