Creates a new MiniXMLElement with name NAME. This element is an orphan (has no assigned parent) and will be lost unless it is appended (using MiniXMLElement::appendChild()) to an element at some point.

If the optional VALUE (string or numeric) parameter is passed, the new element's text/numeric content will be set using VALUE.

Searches the document for an element with name NAME.

MiniXMLElement with name NAME,
if found, NULL otherwise.

The search is performed like this, returning the first element that matches:

- Check the Root Element's immediate children (in order) for a match.
- Ask each immediate child (in order) to MiniXMLElement::getElement()
(each child will then proceed similarly, checking all it's immediate children in order and then asking them to getElement())

Attempts to find and return a reference to the (first) element at PATH where PATH is the path in the structure from the root element to the requested element.

For example, in the document represented by:

<partRateRequest>
 <vendor>
  <accessid user="myusername" password="mypassword"/>
 </vendor>
 <partList>
  <partNum>
   DA42
  </partNum>
  <partNum>
   D99983FFF
  </partNum>
  <partNum>
   ss-839uent
  </partNum>
 </partList>
</partRateRequest>

$accessid =& $xmlDocument->getElementByPath('partRateRequest/vendor/accessid');

Will return what you expect (the accessid element with attributes user = "myusername" and password = "mypassword") but see the Note below.

be careful:

In the example above,
$part =& $xmlDocument->getElementByPath('partRateRequest/partList/partNum');

will return the partNum element with the value "DA42". Other partNums are inaccessible by getElementByPath() as they all share the same path - Use MiniXMLElement::getAllChildren() on the partList parent instead.

Initialise the MiniXMLDoc (and its root MiniXMLElement object) based on the contents of ARRAY. See the oveview for an example. The ARRAY is interpreted as follows - for each KEY => VALUE pair in the array, an element with name KEY is created. If the associated VALUE is

• a string, the KEY element simply contains the string.
• an associative array (a hash ref in Perl), the KEY element contains child elements for each key/value pair within
• a "regular" array (one with unspecified keys defaulting to a continuous sequence of numbers begining with 0 - an array ref in Perl), a KEY element is created for each value in the array, it's contents determined by the type of value itself.

The OPTIONS array MAY be passed, in order to specify additional options, such as which KEYs to treat as attributes (instead of creating children elements)

The best way to understand this method is to check the examples in the MiniXML docs/ directory and to play with it while checking the output using toString(). This method is named fromHash() in the XML::Mini Perl implementation.

Initialise the MiniXMLDoc (and its root MiniXMLElement object) using the XML string XMLSTRING.

Initialise the MiniXMLDoc (and its root MiniXMLElement object) using the XML found in file XMLFILE.

If a NEWNAME string is passed, the MiniXMLElement's name is set to NEWNAME.

attribute NAME [SETTO [SETTOALT]]

The attribute method is used to get and set the MiniXMLElement's attributes (ie the name/value pairs contained within the tag, <tagname attrib1="value1" attrib2="value2">)

If the optional SETTO is passed, the attribute's value is set to SETTO.

If the optional SETTOALT is passed and SETTO is false, the attribute's value is set to SETTOALT. This is usefull in cases when you wish to set the attribute to a default value if no SETTO is present, eg
$myelement->attribute('href', $theHref, 'http://psychogenic.com')
will default to 'http://psychogenic.com'.

The text() method is used to get or append text data to this element (it is appended to the child list as a new MiniXMLNode object).

If SETTO is passed, a new node is created, filled with SETTO and appended to the list of this element's children.

If the optional SETTOALT is passed and SETTO is false, the new node's value is set to SETTOALT. See the attribute() method for an example use.

The numeric method is used to get or append numeric data to this element (it is appended to the child list as a MiniXMLNode object).

If SETTO is passed, a new node is created, filled with SETTO and appended to the list of this element's children.

If the optional SETTOALT is passed and SETTO is null, the new node's value is set to SETTOALT. See the attribute() method for an example use.

The comment() method allows you to add a new MiniXMLElement (actually, an instance of the derived MiniXMLCommentELement class) to this element's list of children.

Comments will return a <!-- CONTENTS --> string when their toString() method is called.

Returns a string containing the value of all the element's child MiniXMLNodes (and all the MiniXMLNodes contained within it's child MiniXMLElements, recursively).

