README.md
1Mini-XML Version 3.1
2====================
3
4Mini-XML is a small XML parsing library that you can use to read XML data files
5or strings in your application without requiring large non-standard libraries.
6Mini-XML only requires a "make" program and an ANSI C compatible compiler - GCC
7works, as do most vendors' ANSI C compilers.
8
9Mini-XML provides the following functionality:
10
11- Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and
12 strings.
13- Data is stored in a linked-list tree structure, preserving the XML data
14 hierarchy.
15- SAX (streamed) reading of XML files and strings to minimize memory usage.
16- Supports arbitrary element names, attributes, and attribute values with no
17 preset limits, just available memory.
18- Supports integer, real, opaque ("cdata"), and text data types in "leaf" nodes.
19- Functions for creating and managing trees of data.
20- "Find" and "walk" functions for easily locating and navigating trees of data.
21
22Mini-XML doesn't do validation or other types of processing on the data
23based upon schema files or other sources of definition information.
24
25> Note: Version 3.0 hides the definition of the `mxml_node_t` structure,
26> requiring the use of the various accessor functions that were introduced in
27> version 2.0.
28
29
30Building Mini-XML
31-----------------
32
33Mini-XML comes with an autoconf-based configure script; just type the
34following command to get things going:
35
36 ./configure
37
38The default install prefix is `/usr/local`, which can be overridden using the
39`--prefix` option:
40
41 ./configure --prefix=/foo
42
43Other configure options can be found using the `--help` option:
44
45 ./configure --help
46
47Once you have configured the software, type `make` to do the build and run
48the test program to verify that things are working, as follows:
49
50 make
51
52If you are using Mini-XML under Microsoft Windows with Visual C++, use the
53included project files in the `vcnet` subdirectory to build the library
54instead. Note: The static library on Windows is NOT thread-safe.
55
56
57## Installing Mini-XML
58
59The `install` target will install Mini-XML in the lib and include
60directories:
61
62 make install
63
64Once you have installed it, use the `-lmxml` option to link your application
65against it.
66
67
68Documentation
69-------------
70
71The documentation is available in the `doc` subdirectory in the files
72`mxml.html` (HTML) and `mxml.epub` (EPUB). You can also look at the
73`testmxml.c` source file for examples of using Mini-XML.
74
75Mini-XML provides a single header file which you include:
76
77 #include <mxml.h>
78
79Nodes (elements, comments, processing directives, integers, opaque strings, real
80numbers, and text strings) are represented by `mxml_node_t` objects. New nodes
81can be created using the `mxmlNewElement()`, `mxmlNewInteger()`,
82`mxmlNewOpaque()`, `mxmlNewReal()`, and `mxmlNewText()` functions. Only
83elements can have child nodes, and the top node must be the "?xml" processing
84directive.
85
86You load an XML file using the `mxmlLoadFile()` function:
87
88 FILE *fp;
89 mxml_node_t *tree;
90
91 fp = fopen("filename.xml", "r");
92 tree = mxmlLoadFile(NULL, fp, MXML_OPAQUE_CALLBACK);
93 fclose(fp);
94
95Similarly, you save an XML file using the `mxmlSaveFile()` function:
96
97 FILE *fp;
98 mxml_node_t *tree;
99
100 fp = fopen("filename.xml", "w");
101 mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
102 fclose(fp);
103
104The `mxmlLoadString()`, `mxmlSaveAllocString()`, and `mxmlSaveString()`
105functions load XML node trees from and save XML node trees to strings:
106
107 char buffer[8192];
108 char *ptr;
109 mxml_node_t *tree;
110
111 ...
112 tree = mxmlLoadString(NULL, buffer, MXML_OPAQUE_CALLBACK);
113
114 ...
115 mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK);
116
117 ...
118 ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
119
120You can find a named element/node using the `mxmlFindElement()` function:
121
122 mxml_node_t *node = mxmlFindElement(tree, tree, "name", "attr",
123 "value", MXML_DESCEND);
124
125The `name`, `attr`, and `value` arguments can be passed as `NULL` to act as
126wildcards, e.g.:
127
128 /* Find the first "a" element */
129 node = mxmlFindElement(tree, tree, "a", NULL, NULL, MXML_DESCEND);
130
131 /* Find the first "a" element with "href" attribute */
132 node = mxmlFindElement(tree, tree, "a", "href", NULL, MXML_DESCEND);
133
134 /* Find the first "a" element with "href" to a URL */
135 node = mxmlFindElement(tree, tree, "a", "href",
136 "http://www.minixml.org/",
137 MXML_DESCEND);
138
139 /* Find the first element with a "src" attribute*/
140 node = mxmlFindElement(tree, tree, NULL, "src", NULL, MXML_DESCEND);
141
142 /* Find the first element with a "src" = "foo.jpg" */
143 node = mxmlFindElement(tree, tree, NULL, "src", "foo.jpg",
144 MXML_DESCEND);
145
146You can also iterate with the same function:
147
148 mxml_node_t *node;
149
150 for (node = mxmlFindElement(tree, tree, "name", NULL, NULL,
151 MXML_DESCEND);
152 node != NULL;
153 node = mxmlFindElement(node, tree, "name", NULL, NULL,
154 MXML_DESCEND))
155 {
156 ... do something ...
157 }
158
159The `mxmlFindPath()` function finds the (first) value node under a specific
160element using an XPath:
161
162 mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
163
164The `mxmlGetInteger()`, `mxmlGetOpaque()`, `mxmlGetReal()`, and
165`mxmlGetText()` functions retrieve the corresponding value from a node:
166
167 mxml_node_t *node;
168
169 int intvalue = mxmlGetInteger(node);
170
171 const char *opaquevalue = mxmlGetOpaque(node);
172
173 double realvalue = mxmlGetReal(node);
174
175 int whitespacevalue;
176 const char *textvalue = mxmlGetText(node, &whitespacevalue);
177
178Finally, once you are done with the XML data, use the `mxmlDelete()`
179function to recursively free the memory that is used for a particular node
180or the entire tree:
181
182 mxmlDelete(tree);
183
184
185Getting Help And Reporting Problems
186-----------------------------------
187
188The [Mini-XML project page](https://www.msweet.org/mxml) provides access to the
189current version of this software, documentation, and Github issue tracking page.
190
191
192Legal Stuff
193-----------
194
195Copyright © 2003-2019 by Michael R Sweet
196
197The Mini-XML library is licensed under the Apache License Version 2.0 with an
198exception to allow linking against GPL2/LGPL2-only software. See the files
199"LICENSE" and "NOTICE" for more information.
200