<!DOCTYPE class>
<class name='Element' extends='Parent'>
   Represents a tagged XML element.  Elements are characterized by having children, attributes, and names, and can themselves be children.
  <include name='Namespace'>
    
  </include>
  <attribute name='attributes' type='reader'>
     Mechanisms for accessing attributes and child elements of this element.
  </attribute>
  <attribute name='elements' type='reader'>
     Mechanisms for accessing attributes and child elements of this element.
  </attribute>
  <method name='initialize'>
    <argument default='UNDEFINED' name='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. If a Source, the source will be scanned and parsed for an Element, and all child elements will be recursively parsed as well.
    </argument>
    <argument default='nil' name='parent'>
      if supplied, must be a Parent, and will be used as the parent of this object. 
    </argument>
     Constructor 
  </method>
  <method name='clone'/>
  <method name='root'>
    <return>
      the root 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.
    </return>
     
  </method>
  <method name='prefixes'>
    <return>
      an Array of all defined namespaces
    </return>
     
  </method>
  <method name='namespace'>
    <argument default='nil' name='prefix'/>
    <return>
      the URI for a namespace, or the empty string if no such  namespace is declared
    </return>
     
  </method>
  <method name='add_namespace'>
    <argument name='prefix'>
      the namespace.  If the second argument is not supplied, this should be the URI of the default namespace. 
    </argument>
    <argument default='nil' name='uri'/>
     Adds a namespace to this element 
  </method>
  <method name='delete_namespace'>
    <argument default='xmlns' name='namespace'/>
     NEEDS DOCUMENTATION
  </method>
  <method name='add_element'>
    <argument default='nil' name='element'>
      optional.  If Element, the element is added. Otherwise, a new Element is constructed with the argument (see Element.initialize). 
    </argument>
    <argument default='nil' name='attrs'>
      If supplied, must be a hash of String name,value  pairs, which will be used to set the attributes of the new Element. 
    </argument>
    <return>
      the Element that was added
    </return>
     Adds a child to this element, optionally setting attributes in the element. 
  </method>
  <method name='delete_element'>
    <argument name='element'>
      Must be an Element, String, or Integer.  If Element,  the element is removed.  If String, the element is found (via XPath)  and removed.  NOTE that this means that any parent can remove any descendant.  If Integer, the Element indexed by that number will be removed. 
    </argument>
    <return>
      the element that was removed.
    </return>
     Deletes a child element. 
  </method>
  <method name='has_elements'>
    <return>
      true if this element has at least one child Element
    </return>
     
  </method>
  <method name='each_element_with_attribute'>
    <argument name='key'>
      the name of the attribute to search for 
    </argument>
    <argument name='value'>
      the value of the attribute 
    </argument>
    <argument default='0' name='max'>
      (optional) causes this method to return after yielding for this number of matching children 
    </argument>
    <argument default='nil' name='name'>
      (optional) if supplied, this is an XPath that filters the children to check.
    </argument>
    <argument name='block'/>
     Iterates through the children, yielding for each Element that has a particular attribute set. 
  </method>
  <method name='each_element_with_text'>
    <argument name='text'/>
    <argument default='0' name='max'>
      (optional) causes this method to return after yielding for this number of matching children 
    </argument>
    <argument default='nil' name='name'>
      (optional) if supplied, this is an XPath that filters the children to check. 
    </argument>
    <argument name='block'/>
     Iterates through the children, yielding for each Element that has a particular text set. @see text
  </method>
  <method name='each_element'>
    <argument default='nil' name='xpath'/>
    <argument name='block'/>
     Synonym for elements.each
  </method>
  <method name='get_elements'>
    <argument name='xpath'>
      any XPath by which to search for elements in the tree
    </argument>
    <return>
      an array of Elements that match the supplied path 
    </return>
     This is a little slower than calling elements.each directly. 
  </method>
  <method name='next_element'>
     Returns the next sibling that is an element, or nil if there is no Element sibling after this one
  </method>
  <method name='previous_element'>
     Returns the previous sibling that is an element, or nil if there is no Element sibling prior to this one
  </method>
  <method name='has_text'>
    <return>
      true if this element has at least one Text child
    </return>
     
  </method>
  <method name='text'>
    <argument default='nil' name='path'/>
    <return>
      the String content of the first child text element  encountered.  
    </return>
     A convenience method which returns the first child text element. NOTE that an element may have multiple Text elements, perhaps separated by other children; consider: "&lt;p&gt;some text &lt;b&gt;this is bold!&lt;/b&gt; more text&lt;p&gt;" The element &lt;p&gt; has two text elements, "some text " and " more text". This method would return only the first, "some text ". 
  </method>
  <method name='get_text'>
    <argument default='nil' name='path'/>
    <return>
      the first Text child encountered.
    </return>
     This is the same method as text(), only this method returns the actual Text object, rather than the String content. 
  </method>
  <method name='text='>
    <argument name='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. 
    </argument>
    <return>
      self.  NOTE that contrary to most REXML methods, the replaced content is not returned.
    </return>
     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. 
  </method>
  <method name='add_text'>
    <argument name='text'>
      if a String, a new Text instance is created and added to the parent.  If Text, the object is added directly. 
    </argument>
    <return>
      self.  NOTE that contrary to most REXML methods, the object added to the parent is not returned.
    </return>
     A helper method to add a Text child.  Actual Text instances can be added with regular Parent methods, such as add() and &lt;&lt;() 
  </method>
  <method name='has_attributes'>
    <return>
      true if this element has any attributes set, false otherwise.
    </return>
     
  </method>
  <method name='add_attribute'>
    <argument 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. 
    </argument>
    <argument default='nil' name='value'>
      not required, and is ignored if the first argument is an Attribute.  Otherwise, this is a String, and is used as the value of the new Attribute. 
    </argument>
    <return>
      the Attribute added
    </return>
     Adds an attribute to this element, overwriting any existing attribute by the same name. 
  </method>
  <method name='delete_attribute'>
    <argument name='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. 
    </argument>
    <return>
      the attribute removed, or nil if this Element did not contain a matching attribute
    </return>
     Removes an attribute 
  </method>
  <method name='write'>
    <argument name='writer'>
      A String or IO (or any object supporting &lt;&lt;(String)) 
    </argument>
    <argument default='0' name='indent'>
      if supplied, must be an Integer, which is then used to determine the indentation of this element and its children.
    </argument>
     Writes out this element, and recursively, all children. 
  </method>
  <method name='Element'>
    <argument name='parse_stream source'/>
    <argument name='listener'/>
  </method>
  <method name='each_with_something'>
    <argument name='test'/>
    <argument default='0' name='max'/>
    <argument default='nil' name='name'/>
     A private helper method
  </method>
  <method name='parse'>
    <argument name='source'/>
  </method>
  <method name='parse_children'>
    <argument name='source'/>
     A private helper method
  </method>
  <method name='write_children'>
    <argument name='writer'/>
    <argument name='indent'/>
     A private helper method
  </method>
  <method name='parse_error'>
    <argument name='source'/>
    <argument default='nil' name='message'/>
  </method>
</class>