NAME
XML::TinyXML - Little and efficient Perl module to manage xml data.
SYNOPSIS
use XML::TinyXML;
# First create an XML Context
$xml = XML::TinyXML->new();
# and add a root node
$xml->addRootNode('nodelabel', 'somevalue', { attr1 => v1, attr2 => v2 });
# if you want to reuse a previously created node object ...
#
# ( you can create one calling :
# * %attrs = ( attr1 => v1, attr2 => v2 );
# * $node = XML::TinyXML::Node->new('nodelabel', param => 'somevalue', attrs => \%attrs);
# )
#
# the new XML Context can be created giving the root node directly to the constructor
$xml = XML::TinyXML->new($node);
######
# A better (and easier) option is also to let the context constructor create the rootnode for you:
$xml = XML::TinyXML->new('rootnode', param => 'somevalue', attrs => { attr1 => v1, attr2 => v2 });
# an empty root node can be created as well:
$xml = XML::TinyXML->new('rootnode');
# You can later obtain a reference to the node object using the getNode() method
$node = $xml->getNode('/rootnode');
# the leading '/' is optional ... since all paths will be considered absolute and
# first element is assumed to be always a root node
$node = $xml->getNode('rootnode');
# xpath-like predicates are also supported so you can also do something like
$node->addChildNode('child', 'value1');
$node->addChildNode('child', 'value2');
$child2 = $xml->getNode('/rootnode/child[2]');
# or even
$node->addChildNode('child', 'value3', { attr => 'val' });
# the 3rd 'child' has an attribute
$child3 = $xml->getNode('/rootnode/child[@attr='val']');
#### IMPORTANT NOTE: ####
# this is not xpath syntax. use XML::TinyXML::Selector::XPath
# if you want to use an xpath-compliant syntax
# see XML::TinyXML::Node documentation for further details on possible
# operations on a node reference
######## #########
########## hashref2xml and xml2hashref facilities ###########
######## #########
# An useful facility is loading/dumping of hashrefs from/to xml
# for ex:
$hashref = { some => 'thing', someother => 'thing' };
my $xml = XML::TinyXML->new($hashref, param => 'mystruct');
# or to load on an existing XML::TinyXML object
$xml->loadHash($hashref, 'mystruct');
# we can also create and dump to string all at once :
my $xmlstring = XML::TinyXML->new($hashref, param => 'mystruct')->dump;
# to reload the hashref back
my $hashref = $xml->toHash;DESCRIPTION
Since in some environments it could be desirable to avoid installing Expat, XmlParser and blahblahblah , needed by most XML-related perl modules. My main scope was to obtain a fast xml library usable from perl (so with the possibility to expose a powerful api) but without the need to install a lot of other modules (or even C libraries) to have it working.
The actual version of XML::TinyXML (0.18 when I'm writing this) implements an xpath selector and supports encodings (throgh iconv)
The OO Tree-based api allows to : - create a new document programmaticaly - import an existing document from a file - import an existing document by parsing a memory buffer - modify the loaded/created document programmatically - export the document to an xml file - bidirectional conversion between xml documents and perl hashrefs
There are other "no-dependencies" tiny xml implementations on CPAN. Notably : XML::Easy and XML::Tiny but both are still missing some key features which are actually implemented in this module which are required by the projects where I use it, (in particular : - an OO api to allow changing and re-exporting the xml document, - an easy-to-use bidirectional xml<->hashref conversion - encoding-conversion capabilities - xpath selectors - small memory footprint (well... it's always a perl module) ) The underlying xml implementation resides in txml.c and is imported in the perl context through XS. It uses a linkedlist implementation took out of freebsd kernel and is supposed to be fast enough to represent and access 'not-huge' xml trees. If at some stage there will be need for more preformance in accessing the xml data (especially when using the xpath selector) an hash-table based index could be built on top of the tree structure to speed-up access to inner parts of the tree when using paths.
An Event-based api is actually missing, but will be provided in future releases.
METHODS
new ($arg, %params)
Creates a new XML::TinyXML object.
$root can be any of : XML::TinyXML::Node XmlNodePtr HASHREF SCALAR
and if present will be used as first root node of the newly created xml document.
%params is an optional hash parameter used only if $arg is an HASHREF or a scalar
%params = ( param => * if $root is an hashref, this will be name of the root node (it will be passed as second argument to loadHash()) * if $root is a scalar, this will be the value of the root node. attrs => attributes of the 'contextually added' $root node encoding => output encoding to use (among iconv supported ones) );
addNodeAttribute ($node, $key, $value)
Adds an attribute to a specific $node
$node MUST be an XML::TinyXML::Node object.
$key is the name of the attribute $value is the value of the attribute
This method is just an accessor. See XML::TinyXML::Node::addAttributes() instead.
removeNodeAttribute ($node, $index)
Removes from $node the attribute at $index if present.
$node MUST be a XML::TinyXML::Node object.
This method is just an accessor. See XML::TinyXML::Node::removeAttribute() instead.
addRootNode ($name, $val, $attrs)
Adds a new root node. (This can be considered both as a new tree in the forest represented in the xml document or as a new branch in the xml tree represented by the document itself)
addChildNode ($parent, $name, $val, $attrs)
Adds a new child node. This method is exactly like addRootNode but first argument must be a valid XML::TinyXML::Node which will be the parent of the newly created node
dump ()
Returns a stringified version of the XML structure represented internally
loadFile ($path)
Load the xml structure from a file
loadHash ($hash, $root)
Load the xml structure from an hashref (AKA: convert an hashref to an xml document)
if $root is specified, it will be the entity name of the root node in the resulting xml document.
toHash ()
Dump the xml structure represented internally in the form of an hashref
loadBuffer ($buf)
Load the xml structure from a preloaded memory buffer
getNode ($path)
Get a node at a specific path.
$path must be of the form: '/rootnode/child1/child2/leafnod' and the leading '/' is optional (since all paths will be interpreted as absolute)
Returns an XML::TinyXML::Node object
getChildNode ($node, $index)
Get the child of $node at index $index.
Returns an XML::TinyXML::Node object
countChildren ()
Returns the number of $node's children
removeNode ($path)
Remove the node at specific $path , if present. See getNode() documentation for some notes on the $path format.
Returns XML_NOERR (0) if success, error code otherwise.
See Exportable constants for a list of possible error codes
getBranch ($index)
alias for getRootNode
getRootNode ($index)
Get the root node at $index.
Returns an XML::TinyXML::Node object if present, undef otherwise
removeBranch ($index)
Alias for removeRootNode
removeRootNode ($index)
Remove the rootnode (and all his children) at $index.
countRootNodes
Returns the number of root nodes within this context
rootNodes ()
Returns an array containing all rootnodes. In scalar context returns an arrayref.
getChildNodeByName ($node, $name)
Get the child of $node with name == $name.
Returns an XML::TinyXML::Node object if there is such a child, undef otherwise
save ($path)
Save the xml document represented internally into $path.
Returns XML_NOERR if success, a specific error code otherwise
EXPORT
None by default.
Exportable constants
XML_BADARGS
XML_GENERIC_ERR
XML_LINKLIST_ERR
XML_MEMORY_ERR
XML_NOERR
XML_OPEN_FILE_ERR
XML_PARSER_GENERIC_ERR
XML_UPDATE_ERR
XML_BAD_CHARS
XML_MROOT_ERR
XML_NODETYPE_SIMPLE
XML_NODETYPE_COMMENT
XML_NODETYPE_CDATAExportable C functions
TXml *XmlCreateContext()
void XmlDestroyContext(TXml *xml)
XmlNode *XmlCreateNode(char *name,char *val,XmlNode *parent);
char *XmlGetNodeValue(XmlNode *node);
XmlErr XmlSetNodeValue(XmlNode *node,char *val);
void XmlDestroyNode(XmlNode *node);
int XmlAddAttribute(XmlNode *node, char *name, char *val)
int XmlAddRootNode(TXml *xml, XmlNode *node)
int XmlRemoveNode(TXml *xml,char *path);
void XmlRemoveChildNodeAtIndex(XmlNode *node, unsigned long index);
void XmlRemoveChildNode(XmlNode *parent, XmlNode *child);
XmlErr XmlAddChildNode(XmlNode *parent,XmlNode *child);
XmlNode *XmlGetChildNode(XmlNode *node, unsigned long index)
XmlNode *XmlGetChildNodeByName(XmlNode *node,char *name);
XmlNode *XmlGetNode(TXml *xml, char *path)
unsigned long XmlCountBranches(TXml *xml)
int XmlRemoveBranch(TXml *xml, unsigned long index)
XmlNode *XmlGetBranch(TXml *xml,unsigned long index);
int XmlSubstBranch(TXml *xml,unsigned long index, XmlNode *newBranch);
int XmlParseBuffer(TXml *xml, char *buf)
int XmlSave(TXml *xml, char *path)
char *XmlDump(TXml *xml, int *outlen)SEE ALSO
XML::TinyXML::NodeYou should also see libtinyxml documentation (mostly txml.h, redistributed with this module)
If you need a more complete and featureful XML implementation try looking at XML::LibXML XML::Parser XML::API XML::XPath or other modules based on either expat or libxml2
AUTHOR
xant, <xant@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2008-2010 by xant
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.