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

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>
    
```
( 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:
```
    <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)

AUTHOR

xant, <xant@cpan.org>

COPYRIGHT AND LICENSE

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.