More doco updates.

This commit is contained in:
Michael R Sweet 2024-03-16 22:20:24 -04:00
parent c1d787dc5f
commit 143fa436ca
No known key found for this signature in database
GPG Key ID: BE67C75EC81F3244
11 changed files with 1116 additions and 539 deletions

View File

@ -1,4 +1,4 @@
.TH mxml 3 "Mini-XML API" "2024-03-13" "Mini-XML API"
.TH mxml 3 "Mini-XML API" "2024-03-16" "Mini-XML API"
.SH NAME
mxml \- Mini-XML API
.SH INCLUDE FILE
@ -314,11 +314,11 @@ void mxmlAdd (
);
.fi
.PP
Adds the specified node to the parent. If the child argument is not
\fBNULL\fR, puts the new node before or after the specified child depending
on the value of the \fBadd\fR argument. If the child argument is \fBNULL\fR,
puts the new node at the beginning of the child list (\fBMXML_ADD_BEFORE\fR)
or at the end of the child list (\fBMXML_ADD_AFTER\fR).
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
@ -328,10 +328,11 @@ void mxmlDelete (
);
.fi
.PP
If the specified node has a parent, this function first removes the
node from its parent using the \fImxmlRemove\fR function.
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
Delete an attribute.
Remove an attribute from an element.
.PP
.nf
void mxmlElementClearAttr (
@ -339,8 +340,10 @@ void mxmlElementClearAttr (
const char *name
);
.fi
.PP
This function removes the attribute \fBname\fR from the element \fBnode\fR.
.SS mxmlElementGetAttr
Get an attribute.
Get the value of an attribute.
.PP
.nf
const char * mxmlElementGetAttr (
@ -349,10 +352,11 @@ const char * mxmlElementGetAttr (
);
.fi
.PP
This function returns \fBNULL\fR if the node is not an element or the
named attribute does not exist.
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 element attribute by index.
Get an attribute by index.
.PP
.nf
const char * mxmlElementGetAttrByIndex (
@ -362,8 +366,9 @@ const char * mxmlElementGetAttrByIndex (
);
.fi
.PP
The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index
is out of range.
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
@ -372,8 +377,12 @@ 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.
Set an attribute for an element.
.PP
.nf
void mxmlElementSetAttr (
@ -383,10 +392,9 @@ void mxmlElementSetAttr (
);
.fi
.PP
If the named attribute already exists, the value of the attribute
is replaced by the new string value. The string value is copied
into the element node. This function does nothing if the node is
not an element.
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
@ -399,10 +407,9 @@ void mxmlElementSetAttrf (
);
.fi
.PP
If the named attribute already exists, the value of the attribute
is replaced by the new formatted string. The formatted string value is
copied into the element node. This function does nothing if the node
is not an element.
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 mxmlEntityAddCallback
Add a callback to convert entities to Unicode.
.PP
@ -412,6 +419,22 @@ bool mxmlEntityAddCallback (
void *cbdata
);
.fi
.PP
This function adds a callback to the current thread that converts named
XML character entities to Unicode characters. The callback function \fBcb\fR
accepts the callback data pointer \fBcbdata\fR and the entity name and 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);
}
\fB`\fR
.SS mxmlEntityGetValue
Get the character corresponding to a named entity.
.PP
@ -445,14 +468,15 @@ mxml_node_t * mxmlFindElement (
);
.fi
.PP
The search is constrained by the name, attribute name, and value; any
\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. The descend argument determines
whether the search descends into child nodes; normally you will use
\fBMXML_DESCEND_FIRST\fR for the initial search and \fBMXML_NO_DESCEND\fR
to find additional direct descendents of the node. The top node argument
constrains the search to a particular node's children.
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
@ -463,9 +487,10 @@ mxml_node_t * mxmlFindPath (
);
.fi
.PP
The "path" is a slash-separated list of element names. 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.
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.
@ -478,7 +503,8 @@ const char * mxmlGetCDATA (
);
.fi
.PP
\fBNULL\fR is returned if the node is not a CDATA element.
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
@ -488,7 +514,8 @@ const char * mxmlGetComment (
);
.fi
.PP
\fBNULL\fR is returned if the node is not a comment.
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
@ -498,8 +525,8 @@ const void * mxmlGetCustom (
);
.fi
.PP
\fBNULL\fR is returned if the node (or its first child) is not a custom
value node.
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
@ -509,7 +536,8 @@ const char * mxmlGetDeclaration (
);
.fi
.PP
\fBNULL\fR is returned if the node is not a declaration.
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
@ -519,7 +547,8 @@ const char * mxmlGetDirective (
);
.fi
.PP
\fBNULL\fR is returned if the node is not a processing instruction.
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
@ -529,9 +558,10 @@ const char * mxmlGetElement (
);
.fi
.PP
\fBNULL\fR is returned if the node is not an element node.
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 an element node.
Get the first child of a node.
.PP
.nf
mxml_node_t * mxmlGetFirstChild (
@ -539,7 +569,7 @@ mxml_node_t * mxmlGetFirstChild (
);
.fi
.PP
\fBNULL\fR is returned if the node is not an element node or if the node
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
@ -551,9 +581,10 @@ long mxmlGetInteger (
);
.fi
.PP
\fB0\fR is returned if the node (or its first child) is not an integer value node.
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 an element node.
Get the last child of a node.
.PP
.nf
mxml_node_t * mxmlGetLastChild (
@ -561,7 +592,7 @@ mxml_node_t * mxmlGetLastChild (
);
.fi
.PP
\fBNULL\fR is returned if the node is not an element node or if the node
This function gets the last child of a node. \fBNULL\fR is returned if the node
has no children.
.SS mxmlGetNextSibling
@ -580,8 +611,8 @@ const char * mxmlGetOpaque (
);
.fi
.PP
\fBNULL\fR is returned if the node (or its first child) is not an opaque
value node.
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
@ -591,7 +622,7 @@ mxml_node_t * mxmlGetParent (
);
.fi
.PP
\fBNULL\fR is returned for a root node.
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
@ -601,7 +632,8 @@ mxml_node_t * mxmlGetPrevSibling (
);
.fi
.PP
\fBNULL\fR is returned if this is the first child for the current parent.
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
@ -611,7 +643,8 @@ double mxmlGetReal (
);
.fi
.PP
0.0 is returned if the node (or its first child) is not a real value node.
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
@ -634,8 +667,10 @@ const char * mxmlGetText (
);
.fi
.PP
\fBNULL\fR is returned if the node (or its first child) is not a text node.
The "whitespace" argument can be \fBNULL\fR.
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.
@ -651,7 +686,8 @@ mxml_type_t mxmlGetType (
);
.fi
.PP
\fBMXML_TYPE_IGNORE\fR is returned if "node" is \fBNULL\fR.
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
@ -660,6 +696,8 @@ 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
@ -677,6 +715,8 @@ mxml_node_t * mxmlIndexEnum (
);
.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.
@ -691,9 +731,11 @@ mxml_node_t * mxmlIndexFind (
);
.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 "element" and "value"
strings. Passing \fBNULL\fR for both "element" and "value" is equivalent
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.
@ -714,11 +756,13 @@ mxml_index_t * mxmlIndexNew (
);
.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 "element" and "attr" are \fBNULL\fR, then the index will
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 "attr"
argument is not NULL.
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.
@ -729,8 +773,9 @@ mxml_node_t * mxmlIndexReset (
);
.fi
.PP
This function should be called prior to using \fImxmlIndexEnum\fR or
\fImxmlIndexFind\fR for the first time.
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
@ -745,20 +790,24 @@ mxml_node_t * mxmlLoadFd (
);
.fi
.PP
The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like
.URL ?xml ?xml
for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type.
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
is provided, 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
The load callback function \fBload_cb\fR is called to obtain the node type that
should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
if that argument is also \fBNULL\fR.
.PP
The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
.PP
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
text as a series of whitespace-delimited words, instead of using the
\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace).
.SS mxmlLoadFile
Load a file into an XML node tree.
@ -774,20 +823,24 @@ mxml_node_t * mxmlLoadFile (
);
.fi
.PP
The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like
.URL ?xml ?xml
for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type.
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
is provided, 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
The load callback function \fBload_cb\fR is called to obtain the node type that
should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
if that argument is also \fBNULL\fR.
.PP
The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
.PP
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
text as a series of whitespace-delimited words, instead of using the
\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace).
.SS mxmlLoadFilename
Load a file into an XML node tree.
@ -803,20 +856,24 @@ mxml_node_t * mxmlLoadFilename (
);
.fi
.PP
The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like
.URL ?xml ?xml
for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type.
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
is provided, 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
The load callback function \fBload_cb\fR is called to obtain the node type that
should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
if that argument is also \fBNULL\fR.
.PP
The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
.PP
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
text as a series of whitespace-delimited words, instead of using the
\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace).
.SS mxmlLoadIO
Load an XML node tree using a read callback.
@ -833,21 +890,40 @@ mxml_node_t * mxmlLoadIO (
);
.fi
.PP
The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like
.URL ?xml ?xml
for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type.
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
is provided, 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
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
text as a series of whitespace-delimited words, instead of using the
\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
(including whitespace).
The read callback function \fBread_cb\fR is called to read a number of bytes from
the source. The callback data pointer \fBread_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
ssize_t my_read_cb(void \fIcbdata, void \fRbuffer, size_t bytes)
{
... copy up to "bytes" bytes into buffer ...
... return the number of bytes "read" or -1 on error ...
}
.nf
The load callback function `load_cb` is called to obtain the node type that
should be used for child nodes. If `NULL`, the `load_cbdata` argument points
to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
if that argument is also `NULL`.
The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
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 mxmlLoadString
Load a string into an XML node tree.
.PP
@ -862,20 +938,24 @@ mxml_node_t * mxmlLoadString (
);
.fi
.PP
The nodes in the specified string are added to the specified top node.
If no top node is provided, the XML string MUST be well-formed with a
single parent node like
.URL ?xml ?xml
for the entire string. The callback
function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type.
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 is provided,
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
The load callback function \fBload_cb\fR is called to obtain the node type that
should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
if that argument is also \fBNULL\fR.
.PP
The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
.PP
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
text as a series of whitespace-delimited words, instead of using the
\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace).
.SS mxmlNewCDATA
Create a new CDATA node.
@ -1162,16 +1242,28 @@ char * mxmlSaveAllocString (
);
.fi
.PP
This function returns a pointer to a string containing the textual
representation of the XML node tree. The string should be freed
using \fBfree()\fR when you are done with it. \fBNULL\fR is returned if the node
would produce an empty string or if the string cannot be allocated.
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
The callback argument specifies a function that returns a whitespace
string or \fBNULL\fR before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
\fBNULL\fR is returned if the node would produce an empty string or if the string
cannot be allocated.
.PP
The callback function \fBsave_cb\fR specifies a function that returns a
whitespace string or \fBNULL\fR before and after each element. The function
receives the callback data pointer \fBsave_cbdata\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_save_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 mxmlSaveFd
Save an XML tree to a file descriptor.
.PP
@ -1184,11 +1276,23 @@ bool mxmlSaveFd (
);
.fi
.PP
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
This function saves the XML tree \fBnode\fR to a file descriptor.
.PP
The callback function \fBsave_cb\fR specifies a function that returns a
whitespace string or \fBNULL\fR before and after each element. The function
receives the callback data pointer \fBsave_cbdata\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_save_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 mxmlSaveFile
Save an XML tree to a file.
.PP
@ -1201,11 +1305,23 @@ bool mxmlSaveFile (
);
.fi
.PP
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
This function saves the XML tree \fBnode\fR to a stdio \fBFILE\fR.
.PP
The callback function \fBsave_cb\fR specifies a function that returns a
whitespace string or \fBNULL\fR before and after each element. The function
receives the callback data pointer \fBsave_cbdata\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_save_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 mxmlSaveFilename
Save an XML tree to a file.
.PP
@ -1218,11 +1334,23 @@ bool mxmlSaveFilename (
);
.fi
.PP
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
This function saves the XML tree \fBnode\fR to a named file.
.PP
The callback function \fBsave_cb\fR specifies a function that returns a
whitespace string or \fBNULL\fR before and after each element. The function
receives the callback data pointer \fBsave_cbdata\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_save_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 mxmlSaveIO
Save an XML tree using a callback.
.PP
@ -1236,11 +1364,36 @@ bool mxmlSaveIO (
);
.fi
.PP
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
This function saves the XML tree \fBnode\fR using a write callback function
\fBwrite_cb\fR. The write callback is called with the callback data pointer
\fBwrite_cbdata\fR, a buffer pointer, and the number of bytes to write, for
example:
.PP
\fB`\fRc
ssize_t my_write_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 -1 on error ...
}
.nf
The callback function `save_cb` specifies a function that returns a
whitespace string or `NULL` before and after each element. The function
receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
and a "when" value indicating where the whitespace is being added, for
example:
```c
const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return ("n");
else
return (NULL);
}
.fi
.SS mxmlSaveString
Save an XML node tree to a string.
.PP
@ -1254,15 +1407,23 @@ size_t mxmlSaveString (
);
.fi
.PP
This function returns the total number of bytes that would be
required for the string but only copies (bufsize - 1) characters
into the specified buffer.
This function saves the XML tree \fBnode\fR to a string buffer.
.PP
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
with leading whitespace and before attribute names inside opening
element tags.
The callback function \fBsave_cb\fR specifies a function that returns a
whitespace string or \fBNULL\fR before and after each element. The function
receives the callback data pointer \fBsave_cbdata\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_save_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 mxmlSetCDATA
Set the data for a CDATA node.
.PP
@ -1273,7 +1434,8 @@ bool mxmlSetCDATA (
);
.fi
.PP
The node is not changed if it (or its first child) is not a CDATA node.
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
@ -1284,6 +1446,9 @@ bool mxmlSetCDATAf (
...
);
.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
@ -1293,6 +1458,8 @@ bool mxmlSetComment (
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
@ -1303,6 +1470,8 @@ bool mxmlSetCommentf (
...
);
.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
@ -1310,13 +1479,15 @@ Set the data and destructor of a custom data node.
bool mxmlSetCustom (
mxml_node_t *node,
void *data,
mxml_custom_destroy_cb_t destroy
mxml_custom_destroy_cb_t destroy_cb
);
.fi
.PP
The node is not changed if it (or its first child) is not a custom node.
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 comment to a literal string.
Set a declaration to a literal string.
.PP
.nf
bool mxmlSetDeclaration (
@ -1324,8 +1495,10 @@ bool mxmlSetDeclaration (
const char *declaration
);
.fi
.PP
This function sets the string value of a declaration node.
.SS mxmlSetDeclarationf
Set a comment to a formatted string.
Set a declaration to a formatted string.
.PP
.nf
bool mxmlSetDeclarationf (
@ -1334,8 +1507,10 @@ bool mxmlSetDeclarationf (
...
);
.fi
.PP
This function sets the formatted string value of a declaration node.
.SS mxmlSetDirective
Set a directive to a literal string.
Set a processing instruction to a literal string.
.PP
.nf
bool mxmlSetDirective (
@ -1343,8 +1518,10 @@ bool mxmlSetDirective (
const char *directive
);
.fi
.PP
This function sets the string value of a processing instruction node.
.SS mxmlSetDirectivef
Set a directive to a formatted string.
Set a processing instruction to a formatted string.
.PP
.nf
bool mxmlSetDirectivef (
@ -1353,6 +1530,9 @@ bool mxmlSetDirectivef (
...
);
.fi
.PP
This function sets the formatted string value of a processing instruction
node.
.SS mxmlSetElement
Set the name of an element node.
.PP
@ -1363,7 +1543,8 @@ bool mxmlSetElement (
);
.fi
.PP
The node is not changed if it is not an element node.
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
@ -1374,7 +1555,8 @@ bool mxmlSetInteger (
);
.fi
.PP
The node is not changed if it (or its first child) is not an integer node.
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
@ -1385,7 +1567,8 @@ bool mxmlSetOpaque (
);
.fi
.PP
The node is not changed if it (or its first child) is not an opaque node.
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
@ -1397,9 +1580,10 @@ bool mxmlSetOpaquef (
);
.fi
.PP
The node is not changed if it (or its first child) is not an opaque node.
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 number node.
Set the value of a real value node.
.PP
.nf
bool mxmlSetReal (
@ -1408,7 +1592,8 @@ bool mxmlSetReal (
);
.fi
.PP
The node is not changed if it (or its first child) is not a real number node.
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
@ -1420,7 +1605,8 @@ bool mxmlSetText (
);
.fi
.PP
The node is not changed if it (or its first child) is not a text node.
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
@ -1433,6 +1619,7 @@ bool mxmlSetTextf (
);
.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.
@ -1452,7 +1639,8 @@ void mxmlSetWrapMargin (
);
.fi
.PP
Wrapping is disabled when "column" is 0.
This function sets the wrap margin used when saving XML data for the current
thread. Wrapping is disabled when \fBcolumn\fR is \fB0\fR.
.SS mxmlWalkNext
Walk to the next logical node in the tree.
.PP
@ -1464,9 +1652,9 @@ mxml_node_t * mxmlWalkNext (
);
.fi
.PP
The descend argument controls whether the first child is considered
to be the next node. The top node argument constrains the walk to
the node's children.
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
@ -1478,9 +1666,9 @@ mxml_node_t * mxmlWalkPrev (
);
.fi
.PP
The descend argument controls whether the previous node's last child
is considered to be the previous node. The top node argument constrains
the walk to the node's children.
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

Binary file not shown.

View File

@ -1326,11 +1326,11 @@ void mxmlAdd(<a href="#mxml_node_t">mxml_node_t</a> *parent, <a href="#mxml_add_
<td class="description">Node to add</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Adds the specified node to the parent. If the child argument is not
<code>NULL</code>, puts the new node before or after the specified child depending
on the value of the <code>add</code> argument. If the child argument is <code>NULL</code>,
puts the new node at the beginning of the child list (<code>MXML_ADD_BEFORE</code>)
or at the end of the child list (<code>MXML_ADD_AFTER</code>).</p>
<p class="discussion">This function adds the specified node <code>node</code> to the parent. If the <code>child</code>
argument is not <code>NULL</code>, the new node is added before or after the specified
child depending on the value of the <code>add</code> argument. If the <code>child</code> argument
is <code>NULL</code>, the new node is placed at the beginning of the child list
(<code>MXML_ADD_BEFORE</code>) or at the end of the child list (<code>MXML_ADD_AFTER</code>).</p>
<h3 class="function"><a id="mxmlDelete">mxmlDelete</a></h3>
<p class="description">Delete a node and all of its children.</p>
<p class="code">
@ -1341,10 +1341,11 @@ void mxmlDelete(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<td class="description">Node to delete</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">If the specified node has a parent, this function first removes the
node from its parent using the <a href="#mxmlRemove"><code>mxmlRemove</code></a> function.</p>
<p class="discussion">This function deletes the node <code>node</code> and all of its children. If the
specified node has a parent, this function first removes the node from its
parent using the <a href="#mxmlRemove"><code>mxmlRemove</code></a> function.</p>
<h3 class="function"><a id="mxmlElementClearAttr">mxmlElementClearAttr</a></h3>
<p class="description">Delete an attribute.</p>
<p class="description">Remove an attribute from an element.</p>
<p class="code">
void mxmlElementClearAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p>
<h4 class="parameters">Parameters</h4>
@ -1354,8 +1355,10 @@ void mxmlElementClearAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const ch
<tr><th>name</th>
<td class="description">Attribute name</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function removes the attribute <code>name</code> from the element <code>node</code>.</p>
<h3 class="function"><a id="mxmlElementGetAttr">mxmlElementGetAttr</a></h3>
<p class="description">Get an attribute.</p>
<p class="description">Get the value of an attribute.</p>
<p class="code">
const char *mxmlElementGetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p>
<h4 class="parameters">Parameters</h4>
@ -1368,10 +1371,11 @@ const char *mxmlElementGetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, con
<h4 class="returnvalue">Return Value</h4>
<p class="description">Attribute value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns <code>NULL</code> if the node is not an element or the
named attribute does not exist.</p>
<p class="discussion">This function gets the value for the attribute <code>name</code> from the element
<code>node</code>. <code>NULL</code> is returned if the node is not an element or the named
attribute does not exist.</p>
<h3 class="function"><a id="mxmlElementGetAttrByIndex">mxmlElementGetAttrByIndex</a></h3>
<p class="description">Get an element attribute by index.</p>
<p class="description">Get an attribute by index.</p>
<p class="code">
const char *mxmlElementGetAttrByIndex(<a href="#mxml_node_t">mxml_node_t</a> *node, int idx, const char **name);</p>
<h4 class="parameters">Parameters</h4>
@ -1379,15 +1383,16 @@ const char *mxmlElementGetAttrByIndex(<a href="#mxml_node_t">mxml_node_t</a> *no
<tr><th>node</th>
<td class="description">Node</td></tr>
<tr><th>idx</th>
<td class="description">Attribute index, starting at 0</td></tr>
<td class="description">Attribute index, starting at <code>0</code></td></tr>
<tr><th>name</th>
<td class="description">Attribute name</td></tr>
<td class="description">Attribute name or <code>NULL</code> to not return it</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Attribute value</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The index (&quot;idx&quot;) is 0-based. <code>NULL</code> is returned if the specified index
is out of range.</p>
<p class="discussion">This function returned the Nth (<code>idx</code>) attribute for element <code>node</code>. The
attribute name is optionallly returned in the <code>name</code> argument. <code>NULL</code> is
returned if node is not an element or the specified index is out of range.</p>
<h3 class="function"><a id="mxmlElementGetAttrCount">mxmlElementGetAttrCount</a></h3>
<p class="description">Get the number of element attributes.</p>
<p class="code">
@ -1399,8 +1404,12 @@ size_t mxmlElementGetAttrCount(<a href="#mxml_node_t">mxml_node_t</a> *node);</p
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of attributes</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns the number of attributes for the element <code>node</code>. <code>0</code>
is returned if the node is not an element or there are no attributes for the
element.</p>
<h3 class="function"><a id="mxmlElementSetAttr">mxmlElementSetAttr</a></h3>
<p class="description">Set an attribute.</p>
<p class="description">Set an attribute for an element.</p>
<p class="code">
void mxmlElementSetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name, const char *value);</p>
<h4 class="parameters">Parameters</h4>
@ -1413,10 +1422,9 @@ void mxmlElementSetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char
<td class="description">Attribute value</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">If the named attribute already exists, the value of the attribute
is replaced by the new string value. The string value is copied
into the element node. This function does nothing if the node is
not an element.</p>
<p class="discussion">This function sets attribute <code>name</code> to the string <code>value</code> for the element
<code>node</code>. If the named attribute already exists, the value of the attribute
is replaced by the new string value. The string value is copied.</p>
<h3 class="function"><a id="mxmlElementSetAttrf">mxmlElementSetAttrf</a></h3>
<p class="description">Set an attribute with a formatted value.</p>
<p class="code">
@ -1433,10 +1441,9 @@ void mxmlElementSetAttrf(<a href="#mxml_node_t">mxml_node_t</a> *node, const cha
<td class="description">Additional arguments as needed</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">If the named attribute already exists, the value of the attribute
is replaced by the new formatted string. The formatted string value is
copied into the element node. This function does nothing if the node
is not an element.</p>
<p class="discussion">This function sets attribute <code>name</code> to the formatted value of <code>format</code> for
the element <code>node</code>. If the named attribute already exists, the value of the
attribute is replaced by the new formatted string value.</p>
<h3 class="function"><a id="mxmlEntityAddCallback">mxmlEntityAddCallback</a></h3>
<p class="description">Add a callback to convert entities to Unicode.</p>
<p class="code">
@ -1450,6 +1457,22 @@ bool mxmlEntityAddCallback(<a href="#mxml_entity_cb_t">mxml_entity_cb_t</a> cb,
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function adds a callback to the current thread that converts named
XML character entities to Unicode characters. The callback function <code>cb</code>
accepts the callback data pointer <code>cbdata</code> and the entity name and returns a
Unicode character value or <code>-1</code> if the entity is not known. For example, the
following entity callback supports the &quot;euro&quot; entity:<br>
<br>
<code>`</code>c
int my_entity_cb(void <em>cbdata, const char </em>name)
{
if (!strcmp(name, &quot;euro&quot;))
return (0x20ac);
else
return (-1);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlEntityGetValue">mxmlEntityGetValue</a></h3>
<p class="description">Get the character corresponding to a named entity.</p>
<p class="code">
@ -1495,14 +1518,15 @@ void mxmlEntityRemoveCallback(<a href="#mxml_entity_cb_t">mxml_entity_cb_t</a> c
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The search is constrained by the name, attribute name, and value; any
<code>NULL</code> 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. The descend argument determines
whether the search descends into child nodes; normally you will use
<code>MXML_DESCEND_FIRST</code> for the initial search and <code>MXML_NO_DESCEND</code>
to find additional direct descendents of the node. The top node argument
constrains the search to a particular node's children.</p>
<p class="discussion">This function finds the named element <code>element</code> in XML tree <code>top</code> starting at
node <code>node</code>. The search is constrained by element name <code>element</code>, attribute
name <code>attr</code>, and attribute value <code>value</code> - <code>NULL</code> 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.<br>
<br>
The <code>descend</code> argument determines whether the search descends into child
nodes; normally you will use <code>MXML_DESCEND_FIRST</code> for the initial search and
<code>MXML_DESCEND_NONE</code> to find additional direct descendents of the node.</p>
<h3 class="function"><a id="mxmlFindPath">mxmlFindPath</a></h3>
<p class="description">Find a node with the given path.</p>
<p class="code">
@ -1517,9 +1541,10 @@ constrains the search to a particular node's children.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Found node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The &quot;path&quot; is a slash-separated list of element names. The name &quot;<em>" is
considered a wildcard for one or more levels of elements. For example,
"foo/one/two", "bar/two/one", "</em>/one&quot;, and so forth.<br>
<p class="discussion">This function finds a node in XML tree <code>top</code> using a slash-separated list of
element names in <code>path</code>. The name &quot;<em>" is considered a wildcard for one or
more levels of elements, for example, "foo/one/two", "bar/two/one", "</em>/one&quot;,
and so forth.<br>
<br>
The first child node of the found node is returned if the given node has
children and the first child is a value node.</p>
@ -1535,7 +1560,8 @@ const char *mxmlGetCDATA(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">CDATA value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not a CDATA element.</p>
<p class="discussion">This function gets the string value of a CDATA node. <code>NULL</code> is returned if
the node is not a CDATA element.</p>
<h3 class="function"><a id="mxmlGetComment">mxmlGetComment</a></h3>
<p class="description">Get the value for a comment node.</p>
<p class="code">
@ -1548,7 +1574,8 @@ const char *mxmlGetComment(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Comment value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not a comment.</p>
<p class="discussion">This function gets the string value of a comment node. <code>NULL</code> is returned
if the node is not a comment.</p>
<h3 class="function"><a id="mxmlGetCustom">mxmlGetCustom</a></h3>
<p class="description">Get the value for a custom node.</p>
<p class="code">
@ -1561,8 +1588,8 @@ const void *mxmlGetCustom(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Custom value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a custom
value node.</p>
<p class="discussion">This function gets the binary value of a custom node. <code>NULL</code> is returned if
the node (or its first child) is not a custom value node.</p>
<h3 class="function"><a id="mxmlGetDeclaration">mxmlGetDeclaration</a></h3>
<p class="description">Get the value for a declaration node.</p>
<p class="code">
@ -1575,7 +1602,8 @@ const char *mxmlGetDeclaration(<a href="#mxml_node_t">mxml_node_t</a> *node);</p
<h4 class="returnvalue">Return Value</h4>
<p class="description">Declaraction value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not a declaration.</p>
<p class="discussion">This function gets the string value of a declaraction node. <code>NULL</code> is
returned if the node is not a declaration.</p>
<h3 class="function"><a id="mxmlGetDirective">mxmlGetDirective</a></h3>
<p class="description">Get the value for a processing instruction node.</p>
<p class="code">
@ -1588,7 +1616,8 @@ const char *mxmlGetDirective(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Comment value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not a processing instruction.</p>
<p class="discussion">This function gets the string value of a processing instruction. <code>NULL</code> is
returned if the node is not a processing instruction.</p>
<h3 class="function"><a id="mxmlGetElement">mxmlGetElement</a></h3>
<p class="description">Get the name for an element node.</p>
<p class="code">
@ -1601,9 +1630,10 @@ const char *mxmlGetElement(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element name or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node.</p>
<p class="discussion">This function gets the name of an element node. <code>NULL</code> is returned if the
node is not an element node.</p>
<h3 class="function"><a id="mxmlGetFirstChild">mxmlGetFirstChild</a></h3>
<p class="description">Get the first child of an element node.</p>
<p class="description">Get the first child of a node.</p>
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetFirstChild(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="parameters">Parameters</h4>
@ -1614,7 +1644,7 @@ const char *mxmlGetElement(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">First child or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node or if the node
<p class="discussion">This function gets the first child of a node. <code>NULL</code> is returned if the node
has no children.</p>
<h3 class="function"><a id="mxmlGetInteger">mxmlGetInteger</a></h3>
<p class="description">Get the integer value from the specified node or its
@ -1629,9 +1659,10 @@ long mxmlGetInteger(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Integer value or <code>0</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>0</code> is returned if the node (or its first child) is not an integer value node.</p>
<p class="discussion">This function gets the value of an integer node. <code>0</code> is returned if the node
(or its first child) is not an integer value node.</p>
<h3 class="function"><a id="mxmlGetLastChild">mxmlGetLastChild</a></h3>
<p class="description">Get the last child of an element node.</p>
<p class="description">Get the last child of a node.</p>
<p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetLastChild(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="parameters">Parameters</h4>
@ -1642,7 +1673,7 @@ long mxmlGetInteger(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Last child or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node is not an element node or if the node
<p class="discussion">This function gets the last child of a node. <code>NULL</code> is returned if the node
has no children.</p>
<h3 class="function"><a id="mxmlGetNextSibling">mxmlGetNextSibling</a></h3>
<p class="description"></p>
@ -1655,7 +1686,8 @@ has no children.</p>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Get the next node for the current parent.</p>
<p class="discussion"><code>NULL</code> is returned if this is the last child for the current parent.</p>
<p class="discussion">This function gets the next node for the current parent. <code>NULL</code> is returned
if this is the last child for the current parent.</p>
<h3 class="function"><a id="mxmlGetOpaque">mxmlGetOpaque</a></h3>
<p class="description">Get an opaque string value for a node or its first child.</p>
<p class="code">
@ -1668,8 +1700,8 @@ const char *mxmlGetOpaque(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Opaque string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not an opaque
value node.</p>
<p class="discussion">This function gets the string value of an opaque node. <code>NULL</code> is returned if
the node (or its first child) is not an opaque value node.</p>
<h3 class="function"><a id="mxmlGetParent">mxmlGetParent</a></h3>
<p class="description">Get the parent node.</p>
<p class="code">
@ -1682,7 +1714,7 @@ value node.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Parent node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned for a root node.</p>
<p class="discussion">This function gets the parent of a node. <code>NULL</code> is returned for a root node.</p>
<h3 class="function"><a id="mxmlGetPrevSibling">mxmlGetPrevSibling</a></h3>
<p class="description">Get the previous node for the current parent.</p>
<p class="code">
@ -1695,7 +1727,8 @@ value node.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Previous node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if this is the first child for the current parent.</p>
<p class="discussion">This function gets the previous node for the current parent. <code>NULL</code> is
returned if this is the first child for the current parent.</p>
<h3 class="function"><a id="mxmlGetReal">mxmlGetReal</a></h3>
<p class="description">Get the real value for a node or its first child.</p>
<p class="code">
@ -1708,7 +1741,8 @@ double mxmlGetReal(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Real value or 0.0</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">0.0 is returned if the node (or its first child) is not a real value node.</p>
<p class="discussion">This function gets the value of a real value node. <code>0.0</code> is returned if the
node (or its first child) is not a real value node.</p>
<h3 class="function"><a id="mxmlGetRefCount">mxmlGetRefCount</a></h3>
<p class="description">Get the current reference (use) count for a node.</p>
<p class="code">
@ -1738,8 +1772,10 @@ const char *mxmlGetText(<a href="#mxml_node_t">mxml_node_t</a> *node, bool *whit
<h4 class="returnvalue">Return Value</h4>
<p class="description">Text string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a text node.
The &quot;whitespace&quot; argument can be <code>NULL</code>.<br>
<p class="discussion">This function gets the string and whitespace values of a text node. <code>NULL</code>
and <code>false</code> are returned if the node (or its first child) is not a text node.
The <code>whitespace</code> argument can be <code>NULL</code> if you don't want to know the
whitespace value.<br>
<br>
Note: Text nodes consist of whitespace-delimited words. You will only get
single words of text when reading an XML file with <code>MXML_TYPE_TEXT</code> nodes.
@ -1758,7 +1794,8 @@ using the <a href="#mxmlGetOpaque"><code>mxmlGetOpaque</code></a> function inste
<h4 class="returnvalue">Return Value</h4>
<p class="description">Type of node</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion"><code>MXML_TYPE_IGNORE</code> is returned if &quot;node&quot; is <code>NULL</code>.</p>
<p class="discussion">This function gets the type of <code>node</code>. <code>MXML_TYPE_IGNORE</code> is returned if
<code>node</code> is <code>NULL</code>.</p>
<h3 class="function"><a id="mxmlGetUserData">mxmlGetUserData</a></h3>
<p class="description">Get the user data pointer for a node.</p>
<p class="code">
@ -1770,6 +1807,8 @@ void *mxmlGetUserData(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">User data pointer</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function gets the user data pointer associated with <code>node</code>.</p>
<h3 class="function"><a id="mxmlIndexDelete">mxmlIndexDelete</a></h3>
<p class="description">Delete an index.</p>
<p class="code">
@ -1791,7 +1830,9 @@ void mxmlIndexDelete(<a href="#mxml_index_t">mxml_index_t</a> *ind);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Next node or <code>NULL</code> if there is none</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">You should call <a href="#mxmlIndexReset"><code>mxmlIndexReset</code></a> prior to using this function to get
<p class="discussion">This function returns the next node in index <code>ind</code>.<br>
<br>
You should call <a href="#mxmlIndexReset"><code>mxmlIndexReset</code></a> prior to using this function to get
the first node in the index. Nodes are returned in the sorted order of the
index.</p>
<h3 class="function"><a id="mxmlIndexFind">mxmlIndexFind</a></h3>
@ -1810,9 +1851,11 @@ index.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Node or <code>NULL</code> if none found</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">You should call <a href="#mxmlIndexReset"><code>mxmlIndexReset</code></a> prior to using this function for
the first time with a particular set of &quot;element&quot; and &quot;value&quot;
strings. Passing <code>NULL</code> for both &quot;element&quot; and &quot;value&quot; is equivalent
<p class="discussion">This function finds the next matching node in index <code>ind</code>.<br>
<br>
You should call <a href="#mxmlIndexReset"><code>mxmlIndexReset</code></a> prior to using this function for
the first time with a particular set of <code>element</code> and <code>value</code>
strings. Passing <code>NULL</code> for both <code>element</code> and <code>value</code> is equivalent
to calling <a href="#mxmlIndexEnum"><code>mxmlIndexEnum</code></a>.</p>
<h3 class="function"><a id="mxmlIndexGetCount">mxmlIndexGetCount</a></h3>
<p class="description">Get the number of nodes in an index.</p>
@ -1841,11 +1884,13 @@ size_t mxmlIndexGetCount(<a href="#mxml_index_t">mxml_index_t</a> *ind);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New index</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The index will contain all nodes that contain the named element and/or
attribute. If both &quot;element&quot; and &quot;attr&quot; are <code>NULL</code>, then the index will
<p class="discussion">This function creates a new index for XML tree <code>node</code>.<br>
<br>
The index will contain all nodes that contain the named element and/or
attribute. If both <code>element</code> and <code>attr</code> are <code>NULL</code>, 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 &quot;attr&quot;
argument is not NULL.</p>
sorted by element name and optionally by attribute value if the <code>attr</code>
argument is not <code>NULL</code>.</p>
<h3 class="function"><a id="mxmlIndexReset">mxmlIndexReset</a></h3>
<p class="description">Reset the enumeration/find pointer in the index and
return the first node in the index.</p>
@ -1859,8 +1904,9 @@ argument is not NULL.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if there is none</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function should be called prior to using <a href="#mxmlIndexEnum"><code>mxmlIndexEnum</code></a> or
<a href="#mxmlIndexFind"><code>mxmlIndexFind</code></a> for the first time.</p>
<p class="discussion">This function resets the enumeration/find pointer in index <code>ind</code> and should
be called prior to using <a href="#mxmlIndexEnum"><code>mxmlIndexEnum</code></a> or <a href="#mxmlIndexFind"><code>mxmlIndexFind</code></a> for the
first time.</p>
<h3 class="function"><a id="mxmlLoadFd">mxmlLoadFd</a></h3>
<p class="description">Load a file descriptor into an XML node tree.</p>
<p class="code">
@ -1883,18 +1929,24 @@ argument is not NULL.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like <a href="?xml">?xml</a> for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
loading child (data) nodes of the specified type.<br>
<p class="discussion">This function loads the file descriptor <code>fd</code> into an XML node tree. The
nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
is provided, the XML file MUST be well-formed with a single parent processing
instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
<br>
The load callback function <code>load_cb</code> is called to obtain the node type that
should be used for child nodes. If <code>NULL</code>, the <code>load_cbdata</code> argument points
to a <code>mmd_type_t</code> variable that specifies the value type or <code>MMD_TYPE_TEXT</code>
if that argument is also <code>NULL</code>.<br>
<br>
The SAX callback function <code>sax_cb</code> and associated callback data <code>sax_cbdata</code>
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.<br>
<br>
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
text as a series of whitespace-delimited words, instead of using the
<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
<code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p>
<h3 class="function"><a id="mxmlLoadFile">mxmlLoadFile</a></h3>
<p class="description">Load a file into an XML node tree.</p>
@ -1918,18 +1970,24 @@ text as a series of whitespace-delimited words, instead of using the
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like <a href="?xml">?xml</a> for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
loading child (data) nodes of the specified type.<br>
<p class="discussion">This function loads the <code>FILE</code> pointer <code>fp</code> into an XML node tree. The
nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
is provided, the XML file MUST be well-formed with a single parent processing
instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
<br>
The load callback function <code>load_cb</code> is called to obtain the node type that
should be used for child nodes. If <code>NULL</code>, the <code>load_cbdata</code> argument points
to a <code>mmd_type_t</code> variable that specifies the value type or <code>MMD_TYPE_TEXT</code>
if that argument is also <code>NULL</code>.<br>
<br>
The SAX callback function <code>sax_cb</code> and associated callback data <code>sax_cbdata</code>
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.<br>
<br>
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
text as a series of whitespace-delimited words, instead of using the
<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
<code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p>
<h3 class="function"><a id="mxmlLoadFilename">mxmlLoadFilename</a></h3>
<p class="description">Load a file into an XML node tree.</p>
@ -1953,18 +2011,24 @@ text as a series of whitespace-delimited words, instead of using the
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like <a href="?xml">?xml</a> for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
loading child (data) nodes of the specified type.<br>
<p class="discussion">This function loads the named file <code>filename</code> into an XML node tree. The
nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
is provided, the XML file MUST be well-formed with a single parent processing
instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
<br>
The load callback function <code>load_cb</code> is called to obtain the node type that
should be used for child nodes. If <code>NULL</code>, the <code>load_cbdata</code> argument points
to a <code>mmd_type_t</code> variable that specifies the value type or <code>MMD_TYPE_TEXT</code>
if that argument is also <code>NULL</code>.<br>
<br>
The SAX callback function <code>sax_cb</code> and associated callback data <code>sax_cbdata</code>
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.<br>
<br>
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
text as a series of whitespace-delimited words, instead of using the
<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
<code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p>
<h3 class="function"><a id="mxmlLoadIO">mxmlLoadIO</a></h3>
<p class="description">Load an XML node tree using a read callback.</p>
@ -1990,19 +2054,39 @@ text as a series of whitespace-delimited words, instead of using the
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node.
If no top node is provided, the XML file MUST be well-formed with a
single parent node like <a href="?xml">?xml</a> for the entire file. The callback
function returns the value type that should be used for child nodes.
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
loading child (data) nodes of the specified type.<br>
<p class="discussion">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 <code>top</code>. If <code>NULL</code>
is provided, the XML file MUST be well-formed with a single parent processing
instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
<br>
The read callback function <code>read_cb</code> is called to read a number of bytes from
the source. The callback data pointer <code>read_cbdata</code> is passed to the read
callback with a pointer to a buffer and the maximum number of bytes to read,
for example:<br>
<br>
<code>`</code>c
ssize_t my_read_cb(void <em>cbdata, void </em>buffer, size_t bytes)
{
... copy up to &quot;bytes&quot; bytes into buffer ...
... return the number of bytes &quot;read&quot; or -1 on error ...
}
<pre>
The load callback function `load_cb` is called to obtain the node type that
should be used for child nodes. If `NULL`, the `load_cbdata` argument points
to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
if that argument is also `NULL`.
The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
text as a series of whitespace-delimited words, instead of using the
<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
(including whitespace).</p>
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).</pre>
</p>
<h3 class="function"><a id="mxmlLoadString">mxmlLoadString</a></h3>
<p class="description">Load a string into an XML node tree.</p>
<p class="code">
@ -2025,18 +2109,24 @@ text as a series of whitespace-delimited words, instead of using the
<h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the string has errors.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified string are added to the specified top node.
If no top node is provided, the XML string MUST be well-formed with a
single parent node like <a href="?xml">?xml</a> for the entire string. The callback
function returns the value type that should be used for child nodes.
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
loading child (data) nodes of the specified type.<br>
<p class="discussion">This function loads the string into an XML node tree. The nodes in the
specified file are added to the specified node <code>top</code>. If <code>NULL</code> is provided,
the XML file MUST be well-formed with a single parent processing instruction
node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
<br>
The load callback function <code>load_cb</code> is called to obtain the node type that
should be used for child nodes. If <code>NULL</code>, the <code>load_cbdata</code> argument points
to a <code>mmd_type_t</code> variable that specifies the value type or <code>MMD_TYPE_TEXT</code>
if that argument is also <code>NULL</code>.<br>
<br>
The SAX callback function <code>sax_cb</code> and associated callback data <code>sax_cbdata</code>
are used to enable the Simple API for XML streaming mode. The callback is
called as the XML node tree is parsed.<br>
<br>
Note: The most common programming error when using the Mini-XML library is
to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
text as a series of whitespace-delimited words, instead of using the
<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
inline text as a series of whitespace-delimited words, instead of using the
<code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p>
<h3 class="function"><a id="mxmlNewCDATA">mxmlNewCDATA</a></h3>
<p class="description">Create a new CDATA node.</p>
@ -2411,16 +2501,28 @@ char *mxmlSaveAllocString(<a href="#mxml_node_t">mxml_node_t</a> *node, <a href=
<h4 class="returnvalue">Return Value</h4>
<p class="description">Allocated string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns a pointer to a string containing the textual
representation of the XML node tree. The string should be freed
using <code>free()</code> when you are done with it. <code>NULL</code> is returned if the node
would produce an empty string or if the string cannot be allocated.<br>
<p class="discussion">This function saves the XML tree <code>node</code> to an allocated string. The string
should be freed using <code>free</code> (or the string free callback set using
<a href="#mxmlSetStringCallbacks"><code>mxmlSetStringCallbacks</code></a>) when you are done with it.<br>
<br>
The callback argument specifies a function that returns a whitespace
string or <code>NULL</code> before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
<code>NULL</code> is returned if the node would produce an empty string or if the string
cannot be allocated.<br>
<br>
The callback function <code>save_cb</code> specifies a function that returns a
whitespace string or <code>NULL</code> before and after each element. The function
receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:<br>
<br>
<code>`</code>c
const char <em>my_save_cb(void </em>cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlSaveFd">mxmlSaveFd</a></h3>
<p class="description">Save an XML tree to a file descriptor.</p>
<p class="code">
@ -2439,11 +2541,23 @@ bool mxmlSaveFd(<a href="#mxml_node_t">mxml_node_t</a> *node, int fd, <a href="#
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
<p class="discussion">This function saves the XML tree <code>node</code> to a file descriptor.<br>
<br>
The callback function <code>save_cb</code> specifies a function that returns a
whitespace string or <code>NULL</code> before and after each element. The function
receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:<br>
<br>
<code>`</code>c
const char <em>my_save_cb(void </em>cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlSaveFile">mxmlSaveFile</a></h3>
<p class="description">Save an XML tree to a file.</p>
<p class="code">
@ -2462,11 +2576,23 @@ bool mxmlSaveFile(<a href="#mxml_node_t">mxml_node_t</a> *node, FILE *fp, <a hre
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
<p class="discussion">This function saves the XML tree <code>node</code> to a stdio <code>FILE</code>.<br>
<br>
The callback function <code>save_cb</code> specifies a function that returns a
whitespace string or <code>NULL</code> before and after each element. The function
receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:<br>
<br>
<code>`</code>c
const char <em>my_save_cb(void </em>cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlSaveFilename">mxmlSaveFilename</a></h3>
<p class="description">Save an XML tree to a file.</p>
<p class="code">
@ -2485,11 +2611,23 @@ bool mxmlSaveFilename(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
<p class="discussion">This function saves the XML tree <code>node</code> to a named file.<br>
<br>
The callback function <code>save_cb</code> specifies a function that returns a
whitespace string or <code>NULL</code> before and after each element. The function
receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:<br>
<br>
<code>`</code>c
const char <em>my_save_cb(void </em>cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlSaveIO">mxmlSaveIO</a></h3>
<p class="description">Save an XML tree using a callback.</p>
<p class="code">
@ -2510,11 +2648,35 @@ bool mxmlSaveIO(<a href="#mxml_node_t">mxml_node_t</a> *node, <a href="#mxml_wri
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
<p class="discussion">This function saves the XML tree <code>node</code> using a write callback function
<code>write_cb</code>. The write callback is called with the callback data pointer
<code>write_cbdata</code>, a buffer pointer, and the number of bytes to write, for
example:<br>
<br>
<code>`</code>c
ssize_t my_write_cb(void <em>cbdata, const void </em>buffer, size_t bytes)
{
... write/copy bytes from buffer to the output ...
... return the number of bytes written/copied or -1 on error ...
}
<pre>
The callback function `save_cb` specifies a function that returns a
whitespace string or `NULL` before and after each element. The function
receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:
```c
const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
</pre>
</p>
<h3 class="function"><a id="mxmlSaveString">mxmlSaveString</a></h3>
<p class="description">Save an XML node tree to a string.</p>
<p class="code">
@ -2535,15 +2697,23 @@ size_t mxmlSaveString(<a href="#mxml_node_t">mxml_node_t</a> *node, char *buffer
<h4 class="returnvalue">Return Value</h4>
<p class="description">Size of string</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns the total number of bytes that would be
required for the string but only copies (bufsize - 1) characters
into the specified buffer.<br>
<p class="discussion">This function saves the XML tree <code>node</code> to a string buffer.<br>
<br>
The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes
with leading whitespace and before attribute names inside opening
element tags.</p>
The callback function <code>save_cb</code> specifies a function that returns a
whitespace string or <code>NULL</code> before and after each element. The function
receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
and a &quot;when&quot; value indicating where the whitespace is being added, for
example:<br>
<br>
<code>`</code>c
const char <em>my_save_cb(void </em>cbdata, mxml_node_t *node, mxml_ws_t when)
{
if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
return (&quot;n&quot;);
else
return (NULL);
}
<code>`</code></p>
<h3 class="function"><a id="mxmlSetCDATA">mxmlSetCDATA</a></h3>
<p class="description">Set the data for a CDATA node.</p>
<p class="code">
@ -2558,7 +2728,8 @@ bool mxmlSetCDATA(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *data
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not a CDATA node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetCDATAf">mxmlSetCDATAf</a></h3>
<p class="description">Set the data for a CDATA to a formatted string.</p>
<p class="code">
@ -2574,6 +2745,9 @@ bool mxmlSetCDATAf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *for
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetComment">mxmlSetComment</a></h3>
<p class="description">Set a comment to a literal string.</p>
<p class="code">
@ -2587,6 +2761,8 @@ bool mxmlSetComment(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *co
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the string value of a comment node.</p>
<h3 class="function"><a id="mxmlSetCommentf">mxmlSetCommentf</a></h3>
<p class="description">Set a comment to a formatted string.</p>
<p class="code">
@ -2602,25 +2778,29 @@ bool mxmlSetCommentf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *f
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the formatted string value of a comment node.</p>
<h3 class="function"><a id="mxmlSetCustom">mxmlSetCustom</a></h3>
<p class="description">Set the data and destructor of a custom data node.</p>
<p class="code">
bool mxmlSetCustom(<a href="#mxml_node_t">mxml_node_t</a> *node, void *data, <a href="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</a> destroy);</p>
bool mxmlSetCustom(<a href="#mxml_node_t">mxml_node_t</a> *node, void *data, <a href="#mxml_custom_destroy_cb_t">mxml_custom_destroy_cb_t</a> destroy_cb);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>node</th>
<td class="description">Node to set</td></tr>
<tr><th>data</th>
<td class="description">New data pointer</td></tr>
<tr><th>destroy</th>
<tr><th>destroy_cb</th>
<td class="description">New destructor function</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not a custom node.</p>
<p class="discussion">This function sets the data pointer <code>data</code> and destructor callback
<code>destroy_cb</code> of a custom data node. The node is not changed if it (or its
first child) is not a custom node.</p>
<h3 class="function"><a id="mxmlSetDeclaration">mxmlSetDeclaration</a></h3>
<p class="description">Set a comment to a literal string.</p>
<p class="description">Set a declaration to a literal string.</p>
<p class="code">
bool mxmlSetDeclaration(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *declaration);</p>
<h4 class="parameters">Parameters</h4>
@ -2632,8 +2812,10 @@ bool mxmlSetDeclaration(<a href="#mxml_node_t">mxml_node_t</a> *node, const char
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the string value of a declaration node.</p>
<h3 class="function"><a id="mxmlSetDeclarationf">mxmlSetDeclarationf</a></h3>
<p class="description">Set a comment to a formatted string.</p>
<p class="description">Set a declaration to a formatted string.</p>
<p class="code">
bool mxmlSetDeclarationf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p>
<h4 class="parameters">Parameters</h4>
@ -2647,8 +2829,10 @@ bool mxmlSetDeclarationf(<a href="#mxml_node_t">mxml_node_t</a> *node, const cha
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the formatted string value of a declaration node.</p>
<h3 class="function"><a id="mxmlSetDirective">mxmlSetDirective</a></h3>
<p class="description">Set a directive to a literal string.</p>
<p class="description">Set a processing instruction to a literal string.</p>
<p class="code">
bool mxmlSetDirective(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *directive);</p>
<h4 class="parameters">Parameters</h4>
@ -2660,8 +2844,10 @@ bool mxmlSetDirective(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the string value of a processing instruction node.</p>
<h3 class="function"><a id="mxmlSetDirectivef">mxmlSetDirectivef</a></h3>
<p class="description">Set a directive to a formatted string.</p>
<p class="description">Set a processing instruction to a formatted string.</p>
<p class="code">
bool mxmlSetDirectivef(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p>
<h4 class="parameters">Parameters</h4>
@ -2675,6 +2861,9 @@ bool mxmlSetDirectivef(<a href="#mxml_node_t">mxml_node_t</a> *node, const char
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sets the formatted string value of a processing instruction
node.</p>
<h3 class="function"><a id="mxmlSetElement">mxmlSetElement</a></h3>
<p class="description">Set the name of an element node.</p>
<p class="code">
@ -2689,7 +2878,8 @@ bool mxmlSetElement(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *na
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it is not an element node.</p>
<p class="discussion">This function sets the name of an element node. The node is not changed if
it is not an element node.</p>
<h3 class="function"><a id="mxmlSetInteger">mxmlSetInteger</a></h3>
<p class="description">Set the value of an integer node.</p>
<p class="code">
@ -2704,7 +2894,8 @@ bool mxmlSetInteger(<a href="#mxml_node_t">mxml_node_t</a> *node, long integer);
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not an integer node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetOpaque">mxmlSetOpaque</a></h3>
<p class="description">Set the value of an opaque node.</p>
<p class="code">
@ -2719,7 +2910,8 @@ bool mxmlSetOpaque(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *opa
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not an opaque node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetOpaquef">mxmlSetOpaquef</a></h3>
<p class="description">Set the value of an opaque string node to a formatted string.</p>
<p class="code">
@ -2736,9 +2928,10 @@ bool mxmlSetOpaquef(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *fo
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not an opaque node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetReal">mxmlSetReal</a></h3>
<p class="description">Set the value of a real number node.</p>
<p class="description">Set the value of a real value node.</p>
<p class="code">
bool mxmlSetReal(<a href="#mxml_node_t">mxml_node_t</a> *node, double real);</p>
<h4 class="parameters">Parameters</h4>
@ -2751,7 +2944,8 @@ bool mxmlSetReal(<a href="#mxml_node_t">mxml_node_t</a> *node, double real);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not a real number node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetText">mxmlSetText</a></h3>
<p class="description">Set the value of a text node.</p>
<p class="code">
@ -2768,7 +2962,8 @@ bool mxmlSetText(<a href="#mxml_node_t">mxml_node_t</a> *node, bool whitespace,
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not a text node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetTextf">mxmlSetTextf</a></h3>
<p class="description">Set the value of a text node to a formatted string.</p>
<p class="code">
@ -2787,7 +2982,8 @@ bool mxmlSetTextf(<a href="#mxml_node_t">mxml_node_t</a> *node, bool whitespace,
<h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The node is not changed if it (or its first child) is not a text node.</p>
<p class="discussion">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.</p>
<h3 class="function"><a id="mxmlSetUserData">mxmlSetUserData</a></h3>
<p class="description">Set the user data pointer for a node.</p>
<p class="code">
@ -2811,7 +3007,8 @@ void mxmlSetWrapMargin(int column);</p>
<td class="description">Column for wrapping, 0 to disable wrapping</td></tr>
</tbody></table>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Wrapping is disabled when &quot;column&quot; is 0.</p>
<p class="discussion">This function sets the wrap margin used when saving XML data for the current
thread. Wrapping is disabled when <code>column</code> is <code>0</code>.</p>
<h3 class="function"><a id="mxmlWalkNext">mxmlWalkNext</a></h3>
<p class="description">Walk to the next logical node in the tree.</p>
<p class="code">
@ -2828,9 +3025,9 @@ void mxmlSetWrapMargin(int column);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Next node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The descend argument controls whether the first child is considered
to be the next node. The top node argument constrains the walk to
the node's children.</p>
<p class="discussion">This function walks to the next logical node in the tree. The <code>descend</code>
argument controls whether the first child is considered to be the next node.
The <code>top</code> argument constrains the walk to that node's children.</p>
<h3 class="function"><a id="mxmlWalkPrev">mxmlWalkPrev</a></h3>
<p class="description">Walk to the previous logical node in the tree.</p>
<p class="code">
@ -2847,9 +3044,9 @@ the node's children.</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Previous node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The descend argument controls whether the previous node's last child
is considered to be the previous node. The top node argument constrains
the walk to the node's children.</p>
<p class="discussion">This function walks to the previous logical node in the tree. The <code>descend</code>
argument controls whether the first child is considered to be the next node.
The <code>top</code> argument constrains the walk to that node's children.</p>
<h2 class="title"><a id="TYPES">Data Types</a></h2>
<h3 class="typedef"><a id="mxml_add_t">mxml_add_t</a></h3>
<p class="description"><a href="#mxmlAdd"><code>mxmlAdd</code></a> add values</p>

View File

@ -20,7 +20,9 @@ static bool mxml_set_attr(mxml_node_t *node, const char *name, char *value);
//
// 'mxmlElementClearAttr()' - Delete an attribute.
// 'mxmlElementClearAttr()' - Remove an attribute from an element.
//
// This function removes the attribute `name` from the element `node`.
//
void
@ -63,13 +65,14 @@ mxmlElementClearAttr(mxml_node_t *node, // I - Element
//
// 'mxmlElementGetAttr()' - Get an attribute.
// 'mxmlElementGetAttr()' - Get the value of an attribute.
//
// This function returns @code NULL@ if the node is not an element or the
// named attribute does not exist.
// This function gets the value for the attribute `name` from the element
// `node`. `NULL` is returned if the node is not an element or the named
// attribute does not exist.
//
const char * // O - Attribute value or @code NULL@
const char * // O - Attribute value or `NULL`
mxmlElementGetAttr(mxml_node_t *node, // I - Element node
const char *name) // I - Name of attribute
{
@ -103,17 +106,18 @@ mxmlElementGetAttr(mxml_node_t *node, // I - Element node
//
// 'mxmlElementGetAttrByIndex()' - Get an element attribute by index.
// 'mxmlElementGetAttrByIndex()' - Get an attribute by index.
//
// The index ("idx") is 0-based. @code NULL@ is returned if the specified index
// is out of range.
// This function returned the Nth (`idx`) attribute for element `node`. The
// attribute name is optionallly returned in the `name` argument. `NULL` is
// returned if node is not an element or the specified index is out of range.
//
const char * // O - Attribute value
mxmlElementGetAttrByIndex(
mxml_node_t *node, // I - Node
int idx, // I - Attribute index, starting at 0
const char **name) // O - Attribute name
int idx, // I - Attribute index, starting at `0`
const char **name) // O - Attribute name or `NULL` to not return it
{
if (!node || node->type != MXML_TYPE_ELEMENT || idx < 0 || idx >= node->value.element.num_attrs)
return (NULL);
@ -128,6 +132,10 @@ mxmlElementGetAttrByIndex(
//
// 'mxmlElementGetAttrCount()' - Get the number of element attributes.
//
// This function returns the number of attributes for the element `node`. `0`
// is returned if the node is not an element or there are no attributes for the
// element.
//
size_t // O - Number of attributes
mxmlElementGetAttrCount(
@ -141,12 +149,11 @@ mxmlElementGetAttrCount(
//
// 'mxmlElementSetAttr()' - Set an attribute.
// 'mxmlElementSetAttr()' - Set an attribute for an element.
//
// If the named attribute already exists, the value of the attribute
// is replaced by the new string value. The string value is copied
// into the element node. This function does nothing if the node is
// not an element.
// This function sets attribute `name` to the string `value` for the element
// `node`. If the named attribute already exists, the value of the attribute
// is replaced by the new string value. The string value is copied.
//
void
@ -184,10 +191,9 @@ mxmlElementSetAttr(mxml_node_t *node, // I - Element node
//
// 'mxmlElementSetAttrf()' - Set an attribute with a formatted value.
//
// If the named attribute already exists, the value of the attribute
// is replaced by the new formatted string. The formatted string value is
// copied into the element node. This function does nothing if the node
// is not an element.
// This function sets attribute `name` to the formatted value of `format` for
// the element `node`. If the named attribute already exists, the value of the
// attribute is replaced by the new formatted string value.
//
void

View File

@ -15,6 +15,22 @@
//
// 'mxmlEntityAddCallback()' - Add a callback to convert entities to Unicode.
//
// This function adds a callback to the current thread that converts named
// XML character entities to Unicode characters. The callback function `cb`
// accepts the callback data pointer `cbdata` and the entity name and returns a
// Unicode character value or `-1` if the entity is not known. For example, the
// following entity callback supports the "euro" entity:
//
// ```c
// int my_entity_cb(void *cbdata, const char *name)
// {
// if (!strcmp(name, "euro"))
// return (0x20ac);
// else
// return (-1);
// }
// ```
//
bool // O - `true` on success, `false` on failure
mxmlEntityAddCallback(

View File

@ -71,18 +71,24 @@ static int mxml_write_ws(mxml_write_cb_t write_cb, void *write_cbdata, mxml_nod
//
// 'mxmlLoadFd()' - Load a file descriptor into an XML node tree.
//
// The nodes in the specified file are added to the specified top node.
// If no top node is provided, the XML file MUST be well-formed with a
// single parent node like <?xml> for the entire file. The callback
// function returns the value type that should be used for child nodes.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`,
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for
// loading child (data) nodes of the specified type.
// This function loads the file descriptor `fd` into an XML node tree. The
// nodes in the specified file are added to the specified node `top`. If `NULL`
// is provided, the XML file MUST be well-formed with a single parent processing
// instruction node like `<?xml version="1.0"?>` at the start of the file.
//
// The load callback function `load_cb` is called to obtain the node type that
// should be used for child nodes. If `NULL`, the `load_cbdata` argument points
// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
// if that argument is also `NULL`.
//
// The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
// are used to enable the Simple API for XML streaming mode. The callback is
// called as the XML node tree is parsed.
//
// Note: The most common programming error when using the Mini-XML library is
// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline
// text as a series of whitespace-delimited words, instead of using the
// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string
// 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).
//
@ -107,18 +113,24 @@ mxmlLoadFd(
//
// 'mxmlLoadFile()' - Load a file into an XML node tree.
//
// The nodes in the specified file are added to the specified top node.
// If no top node is provided, the XML file MUST be well-formed with a
// single parent node like <?xml> for the entire file. The callback
// function returns the value type that should be used for child nodes.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`,
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for
// loading child (data) nodes of the specified type.
// This function loads the `FILE` pointer `fp` into an XML node tree. The
// nodes in the specified file are added to the specified node `top`. If `NULL`
// is provided, the XML file MUST be well-formed with a single parent processing
// instruction node like `<?xml version="1.0"?>` at the start of the file.
//
// The load callback function `load_cb` is called to obtain the node type that
// should be used for child nodes. If `NULL`, the `load_cbdata` argument points
// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
// if that argument is also `NULL`.
//
// The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
// are used to enable the Simple API for XML streaming mode. The callback is
// called as the XML node tree is parsed.
//
// Note: The most common programming error when using the Mini-XML library is
// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline
// text as a series of whitespace-delimited words, instead of using the
// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string
// 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).
//
@ -143,18 +155,24 @@ mxmlLoadFile(
//
// 'mxmlLoadFilename()' - Load a file into an XML node tree.
//
// The nodes in the specified file are added to the specified top node.
// If no top node is provided, the XML file MUST be well-formed with a
// single parent node like <?xml> for the entire file. The callback
// function returns the value type that should be used for child nodes.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`,
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for
// loading child (data) nodes of the specified type.
// This function loads the named file `filename` into an XML node tree. The
// nodes in the specified file are added to the specified node `top`. If `NULL`
// is provided, the XML file MUST be well-formed with a single parent processing
// instruction node like `<?xml version="1.0"?>` at the start of the file.
//
// The load callback function `load_cb` is called to obtain the node type that
// should be used for child nodes. If `NULL`, the `load_cbdata` argument points
// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
// if that argument is also `NULL`.
//
// The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
// are used to enable the Simple API for XML streaming mode. The callback is
// called as the XML node tree is parsed.
//
// Note: The most common programming error when using the Mini-XML library is
// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline
// text as a series of whitespace-delimited words, instead of using the
// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string
// 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).
//
@ -192,18 +210,37 @@ mxmlLoadFilename(
//
// 'mxmlLoadIO()' - Load an XML node tree using a read callback.
//
// The nodes in the specified file are added to the specified top node.
// If no top node is provided, the XML file MUST be well-formed with a
// single parent node like <?xml> for the entire file. The callback
// function returns the value type that should be used for child nodes.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`,
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for
// loading child (data) nodes of the specified type.
// 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 `top`. If `NULL`
// is provided, the XML file MUST be well-formed with a single parent processing
// instruction node like `<?xml version="1.0"?>` at the start of the file.
//
// The read callback function `read_cb` is called to read a number of bytes from
// the source. The callback data pointer `read_cbdata` is passed to the read
// callback with a pointer to a buffer and the maximum number of bytes to read,
// for example:
//
// ```c
// ssize_t my_read_cb(void *cbdata, void *buffer, size_t bytes)
// {
// ... copy up to "bytes" bytes into buffer ...
// ... return the number of bytes "read" or -1 on error ...
// }
// ```
//
// The load callback function `load_cb` is called to obtain the node type that
// should be used for child nodes. If `NULL`, the `load_cbdata` argument points
// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
// if that argument is also `NULL`.
//
// The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
// are used to enable the Simple API for XML streaming mode. The callback is
// called as the XML node tree is parsed.
//
// Note: The most common programming error when using the Mini-XML library is
// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline
// text as a series of whitespace-delimited words, instead of using the
// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string
// 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).
//
@ -229,18 +266,24 @@ mxmlLoadIO(
//
// 'mxmlLoadString()' - Load a string into an XML node tree.
//
// The nodes in the specified string are added to the specified top node.
// If no top node is provided, the XML string MUST be well-formed with a
// single parent node like <?xml> for the entire string. The callback
// function returns the value type that should be used for child nodes.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`,
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for
// loading child (data) nodes of the specified type.
// This function loads the string into an XML node tree. The nodes in the
// specified file are added to the specified node `top`. If `NULL` is provided,
// the XML file MUST be well-formed with a single parent processing instruction
// node like `<?xml version="1.0"?>` at the start of the file.
//
// The load callback function `load_cb` is called to obtain the node type that
// should be used for child nodes. If `NULL`, the `load_cbdata` argument points
// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
// if that argument is also `NULL`.
//
// The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
// are used to enable the Simple API for XML streaming mode. The callback is
// called as the XML node tree is parsed.
//
// Note: The most common programming error when using the Mini-XML library is
// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline
// text as a series of whitespace-delimited words, instead of using the
// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string
// 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).
//
@ -274,16 +317,28 @@ mxmlLoadString(
//
// 'mxmlSaveAllocString()' - Save an XML tree to an allocated string.
//
// This function returns a pointer to a string containing the textual
// representation of the XML node tree. The string should be freed
// using `free()` when you are done with it. `NULL` is returned if the node
// would produce an empty string or if the string cannot be allocated.
// This function saves the XML tree `node` to an allocated string. The string
// should be freed using `free` (or the string free callback set using
// @link mxmlSetStringCallbacks@) when you are done with it.
//
// The callback argument specifies a function that returns a whitespace
// string or `NULL` before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// `NULL` is returned if the node would produce an empty string or if the string
// cannot be allocated.
//
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
char * // O - Allocated string or `NULL`
@ -323,11 +378,23 @@ mxmlSaveAllocString(
//
// 'mxmlSaveFd()' - Save an XML tree to a file descriptor.
//
// The callback argument specifies a function that returns a whitespace
// string or NULL before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// This function saves the XML tree `node` to a file descriptor.
//
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
bool // O - `true` on success, `false` on error.
@ -359,11 +426,23 @@ mxmlSaveFd(mxml_node_t *node, // I - Node to write
//
// 'mxmlSaveFile()' - Save an XML tree to a file.
//
// The callback argument specifies a function that returns a whitespace
// string or NULL before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// This function saves the XML tree `node` to a stdio `FILE`.
//
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
bool // O - `true` on success, `false` on error.
@ -396,11 +475,23 @@ mxmlSaveFile(
//
// 'mxmlSaveFilename()' - Save an XML tree to a file.
//
// The callback argument specifies a function that returns a whitespace
// string or NULL before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// This function saves the XML tree `node` to a named file.
//
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
bool // O - `true` on success, `false` on error.
@ -442,11 +533,34 @@ mxmlSaveFilename(
//
// 'mxmlSaveIO()' - Save an XML tree using a callback.
//
// The callback argument specifies a function that returns a whitespace
// string or NULL before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// This function saves the XML tree `node` using a write callback function
// `write_cb`. The write callback is called with the callback data pointer
// `write_cbdata`, a buffer pointer, and the number of bytes to write, for
// example:
//
// ```c
// ssize_t my_write_cb(void *cbdata, const void *buffer, size_t bytes)
// {
// ... write/copy bytes from buffer to the output ...
// ... return the number of bytes written/copied or -1 on error ...
// }
// ```
//
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
bool // O - `true` on success, `false` on error.
@ -484,15 +598,23 @@ mxmlSaveIO(
//
// 'mxmlSaveString()' - Save an XML node tree to a string.
//
// This function returns the total number of bytes that would be
// required for the string but only copies (bufsize - 1) characters
// into the specified buffer.
// This function saves the XML tree `node` to a string buffer.
//
// The callback argument specifies a function that returns a whitespace
// string or NULL before and after each element. If `MXML_NO_CALLBACK`
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes
// with leading whitespace and before attribute names inside opening
// element tags.
// The callback function `save_cb` specifies a function that returns a
// whitespace string or `NULL` before and after each element. The function
// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// and a "when" value indicating where the whitespace is being added, for
// example:
//
// ```c
// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
// {
// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
// return ("\n");
// else
// return (NULL);
// }
// ```
//
size_t // O - Size of string
@ -530,7 +652,8 @@ mxmlSaveString(
//
// 'mxmlSetWrapMargin()' - Set the wrap margin when saving XML data.
//
// Wrapping is disabled when "column" is 0.
// This function sets the wrap margin used when saving XML data for the current
// thread. Wrapping is disabled when `column` is `0`.
//
void

View File

@ -15,7 +15,8 @@
//
// 'mxmlGetCDATA()' - Get the value for a CDATA node.
//
// `NULL` is returned if the node is not a CDATA element.
// This function gets the string value of a CDATA node. `NULL` is returned if
// the node is not a CDATA element.
//
const char * // O - CDATA value or `NULL`
@ -33,7 +34,8 @@ mxmlGetCDATA(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetComment()' - Get the value for a comment node.
//
// `NULL` is returned if the node is not a comment.
// This function gets the string value of a comment node. `NULL` is returned
// if the node is not a comment.
//
const char * // O - Comment value or `NULL`
@ -51,8 +53,8 @@ mxmlGetComment(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetCustom()' - Get the value for a custom node.
//
// `NULL` is returned if the node (or its first child) is not a custom
// value node.
// This function gets the binary value of a custom node. `NULL` is returned if
// the node (or its first child) is not a custom value node.
//
const void * // O - Custom value or `NULL`
@ -75,7 +77,8 @@ mxmlGetCustom(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetDeclaration()' - Get the value for a declaration node.
//
// `NULL` is returned if the node is not a declaration.
// This function gets the string value of a declaraction node. `NULL` is
// returned if the node is not a declaration.
//
const char * // O - Declaraction value or `NULL`
@ -93,7 +96,8 @@ mxmlGetDeclaration(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetDirective()' - Get the value for a processing instruction node.
//
// `NULL` is returned if the node is not a processing instruction.
// This function gets the string value of a processing instruction. `NULL` is
// returned if the node is not a processing instruction.
//
const char * // O - Comment value or `NULL`
@ -111,7 +115,8 @@ mxmlGetDirective(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetElement()' - Get the name for an element node.
//
// `NULL` is returned if the node is not an element node.
// This function gets the name of an element node. `NULL` is returned if the
// node is not an element node.
//
const char * // O - Element name or `NULL`
@ -127,9 +132,9 @@ mxmlGetElement(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetFirstChild()' - Get the first child of an element node.
// 'mxmlGetFirstChild()' - Get the first child of a node.
//
// `NULL` is returned if the node is not an element node or if the node
// This function gets the first child of a node. `NULL` is returned if the node
// has no children.
//
@ -145,7 +150,8 @@ mxmlGetFirstChild(mxml_node_t *node) // I - Node to get
// 'mxmlGetInteger()' - Get the integer value from the specified node or its
// first child.
//
// `0` is returned if the node (or its first child) is not an integer value node.
// This function gets the value of an integer node. `0` is returned if the node
// (or its first child) is not an integer value node.
//
long // O - Integer value or `0`
@ -166,9 +172,9 @@ mxmlGetInteger(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetLastChild()' - Get the last child of an element node.
// 'mxmlGetLastChild()' - Get the last child of a node.
//
// `NULL` is returned if the node is not an element node or if the node
// This function gets the last child of a node. `NULL` is returned if the node
// has no children.
//
@ -182,7 +188,8 @@ mxmlGetLastChild(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetNextSibling()' - Get the next node for the current parent.
//
// `NULL` is returned if this is the last child for the current parent.
// This function gets the next node for the current parent. `NULL` is returned
// if this is the last child for the current parent.
//
mxml_node_t *
@ -195,8 +202,8 @@ mxmlGetNextSibling(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetOpaque()' - Get an opaque string value for a node or its first child.
//
// `NULL` is returned if the node (or its first child) is not an opaque
// value node.
// This function gets the string value of an opaque node. `NULL` is returned if
// the node (or its first child) is not an opaque value node.
//
const char * // O - Opaque string or `NULL`
@ -219,7 +226,7 @@ mxmlGetOpaque(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetParent()' - Get the parent node.
//
// `NULL` is returned for a root node.
// This function gets the parent of a node. `NULL` is returned for a root node.
//
mxml_node_t * // O - Parent node or `NULL`
@ -232,7 +239,8 @@ mxmlGetParent(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetPrevSibling()' - Get the previous node for the current parent.
//
// `NULL` is returned if this is the first child for the current parent.
// This function gets the previous node for the current parent. `NULL` is
// returned if this is the first child for the current parent.
//
mxml_node_t * // O - Previous node or `NULL`
@ -245,7 +253,8 @@ mxmlGetPrevSibling(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetReal()' - Get the real value for a node or its first child.
//
// 0.0 is returned if the node (or its first child) is not a real value node.
// This function gets the value of a real value node. `0.0` is returned if the
// node (or its first child) is not a real value node.
//
double // O - Real value or 0.0
@ -268,8 +277,10 @@ mxmlGetReal(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetText()' - Get the text value for a node or its first child.
//
// `NULL` is returned if the node (or its first child) is not a text node.
// The "whitespace" argument can be `NULL`.
// This function gets the string and whitespace values of a text node. `NULL`
// and `false` are returned if the node (or its first child) is not a text node.
// The `whitespace` argument can be `NULL` if you don't want to know the
// whitespace value.
//
// Note: Text nodes consist of whitespace-delimited words. You will only get
// single words of text when reading an XML file with `MXML_TYPE_TEXT` nodes.
@ -319,7 +330,8 @@ mxmlGetText(mxml_node_t *node, // I - Node to get
//
// 'mxmlGetType()' - Get the node type.
//
// `MXML_TYPE_IGNORE` is returned if "node" is `NULL`.
// This function gets the type of `node`. `MXML_TYPE_IGNORE` is returned if
// `node` is `NULL`.
//
mxml_type_t // O - Type of node
@ -337,6 +349,8 @@ mxmlGetType(mxml_node_t *node) // I - Node to get
//
// 'mxmlGetUserData()' - Get the user data pointer for a node.
//
// This function gets the user data pointer associated with `node`.
//
void * // O - User data pointer
mxmlGetUserData(mxml_node_t *node) // I - Node to get

View File

@ -42,6 +42,8 @@ mxmlIndexDelete(mxml_index_t *ind) // I - Index to delete
//
// 'mxmlIndexEnum()' - Return the next node in the index.
//
// This function returns the next node in index `ind`.
//
// You should call @link mxmlIndexReset@ prior to using this function to get
// the first node in the index. Nodes are returned in the sorted order of the
// index.
@ -65,9 +67,11 @@ mxmlIndexEnum(mxml_index_t *ind) // I - Index to enumerate
//
// 'mxmlIndexFind()' - Find the next matching node.
//
// This function finds the next matching node in index `ind`.
//
// You should call @link mxmlIndexReset@ prior to using this function for
// the first time with a particular set of "element" and "value"
// strings. Passing `NULL` for both "element" and "value" is equivalent
// the first time with a particular set of `element` and `value`
// strings. Passing `NULL` for both `element` and `value` is equivalent
// to calling @link mxmlIndexEnum@.
//
@ -196,11 +200,13 @@ mxmlIndexGetCount(mxml_index_t *ind) // I - Index of nodes
//
// 'mxmlIndexNew()' - Create a new index.
//
// This function creates a new index for XML tree `node`.
//
// The index will contain all nodes that contain the named element and/or
// attribute. If both "element" and "attr" are `NULL`, then the index will
// attribute. If both `element` and `attr` are `NULL`, 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 "attr"
// argument is not NULL.
// sorted by element name and optionally by attribute value if the `attr`
// argument is not `NULL`.
//
mxml_index_t * // O - New index
@ -275,8 +281,9 @@ mxmlIndexNew(mxml_node_t *node, // I - XML node tree
// 'mxmlIndexReset()' - Reset the enumeration/find pointer in the index and
// return the first node in the index.
//
// This function should be called prior to using @link mxmlIndexEnum@ or
// @link mxmlIndexFind@ for the first time.
// This function resets the enumeration/find pointer in index `ind` and should
// be called prior to using @link mxmlIndexEnum@ or @link mxmlIndexFind@ for the
// first time.
//
mxml_node_t * // O - First node or `NULL` if there is none

View File

@ -23,11 +23,11 @@ static mxml_node_t *mxml_new(mxml_node_t *parent, mxml_type_t type);
//
// 'mxmlAdd()' - Add a node to a tree.
//
// Adds the specified node to the parent. If the child argument is not
// `NULL`, puts the new node before or after the specified child depending
// on the value of the `add` argument. If the child argument is `NULL`,
// puts the new node at the beginning of the child list (`MXML_ADD_BEFORE`)
// or at the end of the child list (`MXML_ADD_AFTER`).
// This function adds the specified node `node` to the parent. If the `child`
// argument is not `NULL`, the new node is added before or after the specified
// child depending on the value of the `add` argument. If the `child` argument
// is `NULL`, the new node is placed at the beginning of the child list
// (`MXML_ADD_BEFORE`) or at the end of the child list (`MXML_ADD_AFTER`).
//
void
@ -114,8 +114,9 @@ mxmlAdd(mxml_node_t *parent, // I - Parent node
//
// 'mxmlDelete()' - Delete a node and all of its children.
//
// If the specified node has a parent, this function first removes the
// node from its parent using the @link mxmlRemove@ function.
// This function deletes the node `node` and all of its children. If the
// specified node has a parent, this function first removes the node from its
// parent using the @link mxmlRemove@ function.
//
void

View File

@ -15,14 +15,15 @@
//
// 'mxmlFindElement()' - Find the named element.
//
// The search is constrained by the name, attribute name, and value; any
// `NULL` 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. The descend argument determines
// whether the search descends into child nodes; normally you will use
// `MXML_DESCEND_FIRST` for the initial search and `MXML_NO_DESCEND`
// to find additional direct descendents of the node. The top node argument
// constrains the search to a particular node's children.
// This function finds the named element `element` in XML tree `top` starting at
// node `node`. The search is constrained by element name `element`, attribute
// name `attr`, and attribute value `value` - `NULL` 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.
//
// The `descend` argument determines whether the search descends into child
// nodes; normally you will use `MXML_DESCEND_FIRST` for the initial search and
// `MXML_DESCEND_NONE` to find additional direct descendents of the node.
//
mxml_node_t * // O - Element node or `NULL`
@ -76,9 +77,10 @@ mxmlFindElement(mxml_node_t *node, // I - Current node
//
// 'mxmlFindPath()' - Find a node with the given path.
//
// The "path" is a slash-separated list of element names. The name "*" is
// considered a wildcard for one or more levels of elements. For example,
// "foo/one/two", "bar/two/one", "*\/one", and so forth.
// This function finds a node in XML tree `top` using a slash-separated list of
// element names in `path`. The name "*" is considered a wildcard for one or
// more levels of elements, for example, "foo/one/two", "bar/two/one", "*\/one",
// and so forth.
//
// The first child node of the found node is returned if the given node has
// children and the first child is a value node.
@ -144,9 +146,9 @@ mxmlFindPath(mxml_node_t *top, // I - Top node
//
// 'mxmlWalkNext()' - Walk to the next logical node in the tree.
//
// The descend argument controls whether the first child is considered
// to be the next node. The top node argument constrains the walk to
// the node's children.
// This function walks to the next logical node in the tree. The `descend`
// argument controls whether the first child is considered to be the next node.
// The `top` argument constrains the walk to that node's children.
//
mxml_node_t * // O - Next node or `NULL`
@ -194,9 +196,9 @@ mxmlWalkNext(mxml_node_t *node, // I - Current node
//
// 'mxmlWalkPrev()' - Walk to the previous logical node in the tree.
//
// The descend argument controls whether the previous node's last child
// is considered to be the previous node. The top node argument constrains
// the walk to the node's children.
// This function walks to the previous logical node in the tree. The `descend`
// argument controls whether the first child is considered to be the next node.
// The `top` argument constrains the walk to that node's children.
//
mxml_node_t * // O - Previous node or `NULL`

View File

@ -15,7 +15,8 @@
//
// 'mxmlSetCDATA()' - Set the data for a CDATA node.
//
// The node is not changed if it (or its first child) is not a CDATA node.
// 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.
//
bool // O - `true` on success, `false` on failure
@ -63,6 +64,9 @@ mxmlSetCDATA(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetCDATAf()' - Set the data for a CDATA to a formatted string.
//
// 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.
//
bool // O - `true` on success, `false` on failure
mxmlSetCDATAf(mxml_node_t *node, // I - Node
@ -110,6 +114,8 @@ mxmlSetCDATAf(mxml_node_t *node, // I - Node
//
// 'mxmlSetComment()' - Set a comment to a literal string.
//
// This function sets the string value of a comment node.
//
bool // O - `true` on success, `false` on failure
mxmlSetComment(mxml_node_t *node, // I - Node
@ -153,6 +159,8 @@ mxmlSetComment(mxml_node_t *node, // I - Node
//
// 'mxmlSetCommentf()' - Set a comment to a formatted string.
//
// This function sets the formatted string value of a comment node.
//
bool // O - `true` on success, `false` on failure
mxmlSetCommentf(mxml_node_t *node, // I - Node
@ -200,14 +208,16 @@ mxmlSetCommentf(mxml_node_t *node, // I - Node
//
// 'mxmlSetCustom()' - Set the data and destructor of a custom data node.
//
// The node is not changed if it (or its first child) is not a custom node.
// This function sets the data pointer `data` and destructor callback
// `destroy_cb` of a custom data node. The node is not changed if it (or its
// first child) is not a custom node.
//
bool // O - `true` on success, `false` on failure
mxmlSetCustom(
mxml_node_t *node, // I - Node to set
void *data, // I - New data pointer
mxml_custom_destroy_cb_t destroy) // I - New destructor function
mxml_custom_destroy_cb_t destroy_cb)// I - New destructor function
{
// Range check input...
if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_CUSTOM)
@ -221,7 +231,7 @@ mxmlSetCustom(
if (data == node->value.custom.data)
{
node->value.custom.destroy = destroy;
node->value.custom.destroy = destroy_cb;
return (true);
}
@ -230,14 +240,16 @@ mxmlSetCustom(
(*(node->value.custom.destroy))(node->value.custom.data);
node->value.custom.data = data;
node->value.custom.destroy = destroy;
node->value.custom.destroy = destroy_cb;
return (true);
}
//
// 'mxmlSetDeclaration()' - Set a comment to a literal string.
// 'mxmlSetDeclaration()' - Set a declaration to a literal string.
//
// This function sets the string value of a declaration node.
//
bool // O - `true` on success, `false` on failure
@ -281,7 +293,9 @@ mxmlSetDeclaration(
//
// 'mxmlSetDeclarationf()' - Set a comment to a formatted string.
// 'mxmlSetDeclarationf()' - Set a declaration to a formatted string.
//
// This function sets the formatted string value of a declaration node.
//
bool // O - `true` on success, `false` on failure
@ -328,7 +342,9 @@ mxmlSetDeclarationf(mxml_node_t *node, // I - Node
//
// 'mxmlSetDirective()' - Set a directive to a literal string.
// 'mxmlSetDirective()' - Set a processing instruction to a literal string.
//
// This function sets the string value of a processing instruction node.
//
bool // O - `true` on success, `false` on failure
@ -371,7 +387,10 @@ mxmlSetDirective(mxml_node_t *node, // I - Node
//
// 'mxmlSetDirectivef()' - Set a directive to a formatted string.
// 'mxmlSetDirectivef()' - Set a processing instruction to a formatted string.
//
// This function sets the formatted string value of a processing instruction
// node.
//
bool // O - `true` on success, `false` on failure
@ -420,7 +439,8 @@ mxmlSetDirectivef(mxml_node_t *node, // I - Node
//
// 'mxmlSetElement()' - Set the name of an element node.
//
// The node is not changed if it is not an element node.
// This function sets the name of an element node. The node is not changed if
// it is not an element node.
//
bool // O - `true` on success, `false` on failure
@ -462,7 +482,8 @@ mxmlSetElement(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetInteger()' - Set the value of an integer node.
//
// The node is not changed if it (or its first child) is not an integer node.
// 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.
//
bool // O - `true` on success, `false` on failure
@ -489,7 +510,8 @@ mxmlSetInteger(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetOpaque()' - Set the value of an opaque node.
//
// The node is not changed if it (or its first child) is not an opaque node.
// 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.
//
bool // O - `true` on success, `false` on failure
@ -534,7 +556,8 @@ mxmlSetOpaque(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetOpaquef()' - Set the value of an opaque string node to a formatted string.
//
// The node is not changed if it (or its first child) is not an opaque node.
// 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.
//
bool // O - `true` on success, `false` on failure
@ -581,19 +604,17 @@ mxmlSetOpaquef(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetReal()' - Set the value of a real number node.
// 'mxmlSetReal()' - Set the value of a real value node.
//
// The node is not changed if it (or its first child) is not a real number node.
// 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.
//
bool // O - `true` on success, `false` on failure
mxmlSetReal(mxml_node_t *node, // I - Node to set
double real) // I - Real number value
{
/*
* Range check input...
*/
// Range check input...
if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_REAL)
node = node->child;
@ -613,7 +634,8 @@ mxmlSetReal(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetText()' - Set the value of a text node.
//
// The node is not changed if it (or its first child) is not a text node.
// 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.
//
bool // O - `true` on success, `false` on failure
@ -664,6 +686,7 @@ mxmlSetText(mxml_node_t *node, // I - Node to set
//
// 'mxmlSetTextf()' - Set the value of a text node to a formatted string.
//
// 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.
//