oga 1.2.3-java → 1.3.0-java

data/lib/oga/xml/node.rb

@@ -1,17 +1,14 @@
 module Oga
   module XML
-    ##
     # A generic XML node. Instances of this class can belong to a
     # {Oga::XML::NodeSet} and can be used to query surrounding and parent
     # nodes.
-    #
     class Node
       include Traversal
 
       # @return [Oga::XML::NodeSet]
       attr_reader :node_set
 
-      ##
       # @param [Hash] options
       #
       # @option options [Oga::XML::NodeSet] :node_set The node set that this
@@ -19,35 +16,28 @@ module Oga
       #
       # @option options [Oga::XML::NodeSet|Array] :children The child nodes of
       #  the current node.
-      #
       def initialize(options = {})
         self.node_set = options[:node_set]
         self.children = options[:children] if options[:children]
       end
 
-      ##
       # @param [Oga::XML::NodeSet] set
-      #
       def node_set=(set)
         @node_set  = set
         @root_node = nil
         @html_p    = nil
       end
 
-      ##
       # Returns the child nodes of the current node.
       #
       # @return [Oga::XML::NodeSet]
-      #
       def children
         @children ||= NodeSet.new([], self)
       end
 
-      ##
       # Sets the child nodes of the element.
       #
       # @param [Oga::XML::NodeSet|Array] nodes
-      #
       def children=(nodes)
         if nodes.is_a?(NodeSet)
           @children = nodes
@@ -56,32 +46,26 @@ module Oga
         end
       end
 
-      ##
       # Returns the parent node of the current node. If there is no parent node
       # `nil` is returned instead.
       #
       # @return [Oga::XML::Node]
-      #
       def parent
         node_set ? node_set.owner : nil
       end
 
-      ##
       # Returns the preceding node, or nil if there is none.
       #
       # @return [Oga::XML::Node]
-      #
       def previous
         index = node_set.index(self) - 1
 
         index >= 0 ? node_set[index] : nil
       end
 
-      ##
       # Returns the following node, or nil if there is none.
       #
       # @return [Oga::XML::Node]
-      #
       def next
         index  = node_set.index(self) + 1
         length = node_set.length
@@ -89,11 +73,9 @@ module Oga
         index <= length ? node_set[index] : nil
       end
 
-      ##
       # Returns the previous element node or nil if there is none.
       #
       # @return [Oga::XML::Element]
-      #
       def previous_element
         node = self
 
@@ -104,11 +86,9 @@ module Oga
         return
       end
 
-      ##
       # Returns the next element node or nil if there is none.
       #
       # @return [Oga::XML::Element]
-      #
       def next_element
         node = self
 
@@ -119,12 +99,10 @@ module Oga
         return
       end
 
-      ##
       # Returns the root document/node of the current node. The node is
       # retrieved by traversing upwards in the DOM tree from the current node.
       #
       # @return [Oga::XML::Document|Oga::XML::Node]
-      #
       def root_node
         unless @root_node
           node = self
@@ -143,16 +121,13 @@ module Oga
         @root_node
       end
 
-      ##
       # Removes the current node from the owning node set.
       #
       # @return [Oga::XML::Node]
-      #
       def remove
         return node_set.delete(self) if node_set
       end
 
-      ##
       # Replaces the current node with another.
       #
       # @example Replacing with an element
@@ -163,7 +138,6 @@ module Oga
       #  some_node.replace('this will replace the current node with a text node')
       #
       # @param [String|Oga::XML::Node] other
-      #
       def replace(other)
         if other.is_a?(String)
           other = Text.new(:text => other)
@@ -173,31 +147,25 @@ module Oga
         remove
       end
 
-      ##
       # Inserts the given node before the current node.
       #
       # @param [Oga::XML::Node] other
-      #
       def before(other)
         index = node_set.index(self)
 
         node_set.insert(index, other)
       end
 
-      ##
       # Inserts the given node after the current node.
       #
       # @param [Oga::XML::Node] other
-      #
       def after(other)
         index = node_set.index(self) + 1
 
         node_set.insert(index, other)
       end
 
-      ##
       # @return [TrueClass|FalseClass]
-      #
       def html?
         if @html_p.nil?
           root = root_node
@@ -208,12 +176,28 @@ module Oga
         @html_p
       end
 
-      ##
       # @return [TrueClass|FalseClass]
-      #
       def xml?
         !html?
       end
+
+      # Yields all ancestor elements of the current node.
+      #
+      # @example
+      #  some_element.each_ancestor do |node|
+      #    # ...
+      #  end
+      #
+      # @yieldparam [Oga::XML::Node]
+      def each_ancestor
+        node = parent
+
+        while node.is_a?(XML::Element)
+          yield node
+
+          node = node.parent
+        end
+      end
     end # Element
   end # XML
 end # Oga

data/lib/oga/xml/node_set.rb

@@ -1,6 +1,5 @@
 module Oga
   module XML
-    ##
     # The NodeSet class contains a set of unique {Oga::XML::Node} instances that
     # can be queried and modified. Optionally NodeSet instances can take
     # ownership of a node (besides just containing it). This allows the nodes to
@@ -30,17 +29,14 @@ module Oga
     #
     # If ownership was not handled then you'd have to manually set the
     # `element` variable's `node_set` attribute after pushing it into a set.
-    #
     class NodeSet
       include Enumerable
 
       # @return [Oga::XML::Node]
       attr_accessor :owner
 
-      ##
       # @param [Array] nodes The nodes to add to the set.
       # @param [Oga::XML::NodeSet] owner The owner of the set.
