123456789_123456789_123456789_123456789_123456789_

Class: REXML::Element

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Parent, Child
Instance Chain:
self, Namespace, XMLTokens, Parent, Enumerable, Child, Node
Inherits: REXML::Parent
Defined in: lib/rexml/element.rb

Overview

Represents a tagged XML element. Elements are characterized by having children, attributes, and names, and can themselves be children.

Constant Summary

XMLTokens - Included

NAME, NAMECHAR, NAME_CHAR, NAME_START_CHAR, NAME_STR, NCNAME_STR, NMTOKEN, NMTOKENS, REFERENCE

Namespace - Included

NAMESPLIT

Class Method Summary

Parent - Inherited

.new

Constructor.

Child - Inherited

.new

Constructor.

Instance Attribute Summary

  • #attributes readonly

    Mechanisms for accessing attributes and child elements of this element.

  • #context rw

    The context holds information about the processing environment, such as whitespace handling.

  • #elements readonly

    Mechanisms for accessing attributes and child elements of this element.

  • #has_attributes? ⇒ Boolean readonly

    Evaluates to true if this element has any attributes set, false otherwise.

  • #has_elements? ⇒ Boolean readonly

    Evaluates to true if this element has at least one child Element doc = Document.new “<a><b/><c>Text</c></a>” doc.root.has_elements # -> true doc.elements.has_elements # -> false doc.elements.has_elements # -> false.

  • #has_text? ⇒ Boolean readonly

    Evaluates to true if this element has at least one Text child.

Namespace - Included

#expanded_name

The name of the object, valid if set.

#local_name

Alias for Namespace#name.

#name

The name of the object, valid if set.

#name=

Sets the name and the expanded name.

#prefix

The expanded name of the object, valid if name is set.

Parent - Inherited

Child - Inherited

#next_sibling
#next_sibling=

Sets the next sibling of this child.

#parent

The Parent of this object.

#parent=

Sets the parent of this child to the supplied argument.

#previous_sibling
#previous_sibling=

Sets the previous sibling of this child.

Node - Included

Instance Method Summary

Namespace - Included

#fully_expanded_name

Fully expand the name, even if the prefix wasn’t specified in the source file.

#has_name?

Compares names optionally WITH namespaces.

Parent - Inherited

#<<

Alias for Parent#push.

#[]

Fetches a child at a given index.

#[]=

Set an index entry.

#add,
#children

Alias for Parent#to_a.

#deep_clone

Deeply clones this object.

#delete, #delete_at, #delete_if, #each,
#each_child

Alias for Parent#each.

#each_index,
#index

Fetches the index of a given child of this parent.

#insert_after

Inserts an child after another child child2 will be inserted after child1 in the child list of the parent.

#insert_before

Inserts an child before another child child2 will be inserted before child1 in the child list of the parent.

#length

Alias for Parent#size.

#push

Alias for Parent#add.

#replace_child

Replaces one child with another, making sure the nodelist is correct Child).

#size, #to_a, #unshift

Child - Inherited

#bytes

This doesn’t yet handle encodings.

#document
Returns

the document this child belongs to, or nil if this child belongs to no document.

#remove

Removes this child from the parent.

#replace_with

Replaces this object with another object.

Node - Included

#each_recursive

Visit all subnodes of self recursively.

#find_first_recursive

Find (and return) first subnode (recursively) for which the block evaluates to true.

#indent,
#index_in_parent

Returns the position that self holds in its parent’s array, indexed from 1.

#next_sibling_node, #previous_sibling_node,
#to_s
indent

Constructor Details

.new(arg = UNDEFINED, parent = nil, context = nil) ⇒ Element

Constructor

arg

if not supplied, will be set to the default value. If a String, the name of this object will be set to the argument. If an Element, the object will be shallowly cloned; name, attributes, and namespaces will be copied. Children will not be copied.

parent

if supplied, must be a Parent, and will be used as the parent of this object.

context

