JezK
Edit File: element.rb
# frozen_string_literal: false require_relative "parent" require_relative "namespace" require_relative "attribute" require_relative "cdata" require_relative "xpath" require_relative "parseexception" module REXML # An implementation note about namespaces: # As we parse, when we find namespaces we put them in a hash and assign # them a unique ID. We then convert the namespace prefix for the node # to the unique ID. This makes namespace lookup much faster for the # cost of extra memory use. We save the namespace prefix for the # context node and convert it back when we write it. @@namespaces = {} # 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}[../doc/rexml/tasks/tocs/master_toc_rdoc.html], # and in particular, the # {tasks page for elements}[../doc/rexml/tasks/tocs/element_toc_rdoc.html]. # # === 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 (<tt>...</tt>). # # 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::Child # - REXML::Parent # # \REXML::Element itself and its ancestors also include modules: # # - {Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html] # - REXML::Namespace # - REXML::Node # - REXML::XMLTokens # # === Methods for Creating an \Element # # ::new:: Returns a new empty element. # #clone:: Returns a clone of another element. # # === Methods for Attributes # # {[attribute_name]}[#method-i-5B-5D]:: 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]}[#method-i-5B-5D]:: 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 <tt>:element</tt>. # # === 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. # class Element < Parent include Namespace UNDEFINED = "UNDEFINED"; # The default name # Mechanisms for accessing attributes and child elements of this # element. attr_reader :attributes, :elements # The context holds information about the processing environment, such as # whitespace handling. attr_accessor :context # :call-seq: # Element.new(name = 'UNDEFINED', parent = nil, context = nil) -> new_element # Element.new(element, parent = nil, context = nil) -> new_element # # Returns a new \REXML::Element object. # # When no arguments are given, # returns an element with name <tt>'UNDEFINED'</tt>: # # 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}[../doc/rexml/context_rdoc.html]: # # e = REXML::Element.new('foo', nil, {raw: :all}) # e.context # => {:raw=>:all} # 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 # :call-seq: # inspect -> string # # 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 (<tt>...</tt>), 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'> ... </>" # 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 # :call-seq: # clone -> new_element # # 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'/> # def clone self.class.new self end # :call-seq: # root_node -> document or element # # 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 # # Related: #root, #document. # def root_node parent.nil? ? self : parent.root_node end # :call-seq: # root -> element # # 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 # # Related: #root_node, #document. # def root return elements[1] if self.kind_of? Document return self if parent.kind_of? Document or parent.nil? return parent.root end # :call-seq: # document -> document or nil # # 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 # # Related: #root, #root_node. # def document rt = root rt.parent if rt end # :call-seq: # whitespace # # Returns +true+ if whitespace is respected for this element, # +false+ otherwise. # # See {Element Context}[../doc/rexml/context_rdoc.html]. # # The evaluation is tested against the element's +expanded_name+, # and so is namespace-sensitive. 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 # :call-seq: # ignore_whitespace_nodes # # Returns +true+ if whitespace nodes are ignored for the element. # # See {Element Context}[../doc/rexml/context_rdoc.html]. # 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 # :call-seq: # raw # # Returns +true+ if raw mode is set for the element. # # See {Element Context}[../doc/rexml/context_rdoc.html]. # # The evaluation is tested against +expanded_name+, and so is namespace # sensitive. def raw @raw = (@context and @context[:raw] and (@context[:raw] == :all or @context[:raw].include? expanded_name)) @raw end #once :whitespace, :raw, :ignore_whitespace_nodes ################################################# # Namespaces # ################################################# # :call-seq: # prefixes -> array_of_namespace_prefixes # # 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"] # def prefixes prefixes = [] prefixes = parent.prefixes if parent prefixes |= attributes.prefixes return prefixes end # :call-seq: # namespaces -> array_of_namespace_names # # 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"} # def namespaces namespaces = {} namespaces = parent.namespaces if parent namespaces = namespaces.merge( attributes.namespaces ) return namespaces end # :call-seq: # namespace(prefix = nil) -> string_uri or nil # # 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 # 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 # :call-seq: # add_namespace(prefix, uri = nil) -> self # # 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"} # def add_namespace( prefix, uri=nil ) unless uri @attributes["xmlns"] = prefix else prefix = "xmlns:#{prefix}" unless prefix =~ /^xmlns:/ @attributes[ prefix ] = uri end self end # :call-seq: # delete_namespace(namespace = 'xmlns') -> self # # 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/>" # def delete_namespace namespace="xmlns" namespace = "xmlns:#{namespace}" unless namespace == 'xmlns' attribute = attributes.get_attribute(namespace) attribute.remove unless attribute.nil? self end ################################################# # Elements # ################################################# # :call-seq: # add_element(name, attributes = nil) -> new_element # add_element(element, attributes = nil) -> element # # 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'/> # 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 # :call-seq: # delete_element(index) -> removed_element or nil # delete_element(element) -> removed_element or nil # delete_element(xpath) -> removed_element or nil # # 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 # def delete_element element @elements.delete element end # :call-seq: # has_elements? # # 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 # def has_elements? !@elements.empty? end # :call-seq: # each_element_with_attribute(attr_name, value = nil, max = 0, xpath = nil) {|e| ... } # # 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'/> # 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 # :call-seq: # each_element_with_text(text = nil, max = 0, xpath = nil) {|e| ... } # # 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> ... </> # 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 # :call-seq: # each_element {|e| ... } # # 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/> # def each_element( xpath=nil, &block ) # :yields: Element @elements.each( xpath, &block ) end # :call-seq: # get_elements(xpath) # # 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'/>] # def get_elements( xpath ) @elements.to_a( xpath ) end # :call-seq: # next_element # # 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 # def next_element element = next_sibling element = element.next_sibling until element.nil? or element.kind_of? Element return element end # :call-seq: # previous_element # # 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 # def previous_element element = previous_sibling element = element.previous_sibling until element.nil? or element.kind_of? Element return element end ################################################# # Text # ################################################# # :call-seq: # has_text? -> true or false # # 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 # def has_text? not text().nil? end # :call-seq: # text(xpath = nil) -> text_string or nil # # 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 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. # def text( path = nil ) rv = get_text(path) return rv.value unless rv.nil? nil end # :call-seq: # get_text(xpath = nil) -> text_node or nil # # 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!" # 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 # :call-seq: # text = string -> string # text = nil -> nil # # 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>' # 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 # :call-seq: # add_text(string) -> nil # add_text(text_node) -> self # # 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"] # 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 # :call-seq: # node_type -> :element # # Returns symbol <tt>:element</tt>: # # d = REXML::Document.new('<a/>') # a = d.root # => <a/> # a.node_type # => :element # def node_type :element end # :call-seq: # xpath -> string_xpath # # 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" # 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 ################################################# # Attributes # ################################################# # :call-seq: # [index] -> object # [attr_name] -> attr_value # [attr_sym] -> attr_value # # 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 <tt>[attr_sym.to_s]</tt>: # # root[:attr] # => "value" # root[:nosuch] # => nil # 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 # :call-seq: # attribute(name, namespace = nil) # # 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' # 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 # :call-seq: # has_attributes? -> true or false # # 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 # def has_attributes? return !@attributes.empty? end # :call-seq: # add_attribute(name, value) -> value # add_attribute(attribute) -> attribute # # 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" # def add_attribute( key, value=nil ) if key.kind_of? Attribute @attributes << key else @attributes[key] = value end end # :call-seq: # add_attributes(hash) -> hash # add_attributes(array) # # 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) # 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 # :call-seq: # delete_attribute(name) -> removed_attribute or nil # # 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 # def delete_attribute(key) attr = @attributes.get_attribute(key) attr.remove unless attr.nil? end ################################################# # Other Utilities # ################################################# # :call-seq: # cdatas -> array_of_cdata_children # # 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] # def cdatas find_all { |child| child.kind_of? CData }.freeze end # :call-seq: # comments -> array_of_comment_children # # 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"] # def comments find_all { |child| child.kind_of? Comment }.freeze end # :call-seq: # instructions -> array_of_instruction_children # # 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?>"] # def instructions find_all { |child| child.kind_of? Instruction }.freeze end # :call-seq: # texts -> array_of_text_children # # 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"] # def texts find_all { |child| child.kind_of? Text }.freeze end # == DEPRECATED # See REXML::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 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 private 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 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 end ######################################################################## # ELEMENTS # ######################################################################## # A class which provides filtering of children for Elements, and # XPath search support. You are expected to only encounter this class as # the <tt>element.elements</tt> object. Therefore, you are # _not_ expected to instantiate this yourself. # # xml_string = <<-EOT # <?xml version="1.0" encoding="UTF-8"?> # <bookstore> # <book category="cooking"> # <title lang="en">Everyday Italian</title> # <author>Giada De Laurentiis</author> # <year>2005</year> # <price>30.00</price> # </book> # <book category="children"> # <title lang="en">Harry Potter</title> # <author>J K. Rowling</author> # <year>2005</year> # <price>29.99</price> # </book> # <book category="web"> # <title lang="en">XQuery Kick Start</title> # <author>James McGovern</author> # <author>Per Bothner</author> # <author>Kurt Cagle</author> # <author>James Linn</author> # <author>Vaidyanathan Nagarajan</author> # <year>2003</year> # <price>49.99</price> # </book> # <book category="web" cover="paperback"> # <title lang="en">Learning XML</title> # <author>Erik T. Ray</author> # <year>2003</year> # <price>39.95</price> # </book> # </bookstore> # EOT # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements # => #<REXML::Elements @element=<bookstore> ... </>> # class Elements include Enumerable # :call-seq: # new(parent) -> new_elements_object # # Returns a new \Elements object with the given +parent+. # Does _not_ assign <tt>parent.elements = self</tt>: # # d = REXML::Document.new(xml_string) # eles = REXML::Elements.new(d.root) # eles # => #<REXML::Elements @element=<bookstore> ... </>> # eles == d.root.elements # => false # def initialize parent @element = parent end # :call-seq: # parent # # Returns the parent element cited in creating the \Elements object. # This element is also the default starting point for searching # in the \Elements object. # # d = REXML::Document.new(xml_string) # elements = REXML::Elements.new(d.root) # elements.parent == d.root # => true # def parent @element end # :call-seq: # elements[index] -> element or nil # elements[xpath] -> element or nil # elements[n, name] -> element or nil # # Returns the first \Element object selected by the arguments, # if any found, or +nil+ if none found. # # Notes: # - The +index+ is 1-based, not 0-based, so that: # - The first element has index <tt>1</tt> # - The _nth_ element has index +n+. # - The selection ignores non-\Element nodes. # # When the single argument +index+ is given, # returns the element given by the index, if any; otherwise, +nil+: # # d = REXML::Document.new(xml_string) # eles = d.root.elements # eles # => #<REXML::Elements @element=<bookstore> ... </>> # eles[1] # => <book category='cooking'> ... </> # eles.size # => 4 # eles[4] # => <book category='web' cover='paperback'> ... </> # eles[5] # => nil # # The node at this index is not an \Element, and so is not returned: # # eles = d.root.first.first # => <title lang='en'> ... </> # eles.to_a # => ["Everyday Italian"] # eles[1] # => nil # # When the single argument +xpath+ is given, # returns the first element found via that +xpath+, if any; otherwise, +nil+: # # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> # eles['/bookstore'] # => <bookstore> ... </> # eles['//book'] # => <book category='cooking'> ... </> # eles['//book [@category="children"]'] # => <book category='children'> ... </> # eles['/nosuch'] # => nil # eles['//nosuch'] # => nil # eles['//book [@category="nosuch"]'] # => nil # eles['.'] # => <bookstore> ... </> # eles['..'].class # => REXML::Document # # With arguments +n+ and +name+ given, # returns the _nth_ found element that has the given +name+, # or +nil+ if there is no such _nth_ element: # # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> # eles[1, 'book'] # => <book category='cooking'> ... </> # eles[4, 'book'] # => <book category='web' cover='paperback'> ... </> # eles[5, 'book'] # => nil # def []( index, name=nil) if index.kind_of? Integer raise "index (#{index}) must be >= 1" if index < 1 name = literalize(name) if name num = 0 @element.find { |child| child.kind_of? Element and (name.nil? ? true : child.has_name?( name )) and (num += 1) == index } else return XPath::first( @element, index ) #{ |element| # return element if element.kind_of? Element #} #return nil end end # :call-seq: # elements[] = index, replacement_element -> replacement_element or nil # # Replaces or adds an element. # # When <tt>eles[index]</tt> exists, replaces it with +replacement_element+ # and returns +replacement_element+: # # d = REXML::Document.new(xml_string) # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> # eles[1] # => <book category='cooking'> ... </> # eles[1] = REXML::Element.new('foo') # eles[1] # => <foo/> # # Does nothing (or raises an exception) # if +replacement_element+ is not an \Element: # eles[2] # => <book category='web' cover='paperback'> ... </> # eles[2] = REXML::Text.new('bar') # eles[2] # => <book category='web' cover='paperback'> ... </> # # When <tt>eles[index]</tt> does not exist, # adds +replacement_element+ to the element and returns # # d = REXML::Document.new(xml_string) # eles = d.root.elements # => #<REXML::Elements @element=<bookstore> ... </>> # eles.size # => 4 # eles[50] = REXML::Element.new('foo') # => <foo/> # eles.size # => 5 # eles[5] # => <foo/> # # Does nothing (or raises an exception) # if +replacement_element+ is not an \Element: # # eles[50] = REXML::Text.new('bar') # => "bar" # eles.size # => 5 # def []=( index, element ) previous = self[index] if previous.nil? @element.add element else previous.replace_with element end return previous end # :call-seq: # empty? -> true or false # # Returns +true+ if there are no children, +false+ otherwise. # # d = REXML::Document.new('') # d.elements.empty? # => true # d = REXML::Document.new(xml_string) # d.elements.empty? # => false # def empty? @element.find{ |child| child.kind_of? Element}.nil? end # :call-seq: # index(element) # # Returns the 1-based index of the given +element+, if found; # otherwise, returns -1: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # ele_1, ele_2, ele_3, ele_4 = *elements # elements.index(ele_4) # => 4 # elements.delete(ele_3) # elements.index(ele_4) # => 3 # elements.index(ele_3) # => -1 # def index element rv = 0 found = @element.find do |child| child.kind_of? Element and (rv += 1) and child == element end return rv if found == element return -1 end # :call-seq: # delete(index) -> removed_element or nil # delete(element) -> removed_element or nil # delete(xpath) -> removed_element or nil # # Removes an element; returns the removed element, or +nil+ if none removed. # # With integer argument +index+ given, # removes the child element at that offset: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.size # => 4 # elements[2] # => <book category='children'> ... </> # elements.delete(2) # => <book category='children'> ... </> # elements.size # => 3 # elements[2] # => <book category='web'> ... </> # elements.delete(50) # => nil # # With element argument +element+ given, # removes that child element: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # ele_1, ele_2, ele_3, ele_4 = *elements # elements.size # => 4 # elements[2] # => <book category='children'> ... </> # elements.delete(ele_2) # => <book category='children'> ... </> # elements.size # => 3 # elements[2] # => <book category='web'> ... </> # elements.delete(ele_2) # => nil # # With string argument +xpath+ given, # removes the first element found via that xpath: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.delete('//book') # => <book category='cooking'> ... </> # elements.delete('//book [@category="children"]') # => <book category='children'> ... </> # elements.delete('//nosuch') # => nil # def delete element if element.kind_of? Element @element.delete element else el = self[element] el.remove if el end end # :call-seq: # delete_all(xpath) # # Removes all elements found via the given +xpath+; # returns the array of removed elements, if any, else +nil+. # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.size # => 4 # deleted_elements = elements.delete_all('//book [@category="web"]') # deleted_elements.size # => 2 # elements.size # => 2 # deleted_elements = elements.delete_all('//book') # deleted_elements.size # => 2 # elements.size # => 0 # elements.delete_all('//book') # => [] # def delete_all( xpath ) rv = [] XPath::each( @element, xpath) {|element| rv << element if element.kind_of? Element } rv.each do |element| @element.delete element element.remove end return rv end # :call-seq: # add -> new_element # add(name) -> new_element # add(element) -> element # # Adds an element; returns the element added. # # With no argument, creates and adds a new element. # The new element has: # # - No name. # - \Parent from the \Elements object. # - Context from the that parent. # # Example: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # parent = elements.parent # => <bookstore> ... </> # parent.context = {raw: :all} # elements.size # => 4 # new_element = elements.add # => </> # elements.size # => 5 # new_element.name # => nil # new_element.parent # => <bookstore> ... </> # new_element.context # => {:raw=>:all} # # With string argument +name+, creates and adds a new element. # The new element has: # # - Name +name+. # - \Parent from the \Elements object. # - Context from the that parent. # # Example: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # parent = elements.parent # => <bookstore> ... </> # parent.context = {raw: :all} # elements.size # => 4 # new_element = elements.add('foo') # => <foo/> # elements.size # => 5 # new_element.name # => "foo" # new_element.parent # => <bookstore> ... </> # new_element.context # => {:raw=>:all} # # With argument +element+, # creates and adds a clone of the given +element+. # The new element has name, parent, and context from the given +element+. # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.size # => 4 # e0 = REXML::Element.new('foo') # e1 = REXML::Element.new('bar', e0, {raw: :all}) # element = elements.add(e1) # => <bar/> # elements.size # => 5 # element.name # => "bar" # element.parent # => <bookstore> ... </> # element.context # => {:raw=>:all} # def add element=nil if element.nil? Element.new("", self, @element.context) elsif not element.kind_of?(Element) Element.new(element, self, @element.context) else @element << element element.context = @element.context element end end alias :<< :add # :call-seq: # each(xpath = nil) {|element| ... } -> self # # Iterates over the elements. # # With no argument, calls the block with each element: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.each {|element| p element } # # Output: # # <book category='cooking'> ... </> # <book category='children'> ... </> # <book category='web'> ... </> # <book category='web' cover='paperback'> ... </> # # With argument +xpath+, calls the block with each element # that matches the given +xpath+: # # elements.each('//book [@category="web"]') {|element| p element } # # Output: # # <book category='web'> ... </> # <book category='web' cover='paperback'> ... </> # def each( xpath=nil ) XPath::each( @element, xpath ) {|e| yield e if e.kind_of? Element } end # :call-seq: # collect(xpath = nil) {|element| ... } -> array # # Iterates over the elements; returns the array of block return values. # # With no argument, iterates over all elements: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.collect {|element| element.size } # => [9, 9, 17, 9] # # With argument +xpath+, iterates over elements that match # the given +xpath+: # # xpath = '//book [@category="web"]' # elements.collect(xpath) {|element| element.size } # => [17, 9] # def collect( xpath=nil ) collection = [] XPath::each( @element, xpath ) {|e| collection << yield(e) if e.kind_of?(Element) } collection end # :call-seq: # inject(xpath = nil, initial = nil) -> object # # Calls the block with elements; returns the last block return value. # # With no argument, iterates over the elements, calling the block # <tt>elements.size - 1</tt> times. # # - The first call passes the first and second elements. # - The second call passes the first block return value and the third element. # - The third call passes the second block return value and the fourth element. # - And so on. # # In this example, the block returns the passed element, # which is then the object argument to the next call: # # d = REXML::Document.new(xml_string) # elements = d.root.elements # elements.inject do |object, element| # p [elements.index(object), elements.index(element)] # element # end # # Output: # # [1, 2] # [2, 3] # [3, 4] # # With the single argument +xpath+, calls the block only with # elements matching that xpath: # # elements.inject('//book [@category="web"]') do |object, element| # p [elements.index(object), elements.index(element)] # element # end # # Output: # # [3, 4] # # With argument +xpath+ given as +nil+ # and argument +initial+ also given, # calls the block once for each element. # # - The first call passes the +initial+ and the first element. # - The second call passes the first block return value and the second element. # - The third call passes the second block return value and the third element. # - And so on. # # In this example, the first object index is <tt>-1</tt> # # elements.inject(nil, 'Initial') do |object, element| # p [elements.index(object), elements.index(element)] # element # end # # Output: # # [-1, 1] # [1, 2] # [2, 3] # [3, 4] # # In this form the passed object can be used as an accumulator: # # elements.inject(nil, 0) do |total, element| # total += element.size # end # => 44 # # With both arguments +xpath+ and +initial+ are given, # calls the block only with elements matching that xpath: # # elements.inject('//book [@category="web"]', 0) do |total, element| # total += element.size # end # => 26 # def inject( xpath=nil, initial=nil ) first = true XPath::each( @element, xpath ) {|e| if (e.kind_of? Element) if (first and initial == nil) initial = e first = false else initial = yield( initial, e ) if e.kind_of? Element end end } initial end # :call-seq: # size -> integer # # Returns the count of \Element children: # # d = REXML::Document.new '<a>sean<b/>elliott<b/>russell<b/></a>' # d.root.elements.size # => 3 # Three elements. # d.root.size # => 6 # Three elements plus three text nodes.. # def size count = 0 @element.each {|child| count+=1 if child.kind_of? Element } count end # :call-seq: # to_a(xpath = nil) -> array_of_elements # # Returns an array of element children (not including non-element children). # # With no argument, returns an array of all element children: # # d = REXML::Document.new '<a>sean<b/>elliott<c/></a>' # elements = d.root.elements # elements.to_a # => [<b/>, <c/>] # Omits non-element children. # children = d.root.children # children # => ["sean", <b/>, "elliott", <c/>] # Includes non-element children. # # With argument +xpath+, returns an array of element children # that match the xpath: # # elements.to_a('//c') # => [<c/>] # def to_a( xpath=nil ) rv = XPath.match( @element, xpath ) return rv.find_all{|e| e.kind_of? Element} if xpath rv end private # Private helper class. Removes quotes from quoted strings def literalize name name = name[1..-2] if name[0] == ?' or name[0] == ?" #' name end end ######################################################################## # ATTRIBUTES # ######################################################################## # A class that defines the set of Attributes of an Element and provides # operations for accessing elements in that set. class Attributes < Hash # :call-seq: # new(element) # # Creates and returns a new \REXML::Attributes object. # The element given by argument +element+ is stored, # but its own attributes are not modified: # # ele = REXML::Element.new('foo') # attrs = REXML::Attributes.new(ele) # attrs.object_id == ele.attributes.object_id # => false # # Other instance methods in class \REXML::Attributes may refer to: # # - +element.document+. # - +element.prefix+. # - +element.expanded_name+. # def initialize element @element = element end # :call-seq: # [name] -> attribute_value or nil # # Returns the value for the attribute given by +name+, # if it exists; otherwise +nil+. # The value returned is the unnormalized attribute value, # with entities expanded: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # ele.attributes['att'] # => "<" # ele.attributes['bar:att'] # => "2" # ele.attributes['nosuch'] # => nil # # Related: get_attribute (returns an \Attribute object). # def [](name) attr = get_attribute(name) return attr.value unless attr.nil? return nil end # :call-seq: # to_a -> array_of_attribute_objects # # Returns an array of \REXML::Attribute objects representing # the attributes: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes.to_a # => [foo:att='1', bar:att='2', att='<'] # attrs.first.class # => REXML::Attribute # def to_a enum_for(:each_attribute).to_a end # :call-seq: # length # # Returns the count of attributes: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # ele.attributes.length # => 3 # def length c = 0 each_attribute { c+=1 } c end alias :size :length # :call-seq: # each_attribute {|attr| ... } # # Calls the given block with each \REXML::Attribute object: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # ele.attributes.each_attribute do |attr| # p [attr.class, attr] # end # # Output: # # [REXML::Attribute, foo:att='1'] # [REXML::Attribute, bar:att='2'] # [REXML::Attribute, att='<'] # def each_attribute # :yields: attribute return to_enum(__method__) unless block_given? each_value do |val| if val.kind_of? Attribute yield val else val.each_value { |atr| yield atr } end end end # :call-seq: # each {|expanded_name, value| ... } # # Calls the given block with each expanded-name/value pair: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # ele.attributes.each do |expanded_name, value| # p [expanded_name, value] # end # # Output: # # ["foo:att", "1"] # ["bar:att", "2"] # ["att", "<"] # def each return to_enum(__method__) unless block_given? each_attribute do |attr| yield [attr.expanded_name, attr.value] end end # :call-seq: # get_attribute(name) -> attribute_object or nil # # Returns the \REXML::Attribute object for the given +name+: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs.get_attribute('foo:att') # => foo:att='1' # attrs.get_attribute('foo:att').class # => REXML::Attribute # attrs.get_attribute('bar:att') # => bar:att='2' # attrs.get_attribute('att') # => att='<' # attrs.get_attribute('nosuch') # => nil # def get_attribute( name ) attr = fetch( name, nil ) if attr.nil? return nil if name.nil? # Look for prefix name =~ Namespace::NAMESPLIT prefix, n = $1, $2 if prefix attr = fetch( n, nil ) # check prefix if attr == nil elsif attr.kind_of? Attribute return attr if prefix == attr.prefix else attr = attr[ prefix ] return attr end end element_document = @element.document if element_document and element_document.doctype expn = @element.expanded_name expn = element_document.doctype.name if expn.size == 0 attr_val = element_document.doctype.attribute_of(expn, name) return Attribute.new( name, attr_val ) if attr_val end return nil end if attr.kind_of? Hash attr = attr[ @element.prefix ] end return attr end # :call-seq: # [name] = value -> value # # When +value+ is non-+nil+, # assigns that to the attribute for the given +name+, # overwriting the previous value if it exists: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs['foo:att'] = '2' # => "2" # attrs['baz:att'] = '3' # => "3" # # When +value+ is +nil+, deletes the attribute if it exists: # # attrs['baz:att'] = nil # attrs.include?('baz:att') # => false # def []=( name, value ) if value.nil? # Delete the named attribute attr = get_attribute(name) delete attr return end unless value.kind_of? Attribute if @element.document and @element.document.doctype value = Text::normalize( value, @element.document.doctype ) else value = Text::normalize( value, nil ) end value = Attribute.new(name, value) end value.element = @element old_attr = fetch(value.name, nil) if old_attr.nil? store(value.name, value) elsif old_attr.kind_of? Hash old_attr[value.prefix] = value elsif old_attr.prefix != value.prefix # Check for conflicting namespaces if value.prefix != "xmlns" and old_attr.prefix != "xmlns" old_namespace = old_attr.namespace new_namespace = value.namespace if old_namespace == new_namespace raise ParseException.new( "Namespace conflict in adding attribute \"#{value.name}\": "+ "Prefix \"#{old_attr.prefix}\" = \"#{old_namespace}\" and "+ "prefix \"#{value.prefix}\" = \"#{new_namespace}\"") end end store value.name, {old_attr.prefix => old_attr, value.prefix => value} else store value.name, value end return @element end # :call-seq: # prefixes -> array_of_prefix_strings # # Returns an array of prefix strings in the attributes. # The array does not include the default # namespace declaration, if one exists. # # xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>' # d = REXML::Document.new(xml_string) # d.root.attributes.prefixes # => ["x", "y"] # def prefixes ns = [] each_attribute do |attribute| ns << attribute.name if attribute.prefix == 'xmlns' end if @element.document and @element.document.doctype expn = @element.expanded_name expn = @element.document.doctype.name if expn.size == 0 @element.document.doctype.attributes_of(expn).each { |attribute| ns << attribute.name if attribute.prefix == 'xmlns' } end ns end # :call-seq: # namespaces # # Returns a hash of name/value pairs for the namespaces: # # xml_string = '<a xmlns="foo" xmlns:x="bar" xmlns:y="twee" z="glorp"/>' # d = REXML::Document.new(xml_string) # d.root.attributes.namespaces # => {"xmlns"=>"foo", "x"=>"bar", "y"=>"twee"} # def namespaces namespaces = {} each_attribute do |attribute| namespaces[attribute.name] = attribute.value if attribute.prefix == 'xmlns' or attribute.name == 'xmlns' end if @element.document and @element.document.doctype expn = @element.expanded_name expn = @element.document.doctype.name if expn.size == 0 @element.document.doctype.attributes_of(expn).each { |attribute| namespaces[attribute.name] = attribute.value if attribute.prefix == 'xmlns' or attribute.name == 'xmlns' } end namespaces end # :call-seq: # delete(name) -> element # delete(attribute) -> element # # Removes a specified attribute if it exists; # returns the attributes' element. # # When string argument +name+ is given, # removes the attribute of that name if it exists: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs.delete('foo:att') # => <ele bar:att='2' att='<'/> # attrs.delete('foo:att') # => <ele bar:att='2' att='<'/> # # When attribute argument +attribute+ is given, # removes that attribute if it exists: # # attr = REXML::Attribute.new('bar:att', '2') # attrs.delete(attr) # => <ele att='<'/> # => <ele att='<'/> # attrs.delete(attr) # => <ele att='<'/> # => <ele/> # def delete( attribute ) name = nil prefix = nil if attribute.kind_of? Attribute name = attribute.name prefix = attribute.prefix else attribute =~ Namespace::NAMESPLIT prefix, name = $1, $2 prefix = '' unless prefix end old = fetch(name, nil) if old.kind_of? Hash # the supplied attribute is one of many old.delete(prefix) if old.size == 1 repl = nil old.each_value{|v| repl = v} store name, repl end elsif old.nil? return @element else # the supplied attribute is a top-level one super(name) end @element end # :call-seq: # add(attribute) -> attribute # # Adds attribute +attribute+, replacing the previous # attribute of the same name if it exists; # returns +attribute+: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs # => {"att"=>{"foo"=>foo:att='1', "bar"=>bar:att='2', ""=>att='<'}} # attrs.add(REXML::Attribute.new('foo:att', '2')) # => foo:att='2' # attrs.add(REXML::Attribute.new('baz', '3')) # => baz='3' # attrs.include?('baz') # => true # def add( attribute ) self[attribute.name] = attribute end alias :<< :add # :call-seq: # delete_all(name) -> array_of_removed_attributes # # Removes all attributes matching the given +name+; # returns an array of the removed attributes: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs.delete_all('att') # => [att='<'] # def delete_all( name ) rv = [] each_attribute { |attribute| rv << attribute if attribute.expanded_name == name } rv.each{ |attr| attr.remove } return rv end # :call-seq: # get_attribute_ns(namespace, name) # # Returns the \REXML::Attribute object among the attributes # that matches the given +namespace+ and +name+: # # xml_string = <<-EOT # <root xmlns:foo="http://foo" xmlns:bar="http://bar"> # <ele foo:att='1' bar:att='2' att='<'/> # </root> # EOT # d = REXML::Document.new(xml_string) # ele = d.root.elements['//ele'] # => <a foo:att='1' bar:att='2' att='<'/> # attrs = ele.attributes # attrs.get_attribute_ns('http://foo', 'att') # => foo:att='1' # attrs.get_attribute_ns('http://foo', 'nosuch') # => nil # def get_attribute_ns(namespace, name) result = nil each_attribute() { |attribute| if name == attribute.name && namespace == attribute.namespace() && ( !namespace.empty? || !attribute.fully_expanded_name.index(':') ) # foo will match xmlns:foo, but only if foo isn't also an attribute result = attribute if !result or !namespace.empty? or !attribute.fully_expanded_name.index(':') end } result end end end