| <!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.8</TITLE> |
| <META NAME="author" CONTENT="Michael R. Sweet"> |
| <META NAME="copyright" CONTENT="Copyright 2003-2014"> |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-iso-8859-1"> |
| <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> |
| <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1> |
| <BR> |
| <BR><B><A HREF="#INTRO">Introduction</A></B> |
| <UL> |
| <LI><A HREF="#1_1">Organization of This Document</A></LI> |
| <LI><A HREF="#1_2">Notation Conventions</A></LI> |
| <LI><A HREF="#1_3">Abbreviations</A></LI> |
| <LI><A HREF="#1_4">Other References</A></LI> |
| <LI><A HREF="#1_5">Legal Stuff</A></LI> |
| </UL> |
| <B><A HREF="#INSTALL">Building, Installing, and Packaging Mini-XML</A></B> |
| <UL> |
| <LI><A HREF="#2_1">Compiling Mini-XML</A> |
| <UL> |
| <LI><A HREF="#2_1_1">Compiling with Visual C++</A></LI> |
| <LI><A HREF="#2_1_2">Compiling with Command-Line Tools</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#2_2">Installing Mini-XML</A></LI> |
| <LI><A HREF="#2_3">Creating Mini-XML Packages</A></LI> |
| </UL> |
| <B><A HREF="#BASICS">Getting Started with Mini-XML</A></B> |
| <UL> |
| <LI><A HREF="#3_1">The Basics</A></LI> |
| <LI><A HREF="#3_2">Nodes</A> |
| <UL> |
| <LI><A HREF="#3_2_1">CDATA Nodes</A></LI> |
| <LI><A HREF="#3_2_2">Custom Nodes</A></LI> |
| <LI><A HREF="#3_2_3">Comment Nodes</A></LI> |
| <LI><A HREF="#3_2_4">Element Nodes</A></LI> |
| <LI><A HREF="#3_2_5">Integer Nodes</A></LI> |
| <LI><A HREF="#3_2_6">Opaque Nodes</A></LI> |
| <LI><A HREF="#3_2_7">Text Nodes</A></LI> |
| <LI><A HREF="#3_2_8">Processing Instruction Nodes</A></LI> |
| <LI><A HREF="#3_2_9">Real Number Nodes</A></LI> |
| <LI><A HREF="#3_2_10">XML Declaration Nodes</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#3_3">Creating XML Documents</A></LI> |
| <LI><A HREF="#3_4">Loading XML</A></LI> |
| <LI><A HREF="#3_5">Saving XML</A> |
| <UL> |
| <LI><A HREF="#3_5_1">Controlling Line Wrapping</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#3_6">Memory Management</A></LI> |
| <LI><A HREF="#3_7">Finding and Iterating Nodes</A></LI> |
| <LI><A HREF="#3_8">Finding Specific Nodes</A></LI> |
| </UL> |
| <B><A HREF="#ADVANCED">More Mini-XML Programming Techniques</A></B> |
| <UL> |
| <LI><A HREF="#LOAD_CALLBACKS">Load Callbacks</A></LI> |
| <LI><A HREF="#SAVE_CALLBACKS">Save Callbacks</A></LI> |
| <LI><A HREF="#4_3">Custom Data Types</A></LI> |
| <LI><A HREF="#4_4">Changing Node Values</A></LI> |
| <LI><A HREF="#4_5">Formatted Text</A></LI> |
| <LI><A HREF="#4_6">Indexing</A></LI> |
| <LI><A HREF="#4_7">SAX (Stream) Loading of Documents</A></LI> |
| </UL> |
| <B><A HREF="#MXMLDOC">Using the mxmldoc Utility</A></B> |
| <UL> |
| <LI><A HREF="#5_1">The Basics</A> |
| <UL> |
| <LI><A HREF="#5_1_1">Creating Man Pages</A></LI> |
| <LI><A HREF="#5_1_2">Creating Xcode Documentation Sets</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#5_2">Commenting Your Code</A></LI> |
| <LI><A HREF="#5_3">Titles, Sections, and Introductions</A></LI> |
| </UL> |
| <B><A HREF="#LICENSE">Mini-XML License</A></B> |
| <BR> |
| <BR><B><A HREF="#RELNOTES">Release Notes</A></B> |
| <UL></UL> |
| <B><A HREF="#REFERENCE">Library Reference</A></B> |
| <UL> |
| <LI><A HREF="#8_1">Contents</A></LI> |
| <LI><A HREF="#FUNCTIONS">Functions</A> |
| <UL> |
| <LI><A HREF="#mxmlAdd">mxmlAdd</A></LI> |
| <LI><A HREF="#mxmlDelete">mxmlDelete</A></LI> |
| <LI><A HREF="#8_2_3">mxmlElementDeleteAttr</A></LI> |
| <LI><A HREF="#mxmlElementGetAttr">mxmlElementGetAttr</A></LI> |
| <LI><A HREF="#mxmlElementSetAttr">mxmlElementSetAttr</A></LI> |
| <LI><A HREF="#8_2_6">mxmlElementSetAttrf</A></LI> |
| <LI><A HREF="#mxmlEntityAddCallback">mxmlEntityAddCallback</A></LI> |
| <LI><A HREF="#mxmlEntityGetName">mxmlEntityGetName</A></LI> |
| <LI><A HREF="#mxmlEntityGetValue">mxmlEntityGetValue</A></LI> |
| <LI><A HREF="#mxmlEntityRemoveCallback">mxmlEntityRemoveCallback</A></LI> |
| <LI><A HREF="#mxmlFindElement">mxmlFindElement</A></LI> |
| <LI><A HREF="#8_2_12">mxmlFindPath</A></LI> |
| <LI><A HREF="#8_2_13">mxmlGetCDATA</A></LI> |
| <LI><A HREF="#8_2_14">mxmlGetCustom</A></LI> |
| <LI><A HREF="#8_2_15">mxmlGetElement</A></LI> |
| <LI><A HREF="#8_2_16">mxmlGetFirstChild</A></LI> |
| <LI><A HREF="#8_2_17">mxmlGetInteger</A></LI> |
| <LI><A HREF="#8_2_18">mxmlGetLastChild</A></LI> |
| <LI><A HREF="#mxmlGetNextSibling">mxmlGetNextSibling</A></LI> |
| <LI><A HREF="#8_2_20">mxmlGetOpaque</A></LI> |
| <LI><A HREF="#8_2_21">mxmlGetParent</A></LI> |
| <LI><A HREF="#8_2_22">mxmlGetPrevSibling</A></LI> |
| <LI><A HREF="#8_2_23">mxmlGetReal</A></LI> |
| <LI><A HREF="#8_2_24">mxmlGetRefCount</A></LI> |
| <LI><A HREF="#8_2_25">mxmlGetText</A></LI> |
| <LI><A HREF="#8_2_26">mxmlGetType</A></LI> |
| <LI><A HREF="#8_2_27">mxmlGetUserData</A></LI> |
| <LI><A HREF="#mxmlIndexDelete">mxmlIndexDelete</A></LI> |
| <LI><A HREF="#mxmlIndexEnum">mxmlIndexEnum</A></LI> |
| <LI><A HREF="#mxmlIndexFind">mxmlIndexFind</A></LI> |
| <LI><A HREF="#8_2_31">mxmlIndexGetCount</A></LI> |
| <LI><A HREF="#mxmlIndexNew">mxmlIndexNew</A></LI> |
| <LI><A HREF="#mxmlIndexReset">mxmlIndexReset</A></LI> |
| <LI><A HREF="#mxmlLoadFd">mxmlLoadFd</A></LI> |
| <LI><A HREF="#mxmlLoadFile">mxmlLoadFile</A></LI> |
| <LI><A HREF="#mxmlLoadString">mxmlLoadString</A></LI> |
| <LI><A HREF="#8_2_37">mxmlNewCDATA</A></LI> |
| <LI><A HREF="#8_2_38">mxmlNewCustom</A></LI> |
| <LI><A HREF="#mxmlNewElement">mxmlNewElement</A></LI> |
| <LI><A HREF="#mxmlNewInteger">mxmlNewInteger</A></LI> |
| <LI><A HREF="#mxmlNewOpaque">mxmlNewOpaque</A></LI> |
| <LI><A HREF="#mxmlNewReal">mxmlNewReal</A></LI> |
| <LI><A HREF="#mxmlNewText">mxmlNewText</A></LI> |
| <LI><A HREF="#mxmlNewTextf">mxmlNewTextf</A></LI> |
| <LI><A HREF="#8_2_45">mxmlNewXML</A></LI> |
| <LI><A HREF="#8_2_46">mxmlRelease</A></LI> |
| <LI><A HREF="#mxmlRemove">mxmlRemove</A></LI> |
| <LI><A HREF="#8_2_48">mxmlRetain</A></LI> |
| <LI><A HREF="#8_2_49">mxmlSAXLoadFd</A></LI> |
| <LI><A HREF="#8_2_50">mxmlSAXLoadFile</A></LI> |
| <LI><A HREF="#8_2_51">mxmlSAXLoadString</A></LI> |
| <LI><A HREF="#mxmlSaveAllocString">mxmlSaveAllocString</A></LI> |
| <LI><A HREF="#mxmlSaveFd">mxmlSaveFd</A></LI> |
| <LI><A HREF="#mxmlSaveFile">mxmlSaveFile</A></LI> |
| <LI><A HREF="#mxmlSaveString">mxmlSaveString</A></LI> |
| <LI><A HREF="#8_2_56">mxmlSetCDATA</A></LI> |
| <LI><A HREF="#8_2_57">mxmlSetCustom</A></LI> |
| <LI><A HREF="#mxmlSetCustomHandlers">mxmlSetCustomHandlers</A></LI> |
| <LI><A HREF="#mxmlSetElement">mxmlSetElement</A></LI> |
| <LI><A HREF="#mxmlSetErrorCallback">mxmlSetErrorCallback</A></LI> |
| <LI><A HREF="#mxmlSetInteger">mxmlSetInteger</A></LI> |
| <LI><A HREF="#mxmlSetOpaque">mxmlSetOpaque</A></LI> |
| <LI><A HREF="#mxmlSetReal">mxmlSetReal</A></LI> |
| <LI><A HREF="#mxmlSetText">mxmlSetText</A></LI> |
| <LI><A HREF="#mxmlSetTextf">mxmlSetTextf</A></LI> |
| <LI><A HREF="#8_2_66">mxmlSetUserData</A></LI> |
| <LI><A HREF="#8_2_67">mxmlSetWrapMargin</A></LI> |
| <LI><A HREF="#mxmlWalkNext">mxmlWalkNext</A></LI> |
| <LI><A HREF="#mxmlWalkPrev">mxmlWalkPrev</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#TYPES">Data Types</A> |
| <UL> |
| <LI><A HREF="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</A></LI> |
| <LI><A HREF="#mxml_custom_load_cb_t">mxml_custom_load_cb_t</A></LI> |
| <LI><A HREF="#mxml_custom_save_cb_t">mxml_custom_save_cb_t</A></LI> |
| <LI><A HREF="#mxml_entity_cb_t">mxml_entity_cb_t</A></LI> |
| <LI><A HREF="#mxml_error_cb_t">mxml_error_cb_t</A></LI> |
| <LI><A HREF="#mxml_index_t">mxml_index_t</A></LI> |
| <LI><A HREF="#mxml_load_cb_t">mxml_load_cb_t</A></LI> |
| <LI><A HREF="#mxml_node_t">mxml_node_t</A></LI> |
| <LI><A HREF="#mxml_save_cb_t">mxml_save_cb_t</A></LI> |
| <LI><A HREF="#mxml_sax_cb_t">mxml_sax_cb_t</A></LI> |
| <LI><A HREF="#mxml_sax_event_t">mxml_sax_event_t</A></LI> |
| <LI><A HREF="#mxml_type_t">mxml_type_t</A></LI> |
| </UL> |
| </LI> |
| <LI><A HREF="#ENUMERATIONS">Constants</A> |
| <UL> |
| <LI><A HREF="#mxml_sax_event_e">mxml_sax_event_e</A></LI> |
| <LI><A HREF="#mxml_type_e">mxml_type_e</A></LI> |
| </UL> |
| </LI> |
| </UL> |
| <B><A HREF="#SCHEMA">XML Schema</A></B> |
| <UL></UL> |
| <HR NOSHADE> |
| <H1 align="right"><A name="INTRO"><IMG align="right" alt="0" height="100" |
| hspace="10" src="0.gif" width="100"></A>Introduction</H1> |
| <P>This programmers manual describes Mini-XML version 2.8, a small XML |
| parsing library that you can use to read and write XML data files in |
| your C and C++ applications.</P> |
| <P>Mini-XML was initially developed for the <A href="http://gutenprint.sf.net/"> |
| Gutenprint</A> project to replace the rather large and unwieldy <TT> |
| libxml2</TT> 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><EM>It's bad enough that we require libxml2, but rolling our |
| own XML parser is a bit more than we can handle.</EM></BLOCKQUOTE> |
| <P>I then replied with:</P> |
| <BLOCKQUOTE><EM>Given the limited scope of what you use in XML, it |
| should be trivial to code a mini-XML API in a few hundred lines of |
| code.</EM></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 3,792 lines of code, |
| compared to 140,410 lines of code for libxml2 version 2.9.1.</P> |
| <P>Aside from Gutenprint, Mini-XML is used for the following |
| projects/software applications:</P> |
| <UL> |
| <LI><A href="https://www.cups.org/">CUPS</A></LI> |
| <LI><A href="http://zynaddsubfx.sourceforge.net">ZynAddSubFX</A></LI> |
| </UL> |
| <P>Please file a bug on msweet.org if you would like your project added |
| or removed from this list, or if you have any comments/quotes you would |
| like me to publish about your experiences with Mini-XML.</P> |
| |
| <!-- NEED 1in --> |
| <H2><A NAME="1_1">Organization of This Document</A></H2> |
| <P>This manual is organized into the following chapters and appendices:</P> |
| <UL> |
| <LI>Chapter 1, "<A href="#INSTALL">Building, Installing, and Packaging |
| Mini-XML</A>", provides compilation, installation, and packaging |
| instructions for Mini-XML.</LI> |
| <LI>Chapter 2, "<A href="#BASICS">Getting Started with Mini-XML</A>", |
| shows how to use the Mini-XML library in your programs.</LI> |
| <LI>Chapter 3, "<A href="#ADVANCED">More Mini-XML Programming Techniques</A> |
| ", shows additional ways to use the Mini-XML library.</LI> |
| <LI>Chapter 4, "<A href="#MXMLDOC">Using the mxmldoc Utility</A>", |
| describes how to use the <TT>mxmldoc(1)</TT> program to generate |
| software documentation.</LI> |
| <LI>Appendix A, "<A href="#LICENSE">Mini-XML License</A>", provides the |
| terms and conditions for using and distributing Mini-XML.</LI> |
| <LI>Appendix B, "<A href="#RELNOTES">Release Notes</A>", lists the |
| changes in each release of Mini-XML.</LI> |
| <LI>Appendix C, "<A href="#REFERENCE">Library Reference</A>", contains a |
| complete reference for Mini-XML, generated by <TT>mxmldoc</TT>.</LI> |
| <LI>Appendix D, "<A href="#SCHEMA">XML Schema</A>", shows the XML schema |
| used for the XML files produced by <TT>mxmldoc</TT>.</LI> |
| </UL> |
| |
| <!-- NEED 10 --> |
| <H2><A NAME="1_2">Notation Conventions</A></H2> |
| <P>Various font and syntax conventions are used in this guide. Examples |
| and their meanings and uses are explained below:</P> |
| <DL> |
| <DT><CODE>mxmldoc</CODE> |
| <BR> <CODE>mxmldoc(1)</CODE></DT> |
| <DD>The names of commands; the first mention of a command or function in |
| a chapter is followed by a manual page section number. |
| <BR> |
| <BR></DD> |
| <DT><VAR>/var</VAR> |
| <BR><VAR> /etc/hosts</VAR></DT> |
| <DD>File and directory names. |
| <BR> |
| <BR></DD> |
| <DT><TT>Request ID is Printer-123</TT></DT> |
| <DD>Screen output. |
| <BR> |
| <BR></DD> |
| <DT><KBD>lp -d printer filename ENTER</KBD></DT> |
| <DD>Literal user input; special keys like <KBD>ENTER</KBD> are in ALL |
| CAPS. |
| <BR> |
| <BR></DD> |
| <DT>12.3</DT> |
| <DD>Numbers in the text are written using the period (.) to indicate the |
| decimal point. |
| <BR> |
| <BR></DD> |
| </DL> |
| |
| <!-- NEED 10 --> |
| <H2><A NAME="1_3">Abbreviations</A></H2> |
| <P>The following abbreviations are used throughout this manual:</P> |
| <DL> |
| <DT>Gb</DT> |
| <DD>Gigabytes, or 1073741824 bytes |
| <BR> |
| <BR></DD> |
| <DT>kb</DT> |
| <DD>Kilobytes, or 1024 bytes |
| <BR> |
| <BR></DD> |
| <DT>Mb</DT> |
| <DD>Megabytes, or 1048576 bytes |
| <BR> |
| <BR></DD> |
| <DT>UTF-8, UTF-16</DT> |
| <DD>Unicode Transformation Format, 8-bit or 16-bit |
| <BR> |
| <BR></DD> |
| <DT>W3C</DT> |
| <DD>World Wide Web Consortium |
| <BR> |
| <BR></DD> |
| <DT>XML</DT> |
| <DD>Extensible Markup Language |
| <BR> |
| <BR></DD> |
| </DL> |
| |
| <!-- NEED 12 --> |
| <H2><A NAME="1_4">Other References</A></H2> |
| <DL> |
| <DT>The Unicode Standard, Version 4.0, Addison-Wesley, ISBN |
| 0-321-18578-1</DT> |
| <DD>The definition of the Unicode character set which is used for XML. |
| <BR> |
| <BR></DD> |
| <DT><A href="http://www.w3.org/TR/2004/REC-xml-20040204/">Extensible |
| Markup Language (XML) 1.0 (Third Edition)</A></DT> |
| <DD>The XML specification from the World Wide Web Consortium (W3C) |
| <BR> |
| <BR></DD> |
| </DL> |
| |
| <!-- NEED 6 --> |
| <H2><A NAME="1_5">Legal Stuff</A></H2> |
| <P>The Mini-XML library is copyright 2003-2014 by Michael R Sweet. |
| License terms are described in <A href="#LICENSE">Appendix A - Mini-XML |
| License</A>.</P> |
| <HR NOSHADE> |
| <H1 align="right"><A name="INSTALL"><IMG align="right" alt="1" height="100" |
| hspace="10" src="1.gif" width="100"></A>Building, Installing, and |
| Packaging Mini-XML</H1> |
| <P>This chapter describes how to build, install, and package Mini-XML on |
| your system from the source archive. You will need an ANSI/ISO-C |
| compatible compiler to build Mini-XML - GCC works, as do most vendors' |
| C compilers. If you are building Mini-XML on Windows, we recommend |
| using the Visual C++ environment with the supplied solution file. For |
| other operating systems, you'll need a POSIX-compatible shell and <TT> |
| make</TT> program in addition to the C compiler.</P> |
| <H2><A NAME="2_1">Compiling Mini-XML</A></H2> |
| <P>Mini-XML comes with both an autoconf-based configure script and a |
| Visual C++ solution that can be used to compile the library and |
| associated tools.</P> |
| <H3><A NAME="2_1_1">Compiling with Visual C++</A></H3> |
| <P>Open the<VAR> mxml.sln</VAR> solution in the<VAR> vcnet</VAR> folder. |
| Choose the desired build configuration, "Debug" (the default) or |
| "Release", and then choose<VAR> Build Solution</VAR> from the<VAR> |
| Build</VAR> menu.</P> |
| <H3><A NAME="2_1_2">Compiling with Command-Line Tools</A></H3> |
| <P>Type the following command to configure the Mini-XML source code for |
| your system:</P> |
| <PRE> |
| <KBD>./configure ENTER</KBD> |
| </PRE> |
| <P>The default install prefix is<VAR> /usr/local</VAR>, which can be |
| overridden using the <KBD>--prefix</KBD> option:</P> |
| <PRE> |
| <KBD>./configure --prefix=/foo ENTER</KBD> |
| </PRE> |
| <P>Other configure options can be found using the <KBD>--help</KBD> |
| option:</P> |
| <PRE> |
| <KBD>./configure --help ENTER</KBD> |
| </PRE> |
| <P>Once you have configured the software, use the <TT>make(1)</TT> |
| program to do the build and run the test program to verify that things |
| are working, as follows:</P> |
| <PRE> |
| <KBD>make ENTER</KBD> |
| </PRE> |
| <H2><A NAME="2_2">Installing Mini-XML</A></H2> |
| <P>If you are using Visual C++, copy the<VAR> mxml.lib</VAR> and and<VAR> |
| mxml.h</VAR> files to the Visual C++<VAR> lib</VAR> and<VAR> include<VAR> |
| directories, respectively.</VAR></VAR></P> |
| <P>Otherwise, use the <TT>make</TT> command with the <KBD>install</KBD> |
| target to install Mini-XML in the configured directories:</P> |
| <PRE> |
| <KBD>make install ENTER</KBD> |
| </PRE> |
| <H2><A NAME="2_3">Creating Mini-XML Packages</A></H2> |
| <P>Mini-XML includes two files that can be used to create binary |
| packages. The first file is<VAR> mxml.spec</VAR> which is used by the <TT> |
| rpmbuild(8)</TT> software to create Red Hat Package Manager ("RPM") |
| packages which are commonly used on Linux. Since <TT>rpmbuild</TT> |
| wants to compile the software on its own, you can provide it with the |
| Mini-XML tar file to build the package:</P> |
| <PRE> |
| <KBD>rpmbuild -ta mxml-<I>version</I>.tar.gz ENTER</KBD> |
| </PRE> |
| <P>The second file is<VAR> mxml.list</VAR> which is used by the <TT> |
| epm(1)</TT> program to create software packages in a variety of formats. |
| The <TT>epm</TT> program is available from the following URL:</P> |
| <PRE> |
| <A href="http://www.epmhome.org/">http://www.epmhome.org/</A> |
| </PRE> |
| <P>Use the <TT>make</TT> command with the <KBD>epm</KBD> target to |
| create portable and native packages for your system:</P> |
| <PRE> |
| <KBD>make epm ENTER</KBD> |
| </PRE> |
| <P>The packages are stored in a subdirectory named<VAR> dist</VAR> for |
| your convenience. The portable packages utilize scripts and tar files |
| to install the software on the target system. After extracting the |
| package archive, use the<VAR> mxml.install</VAR> script to install the |
| software.</P> |
| <P>The native packages will be in the local OS's native format: RPM for |
| Red Hat Linux, DPKG for Debian Linux, PKG for Solaris, and so forth. |
| Use the corresponding commands to install the native packages.</P> |
| <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 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> |
| <P>For example, if you have an XML file like the following:</P> |
| <PRE> |
| <?xml version="1.0" encoding="utf-8"?> |
| <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 version="1.0" encoding="utf-8"? |
| | |
| 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 sibling node and "|" is a pointer to |
| the first child or parent node.</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><A NAME="3_2_1">CDATA Nodes</A></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><A NAME="3_2_2">Custom Nodes</A></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><A NAME="3_2_3">Comment Nodes</A></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><A NAME="3_2_4">Element Nodes</A></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><A NAME="3_2_5">Integer Nodes</A></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><A NAME="3_2_6">Opaque Nodes</A></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><A NAME="3_2_7">Text Nodes</A></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><A NAME="3_2_8">Processing Instruction Nodes</A></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><A NAME="3_2_9">Real Number Nodes</A></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><A NAME="3_2_10">XML Declaration Nodes</A></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> |
| <!-- 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> |
| |
| <!-- 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><data></TT> node used for this document using |
| the <A href="#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="#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> |
| |
| <!-- NEED 15 --> |
| <H2><A NAME="3_4">Loading XML</A></H2> |
| <P>You load an XML file using the <A href="#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="#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="#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> |
| |
| <!-- NEED 15 --> |
| <H2><A NAME="3_5">Saving XML</A></H2> |
| <P>You save an XML file using the <A href="#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="#mxmlSaveAllocString"><TT>mxmlSaveAllocString</TT></A>, |
| and <A href="#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> |
| |
| <!-- NEED 15 --> |
| <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="#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> |
| <H2><A NAME="3_6">Memory Management</A></H2> |
| <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> |
| <PRE> |
| mxmlDelete(tree); |
| </PRE> |
| <P>You can also use reference counting to manage memory usage. The <A href="#mxmlRetain"> |
| <TT>mxmlRetain</TT></A> and <A href="#mxmlRelease"><TT>mxmlRelease</TT></A> |
| functions increment and decrement a node's use count, respectively. |
| When the use count goes to 0, <TT>mxmlRelease</TT> will automatically |
| call <TT>mxmlDelete</TT> to actually free the memory used by the node |
| tree. New nodes automatically start with a use count of 1.</P> |
| |
| <!-- NEW PAGE--> |
| <H2><A NAME="3_7">Finding and Iterating Nodes</A></H2> |
| <P>The <A href="#mxmlWalkPrev"><TT>mxmlWalkPrev</TT></A> and <A href="#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="#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> |
| <H2><A NAME="3_8">Finding Specific Nodes</A></H2> |
| <P>You can find specific nodes in the tree using the <A href="#mxmlFindValue"> |
| <TT>mxmlFindPath</TT></A>, for example:</P> |
| <PRE> |
| mxml_node_t *value; |
| |
| value = mxmlFindPath(tree, "path/to/*/foo/bar"); |
| </PRE> |
| <P>The second argument is a "path" to the parent node. Each component of |
| the path is separated by a slash (/) and represents a named element in |
| the document tree or a wildcard (*) path representing 0 or more |
| intervening nodes.</P> |
| <HR NOSHADE> |
| <H1 align="right"><A name="ADVANCED"><IMG align="right" alt="3" height="100" |
| hspace="10" src="3.gif" width="100"></A>More Mini-XML Programming |
| Techniques</H1> |
| <P>This chapter shows additional ways to use the Mini-XML library in |
| your programs.</P> |
| <H2><A name="LOAD_CALLBACKS">Load Callbacks</A></H2> |
| <P><A href="#LOAD_XML">Chapter 2</A> introduced the <A href="#mxmlLoadFile"> |
| <TT>mxmlLoadFile()</TT></A> and <A href="#mxmlLoadString"><TT> |
| mxmlLoadString()</TT></A> functions. The last argument to these |
| functions is a callback function which is used to determine the value |
| type of each data node in an XML document.</P> |
| <P>Mini-XML defines several standard callbacks for simple XML data |
| files:</P> |
| <UL> |
| <LI><TT>MXML_INTEGER_CALLBACK</TT> - All data nodes contain |
| whitespace-separated integers.</LI> |
| <LI><TT>MXML_OPAQUE_CALLBACK</TT> - All data nodes contain opaque |
| strings ("CDATA").</LI> |
| <LI><TT>MXML_REAL_CALLBACK</TT> - All data nodes contain |
| whitespace-separated floating-point numbers.</LI> |
| <LI><TT>MXML_TEXT_CALLBACK</TT> - All data nodes contain |
| whitespace-separated strings.</LI> |
| </UL> |
| <P>You can provide your own callback functions for more complex XML |
| documents. Your callback function will receive a pointer to the current |
| element node and must return the value type of the immediate children |
| for that element node: <TT>MXML_INTEGER</TT>, <TT>MXML_OPAQUE</TT>, <TT> |
| MXML_REAL</TT>, or <TT>MXML_TEXT</TT>. The function is called<I> after</I> |
| the element and its attributes have been read, so you can look at the |
| element name, attributes, and attribute values to determine the proper |
| value type to return.</P> |
| |
| <!-- NEED 2in --> |
| <P>The following callback function looks for an attribute named "type" |
| or the element name to determine the value type for its child nodes:</P> |
| <PRE> |
| mxml_type_t |
| type_cb(mxml_node_t *node) |
| { |
| const char *type; |
| |
| /* |
| * You can lookup attributes and/or use the |
| * element name, hierarchy, etc... |
| */ |
| |
| type = mxmlElementGetAttr(node, "type"); |
| if (type == NULL) |
| type = mxmlGetElement(node); |
| |
| if (!strcmp(type, "integer")) |
| return (MXML_INTEGER); |
| else if (!strcmp(type, "opaque")) |
| return (MXML_OPAQUE); |
| else if (!strcmp(type, "real")) |
| return (MXML_REAL); |
| else |
| return (MXML_TEXT); |
| } |
| </PRE> |
| <P>To use this callback function, simply use the name when you call any |
| of the load functions:</P> |
| <PRE> |
| FILE *fp; |
| mxml_node_t *tree; |
| |
| fp = fopen("filename.xml", "r"); |
| tree = mxmlLoadFile(NULL, fp, <B>type_cb</B>); |
| fclose(fp); |
| </PRE> |
| <H2><A name="SAVE_CALLBACKS">Save Callbacks</A></H2> |
| <P><A href="#LOAD_XML">Chapter 2</A> also introduced the <A href="#mxmlSaveFile"> |
| <TT>mxmlSaveFile()</TT></A>, <A href="#mxmlSaveString"><TT> |
| mxmlSaveString()</TT></A>, and <A href="#mxmlSaveAllocString"><TT> |
| mxmlSaveAllocString()</TT></A> functions. The last argument to these |
| functions is a callback function which is used to automatically insert |
| whitespace in an XML document.</P> |
| <P>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 <TT> |
| MXML_WS_BEFORE_OPEN</TT>, <TT>MXML_WS_AFTER_OPEN</TT>, <TT> |
| MXML_WS_BEFORE_CLOSE</TT>, or <TT>MXML_WS_AFTER_CLOSE</TT>. The callback |
| function should return <TT>NULL</TT> if no whitespace should be added |
| and 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> |
| <PRE> |
| const char * |
| whitespace_cb(mxml_node_t *node, |
| int where) |
| { |
| const char *name; |
| |
| /* |
| * We can conditionally break to a new line |
| * before or after any element. These are |
| * just common HTML elements... |
| */ |
| |
| name = mxmlGetElement(node); |
| |
| if (!strcmp(name, "html") || |
| !strcmp(name, "head") || |
| !strcmp(name, "body") || |
| !strcmp(name, "pre") || |
| !strcmp(name, "p") || |
| !strcmp(name, "h1") || |
| !strcmp(name, "h2") || |
| !strcmp(name, "h3") || |
| !strcmp(name, "h4") || |
| !strcmp(name, "h5") || |
| !strcmp(name, "h6")) |
| { |
| /* |
| * Newlines before open and after |
| * close... |
| */ |
| |
| if (where == MXML_WS_BEFORE_OPEN || |
| where == MXML_WS_AFTER_CLOSE) |
| return ("\n"); |
| } |
| else if (!strcmp(name, "dl") || |
| !strcmp(name, "ol") || |
| !strcmp(name, "ul")) |
| { |
| /* |
| * Put a newline before and after list |
| * elements... |
| */ |
| |
| return ("\n"); |
| } |
| else if (!strcmp(name, "dd") || |
| !strcmp(name, "dt") || |
| !strcmp(name, "li")) |
| { |
| /* |
| * Put a tab before <li>'s, * <dd>'s, |
| * and <dt>'s, and a newline after them... |
| */ |
| |
| if (where == MXML_WS_BEFORE_OPEN) |
| return ("\t"); |
| else if (where == MXML_WS_AFTER_CLOSE) |
| return ("\n"); |
| } |
| |
| /* |
| * Return NULL for no added whitespace... |
| */ |
| |
| return (NULL); |
| } |
| </PRE> |
| <P>To use this callback function, simply use the name when you call any |
| of the save functions:</P> |
| <PRE> |
| FILE *fp; |
| mxml_node_t *tree; |
| |
| fp = fopen("filename.xml", "w"); |
| mxmlSaveFile(tree, fp, <B>whitespace_cb</B>); |
| fclose(fp); |
| </PRE> |
| |
| <!-- NEED 10 --> |
| <H2><A NAME="4_3">Custom Data Types</A></H2> |
| <P>Mini-XML supports custom data types via global load and save |
| callbacks. Only a single set of callbacks can be active at any time, |
| however your callbacks can store additional information in order to |
| support multiple custom data types as needed. The <TT>MXML_CUSTOM</TT> |
| node type identifies custom data nodes.</P> |
| <P>The load callback receives a pointer to the current data node and a |
| string of opaque character data from the XML source with character |
| entities converted to the corresponding UTF-8 characters. For example, |
| if we wanted to support a custom date/time type whose value is encoded |
| as "yyyy-mm-ddThh:mm:ssZ" (ISO format), the load callback would look |
| like the following:</P> |
| <PRE> |
| typedef struct |
| { |
| unsigned year, /* Year */ |
| month, /* Month */ |
| day, /* Day */ |
| hour, /* Hour */ |
| minute, /* Minute */ |
| second; /* Second */ |
| time_t unix; /* UNIX time */ |
| } iso_date_time_t; |
| |
| int |
| load_custom(mxml_node_t *node, |
| const char *data) |
| { |
| iso_date_time_t *dt; |
| struct tm tmdata; |
| |
| /* |
| * Allocate data structure... |
| */ |
| |
| dt = calloc(1, sizeof(iso_date_time_t)); |
| |
| /* |
| * Try reading 6 unsigned integers from the |
| * data string... |
| */ |
| |
| if (sscanf(data, "%u-%u-%uT%u:%u:%uZ", |
| &(dt->year), &(dt->month), |
| &(dt->day), &(dt->hour), |
| &(dt->minute), |
| &(dt->second)) != 6) |
| { |
| /* |
| * Unable to read numbers, free the data |
| * structure and return an error... |
| */ |
| |
| free(dt); |
| |
| return (-1); |
| } |
| |
| /* |
| * Range check values... |
| */ |
| |
| if (dt->month <1 || dt->month > 12 || |
| dt->day <1 || dt->day > 31 || |
| dt->hour <0 || dt->hour > 23 || |
| dt->minute <0 || dt->minute > 59 || |
| dt->second <0 || dt->second > 59) |
| { |
| /* |
| * Date information is out of range... |
| */ |
| |
| free(dt); |
| |
| return (-1); |
| } |
| |
| /* |
| * Convert ISO time to UNIX time in |
| * seconds... |
| */ |
| |
| tmdata.tm_year = dt->year - 1900; |
| tmdata.tm_mon = dt->month - 1; |
| tmdata.tm_day = dt->day; |
| tmdata.tm_hour = dt->hour; |
| tmdata.tm_min = dt->minute; |
| tmdata.tm_sec = dt->second; |
| |
| dt->unix = gmtime(&tmdata); |
| |
| /* |
| * Assign custom node data and destroy |
| * function pointers... |
| */ |
| |
| mxmlSetCustom(node, data, destroy); |
| |
| /* |
| * Return with no errors... |
| */ |
| |
| return (0); |
| } |
| </PRE> |
| <P>The function itself can return 0 on success or -1 if it is unable to |
| decode the custom data or the data contains an error. Custom data nodes |
| contain a <TT>void</TT> pointer to the 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> |
| <PRE> |
| char * |
| save_custom(mxml_node_t *node) |
| { |
| char data[255]; |
| iso_date_time_t *dt; |
| |
| |
| dt = (iso_date_time_t *)mxmlGetCustom(node); |
| |
| snprintf(data, sizeof(data), |
| "%04u-%02u-%02uT%02u:%02u:%02uZ", |
| dt->year, dt->month, dt->day, |
| dt->hour, dt->minute, dt->second); |
| |
| return (strdup(data)); |
| } |
| </PRE> |
| <P>You register the callback functions using the <A href="#mxmlSetCustomHandlers"> |
| <TT>mxmlSetCustomHandlers()</TT></A> function:</P> |
| <PRE> |
| mxmlSetCustomHandlers(<B>load_custom</B>, |
| <B>save_custom</B>); |
| </PRE> |
| |
| <!-- NEED 20 --> |
| <H2><A NAME="4_4">Changing Node Values</A></H2> |
| <P>All of the examples so far have concentrated on creating and loading |
| new XML data nodes. Many applications, however, need to manipulate or |
| change the nodes during their operation, so Mini-XML provides functions |
| to change node values safely and without leaking memory.</P> |
| <P>Existing nodes can be changed using the <A href="#mxmlSetElement"><TT> |
| mxmlSetElement()</TT></A>, <A href="#mxmlSetInteger"><TT> |
| mxmlSetInteger()</TT></A>, <A href="#mxmlSetOpaque"><TT>mxmlSetOpaque()</TT> |
| </A>, <A href="#mxmlSetReal"><TT>mxmlSetReal()</TT></A>, <A href="#mxmlSetText"> |
| <TT>mxmlSetText()</TT></A>, and <A href="#mxmlSetTextf"><TT> |
| mxmlSetTextf()</TT></A> functions. For example, use the following |
| function call to change a text node to contain the text "new" with |
| leading whitespace:</P> |
| <PRE> |
| mxml_node_t *node; |
| |
| mxmlSetText(node, 1, "new"); |
| </PRE> |
| <H2><A NAME="4_5">Formatted Text</A></H2> |
| <P>The <A href="#mxmlNewTextf"><TT>mxmlNewTextf()</TT></A> and <A href="#mxmlSetTextf"> |
| <TT>mxmlSetTextf()</TT></A> functions create and change text nodes, |
| respectively, using <TT>printf</TT>-style format strings and arguments. |
| For example, use the following function call to create a new text node |
| containing a constructed filename:</P> |
| <PRE> |
| mxml_node_t *node; |
| |
| node = mxmlNewTextf(node, 1, "%s/%s", |
| path, filename); |
| </PRE> |
| <H2><A NAME="4_6">Indexing</A></H2> |
| <P>Mini-XML provides functions for managing indices of nodes. The |
| current implementation provides the same functionality as <A href="#mxmlFindElement"> |
| <TT>mxmlFindElement()</TT></A>. The advantage of using an index is that |
| searching and enumeration of elements is significantly faster. The only |
| disadvantage is that each index is a static snapshot of the XML |
| document, so indices are not well suited to XML data that is updated |
| more often than it is searched. The overhead of creating 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 creates a new index:</P> |
| <PRE> |
| mxml_node_t *tree; |
| mxml_index_t *ind; |
| |
| ind = mxmlIndexNew(tree, "element", |
| "attribute"); |
| </PRE> |
| <P>The first argument is the XML node tree to index. Normally this will |
| be a pointer to the <TT>?xml</TT> element.</P> |
| <P>The second argument contains the element to index; passing <TT>NULL</TT> |
| indexes all element nodes alphabetically.</P> |
| <P>The third argument contains the attribute to index; passing <TT>NULL</TT> |
| causes only the element name to be indexed.</P> |
| <P>Once the index is created, the <A href="#mxmlIndexEnum"><TT> |
| mxmlIndexEnum()</TT></A>, <A href="#mxmlIndexFind"><TT>mxmlIndexFind()</TT> |
| </A>, and <A href="#mxmlIndexReset"><TT>mxmlIndexReset()</TT></A> |
| functions are used to access the nodes in the index. The <A href="#mxmlIndexReset"> |
| <TT>mxmlIndexReset()</TT></A> function resets the "current" node pointer |
| in the index, allowing you to do new searches and enumerations on the |
| same index. Typically you will call this function prior to your calls |
| to <A href="#mxmlIndexEnum"><TT>mxmlIndexEnum()</TT></A> and <A href="#mxmlIndexFind"> |
| <TT>mxmlIndexFind()</TT></A>.</P> |
| <P>The <A href="#mxmlIndexEnum"><TT>mxmlIndexEnum()</TT></A> function |
| enumerates each of the nodes in the index and can be used in a loop as |
| follows:</P> |
| <PRE> |
| mxml_node_t *node; |
| |
| mxmlIndexReset(ind); |
| |
| while ((node = mxmlIndexEnum(ind)) != NULL) |
| { |
| // do something with node |
| } |
| </PRE> |
| <P>The <A href="#mxmlIndexFind"><TT>mxmlIndexFind()</TT></A> function |
| locates the next occurrence of the named element and attribute value in |
| the index. It can be used to find all matching elements in an index, as |
| follows:</P> |
| <PRE> |
| mxml_node_t *node; |
| |
| mxmlIndexReset(ind); |
| |
| while ((node = mxmlIndexFind(ind, "element", |
| "attr-value")) |
| != NULL) |
| { |
| // do something with node |
| } |
| </PRE> |
| <P>The second and third arguments represent the element name and |
| attribute value, respectively. A <TT>NULL</TT> pointer is used to |
| return all elements or attributes in the index. Passing <TT>NULL</TT> |
| for both the element name and attribute value is equivalent to calling <TT> |
| mxmlIndexEnum</TT>.</P> |
| <P>When you are done using the index, delete it using the <A href="#mxmlIndexDelete()"> |
| <TT>mxmlIndexDelete()</TT></A> function:</P> |
| <PRE> |
| mxmlIndexDelete(ind); |
| </PRE> |
| <H2><A NAME="4_7">SAX (Stream) Loading of Documents</A></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 <A href="#mxmlSAXLoad"><TT>mxmlSAXLoadFd</TT></A>, <A href="#mxmlSAXLoadFile"> |
| <TT>mxmlSAXLoadFile</TT></A>, and <A href="#mxmlSAXLoadString"><TT> |
| mxmlSAXLoadString</TT></A> functions provide the SAX loading APIs. Each |
| function works like the corresponding <TT>mxmlLoad</TT> function but |
| uses a callback to process each node as it is read.</P> |
| <P>The callback function receives the node, an event code, and a user |
| data pointer you supply:</P> |
| <PRE> |
| void |
| sax_cb(mxml_node_t *node, |
| mxml_sax_event_t event, |
| void *data) |
| { |
| ... do something ... |
| } |
| </PRE> |
| <P>The event will be one of the following:</P> |
| <UL> |
| <LI><TT>MXML_SAX_CDATA</TT> - CDATA was just read</LI> |
| <LI><TT>MXML_SAX_COMMENT</TT> - A comment was just read</LI> |
| <LI><TT>MXML_SAX_DATA</TT> - Data (custom, integer, opaque, real, or |
| text) was just read</LI> |
| <LI><TT>MXML_SAX_DIRECTIVE</TT> - A processing directive was just read</LI> |
| <LI><TT>MXML_SAX_ELEMENT_CLOSE</TT> - A close element was just read (<TT> |
| </element></TT>)</LI> |
| <LI><TT>MXML_SAX_ELEMENT_OPEN</TT> - An open element was just read (<TT> |
| <element></TT>)</LI> |
| </UL> |
| <P>Elements are<EM> released</EM> after the close element is processed. |
| All other nodes are released after they are processed. The SAX callback |
| can<EM> retain</EM> the node using the <A href="#mxmlRetain"><TT> |
| mxmlRetain</TT></A> function. For example, the following SAX callback |
| will retain all nodes, effectively simulating a normal in-memory load:</P> |
| <PRE> |
| void |
| sax_cb(mxml_node_t *node, |
| mxml_sax_event_t event, |
| void *data) |
| { |
| if (event != MXML_SAX_ELEMENT_CLOSE) |
| mxmlRetain(node); |
| } |
| </PRE> |
| <P>More typically the SAX callback will only retain a small portion of |
| the document that is needed for post-processing. For example, the |
| following SAX callback will retain the title and headings in an XHTML |
| file. It also retains the (parent) elements like <TT><html></TT>, <TT> |
| <head></TT>, and <TT><body></TT>, and processing directives like <TT> |
| <?xml ... ?></TT> and <TT><!DOCTYPE ... ></TT>:</P> |
| |
| <!-- NEED 10 --> |
| <PRE> |
| void |
| sax_cb(mxml_node_t *node, |
| mxml_sax_event_t event, |
| void *data) |
| { |
| if (event == MXML_SAX_ELEMENT_OPEN) |
| { |
| /* |
| * Retain headings and titles... |
| */ |
| |
| char *name = mxmlGetElement(node); |
| |
| if (!strcmp(name, "html") || |
| !strcmp(name, "head") || |
| !strcmp(name, "title") || |
| !strcmp(name, "body") || |
| !strcmp(name, "h1") || |
| !strcmp(name, "h2") || |
| !strcmp(name, "h3") || |
| !strcmp(name, "h4") || |
| !strcmp(name, "h5") || |
| !strcmp(name, "h6")) |
| mxmlRetain(node); |
| } |
| else if (event == MXML_SAX_DIRECTIVE) |
| mxmlRetain(node); |
| else if (event == MXML_SAX_DATA) |
| { |
| if (mxmlGetRefCount(mxmlGetParent(node)) > 1) |
| { |
| /* |
| * If the parent was retained, then retain |
| * this data node as well. |
| */ |
| |
| mxmlRetain(node); |
| } |
| } |
| } |
| </PRE> |
| <P>The resulting skeleton document tree can then be searched just like |
| one loaded using the <TT>mxmlLoad</TT> functions. For example, a filter |
| that reads an XHTML document from stdin and then shows the title and |
| headings in the document would look like:</P> |
| <PRE> |
| mxml_node_t *doc, *title, *body, *heading; |
| |
| doc = mxmlSAXLoadFd(NULL, 0, |
| MXML_TEXT_CALLBACK, |
| <B>sax_cb</B>, NULL); |
| |
| title = mxmlFindElement(doc, doc, "title", |
| NULL, NULL, |
| MXML_DESCEND); |
| |
| if (title) |
| print_children(title); |
| |
| body = mxmlFindElement(doc, doc, "body", |
| NULL, NULL, |
| MXML_DESCEND); |
| |
| if (body) |
| { |
| for (heading = mxmlGetFirstChild(body); |
| heading; |
| heading = mxmlGetNextSibling(heading)) |
| print_children(heading); |
| } |
| </PRE> |
| <HR NOSHADE> |
| <H1 align="right"><A name="MXMLDOC"><IMG align="right" alt="4" height="100" |
| hspace="10" src="4.gif" width="100"></A>Using the mxmldoc Utility</H1> |
| <P>This chapter describes how to use <TT>mxmldoc(1)</TT> program to |
| automatically generate documentation from C and C++ source files.</P> |
| <H2><A NAME="5_1">The Basics</A></H2> |
| <P>Originally developed to generate the Mini-XML and CUPS API |
| documentation, <TT>mxmldoc</TT> is now a general-purpose utility which |
| scans C and C++ source files to produce HTML and man page documentation |
| along with an XML file representing the functions, types, and |
| definitions in those source files. Unlike popular documentation |
| generators like Doxygen or Javadoc, <TT>mxmldoc</TT> uses in-line |
| comments rather than comment headers, allowing for more "natural" code |
| documentation.</P> |
| <P>By default, <TT>mxmldoc</TT> produces HTML documentation. For |
| example, the following command will scan all of the C source and header |
| files in the current directory and produce a HTML documentation file |
| called<VAR> filename.html</VAR>:</P> |
| <PRE> |
| <KBD>mxmldoc *.h *.c >filename.html ENTER</KBD> |
| </PRE> |
| <P>You can also specify an XML file to create which contains all of the |
| information from the source files. For example, the following command |
| creates an XML file called<VAR> filename.xml</VAR> in addition to the |
| HTML file:</P> |
| <PRE> |
| <KBD>mxmldoc filename.xml *.h *.c >filename.html ENTER</KBD> |
| </PRE> |
| <P>The <TT>--no-output</TT> option disables the normal HTML output:</P> |
| <PRE> |
| <KBD>mxmldoc --no-output filename.xml *.h *.c ENTER</KBD> |
| </PRE> |
| <P>You can then run <TT>mxmldoc</TT> again with the XML file alone to |
| generate the HTML documentation:</P> |
| <PRE> |
| <KBD>mxmldoc filename.xml >filename.html ENTER</KBD> |
| </PRE> |
| <H3><A NAME="5_1_1">Creating Man Pages</A></H3> |
| <P>The <TT>--man filename</TT> option tells <TT>mxmldoc</TT> to create a |
| man page instead of HTML documentation, for example:</P> |
| <PRE> |
| <KBD>mxmldoc --man filename filename.xml \ |
| >filename.man ENTER</KBD> |
| |
| <KBD>mxmldoc --man filename *.h *.c \ |
| >filename.man ENTER</KBD> |
| </PRE> |
| <H3><A NAME="5_1_2">Creating Xcode Documentation Sets</A></H3> |
| <P>The <TT>--docset directory.docset</TT> option tells <TT>mxmldoc</TT> |
| to create an Xcode documentation set containing the HTML documentation, |
| for example:</P> |
| <PRE> |
| <KBD>mxmldoc --docset foo.docset *.h *.c foo.xml ENTER</KBD> |
| </PRE> |
| <P>Xcode documentation sets can only be built on Mac OS X with Xcode 3.0 |
| or higher installed.</P> |
| <H2><A NAME="5_2">Commenting Your Code</A></H2> |
| <P>As noted previously, <TT>mxmldoc</TT> looks for in-line comments to |
| describe the functions, types, and constants in your code. <TT>Mxmldoc</TT> |
| will document all public names it finds in your source files - any |
| names starting with the underscore character (_) or names that are |
| documented with the <A HREF="#ATDIRECTIVES">@private@</A> directive are |
| treated as private and are not documented.</P> |
| <P>Comments appearing directly before a function or type definition are |
| used to document that function or type. Comments appearing after |
| argument, definition, return type, or variable declarations are used to |
| document that argument, definition, return type, or variable. For |
| example, the following code excerpt defines a key/value structure and a |
| function that creates a new instance of that structure:</P> |
| <PRE> |
| /* A key/value pair. This is used with the |
| dictionary structure. */ |
| |
| struct keyval |
| { |
| char *key; /* Key string */ |
| char *val; /* Value string */ |
| }; |
| |
| /* Create a new key/value pair. */ |
| |
| struct keyval * /* New key/value pair */ |
| new_keyval( |
| const char *key, /* Key string */ |
| const char *val) /* Value string */ |
| { |
| ... |
| } |
| </PRE> |
| <P><TT>Mxmldoc</TT> also knows to remove extra asterisks (*) from the |
| comment string, so the comment string:</P> |
| <PRE> |
| /* |
| * Compute the value of PI. |
| * |
| * The function connects to an Internet server |
| * that streams audio of mathematical monks |
| * chanting the first 100 digits of PI. |
| */ |
| </PRE> |
| <P>will be shown as:</P> |
| <PRE> |
| Compute the value of PI. |
| |
| The function connects to an Internet server |
| that streams audio of mathematical monks |
| chanting the first 100 digits of PI. |
| </PRE> |
| <P><A name="ATDIRECTIVES">Comments</A> can also include the following |
| special <TT>@name ...@</TT> directive strings:</P> |
| <UL> |
| <LI><TT>@deprecated@</TT> - flags the item as deprecated to discourage |
| its use</LI> |
| <LI><TT>@private@</TT> - flags the item as private so it will not be |
| included in the documentation</LI> |
| <LI><TT>@since ...@</TT> - flags the item as new since a particular |
| release. The text following the <TT>@since</TT> up to the closing <TT>@</TT> |
| is highlighted in the generated documentation, e.g. <TT>@since Mini-XML |
| 2.7@</TT>.</LI> |
| </UL> |
| |
| <!-- NEED 10 --> |
| <H2><A NAME="5_3">Titles, Sections, and Introductions</A></H2> |
| <P><TT>Mxmldoc</TT> also provides options to set the title, section, and |
| introduction text for the generated documentation. The <TT>--title text</TT> |
| option specifies the title for the documentation. The title string is |
| usually put in quotes:</P> |
| <PRE> |
| <KBD>mxmldoc filename.xml \ |
| --title "My Famous Documentation" \ |
| >filename.html ENTER</KBD> |
| </PRE> |
| <P>The <TT>--section name</TT> option specifies the section for the |
| documentation. For HTML documentation, the name is placed in a HTML |
| comment such as:</P> |
| <PRE> |
| <!-- SECTION: name --> |
| </PRE> |
| <P>For man pages, the section name is usually just a number ("3"), or a |
| number followed by a vendor name ("3acme"). The section name is used in |
| the <TT>.TH</TT> directive in the man page:</P> |
| <PRE> |
| .TH mylibrary 3acme "My Title" ... |
| </PRE> |
| <P>The default section name for man page output is "3". There is no |
| default section name for HTML output.</P> |
| <P>Finally, the <TT>--intro filename</TT> option specifies a file to |
| embed after the title and section but before the generated |
| documentation. For HTML documentation, the file must consist of valid |
| HTML without the usual <TT>DOCTYPE</TT>, <TT>html</TT>, and <TT>body</TT> |
| elements. For man page documentation, the file must consist of valid <TT> |
| nroff(1)</TT> text.</P> |
| <HR NOSHADE> |
| <H1 align="right"><A name="LICENSE"><IMG align="right" alt="A" height="100" |
| hspace="10" src="A.gif" width="100"></A>Mini-XML License</H1> |
| <P>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:</P> |
| <P><B>1.</B> 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.</P> |
| <P><I>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.</I></P> |
| <P><B>2.</B> 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.</P> |
| <P> </P> |
| <P align="center"><B>GNU LIBRARY GENERAL PUBLIC LICENSE</B></P> |
| <P align="center">Version 2, June 1991 |
| <BR> Copyright (C) 1991 Free Software Foundation, Inc. |
| <BR> 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA |
| <BR> Everyone is permitted to copy and distribute verbatim copies of |
| this license document, but changing it is not allowed. |
| <BR> [This is the first released version of the library GPL. It is |
| numbered 2 because it goes with version 2 of the ordinary GPL.]</P> |
| <P><B>Preamble</B></P> |
| <P>The licenses for most software are designed to take away your freedom |
| to share and change it. By contrast, the GNU General Public Licenses |
| are intended to guarantee your freedom to share and change free |
| software--to make sure the software is free for all its users.</P> |
| <P>This license, the Library General Public License, applies to some |
| specially designated Free Software Foundation software, and to any |
| other libraries whose authors decide to use it. You can use it for your |
| libraries, too.</P> |
| <P>When we speak of free software, we are referring to freedom, not |
| price. Our General Public Licenses are designed to make sure that you |
| have the freedom to distribute copies of free software (and charge for |
| this service if you wish), that you receive source code or can get it |
| if you want it, that you can change the software or use pieces of it in |
| new free programs; and that you know you can do these things.</P> |
| <P>To protect your rights, we need to make restrictions that forbid |
| anyone to deny you these rights or to ask you to surrender the rights. |
| These restrictions translate to certain responsibilities for you if you |
| distribute copies of the library, or if you modify it.</P> |
| <P>For example, if you distribute copies of the library, whether gratis |
| or for a fee, you must give the recipients all the rights that we gave |
| you. You must make sure that they, too, receive or can get the source |
| code. If you link a program with the library, you must provide complete |
| object files to the recipients so that they can relink them with the |
| library, after making changes to the library and recompiling it. And |
| you must show them these terms so they know their rights.</P> |
| <P>Our method of protecting your rights has two steps: (1) copyright the |
| library, and (2) offer you this license which gives you legal |
| permission to copy, distribute and/or modify the library.</P> |
| <P>Also, for each distributor's protection, we want to make certain that |
| everyone understands that there is no warranty for this free library. |
| If the library is modified by someone else and passed on, we want its |
| recipients to know that what they have is not the original version, so |
| that any problems introduced by others will not reflect on the original |
| authors' reputations.</P> |
| <P>Finally, any free program is threatened constantly by software |
| patents. We wish to avoid the danger that companies distributing free |
| software will individually obtain patent licenses, thus in effect |
| transforming the program into proprietary software. To prevent this, we |
| have made it clear that any patent must be licensed for everyone's free |
| use or not licensed at all.</P> |
| <P>Most GNU software, including some libraries, is covered by the |
| ordinary GNU General Public License, which was designed for utility |
| programs. This license, the GNU Library General Public License, applies |
| to certain designated libraries. This license is quite different from |
| the ordinary one; be sure to read it in full, and don't assume that |
| anything in it is the same as in the ordinary license.</P> |
| <P>The reason we have a separate public license for some libraries is |
| that they blur the distinction we usually make between modifying or |
| adding to a program and simply using it. Linking a program with a |
| library, without changing the library, is in some sense simply using |
| the library, and is analogous to running a utility program or |
| application program. However, in a textual and legal sense, the linked |
| executable is a combined work, a derivative of the original library, |
| and the ordinary General Public License treats it as such.</P> |
| <P>Because of this blurred distinction, using the ordinary General |
| Public License for libraries did not effectively promote software |
| sharing, because most developers did not use the libraries. We |
| concluded that weaker conditions might promote sharing better.</P> |
| <P>However, unrestricted linking of non-free programs would deprive the |
| users of those programs of all benefit from the free status of the |
| libraries themselves. This Library General Public License is intended |
| to permit developers of non-free programs to use free libraries, while |
| preserving your freedom as a user of such programs to change the free |
| libraries that are incorporated in them. (We have not seen how to |
| achieve this as regards changes in header files, but we have achieved |
| it as regards changes in the actual functions of the Library.) The hope |
| is that this will lead to faster development of free libraries.</P> |
| <P>The precise terms and conditions for copying, distribution and |
| modification follow. Pay close attention to the difference between a |
| "work based on the libary" and a "work that uses the library". The |
| former contains code derived from the library, while the latter only |
| works together with the library.</P> |
| <P>Note that it is possible for a library to be covered by the ordinary |
| General Public License rather than by this special one.</P> |
| <P align="center"><B>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND |
| MODIFICATION</B></P> |
| <P><STRONG>0.</STRONG> This License Agreement applies to any software |
| library which contains a notice placed by the copyright holder or other |
| authorized party saying it may be distributed under the terms of this |
| Library General Public License (also called "this License"). Each |
| licensee is addressed as "you".</P> |
| <P>A "library" means a collection of software functions and/or data |
| prepared so as to be conveniently linked with application programs |
| (which use some of those functions and data) to form executables.</P> |
| <P>The "Library", below, refers to any such software library or work |
| which has been distributed under these terms. A "work based on the |
| Library" means either the Library or any derivative work under |
| copyright law: that is to say, a work containing the Library or a |
| portion of it, either verbatim or with modifications and/or translated |
| straightforwardly into another language. (Hereinafter, translation is |
| included without limitation in the term "modification".)</P> |
| <P>"Source code" for a work means the preferred form of the work for |
| making modifications to it. For a library, complete source code means |
| all the source code for all modules it contains, plus any associated |
| interface definition files, plus the scripts used to control |
| compilation and installation of the library.</P> |
| <P>Activities other than copying, distribution and modification are not |
| covered by this License; they are outside its scope. The act of running |
| a program using the Library is not restricted, and output from such a |
| program is covered only if its contents constitute a work based on the |
| Library (independent of the use of the Library in a tool for writing |
| it). Whether that is true depends on what the Library does and what the |
| program that uses the Library does.</P> |
| <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of |
| the Library's complete source code as you receive it, in any medium, |
| provided that you conspicuously and appropriately publish on each copy |
| an appropriate copyright notice and disclaimer of warranty; keep intact |
| all the notices that refer to this License and to the absence of any |
| warranty; and distribute a copy of this License along with the Library.</P> |
| <P>You may charge a fee for the physical act of transferring a copy, and |
| you may at your option offer warranty protection in exchange for a fee.</P> |
| <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library |
| or any portion of it, thus forming a work based on the Library, and |
| copy and distribute such modifications or work under the terms of |
| Section 1 above, provided that you also meet all of these conditions:</P> |
| <UL> |
| <P><STRONG>a)</STRONG> The modified work must itself be a software |
| library.</P> |
| <P><STRONG>b)</STRONG> You must cause the files modified to carry |
| prominent notices stating that you changed the files and the date of |
| any change.</P> |
| <P><STRONG>c)</STRONG> You must cause the whole of the work to be |
| licensed at no charge to all third parties under the terms of this |
| License.</P> |
| <P><STRONG>d)</STRONG> If a facility in the modified Library refers to a |
| function or a table of data to be supplied by an application program |
| that uses the facility, other than as an argument passed when the |
| facility is invoked, then you must make a good faith effort to ensure |
| that, in the event an application does not supply such function or |
| table, the facility still operates, and performs whatever part of its |
| purpose remains meaningful.</P> |
| <P>(For example, a function in a library to compute square roots has a |
| purpose that is entirely well-defined independent of the application. |
| Therefore, Subsection 2d requires that any application-supplied |
| function or table used by this function must be optional: if the |
| application does not supply it, the square root function must still |
| compute square roots.)</P> |
| </UL> |
| <P>These requirements apply to the modified work as a whole. If |
| identifiable sections of that work are not derived from the Library, |
| and can be reasonably considered independent and separate works in |
| themselves, then this License, and its terms, do not apply to those |
| sections when you distribute them as separate works. But when you |
| distribute the same sections as part of a whole which is a work based |
| on the Library, the distribution of the whole must be on the terms of |
| this License, whose permissions for other licensees extend to the |
| entire whole, and thus to each and every part regardless of who wrote |
| it.</P> |
| <P>Thus, it is not the intent of this section to claim rights or contest |
| your rights to work written entirely by you; rather, the intent is to |
| exercise the right to control the distribution of derivative or |
| collective works based on the Library.</P> |
| <P>In addition, mere aggregation of another work not based on the |
| Library with the Library (or with a work based on the Library) on a |
| volume of a storage or distribution medium does not bring the other |
| work under the scope of this License.</P> |
| <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary |
| GNU General Public License instead of this License to a given copy of |
| the Library. To do this, you must alter all the notices that refer to |
| this License, so that they refer to the ordinary GNU General Public |
| License, version 2, instead of to this License. (If a newer version |
| than version 2 of the ordinary GNU General Public License has appeared, |
| then you can specify that version instead if you wish.) Do not make any |
| other change in these notices.</P> |
| <P>Once this change is made in a given copy, it is irreversible for that |
| copy, so the ordinary GNU General Public License applies to all |
| subsequent copies and derivative works made from that copy.</P> |
| <P>This option is useful when you wish to copy part of the code of the |
| Library into a program that is not a library.</P> |
| <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a |
| portion or derivative of it, under Section 2) in object code or |
| executable form under the terms of Sections 1 and 2 above provided that |
| you accompany it with the complete corresponding machine-readable |
| source code, which must be distributed under the terms of Sections 1 |
| and 2 above on a medium customarily used for software interchange.</P> |
| <P>If distribution of object code is made by offering access to copy |
| from a designated place, then offering equivalent access to copy the |
| source code from the same place satisfies the requirement to distribute |
| the source code, even though third parties are not compelled to copy |
| the source along with the object code.</P> |
| <P><STRONG>5.</STRONG> A program that contains no derivative of any |
| portion of the Library, but is designed to work with the Library by |
| being compiled or linked with it, is called a "work that uses the |
| Library". Such a work, in isolation, is not a derivative work of the |
| Library, and therefore falls outside the scope of this License.</P> |
| <P>However, linking a "work that uses the Library" with the Library |
| creates an executable that is a derivative of the Library (because it |
| contains portions of the Library), rather than a "work that uses the |
| library". The executable is therefore covered by this License. Section |
| 6 states terms for distribution of such executables.</P> |
| <P>When a "work that uses the Library" uses material from a header file |
| that is part of the Library, the object code for the work may be a |
| derivative work of the Library even though the source code is not. |
| Whether this is true is especially significant if the work can be |
| linked without the Library, or if the work is itself a library. The |
| threshold for this to be true is not precisely defined by law.</P> |
| <P>If such an object file uses only numerical parameters, data structure |
| layouts and accessors, and small macros and small inline functions (ten |
| lines or less in length), then the use of the object file is |
| unrestricted, regardless of whether it is legally a derivative work. |
| (Executables containing this object code plus portions of the Library |
| will still fall under Section 6.)</P> |
| <P>Otherwise, if the work is a derivative of the Library, you may |
| distribute the object code for the work under the terms of Section 6. |
| Any executables containing that work also fall under Section 6, whether |
| or not they are linked directly with the Library itself.</P> |
| <P><STRONG>6.</STRONG> As an exception to the Sections above, you may |
| also compile or link a "work that uses the Library" with the Library to |
| produce a work containing portions of the Library, and distribute that |
| work under terms of your choice, provided that the terms permit |
| modification of the work for the customer's own use and reverse |
| engineering for debugging such modifications.</P> |
| <P>You must give prominent notice with each copy of the work that the |
| Library is used in it and that the Library and its use are covered by |
| this License. You must supply a copy of this License. If the work |
| during execution displays copyright notices, you must include the |
| copyright notice for the Library among them, as well as a reference |
| directing the user to the copy of this License. Also, you must do one |
| of these things:</P> |
| <UL><STRONG> a)</STRONG> Accompany the work with the complete |
| corresponding machine-readable source code for the Library including |
| whatever changes were used in the work (which must be distributed under |
| Sections 1 and 2 above); and, if the work is an executable linked with |
| the Library, with the complete machine-readable "work that uses the |
| Library", as object code and/or source code, so that the user can |
| modify the Library and then relink to produce a modified executable |
| containing the modified Library. (It is understood that the user who |
| changes the contents of definitions files in the Library will not |
| necessarily be able to recompile the application to use the modified |
| definitions.) |
| <P><STRONG>b)</STRONG> Accompany the work with a written offer, valid |
| for at least three years, to give the same user the materials specified |
| in Subsection 6a, above, for a charge no more than the cost of |
| performing this distribution.</P> |
| <P><STRONG>c)</STRONG> If distribution of the work is made by offering |
| access to copy from a designated place, offer equivalent access to copy |
| the above specified materials from the same place.</P> |
| <P><STRONG>d)</STRONG> Verify that the user has already received a copy |
| of these materials or that you have already sent this user a copy.</P> |
| </UL> |
| <P>For an executable, the required form of the "work that uses the |
| Library" must include any data and utility programs needed for |
| reproducing the executable from it. However, as a special exception, |
| the source code distributed need not include anything that is normally |
| distributed (in either source or binary form) with the major components |
| (compiler, kernel, and so on) of the operating system on which the |
| executable runs, unless that component itself accompanies the |
| executable.</P> |
| <P>It may happen that this requirement contradicts the license |
| restrictions of other proprietary libraries that do not normally |
| accompany the operating system. Such a contradiction means you cannot |
| use both them and the Library together in an executable that you |
| distribute.</P> |
| <P><STRONG>7.</STRONG> You may place library facilities that are a work |
| based on the Library side-by-side in a single library together with |
| other library facilities not covered by this License, and distribute |
| such a combined library, provided that the separate distribution of the |
| work based on the Library and of the other library facilities is |
| otherwise permitted, and provided that you do these two things:</P> |
| <UL><STRONG> a)</STRONG> Accompany the combined library with a copy of |
| the same work based on the Library, uncombined with any other library |
| facilities. This must be distributed under the terms of the Sections |
| above. |
| <P><STRONG>b)</STRONG> Give prominent notice with the combined library |
| of the fact that part of it is a work based on the Library, and |
| explaining where to find the accompanying uncombined form of the same |
| work.</P> |
| </UL> |
| <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with, |
| or distribute the Library except as expressly provided under this |
| License. Any attempt otherwise to copy, modify, sublicense, link with, |
| or distribute the Library is void, and will automatically terminate |
| your rights under this License. However, parties who have received |
| copies, or rights, from you under this License will not have their |
| licenses terminated so long as such parties remain in full compliance.</P> |
| <P><STRONG>9.</STRONG> You are not required to accept this License, |
| since you have not signed it. However, nothing else grants you |
| permission to modify or distribute the Library or its derivative works. |
| These actions are prohibited by law if you do not accept this License. |
| Therefore, by modifying or distributing the Library (or any work based |
| on the Library), you indicate your acceptance of this License to do so, |
| and all its terms and conditions for copying, distributing or modifying |
| the Library or works based on it.</P> |
| <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any |
| work based on the Library), the recipient automatically receives a |
| license from the original licensor to copy, distribute, link with or |
| modify the Library subject to these terms and conditions. You may not |
| impose any further restrictions on the recipients' exercise of the |
| rights granted herein. You are not responsible for enforcing compliance |
| by third parties to this License.</P> |
| <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or |
| allegation of patent infringement or for any other reason (not limited |
| to patent issues), conditions are imposed on you (whether by court |
| order, agreement or otherwise) that contradict the conditions of this |
| License, they do not excuse you from the conditions of this License. If |
| you cannot distribute so as to satisfy simultaneously your obligations |
| under this License and any other pertinent obligations, then as a |
| consequence you may not distribute the Library at all. For example, if |
| a patent license would not permit royalty-free redistribution of the |
| Library by all those who receive copies directly or indirectly through |
| you, then the only way you could satisfy both it and this License would |
| be to refrain entirely from distribution of the Library.</P> |
| <P>If any portion of this section is held invalid or unenforceable under |
| any particular circumstance, the balance of the section is intended to |
| apply, and the section as a whole is intended to apply in other |
| circumstances.</P> |
| <P>It is not the purpose of this section to induce you to infringe any |
| patents or other property right claims or to contest validity of any |
| such claims; this section has the sole purpose of protecting the |
| integrity of the free software distribution system which is implemented |
| by public license practices. Many people have made generous |
| contributions to the wide range of software distributed through that |
| system in reliance on consistent application of that system; it is up |
| to the author/donor to decide if he or she is willing to distribute |
| software through any other system and a licensee cannot impose that |
| choice.</P> |
| <P>This section is intended to make thoroughly clear what is believed to |
| be a consequence of the rest of this License.</P> |
| <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is |
| restricted in certain countries either by patents or by copyrighted |
| interfaces, the original copyright holder who places the Library under |
| this License may add an explicit geographical distribution limitation |
| excluding those countries, so that distribution is permitted only in or |
| among countries not thus excluded. In such case, this License |
| incorporates the limitation as if written in the body of this License.</P> |
| <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised |
| and/or new versions of the Library General Public License from time to |
| time. Such new versions will be similar in spirit to the present |
| version, but may differ in detail to address new problems or concerns.</P> |
| <P>Each version is given a distinguishing version number. If the Library |
| specifies a version number of this License which applies to it and "any |
| later version", you have the option of following the terms and |
| conditions either of that version or of any later version published by |
| the Free Software Foundation. If the Library does not specify a license |
| version number, you may choose any version ever published by the Free |
| Software Foundation.</P> |
| <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library |
| into other free programs whose distribution conditions are incompatible |
| with these, write to the author to ask for permission. For software |
| which is copyrighted by the Free Software Foundation, write to the Free |
| Software Foundation; we sometimes make exceptions for this. Our |
| decision will be guided by the two goals of preserving the free status |
| of all derivatives of our free software and of promoting the sharing |
| and reuse of software generally.</P> |
| <P align="center"><B>NO WARRANTY</B></P> |
| <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, |
| THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY |
| APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT |
| HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT |
| WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT |
| LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A |
| PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE |
| OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU |
| ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P> |
| <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR |
| AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO |
| MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE |
| LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL |
| OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| DAMAGES.</P> |
| <P align="center"><B>END OF TERMS AND CONDITIONS</B></P> |
| <P><B>How to Apply These Terms to Your New Libraries</B></P> |
| <P>If you develop a new library, and you want it to be of the greatest |
| possible use to the public, we recommend making it free software that |
| everyone can redistribute and change. You can do so by permitting |
| redistribution under these terms (or, alternatively, under the terms of |
| the ordinary General Public License).</P> |
| <P>To apply these terms, attach the following notices to the library. It |
| is safest to attach them to the start of each source file to most |
| effectively convey the exclusion of warranty; and each file should have |
| at least the "copyright" line and a pointer to where the full notice is |
| found.</P> |
| <UL> |
| <P><VAR>one line to give the library's name and an idea of what it does.</VAR> |
| <BR> Copyright (C)<VAR> year</VAR><VAR> name of author</VAR></P> |
| <P>This library is free software; you can redistribute it and/or modify |
| it under the terms of the GNU Lesser General Public License as |
| published by the Free Software Foundation; either version 2.1 of the |
| License, or (at your option) any later version.</P> |
| <P>This library is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser |
| General Public License for more details.</P> |
| <P>You should have received a copy of the GNU Lesser General Public |
| License along with this library; if not, write to the Free Software |
| Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</P> |
| </UL> |
| <P>Also add information on how to contact you by electronic and paper |
| mail.</P> |
| <P>You should also get your employer (if you work as a programmer) or |
| your school, if any, to sign a "copyright disclaimer" for the library, |
| if necessary. Here is a sample; alter the names:</P> |
| <UL> |
| <P>Yoyodyne, Inc., hereby disclaims all copyright interest in the |
| library `Frob' (a library for tweaking knobs) written by James Random |
| Hacker.</P> |
| <P><VAR>signature of Ty Coon</VAR>, 1 April 1990 Ty Coon, President of |
| Vice</P> |
| </UL> |
| <P>That's all there is to it!</P> |
| <HR NOSHADE> |
| <H1 align="right"><A name="RELNOTES"><IMG align="right" alt="B" height="100" |
| hspace="10" src="B.gif" width="100"></A>Release Notes</H1> |
| <H2><A NAME="7_1">Changes in Mini-XML 2.8</A></H2> |
| <UL> |
| <LI>Now call docsetutil using xcrun on OS X (Bug #458)</LI> |
| <LI>mxmldoc did not escape special HTML characters inside @code foo@ |
| comments.</LI> |
| <LI>Fixed a memory leak in mxmlElementDeleteAttr (Bug #452)</LI> |
| <LI>Added MXML_MAJOR/MINOR_VERSION definitions to mxml.h (Bug $461)</LI> |
| <LI>Fixed a bug reading UTF-16 characters from a file (Bug #454)</LI> |
| <LI>Fixed a memory leak when loading invalid XML (Bug #496)</LI> |
| <LI>Fixed an XML fragment loading problem (Bug #494)</LI> |
| </UL> |
| <H2><A NAME="7_2">Changes in Mini-XML 2.7</A></H2> |
| <UL> |
| <LI>Added 64-bit configurations to the VC++ project files (STR #129)</LI> |
| <LI>Fixed conformance of mxmldoc's HTML and CSS output.</LI> |
| <LI>Added data accessor ("get") functions and made the mxml_node_t and |
| mxml_index_t structures private but still available in the Mini-XML |
| header to preserve source compatibility (STR #118)</LI> |
| <LI>Updated the source headers to reference the Mini-XML license and its |
| exceptions to the LGPL2 (STR #108)</LI> |
| <LI>Added a new mxmlFindPath() function to find the value node of a |
| named element (STR #110)</LI> |
| <LI>Building a static version of the library did not work on Windows |
| (STR #112)</LI> |
| <LI>The shared library did not include a destructor for the thread- |
| specific data key on UNIX-based operating systems (STR #103)</LI> |
| <LI>mxmlLoad* did not error out on XML with multiple root nodes (STR |
| #101)</LI> |
| <LI>Fixed an issue with the _mxml_vstrdupf function (STR #107)</LI> |
| <LI>mxmlSave* no longer write all siblings of the passed node, just that |
| node and its children (STR #109)</LI> |
| </UL> |
| <H2><A NAME="7_3">Changes in Mini-XML 2.6</A></H2> |
| <UL> |
| <LI>Documentation fixes (STR #91, STR #92)</LI> |
| <LI>The mxmldoc program did not handle typedef comments properly (STR |
| #72)</LI> |
| <LI>Added support for "long long" printf formats.</LI> |
| <LI>The XML parser now ignores BOMs in UTF-8 XML files (STR #89)</LI> |
| <LI>The mxmldoc program now supports generating Xcode documentation |
| sets.</LI> |
| <LI>mxmlSave*() did not output UTF-8 correctly on some platforms.</LI> |
| <LI>mxmlNewXML() now adds encoding="utf-8" in the ?xml directive to |
| avoid problems with non-conformant XML parsers that assume something |
| other than UTF-8 as the default encoding.</LI> |
| <LI>Wrapping was not disabled when mxmlSetWrapMargin(0) was called, and |
| "<?xml ... ?>" was always followed by a newline (STR #76)</LI> |
| <LI>The mxml.pc.in file was broken (STR #79)</LI> |
| <LI>The mxmldoc program now handles "typedef enum name {} name" |
| correctly (STR #72)</LI> |
| </UL> |
| <H2><A NAME="7_4">Changes in Mini-XML 2.5</A></H2> |
| <UL> |
| <LI>The mxmldoc program now makes greater use of CSS and supports a |
| --css option to embed an alternate stylesheet.</LI> |
| <LI>The mxmldoc program now supports --header and --footer options to |
| insert documentation content before and after the generated content.</LI> |
| <LI>The mxmldoc program now supports a --framed option to generate |
| framed HTML output.</LI> |
| <LI>The mxmldoc program now creates a table of contents including any |
| headings in the --intro file when generating HTML output.</LI> |
| <LI>The man pages and man page output from mxmldoc did not use "\-" for |
| dashes (STR #68)</LI> |
| <LI>The debug version of the Mini-XML DLL could not be built (STR #65)</LI> |
| <LI>Processing instructions and directives did not work when not at the |
| top level of a document (STR #67)</LI> |
| <LI>Spaces around the "=" in attributes were not supported (STR #67)</LI> |
| </UL> |
| <H2><A NAME="7_5">Changes in Mini-XML 2.4</A></H2> |
| <UL> |
| <LI>Fixed shared library build problems on HP-UX and Mac OS X.</LI> |
| <LI>The mxmldoc program did not output argument descriptions for |
| functions properly.</LI> |
| <LI>All global settings (custom, error, and entity callbacks and the |
| wrap margin) are now managed separately for each thread.</LI> |
| <LI>Added mxmlElementDeleteAttr() function (STR #59)</LI> |
| <LI>mxmlElementSetAttrf() did not work (STR #57)</LI> |
| <LI>mxmlLoad*() incorrectly treated declarations as parent elements (STR |
| #56)</LI> |
| <LI>mxmlLoad*() incorrectly allowed attributes without values (STR #47)</LI> |
| <LI>Fixed Visual C++ build problems (STR #49)</LI> |
| <LI>mxmlLoad*() did not return NULL when an element contained an error |
| (STR #46)</LI> |
| <LI>Added support for the apos character entity (STR #54)</LI> |
| <LI>Fixed whitespace detection with Unicode characters (STR #48)</LI> |
| <LI>mxmlWalkNext() and mxmlWalkPrev() did not work correctly when called |
| with a node with no children as the top node (STR #53)</LI> |
| </UL> |
| <H2><A NAME="7_6">Changes in Mini-XML 2.3</A></H2> |
| <UL> |
| <LI>Added two exceptions to the LGPL to support static linking of |
| applications against Mini-XML</LI> |
| <LI>The mxmldoc utility can now generate man pages, too.</LI> |
| <LI>Added a mxmlNewXML() function</LI> |
| <LI>Added a mxmlElementSetAttrf() function (STR #43)</LI> |
| <LI>Added a snprintf() emulation function for the test program (STR #32)</LI> |
| <LI>Added the _CRT_SECURE_NO_DEPRECATE definition when building on VC++ |
| 2005 (STR #36)</LI> |
| <LI>mxmlLoad*() did not detect missing > characters in elements (STR |
| #41)</LI> |
| <LI>mxmlLoad*() did not detect missing close tags at the end of an XML |
| document (STR #45)</LI> |
| <LI>Added user_data and ref_count members to mxml_node_t structure</LI> |
| <LI>Added mxmlReleaseNode() and mxmlRetainNode() APIs for |
| reference-counted nodes</LI> |
| <LI>Added mxmlSetWrapMargin() to control the wrapping of XML output</LI> |
| <LI>Added conditional check for EINTR error code for certain Windows |
| compilers that do not define it (STR #33)</LI> |
| <LI>The mxmldoc program now generates correct HTML 4.0 output - |
| previously it generated invalid XHTML</LI> |
| <LI>The mxmldoc program now supports "@deprecated@, "@private@", and |
| "@since version@" comments</LI> |
| <LI>Fixed function and enumeration type bugs in mxmldoc</LI> |
| <LI>Fixed the XML schema for mxmldoc</LI> |
| <LI>The mxmldoc program now supports --intro, --section, and --title |
| options</LI> |
| <LI>The mxmlLoad*() functions could leak a node on an error (STR #27)</LI> |
| <LI>The mxml_vsnprintf() function could get in an infinite loop on a |
| buffer overflow (STR #25)</LI> |
| <LI>Added new mxmlNewCDATA() and mxmlSetCDATA() functions to create and |
| set CDATA nodes, which are really just special element nodes</LI> |
| <LI>Added new MXML_IGNORE type and MXML_IGNORE_CB callback to ignore |
| non-element nodes, e.g. whitespace</LI> |
| <LI>mxmlLoad*() did not treat custom data as opaque, so whitespace |
| characters would be lost</LI> |
| </UL> |
| <H2><A NAME="7_7">Changes in Mini-XML 2.2.2</A></H2> |
| <UL> |
| <LI>mxmlLoad*() did not treat custom data as opaque, so whitespace |
| characters would be lost.</LI> |
| </UL> |
| <H2><A NAME="7_8">Changes in Mini-XML 2.2.1</A></H2> |
| <UL> |
| <LI>mxmlLoadFd(), mxmlLoadFile(), and mxmlLoadString() now correctly |
| return NULL on error (STR #21)</LI> |
| <LI>mxmlNewInteger(), mxmlNewOpaque(), mxmlNewReal(), mxmlNewText(), and |
| mxmlNewTextf() incorrectly required a parent node (STR #22)</LI> |
| <LI>Fixed an XML output bug in mxmldoc.</LI> |
| <LI>The "make install" target now uses the install command to set the |
| proper permissions on UNIX/Linux/OSX.</LI> |
| <LI>Fixed a MingW/Cygwin compilation problem (STR #18)</LI> |
| </UL> |
| <H2><A NAME="7_9">Changes in Mini-XML 2.2</A></H2> |
| <UL> |
| <LI>Added shared library support (STR #17)</LI> |
| <LI>mxmlLoad*() now returns an error when an XML stream contains illegal |
| control characters (STR #10)</LI> |
| <LI>mxmlLoad*() now returns an error when an element contains two |
| attributes with the same name in conformance with the XML spec (STR |
| #16)</LI> |
| <LI>Added support for CDATA (STR #14, STR #15)</LI> |
| <LI>Updated comment and processing instruction handling - no entity |
| support per XML specification.</LI> |
| <LI>Added checking for invalid comment termination ("--->" is not |
| allowed)</LI> |
| </UL> |
| <H2><A NAME="7_10">Changes in Mini-XML 2.1</A></H2> |
| <UL> |
| <LI>Added support for custom data nodes (STR #6)</LI> |
| <LI>Now treat UTF-8 sequences which are longer than necessary as an |
| error (STR #4)</LI> |
| <LI>Fixed entity number support (STR #8)</LI> |
| <LI>Fixed mxmlLoadString() bug with UTF-8 (STR #7)</LI> |
| <LI>Fixed entity lookup bug (STR #5)</LI> |
| <LI>Added mxmlLoadFd() and mxmlSaveFd() functions.</LI> |
| <LI>Fixed multi-word UTF-16 handling.</LI> |
| </UL> |
| <H2><A NAME="7_11">Changes in Mini-XML 2.0</A></H2> |
| <UL> |
| <LI>New programmers manual.</LI> |
| <LI>Added Visual C++ project files for Microsoft Windows users.</LI> |
| <LI>Added optimizations to mxmldoc, mxmlSaveFile(), and mxmlIndexNew() |
| (STR #2)</LI> |
| <LI>mxmlEntityAddCallback() now returns an integer status (STR #2)</LI> |
| <LI>Added UTF-16 support (input only; all output is UTF-8)</LI> |
| <LI>Added index functions to build a searchable index of XML nodes.</LI> |
| <LI>Added character entity callback interface to support additional |
| character entities beyond those defined in the XHTML specification.</LI> |
| <LI>Added support for XHTML character entities.</LI> |
| <LI>The mxmldoc utility now produces XML output which conforms to an |
| updated XML schema, described in the file "doc/mxmldoc.xsd".</LI> |
| <LI>Changed the whitespace callback interface to return strings instead |
| of a single character, allowing for greater control over the formatting |
| of XML files written using Mini-XML. THIS CHANGE WILL REQUIRE CHANGES |
| TO YOUR 1.x CODE IF YOU USE WHITESPACE CALLBACKS.</LI> |
| <LI>The mxmldoc utility now produces XML output which conforms to an |
| updated XML schema, described in the file "doc/mxmldoc.xsd".</LI> |
| <LI>Changed the whitespace callback interface to return strings instead |
| of a single character, allowing for greater control over the formatting |
| of XML files written using Mini-XML. THIS CHANGE WILL REQUIRE CHANGES |
| TO YOUR 1.x CODE IF YOU USE WHITESPACE CALLBACKS.</LI> |
| <LI>The mxmldoc utility is now capable of documenting C++ classes, |
| functions, and structures, and correctly handles C++ comments.</LI> |
| <LI>Added new modular tests for mxmldoc.</LI> |
| <LI>Updated the mxmldoc output to be more compatible with embedding in |
| manuals produced with HTMLDOC.</LI> |
| <LI>The makefile incorrectly included a "/" separator between the |
| destination path and install path. This caused problems when building |
| and installing with MingW.</LI> |
| </UL> |
| <H2><A NAME="7_12">Changes in Mini-XML 1.3</A></H2> |
| <UL> |
| <LI>Fixes for mxmldoc.</LI> |
| <LI>Added support for reading standard HTML entity names.</LI> |
| <LI>mxmlLoadString/File() did not decode character entities in element |
| names, attribute names, or attribute values.</LI> |
| <LI>mxmlLoadString/File() would crash when loading non- conformant XML |
| data under an existing parent (top) node.</LI> |
| <LI>Fixed several bugs in the mxmldoc utility.</LI> |
| <LI>Added new error callback function to catch a variety of errors and |
| log them to someplace other than stderr.</LI> |
| <LI>The mxmlElementSetAttr() function now allows for NULL attribute |
| values.</LI> |
| <LI>The load and save functions now properly handle quoted element and |
| attribute name strings properly, e.g. for !DOCTYPE declarations.</LI> |
| </UL> |
| <H2><A NAME="7_13">Changes in Mini-XML 1.2</A></H2> |
| <UL> |
| <LI>Added new "set" methods to set the value of a node.</LI> |
| <LI>Added new formatted text methods mxmlNewTextf() and mxmlSetTextf() |
| to create/set a text node value using printf-style formats.</LI> |
| <LI>Added new standard callbacks for use with the mxmlLoad functions.</LI> |
| <LI>Updated the HTML documentation to include examples of the walk and |
| load function output.</LI> |
| <LI>Added --with/without-ansi configure option to control the strdup() |
| function check.</LI> |
| <LI>Added --with/without-snprintf configure option to control the |
| snprintf() and vsnprintf() function checks.</LI> |
| </UL> |
| <H2><A NAME="7_14">Changes in Mini-XML 1.1.2</A></H2> |
| <UL> |
| <LI>The mxml(3) man page wasn't updated for the string functions.</LI> |
| <LI>mxmlSaveString() returned the wrong number of characters.</LI> |
| <LI>mxml_add_char() updated the buffer pointer in the wrong place.</LI> |
| </UL> |
| <H2><A NAME="7_15">Changes in Mini-XML 1.1.1</A></H2> |
| <UL> |
| <LI>The private mxml_add_ch() function did not update the |
| start-of-buffer pointer which could cause a crash when using |
| mxmlSaveString().</LI> |
| <LI>The private mxml_write_ws() function called putc() instead of using |
| the proper callback which could cause a crash when using |
| mxmlSaveString().</LI> |
| <LI>Added a mxmlSaveAllocString() convenience function for saving an XML |
| node tree to an allocated string.</LI> |
| </UL> |
| <H2><A NAME="7_16">Changes in Mini-XML 1.1</A></H2> |
| <UL> |
| <LI>The mxmlLoadFile() function now uses dynamically allocated string |
| buffers for element names, attribute names, and attribute values. |
| Previously they were capped at 16383, 255, and 255 bytes, respectively.</LI> |
| <LI>Added a new mxmlLoadString() function for loading an XML node tree |
| from a string.</LI> |
| <LI>Added a new mxmlSaveString() function for saving an XML node tree to |
| a string.</LI> |
| <LI>Add emulation of strdup() if the local platform does not provide the |
| function.</LI> |
| </UL> |
| <H2><A NAME="7_17">Changes in Mini-XML 1.0</A></H2> |
| <UL> |
| <LI>The mxmldoc program now handles function arguments, structures, |
| unions, enumerations, classes, and typedefs properly.</LI> |
| <LI>Documentation provided via mxmldoc and more in-line comments in the |
| code.</LI> |
| <LI>Added man pages and packaging files.</LI> |
| </UL> |
| <H2><A NAME="7_18">Changes in Mini-XML 0.93</A></H2> |
| <UL> |
| <LI>New mxmldoc example program that is also used to create and update |
| code documentation using XML and produce HTML reference pages.</LI> |
| <LI>Added mxmlAdd() and mxmlRemove() functions to add and remove nodes |
| from a tree. This provides more flexibility over where the nodes are |
| inserted and allows nodes to be moved within the tree as needed.</LI> |
| <LI>mxmlLoadFile() now correctly handles comments.</LI> |
| <LI>mxmlLoadFile() now supports the required "gt", "quot", and "nbsp" |
| character entities.</LI> |
| <LI>mxmlSaveFile() now uses newlines as whitespace when valid to do so.</LI> |
| <LI>mxmlFindElement() now also takes attribute name and attribute value |
| string arguments to limit the search to specific elements with |
| attributes and/or values.</LI> |
| NULL pointers can be used as "wildcards". |
| <LI>Added uninstall target to makefile, and auto-reconfig if Makefile.in |
| or configure.in are changed.</LI> |
| <LI>mxmlFindElement(), mxmlWalkNext(), and mxmlWalkPrev() now all |
| provide "descend" arguments to control whether they descend into child |
| nodes in the tree.</LI> |
| <LI>Fixed some whitespace issues in mxmlLoadFile().</LI> |
| <LI>Fixed Unicode output and whitespace issues in mxmlSaveFile().</LI> |
| <LI>mxmlSaveFile() now supports a whitespace callback to provide more |
| human-readable XML output under program control.</LI> |
| </UL> |
| <H2><A NAME="7_19">Changes in Mini-XML 0.92</A></H2> |
| <UL> |
| <LI>mxmlSaveFile() didn't return a value on success.</LI> |
| </UL> |
| <H2><A NAME="7_20">Changes in Mini-XML 0.91</A></H2> |
| <UL> |
| <LI>mxmlWalkNext() would go into an infinite loop.</LI> |
| </UL> |
| <H2><A NAME="7_21">Changes in Mini-XML 0.9</A></H2> |
| <UL> |
| <LI>Initial public release.</LI> |
| </UL> |
| <HR NOSHADE> |
| <DIV class="body"> |
| <H1 align="right"><A name="REFERENCE"><IMG align="right" alt="C" height="100" |
| hspace="10" src="C.gif" width="100"></A>Library Reference</H1> |
| <H2 class="title"><A NAME="8_1">Contents</A></H2> |
| <UL class="contents"> |
| <LI><A href="#FUNCTIONS">Functions</A> |
| <UL class="code"> |
| <LI><A href="#mxmlAdd" title="Add a node to a tree.">mxmlAdd</A></LI> |
| <LI><A href="#mxmlDelete" title="Delete a node and all of its children."> |
| mxmlDelete</A></LI> |
| <LI><A href="#mxmlElementDeleteAttr" title="Delete an attribute."> |
| mxmlElementDeleteAttr</A></LI> |
| <LI><A href="#mxmlElementGetAttr" title="Get an attribute."> |
| mxmlElementGetAttr</A></LI> |
| <LI><A href="#mxmlElementSetAttr" title="Set an attribute."> |
| mxmlElementSetAttr</A></LI> |
| <LI><A href="#mxmlElementSetAttrf" title="Set an attribute with a formatted value."> |
| mxmlElementSetAttrf</A></LI> |
| <LI><A href="#mxmlEntityAddCallback" title="Add a callback to convert entities to Unicode."> |
| mxmlEntityAddCallback</A></LI> |
| <LI><A href="#mxmlEntityGetName" title="Get the name that corresponds to the character value."> |
| mxmlEntityGetName</A></LI> |
| <LI><A href="#mxmlEntityGetValue" title="Get the character corresponding to a named entity."> |
| mxmlEntityGetValue</A></LI> |
| <LI><A href="#mxmlEntityRemoveCallback" title="Remove a callback."> |
| mxmlEntityRemoveCallback</A></LI> |
| <LI><A href="#mxmlFindElement" title="Find the named element."> |
| mxmlFindElement</A></LI> |
| <LI><A href="#mxmlFindPath" title="Find a node with the given path."> |
| mxmlFindPath</A></LI> |
| <LI><A href="#mxmlGetCDATA" title="Get the value for a CDATA node."> |
| mxmlGetCDATA</A></LI> |
| <LI><A href="#mxmlGetCustom" title="Get the value for a custom node."> |
| mxmlGetCustom</A></LI> |
| <LI><A href="#mxmlGetElement" title="Get the name for an element node."> |
| mxmlGetElement</A></LI> |
| <LI><A href="#mxmlGetFirstChild" title="Get the first child of an element node."> |
| mxmlGetFirstChild</A></LI> |
| <LI><A href="#mxmlGetInteger" title="Get the integer value from the specified node or its first child."> |
| mxmlGetInteger</A></LI> |
| <LI><A href="#mxmlGetLastChild" title="Get the last child of an element node."> |
| mxmlGetLastChild</A></LI> |
| <LI><A href="#mxmlGetNextSibling" title="Return the node type..."> |
| mxmlGetNextSibling</A></LI> |
| <LI><A href="#mxmlGetOpaque" title="Get an opaque string value for a node or its first child."> |
| mxmlGetOpaque</A></LI> |
| <LI><A href="#mxmlGetParent" title="Get the parent node.">mxmlGetParent</A> |
| </LI> |
| <LI><A href="#mxmlGetPrevSibling" title="Get the previous node for the current parent."> |
| mxmlGetPrevSibling</A></LI> |
| <LI><A href="#mxmlGetReal" title="Get the real value for a node or its first child."> |
| mxmlGetReal</A></LI> |
| <LI><A href="#mxmlGetRefCount" title="Get the current reference (use) count for a node."> |
| mxmlGetRefCount</A></LI> |
| <LI><A href="#mxmlGetText" title="Get the text value for a node or its first child."> |
| mxmlGetText</A></LI> |
| <LI><A href="#mxmlGetType" title="Get the node type.">mxmlGetType</A></LI> |
| <LI><A href="#mxmlGetUserData" title="Get the user data pointer for a node."> |
| mxmlGetUserData</A></LI> |
| <LI><A href="#mxmlIndexDelete" title="Delete an index.">mxmlIndexDelete</A> |
| </LI> |
| <LI><A href="#mxmlIndexEnum" title="Return the next node in the index."> |
| mxmlIndexEnum</A></LI> |
| <LI><A href="#mxmlIndexFind" title="Find the next matching node."> |
| mxmlIndexFind</A></LI> |
| <LI><A href="#mxmlIndexGetCount" title="Get the number of nodes in an index."> |
| mxmlIndexGetCount</A></LI> |
| <LI><A href="#mxmlIndexNew" title="Create a new index.">mxmlIndexNew</A></LI> |
| <LI><A href="#mxmlIndexReset" title="Reset the enumeration/find pointer in the index and return the first node in the index."> |
| mxmlIndexReset</A></LI> |
| <LI><A href="#mxmlLoadFd" title="Load a file descriptor into an XML node tree."> |
| mxmlLoadFd</A></LI> |
| <LI><A href="#mxmlLoadFile" title="Load a file into an XML node tree."> |
| mxmlLoadFile</A></LI> |
| <LI><A href="#mxmlLoadString" title="Load a string into an XML node tree."> |
| mxmlLoadString</A></LI> |
| <LI><A href="#mxmlNewCDATA" title="Create a new CDATA node."> |
| mxmlNewCDATA</A></LI> |
| <LI><A href="#mxmlNewCustom" title="Create a new custom data node."> |
| mxmlNewCustom</A></LI> |
| <LI><A href="#mxmlNewElement" title="Create a new element node."> |
| mxmlNewElement</A></LI> |
| <LI><A href="#mxmlNewInteger" title="Create a new integer node."> |
| mxmlNewInteger</A></LI> |
| <LI><A href="#mxmlNewOpaque" title="Create a new opaque string."> |
| mxmlNewOpaque</A></LI> |
| <LI><A href="#mxmlNewReal" title="Create a new real number node."> |
| mxmlNewReal</A></LI> |
| <LI><A href="#mxmlNewText" title="Create a new text fragment node."> |
| mxmlNewText</A></LI> |
| <LI><A href="#mxmlNewTextf" title="Create a new formatted text fragment node."> |
| mxmlNewTextf</A></LI> |
| <LI><A href="#mxmlNewXML" title="Create a new XML document tree."> |
| mxmlNewXML</A></LI> |
| <LI><A href="#mxmlRelease" title="Release a node.">mxmlRelease</A></LI> |
| <LI><A href="#mxmlRemove" title="Remove a node from its parent."> |
| mxmlRemove</A></LI> |
| <LI><A href="#mxmlRetain" title="Retain a node.">mxmlRetain</A></LI> |
| <LI><A href="#mxmlSAXLoadFd" title="Load a file descriptor into an XML node tree using a SAX callback."> |
| mxmlSAXLoadFd</A></LI> |
| <LI><A href="#mxmlSAXLoadFile" title="Load a file into an XML node tree using a SAX callback."> |
| mxmlSAXLoadFile</A></LI> |
| <LI><A href="#mxmlSAXLoadString" title="Load a string into an XML node tree using a SAX callback."> |
| mxmlSAXLoadString</A></LI> |
| <LI><A href="#mxmlSaveAllocString" title="Save an XML tree to an allocated string."> |
| mxmlSaveAllocString</A></LI> |
| <LI><A href="#mxmlSaveFd" title="Save an XML tree to a file descriptor."> |
| mxmlSaveFd</A></LI> |
| <LI><A href="#mxmlSaveFile" title="Save an XML tree to a file."> |
| mxmlSaveFile</A></LI> |
| <LI><A href="#mxmlSaveString" title="Save an XML node tree to a string."> |
| mxmlSaveString</A></LI> |
| <LI><A href="#mxmlSetCDATA" title="Set the element name of a CDATA node."> |
| mxmlSetCDATA</A></LI> |
| <LI><A href="#mxmlSetCustom" title="Set the data and destructor of a custom data node."> |
| mxmlSetCustom</A></LI> |
| <LI><A href="#mxmlSetCustomHandlers" title="Set the handling functions for custom data."> |
| mxmlSetCustomHandlers</A></LI> |
| <LI><A href="#mxmlSetElement" title="Set the name of an element node."> |
| mxmlSetElement</A></LI> |
| <LI><A href="#mxmlSetErrorCallback" title="Set the error message callback."> |
| mxmlSetErrorCallback</A></LI> |
| <LI><A href="#mxmlSetInteger" title="Set the value of an integer node."> |
| mxmlSetInteger</A></LI> |
| <LI><A href="#mxmlSetOpaque" title="Set the value of an opaque node."> |
| mxmlSetOpaque</A></LI> |
| <LI><A href="#mxmlSetReal" title="Set the value of a real number node."> |
| mxmlSetReal</A></LI> |
| <LI><A href="#mxmlSetText" title="Set the value of a text node."> |
| mxmlSetText</A></LI> |
| <LI><A href="#mxmlSetTextf" title="Set the value of a text node to a formatted string."> |
| mxmlSetTextf</A></LI> |
| <LI><A href="#mxmlSetUserData" title="Set the user data pointer for a node."> |
| mxmlSetUserData</A></LI> |
| <LI><A href="#mxmlSetWrapMargin" title="Set the wrap margin when saving XML data."> |
| mxmlSetWrapMargin</A></LI> |
| <LI><A href="#mxmlWalkNext" title="Walk to the next logical node in the tree."> |
| mxmlWalkNext</A></LI> |
| <LI><A href="#mxmlWalkPrev" title="Walk to the previous logical node in the tree."> |
| mxmlWalkPrev</A></LI> |
| </UL> |
| </LI> |
| <LI><A href="#TYPES">Data Types</A> |
| <UL class="code"> |
| <LI><A href="#mxml_custom_destroy_cb_t" title="Custom data destructor"> |
| mxml_custom_destroy_cb_t</A></LI> |
| <LI><A href="#mxml_custom_load_cb_t" title="Custom data load callback function"> |
| mxml_custom_load_cb_t</A></LI> |
| <LI><A href="#mxml_custom_save_cb_t" title="Custom data save callback function"> |
| mxml_custom_save_cb_t</A></LI> |
| <LI><A href="#mxml_entity_cb_t" title="Entity callback function"> |
| mxml_entity_cb_t</A></LI> |
| <LI><A href="#mxml_error_cb_t" title="Error callback function"> |
| mxml_error_cb_t</A></LI> |
| <LI><A href="#mxml_index_t" title="An XML node index.">mxml_index_t</A></LI> |
| <LI><A href="#mxml_load_cb_t" title="Load callback function"> |
| mxml_load_cb_t</A></LI> |
| <LI><A href="#mxml_node_t" title="An XML node.">mxml_node_t</A></LI> |
| <LI><A href="#mxml_save_cb_t" title="Save callback function"> |
| mxml_save_cb_t</A></LI> |
| <LI><A href="#mxml_sax_cb_t" title="SAX callback function">mxml_sax_cb_t</A> |
| </LI> |
| <LI><A href="#mxml_sax_event_t" title="SAX event type.">mxml_sax_event_t</A> |
| </LI> |
| <LI><A href="#mxml_type_t" title="The XML node type.">mxml_type_t</A></LI> |
| </UL> |
| </LI> |
| <LI><A href="#ENUMERATIONS">Constants</A> |
| <UL class="code"> |
| <LI><A href="#mxml_sax_event_e" title="SAX event type.">mxml_sax_event_e</A> |
| </LI> |
| <LI><A href="#mxml_type_e" title="The XML node type.">mxml_type_e</A></LI> |
| </UL> |
| </LI> |
| </UL> |
| <H2 class="title"><A name="FUNCTIONS">Functions</A></H2> |
| <H3 class="function"><A name="mxmlAdd">mxmlAdd</A></H3> |
| <P class="description">Add a node to a tree.</P> |
| <P class="code"> void mxmlAdd ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> int where, |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *child, |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node</DD> |
| <DT>where</DT> |
| <DD class="description">Where to add, MXML_ADD_BEFORE or MXML_ADD_AFTER</DD> |
| <DT>child</DT> |
| <DD class="description">Child node for where or MXML_ADD_TO_PARENT</DD> |
| <DT>node</DT> |
| <DD class="description">Node to add</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">Adds the specified node to the parent. If the |
| child argument is not NULL, puts the new node before or after the |
| specified child depending on the value of the where argument. If the |
| child argument is NULL, puts the new node at the beginning of the child |
| list (MXML_ADD_BEFORE) or at the end of the child list |
| (MXML_ADD_AFTER). The constant MXML_ADD_TO_PARENT can be used to |
| specify a NULL child pointer.</P> |
| <H3 class="function"><A name="mxmlDelete">mxmlDelete</A></H3> |
| <P class="description">Delete a node and all of its children.</P> |
| <P class="code"> void mxmlDelete ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to delete</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">If the specified node has a parent, this function |
| first removes the node from its parent using the mxmlRemove() function.</P> |
| <H3 class="function"><A NAME="8_2_3"> |
| <!--span class="info"--> |
| Mini-XML 2.4 <A name="mxmlElementDeleteAttr">mxmlElementDeleteAttr</A></A> |
| </H3> |
| <P class="description">Delete an attribute.</P> |
| <P class="code"> void mxmlElementDeleteAttr ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *name |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Element</DD> |
| <DT>name</DT> |
| <DD class="description">Attribute name</DD> |
| </DL> |
| <H3 class="function"><A name="mxmlElementGetAttr">mxmlElementGetAttr</A></H3> |
| <P class="description">Get an attribute.</P> |
| <P class="code"> const char *mxmlElementGetAttr ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *name |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Element node</DD> |
| <DT>name</DT> |
| <DD class="description">Name of attribute</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Attribute value or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">This function returns NULL if the node is not an |
| element or the named attribute does not exist.</P> |
| <H3 class="function"><A name="mxmlElementSetAttr">mxmlElementSetAttr</A></H3> |
| <P class="description">Set an attribute.</P> |
| <P class="code"> void mxmlElementSetAttr ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *name, |
| <BR> const char *value |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Element node</DD> |
| <DT>name</DT> |
| <DD class="description">Name of attribute</DD> |
| <DT>value</DT> |
| <DD class="description">Attribute value</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">If the named attribute already exists, the value |
| of the attribute is replaced by the new string value. The string value |
| is copied into the element node. This function does nothing if the node |
| is not an element.</P> |
| <H3 class="function"><A NAME="8_2_6"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlElementSetAttrf">mxmlElementSetAttrf</A></A></H3> |
| <P class="description">Set an attribute with a formatted value.</P> |
| <P class="code"> void mxmlElementSetAttrf ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *name, |
| <BR> const char *format, |
| <BR> ... |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Element node</DD> |
| <DT>name</DT> |
| <DD class="description">Name of attribute</DD> |
| <DT>format</DT> |
| <DD class="description">Printf-style attribute value</DD> |
| <DT>...</DT> |
| <DD class="description">Additional arguments as needed</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">If the named attribute already exists, the value |
| of the attribute is replaced by the new formatted string. The formatted |
| string value is copied into the element node. This function does |
| nothing if the node is not an element.</P> |
| <H3 class="function"><A name="mxmlEntityAddCallback"> |
| mxmlEntityAddCallback</A></H3> |
| <P class="description">Add a callback to convert entities to Unicode.</P> |
| <P class="code"> int mxmlEntityAddCallback ( |
| <BR> <A href="#mxml_entity_cb_t">mxml_entity_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>cb</DT> |
| <DD class="description">Callback function to add</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H3 class="function"><A name="mxmlEntityGetName">mxmlEntityGetName</A></H3> |
| <P class="description">Get the name that corresponds to the character |
| value.</P> |
| <P class="code"> const char *mxmlEntityGetName ( |
| <BR> int val |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>val</DT> |
| <DD class="description">Character value</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Entity name or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">If val does not need to be represented by a named |
| entity, NULL is returned.</P> |
| <H3 class="function"><A name="mxmlEntityGetValue">mxmlEntityGetValue</A></H3> |
| <P class="description">Get the character corresponding to a named |
| entity.</P> |
| <P class="code"> int mxmlEntityGetValue ( |
| <BR> const char *name |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>name</DT> |
| <DD class="description">Entity name</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Character value or -1 on error</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The entity name can also be a numeric constant. -1 |
| is returned if the name is not known.</P> |
| <H3 class="function"><A name="mxmlEntityRemoveCallback"> |
| mxmlEntityRemoveCallback</A></H3> |
| <P class="description">Remove a callback.</P> |
| <P class="code"> void mxmlEntityRemoveCallback ( |
| <BR> <A href="#mxml_entity_cb_t">mxml_entity_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>cb</DT> |
| <DD class="description">Callback function to remove</DD> |
| </DL> |
| <H3 class="function"><A name="mxmlFindElement">mxmlFindElement</A></H3> |
| <P class="description">Find the named element.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlFindElement |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> const char *name, |
| <BR> const char *attr, |
| <BR> const char *value, |
| <BR> int descend |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Current node</DD> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>name</DT> |
| <DD class="description">Element name or NULL for any</DD> |
| <DT>attr</DT> |
| <DD class="description">Attribute name, or NULL for none</DD> |
| <DT>value</DT> |
| <DD class="description">Attribute value, or NULL for any</DD> |
| <DT>descend</DT> |
| <DD class="description">Descend into tree - MXML_DESCEND, |
| MXML_NO_DESCEND, or MXML_DESCEND_FIRST</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Element node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The search is constrained by the name, attribute |
| name, and value; any NULL names or values are treated as wildcards, so |
| different kinds of searches can be implemented by looking for all |
| elements of a given name or all elements with a specific attribute. The |
| descend argument determines whether the search descends into child |
| nodes; normally you will use MXML_DESCEND_FIRST for the initial search |
| and MXML_NO_DESCEND to find additional direct descendents of the node. |
| The top node argument constrains the search to a particular node's |
| children.</P> |
| <H3 class="function"><A NAME="8_2_12"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlFindPath">mxmlFindPath</A></A></H3> |
| <P class="description">Find a node with the given path.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlFindPath ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> const char *path |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>path</DT> |
| <DD class="description">Path to element</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Found node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The "path" is a slash-separated list of element |
| names. The name "*" is considered a wildcard for one or more levels of |
| elements. For example, "foo/one/two", "bar/two/one", "*/one", and so |
| forth. |
| <BR> |
| <BR> The first child node of the found node is returned if the given |
| node has children and the first child is a value node.</P> |
| <H3 class="function"><A NAME="8_2_13"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetCDATA">mxmlGetCDATA</A></A></H3> |
| <P class="description">Get the value for a CDATA node.</P> |
| <P class="code"> const char *mxmlGetCDATA ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">CDATA value or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node is not a |
| CDATA element.</P> |
| <H3 class="function"><A NAME="8_2_14"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetCustom">mxmlGetCustom</A></A></H3> |
| <P class="description">Get the value for a custom node.</P> |
| <P class="code"> const void *mxmlGetCustom ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Custom value or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node (or its |
| first child) is not a custom value node.</P> |
| <H3 class="function"><A NAME="8_2_15"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetElement">mxmlGetElement</A></A></H3> |
| <P class="description">Get the name for an element node.</P> |
| <P class="code"> const char *mxmlGetElement ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Element name or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node is not |
| an element node.</P> |
| <H3 class="function"><A NAME="8_2_16"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetFirstChild">mxmlGetFirstChild</A></A></H3> |
| <P class="description">Get the first child of an element node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> |
| *mxmlGetFirstChild ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First child or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node is not |
| an element node or if the node has no children.</P> |
| <H3 class="function"><A NAME="8_2_17"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetInteger">mxmlGetInteger</A></A></H3> |
| <P class="description">Get the integer value from the specified node or |
| its first child.</P> |
| <P class="code"> int mxmlGetInteger ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Integer value or 0</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">0 is returned if the node (or its first child) is |
| not an integer value node.</P> |
| <H3 class="function"><A NAME="8_2_18"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetLastChild">mxmlGetLastChild</A></A></H3> |
| <P class="description">Get the last child of an element node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> |
| *mxmlGetLastChild ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Last child or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node is not |
| an element node or if the node has no children.</P> |
| <H3 class="function"><A name="mxmlGetNextSibling">mxmlGetNextSibling</A></H3> |
| <P class="description">Return the node type...</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> |
| *mxmlGetNextSibling ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Get the next node for the current parent.</P> |
| <P class="discussion"><CODE>NULL</CODE> is returned if this is the last |
| child for the current parent.</P> |
| <H3 class="function"><A NAME="8_2_20"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetOpaque">mxmlGetOpaque</A></A></H3> |
| <P class="description">Get an opaque string value for a node or its |
| first child.</P> |
| <P class="code"> const char *mxmlGetOpaque ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Opaque string or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node (or its |
| first child) is not an opaque value node.</P> |
| <H3 class="function"><A NAME="8_2_21"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetParent">mxmlGetParent</A></A></H3> |
| <P class="description">Get the parent node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlGetParent ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Parent node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned for a root node.</P> |
| <H3 class="function"><A NAME="8_2_22"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetPrevSibling">mxmlGetPrevSibling</A></A></H3> |
| <P class="description">Get the previous node for the current parent.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> |
| *mxmlGetPrevSibling ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Previous node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if this is the first |
| child for the current parent.</P> |
| <H3 class="function"><A NAME="8_2_23"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetReal">mxmlGetReal</A></A></H3> |
| <P class="description">Get the real value for a node or its first child.</P> |
| <P class="code"> double mxmlGetReal ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Real value or 0.0</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">0.0 is returned if the node (or its first child) |
| is not a real value node.</P> |
| <H3 class="function"><A NAME="8_2_24"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetRefCount">mxmlGetRefCount</A></A></H3> |
| <P class="description">Get the current reference (use) count for a node.</P> |
| <P class="code"> int mxmlGetRefCount ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Reference count</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The initial reference count of new nodes is 1. Use |
| the <A href="#mxmlRetain"><CODE>mxmlRetain</CODE></A> and <A href="#mxmlRelease"> |
| <CODE>mxmlRelease</CODE></A> functions to increment and decrement a |
| node's reference count. .</P> |
| <H3 class="function"><A NAME="8_2_25"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetText">mxmlGetText</A></A></H3> |
| <P class="description">Get the text value for a node or its first child.</P> |
| <P class="code"> const char *mxmlGetText ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> int *whitespace |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| <DT>whitespace</DT> |
| <DD class="description">1 if string is preceded by whitespace, 0 |
| otherwise</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Text string or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>NULL</CODE> is returned if the node (or its |
| first child) is not a text node. The "whitespace" argument can be NULL.</P> |
| <H3 class="function"><A NAME="8_2_26"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetType">mxmlGetType</A></A></H3> |
| <P class="description">Get the node type.</P> |
| <P class="code"> <A href="#mxml_type_t">mxml_type_t</A> mxmlGetType ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Type of node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion"><CODE>MXML_IGNORE</CODE> is returned if "node" is <CODE> |
| NULL</CODE>.</P> |
| <H3 class="function"><A NAME="8_2_27"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlGetUserData">mxmlGetUserData</A></A></H3> |
| <P class="description">Get the user data pointer for a node.</P> |
| <P class="code"> void *mxmlGetUserData ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to get</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">User data pointer</P> |
| <H3 class="function"><A name="mxmlIndexDelete">mxmlIndexDelete</A></H3> |
| <P class="description">Delete an index.</P> |
| <P class="code"> void mxmlIndexDelete ( |
| <BR> <A href="#mxml_index_t">mxml_index_t</A> *ind |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>ind</DT> |
| <DD class="description">Index to delete</DD> |
| </DL> |
| <H3 class="function"><A name="mxmlIndexEnum">mxmlIndexEnum</A></H3> |
| <P class="description">Return the next node in the index.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlIndexEnum ( |
| <BR> <A href="#mxml_index_t">mxml_index_t</A> *ind |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>ind</DT> |
| <DD class="description">Index to enumerate</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Next node or NULL if there is none</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">Nodes are returned in the sorted order of the |
| index.</P> |
| <H3 class="function"><A name="mxmlIndexFind">mxmlIndexFind</A></H3> |
| <P class="description">Find the next matching node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlIndexFind ( |
| <BR> <A href="#mxml_index_t">mxml_index_t</A> *ind, |
| <BR> const char *element, |
| <BR> const char *value |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>ind</DT> |
| <DD class="description">Index to search</DD> |
| <DT>element</DT> |
| <DD class="description">Element name to find, if any</DD> |
| <DT>value</DT> |
| <DD class="description">Attribute value, if any</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Node or NULL if none found</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">You should call mxmlIndexReset() prior to using |
| this function for the first time with a particular set of "element" and |
| "value" strings. Passing NULL for both "element" and "value" is |
| equivalent to calling mxmlIndexEnum().</P> |
| <H3 class="function"><A NAME="8_2_31"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlIndexGetCount">mxmlIndexGetCount</A></A></H3> |
| <P class="description">Get the number of nodes in an index.</P> |
| <P class="code"> int mxmlIndexGetCount ( |
| <BR> <A href="#mxml_index_t">mxml_index_t</A> *ind |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>ind</DT> |
| <DD class="description">Index of nodes</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Number of nodes in index</P> |
| <H3 class="function"><A name="mxmlIndexNew">mxmlIndexNew</A></H3> |
| <P class="description">Create a new index.</P> |
| <P class="code"> <A href="#mxml_index_t">mxml_index_t</A> *mxmlIndexNew |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *element, |
| <BR> const char *attr |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">XML node tree</DD> |
| <DT>element</DT> |
| <DD class="description">Element to index or NULL for all</DD> |
| <DT>attr</DT> |
| <DD class="description">Attribute to index or NULL for none</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New index</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The index will contain all nodes that contain the |
| named element and/or attribute. If both "element" and "attr" are NULL, |
| then the index will contain a sorted list of the elements in the node |
| tree. Nodes are sorted by element name and optionally by attribute |
| value if the "attr" argument is not NULL.</P> |
| <H3 class="function"><A name="mxmlIndexReset">mxmlIndexReset</A></H3> |
| <P class="description">Reset the enumeration/find pointer in the index |
| and return the first node in the index.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlIndexReset |
| ( |
| <BR> <A href="#mxml_index_t">mxml_index_t</A> *ind |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>ind</DT> |
| <DD class="description">Index to reset</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if there is none</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">This function should be called prior to using |
| mxmlIndexEnum() or mxmlIndexFind() for the first time.</P> |
| <H3 class="function"><A name="mxmlLoadFd">mxmlLoadFd</A></H3> |
| <P class="description">Load a file descriptor into an XML node tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlLoadFd ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> int fd, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>fd</DT> |
| <DD class="description">File descriptor to read from</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the file could not be read.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified file are added to the |
| specified top node. If no top node is provided, the XML file MUST be |
| well-formed with a single parent node like <?xml> for the entire file. |
| The callback function returns the value type that should be used for |
| child nodes. If MXML_NO_CALLBACK is specified then all child nodes will |
| be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type.</P> |
| <H3 class="function"><A name="mxmlLoadFile">mxmlLoadFile</A></H3> |
| <P class="description">Load a file into an XML node tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlLoadFile ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> FILE *fp, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>fp</DT> |
| <DD class="description">File to read from</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the file could not be read.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified file are added to the |
| specified top node. If no top node is provided, the XML file MUST be |
| well-formed with a single parent node like <?xml> for the entire file. |
| The callback function returns the value type that should be used for |
| child nodes. If MXML_NO_CALLBACK is specified then all child nodes will |
| be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type.</P> |
| <H3 class="function"><A name="mxmlLoadString">mxmlLoadString</A></H3> |
| <P class="description">Load a string into an XML node tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlLoadString |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> const char *s, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>s</DT> |
| <DD class="description">String to load</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the string has errors.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified string are added to the |
| specified top node. If no top node is provided, the XML string MUST be |
| well-formed with a single parent node like <?xml> for the entire |
| string. The callback function returns the value type that should be |
| used for child nodes. If MXML_NO_CALLBACK is specified then all child |
| nodes will be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type.</P> |
| <H3 class="function"><A NAME="8_2_37"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlNewCDATA">mxmlNewCDATA</A></A></H3> |
| <P class="description">Create a new CDATA node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewCDATA ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> const char *data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>data</DT> |
| <DD class="description">Data string</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new CDATA node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new CDATA node has no parent. The data string must |
| be nul-terminated and is copied into the new node. CDATA nodes use the |
| MXML_ELEMENT type.</P> |
| <H3 class="function"><A NAME="8_2_38"> |
| <!--span class="info"--> |
| Mini-XML 2.1 <A name="mxmlNewCustom">mxmlNewCustom</A></A></H3> |
| <P class="description">Create a new custom data node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewCustom ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> void *data, |
| <BR> <A href="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</A> |
| destroy |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>data</DT> |
| <DD class="description">Pointer to data</DD> |
| <DT>destroy</DT> |
| <DD class="description">Function to destroy data</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new custom node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new element node has no parent. NULL can be passed |
| when the data in the node is not dynamically allocated or is separately |
| managed.</P> |
| <H3 class="function"><A name="mxmlNewElement">mxmlNewElement</A></H3> |
| <P class="description">Create a new element node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewElement |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> const char *name |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>name</DT> |
| <DD class="description">Name of element</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new element node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new element node has no parent.</P> |
| <H3 class="function"><A name="mxmlNewInteger">mxmlNewInteger</A></H3> |
| <P class="description">Create a new integer node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewInteger |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> int integer |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>integer</DT> |
| <DD class="description">Integer value</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new integer node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new integer node has no parent.</P> |
| <H3 class="function"><A name="mxmlNewOpaque">mxmlNewOpaque</A></H3> |
| <P class="description">Create a new opaque string.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewOpaque ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> const char *opaque |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>opaque</DT> |
| <DD class="description">Opaque string</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new opaque node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new opaque node has no parent. The opaque string |
| must be nul-terminated and is copied into the new node.</P> |
| <H3 class="function"><A name="mxmlNewReal">mxmlNewReal</A></H3> |
| <P class="description">Create a new real number node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewReal ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> double real |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>real</DT> |
| <DD class="description">Real number value</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new real number node is added to the end of |
| the specified parent's child list. The constant MXML_NO_PARENT can be |
| used to specify that the new real number node has no parent.</P> |
| <H3 class="function"><A name="mxmlNewText">mxmlNewText</A></H3> |
| <P class="description">Create a new text fragment node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewText ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> int whitespace, |
| <BR> const char *string |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>whitespace</DT> |
| <DD class="description">1 = leading whitespace, 0 = no whitespace</DD> |
| <DT>string</DT> |
| <DD class="description">String</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new text node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new text node has no parent. The whitespace |
| parameter is used to specify whether leading whitespace is present |
| before the node. The text string must be nul-terminated and is copied |
| into the new node.</P> |
| <H3 class="function"><A name="mxmlNewTextf">mxmlNewTextf</A></H3> |
| <P class="description">Create a new formatted text fragment node.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewTextf ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *parent, |
| <BR> int whitespace, |
| <BR> const char *format, |
| <BR> ... |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>parent</DT> |
| <DD class="description">Parent node or MXML_NO_PARENT</DD> |
| <DT>whitespace</DT> |
| <DD class="description">1 = leading whitespace, 0 = no whitespace</DD> |
| <DT>format</DT> |
| <DD class="description">Printf-style frmat string</DD> |
| <DT>...</DT> |
| <DD class="description">Additional args as needed</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The new text node is added to the end of the |
| specified parent's child list. The constant MXML_NO_PARENT can be used |
| to specify that the new text node has no parent. The whitespace |
| parameter is used to specify whether leading whitespace is present |
| before the node. The format string must be nul-terminated and is |
| formatted into the new node.</P> |
| <H3 class="function"><A NAME="8_2_45"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlNewXML">mxmlNewXML</A></A></H3> |
| <P class="description">Create a new XML document tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlNewXML ( |
| <BR> const char *version |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>version</DT> |
| <DD class="description">Version number to use</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New ?xml node</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The "version" argument specifies the version |
| number to put in the ?xml element node. If NULL, version 1.0 is |
| assumed.</P> |
| <H3 class="function"><A NAME="8_2_46"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlRelease">mxmlRelease</A></A></H3> |
| <P class="description">Release a node.</P> |
| <P class="code"> int mxmlRelease ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New reference count</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">When the reference count reaches zero, the node |
| (and any children) is deleted via mxmlDelete().</P> |
| <H3 class="function"><A name="mxmlRemove">mxmlRemove</A></H3> |
| <P class="description">Remove a node from its parent.</P> |
| <P class="code"> void mxmlRemove ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to remove</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">Does not free memory used by the node - use |
| mxmlDelete() for that. This function does nothing if the node has no |
| parent.</P> |
| <H3 class="function"><A NAME="8_2_48"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlRetain">mxmlRetain</A></A></H3> |
| <P class="description">Retain a node.</P> |
| <P class="code"> int mxmlRetain ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">New reference count</P> |
| <H3 class="function"><A NAME="8_2_49"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlSAXLoadFd">mxmlSAXLoadFd</A></A></H3> |
| <P class="description">Load a file descriptor into an XML node tree |
| using a SAX callback.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlSAXLoadFd ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> int fd, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb, |
| <BR> <A href="#mxml_sax_cb_t">mxml_sax_cb_t</A> sax_cb, |
| <BR> void *sax_data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>fd</DT> |
| <DD class="description">File descriptor to read from</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| <DT>sax_cb</DT> |
| <DD class="description">SAX callback or MXML_NO_CALLBACK</DD> |
| <DT>sax_data</DT> |
| <DD class="description">SAX user data</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the file could not be read.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified file are added to the |
| specified top node. If no top node is provided, the XML file MUST be |
| well-formed with a single parent node like <?xml> for the entire file. |
| The callback function returns the value type that should be used for |
| child nodes. If MXML_NO_CALLBACK is specified then all child nodes will |
| be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type. |
| <BR> |
| <BR> The SAX callback must call mxmlRetain() for any nodes that need to |
| be kept for later use. Otherwise, nodes are deleted when the parent |
| node is closed or after each data, comment, CDATA, or directive node.</P> |
| <H3 class="function"><A NAME="8_2_50"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlSAXLoadFile">mxmlSAXLoadFile</A></A></H3> |
| <P class="description">Load a file into an XML node tree using a SAX |
| callback.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlSAXLoadFile |
| ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> FILE *fp, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb, |
| <BR> <A href="#mxml_sax_cb_t">mxml_sax_cb_t</A> sax_cb, |
| <BR> void *sax_data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>fp</DT> |
| <DD class="description">File to read from</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| <DT>sax_cb</DT> |
| <DD class="description">SAX callback or MXML_NO_CALLBACK</DD> |
| <DT>sax_data</DT> |
| <DD class="description">SAX user data</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the file could not be read.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified file are added to the |
| specified top node. If no top node is provided, the XML file MUST be |
| well-formed with a single parent node like <?xml> for the entire file. |
| The callback function returns the value type that should be used for |
| child nodes. If MXML_NO_CALLBACK is specified then all child nodes will |
| be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type. |
| <BR> |
| <BR> The SAX callback must call mxmlRetain() for any nodes that need to |
| be kept for later use. Otherwise, nodes are deleted when the parent |
| node is closed or after each data, comment, CDATA, or directive node.</P> |
| <H3 class="function"><A NAME="8_2_51"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlSAXLoadString">mxmlSAXLoadString</A></A></H3> |
| <P class="description">Load a string into an XML node tree using a SAX |
| callback.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> |
| *mxmlSAXLoadString ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> const char *s, |
| <BR> <A href="#mxml_load_cb_t">mxml_load_cb_t</A> cb, |
| <BR> <A href="#mxml_sax_cb_t">mxml_sax_cb_t</A> sax_cb, |
| <BR> void *sax_data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>s</DT> |
| <DD class="description">String to load</DD> |
| <DT>cb</DT> |
| <DD class="description">Callback function or MXML_NO_CALLBACK</DD> |
| <DT>sax_cb</DT> |
| <DD class="description">SAX callback or MXML_NO_CALLBACK</DD> |
| <DT>sax_data</DT> |
| <DD class="description">SAX user data</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">First node or NULL if the string has errors.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The nodes in the specified string are added to the |
| specified top node. If no top node is provided, the XML string MUST be |
| well-formed with a single parent node like <?xml> for the entire |
| string. The callback function returns the value type that should be |
| used for child nodes. If MXML_NO_CALLBACK is specified then all child |
| nodes will be either MXML_ELEMENT or MXML_TEXT nodes. |
| <BR> |
| <BR> The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, |
| MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for loading |
| child nodes of the specified type. |
| <BR> |
| <BR> The SAX callback must call mxmlRetain() for any nodes that need to |
| be kept for later use. Otherwise, nodes are deleted when the parent |
| node is closed or after each data, comment, CDATA, or directive node.</P> |
| <H3 class="function"><A name="mxmlSaveAllocString">mxmlSaveAllocString</A> |
| </H3> |
| <P class="description">Save an XML tree to an allocated string.</P> |
| <P class="code"> char *mxmlSaveAllocString ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> <A href="#mxml_save_cb_t">mxml_save_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to write</DD> |
| <DT>cb</DT> |
| <DD class="description">Whitespace callback or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Allocated string or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">This function returns a pointer to a string |
| containing the textual representation of the XML node tree. The string |
| should be freed using the free() function when you are done with it. |
| NULL is returned if the node would produce an empty string or if the |
| string cannot be allocated. |
| <BR> |
| <BR> The callback argument specifies a function that returns a |
| whitespace string or NULL before and after each element. If |
| MXML_NO_CALLBACK is specified, whitespace will only be added before |
| MXML_TEXT nodes with leading whitespace and before attribute names |
| inside opening element tags.</P> |
| <H3 class="function"><A name="mxmlSaveFd">mxmlSaveFd</A></H3> |
| <P class="description">Save an XML tree to a file descriptor.</P> |
| <P class="code"> int mxmlSaveFd ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> int fd, |
| <BR> <A href="#mxml_save_cb_t">mxml_save_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to write</DD> |
| <DT>fd</DT> |
| <DD class="description">File descriptor to write to</DD> |
| <DT>cb</DT> |
| <DD class="description">Whitespace callback or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on error.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The callback argument specifies a function that |
| returns a whitespace string or NULL before and after each element. If |
| MXML_NO_CALLBACK is specified, whitespace will only be added before |
| MXML_TEXT nodes with leading whitespace and before attribute names |
| inside opening element tags.</P> |
| <H3 class="function"><A name="mxmlSaveFile">mxmlSaveFile</A></H3> |
| <P class="description">Save an XML tree to a file.</P> |
| <P class="code"> int mxmlSaveFile ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> FILE *fp, |
| <BR> <A href="#mxml_save_cb_t">mxml_save_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to write</DD> |
| <DT>fp</DT> |
| <DD class="description">File to write to</DD> |
| <DT>cb</DT> |
| <DD class="description">Whitespace callback or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on error.</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The callback argument specifies a function that |
| returns a whitespace string or NULL before and after each element. If |
| MXML_NO_CALLBACK is specified, whitespace will only be added before |
| MXML_TEXT nodes with leading whitespace and before attribute names |
| inside opening element tags.</P> |
| <H3 class="function"><A name="mxmlSaveString">mxmlSaveString</A></H3> |
| <P class="description">Save an XML node tree to a string.</P> |
| <P class="code"> int mxmlSaveString ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> char *buffer, |
| <BR> int bufsize, |
| <BR> <A href="#mxml_save_cb_t">mxml_save_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to write</DD> |
| <DT>buffer</DT> |
| <DD class="description">String buffer</DD> |
| <DT>bufsize</DT> |
| <DD class="description">Size of string buffer</DD> |
| <DT>cb</DT> |
| <DD class="description">Whitespace callback or MXML_NO_CALLBACK</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Size of string</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">This function returns the total number of bytes |
| that would be required for the string but only copies (bufsize - 1) |
| characters into the specified buffer. |
| <BR> |
| <BR> The callback argument specifies a function that returns a |
| whitespace string or NULL before and after each element. If |
| MXML_NO_CALLBACK is specified, whitespace will only be added before |
| MXML_TEXT nodes with leading whitespace and before attribute names |
| inside opening element tags.</P> |
| <H3 class="function"><A NAME="8_2_56"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlSetCDATA">mxmlSetCDATA</A></A></H3> |
| <P class="description">Set the element name of a CDATA node.</P> |
| <P class="code"> int mxmlSetCDATA ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>data</DT> |
| <DD class="description">New data string</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not a CDATA element node.</P> |
| <H3 class="function"><A NAME="8_2_57"> |
| <!--span class="info"--> |
| Mini-XML 2.1 <A name="mxmlSetCustom">mxmlSetCustom</A></A></H3> |
| <P class="description">Set the data and destructor of a custom data |
| node.</P> |
| <P class="code"> int mxmlSetCustom ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> void *data, |
| <BR> <A href="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</A> |
| destroy |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>data</DT> |
| <DD class="description">New data pointer</DD> |
| <DT>destroy</DT> |
| <DD class="description">New destructor function</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not a custom node.</P> |
| <H3 class="function"><A name="mxmlSetCustomHandlers"> |
| mxmlSetCustomHandlers</A></H3> |
| <P class="description">Set the handling functions for custom data.</P> |
| <P class="code"> void mxmlSetCustomHandlers ( |
| <BR> <A href="#mxml_custom_load_cb_t">mxml_custom_load_cb_t</A> |
| load, |
| <BR> <A href="#mxml_custom_save_cb_t">mxml_custom_save_cb_t</A> save |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>load</DT> |
| <DD class="description">Load function</DD> |
| <DT>save</DT> |
| <DD class="description">Save function</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The load function accepts a node pointer and a |
| data string and must return 0 on success and non-zero on error. |
| <BR> |
| <BR> The save function accepts a node pointer and must return a malloc'd |
| string on success and NULL on error.</P> |
| <H3 class="function"><A name="mxmlSetElement">mxmlSetElement</A></H3> |
| <P class="description">Set the name of an element node.</P> |
| <P class="code"> int mxmlSetElement ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *name |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>name</DT> |
| <DD class="description">New name string</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it is not an element |
| node.</P> |
| <H3 class="function"><A name="mxmlSetErrorCallback">mxmlSetErrorCallback</A> |
| </H3> |
| <P class="description">Set the error message callback.</P> |
| <P class="code"> void mxmlSetErrorCallback ( |
| <BR> <A href="#mxml_error_cb_t">mxml_error_cb_t</A> cb |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>cb</DT> |
| <DD class="description">Error callback function</DD> |
| </DL> |
| <H3 class="function"><A name="mxmlSetInteger">mxmlSetInteger</A></H3> |
| <P class="description">Set the value of an integer node.</P> |
| <P class="code"> int mxmlSetInteger ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> int integer |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>integer</DT> |
| <DD class="description">Integer value</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not an integer node.</P> |
| <H3 class="function"><A name="mxmlSetOpaque">mxmlSetOpaque</A></H3> |
| <P class="description">Set the value of an opaque node.</P> |
| <P class="code"> int mxmlSetOpaque ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> const char *opaque |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>opaque</DT> |
| <DD class="description">Opaque string</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not an opaque node.</P> |
| <H3 class="function"><A name="mxmlSetReal">mxmlSetReal</A></H3> |
| <P class="description">Set the value of a real number node.</P> |
| <P class="code"> int mxmlSetReal ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> double real |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>real</DT> |
| <DD class="description">Real number value</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not a real number node.</P> |
| <H3 class="function"><A name="mxmlSetText">mxmlSetText</A></H3> |
| <P class="description">Set the value of a text node.</P> |
| <P class="code"> int mxmlSetText ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> int whitespace, |
| <BR> const char *string |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>whitespace</DT> |
| <DD class="description">1 = leading whitespace, 0 = no whitespace</DD> |
| <DT>string</DT> |
| <DD class="description">String</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not a text node.</P> |
| <H3 class="function"><A name="mxmlSetTextf">mxmlSetTextf</A></H3> |
| <P class="description">Set the value of a text node to a formatted |
| string.</P> |
| <P class="code"> int mxmlSetTextf ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> int whitespace, |
| <BR> const char *format, |
| <BR> ... |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>whitespace</DT> |
| <DD class="description">1 = leading whitespace, 0 = no whitespace</DD> |
| <DT>format</DT> |
| <DD class="description">Printf-style format string</DD> |
| <DT>...</DT> |
| <DD class="description">Additional arguments as needed</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The node is not changed if it (or its first child) |
| is not a text node.</P> |
| <H3 class="function"><A NAME="8_2_66"> |
| <!--span class="info"--> |
| Mini-XML 2.7 <A name="mxmlSetUserData">mxmlSetUserData</A></A></H3> |
| <P class="description">Set the user data pointer for a node.</P> |
| <P class="code"> int mxmlSetUserData ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> void *data |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Node to set</DD> |
| <DT>data</DT> |
| <DD class="description">User data pointer</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">0 on success, -1 on failure</P> |
| <H3 class="function"><A NAME="8_2_67"> |
| <!--span class="info"--> |
| Mini-XML 2.3 <A name="mxmlSetWrapMargin">mxmlSetWrapMargin</A></A></H3> |
| <P class="description">Set the wrap margin when saving XML data.</P> |
| <P class="code"> void mxmlSetWrapMargin ( |
| <BR> int column |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>column</DT> |
| <DD class="description">Column for wrapping, 0 to disable wrapping</DD> |
| </DL> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">Wrapping is disabled when "column" is 0.</P> |
| <H3 class="function"><A name="mxmlWalkNext">mxmlWalkNext</A></H3> |
| <P class="description">Walk to the next logical node in the tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlWalkNext ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> int descend |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Current node</DD> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>descend</DT> |
| <DD class="description">Descend into tree - MXML_DESCEND, |
| MXML_NO_DESCEND, or MXML_DESCEND_FIRST</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Next node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The descend argument controls whether the first |
| child is considered to be the next node. The top node argument |
| constrains the walk to the node's children.</P> |
| <H3 class="function"><A name="mxmlWalkPrev">mxmlWalkPrev</A></H3> |
| <P class="description">Walk to the previous logical node in the tree.</P> |
| <P class="code"> <A href="#mxml_node_t">mxml_node_t</A> *mxmlWalkPrev ( |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *node, |
| <BR> <A href="#mxml_node_t">mxml_node_t</A> *top, |
| <BR> int descend |
| <BR> );</P> |
| <H4 class="parameters">Parameters</H4> |
| <DL> |
| <DT>node</DT> |
| <DD class="description">Current node</DD> |
| <DT>top</DT> |
| <DD class="description">Top node</DD> |
| <DT>descend</DT> |
| <DD class="description">Descend into tree - MXML_DESCEND, |
| MXML_NO_DESCEND, or MXML_DESCEND_FIRST</DD> |
| </DL> |
| <H4 class="returnvalue">Return Value</H4> |
| <P class="description">Previous node or NULL</P> |
| <H4 class="discussion">Discussion</H4> |
| <P class="discussion">The descend argument controls whether the previous |
| node's last child is considered to be the previous node. The top node |
| argument constrains the walk to the node's children.</P> |
| <H2 class="title"><A name="TYPES">Data Types</A></H2> |
| <H3 class="typedef"><A name="mxml_custom_destroy_cb_t"> |
| mxml_custom_destroy_cb_t</A></H3> |
| <P class="description">Custom data destructor</P> |
| <P class="code"> typedef void (*mxml_custom_destroy_cb_t)(void *);</P> |
| <H3 class="typedef"><A name="mxml_custom_load_cb_t"> |
| mxml_custom_load_cb_t</A></H3> |
| <P class="description">Custom data load callback function</P> |
| <P class="code"> typedef int (*mxml_custom_load_cb_t)(<A href="#mxml_node_t"> |
| mxml_node_t</A> *, const char *);</P> |
| <H3 class="typedef"><A name="mxml_custom_save_cb_t"> |
| mxml_custom_save_cb_t</A></H3> |
| <P class="description">Custom data save callback function</P> |
| <P class="code"> typedef char *(*mxml_custom_save_cb_t)(<A href="#mxml_node_t"> |
| mxml_node_t</A> *);</P> |
| <H3 class="typedef"><A name="mxml_entity_cb_t">mxml_entity_cb_t</A></H3> |
| <P class="description">Entity callback function</P> |
| <P class="code"> typedef int (*mxml_entity_cb_t)(const char *);</P> |
| <H3 class="typedef"><A name="mxml_error_cb_t">mxml_error_cb_t</A></H3> |
| <P class="description">Error callback function</P> |
| <P class="code"> typedef void (*mxml_error_cb_t)(const char *);</P> |
| <H3 class="typedef"><A name="mxml_index_t">mxml_index_t</A></H3> |
| <P class="description">An XML node index.</P> |
| <P class="code"> typedef struct <A href="#mxml_index_s">mxml_index_s</A> |
| mxml_index_t;</P> |
| <H3 class="typedef"><A name="mxml_load_cb_t">mxml_load_cb_t</A></H3> |
| <P class="description">Load callback function</P> |
| <P class="code"> typedef <A href="#mxml_type_t">mxml_type_t</A> |
| (*mxml_load_cb_t)(<A href="#mxml_node_t">mxml_node_t</A> *);</P> |
| <H3 class="typedef"><A name="mxml_node_t">mxml_node_t</A></H3> |
| <P class="description">An XML node.</P> |
| <P class="code"> typedef struct <A href="#mxml_node_s">mxml_node_s</A> |
| mxml_node_t;</P> |
| <H3 class="typedef"><A name="mxml_save_cb_t">mxml_save_cb_t</A></H3> |
| <P class="description">Save callback function</P> |
| <P class="code"> typedef const char *(*mxml_save_cb_t)(<A href="#mxml_node_t"> |
| mxml_node_t</A> *, int);</P> |
| <H3 class="typedef"><A name="mxml_sax_cb_t">mxml_sax_cb_t</A></H3> |
| <P class="description">SAX callback function</P> |
| <P class="code"> typedef void (*mxml_sax_cb_t)(<A href="#mxml_node_t"> |
| mxml_node_t</A> *, mxml_sax_event_t, void *);</P> |
| <H3 class="typedef"><A name="mxml_sax_event_t">mxml_sax_event_t</A></H3> |
| <P class="description">SAX event type.</P> |
| <P class="code"> typedef enum <A href="#mxml_sax_event_e"> |
| mxml_sax_event_e</A> mxml_sax_event_t;</P> |
| <H3 class="typedef"><A name="mxml_type_t">mxml_type_t</A></H3> |
| <P class="description">The XML node type.</P> |
| <P class="code"> typedef enum <A href="#mxml_type_e">mxml_type_e</A> |
| mxml_type_t;</P> |
| <H2 class="title"><A name="ENUMERATIONS">Constants</A></H2> |
| <H3 class="enumeration"><A name="mxml_sax_event_e">mxml_sax_event_e</A></H3> |
| <P class="description">SAX event type.</P> |
| <H4 class="constants">Constants</H4> |
| <DL> |
| <DT>MXML_SAX_CDATA</DT> |
| <DD class="description">CDATA node</DD> |
| <DT>MXML_SAX_COMMENT</DT> |
| <DD class="description">Comment node</DD> |
| <DT>MXML_SAX_DATA</DT> |
| <DD class="description">Data node</DD> |
| <DT>MXML_SAX_DIRECTIVE</DT> |
| <DD class="description">Processing directive node</DD> |
| <DT>MXML_SAX_ELEMENT_CLOSE</DT> |
| <DD class="description">Element closed</DD> |
| <DT>MXML_SAX_ELEMENT_OPEN</DT> |
| <DD class="description">Element opened</DD> |
| </DL> |
| <H3 class="enumeration"><A name="mxml_type_e">mxml_type_e</A></H3> |
| <P class="description">The XML node type.</P> |
| <H4 class="constants">Constants</H4> |
| <DL> |
| <DT>MXML_CUSTOM |
| <!--span class="info"--> |
| Mini-XML 2.1 </DT> |
| <DD class="description">Custom data</DD> |
| <DT>MXML_ELEMENT</DT> |
| <DD class="description">XML element with attributes</DD> |
| <DT>MXML_IGNORE |
| <!--span class="info"--> |
| Mini-XML 2.3 </DT> |
| <DD class="description">Ignore/throw away node</DD> |
| <DT>MXML_INTEGER</DT> |
| <DD class="description">Integer value</DD> |
| <DT>MXML_OPAQUE</DT> |
| <DD class="description">Opaque string</DD> |
| <DT>MXML_REAL</DT> |
| <DD class="description">Real value</DD> |
| <DT>MXML_TEXT</DT> |
| <DD class="description">Text fragment</DD> |
| </DL> |
| </DIV><HR NOSHADE> |
| <H1 align="right"><A name="SCHEMA"><IMG align="right" alt="D" height="100" |
| hspace="10" src="D.gif" width="100"></A>XML Schema</H1> |
| <P>This appendix provides the XML schema that is used for the XML files |
| produced by <TT>mxmldoc</TT>. This schema is available on-line at:</P> |
| <PRE> |
| http://www.msweet.org/schema/mxmldoc.xsd |
| </PRE> |
| <H2><A NAME="9_1">mxmldoc.xsd</A></H2> |
| <PRE><SMALL> |
| <?xml version="1.0"?> |
| <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> |
| <xsd:annotation> |
| <xsd:documentation xml:lang="en"> |
| Mini-XML 2.8 documentation schema for mxmldoc output. |
| Copyright 2003-2014 by Michael Sweet. |
| </xsd:documentation> |
| </xsd:annotation> |
| |
| <!-- basic element definitions --> |
| <xsd:element name="argument" type="argumentType"/> |
| <xsd:element name="class" type="classType"/> |
| <xsd:element name="constant" type="constantType"/> |
| <xsd:element name="description" type="xsd:string"/> |
| <xsd:element name="enumeration" type="enumerationType"/> |
| <xsd:element name="function" type="functionType"/> |
| <xsd:element name="mxmldoc" type="mxmldocType"/> |
| <xsd:element name="namespace" type="namespaceType"/> |
| <xsd:element name="returnvalue" type="returnvalueType"/> |
| <xsd:element name="seealso" type="identifierList"/> |
| <xsd:element name="struct" type="structType"/> |
| <xsd:element name="typedef" type="typedefType"/> |
| <xsd:element name="type" type="xsd:string"/> |
| <xsd:element name="union" type="unionType"/> |
| <xsd:element name="variable" type="variableType"/> |
| |
| <!-- descriptions of complex elements --> |
| <xsd:complexType name="argumentType"> |
| <xsd:sequence> |
| <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| <xsd:attribute name="default" type="xsd:string" use="optional"/> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| <xsd:attribute name="direction" type="direction" use="optional" |
| default="I"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="classType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:choice minOccurs="0" maxOccurs="unbounded"> |
| <xsd:element ref="class"/> |
| <xsd:element ref="enumeration"/> |
| <xsd:element ref="function"/> |
| <xsd:element ref="struct"/> |
| <xsd:element ref="typedef"/> |
| <xsd:element ref="union"/> |
| <xsd:element ref="variable"/> |
| </xsd:choice> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| <xsd:attribute name="parent" type="xsd:string" use="optional"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="constantType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="enumerationType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="functionType"> |
| <xsd:sequence> |
| <xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/> |
| <xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| <xsd:attribute name="scope" type="scope" use="optional"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="mxmldocType"> |
| <xsd:choice minOccurs="0" maxOccurs="unbounded"> |
| <xsd:element ref="class"/> |
| <xsd:element ref="enumeration"/> |
| <xsd:element ref="function"/> |
| <xsd:element ref="namespace"/> |
| <xsd:element ref="struct"/> |
| <xsd:element ref="typedef"/> |
| <xsd:element ref="union"/> |
| <xsd:element ref="variable"/> |
| </xsd:choice> |
| </xsd:complexType> |
| |
| <xsd:complexType name="namespaceType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:choice minOccurs="0" maxOccurs="unbounded"> |
| <xsd:element ref="class"/> |
| <xsd:element ref="enumeration"/> |
| <xsd:element ref="function"/> |
| <xsd:element ref="struct"/> |
| <xsd:element ref="typedef"/> |
| <xsd:element ref="union"/> |
| <xsd:element ref="variable"/> |
| </xsd:choice> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="returnvalueType"> |
| <xsd:sequence> |
| <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| </xsd:complexType> |
| |
| <xsd:complexType name="structType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:choice minOccurs="0" maxOccurs="unbounded"> |
| <xsd:element ref="variable"/> |
| <xsd:element ref="function"/> |
| </xsd:choice> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="typedefType"> |
| <xsd:sequence> |
| <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="unionType"> |
| <xsd:sequence> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <xsd:complexType name="variableType"> |
| <xsd:sequence> |
| <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> |
| <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> |
| </xsd:sequence> |
| <xsd:attribute name="name" type="identifier" use="required"/> |
| </xsd:complexType> |
| |
| <!-- data types --> |
| <xsd:simpleType name="direction"> |
| <xsd:restriction base="xsd:string"> |
| <xsd:enumeration value="I"/> |
| <xsd:enumeration value="O"/> |
| <xsd:enumeration value="IO"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <xsd:simpleType name="identifier"> |
| <xsd:restriction base="xsd:string"> |
| <xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| |
| <xsd:simpleType name="identifierList"> |
| <xsd:list itemType="identifier"/> |
| </xsd:simpleType> |
| |
| <xsd:simpleType name="scope"> |
| <xsd:restriction base="xsd:string"> |
| <xsd:enumeration value=""/> |
| <xsd:enumeration value="private"/> |
| <xsd:enumeration value="protected"/> |
| <xsd:enumeration value="public"/> |
| </xsd:restriction> |
| </xsd:simpleType> |
| </xsd:schema> |
| </SMALL></PRE> |
| </BODY> |
| </HTML> |