diff options
Diffstat (limited to 'mxml/README')
| -rw-r--r-- | mxml/README | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/mxml/README b/mxml/README new file mode 100644 index 000000000..31a026649 --- /dev/null +++ b/mxml/README @@ -0,0 +1,204 @@ +README - 05/19/2005 +------------------- + + +INTRODUCTION + + This README file describes the Mini-XML library version + 2.2.2. + + Mini-XML is a small XML parsing library that you can use to + read XML and XML-like data files in your application without + requiring large non-standard libraries. Mini-XML only + requires an ANSI C compatible compiler (GCC works, as do + most vendors' ANSI C compilers) and a "make" program. + + Mini-XML provides the following functionality: + + - Reading of UTF-8 and UTF-16 and writing of UTF-8 + encoded XML files and strings. + - Data is stored in a linked-list tree structure, + preserving the XML data hierarchy. + - Supports arbitrary element names, attributes, and + attribute values with no preset limits, just available + memory. + - Supports integer, real, opaque ("cdata"), and text + data types in "leaf" nodes. + - Functions for creating and managing trees of data. + - "Find" and "walk" functions for easily locating and + navigating trees of data. + + Mini-XML doesn't do validation or other types of processing + on the data based upon schema files or other sources of + definition information. + + +BUILDING Mini-XML + + Mini-XML comes with an autoconf-based configure script; just + type the following command to get things going: + + ./configure + + The default install prefix is /usr/local, which can be + overridden using the --prefix option: + + ./configure --prefix=/foo + + Other configure options can be found using the --help + option: + + ./configure --help + + Once you have configured the software, type "make" to do the + build and run the test program to verify that things are + working, as follows: + + make + + If you are using Mini-XML under Microsoft Windows with + Visual C++, use the included project files in the "vcnet" + subdirectory to build the library instead. + + +INSTALLING Mini-XML + + The "install" target will install Mini-XML in the lib and + include directories: + + make install + + Once you have installed it, use the "-lmxml" option to link + your application against it. + + +DOCUMENTATION + + The documentation is available in the "doc" subdirectory in + the files "mxml.html" (HTML) and "mxml.pdf" (PDF). You can + also look at the "testmxml.c" and "mxmldoc.c" source files + for examples of using Mini-XML. + + Mini-XML provides a single header file which you include: + + #include <mxml.h> + + Nodes are defined by the "mxml_node_t" structure; the "type" + member defines the node type (element, integer, opaque, + real, or text) which determines which value you want to look + at in the "value" union. New nodes can be created using the + "mxmlNewElement()", "mxmlNewInteger()", "mxmlNewOpaque()", + "mxmlNewReal()", and "mxmlNewText()" functions. Only + elements can have child nodes, and the top node must be an + element, usually "?xml". + + You load an XML file using the "mxmlLoadFile()" function: + + FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "r"); + tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK); + fclose(fp); + + Similarly, you save an XML file using the "mxmlSaveFile()" + function: + + FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "w"); + mxmlSaveFile(tree, fp, MXML_NO_CALLBACK); + fclose(fp); + + The "mxmlLoadString()", "mxmlSaveAllocString()", and + "mxmlSaveString()" functions load XML node trees from and + save XML node trees to strings: + + char buffer[8192]; + char *ptr; + mxml_node_t *tree; + + ... + tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK); + + ... + mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK); + + ... + ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK); + + You can find a named element/node using the + "mxmlFindElement()" function: + + mxml_node_t *node = mxmlFindElement(tree, tree, "name", "attr", + "value", MXML_DESCEND); + + The "name", "attr", and "value" arguments can be passed as + NULL to act as wildcards, e.g.: + + /* Find the first "a" element */ + node = mxmlFindElement(tree, tree, "a", NULL, NULL, MXML_DESCEND); + + /* Find the first "a" element with "href" attribute */ + node = mxmlFindElement(tree, tree, "a", "href", NULL, MXML_DESCEND); + + /* Find the first "a" element with "href" to a URL */ + node = mxmlFindElement(tree, tree, "a", "href", + "http://www.easysw.com/~mike/mxml/", + MXML_DESCEND); + + /* Find the first element with a "src" attribute*/ + node = mxmlFindElement(tree, tree, NULL, "src", NULL, MXML_DESCEND); + + /* Find the first element with a "src" = "foo.jpg" */ + node = mxmlFindElement(tree, tree, NULL, "src", "foo.jpg", + MXML_DESCEND); + + You can also iterate with the same function: + + 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 ... + } + + Finally, once you are done with the XML data, use the + "mxmlDelete()" function to recursively free the memory that + is used for a particular node or the entire tree: + + mxmlDelete(tree); + + +GETTING HELP AND REPORTING PROBLEMS + + You can email me at "mxml@easysw.com" to report problems + and/or ask for help. Just don't expect an instant response, + as I get a *lot* of email... + + +LEGAL STUFF + + The Mini-XML library is Copyright 2003-2005 by Michael Sweet. + + This library is free software; you can redistribute it + and/or modify it under the terms of the GNU Library General + Public License as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any + later version. + + 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 Library General Public License for + more details. + + You should have received a copy of the GNU Library General + Public License along with this library; if not, write to the + Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA + 02139, USA. |