| Class | REXML::Elements |
| In: |
|
| Parent: | Object |
Included Modules
Public Class methods
Public Instance methods
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"/>
800: def []( index, name=nil) 801: if index.kind_of? Integer 802: raise "index (#{index}) must be >= 1" if index < 1 803: name = literalize(name) if name 804: num = 0 805: child = nil 806: @element.find { |child| 807: child.kind_of? Element and 808: (name.nil? ? true : child.has_name?( name )) and 809: (num += 1) == index 810: } 811: else 812: return XPath::first( @element, index ) 813: #{ |element| 814: # return element if element.kind_of? Element 815: #} 816: #return nil 817: end 818: end
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>
833: def []=( index, element ) 834: previous = self[index] 835: if previous.nil? 836: @element.add element 837: else 838: previous.replace_with element 839: end 840: return previous 841: end
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>
909: def add element=nil 910: rv = nil 911: if element.nil? 912: Element.new "", self, @element.context 913: elsif not element.kind_of?(Element) 914: Element.new element, self, @element.context 915: else 916: @element << element 917: element.context = @element.context 918: element 919: end 920: end
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/>
873: def delete element 874: if element.kind_of? Element 875: @element.delete element 876: else 877: el = self[element] 878: el.remove if el 879: end 880: end
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/>]
888: def delete_all( xpath ) 889: rv = [] 890: XPath::each( @element, xpath) {|element| 891: rv << element if element.kind_of? Element 892: } 893: rv.each do |element| 894: @element.delete element 895: element.remove 896: end 897: return rv 898: end
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/>
938: def each( xpath=nil, &block) 939: XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } 940: end
Returns the index of the supplied child (starting at 1), or -1 if the element is not a child
| element: | an Element child |
851: def index element 852: rv = 0 853: found = @element.find do |child| 854: child.kind_of? Element and 855: (rv += 1) and 856: child == element 857: end 858: return rv if found == element 859: return -1 860: 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
946: def size 947: count = 0 948: @element.each {|child| count+=1 if child.kind_of? Element } 949: count 950: 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/> ]
959: def to_a( xpath=nil ) 960: rv = XPath.match( @element, xpath ) 961: return rv.find_all{|e| e.kind_of? Element} if xpath 962: rv 963: end