If supplied, must be a hash containing context items. Context items include:

  • :respect_whitespace the value of this is :all or an array of strings being the names of the elements to respect whitespace for. Defaults to :all.

  • :compress_whitespace the value can be :all or an array of strings being the names of the elements to ignore whitespace on. Overrides :respect_whitespace.

  • :ignore_whitespace_nodes the value can be :all or an array of strings being the names of the elements in which to ignore whitespace-only nodes. If this is set, Text nodes which contain only whitespace will not be added to the document tree.

  • :raw can be :all, or an array of strings being the names of the elements to process in raw mode. In raw mode, special characters in text is not converted to or from entities.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 59

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

Instance Attribute Details

#attributes (readonly)

Mechanisms for accessing attributes and child elements of this element.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 28

attr_reader :attributes, :elements

#context (rw)

The context holds information about the processing environment, such as whitespace handling.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 31

attr_accessor :context

#elements (readonly)

Mechanisms for accessing attributes and child elements of this element.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 28

attr_reader :attributes, :elements

#has_attributes?Boolean (readonly)

Evaluates to true if this element has any attributes set, false otherwise.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 603

def has_attributes?
  return !@attributes.empty?
end

#has_elements?Boolean (readonly)

Evaluates to true if this element has at least one child Element

doc = Document.new "<a><b/><c>Text</c></a>"
doc.root.has_elements               # -> true
doc.elements["/a/b"].has_elements   # -> false
doc.elements["/a/c"].has_elements   # -> false
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 325

def has_elements?
  !@elements.empty?
end

#has_text?Boolean (readonly)

Evaluates to true if this element has at least one Text child

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 433

def has_text?
  not text().nil?
end

Instance Method Details

#[](name_or_index)

Fetches an attribute value or a child.

If String or ::Symbol is specified, it’s treated as attribute name. Attribute value as String or nil is returned. This case is shortcut of attributes[name].

If Integer is specified, it’s treated as the index of child. It returns Nth child.

doc = REXML::Document.new("<a attr='1'><b/><c/></a>")
doc.root["attr"]             # => "1"
doc.root.attributes["attr"]  # => "1"
doc.root[1]                  # => <c/>
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 567

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

#__to_xpath_helper(node) (private)

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 729

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

#add_attribute(key, value = nil)

Adds an attribute to this element, overwriting any existing attribute by the same name.

key

can be either an Attribute or a String. If an Attribute, the attribute is added to the list of Element attributes. If String, the argument is used as the name of the new attribute, and the value parameter must be supplied.

value

Required if key is a String, and ignored if the first argument is an Attribute. This is a String, and is used as the value of the new Attribute. This should be the unnormalized value of the attribute (without entities).

Returns

the Attribute added

e = Element.new 'e'
e.add_attribute( 'a', 'b' )               #-> <e a='b'/>
e.add_attribute( 'x:a', 'c' )             #-> <e a='b' x:a='c'/>
e.add_attribute Attribute.new('b', 'd')   #-> <e a='b' x:a='c' b='d'/>
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 624

def add_attribute( key, value=nil )
  if key.kind_of? Attribute
    @attributes << key
  else
    @attributes[key] = value
  end
end

#add_attributes(hash)

Add multiple attributes to this element.

hash

is either a hash, or array of arrays

el.add_attributes( {"name1"=>"value1", "name2"=>"value2"} )
el.add_attributes( [ ["name1","value1"], ["name2"=>"value2"] ] )
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 636

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

#add_element(element, attrs = nil)

Adds a child to this element, optionally setting attributes in the element.

element

optional. If Element, the element is added. Otherwise, a new Element is constructed with the argument (see Element.initialize).

attrs

If supplied, must be a Hash containing String name,value pairs, which will be used to set the attributes of the new Element.

Returns

the Element that was added

el = doc.add_element 'my-tag'
el = doc.add_element 'my-tag', {'attr1'=>'val1', 'attr2'=>'val2'}
el = Element.new 'my-tag'
doc.add_element el
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 296

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

#add_namespace(prefix, uri = nil)

Adds a namespace to this element.

prefix

the prefix string, or the namespace URI if uri is not supplied

uri

the namespace URI. May be nil, in which prefix is used as the URI

