oga 0.1.0

data/lib/oga/xml/element.rb

@@ -0,0 +1,340 @@
+module Oga
+  module XML
+    ##
+    # Class that contains information about an XML element such as the name,
+    # attributes and child nodes.
+    #
+    # @!attribute [rw] name
+    #  The name of the element.
+    #  @return [String]
+    #
+    # @!attribute [ww] namespace_name
+    #  The name of the namespace.
+    #  @return [String]
+    #
+    # @!attribute [rw] attributes
+    #  The attributes of the element.
+    #  @return [Array<Oga::XML::Attribute>]
+    #
+    # @!attribute [rw] namespaces
+    #  The registered namespaces.
+    #  @return [Hash]
+    #
+    class Element < Node
+      include Querying
+
+      attr_accessor :name, :namespace_name, :attributes, :namespaces
+
+      ##
+      # The attribute prefix/namespace used for registering element namespaces.
+      #
+      # @return [String]
+      #
+      XMLNS_PREFIX = 'xmlns'.freeze
+
+      ##
+      # @param [Hash] options
+      #
+      # @option options [String] :name The name of the element.
+      #
+      # @option options [String] :namespace_name The name of the namespace.
+      #
+      # @option options [Array<Oga::XML::Attribute>] :attributes The attributes
+      #  of the element as an Array.
+      #
+      def initialize(options = {})
+        super
+
+        @name           = options[:name]
+        @namespace_name = options[:namespace_name]
+        @attributes     = options[:attributes] || []
+        @namespaces     = options[:namespaces] || {}
+
+        link_attributes
+        register_namespaces_from_attributes
+      end
+
+      ##
+      # Returns an attribute matching the given name (with or without the
+      # namespace).
+      #
+      # @example
+      #  # find an attribute that only has the name "foo"
+      #  attribute('foo')
+      #
+      #  # find an attribute with namespace "foo" and name bar"
+      #  attribute('foo:bar')
+      #
+      # @param [String|Symbol] name The name (with or without the namespace)
+      #  of the attribute.
+      #
+      # @return [Oga::XML::Attribute]
+      #
+      def attribute(name)
+        name, ns = split_name(name)
+
+        attributes.each do |attr|
+          return attr if attribute_matches?(attr, ns, name)
+        end
+
+        return
+      end
+
+      alias_method :attr, :attribute
+
+      ##
+      # Returns the value of the given attribute.
+      #
+      # @example
+      #  element.get('class') # => "container"
+      #
+      # @see [#attribute]
+      #
+      def get(name)
+        found = attribute(name)
+
+        return found ? found.value : nil
+      end
+
+      ##
+      # Adds a new attribute to the element.
+      #
+      # @param [Oga::XML::Attribute] attribute
+      #
+      def add_attribute(attribute)
+        attribute.element = self
+
+        attributes << attribute
+      end
+
+      ##
+      # Sets the value of an attribute to the given value. If the attribute does
+      # not exist it is created automatically.
+      #
+      # @param [String] name The name of the attribute, optionally including the
+      #  namespace.
+      #
+      # @param [String] value The new value of the attribute.
+      #
+      def set(name, value)
+        found = attribute(name)
+
+        if found
+          found.value = value
+        else
+          if name.include?(':')
+            ns, name = name.split(':')
+          else
+            ns = nil
+          end
+
+          attr = Attribute.new(
+            :name           => name,
+            :namespace_name => ns,
+            :value          => value
+          )
+
+          add_attribute(attr)
+        end
+      end
+
+      ##
+      # Returns the namespace of the element.
+      #
+      # @return [Oga::XML::Namespace]
+      #
+      def namespace
+        return @namespace ||= available_namespaces[namespace_name]
+      end
+
+      ##
+      # Returns the text of all child nodes joined together.
+      #
+      # @return [String]
+      #
+      def text
+        return children.text
+      end
+
+      ##
+      # Returns the text of the current element only.
+      #
+      # @return [String]
+      #
+      def inner_text
+        text = ''
+
+        text_nodes.each do |node|
+          text << node.text
+        end
+
+        return text
+      end
+
+      ##
+      # Returns any {Oga::XML::Text} nodes that are a direct child of this
+      # element.
+      #
+      # @return [Oga::XML::NodeSet]
+      #
+      def text_nodes
+        nodes = NodeSet.new
+
+        children.each do |child|
+          nodes << child if child.is_a?(Text)
+        end
+
+        return nodes
+      end
+
+      ##
+      # Sets the inner text of the current element to the given String.
+      #
+      # @param [String] text
+      #
+      def inner_text=(text)
+        children.each do |child|
+          child.remove if child.is_a?(Text)
+        end
+
+        children << XML::Text.new(:text => text)
+      end
+
+      ##
+      # Converts the element and its child elements to XML.
+      #
+      # @return [String]
+      #
+      def to_xml
+        ns    = namespace ? "#{namespace}:" : ''
+        body  = children.map(&:to_xml).join('')
+        attrs = ''
+
+        attributes.each do |attr|
+          attrs << attr.to_xml
+        end
+
+        attrs = " #{attrs}" unless attrs.empty?
+
+        return "<#{ns}#{name}#{attrs}>#{body}</#{ns}#{name}>"
+      end
+
+      ##
+      # @return [String]
+      #
+      def inspect
+        segments = []
+
+        [:name, :namespace, :attributes, :children].each do |attr|
+          value = send(attr)
+
+          if !value or (value.respond_to?(:empty?) and value.empty?)
+            next
+          end
+
+          segments << "#{attr}: #{value.inspect}"
+        end
+
+        return "Element(#{segments.join(' ')})"
+      end
+
+      ##
+      # @return [Symbol]
+      #
+      def node_type
+        return :element
+      end
+
+      ##
+      # Registers a new namespace for the current element and its child
+      # elements.
+      #
+      # @param [String] name
+      # @param [String] uri
+      # @see [Oga::XML::Namespace#initialize]
+      #
+      def register_namespace(name, uri)
+        if namespaces[name]
+          raise ArgumentError, "The namespace #{name.inspect} already exists"
+        end
+
+        namespaces[name] = Namespace.new(:name => name, :uri => uri)
+      end
+
+      ##
+      # Returns a Hash containing all the namespaces available to the current
+      # element.
+      #
+      # @return [Hash]
+      #
+      def available_namespaces
+        merged = namespaces
+        node   = parent
+
+        while node && node.respond_to?(:namespaces)
+          merged = merged.merge(node.namespaces)
+          node   = node.parent
+        end
+
+        return merged
+      end
+
+      private
+
+      ##
+      # Registers namespaces based on any "xmlns" attributes. Once a namespace
+      # has been registered the corresponding attribute is removed.
+      #
+      def register_namespaces_from_attributes
+        self.attributes = attributes.reject do |attr|
+          # We're using `namespace_name` opposed to `namespace.name` as "xmlns"
+          # is not a registered namespace.
+          remove = attr.namespace_name && attr.namespace_name == XMLNS_PREFIX
+
+          register_namespace(attr.name, attr.value) if remove
+
+          remove
+        end
+      end
+
+      ##
+      # Links all attributes to the current element.
+      #
+      def link_attributes
+        attributes.each do |attr|
+          attr.element = self
+        end
+      end
+
+      ##
+      # @param [String] name
+      # @return [Array]
+      #
+      def split_name(name)
+        segments = name.to_s.split(':')
+
+        return segments.pop, segments.pop
+      end
+
+      ##
+      # @param [Oga::XML::Attribute] attr
+      # @param [String] ns
+      # @param [String] name
+      # @return [TrueClass|FalseClass]
+      #
+      def attribute_matches?(attr, ns, name)
+        name_matches = attr.name == name
+        ns_matches   = false
+
+        if ns
+          ns_matches = attr.namespace.to_s == ns
+
+        elsif name_matches and !attr.namespace
+          ns_matches = true
+        end
+
+        return name_matches && ns_matches
+      end
+    end # Element
+  end # XML
+end # Oga

