Class: REXML::Elements

Inherits:
Object show all
Includes:
Enumerable
Defined in:
lib/rexml/element.rb

Overview

A class which provides filtering of children for Elements, and XPath search support. You are expected to only encounter this class as the element.elements object. Therefore, you are not expected to instantiate this yourself.

Instance Method Summary (collapse)

Methods included from Enumerable

#to_set

Constructor Details

- (Elements) initialize(parent)

Constructor

parent

the parent Element



743
744
745
 
# File 'lib/rexml/element.rb', line 743

def initialize parent
  @element = parent
end

Instance Method Details

- (Object) [](index, name = nil)

Fetches a child element. Filters only Element children, regardless of the XPath match.

index

the search parameter. This is either an Integer, which will be used to find the index'th child Element, or an XPath, which will be used to search for the Element. Because of the nature of XPath searches, any element in the connected XML document can be fetched through any other element. The Integer index is 1-based, not 0-based. This means that the first child element is at index 1, not 0, and the nth element is at index n, not n-1. This is because XPath indexes element children starting from 1, not 0, and the indexes should be the same.

name

optional, and only used in the first argument is an Integer. In that case, the index'th child Element that has the supplied name will be returned. Note again that the indexes start at 1.

Returns

the first matching Element, or nil if no child matched

doc = Document.new '<a><b/><c id="1"/><c id="2"/><d/></a>'
doc.root.elements[1]       #-> <b/>
doc.root.elements['c']     #-> <c id="1"/>
doc.root.elements[2,'c']   #-> <c id="2"/>


768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
 
# File 'lib/rexml/element.rb', line 768

def []( index, name=nil)
  if index.kind_of? Integer
    raise "index (#{index}) must be >= 1" if index < 1
    name = literalize(name) if name
    num = 0
    @element.find { |child|
      child.kind_of? Element and
      (name.nil? ? true : child.has_name?( name )) and
      (num += 1) == index
    }
  else
    return XPath::first( @element, index )
    #{ |element|
    #	return element if element.kind_of? Element
    #}
    #return nil
  end
end

- (Object) []=(index, element)

Sets an element, replacing any previous matching element. If no existing element is found ,the element is added.

index

Used to find a matching element to replace. See []().

element

The element to replace the existing element with the previous element

Returns

nil if no previous element was found.

doc = Document.new '<a/>'
doc.root.elements[10] = Element.new('b')    #-> <a><b/></a>
doc.root.elements[1]                        #-> <b/>
doc.root.elements[1] = Element.new('c')     #-> <a><c/></a>
doc.root.elements['c'] = Element.new('d')   #-> <a><d/></a>


800
801
802
803
804
805
806
807
808
 
# File 'lib/rexml/element.rb', line 800

def []=( index, element )
  previous = self[index]
  if previous.nil?
    @element.add element
  else
    previous.replace_with element
  end
  return previous
end

- (Object) add(element = nil) Also known as: <<

Adds an element

element

if supplied, is either an Element, String, or Source (see Element.initialize). If not supplied or nil, a new, default Element will be constructed

Returns

the added Element

a = Element.new('a')
a.elements.add(Element.new('b'))  #-> <a><b/></a>
a.elements.add('c')               #-> <a><b/><c/></a>


876
877
878
879
880
881
882
883
884
885
886
887
 
# File 'lib/rexml/element.rb', line 876

def add element=nil
  rv = nil
  if element.nil?
    Element.new("", self, @element.context)
  elsif not element.kind_of?(Element)
    Element.new(element, self, @element.context)
  else
    @element << element
    element.context = @element.context
    element
  end
end

- (Object) collect(xpath = nil, &block) 



909
910
911
912
913
914
915
 
# File 'lib/rexml/element.rb', line 909

def collect( xpath=nil, &block )
  collection = []
  XPath::each( @element, xpath ) {|e|
    collection << yield(e)  if e.kind_of?(Element)
  }
  collection
end

- (Object) delete(element)

Deletes a child Element

element

Either an Element, which is removed directly; an xpath, where the first matching child is removed; or an Integer, where the n'th Element is removed.

Returns

the removed child

doc = Document.new '<a><b/><c/><c id="1"/></a>'
b = doc.root.elements[1]
doc.root.elements.delete b           #-> <a><c/><c id="1"/></a>
doc.elements.delete("a/c[@id='1']")  #-> <a><c/></a>
doc.root.elements.delete 1           #-> <a/>