Evaluates to: this Element

a = Element.new("a")
a.add_namespace("xmlns:foo", "bar" )
a.add_namespace("foo", "bar")  # shorthand for previous line
a.add_namespace("twiddle")
puts a   #-> <a xmlns:foo='bar' xmlns='twiddle'/>
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 251

def add_namespace( prefix, uri=nil )
  unless uri
    @attributes["xmlns"] = prefix
  else
    prefix = "xmlns:#{prefix}" unless prefix =~ /^xmlns:/
    @attributes[ prefix ] = uri
  end
  self
end

#add_text(text)

A helper method to add a Text child. Actual Text instances can be added with regular Parent methods, such as add() and <<()

text

if a String, a new Text instance is created and added to the parent. If Text, the object is added directly.

Returns

this Element

e = Element.new('a')          #-> <e/>
e.add_text 'foo'              #-> <e>foo</e>
e.add_text Text.new(' bar')    #-> <e>foo bar</e>

Note that at the end of this example, the branch has 3 nodes; the ‘e’ element and 2 Text node children.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 523

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

#attribute(name, namespace = nil)

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 578

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

#cdatas

Get an array of all CData children. IMMUTABLE

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 668

def cdatas
  find_all { |child| child.kind_of? CData }.freeze
end

#clone

Creates a shallow copy of self.

d = Document.new "<a><b/><b/><c><d/></c></a>"
new_a = d.root.clone
puts new_a  # => "<a/>"
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 97

def clone
  self.class.new self
end

#comments

Get an array of all Comment children. IMMUTABLE

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 674

def comments
  find_all { |child| child.kind_of? Comment }.freeze
end

#delete_attribute(key)

Removes an attribute

key

either an Attribute or a String. In either case, the attribute is found by matching the attribute name to the argument, and then removed. If no attribute is found, no action is taken.

Returns

the attribute removed, or nil if this Element did not contain a matching attribute

e = Element.new('E')
e.add_attribute( 'name', 'Sean' )             #-> <E name='Sean'/>
r = e.add_attribute( 'sur:name', 'Russell' )  #-> <E name='Sean' sur:name='Russell'/>
e.delete_attribute( 'name' )                  #-> <E sur:name='Russell'/>
e.delete_attribute( r )                       #-> <E/>
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 657

def delete_attribute(key)
  attr = @attributes.get_attribute(key)
  attr.remove unless attr.nil?
end

#delete_element(element)

Deletes a child element.

element

Must be an Element, String, or Integer. If Element, the element is removed. If String, the element is found (via XPath) and removed. <em>This means that any parent can remove any descendant.<em> If Integer, the Element indexed by that number will be removed.

Returns

the element that was removed.

doc.delete_element "/a/b/c[@id='4']"
doc.delete_element doc.elements["//k"]
doc.delete_element 1
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 316

def delete_element element
  @elements.delete element
end

#delete_namespace(namespace = "xmlns")

Removes a namespace from this node. This only works if the namespace is actually declared in this node. If no argument is passed, deletes the default namespace.

Evaluates to: this element

doc = Document.new "<a xmlns:foo='bar' xmlns='twiddle'/>"
doc.root.delete_namespace
puts doc     # -> <a xmlns:foo='bar'/>
doc.root.delete_namespace 'foo'
puts doc     # -> <a/>
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 271

def delete_namespace namespace="xmlns"
  namespace = "xmlns:#{namespace}" unless namespace == 'xmlns'
  attribute = attributes.get_attribute(namespace)
  attribute.remove unless attribute.nil?
  self
end

#document

Evaluates to the document to which this element belongs, or nil if this element doesn’t belong to a document.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 132

def document
  rt = root
  rt.parent if rt
end

#each_element(xpath = nil, &block)

Synonym for #elements.each

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 393

def each_element( xpath=nil, &block ) # :yields: Element
  @elements.each( xpath, &block )
end

#each_element_with_attribute(key, value = nil, max = 0, name = nil, &block)

Iterates through the child elements, yielding for each Element that has a particular attribute set.

key

