libxml++ 0.14
-------------

This library provides a C++ interface to XML files.  It presently uses
libxml (gnome-xml) >= 2.0.0 to access the XML files, and in order to
configure libxml++ you must have libxml installed and its xml-config
script must be available in your shell's command path.

To get the latest version of libxml++, check out http://sourceforge.net/projects/libxmlplusplus/
To contact the developer, send e-mail to cdevienne@netcourrier.com

Read the file 'INSTALL' for instructions to compile and install the library.

To use libxml++ in your program, you can #include <libxml++/xml++.h> and use the
class interfaces presented in that file (and documented below).

To compile,
you will need to provide your compiler with the path to xml++.h, which should
be available by running 'xml++-config --cflags', assuming that xml++-config
is in your present path.  To link with libxml++, you will need to link with
-lxml++ -lxml -lz.  The full set of linker options to use should be available
by running 'xml++-config --libs'.

If you are writing a program that uses libxml++, and you wish to check for
it in your GNU autoconf script, make sure that the libxml++.m4 file
(installed in $(prefix)/share/aclocal by default) is in your global
aclocal include directory or you run aclocal with the -I option, pointing
to the location of libxml++.m4.  Then, use the AM_LIBXMLPP macro.  Both of
its arguments are optional.  The first one is executed if libxml++ is
found, and the second is executed if it is not found.

API Documentation
-----------------

xml++.h declares several data types.  These are XMLTree, XMLNode, XMLProperty,
XMLNodeList, and XMLPropertyList.  XMLNodeList and XMLPropertyList are
STL 'list's of their respective types.  A SAX parser is also declared in
xml++.h, involving the classes XMLParser and XMLParserCallback.


XMLTree
-------
Contains an entire XML tree, or file.

XMLTree()
	This constructor creates an empty tree with no filename.

XMLTree(const string &fn)
	This constructor creates a new tree, sets the filename to its
	single argument, and loads that file's XML data into the tree.
	If the tree was full, all of its nodes will be deallocated as well.

~XMLTree()
	The destructor frees all memory used by the tree, including
	all of its nodes.

XMLNode *root()
	Returns a pointer to the root node of the tree.

XMLNode *set_root(XMLNode *r)
	Sets a new root node for the tree.  The old root node is
	not deallocated.

const string & filename()
	Returns the filename of the tree.

const string & set_filename(const string &fn)
	Sets a new filename for the tree.

const string & encoding()
	Returns the encoding of file

const string & set_encoding(const string & e)
	Set the encoding of the file.
	If the encoding type is not supported by libxml, the given
	value is silently ignored.
	The encoding is returned (can be different if given value is ignored).

int compression()
	Returns the level of compression (0-9 inclusive, 0 denoting
	no compression at all) of the file.

int set_compression(int c)
	Sets the level of compression.

bool read()
	Reads the XML file into the tree, returning true on success
	and false on failure.

bool read(const string &fn)
	Sets a new filename and reads its XML data into the tree,
	returning true on success and false on failure.

bool read_buffer(const string &buffer)
	Reads XML data from a buffer in memory, returning true on
	success and false on failure.

bool write()
	Writes the tree to an XML file, returning true on success and
	failure on failure.

bool write(const string &fn)
	Sets a new filename for the tree and writes the tree to
	that file, returning true on success and false on failure.

const string & write_buffer()
	Returns a string containing the data in the XML tree.


XMLNode
-------
This type contains a single XML node and links to its children and
properties.

XMLNode(const string &n)
	This constructor creates a new XMLNode and sets its name.

XMLNode(const string &n, const string &c)
	This constructor creates a new, nameless XMLNode and sets its
	content value.

~XMLNode()
	The destructor frees all memory used by the node, its properties,
	and its children.

initialized()
	Returns true if the node is initialized and ready for use, false
	otherwise.

const string & name()
	Returns the name of the node.

bool is_content()
	Returns true if the node is a content node and false otherwise.

const string & content()
	Returns the content of the node.

const string & content(const string &c)
	Sets the content of the node.

int line()
	Returns the line number of the node in the source file.

const XMLNodeList & children(const string &n = string())
	Returns an XMLNodeList of all this node's children with the
	given name, or all of its children if no name is given.

XMLNode *add_child(const string &n)
	Adds a new child, setting its name, and returns a
	pointer to the new node.

XMLNode *add_child(XMLNode *n)
	Inserts a new child from an existing XMLNode, and
	returns a pointer to the new child node.  No duplication
	is performed.

XMLNode *add_content(const string &c = string())
	Adds a new child that is set to store content.

remove_child(XMLNode *n)
	Removes the child to which the argument points from this node.

const XMLPropertyList & properties()
	Returns a list of all the properties of this node.

XMLProperty *property(const string &n)
	Returns the property named in the argument.

XMLProperty *add_property(const string &n, const string &v = string())
	Adds a new property to the node, setting its name and
	optionally its value, and returns a pointer to the new
	property.

remove_property(const string &n)
	Removes, by name, the selected property from the node.


XMLProperty
-----------
Contains a property of an XML node.

XMLProperty(const string &n, const string &v = string())
	Creates a new property and sets its name and optionally
	its value.

~XMLProperty()
	Frees all memory used by the property.

const string & name()
	Returns the name of the property.

const string & value()
	Returns the value of the property.

const string & set_value(const string &v)
	Sets and returns the value of the property.


XMLParser
---------
Defines a SAX parser for XML files.

The class is declared as a template, so you must first define a child class
of XMLParserCallback (see documentation of that class below).  Then, to create
a parser, you simply create an object of type 'XMLParser<X>', where X is the
XMLParserCallback class you defined.

XMLParser()
	The constructor sets up the libxml SAX parser context.

~XMLParser()
	The destructor frees all memory used by the XMLParser object.

parse_chunk(const string &s)
	Parses a chunk of XML data.

finish()
	Finalizes the XML parser's input.


XMLParserCallback
-----------------
Declares the callbacks for an XMLParser, but by itself does nothing.
You must create a new class that inherits (using the 'public' inheritance
type) from this one, and then give that class to the XMLParser object.
Documentation here is for the callbacks that you can define in your class
Any callbacks that you do not define will simply be ignored.

start_document()
	Called at the start of the document.

end_document()
	Called when the document is finalized.

start_element(const string &n, const XMLPropertyHash &p)
	Called when an element's opening tag is encountered, with the name
	of the tag and a hash of all of its properties.

end_element(const string &n)
	Called when an element's closing tag is encountered, or immediately
	after start_element() if the tag is in <tag/> format.

characters(const string &s)
	Called when characters are encountered.

comment(const string &s)
	Called when a comment is encountered.

warning(const string &s)
	Called when a parser warning occurs.

error(const string &s)
	Called when a parser error occurs.

fatal_error(const string &s)
	Called when a parser fatal error occurs.