module Hpricot::Container::Trav - The Hpricot Reference

# module Hpricot::Container::Trav

### Public Instance Methods

classes() click to toggle source

Returns a list of CSS classes to which this element belongs.

    # File lib/hpricot/traverse.rb, line 518
    def classes
      get_attribute('class').to_s.strip.split(/\s+/)
    end

containers() click to toggle source

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.

    # File lib/hpricot/traverse.rb, line 404
    def containers
      children.grep(Container::Trav)
    end

each_child() { |child_node| ... } click to toggle source

`each_child` iterates over each child.

    # File lib/hpricot/traverse.rb, line 498
    def each_child(&block) # :yields: child_node
      children.each(&block) if children
      nil
    end

each_child_with_index() { |child_node, index| ... } click to toggle source

`each_child_with_index` iterates over each child.

    # File lib/hpricot/traverse.rb, line 504
    def each_child_with_index(&block) # :yields: child_node, index
      children.each_with_index(&block) if children
      nil
    end

each_hyperlink() { |text| ... } click to toggle source

`each_hyperlink` traverses hyperlinks such as HTML href attribute of A element.

It yields Hpricot::Text.

Note that `each_hyperlink` yields HTML href attribute of BASE element.

    # File lib/hpricot/traverse.rb, line 614
    def each_hyperlink # :yields: text
      links = []
      each_hyperlink_attribute {|elem, attr, hyperlink|
        yield hyperlink
      }
    end

each_hyperlink_uri(base_uri=nil) { |hyperlink, uri| ... } click to toggle source

`each_hyperlink_uri` traverses hyperlinks such as HTML href attribute of A element.

It yields Hpricot::Text and URI for each hyperlink.

