oga 1.2.3 → 1.3.0

data/lib/oga/xml/document.rb

@@ -1,9 +1,7 @@
 module Oga
   module XML
-    ##
     # Class used for storing information about an entire XML document. This
     # includes the doctype, XML declaration, child nodes and more.
-    #
     class Document
       include Querying
       include Traversal
@@ -18,14 +16,12 @@ module Oga
       # @return [Symbol]
       attr_reader :type
 
-      ##
       # @param [Hash] options
       #
       # @option options [Oga::XML::NodeSet] :children
       # @option options [Oga::XML::Doctype] :doctype
       # @option options [Oga::XML::XmlDeclaration] :xml_declaration
       # @option options [Symbol] :type
-      #
       def initialize(options = {})
         @doctype         = options[:doctype]
         @xml_declaration = options[:xml_declaration]
@@ -34,18 +30,14 @@ module Oga
         self.children = options[:children] if options[:children]
       end
 
-      ##
       # @return [Oga::XML::NodeSet]
-      #
       def children
         @children ||= NodeSet.new([], self)
       end
 
-      ##
       # Sets the child nodes of the document.
       #
       # @param [Oga::XML::NodeSet|Array] nodes
-      #
       def children=(nodes)
         if nodes.is_a?(NodeSet)
           @children = nodes
@@ -54,11 +46,19 @@ module Oga
         end
       end
 
-      ##
+      # Returns self.
+      #
+      # This method exists to make this class compatible with Element, which in
+      # turn makes it easier to use both in the XPath compiler.
+      #
+      # @return [Oga::XML::Document]
+      def root_node
+        self
+      end
+
       # Converts the document and its child nodes to XML.
       #
       # @return [String]
-      #
       def to_xml
         xml = children.map(&:to_xml).join('')
 
@@ -73,19 +73,15 @@ module Oga
         xml
       end
 
-      ##
       # @return [TrueClass|FalseClass]
-      #
       def html?
         type.equal?(:html)
       end
 
-      ##
       # Inspects the document and its child nodes. Child nodes are indented for
       # each nesting level.
       #
       # @return [String]
-      #
       def inspect
         segments = []
 

data/lib/oga/xml/element.rb

@@ -1,11 +1,10 @@
 module Oga
   module XML
-    ##
     # Class that contains information about an XML element such as the name,
     # attributes and child nodes.
-    #
     class Element < Node
       include Querying
+      include ExpandedName
 
       # @return [String]
       attr_reader :namespace_name
@@ -19,14 +18,11 @@ module Oga
       # @return [Hash]
       attr_writer :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.
@@ -35,7 +31,6 @@ module Oga
       #
       # @option options [Array<Oga::XML::Attribute>] :attributes The attributes
       #  of the element as an Array.
-      #
       def initialize(options = {})
         super
 
@@ -48,15 +43,12 @@ module Oga
         register_namespaces_from_attributes
       end
 
-      ##
       # @param [String] name
-      #
       def namespace_name=(name)
         @namespace_name = name
         @namespace      = nil
       end
 
-      ##
       # Returns an attribute matching the given name (with or without the
       # namespace).
       #
@@ -71,7 +63,6 @@ module Oga
       #  of the attribute.
       #
       # @return [Oga::XML::Attribute]
-      #
       def attribute(name)
         name, ns = split_name(name)
 
@@ -84,32 +75,27 @@ module Oga
 
       alias_method :attr, :attribute
 
-      ##
       # Returns the value of the given attribute.
       #
       # @example
       #  element.get('class') # => "container"
       #
       # @see [#attribute]
-      #
       def get(name)
         found = attribute(name)
 
         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.
       #
@@ -117,7 +103,6 @@ module Oga
       #  namespace.
       #
       # @param [String] value The new value of the attribute.
-      #
       def set(name, value)
         found = attribute(name)
 
@@ -140,25 +125,21 @@ module Oga
         end
       end
 
-      ##
       # Removes an attribute from the element.
       #
       # @param [String] name The name (optionally including namespace prefix)
       #  of the attribute to remove.
       #
       # @return [Oga::XML::Attribute]
-      #
       def unset(name)
         found = attribute(name)
 
         return attributes.delete(found) if found
       end
 
-      ##
       # Returns the namespace of the element.
       #
       # @return [Oga::XML::Namespace]
-      #
       def namespace
         unless @namespace
           available  = available_namespaces
@@ -168,40 +149,32 @@ module Oga
         @namespace
       end
 
-      ##
       # Returns the namespaces registered on this element, or an empty Hash in
       # case of an HTML element.
       #
       # @return [Hash]
-      #
       def namespaces
         html? ? {} : @namespaces
       end
 
-      ##
       # Returns true if the current element resides in the default XML
       # namespace.
       #
       # @return [TrueClass|FalseClass]
-      #
       def default_namespace?
         namespace == DEFAULT_NAMESPACE || namespace.nil?
       end
 
-      ##
       # Returns the text of all child nodes joined together.
       #
       # @return [String]
-      #
       def text
         children.text
       end
 
-      ##
       # Returns the text of the current element only.
       #
       # @return [String]
-      #
       def inner_text
         text = ''
 
@@ -212,12 +185,10 @@ module Oga
         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
 
@@ -228,21 +199,17 @@ module Oga
         nodes
       end
 
-      ##
       # Sets the inner text of the current element to the given String.
       #
       # @param [String] text
-      #
       def inner_text=(text)
         text_node = XML::Text.new(:text => text)
         @children = NodeSet.new([text_node], self)
       end
 
