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

Constructor

• :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.

Parses a stream containing a single top-level element and possibly multiple children.

 s = Source.new( "<a>some text</a>" )
 l = Listener.new
 class << l
   def tag_start name, attributes
     p "NEW ELEMENT, NAME OF #{name}"
   end
 end
 Element::parse_stream s, l

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

Evaluates to the root element 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.

 d = Document.new '<a><b><c/></b></a>'
 a = d[1] ; c = a[1][1]
 d.root        # These all evaluate to the same Element,
 a.root        # namely, <a>
 c.root        #

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

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.

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.

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

 doc.elements['//b'].prefixes # -> ['x', 'y']

Evalutas 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.

 b = doc.elements['//b']
 b.namespace           # -> '1'
 b.namespace("y")      # -> '2'

Adds a namespace to this element.

Evaluates to: this Element

 a = Element.new("a")
 a.add_namespace("foo", "bar")  # shorthand for previous line
 a.add_namespace("twiddle")

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.root.delete_namespace
 doc.root.delete_namespace 'foo'
 puts doc     # -> <a/>

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

 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

Deletes a child element.

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

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

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

 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}

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

 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}

Synonym for Element.elements.each

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

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

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

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

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.

 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 "

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 "

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.

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

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

 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.

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

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

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

Add multiple attributes to this element.

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

Removes an 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/>

Get an array of all CData children. IMMUTABLE

Get an array of all Comment children. IMMUTABLE

Get an array of all Instruction children. IMMUTABLE

Get an array of all Text children. IMMUTABLE

Writes out this element, and recursively, all children.

 out = ''
 doc.write( out )     #-> doc is written to the string 'out'
 doc.write( $stdout ) #-> doc written to the console