| Class | REXML::Element |
| In: |
|
| Parent: | Parent |
Methods
Included Modules
Constants
| UNDEFINED | = | "UNDEFINED"; |
Attributes
| attributes | [R] | 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 | [R] | Mechanisms for accessing attributes and child elements of this element. |
Public Class methods
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.
58: def initialize( arg = UNDEFINED, parent=nil, context=nil ) 59: super(parent) 60: 61: @elements = Elements.new(self) 62: @attributes = Attributes.new(self) 63: @context = context 64: 65: if arg.kind_of? String 66: self.name = arg 67: elsif arg.kind_of? Element 68: self.name = arg.expanded_name 69: arg.attributes.each_attribute{ |attribute| 70: @attributes << Attribute.new( attribute ) 71: } 72: @context = arg.context 73: end 74: end
Public Instance methods
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. |
| 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'/>
591: def add_attribute( key, value=nil ) 592: if key.kind_of? Attribute 593: @attributes << key 594: else 595: @attributes[key] = value 596: end 597: end
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"] ] )
603: def add_attributes hash 604: if hash.kind_of? Hash 605: hash.each_pair {|key, value| @attributes[key] = value } 606: elsif hash.kind_of? Array 607: hash.each { |value| @attributes[ value[0] ] = value[1] } 608: end 609: end
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
295: def add_element element, attrs=nil 296: raise "First argument must be either an element name, or an Element object" if element.nil? 297: el = @elements.add(element) 298: if attrs.kind_of? Hash 299: attrs.each do |key, value| 301: end 302: attrs.each do |key, value| 304: end 305: end 306: el 307: end
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("foo", "bar") # shorthand for previous line
a.add_namespace("twiddle")
250: def add_namespace( prefix, uri=nil ) 251: unless uri 253: else 255: @attributes[ prefix ] = uri 256: end 257: self 258: end
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.
528: def add_text( text ) 529: if text.kind_of? String 530: if @children[-1].kind_of? Text 531: @children[-1] << text 532: return 533: end 534: text = Text.new( text, whitespace(), nil, raw() ) 535: end 536: self << text unless text.nil? 537: return self 538: end
559: def attribute( name, namespace=nil ) 560: prefix = '' 561: if namespace 562: prefix = attributes.prefixes.each { |prefix| 563: return "#{prefix}:" if namespace( prefix ) == namespace 564: } || '' 565: end 566: attributes.get_attribute( "#{prefix}#{name}" ) 567: end
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/>"
96: def clone 97: Element.new self 98: end
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/>
624: def delete_attribute(key) 625: attr = @attributes.get_attribute(key) 626: attr.remove unless attr.nil? 627: end
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
320: def delete_element element 321: @elements.delete element 322: end
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/>
272: attribute = attributes.get_attribute(namespace) 273: attribute.remove unless attribute.nil? 274: self 275: end
Evaluates to the document to which this element belongs, or nil if this element doesn’t belong to a document.
131: def document 132: rt = root 133: rt.parent if rt 134: end
Synonym for Element.elements.each
397: def each_element( xpath=nil, &block ) # :yields: Element 398: @elements.each( xpath, &block ) 399: end
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}
355: def each_element_with_attribute( key, value=nil, max=0, name=nil, &block ) # :yields: Element 356: each_with_something( proc {|child| 357: if value.nil? 358: child.attributes[key] != nil 359: else 360: child.attributes[key]==value 361: end 362: }, max, name, &block ) 363: end
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 itterate 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}
386: def each_element_with_text( text=nil, max=0, name=nil, &block ) # :yields: Element 387: each_with_something( proc {|child| 388: if text.nil? 389: child.has_text? 390: else 391: child.text == text 392: end 393: }, max, name, &block ) 394: end
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 "
466: def get_text path = nil 467: rv = nil 468: if path 469: element = @elements[ path ] 470: rv = element.get_text unless element.nil? 471: else 472: rv = @children.find { |node| node.kind_of? Text } 473: end 474: return rv 475: end
Evaluates to true if this element has any attributes set, false otherwise.
571: def has_attributes? 572: return !@attributes.empty? 573: end
161: def ignore_whitespace_nodes 162: @ignore_whitespace_nodes = false 163: if @context 164: if @context[:ignore_whitespace_nodes] 165: @ignore_whitespace_nodes = 166: (@context[:ignore_whitespace_nodes] == :all or 167: @context[:ignore_whitespace_nodes].include? expanded_name) 168: end 169: end 170: end
76: def inspect 77: rv = "<#@expanded_name" 78: 79: @attributes.each_attribute do |attr| 80: rv << " " 81: attr.write( rv, 0 ) 82: end 83: 84: if children.size > 0 85: rv << "> ... </>" 86: else 87: rv << "/>" 88: end 89: end
Get an array of all Instruction children. IMMUTABLE
647: def instructions 648: find_all { |child| child.kind_of? Instruction }.freeze 649: end
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.
| 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 |
b = doc.elements['//b']
b.namespace # -> '1'
b.namespace("y") # -> '2'
222: def namespace(prefix=nil) 223: if prefix.nil? 224: prefix = prefix() 225: end 226: if prefix == '' 228: else 230: end 231: ns = attributes[ prefix ] 232: ns = parent.namespace(prefix) if ns.nil? and parent 234: return ns 235: end
202: def namespaces 203: namespaces = [] 204: namespaces = parent.namespaces if parent 205: namespaces |= attributes.namespaces 206: return namespaces 207: end
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
414: def next_element 415: element = next_sibling 416: element = element.next_sibling until element.nil? or element.kind_of? Element 417: return element 418: end
Evaluates to an Array containing the prefixes (names) of all defined namespaces at this context node.
doc.elements['//b'].prefixes # -> ['x', 'y']
195: def prefixes 196: prefixes = [] 197: prefixes = parent.prefixes if parent 198: prefixes |= attributes.prefixes 199: return prefixes 200: end
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
425: def previous_element 426: element = previous_sibling 427: element = element.previous_sibling until element.nil? or element.kind_of? Element 428: return element 429: end
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.
178: def raw 179: @raw = (@context and @context[:raw] and 180: (@context[:raw] == :all or 181: @context[:raw].include? expanded_name)) 182: @raw 183: end
123: def root 124: return elements[1] if self.kind_of? Document 125: return self if parent.kind_of? Document or parent.nil? 126: return parent.root 127: end
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
119: def root_node 120: parent.nil? ? self : parent.root_node 121: end
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 "
455: def text( path = nil ) 456: rv = get_text(path) 457: return rv.value unless rv.nil? 458: nil 459: end
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>'
497: def text=( text ) 498: if text.kind_of? String 499: text = Text.new( text, whitespace(), nil, raw() ) 500: elsif text and !text.kind_of? Text 501: text = Text.new( text.to_s, whitespace(), nil, raw() ) 502: end 503: 504: old_text = get_text 505: if text.nil? 506: old_text.remove unless old_text.nil? 507: else 508: if old_text.nil? 509: self << text 510: else 511: old_text.replace_with( text ) 512: end 513: end 514: return self 515: end
Evaluates to true if whitespace is respected for this element. This is the case if:
- Neither :respect_whitespace nor :compress_whitespace has any value
- 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.
145: def whitespace 146: @whitespace = nil 147: if @context 148: if @context[:respect_whitespace] 149: @whitespace = (@context[:respect_whitespace] == :all or 150: @context[:respect_whitespace].include? expanded_name) 151: end 152: @whitespace = false if (@context[:compress_whitespace] and 153: (@context[:compress_whitespace] == :all or 154: @context[:compress_whitespace].include? expanded_name) 155: ) 156: end 157: @whitespace = true unless @whitespace == false 158: @whitespace 159: end
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: | Internet Explorer is the worst piece of crap to have ever been written, with the possible exception of Windows itself. Since IE is unable to parse proper XML, we have to provide a hack to generate XML that IE’s limited abilities can handle. This hack inserts a space before the /> on empty tags. Defaults to false |
out = '' doc.write( out ) #-> doc is written to the string 'out' doc.write( $stdout ) #-> doc written to the console
679: def write(writer=$stdout, indent=-1, transitive=false, ie_hack=false) 680: #print "ID:#{indent}" 681: writer << "<#@expanded_name" 682: 683: @attributes.each_attribute do |attr| 684: writer << " " 685: attr.write( writer, indent ) 686: end unless @attributes.empty? 687: 688: if @children.empty? 689: if transitive and indent>-1 690: writer << "\n" 691: indent( writer, indent ) 692: elsif ie_hack 693: writer << " " 694: end 695: writer << "/" 696: else 697: if transitive and indent>-1 and !@children[0].kind_of? Text 698: writer << "\n" 699: indent writer, indent+1 700: end 701: writer << ">" 702: write_children( writer, indent, transitive, ie_hack ) 703: writer << "</#{expanded_name}" 704: end 705: if transitive and indent>-1 and !@children.empty? 706: writer << "\n" 707: indent -= 1 if next_sibling.nil? 708: indent(writer, indent) 709: end 710: writer << ">" 711: end