-      ##
       # Converts the element and its child elements to XML.
       #
       # @return [String]
-      #
       def to_xml
         if namespace_name
           full_name = "#{namespace_name}:#{name}"
@@ -264,9 +231,7 @@ module Oga
         end
       end
 
-      ##
       # @return [String]
-      #
       def inspect
         segments = []
 
@@ -283,7 +248,6 @@ module Oga
         "Element(#{segments.join(' ')})"
       end
 
-      ##
       # Registers a new namespace for the current element and its child
       # elements.
       #
@@ -291,7 +255,6 @@ module Oga
       # @param [String] uri
       # @param [TrueClass|FalseClass] flush
       # @see [Oga::XML::Namespace#initialize]
-      #
       def register_namespace(name, uri, flush = true)
         if namespaces[name]
           raise ArgumentError, "The namespace #{name.inspect} already exists"
@@ -302,12 +265,10 @@ module Oga
         flush_namespaces_cache if flush
       end
 
-      ##
       # Returns a Hash containing all the namespaces available to the current
       # element.
       #
       # @return [Hash]
-      #
       def available_namespaces
         # HTML(5) completely ignores namespaces
         unless @available_namespaces
@@ -332,11 +293,9 @@ module Oga
         @available_namespaces
       end
 
-      ##
       # Returns `true` if the element is a self-closing element.
       #
       # @return [TrueClass|FalseClass]
-      #
       def self_closing?
         self_closing = children.empty?
         root         = root_node
@@ -349,10 +308,8 @@ module Oga
         self_closing
       end
 
-      ##
       # Flushes the namespaces cache of the current element and all its child
       # elements.
-      #
       def flush_namespaces_cache
         @available_namespaces = nil
         @namespace            = nil
@@ -364,9 +321,7 @@ module Oga
 
       private
 
-      ##
       # Registers namespaces based on any "xmlns" attributes.
-      #
       def register_namespaces_from_attributes
         flush = false
 
@@ -385,31 +340,25 @@ module Oga
         flush_namespaces_cache if flush
       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(':')
 
         [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

data/lib/oga/xml/entities.rb

@@ -1,18 +1,14 @@
 module Oga
   module XML
-    ##
     # Module for encoding/decoding XML and HTML entities. The mapping of HTML
     # entities can be found in {Oga::HTML::Entities::DECODE_MAPPING}.
-    #
     module Entities
-      ##
       # Hash containing XML entities and the corresponding characters.
       #
       # The `&` mapping must come last to ensure proper conversion of non
       # encoded to encoded forms (see {Oga::XML::Text#to_xml}).
       #
       # @return [Hash]
-      #
       DECODE_MAPPING = {
         '&lt;'   => '<',
         '&gt;'   => '>',
@@ -21,23 +17,19 @@ module Oga
         '&amp;'  => '&',
       }
 
-      ##
       # Hash containing characters and the corresponding XML entities.
       #
       # @return [Hash]
-      #
       ENCODE_MAPPING = {
         '&' => '&amp;',
         '>' => '&gt;',
         '<' => '&lt;',
       }
 
-      ##
       # Hash containing characters and the corresponding XML entities to use
       # when encoding XML/HTML attribute values.
       #
       # @return [Hash]
-      #
       ENCODE_ATTRIBUTE_MAPPING = {
         '&' => '&amp;',
         '>' => '&gt;',
@@ -46,50 +38,36 @@ module Oga
         '"' => '&quot;'
       }
 
-      ##
       # @return [String]
-      #
       AMPERSAND = '&'.freeze
 
-      ##
       # Regexp for matching XML/HTML entities such as "&nbsp;".
       #
       # @return [Regexp]
-      #
       REGULAR_ENTITY = /&[a-zA-Z0-9]+;/
 
-      ##
       # Regexp for matching XML/HTML numeric entities such as "&#38;".
       #
       # @return [Regexp]
-      #
       NUMERIC_CODE_POINT_ENTITY = /&#(\d+);/
 
-      ##
       # Regexp for matching XML/HTML hex entities such as "&#x3C;".
       #
       # @return [Regexp]
-      #
       HEX_CODE_POINT_ENTITY = /&#x([a-fA-F0-9]+);/
 
-      ##
       # @return [Regexp]
-      #
       ENCODE_REGEXP = Regexp.new(ENCODE_MAPPING.keys.join('|'))
 
-      ##
       # @return [Regexp]
-      #
       ENCODE_ATTRIBUTE_REGEXP =
         Regexp.new(ENCODE_ATTRIBUTE_MAPPING.keys.join('|'))
 
-      ##
       # Decodes XML entities.
       #
       # @param [String] input
       # @param [Hash] mapping
       # @return [String]
-      #
       def self.decode(input, mapping = DECODE_MAPPING)
         return input unless input.include?(AMPERSAND)
 
@@ -110,23 +88,19 @@ module Oga
         input
       end
 
-      ##
       # Encodes special characters as XML entities.
       #
       # @param [String] input
       # @param [Hash] mapping
       # @return [String]
-      #
       def self.encode(input, mapping = ENCODE_MAPPING)
         input.gsub(ENCODE_REGEXP, mapping)
       end
 
-      ##
       # Encodes special characters in an XML attribute value.
       #
       # @param [String] input
       # @return [String]
-      #
       def self.encode_attribute(input)
         input.gsub(ENCODE_ATTRIBUTE_REGEXP, ENCODE_ATTRIBUTE_MAPPING)
       end