hpricot 0.4-mswin32 → 0.5-mswin32

data/lib/hpricot/traverse.rb

@@ -3,20 +3,93 @@ require 'uri'
 
 module Hpricot
   module Traverse
+    # Is this object the enclosing HTML or XML document?
     def doc?() Doc::Trav === self end
+    # Is this object an HTML or XML element?
     def elem?() Elem::Trav === self end
+    # Is this object an HTML text node?
     def text?() Text::Trav === self end
+    # Is this object an XML declaration?
     def xmldecl?() XMLDecl::Trav === self end
+    # Is this object a doctype tag?
     def doctype?() DocType::Trav === self end
+    # Is this object an XML processing instruction?
     def procins?() ProcIns::Trav === self end
+    # Is this object a comment?
     def comment?() Comment::Trav === self end
+    # Is this object a stranded end tag?
     def bogusetag?() BogusETag::Trav === self end
 
+    # Builds an HTML string from this node and its contents.
+    # If you need to write to a stream, try calling <tt>output(io)</tt>
+    # as a method on this object.
     def to_html
       output("")
     end
     alias_method :to_s, :to_html
 
+    # Attempts to preserve the original HTML of the document, only
+    # outputing new tags for elements which have changed.
+    def to_original_html
+      output("", :preserve => true)
+    end
+
+    # Puts together an array of neighboring nodes based on their proximity
+    # to this node.  So, for example, to get the next node, you could use
+    # <tt>nodes_at(1).  Or, to get the previous node, use <tt>nodes_at(1)</tt>.
+    #
+    # This method also accepts ranges and sets of numbers.
+    #
+    #    ele.nodes_at(-3..-1, 1..3) # gets three nodes before and three after
+    #    ele.nodes_at(1, 5, 7) # gets three nodes at offsets below the current node
+    #    ele.nodes_at(0, 5..6) # the current node and two others
+    def nodes_at(*pos)
+      sib = parent.children
+      i, si = 0, sib.index(self)
+      Elements[*
+        sib.select do |x|
+          sel = case i - si when *pos
+                  true
+                end
+          i += 1
+          sel
+        end
+      ]
+    end
+
+    # Returns the node neighboring this node to the south: just below it.
+    # This method includes text nodes and comments and such.
+    def next_node
+      sib = parent.children
+      sib[sib.index(self) + 1] if parent
+    end
+
+    # Returns to node neighboring this node to the north: just above it.
+    # This method includes text nodes and comments and such.
+    def previous_node
+      sib = parent.children
+      x = sib.index(self) - 1
+      sib[x] if sib and x >= 0
+    end
+
+    # Adds elements immediately after this element, contained in the +html+ string.
+    def after(html)
+      parent.insert_after(Hpricot.make(html), self)
+    end
+
+    # Adds elements immediately before this element, contained in the +html+ string.
+    def before(html)
+      parent.insert_after(Hpricot.make(html), self)
+    end
+
+
+    # Replace this element and its contents with the nodes contained
+    # in the +html+ string.
+    def swap(html)
+      parent.altered!
+      parent.replace_child(self, Hpricot.make(html))
+    end
+
     def get_subnode(*indexes)
       n = self
       indexes.each {|index|
@@ -24,37 +97,36 @@ module Hpricot
       }
       n
     end
-  end
 
-  module Container::Trav
-    def containers
-      children.grep(Container::Trav)
-    end
-    def replace_child(old, new)
-      children[children.index(old), 1] = [*new]
-    end
-    def insert_before(nodes, ele)
-      case nodes
-      when Array
-        nodes.each { |n| insert_before(n, ele) }
-      else
-        children[children.index(ele) || 0, 0] = nodes
+    # Builds a string from the text contained in this node.  All
+    # HTML elements are removed.
+    def to_plain_text
+      if respond_to? :children
+        children.map { |x| x.to_plain_text }.join.strip.gsub(/\n{2,}/, "\n\n")
       end
     end
