class REXML::Elements
elements # => #<REXML::Elements @element=<bookstore> … </>>
elements = d.root.elements
d = REXML::Document.new(xml_string)
EOT
</bookstore>
</book>
<price>39.95</price>
<year>2003</year>
<author>Erik T. Ray</author>
<title lang=“en”>Learning XML</title>
<book category=“web” cover=“paperback”>
</book>
<price>49.99</price>
<year>2003</year>
<author>Vaidyanathan Nagarajan</author>
<author>James Linn</author>
<author>Kurt Cagle</author>
<author>Per Bothner</author>
<author>James McGovern</author>
<title lang=“en”>XQuery Kick Start</title>
<book category=“web”>
</book>
<price>29.99</price>
<year>2005</year>
<author>J K. Rowling</author>
<title lang=“en”>Harry Potter</title>
<book category=“children”>
</book>
<price>30.00</price>
<year>2005</year>
<author>Giada De Laurentiis</author>
<title lang=“en”>Everyday Italian</title>
<book category=“cooking”>
<bookstore>
<?xml version=“1.0” encoding=“UTF-8”?>
xml_string = <<-EOT
not expected to instantiate this yourself.
the element.elements
object. Therefore, you are
XPath search support. You are expected to only encounter this class as
A class which provides filtering of children for Elements, and
def []( index, name=nil)
eles[5, 'book'] # => nil
eles[4, 'book'] # =>
eles[1, 'book'] # =>
eles = d.root.elements # => #
or +nil+ if there is no such _nth_ element:
returns the _nth_ found element that has the given +name+,
With arguments +n+ and +name+ given,
eles['..'].class # => REXML::Document
eles['.'] # =>
eles['//book [@category="nosuch"]'] # => nil
eles['//nosuch'] # => nil
eles['/nosuch'] # => nil
eles['//book [@category="children"]'] # =>
eles['//book'] # =>
eles['/bookstore'] # =>
eles = d.root.elements # => #
returns the first element found via that +xpath+, if any; otherwise, +nil+:
When the single argument +xpath+ is given,
eles[1] # => nil
eles.to_a # => ["Everyday Italian"]
eles = d.root.first.first # =>
The node at this index is not an \Element, and so is not returned:
eles[5] # => nil
eles[4] # =>
eles.size # => 4
eles[1] # =>
eles # => #
eles = d.root.elements
d = REXML::Document.new(xml_string)
returns the element given by the index, if any; otherwise, +nil+:
When the single argument +index+ is given,
- The selection ignores non-\Element nodes.
- The _nth_ element has index +n+.
- The first element has index 1
- The +index+ is 1-based, not 0-based, so that:
Notes:
if any found, or +nil+ if none found.
Returns the first \Element object selected by the arguments,
elements[n, name] -> element or nil
elements[xpath] -> element or nil
elements[index] -> element or nil
:call-seq:
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
def []=( index, element )
eles.size # => 5
eles[50] = REXML::Text.new('bar') # => "bar"
if +replacement_element+ is not an \Element:
Does nothing (or raises an exception)
eles[5] # =>
eles.size # => 5
eles[50] = REXML::Element.new('foo') # =>
eles.size # => 4
eles = d.root.elements # => #
d = REXML::Document.new(xml_string)
adds +replacement_element+ to the element and returns
When eles[index] does not exist,
eles[2] # =>
eles[2] = REXML::Text.new('bar')
eles[2] # =>
if +replacement_element+ is not an \Element:
Does nothing (or raises an exception)
eles[1] # =>
eles[1] = REXML::Element.new('foo')
eles[1] # =>
eles = d.root.elements # => #
d = REXML::Document.new(xml_string)
and returns +replacement_element+:
When eles[index] exists, replaces it with +replacement_element+
Replaces or adds an element.
elements[] = index, replacement_element -> replacement_element or nil
:call-seq:
def []=( index, element ) previous = self[index] if previous.nil? @element.add element else previous.replace_with element end return previous end
def add element=nil
element.context # => {:raw=>:all}
element.parent # =>
element.name # => "bar"
elements.size # => 5
element = elements.add(e1) # =>
e1 = REXML::Element.new('bar', e0, {raw: :all})
e0 = REXML::Element.new('foo')
elements.size # => 4
elements = d.root.elements
d = REXML::Document.new(xml_string)
The new element has name, parent, and context from the given +element+.
creates and adds a clone of the given +element+.
With argument +element+,
new_element.context # => {:raw=>:all}
new_element.parent # =>
new_element.name # => "foo"
elements.size # => 5
new_element = elements.add('foo') # =>
elements.size # => 4
parent.context = {raw: :all}
parent = elements.parent # =>
elements = d.root.elements
d = REXML::Document.new(xml_string)
Example:
- Context from the that parent.
- \Parent from the \Elements object.
- Name +name+.
The new element has:
With string argument +name+, creates and adds a new element.
new_element.context # => {:raw=>:all}
new_element.parent # =>
new_element.name # => nil
elements.size # => 5
new_element = elements.add # => >
elements.size # => 4
parent.context = {raw: :all}
parent = elements.parent # =>
elements = d.root.elements
d = REXML::Document.new(xml_string)
Example:
- Context from the that parent.
- \Parent from the \Elements object.
- No name.
The new element has:
With no argument, creates and adds a new element.
Adds an element; returns the element added.
add(element) -> element
add(name) -> new_element
add -> new_element
:call-seq:
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
def collect( xpath=nil )
elements.collect(xpath) {|element| element.size } # => [17, 9]
xpath = '//book [@category="web"]'
the given +xpath+:
With argument +xpath+, iterates over elements that match
elements.collect {|element| element.size } # => [9, 9, 17, 9]
elements = d.root.elements
d = REXML::Document.new(xml_string)
With no argument, iterates over all elements:
Iterates over the elements; returns the array of block return values.
collect(xpath = nil) {|element| ... } -> array
:call-seq:
def collect( xpath=nil ) collection = [] XPath::each( @element, xpath ) {|e| collection << yield(e) if e.kind_of?(Element) } collection end
def delete element
elements.delete('//nosuch') # => nil
elements.delete('//book [@category="children"]') # =>
elements.delete('//book') # =>
elements = d.root.elements
d = REXML::Document.new(xml_string)
removes the first element found via that xpath:
With string argument +xpath+ given,
elements.delete(ele_2) # => nil
elements[2] # =>
elements.size # => 3
elements.delete(ele_2) # =>
elements[2] # =>
elements.size # => 4
ele_1, ele_2, ele_3, ele_4 = *elements
elements = d.root.elements
d = REXML::Document.new(xml_string)
removes that child element:
With element argument +element+ given,
elements.delete(50) # => nil
elements[2] # =>
elements.size # => 3
elements.delete(2) # =>
elements[2] # =>
elements.size # => 4
elements = d.root.elements
d = REXML::Document.new(xml_string)
removes the child element at that offset:
With integer argument +index+ given,
Removes an element; returns the removed element, or +nil+ if none removed.
delete(xpath) -> removed_element or nil
delete(element) -> removed_element or nil
delete(index) -> removed_element or nil
:call-seq:
def delete element if element.kind_of? Element @element.delete element else el = self[element] el.remove if el end end
def delete_all( xpath )
elements.delete_all('//book') # => []
elements.size # => 0
deleted_elements.size # => 2
deleted_elements = elements.delete_all('//book')
elements.size # => 2
deleted_elements.size # => 2
deleted_elements = elements.delete_all('//book [@category="web"]')
elements.size # => 4
elements = d.root.elements
d = REXML::Document.new(xml_string)
returns the array of removed elements, if any, else +nil+.
Removes all elements found via the given +xpath+;
delete_all(xpath)
:call-seq:
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
def each( xpath=nil )
Output:
elements.each('//book [@category="web"]') {|element| p element }
that matches the given +xpath+:
With argument +xpath+, calls the block with each element
Output:
elements.each {|element| p element }
elements = d.root.elements
d = REXML::Document.new(xml_string)
With no argument, calls the block with each element:
Iterates over the elements.
each(xpath = nil) {|element| ... } -> self
:call-seq:
def each( xpath=nil ) XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } end
def empty?
d.elements.empty? # => false
d = REXML::Document.new(xml_string)
d.elements.empty? # => true
d = REXML::Document.new('')
Returns +true+ if there are no children, +false+ otherwise.
empty? -> true or false
:call-seq:
def empty? @element.find{ |child| child.kind_of? Element}.nil? end
def index element
elements.index(ele_3) # => -1
elements.index(ele_4) # => 3
elements.delete(ele_3)
elements.index(ele_4) # => 4
ele_1, ele_2, ele_3, ele_4 = *elements
elements = d.root.elements
d = REXML::Document.new(xml_string)
otherwise, returns -1:
Returns the 1-based index of the given +element+, if found;
index(element)
:call-seq:
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
def initialize parent
eles == d.root.elements # => false
eles # => #
eles = REXML::Elements.new(d.root)
d = REXML::Document.new(xml_string)
Does _not_ assign parent.elements = self:
Returns a new \Elements object with the given +parent+.
new(parent) -> new_elements_object
:call-seq:
def initialize parent @element = parent end
def inject( xpath=nil, initial=nil )
end # => 26
total += element.size
elements.inject('//book [@category="web"]', 0) do |total, element|
calls the block only with elements matching that xpath:
With both arguments +xpath+ and +initial+ are given,
end # => 44
total += element.size
elements.inject(nil, 0) do |total, element|
In this form the passed object can be used as an accumulator:
[3, 4]
[2, 3]
[1, 2]
[-1, 1]
Output:
end
element
p [elements.index(object), elements.index(element)]
elements.inject(nil, 'Initial') do |object, element|
In this example, the first object index is -1
- And so on.
- The third call passes the second block return value and the third element.
- The second call passes the first block return value and the second element.
- The first call passes the +initial+ and the first element.
calls the block once for each element.
and argument +initial+ also given,
With argument +xpath+ given as +nil+
[3, 4]
Output:
end
element
p [elements.index(object), elements.index(element)]
elements.inject('//book [@category="web"]') do |object, element|
elements matching that xpath:
With the single argument +xpath+, calls the block only with
[3, 4]
[2, 3]
[1, 2]
Output:
end
element
p [elements.index(object), elements.index(element)]
elements.inject do |object, element|
elements = d.root.elements
d = REXML::Document.new(xml_string)
which is then the object argument to the next call:
In this example, the block returns the passed element,
- And so on.
- The third call passes the second block return value and the fourth element.
- The second call passes the first block return value and the third element.
- The first call passes the first and second elements.
elements.size - 1 times.
With no argument, iterates over the elements, calling the block
Calls the block with elements; returns the last block return value.
inject(xpath = nil, initial = nil) -> object
:call-seq:
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
def literalize name
def literalize name name = name[1..-2] if name[0] == ?' or name[0] == ?" #' name end
def parent
elements.parent == d.root # => true
elements = REXML::Elements.new(d.root)
d = REXML::Document.new(xml_string)
in the \Elements object.
This element is also the default starting point for searching
Returns the parent element cited in creating the \Elements object.
parent
:call-seq:
def parent @element end
def size
d.root.size # => 6 # Three elements plus three text nodes..
d.root.elements.size # => 3 # Three elements.
d = REXML::Document.new 'seanelliottrussell'
Returns the count of \Element children:
size -> integer
:call-seq:
def size count = 0 @element.each {|child| count+=1 if child.kind_of? Element } count end
def to_a( xpath=nil )
elements.to_a('//c') # => [
that match the xpath:
With argument +xpath+, returns an array of element children
children # => ["sean", , "elliott",
children = d.root.children
elements.to_a # => [,
elements = d.root.elements
d = REXML::Document.new 'seanelliott
With no argument, returns an array of all element children:
Returns an array of element children (not including non-element children).
to_a(xpath = nil) -> array_of_elements
:call-seq:
def to_a( xpath=nil ) rv = XPath.match( @element, xpath ) return rv.find_all{|e| e.kind_of? Element} if xpath rv end