Thanks to the fine work of Russell Bryant and Dancho Lazarov, we now have autoconf...
[asterisk/asterisk.git] / 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.