<p>Mini-XML is a small XML parsing library that you can use to read XML data files or strings in your application without requiring large non-standard libraries. Mini-XML provides the following functionality:</p>
<ul>
<li>Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and strings.</li>
@ -314,7 +304,7 @@ h3.title {
<li>"Find" and "walk" functions for easily locating and navigating trees of data.</li>
</ul>
<p>Mini-XML doesn't do validation or other types of processing on the data based upon schema files or other sources of definition information.</p>
<h3><aid="history">History</a></h3>
<h3class="title"id="history">History</h3>
<p>Mini-XML was initially developed for the <ahref="http://gutenprint.sf.net/">Gutenprint</a> project to replace the rather large and unwieldy <code>libxml2</code> library with something substantially smaller and easier-to-use. It all began one morning in June of 2003 when Robert posted the following sentence to the developer's list:</p>
<blockquote>
<p>It's bad enough that we require libxml2, but rolling our own XML parser is a bit more than we can handle.</p>
@ -325,14 +315,14 @@ h3.title {
</blockquote>
<p>I took my own challenge and coded furiously for two days to produced the initial public release of Mini-XML, total lines of code: 696. Robert promptly integrated Mini-XML into Gutenprint and removed libxml2.</p>
<p>Thanks to lots of feedback and support from various developers, Mini-XML has evolved since then to provide a more complete XML implementation and now stands at a whopping 4,115 lines of code, compared to 140,410 lines of code for libxml2 version 2.9.1.</p>
<h3><aid="resources">Resources</a></h3>
<h3class="title"id="resources">Resources</h3>
<p>The Mini-XML home page can be found at:</p>
<pre><code>https://www.msweet.orgm/mxml
</code></pre>
<p>From here you can download the current version of Mini-XML, the issue tracker, and other resources.</p>
<h3><aid="legal-stuff">Legal Stuff</a></h3>
<h3class="title"id="legal-stuff">Legal Stuff</h3>
<p>The Mini-XML library is copyright © 2003-2019 by Michael R Sweet and is provided under the Apache License Version 2.0 with an exception to allow linking against GPL2/LGPL2-only software. See the files "LICENSE" and "NOTICE" for more information.</p>
<p>Mini-XML provides a single header file which you include:</p>
<pre><code>#include <mxml.h>
</code></pre>
@ -342,7 +332,7 @@ h3.title {
<p>If you have the <code>pkg-config</code> software installed, you can use it to determine the proper compiler and linker options for your installation:</p>
<h3><aid="loading-an-xml-file">Loading an XML File</a></h3>
<h3class="title"id="loading-an-xml-file">Loading an XML File</h3>
<p>You load an XML file using the <code>mxmlLoadFile</code> function:</p>
<pre><code>mxml_node_t *
mxmlLoadFile(mxml_node_t *top, FILE *fp,
@ -365,7 +355,7 @@ mxml_node_t *
mxmlLoadString(mxml_node_t *top, const char *s,
mxml_type_t (*cb)(mxml_node_t *));
</code></pre>
<h4><aid="load-callbacks">Load Callbacks</a></h4>
<h4id="load-callbacks">Load Callbacks</h4>
<p>The last argument to the <code>mxmlLoad</code> functions is a callback function which is used to determine the value type of each data node in an XML document. Mini-XML defines several standard callbacks for simple XML data files:</p>
<ul>
<li><code>MXML_INTEGER_CALLBACK</code>: All data nodes contain whitespace-separated integers.</li>
<p>Every piece of information in an XML file is stored in memory in "nodes". Nodes are defined by the <code>mxml_node_t</code> structure. Each node has a typed value, optional user data, a parent node, sibling nodes (previous and next), and potentially child nodes.</p>
<p>For example, if you have an XML file like the following:</p>
where "-" is a pointer to the sibling node and "" is a pointer to the first <p>child or parent node.</p>
<p>where "-" is a pointer to the sibling node and "|" is a pointer to the first child or parent node.</p>
<p>The <code>mxmlGetType</code> function gets the type of a node:</p>
<pre><code>mxml_type_t
mxmlGetType(mxml_node_t *node);
</code></pre>
<ul>
<li><code>MXML_CUSTOM</code> : A custom value defined by your application,</li>
<li><code>MXML_ELEMENT</code> : An XML element, CDATA, comment, or processing instruction,</li>
<li><code>MXML_INTEGER</code> : A whitespace-delimited integer value,</li>
<li><code>MXML_OPAQUE</code> : An opaque string value that preserves all whitespace,</li>
<li><code>MXML_REAL</code> : A whitespace-delimited floating point value, or</li>
<li><code>MXML_TEXT</code> : A whitespace-delimited text (fragment) value.</li>
</ul>
<blockquote>
<p>Note: CDATA, comment, and processing directive nodes are currently stored in memory as special elements. This will be changed in a future major release of Mini-XML.</p>
<h3><aid="creating-xml-documents">Creating XML Documents</a></h3>
<h3class="title"id="creating-xml-documents">Creating XML Documents</h3>
<p>You can create and update XML documents in memory using the various <code>mxmlNew</code> functions. The following code will create the XML document described in the previous section:</p>
@ -508,7 +506,7 @@ data = mxmlNewElement(xml, "data");
mxmlNewText(node, 0, "val1");
</code></pre>
<p>The resulting in-memory XML document can then be saved or processed just like one loaded from disk or a string.</p>
<h3><aid="saving-an-xml-file">Saving an XML File</a></h3>
<h3class="title"id="saving-an-xml-file">Saving an XML File</h3>
<p>You save an XML file using the <code>mxmlSaveFile</code> function:</p>
<pre><code>int
mxmlSaveFile(mxml_node_t *node, FILE *fp,
@ -532,7 +530,7 @@ int
mxmlSaveString(mxml_node_t *node, char *buffer, int bufsize,
mxml_save_cb_t cb);
</code></pre>
<h4><aid="controlling-line-wrapping">Controlling Line Wrapping</a></h4>
<h4id="controlling-line-wrapping">Controlling Line Wrapping</h4>
<p>When saving XML documents, Mini-XML normally wraps output lines at column 75 so that the text is readable in terminal windows. The <code>mxmlSetWrapMargin</code> function overrides the default wrap margin for the current thread:</p>
<pre><code>void mxmlSetWrapMargin(int column);
</code></pre>
@ -542,7 +540,7 @@ mxmlSaveString(mxml_node_t *node, char *buffer, int bufsize,
<p>while the following code disables wrapping by setting the margin to 0:</p>
<pre><code>mxmlSetWrapMargin(0);
</code></pre>
<h4><aid="save-callbacks">Save Callbacks</a></h4>
<h4id="save-callbacks">Save Callbacks</h4>
<p>The last argument to the <code>mxmlSave</code> functions is a callback function which is used to automatically insert whitespace in an XML document. Your callback function will be called up to four times for each element node with a pointer to the node and a "where" value of <code>MXML_WS_BEFORE_OPEN</code>, <code>MXML_WS_AFTER_OPEN</code>, <code>MXML_WS_BEFORE_CLOSE</code>, or <code>MXML_WS_AFTER_CLOSE</code>. The callback function should return <code>NULL</code> if no whitespace should be added or the string to insert (spaces, tabs, carriage returns, and newlines) otherwise.</p>
<p>The following whitespace callback can be used to add whitespace to XHTML output to make it more readable in a standard text editor:</p>
<p>Once you are done with the XML data, use the <code>mxmlDelete</code> function to recursively free the memory that is used for a particular node or the entire tree:</p>
<pre><code>void
mxmlDelete(mxml_node_t *tree);
</code></pre>
<p>You can also use reference counting to manage memory usage. The <code>mxmlRetain</code> and <code>mxmlRelease</code> functions increment and decrement a node's use count, respectively. When the use count goes to zero, <code>mxmlRelease</code> automatically calls <code>mxmlDelete</code> to actually free the memory used by the node tree. New nodes start with a use count of 1.</p>
<h2><aid="more-about-nodes">More About Nodes</a></h2>
<h3><aid="element-nodes">Element Nodes</a></h3>
<h2class="title"id="more-about-nodes">More About Nodes</h2>
<p>Element (<code>MXML_ELEMENT</code>) nodes are created using the <code>mxmlNewElement</code> function. Element attributes are set using the <code>mxmlElementSetAttr</code> and <code>mxmlElementSetAttrf</code> functions and cleared using the <code>mxmlElementDeleteAttr</code> function:</p>
<p>Because comments are currently stored as element nodes, comment (<code>MXML_ELEMENT</code>) nodes are created using the <code>mxmlNewElement</code> function by including the surrounding "!--" and "--" characters in the element name, for example:</p>
<pre><code>mxml_node_t *node = mxmlNewElement("!-- This is a comment --");
<p>Because processing instructions are currently stored as element nodes, processing instruction (<code>MXML_ELEMENT</code>) nodes are created using the <code>mxmlNewElement</code> function including the surrounding "?" characters:</p>
<p>Whitespace-delimited text string (<code>MXML_TEXT</code>) nodes are created using the <code>mxmlNewText</code> and <code>mxmlNewTextf</code> functions. Each text node consists of a text string and (leading) whitespace flag value.</p>
<pre><code>mxml_node_t *
mxmlNewText(mxml_node_t *parent, int whitespace,
@ -713,7 +711,7 @@ mxmlNewTextf(mxml_node_t *parent, int whitespace,
<pre><code> const char *
mxmlGetText(mxml_node_t *node, int *whitespace);
</code></pre>
<h3><aid="real-number-nodes">Real Number Nodes</a></h3>
<h3class="title"id="real-number-nodes">Real Number Nodes</h3>
<p>Real number (<code>MXML_REAL</code>) nodes are created using the <code>mxmlNewReal</code> function:</p>
<li><code>MXML_DESCEND_FIRST</code>: start the search with the first child of the node, and then search siblings. You'll normally use this when iterating through direct children of a parent node, e.g. all of the "node" and "group" elements under the "?xml" parent node in the previous example.</li>
<li><code>MXML_DESCEND</code>: search child nodes first, then sibling nodes, and then parent nodes.</li>
<p>While the <code>mxmlFindNode</code> and <code>mxmlFindPath</code> functions will find a particular element node, sometimes you need to iterate over all nodes. The <code>mxmlWalkNext</code> and <code>mxmlWalkPrev</code> functions can be used to iterate through the XML node tree:</p>
<pre><code>mxml_node_t *
mxmlWalkNext(mxml_node_t *node, mxml_node_t *top,
@ -821,7 +819,7 @@ val7
<node>
val8
</code></pre>
<h3><aid="indexing">Indexing</a></h3>
<h3class="title"id="indexing">Indexing</h3>
<p>The <code>mxmlIndexNew</code> function allows you to create an index of nodes for faster searching and enumeration:</p>
<h2><aid="custom-data-types">Custom Data Types</a></h2>
<h2class="title"id="custom-data-types">Custom Data Types</h2>
<p>Mini-XML supports custom data types via per-thread load and save callbacks. Only a single set of callbacks can be active at any time for the current thread, however your callbacks can store additional information in order to support multiple custom data types as needed. The <code>MXML_CUSTOM</code> node type identifies custom data nodes.</p>
<p>The <code>mxmlGetCustom</code> function retrieves the custom value pointer for a node.</p>
<pre><code>const void *
@ -996,7 +994,7 @@ save_custom(mxml_node_t *node)
<p>You register the callback functions using the <code>mxmlSetCustomHandlers</code> function:</p>
<h2><aid="sax-stream-loading-of-documents">SAX (Stream) Loading of Documents</a></h2>
<h2class="title"id="sax-stream-loading-of-documents">SAX (Stream) Loading of Documents</h2>
<p>Mini-XML supports an implementation of the Simple API for XML (SAX) which allows you to load and process an XML document as a stream of nodes. Aside from allowing you to process XML documents of any size, the Mini-XML implementation also allows you to retain portions of the document in memory for later processing.</p>
<p>The <code>mxmlSAXLoadFd</code>, <code>mxmlSAXLoadFile</code>, and <code>mxmlSAXLoadString</code> functions provide the SAX loading APIs:</p>
Michael R Sweet
5 years ago