the name of the attribute to search for

value

the value of the attribute

max

(optional) causes this method to return after yielding for this number of matching children

name

(optional) if supplied, this is an XPath that filters the children to check.

doc = Document.new "<a><b @id='1'/><c @id='2'/><d @id='1'/><e/></a>"
# Yields b, c, d
doc.root.each_element_with_attribute( 'id' ) {|e| p e}
# Yields b, d
doc.root.each_element_with_attribute( 'id', '1' ) {|e| p e}
# Yields b
doc.root.each_element_with_attribute( 'id', '1', 1 ) {|e| p e}
# Yields d
doc.root.each_element_with_attribute( 'id', '1', 0, 'd' ) {|e| p e}
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 351

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

#each_element_with_text(text = nil, max = 0, name = nil, &block)

Iterates through the children, yielding for each Element that has a particular text set.

text

the text to search for. If nil, or not supplied, will iterate over all Element children that contain at least one Text node.

max

(optional) causes this method to return after yielding for this number of matching children

name

(optional) if supplied, this is an XPath that filters the children to check.

doc = Document.new '<a><b>b</b><c>b</c><d>d</d><e/></a>'
# Yields b, c, d
doc.each_element_with_text {|e|p e}
# Yields b, c
doc.each_element_with_text('b'){|e|p e}
# Yields b
doc.each_element_with_text('b', 1){|e|p e}
# Yields d
doc.each_element_with_text(nil, 0, 'd'){|e|p e}
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 382

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

#each_with_something(test, max = 0, name = nil) (private)

A private helper method

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 744

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

#get_elements(xpath)

Synonym for Element.to_a This is a little slower than calling elements.each directly.

xpath

any XPath by which to search for elements in the tree

Returns

an array of Elements that match the supplied path

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 401

def get_elements( xpath )
  @elements.to_a( xpath )
end

#get_text(path = nil)

Returns the first child Text node, if any, or nil otherwise. This method returns the actual Text node, rather than the String content.

doc = Document.new "<p>some text <b>this is bold!</b> more text</p>"
# The element 'p' has two text elements, "some text " and " more text".
doc.root.get_text.value            #-> "some text "
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 462

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

#ignore_whitespace_nodes

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 162

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

#inspect

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 77

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

#instructions

Get an array of all Instruction children. IMMUTABLE

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 680

def instructions
  find_all { |child| child.kind_of? Instruction }.freeze
end

#namespace(prefix = nil)

Evaluates to the URI for a prefix, or the empty string if no such namespace is declared for this element. Evaluates recursively for ancestors. Returns the default namespace, if there is one.

prefix

the prefix to search for. If not supplied, returns the default namespace if one exists

Returns

the namespace URI as a String, or nil if no such namespace exists. If the namespace is undefined, returns an empty string

doc = Document.new("<a xmlns='1' xmlns:y='2'><b/><c xmlns:z='3'/></a>")
b = doc.elements['//b']
b.namespace           # -> '1'
b.namespace("y")      # -> '2'
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 223

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

#namespaces

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 203

def namespaces
  namespaces = {}
  namespaces = parent.namespaces if parent
  namespaces = namespaces.merge( attributes.namespaces )
  return namespaces
end

#next_element

Returns the next sibling that is an element, or nil if there is no Element sibling after this one

doc = Document.new '<a><b/>text<c/></a>'
doc.root.elements['b'].next_element          #-> <c/>
doc.root.elements['c'].next_element          #-> nil
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 410

def next_element
  element = next_sibling
  element = element.next_sibling until element.nil? or element.kind_of? Element
  return element
end

#node_type

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 535

def node_type
  :element
end

#prefixes

Evaluates to an ::Array containing the prefixes (names) of all defined namespaces at this context node.

doc = Document.new("<a xmlns:x='1' xmlns:y='2'><b/><c xmlns:z='3'/></a>")
doc.elements['//b'].prefixes # -> ['x', 'y']
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 196

def prefixes
  prefixes = []
  prefixes = parent.prefixes if parent
  prefixes |= attributes.prefixes
  return prefixes
end

#previous_element

Returns the previous sibling that is an element, or nil if there is no Element sibling prior to this one

doc = Document.new '<a><b/>text<c/></a>'
doc.root.elements['c'].previous_element          #-> <b/>
doc.root.elements['b'].previous_element          #-> nil
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 421

def previous_element
  element = previous_sibling
  element = element.previous_sibling until element.nil? or element.kind_of? Element
  return element
end

#raw

Evaluates to true if raw mode is set for this element. This is the case if the context has :raw set to :all or an array containing the name of this element.

The evaluation is tested against expanded_name, and so is namespace sensitive.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 179

def raw
  @raw = (@context and @context[:raw] and
          (@context[:raw] == :all or
           @context[:raw].include? expanded_name))
           @raw
end

#root

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 124

def root
  return elements[1] if self.kind_of? Document
  return self if parent.kind_of? Document or parent.nil?
  return parent.root
end

#root_node

Evaluates to the root node of the document that this element belongs to. If this element doesn’t belong to a document, but does belong to another Element, the parent’s root will be returned, until the earliest ancestor is found.

Note that this is not the same as the document element. In the following example, <a> is the document element, and the root node is the parent node of the document element. You may ask yourself why the root node is useful: consider the doctype and XML declaration, and any processing instructions before the document element… they are children of the root node, or siblings of the document element. The only time this isn’t true is when an Element is created that is not part of any Document. In this case, the ancestor that has no parent acts as the root node.

d = Document.new '<a><b><c/></b></a>'
a = d[1] ; c = a[1][1]
d.root_node == d   # TRUE
a.root_node        # namely, d
c.root_node        # again, d
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 120

def root_node
  parent.nil? ? self : parent.root_node
end

#text(path = nil)

A convenience method which returns the String value of the first child text element, if one exists, and nil otherwise.

Note that an element may have multiple Text elements, perhaps separated by other children. Be aware that this method only returns the first Text node.

This method returns the value of the first text child node, which ignores the #raw setting, so always returns normalized text. See the Text#value documentation.

doc = Document.new "<p>some text <b>this is bold!</b> more text</p>"
# The element 'p' has two text elements, "some text " and " more text".
doc.root.text              #-> "some text "
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 451

def text( path = nil )
  rv = get_text(path)
  return rv.value unless rv.nil?
  nil
end

#text=(text)

Sets the first Text child of this object. See text() for a discussion about Text children.

If a Text child already exists, the child is replaced by this content. This means that Text content can be deleted by calling this method with a nil argument. In this case, the next Text child becomes the first Text child. In no case is the order of any siblings disturbed.

text

If a String, a new Text child is created and added to this Element as the first Text child. If Text, the text is set as the first Child element. If nil, then any existing first Text child is removed.

Returns

this Element.

doc = Document.new '<a><b/></a>'
doc.root.text = 'Sean'      #-> '<a><b/>Sean</a>'
doc.root.text = 'Elliott'   #-> '<a><b/>Elliott</a>'
doc.root.add_element 'c'    #-> '<a><b/>Elliott<c/></a>'
doc.root.text = 'Russell'   #-> '<a><b/>Russell<c/></a>'
doc.root.text = nil         #-> '<a><b/><c/></a>'
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 493

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

#texts

Get an array of all Text children. IMMUTABLE

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 686

def texts
  find_all { |child| child.kind_of? Text }.freeze
end

#whitespace

Evaluates to true if whitespace is respected for this element. This is the case if:

  1. Neither :respect_whitespace nor :compress_whitespace has any value

  2. The context has :respect_whitespace set to :all or an array containing the name of this element, and :compress_whitespace isn’t set to :all or an array containing the name of this element.

The evaluation is tested against expanded_name, and so is namespace sensitive.

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 146

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

#write(output = $stdout, indent = -1,, transitive = false, ie_hack = false)

DEPRECATED

See Formatters

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
[ GitHub ]

  
# File 'lib/rexml/element.rb', line 712

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

#xpath

[ GitHub ]

  
# File 'lib/rexml/element.rb', line 539

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