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 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.

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

• setOutputEncoding ($encoding)

  Sets the output encding to the specified one

  (any iconv-supported encoding is a valid argument for this method)

  Returns XML_NOERR if success, a specific error code otherwise

• 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>

  ( literaly : "<parent>\n\t<child>value</child>\n</parent>" )

  the parser will gnore 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: <parent> <child>value</child> </parent>

  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

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_CDATA

Exportable 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::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

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.