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.
Constructor
the parent Element
# File rexml/element.rb, line 765 def initialize parent @element = parent end
Fetches a child element. Filters only Element
children, regardless of the XPath
match.
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.
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.
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"/>
# File rexml/element.rb, line 790 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
Sets an element, replacing any previous matching element. If no existing element is found ,the element is added.
Used to find a matching element to replace. See []().
The element to replace the existing element with the previous element
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>
# File rexml/element.rb, line 822 def []=( index, element ) previous = self[index] if previous.nil? @element.add element else previous.replace_with element end return previous end
Adds an 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
the added Element
a = Element.new('a') a.elements.add(Element.new('b')) #-> <a><b/></a> a.elements.add('c') #-> <a><b/><c/></a>
# File rexml/element.rb, line 898 def add element=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
# File rexml/element.rb, line 930 def collect( xpath=nil ) collection = [] XPath::each( @element, xpath ) {|e| collection << yield(e) if e.kind_of?(Element) } collection end
Deletes a child 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.
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/>
# File rexml/element.rb, line 862 def delete element if element.kind_of? Element @element.delete element else el = self[element] el.remove if el end end
Removes multiple elements. Filters for Element
children, regardless of XPath
matching.
all elements matching this String path are removed.
doc = Document.new '<a><c/><c/><c/><c/></a>' deleted = doc.elements.delete_all 'a/c' #-> [<c/>, <c/>, <c/>, <c/>]
# File rexml/element.rb, line 877 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
Iterates through all of the child Elements
, optionally filtering them by a given 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.elements.each {|e|p e} #-> Yields b, c, d, b, c, d elements doc.root.elements.each('b') {|e|p e} #-> Yields b, b elements doc.root.elements.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/>
# File rexml/element.rb, line 926 def each( xpath=nil ) XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } end
Returns true
if there are no Element
children, false
otherwise
# File rexml/element.rb, line 833 def empty? @element.find{ |child| child.kind_of? Element}.nil? end
Returns the index of the supplied child (starting at 1), or -1 if the element is not a child
an Element
child
# File rexml/element.rb, line 840 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
# File rexml/element.rb, line 938 def inject( xpath=nil, initial=nil ) 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
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
# File rexml/element.rb, line 957 def size count = 0 @element.each {|child| count+=1 if child.kind_of? Element } count end
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/> ]
# File rexml/element.rb, line 970 def to_a( xpath=nil ) rv = XPath.match( @element, xpath ) return rv.find_all{|e| e.kind_of? Element} if xpath rv end