1README - 2011-12-20
2-------------------
3
4
5INTRODUCTION
6
7 This README file describes the Mini-XML library version 2.7.
8
9 Mini-XML is a small XML parsing library that you can use to read XML and
10 XML-like data files in your application without requiring large non-standard
11 libraries. Mini-XML only requires an ANSI C compatible compiler (GCC works,
12 as do most vendors' ANSI C compilers) and a "make" program.
13
14 Mini-XML provides the following functionality:
15
16 - Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and
17 strings.
18 - Data is stored in a linked-list tree structure, preserving the XML
19 data hierarchy.
20 - Supports arbitrary element names, attributes, and attribute values
21 with no preset limits, just available memory.
22 - Supports integer, real, opaque ("cdata"), and text data types in
23 "leaf" nodes.
24 - Functions for creating and managing trees of data.
25 - "Find" and "walk" functions for easily locating and navigating trees
26 of data.
27
28 Mini-XML doesn't do validation or other types of processing on the data
29 based upon schema files or other sources of definition information.
30
31
32BUILDING Mini-XML
33
34 Mini-XML comes with an autoconf-based configure script; just type the
35 following command to get things going:
36
37 ./configure
38
39 The default install prefix is /usr/local, which can be overridden using the
40 --prefix option:
41
42 ./configure --prefix=/foo
43
44 Other configure options can be found using the --help option:
45
46 ./configure --help
47
48 Once you have configured the software, type "make" to do the build and run
49 the test program to verify that things are working, as follows:
50
51 make
52
53 If you are using Mini-XML under Microsoft Windows with Visual C++ 2008, use
54 the included project files in the "vcnet" subdirectory to build the library
55 instead.
56
57
58INSTALLING Mini-XML
59
60 The "install" target will install Mini-XML in the lib and include
61 directories:
62
63 make install
64
65 Once you have installed it, use the "-lmxml" option to link your application
66 against it.
67
68
69DOCUMENTATION
70
71 The documentation is available in the "doc" subdirectory in the files
72 "mxml.html" (HTML) and "mxml.pdf" (PDF). You can also look at the
73 "testmxml.c" and "mxmldoc.c" source files for examples of using Mini-XML.
74
75 Mini-XML provides a single header file which you include:
76
77 #include <mxml.h>
78
79 Nodes are defined by the "mxml_node_t" structure; the "type" member defines
80 the node type (element, integer, opaque, real, or text) which determines
81 which value you want to look at in the "value" union. New nodes can be
82 created using the "mxmlNewElement()", "mxmlNewInteger()", "mxmlNewOpaque()",
83 "mxmlNewReal()", and "mxmlNewText()" functions. Only elements can have
84 child nodes, and the top node must be an element, usually "?xml".
85
86 You 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_NO_CALLBACK);
93 fclose(fp);
94
95 Similarly, 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
104 The "mxmlLoadString()", "mxmlSaveAllocString()", and "mxmlSaveString()"
105 functions 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_NO_CALLBACK);
113
114 ...
115 mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK);
116
117 ...
118 ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
119
120 You 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
125 The "name", "attr", and "value" arguments can be passed as NULL to act as
126 wildcards, 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
146 You 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
159 The "mxmlFindPath()" function finds the (first) value node under a specific
160 element using a "path":
161
162 mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
163
164 The "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and
165 "mxmlGetText()" functions retrieve the 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
178 Finally, once you are done with the XML data, use the "mxmlDelete()"
179 function to recursively free the memory that is used for a particular node
180 or the entire tree:
181
182 mxmlDelete(tree);
183
184
185GETTING HELP AND REPORTING PROBLEMS
186
187 The Mini-XML web site provides access to a discussion forum and bug
188 reporting page:
189
190 http://www.minixml.org/
191
192
193LEGAL STUFF
194
195 The Mini-XML library is Copyright 2003-2011 by Michael Sweet. License terms
196 are described in the file "COPYING".
197