


mxml(3)                   Michael Sweet                   mxml(3)


NAME
       mxml - mini-xml library

INCLUDE FILE
       #include <mxml.h>

LIBRARY
       -lmxml

DESCRIPTION
       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:

       o   Reading and writing of UTF-8 encoded XML files.

       o   Reading and writing of UTF-8 encoded XML strings.

       o   Data  is  stored in a linked-list tree structure, pre-
           serving the XML data hierarchy.

       o   Supports  arbitrary  element  names,  attributes,  and
           attribute values with no preset limits, just available
           memory.

       o   Supports integer, real,  opaque  ("cdata"),  and  text
           data types in "leaf" nodes.

       o   Functions for creating and managing trees of data.

       o   "Find"  and  "walk"  functions for easily locating and
           navigating trees of data.

       Mini-XML doesn't do validation or other types of  process-
       ing  on  the data based upon schema files or other sources
       of definition information, nor does it  support  character
       entities  other  than those required by the XML specifica-
       tion.  Also, since Mini-XML does not  support  the  UTF-16
       encoding,  it  is  technically  not  a conforming XML con-
       sumer/client.

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



25 February 2005             mini-XML                           1





mxml(3)                   Michael Sweet                   mxml(3)


       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  "mxmlFindEle-
       ment()" 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,



25 February 2005             mini-XML                           2





mxml(3)                   Michael Sweet                   mxml(3)


                                  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);

SEE ALSO
       mxmldoc(1),       Mini-XML       Programmers       Manual,
       http://www.easysw.com/~mike/mxml/

COPYRIGHT
       Copyright 2003-2005 by Michael Sweet.













25 February 2005             mini-XML                           3