-    def insert_after(nodes, ele)
-      case nodes
-      when Array
-        nodes.each { |n| insert_after(n, ele) }
-      else
-        idx = children.index(ele)
-        children[idx ? idx + 1 : children.length, 0] = nodes
+
+    # Builds a string from the text contained in this node.  All
+    # HTML elements are removed.
+    def inner_text
+      if respond_to? :children
+        children.map { |x| x.inner_text }.join
       end
     end
+    alias_method :innerText, :inner_text
+
+    # Builds an HTML string from the contents of this node.
     def inner_html
-      children.map { |x| x.output("") }.join
+      if respond_to? :children
+        children.map { |x| x.output("") }.join
+      end
     end
     alias_method :innerHTML, :inner_html
+
+    # Inserts new contents into the current node, based on
+    # the HTML contained in string +inner+.
     def inner_html=(inner)
+      altered!
       case inner
       when String, IO
         self.children = Hpricot.parse(inner).children
@@ -63,63 +135,137 @@ module Hpricot
       when nil
         self.children = []
       end
+      reparent self.children
     end
     alias_method :innerHTML=, :inner_html=
+
+    def reparent(nodes)
+      altered!
+      [*nodes].each { |e| e.parent = self }
+    end
+    private :reparent
+
+    def clean_path(path)
+      path.gsub(/^\s+|\s+$/, '')
+    end
+
+    # Builds a unique XPath string for this node, from the
+    # root of the document containing it.
+    def xpath
+      if elem? and has_attribute? 'id'
+        "//#{self.name}[@id='#{get_attribute('id')}']"
+      else
+        sim, id = 0, 0, 0
+        parent.children.each do |e|
+          id = sim if e == self
+          sim += 1 if e.pathname == self.pathname
+        end
+        p = File.join(parent.xpath, self.pathname)
+        p += "[#{id+1}]" if sim >= 2
+        p
+      end
+    end
+
+    # Builds a unique CSS string for this node, from the
+    # root of the document containing it.
+    def css_path
+      if elem? and has_attribute? 'id'
+        "##{get_attribute('id')}"
+      else
+        sim, i, id = 0, 0, 0
+        parent.children.each do |e|
+          id = sim if e == self
+          sim += 1 if e.pathname == self.pathname
+        end
+        p = parent.css_path
+        p = p ? "#{p} > #{self.pathname}" : self.pathname
+        p += ":nth(#{id})" if sim >= 2
+        p
+      end
+    end
+
+    def node_position
+      parent.children.index(self)
+    end
+
+    def position
+      parent.children_of_type(self.pathname).index(self)
+    end
+
+    # Searches this node for all elements matching
+    # the CSS or XPath +expr+.  Returns an Elements array
+    # containing the matching nodes.  If +blk+ is given, it
+    # is used to iterate through the matching set.
     def search(expr, &blk)
       last = nil
       nodes = [self]
       done = []
       expr = expr.to_s
