mirror of
https://github.com/michaelrsweet/mxml.git
synced 2024-11-17 08:25:31 +00:00
442 lines
18 KiB
HTML
442 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Mini-XML Programmers Manual, Version 2.5</TITLE>
|
|
<META NAME="author" CONTENT="Michael R. Sweet">
|
|
<META NAME="copyright" CONTENT="Copyright 2003-2008">
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-iso-8859-1">
|
|
<LINK REL="Start" HREF="index.html">
|
|
<LINK REL="Contents" HREF="index.html">
|
|
<LINK REL="Prev" HREF="install.html">
|
|
<LINK REL="Next" HREF="advanced.html">
|
|
<STYLE TYPE="text/css"><!--
|
|
BODY { font-family: sans-serif }
|
|
H1 { font-family: sans-serif }
|
|
H2 { font-family: sans-serif }
|
|
H3 { font-family: sans-serif }
|
|
H4 { font-family: sans-serif }
|
|
H5 { font-family: sans-serif }
|
|
H6 { font-family: sans-serif }
|
|
SUB { font-size: smaller }
|
|
SUP { font-size: smaller }
|
|
PRE { font-family: monospace }
|
|
A { text-decoration: none }
|
|
--></STYLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="index.html">Contents</A>
|
|
<A HREF="install.html">Previous</A>
|
|
<A HREF="advanced.html">Next</A>
|
|
<HR NOSHADE>
|
|
<H1 align="right"><A name="BASICS"><IMG align="right" alt="2" height="100"
|
|
hspace="10" src="2.gif" width="100"></A>Getting Started with Mini-XML</H1>
|
|
<P>This chapter describes how to write programs that use Mini-XML to
|
|
access data in an XML file. Mini-XML provides the following
|
|
functionality:</P>
|
|
<UL>
|
|
<LI>Functions for creating and managing XML documents in memory.</LI>
|
|
<LI>Reading of UTF-8 and UTF-16 encoded XML files and strings.</LI>
|
|
<LI>Writing of UTF-8 encoded XML files and strings.</LI>
|
|
<LI>Support for arbitrary element names, attributes, and attribute
|
|
values with no preset limits, just available memory.</LI>
|
|
<LI>Support for integer, real, opaque ("cdata"), and text data types in
|
|
"leaf" nodes.</LI>
|
|
<LI>"Find", "index", and "walk" functions for easily accessing data in
|
|
an XML document.</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, nor does it support character entities other than those
|
|
required by the XML specification.</P>
|
|
<H2><A NAME="3_1">The Basics</A></H2>
|
|
<P>Mini-XML provides a single header file which you include:</P>
|
|
<PRE>
|
|
#include <mxml.h>
|
|
</PRE>
|
|
<P>The Mini-XML library is included with your program using the <KBD>
|
|
-lmxml</KBD> option:</P>
|
|
<PRE>
|
|
<KBD>gcc -o myprogram myprogram.c -lmxml ENTER</KBD>
|
|
</PRE>
|
|
<P>If you have the <TT>pkg-config(1)</TT> software installed, you can
|
|
use it to determine the proper compiler and linker options for your
|
|
installation:</P>
|
|
<PRE>
|
|
<KBD>pkg-config --cflags mxml ENTER</KBD>
|
|
<KBD>pkg-config --libs mxml ENTER</KBD>
|
|
</PRE>
|
|
<H2><A NAME="3_2">Nodes</A></H2>
|
|
<P>Every piece of information in an XML file (elements, text, numbers)
|
|
is stored in memory in "nodes". Nodes are defined by the <A href="reference.html#mxml_node_t">
|
|
<TT>mxml_node_t</TT></A> structure. The <A href="#mxml_type_t"><TT>type</TT>
|
|
</A> member defines the node type (element, integer, opaque, real, or
|
|
text) which determines which value you want to look at in the <A href="reference.html#mxml_value_t">
|
|
<TT>value</TT></A> union.</P>
|
|
|
|
<!-- NEED 10 -->
|
|
<CENTER>
|
|
<TABLE border="1" cellpadding="5" cellspacing="0" summary="Mini-XML Node Value Members"
|
|
width="80%"><CAPTION align="bottom"><I> Table 2-1: Mini-XML Node Value
|
|
Members</I></CAPTION>
|
|
<TR bgcolor="#cccccc"><TH>Value</TH><TH>Type</TH><TH>Node member</TH></TR>
|
|
<TR><TD>Custom</TD><TD><TT>void *</TT></TD><TD><TT>
|
|
node->value.custom.data</TT></TD></TR>
|
|
<TR><TD>Element</TD><TD><TT>char *</TT></TD><TD><TT>
|
|
node->value.element.name</TT></TD></TR>
|
|
<TR><TD>Integer</TD><TD><TT>int</TT></TD><TD><TT>node->value.integer</TT>
|
|
</TD></TR>
|
|
<TR><TD>Opaque (string)</TD><TD><TT>char *</TT></TD><TD><TT>
|
|
node->value.opaque</TT></TD></TR>
|
|
<TR><TD>Real</TD><TD><TT>double</TT></TD><TD><TT>node->value.real</TT></TD>
|
|
</TR>
|
|
<TR><TD>Text</TD><TD><TT>char *</TT></TD><TD><TT>node->value.text.string</TT>
|
|
</TD></TR>
|
|
</TABLE>
|
|
</CENTER>
|
|
<P>Each node also has a <TT>user_data</TT> member which allows you to
|
|
associate application-specific data with each node as needed.</P>
|
|
<P>New nodes are created using the <A href="reference.html#mxmlNewElement">
|
|
<TT>mxmlNewElement</TT></A>, <A href="reference.html#mxmlNewInteger"><TT>
|
|
mxmlNewInteger</TT></A>, <A href="reference.html#mxmlNewOpaque"><TT>
|
|
mxmlNewOpaque</TT></A>, <A href="reference.html#mxmlNewReal"><TT>
|
|
mxmlNewReal</TT></A>, <A href="reference.html#mxmlNewText"><TT>
|
|
mxmlNewText</TT></A> <A href="reference.html#mxmlNewTextf"><TT>
|
|
mxmlNewTextf</TT></A> <A href="reference.html#mxmlNewXML"><TT>mxmlNewXML</TT>
|
|
</A> functions. Only elements can have child nodes, and the top node
|
|
must be an element, usually the <TT><?xml version="1.0"?></TT> node
|
|
created by <TT>mxmlNewXML()</TT>.</P>
|
|
<P>Nodes have pointers to the node above (<TT>parent</TT>), below (<TT>
|
|
child</TT>), left (<TT>prev</TT>), and right (<TT>next</TT>) of the
|
|
current node. If you have an XML file like the following:</P>
|
|
<PRE>
|
|
<?xml version="1.0"?>
|
|
<data>
|
|
<node>val1</node>
|
|
<node>val2</node>
|
|
<node>val3</node>
|
|
<group>
|
|
<node>val4</node>
|
|
<node>val5</node>
|
|
<node>val6</node>
|
|
</group>
|
|
<node>val7</node>
|
|
<node>val8</node>
|
|
</data>
|
|
</PRE>
|
|
<P>the node tree for the file would look like the following in memory:</P>
|
|
<PRE>
|
|
?xml
|
|
|
|
|
data
|
|
|
|
|
node - node - node - group - node - node
|
|
| | | | | |
|
|
val1 val2 val3 | val7 val8
|
|
|
|
|
node - node - node
|
|
| | |
|
|
val4 val5 val6
|
|
</PRE>
|
|
<P>where "-" is a pointer to the next node and "|" is a pointer to the
|
|
first child node.</P>
|
|
<P>Once you are done with the XML data, use the <A href="reference.html#mxmlDelete">
|
|
<TT>mxmlDelete</TT></A> function to recursively free the memory that is
|
|
used for a particular node or the entire tree:</P>
|
|
<PRE>
|
|
mxmlDelete(tree);
|
|
</PRE>
|
|
|
|
<!-- NEW PAGE -->
|
|
<H2><A NAME="3_3">Creating XML Documents</A></H2>
|
|
<P>You can create and update XML documents in memory using the various <TT>
|
|
mxmlNew</TT> functions. The following code will create the XML document
|
|
described in the previous section:</P>
|
|
<PRE>
|
|
mxml_node_t *xml; /* <?xml ... ?> */
|
|
mxml_node_t *data; /* <data> */
|
|
mxml_node_t *node; /* <node> */
|
|
mxml_node_t *group; /* <group> */
|
|
|
|
xml = mxmlNewXML("1.0");
|
|
|
|
data = mxmlNewElement(xml, "data");
|
|
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val1");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val2");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val3");
|
|
|
|
group = mxmlNewElement(data, "group");
|
|
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val4");
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val5");
|
|
node = mxmlNewElement(group, "node");
|
|
mxmlNewText(node, 0, "val6");
|
|
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val7");
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val8");
|
|
</PRE>
|
|
<P>We start by creating the <TT><?xml version="1.0"?></TT> node common
|
|
to all XML files using the <A href="reference.html#mxmlNewXML"><TT>
|
|
mxmlNewXML</TT></A> function:</P>
|
|
<PRE>
|
|
xml = mxmlNewXML("1.0");
|
|
</PRE>
|
|
<P>We then create the <TT><data></TT> node used for this document using
|
|
the <A href="reference.html#mxmlNewElement"><TT>mxmlNewElement</TT></A>
|
|
function. The first argument specifies the parent node (<TT>xml</TT>)
|
|
while the second specifies the element name (<TT>data</TT>):</P>
|
|
<PRE>
|
|
data = mxmlNewElement(xml, "data");
|
|
</PRE>
|
|
<P>Each <TT><node>...</node></TT> in the file is created using the <TT>
|
|
mxmlNewElement</TT> and <A href="reference.html#mxmlNewText"><TT>
|
|
mxmlNewText</TT></A> functions. The first argument of <TT>mxmlNewText</TT>
|
|
specifies the parent node (<TT>node</TT>). The second argument
|
|
specifies whether whitespace appears before the text - 0 or false in
|
|
this case. The last argument specifies the actual text to add:</P>
|
|
<PRE>
|
|
node = mxmlNewElement(data, "node");
|
|
mxmlNewText(node, 0, "val1");
|
|
</PRE>
|
|
<P>The resulting in-memory XML document can then be saved or processed
|
|
just like one loaded from disk or a string.</P>
|
|
|
|
<!-- NEW PAGE -->
|
|
<H2><A NAME="3_4">Loading XML</A></H2>
|
|
<P>You load an XML file using the <A href="reference.html#mxmlLoadFile"><TT>
|
|
mxmlLoadFile</TT></A> function:</P>
|
|
<PRE>
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "r");
|
|
tree = mxmlLoadFile(NULL, fp,
|
|
MXML_TEXT_CALLBACK);
|
|
fclose(fp);
|
|
</PRE>
|
|
<P>The first argument specifies an existing XML parent node, if any.
|
|
Normally you will pass <TT>NULL</TT> for this argument unless you are
|
|
combining multiple XML sources. The XML file must contain a complete
|
|
XML document including the <TT>?xml</TT> element if the parent node is <TT>
|
|
NULL</TT>.</P>
|
|
<P>The second argument specifies the stdio file to read from, as opened
|
|
by <TT>fopen()</TT> or <TT>popen()</TT>. You can also use <TT>stdin</TT>
|
|
if you are implementing an XML filter program.</P>
|
|
<P>The third argument specifies a callback function which returns the
|
|
value type of the immediate children for a new element node: <TT>
|
|
MXML_CUSTOM</TT>, <TT>MXML_IGNORE</TT>, <TT>MXML_INTEGER</TT>, <TT>
|
|
MXML_OPAQUE</TT>, <TT>MXML_REAL</TT>, or <TT>MXML_TEXT</TT>. Load
|
|
callbacks are described in detail in <A href="advanced.html#LOAD_CALLBACKS">
|
|
Chapter 3</A>. The example code uses the <TT>MXML_TEXT_CALLBACK</TT>
|
|
constant which specifies that all data nodes in the document contain
|
|
whitespace-separated text values. Other standard callbacks include <TT>
|
|
MXML_IGNORE_CALLBACK</TT>, <TT>MXML_INTEGER_CALLBACK</TT>, <TT>
|
|
MXML_OPAQUE_CALLBACK</TT>, and <TT>MXML_REAL_CALLBACK</TT>.</P>
|
|
<P>The <A href="reference.html#mxmlLoadString"><TT>mxmlLoadString</TT></A>
|
|
function loads XML node trees from a string:</P>
|
|
|
|
<!-- NEED 10 -->
|
|
<PRE>
|
|
char buffer[8192];
|
|
mxml_node_t *tree;
|
|
|
|
...
|
|
tree = mxmlLoadString(NULL, buffer,
|
|
MXML_TEXT_CALLBACK);
|
|
</PRE>
|
|
<P>The first and third arguments are the same as used for <TT>
|
|
mxmlLoadFile()</TT>. The second argument specifies the string or
|
|
character buffer to load and must be a complete XML document including
|
|
the <TT>?xml</TT> element if the parent node is <TT>NULL</TT>.</P>
|
|
|
|
<!-- NEW PAGE -->
|
|
<H2><A NAME="3_5">Saving XML</A></H2>
|
|
<P>You save an XML file using the <A href="reference.html#mxmlSaveFile"><TT>
|
|
mxmlSaveFile</TT></A> function:</P>
|
|
<PRE>
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "w");
|
|
mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
|
|
fclose(fp);
|
|
</PRE>
|
|
<P>The first argument is the XML node tree to save. It should normally
|
|
be a pointer to the top-level <TT>?xml</TT> node in your XML document.</P>
|
|
<P>The second argument is the stdio file to write to, as opened by <TT>
|
|
fopen()</TT> or <TT>popen()</TT>. You can also use <TT>stdout</TT> if
|
|
you are implementing an XML filter program.</P>
|
|
<P>The third argument is the whitespace callback to use when saving the
|
|
file. Whitespace callbacks are covered in detail in <A href="SAVE_CALLBACKS">
|
|
Chapter 3</A>. The previous example code uses the <TT>MXML_NO_CALLBACK</TT>
|
|
constant to specify that no special whitespace handling is required.</P>
|
|
<P>The <A href="reference.html#mxmlSaveAllocString"><TT>
|
|
mxmlSaveAllocString</TT></A>, and <A href="reference.html#mxmlSaveString">
|
|
<TT>mxmlSaveString</TT></A> functions save XML node trees to strings:</P>
|
|
<PRE>
|
|
char buffer[8192];
|
|
char *ptr;
|
|
mxml_node_t *tree;
|
|
|
|
...
|
|
mxmlSaveString(tree, buffer, sizeof(buffer),
|
|
MXML_NO_CALLBACK);
|
|
|
|
...
|
|
ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
|
|
</PRE>
|
|
<P>The first and last arguments are the same as used for <TT>
|
|
mxmlSaveFile()</TT>. The <TT>mxmlSaveString</TT> function takes pointer
|
|
and size arguments for saving the XML document to a fixed-size buffer,
|
|
while <TT>mxmlSaveAllocString()</TT> returns a string buffer that was
|
|
allocated using <TT>malloc()</TT>.</P>
|
|
<H3><A NAME="3_5_1">Controlling Line Wrapping</A></H3>
|
|
<P>When saving XML documents, Mini-XML normally wraps output lines at
|
|
column 75 so that the text is readable in terminal windows. The <A href="reference.html#mxmlSetWrapMargin">
|
|
<TT>mxmlSetWrapMargin</TT></A> function overrides the default wrap
|
|
margin:</P>
|
|
<PRE>
|
|
/* Set the margin to 132 columns */
|
|
mxmlSetWrapMargin(132);
|
|
|
|
/* Disable wrapping */
|
|
mxmlSetWrapMargin(0);
|
|
</PRE>
|
|
|
|
<!-- NEW PAGE-->
|
|
<H2><A NAME="3_6">Finding and Iterating Nodes</A></H2>
|
|
<P>The <A href="reference.html#mxmlWalkPrev"><TT>mxmlWalkPrev</TT></A>
|
|
and <A href="reference.html#mxmlWalkNext"><TT>mxmlWalkNext</TT></A>
|
|
functions can be used to iterate through the XML node tree:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
node = mxmlWalkPrev(current, tree,
|
|
MXML_DESCEND);
|
|
|
|
node = mxmlWalkNext(current, tree,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>In addition, you can find a named element/node using the <A href="reference.html#mxmlFindElement">
|
|
<TT>mxmlFindElement</TT></A> function:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
node = mxmlFindElement(tree, tree, "name",
|
|
"attr", "value",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>The <TT>name</TT>, <TT>attr</TT>, and <TT>value</TT> arguments can be
|
|
passed as <TT>NULL</TT> to act as wildcards, e.g.:</P>
|
|
|
|
<!-- NEED 4 -->
|
|
<PRE>
|
|
/* Find the first "a" element */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
NULL, NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first "a" element with "href"
|
|
attribute */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
"href", NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 6 -->
|
|
<PRE>
|
|
/* Find the first "a" element with "href"
|
|
to a URL */
|
|
node = mxmlFindElement(tree, tree, "a",
|
|
"href",
|
|
"http://www.easysw.com/",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first element with a "src"
|
|
attribute */
|
|
node = mxmlFindElement(tree, tree, NULL,
|
|
"src", NULL,
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
|
|
<!-- NEED 5 -->
|
|
<PRE>
|
|
/* Find the first element with a "src"
|
|
= "foo.jpg" */
|
|
node = mxmlFindElement(tree, tree, NULL,
|
|
"src", "foo.jpg",
|
|
MXML_DESCEND);
|
|
</PRE>
|
|
<P>You can also iterate with the same function:</P>
|
|
<PRE>
|
|
mxml_node_t *node;
|
|
|
|
for (node = mxmlFindElement(tree, tree,
|
|
"name",
|
|
NULL, NULL,
|
|
MXML_DESCEND);
|
|
node != NULL;
|
|
node = mxmlFindElement(node, tree,
|
|
"name",
|
|
NULL, NULL,
|
|
MXML_DESCEND))
|
|
{
|
|
... do something ...
|
|
}
|
|
</PRE>
|
|
|
|
<!-- NEED 10 -->
|
|
<P>The <TT>MXML_DESCEND</TT> argument can actually be one of three
|
|
constants:</P>
|
|
<UL>
|
|
<LI><TT>MXML_NO_DESCEND</TT> means to not to look at any child nodes in
|
|
the element hierarchy, just look at siblings at the same level or
|
|
parent nodes until the top node or top-of-tree is reached.
|
|
<P>The previous node from "group" would be the "node" element to the
|
|
left, while the next node from "group" would be the "node" element to
|
|
the right.
|
|
<BR>
|
|
<BR></P>
|
|
</LI>
|
|
<LI><TT>MXML_DESCEND_FIRST</TT> means that it is OK to descend to the
|
|
first child of a node, but not to descend further when searching.
|
|
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 example above.
|
|
<P>This mode is only applicable to the search function; the walk
|
|
functions treat this as <TT>MXML_DESCEND</TT> since every call is a
|
|
first time.
|
|
<BR>
|
|
<BR></P>
|
|
</LI>
|
|
<LI><TT>MXML_DESCEND</TT> means to keep descending until you hit the
|
|
bottom of the tree. The previous node from "group" would be the "val3"
|
|
node and the next node would be the first node element under "group".
|
|
<P>If you were to walk from the root node "?xml" to the end of the tree
|
|
with <TT>mxmlWalkNext()</TT>, the order would be:</P>
|
|
<P><TT>?xml data node val1 node val2 node val3 group node val4 node val5
|
|
node val6 node val7 node val8</TT></P>
|
|
<P>If you started at "val8" and walked using <TT>mxmlWalkPrev()</TT>,
|
|
the order would be reversed, ending at "?xml".</P>
|
|
</LI>
|
|
</UL>
|
|
<HR NOSHADE>
|
|
<A HREF="index.html">Contents</A>
|
|
<A HREF="install.html">Previous</A>
|
|
<A HREF="advanced.html">Next</A>
|
|
</BODY>
|
|
</HTML>
|