Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  XML::TINYXML (3)

.ds Aq ’


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


o new ($arg, %params)

Creates a new XML::TinyXML object.

$root can be any of :


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)

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

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

o 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)

o 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

o dump ()

Returns a stringified version of the XML structure represented internally

o loadFile ($path)

Load the xml structure from a file

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

o toHash ()

Dump the xml structure represented internally in the form of an hashref

o loadBuffer ($buf)

Load the xml structure from a preloaded memory buffer

o 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

o getChildNode ($node, $index)

Get the child of $node at index $index.

Returns an XML::TinyXML::Node object

o countChildren ()

Returns the number of $node’s children

o removeNode ($path)

Remove the node at specific $path, if present. See getNode() documentation for some notes on the $path format.

Returns XML_NOERR \fIs0(0) if success, error code otherwise.

See Exportable constants for a list of possible error codes

o getBranch ($index)

alias for getRootNode

o getRootNode ($index)

Get the root node at $index.

Returns an XML::TinyXML::Node object if present, undef otherwise

o removeBranch ($index)

Alias for removeRootNode

o removeRootNode ($index)

Remove the rootnode (and all his children) at $index.

o countRootNodes

Returns the number of root nodes within this context

o rootNodes ()

Returns an array containing all rootnodes. In scalar context returns an arrayref.

o 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

o save ($path)

Save the xml document represented internally into $path.

Returns XML_NOERR if success, a specific error code otherwise

o 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

o 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

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


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


Default is 1.

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

    Exportable constants


    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)



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


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 XML::TINYXML (3) 2013-09-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.