840
841
842
843
844
845
846
847
 
# File 'lib/rexml/element.rb', line 840

def delete element
  if element.kind_of? Element
    @element.delete element
  else
    el = self[element]
    el.remove if el
  end
end

- (Object) delete_all(xpath)

Removes multiple elements. Filters for Element children, regardless of XPath matching.

xpath

all elements matching this String path are removed.

Returns

an Array of Elements that have been removed

doc = Document.new '<a><c/><c/><c/><c/></a>'
deleted = doc.elements.delete_all 'a/c' #-> [<c/>, <c/>, <c/>, <c/>]


855
856
857
858
859
860
861
862
863
864
865
 
# File 'lib/rexml/element.rb', line 855

def delete_all( xpath )
  rv = []
  XPath::each( @element, xpath) {|element|
    rv << element if element.kind_of? Element
  }
  rv.each do |element|
    @element.delete element
    element.remove
  end
  return rv
end

- (Object) each(xpath = nil, &block)

Iterates through all of the child Elements, optionally filtering them by a given XPath

xpath

optional. If supplied, this is a String XPath, and is used to filter the children, so that only matching children are yielded. Note that XPaths are automatically filtered for Elements, so that non-Element children will not be yielded

doc = Document.new '<a><b/><c/><d/>sean<b/><c/><d/></a>'
doc.root.each {|e|p e}       #-> Yields b, c, d, b, c, d elements
doc.root.each('b') {|e|p e}  #-> Yields b, b elements
doc.root.each('child::node()')  {|e|p e}
#-> Yields <b/>, <c/>, <d/>, <b/>, <c/>, <d/>
XPath.each(doc.root, 'child::node()', &block)
#-> Yields <b/>, <c/>, <d/>, sean, <b/>, <c/>, <d/>


905
906
907
 
# File 'lib/rexml/element.rb', line 905

def each( xpath=nil, &block)
  XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element }
end

- (Boolean) empty?

Returns true if there are no Element children, false otherwise

Returns:

  • (Boolean) 


811
812
813
 
# File 'lib/rexml/element.rb', line 811

def empty?
  @element.find{ |child| child.kind_of? Element}.nil?
end

- (Object) index(element)

Returns the index of the supplied child (starting at 1), or -1 if the element is not a child

element

an Element child



818
819
820
821
822
823
824
825
826
827
 
# File 'lib/rexml/element.rb', line 818

def index element
  rv = 0
  found = @element.find do |child|
    child.kind_of? Element and
    (rv += 1) and
    child == element
  end
  return rv if found == element
  return -1
end

- (Object) inject(xpath = nil, initial = nil, &block) 



917
918
919
920
921
922
923
924
925
926
927
928
929
930
 
# File 'lib/rexml/element.rb', line 917

def inject( xpath=nil, initial=nil, &block )
  first = true
  XPath::each( @element, xpath ) {|e|
    if (e.kind_of? Element)
      if (first and initial == nil)
        initial = e
        first = false
      else
        initial = yield( initial, e ) if e.kind_of? Element
      end
    end
  }
  initial
end

- (Object) size

Returns the number of Element children of the parent object.

doc = Document.new '<a>sean<b/>elliott<b/>russell<b/></a>'
doc.root.size            #-> 6, 3 element and 3 text nodes
doc.root.elements.size   #-> 3


936
937
938
939
940
 
# File 'lib/rexml/element.rb', line 936

def size
  count = 0
  @element.each {|child| count+=1 if child.kind_of? Element }
  count
end

- (Object) to_a(xpath = nil)

Returns an Array of Element children. An XPath may be supplied to filter the children. Only Element children are returned, even if the supplied XPath matches non-Element children.

doc = Document.new '<a>sean<b/>elliott<c/></a>'
doc.root.elements.to_a                  #-> [ <b/>, <c/> ]
doc.root.elements.to_a("child::node()") #-> [ <b/>, <c/> ]
XPath.match(doc.root, "child::node()")  #-> [ sean, <b/>, elliott, <c/> ]


949
950
951
952
953
 
# File 'lib/rexml/element.rb', line 949

def to_a( xpath=nil )
  rv = XPath.match( @element, xpath )
  return rv.find_all{|e| e.kind_of? Element} if xpath
  rv
end