-      #
       def initialize(nodes = [], owner = nil)
         @nodes    = nodes
         @owner    = owner
@@ -53,38 +49,30 @@ module Oga
         end
       end
 
-      ##
       # Yields the supplied block for every node.
       #
       # @yieldparam [Oga::XML::Node]
-      #
       def each
         @nodes.each { |node| yield node }
       end
 
-      ##
       # Returns the last node in the set.
       #
       # @return [Oga::XML::Node]
-      #
       def last
         @nodes[-1]
       end
 
-      ##
       # Returns `true` if the set is empty.
       #
       # @return [TrueClass|FalseClass]
-      #
       def empty?
         @nodes.empty?
       end
 
-      ##
       # Returns the amount of nodes in the set.
       #
       # @return [Fixnum]
-      #
       def length
         @nodes.length
       end
@@ -92,21 +80,17 @@ module Oga
       alias_method :count, :length
       alias_method :size, :length
 
-      ##
       # Returns the index of the given node.
       #
       # @param [Oga::XML::Node] node
       # @return [Fixnum]
-      #
       def index(node)
         @nodes.index(node)
       end
 
-      ##
       # Pushes the node at the end of the set.
       #
       # @param [Oga::XML::Node] node
-      #
       def push(node)
         return if exists?(node)
 
@@ -119,11 +103,9 @@ module Oga
 
       alias_method :<<, :push
 
-      ##
       # Pushes the node at the start of the set.
       #
       # @param [Oga::XML::Node] node
-      #
       def unshift(node)
         return if exists?(node)
 
@@ -134,11 +116,9 @@ module Oga
         take_ownership(node) if @owner
       end
 
-      ##
       # Shifts a node from the start of the set.
       #
       # @return [Oga::XML::Node]
-      #
       def shift
         node = @nodes.shift
 
@@ -151,11 +131,9 @@ module Oga
         node
       end
 
-      ##
       # Pops a node from the end of the set.
       #
       # @return [Oga::XML::Node]
-      #
       def pop
         node = @nodes.pop
 
@@ -168,12 +146,10 @@ module Oga
         node
       end
 
-      ##
       # Inserts a node into the set at the given index.
       #
       # @param [Fixnum] index The index to insert the node at.
       # @param [Oga::XML::Node] node
-      #
       def insert(index, node)
         return if exists?(node)
 
@@ -184,73 +160,59 @@ module Oga
         take_ownership(node) if @owner
       end
 
-      ##
       # Returns the node for the given index.
       #
       # @param [Fixnum] index
       # @return [Oga::XML::Node]
-      #
       def [](index)
         @nodes[index]
       end
 
-      ##
       # Converts the current set to an Array.
       #
       # @return [Array]
-      #
       def to_a
         @nodes
       end
 
-      ##
       # Creates a new set based on the current and the specified set. The newly
       # created set does not inherit ownership rules of the current set.
       #
       # @param [Oga::XML::NodeSet] other
       # @return [Oga::XML::NodeSet]
-      #
       def +(other)
         self.class.new(to_a | other.to_a)
       end
 
-      ##
       # Returns `true` if the current node set and the one given in `other` are
       # equal to each other.
       #
       # @param [Oga::XML::NodeSet] other
-      #
       def ==(other)
         other.is_a?(NodeSet) && other.equal_nodes?(@nodes)
       end
 
-      ##
       # Returns `true` if the nodes given in `nodes` are equal to those
       # specified in the current `@nodes` variable. This method allows two
       # NodeSet instances to compare each other without the need of exposing
       # `@nodes` to the public.
       #
       # @param [Array<Oga::XML::Node>] nodes
-      #
       def equal_nodes?(nodes)
         @nodes == nodes
       end
 
-      ##
       # Adds the nodes of the given node set to the current node set.
       #
       # @param [Oga::XML::NodeSet] other
-      #
       def concat(other)
         other.each { |node| push(node) }
       end
 
-      ##
       # Removes the current nodes from their owning set. The nodes are *not*
       # removed from the current set.
       #
       # This method is intended to remove nodes from an XML document/node.
-      #
       def remove
         sets = []
 
@@ -270,9 +232,7 @@ module Oga
         end
       end
 
-      ##
       # Removes a node from the current set only.
-      #
       def delete(node)
         removed = @nodes.delete(node)
 
@@ -285,12 +245,10 @@ module Oga
         removed
       end
 
-      ##
       # Returns the values of the given attribute.
       #
       # @param [String|Symbol] name The name of the attribute.
       # @return [Array]
-      #
       def attribute(name)
         values = []
 
@@ -305,11 +263,9 @@ module Oga
 
       alias_method :attr, :attribute
 
-      ##
       # Returns the text of all nodes in the set, ignoring comment nodes.
       #
       # @return [String]
-      #
       def text
         text = ''
 
@@ -322,9 +278,7 @@ module Oga
         text
       end
 
-      ##
       # @return [String]
-      #
       def inspect
         values = @nodes.map(&:inspect).join(', ')
 
@@ -333,21 +287,17 @@ module Oga
 
       private
 
-      ##
       # Takes ownership of the given node. This only occurs when the current
       # set has an owner.
       #
       # @param [Oga::XML::Node] node
-      #
       def take_ownership(node)
         node.node_set = self
       end
 
-      ##
       # Removes ownership of the node if it belongs to the current set.
       #
       # @param [Oga::XML::Node] node
-      #
       def remove_ownership(node)
         node.node_set = nil if node.node_set == self
       end