For example the P element in:

<P> 
 Hello my
  <I>
  very
   <B>
    nice
   </B>
  </I>
 Friend
</P>

Will return "Hello my very nice Friend" when getValue() is called.

Searches the element and it's children for an element with name NAME.

The search is performed like this, returning the first element that matches:

• Check this element for a match
• Check this element's immediate children (in order) for a match.
• Ask each immediate child (in order) to MiniXMLElement::getElement() in turn (each child will then proceed similarly, checking all it's immediate children in order and then asking them to getElement() thus performing the search recursively all the way to the tree's leaf nodes.)

Attempts to find and return a reference to the (first) element at RELPATH where RELPATH is the relative path in the structure from this element to the requested element.

For example, in the document represented by:

<partRateRequest>
 <vendor>
  <accessid user="myusername" password="mypassword"/>
 </vendor>
 <partList>
  <partNum>
   DA42
  </partNum>
  <partNum>
   D99983FFF
  </partNum>
  <partNum>
   ss-839uent
  </partNum>
 </partList>
</partRateRequest>

$accessid =& $partRateRequest->getElementByPath('vendor/accessid');

Will return what you expect (the accessid element with attributes user = "myusername" and password = "mypassword") but see the Note below.

be careful:

In the example above,
$part =& $xmlDocument->getElementByPath('partRateRequest/partList/partNum');

will return the partNum element with the value "DA42". Other partNums are inaccessible by getElementByPath() as they all share the same path - Use MiniXMLElement::getAllChildren() on the partList parent instead.

Creates and returns a reference to an array of all this element's immediate MiniXMLElement children.

Creates a new MiniXMLElement instance and appends it to the list of this element's children. The new child element's name is set to ELEMENTNAME.

If the optional VALUE (string or numeric) parameter is passed, the new element's text/numeric content will be set using VALUE.

Don't forget to use the =& (reference assignment) operator
when calling createChild:

$newChild =& $myElement->createChild('newChildName');

prependChild is used to prepend an existing MiniXMLElement object to this element's list. The child is inserted in the first position of the element's list of children (it will be output first in the XML)

Be careful not to create loops in the hierarchy, eg

$parent->prependChild($child);
$child->prependChild($subChild);
$subChild->prependChild($parent);

If you want to be sure to avoid loops, set the MINIXML_AVOIDLOOPS define to 1 or use the avoidLoops() method (will apply to all children added with createChild())

appendChild is used to append an existing MiniXMLElement object to this element's list

Be careful not to create loops in the hierarchy, eg

$parent->appendChild($child);
$child->appendChild($subChild);
$subChild->appendChild($parent);

If you want to be sure to avoid loops, set the MINIXML_AVOIDLOOPS define to 1 or use the avoidLoops() method (will apply to all children added with createChild())

insertChild is used to insert an existing MiniXMLElement object to this element's list. The child is inserted in at the position INDEX within element's list of children

insertChild treats the list of child elements as an array - that means that the first position is at INDEX = 0 and the last position is numChildren() - 1.
In addition, if INDEX is greater than numChildren(), the element will be positioned at the end of the list (same effect as appendChild())

Removes child element CHILD from the list of this element's children. The method has no effect if CHILD is not found.

Removes all children assigned to this element.

The parent() method is used to get/set the element's parent.

If the NEWPARENT parameter is passed, sets the parent to NEWPARENT (NEWPARENT must be an instance of MiniXMLElement)

The avoidLoops() method is used to get or set the avoidLoops flag for this element.

When avoidLoops is true, children with parents already set can NOT be appended to any other elements. This is overkill but it is a quick and easy way to avoid infinite loops in the heirarchy.

If the optional SETTO is passed, avoidLoops is set to SETTO for this element.

toString returns an XML string based on the element's attributes and content (recursively doing the same for all children).

The optional SPACEOFFSET parameter sets the number of spaces to use after newlines for elements at this level (adding 1 space per level in depth). SPACEOFFSET defaults to 0.