XML::TinyXML - Little and efficient Perl module to manage xml data.
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;
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 (through 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 and 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.
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.
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
setOutputEncoding ($encoding)
Sets the output encding to the specified one
(any iconv-supported encoding is a valid argument for this method)
allowMultipleRootNodes ($bool)
Allow to control if the document can contain multiple root nodes (out of xml spec) or if it will support only one single root node. Default is 0
ignoreBlanks ($bool)
Controls the behaviour of both the parser and the dumper.
- Parser :
If ignoreBlanks is true any 'tab', 'newline' and 'carriage-return' ("\t", "\n", "\r"), between two tags will be ignored, unless surrounded by non-whitespace character. For example, considering the following node:
<parent> <child>value</child> </parent>
( literally : "<parent>\n\t<child>value</child>\n</parent>" )
the parser will ignore the newlines and the tab between two nodes. So, the resulting structure would be :
$node = { value => undef, children => [ { child => "value" } ] }
If ignoreBlanks is false, all characters between the node tags will be part of the value and the result would be :
$node = { value => "\n\t\n", children => [ { child => "value" } ] }
- Dumper :
If ignoreBlanks is true, both newlines and tabs will be used to prettify text formatting, so the node in the previous example will be printed out as:
If ignoreBlanks is false, no extra characters will be added to the xml data (so no newlines, indentation or such). The previous example would be dumped as follows:
<parent><child>value</child></parent>
Default is 1.
ignoreWhiteSpaces ($bool)
Controls the behaviour of the parser.
This flag includes the literal whitespace ' ' among the ignored characters commended by ignoreBlanks()
consider the following examples:
<child> </child> - if true: value = "" - if false: value = " "
The parser will ignore the whitespace if this flag is true.
<child> a value </child> <child> a value</child> <child>a value </child> - if true: value = "a value" - if false: value = " a value " " a value" "a value "
The whitespace will be part of the value if this flag is false.
The dumper is not affected by this flag.
Default is 1
None by default.
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_CDATA
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)
XML::TinyXML::Node
You 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
xant, <xant@cpan.org>
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.
To install XML::TinyXML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::TinyXML
CPAN shell
perl -MCPAN -e shell install XML::TinyXML
For more information on module installation, please visit the detailed CPAN module installation guide.