The URI objects are created with a base URI which is given by HTML BASE element or the argument ((|base_uri|)). `each_hyperlink_uri` doesn't yields href of the BASE element.

    # File lib/hpricot/traverse.rb, line 591
    def each_hyperlink_uri(base_uri=nil) # :yields: hyperlink, uri
      base_uri = URI.parse(base_uri) if String === base_uri
      links = []
      each_hyperlink_attribute {|elem, attr, hyperlink|
        if %r{\{http://www.w3.org/1999/xhtml\}(?:base)\z}i =~ elem.name
          base_uri = URI.parse(hyperlink.to_s)
        else
          links << hyperlink
        end
      }
      if base_uri
        links.each {|hyperlink| yield hyperlink, base_uri + hyperlink.to_s }
      else
        links.each {|hyperlink| yield hyperlink, URI.parse(hyperlink.to_s) }
      end
    end

each_uri(base_uri=nil) { |URI| ... } click to toggle source

`each_uri` traverses hyperlinks such as HTML href attribute of A element.

It yields URI for each hyperlink.

The URI objects are created with a base URI which is given by HTML BASE element or the argument ((|base_uri|)).

    # File lib/hpricot/traverse.rb, line 628
    def each_uri(base_uri=nil) # :yields: URI
      each_hyperlink_uri(base_uri) {|hyperlink, uri| yield uri }
    end

filter() { |descendant| ... } click to toggle source

`filter` rebuilds the tree without some components.

    node.filter {|descendant_node| predicate } -> node
    loc.filter {|descendant_loc| predicate } -> node

`filter` yields each node except top node. If given block returns false, corresponding node is dropped. If given block returns true, corresponding node is retained and inner nodes are examined.

`filter` returns an node. It doesn't return location object even if self is location object.

    # File lib/hpricot/traverse.rb, line 719
    def filter(&block)
      subst = {}
      each_child_with_index {|descendant, i|
        if yield descendant
          if descendant.elem?
            subst[i] = descendant.filter(&block)
          else
            subst[i] = descendant
          end
        else
          subst[i] = nil
        end
      }
      to_node.subst_subnode(subst)
    end

find_element(*names) click to toggle source

`find_element` searches an element which universal name is specified by the arguments. It returns nil if not found.

    # File lib/hpricot/traverse.rb, line 512
    def find_element(*names)
      traverse_element(*names) {|e| return e }
      nil
    end

following_siblings() click to toggle source

Find sibling elements which follow the current one. Like the other “sibling” methods, this weeds out text and comment nodes.

    # File lib/hpricot/traverse.rb, line 435
    def following_siblings()
      sibs = parent.containers
      si = sibs.index(self) + 1
      return Elements[*sibs[si...sibs.length]]
    end

get_element_by_id(id) click to toggle source

    # File lib/hpricot/traverse.rb, line 522
    def get_element_by_id(id)
      traverse_all_element do |ele|
          if ele.elem? and eid = ele.get_attribute('id')
              return ele if eid.to_s == id
          end
      end
      nil
    end

get_elements_by_tag_name(*a) click to toggle source

    # File lib/hpricot/traverse.rb, line 531
    def get_elements_by_tag_name(*a)
      list = Elements[]
      a.delete("*")
      traverse_element(*a.map { |tag| [tag, "{http://www.w3.org/1999/xhtml}#{tag}"] }.flatten) do |e|
        list << e if e.elem?
      end
      list
    end

insert_after(nodes, ele) click to toggle source

Insert `nodes`, an array of HTML elements or a single element, after the node `ele`, a child of the current node.

    # File lib/hpricot/traverse.rb, line 486
    def insert_after(nodes, ele)
      case nodes
      when Array
        nodes.reverse_each { |n| insert_after(n, ele) }
      else
        reparent nodes
        idx = children.index(ele)
        children[idx ? idx + 1 : children.length, 0] = nodes
      end
    end

insert_before(nodes, ele) click to toggle source

Insert `nodes`, an array of HTML elements or a single element, before the node `ele`, a child of the current node.

    # File lib/hpricot/traverse.rb, line 474
    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

next_sibling() click to toggle source

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.

    # File lib/hpricot/traverse.rb, line 411
    def next_sibling
      sib = parent.containers
      sib[sib.index(self) + 1] if parent
    end

preceding_siblings() click to toggle source

Find all preceding sibling elements. Like the other “sibling” methods, this weeds out text and comment nodes.

    # File lib/hpricot/traverse.rb, line 427
    def preceding_siblings()
      sibs = parent.containers
      si = sibs.index(self)
      return Elements[*sibs[0...si]]
    end

previous_sibling() click to toggle source

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.

    # File lib/hpricot/traverse.rb, line 419
    def previous_sibling
      sib = parent.containers
      x = sib.index(self) - 1
      sib[x] if sib and x >= 0
    end

replace_child(old, new) click to toggle source

Replace `old`, a child of the current node, with `new` node.

    # File lib/hpricot/traverse.rb, line 467
    def replace_child(old, new)
      reparent new
      children[children.index(old), 1] = [*new]
    end

siblings_at(*pos) click to toggle source

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.

    # File lib/hpricot/traverse.rb, line 452
    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

traverse_text_internal(&block) click to toggle source

    # File lib/hpricot/traverse.rb, line 688
    def traverse_text_internal(&block)
      each_child {|c| c.traverse_text_internal(&block) }
    end

### Private Instance Methods

each_hyperlink_attribute() { |elem, attr, hyperlink| ... } click to toggle source

    # File lib/hpricot/traverse.rb, line 540
    def each_hyperlink_attribute
      traverse_element(
          '{http://www.w3.org/1999/xhtml}a',
          '{http://www.w3.org/1999/xhtml}area',
          '{http://www.w3.org/1999/xhtml}link',
          '{http://www.w3.org/1999/xhtml}img',
          '{http://www.w3.org/1999/xhtml}object',
          '{http://www.w3.org/1999/xhtml}q',
          '{http://www.w3.org/1999/xhtml}blockquote',
          '{http://www.w3.org/1999/xhtml}ins',
          '{http://www.w3.org/1999/xhtml}del',
          '{http://www.w3.org/1999/xhtml}form',
          '{http://www.w3.org/1999/xhtml}input',
          '{http://www.w3.org/1999/xhtml}head',
          '{http://www.w3.org/1999/xhtml}base',
          '{http://www.w3.org/1999/xhtml}script') {|elem|
        case elem.name
        when %r{\{http://www.w3.org/1999/xhtml\}(?:base|a|area|link)\z}i
          attrs = ['href']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:img)\z}i
          attrs = ['src', 'longdesc', 'usemap']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:object)\z}i
          attrs = ['classid', 'codebase', 'data', 'usemap']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:q|blockquote|ins|del)\z}i
          attrs = ['cite']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:form)\z}i
          attrs = ['action']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:input)\z}i
          attrs = ['src', 'usemap']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:head)\z}i
          attrs = ['profile']
        when %r{\{http://www.w3.org/1999/xhtml\}(?:script)\z}i
          attrs = ['src', 'for']
        end
        attrs.each {|attr|
          if hyperlink = elem.get_attribute(attr)
            yield elem, attr, hyperlink
          end
        }
      }
    end