class REXML::Element
An REXML::Element object represents an XML element.
An element:
-
Has a name (string).
-
May have a parent (another element).
-
Has zero or more children (other elements, text, CDATA, processing instructions, and comments).
-
Has zero or more siblings (other elements, text, CDATA, processing instructions, and comments).
-
Has zero or more named attributes.
In a Hurry?¶ ↑
If you’re somewhat familiar with XML and have a particular task in mind, you may want to see the tasks pages, and in particular, the tasks page for elements.
Name¶ ↑
An element has a name, which is initially set when the element is created:
e = REXML::Element.new('foo') e.name # => "foo"
The name may be changed:
e.name = 'bar' e.name # => "bar"
Parent¶ ↑
An element may have a parent.
Its parent may be assigned explicitly when the element is created:
e0 = REXML::Element.new('foo') e1 = REXML::Element.new('bar', e0) e1.parent # => <foo> ... </>
Note: the representation of an element always shows the element’s name. If the element has children, the representation indicates that by including an ellipsis (...
).
The parent may be assigned explicitly at any time:
e2 = REXML::Element.new('baz') e1.parent = e2 e1.parent # => <baz/>
When an element is added as a child, its parent is set automatically:
e1.add_element(e0) e0.parent # => <bar> ... </>
For an element that has no parent, method parent
returns nil
.
Children¶ ↑
An element has zero or more children. The children are an ordered collection of all objects whose parent is the element itself.
The children may include any combination of elements, text, comments, processing instructions, and CDATA. (This example keeps things clean by controlling whitespace via a context
setting.)
xml_string = <<-EOT <root> <ele_0/> text 0 <!--comment 0--> <?target_0 pi_0?> <![CDATA[cdata 0]]> <ele_1/> text 1 <!--comment 1--> <?target_0 pi_1?> <![CDATA[cdata 1]]> </root> EOT context = {ignore_whitespace_nodes: :all, compress_whitespace: :all} d = REXML::Document.new(xml_string, context) root = d.root root.children.size # => 10 root.each {|child| p "#{child.class}: #{child}" }
Output:
"REXML::Element: <ele_0/>" "REXML::Text: \n text 0\n " "REXML::Comment: comment 0" "REXML::Instruction: <?target_0 pi_0?>" "REXML::CData: cdata 0" "REXML::Element: <ele_1/>" "REXML::Text: \n text 1\n " "REXML::Comment: comment 1" "REXML::Instruction: <?target_0 pi_1?>" "REXML::CData: cdata 1"
A child may be added using inherited methods Parent#insert_before
or Parent#insert_after
:
xml_string = '<root><a/><c/><d/></root>' d = REXML::Document.new(xml_string) root = d.root c = d.root[1] # => <c/> root.insert_before(c, REXML::Element.new('b')) root.to_a # => [<a/>, <b/>, <c/>, <d/>]
A child may be replaced using Parent#replace_child
:
root.replace_child(c, REXML::Element.new('x')) root.to_a # => [<a/>, <b/>, <x/>, <d/>]
A child may be removed using Parent#delete
:
x = root[2] # => <x/> root.delete(x) root.to_a # => [<a/>, <b/>, <d/>]
Siblings¶ ↑
An element has zero or more siblings, which are the other children of the element’s parent.
In the example above, element ele_1
is between a CDATA sibling and a text sibling:
ele_1 = root[5] # => <ele_1/> ele_1.previous_sibling # => "cdata 0" ele_1.next_sibling # => "\n text 1\n "
Attributes¶ ↑
An element has zero or more named attributes.
A new element has no attributes:
e = REXML::Element.new('foo') e.attributes # => {}
Attributes
may be added:
e.add_attribute('bar', 'baz') e.add_attribute('bat', 'bam') e.attributes.size # => 2 e['bar'] # => "baz" e['bat'] # => "bam"
An existing attribute may be modified:
e.add_attribute('bar', 'bad') e.attributes.size # => 2 e['bar'] # => "bad"
An existing attribute may be deleted:
e.delete_attribute('bar') e.attributes.size # => 1 e['bar'] # => nil
What’s Here¶ ↑
To begin with, what’s elsewhere?
Class REXML::Element inherits from its ancestor classes:
REXML::Element itself and its ancestors also include modules:
Methods for Creating an Element¶ ↑
Methods for Attributes
¶ ↑
- [attribute_name]
-
Returns an attribute value.
add_attribute
-
Adds a new attribute.
add_attributes
-
Adds multiple new attributes.
attribute
-
Returns the attribute value for a given name and optional namespace.
delete_attribute
-
Removes an attribute.
Methods for Children¶ ↑
- [index]
-
Returns the child at the given offset.
add_element
-
Adds an element as the last child.
delete_element
-
Deletes a child element.
each_element
-
Calls the given block with each child element.
each_element_with_attribute
-
Calls the given block with each child element that meets given criteria, which can include the attribute name.
each_element_with_text
-
Calls the given block with each child element that meets given criteria, which can include text.
get_elements
-
Returns an array of element children that match a given xpath.
Methods for Text Children¶ ↑
add_text
-
Adds a text node to the element.
get_text
-
Returns a text node that meets specified criteria.
text
-
Returns the text string from the first node that meets specified criteria.
texts
-
Returns an array of the text children of the element.
text=
-
Adds, removes, or replaces the first text child of the element
Methods for Other Children¶ ↑
cdatas
-
Returns an array of the cdata children of the element.
comments
-
Returns an array of the comment children of the element.
instructions
-
Returns an array of the instruction children of the element.
Methods for Namespaces¶ ↑
add_namespace
-
Adds a namespace to the element.
delete_namespace
-
Removes a namespace from the element.
namespace
-
Returns the string namespace URI for the element.
namespaces
-
Returns a hash of all defined namespaces in the element.
prefixes
-
Returns an array of the string prefixes (names) of all defined namespaces in the element
Methods for Querying¶ ↑
document
-
Returns the document, if any, that the element belongs to.
root
-
Returns the most distant element (not document) ancestor of the element.
root_node
-
Returns the most distant ancestor of the element.
xpath
-
Returns the string xpath to the element relative to the most distant parent
has_attributes?
-
Returns whether the element has attributes.
has_elements?
-
Returns whether the element has elements.
has_text?
-
Returns whether the element has text.
next_element
-
Returns the next sibling that is an element.
previous_element
-
Returns the previous sibling that is an element.
raw
-
Returns whether raw mode is set for the element.
whitespace
-
Returns whether whitespace is respected for the element.
ignore_whitespace_nodes
-
Returns whether whitespace nodes are to be ignored for the element.
node_type
-
Returns symbol
:element
.
One More Method¶ ↑
inspect
-
Returns a string representation of the element.
Accessors¶ ↑
elements
-
Returns the
REXML::Elements
object for the element. attributes
-
Returns the
REXML::Attributes
object for the element. context
-
Returns or sets the context hash for the element.
Constants
- UNDEFINED
Attributes
Mechanisms for accessing attributes and child elements of this element.
The context holds information about the processing environment, such as whitespace handling.
Mechanisms for accessing attributes and child elements of this element.
Public Class Methods
Returns a new REXML::Element object.
When no arguments are given, returns an element with name 'UNDEFINED'
:
e = REXML::Element.new # => <UNDEFINED/> e.class # => REXML::Element e.name # => "UNDEFINED"
When only argument name
is given, returns an element of the given name:
REXML::Element.new('foo') # => <foo/>
When only argument element
is given, it must be an REXML::Element object; returns a shallow copy of the given element:
e0 = REXML::Element.new('foo') e1 = REXML::Element.new(e0) # => <foo/>
When argument parent
is also given, it must be an REXML::Parent
object:
e = REXML::Element.new('foo', REXML::Parent.new) e.parent # => #<REXML::Parent @parent=nil, @children=[<foo/>]>
When argument context
is also given, it must be a hash representing the context for the element; see Element Context:
e = REXML::Element.new('foo', nil, {raw: :all}) e.context # => {:raw=>:all}
# File rexml-3.2.8/lib/rexml/element.rb, line 327 def initialize( arg = UNDEFINED, parent=nil, context=nil ) super(parent) @elements = Elements.new(self) @attributes = Attributes.new(self) @context = context if arg.kind_of? String self.name = arg elsif arg.kind_of? Element self.name = arg.expanded_name arg.attributes.each_attribute{ |attribute| @attributes << Attribute.new( attribute ) } @context = arg.context end end
Public Instance Methods
With integer argument index
given, returns the child at offset index
, or nil
if none:
d = REXML::Document.new '><root><a/>text<b/>more<c/></root>' root = d.root (0..root.size).each do |index| node = root[index] p "#{index}: #{node} (#{node.class})" end
Output:
"0: <a/> (REXML::Element)" "1: text (REXML::Text)" "2: <b/> (REXML::Element)" "3: more (REXML::Text)" "4: <c/> (REXML::Element)" "5: (NilClass)"
With string argument attr_name
given, returns the string value for the given attribute name if it exists, otherwise nil
:
d = REXML::Document.new('<root attr="value"></root>') root = d.root root['attr'] # => "value" root['nosuch'] # => nil
With symbol argument attr_sym
given, returns [attr_sym.to_s]
:
root[:attr] # => "value" root[:nosuch] # => nil
# File rexml-3.2.8/lib/rexml/element.rb, line 1245 def [](name_or_index) case name_or_index when String attributes[name_or_index] when Symbol attributes[name_or_index.to_s] else super end end
Adds an attribute to this element, overwriting any existing attribute by the same name.
With string argument name
and object value
are given, adds the attribute created with that name and value:
e = REXML::Element.new e.add_attribute('attr', 'value') # => "value" e['attr'] # => "value" e.add_attribute('attr', 'VALUE') # => "VALUE" e['attr'] # => "VALUE"
With only attribute object attribute
given, adds the given attribute:
a = REXML::Attribute.new('attr', 'value') e.add_attribute(a) # => attr='value' e['attr'] # => "value" a = REXML::Attribute.new('attr', 'VALUE') e.add_attribute(a) # => attr='VALUE' e['attr'] # => "VALUE"
# File rexml-3.2.8/lib/rexml/element.rb, line 1349 def add_attribute( key, value=nil ) if key.kind_of? Attribute @attributes << key else @attributes[key] = value end end
Adds zero or more attributes to the element; returns the argument.
If hash argument hash
is given, each key must be a string; adds each attribute created with the key/value pair:
e = REXML::Element.new h = {'foo' => 'bar', 'baz' => 'bat'} e.add_attributes(h)
If argument array
is given, each array member must be a 2-element array <tt>[name, value]; each name must be a string:
e = REXML::Element.new a = [['foo' => 'bar'], ['baz' => 'bat']] e.add_attributes(a)
# File rexml-3.2.8/lib/rexml/element.rb, line 1380 def add_attributes hash if hash.kind_of? Hash hash.each_pair {|key, value| @attributes[key] = value } elsif hash.kind_of? Array hash.each { |value| @attributes[ value[0] ] = value[1] } end end
Adds a child element, optionally setting attributes on the added element; returns the added element.
With string argument name
, creates a new element with that name and adds the new element as a child:
e0 = REXML::Element.new('foo') e0.add_element('bar') e0[0] # => <bar/>
With argument name
and hash argument attributes
, sets attributes on the new element:
e0.add_element('baz', {'bat' => '0', 'bam' => '1'}) e0[1] # => <baz bat='0' bam='1'/>
With element argument element
, adds that element as a child:
e0 = REXML::Element.new('foo') e1 = REXML::Element.new('bar') e0.add_element(e1) e0[0] # => <bar/>
With argument element
and hash argument attributes
, sets attributes on the added element:
e0.add_element(e1, {'bat' => '0', 'bam' => '1'}) e0[1] # => <bar bat='0' bam='1'/>
# File rexml-3.2.8/lib/rexml/element.rb, line 731 def add_element element, attrs=nil raise "First argument must be either an element name, or an Element object" if element.nil? el = @elements.add(element) attrs.each do |key, value| el.attributes[key]=value end if attrs.kind_of? Hash el end
Adds a namespace to the element; returns self
.
With the single argument prefix
, adds a namespace using the given prefix
and the namespace URI:
e = REXML::Element.new('foo') e.add_namespace('bar') e.namespaces # => {"xmlns"=>"bar"}
With both arguments prefix
and uri
given, adds a namespace using both arguments:
e.add_namespace('baz', 'bat') e.namespaces # => {"xmlns"=>"bar", "baz"=>"bat"}
# File rexml-3.2.8/lib/rexml/element.rb, line 654 def add_namespace( prefix, uri=nil ) unless uri @attributes["xmlns"] = prefix else prefix = "xmlns:#{prefix}" unless prefix =~ /^xmlns:/ @attributes[ prefix ] = uri end self end
Adds text to the element.
When string argument string
is given, returns nil
.
If the element has no child text node, creates a REXML::Text object using the string, honoring the current settings for whitespace and raw, then adds that node to the element:
d = REXML::Document.new('<a><b/></a>') a = d.root a.add_text('foo') a.to_a # => [<b/>, "foo"]
If the element has child text nodes, appends the string to the last text node:
d = REXML::Document.new('<a>foo<b/>bar</a>') a = d.root a.add_text('baz') a.to_a # => ["foo", <b/>, "barbaz"] a.add_text('baz') a.to_a # => ["foo", <b/>, "barbazbaz"]
When text node argument text_node
is given, appends the node as the last text node in the element; returns self
:
d = REXML::Document.new('<a>foo<b/>bar</a>') a = d.root a.add_text(REXML::Text.new('baz')) a.to_a # => ["foo", <b/>, "bar", "baz"] a.add_text(REXML::Text.new('baz')) a.to_a # => ["foo", <b/>, "bar", "baz", "baz"]
# File rexml-3.2.8/lib/rexml/element.rb, line 1146 def add_text( text ) if text.kind_of? String if @children[-1].kind_of? Text @children[-1] << text return end text = Text.new( text, whitespace(), nil, raw() ) end self << text unless text.nil? return self end
Returns the string value for the given attribute name.
With only argument name
given, returns the value of the named attribute if it exists, otherwise nil
:
xml_string = <<-EOT <root xmlns="ns0"> <a xmlns="ns1" attr="value"></a> <b xmlns="ns2" attr="value"></b> <c attr="value"/> </root> EOT d = REXML::Document.new(xml_string) root = d.root a = root[1] # => <a xmlns='ns1' attr='value'/> a.attribute('attr') # => attr='value' a.attribute('nope') # => nil
With arguments name
and namespace
given, returns the value of the named attribute if it exists, otherwise nil
:
xml_string = "<root xmlns:a='a' a:x='a:x' x='x'/>" document = REXML::Document.new(xml_string) document.root.attribute("x") # => x='x' document.root.attribute("x", "a") # => a:x='a:x'
# File rexml-3.2.8/lib/rexml/element.rb, line 1286 def attribute( name, namespace=nil ) prefix = nil if namespaces.respond_to? :key prefix = namespaces.key(namespace) if namespace else prefix = namespaces.index(namespace) if namespace end prefix = nil if prefix == 'xmlns' ret_val = attributes.get_attribute( "#{prefix ? prefix + ':' : ''}#{name}" ) return ret_val unless ret_val.nil? return nil if prefix.nil? # now check that prefix'es namespace is not the same as the # default namespace return nil unless ( namespaces[ prefix ] == namespaces[ 'xmlns' ] ) attributes.get_attribute( name ) end
Returns a frozen array of the REXML::CData
children of the element:
xml_string = <<-EOT <root> <![CDATA[foo]]> <![CDATA[bar]]> </root> EOT d = REXML::Document.new(xml_string) cds = d.root.cdatas # => ["foo", "bar"] cds.frozen? # => true cds.map {|cd| cd.class } # => [REXML::CData, REXML::CData]
# File rexml-3.2.8/lib/rexml/element.rb, line 1424 def cdatas find_all { |child| child.kind_of? CData }.freeze end
Returns a shallow copy of the element, containing the name and attributes, but not the parent or children:
e = REXML::Element.new('foo') e.add_attributes({'bar' => 0, 'baz' => 1}) e.clone # => <foo bar='0' baz='1'/>
# File rexml-3.2.8/lib/rexml/element.rb, line 391 def clone self.class.new self end
Returns a frozen array of the REXML::Comment
children of the element:
xml_string = <<-EOT <root> <!--foo--> <!--bar--> </root> EOT d = REXML::Document.new(xml_string) cs = d.root.comments cs.frozen? # => true cs.map {|c| c.class } # => [REXML::Comment, REXML::Comment] cs.map {|c| c.to_s } # => ["foo", "bar"]
# File rexml-3.2.8/lib/rexml/element.rb, line 1445 def comments find_all { |child| child.kind_of? Comment }.freeze end
Removes a named attribute if it exists; returns the removed attribute if found, otherwise nil
:
e = REXML::Element.new('foo') e.add_attribute('bar', 'baz') e.delete_attribute('bar') # => <bar/> e.delete_attribute('bar') # => nil
# File rexml-3.2.8/lib/rexml/element.rb, line 1399 def delete_attribute(key) attr = @attributes.get_attribute(key) attr.remove unless attr.nil? end
Deletes a child element.
When 1-based integer argument index
is given, removes and returns the child element at that offset if it exists; indexing does not include text nodes; returns nil
if the element does not exist:
d = REXML::Document.new '<a><b/>text<c/></a>' a = d.root # => <a> ... </> a.delete_element(1) # => <b/> a.delete_element(1) # => <c/> a.delete_element(1) # => nil
When element argument element
is given, removes and returns that child element if it exists, otherwise returns nil
:
d = REXML::Document.new '<a><b/>text<c/></a>' a = d.root # => <a> ... </> c = a[2] # => <c/> a.delete_element(c) # => <c/> a.delete_element(c) # => nil
When xpath argument xpath
is given, removes and returns the element at xpath if it exists, otherwise returns nil
:
d = REXML::Document.new '<a><b/>text<c/></a>' a = d.root # => <a> ... </> a.delete_element('//c') # => <c/> a.delete_element('//c') # => nil
# File rexml-3.2.8/lib/rexml/element.rb, line 777 def delete_element element @elements.delete element end
Removes a namespace from the element.
With no argument, removes the default namespace:
d = REXML::Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>" d.to_s # => "<a xmlns:foo='bar' xmlns='twiddle'/>" d.root.delete_namespace # => <a xmlns:foo='bar'/> d.to_s # => "<a xmlns:foo='bar'/>"
With argument namespace
, removes the specified namespace:
d.root.delete_namespace('foo') d.to_s # => "<a/>"
Does nothing if no such namespace is found:
d.root.delete_namespace('nosuch') d.to_s # => "<a/>"
# File rexml-3.2.8/lib/rexml/element.rb, line 686 def delete_namespace namespace="xmlns" namespace = "xmlns:#{namespace}" unless namespace == 'xmlns' attribute = attributes.get_attribute(namespace) attribute.remove unless attribute.nil? self end
If the element is part of a document, returns that document:
d = REXML::Document.new('<a><b><c/></b></a>') top_element = d.first child = top_element.first top_element.document == d # => true child.document == d # => true
If the element is not part of a document, returns nil
:
REXML::Element.new.document # => nil
For a document, returns self
:
d.document == d # => true
# File rexml-3.2.8/lib/rexml/element.rb, line 478 def document rt = root rt.parent if rt end
Calls the given block with each child element:
d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' a = d.root a.each_element {|e| p e }
Output:
<b> ... </> <c> ... </> <d> ... </> <e/>
# File rexml-3.2.8/lib/rexml/element.rb, line 929 def each_element( xpath=nil, &block ) # :yields: Element @elements.each( xpath, &block ) end
Calls the given block with each child element that meets given criteria.
When only string argument attr_name
is given, calls the block with each child element that has that attribute:
d = REXML::Document.new '<a><b id="1"/><c id="2"/><d id="1"/><e/></a>' a = d.root a.each_element_with_attribute('id') {|e| p e }
Output:
<b id='1'/> <c id='2'/> <d id='1'/>
With argument attr_name
and string argument value
given, calls the block with each child element that has that attribute with that value:
a.each_element_with_attribute('id', '1') {|e| p e }
Output:
<b id='1'/> <d id='1'/>
With arguments attr_name
, value
, and integer argument max
given, calls the block with at most max
child elements:
a.each_element_with_attribute('id', '1', 1) {|e| p e }
Output:
<b id='1'/>
With all arguments given, including xpath
, calls the block with only those child elements that meet the first three criteria, and also match the given xpath
:
a.each_element_with_attribute('id', '1', 2, '//d') {|e| p e }
Output:
<d id='1'/>
# File rexml-3.2.8/lib/rexml/element.rb, line 846 def each_element_with_attribute( key, value=nil, max=0, name=nil, &block ) # :yields: Element each_with_something( proc {|child| if value.nil? child.attributes[key] != nil else child.attributes[key]==value end }, max, name, &block ) end
Calls the given block with each child element that meets given criteria.
With no arguments, calls the block with each child element that has text:
d = REXML::Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>' a = d.root a.each_element_with_text {|e| p e }
Output:
<b> ... </> <c> ... </> <d> ... </>
With the single string argument text
, calls the block with each element that has exactly that text:
a.each_element_with_text('b') {|e| p e }
Output:
<b> ... </> <c> ... </>
With argument text
and integer argument max
, calls the block with at most max
elements:
a.each_element_with_text('b', 1) {|e| p e }
Output:
<b> ... </>
With all arguments given, including xpath
, calls the block with only those child elements that meet the first two criteria, and also match the given xpath
:
a.each_element_with_text('b', 2, '//c') {|e| p e }
Output:
<c> ... </>
# File rexml-3.2.8/lib/rexml/element.rb, line 903 def each_element_with_text( text=nil, max=0, name=nil, &block ) # :yields: Element each_with_something( proc {|child| if text.nil? child.has_text? else child.text == text end }, max, name, &block ) end
Returns an array of the elements that match the given xpath
:
xml_string = <<-EOT <root> <a level='1'> <a level='2'/> </a> </root> EOT d = REXML::Document.new(xml_string) d.root.get_elements('//a') # => [<a level='1'> ... </>, <a level='2'/>]
# File rexml-3.2.8/lib/rexml/element.rb, line 948 def get_elements( xpath ) @elements.to_a( xpath ) end
Returns the first text node child in a specified element, if it exists, nil
otherwise.
With no argument, returns the first text node from self
:
d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>" d.root.get_text.class # => REXML::Text d.root.get_text # => "some text "
With argument xpath
, returns the first text node from the element that matches xpath
:
d.root.get_text(1) # => "this is bold!"
# File rexml-3.2.8/lib/rexml/element.rb, line 1052 def get_text path = nil rv = nil if path element = @elements[ path ] rv = element.get_text unless element.nil? else rv = @children.find { |node| node.kind_of? Text } end return rv end
Returns true
if the element has attributes, false
otherwise:
d = REXML::Document.new('<root><a attr="val"/><b/></root>') a, b = *d.root a.has_attributes? # => true b.has_attributes? # => false
# File rexml-3.2.8/lib/rexml/element.rb, line 1319 def has_attributes? return !@attributes.empty? end
Returns true
if the element has one or more element children, false
otherwise:
d = REXML::Document.new '<a><b/>text<c/></a>' a = d.root # => <a> ... </> a.has_elements? # => true b = a[0] # => <b/> b.has_elements? # => false
# File rexml-3.2.8/lib/rexml/element.rb, line 793 def has_elements? !@elements.empty? end
Returns true
if the element has one or more text noded, false
otherwise:
d = REXML::Document.new '<a><b/>text<c/></a>' a = d.root a.has_text? # => true b = a[0] b.has_text? # => false
# File rexml-3.2.8/lib/rexml/element.rb, line 1001 def has_text? not text().nil? end
Returns true
if whitespace nodes are ignored for the element.
See Element Context.
# File rexml-3.2.8/lib/rexml/element.rb, line 516 def ignore_whitespace_nodes @ignore_whitespace_nodes = false if @context if @context[:ignore_whitespace_nodes] @ignore_whitespace_nodes = (@context[:ignore_whitespace_nodes] == :all or @context[:ignore_whitespace_nodes].include? expanded_name) end end end
Returns a string representation of the element.
For an element with no attributes and no children, shows the element name:
REXML::Element.new.inspect # => "<UNDEFINED/>"
Shows attributes, if any:
e = REXML::Element.new('foo') e.add_attributes({'bar' => 0, 'baz' => 1}) e.inspect # => "<foo bar='0' baz='1'/>"
Shows an ellipsis (...
), if there are child elements:
e.add_element(REXML::Element.new('bar')) e.add_element(REXML::Element.new('baz')) e.inspect # => "<foo bar='0' baz='1'> ... </>"
# File rexml-3.2.8/lib/rexml/element.rb, line 366 def inspect rv = "<#@expanded_name" @attributes.each_attribute do |attr| rv << " " attr.write( rv, 0 ) end if children.size > 0 rv << "> ... </>" else rv << "/>" end end
Returns a frozen array of the REXML::Instruction
children of the element:
xml_string = <<-EOT <root> <?target0 foo?> <?target1 bar?> </root> EOT d = REXML::Document.new(xml_string) is = d.root.instructions is.frozen? # => true is.map {|i| i.class } # => [REXML::Instruction, REXML::Instruction] is.map {|i| i.to_s } # => ["<?target0 foo?>", "<?target1 bar?>"]
# File rexml-3.2.8/lib/rexml/element.rb, line 1466 def instructions find_all { |child| child.kind_of? Instruction }.freeze end
Returns the string namespace URI for the element, possibly deriving from one of its ancestors.
xml_string = <<-EOT <root> <a xmlns='1' xmlns:y='2'> <b/> <c xmlns:z='3'/> </a> </root> EOT d = REXML::Document.new(xml_string) b = d.elements['//b'] b.namespace # => "1" b.namespace('y') # => "2" b.namespace('nosuch') # => nil
# File rexml-3.2.8/lib/rexml/element.rb, line 621 def namespace(prefix=nil) if prefix.nil? prefix = prefix() end if prefix == '' prefix = "xmlns" else prefix = "xmlns:#{prefix}" unless prefix[0,5] == 'xmlns' end ns = attributes[ prefix ] ns = parent.namespace(prefix) if ns.nil? and parent ns = '' if ns.nil? and prefix == 'xmlns' return ns end
Returns a hash of all defined namespaces in the element and its ancestors:
xml_string = <<-EOT <root> <a xmlns:x='1' xmlns:y='2'> <b/> <c xmlns:z='3'/> </a> </root> EOT d = REXML::Document.new(xml_string) d.elements['//a'].namespaces # => {"x"=>"1", "y"=>"2"} d.elements['//b'].namespaces # => {"x"=>"1", "y"=>"2"} d.elements['//c'].namespaces # => {"x"=>"1", "y"=>"2", "z"=>"3"}
# File rexml-3.2.8/lib/rexml/element.rb, line 594 def namespaces namespaces = {} namespaces = parent.namespaces if parent namespaces = namespaces.merge( attributes.namespaces ) return namespaces end
Returns the next sibling that is an element if it exists, niL
otherwise:
d = REXML::Document.new '<a><b/>text<c/></a>' d.root.elements['b'].next_element #-> <c/> d.root.elements['c'].next_element #-> nil
# File rexml-3.2.8/lib/rexml/element.rb, line 962 def next_element element = next_sibling element = element.next_sibling until element.nil? or element.kind_of? Element return element end
Returns symbol :element
:
d = REXML::Document.new('<a/>') a = d.root # => <a/> a.node_type # => :element
# File rexml-3.2.8/lib/rexml/element.rb, line 1167 def node_type :element end
Returns an array of the string prefixes (names) of all defined namespaces in the element and its ancestors:
xml_string = <<-EOT <root> <a xmlns:x='1' xmlns:y='2'> <b/> <c xmlns:z='3'/> </a> </root> EOT d = REXML::Document.new(xml_string, {compress_whitespace: :all}) d.elements['//a'].prefixes # => ["x", "y"] d.elements['//b'].prefixes # => ["x", "y"] d.elements['//c'].prefixes # => ["x", "y", "z"]
# File rexml-3.2.8/lib/rexml/element.rb, line 568 def prefixes prefixes = [] prefixes = parent.prefixes if parent prefixes |= attributes.prefixes return prefixes end
Returns the previous sibling that is an element if it exists, niL
otherwise:
d = REXML::Document.new '<a><b/>text<c/></a>' d.root.elements['c'].previous_element #-> <b/> d.root.elements['b'].previous_element #-> nil
# File rexml-3.2.8/lib/rexml/element.rb, line 978 def previous_element element = previous_sibling element = element.previous_sibling until element.nil? or element.kind_of? Element return element end
Returns true
if raw mode is set for the element.
See Element Context.
The evaluation is tested against expanded_name
, and so is namespace sensitive.
# File rexml-3.2.8/lib/rexml/element.rb, line 536 def raw @raw = (@context and @context[:raw] and (@context[:raw] == :all or @context[:raw].include? expanded_name)) @raw end
Returns the most distant element (not document) ancestor of the element:
d = REXML::Document.new('<a><b><c/></b></a>') top_element = d.first child = top_element.first top_element.root == top_element # => true child.root == top_element # => true
For a document, returns the topmost element:
d.root == top_element # => true
# File rexml-3.2.8/lib/rexml/element.rb, line 451 def root return elements[1] if self.kind_of? Document return self if parent.kind_of? Document or parent.nil? return parent.root end
Returns the most distant ancestor of self
.
When the element is part of a document, returns the root node of the document. Note that the root node is different from the document element; in this example a
is document element and the root node is its parent:
d = REXML::Document.new('<a><b><c/></b></a>') top_element = d.first # => <a> ... </> child = top_element.first # => <b> ... </> d.root_node == d # => true top_element.root_node == d # => true child.root_node == d # => true
When the element is not part of a document, but does have ancestor elements, returns the most distant ancestor element:
e0 = REXML::Element.new('foo') e1 = REXML::Element.new('bar') e1.parent = e0 e2 = REXML::Element.new('baz') e2.parent = e1 e2.root_node == e0 # => true
When the element has no ancestor elements, returns self
:
e = REXML::Element.new('foo') e.root_node == e # => true
# File rexml-3.2.8/lib/rexml/element.rb, line 430 def root_node parent.nil? ? self : parent.root_node end
Returns the text string from the first text node child in a specified element, if it exists, nil
otherwise.
With no argument, returns the text from the first text node in self
:
d = REXML::Document.new "<p>some text <b>this is bold!</b> more text</p>" d.root.text.class # => String d.root.text # => "some text "
With argument xpath
, returns text from the first text node in the element that matches xpath
:
d.root.text(1) # => "this is bold!"
Note that an element may have multiple text nodes, possibly separated by other non-text children, as above. Even so, the returned value is the string text from the first such node.
Note also that the text note is retrieved by method get_text
, and so is always normalized text.
# File rexml-3.2.8/lib/rexml/element.rb, line 1029 def text( path = nil ) rv = get_text(path) return rv.value unless rv.nil? nil end
Adds, replaces, or removes the first text node child in the element.
With string argument string
, creates a new REXML::Text node containing that string, honoring the current settings for whitespace and row, then places the node as the first text child in the element; returns string
.
If the element has no text child, the text node is added:
d = REXML::Document.new '<a><b/></a>' d.root.text = 'foo' #-> '<a><b/>foo</a>'
If the element has a text child, it is replaced:
d.root.text = 'bar' #-> '<a><b/>bar</a>'
With argument nil
, removes the first text child:
d.root.text = nil #-> '<a><b/><c/></a>'
# File rexml-3.2.8/lib/rexml/element.rb, line 1088 def text=( text ) if text.kind_of? String text = Text.new( text, whitespace(), nil, raw() ) elsif !text.nil? and !text.kind_of? Text text = Text.new( text.to_s, whitespace(), nil, raw() ) end old_text = get_text if text.nil? old_text.remove unless old_text.nil? else if old_text.nil? self << text else old_text.replace_with( text ) end end return self end
Returns a frozen array of the REXML::Text
children of the element:
xml_string = '<root><a/>text<b/>more<c/></root>' d = REXML::Document.new(xml_string) ts = d.root.texts ts.frozen? # => true ts.map {|t| t.class } # => [REXML::Text, REXML::Text] ts.map {|t| t.to_s } # => ["text", "more"]
# File rexml-3.2.8/lib/rexml/element.rb, line 1482 def texts find_all { |child| child.kind_of? Text }.freeze end
Returns true
if whitespace is respected for this element, false
otherwise.
See Element Context.
The evaluation is tested against the element’s expanded_name
, and so is namespace-sensitive.
# File rexml-3.2.8/lib/rexml/element.rb, line 493 def whitespace @whitespace = nil if @context if @context[:respect_whitespace] @whitespace = (@context[:respect_whitespace] == :all or @context[:respect_whitespace].include? expanded_name) end @whitespace = false if (@context[:compress_whitespace] and (@context[:compress_whitespace] == :all or @context[:compress_whitespace].include? expanded_name) ) end @whitespace = true unless @whitespace == false @whitespace end
DEPRECATED¶ ↑
Writes out this element, and recursively, all children.
- output
-
output an object which supports ‘<< string’; this is where the
document will be written.
- indent
-
An integer. If -1, no indenting will be used; otherwise, the indentation will be this number of spaces, and children will be indented an additional amount. Defaults to -1
- transitive
-
If transitive is true and indent is >= 0, then the output will be pretty-printed in such a way that the added whitespace does not affect the parse tree of the document
- ie_hack
-
This hack inserts a space before the /> on empty tags to address a limitation of Internet Explorer. Defaults to false
out = '' doc.write( out ) #-> doc is written to the string 'out' doc.write( $stdout ) #-> doc written to the console
# File rexml-3.2.8/lib/rexml/element.rb, line 1508 def write(output=$stdout, indent=-1, transitive=false, ie_hack=false) Kernel.warn("#{self.class.name}.write is deprecated. See REXML::Formatters", uplevel: 1) formatter = if indent > -1 if transitive require_relative "formatters/transitive" REXML::Formatters::Transitive.new( indent, ie_hack ) else REXML::Formatters::Pretty.new( indent, ie_hack ) end else REXML::Formatters::Default.new( ie_hack ) end formatter.write( self, output ) end
Returns the string xpath to the element relative to the most distant parent:
d = REXML::Document.new('<a><b><c/></b></a>') a = d.root # => <a> ... </> b = a[0] # => <b> ... </> c = b[0] # => <c/> d.xpath # => "" a.xpath # => "/a" b.xpath # => "/a/b" c.xpath # => "/a/b/c"
If there is no parent, returns the expanded name of the element:
e = REXML::Element.new('foo') e.xpath # => "foo"
# File rexml-3.2.8/lib/rexml/element.rb, line 1191 def xpath path_elements = [] cur = self path_elements << __to_xpath_helper( self ) while cur.parent cur = cur.parent path_elements << __to_xpath_helper( cur ) end return path_elements.reverse.join( "/" ) end
Private Instance Methods
# File rexml-3.2.8/lib/rexml/element.rb, line 1525 def __to_xpath_helper node rv = node.expanded_name.clone if node.parent results = node.parent.find_all {|n| n.kind_of?(REXML::Element) and n.expanded_name == node.expanded_name } if results.length > 1 idx = results.index( node ) rv << "[#{idx+1}]" end end rv end
A private helper method
# File rexml-3.2.8/lib/rexml/element.rb, line 1540 def each_with_something( test, max=0, name=nil ) num = 0 @elements.each( name ){ |child| yield child if test.call(child) and num += 1 return if max>0 and num == max } end