gpl/axl/src/axl.c - view

File: [ELWIX - Embedded LightWeight unIX -] / gpl / axl / src / axl.c
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Wed Jun 8 07:09:12 2011 UTC (12 years, 11 months ago) by misho
Branches: axl, MAIN
CVS tags: HEAD, AXL0_6_7, AXL0_6_1

3th party - XML

/* * @internal * * LibAxl: Another XML library * Copyright (C) 2006 Advanced Software Production Line, S.L. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public License * as published by the Free Software Foundation; either version 2.1 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this program; if not, write to the Free * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA * 02111-1307 USA * * You may find a copy of the license under this software is released * at COPYING file. This is LGPL software: you are welcome to * develop proprietary applications using this library without any * royalty or fee but returning back any change, improvement or * addition in the form of source code, project image, documentation * patches, etc. * * For commercial support on build XML enabled solutions contact us: * * Postal address: * Advanced Software Production Line, S.L. * Edificio Alius A, Oficina 102, * C/ Antonio Suarez Nº 10, * Alcalá de Henares 28802 Madrid * Spain * * Email address: * info@aspl.es - http://www.aspl.es/xml */ #include <axl.h> /** * \mainpage AXL: Another XML Library implementation (XML 1.0 standard) * * \section intro Introduction * * AXL is a library which aims to implement the XML 1.0 standard, as * defined at the XML 1.0 third edition * recommendation found at: http://www.w3.org/TR/REC-xml/. * * It was implemented to support XML requirements inside projects * developed by <a href="http://www.aspl.es">Advanced Software * Production Line, S.L.</a>, especially <a * href="http://fact.aspl.es">Af-Arch</a> and <a * href="http://vortex.aspl.es">Vortex Library</a>, which are already * using the library successfully in production environments. * * Some features this library has are: * * <ul> * * <li>A clean implementation, that only includes, those elements * defined, and only those, inside the XML 1.0 standard, as defined in <a href="http://www.w3.org/TR/REC-xml/">the third edition</a>.</li> * * <li>Fast and memory efficient implementation. If you still * think that XML is slow and memory inefficient, you didn't taste Axl * Library. You'll find report about its performance and memory usage at: http://www.aspl.es/xml/doc.html </li> * * <li>Ensure that the library is implemented using abstract data types, * commonly known as opaque types, to avoid exposing details to the * user space code that is consuming the API. * This will allow us to improve the library without breaking existing * code and, the most important, to not be limited by details already * exposed. * In fact, this design have being already used to improve the library * performance greatly. See reports founds at: http://www.aspl.es/xml/doc.html</a>.</li> * * <li>Small and efficient, ensuring on every stable release that * the library do not leak, not only while using the library in a * proper manner but also when errors were found. </li> * * <li>Have a modular design that allows to use only those * elements required by your software. At this moment it is provided a * base library (with implements XML 1.0) and optional libraries that * provides additional features to support XML Namespaces 1.0 and * extended encodings.</li> * * <li>To have an small footprint is a requirement. Currently LibAxl (118K) and LibAxl-Ns (9K)</li> * * <li>Bindings for other languages. At this moment it is officially supported PyAxl, a binding for the Python Language.</li> * </ul> * * \section features_and_status What is the status of the library * * Currently the library is stable and it is known to work under * GNU/Linux and Windows with a really good performance. See reports found at http://www.aspl.es/xml/doc.html to know more about this. * * The library already covers the 95% of common requires that XML * development needs. Among others, it support: * * - XML tree parsing, from memory and files, allowing a great level * of detail while accessing to the data (comments, process * instructions, xml nodes, and content). * * - Mostly completed DTD validation support, including <!ATTLIST>, <!ENTITY> * and <!ELEMENT> elements. Remains to implement NOTATION declarations * and full entity replacement. * * - Two modes to inspect the xml documents at the same time, * MIXED API: an API to traverse the document allowing access * to all items found (\ref axlItem) inside the document (\ref * axlDoc) root node (\ref axlNode), and CHILDREN API: an API * that allows to traverse the node using as reference only the nodes * (\ref axlNode) inside the document (\ref axlDoc). * * - <a href="http://www.w3.org/TR/REC-xml-names/">XML 1.0 * Namespaces</a> full support, through the additional component * (libaxl-ns), allowing to produce xml applications that are * XML Namespace aware. * * - Support for extended encodings (libaxl-babel), beyond default encoding utf-8. * * \section documentation Library Documentation * * The library documentation is composed into two pieces. The Axl * manual and the API documentation. * * - \ref axl_install * - \ref axl_manual * - \ref axl_api * - \ref axl_knife_manual * * \section contact_us Contact us * * If you find something not properly documented, or some question is * not answered on this documentation, check the <a href="http://www.aspl.es/axl/doc.html">mailing list</a>. * * You can also contact us if you have patches, improvements or * suggestions at the mailing list. */ /** * \page axl_manual XML development with Axl Library * * \section Manual Index * * On this manual you'll find the following section: * * Section 1: Basic elements to understand XML and Axl * * - \ref intro * - \ref concepts * - \ref two_apis * * Section 2: Manipulating and producing XML documents * * - \ref parsing * - \ref iterating * - \ref modifying * - \ref dumping_functions * * Section 3: Doing validation on your documents * * - \ref validation * - \ref xml_namespace * - \ref using_axl_babel * * Section 4: Advanced topics * * - \ref reducing_foot_print * * Apendix * * - \ref futher * * * \section intro Introduction: XML development * * XML 1.0 definition allows to build documents that could be used to * represents textual information, remote procedure invocations or * dynamic user interfaces. Its definition is based on very simple * principles, that allows to developers to compose them to create * bigger abstractions that are roughly on every place in modern * computer software design. * * It is a "quite" human readable format, so you will find that is not * the best format if you are looking for space efficiency. What XML * 1.0 provides you on the other hand is the ability to quickly * prototype and produce working formats that encapsulate your data, * and, as your system evolves, XML 1.0 will do it with you. * * Among other things, XML 1.0 provides you ways to validate your * documents to ensure your code will read XML documents in the format * expected, reducing the time and development cost due to additional * checkings required. * * Before continuing, we will explain some concepts that are required * to understand XML 1.0 and why the Axl API was built this way. * * \section concepts Some concepts before starting to use Axl Library * * Here is a simple example of a XML 1.0 document: * <div class="xml-doc"> * \code * <?xml version="1.0"> *  * <complex> * <data> * <simple>10</simple> * <empty attr1="value1" /> * </data> * </complex> * \endcode * </div> * * Previous XML document represents an structure with a top level * node, called complex, that has one single child called * data which in turn have two childs. The first one is the * child called simple that have content and other one, called * empty, which is a node usually called an empty xml node. * * The XML representation for previous document is the following: * \image html image01.png "Document representation" * * Several issues must be considered while interpreting previous * diagram and how Axl library parse and expose those elements through * the API to the client application: * <ul> * * <li>Every XML document have a root node (\ref axl_doc_get_root). Without exception. In this * case, the root node for our example is complex. </li> * * <li>If a node have content, that content is not represented with * another node. That content is associated to the node and could be * retrieved using several function (\ref axl_node_get_content, \ref * axl_node_get_content_copy and \ref * axl_node_get_content_trans). * * Alternatively, while using the MIXED API, you can traverse child * items stored for a particular node, detecting those items that are * \ref ITEM_CONTENT or \ref ITEM_CDATA (using \ref * axl_item_get_type). </li> * * <li>Having a node (\ref axlNode) with content doesn't mean to have a node with * childs. The child notion is only about having more xml nodes (\ref axlNode) as * childs. * * This is particularly important if you take into consideration that a * node could have content (\ref ITEM_CONTENT), comments (\ref * ITEM_COMMENT), application process instructions (\ref ITEM_PI), * CDATA content (uninterpreted content \ref ITEM_CDATA), all of them * mixed with more xml nodes (\ref ITEM_NODE). </li> * * <li>A final node which is empty because it doesn't have content or * childs, is usually referred to as EMPTY type node. A final * node with content but no childs is usually referred to as * PCDATA. A node that have content mixed with references to * more child xml nodes is referred to as MIXED.</li> * * <li>At the empty node, you'll find that it has an attribute * called attr1 with a value value1. A node could have * any number of attributes but, it should be named * differently. Again, if a node is empty, it keeps empty even if it * has attributes. * </li> * * So, to summarize, we have a root node, that could contain more * nodes, that could contain PCDATA, or content, and those nodes could * contain named attributes with values. * * \section two_apis MIXED and CHILDREN API: How to use them * * XML 1.0 is used for a variety of purposes, some of them requires * the CHILDREN API and the rest the MIXED API. To require, we * mean that it fits better, so you will get better results, your * application will react in a proper manner and you'll have to do * less work. * * The reason for this API is simple. XML 1.0 definition allows to mix * content with more nodes, comments and many more elements to be * placed as childs for a particular node. * * This definition, found at the standard, have moved many XML * implementations to support only an API that support all these * features, that is, an interface that is complicated and overloaded, * that gives you a power that you don't require, making your * development more inefficient. * * As a result, when a developer only requires a usual form of xml, * called CHILDREN, that means nodes have only another childs * nodes or content but not both at the same time. This kind of xml is * really useful, easy to parse, easy to make a DTD definition, more * compact and extensible. * * Lets see an example for both formats to clarify: * * <div class="xml-doc"> * \code * <?xml version='1.0' ?> * <document> *  *  *  * <node1> * This is node1 content * </node1> * <node2> * <node3> * This is node3 content * </node3> * <node4 /> * </node2> * </document> * \endcode * </div> * * While an MIXED xml document could be: * * <div class="xml-doc"> * \code * <?xml version='1.0' ?> * <document> *  *  *  * <node1> * This is node1 content * </node1> * Content mixed with xml nodes at the same level. * <node2> * More content.... * <node3> * This is node3 content * </node3> * <node4 /> * </node2> * </document> * \endcode * </div> * * Both approaches, which are valid using the XML 1.0 standard, are * appropriate for particular situations: * * - CHILDREN API: compact representations, configuration files, rpc * invocation description, graphical user interface definition. * - MIXED API: textual description, for example: XSL-FO. * * Having introduced the context of the problem, Axl Library takes no * position, providing an API that fits while developing xml content * that follows a CHILDREN description and an API for the MIXED * description. * * In this context, which API you use, will only affect to the way you * traverse the document. The CHILDREN API is mainly provided by the * \ref axl_node_module "Axl Node interface" and the MIXED API is * mainly provided by the \ref axl_item_module "Axl Item interface". * * You don't need to do any especial operation to activate both APIs, * both are provided at the same time. Lets see an example: * * Supposing the previous mixed example, the following code will get * access to the <node2> reference: * \code * // supposing "doc" reference contains the document loaded * axlNode * node; * * // get the document root, that is <document> * node = axl_doc_get_root (doc); * * // get the first child for the document root (<node1>) * node = axl_node_get_first_child (node); * * // get the next child (brother of <node1>, that is <node2>) * node = axl_node_get_next (node); * \endcode * * However, with the MIXED API you can get every detail, every item * found for a particular node. This is how: * * \code * // supposing "doc" reference contains the document loaded * axlNode * node; * axlItem * item; * * // get the document root, that is <document> * node = axl_doc_get_root (doc); * * // get the first item child for the document root that is the comment: * // "Children XML format example: as you can see". * item = axl_item_get_first_child (node); * * // now skip the following two comments * item = axl_item_get_next (item); * item = axl_item_get_next (item); * * // now the next item is holding the <node1> * item = axl_item_get_next (item); * node = axl_item_get_data (item); * * // now get the content between the <node1> and <node2> * item = axl_item_get_next (item); * * // and finally, get the next child (brother of <node1>, that is * // <node2>) * item = axl_item_get_next (item); * node = axl_item_get_data (item); * \endcode * * Obviously, the mixed example contains more code and it is more * fragile to xml document changes. The problem is that the MIXED API * is more general than the CHILDREN, making XML libraries to only * provide that API. * * As a consequence: * * - You only need to use the MIXED API (\ref axlItem) if you are * going to do an xml application that allows having content mixed * with nodes, comments, etc, and you want to get access to such * content. * * - If you are planing to develop an XML solution that represents * information (user interfaces), module descriptions, configuration * files, etc, try to use the CHILDREN API: it will save you lot of * work! Remember, CHILDREN xml format: childs are either content or * more xml nodes but not both. Never mixed. * * \section parsing Parsing XML documents * * We have seen how an XML document is. Now we are going to see how to * parse those document into data structures that are usable to * inspect the content. All parsing functions are available at the * \ref axl_doc_module "Axl Doc interface". * * Let's start with a very simple example: * * \code * #include <axl.h> * #include <stdio.h> * * int main (int argc, char ** argv) * { * axlError ** error; * * // top level definitions * axlDoc * doc = NULL; * * // initialize axl library * if (! axl_init ()) { * printf ("Unable to initialize Axl library\n"); * return -1; * } * * // get current doc reference * doc = axl_doc_parse_from_file ("large.xml", error); * if (doc == NULL) { * axl_error_free (error); * return axl_false; * } * * // DO SOME WORK WITH THE DOCUMENT HERE * * // release the document * axl_doc_free (doc); * * // cleanup axl library * axl_end (); * * return axl_true; * } * \endcode * * \section iterating Traveling an XML document * * Once the document is loaded you can use several function to * traverse the document. * * First you must use \ref axl_doc_get_root to get the document root * (\ref axlNode) which contains all the information. Then, according * to the interface you are using, you must call to either \ref * axl_node_get_first_child or \ref axl_item_get_first_child. * * Once you have access to the first element, you can use the * following set of function to get more references to other nodes or * items: * * <ul> * <li>MIXED API: * * - \ref axl_item_get_first_child * - \ref axl_item_get_last_child * - \ref axl_item_get_next * - \ref axl_item_get_previous * * </li> * <li>CHILDREN API: * * - \ref axl_node_get_first_child * - \ref axl_node_get_last_child * - \ref axl_node_get_next * - \ref axl_node_get_previous * * </li> * </ul> * * There are alternative APIs that will allow you to iterate the * document, providing a callback: \ref axl_doc_iterate. * * Another approach is to use \ref axl_doc_get and \ref * axl_doc_get_content_at to get fast access to a particular node * using a really limited XPath syntax. * * \section modifying Modifying a loaded XML document * * One feature that comes with Axl Library is ability to modify the * content, replacing it with other content and transferring node node * to another place. * * Check the following function while operating with \ref axlNode elements: * * - \ref axl_node_replace * - \ref axl_node_remove * - \ref axl_node_transfer_childs * * Check the following functions while operating with \ref axlItem elements: * * - \ref axl_item_replace * - \ref axl_item_remove * - \ref axl_item_transfer_childs_after * * \section dumping_functions Producing xml documents from memory * * Axl Library comes with several functions to perform xml memory dump * operations, allowing to translate a xml representation (\ref axlDoc * or \ref axlNode) into a string: * * - \ref axl_doc_dump * - \ref axl_doc_dump_pretty * - \ref axl_doc_dump_to_file * - \ref axl_doc_dump_pretty_to_file * * In the case you want to produce xml content taking as reference a * particular node use: * * - \ref axl_node_dump * - \ref axl_node_dump_pretty * - \ref axl_node_dump_to_file * - \ref axl_node_dump_pretty_to_file * * \section validation Validating XML documents * * Once you are familiar with the Axl API, or any other XML toolkit, * it turns that it is not a good practice to write lot of source code * to check node names expected or how they are nested. This makes * your program really weak to changes and makes your to write more * code that is not actual work but a simple environment check. * * You may also need to check that some XML document received follows * a defined XML structure, but it is too complex to be done. * * For this purpose, XML 1.0 defines DTD or (Document Type Definition) * which allows to specify the document grammar, how are nested * nodes, which attributes could contain, or if the are allocated to * be empty nodes or nodes that must have another child nodes. * * Let start with the DTD syntax used to configure restrictions about * node structure: * * <div class="xml-doc"> * \code *  * <!ELEMENT testA (test1, test2, test3)> * *  * <!ELEMENT testB (test1 | test2 | test3)> * \endcode * </div> * * * DTD <!ELEMENT is modeled on top of two concepts which are * later expanded with repetition patterns. We will explain then * later. For now, this two top level concepts are: sequence and choice. * * Sequence specification (elements separated by , (comma), the * one used to apply restriction to the node testA, are used to * denote that testA have as childs test1, followed by test2 * and ended by test3. The order specified must be followed and all * instances must appear. This could be tweaked using repetition * pattern. * * In the other hand, choice specification (elements separated by * | (pipe), are used to specify that the content of a node is * built using nodes of the choice list. So, in this case, * testB node could have either one instance of test1 or test2 * or test3. * * Now you know these to basic elements to model how childs are * organized for a node, what it is need is to keep on adding more * <!ELEMENT directives until all nodes are specified. You will end * your DTD document with final nodes that are either empty ones or * have PCDATA. At this moment MIXED nodes are not supported. * * Suppose that all nodes that are inside testA and testB are final * ones. Then this could be its DTD specification: * * <div class="xml-doc"> * \code *  * <!ELEMENT test1 (#PCDATA)> * *  * <!ELEMENT test1 EMPTY> * *  * <!ELEMENT test3 (test1 | test2)> * \endcode * </div> * * Sequences and choices could be composed to create richer DTD * expressions that combines sequences of choices and so on. * * At this point all required elements to model choices, sequences and * final nodes are explained, but, we have to talk about repetition * pattern. They are symbols that are appended to elements inside * choices (or sequences) including those list specifications. * * Patterns available are: +, ? and *. By * default, if no pattern is applied to the element, it means that the * match should be produced one and only one time. * * The + pattern is used to model that element should be * matched one, and at least one, or more. * * The * pattern is used to model elements that should be * matched zero or any times. * * The ? pattern is used to model elements that should be * matched zero or one times. * * For the exampled initially explained, let's suppose we want that * the content inside testA have sequences repeated at leat one * time, being that sequence: test1, test2 and test3. We only need to * add a + repetition pattern as follows: * * <div class="xml-doc"> * \code *  * <!ELEMENT testA (test1, test2, test3)+> * \endcode * </div> * * So, we are saying to our validation engine that the sequence inside * testA could be found one or many times, but the entire sequence * match be found every time. * * Here is an simple example that loads an XML document, then loads an * DTD file, and then validates the XML document: * \code * bool test_12 (axlError ** error) * { * axlDoc * doc = NULL; * axlDtd * dtd = NULL; * * // parse gmovil file (an af-arch xml chunk) * doc = axl_doc_parse_from_file ("channel.xml", error); * if (doc == NULL) * return axl_false; * * // parse af-arch DTD * dtd = axl_dtd_parse_from_file ("channel.dtd", error); * if (dtd == NULL) * return axl_false; * * // perform DTD validation * if (! axl_dtd_validate (doc, dtd, error)) { * return axl_false; * } * * // free doc reference * axl_doc_free (doc); * * // free dtd reference * axl_doc_free (dtd); * * return axl_true; * } * \endcode * * Until now, we have seen how to check xml structure. But this do not * cover xml node attributes. This is checked by using * <!ATTLIST> declaration. * * In the case we have a node testA with two attribuets * attr1 and attr2 the first one optional and the second * one mandatory, we can declare something like: * * <div class="xml-doc"> * \code *  * <!ATTLIST testA * attr1 CDATA #IMPLIED * attr2 CDATA #REQUIRED> * \endcode * </div> * * * \section xml_namespace Enabling your software with XML Namespaces * * XML 1.0 initial design didn't take care about situations where * several software vendors could introduce content inside the same * XML documents. This has several benefits, but one problem to solve: * how to avoid xml node names (tags) to clash from each other. * * Think about using <table> as a tag for your document. Many XML * applications uses <table> as a valid tag for its XML language * set. However, each of them has a different meaning and must be * handled by the proper XML software. * * While developing applications with XML, and supposing such XML * documents will be used by more applications than yours, you are * likely to be interested in use XML Namespaces. In other words, many * of the new XML standards that are appearing uses XML Namespaces to * allow defining its xml node names, while allowing users/developers * to use their own set of xml tags, under their own XML Namespaces, * in order they can use them in the same document. * * XML Namespaces support inside Axl Library is handled through a * separated library, which requires the base library to function. \ref axl_install "Here are some instructions to get Axl Library Namespace installed." * * This library provides functions that replaces some of the functions * used by XML applications that don't require XML Namespaces. In * particular, some of them are: * * - \ref axl_ns_doc_validate (see this for an example) * - \ref axl_ns_node_cmp * * See also API documentation for all functions that are provided to * enable your application with XML Namespaces: * * - \ref axl_ns_doc_module * - \ref axl_ns_node_module * * \section using_axl_babel Making your software to support other encodings than UTF-8 * * Default axl library implementation (libaxl) assumes it will receive * and produce UTF-8 content. * * Because the subset of characters that are used to properly parse * XML content are located in the ASCII range, still valid UTF-8, but * at same time valid in other encodings such ISO 646, some part of * ISO 8859, Shift-JIS, EUC, or any other 7-bit, 8-bit, or mixed-width * encoding which ensures that the characters of ASCII have their * normal positions, width, and values (See section F. Autodetecting * of Character Encodings at http://www.w3.org/TR/REC-xml/), causes * the library to properly parse the content, even if it is not UTF-8. * * In many cases this is not important for you since your application * do not care about content codification (such configuration files) * or they are in UTF-8. * * However, this could present problems if you are handling different * documents with several encoding types. The idea is to have an * unified way to handle such different encoded documents, with a * single, run-time encoding: UTF-8. * * libaxl-babel provides support to read content in supported * codifications and translate it into UTF-8 at run-time (checking * result to be valid UTF-8): * * \image html axl_babel_reading.png "Reading documents and handle them as they were in UTF-8" * * The library works as an extension that configures a set of handlers * making the library to open XML documents and translating them into * UTF-8 if required. * * To activate the library, you must use \ref axl_babel_init at the * begining of your application or library. Here is an example: * * \code * // optional axlError declaration * axlError * error; * * // init axl babel * if (! axl_babel_init (&error)) { * printf ("Failed to start axl babel: %s...\n", * axl_error_get (error)); * axl_error_free (error); * return axl_false; * } * \endcode * * Once done, every call to the base API (such \ref axl_doc_parse, * \ref axl_doc_parse_from_file) will open the document as usual. It * is not required to perform any additional special operation. * * It is not required to call to \ref axl_babel_finish on application * exit. However, in the case you want to deactivate * libaxl-babel but still keep on using axl base library, you * can use \ref axl_babel_finish. * * See \ref axl_babel_init for currently supported formats. * * \section reducing_foot_print How to reduce the library footprint * * Axl Library is implemented in a modular way to ensure you are only * linked against those software elements that you really * require. Additionally, the library allows the following to reduce * the library footprint to the minimum: * * <ul> * <li>Remove log information: Axl library uses a console log * mechanism to report what's happening during processing. See \ref * axl_log_module "Axl Log reporting" module for more * information. However, under production environments this console * log isn't necessary, so you can safely remove it, at compile time, * using --axl-log-disable as follow: * * \code * >> ./configure --axl-log-disable * \endcode * * According to our results, the library including the log to console * information is about 366K. Without log to console information the * library takes about 288K. * * </li> * * <li>Remove debugging information from the library: You * can also remove debugging information from your library on * production environments doing the following once finished compilation process: * * \code * >> make install-strip * \endcode * * According to our results, the library without log to console and * debugging information takes about 100K. * * </li> * </ul> * * Previous information applies to the Axl base Library * (libaxl.so/.dll), however the same happens for the rest of software * components bundle with Axl. * * * \section futher Futher reading where to go for more information * * You can also check \ref axl_api "API documentation" for a complete * detailed explanation about the library. * * Please, if you find that something isn't properly documented or you * think that something could be improved, contact us in the mailing * list. We are building Axl Library with the aim to produce a high * quality, commercial grade, open source XML development kit, so, any * help received will be welcome. * * Remember you can always contact us at the mailing list for any * question not properly answered by this documentation. See <a * href="http://www.aspl.es/axl/doc.html">Axl Library website * documentation</a> to get more * information about mailing list. * */ /** * \page axl_api LibAxl API documentation * * Here is the API for the modules defined inside the library: * * <ul> * <li>Basic API to interact with XML documents (base library libaxl): </li> * * - \ref axl_module * - \ref axl_doc_module * - \ref axl_node_module * - \ref axl_node_attribute_cursor * - \ref axl_node_annotate * - \ref axl_item_module * - \ref axl_dtd_module * - \ref axl_decl_module * - \ref axl_handlers * * </li> * <li>XML Namespaces API (required additional library libaxl-ns): </li> * * - \ref axl_ns_doc_module * - \ref axl_ns_node_module * * </li> * <li>Axl BABEL API (required to support additional encoding formats): </li> * * - \ref axl_babel * * </li> * <li>Error reporting and debugging functions (base library libaxl): </li> * * - \ref axl_error_module * - \ref axl_log_module * * <li>Auxiliary modules, supporting data types, string handling, etc (base library libaxl):</li> * * - \ref axl_stream_module * - \ref axl_list_module * - \ref axl_list_cursor_module * - \ref axl_stack_module * - \ref axl_binary_stack_module * - \ref axl_hash_module * - \ref axl_hash_cursor_module * - \ref axl_string_module * * </li> * </ul> * */ /** * @page axl_install Installing Axl library and using it * * \section intro Introduction * * Axl library is an XML library written in ANSI C, which is known to * work on Microsoft Windows, GNU/Linux, *-BSD, GNU/Linux under * Amd64/Itanium and MacOS/X platforms. * * The library package is composed by the following items: * * \image html axl-components.png "Axl library components" * * - libaxl: base library implementing all XML functions, and * common API used by extension libraries. It has no external * dependencies. * * - libaxl-ns: optional library, built on top of libaxl, which * provides Namespaces support. It depends on libaxl. * * - libaxl-babel: optional library, built on top of libaxl, * which provides extended encoding support to defult utf-8. * * - axl-knife: command line tool, built on top of libaxl and * libaxl-ns. It depends on the base library and the namespace * library. * * Here are a set of instructions to get the library compiled for your * platform: * * \section axl_on_unix GNU/Linux (or any posix OS) installation instructions * * First, download the package from the download section. Check <a * href="http://www.aspl.es/axl/doc.html">this section to know more * about this.</a> * * Then use the standard procedure to get compiled an autotool ready * package. Here are the steps: * * \code * >> tar xzvf axl-0.2.1.b1984.g1985.tar.gz * >> cd axl-0.2.1.b1984.g1985/ * >> ./configure * >> make * >> make install * \endcode * * \section checking_axl Checking Axl Library compilation (regression test) * * Once finished, to check your axl build to properly work, get inside * the test/ directory and run axl regression test (test_01): * \code * >> cd test/ * >> ./test_01 * \endcode * * All test must execute properly to ensure the library is fully functional. * * \section windows Windows installation instructions * * Axl library comes with packages already built for Microsoft Windows platforms. * Check <a href="http://www.aspl.es/axl/doc.html">the download section to get them</a>. * * \section using Using LibAxl library (installations with pkg-config infrastructure) * * Axl Library is composed by a base library, which provides all XML * 1.0 function. Additionally, a separated library is provided for * Namespace functions. * * Axl library comes with pkg-config support, which makes easy to use * it inside your pkg-config enable projects. * * To check current support for your Axl Library you can execute: * * \code * >> pkg-config --libs --cflags axl * \endcode * * To give support for XML Namespaces (libaxl-ns), you must use: * \code * >> pkg-config --libs --cflags axl-ns * \endcode * * To give support for extended encoding support (libaxl-babel), you must use: * \code * >> pkg-config --libs --cflags axl-babel * \endcode * * To include support into your autotool checks (configure.ac/in * files) you can place the following piece: * \code * PKG_CHECK_MODULES(LIBRARIES, axl) * \endcode * * Again, add axl-ns or axl-babel to the previous * instruction if you want your package to also check for Axl Library * Namespace support. * * \section Including Axl Library headers * * For all platforms, Axl Library base headers has to be included as follows: * \code * #include <axl.h> * \endcode * * In the case Namespace is required, you must use: * \code * #include <axl_ns.h> * \endcode * * To include babel support, you must use: * \code * #include <axl_babel.h> * \endcode */ /** * \defgroup axl_module Axl main: Init functions for the library */ /** * \addtogroup axl_module * @{ */ /** * @brief Initializes Axl library. * * Currently this function is not required to be executed because * libaxl implementation don't use it. The implementation will try to * make no used for internal variable initialization. * * However the API is provided for future usage. * * @return The function returns \ref axl_true if it was properly * initialized or \ref axl_false if something fails. if fails. */ axl_bool axl_init (void) { /* nothing to initialize dude */ return axl_true; } /** * @brief Allows to terminate libaxl library function. * * Currently this function is not required becasue nothing is done to * stop libaxl function. The implementation will try to keep this, * however, if the future this could be required. */ void axl_end (void) { /* nothing to do jack */ return; } /* @} */