You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1944 lines
49 KiB
1944 lines
49 KiB
.TH mxml 3 "Mini-XML API" "2024-03-20" "Mini-XML API"
|
|
.SH NAME
|
|
mxml \- Mini-XML API
|
|
.SH INCLUDE FILE
|
|
#include <mxml.h>
|
|
.SH LIBRARY
|
|
\-lmxml
|
|
.SH 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.
|
|
.PP
|
|
Mini-XML provides the following functionality:
|
|
.IP \(bu 4
|
|
Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and strings.
|
|
.IP \(bu 4
|
|
Data is stored in a linked-list tree structure,
|
|
preserving the XML data hierarchy.
|
|
.IP \(bu 4
|
|
Supports arbitrary element names, attributes, and attribute
|
|
values with no preset limits, just available memory.
|
|
.IP \(bu 4
|
|
Supports integer, real, opaque ("CDATA"), and text data types in
|
|
"leaf" nodes.
|
|
.IP \(bu 4
|
|
Functions for creating, indexing, and managing trees of data.
|
|
.IP \(bu 4
|
|
"Find" and "walk" functions for easily locating and navigating
|
|
trees of data.
|
|
.PP
|
|
Mini-XML doesn't do validation or other types of processing
|
|
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
|
|
specification.
|
|
.SH USING MINI-XML
|
|
Mini-XML provides a single header file which you include:
|
|
.nf
|
|
|
|
#include <mxml.h>
|
|
.fi
|
|
.PP
|
|
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".
|
|
.PP
|
|
You load an XML file using the "mxmlLoadFile()" function:
|
|
.nf
|
|
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "r");
|
|
tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
|
|
fclose(fp);
|
|
.fi
|
|
.PP
|
|
Similarly, you save an XML file using the "mxmlSaveFile()"
|
|
function:
|
|
.nf
|
|
|
|
FILE *fp;
|
|
mxml_node_t *tree;
|
|
|
|
fp = fopen("filename.xml", "w");
|
|
mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
|
|
fclose(fp);
|
|
.fi
|
|
.PP
|
|
The "mxmlLoadString()", "mxmlSaveAllocString()", and
|
|
"mxmlSaveString()" functions load XML node trees from and save
|
|
XML node trees to strings:
|
|
.nf
|
|
|
|
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);
|
|
.fi
|
|
.PP
|
|
You can find a named element/node using the "mxmlFindElement()"
|
|
function:
|
|
.nf
|
|
|
|
mxml_node_t *node = mxmlFindElement(tree, tree, "name",
|
|
"attr", "value",
|
|
MXML_DESCEND);
|
|
.fi
|
|
.PP
|
|
The "name", "attr", and "value" arguments can be passed as
|
|
NULL to act as wildcards, e.g.:
|
|
.nf
|
|
|
|
/* 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);
|
|
.fi
|
|
.PP
|
|
You can also iterate with the same function:
|
|
.nf
|
|
|
|
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 ...
|
|
}
|
|
.fi
|
|
.PP
|
|
To find the value of a specific node in the tree, use the "mxmlFindPath()"
|
|
function:
|
|
.nf
|
|
|
|
mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
|
|
.fi
|
|
.PP
|
|
The "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and "mxmlGetText()"
|
|
functions retrieve the value from a node:
|
|
.nf
|
|
|
|
mxml_node_t *node;
|
|
|
|
long intvalue = mxmlGetInteger(node);
|
|
|
|
const char *opaquevalue = mxmlGetOpaque(node);
|
|
|
|
double realvalue = mxmlGetReal(node);
|
|
|
|
bool whitespacevalue;
|
|
const char *textvalue = mxmlGetText(node, &whitespacevalue);
|
|
.fi
|
|
.PP
|
|
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:
|
|
.nf
|
|
|
|
mxmlDelete(tree);
|
|
.fi
|
|
.SH ENUMERATIONS
|
|
.SS mxml_add_e
|
|
\fImxmlAdd\fR add values
|
|
.TP 5
|
|
MXML_ADD_AFTER
|
|
.br
|
|
Add node after specified node
|
|
.TP 5
|
|
MXML_ADD_BEFORE
|
|
.br
|
|
Add node before specified node
|
|
.SS mxml_descend_e
|
|
\fImxmlFindElement\fR, \fImxmlWalkNext\fR, and \fImxmlWalkPrev\fR descend values
|
|
.TP 5
|
|
MXML_DESCEND_ALL
|
|
.br
|
|
Descend when finding/walking
|
|
.TP 5
|
|
MXML_DESCEND_FIRST
|
|
.br
|
|
Descend for first find
|
|
.TP 5
|
|
MXML_DESCEND_NONE
|
|
.br
|
|
Don't descend when finding/walking
|
|
.SS mxml_sax_event_e
|
|
SAX event type.
|
|
.TP 5
|
|
MXML_SAX_EVENT_CDATA
|
|
.br
|
|
CDATA node
|
|
.TP 5
|
|
MXML_SAX_EVENT_COMMENT
|
|
.br
|
|
Comment node
|
|
.TP 5
|
|
MXML_SAX_EVENT_DATA
|
|
.br
|
|
Data node
|
|
.TP 5
|
|
MXML_SAX_EVENT_DECLARATION
|
|
.br
|
|
Declaration node
|
|
.TP 5
|
|
MXML_SAX_EVENT_DIRECTIVE
|
|
.br
|
|
Processing instruction node
|
|
.TP 5
|
|
MXML_SAX_EVENT_ELEMENT_CLOSE
|
|
.br
|
|
Element closed
|
|
.TP 5
|
|
MXML_SAX_EVENT_ELEMENT_OPEN
|
|
.br
|
|
Element opened
|
|
.SS mxml_type_e
|
|
The XML node type.
|
|
.TP 5
|
|
MXML_TYPE_CDATA
|
|
.br
|
|
CDATA value ("
|
|
.URL [CDATA[...]] [CDATA[...]]
|
|
")
|
|
.TP 5
|
|
MXML_TYPE_COMMENT
|
|
.br
|
|
Comment ("
|
|
.URL !--...-- !--...--
|
|
")
|
|
.TP 5
|
|
MXML_TYPE_CUSTOM
|
|
.br
|
|
Custom data
|
|
.TP 5
|
|
MXML_TYPE_DECLARATION
|
|
.br
|
|
Declaration ("
|
|
.URL !... !...
|
|
")
|
|
.TP 5
|
|
MXML_TYPE_DIRECTIVE
|
|
.br
|
|
Processing instruction ("
|
|
.URL ?...? ?...?
|
|
")
|
|
.TP 5
|
|
MXML_TYPE_ELEMENT
|
|
.br
|
|
XML element with attributes
|
|
.TP 5
|
|
MXML_TYPE_IGNORE
|
|
.br
|
|
Ignore/throw away node
|
|
.TP 5
|
|
MXML_TYPE_INTEGER
|
|
.br
|
|
Integer value
|
|
.TP 5
|
|
MXML_TYPE_OPAQUE
|
|
.br
|
|
Opaque string
|
|
.TP 5
|
|
MXML_TYPE_REAL
|
|
.br
|
|
Real value
|
|
.TP 5
|
|
MXML_TYPE_TEXT
|
|
.br
|
|
Text fragment
|
|
.SS mxml_ws_e
|
|
Whitespace periods
|
|
.TP 5
|
|
MXML_WS_AFTER_CLOSE
|
|
.br
|
|
Callback for after close tag
|
|
.TP 5
|
|
MXML_WS_AFTER_OPEN
|
|
.br
|
|
Callback for after open tag
|
|
.TP 5
|
|
MXML_WS_BEFORE_CLOSE
|
|
.br
|
|
Callback for before close tag
|
|
.TP 5
|
|
MXML_WS_BEFORE_OPEN
|
|
.br
|
|
Callback for before open tag
|
|
.SH FUNCTIONS
|
|
.SS mxmlAdd
|
|
Add a node to a tree.
|
|
.PP
|
|
.nf
|
|
void mxmlAdd (
|
|
mxml_node_t *parent,
|
|
mxml_add_t add,
|
|
mxml_node_t *child,
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function adds the specified node \fBnode\fR to the parent. If the \fBchild\fR
|
|
argument is not \fBNULL\fR, the new node is added before or after the specified
|
|
child depending on the value of the \fBadd\fR argument. If the \fBchild\fR argument
|
|
is \fBNULL\fR, the new node is placed at the beginning of the child list
|
|
(\fBMXML_ADD_BEFORE\fR) or at the end of the child list (\fBMXML_ADD_AFTER\fR).
|
|
.SS mxmlDelete
|
|
Delete a node and all of its children.
|
|
.PP
|
|
.nf
|
|
void mxmlDelete (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function deletes the node \fBnode\fR and all of its children. If the
|
|
specified node has a parent, this function first removes the node from its
|
|
parent using the \fImxmlRemove\fR function.
|
|
.SS mxmlElementClearAttr
|
|
Remove an attribute from an element.
|
|
.PP
|
|
.nf
|
|
void mxmlElementClearAttr (
|
|
mxml_node_t *node,
|
|
const char *name
|
|
);
|
|
.fi
|
|
.PP
|
|
This function removes the attribute \fBname\fR from the element \fBnode\fR.
|
|
.SS mxmlElementGetAttr
|
|
Get the value of an attribute.
|
|
.PP
|
|
.nf
|
|
const char * mxmlElementGetAttr (
|
|
mxml_node_t *node,
|
|
const char *name
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the value for the attribute \fBname\fR from the element
|
|
\fBnode\fR. \fBNULL\fR is returned if the node is not an element or the named
|
|
attribute does not exist.
|
|
.SS mxmlElementGetAttrByIndex
|
|
Get an attribute by index.
|
|
.PP
|
|
.nf
|
|
const char * mxmlElementGetAttrByIndex (
|
|
mxml_node_t *node,
|
|
size_t idx,
|
|
const char **name
|
|
);
|
|
.fi
|
|
.PP
|
|
This function returned the Nth (\fBidx\fR) attribute for element \fBnode\fR. The
|
|
attribute name is optionallly returned in the \fBname\fR argument. \fBNULL\fR is
|
|
returned if node is not an element or the specified index is out of range.
|
|
.SS mxmlElementGetAttrCount
|
|
Get the number of element attributes.
|
|
.PP
|
|
.nf
|
|
size_t mxmlElementGetAttrCount (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function returns the number of attributes for the element \fBnode\fR. \fB0\fR
|
|
is returned if the node is not an element or there are no attributes for the
|
|
element.
|
|
.SS mxmlElementSetAttr
|
|
Set an attribute for an element.
|
|
.PP
|
|
.nf
|
|
void mxmlElementSetAttr (
|
|
mxml_node_t *node,
|
|
const char *name,
|
|
const char *value
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets attribute \fBname\fR to the string \fBvalue\fR for the element
|
|
\fBnode\fR. If the named attribute already exists, the value of the attribute
|
|
is replaced by the new string value. The string value is copied.
|
|
.SS mxmlElementSetAttrf
|
|
Set an attribute with a formatted value.
|
|
.PP
|
|
.nf
|
|
void mxmlElementSetAttrf (
|
|
mxml_node_t *node,
|
|
const char *name,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets attribute \fBname\fR to the formatted value of \fBformat\fR for
|
|
the element \fBnode\fR. If the named attribute already exists, the value of the
|
|
attribute is replaced by the new formatted string value.
|
|
.SS mxmlFindElement
|
|
Find the named element.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlFindElement (
|
|
mxml_node_t *node,
|
|
mxml_node_t *top,
|
|
const char *element,
|
|
const char *attr,
|
|
const char *value,
|
|
mxml_descend_t descend
|
|
);
|
|
.fi
|
|
.PP
|
|
This function finds the named element \fBelement\fR in XML tree \fBtop\fR starting at
|
|
node \fBnode\fR. The search is constrained by element name \fBelement\fR, attribute
|
|
name \fBattr\fR, and attribute value \fBvalue\fR - \fBNULL\fR names or values are treated
|
|
as wildcards, so different kinds of searches can be implemented by looking
|
|
for all elements of a given name or all elements with a specific attribute.
|
|
.PP
|
|
The \fBdescend\fR argument determines whether the search descends into child
|
|
nodes; normally you will use \fBMXML_DESCEND_FIRST\fR for the initial search and
|
|
\fBMXML_DESCEND_NONE\fR to find additional direct descendents of the node.
|
|
.SS mxmlFindPath
|
|
Find a node with the given path.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlFindPath (
|
|
mxml_node_t *top,
|
|
const char *path
|
|
);
|
|
.fi
|
|
.PP
|
|
This function finds a node in XML tree \fBtop\fR using a slash-separated list of
|
|
element names in \fBpath\fR. The name "\fI" is considered a wildcard for one or
|
|
more levels of elements, for example, "foo/one/two", "bar/two/one", "\fR/one",
|
|
and so forth.
|
|
.PP
|
|
The first child node of the found node is returned if the given node has
|
|
children and the first child is a value node.
|
|
.SS mxmlGetCDATA
|
|
Get the value for a CDATA node.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetCDATA (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string value of a CDATA node. \fBNULL\fR is returned if
|
|
the node is not a CDATA element.
|
|
.SS mxmlGetComment
|
|
Get the value for a comment node.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetComment (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string value of a comment node. \fBNULL\fR is returned
|
|
if the node is not a comment.
|
|
.SS mxmlGetCustom
|
|
Get the value for a custom node.
|
|
.PP
|
|
.nf
|
|
const void * mxmlGetCustom (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the binary value of a custom node. \fBNULL\fR is returned if
|
|
the node (or its first child) is not a custom value node.
|
|
.SS mxmlGetDeclaration
|
|
Get the value for a declaration node.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetDeclaration (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string value of a declaraction node. \fBNULL\fR is
|
|
returned if the node is not a declaration.
|
|
.SS mxmlGetDirective
|
|
Get the value for a processing instruction node.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetDirective (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string value of a processing instruction. \fBNULL\fR is
|
|
returned if the node is not a processing instruction.
|
|
.SS mxmlGetElement
|
|
Get the name for an element node.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetElement (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the name of an element node. \fBNULL\fR is returned if the
|
|
node is not an element node.
|
|
.SS mxmlGetFirstChild
|
|
Get the first child of a node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlGetFirstChild (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the first child of a node. \fBNULL\fR is returned if the node
|
|
has no children.
|
|
.SS mxmlGetInteger
|
|
Get the integer value from the specified node or its
|
|
first child.
|
|
.PP
|
|
.nf
|
|
long mxmlGetInteger (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the value of an integer node. \fB0\fR is returned if the node
|
|
(or its first child) is not an integer value node.
|
|
.SS mxmlGetLastChild
|
|
Get the last child of a node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlGetLastChild (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the last child of a node. \fBNULL\fR is returned if the node
|
|
has no children.
|
|
.SS mxmlGetNextSibling
|
|
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlGetNextSibling (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.SS mxmlGetOpaque
|
|
Get an opaque string value for a node or its first child.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetOpaque (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string value of an opaque node. \fBNULL\fR is returned if
|
|
the node (or its first child) is not an opaque value node.
|
|
.SS mxmlGetParent
|
|
Get the parent node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlGetParent (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the parent of a node. \fBNULL\fR is returned for a root node.
|
|
.SS mxmlGetPrevSibling
|
|
Get the previous node for the current parent.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlGetPrevSibling (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the previous node for the current parent. \fBNULL\fR is
|
|
returned if this is the first child for the current parent.
|
|
.SS mxmlGetReal
|
|
Get the real value for a node or its first child.
|
|
.PP
|
|
.nf
|
|
double mxmlGetReal (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the value of a real value node. \fB0.0\fR is returned if the
|
|
node (or its first child) is not a real value node.
|
|
.SS mxmlGetRefCount
|
|
Get the current reference (use) count for a node.
|
|
.PP
|
|
.nf
|
|
size_t mxmlGetRefCount (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
The initial reference count of new nodes is 1. Use the \fImxmlRetain\fR
|
|
and \fImxmlRelease\fR functions to increment and decrement a node's
|
|
reference count.
|
|
.SS mxmlGetText
|
|
Get the text value for a node or its first child.
|
|
.PP
|
|
.nf
|
|
const char * mxmlGetText (
|
|
mxml_node_t *node,
|
|
bool *whitespace
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the string and whitespace values of a text node. \fBNULL\fR
|
|
and \fBfalse\fR are returned if the node (or its first child) is not a text node.
|
|
The \fBwhitespace\fR argument can be \fBNULL\fR if you don't want to know the
|
|
whitespace value.
|
|
.PP
|
|
Note: Text nodes consist of whitespace-delimited words. You will only get
|
|
single words of text when reading an XML file with \fBMXML_TYPE_TEXT\fR nodes.
|
|
If you want the entire string between elements in the XML file, you MUST read
|
|
the XML file with \fBMXML_TYPE_OPAQUE\fR nodes and get the resulting strings
|
|
using the \fImxmlGetOpaque\fR function instead.
|
|
.SS mxmlGetType
|
|
Get the node type.
|
|
.PP
|
|
.nf
|
|
mxml_type_t mxmlGetType (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the type of \fBnode\fR. \fBMXML_TYPE_IGNORE\fR is returned if
|
|
\fBnode\fR is \fBNULL\fR.
|
|
.SS mxmlGetUserData
|
|
Get the user data pointer for a node.
|
|
.PP
|
|
.nf
|
|
void * mxmlGetUserData (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function gets the user data pointer associated with \fBnode\fR.
|
|
.SS mxmlIndexDelete
|
|
Delete an index.
|
|
.PP
|
|
.nf
|
|
void mxmlIndexDelete (
|
|
mxml_index_t *ind
|
|
);
|
|
.fi
|
|
.SS mxmlIndexEnum
|
|
Return the next node in the index.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlIndexEnum (
|
|
mxml_index_t *ind
|
|
);
|
|
.fi
|
|
.PP
|
|
This function returns the next node in index \fBind\fR.
|
|
.PP
|
|
You should call \fImxmlIndexReset\fR prior to using this function to get
|
|
the first node in the index. Nodes are returned in the sorted order of the
|
|
index.
|
|
.SS mxmlIndexFind
|
|
Find the next matching node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlIndexFind (
|
|
mxml_index_t *ind,
|
|
const char *element,
|
|
const char *value
|
|
);
|
|
.fi
|
|
.PP
|
|
This function finds the next matching node in index \fBind\fR.
|
|
.PP
|
|
You should call \fImxmlIndexReset\fR prior to using this function for
|
|
the first time with a particular set of \fBelement\fR and \fBvalue\fR
|
|
strings. Passing \fBNULL\fR for both \fBelement\fR and \fBvalue\fR is equivalent
|
|
to calling \fImxmlIndexEnum\fR.
|
|
.SS mxmlIndexGetCount
|
|
Get the number of nodes in an index.
|
|
.PP
|
|
.nf
|
|
size_t mxmlIndexGetCount (
|
|
mxml_index_t *ind
|
|
);
|
|
.fi
|
|
.SS mxmlIndexNew
|
|
Create a new index.
|
|
.PP
|
|
.nf
|
|
mxml_index_t * mxmlIndexNew (
|
|
mxml_node_t *node,
|
|
const char *element,
|
|
const char *attr
|
|
);
|
|
.fi
|
|
.PP
|
|
This function creates a new index for XML tree \fBnode\fR.
|
|
.PP
|
|
The index will contain all nodes that contain the named element and/or
|
|
attribute. If both \fBelement\fR and \fBattr\fR are \fBNULL\fR, then the index will
|
|
contain a sorted list of the elements in the node tree. Nodes are
|
|
sorted by element name and optionally by attribute value if the \fBattr\fR
|
|
argument is not \fBNULL\fR.
|
|
.SS mxmlIndexReset
|
|
Reset the enumeration/find pointer in the index and
|
|
return the first node in the index.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlIndexReset (
|
|
mxml_index_t *ind
|
|
);
|
|
.fi
|
|
.PP
|
|
This function resets the enumeration/find pointer in index \fBind\fR and should
|
|
be called prior to using \fImxmlIndexEnum\fR or \fImxmlIndexFind\fR for the
|
|
first time.
|
|
.SS mxmlLoadFd
|
|
Load a file descriptor into an XML node tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlLoadFd (
|
|
mxml_node_t *top,
|
|
mxml_options_t *options,
|
|
int fd
|
|
);
|
|
.fi
|
|
.PP
|
|
This function loads the file descriptor \fBfd\fR into an XML node tree. The
|
|
nodes in the specified file are added to the specified node \fBtop\fR - if \fBNULL\fR
|
|
the XML file MUST be well-formed with a single parent processing instruction
|
|
node like \fB<?xml version="1.0"?>\fR at the start of the file.
|
|
.PP
|
|
Load options are provides via the \fBoptions\fR argument. If \fBNULL\fR, all values
|
|
will be loaded into \fBMXML_TYPE_TEXT\fR nodes. Use the \fImxmlOptionsNew\fR
|
|
function to create options when loading XML data.
|
|
.SS mxmlLoadFile
|
|
Load a file into an XML node tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlLoadFile (
|
|
mxml_node_t *top,
|
|
mxml_options_t *options,
|
|
FILE *fp
|
|
);
|
|
.fi
|
|
.PP
|
|
This function loads the \fBFILE\fR pointer \fBfp\fR into an XML node tree. The
|
|
nodes in the specified file are added to the specified node \fBtop\fR - if \fBNULL\fR
|
|
the XML file MUST be well-formed with a single parent processing instruction
|
|
node like \fB<?xml version="1.0"?>\fR at the start of the file.
|
|
.PP
|
|
Load options are provides via the \fBoptions\fR argument. If \fBNULL\fR, all values
|
|
will be loaded into \fBMXML_TYPE_TEXT\fR nodes. Use the \fImxmlOptionsNew\fR
|
|
function to create options when loading XML data.
|
|
.SS mxmlLoadFilename
|
|
Load a file into an XML node tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlLoadFilename (
|
|
mxml_node_t *top,
|
|
mxml_options_t *options,
|
|
const char *filename
|
|
);
|
|
.fi
|
|
.PP
|
|
This function loads the named file \fBfilename\fR into an XML node tree. The
|
|
nodes in the specified file are added to the specified node \fBtop\fR - if \fBNULL\fR
|
|
the XML file MUST be well-formed with a single parent processing instruction
|
|
node like \fB<?xml version="1.0"?>\fR at the start of the file.
|
|
.PP
|
|
Load options are provides via the \fBoptions\fR argument. If \fBNULL\fR, all values
|
|
will be loaded into \fBMXML_TYPE_TEXT\fR nodes. Use the \fImxmlOptionsNew\fR
|
|
function to create options when loading XML data.
|
|
.SS mxmlLoadIO
|
|
Load an XML node tree using a read callback.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlLoadIO (
|
|
mxml_node_t *top,
|
|
mxml_options_t *options,
|
|
mxml_io_cb_t io_cb,
|
|
void *io_cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function loads data into an XML node tree using a read callback. The
|
|
nodes in the specified file are added to the specified node \fBtop\fR - if \fBNULL\fR
|
|
the XML file MUST be well-formed with a single parent processing instruction
|
|
node like \fB<?xml version="1.0"?>\fR at the start of the file.
|
|
.PP
|
|
Load options are provides via the \fBoptions\fR argument. If \fBNULL\fR, all values
|
|
will be loaded into \fBMXML_TYPE_TEXT\fR nodes. Use the \fImxmlOptionsNew\fR
|
|
function to create options when loading XML data.
|
|
.PP
|
|
The read callback function \fBio_cb\fR is called to read a number of bytes from
|
|
the source. The callback data pointer \fBio_cbdata\fR is passed to the read
|
|
callback with a pointer to a buffer and the maximum number of bytes to read,
|
|
for example:
|
|
.PP
|
|
\fB`\fRc
|
|
size_t my_io_cb(void \fIcbdata, void \fRbuffer, size_t bytes)
|
|
{
|
|
... copy up to "bytes" bytes into buffer ...
|
|
... return the number of bytes "read" or 0 on error ...
|
|
}
|
|
\fB`\fR
|
|
.SS mxmlLoadString
|
|
Load a string into an XML node tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlLoadString (
|
|
mxml_node_t *top,
|
|
mxml_options_t *options,
|
|
const char *s
|
|
);
|
|
.fi
|
|
.PP
|
|
This function loads the string into an XML node tree. The nodes in the
|
|
specified file are added to the specified node \fBtop\fR - if \fBNULL\fR the XML file
|
|
MUST be well-formed with a single parent processing instruction node like
|
|
\fB<?xml version="1.0"?>\fR at the start of the file.
|
|
.PP
|
|
Load options are provides via the \fBoptions\fR argument. If \fBNULL\fR, all values
|
|
will be loaded into \fBMXML_TYPE_TEXT\fR nodes. Use the \fImxmlOptionsNew\fR
|
|
function to create options when loading XML data.
|
|
.SS mxmlNewCDATA
|
|
Create a new CDATA node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewCDATA (
|
|
mxml_node_t *parent,
|
|
const char *data
|
|
);
|
|
.fi
|
|
.PP
|
|
The new CDATA node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
CDATA node has no parent. The data string must be nul-terminated and
|
|
is copied into the new node. CDATA nodes currently use the
|
|
\fBMXML_TYPE_ELEMENT\fR type.
|
|
.SS mxmlNewCDATAf
|
|
Create a new formatted CDATA node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewCDATAf (
|
|
mxml_node_t *parent,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new CDATA node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The format string must be
|
|
nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewComment
|
|
Create a new comment node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewComment (
|
|
mxml_node_t *parent,
|
|
const char *comment
|
|
);
|
|
.fi
|
|
.PP
|
|
The new comment node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
comment node has no parent. The comment string must be nul-terminated and
|
|
is copied into the new node.
|
|
.SS mxmlNewCommentf
|
|
Create a new formatted comment string node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewCommentf (
|
|
mxml_node_t *parent,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new comment string node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The format string must be
|
|
nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewCustom
|
|
Create a new custom data node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewCustom (
|
|
mxml_node_t *parent,
|
|
void *data,
|
|
mxml_custfree_cb_t free_cb,
|
|
void *free_cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
The new custom node is added to the end of the specified parent's child
|
|
list. The \fBfree_cb\fR argument specifies a function to call to free the custom
|
|
data when the node is deleted.
|
|
.SS mxmlNewDeclaration
|
|
Create a new declaraction node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewDeclaration (
|
|
mxml_node_t *parent,
|
|
const char *declaration
|
|
);
|
|
.fi
|
|
.PP
|
|
The new declaration node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
declaration node has no parent. The declaration string must be nul-
|
|
terminated and is copied into the new node.
|
|
.SS mxmlNewDeclarationf
|
|
Create a new formatted declaration node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewDeclarationf (
|
|
mxml_node_t *parent,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new declaration node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The format string must be
|
|
nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewDirective
|
|
Create a new processing instruction node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewDirective (
|
|
mxml_node_t *parent,
|
|
const char *directive
|
|
);
|
|
.fi
|
|
.PP
|
|
The new processing instruction node is added to the end of the specified
|
|
parent's child list. The constant \fBMXML_NO_PARENT\fR can be used to specify
|
|
that the new processing instruction node has no parent. The data string must
|
|
be nul-terminated and is copied into the new node.
|
|
.SS mxmlNewDirectivef
|
|
Create a new formatted processing instruction node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewDirectivef (
|
|
mxml_node_t *parent,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new processing instruction node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The format string must be
|
|
nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewElement
|
|
Create a new element node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewElement (
|
|
mxml_node_t *parent,
|
|
const char *name
|
|
);
|
|
.fi
|
|
.PP
|
|
The new element node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
element node has no parent.
|
|
.SS mxmlNewInteger
|
|
Create a new integer node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewInteger (
|
|
mxml_node_t *parent,
|
|
long integer
|
|
);
|
|
.fi
|
|
.PP
|
|
The new integer node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
integer node has no parent.
|
|
.SS mxmlNewOpaque
|
|
Create a new opaque string.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewOpaque (
|
|
mxml_node_t *parent,
|
|
const char *opaque
|
|
);
|
|
.fi
|
|
.PP
|
|
The new opaque string node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The opaque string must be nul-
|
|
terminated and is copied into the new node.
|
|
.SS mxmlNewOpaquef
|
|
Create a new formatted opaque string node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewOpaquef (
|
|
mxml_node_t *parent,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new opaque string node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new opaque string node has no parent. The format string must be
|
|
nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewReal
|
|
Create a new real number node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewReal (
|
|
mxml_node_t *parent,
|
|
double real
|
|
);
|
|
.fi
|
|
.PP
|
|
The new real number node is added to the end of the specified parent's
|
|
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
|
the new real number node has no parent.
|
|
.SS mxmlNewText
|
|
Create a new text fragment node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewText (
|
|
mxml_node_t *parent,
|
|
bool whitespace,
|
|
const char *string
|
|
);
|
|
.fi
|
|
.PP
|
|
The new text node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
text node has no parent. The whitespace parameter is used to specify
|
|
whether leading whitespace is present before the node. The text
|
|
string must be nul-terminated and is copied into the new node.
|
|
.SS mxmlNewTextf
|
|
Create a new formatted text fragment node.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewTextf (
|
|
mxml_node_t *parent,
|
|
bool whitespace,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
The new text node is added to the end of the specified parent's child
|
|
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
|
text node has no parent. The whitespace parameter is used to specify
|
|
whether leading whitespace is present before the node. The format
|
|
string must be nul-terminated and is formatted into the new node.
|
|
.SS mxmlNewXML
|
|
Create a new XML document tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlNewXML (
|
|
const char *version
|
|
);
|
|
.fi
|
|
.PP
|
|
The "version" argument specifies the version number to put in the
|
|
?xml directive node. If \fBNULL\fR, version "1.0" is assumed.
|
|
.SS mxmlOptionsDelete
|
|
Free load/save options.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsDelete (
|
|
mxml_options_t *options
|
|
);
|
|
.fi
|
|
.SS mxmlOptionsNew
|
|
Allocate load/save options.
|
|
.PP
|
|
.nf
|
|
mxml_options_t * mxmlOptionsNew (void);
|
|
.fi
|
|
.PP
|
|
This function creates a new set of load/save options to use with the
|
|
\fImxmlLoadFd\fR, \fImxmlLoadFile\fR, \fImxmlLoadFilename\fR,
|
|
\fImxmlLoadIO\fR, \fImxmlLoadString\fR, \fImxmlSaveAllocString\fR,
|
|
\fImxmlSaveFd\fR, \fImxmlSaveFile\fR, \fImxmlSaveFilename\fR,
|
|
\fImxmlSaveIO\fR, and \fImxmlSaveString\fR functions. Options can be
|
|
reused for multiple calls to these functions and should be freed using the
|
|
\fImxmlOptionsDelete\fR function.
|
|
.PP
|
|
The default load/save options load values using the constant type
|
|
\fBMXML_TYPE_TEXT\fR and save XML data with a wrap margin of 72 columns.
|
|
The various \fBmxmlOptionsSet\fR functions are used to change the defaults,
|
|
for example:
|
|
.PP
|
|
\fB`\fRc
|
|
mxml_options_t \fIoptions = mxmlOptionsNew();
|
|
|
|
/\fR Load values as opaque strings */
|
|
mxmlOptionsSetTypeValue(options, MXML_TYPE_OPAQUE);
|
|
.nf
|
|
|
|
Note: The most common programming error when using the Mini-XML library is
|
|
to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
|
|
inline text as a series of whitespace-delimited words, instead of using the
|
|
`MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
|
|
(including whitespace).
|
|
.fi
|
|
|
|
.SS mxmlOptionsSetCustomCallbacks
|
|
Set the custom data callbacks.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetCustomCallbacks (
|
|
mxml_options_t *options,
|
|
mxml_custload_cb_t load_cb,
|
|
mxml_custsave_cb_t save_cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the callbacks that are used for loading and saving custom
|
|
data types. The load callback \fBload_cb\fR accepts the callback data pointer
|
|
\fBcbdata\fR, a node pointer, and a data string and returns \fBtrue\fR on success and
|
|
\fBfalse\fR on error, for example:
|
|
.PP
|
|
\fB`\fRc
|
|
typedef struct
|
|
{
|
|
unsigned year, /\fI Year \fR/
|
|
month, /\fI Month \fR/
|
|
day, /\fI Day \fR/
|
|
hour, /\fI Hour \fR/
|
|
minute, /\fI Minute \fR/
|
|
second; /\fI Second \fR/
|
|
time_t unix; /\fI UNIX time \fR/
|
|
} iso_date_time_t;
|
|
.PP
|
|
void
|
|
my_custom_free_cb(void \fIcbdata, void \fRdata)
|
|
{
|
|
free(data);
|
|
}
|
|
.PP
|
|
bool
|
|
my_custom_load_cb(void \fIcbdata, mxml_node_t \fRnode, const char \fIdata)
|
|
{
|
|
iso_date_time_t \fRdt;
|
|
struct tm tmdata;
|
|
.PP
|
|
/\fI Allocate custom data structure ... \fR/
|
|
dt = calloc(1, sizeof(iso_date_time_t));
|
|
.PP
|
|
/\fI Parse the data string... \fR/
|
|
if (sscanf(data, "%u-%u-%uT%u:%u:%uZ", &(dt->year), &(dt->month),
|
|
&(dt->day), &(dt->hour), &(dt->minute), &(dt->second)) != 6)
|
|
{
|
|
/\fI Unable to parse date and time numbers... \fR/
|
|
free(dt);
|
|
return (false);
|
|
}
|
|
.PP
|
|
/\fI Range check values... \fR/
|
|
if (dt->month
|
|
.URL 1 || dt- 1 || dt-
|
|
month > 12 || dt->day
|
|
.URL 1 || dt- 1 || dt-
|
|
day > 31 ||
|
|
dt->hour
|
|
.URL 0 || dt- 0 || dt-
|
|
hour > 23 || dt->minute
|
|
.URL 0 || dt- 0 || dt-
|
|
minute > 59 ||
|
|
dt->second
|
|
.URL 0 || dt- 0 || dt-
|
|
second > 60)
|
|
{
|
|
/\fI Date information is out of range... \fR/
|
|
free(dt);
|
|
return (false);
|
|
}
|
|
.PP
|
|
/\fI Convert ISO time to UNIX time in seconds... \fR/
|
|
tmdata.tm_year = dt->year - 1900;
|
|
tmdata.tm_mon = dt->month - 1;
|
|
tmdata.tm_day = dt->day;
|
|
tmdata.tm_hour = dt->hour;
|
|
tmdata.tm_min = dt->minute;
|
|
tmdata.tm_sec = dt->second;
|
|
.PP
|
|
dt->unix = gmtime(&tmdata);
|
|
.PP
|
|
/\fI Set custom data and free function... \fR/
|
|
mxmlSetCustom(node, data, my_custom_free, /\fIcbdata\fR/NULL);
|
|
.PP
|
|
/\fI Return with no errors... \fR/
|
|
return (true);
|
|
}
|
|
.nf
|
|
|
|
The save callback `save_cb` accepts the callback data pointer `cbdata` and a
|
|
node pointer and returns a malloc'd string on success and `NULL` on error,
|
|
for example:
|
|
|
|
```c
|
|
char *
|
|
my_custom_save_cb(void *cbdata, mxml_node_t *node)
|
|
{
|
|
char data[255];
|
|
iso_date_time_t *dt;
|
|
|
|
/* Get the custom data structure */
|
|
dt = (iso_date_time_t *)mxmlGetCustom(node);
|
|
|
|
/* Generate string version of the date/time... */
|
|
snprintf(data, sizeof(data), "%04u-%02u-%02uT%02u:%02u:%02uZ",
|
|
dt->year, dt->month, dt->day, dt->hour, dt->minute, dt->second);
|
|
|
|
/* Duplicate the string and return... */
|
|
return (strdup(data));
|
|
}
|
|
|
|
.fi
|
|
|
|
.SS mxmlOptionsSetEntityCallback
|
|
Set the entity lookup callback to use when loading XML data.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetEntityCallback (
|
|
mxml_options_t *options,
|
|
mxml_entity_cb_t cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the callback that is used to lookup named XML character
|
|
entities when loading XML data. The callback function \fBcb\fR accepts the
|
|
callback data pointer \fBcbdata\fR and the entity name. The function returns a
|
|
Unicode character value or \fB-1\fR if the entity is not known. For example, the
|
|
following entity callback supports the "euro" entity:
|
|
.PP
|
|
\fB`\fRc
|
|
int my_entity_cb(void \fIcbdata, const char \fRname)
|
|
{
|
|
if (!strcmp(name, "euro"))
|
|
return (0x20ac);
|
|
else
|
|
return (-1);
|
|
}
|
|
.nf
|
|
|
|
Mini-XML automatically supports the "amp", "gt", "lt", and "quot" character
|
|
entities which are required by the base XML specification.
|
|
.fi
|
|
char *data)
|
|
{
|
|
iso_date_time_t
|
|
.SS mxmlOptionsSetErrorCallback
|
|
Set the error message callback.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetErrorCallback (
|
|
mxml_options_t *options,
|
|
mxml_error_cb_t cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets a function to use when reporting errors. The callback
|
|
\fBcb\fR accepts the data pointer \fBcbdata\fR and a string pointer containing the
|
|
error message:
|
|
.PP
|
|
\fB`\fRc
|
|
void my_error_cb(void \fIcbdata, const char \fRmessage)
|
|
{
|
|
fprintf(stderr, "myprogram: %sn", message);
|
|
}
|
|
.nf
|
|
|
|
The default error callback writes the error message to the `stderr` file.
|
|
.fi
|
|
ack supports the "euro" entity:
|
|
.PP
|
|
\fB`\fR
|
|
.SS mxmlOptionsSetSAXCallback
|
|
Set the SAX callback to use when reading XML data.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetSAXCallback (
|
|
mxml_options_t *options,
|
|
mxml_sax_cb_t cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets a SAX callback to use when reading XML data. The SAX
|
|
callback function \fBcb\fR and associated callback data \fBcbdata\fR are used to
|
|
enable the Simple API for XML streaming mode. The callback is called as the
|
|
XML node tree is parsed and receives the \fBcbdata\fR pointer, the \fBmxml_node_t\fR
|
|
pointer, and an event code. The function returns \fBtrue\fR to continue
|
|
processing or \fBfalse\fR to stop:
|
|
.PP
|
|
\fB`\fRc
|
|
bool
|
|
sax_cb(void \fIcbdata, mxml_node_t \fRnode,
|
|
mxml_sax_event_t event)
|
|
{
|
|
... do something ...
|
|
.PP
|
|
/\fI Continue processing... \fR/
|
|
return (true);
|
|
}
|
|
.nf
|
|
|
|
The event will be one of the following:
|
|
|
|
- `MXML_SAX_EVENT_CDATA`: CDATA was just read.
|
|
- `MXML_SAX_EVENT_COMMENT`: A comment was just read.
|
|
- `MXML_SAX_EVENT_DATA`: Data (integer, opaque, real, or text) was just read.
|
|
- `MXML_SAX_EVENT_DECLARATION`: A declaration was just read.
|
|
- `MXML_SAX_EVENT_DIRECTIVE`: A processing directive/instruction was just read.
|
|
- `MXML_SAX_EVENT_ELEMENT_CLOSE` - A close element was just read (`</element>`)
|
|
- `MXML_SAX_EVENT_ELEMENT_OPEN` - An open element was just read (`<element>`)
|
|
|
|
Elements are *released* after the close element is processed. All other nodes
|
|
are released after they are processed. The SAX callback can *retain* the node
|
|
using the [mxmlRetain](@@) function.
|
|
.fi
|
|
/* Date information is out of range...
|
|
.SS mxmlOptionsSetTypeCallback
|
|
Set the type callback for child/value nodes.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetTypeCallback (
|
|
mxml_options_t *options,
|
|
mxml_type_cb_t cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
The load callback function \fBcb\fR is called to obtain the node type child/value
|
|
nodes and receives the \fBcbdata\fR pointer and the \fBmxml_node_t\fR pointer, for
|
|
example:
|
|
.PP
|
|
\fB`\fRc
|
|
mxml_type_t
|
|
my_type_cb(void \fIcbdata, mxml_node_t \fRnode)
|
|
{
|
|
const char \fItype;
|
|
|
|
/\fR
|
|
\fI You can lookup attributes and/or use the element name,
|
|
\fR hierarchy, etc...
|
|
*/
|
|
.PP
|
|
type = mxmlElementGetAttr(node, "type");
|
|
if (type == NULL)
|
|
type = mxmlGetElement(node);
|
|
if (type == NULL)
|
|
type = "text";
|
|
.PP
|
|
if (!strcmp(type, "integer"))
|
|
return (MXML_TYPE_INTEGER);
|
|
else if (!strcmp(type, "opaque"))
|
|
return (MXML_TYPE_OPAQUE);
|
|
else if (!strcmp(type, "real"))
|
|
return (MXML_TYPE_REAL);
|
|
else
|
|
return (MXML_TYPE_TEXT);
|
|
}
|
|
\fB`\fR
|
|
.SS mxmlOptionsSetTypeValue
|
|
Set the type to use for all child/value nodes.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetTypeValue (
|
|
mxml_options_t *options,
|
|
mxml_type_t type
|
|
);
|
|
.fi
|
|
.PP
|
|
This functions sets a constant node type to use for all child/value nodes.
|
|
.SS mxmlOptionsSetWhitespaceCallback
|
|
Set the whitespace callback.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetWhitespaceCallback (
|
|
mxml_options_t *options,
|
|
mxml_ws_cb_t cb,
|
|
void *cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the whitespace callback that is used when saving XML data.
|
|
The callback function \fBcb\fR specifies a function that returns a whitespace
|
|
string or \fBNULL\fR before and after each element. The function receives the
|
|
callback data pointer \fBcbdata\fR, the \fBmxml_node_t\fR pointer, and a "when"
|
|
value indicating where the whitespace is being added, for example:
|
|
.PP
|
|
\fB`\fRc
|
|
const char \fImy_whitespace_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when)
|
|
{
|
|
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
|
|
return ("n");
|
|
else
|
|
return (NULL);
|
|
}
|
|
\fB`\fR
|
|
.SS mxmlOptionsSetWrapMargin
|
|
Set the wrap margin when saving XML data.
|
|
.PP
|
|
.nf
|
|
void mxmlOptionsSetWrapMargin (
|
|
mxml_options_t *options,
|
|
int column
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the wrap margin used when saving XML data. Wrapping is
|
|
disabled when \fBcolumn\fR is \fB0\fR.
|
|
.SS mxmlRelease
|
|
Release a node.
|
|
.PP
|
|
.nf
|
|
int mxmlRelease (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
When the reference count reaches zero, the node (and any children)
|
|
is deleted via \fImxmlDelete\fR.
|
|
.SS mxmlRemove
|
|
Remove a node from its parent.
|
|
.PP
|
|
.nf
|
|
void mxmlRemove (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.PP
|
|
This function does not free memory used by the node - use \fImxmlDelete\fR
|
|
for that. This function does nothing if the node has no parent.
|
|
.SS mxmlRetain
|
|
Retain a node.
|
|
.PP
|
|
.nf
|
|
int mxmlRetain (
|
|
mxml_node_t *node
|
|
);
|
|
.fi
|
|
.SS mxmlSaveAllocString
|
|
Save an XML tree to an allocated string.
|
|
.PP
|
|
.nf
|
|
char * mxmlSaveAllocString (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR to an allocated string. The string
|
|
should be freed using \fBfree\fR (or the string free callback set using
|
|
\fImxmlSetStringCallbacks\fR) when you are done with it.
|
|
.PP
|
|
\fBNULL\fR is returned if the node would produce an empty string or if the string
|
|
cannot be allocated.
|
|
.PP
|
|
Save options are provides via the \fBoptions\fR argument. If \fBNULL\fR, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
\fImxmlOptionsNew\fR function to create options for saving XML data.
|
|
.SS mxmlSaveFd
|
|
Save an XML tree to a file descriptor.
|
|
.PP
|
|
.nf
|
|
bool mxmlSaveFd (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options,
|
|
int fd
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR to a file descriptor.
|
|
.PP
|
|
Save options are provides via the \fBoptions\fR argument. If \fBNULL\fR, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
\fImxmlOptionsNew\fR function to create options for saving XML data.
|
|
.SS mxmlSaveFile
|
|
Save an XML tree to a file.
|
|
.PP
|
|
.nf
|
|
bool mxmlSaveFile (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options,
|
|
FILE *fp
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR to a stdio \fBFILE\fR.
|
|
.PP
|
|
Save options are provides via the \fBoptions\fR argument. If \fBNULL\fR, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
\fImxmlOptionsNew\fR function to create options for saving XML data.
|
|
.SS mxmlSaveFilename
|
|
Save an XML tree to a file.
|
|
.PP
|
|
.nf
|
|
bool mxmlSaveFilename (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options,
|
|
const char *filename
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR to a named file.
|
|
.PP
|
|
Save options are provides via the \fBoptions\fR argument. If \fBNULL\fR, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
\fImxmlOptionsNew\fR function to create options for saving XML data.
|
|
.SS mxmlSaveIO
|
|
Save an XML tree using a callback.
|
|
.PP
|
|
.nf
|
|
bool mxmlSaveIO (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options,
|
|
mxml_io_cb_t io_cb,
|
|
void *io_cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR using a write callback function
|
|
\fBio_cb\fR. The write callback is called with the callback data pointer
|
|
\fBio_cbdata\fR, a buffer pointer, and the number of bytes to write, for
|
|
example:
|
|
.PP
|
|
\fB`\fRc
|
|
size_t my_io_cb(void \fIcbdata, const void \fRbuffer, size_t bytes)
|
|
{
|
|
... write/copy bytes from buffer to the output ...
|
|
... return the number of bytes written/copied or 0 on error ...
|
|
}
|
|
.nf
|
|
|
|
Save options are provides via the `options` argument. If `NULL`, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
@link mxmlOptionsNew@ function to create options for saving XML data.
|
|
.fi
|
|
, "real"))
|
|
return (MXML_TYPE_REAL);
|
|
else
|
|
return (MXML_TYPE_TEXT);
|
|
}
|
|
\fB`\fR
|
|
.SS mxmlSaveString
|
|
Save an XML node tree to a string.
|
|
.PP
|
|
.nf
|
|
size_t mxmlSaveString (
|
|
mxml_node_t *node,
|
|
mxml_options_t *options,
|
|
char *buffer,
|
|
size_t bufsize
|
|
);
|
|
.fi
|
|
.PP
|
|
This function saves the XML tree \fBnode\fR to a fixed-size string buffer.
|
|
.PP
|
|
Save options are provides via the \fBoptions\fR argument. If \fBNULL\fR, the XML
|
|
output will be wrapped at column 72 with no additional whitespace. Use the
|
|
\fImxmlOptionsNew\fR function to create options for saving XML data.
|
|
.SS mxmlSetCDATA
|
|
Set the data for a CDATA node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetCDATA (
|
|
mxml_node_t *node,
|
|
const char *data
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the value string for a CDATA node. The node is not
|
|
changed if it (or its first child) is not a CDATA node.
|
|
.SS mxmlSetCDATAf
|
|
Set the data for a CDATA to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetCDATAf (
|
|
mxml_node_t *node,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string value of a CDATA node. The node is
|
|
not changed if it (or its first child) is not a CDATA node.
|
|
.SS mxmlSetComment
|
|
Set a comment to a literal string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetComment (
|
|
mxml_node_t *node,
|
|
const char *comment
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the string value of a comment node.
|
|
.SS mxmlSetCommentf
|
|
Set a comment to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetCommentf (
|
|
mxml_node_t *node,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string value of a comment node.
|
|
.SS mxmlSetCustom
|
|
Set the data and destructor of a custom data node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetCustom (
|
|
mxml_node_t *node,
|
|
void *data,
|
|
mxml_custfree_cb_t free_cb,
|
|
void *free_cbdata
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the data pointer \fBdata\fR and destructor callback
|
|
\fBdestroy_cb\fR of a custom data node. The node is not changed if it (or its
|
|
first child) is not a custom node.
|
|
.SS mxmlSetDeclaration
|
|
Set a declaration to a literal string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetDeclaration (
|
|
mxml_node_t *node,
|
|
const char *declaration
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the string value of a declaration node.
|
|
.SS mxmlSetDeclarationf
|
|
Set a declaration to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetDeclarationf (
|
|
mxml_node_t *node,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string value of a declaration node.
|
|
.SS mxmlSetDirective
|
|
Set a processing instruction to a literal string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetDirective (
|
|
mxml_node_t *node,
|
|
const char *directive
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the string value of a processing instruction node.
|
|
.SS mxmlSetDirectivef
|
|
Set a processing instruction to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetDirectivef (
|
|
mxml_node_t *node,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string value of a processing instruction
|
|
node.
|
|
.SS mxmlSetElement
|
|
Set the name of an element node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetElement (
|
|
mxml_node_t *node,
|
|
const char *name
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the name of an element node. The node is not changed if
|
|
it is not an element node.
|
|
.SS mxmlSetInteger
|
|
Set the value of an integer node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetInteger (
|
|
mxml_node_t *node,
|
|
long integer
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the value of an integer node. The node is not changed if
|
|
it (or its first child) is not an integer node.
|
|
.SS mxmlSetOpaque
|
|
Set the value of an opaque node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetOpaque (
|
|
mxml_node_t *node,
|
|
const char *opaque
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the string value of an opaque node. The node is not
|
|
changed if it (or its first child) is not an opaque node.
|
|
.SS mxmlSetOpaquef
|
|
Set the value of an opaque string node to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetOpaquef (
|
|
mxml_node_t *node,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string value of an opaque node. The node is
|
|
not changed if it (or its first child) is not an opaque node.
|
|
.SS mxmlSetReal
|
|
Set the value of a real value node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetReal (
|
|
mxml_node_t *node,
|
|
double real
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the value of a real value node. The node is not changed
|
|
if it (or its first child) is not a real value node.
|
|
.SS mxmlSetText
|
|
Set the value of a text node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetText (
|
|
mxml_node_t *node,
|
|
bool whitespace,
|
|
const char *string
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the string and whitespace values of a text node. The node
|
|
is not changed if it (or its first child) is not a text node.
|
|
.SS mxmlSetTextf
|
|
Set the value of a text node to a formatted string.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetTextf (
|
|
mxml_node_t *node,
|
|
bool whitespace,
|
|
const char *format,
|
|
...
|
|
);
|
|
.fi
|
|
.PP
|
|
This function sets the formatted string and whitespace values of a text node.
|
|
The node is not changed if it (or its first child) is not a text node.
|
|
.SS mxmlSetUserData
|
|
Set the user data pointer for a node.
|
|
.PP
|
|
.nf
|
|
bool mxmlSetUserData (
|
|
mxml_node_t *node,
|
|
void *data
|
|
);
|
|
.fi
|
|
.SS mxmlWalkNext
|
|
Walk to the next logical node in the tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlWalkNext (
|
|
mxml_node_t *node,
|
|
mxml_node_t *top,
|
|
mxml_descend_t descend
|
|
);
|
|
.fi
|
|
.PP
|
|
This function walks to the next logical node in the tree. The \fBdescend\fR
|
|
argument controls whether the first child is considered to be the next node.
|
|
The \fBtop\fR argument constrains the walk to that node's children.
|
|
.SS mxmlWalkPrev
|
|
Walk to the previous logical node in the tree.
|
|
.PP
|
|
.nf
|
|
mxml_node_t * mxmlWalkPrev (
|
|
mxml_node_t *node,
|
|
mxml_node_t *top,
|
|
mxml_descend_t descend
|
|
);
|
|
.fi
|
|
.PP
|
|
This function walks to the previous logical node in the tree. The \fBdescend\fR
|
|
argument controls whether the first child is considered to be the next node.
|
|
The \fBtop\fR argument constrains the walk to that node's children.
|
|
.SH TYPES
|
|
.SS mxml_add_t
|
|
\fImxmlAdd\fR add values
|
|
.PP
|
|
.nf
|
|
typedef enum mxml_add_e mxml_add_t;
|
|
.fi
|
|
.SS mxml_custfree_cb_t
|
|
Custom data destructor
|
|
.PP
|
|
.nf
|
|
typedef void(*)(void *cbdata void *custdata) mxml_custfree_cb_t;
|
|
.fi
|
|
.SS mxml_custload_cb_t
|
|
Custom data load callback function
|
|
.PP
|
|
.nf
|
|
typedef bool(*)(void *cbdata mxml_node_t *node const char *s) mxml_custload_cb_t;
|
|
.fi
|
|
.SS mxml_custsave_cb_t
|
|
Custom data save callback function
|
|
.PP
|
|
.nf
|
|
typedef char *(*)(void *cbdata mxml_node_t *node) mxml_custsave_cb_t;
|
|
.fi
|
|
.SS mxml_descend_t
|
|
\fImxmlFindElement\fR, \fImxmlWalkNext\fR, and \fImxmlWalkPrev\fR descend values
|
|
.PP
|
|
.nf
|
|
typedef enum mxml_descend_e mxml_descend_t;
|
|
.fi
|
|
.SS mxml_entity_cb_t
|
|
Entity callback function
|
|
.PP
|
|
.nf
|
|
typedef int(*)(void *cbdata const char *name) mxml_entity_cb_t;
|
|
.fi
|
|
.SS mxml_error_cb_t
|
|
Error callback function
|
|
.PP
|
|
.nf
|
|
typedef void(*)(void *cbdata const char *message) mxml_error_cb_t;
|
|
.fi
|
|
.SS mxml_index_t
|
|
An XML node index
|
|
.PP
|
|
.nf
|
|
typedef struct _mxml_index_s mxml_index_t;
|
|
.fi
|
|
.SS mxml_io_cb_t
|
|
Read/write callback function
|
|
.PP
|
|
.nf
|
|
typedef size_t(*)(void *cbdata void *buffer size_t bytes) mxml_io_cb_t;
|
|
.fi
|
|
.SS mxml_node_t
|
|
An XML node
|
|
.PP
|
|
.nf
|
|
typedef struct _mxml_node_s mxml_node_t;
|
|
.fi
|
|
.SS mxml_options_t
|
|
XML options
|
|
.PP
|
|
.nf
|
|
typedef struct _mxml_options_s mxml_options_t;
|
|
.fi
|
|
.SS mxml_sax_cb_t
|
|
SAX callback function
|
|
.PP
|
|
.nf
|
|
typedef bool(*)(void *cbdata mxml_node_t *node mxml_sax_event_t event) mxml_sax_cb_t;
|
|
.fi
|
|
.SS mxml_sax_event_t
|
|
SAX event type.
|
|
.PP
|
|
.nf
|
|
typedef enum mxml_sax_event_e mxml_sax_event_t;
|
|
.fi
|
|
.SS mxml_strcopy_cb_t
|
|
String copy/allocation callback
|
|
.PP
|
|
.nf
|
|
typedef char *(*)(void *cbdata const char *s) mxml_strcopy_cb_t;
|
|
.fi
|
|
.SS mxml_strfree_cb_t
|
|
String free callback
|
|
.PP
|
|
.nf
|
|
typedef void(*)(void *cbdata char *s) mxml_strfree_cb_t;
|
|
.fi
|
|
.SS mxml_type_cb_t
|
|
Type callback function
|
|
.PP
|
|
.nf
|
|
typedef mxml_type_t(*)(void *cbdata mxml_node_t *node) mxml_type_cb_t;
|
|
.fi
|
|
.SS mxml_type_t
|
|
The XML node type.
|
|
.PP
|
|
.nf
|
|
typedef enum mxml_type_e mxml_type_t;
|
|
.fi
|
|
.SS mxml_ws_cb_t
|
|
Whitespace callback function
|
|
.PP
|
|
.nf
|
|
typedef const char *(*)(void *cbdata mxml_node_t *node mxml_ws_t when) mxml_ws_cb_t;
|
|
.fi
|
|
.SS mxml_ws_t
|
|
Whitespace periods
|
|
.PP
|
|
.nf
|
|
typedef enum mxml_ws_e mxml_ws_t;
|
|
.fi
|
|
.SH SEE ALSO
|
|
Mini-XML Programmers Manual, https://www.msweet.org/mxml
|
|
.SH COPYRIGHT
|
|
Copyright \[co] 2003-2021 by Michael R Sweet.
|
|
|