Class

REXML::Elements

Inheritance
< Object
Included Modules
Enumerable

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.

Methods

Class

Visibility Signature
public new (parent)

Instance

Visibility Signature
public << (element=nil)
public [] ( index, name=nil)
public []= ( index, element )
public add (element=nil)
public collect ( xpath=nil ) {|e| ...}
public delete (element)
public delete_all ( xpath )
public each ( xpath=nil) {|e if e.kind_of? Element| ...}
public empty? ()
public index (element)
public inject ( xpath=nil, initial=nil ) {|initial, e| ...}
public size ()
public to_a ( xpath=nil )

Class Method Detail

new(parent)

Constructor

parent:the parent Element

Instance Method Detail

<<(element=nil)

Alias for add

[]( 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 +n+th 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"/>

[]=( 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>

add(element=nil)

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>

collect( xpath=nil ) {|e| ...}

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/>

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/>]

each( xpath=nil) {|e if e.kind_of? Element| ...}

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/>

empty?()

Returns true if there are no Element children, false otherwise

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

inject( xpath=nil, initial=nil ) {|initial, e| ...}

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

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/> ]