Class REXML::Elements
In: lib/rexml/element.rb
Parent: Object

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

<<   []   []=   add   collect   delete   delete_all   each   empty?   index   inject   literalize   new   size   to_a  

Included Modules

Enumerable

Public Class methods

new(parent)

Constructor

parent:the parent Element

[Source]

     # File lib/rexml/element.rb, line 727
727:     def initialize parent
728:       @element = parent
729:     end

Public Instance methods

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

[Source]

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

[Source]

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

[Source]

     # 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
collect( xpath=nil ) {|e| ...}

[Source]

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

[Source]

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

[Source]

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

[Source]

     # 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
empty?()

Returns true if there are no Element children, false otherwise

[Source]

     # File lib/rexml/element.rb, line 796
796:     def empty?
797:       @element.find{ |child| child.kind_of? Element}.nil?
798:     end
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

[Source]

     # 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
inject( xpath=nil, initial=nil ) {|initial, e| ...}

[Source]

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

[Source]

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

[Source]

     # 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

Private Instance methods

literalize(name)

Private helper class. Removes quotes from quoted strings

[Source]

     # File lib/rexml/element.rb, line 942
942:     def literalize name
943:       name = name[1..-2] if name[0] == ?' or name[0] == ?"               #'
944:       name
945:     end

[Validate]