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();
    
  $node = XML::TinyXML::Node->new("nodelabel", "somevalue");
  # or maybe 
  $attrs = { attr1 => v1, attr2 => v2 };
  $node = XML::TinyXML::Node->new("nodelabel", "somevalue", $attrs);

  $xml->addRootNode($node);

  # or you could want to create the XML Context 
  # specifying the root node directly at creation time
  $xml = XML::TinyXML->new($node);

  # or maybe 
  $xml = XML::TinyXML->new("rootnode", "somevalue", { attr1 => v1, attr2 => v2 });

  # or we can just create an empty root node:
  $xml = XML::TinyXML->new("rootnode");

  # and then obtain a reference using the getNode() method
  $node = $xml->getNode("/rootnode");

  # the leading '/' is optional ... since all paths will be absolute and 
  # first element is assumed to be always a root node
  $node = $xml->getNode("rootnode");

  # 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, '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, '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 a powerful interface) but without the need to install a lot of other modules (or even C libraries) to have it working. Once I discovered XS I started porting a very little and efficent xml library I wrote in C some years ago.

The interesting part of porting it in perl is that now it's really easy to improve the interface and I was almost always pissed off of installing more than 10 modules to have a simple xml implementation.

• new ($arg, $param, $attrs, $doctype)

  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 the parameter passed to loadHash() if $root is a scalar, this will be the value of the root node, attrs => attributes of the 'contextually added' $root node );

• addNodeAttribute ($node, $key, $value)

  Adds an attribute to a specific $node

• removeNodeAttribute ($node, $index)

  Removes from $node the attribute at $index if present.

• addRootNode ($name, $val, $attrs)o

  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)

• 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

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

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

• 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_NODETYPE_SIMPLE
  XML_NODETYPE_COMMENT
  XML_NODETYPE_CDATA

Exportable functions

  TXml *XmlCreateContext()
  void XmlDestroyContext(TXml *xml)
  int XmlAddAttribute(XmlNode *node, char *name, char *val)
  int XmlAddRootNode(TXml *xml, XmlNode *node)
  unsigned long XmlCountBranches(TXml *xml)
  XmlNode *XmlGetChildNode(XmlNode *node, unsigned long index)
  XmlNode *XmlGetNode(TXml *xml,  char *path)
  int XmlParseBuffer(TXml *xml, char *buf)
  int XmlRemoveBranch(TXml *xml, unsigned long index)
  int XmlSave(TXml *xml, char *path)
  char *XmlDump(TXml *xml)

SEE ALSO

  XML::TinyXML::Node

You should also see libtinyxml documentation (mostly txml.h, redistributed with this module)

AUTHOR

xant, <xant@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 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.