Annotation of gpl/axl/src/axl.c, revision 1.1
1.1 ! misho 1: /*
! 2: * @internal
! 3: *
! 4: * LibAxl: Another XML library
! 5: * Copyright (C) 2006 Advanced Software Production Line, S.L.
! 6: *
! 7: * This program is free software; you can redistribute it and/or
! 8: * modify it under the terms of the GNU Lesser General Public License
! 9: * as published by the Free Software Foundation; either version 2.1 of
! 10: * the License, or (at your option) any later version.
! 11: *
! 12: * This program is distributed in the hope that it will be useful,
! 13: * but WITHOUT ANY WARRANTY; without even the implied warranty of
! 14: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
! 15: * GNU Lesser General Public License for more details.
! 16: *
! 17: * You should have received a copy of the GNU Lesser General Public
! 18: * License along with this program; if not, write to the Free
! 19: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
! 20: * 02111-1307 USA
! 21: *
! 22: * You may find a copy of the license under this software is released
! 23: * at COPYING file. This is LGPL software: you are welcome to
! 24: * develop proprietary applications using this library without any
! 25: * royalty or fee but returning back any change, improvement or
! 26: * addition in the form of source code, project image, documentation
! 27: * patches, etc.
! 28: *
! 29: * For commercial support on build XML enabled solutions contact us:
! 30: *
! 31: * Postal address:
! 32: * Advanced Software Production Line, S.L.
! 33: * Edificio Alius A, Oficina 102,
! 34: * C/ Antonio Suarez Nº 10,
! 35: * Alcalá de Henares 28802 Madrid
! 36: * Spain
! 37: *
! 38: * Email address:
! 39: * info@aspl.es - http://www.aspl.es/xml
! 40: */
! 41: #include <axl.h>
! 42:
! 43: /**
! 44: * \mainpage AXL: Another XML Library implementation (XML 1.0 standard)
! 45: *
! 46: * \section intro Introduction
! 47: *
! 48: * AXL is a library which aims to implement the XML 1.0 standard, as
! 49: * defined at the XML 1.0 third edition
! 50: * recommendation found at: http://www.w3.org/TR/REC-xml/.
! 51: *
! 52: * It was implemented to support XML requirements inside projects
! 53: * developed by <a href="http://www.aspl.es">Advanced Software
! 54: * Production Line, S.L.</a>, especially <a
! 55: * href="http://fact.aspl.es">Af-Arch</a> and <a
! 56: * href="http://vortex.aspl.es">Vortex Library</a>, which are already
! 57: * using the library successfully in production environments.
! 58: *
! 59: * Some features this library has are:
! 60: *
! 61: * <ul>
! 62: *
! 63: * <li><b>A clean implementation</b>, that only includes, those elements
! 64: * 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>
! 65: *
! 66: * <li><b>Fast and memory efficient</b> implementation. If you still
! 67: * think that XML is slow and memory inefficient, you didn't taste Axl
! 68: * Library. You'll find report about its performance and memory usage at: http://www.aspl.es/xml/doc.html </li>
! 69: *
! 70: * <li>Ensure that the library is implemented using abstract data types,
! 71: * commonly known as opaque types, to avoid exposing details to the
! 72: * user space code that is consuming the API.
! 73: * This will allow us to improve the library without breaking existing
! 74: * code and, the most important, to not be limited by details already
! 75: * exposed.
! 76: * In fact, this design have being already used to improve the library
! 77: * performance greatly. See reports founds at: http://www.aspl.es/xml/doc.html</a>.</li>
! 78: *
! 79: * <li><b>Small and efficient</b>, ensuring on every stable release that
! 80: * the library do not leak, not only while using the library in a
! 81: * proper manner but also when errors were found. </li>
! 82: *
! 83: * <li>Have a <b>modular</b> design that allows to use only those
! 84: * elements required by your software. At this moment it is provided a
! 85: * base library (with implements XML 1.0) and optional libraries that
! 86: * provides additional features to support XML Namespaces 1.0 and
! 87: * extended encodings.</li>
! 88: *
! 89: * <li>To have an <b>small footprint</b> is a requirement. Currently LibAxl (118K) and LibAxl-Ns (9K)</li>
! 90: *
! 91: * <li><b>Bindings</b> for other languages. At this moment it is officially supported <b>PyAxl</b>, a binding for the Python Language.</li>
! 92: * </ul>
! 93: *
! 94: * \section features_and_status What is the status of the library
! 95: *
! 96: * Currently the library is stable and it is known to work under
! 97: * 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.
! 98: *
! 99: * The library already covers the 95% of common requires that XML
! 100: * development needs. Among others, it support:
! 101: *
! 102: * - XML tree parsing, from memory and files, allowing a great level
! 103: * of detail while accessing to the data (comments, process
! 104: * instructions, xml nodes, and content).
! 105: *
! 106: * - Mostly completed DTD validation support, including <!ATTLIST>, <!ENTITY>
! 107: * and <!ELEMENT> elements. Remains to implement NOTATION declarations
! 108: * and full entity replacement.
! 109: *
! 110: * - Two modes to inspect the xml documents at the same time,
! 111: * <b>MIXED API</b>: an API to traverse the document allowing access
! 112: * to all items found (\ref axlItem) inside the document (\ref
! 113: * axlDoc) root node (\ref axlNode), and <b>CHILDREN API</b>: an API
! 114: * that allows to traverse the node using as reference only the nodes
! 115: * (\ref axlNode) inside the document (\ref axlDoc).
! 116: *
! 117: * - <a href="http://www.w3.org/TR/REC-xml-names/">XML 1.0
! 118: * Namespaces</a> full support, through the additional component
! 119: * (<b>libaxl-ns</b>), allowing to produce xml applications that are
! 120: * XML Namespace aware.
! 121: *
! 122: * - Support for extended encodings (<b>libaxl-babel</b>), beyond default encoding utf-8.
! 123: *
! 124: * \section documentation Library Documentation
! 125: *
! 126: * The library documentation is composed into two pieces. The Axl
! 127: * manual and the API documentation.
! 128: *
! 129: * - \ref axl_install
! 130: * - \ref axl_manual
! 131: * - \ref axl_api
! 132: * - \ref axl_knife_manual
! 133: *
! 134: * \section contact_us Contact us
! 135: *
! 136: * If you find something not properly documented, or some question is
! 137: * not answered on this documentation, check the <a href="http://www.aspl.es/axl/doc.html">mailing list</a>.
! 138: *
! 139: * You can also contact us if you have patches, improvements or
! 140: * suggestions at the mailing list.
! 141: */
! 142:
! 143: /**
! 144: * \page axl_manual XML development with Axl Library
! 145: *
! 146: * \section Manual Index
! 147: *
! 148: * On this manual you'll find the following section:
! 149: *
! 150: * <b>Section 1: Basic elements to understand XML and Axl </b><br>
! 151: *
! 152: * - \ref intro
! 153: * - \ref concepts
! 154: * - \ref two_apis
! 155: *
! 156: * <b>Section 2: Manipulating and producing XML documents </b><br>
! 157: *
! 158: * - \ref parsing
! 159: * - \ref iterating
! 160: * - \ref modifying
! 161: * - \ref dumping_functions
! 162: *
! 163: * <b>Section 3: Doing validation on your documents </b><br>
! 164: *
! 165: * - \ref validation
! 166: * - \ref xml_namespace
! 167: * - \ref using_axl_babel
! 168: *
! 169: * <b>Section 4: Advanced topics </b><br>
! 170: *
! 171: * - \ref reducing_foot_print
! 172: *
! 173: * <b>Apendix</b><br>
! 174: *
! 175: * - \ref futher
! 176: *
! 177: *
! 178: * \section intro Introduction: XML development
! 179: *
! 180: * XML 1.0 definition allows to build documents that could be used to
! 181: * represents textual information, remote procedure invocations or
! 182: * dynamic user interfaces. Its definition is based on very simple
! 183: * principles, that allows to developers to compose them to create
! 184: * bigger abstractions that are roughly on every place in modern
! 185: * computer software design.
! 186: *
! 187: * It is a "quite" human readable format, so you will find that is not
! 188: * the best format if you are looking for space efficiency. What XML
! 189: * 1.0 provides you on the other hand is the ability to quickly
! 190: * prototype and produce working formats that encapsulate your data,
! 191: * and, as your system evolves, XML 1.0 will do it with you.
! 192: *
! 193: * Among other things, XML 1.0 provides you ways to validate your
! 194: * documents to ensure your code will read XML documents in the format
! 195: * expected, reducing the time and development cost due to additional
! 196: * checkings required.
! 197: *
! 198: * Before continuing, we will explain some concepts that are required
! 199: * to understand XML 1.0 and why the Axl API was built this way.
! 200: *
! 201: * \section concepts Some concepts before starting to use Axl Library
! 202: *
! 203: * Here is a simple example of a XML 1.0 document:
! 204: * <div class="xml-doc">
! 205: * \code
! 206: * <?xml version="1.0">
! 207: * <!-- This is a comment -->
! 208: * <complex>
! 209: * <data>
! 210: * <simple>10</simple>
! 211: * <empty attr1="value1" />
! 212: * </data>
! 213: * </complex>
! 214: * \endcode
! 215: * </div>
! 216: *
! 217: * Previous XML document represents an structure with a top level
! 218: * node, called <b>complex</b>, that has one single child called
! 219: * <b>data</b> which in turn have two childs. The first one is the
! 220: * child called <b>simple</b> that have content and other one, called
! 221: * <b>empty</b>, which is a node usually called an empty xml node.
! 222: *
! 223: * The XML representation for previous document is the following:
! 224: * \image html image01.png "Document representation"
! 225: *
! 226: * Several issues must be considered while interpreting previous
! 227: * diagram and how Axl library parse and expose those elements through
! 228: * the API to the client application:
! 229: * <ul>
! 230: *
! 231: * <li>Every XML document have a root node (\ref axl_doc_get_root). Without exception. In this
! 232: * case, the root node for our example is <b>complex</b>. </li>
! 233: *
! 234: * <li>If a node have content, that content is not represented with
! 235: * another node. That content is associated to the node and could be
! 236: * retrieved using several function (\ref axl_node_get_content, \ref
! 237: * axl_node_get_content_copy and \ref
! 238: * axl_node_get_content_trans).
! 239: *
! 240: * Alternatively, while using the MIXED API, you can traverse child
! 241: * items stored for a particular node, detecting those items that are
! 242: * \ref ITEM_CONTENT or \ref ITEM_CDATA (using \ref
! 243: * axl_item_get_type). </li>
! 244: *
! 245: * <li>Having a node (\ref axlNode) with content doesn't mean to have a node with
! 246: * childs. The child notion is only about having more xml nodes (\ref axlNode) as
! 247: * childs.
! 248: *
! 249: * This is particularly important if you take into consideration that a
! 250: * node could have content (\ref ITEM_CONTENT), comments (\ref
! 251: * ITEM_COMMENT), application process instructions (\ref ITEM_PI),
! 252: * CDATA content (uninterpreted content \ref ITEM_CDATA), all of them
! 253: * mixed with more xml nodes (\ref ITEM_NODE). </li>
! 254: *
! 255: * <li>A final node which is empty because it doesn't have content or
! 256: * childs, is usually referred to as <b>EMPTY</b> type node. A final
! 257: * node with content but no childs is usually referred to as
! 258: * <b>PCDATA</b>. A node that have content mixed with references to
! 259: * more child xml nodes is referred to as <b>MIXED</b>.</li>
! 260: *
! 261: * <li>At the <b>empty</b> node, you'll find that it has an attribute
! 262: * called <b>attr1</b> with a value <b>value1</b>. A node could have
! 263: * any number of attributes but, it should be named
! 264: * differently. Again, if a node is empty, it keeps empty even if it
! 265: * has attributes.
! 266: * </li>
! 267: *
! 268: * So, to summarize, we have a root node, that could contain more
! 269: * nodes, that could contain PCDATA, or content, and those nodes could
! 270: * contain named attributes with values.
! 271: *
! 272: * \section two_apis MIXED and CHILDREN API: How to use them
! 273: *
! 274: * XML 1.0 is used for a variety of purposes, some of them requires
! 275: * the CHILDREN API and the rest the MIXED API. To <i>require</i>, we
! 276: * mean that it fits better, so you will get better results, your
! 277: * application will react in a proper manner and you'll have to do
! 278: * less work.
! 279: *
! 280: * The reason for this API is simple. XML 1.0 definition allows to mix
! 281: * content with more nodes, comments and many more elements to be
! 282: * placed as childs for a particular node.
! 283: *
! 284: * This definition, found at the standard, have moved many XML
! 285: * implementations to support only an API that support all these
! 286: * features, that is, an interface that is complicated and overloaded,
! 287: * that gives you a power that you don't require, making your
! 288: * development more inefficient.
! 289: *
! 290: * As a result, when a developer only requires a usual form of xml,
! 291: * called CHILDREN, that means nodes have only another childs
! 292: * nodes or content but not both at the same time. This kind of xml is
! 293: * really useful, easy to parse, easy to make a DTD definition, more
! 294: * compact and extensible.
! 295: *
! 296: * Lets see an example for both formats to clarify:
! 297: *
! 298: * <div class="xml-doc">
! 299: * \code
! 300: * <?xml version='1.0' ?>
! 301: * <document>
! 302: * <!-- Children XML format example: as you can see -->
! 303: * <!-- nodes only contains either nodes or node content -->
! 304: * <!-- but nothing mixed at the same level -->
! 305: * <node1>
! 306: * This is node1 content
! 307: * </node1>
! 308: * <node2>
! 309: * <node3>
! 310: * This is node3 content
! 311: * </node3>
! 312: * <node4 />
! 313: * </node2>
! 314: * </document>
! 315: * \endcode
! 316: * </div>
! 317: *
! 318: * While an MIXED xml document could be:
! 319: *
! 320: * <div class="xml-doc">
! 321: * \code
! 322: * <?xml version='1.0' ?>
! 323: * <document>
! 324: * <!-- Children XML format example: as you can see -->
! 325: * <!-- nodes only contains either nodes or node content -->
! 326: * <!-- but nothing mixed at the same level -->
! 327: * <node1>
! 328: * This is node1 content
! 329: * </node1>
! 330: * Content mixed with xml nodes at the same level.
! 331: * <node2>
! 332: * More content....
! 333: * <node3>
! 334: * This is node3 content
! 335: * </node3>
! 336: * <node4 />
! 337: * </node2>
! 338: * </document>
! 339: * \endcode
! 340: * </div>
! 341: *
! 342: * Both approaches, which are valid using the XML 1.0 standard, are
! 343: * appropriate for particular situations:
! 344: *
! 345: * - CHILDREN API: compact representations, configuration files, rpc
! 346: * invocation description, graphical user interface definition.
! 347: * - MIXED API: textual description, for example: XSL-FO.
! 348: *
! 349: * Having introduced the context of the problem, Axl Library takes no
! 350: * position, providing an API that fits while developing xml content
! 351: * that follows a CHILDREN description and an API for the MIXED
! 352: * description.
! 353: *
! 354: * In this context, which API you use, will only affect to the way you
! 355: * traverse the document. The CHILDREN API is mainly provided by the
! 356: * \ref axl_node_module "Axl Node interface" and the MIXED API is
! 357: * mainly provided by the \ref axl_item_module "Axl Item interface".
! 358: *
! 359: * You don't need to do any especial operation to activate both APIs,
! 360: * both are provided at the same time. Lets see an example:
! 361: *
! 362: * Supposing the previous mixed example, the following code will get
! 363: * access to the <node2> reference:
! 364: * \code
! 365: * // supposing "doc" reference contains the document loaded
! 366: * axlNode * node;
! 367: *
! 368: * // get the document root, that is <document>
! 369: * node = axl_doc_get_root (doc);
! 370: *
! 371: * // get the first child for the document root (<node1>)
! 372: * node = axl_node_get_first_child (node);
! 373: *
! 374: * // get the next child (brother of <node1>, that is <node2>)
! 375: * node = axl_node_get_next (node);
! 376: * \endcode
! 377: *
! 378: * However, with the MIXED API you can get every detail, every item
! 379: * found for a particular node. This is how:
! 380: *
! 381: * \code
! 382: * // supposing "doc" reference contains the document loaded
! 383: * axlNode * node;
! 384: * axlItem * item;
! 385: *
! 386: * // get the document root, that is <document>
! 387: * node = axl_doc_get_root (doc);
! 388: *
! 389: * // get the first item child for the document root that is the comment:
! 390: * // "Children XML format example: as you can see".
! 391: * item = axl_item_get_first_child (node);
! 392: *
! 393: * // now skip the following two comments
! 394: * item = axl_item_get_next (item);
! 395: * item = axl_item_get_next (item);
! 396: *
! 397: * // now the next item is holding the <node1>
! 398: * item = axl_item_get_next (item);
! 399: * node = axl_item_get_data (item);
! 400: *
! 401: * // now get the content between the <node1> and <node2>
! 402: * item = axl_item_get_next (item);
! 403: *
! 404: * // and finally, get the next child (brother of <node1>, that is
! 405: * // <node2>)
! 406: * item = axl_item_get_next (item);
! 407: * node = axl_item_get_data (item);
! 408: * \endcode
! 409: *
! 410: * Obviously, the mixed example contains more code and it is more
! 411: * fragile to xml document changes. The problem is that the MIXED API
! 412: * is more general than the CHILDREN, making XML libraries to only
! 413: * provide that API.
! 414: *
! 415: * As a consequence:
! 416: *
! 417: * - You only need to use the MIXED API (\ref axlItem) if you are
! 418: * going to do an xml application that allows having content mixed
! 419: * with nodes, comments, etc, and you want to get access to such
! 420: * content.
! 421: *
! 422: * - If you are planing to develop an XML solution that represents
! 423: * information (user interfaces), module descriptions, configuration
! 424: * files, etc, try to use the CHILDREN API: it will save you lot of
! 425: * work! Remember, CHILDREN xml format: childs are either content or
! 426: * more xml nodes but not both. Never mixed.
! 427: *
! 428: * \section parsing Parsing XML documents
! 429: *
! 430: * We have seen how an XML document is. Now we are going to see how to
! 431: * parse those document into data structures that are usable to
! 432: * inspect the content. All parsing functions are available at the
! 433: * \ref axl_doc_module "Axl Doc interface".
! 434: *
! 435: * Let's start with a very simple example:
! 436: *
! 437: * \code
! 438: * #include <axl.h>
! 439: * #include <stdio.h>
! 440: *
! 441: * int main (int argc, char ** argv)
! 442: * {
! 443: * axlError ** error;
! 444: *
! 445: * // top level definitions
! 446: * axlDoc * doc = NULL;
! 447: *
! 448: * // initialize axl library
! 449: * if (! axl_init ()) {
! 450: * printf ("Unable to initialize Axl library\n");
! 451: * return -1;
! 452: * }
! 453: *
! 454: * // get current doc reference
! 455: * doc = axl_doc_parse_from_file ("large.xml", error);
! 456: * if (doc == NULL) {
! 457: * axl_error_free (error);
! 458: * return axl_false;
! 459: * }
! 460: *
! 461: * // DO SOME WORK WITH THE DOCUMENT HERE
! 462: *
! 463: * // release the document
! 464: * axl_doc_free (doc);
! 465: *
! 466: * // cleanup axl library
! 467: * axl_end ();
! 468: *
! 469: * return axl_true;
! 470: * }
! 471: * \endcode
! 472: *
! 473: * \section iterating Traveling an XML document
! 474: *
! 475: * Once the document is loaded you can use several function to
! 476: * traverse the document.
! 477: *
! 478: * First you must use \ref axl_doc_get_root to get the document root
! 479: * (\ref axlNode) which contains all the information. Then, according
! 480: * to the interface you are using, you must call to either \ref
! 481: * axl_node_get_first_child or \ref axl_item_get_first_child.
! 482: *
! 483: * Once you have access to the first element, you can use the
! 484: * following set of function to get more references to other nodes or
! 485: * items:
! 486: *
! 487: * <ul>
! 488: * <li><b>MIXED API</b>:
! 489: *
! 490: * - \ref axl_item_get_first_child
! 491: * - \ref axl_item_get_last_child
! 492: * - \ref axl_item_get_next
! 493: * - \ref axl_item_get_previous
! 494: *
! 495: * </li>
! 496: * <li><b>CHILDREN API</b>:
! 497: *
! 498: * - \ref axl_node_get_first_child
! 499: * - \ref axl_node_get_last_child
! 500: * - \ref axl_node_get_next
! 501: * - \ref axl_node_get_previous
! 502: *
! 503: * </li>
! 504: * </ul>
! 505: *
! 506: * There are alternative APIs that will allow you to iterate the
! 507: * document, providing a callback: \ref axl_doc_iterate.
! 508: *
! 509: * Another approach is to use \ref axl_doc_get and \ref
! 510: * axl_doc_get_content_at to get fast access to a particular node
! 511: * using a really limited XPath syntax.
! 512: *
! 513: * \section modifying Modifying a loaded XML document
! 514: *
! 515: * One feature that comes with Axl Library is ability to modify the
! 516: * content, replacing it with other content and transferring node node
! 517: * to another place.
! 518: *
! 519: * Check the following function while operating with \ref axlNode elements:
! 520: *
! 521: * - \ref axl_node_replace
! 522: * - \ref axl_node_remove
! 523: * - \ref axl_node_transfer_childs
! 524: *
! 525: * Check the following functions while operating with \ref axlItem elements:
! 526: *
! 527: * - \ref axl_item_replace
! 528: * - \ref axl_item_remove
! 529: * - \ref axl_item_transfer_childs_after
! 530: *
! 531: * \section dumping_functions Producing xml documents from memory
! 532: *
! 533: * Axl Library comes with several functions to perform xml memory dump
! 534: * operations, allowing to translate a xml representation (\ref axlDoc
! 535: * or \ref axlNode) into a string:
! 536: *
! 537: * - \ref axl_doc_dump
! 538: * - \ref axl_doc_dump_pretty
! 539: * - \ref axl_doc_dump_to_file
! 540: * - \ref axl_doc_dump_pretty_to_file
! 541: *
! 542: * In the case you want to produce xml content taking as reference a
! 543: * particular node use:
! 544: *
! 545: * - \ref axl_node_dump
! 546: * - \ref axl_node_dump_pretty
! 547: * - \ref axl_node_dump_to_file
! 548: * - \ref axl_node_dump_pretty_to_file
! 549: *
! 550: * \section validation Validating XML documents
! 551: *
! 552: * Once you are familiar with the Axl API, or any other XML toolkit,
! 553: * it turns that it is not a good practice to write lot of source code
! 554: * to check node names expected or how they are nested. This makes
! 555: * your program really weak to changes and makes your to write more
! 556: * code that is not actual work but a simple environment check.
! 557: *
! 558: * You may also need to check that some XML document received follows
! 559: * a defined XML structure, but it is too complex to be done.
! 560: *
! 561: * For this purpose, XML 1.0 defines DTD or (Document Type Definition)
! 562: * which allows to specify the document grammar, how are nested
! 563: * nodes, which attributes could contain, or if the are allocated to
! 564: * be empty nodes or nodes that must have another child nodes.
! 565: *
! 566: * Let start with the DTD syntax used to configure restrictions about
! 567: * node structure:
! 568: *
! 569: * <div class="xml-doc">
! 570: * \code
! 571: * <!-- sequence specification -->
! 572: * <!ELEMENT testA (test1, test2, test3)>
! 573: *
! 574: * <!-- choice specification -->
! 575: * <!ELEMENT testB (test1 | test2 | test3)>
! 576: * \endcode
! 577: * </div>
! 578: *
! 579: *
! 580: * DTD <b><!ELEMENT</b> is modeled on top of two concepts which are
! 581: * later expanded with repetition patterns. We will explain then
! 582: * later. For now, this two top level concepts are: sequence and choice.
! 583: *
! 584: * Sequence specification (elements separated by <b>, (comma)</b>, the
! 585: * one used to apply restriction to the node <b>testA</b>, are used to
! 586: * denote that <b>testA</b> have as childs test1, followed by test2
! 587: * and ended by test3. The order specified must be followed and all
! 588: * instances must appear. This could be tweaked using repetition
! 589: * pattern.
! 590: *
! 591: * In the other hand, choice specification (elements separated by
! 592: * <b>| (pipe)</b>, are used to specify that the content of a node is
! 593: * built using nodes of the choice list. So, in this case,
! 594: * <b>testB</b> node could have either one instance of test1 or test2
! 595: * or test3.
! 596: *
! 597: * Now you know these to basic elements to model how childs are
! 598: * organized for a node, what it is need is to keep on adding more
! 599: * <!ELEMENT directives until all nodes are specified. You will end
! 600: * your DTD document with final nodes that are either empty ones or
! 601: * have PCDATA. At this moment MIXED nodes are not supported.
! 602: *
! 603: * Suppose that all nodes that are inside testA and testB are final
! 604: * ones. Then this could be its DTD specification:
! 605: *
! 606: * <div class="xml-doc">
! 607: * \code
! 608: * <!-- test1 is a node that only have content -->
! 609: * <!ELEMENT test1 (#PCDATA)>
! 610: *
! 611: * <!-- test2 is a node that is always empty -->
! 612: * <!ELEMENT test1 EMPTY>
! 613: *
! 614: * <!-- test3 is a node that could have either test1 or test2 -->
! 615: * <!ELEMENT test3 (test1 | test2)>
! 616: * \endcode
! 617: * </div>
! 618: *
! 619: * Sequences and choices could be composed to create richer DTD
! 620: * expressions that combines sequences of choices and so on.
! 621: *
! 622: * At this point all required elements to model choices, sequences and
! 623: * final nodes are explained, but, we have to talk about repetition
! 624: * pattern. They are symbols that are appended to elements inside
! 625: * choices (or sequences) including those list specifications.
! 626: *
! 627: * Patterns available are: <b>+</b>, <b>?</b> and <b>*</b>. By
! 628: * default, if no pattern is applied to the element, it means that the
! 629: * match should be produced one and only one time.
! 630: *
! 631: * The <b>+</b> pattern is used to model that element should be
! 632: * matched one, and at least one, or more.
! 633: *
! 634: * The <b>*</b> pattern is used to model elements that should be
! 635: * matched zero or any times.
! 636: *
! 637: * The <b>?</b> pattern is used to model elements that should be
! 638: * matched zero or one times.
! 639: *
! 640: * For the exampled initially explained, let's suppose we want that
! 641: * the content inside <b>testA</b> have sequences repeated at leat one
! 642: * time, being that sequence: test1, test2 and test3. We only need to
! 643: * add a <b>+</b> repetition pattern as follows:
! 644: *
! 645: * <div class="xml-doc">
! 646: * \code
! 647: * <!-- sequence specification -->
! 648: * <!ELEMENT testA (test1, test2, test3)+>
! 649: * \endcode
! 650: * </div>
! 651: *
! 652: * So, we are saying to our validation engine that the sequence inside
! 653: * testA could be found one or many times, but the entire sequence
! 654: * match be found every time.
! 655: *
! 656: * Here is an simple example that loads an XML document, then loads an
! 657: * DTD file, and then validates the XML document:
! 658: * \code
! 659: * bool test_12 (axlError ** error)
! 660: * {
! 661: * axlDoc * doc = NULL;
! 662: * axlDtd * dtd = NULL;
! 663: *
! 664: * // parse gmovil file (an af-arch xml chunk)
! 665: * doc = axl_doc_parse_from_file ("channel.xml", error);
! 666: * if (doc == NULL)
! 667: * return axl_false;
! 668: *
! 669: * // parse af-arch DTD
! 670: * dtd = axl_dtd_parse_from_file ("channel.dtd", error);
! 671: * if (dtd == NULL)
! 672: * return axl_false;
! 673: *
! 674: * // perform DTD validation
! 675: * if (! axl_dtd_validate (doc, dtd, error)) {
! 676: * return axl_false;
! 677: * }
! 678: *
! 679: * // free doc reference
! 680: * axl_doc_free (doc);
! 681: *
! 682: * // free dtd reference
! 683: * axl_doc_free (dtd);
! 684: *
! 685: * return axl_true;
! 686: * }
! 687: * \endcode
! 688: *
! 689: * Until now, we have seen how to check xml structure. But this do not
! 690: * cover xml node attributes. This is checked by using
! 691: * <b><!ATTLIST></b> declaration.
! 692: *
! 693: * In the case we have a node <b>testA</b> with two attribuets
! 694: * <b>attr1</b> and <b>attr2</b> the first one optional and the second
! 695: * one mandatory, we can declare something like:
! 696: *
! 697: * <div class="xml-doc">
! 698: * \code
! 699: * <!-- attribute validation for node testA -->
! 700: * <!ATTLIST testA
! 701: * attr1 CDATA #IMPLIED
! 702: * attr2 CDATA #REQUIRED>
! 703: * \endcode
! 704: * </div>
! 705: *
! 706: *
! 707: * \section xml_namespace Enabling your software with XML Namespaces
! 708: *
! 709: * XML 1.0 initial design didn't take care about situations where
! 710: * several software vendors could introduce content inside the same
! 711: * XML documents. This has several benefits, but one problem to solve:
! 712: * <i>how to avoid xml node names (tags) to clash from each other.</i>
! 713: *
! 714: * Think about using <table> as a tag for your document. Many XML
! 715: * applications uses <table> as a valid tag for its XML language
! 716: * set. However, each of them has a different meaning and must be
! 717: * handled by the proper XML software.
! 718: *
! 719: * While developing applications with XML, and supposing such XML
! 720: * documents will be used by more applications than yours, you are
! 721: * likely to be interested in use XML Namespaces. In other words, many
! 722: * of the new XML standards that are appearing uses XML Namespaces to
! 723: * allow defining its xml node names, while allowing users/developers
! 724: * to use their own set of xml tags, under their own XML Namespaces,
! 725: * in order they can use them in the same document.
! 726: *
! 727: * XML Namespaces support inside Axl Library is handled through a
! 728: * separated library, which requires the base library to function. \ref axl_install "Here are some instructions to get Axl Library Namespace installed."
! 729: *
! 730: * This library provides functions that replaces some of the functions
! 731: * used by XML applications that don't require XML Namespaces. In
! 732: * particular, some of them are:
! 733: *
! 734: * - \ref axl_ns_doc_validate (see this for an example)
! 735: * - \ref axl_ns_node_cmp
! 736: *
! 737: * See also API documentation for all functions that are provided to
! 738: * enable your application with XML Namespaces:
! 739: *
! 740: * - \ref axl_ns_doc_module
! 741: * - \ref axl_ns_node_module
! 742: *
! 743: * \section using_axl_babel Making your software to support other encodings than UTF-8
! 744: *
! 745: * Default axl library implementation (libaxl) assumes it will receive
! 746: * and produce UTF-8 content.
! 747: *
! 748: * Because the subset of characters that are used to properly parse
! 749: * XML content are located in the ASCII range, still valid UTF-8, but
! 750: * at same time valid in other encodings such ISO 646, some part of
! 751: * ISO 8859, Shift-JIS, EUC, or any other 7-bit, 8-bit, or mixed-width
! 752: * encoding which ensures that the characters of ASCII have their
! 753: * normal positions, width, and values (See section F. Autodetecting
! 754: * of Character Encodings at http://www.w3.org/TR/REC-xml/), causes
! 755: * the library to properly parse the content, even if it is not UTF-8.
! 756: *
! 757: * In many cases this is not important for you since your application
! 758: * do not care about content codification (such configuration files)
! 759: * or they are in UTF-8.
! 760: *
! 761: * However, this could present problems if you are handling different
! 762: * documents with several encoding types. The idea is to have an
! 763: * unified way to handle such different encoded documents, with a
! 764: * single, run-time encoding: UTF-8.
! 765: *
! 766: * <b>libaxl-babel</b> provides support to read content in supported
! 767: * codifications and translate it into UTF-8 at run-time (checking
! 768: * result to be valid UTF-8):
! 769: *
! 770: * \image html axl_babel_reading.png "Reading documents and handle them as they were in UTF-8"
! 771: *
! 772: * The library works as an extension that configures a set of handlers
! 773: * making the library to open XML documents and translating them into
! 774: * UTF-8 if required.
! 775: *
! 776: * To activate the library, you must use \ref axl_babel_init at the
! 777: * begining of your application or library. Here is an example:
! 778: *
! 779: * \code
! 780: * // optional axlError declaration
! 781: * axlError * error;
! 782: *
! 783: * // init axl babel
! 784: * if (! axl_babel_init (&error)) {
! 785: * printf ("Failed to start axl babel: %s...\n",
! 786: * axl_error_get (error));
! 787: * axl_error_free (error);
! 788: * return axl_false;
! 789: * }
! 790: * \endcode
! 791: *
! 792: * Once done, every call to the base API (such \ref axl_doc_parse,
! 793: * \ref axl_doc_parse_from_file) will open the document as usual. It
! 794: * is not required to perform any additional special operation.
! 795: *
! 796: * It is not required to call to \ref axl_babel_finish on application
! 797: * exit. However, in the case you want to deactivate
! 798: * <b>libaxl-babel</b> but still keep on using axl base library, you
! 799: * can use \ref axl_babel_finish.
! 800: *
! 801: * See \ref axl_babel_init for currently supported formats.
! 802: *
! 803: * \section reducing_foot_print How to reduce the library footprint
! 804: *
! 805: * Axl Library is implemented in a modular way to ensure you are only
! 806: * linked against those software elements that you really
! 807: * require. Additionally, the library allows the following to reduce
! 808: * the library footprint to the minimum:
! 809: *
! 810: * <ul>
! 811: * <li><b>Remove log information:</b> <br> Axl library uses a console log
! 812: * mechanism to report what's happening during processing. See \ref
! 813: * axl_log_module "Axl Log reporting" module for more
! 814: * information. However, under production environments this console
! 815: * log isn't necessary, so you can safely remove it, at compile time,
! 816: * using <b>--axl-log-disable</b> as follow:
! 817: *
! 818: * \code
! 819: * >> ./configure --axl-log-disable
! 820: * \endcode
! 821: *
! 822: * According to our results, the library including the log to console
! 823: * information is about <b>366K</b>. Without log to console information the
! 824: * library takes about <b>288K</b>.
! 825: *
! 826: * </li>
! 827: *
! 828: * <li><b>Remove debugging information from the library: </b> <br>You
! 829: * can also remove debugging information from your library on
! 830: * production environments doing the following once finished compilation process:
! 831: *
! 832: * \code
! 833: * >> make install-strip
! 834: * \endcode
! 835: *
! 836: * According to our results, the library without log to console and
! 837: * debugging information takes about <b>100K</b>.
! 838: *
! 839: * </li>
! 840: * </ul>
! 841: *
! 842: * Previous information applies to the Axl base Library
! 843: * (libaxl.so/.dll), however the same happens for the rest of software
! 844: * components bundle with Axl.
! 845: *
! 846: *
! 847: * \section futher Futher reading where to go for more information
! 848: *
! 849: * You can also check \ref axl_api "API documentation" for a complete
! 850: * detailed explanation about the library.
! 851: *
! 852: * Please, if you find that something isn't properly documented or you
! 853: * think that something could be improved, contact us in the mailing
! 854: * list. We are building Axl Library with the aim to produce a high
! 855: * quality, commercial grade, open source XML development kit, so, any
! 856: * help received will be welcome.
! 857: *
! 858: * Remember you can always contact us at the mailing list for any
! 859: * question not properly answered by this documentation. See <a
! 860: * href="http://www.aspl.es/axl/doc.html">Axl Library website
! 861: * documentation</a> to get more
! 862: * information about mailing list.
! 863: *
! 864: */
! 865:
! 866: /**
! 867: * \page axl_api LibAxl API documentation
! 868: *
! 869: * Here is the API for the modules defined inside the library:
! 870: *
! 871: * <ul>
! 872: * <li><b>Basic API to interact with XML documents (base library libaxl): </b></li>
! 873: *
! 874: * - \ref axl_module
! 875: * - \ref axl_doc_module
! 876: * - \ref axl_node_module
! 877: * - \ref axl_node_attribute_cursor
! 878: * - \ref axl_node_annotate
! 879: * - \ref axl_item_module
! 880: * - \ref axl_dtd_module
! 881: * - \ref axl_decl_module
! 882: * - \ref axl_handlers
! 883: *
! 884: * </li>
! 885: * <li><b>XML Namespaces API (required additional library libaxl-ns): </b></li>
! 886: *
! 887: * - \ref axl_ns_doc_module
! 888: * - \ref axl_ns_node_module
! 889: *
! 890: * </li>
! 891: * <li><b>Axl BABEL API (required to support additional encoding formats): </b></li>
! 892: *
! 893: * - \ref axl_babel
! 894: *
! 895: * </li>
! 896: * <li><b>Error reporting and debugging functions (base library libaxl): </b></li>
! 897: *
! 898: * - \ref axl_error_module
! 899: * - \ref axl_log_module
! 900: *
! 901: * <li><b>Auxiliary modules, supporting data types, string handling, etc (base library libaxl):</b></li>
! 902: *
! 903: * - \ref axl_stream_module
! 904: * - \ref axl_list_module
! 905: * - \ref axl_list_cursor_module
! 906: * - \ref axl_stack_module
! 907: * - \ref axl_binary_stack_module
! 908: * - \ref axl_hash_module
! 909: * - \ref axl_hash_cursor_module
! 910: * - \ref axl_string_module
! 911: *
! 912: * </li>
! 913: * </ul>
! 914: *
! 915: */
! 916:
! 917: /**
! 918: * @page axl_install Installing Axl library and using it
! 919: *
! 920: * \section intro Introduction
! 921: *
! 922: * Axl library is an XML library written in ANSI C, which is known to
! 923: * work on Microsoft Windows, GNU/Linux, *-BSD, GNU/Linux under
! 924: * Amd64/Itanium and MacOS/X platforms.
! 925: *
! 926: * The library package is composed by the following items:
! 927: *
! 928: * \image html axl-components.png "Axl library components"
! 929: *
! 930: * - <b>libaxl</b>: base library implementing all XML functions, and
! 931: * common API used by extension libraries. It has no external
! 932: * dependencies.
! 933: *
! 934: * - <b>libaxl-ns</b>: optional library, built on top of libaxl, which
! 935: * provides Namespaces support. It depends on libaxl.
! 936: *
! 937: * - <b>libaxl-babel</b>: optional library, built on top of libaxl,
! 938: * which provides extended encoding support to defult utf-8.
! 939: *
! 940: * - <b>axl-knife</b>: command line tool, built on top of libaxl and
! 941: * libaxl-ns. It depends on the base library and the namespace
! 942: * library.
! 943: *
! 944: * Here are a set of instructions to get the library compiled for your
! 945: * platform:
! 946: *
! 947: * \section axl_on_unix GNU/Linux (or any posix OS) installation instructions
! 948: *
! 949: * First, download the package from the download section. Check <a
! 950: * href="http://www.aspl.es/axl/doc.html">this section to know more
! 951: * about this.</a>
! 952: *
! 953: * Then use the standard procedure to get compiled an autotool ready
! 954: * package. Here are the steps:
! 955: *
! 956: * \code
! 957: * >> tar xzvf axl-0.2.1.b1984.g1985.tar.gz
! 958: * >> cd axl-0.2.1.b1984.g1985/
! 959: * >> ./configure
! 960: * >> make
! 961: * >> make install
! 962: * \endcode
! 963: *
! 964: * \section checking_axl Checking Axl Library compilation (regression test)
! 965: *
! 966: * Once finished, to check your axl build to properly work, get inside
! 967: * the test/ directory and run axl regression test (test_01):
! 968: * \code
! 969: * >> cd test/
! 970: * >> ./test_01
! 971: * \endcode
! 972: *
! 973: * All test must execute properly to ensure the library is fully functional.
! 974: *
! 975: * \section windows Windows installation instructions
! 976: *
! 977: * Axl library comes with packages already built for Microsoft Windows platforms.
! 978: * Check <a href="http://www.aspl.es/axl/doc.html">the download section to get them</a>.
! 979: *
! 980: * \section using Using LibAxl library (installations with pkg-config infrastructure)
! 981: *
! 982: * Axl Library is composed by a base library, which provides all XML
! 983: * 1.0 function. Additionally, a separated library is provided for
! 984: * Namespace functions.
! 985: *
! 986: * Axl library comes with pkg-config support, which makes easy to use
! 987: * it inside your pkg-config enable projects.
! 988: *
! 989: * To check current support for your Axl Library you can execute:
! 990: *
! 991: * \code
! 992: * >> pkg-config --libs --cflags axl
! 993: * \endcode
! 994: *
! 995: * To give support for XML Namespaces (libaxl-ns), you must use:
! 996: * \code
! 997: * >> pkg-config --libs --cflags axl-ns
! 998: * \endcode
! 999: *
! 1000: * To give support for extended encoding support (libaxl-babel), you must use:
! 1001: * \code
! 1002: * >> pkg-config --libs --cflags axl-babel
! 1003: * \endcode
! 1004: *
! 1005: * To include support into your autotool checks (configure.ac/in
! 1006: * files) you can place the following piece:
! 1007: * \code
! 1008: * PKG_CHECK_MODULES(LIBRARIES, axl)
! 1009: * \endcode
! 1010: *
! 1011: * Again, add <b>axl-ns</b> or <b>axl-babel</b> to the previous
! 1012: * instruction if you want your package to also check for Axl Library
! 1013: * Namespace support.
! 1014: *
! 1015: * \section Including Axl Library headers
! 1016: *
! 1017: * For all platforms, Axl Library base headers has to be included as follows:
! 1018: * \code
! 1019: * #include <axl.h>
! 1020: * \endcode
! 1021: *
! 1022: * In the case Namespace is required, you must use:
! 1023: * \code
! 1024: * #include <axl_ns.h>
! 1025: * \endcode
! 1026: *
! 1027: * To include babel support, you must use:
! 1028: * \code
! 1029: * #include <axl_babel.h>
! 1030: * \endcode
! 1031: */
! 1032:
! 1033:
! 1034: /**
! 1035: * \defgroup axl_module Axl main: Init functions for the library
! 1036: */
! 1037:
! 1038: /**
! 1039: * \addtogroup axl_module
! 1040: * @{
! 1041: */
! 1042:
! 1043: /**
! 1044: * @brief Initializes Axl library.
! 1045: *
! 1046: * Currently this function is not required to be executed because
! 1047: * libaxl implementation don't use it. The implementation will try to
! 1048: * make no used for internal variable initialization.
! 1049: *
! 1050: * However the API is provided for future usage.
! 1051: *
! 1052: * @return The function returns \ref axl_true if it was properly
! 1053: * initialized or \ref axl_false if something fails. if fails.
! 1054: */
! 1055: axl_bool axl_init (void)
! 1056: {
! 1057: /* nothing to initialize dude */
! 1058: return axl_true;
! 1059: }
! 1060:
! 1061: /**
! 1062: * @brief Allows to terminate libaxl library function.
! 1063: *
! 1064: * Currently this function is not required becasue nothing is done to
! 1065: * stop libaxl function. The implementation will try to keep this,
! 1066: * however, if the future this could be required.
! 1067: */
! 1068: void axl_end (void)
! 1069: {
! 1070: /* nothing to do jack */
! 1071: return;
! 1072: }
! 1073:
! 1074: /* @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axl.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / src