From aaefc5c07c766284876065d79c07498f5f64f08d Mon Sep 17 00:00:00 2001
From: Michael R Sweet
Date: Mon, 3 Jan 2011 02:03:29 +0000
Subject: [PATCH] Rename mxmlFindValue to mxmlFindPath.
Rename mxmlGetPrevious to mxmlGetPrevSibling.
Rename mxmlGetNext to mxmlGetNextSibling.
Update documentation.
---
CHANGES | 4 +-
COPYING | 26 +--
Makefile.in | 79 +++++++--
README | 26 ++-
configure.in | 10 +-
doc/advanced.html | 45 ++---
doc/basics.html | 271 ++++++++++++++++++-----------
doc/docset.intro | 25 ++-
doc/footer.man | 2 +-
doc/hires/logo.png | Bin 141627 -> 0 bytes
doc/install.html | 2 +-
doc/intro.html | 2 +-
doc/intro.man | 22 ++-
doc/license.html | 36 ++--
doc/logo.opacity | Bin 14917 -> 0 bytes
doc/logo.png | Bin 25191 -> 0 bytes
doc/mxml.html | 417 ++++++++++++++++++++++++++++-----------------
doc/mxmldoc.html | 4 +-
doc/mxmldoc.xsd | 4 +-
doc/reference.html | 57 +++++--
doc/relnotes.html | 6 +-
doc/schema.html | 6 +-
mxml-get.c | 50 +++---
mxml-node.c | 45 +++--
mxml-search.c | 22 ++-
mxml.h | 17 +-
mxml.xml | 40 +++--
testmxml.c | 8 +-
vcnet/mxml1.def | 19 ++-
vcnet/mxml1.vcproj | 4 +
30 files changed, 805 insertions(+), 444 deletions(-)
delete mode 100644 doc/hires/logo.png
delete mode 100644 doc/logo.opacity
delete mode 100644 doc/logo.png
diff --git a/CHANGES b/CHANGES
index 2093f23..62b2666 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,4 +1,4 @@
-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)
diff --git a/COPYING b/COPYING
index d7b975c..4d0aa78 100644
--- a/COPYING
+++ b/COPYING
@@ -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.
+ 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.
+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.
+ 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
diff --git a/Makefile.in b/Makefile.in
index 3b8fe88..6e51352 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -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 \
diff --git a/README b/README
index 620c5d7..248b090 100644
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-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".
diff --git a/configure.in b/configure.in
index 753c8d7..d2a686e 100644
--- a/configure.in
+++ b/configure.in
@@ -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)"
diff --git a/doc/advanced.html b/doc/advanced.html
index a1aef45..67fcbb8 100644
--- a/doc/advanced.html
+++ b/doc/advanced.html
@@ -64,7 +64,7 @@ child nodes:
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:
* just common HTML elements...
*/
- name = node->value.element.name;
+ name = mxmlGetElement(node);
if (!strcmp(name, "html") ||
!strcmp(name, "head") ||
@@ -243,10 +243,10 @@ following:
*/
if (sscanf(data, "%u-%u-%uT%u:%u:%uZ",
- &(dt->year), &(dt->month),
- &(dt->day), &(dt->hour),
- &(dt->minute),
- &(dt->second)) != 6)
+ &(dt->year), &(dt->month),
+ &(dt->day), &(dt->hour),
+ &(dt->minute),
+ &(dt->second)) != 6)
{
/*
* Unable to read numbers, free the data
@@ -296,8 +296,7 @@ following:
* 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.
+
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:
@@ -326,7 +326,7 @@ save callback could be used for our ISO date/time type:
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.
-"Find", "index", and "walk" functions for easily
@@ -63,74 +63,12 @@ for your installation:
Nodes
-Every piece of information in an XML file (elements, text,
-numbers) is stored in memory in "nodes". Nodes are defined by
-the mxml_node_t
-structure. The type member
-defines the node type (element, integer, opaque, real, or text)
-which determines which value you want to look at in the value union.
+Every piece of information in an XML file is stored in memory in "nodes".
+Nodes are defined by the mxml_node_t
+structure. Each node has a typed value, optional user data, a parent node,
+sibling nodes (previous and next), and potentially child nodes.
-
-
-Table 2-1: Mini-XML Node Value Members
-
- Value |
- Type |
- Node member |
-
-
- Custom |
- void * |
- node->value.custom.data |
-
-
- Element |
- char * |
- node->value.element.name |
-
-
- Integer |
- int |
- node->value.integer |
-
-
- Opaque (string) |
- char * |
- node->value.opaque |
-
-
- Real |
- double |
- node->value.real |
-
-
- Text |
- char * |
- node->value.text.string |
-
-
-
-Each node also has a user_data member which allows you
-to associate application-specific data with each node as needed.
-
-New nodes are created using the mxmlNewElement, mxmlNewInteger, mxmlNewOpaque, mxmlNewReal, mxmlNewText, mxmlNewTextf, and mxmlNewXML functions. Only
-elements can have child nodes, and the top node must be an element, usually the
-<?xml version="1.0" encoding="utf-8"?> node created by
-mxmlNewXML().
-
-Nodes have pointers to the node above (parent), below
-(child), left (prev), and right (next)
-of the current node. If you have an XML file like the following:
+For example, if you have an XML file like the following:
<?xml version="1.0" encoding="utf-8"?>
@@ -148,8 +86,7 @@ of the current node. If you have an XML file like the following:
</data>
-the node tree for the file would look like the following in
-memory:
+the node tree for the file would look like the following in memory:
?xml version="1.0" encoding="utf-8"?
@@ -165,17 +102,127 @@ memory:
val4 val5 val6
-where "-" is a pointer to the next node and "|" is a pointer
-to the first child node.
+where "-" is a pointer to the sibling node and "|" is a pointer
+to the first child or parent node.
-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:
+The mxmlGetType function gets the type of
+a node, one of MXML_CUSTOM, MXML_ELEMENT,
+MXML_INTEGER, MXML_OPAQUE, MXML_REAL, or
+MXML_TEXT. The parent and sibling nodes are accessed using the
+mxmlGetParent,
+mxmlGetNext, and
+mxmlGetPrevious functions. The
+mxmlGetUserData function gets any user
+data associated with the node.
+
+CDATA Nodes
+
+CDATA (MXML_ELEMENT) nodes are created using the
+mxmlNewCDATA function. The
+mxmlGetCDATA function retrieves the
+CDATA string pointer for a node.
+
+Note:
+
+CDATA nodes are currently stored in memory as special elements. This will
+be changed in a future major release of Mini-XML.
+
+
+Custom Nodes
+
+Custom (MXML_CUSTOM) nodes are created using the
+mxmlNewCustom function or using a custom
+load callback specified using the
+mxmlSetCustomHandlers function.
+The mxmlGetCustom function retrieves the
+custom value pointer for a node.
+
+Comment Nodes
+
+Comment (MXML_ELEMENT) nodes are created using the
+mxmlNewElement function. The
+mxmlGetElement function retrieves the
+comment string pointer for a node, including the surrounding "!--" and "--"
+characters.
+
+Note:
+
+Comment nodes are currently stored in memory as special elements. This will
+be changed in a future major release of Mini-XML.
+
+
+Element Nodes
+
+Element (MXML_ELEMENT) nodes are created using the
+mxmlNewElement function. The
+mxmlGetElement function retrieves the
+element name, the
+mxmlElementGetAttr function retrieves
+the value string for a named attribute associated with the element, and the
+mxmlGetFirstChild and
+mxmlGetLastChild functions retrieve the
+first and last child nodes for the element, respectively.
+
+Integer Nodes
+
+Integer (MXML_INTEGER) nodes are created using the
+mxmlNewInteger function. The
+mxmlGetInteger function retrieves the
+integer value for a node.
+
+Opaque Nodes
+
+Opaque (MXML_OPAQUE) nodes are created using the
+mxmlNewOpaque function. The
+mxmlGetOpaque function retrieves the
+opaque string pointer for a node. Opaque nodes are like string nodes but
+preserve all whitespace between nodes.
+
+Text Nodes
+
+Text (MXML_TEXT) nodes are created using the
+mxmlNewText and
+mxmlNewTextf functions. Each text node
+consists of a text string and (leading) whitespace value - the
+mxmlGetText function retrieves the
+text string pointer and whitespace value for a node.
+
+
+Processing Instruction Nodes
+
+Processing instruction (MXML_ELEMENT) nodes are created using the
+mxmlNewElement function. The
+mxmlGetElement function retrieves the
+processing instruction string for a node, including the surrounding "?"
+characters.
+
+Note:
+
+Processing instruction nodes are currently stored in memory as special
+elements. This will be changed in a future major release of Mini-XML.
+
+
+Real Number Nodes
+
+Real number (MXML_REAL) nodes are created using the
+mxmlNewReal function. The
+mxmlGetReal function retrieves the
+CDATA string pointer for a node.
+
+
+XML Declaration Nodes
+
+XML declaration (MXML_ELEMENT) nodes are created using the
+mxmlNewXML function. The
+mxmlGetElement function retrieves the
+XML declaration string for a node, including the surrounding "?" characters.
+
+Note:
+
+XML declaration nodes are currently stored in memory as special elements.
+This will be changed in a future major release of Mini-XML.
+
-
- mxmlDelete(tree);
-
Creating XML Documents
@@ -216,41 +263,39 @@ create the XML document described in the previous section:
mxmlNewText(node, 0, "val8");
-We start by creating the <?xml version="1.0" encoding="utf-8"?>
-node common to all XML files using the mxmlNewXML function:
+
+We start by creating the declaration node common to all XML files using the
+mxmlNewXML function:
xml = mxmlNewXML("1.0");
-We then create the <data> node used for this
-document using the mxmlNewElement function. The
-first argument specifies the parent node (xml) while the
-second specifies the element name (data):
+We then create the <data> node used for this document using
+the mxmlNewElement function. The first
+argument specifies the parent node (xml) while the second specifies the
+element name (data):
data = mxmlNewElement(xml, "data");
-Each <node>...</node> in the file is
-created using the mxmlNewElement and mxmlNewText functions. The first
-argument of mxmlNewText specifies the parent node
-(node). 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:
+Each <node>...</node> in the file is created using the
+mxmlNewElement and mxmlNewText
+functions. The first argument of mxmlNewText specifies the parent node
+(node). 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:
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val1");
-The resulting in-memory XML document can then be saved or
-processed just like one loaded from disk or a string.
+The resulting in-memory XML document can then be saved or processed just like
+one loaded from disk or a string.
-
+
Loading XML
You load an XML file using the ?xml element if the parent node
is NULL.
-
+
Saving XML
You save an XML file using the mxmlSaveAllocString()
returns a string buffer that was allocated using
malloc().
+
Controlling Line Wrapping
When saving XML documents, Mini-XML normally wraps output
@@ -382,6 +428,25 @@ overrides the default wrap margin:
mxmlSetWrapMargin(0);
+Memory Management
+
+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:
+
+
+ mxmlDelete(tree);
+
+
+You can also use reference counting to manage memory usage. The
+mxmlRetain and
+mxmlRelease functions increment and
+decrement a node's use count, respectively. When the use count goes to 0,
+mxmlRelease will automatically call mxmlDelete to actually
+free the memory used by the node tree. New nodes automatically start with a
+use count of 1.
+
Finding and Iterating Nodes
@@ -522,13 +587,15 @@ three constants:
-Finding Value Nodes
+Finding Specific Nodes
-You can find the value of a specific node in the tree using the mxmlFindValue, for example:
+
You can find specific nodes in the tree using the mxmlFindPath, for example:
- mxml_node_t *value = mxmlFindValue(tree, "path/to/*/foo/bar");
+ mxml_node_t *value;
+
+ value = mxmlFindPath(tree, "path/to/*/foo/bar");
The second argument is a "path" to the parent node. Each component of the
diff --git a/doc/docset.intro b/doc/docset.intro
index a900653..a179ddd 100644
--- a/doc/docset.intro
+++ b/doc/docset.intro
@@ -18,7 +18,7 @@ as do most vendors' ANSI C compilers) and a "make" program.
The "mxmlFindPath()" function finds the (first) value node under a specific
+element using a "path":
+
+The "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and
+"mxmlGetText()" functions retrieve the value from a node:
+
+