/ 
XML-Mini-1.2.3
River stage one • 3 direct dependents • 3 total dependents
/ XML::Mini::Document

NAME

XML::Mini::Document - Perl implementation of the XML::Mini Document API.

SYNOPSIS

use XML::Mini::Document;

my $xmlDoc = XML::Mini::Document->new();

# init the doc from an XML string
$xmlDoc->fromString($XMLString);

# Fetch the ROOT element for the document
# (an instance of XML::Mini::Element)
my $xmlElement = $xmlDoc->getRoot();

# play with the element and its children
# ...

# output the document
print $xmlDoc->toString();

DESCRIPTION

The XML::Mini::Document class is the programmer's handle to XML::Mini functionality.

A XML::Mini::Document instance is created in every program that uses XML::Mini. With the XML::Mini::Document object, you can access the root XML::Mini::Element, find/fetch/create elements and read in or output XML strings.

new [XMLSTRING]

Creates a new instance of XML::Mini::Document, optionally calling fromString with the passed XMLSTRING

getRoot

Returns a reference the this document's root element (an instance of XML::Mini::Element)

setRoot NEWROOT

setRoot NEWROOT Set the document root to the NEWROOT XML::Mini::Element object.

isElement ELEMENT

Returns a true value if ELEMENT is an instance of XML::Mini::Element, false otherwise.

isNode NODE

Returns a true value if NODE is an instance of XML::MiniNode, false otherwise.

createElement NAME [VALUE]

Creates a new XML::Mini::Element with name NAME.

This element is an orphan (has no assigned parent) and will be lost unless it is appended (XML::Mini::Element::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. Returns a reference to the newly created element (use the =& operator)

getElement NAME

Searches the document for an element with name NAME.

Returns a reference to the first XML::Mini::Element with name NAME, if found, NULL otherwise.

NOTE: 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 XML::Mini::Element::getElement()
 (each child will then proceed similarly, checking all it's immediate
  children in order and then asking them to getElement())

getElementByPath PATH

Attempts to 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 be careful:

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

will return the partNum element with the value "DA42". Other partNums are inaccessible by getElementByPath() - Use XML::Mini::Element::getAllChildren() instead.

Returns the XML::Mini::Element reference if found, NULL otherwise.

fromString XMLSTRING

Initialise the XML::Mini::Document (and it's root XML::Mini::Element) using the XML string XMLSTRING.

Returns the number of immediate children the root XML::Mini::Element now has.

fromFile FILENAME

Initialise the XML::Mini::Document (and it's root XML::Mini::Element) using the XML from file FILNAME.

Returns the number of immediate children the root XML::Mini::Element now has.

toString [DEPTH]

Converts this XML::MiniDoc object to a string and returns it.

The optional DEPTH may be passed to set the space offset for the first element.

If the optional DEPTH is set to $XML::Mini::NoWhiteSpaces no \n or whitespaces will be inserted in the xml string (ie it will all be on a single line with no spaces between the tags.

Returns a string of XML representing the document.

toFile FILENAME [SAFE]

Stringify and save the XML document to file FILENAME

If SAFE flag is passed and is a true value, toFile will do some extra checking, refusing to open the file if the filename matches m|/\.\./| or m|#;`\*| or if FILENAME points to a softlink. In addition, if SAFE is 'NOOVERWRITE', toFile will fail if the FILENAME already exists.

getValue

Utility function, call the root XML::Mini::Element's getValue()

dump

Debugging aid, dump returns a nicely formatted dump of the current structure of the XML::MiniDoc object.

AUTHOR

LICENSE

XML::Mini::Document module, part of the XML::Mini XML parser/generator package.
Copyright (C) 2002 Patrick Deegan
All rights reserved

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Official XML::Mini site: http://minixml.psychogenic.com

Contact page for author available at http://www.psychogenic.com/en/contact.shtml

SEE ALSO

XML::Mini, XML::Mini::Element

http://minixml.psychogenic.com