<introduction>

This library is minimum, easy-to-use, C implementation for XML file parsing It includes:

the library libroxml for XML parsing inside applications.
the binary roxml, an xpath resolver that can be used from shell.
the module fuse.XML that can be used to mount an XML file as a filesystem.
the full public API and private API documentation.

The stripped binary is about 50K. The public API defines less than 30 functions to do all you need, making it very easy to start with. For bug reporting, you can check the github dedicated project: https://github.com/blunderer/libroxml

Libroxml is distributed under the terms of the GNU Lesser General Public License v2.1 with a static linking exception (see License.txt).

</introduction>

<downloads>

The source code is available from github project GIT repository:

$> git clone https://github.com/blunderer/libroxml.git

You can download source packages:

Lastest version is 3.0.2: download now
Go to the download section if you need older libroxml revision: http://download.libroxml.net

</downloads>

<why libroxml>

Because XML parsing is always hard to reinvent, and because very often XML lib are too big to fit with very little application. Libroxml target mainly embedded software and environment, but you can use it whenever you need to deal with XML since libroxml is ligth and fast. libroxml is now provided in buildroot (http://buildroot.uclibc.org).

libroxml allow you to easily:

load / unload XML document from buffers or files.
navigate throughout an XML tree using simple getter API.
handle namespace.
use xpath syntax to access some nodes in the XML tree.
read nodes contents (text, attributes, comments ...)
create/modify XML trees and save them to a file or buffer.

Note: libroxml work with both strict XML documents but also with XML like formatted documents (without any <?XML?> definition...)

Warning: libroxml may behave strangely when dealing with node names or attribute values bigger than 512 bytes. For those who really need it, they can increase this limit by modifying the ROXML_BASE_LEN define in roxml_defines.h.; libroxml do not handle DOCTYPE nodes. However, it will nicely ignore them during parsing and will still return the XML tree.; libroxml is not thread safe for all write operations (roxml_set_ns, roxml_add_node, roxml_del_node) therefore, those functions must be granted exclusive access to the XML tree when called. On the other hand, all other functions can be safely called simultaneously.

</why libroxml>

<how does it work>

You can refer to public API for documentation on all functions

there are several groups of functions in public API:

Load and close XML data from different sources.
Get nodes and navigate into the loaded XML tree.
Get the XML content of nodes, attributes...
Create and delete nodes, export tree.
Some libroxml specific functions for memory handling

</how does it work>

<building libroxml>

libroxml is a cross-platform library. It is developed on Linux OS, but is pretty much standalone and only depends of pthread mutexes in case it is compiled with thread safety enabled. This should make the library work on any platform that is POSIX compliant. Libroxml also works on Microsoft, the pthread API being converted to CriticalSection using basic macros.

Libroxml build system relies on autotool to guaranty the best compatibility on all machines. A CMakeList.txt is also provided in order to ease the native build on Windows machines, but this one provides less options for tuning the behavior of library.

Libroxml can be tuned to make it full-featured or minimalistic, in order to fit most usage:

Development options

–enable-docs Enable building documentation.
–enable-tests Enable building unit tests (only available from git repository).
–enable-debug Turn on debugging.

Feature options

–disable-file Remove support for parsing a file, only parses char buffer containing the XML stream.
–disable-edit Disable the edition of the XML tree: read only XML.
–disable-commit Disable the ability to serialize the modified XML tree back to the disk or to a buffer.
–disable-xpath Disable support for Xpath handling
–disable-roxml Disable building roxml binary (xpath shell solver).
–enable-verbose Enable verbose parsing on errors (printf on stderr of parsing error as they come).

Fine tuning for small systems

–disable-float Remove support for float values in xpath comparisons (if any float is still parsed, it will be floor-ed)
–disable-threadsafe Make the library not threadsafe (but remove dependency on mutex).
–enable-heapbuffers Force all buffers to be allocated on the heap rather than on the stack for tiny systems with small stacks.
–enable-smallbuffer Force using smaller buffer for all XML operations. Useful for small systems, but limits the size of text objects.
–enable-smallinputfile Disable support of files bigger than 64kiB. This reduces the tree footprint. Useful for small systems.