Class | REXML::Elements |
In: |
lib/rexml/element.rb
|
Parent: | Object |
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"/>
# File lib/rexml/element.rb, line 752 752: def []( index, name=nil) 753: if index.kind_of? Integer 754: raise "index (#{index}) must be >= 1" if index < 1 755: name = literalize(name) if name 756: num = 0 757: child = nil 758: @element.find { |child| 759: child.kind_of? Element and 760: (name.nil? ? true : child.has_name?( name )) and 761: (num += 1) == index 762: } 763: else 764: return XPath::first( @element, index ) 765: #{ |element| 766: # return element if element.kind_of? Element 767: #} 768: #return nil 769: end 770: 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>
# File lib/rexml/element.rb, line 785 785: def []=( index, element ) 786: previous = self[index] 787: if previous.nil? 788: @element.add element 789: else 790: previous.replace_with element 791: end 792: return previous 793: 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>
# File lib/rexml/element.rb, line 861 861: def add element=nil 862: rv = nil 863: if element.nil? 864: Element.new("", self, @element.context) 865: elsif not element.kind_of?(Element) 866: Element.new(element, self, @element.context) 867: else 868: @element << element 869: element.context = @element.context 870: element 871: end 872: end
# File lib/rexml/element.rb, line 894 894: def collect( xpath=nil, &block ) 895: collection = [] 896: XPath::each( @element, xpath ) {|e| 897: collection << yield(e) if e.kind_of?(Element) 898: } 899: collection 900: 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/>
# File lib/rexml/element.rb, line 825 825: def delete element 826: if element.kind_of? Element 827: @element.delete element 828: else 829: el = self[element] 830: el.remove if el 831: end 832: 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/>]
# File lib/rexml/element.rb, line 840 840: def delete_all( xpath ) 841: rv = [] 842: XPath::each( @element, xpath) {|element| 843: rv << element if element.kind_of? Element 844: } 845: rv.each do |element| 846: @element.delete element 847: element.remove 848: end 849: return rv 850: 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/>
# File lib/rexml/element.rb, line 890 890: def each( xpath=nil, &block) 891: XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } 892: end
Returns the index of the supplied child (starting at 1), or -1 if the element is not a child
element: | an Element child |
# File lib/rexml/element.rb, line 803 803: def index element 804: rv = 0 805: found = @element.find do |child| 806: child.kind_of? Element and 807: (rv += 1) and 808: child == element 809: end 810: return rv if found == element 811: return -1 812: end
# File lib/rexml/element.rb, line 902 902: def inject( xpath=nil, initial=nil, &block ) 903: first = true 904: XPath::each( @element, xpath ) {|e| 905: if (e.kind_of? Element) 906: if (first and initial == nil) 907: initial = e 908: first = false 909: else 910: initial = yield( initial, e ) if e.kind_of? Element 911: end 912: end 913: } 914: initial 915: 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 lib/rexml/element.rb, line 921 921: def size 922: count = 0 923: @element.each {|child| count+=1 if child.kind_of? Element } 924: count 925: 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 lib/rexml/element.rb, line 934 934: def to_a( xpath=nil ) 935: rv = XPath.match( @element, xpath ) 936: return rv.find_all{|e| e.kind_of? Element} if xpath 937: rv 938: end