Commit aaefc5c0 authored by Michael R Sweet's avatar Michael R Sweet

Rename mxmlFindValue to mxmlFindPath.

Rename mxmlGetPrevious to mxmlGetPrevSibling.

Rename mxmlGetNext to mxmlGetNextSibling.

Update documentation.
parent a9012172
CHANGES - 2011-01-01
CHANGES - 2011-01-02
--------------------
CHANGES IN Mini-XML 2.7
......@@ -8,7 +8,7 @@ CHANGES IN Mini-XML 2.7
header to preserve source compatibility (STR #118)
- Updated the source headers to reference the Mini-XML license and its
exceptions to the LGPL2 (STR #108)
- Added a new mxmlFindValue() function to find the value node of a
- Added a new mxmlFindPath() function to find the value node of a
named element (STR #110)
- Building a static version of the library did not work on Windows
(STR #112)
......
......@@ -6,21 +6,21 @@ The Mini-XML library and included programs are provided under the
terms of the GNU Library General Public License version 2 (LGPL2)
with the following exceptions:
1. Static linking of applications to the Mini-XML library
does not constitute a derivative work and does not require
the author to provide source code for the application, use
the shared Mini-XML libraries, or link their applications
against a user-supplied version of Mini-XML.
If you link the application to a modified version of
Mini-XML, then the changes to Mini-XML must be provided
under the terms of the LGPL2 in sections 1, 2, and 4.
2. You do not have to provide a copy of the Mini-XML license
with programs that are linked to the Mini-XML library, nor
do you have to identify the Mini-XML license in your
program or documentation as required by section 6 of the
LGPL2.
1. Static linking of applications to the Mini-XML library
does not constitute a derivative work and does not require
the author to provide source code for the application, use
the shared Mini-XML libraries, or link their applications
against a user-supplied version of Mini-XML.
If you link the application to a modified version of
Mini-XML, then the changes to Mini-XML must be provided
under the terms of the LGPL2 in sections 1, 2, and 4.
2. You do not have to provide a copy of the Mini-XML license
with programs that are linked to the Mini-XML library, nor
do you have to identify the Mini-XML license in your
program or documentation as required by section 6 of the
LGPL2.
GNU LIBRARY GENERAL PUBLIC LICENSE
......
......@@ -3,7 +3,7 @@
#
# Makefile for Mini-XML, a small XML-like file parsing library.
#
# Copyright 2003-2010 by Michael R Sweet.
# Copyright 2003-2011 by Michael R Sweet.
#
# These coded instructions, statements, and computer programs are the
# property of Michael R Sweet and are protected by Federal copyright
......@@ -69,9 +69,11 @@ INSTALL_SCRIPT = $(INSTALL) -m 755
# Rules...
#
.SILENT:
.SUFFIXES: .c .man .o
.c.o:
$(CC) $(CFLAGS) -c $<
echo Compiling $<
$(CC) $(CFLAGS) -c -o $@ $<
#
......@@ -101,6 +103,7 @@ all: Makefile config.h $(TARGETS)
#
clean:
echo Cleaning build files...
$(RM) $(OBJS) $(TARGETS)
$(RM) mxmldoc-static libmxml.a
......@@ -110,6 +113,7 @@ clean:
#
distclean: clean
echo Cleaning distribution files...
$(RM) config.cache config.log config.status
$(RM) Makefile config.h
$(RM) -r autom4te*.cache
......@@ -123,9 +127,11 @@ distclean: clean
.PHONY: clang clang-changes
clang:
echo Doing static code analysis of all code using CLANG...
$(RM) -r clang
scan-build -V -k -o `pwd`/clang $(MAKE) $(MFLAGS) clean all
clang-changes:
echo Doing static code analysis of changed code using CLANG...
scan-build -V -k -o `pwd`/clang $(MAKE) $(MFLAGS) all
......@@ -134,41 +140,50 @@ clang-changes:
#
install: $(TARGETS) install-$(LIBMXML) install-libmxml.a
echo Installing mxmldoc in $(BUILDROOT)$(bindir)...
$(INSTALL_DIR) $(BUILDROOT)$(bindir)
$(INSTALL_BIN) mxmldoc $(BUILDROOT)$(bindir)
$(INSTALL_BIN) mxmldoc $(BUILDROOT)$(bindir)
echo Installing documentation in $(BUILDROOT)$(docdir)...
$(INSTALL_DIR) $(BUILDROOT)$(docdir)
for file in $(DOCFILES); do \
$(INSTALL_MAN) $$file $(BUILDROOT)$(docdir); \
done
echo Installing header files in $(BUILDROOT)$(includedir)...
$(INSTALL_DIR) $(BUILDROOT)$(includedir)
$(INSTALL_DATA) mxml.h $(BUILDROOT)$(includedir)
echo Installing pkgconfig files in $(BUILDROOT)$(libdir)/pkgconfig...
$(INSTALL_DIR) $(BUILDROOT)$(libdir)/pkgconfig
$(INSTALL_DATA) mxml.pc $(BUILDROOT)$(libdir)/pkgconfig
echo Installing man pages in $(BUILDROOT)$(mandir)...
$(INSTALL_DIR) $(BUILDROOT)$(mandir)/man1
$(INSTALL_MAN) doc/mxmldoc.man $(BUILDROOT)$(mandir)/man1/mxmldoc.1
$(INSTALL_DIR) $(BUILDROOT)$(mandir)/man3
$(INSTALL_MAN) doc/mxml.man $(BUILDROOT)$(mandir)/man3/mxml.3
install-libmxml.a:
echo Installing libmxml.a to $(BUILDROOT)$(libdir)...
$(INSTALL_DIR) $(BUILDROOT)$(libdir)
$(INSTALL_LIB) libmxml.a $(BUILDROOT)$(libdir)
$(RANLIB) $(BUILDROOT)$(libdir)/libmxml.a
install-libmxml.so.1.4:
install-libmxml.so.1.5:
echo Installing libmxml.so to $(BUILDROOT)$(libdir)...
$(INSTALL_DIR) $(BUILDROOT)$(libdir)
$(INSTALL_LIB) libmxml.so.1.4 $(BUILDROOT)$(libdir)
$(INSTALL_LIB) libmxml.so.1.5 $(BUILDROOT)$(libdir)
$(RM) $(BUILDROOT)$(libdir)/libmxml.so
$(LN) libmxml.so.1.4 $(BUILDROOT)$(libdir)/libmxml.so
$(LN) libmxml.so.1.5 $(BUILDROOT)$(libdir)/libmxml.so
$(RM) $(BUILDROOT)$(libdir)/libmxml.so.1
$(LN) libmxml.so.1.4 $(BUILDROOT)$(libdir)/libmxml.so.1
$(LN) libmxml.so.1.5 $(BUILDROOT)$(libdir)/libmxml.so.1
install-libmxml.sl.1:
echo Installing libmxml.sl to $(BUILDROOT)$(libdir)...
$(INSTALL_DIR) $(BUILDROOT)$(libdir)
$(INSTALL_LIB) libmxml.sl.1 $(BUILDROOT)$(libdir)
$(RM) $(BUILDROOT)$(libdir)/libmxml.so
$(LN) libmxml.sl.1 $(BUILDROOT)$(libdir)/libmxml.sl
install-libmxml.1.dylib:
echo Installing libmxml.dylib to $(BUILDROOT)$(libdir)...
$(INSTALL_DIR) $(BUILDROOT)$(libdir)
$(INSTALL_LIB) libmxml.1.dylib $(BUILDROOT)$(libdir)
$(RM) $(BUILDROOT)$(libdir)/libmxml.dylib
......@@ -180,35 +195,45 @@ install-libmxml.1.dylib:
#
uninstall: uninstall-$(LIBMXML) uninstall-libmxml.a
echo Uninstalling mxmldoc from $(BUILDROOT)$(bindir)...
$(RM) $(BUILDROOT)$(bindir)/mxmldoc
echo Uninstalling documentation from $(BUILDROOT)$(docdir)...
$(RM) -r $(BUILDROOT)$(docdir)
echo Uninstalling headers from $(BUILDROOT)$(includedir)...
$(RM) $(BUILDROOT)$(includedir)/mxml.h
echo Uninstalling pkgconfig files from $(BUILDROOT)$(libdir)/pkgconfig...
$(RM) $(BUILDROOT)$(libdir)/pkgconfig/mxml.pc
echo Uninstalling man pages from $(BUILDROOT)$(mandir)...
$(RM) $(BUILDROOT)$(mandir)/man1/mxmldoc.1
$(RM) $(BUILDROOT)$(mandir)/man3/mxml.3
uninstall-libmxml.a:
echo Uninstalling libmxml.a from $(BUILDROOT)$(libdir)...
$(RM) $(BUILDROOT)$(libdir)/libmxml.a
uninstall-libmxml.so.1.4:
uninstall-libmxml.so.1.5:
echo Uninstalling libmxml.so from $(BUILDROOT)$(libdir)...
$(RM) $(BUILDROOT)$(libdir)/libmxml.so
$(RM) $(BUILDROOT)$(libdir)/libmxml.so.1
$(RM) $(BUILDROOT)$(libdir)/libmxml.so.1.4
uninstall-libmxml.sl.1:
echo Uninstalling libmxml.sl from $(BUILDROOT)$(libdir)...
$(RM) $(BUILDROOT)$(libdir)/libmxml.sl
$(RM) $(BUILDROOT)$(libdir)/libmxml.sl.1
uninstall-libmxml.1.dylib:
echo Uninstalling libmxml.dylib from $(BUILDROOT)$(libdir)...
$(RM) $(BUILDROOT)$(libdir)/libmxml.dylib
$(RM) $(BUILDROOT)$(libdir)/libmxml.1.dylib
#
# Make packages using EPM (http://www.easysw.com/epm/)
# Make packages using EPM (http://www.epmhome.org/)
#
epm: all
echo Creating distribution packages...
epm --output-dir dist -v -f native mxml
epm --output-dir dist -v -f portable mxml
......@@ -218,6 +243,7 @@ epm: all
#
Makefile: configure Makefile.in
echo Updating makefile...
if test -f config.status; then \
./config.status --recheck; \
./config.status; \
......@@ -228,6 +254,7 @@ Makefile: configure Makefile.in
config.h: configure config.h.in
echo Updating config.h...
autoconf
if test -f config.status; then \
./config.status --recheck; \
......@@ -238,11 +265,24 @@ config.h: configure config.h.in
touch config.h
#
# Figure out lines-of-code...
#
.PHONY: sloc
sloc:
echo "libmxml: \c"
sloccount $(LIBOBJS:.o=.c) mxml-private.c mxml.h 2>/dev/null | \
grep "Total Physical" | awk '{print $$9}'
#
# libmxml.a
#
libmxml.a: $(LIBOBJS)
echo Creating $@...
$(RM) $@
$(AR) $(ARFLAGS) $@ $(LIBOBJS)
$(RANLIB) $@
......@@ -252,14 +292,15 @@ mxml-entity.o mxml-file.o mxml-private.o: mxml-private.h
#
# libmxml.so.1.4
# libmxml.so.1.5
#
libmxml.so.1.4: $(LIBOBJS)
$(DSO) $(DSOFLAGS) -o libmxml.so.1.4 $(LIBOBJS)
libmxml.so.1.5: $(LIBOBJS)
echo Creating $@...
$(DSO) $(DSOFLAGS) -o libmxml.so.1.5 $(LIBOBJS)
$(RM) libmxml.so libmxml.so.1
$(LN) libmxml.so.1.4 libmxml.so
$(LN) libmxml.so.1.4 libmxml.so.1
$(LN) libmxml.so.1.5 libmxml.so
$(LN) libmxml.so.1.5 libmxml.so.1
#
......@@ -267,6 +308,7 @@ libmxml.so.1.4: $(LIBOBJS)
#
libmxml.sl.1: $(LIBOBJS)
echo Creating $@...
$(DSO) $(DSOFLAGS) -o libmxml.sl.1 $(LIBOBJS)
$(RM) libmxml.sl
$(LN) libmxml.sl.1 libmxml.sl
......@@ -277,9 +319,10 @@ libmxml.sl.1: $(LIBOBJS)
#
libmxml.1.dylib: $(LIBOBJS)
echo Creating $@...
$(DSO) $(DSOFLAGS) -o libmxml.1.dylib \
-install_name $(libdir)/libmxml.dylib \
-current_version 1.4.0 \
-current_version 1.5.0 \
-compatibility_version 1.0.0 \
$(LIBOBJS)
$(RM) libmxml.dylib
......@@ -291,9 +334,11 @@ libmxml.1.dylib: $(LIBOBJS)
#
mxmldoc: $(LIBMXML) mxmldoc.o
echo Linking $@...
$(CC) -L. $(LDFLAGS) -o $@ mxmldoc.o -lmxml $(LIBS)
mxmldoc-static: libmxml.a mxmldoc.o
echo Linking $@...
$(CC) $(LDFLAGS) -o $@ mxmldoc.o libmxml.a $(LIBS)
mxmldoc.o: mxml.h
......@@ -304,6 +349,7 @@ mxmldoc.o: mxml.h
#
testmxml: libmxml.a testmxml.o
echo Linking $@...
$(CC) $(LDFLAGS) -o $@ testmxml.o libmxml.a $(LIBS)
@echo Testing library...
./testmxml test.xml >temp1.xml 2>temp1s.xml
......@@ -335,6 +381,7 @@ testmxml.o: mxml.h
#
mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c)
echo Generating API documentation...
$(RM) mxml.xml
./mxmldoc-static --header doc/reference.heading mxml.xml mxml.h $(PUBLIBOBJS:.o=.c) >doc/reference.html
if test "x`uname`" = xDarwin; then \
......@@ -351,6 +398,7 @@ mxml.xml: mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c)
fi
valgrind: mxmldoc-static
echo Doing dynamic code analysis using Valgrind...
$(RM) valgrind.xml
valgrind --tool=memcheck --leak-check=yes ./mxmldoc-static \
valgrind.xml mxml.h $(PUBLIBOBJS:.o=.c) \
......@@ -362,6 +410,7 @@ valgrind: mxmldoc-static
#
doc/mxml.man: mxmldoc-static mxml.xml
echo "Generating mxml(3) man page..."
$(RM) doc/mxml.man
./mxmldoc-static --man mxml --title "Mini-XML API" \
--intro doc/intro.man --footer doc/footer.man \
......
README - 2010-11-08
README - 2011-01-02
-------------------
......@@ -133,7 +133,7 @@ DOCUMENTATION
/* Find the first "a" element with "href" to a URL */
node = mxmlFindElement(tree, tree, "a", "href",
"http://www.easysw.com/~mike/mxml/",
"http://www.minixml.org/",
MXML_DESCEND);
/* Find the first element with a "src" attribute*/
......@@ -156,11 +156,25 @@ DOCUMENTATION
... do something ...
}
The "mxmlFindValue()" function finds the (first) value node under a specific
The "mxmlFindPath()" function finds the (first) value node under a specific
element using a "path":
mxml_node_t *value = mxmlFindValue(tree, "path/to/*/foo/bar");
mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
The "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and
"mxmlGetText()" functions retrieve the value from a node:
mxml_node_t *node;
int intvalue = mxmlGetInteger(node);
const char *opaquevalue = mxmlGetOpaque(node);
double realvalue = mxmlGetReal(node);
int whitespacevalue;
const char *textvalue = mxmlGetText(node, &whitespacevalue);
Finally, once you are done with the XML data, use the "mxmlDelete()"
function to recursively free the memory that is used for a particular node
or the entire tree:
......@@ -178,5 +192,5 @@ GETTING HELP AND REPORTING PROBLEMS
LEGAL STUFF
The Mini-XML library is Copyright 2003-2010 by Michael Sweet. License terms
The Mini-XML library is Copyright 2003-2011 by Michael Sweet. License terms
are described in the file "COPYING".
......@@ -3,7 +3,7 @@ dnl "$Id$"
dnl
dnl Configuration script for Mini-XML, a small XML-like file parsing library.
dnl
dnl Copyright 2003-2010 by Michael R Sweet.
dnl Copyright 2003-2011 by Michael R Sweet.
dnl
dnl These coded instructions, statements, and computer programs are the
dnl property of Michael R Sweet and are protected by Federal copyright
......@@ -171,7 +171,7 @@ if test x$enable_shared != xno; then
case "$uname" in
SunOS* | UNIX_S*)
AC_MSG_RESULT(yes)
LIBMXML="libmxml.so.1.4"
LIBMXML="libmxml.so.1.5"
DSO="\$(CC)"
DSOFLAGS="$DSOFLAGS -Wl,-h,libmxml.so.1 -G -R\$(libdir) \$(OPTIM)"
LDFLAGS="$LDFLAGS -R\$(libdir)"
......@@ -187,14 +187,14 @@ if test x$enable_shared != xno; then
IRIX)
AC_MSG_RESULT(yes)
LIBMXML="libmxml.so.1.4"
LIBMXML="libmxml.so.1.5"
DSO="\$(CC)"
DSOFLAGS="$DSOFLAGS -Wl,-rpath,\$(libdir),-set_version,sgi1.0,-soname,libmxml.so.1 -shared \$(OPTIM)"
;;
OSF1* | Linux | GNU)
AC_MSG_RESULT(yes)
LIBMXML="libmxml.so.1.4"
LIBMXML="libmxml.so.1.5"
DSO="\$(CC)"
DSOFLAGS="$DSOFLAGS -Wl,-soname,libmxml.so.1,-rpath,\$(libdir) -shared \$(OPTIM)"
LDFLAGS="$LDFLAGS -Wl,-rpath,\$(libdir)"
......@@ -202,7 +202,7 @@ if test x$enable_shared != xno; then
*BSD*)
AC_MSG_RESULT(yes)
LIBMXML="libmxml.so.1.4"
LIBMXML="libmxml.so.1.5"
DSO="\$(CC)"
DSOFLAGS="$DSOFLAGS -Wl,-soname,libmxml.so.1,-R\$(libdir) -shared \$(OPTIM)"
LDFLAGS="$LDFLAGS -Wl,-R\$(libdir)"
......
......@@ -64,7 +64,7 @@ child nodes:</p>
type = mxmlElementGetAttr(node, "type");
if (type == NULL)
type = node->value.element.name;
type = mxmlGetElement(node);
if (!strcmp(type, "integer"))
return (MXML_INTEGER);
......@@ -125,7 +125,7 @@ text editor:</p>
* just common HTML elements...
*/
name = node->value.element.name;
name = mxmlGetElement(node);
if (!strcmp(name, "html") ||
!strcmp(name, "head") ||
......@@ -243,10 +243,10 @@ following:</p>
*/
if (sscanf(data, "%u-%u-%uT%u:%u:%uZ",
&(dt->year), &(dt->month),
&(dt->day), &(dt->hour),
&(dt->minute),
&(dt->second)) != 6)
&amp;(dt->year), &amp;(dt->month),
&amp;(dt->day), &amp;(dt->hour),
&amp;(dt->minute),
&amp;(dt->second)) != 6)
{
/*
* Unable to read numbers, free the data
......@@ -296,8 +296,7 @@ following:</p>
* function pointers...
*/
node->value.custom.data = dt;
node->value.custom.destroy = free;
mxmlSetCustom(node, data, destroy);
/*
* Return with no errors...
......@@ -314,6 +313,7 @@ allocated custom data for the node and a pointer to a destructor
function which will free the custom data when the node is
deleted.</p>
<!-- NEED 15 -->
<p>The save callback receives the node pointer and returns an
allocated string containing the custom data value. The following
save callback could be used for our ISO date/time type:</p>
......@@ -326,7 +326,7 @@ save callback could be used for our ISO date/time type:</p>
iso_date_time_t *dt;
dt = (iso_date_time_t *)node->custom.data;
dt = (iso_date_time_t *)mxmlGetCustom(node);
snprintf(data, sizeof(data),
"%04u-%02u-%02uT%02u:%02u:%02uZ",
......@@ -404,9 +404,8 @@ an index is approximately equal to walking the XML document
tree. Nodes in the index are sorted by element name and
attribute value.</p>
<p>Indices are stored in <a
href='#mxml_index_t'><tt>mxml_index_t</tt></a> structures. The
<a href='#mxmlIndexNew'><tt>mxmlIndexNew()</tt></a> function
<p>Indices are stored in <a href='#mxml_index_t'><tt>mxml_index_t</tt></a>
structures. The <a href='#mxmlIndexNew'><tt>mxmlIndexNew()</tt></a> function
creates a new index:</p>
<pre>
......@@ -568,7 +567,7 @@ directives like <tt>&lt;?xml ... ?&gt;</tt> and <tt>&lt;!DOCTYPE ... &gt;</tt>
* Retain headings and titles...
*/
char *name = node->value.element.name;
char *name = mxmlGetElement(node);
if (!strcmp(name, "html") ||
!strcmp(name, "head") ||
......@@ -584,15 +583,17 @@ directives like <tt>&lt;?xml ... ?&gt;</tt> and <tt>&lt;!DOCTYPE ... &gt;</tt>
}
else if (event == MXML_SAX_DIRECTIVE)
mxmlRetain(node);
else if (event == MXML_SAX_DATA &amp;&amp;
node->parent->ref_count > 1)
else if (event == MXML_SAX_DATA)
{
/*
* If the parent was retained, then retain
* this data node as well.
*/
if (mxmlGetRefCount(mxmlGetParent(node)) > 1)
{
/*
* If the parent was retained, then retain
* this data node as well.
*/
mxmlRetain(node);
mxmlRetain(node);
}
}
}
</pre>
......@@ -622,9 +623,9 @@ title and headings in the document would look like:</p>
if (body)
{
for (heading = body->child;
for (heading = mxmlGetFirstChild(body);
heading;
heading = heading->next)
heading = mxmlGetNextSibling(heading))
print_children(heading);
}
</pre>
......
......@@ -23,7 +23,7 @@ functionality:</p>
attribute values with no preset limits, just available
memory.</li>
<li>Support for integer, real, opaque ("cdata"), and text
<li>Support for integer, real, opaque ("CDATA"), and text
data types in "leaf" nodes.</li>
<li>"Find", "index", and "walk" functions for easily
......@@ -63,74 +63,12 @@ for your installation:</p>
<h2>Nodes</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='#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='#mxml_value_t'><tt>value</tt></a> union.</p>
<p>Every piece of information in an XML file is stored in memory in "nodes".
Nodes are defined by the <a href='#mxml_node_t'><tt>mxml_node_t</tt></a>
structure. Each node has a typed value, optional user data, a parent node,
sibling nodes (previous and next), and potentially child nodes.</p>
<!-- NEED 10 -->
<center><table width="80%" border="1" cellpadding="5" cellspacing="0" summary="Mini-XML Node Value Members">
<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-&gt;value.custom.data</tt></td>
</tr>
<tr>
<td>Element</td>
<td><tt>char *</tt></td>
<td><tt>node-&gt;value.element.name</tt></td>
</tr>
<tr>
<td>Integer</td>
<td><tt>int</tt></td>
<td><tt>node-&gt;value.integer</tt></td>
</tr>
<tr>
<td>Opaque (string)</td>
<td><tt>char *</tt></td>
<td><tt>node-&gt;value.opaque</tt></td>
</tr>
<tr>
<td>Real</td>
<td><tt>double</tt></td>
<td><tt>node-&gt;value.real</tt></td>
</tr>
<tr>
<td>Text</td>
<td><tt>char *</tt></td>
<td><tt>node-&gt;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='#mxmlNewElement'><tt>mxmlNewElement</tt></a>, <a
href='#mxmlNewInteger'><tt>mxmlNewInteger</tt></a>, <a
href='#mxmlNewOpaque'><tt>mxmlNewOpaque</tt></a>, <a
href='#mxmlNewReal'><tt>mxmlNewReal</tt></a>, <a
href='#mxmlNewText'><tt>mxmlNewText</tt></a>, <a
href='#mxmlNewTextf'><tt>mxmlNewTextf</tt></a>, and <a
href='#mxmlNewXML'><tt>mxmlNewXML</tt></a> functions. Only
elements can have child nodes, and the top node must be an element, usually the
<tt>&lt;?xml version="1.0" encoding="utf-8"?&gt;</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>
<p>For example, if you have an XML file like the following:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
......@@ -148,8 +86,7 @@ of the current node. If you have an XML file like the following:</p>
&lt;/data&gt;
</pre>
<p>the node tree for the file would look like the following in
memory:</p>
<p>the node tree for the file would look like the following in memory:</p>
<pre>
?xml version="1.0" encoding="utf-8"?
......@@ -165,17 +102,127 @@ memory:</p>
val4 val5 val6
</pre>
<p>where "-" is a pointer to the next node and "|" is a pointer
to the first child node.</p>
<p>where "-" is a pointer to the sibling node and "|" is a pointer
to the first child or parent node.</p>
<p>Once you are done with the XML data, use the <a
href='#mxmlDelete'><tt>mxmlDelete</tt></a> function to recursively
free the memory that is used for a particular node or the entire
tree:</p>
<p>The <a href="#mxmlGetType"><tt>mxmlGetType</tt></a> function gets the type of
a node, one of <tt>MXML_CUSTOM</tt>, <tt>MXML_ELEMENT</tt>,
<tt>MXML_INTEGER</tt>, <tt>MXML_OPAQUE</tt>, <tt>MXML_REAL</tt>, or
<tt>MXML_TEXT</tt>. The parent and sibling nodes are accessed using the
<a href="#mxmlGetParent"><tt>mxmlGetParent</tt></a>,
<a href="#mxmlGetNext"><tt>mxmlGetNext</tt></a>, and
<a href="#mxmlGetPrevious"><tt>mxmlGetPrevious</tt></a> functions. The
<a href="#mxmlGetUserData"><tt>mxmlGetUserData</tt></a> function gets any user
data associated with the node.</p>
<h3>CDATA Nodes</h3>
<p>CDATA (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewCDATA"><tt>mxmlNewCDATA</tt></a> function. The
<a href="#mxmlGetCDATA"><tt>mxmlGetCDATA</tt></a> function retrieves the
CDATA string pointer for a node.</p>
<blockquote><b>Note:</b>
<p>CDATA nodes are currently stored in memory as special elements. This will
be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Custom Nodes</h3>
<p>Custom (<tt>MXML_CUSTOM</tt>) nodes are created using the
<a href="#mxmlNewCustom"><tt>mxmlNewCustom</tt></a> function or using a custom
load callback specified using the
<a href="#mxmlSetCustomHandlers"><tt>mxmlSetCustomHandlers</tt></a> function.
The <a href="#mxmlGetCustom"><tt>mxmlGetCustom</tt></a> function retrieves the
custom value pointer for a node.</p>
<h3>Comment Nodes</h3>
<p>Comment (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
comment string pointer for a node, including the surrounding "!--" and "--"
characters.</p>
<blockquote><b>Note:</b>
<p>Comment nodes are currently stored in memory as special elements. This will
be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Element Nodes</h3>
<p>Element (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
element name, the
<a href="#mxmlElementGetAttr"><tt>mxmlElementGetAttr</tt></a> function retrieves
the value string for a named attribute associated with the element, and the
<a href="#mxmlGetFirstChild"><tt>mxmlGetFirstChild</tt></a> and
<a href="#mxmlGetLastChild"><tt>mxmlGetLastChild</tt></a> functions retrieve the
first and last child nodes for the element, respectively.</p>
<h3>Integer Nodes</h3>
<p>Integer (<tt>MXML_INTEGER</tt>) nodes are created using the
<a href="#mxmlNewInteger"><tt>mxmlNewInteger</tt></a> function. The
<a href="#mxmlGetInteger"><tt>mxmlGetInteger</tt></a> function retrieves the
integer value for a node.</p>
<h3>Opaque Nodes</h3>
<p>Opaque (<tt>MXML_OPAQUE</tt>) nodes are created using the
<a href="#mxmlNewOpaque"><tt>mxmlNewOpaque</tt></a> function. The
<a href="#mxmlGetOpaque"><tt>mxmlGetOpaque</tt></a> function retrieves the
opaque string pointer for a node. Opaque nodes are like string nodes but
preserve all whitespace between nodes.</p>
<h3>Text Nodes</h3>
<p>Text (<tt>MXML_TEXT</tt>) nodes are created using the
<a href="#mxmlNewText"><tt>mxmlNewText</tt></a> and
<a href="#mxmlNewTextf"><tt>mxmlNewTextf</tt></a> functions. Each text node
consists of a text string and (leading) whitespace value - the
<a href="#mxmlGetText"><tt>mxmlGetText</tt></a> function retrieves the
text string pointer and whitespace value for a node.</p>
<!-- NEED 12 -->
<h3>Processing Instruction Nodes</h3>
<p>Processing instruction (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
processing instruction string for a node, including the surrounding "?"
characters.</p>
<blockquote><b>Note:</b>
<p>Processing instruction nodes are currently stored in memory as special
elements. This will be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Real Number Nodes</h3>
<p>Real number (<tt>MXML_REAL</tt>) nodes are created using the
<a href="#mxmlNewReal"><tt>mxmlNewReal</tt></a> function. The
<a href="#mxmlGetReal"><tt>mxmlGetReal</tt></a> function retrieves the
CDATA string pointer for a node.</p>
<!-- NEED 15 -->
<h3>XML Declaration Nodes</h3>
<p>XML declaration (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewXML"><tt>mxmlNewXML</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
XML declaration string for a node, including the surrounding "?" characters.</p>
<blockquote><b>Note:</b>
<p>XML declaration nodes are currently stored in memory as special elements.
This will be changed in a future major release of Mini-XML.</p>
</blockquote>
<pre>
mxmlDelete(tree);
</pre>
<!-- NEW PAGE -->
<h2>Creating XML Documents</h2>
......@@ -216,41 +263,39 @@ create the XML document described in the previous section:</p>
mxmlNewText(node, 0, "val8");
</pre>
<p>We start by creating the <tt>&lt;?xml version="1.0" encoding="utf-8"?&gt;</tt>
node common to all XML files using the <a
href="#mxmlNewXML"><tt>mxmlNewXML</tt></a> function:</p>
<!-- NEED 6 -->
<p>We start by creating the declaration node common to all XML files using the
<a href="#mxmlNewXML"><tt>mxmlNewXML</tt></a> function:</p>
<pre>
xml = mxmlNewXML("1.0");
</pre>
<p>We then create the <tt>&lt;data&gt;</tt> node used for this