| 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 795
795: def []( index, name=nil)
796: if index.kind_of? Integer
797: raise "index (#{index}) must be >= 1" if index < 1
798: name = literalize(name) if name
799: num = 0
800: child = nil
801: @element.find { |child|
802: child.kind_of? Element and
803: (name.nil? ? true : child.has_name?( name )) and
804: (num += 1) == index
805: }
806: else
807: return XPath::first( @element, index )
808: #{ |element|
809: # return element if element.kind_of? Element
810: #}
811: #return nil
812: end
813: 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 828
828: def []=( index, element )
829: previous = self[index]
830: if previous.nil?
831: @element.add element
832: else
833: previous.replace_with element
834: end
835: return previous
836: 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 904
904: def add element=nil
905: rv = nil
906: if element.nil?
907: Element.new "", self, @element.context
908: elsif not element.kind_of?(Element)
909: Element.new element, self, @element.context
910: else
911: @element << element
912: element.context = @element.context
913: element
914: end
915: end
# File lib/rexml/element.rb, line 937
937: def collect( xpath=nil, &block )
938: collection = []
939: XPath::each( @element, xpath ) {|e|
940: collection << yield(e) if e.kind_of?(Element)
941: }
942: collection
943: 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 868
868: def delete element
869: if element.kind_of? Element
870: @element.delete element
871: else
872: el = self[element]
873: el.remove if el
874: end
875: 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 883
883: def delete_all( xpath )
884: rv = []
885: XPath::each( @element, xpath) {|element|
886: rv << element if element.kind_of? Element
887: }
888: rv.each do |element|
889: @element.delete element
890: element.remove
891: end
892: return rv
893: 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 933
933: def each( xpath=nil, &block)
934: XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element }
935: 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 846
846: def index element
847: rv = 0
848: found = @element.find do |child|
849: child.kind_of? Element and
850: (rv += 1) and
851: child == element
852: end
853: return rv if found == element
854: return -1
855: end
# File lib/rexml/element.rb, line 945
945: def inject( xpath=nil, initial=nil, &block )
946: first = true
947: XPath::each( @element, xpath ) {|e|
948: if (e.kind_of? Element)
949: if (first and initial == nil)
950: initial = e
951: first = false
952: else
953: initial = yield( initial, e ) if e.kind_of? Element
954: end
955: end
956: }
957: initial
958: 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 964
964: def size
965: count = 0
966: @element.each {|child| count+=1 if child.kind_of? Element }
967: count
968: 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 977
977: def to_a( xpath=nil )
978: rv = XPath.match( @element, xpath )
979: return rv.find_all{|e| e.kind_of? Element} if xpath
980: rv
981: end