mxml/README

   1 README - 05/19/2005
   2 -------------------
   3
   4
   5 INTRODUCTION
   6
   7     This README file describes the Mini-XML library version
   8     2.2.2.
   9
  10     Mini-XML is a small XML parsing library that you can use to
  11     read XML and XML-like data files in your application without
  12     requiring large non-standard libraries.  Mini-XML only
  13     requires an ANSI C compatible compiler (GCC works, as do
  14     most vendors' ANSI C compilers) and a "make" program.
  15
  16     Mini-XML provides the following functionality:
  17
  18         - Reading of UTF-8 and UTF-16 and writing of UTF-8
  19           encoded XML files and strings.
  20         - Data is stored in a linked-list tree structure,
  21           preserving the XML data hierarchy.
  22         - Supports arbitrary element names, attributes, and
  23           attribute values with no preset limits, just available
  24           memory.
  25         - Supports integer, real, opaque ("cdata"), and text
  26           data types in "leaf" nodes.
  27         - Functions for creating and managing trees of data.
  28         - "Find" and "walk" functions for easily locating and
  29           navigating trees of data.
  30
  31     Mini-XML doesn't do validation or other types of processing
  32     on the data based upon schema files or other sources of
  33     definition information.
  34
  35
  36 BUILDING Mini-XML
  37
  38     Mini-XML comes with an autoconf-based configure script; just
  39     type the following command to get things going:
  40
  41         ./configure
  42
  43     The default install prefix is /usr/local, which can be
  44     overridden using the --prefix option:
  45
  46         ./configure --prefix=/foo
  47
  48     Other configure options can be found using the --help
  49     option:
  50
  51         ./configure --help
  52
  53     Once you have configured the software, type "make" to do the
  54     build and run the test program to verify that things are
  55     working, as follows:
  56
  57         make
  58
  59     If you are using Mini-XML under Microsoft Windows with
  60     Visual C++, use the included project files in the "vcnet"
  61     subdirectory to build the library instead.
  62
  63
  64 INSTALLING Mini-XML
  65
  66     The "install" target will install Mini-XML in the lib and
  67     include directories:
  68
  69         make install
  70
  71     Once you have installed it, use the "-lmxml" option to link
  72     your application against it.
  73
  74
  75 DOCUMENTATION
  76
  77     The documentation is available in the "doc" subdirectory in
  78     the files "mxml.html" (HTML) and "mxml.pdf" (PDF). You can
  79     also look at the "testmxml.c" and "mxmldoc.c" source files
  80     for examples of using Mini-XML.
  81
  82     Mini-XML provides a single header file which you include:
  83
  84         #include <mxml.h>
  85
  86     Nodes are defined by the "mxml_node_t" structure; the "type"
  87     member defines the node type (element, integer, opaque,
  88     real, or text) which determines which value you want to look
  89     at in the "value" union.  New nodes can be created using the
  90     "mxmlNewElement()", "mxmlNewInteger()", "mxmlNewOpaque()",
  91     "mxmlNewReal()", and "mxmlNewText()" functions.  Only
  92     elements can have child nodes, and the top node must be an
  93     element, usually "?xml".
  94
  95     You load an XML file using the "mxmlLoadFile()" function:
  96
  97         FILE *fp;
  98         mxml_node_t *tree;
  99
 100         fp = fopen("filename.xml", "r");
 101         tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
 102         fclose(fp);
 103
 104     Similarly, you save an XML file using the "mxmlSaveFile()"
 105     function:
 106
 107         FILE *fp;
 108         mxml_node_t *tree;
 109
 110         fp = fopen("filename.xml", "w");
 111         mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
 112         fclose(fp);
 113
 114     The "mxmlLoadString()", "mxmlSaveAllocString()", and
 115     "mxmlSaveString()" functions load XML node trees from and
 116     save XML node trees to strings:
 117
 118         char buffer[8192];
 119         char *ptr;
 120         mxml_node_t *tree;
 121
 122         ...
 123         tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK);
 124
 125         ...
 126         mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK);
 127
 128         ...
 129         ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
 130
 131     You can find a named element/node using the
 132     "mxmlFindElement()" function:
 133
 134         mxml_node_t *node = mxmlFindElement(tree, tree, "name", "attr",
 135                                             "value", MXML_DESCEND);
 136
 137     The "name", "attr", and "value" arguments can be passed as
 138     NULL to act as wildcards, e.g.:
 139
 140         /* Find the first "a" element */
 141         node = mxmlFindElement(tree, tree, "a", NULL, NULL, MXML_DESCEND);
 142
 143         /* Find the first "a" element with "href" attribute */
 144         node = mxmlFindElement(tree, tree, "a", "href", NULL, MXML_DESCEND);
 145
 146         /* Find the first "a" element with "href" to a URL */
 147         node = mxmlFindElement(tree, tree, "a", "href",
 148                                "http://www.easysw.com/~mike/mxml/",
 149                                MXML_DESCEND);
 150
 151         /* Find the first element with a "src" attribute*/
 152         node = mxmlFindElement(tree, tree, NULL, "src", NULL, MXML_DESCEND);
 153
 154         /* Find the first element with a "src" = "foo.jpg" */
 155         node = mxmlFindElement(tree, tree, NULL, "src", "foo.jpg",
 156                                MXML_DESCEND);
 157
 158     You can also iterate with the same function:
 159
 160         mxml_node_t *node;
 161
 162         for (node = mxmlFindElement(tree, tree, "name", NULL, NULL,
 163                                     MXML_DESCEND);
 164              node != NULL;
 165              node = mxmlFindElement(node, tree, "name", NULL, NULL,
 166                                     MXML_DESCEND))
 167         {
 168           ... do something ...
 169         }
 170
 171     Finally, once you are done with the XML data, use the
 172     "mxmlDelete()" function to recursively free the memory that
 173     is used for a particular node or the entire tree:
 174
 175         mxmlDelete(tree);
 176
 177
 178 GETTING HELP AND REPORTING PROBLEMS
 179
 180     You can email me at "mxml@easysw.com" to report problems
 181     and/or ask for help.  Just don't expect an instant response,
 182     as I get a *lot* of email...
 183
 184
 185 LEGAL STUFF
 186
 187     The Mini-XML library is Copyright 2003-2005 by Michael Sweet.
 188
 189     This library is free software; you can redistribute it
 190     and/or modify it under the terms of the GNU Library General
 191     Public License as published by the Free Software Foundation;
 192     either version 2 of the License, or (at your option) any
 193     later version.
 194
 195     This library is distributed in the hope that it will be
 196     useful, but WITHOUT ANY WARRANTY; without even the implied
 197     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 198     PURPOSE.  See the GNU Library General Public License for
 199     more details.
 200
 201     You should have received a copy of the GNU Library General
 202     Public License along with this library; if not, write to the
 203     Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
 204     02139, USA.