data/lib/oga/xml/lexer.rb

@@ -0,0 +1,399 @@
+module Oga
+  module XML
+    ##
+    # Low level lexer that supports both XML and HTML (using an extra option).
+    # To lex HTML input set the `:html` option to `true` when creating an
+    # instance of the lexer:
+    #
+    #     lexer = Oga::XML::Lexer.new(:html => true)
+    #
+    # This lexer can process both String and IO instances. IO instances are
+    # processed on a line by line basis. This can greatly reduce memory usage
+    # in exchange for a slightly slower runtime.
+    #
+    # ## Thread Safety
+    #
+    # Since this class keeps track of an internal state you can not use the
+    # same instance between multiple threads at the same time. For example, the
+    # following will not work reliably:
+    #
+    #     # Don't do this!
+    #     lexer   = Oga::XML::Lexer.new('....')
+    #     threads = []
+    #
+    #     2.times do
+    #       threads << Thread.new do
+    #         lexer.advance do |*args|
+    #           p args
+    #         end
+    #       end
+    #     end
+    #
+    #     threads.each(&:join)
+    #
+    # However, it is perfectly save to use different instances per thread.
+    # There is no _global_ state used by this lexer.
+    #
+    # @!attribute [r] html
+    #  @return [TrueClass|FalseClass]
+    #
+    class Lexer
+      attr_reader :html
+
+      ##
+      # Names of the HTML void elements that should be handled when HTML lexing
+      # is enabled.
+      #
+      # @return [Set]
+      #
+      HTML_VOID_ELEMENTS = Set.new([
+        'area',
+        'base',
+        'br',
+        'col',
+        'command',
+        'embed',
+        'hr',
+        'img',
+        'input',
+        'keygen',
+        'link',
+        'meta',
+        'param',
+        'source',
+        'track',
+        'wbr'
+      ])
+
+      ##
+      # @param [String|IO] data The data to lex. This can either be a String or
+      #  an IO instance.
+      #
+      # @param [Hash] options
+      #
+      # @option options [Symbol] :html When set to `true` the lexer will treat
+      #  the input as HTML instead of SGML/XML. This makes it possible to lex
+      #  HTML void elements such as `<link href="">`.
+      #
+      def initialize(data, options = {})
+        @data = data
+        @html = options[:html]
+
+        reset
+      end
+
+      ##
+      # Resets the internal state of the lexer. Typically you don't need to
+      # call this method yourself as its called by #lex after lexing a given
+      # String.
+      #
+      def reset
+        @line     = 1
+        @elements = []
+
+        @data.rewind if io_input?
+
+        reset_native
+      end
+
+      ##
+      # Yields the data to lex to the supplied block.
+      #
+      # @return [String]
+      # @yieldparam [String]
+      #
+      def read_data
+        # We can't check for #each_line since String also defines that. Using
+        # String#each_line has no benefit over just lexing the String in one
+        # go.
+        if io_input?
+          @data.each_line do |line|
+            yield line
+          end
+        else
+          yield @data
+        end
+      end
+
+      ##
+      # Returns `true` if the input is an IO like object, false otherwise.
+      #
+      # @return [TrueClass|FalseClass]
+      #
+      def io_input?
+        return @data.is_a?(IO) || @data.is_a?(StringIO)
+      end
+
+      ##
+      # Gathers all the tokens for the input and returns them as an Array.
+      #
+      # This method resets the internal state of the lexer after consuming the
+      # input.
+      #
+      # @see #advance
+      # @return [Array]
+      #
+      def lex
+        tokens = []
+
+        advance do |type, value, line|
+          tokens << [type, value, line]
+        end
+
+        reset
+
+        return tokens
+      end
+
+      ##
+      # Advances through the input and generates the corresponding tokens. Each
+      # token is yielded to the supplied block.
+      #
+      # Each token is an Array in the following format:
+      #
+      #     [TYPE, VALUE]
+      #
+      # The type is a symbol, the value is either nil or a String.
+      #
+      # This method stores the supplied block in `@block` and resets it after
+      # the lexer loop has finished.
+      #
+      # This method does *not* reset the internal state of the lexer.
+      #
+      # @yieldparam [Symbol] type
+      # @yieldparam [String] value
+      # @yieldparam [Fixnum] line
+      #
+      def advance(&block)
+        @block = block
+
+        read_data do |chunk|
+          advance_native(chunk)
+        end
+      ensure
+        @block = nil
+      end
+
+      ##
+      # @return [TrueClass|FalseClass]
+      #
+      def html?
+        return !!html
+      end
+
+      private
+
+      ##
+      # @param [Fixnum] amount The amount of lines to advance.
+      #
+      def advance_line(amount = 1)
+        @line += amount
+      end
+
+      ##
+      # Calls the supplied block with the information of the current token.
+      #
+      # @param [Symbol] type The token type.
+      # @param [String] value The token value.
+      #
+      # @yieldparam [String] type
+      # @yieldparam [String] value
+      # @yieldparam [Fixnum] line
+      #
+      def add_token(type, value = nil)
+        @block.call(type, value, @line)
+      end
+
+      ##
+      # Returns the name of the element we're currently in.
+      #
+      # @return [String]
+      #
+      def current_element
+        return @elements.last
+      end
+
+      ##
+      # Called when processing single/double quoted strings.
+      #
+      # @param [String] value The data between the quotes.
+      #
+      def on_string(value)
+        add_token(:T_STRING, value)
+      end
+
+      ##
+      # Called when a doctype starts.
+      #
+      def on_doctype_start
+        add_token(:T_DOCTYPE_START)
+      end
+
+      ##
+      # Called on the identifier specifying the type of the doctype.
+      #
+      # @param [String] value
+      #
+      def on_doctype_type(value)
+        add_token(:T_DOCTYPE_TYPE, value)
+      end
+
+      ##
+      # Called on the identifier specifying the name of the doctype.
+      #
+      # @param [String] value
+      #
+      def on_doctype_name(value)
+        add_token(:T_DOCTYPE_NAME, value)
+      end
+
+      ##
+      # Called on the end of a doctype.
+      #
+      def on_doctype_end
+        add_token(:T_DOCTYPE_END)
+      end
+
+      ##
+      # Called on an inline doctype block.
+      #
+      # @param [String] value
+      #
+      def on_doctype_inline(value)
+        add_token(:T_DOCTYPE_INLINE, value)
+      end
+
+      ##
+      # Called on a CDATA tag.
+      #
+      def on_cdata(value)
+        add_token(:T_CDATA, value)
+      end
+
+      ##
+      # Called on a comment.
+      #
+      # @param [String] value
+      #
+      def on_comment(value)
+        add_token(:T_COMMENT, value)
+      end
+
+      ##
+      # Called on the start of an XML declaration tag.
+      #
+      def on_xml_decl_start
+        add_token(:T_XML_DECL_START)
+      end
+
+      ##
+      # Called on the end of an XML declaration tag.
+      #
+      def on_xml_decl_end
+        add_token(:T_XML_DECL_END)
+      end
+
+      ##
+      # Called on the start of an element.
+      #
+      def on_element_start
+        add_token(:T_ELEM_START)
+      end
+
+      ##
+      # Called on the start of a processing instruction.
+      #
+      def on_proc_ins_start
+        add_token(:T_PROC_INS_START)
+      end
+
+      ##
+      # Called on a processing instruction name.
+      #
+      # @param [String] value
+      #
+      def on_proc_ins_name(value)
+        add_token(:T_PROC_INS_NAME, value)
+      end
+
+      ##
+      # Called on the end of a processing instruction.
+      #
+      def on_proc_ins_end
+        add_token(:T_PROC_INS_END)
+      end
+
+      ##
+      # Called on the name of an element.
+      #
+      # @param [String] name The name of the element, including namespace.
+      #
+      def on_element_name(name)
+        @elements << name if html?
+
+        add_token(:T_ELEM_NAME, name)
+      end
+
+      ##
+      # Called on the element namespace.
+      #
+      # @param [String] namespace
+      #
+      def on_element_ns(namespace)
+        add_token(:T_ELEM_NS, namespace)
+      end
+
+      ##
+      # Called on the closing `>` of the open tag of an element.
+      #
+      def on_element_open_end
+        if html? and HTML_VOID_ELEMENTS.include?(current_element)
+          add_token(:T_ELEM_END)
+          @elements.pop
+        end
+      end
+
+      ##
+      # Called on the closing tag of an element.
+      #
+      def on_element_end
+        add_token(:T_ELEM_END)
+
+        @elements.pop if html?
+      end
+
+      ##
+      # Called on regular text values.
+      #
+      # @param [String] value
+      #
+      def on_text(value)
+        unless value.empty?
+          add_token(:T_TEXT, value)
+
+          lines = value.count("\n")
+
+          advance_line(lines) if lines > 0
+        end
+      end
+
+      ##
+      # Called on attribute namespaces.
+      #
+      # @param [String] value
+      #
+      def on_attribute_ns(value)
+        add_token(:T_ATTR_NS, value)
+      end
+
+      ##
+      # Called on tag attributes.
+      #
+      # @param [String] value
+      #
+      def on_attribute(value)
+        add_token(:T_ATTR, value)
+      end
+    end # Lexer
+  end # XML
+end # Oga