+      hist = []
       until expr.empty?
           expr = clean_path(expr)
           expr.gsub!(%r!^//!, '')
 
           case expr
           when %r!^/?\.\.!
-              expr = $'
+              last = expr = $'
               nodes.map! { |node| node.parent }
           when %r!^[>/]!
-              expr = $'
-              nodes = Elements[*nodes.map { |node| node.containers }.flatten]
+              last = expr = $'
+              nodes = Elements[*nodes.map { |node| node.children if node.respond_to? :children }.flatten.compact]
           when %r!^\+!
-              expr = $'
+              last = expr = $'
               nodes.map! do |node|
-                  siblings = node.parent.containers
+                  siblings = node.parent.children
                   siblings[siblings.index(node)+1]
               end
               nodes.compact!
           when %r!^~!
-              expr = $'
+              last = expr = $'
               nodes.map! do |node|
-                  siblings = node.parent.containers
+                  siblings = node.parent.children
                   siblings[(siblings.index(node)+1)..-1]
               end
               nodes.flatten!
           when %r!^[|,]!
-              expr = " #$'"
+              last = expr = " #$'"
               nodes.shift if nodes.first == self
               done += nodes
               nodes = [self]
           else
-              m = expr.match %r!^([#.]?)([a-z0-9\\*_-]*)!i
-              expr = $'
+              m = expr.match(%r!^([#.]?)([a-z0-9\\*_-]*)!i).to_a
+              after = $'
+              mt = after[%r!:[a-z0-9\\*_-]+!i, 0]
+              oop = false
+              if mt and not (mt == ":not" or Traverse.method_defined? "filter[#{mt}]")
+                after = $' 
+                m[2] += mt
+                expr = after
+              end
               if m[1] == '#'
                   oid = get_element_by_id(m[2])
                   nodes = oid ? [oid] : []
+                  expr = after
               else
-                  m[2] = "*" if m[2] == "" || m[1] == "."
+                  m[2] = "*" if after =~ /^\(\)/ || m[2] == "" || m[1] == "."
                   ret = []
                   nodes.each do |node|
                       case m[2]
                       when '*'
+                          node.traverse_element { |n| ret << n }
                       else
-                          ret += [*node.get_elements_by_tag_name(m[2])]
+                          if node.respond_to? :get_elements_by_tag_name
+                            ret += [*node.get_elements_by_tag_name(m[2])] - [*(node unless last)]
+                          end
                       end
                   end
                   nodes = ret
               end
+              last = nil
           end
 
+          hist << expr
+          break if hist[-1] == hist[-2]
           nodes, expr = Elements.filter(nodes, expr)
       end
       nodes = done + nodes.flatten.uniq
@@ -132,35 +278,13 @@ module Hpricot
     end
     alias_method :/, :search
 
-    def at(expr, &blk)
-      search(expr, &blk).first
+    # Find the first matching node for the CSS or XPath
+    # +expr+ string.
+    def at(expr)
+      search(expr).first
     end
     alias_method :%, :at
 
-    def clean_path(path)
-      path.gsub(/^\s+|\s+$/, '')
-    end
-
-    # +each_child+ iterates over each child.
-    def each_child(&block) # :yields: child_node
-      children.each(&block)
-      nil
-    end
-
-    # +each_child_with_index+ iterates over each child.
-    def each_child_with_index(&block) # :yields: child_node, index
-      children.each_with_index(&block)
-      nil
-    end
-
-    # +find_element+ searches an element which universal name is specified by
-    # the arguments. 
-    # It returns nil if not found.
-    def find_element(*names)
-      traverse_element(*names) {|e| return e }
-      nil
-    end
-
     # +traverse_element+ traverses elements in the tree.
     # It yields elements in depth first order.
     #
@@ -200,13 +324,130 @@ module Hpricot
       nil
     end
 
+    # Find children of a given +tag_name+.
+    #
+    #   ele.children_of_type('p')
+    #     #=> [...array of paragraphs...]
+    #
+    def children_of_type(tag_name)
+      if respond_to? :children
+        children.find_all do |x|
+          x.respond_to?(:pathname) && x.pathname == tag_name
+        end
+      end
+    end
+
+  end
+
+  module Container::Trav
+    # Return all children of this node which can contain other
+    # nodes.  This is a good way to get all HTML elements which
+    # aren't text, comment, doctype or processing instruction nodes.
+    def containers
+      children.grep(Container::Trav)
+    end
+
+    # Returns the container node neighboring this node to the south: just below it.
+    # By "container" node, I mean: this method does not find text nodes or comments or cdata or any of that.
+    # See Hpricot::Traverse#next_node if you need to hunt out all kinds of nodes.
+    def next_sibling
+      sib = parent.containers
+      sib[sib.index(self) + 1] if parent
+    end
+
+    # Returns the container node neighboring this node to the north: just above it.
+    # By "container" node, I mean: this method does not find text nodes or comments or cdata or any of that.
+    # See Hpricot::Traverse#previous_node if you need to hunt out all kinds of nodes.
+    def previous_sibling
+      sib = parent.containers
+      x = sib.index(self) - 1
+      sib[x] if sib and x >= 0
+    end
+
+    # Puts together an array of neighboring sibling elements based on their proximity
+    # to this element.
+    #
+    # This method accepts ranges and sets of numbers.
+    #
+    #    ele.siblings_at(-3..-1, 1..3) # gets three elements before and three after
+    #    ele.siblings_at(1, 5, 7) # gets three elements at offsets below the current element
+    #    ele.siblings_at(0, 5..6) # the current element and two others
+    #
+    # Like the other "sibling" methods, this doesn't find text and comment nodes.
+    # Use nodes_at to include those nodes.
+    def siblings_at(*pos)
+      sib = parent.containers
+      i, si = 0, sib.index(self)
+      Elements[*
+        sib.select do |x|
+          sel = case i - si when *pos
+                  true
+                end
+          i += 1
+          sel
+        end
+      ]
+    end
+
+    # Replace +old+, a child of the current node, with +new+ node.
+    def replace_child(old, new)
+      reparent new
+      children[children.index(old), 1] = [*new]
+    end
+
+    # Insert +nodes+, an array of HTML elements or a single element,
+    # before the node +ele+, a child of the current node.
+    def insert_before(nodes, ele)
+      case nodes
+      when Array
+        nodes.each { |n| insert_before(n, ele) }
+      else
+        reparent nodes
+        children[children.index(ele) || 0, 0] = nodes
+      end
+    end
+
+    # Insert +nodes+, an array of HTML elements or a single element,
+    # after the node +ele+, a child of the current node.
+    def insert_after(nodes, ele)
+      case nodes
+      when Array
+        nodes.each { |n| insert_after(n, ele) }
+      else
+        reparent nodes
+        idx = children.index(ele)
+        children[idx ? idx + 1 : children.length, 0] = nodes
+      end
+    end
+
+    # +each_child+ iterates over each child.
+    def each_child(&block) # :yields: child_node
+      children.each(&block)
+      nil
+    end
+
+    # +each_child_with_index+ iterates over each child.
+    def each_child_with_index(&block) # :yields: child_node, index
+      children.each_with_index(&block)
+      nil
+    end
+
+    # +find_element+ searches an element which universal name is specified by
+    # the arguments. 
+    # It returns nil if not found.
+    def find_element(*names)
+      traverse_element(*names) {|e| return e }
+      nil
+    end
+
+    # Returns a list of CSS classes to which this element belongs.
     def classes
       get_attribute('class').to_s.strip.split(/\s+/)
     end
 
     def get_element_by_id(id)
       traverse_all_element do |ele|
-          if eid = ele.get_attribute('id')
+          if ele.elem? and eid = ele.get_attribute('id')
               return ele if eid.to_s == id
           end
       end
@@ -319,6 +560,12 @@ module Hpricot
     def traverse_all_element(&block)
       children.each {|c| c.traverse_all_element(&block) }
     end
+    def xpath
+      "/"
+    end
+    def css_path
+      nil
+    end
   end
 
   module Elem::Trav
@@ -330,6 +577,7 @@ module Hpricot
 
   module Leaf::Trav
     def traverse_all_element
+      yield self
     end
   end
 
@@ -497,12 +745,14 @@ module Hpricot
     end
     alias_method :[], :get_attribute
     def set_attribute(name, val)
+      altered!
       self.attributes ||= {}
       self.attributes[name.to_s] = val
     end
     alias_method :[]=, :set_attribute
     def remove_attribute(name)
       if has_attribute? name
+        altered!
         self.attributes.delete(name)
       end
     end