AIR/mxml
1
0
Fork 0
mirror of https://github.com/michaelrsweet/mxml.git synced 2024-11-14 15:55:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

More doco updates.

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

548
doc/mxml.3
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 .SH NAME
mxml \- Mini-XML API mxml \- Mini-XML API
.SH INCLUDE FILE .SH INCLUDE FILE
@ -314,11 +314,11 @@ void mxmlAdd (
); );
.fi .fi
.PP .PP
Adds the specified node to the parent. If the child argument is not This function adds the specified node \fBnode\fR to the parent. If the \fBchild\fR
\fBNULL\fR, puts the new node before or after the specified child depending argument is not \fBNULL\fR, the new node is added before or after the specified
on the value of the \fBadd\fR argument. If the child argument is \fBNULL\fR, child depending on the value of the \fBadd\fR argument. If the \fBchild\fR argument
puts the new node at the beginning of the child list (\fBMXML_ADD_BEFORE\fR) is \fBNULL\fR, the new node is placed at the beginning of the child list
or at the end of the child list (\fBMXML_ADD_AFTER\fR). (\fBMXML_ADD_BEFORE\fR) or at the end of the child list (\fBMXML_ADD_AFTER\fR).
.SS mxmlDelete .SS mxmlDelete
Delete a node and all of its children. Delete a node and all of its children.
.PP .PP
@ -328,10 +328,11 @@ void mxmlDelete (
); );
.fi .fi
.PP .PP
If the specified node has a parent, this function first removes the This function deletes the node \fBnode\fR and all of its children. If the
node from its parent using the \fImxmlRemove\fR function. specified node has a parent, this function first removes the node from its
parent using the \fImxmlRemove\fR function.
.SS mxmlElementClearAttr .SS mxmlElementClearAttr
Delete an attribute. Remove an attribute from an element.
.PP .PP
.nf .nf
void mxmlElementClearAttr ( void mxmlElementClearAttr (
@ -339,8 +340,10 @@ void mxmlElementClearAttr (
const char *name const char *name
); );
.fi .fi
.PP
This function removes the attribute \fBname\fR from the element \fBnode\fR.
.SS mxmlElementGetAttr .SS mxmlElementGetAttr
Get an attribute. Get the value of an attribute.
.PP .PP
.nf .nf
const char * mxmlElementGetAttr ( const char * mxmlElementGetAttr (
@ -349,10 +352,11 @@ const char * mxmlElementGetAttr (
); );
.fi .fi
.PP .PP
This function returns \fBNULL\fR if the node is not an element or the This function gets the value for the attribute \fBname\fR from the element
named attribute does not exist. \fBnode\fR. \fBNULL\fR is returned if the node is not an element or the named
attribute does not exist.
.SS mxmlElementGetAttrByIndex .SS mxmlElementGetAttrByIndex
Get an element attribute by index. Get an attribute by index.
.PP .PP
.nf .nf
const char * mxmlElementGetAttrByIndex ( const char * mxmlElementGetAttrByIndex (
@ -362,8 +366,9 @@ const char * mxmlElementGetAttrByIndex (
); );
.fi .fi
.PP .PP
The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index This function returned the Nth (\fBidx\fR) attribute for element \fBnode\fR. The
is out of range. 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 .SS mxmlElementGetAttrCount
Get the number of element attributes. Get the number of element attributes.
.PP .PP
@ -372,8 +377,12 @@ size_t mxmlElementGetAttrCount (
mxml_node_t *node mxml_node_t *node
); );
.fi .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 .SS mxmlElementSetAttr
Set an attribute. Set an attribute for an element.
.PP .PP
.nf .nf
void mxmlElementSetAttr ( void mxmlElementSetAttr (
@ -383,10 +392,9 @@ void mxmlElementSetAttr (
); );
.fi .fi
.PP .PP
If the named attribute already exists, the value of the attribute This function sets attribute \fBname\fR to the string \fBvalue\fR for the element
is replaced by the new string value. The string value is copied \fBnode\fR. If the named attribute already exists, the value of the attribute
into the element node. This function does nothing if the node is is replaced by the new string value. The string value is copied.
not an element.
.SS mxmlElementSetAttrf .SS mxmlElementSetAttrf
Set an attribute with a formatted value. Set an attribute with a formatted value.
.PP .PP
@ -399,10 +407,9 @@ void mxmlElementSetAttrf (
); );
.fi .fi
.PP .PP
If the named attribute already exists, the value of the attribute This function sets attribute \fBname\fR to the formatted value of \fBformat\fR for
is replaced by the new formatted string. The formatted string value is the element \fBnode\fR. If the named attribute already exists, the value of the
copied into the element node. This function does nothing if the node attribute is replaced by the new formatted string value.
is not an element.
.SS mxmlEntityAddCallback .SS mxmlEntityAddCallback
Add a callback to convert entities to Unicode. Add a callback to convert entities to Unicode.
.PP .PP
@ -412,6 +419,22 @@ bool mxmlEntityAddCallback (
void *cbdata void *cbdata
); );
.fi .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 .SS mxmlEntityGetValue
Get the character corresponding to a named entity. Get the character corresponding to a named entity.
.PP .PP
@ -445,14 +468,15 @@ mxml_node_t * mxmlFindElement (
); );
.fi .fi
.PP .PP
The search is constrained by the name, attribute name, and value; any This function finds the named element \fBelement\fR in XML tree \fBtop\fR starting at
\fBNULL\fR names or values are treated as wildcards, so different kinds of node \fBnode\fR. The search is constrained by element name \fBelement\fR, attribute
searches can be implemented by looking for all elements of a given name name \fBattr\fR, and attribute value \fBvalue\fR - \fBNULL\fR names or values are treated
or all elements with a specific attribute. The descend argument determines as wildcards, so different kinds of searches can be implemented by looking
whether the search descends into child nodes; normally you will use for all elements of a given name or all elements with a specific attribute.
\fBMXML_DESCEND_FIRST\fR for the initial search and \fBMXML_NO_DESCEND\fR .PP
to find additional direct descendents of the node. The top node argument The \fBdescend\fR argument determines whether the search descends into child
constrains the search to a particular node's children. 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 .SS mxmlFindPath
Find a node with the given path. Find a node with the given path.
.PP .PP
@ -463,9 +487,10 @@ mxml_node_t * mxmlFindPath (
); );
.fi .fi
.PP .PP
The "path" is a slash-separated list of element names. The name "\fI" is This function finds a node in XML tree \fBtop\fR using a slash-separated list of
considered a wildcard for one or more levels of elements. For example, element names in \fBpath\fR. The name "\fI" is considered a wildcard for one or
"foo/one/two", "bar/two/one", "\fR/one", and so forth. more levels of elements, for example, "foo/one/two", "bar/two/one", "\fR/one",
and so forth.
.PP .PP
The first child node of the found node is returned if the given node has The first child node of the found node is returned if the given node has
children and the first child is a value node. children and the first child is a value node.
@ -478,7 +503,8 @@ const char * mxmlGetCDATA (
); );
.fi .fi
.PP .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 .SS mxmlGetComment
Get the value for a comment node. Get the value for a comment node.
.PP .PP
@ -488,7 +514,8 @@ const char * mxmlGetComment (
); );
.fi .fi
.PP .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 .SS mxmlGetCustom
Get the value for a custom node. Get the value for a custom node.
.PP .PP
@ -498,8 +525,8 @@ const void * mxmlGetCustom (
); );
.fi .fi
.PP .PP
\fBNULL\fR is returned if the node (or its first child) is not a custom This function gets the binary value of a custom node. \fBNULL\fR is returned if
value node. the node (or its first child) is not a custom value node.
.SS mxmlGetDeclaration .SS mxmlGetDeclaration
Get the value for a declaration node. Get the value for a declaration node.
.PP .PP
@ -509,7 +536,8 @@ const char * mxmlGetDeclaration (
); );
.fi .fi
.PP .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 .SS mxmlGetDirective
Get the value for a processing instruction node. Get the value for a processing instruction node.
.PP .PP
@ -519,7 +547,8 @@ const char * mxmlGetDirective (
); );
.fi .fi
.PP .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 .SS mxmlGetElement
Get the name for an element node. Get the name for an element node.
.PP .PP
@ -529,9 +558,10 @@ const char * mxmlGetElement (
); );
.fi .fi
.PP .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 .SS mxmlGetFirstChild
Get the first child of an element node. Get the first child of a node.
.PP .PP
.nf .nf
mxml_node_t * mxmlGetFirstChild ( mxml_node_t * mxmlGetFirstChild (
@ -539,7 +569,7 @@ mxml_node_t * mxmlGetFirstChild (
); );
.fi .fi
.PP .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. has no children.
.SS mxmlGetInteger .SS mxmlGetInteger
Get the integer value from the specified node or its Get the integer value from the specified node or its
@ -551,9 +581,10 @@ long mxmlGetInteger (
); );
.fi .fi
.PP .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 .SS mxmlGetLastChild
Get the last child of an element node. Get the last child of a node.
.PP .PP
.nf .nf
mxml_node_t * mxmlGetLastChild ( mxml_node_t * mxmlGetLastChild (
@ -561,7 +592,7 @@ mxml_node_t * mxmlGetLastChild (
); );
.fi .fi
.PP .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. has no children.
.SS mxmlGetNextSibling .SS mxmlGetNextSibling
@ -580,8 +611,8 @@ const char * mxmlGetOpaque (
); );
.fi .fi
.PP .PP
\fBNULL\fR is returned if the node (or its first child) is not an opaque This function gets the string value of an opaque node. \fBNULL\fR is returned if
value node. the node (or its first child) is not an opaque value node.
.SS mxmlGetParent .SS mxmlGetParent
Get the parent node. Get the parent node.
.PP .PP
@ -591,7 +622,7 @@ mxml_node_t * mxmlGetParent (
); );
.fi .fi
.PP .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 .SS mxmlGetPrevSibling
Get the previous node for the current parent. Get the previous node for the current parent.
.PP .PP
@ -601,7 +632,8 @@ mxml_node_t * mxmlGetPrevSibling (
); );
.fi .fi
.PP .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 .SS mxmlGetReal
Get the real value for a node or its first child. Get the real value for a node or its first child.
.PP .PP
@ -611,7 +643,8 @@ double mxmlGetReal (
); );
.fi .fi
.PP .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 .SS mxmlGetRefCount
Get the current reference (use) count for a node. Get the current reference (use) count for a node.
.PP .PP
@ -634,8 +667,10 @@ const char * mxmlGetText (
); );
.fi .fi
.PP .PP
\fBNULL\fR is returned if the node (or its first child) is not a text node. This function gets the string and whitespace values of a text node. \fBNULL\fR
The "whitespace" argument can be \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 .PP
Note: Text nodes consist of whitespace-delimited words. You will only get 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. single words of text when reading an XML file with \fBMXML_TYPE_TEXT\fR nodes.
@ -651,7 +686,8 @@ mxml_type_t mxmlGetType (
); );
.fi .fi
.PP .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 .SS mxmlGetUserData
Get the user data pointer for a node. Get the user data pointer for a node.
.PP .PP
@ -660,6 +696,8 @@ void * mxmlGetUserData (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
.PP
This function gets the user data pointer associated with \fBnode\fR.
.SS mxmlIndexDelete .SS mxmlIndexDelete
Delete an index. Delete an index.
.PP .PP
@ -677,6 +715,8 @@ mxml_node_t * mxmlIndexEnum (
); );
.fi .fi
.PP .PP
This function returns the next node in index \fBind\fR.
.PP
You should call \fImxmlIndexReset\fR prior to using this function to get 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 the first node in the index. Nodes are returned in the sorted order of the
index. index.
@ -691,9 +731,11 @@ mxml_node_t * mxmlIndexFind (
); );
.fi .fi
.PP .PP
This function finds the next matching node in index \fBind\fR.
.PP
You should call \fImxmlIndexReset\fR prior to using this function for You should call \fImxmlIndexReset\fR prior to using this function for
the first time with a particular set of "element" and "value" the first time with a particular set of \fBelement\fR and \fBvalue\fR
strings. Passing \fBNULL\fR for both "element" and "value" is equivalent strings. Passing \fBNULL\fR for both \fBelement\fR and \fBvalue\fR is equivalent
to calling \fImxmlIndexEnum\fR. to calling \fImxmlIndexEnum\fR.
.SS mxmlIndexGetCount .SS mxmlIndexGetCount
Get the number of nodes in an index. Get the number of nodes in an index.
@ -714,11 +756,13 @@ mxml_index_t * mxmlIndexNew (
); );
.fi .fi
.PP .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 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 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" sorted by element name and optionally by attribute value if the \fBattr\fR
argument is not NULL. argument is not \fBNULL\fR.
.SS mxmlIndexReset .SS mxmlIndexReset
Reset the enumeration/find pointer in the index and Reset the enumeration/find pointer in the index and
return the first node in the index. return the first node in the index.
@ -729,8 +773,9 @@ mxml_node_t * mxmlIndexReset (
); );
.fi .fi
.PP .PP
This function should be called prior to using \fImxmlIndexEnum\fR or This function resets the enumeration/find pointer in index \fBind\fR and should
\fImxmlIndexFind\fR for the first time. be called prior to using \fImxmlIndexEnum\fR or \fImxmlIndexFind\fR for the
first time.
.SS mxmlLoadFd .SS mxmlLoadFd
Load a file descriptor into an XML node tree. Load a file descriptor into an XML node tree.
.PP .PP
@ -745,20 +790,24 @@ mxml_node_t * mxmlLoadFd (
); );
.fi .fi
.PP .PP
The nodes in the specified file are added to the specified top node. This function loads the file descriptor \fBfd\fR into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR
single parent node like is provided, the XML file MUST be well-formed with a single parent processing
.URL ?xml ?xml instruction node like \fB<?xml version="1.0"?>\fR at the start of the file.
for the entire file. The callback .PP
function returns the value type that should be used for child nodes. The load callback function \fBload_cb\fR is called to obtain the node type that
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
loading child (data) nodes of the specified type. 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 .PP
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 \fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace). (including whitespace).
.SS mxmlLoadFile .SS mxmlLoadFile
Load a file into an XML node tree. Load a file into an XML node tree.
@ -774,20 +823,24 @@ mxml_node_t * mxmlLoadFile (
); );
.fi .fi
.PP .PP
The nodes in the specified file are added to the specified top node. This function loads the \fBFILE\fR pointer \fBfp\fR into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR
single parent node like is provided, the XML file MUST be well-formed with a single parent processing
.URL ?xml ?xml instruction node like \fB<?xml version="1.0"?>\fR at the start of the file.
for the entire file. The callback .PP
function returns the value type that should be used for child nodes. The load callback function \fBload_cb\fR is called to obtain the node type that
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
loading child (data) nodes of the specified type. 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 .PP
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 \fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace). (including whitespace).
.SS mxmlLoadFilename .SS mxmlLoadFilename
Load a file into an XML node tree. Load a file into an XML node tree.
@ -803,20 +856,24 @@ mxml_node_t * mxmlLoadFilename (
); );
.fi .fi
.PP .PP
The nodes in the specified file are added to the specified top node. This function loads the named file \fBfilename\fR into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR
single parent node like is provided, the XML file MUST be well-formed with a single parent processing
.URL ?xml ?xml instruction node like \fB<?xml version="1.0"?>\fR at the start of the file.
for the entire file. The callback .PP
function returns the value type that should be used for child nodes. The load callback function \fBload_cb\fR is called to obtain the node type that
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
loading child (data) nodes of the specified type. 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 .PP
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 \fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace). (including whitespace).
.SS mxmlLoadIO .SS mxmlLoadIO
Load an XML node tree using a read callback. Load an XML node tree using a read callback.
@ -833,21 +890,40 @@ mxml_node_t * mxmlLoadIO (
); );
.fi .fi
.PP .PP
The nodes in the specified file are added to the specified top node. This function loads data into an XML node tree using a read callback. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR
single parent node like is provided, the XML file MUST be well-formed with a single parent processing
.URL ?xml ?xml instruction node like \fB<?xml version="1.0"?>\fR at the start of the file.
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.
.PP .PP
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 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 to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
(including whitespace). (including whitespace).
.fi

.SS mxmlLoadString .SS mxmlLoadString
Load a string into an XML node tree. Load a string into an XML node tree.
.PP .PP
@ -862,20 +938,24 @@ mxml_node_t * mxmlLoadString (
); );
.fi .fi
.PP .PP
The nodes in the specified string are added to the specified top node. This function loads the string into an XML node tree. The nodes in the
If no top node is provided, the XML string MUST be well-formed with a specified file are added to the specified node \fBtop\fR. If \fBNULL\fR is provided,
single parent node like the XML file MUST be well-formed with a single parent processing instruction
.URL ?xml ?xml node like \fB<?xml version="1.0"?>\fR at the start of the file.
for the entire string. The callback .PP
function returns the value type that should be used for child nodes. The load callback function \fBload_cb\fR is called to obtain the node type that
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR
loading child (data) nodes of the specified type. 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 .PP
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 \fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string
(including whitespace). (including whitespace).
.SS mxmlNewCDATA .SS mxmlNewCDATA
Create a new CDATA node. Create a new CDATA node.
@ -1162,16 +1242,28 @@ char * mxmlSaveAllocString (
); );
.fi .fi
.PP .PP
This function returns a pointer to a string containing the textual This function saves the XML tree \fBnode\fR to an allocated string. The string
representation of the XML node tree. The string should be freed should be freed using \fBfree\fR (or the string free callback set using
using \fBfree()\fR when you are done with it. \fBNULL\fR is returned if the node \fImxmlSetStringCallbacks\fR) when you are done with it.
would produce an empty string or if the string cannot be allocated.
.PP .PP
The callback argument specifies a function that returns a whitespace \fBNULL\fR is returned if the node would produce an empty string or if the string
string or \fBNULL\fR before and after each element. If \fBMXML_NO_CALLBACK\fR cannot be allocated.
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes .PP
with leading whitespace and before attribute names inside opening The callback function \fBsave_cb\fR specifies a function that returns a
element tags. 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 .SS mxmlSaveFd
Save an XML tree to a file descriptor. Save an XML tree to a file descriptor.
.PP .PP
@ -1184,11 +1276,23 @@ bool mxmlSaveFd (
); );
.fi .fi
.PP .PP
The callback argument specifies a function that returns a whitespace This function saves the XML tree \fBnode\fR to a file descriptor.
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR .PP
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes The callback function \fBsave_cb\fR specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or \fBNULL\fR before and after each element. The function
element tags. 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 .SS mxmlSaveFile
Save an XML tree to a file. Save an XML tree to a file.
.PP .PP
@ -1201,11 +1305,23 @@ bool mxmlSaveFile (
); );
.fi .fi
.PP .PP
The callback argument specifies a function that returns a whitespace This function saves the XML tree \fBnode\fR to a stdio \fBFILE\fR.
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR .PP
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes The callback function \fBsave_cb\fR specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or \fBNULL\fR before and after each element. The function
element tags. 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 .SS mxmlSaveFilename
Save an XML tree to a file. Save an XML tree to a file.
.PP .PP
@ -1218,11 +1334,23 @@ bool mxmlSaveFilename (
); );
.fi .fi
.PP .PP
The callback argument specifies a function that returns a whitespace This function saves the XML tree \fBnode\fR to a named file.
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR .PP
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes The callback function \fBsave_cb\fR specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or \fBNULL\fR before and after each element. The function
element tags. 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 .SS mxmlSaveIO
Save an XML tree using a callback. Save an XML tree using a callback.
.PP .PP
@ -1236,11 +1364,36 @@ bool mxmlSaveIO (
); );
.fi .fi
.PP .PP
The callback argument specifies a function that returns a whitespace This function saves the XML tree \fBnode\fR using a write callback function
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR \fBwrite_cb\fR. The write callback is called with the callback data pointer
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes \fBwrite_cbdata\fR, a buffer pointer, and the number of bytes to write, for
with leading whitespace and before attribute names inside opening example:
element tags. .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 .SS mxmlSaveString
Save an XML node tree to a string. Save an XML node tree to a string.
.PP .PP
@ -1254,15 +1407,23 @@ size_t mxmlSaveString (
); );
.fi .fi
.PP .PP
This function returns the total number of bytes that would be This function saves the XML tree \fBnode\fR to a string buffer.
required for the string but only copies (bufsize - 1) characters
into the specified buffer.
.PP .PP
The callback argument specifies a function that returns a whitespace The callback function \fBsave_cb\fR specifies a function that returns a
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR whitespace string or \fBNULL\fR before and after each element. The function
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer,
with leading whitespace and before attribute names inside opening and a "when" value indicating where the whitespace is being added, for
element tags. 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 .SS mxmlSetCDATA
Set the data for a CDATA node. Set the data for a CDATA node.
.PP .PP
@ -1273,7 +1434,8 @@ bool mxmlSetCDATA (
); );
.fi .fi
.PP .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 .SS mxmlSetCDATAf
Set the data for a CDATA to a formatted string. Set the data for a CDATA to a formatted string.
.PP .PP
@ -1284,6 +1446,9 @@ bool mxmlSetCDATAf (
... ...
); );
.fi .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 .SS mxmlSetComment
Set a comment to a literal string. Set a comment to a literal string.
.PP .PP
@ -1293,6 +1458,8 @@ bool mxmlSetComment (
const char *comment const char *comment
); );
.fi .fi
.PP
This function sets the string value of a comment node.
.SS mxmlSetCommentf .SS mxmlSetCommentf
Set a comment to a formatted string. Set a comment to a formatted string.
.PP .PP
@ -1303,6 +1470,8 @@ bool mxmlSetCommentf (
... ...
); );
.fi .fi
.PP
This function sets the formatted string value of a comment node.
.SS mxmlSetCustom .SS mxmlSetCustom
Set the data and destructor of a custom data node. Set the data and destructor of a custom data node.
.PP .PP
@ -1310,13 +1479,15 @@ Set the data and destructor of a custom data node.
bool mxmlSetCustom ( bool mxmlSetCustom (
mxml_node_t *node, mxml_node_t *node,
void *data, void *data,
mxml_custom_destroy_cb_t destroy mxml_custom_destroy_cb_t destroy_cb
); );
.fi .fi
.PP .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 .SS mxmlSetDeclaration
Set a comment to a literal string. Set a declaration to a literal string.
.PP .PP
.nf .nf
bool mxmlSetDeclaration ( bool mxmlSetDeclaration (
@ -1324,8 +1495,10 @@ bool mxmlSetDeclaration (
const char *declaration const char *declaration
); );
.fi .fi
.PP
This function sets the string value of a declaration node.
.SS mxmlSetDeclarationf .SS mxmlSetDeclarationf
Set a comment to a formatted string. Set a declaration to a formatted string.
.PP .PP
.nf .nf
bool mxmlSetDeclarationf ( bool mxmlSetDeclarationf (
@ -1334,8 +1507,10 @@ bool mxmlSetDeclarationf (
... ...
); );
.fi .fi
.PP
This function sets the formatted string value of a declaration node.
.SS mxmlSetDirective .SS mxmlSetDirective
Set a directive to a literal string. Set a processing instruction to a literal string.
.PP .PP
.nf .nf
bool mxmlSetDirective ( bool mxmlSetDirective (
@ -1343,8 +1518,10 @@ bool mxmlSetDirective (
const char *directive const char *directive
); );
.fi .fi
.PP
This function sets the string value of a processing instruction node.
.SS mxmlSetDirectivef .SS mxmlSetDirectivef
Set a directive to a formatted string. Set a processing instruction to a formatted string.
.PP .PP
.nf .nf
bool mxmlSetDirectivef ( bool mxmlSetDirectivef (
@ -1353,6 +1530,9 @@ bool mxmlSetDirectivef (
... ...
); );
.fi .fi
.PP
This function sets the formatted string value of a processing instruction
node.
.SS mxmlSetElement .SS mxmlSetElement
Set the name of an element node. Set the name of an element node.
.PP .PP
@ -1363,7 +1543,8 @@ bool mxmlSetElement (
); );
.fi .fi
.PP .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 .SS mxmlSetInteger
Set the value of an integer node. Set the value of an integer node.
.PP .PP
@ -1374,7 +1555,8 @@ bool mxmlSetInteger (
); );
.fi .fi
.PP .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 .SS mxmlSetOpaque
Set the value of an opaque node. Set the value of an opaque node.
.PP .PP
@ -1385,7 +1567,8 @@ bool mxmlSetOpaque (
); );
.fi .fi
.PP .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 .SS mxmlSetOpaquef
Set the value of an opaque string node to a formatted string. Set the value of an opaque string node to a formatted string.
.PP .PP
@ -1397,9 +1580,10 @@ bool mxmlSetOpaquef (
); );
.fi .fi
.PP .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 .SS mxmlSetReal
Set the value of a real number node. Set the value of a real value node.
.PP .PP
.nf .nf
bool mxmlSetReal ( bool mxmlSetReal (
@ -1408,7 +1592,8 @@ bool mxmlSetReal (
); );
.fi .fi
.PP .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 .SS mxmlSetText
Set the value of a text node. Set the value of a text node.
.PP .PP
@ -1420,7 +1605,8 @@ bool mxmlSetText (
); );
.fi .fi
.PP .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 .SS mxmlSetTextf
Set the value of a text node to a formatted string. Set the value of a text node to a formatted string.
.PP .PP
@ -1433,6 +1619,7 @@ bool mxmlSetTextf (
); );
.fi .fi
.PP .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. The node is not changed if it (or its first child) is not a text node.
.SS mxmlSetUserData .SS mxmlSetUserData
Set the user data pointer for a node. Set the user data pointer for a node.
@ -1452,7 +1639,8 @@ void mxmlSetWrapMargin (
); );
.fi .fi
.PP .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 .SS mxmlWalkNext
Walk to the next logical node in the tree. Walk to the next logical node in the tree.
.PP .PP
@ -1464,9 +1652,9 @@ mxml_node_t * mxmlWalkNext (
); );
.fi .fi
.PP .PP
The descend argument controls whether the first child is considered This function walks to the next logical node in the tree. The \fBdescend\fR
to be the next node. The top node argument constrains the walk to argument controls whether the first child is considered to be the next node.
the node's children. The \fBtop\fR argument constrains the walk to that node's children.
.SS mxmlWalkPrev .SS mxmlWalkPrev
Walk to the previous logical node in the tree. Walk to the previous logical node in the tree.
.PP .PP
@ -1478,9 +1666,9 @@ mxml_node_t * mxmlWalkPrev (
); );
.fi .fi
.PP .PP
The descend argument controls whether the previous node's last child This function walks to the previous logical node in the tree. The \fBdescend\fR
is considered to be the previous node. The top node argument constrains argument controls whether the first child is considered to be the next node.
the walk to the node's children. The \fBtop\fR argument constrains the walk to that node's children.
.SH TYPES .SH TYPES
.SS mxml_add_t .SS mxml_add_t
\fImxmlAdd\fR add values \fImxmlAdd\fR add values

BIN
doc/mxml.epub
View File

Binary file not shown.

553
doc/mxml.html
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> <td class="description">Node to add</td></tr>
</tbody></table> </tbody></table>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">Adds the specified node to the parent. If the child argument is not <p class="discussion">This function adds the specified node <code>node</code> to the parent. If the <code>child</code>
<code>NULL</code>, puts the new node before or after the specified child depending argument is not <code>NULL</code>, the new node is added before or after the specified
on the value of the <code>add</code> argument. If the child argument is <code>NULL</code>, child depending on the value of the <code>add</code> argument. If the <code>child</code> argument
puts the new node at the beginning of the child list (<code>MXML_ADD_BEFORE</code>) is <code>NULL</code>, the new node is placed at the beginning of the child list
or at the end of the child list (<code>MXML_ADD_AFTER</code>).</p> (<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> <h3 class="function"><a id="mxmlDelete">mxmlDelete</a></h3>
<p class="description">Delete a node and all of its children.</p> <p class="description">Delete a node and all of its children.</p>
<p class="code"> <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> <td class="description">Node to delete</td></tr>
</tbody></table> </tbody></table>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">If the specified node has a parent, this function first removes the <p class="discussion">This function deletes the node <code>node</code> and all of its children. If the
node from its parent using the <a href="#mxmlRemove"><code>mxmlRemove</code></a> function.</p> 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> <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"> <p class="code">
void mxmlElementClearAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p> void mxmlElementClearAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p>
<h4 class="parameters">Parameters</h4> <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> <tr><th>name</th>
<td class="description">Attribute name</td></tr> <td class="description">Attribute name</td></tr>
</tbody></table> </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> <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"> <p class="code">
const char *mxmlElementGetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p> const char *mxmlElementGetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name);</p>
<h4 class="parameters">Parameters</h4> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Attribute value or <code>NULL</code></p> <p class="description">Attribute value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns <code>NULL</code> if the node is not an element or the <p class="discussion">This function gets the value for the attribute <code>name</code> from the element
named attribute does not exist.</p> <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> <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"> <p class="code">
const char *mxmlElementGetAttrByIndex(<a href="#mxml_node_t">mxml_node_t</a> *node, int idx, const char **name);</p> const char *mxmlElementGetAttrByIndex(<a href="#mxml_node_t">mxml_node_t</a> *node, int idx, const char **name);</p>
<h4 class="parameters">Parameters</h4> <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> <tr><th>node</th>
<td class="description">Node</td></tr> <td class="description">Node</td></tr>
<tr><th>idx</th> <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> <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> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Attribute value</p> <p class="description">Attribute value</p>
<h4 class="discussion">Discussion</h4> <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 <p class="discussion">This function returned the Nth (<code>idx</code>) attribute for element <code>node</code>. The
is out of range.</p> 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> <h3 class="function"><a id="mxmlElementGetAttrCount">mxmlElementGetAttrCount</a></h3>
<p class="description">Get the number of element attributes.</p> <p class="description">Get the number of element attributes.</p>
<p class="code"> <p class="code">
@ -1399,8 +1404,12 @@ size_t mxmlElementGetAttrCount(<a href="#mxml_node_t">mxml_node_t</a> *node);</p
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Number of attributes</p> <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> <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"> <p class="code">
void mxmlElementSetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name, const char *value);</p> void mxmlElementSetAttr(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *name, const char *value);</p>
<h4 class="parameters">Parameters</h4> <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> <td class="description">Attribute value</td></tr>
</tbody></table> </tbody></table>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">If the named attribute already exists, the value of the attribute <p class="discussion">This function sets attribute <code>name</code> to the string <code>value</code> for the element
is replaced by the new string value. The string value is copied <code>node</code>. If the named attribute already exists, the value of the attribute
into the element node. This function does nothing if the node is is replaced by the new string value. The string value is copied.</p>
not an element.</p>
<h3 class="function"><a id="mxmlElementSetAttrf">mxmlElementSetAttrf</a></h3> <h3 class="function"><a id="mxmlElementSetAttrf">mxmlElementSetAttrf</a></h3>
<p class="description">Set an attribute with a formatted value.</p> <p class="description">Set an attribute with a formatted value.</p>
<p class="code"> <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> <td class="description">Additional arguments as needed</td></tr>
</tbody></table> </tbody></table>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">If the named attribute already exists, the value of the attribute <p class="discussion">This function sets attribute <code>name</code> to the formatted value of <code>format</code> for
is replaced by the new formatted string. The formatted string value is the element <code>node</code>. If the named attribute already exists, the value of the
copied into the element node. This function does nothing if the node attribute is replaced by the new formatted string value.</p>
is not an element.</p>
<h3 class="function"><a id="mxmlEntityAddCallback">mxmlEntityAddCallback</a></h3> <h3 class="function"><a id="mxmlEntityAddCallback">mxmlEntityAddCallback</a></h3>
<p class="description">Add a callback to convert entities to Unicode.</p> <p class="description">Add a callback to convert entities to Unicode.</p>
<p class="code"> <p class="code">
@ -1450,6 +1457,22 @@ bool mxmlEntityAddCallback(<a href="#mxml_entity_cb_t">mxml_entity_cb_t</a> cb,
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <h3 class="function"><a id="mxmlEntityGetValue">mxmlEntityGetValue</a></h3>
<p class="description">Get the character corresponding to a named entity.</p> <p class="description">Get the character corresponding to a named entity.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Element node or <code>NULL</code></p> <p class="description">Element node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The search is constrained by the name, attribute name, and value; any <p class="discussion">This function finds the named element <code>element</code> in XML tree <code>top</code> starting at
<code>NULL</code> names or values are treated as wildcards, so different kinds of node <code>node</code>. The search is constrained by element name <code>element</code>, attribute
searches can be implemented by looking for all elements of a given name name <code>attr</code>, and attribute value <code>value</code> - <code>NULL</code> names or values are treated
or all elements with a specific attribute. The descend argument determines as wildcards, so different kinds of searches can be implemented by looking
whether the search descends into child nodes; normally you will use for all elements of a given name or all elements with a specific attribute.<br>
<code>MXML_DESCEND_FIRST</code> for the initial search and <code>MXML_NO_DESCEND</code> <br>
to find additional direct descendents of the node. The top node argument The <code>descend</code> argument determines whether the search descends into child
constrains the search to a particular node's children.</p> 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> <h3 class="function"><a id="mxmlFindPath">mxmlFindPath</a></h3>
<p class="description">Find a node with the given path.</p> <p class="description">Find a node with the given path.</p>
<p class="code"> <p class="code">
@ -1517,9 +1541,10 @@ constrains the search to a particular node's children.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Found node or <code>NULL</code></p> <p class="description">Found node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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 <p class="discussion">This function finds a node in XML tree <code>top</code> using a slash-separated list of
considered a wildcard for one or more levels of elements. For example, element names in <code>path</code>. The name &quot;<em>" is considered a wildcard for one or
"foo/one/two", "bar/two/one", "</em>/one&quot;, and so forth.<br> more levels of elements, for example, "foo/one/two", "bar/two/one", "</em>/one&quot;,
and so forth.<br>
<br> <br>
The first child node of the found node is returned if the given node has 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> 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> <h4 class="returnvalue">Return Value</h4>
<p class="description">CDATA value or <code>NULL</code></p> <p class="description">CDATA value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetComment">mxmlGetComment</a></h3>
<p class="description">Get the value for a comment node.</p> <p class="description">Get the value for a comment node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Comment value or <code>NULL</code></p> <p class="description">Comment value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetCustom">mxmlGetCustom</a></h3>
<p class="description">Get the value for a custom node.</p> <p class="description">Get the value for a custom node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Custom value or <code>NULL</code></p> <p class="description">Custom value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a custom <p class="discussion">This function gets the binary value of a custom node. <code>NULL</code> is returned if
value node.</p> the node (or its first child) is not a custom value node.</p>
<h3 class="function"><a id="mxmlGetDeclaration">mxmlGetDeclaration</a></h3> <h3 class="function"><a id="mxmlGetDeclaration">mxmlGetDeclaration</a></h3>
<p class="description">Get the value for a declaration node.</p> <p class="description">Get the value for a declaration node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Declaraction value or <code>NULL</code></p> <p class="description">Declaraction value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetDirective">mxmlGetDirective</a></h3>
<p class="description">Get the value for a processing instruction node.</p> <p class="description">Get the value for a processing instruction node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Comment value or <code>NULL</code></p> <p class="description">Comment value or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetElement">mxmlGetElement</a></h3>
<p class="description">Get the name for an element node.</p> <p class="description">Get the name for an element node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Element name or <code>NULL</code></p> <p class="description">Element name or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <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"> <p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetFirstChild(<a href="#mxml_node_t">mxml_node_t</a> *node);</p> <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> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">First child or <code>NULL</code></p> <p class="description">First child or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> has no children.</p>
<h3 class="function"><a id="mxmlGetInteger">mxmlGetInteger</a></h3> <h3 class="function"><a id="mxmlGetInteger">mxmlGetInteger</a></h3>
<p class="description">Get the integer value from the specified node or its <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Integer value or <code>0</code></p> <p class="description">Integer value or <code>0</code></p>
<h4 class="discussion">Discussion</h4> <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> <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"> <p class="code">
<a href="#mxml_node_t">mxml_node_t</a> *mxmlGetLastChild(<a href="#mxml_node_t">mxml_node_t</a> *node);</p> <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> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Last child or <code>NULL</code></p> <p class="description">Last child or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> has no children.</p>
<h3 class="function"><a id="mxmlGetNextSibling">mxmlGetNextSibling</a></h3> <h3 class="function"><a id="mxmlGetNextSibling">mxmlGetNextSibling</a></h3>
<p class="description"></p> <p class="description"></p>
@ -1655,7 +1686,8 @@ has no children.</p>
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Get the next node for the current parent.</p> <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> <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="description">Get an opaque string value for a node or its first child.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Opaque string or <code>NULL</code></p> <p class="description">Opaque string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not an opaque <p class="discussion">This function gets the string value of an opaque node. <code>NULL</code> is returned if
value node.</p> the node (or its first child) is not an opaque value node.</p>
<h3 class="function"><a id="mxmlGetParent">mxmlGetParent</a></h3> <h3 class="function"><a id="mxmlGetParent">mxmlGetParent</a></h3>
<p class="description">Get the parent node.</p> <p class="description">Get the parent node.</p>
<p class="code"> <p class="code">
@ -1682,7 +1714,7 @@ value node.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Parent node or <code>NULL</code></p> <p class="description">Parent node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetPrevSibling">mxmlGetPrevSibling</a></h3>
<p class="description">Get the previous node for the current parent.</p> <p class="description">Get the previous node for the current parent.</p>
<p class="code"> <p class="code">
@ -1695,7 +1727,8 @@ value node.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Previous node or <code>NULL</code></p> <p class="description">Previous node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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> <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="description">Get the real value for a node or its first child.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Real value or 0.0</p> <p class="description">Real value or 0.0</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetRefCount">mxmlGetRefCount</a></h3>
<p class="description">Get the current reference (use) count for a node.</p> <p class="description">Get the current reference (use) count for a node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Text string or <code>NULL</code></p> <p class="description">Text string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <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. <p class="discussion">This function gets the string and whitespace values of a text node. <code>NULL</code>
The &quot;whitespace&quot; argument can be <code>NULL</code>.<br> 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> <br>
Note: Text nodes consist of whitespace-delimited words. You will only get 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. 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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Type of node</p> <p class="description">Type of node</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlGetUserData">mxmlGetUserData</a></h3>
<p class="description">Get the user data pointer for a node.</p> <p class="description">Get the user data pointer for a node.</p>
<p class="code"> <p class="code">
@ -1770,6 +1807,8 @@ void *mxmlGetUserData(<a href="#mxml_node_t">mxml_node_t</a> *node);</p>
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">User data pointer</p> <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> <h3 class="function"><a id="mxmlIndexDelete">mxmlIndexDelete</a></h3>
<p class="description">Delete an index.</p> <p class="description">Delete an index.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Next node or <code>NULL</code> if there is none</p> <p class="description">Next node or <code>NULL</code> if there is none</p>
<h4 class="discussion">Discussion</h4> <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 the first node in the index. Nodes are returned in the sorted order of the
index.</p> index.</p>
<h3 class="function"><a id="mxmlIndexFind">mxmlIndexFind</a></h3> <h3 class="function"><a id="mxmlIndexFind">mxmlIndexFind</a></h3>
@ -1810,9 +1851,11 @@ index.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Node or <code>NULL</code> if none found</p> <p class="description">Node or <code>NULL</code> if none found</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">You should call <a href="#mxmlIndexReset"><code>mxmlIndexReset</code></a> prior to using this function for <p class="discussion">This function finds the next matching node in index <code>ind</code>.<br>
the first time with a particular set of &quot;element&quot; and &quot;value&quot; <br>
strings. Passing <code>NULL</code> for both &quot;element&quot; and &quot;value&quot; is equivalent 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> to calling <a href="#mxmlIndexEnum"><code>mxmlIndexEnum</code></a>.</p>
<h3 class="function"><a id="mxmlIndexGetCount">mxmlIndexGetCount</a></h3> <h3 class="function"><a id="mxmlIndexGetCount">mxmlIndexGetCount</a></h3>
<p class="description">Get the number of nodes in an index.</p> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">New index</p> <p class="description">New index</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The index will contain all nodes that contain the named element and/or <p class="discussion">This function creates a new index for XML tree <code>node</code>.<br>
attribute. If both &quot;element&quot; and &quot;attr&quot; are <code>NULL</code>, then the index will <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 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; sorted by element name and optionally by attribute value if the <code>attr</code>
argument is not NULL.</p> argument is not <code>NULL</code>.</p>
<h3 class="function"><a id="mxmlIndexReset">mxmlIndexReset</a></h3> <h3 class="function"><a id="mxmlIndexReset">mxmlIndexReset</a></h3>
<p class="description">Reset the enumeration/find pointer in the index and <p class="description">Reset the enumeration/find pointer in the index and
return the first node in the index.</p> return the first node in the index.</p>
@ -1859,8 +1904,9 @@ argument is not NULL.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if there is none</p> <p class="description">First node or <code>NULL</code> if there is none</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">This function should be called prior to using <a href="#mxmlIndexEnum"><code>mxmlIndexEnum</code></a> or <p class="discussion">This function resets the enumeration/find pointer in index <code>ind</code> and should
<a href="#mxmlIndexFind"><code>mxmlIndexFind</code></a> for the first time.</p> 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> <h3 class="function"><a id="mxmlLoadFd">mxmlLoadFd</a></h3>
<p class="description">Load a file descriptor into an XML node tree.</p> <p class="description">Load a file descriptor into an XML node tree.</p>
<p class="code"> <p class="code">
@ -1883,18 +1929,24 @@ argument is not NULL.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p> <p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node. <p class="discussion">This function loads the file descriptor <code>fd</code> into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
single parent node like <a href="?xml">?xml</a> for the entire file. The callback is provided, the XML file MUST be well-formed with a single parent processing
function returns the value type that should be used for child nodes. instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>, <br>
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for The load callback function <code>load_cb</code> is called to obtain the node type that
loading child (data) nodes of the specified type.<br> 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> <br>
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 <code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p> (including whitespace).</p>
<h3 class="function"><a id="mxmlLoadFile">mxmlLoadFile</a></h3> <h3 class="function"><a id="mxmlLoadFile">mxmlLoadFile</a></h3>
<p class="description">Load a file into an XML node tree.</p> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p> <p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node. <p class="discussion">This function loads the <code>FILE</code> pointer <code>fp</code> into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
single parent node like <a href="?xml">?xml</a> for the entire file. The callback is provided, the XML file MUST be well-formed with a single parent processing
function returns the value type that should be used for child nodes. instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>, <br>
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for The load callback function <code>load_cb</code> is called to obtain the node type that
loading child (data) nodes of the specified type.<br> 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> <br>
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 <code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p> (including whitespace).</p>
<h3 class="function"><a id="mxmlLoadFilename">mxmlLoadFilename</a></h3> <h3 class="function"><a id="mxmlLoadFilename">mxmlLoadFilename</a></h3>
<p class="description">Load a file into an XML node tree.</p> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p> <p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node. <p class="discussion">This function loads the named file <code>filename</code> into an XML node tree. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
single parent node like <a href="?xml">?xml</a> for the entire file. The callback is provided, the XML file MUST be well-formed with a single parent processing
function returns the value type that should be used for child nodes. instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>, <br>
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for The load callback function <code>load_cb</code> is called to obtain the node type that
loading child (data) nodes of the specified type.<br> 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> <br>
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 <code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p> (including whitespace).</p>
<h3 class="function"><a id="mxmlLoadIO">mxmlLoadIO</a></h3> <h3 class="function"><a id="mxmlLoadIO">mxmlLoadIO</a></h3>
<p class="description">Load an XML node tree using a read callback.</p> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the file could not be read.</p> <p class="description">First node or <code>NULL</code> if the file could not be read.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified file are added to the specified top node. <p class="discussion">This function loads data into an XML node tree using a read callback. The
If no top node is provided, the XML file MUST be well-formed with a nodes in the specified file are added to the specified node <code>top</code>. If <code>NULL</code>
single parent node like <a href="?xml">?xml</a> for the entire file. The callback is provided, the XML file MUST be well-formed with a single parent processing
function returns the value type that should be used for child nodes. instruction node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
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>
<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 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 to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
(including whitespace).</p> (including whitespace).</pre>
</p>
<h3 class="function"><a id="mxmlLoadString">mxmlLoadString</a></h3> <h3 class="function"><a id="mxmlLoadString">mxmlLoadString</a></h3>
<p class="description">Load a string into an XML node tree.</p> <p class="description">Load a string into an XML node tree.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">First node or <code>NULL</code> if the string has errors.</p> <p class="description">First node or <code>NULL</code> if the string has errors.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The nodes in the specified string are added to the specified top node. <p class="discussion">This function loads the string into an XML node tree. The nodes in the
If no top node is provided, the XML string MUST be well-formed with a specified file are added to the specified node <code>top</code>. If <code>NULL</code> is provided,
single parent node like <a href="?xml">?xml</a> for the entire string. The callback the XML file MUST be well-formed with a single parent processing instruction
function returns the value type that should be used for child nodes. node like <code>&lt;?xml version="1.0"?&gt;</code> at the start of the file.<br>
The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>, <br>
<code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for The load callback function <code>load_cb</code> is called to obtain the node type that
loading child (data) nodes of the specified type.<br> 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> <br>
Note: The most common programming error when using the Mini-XML library is 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 to load an XML file using the <code>MXML_TYPE_TEXT</code> node type, which returns
text as a series of whitespace-delimited words, instead of using the 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 <code>MXML_TYPE_OPAQUE</code> node type which returns the inline text as a single string
(including whitespace).</p> (including whitespace).</p>
<h3 class="function"><a id="mxmlNewCDATA">mxmlNewCDATA</a></h3> <h3 class="function"><a id="mxmlNewCDATA">mxmlNewCDATA</a></h3>
<p class="description">Create a new CDATA node.</p> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Allocated string or <code>NULL</code></p> <p class="description">Allocated string or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns a pointer to a string containing the textual <p class="discussion">This function saves the XML tree <code>node</code> to an allocated string. The string
representation of the XML node tree. The string should be freed should be freed using <code>free</code> (or the string free callback set using
using <code>free()</code> when you are done with it. <code>NULL</code> is returned if the node <a href="#mxmlSetStringCallbacks"><code>mxmlSetStringCallbacks</code></a>) when you are done with it.<br>
would produce an empty string or if the string cannot be allocated.<br>
<br> <br>
The callback argument specifies a function that returns a whitespace <code>NULL</code> is returned if the node would produce an empty string or if the string
string or <code>NULL</code> before and after each element. If <code>MXML_NO_CALLBACK</code> cannot be allocated.<br>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes <br>
with leading whitespace and before attribute names inside opening The callback function <code>save_cb</code> specifies a function that returns a
element tags.</p> 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> <h3 class="function"><a id="mxmlSaveFd">mxmlSaveFd</a></h3>
<p class="description">Save an XML tree to a file descriptor.</p> <p class="description">Save an XML tree to a file descriptor.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p> <p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace <p class="discussion">This function saves the XML tree <code>node</code> to a file descriptor.<br>
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code> <br>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes The callback function <code>save_cb</code> specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or <code>NULL</code> before and after each element. The function
element tags.</p> 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> <h3 class="function"><a id="mxmlSaveFile">mxmlSaveFile</a></h3>
<p class="description">Save an XML tree to a file.</p> <p class="description">Save an XML tree to a file.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p> <p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace <p class="discussion">This function saves the XML tree <code>node</code> to a stdio <code>FILE</code>.<br>
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code> <br>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes The callback function <code>save_cb</code> specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or <code>NULL</code> before and after each element. The function
element tags.</p> 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> <h3 class="function"><a id="mxmlSaveFilename">mxmlSaveFilename</a></h3>
<p class="description">Save an XML tree to a file.</p> <p class="description">Save an XML tree to a file.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p> <p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace <p class="discussion">This function saves the XML tree <code>node</code> to a named file.<br>
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code> <br>
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes The callback function <code>save_cb</code> specifies a function that returns a
with leading whitespace and before attribute names inside opening whitespace string or <code>NULL</code> before and after each element. The function
element tags.</p> 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> <h3 class="function"><a id="mxmlSaveIO">mxmlSaveIO</a></h3>
<p class="description">Save an XML tree using a callback.</p> <p class="description">Save an XML tree using a callback.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on error.</p> <p class="description"><code>true</code> on success, <code>false</code> on error.</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The callback argument specifies a function that returns a whitespace <p class="discussion">This function saves the XML tree <code>node</code> using a write callback function
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code> <code>write_cb</code>. The write callback is called with the callback data pointer
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes <code>write_cbdata</code>, a buffer pointer, and the number of bytes to write, for
with leading whitespace and before attribute names inside opening example:<br>
element tags.</p> <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> <h3 class="function"><a id="mxmlSaveString">mxmlSaveString</a></h3>
<p class="description">Save an XML node tree to a string.</p> <p class="description">Save an XML node tree to a string.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description">Size of string</p> <p class="description">Size of string</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">This function returns the total number of bytes that would be <p class="discussion">This function saves the XML tree <code>node</code> to a string buffer.<br>
required for the string but only copies (bufsize - 1) characters
into the specified buffer.<br>
<br> <br>
The callback argument specifies a function that returns a whitespace The callback function <code>save_cb</code> specifies a function that returns a
string or NULL before and after each element. If <code>MXML_NO_CALLBACK</code> whitespace string or <code>NULL</code> before and after each element. The function
is specified, whitespace will only be added before <code>MXML_TYPE_TEXT</code> nodes receives the callback data pointer <code>save_cbdata</code>, the <code>mxml_node_t</code> pointer,
with leading whitespace and before attribute names inside opening and a &quot;when&quot; value indicating where the whitespace is being added, for
element tags.</p> 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> <h3 class="function"><a id="mxmlSetCDATA">mxmlSetCDATA</a></h3>
<p class="description">Set the data for a CDATA node.</p> <p class="description">Set the data for a CDATA node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <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="description">Set the data for a CDATA to a formatted string.</p>
<p class="code"> <p class="code">
@ -2574,6 +2745,9 @@ bool mxmlSetCDATAf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *for
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <h3 class="function"><a id="mxmlSetComment">mxmlSetComment</a></h3>
<p class="description">Set a comment to a literal string.</p> <p class="description">Set a comment to a literal string.</p>
<p class="code"> <p class="code">
@ -2587,6 +2761,8 @@ bool mxmlSetComment(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *co
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <h3 class="function"><a id="mxmlSetCommentf">mxmlSetCommentf</a></h3>
<p class="description">Set a comment to a formatted string.</p> <p class="description">Set a comment to a formatted string.</p>
<p class="code"> <p class="code">
@ -2602,25 +2778,29 @@ bool mxmlSetCommentf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *f
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <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="description">Set the data and destructor of a custom data node.</p>
<p class="code"> <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> <h4 class="parameters">Parameters</h4>
<table class="list"><tbody> <table class="list"><tbody>
<tr><th>node</th> <tr><th>node</th>
<td class="description">Node to set</td></tr> <td class="description">Node to set</td></tr>
<tr><th>data</th> <tr><th>data</th>
<td class="description">New data pointer</td></tr> <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> <td class="description">New destructor function</td></tr>
</tbody></table> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <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"> <p class="code">
bool mxmlSetDeclaration(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *declaration);</p> bool mxmlSetDeclaration(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *declaration);</p>
<h4 class="parameters">Parameters</h4> <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> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <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"> <p class="code">
bool mxmlSetDeclarationf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p> bool mxmlSetDeclarationf(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p>
<h4 class="parameters">Parameters</h4> <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> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <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"> <p class="code">
bool mxmlSetDirective(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *directive);</p> bool mxmlSetDirective(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *directive);</p>
<h4 class="parameters">Parameters</h4> <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> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <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"> <p class="code">
bool mxmlSetDirectivef(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p> bool mxmlSetDirectivef(<a href="#mxml_node_t">mxml_node_t</a> *node, const char *format, ...);</p>
<h4 class="parameters">Parameters</h4> <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> </tbody></table>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <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> <h3 class="function"><a id="mxmlSetElement">mxmlSetElement</a></h3>
<p class="description">Set the name of an element node.</p> <p class="description">Set the name of an element node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlSetInteger">mxmlSetInteger</a></h3>
<p class="description">Set the value of an integer node.</p> <p class="description">Set the value of an integer node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlSetOpaque">mxmlSetOpaque</a></h3>
<p class="description">Set the value of an opaque node.</p> <p class="description">Set the value of an opaque node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <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="description">Set the value of an opaque string node to a formatted string.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <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"> <p class="code">
bool mxmlSetReal(<a href="#mxml_node_t">mxml_node_t</a> *node, double real);</p> bool mxmlSetReal(<a href="#mxml_node_t">mxml_node_t</a> *node, double real);</p>
<h4 class="parameters">Parameters</h4> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlSetText">mxmlSetText</a></h3>
<p class="description">Set the value of a text node.</p> <p class="description">Set the value of a text node.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <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="description">Set the value of a text node to a formatted string.</p>
<p class="code"> <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> <h4 class="returnvalue">Return Value</h4>
<p class="description"><code>true</code> on success, <code>false</code> on failure</p> <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlSetUserData">mxmlSetUserData</a></h3>
<p class="description">Set the user data pointer for a node.</p> <p class="description">Set the user data pointer for a node.</p>
<p class="code"> <p class="code">
@ -2811,7 +3007,8 @@ void mxmlSetWrapMargin(int column);</p>
<td class="description">Column for wrapping, 0 to disable wrapping</td></tr> <td class="description">Column for wrapping, 0 to disable wrapping</td></tr>
</tbody></table> </tbody></table>
<h4 class="discussion">Discussion</h4> <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> <h3 class="function"><a id="mxmlWalkNext">mxmlWalkNext</a></h3>
<p class="description">Walk to the next logical node in the tree.</p> <p class="description">Walk to the next logical node in the tree.</p>
<p class="code"> <p class="code">
@ -2828,9 +3025,9 @@ void mxmlSetWrapMargin(int column);</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Next node or <code>NULL</code></p> <p class="description">Next node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The descend argument controls whether the first child is considered <p class="discussion">This function walks to the next logical node in the tree. The <code>descend</code>
to be the next node. The top node argument constrains the walk to argument controls whether the first child is considered to be the next node.
the node's children.</p> The <code>top</code> argument constrains the walk to that node's children.</p>
<h3 class="function"><a id="mxmlWalkPrev">mxmlWalkPrev</a></h3> <h3 class="function"><a id="mxmlWalkPrev">mxmlWalkPrev</a></h3>
<p class="description">Walk to the previous logical node in the tree.</p> <p class="description">Walk to the previous logical node in the tree.</p>
<p class="code"> <p class="code">
@ -2847,9 +3044,9 @@ the node's children.</p>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Previous node or <code>NULL</code></p> <p class="description">Previous node or <code>NULL</code></p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">The descend argument controls whether the previous node's last child <p class="discussion">This function walks to the previous logical node in the tree. The <code>descend</code>
is considered to be the previous node. The top node argument constrains argument controls whether the first child is considered to be the next node.
the walk to the node's children.</p> The <code>top</code> argument constrains the walk to that node's children.</p>
<h2 class="title"><a id="TYPES">Data Types</a></h2> <h2 class="title"><a id="TYPES">Data Types</a></h2>
<h3 class="typedef"><a id="mxml_add_t">mxml_add_t</a></h3> <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> <p class="description"><a href="#mxmlAdd"><code>mxmlAdd</code></a> add values</p>

44
mxml-attr.c
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 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 // This function gets the value for the attribute `name` from the element
// named attribute does not exist. // `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 mxmlElementGetAttr(mxml_node_t *node, // I - Element node
const char *name) // I - Name of attribute 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 // This function returned the Nth (`idx`) attribute for element `node`. The
// is out of range. // 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 const char * // O - Attribute value
mxmlElementGetAttrByIndex( mxmlElementGetAttrByIndex(
mxml_node_t *node, // I - Node mxml_node_t *node, // I - Node
int idx, // I - Attribute index, starting at 0 int idx, // I - Attribute index, starting at `0`
const char **name) // O - Attribute name 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) if (!node || node->type != MXML_TYPE_ELEMENT || idx < 0 || idx >= node->value.element.num_attrs)
return (NULL); return (NULL);
@ -128,6 +132,10 @@ mxmlElementGetAttrByIndex(
// //
// 'mxmlElementGetAttrCount()' - Get the number of element attributes. // '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 size_t // O - Number of attributes
mxmlElementGetAttrCount( 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 // This function sets attribute `name` to the string `value` for the element
// is replaced by the new string value. The string value is copied // `node`. If the named attribute already exists, the value of the attribute
// into the element node. This function does nothing if the node is // is replaced by the new string value. The string value is copied.
// not an element.
// //
void void
@ -184,10 +191,9 @@ mxmlElementSetAttr(mxml_node_t *node, // I - Element node
// //
// 'mxmlElementSetAttrf()' - Set an attribute with a formatted value. // 'mxmlElementSetAttrf()' - Set an attribute with a formatted value.
// //
// If the named attribute already exists, the value of the attribute // This function sets attribute `name` to the formatted value of `format` for
// is replaced by the new formatted string. The formatted string value is // the element `node`. If the named attribute already exists, the value of the
// copied into the element node. This function does nothing if the node // attribute is replaced by the new formatted string value.
// is not an element.
// //
void void

16
mxml-entity.c
View File

@ -15,6 +15,22 @@
// //
// 'mxmlEntityAddCallback()' - Add a callback to convert entities to Unicode. // '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 bool // O - `true` on success, `false` on failure
mxmlEntityAddCallback( mxmlEntityAddCallback(

299
mxml-file.c
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. // 'mxmlLoadFd()' - Load a file descriptor into an XML node tree.
// //
// The nodes in the specified file are added to the specified top node. // This function loads the file descriptor `fd` into an XML node tree. The
// If no top node is provided, the XML file MUST be well-formed with a // nodes in the specified file are added to the specified node `top`. If `NULL`
// single parent node like <?xml> for the entire file. The callback // is provided, the XML file MUST be well-formed with a single parent processing
// function returns the value type that should be used for child nodes. // instruction node like `<?xml version="1.0"?>` at the start of the file.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, //
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for // The load callback function `load_cb` is called to obtain the node type that
// loading child (data) nodes of the specified type. // 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 // 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 // to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
// text as a series of whitespace-delimited words, instead of using the // 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 // `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
// (including whitespace). // (including whitespace).
// //
@ -107,18 +113,24 @@ mxmlLoadFd(
// //
// 'mxmlLoadFile()' - Load a file into an XML node tree. // 'mxmlLoadFile()' - Load a file into an XML node tree.
// //
// The nodes in the specified file are added to the specified top node. // This function loads the `FILE` pointer `fp` into an XML node tree. The
// If no top node is provided, the XML file MUST be well-formed with a // nodes in the specified file are added to the specified node `top`. If `NULL`
// single parent node like <?xml> for the entire file. The callback // is provided, the XML file MUST be well-formed with a single parent processing
// function returns the value type that should be used for child nodes. // instruction node like `<?xml version="1.0"?>` at the start of the file.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, //
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for // The load callback function `load_cb` is called to obtain the node type that
// loading child (data) nodes of the specified type. // 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 // 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 // to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
// text as a series of whitespace-delimited words, instead of using the // 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 // `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
// (including whitespace). // (including whitespace).
// //
@ -143,18 +155,24 @@ mxmlLoadFile(
// //
// 'mxmlLoadFilename()' - Load a file into an XML node tree. // 'mxmlLoadFilename()' - Load a file into an XML node tree.
// //
// The nodes in the specified file are added to the specified top node. // This function loads the named file `filename` into an XML node tree. The
// If no top node is provided, the XML file MUST be well-formed with a // nodes in the specified file are added to the specified node `top`. If `NULL`
// single parent node like <?xml> for the entire file. The callback // is provided, the XML file MUST be well-formed with a single parent processing
// function returns the value type that should be used for child nodes. // instruction node like `<?xml version="1.0"?>` at the start of the file.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, //
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for // The load callback function `load_cb` is called to obtain the node type that
// loading child (data) nodes of the specified type. // 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 // 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 // to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
// text as a series of whitespace-delimited words, instead of using the // 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 // `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
// (including whitespace). // (including whitespace).
// //
@ -192,18 +210,37 @@ mxmlLoadFilename(
// //
// 'mxmlLoadIO()' - Load an XML node tree using a read callback. // 'mxmlLoadIO()' - Load an XML node tree using a read callback.
// //
// The nodes in the specified file are added to the specified top node. // This function loads data into an XML node tree using a read callback. The
// If no top node is provided, the XML file MUST be well-formed with a // nodes in the specified file are added to the specified node `top`. If `NULL`
// single parent node like <?xml> for the entire file. The callback // is provided, the XML file MUST be well-formed with a single parent processing
// function returns the value type that should be used for child nodes. // instruction node like `<?xml version="1.0"?>` at the start of the file.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, //
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for // The read callback function `read_cb` is called to read a number of bytes from
// loading child (data) nodes of the specified type. // 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 // 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 // to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
// text as a series of whitespace-delimited words, instead of using the // 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 // `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
// (including whitespace). // (including whitespace).
// //
@ -229,18 +266,24 @@ mxmlLoadIO(
// //
// 'mxmlLoadString()' - Load a string into an XML node tree. // 'mxmlLoadString()' - Load a string into an XML node tree.
// //
// The nodes in the specified string are added to the specified top node. // This function loads the string into an XML node tree. The nodes in the
// If no top node is provided, the XML string MUST be well-formed with a // specified file are added to the specified node `top`. If `NULL` is provided,
// single parent node like <?xml> for the entire string. The callback // the XML file MUST be well-formed with a single parent processing instruction
// function returns the value type that should be used for child nodes. // node like `<?xml version="1.0"?>` at the start of the file.
// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, //
// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for // The load callback function `load_cb` is called to obtain the node type that
// loading child (data) nodes of the specified type. // 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 // 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 // to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
// text as a series of whitespace-delimited words, instead of using the // 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 // `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
// (including whitespace). // (including whitespace).
// //
@ -274,16 +317,28 @@ mxmlLoadString(
// //
// 'mxmlSaveAllocString()' - Save an XML tree to an allocated string. // 'mxmlSaveAllocString()' - Save an XML tree to an allocated string.
// //
// This function returns a pointer to a string containing the textual // This function saves the XML tree `node` to an allocated string. The string
// representation of the XML node tree. The string should be freed // should be freed using `free` (or the string free callback set using
// using `free()` when you are done with it. `NULL` is returned if the node // @link mxmlSetStringCallbacks@) when you are done with it.
// would produce an empty string or if the string cannot be allocated.
// //
// The callback argument specifies a function that returns a whitespace // `NULL` is returned if the node would produce an empty string or if the string
// string or `NULL` before and after each element. If `MXML_NO_CALLBACK` // cannot be allocated.
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes //
// with leading whitespace and before attribute names inside opening // The callback function `save_cb` specifies a function that returns a
// element tags. // 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` char * // O - Allocated string or `NULL`
@ -323,11 +378,23 @@ mxmlSaveAllocString(
// //
// 'mxmlSaveFd()' - Save an XML tree to a file descriptor. // 'mxmlSaveFd()' - Save an XML tree to a file descriptor.
// //
// The callback argument specifies a function that returns a whitespace // This function saves the XML tree `node` to a file descriptor.
// string or NULL before and after each element. If `MXML_NO_CALLBACK` //
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes // The callback function `save_cb` specifies a function that returns a
// with leading whitespace and before attribute names inside opening // whitespace string or `NULL` before and after each element. The function
// element tags. // 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. 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. // 'mxmlSaveFile()' - Save an XML tree to a file.
// //
// The callback argument specifies a function that returns a whitespace // This function saves the XML tree `node` to a stdio `FILE`.
// string or NULL before and after each element. If `MXML_NO_CALLBACK` //
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes // The callback function `save_cb` specifies a function that returns a
// with leading whitespace and before attribute names inside opening // whitespace string or `NULL` before and after each element. The function
// element tags. // 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. bool // O - `true` on success, `false` on error.
@ -396,11 +475,23 @@ mxmlSaveFile(
// //
// 'mxmlSaveFilename()' - Save an XML tree to a file. // 'mxmlSaveFilename()' - Save an XML tree to a file.
// //
// The callback argument specifies a function that returns a whitespace // This function saves the XML tree `node` to a named file.
// string or NULL before and after each element. If `MXML_NO_CALLBACK` //
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes // The callback function `save_cb` specifies a function that returns a
// with leading whitespace and before attribute names inside opening // whitespace string or `NULL` before and after each element. The function
// element tags. // 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. bool // O - `true` on success, `false` on error.
@ -442,11 +533,34 @@ mxmlSaveFilename(
// //
// 'mxmlSaveIO()' - Save an XML tree using a callback. // 'mxmlSaveIO()' - Save an XML tree using a callback.
// //
// The callback argument specifies a function that returns a whitespace // This function saves the XML tree `node` using a write callback function
// string or NULL before and after each element. If `MXML_NO_CALLBACK` // `write_cb`. The write callback is called with the callback data pointer
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes // `write_cbdata`, a buffer pointer, and the number of bytes to write, for
// with leading whitespace and before attribute names inside opening // example:
// element tags. //
// ```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. bool // O - `true` on success, `false` on error.
@ -484,15 +598,23 @@ mxmlSaveIO(
// //
// 'mxmlSaveString()' - Save an XML node tree to a string. // 'mxmlSaveString()' - Save an XML node tree to a string.
// //
// This function returns the total number of bytes that would be // This function saves the XML tree `node` to a string buffer.
// required for the string but only copies (bufsize - 1) characters
// into the specified buffer.
// //
// The callback argument specifies a function that returns a whitespace // The callback function `save_cb` specifies a function that returns a
// string or NULL before and after each element. If `MXML_NO_CALLBACK` // whitespace string or `NULL` before and after each element. The function
// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes // receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
// with leading whitespace and before attribute names inside opening // and a "when" value indicating where the whitespace is being added, for
// element tags. // 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 size_t // O - Size of string
@ -530,7 +652,8 @@ mxmlSaveString(
// //
// 'mxmlSetWrapMargin()' - Set the wrap margin when saving XML data. // '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 void

56
mxml-get.c
View File

@ -15,7 +15,8 @@
// //
// 'mxmlGetCDATA()' - Get the value for a CDATA node. // '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` 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. // '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` 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. // 'mxmlGetCustom()' - Get the value for a custom node.
// //
// `NULL` is returned if the node (or its first child) is not a custom // This function gets the binary value of a custom node. `NULL` is returned if
// value node. // the node (or its first child) is not a custom value node.
// //
const void * // O - Custom value or `NULL` 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. // '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` 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. // '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` 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. // '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` 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. // 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 // 'mxmlGetInteger()' - Get the integer value from the specified node or its
// first child. // 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` 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. // 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. // '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 * 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. // '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 // This function gets the string value of an opaque node. `NULL` is returned if
// value node. // the node (or its first child) is not an opaque value node.
// //
const char * // O - Opaque string or `NULL` 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. // '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` 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. // '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` 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. // '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 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. // '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. // This function gets the string and whitespace values of a text node. `NULL`
// The "whitespace" argument can be `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 // 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. // 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. // '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 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. // 'mxmlGetUserData()' - Get the user data pointer for a node.
// //
// This function gets the user data pointer associated with `node`.
//
void * // O - User data pointer void * // O - User data pointer
mxmlGetUserData(mxml_node_t *node) // I - Node to get mxmlGetUserData(mxml_node_t *node) // I - Node to get

21
mxml-index.c
View File

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

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

36
mxml-search.c
View File

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

63
mxml-set.c
View File

@ -15,7 +15,8 @@
// //
// 'mxmlSetCDATA()' - Set the data for a CDATA node. // '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 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. // '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 bool // O - `true` on success, `false` on failure
mxmlSetCDATAf(mxml_node_t *node, // I - Node 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. // '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 bool // O - `true` on success, `false` on failure
mxmlSetComment(mxml_node_t *node, // I - Node 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. // '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 bool // O - `true` on success, `false` on failure
mxmlSetCommentf(mxml_node_t *node, // I - Node 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. // '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 bool // O - `true` on success, `false` on failure
mxmlSetCustom( mxmlSetCustom(
mxml_node_t *node, // I - Node to set mxml_node_t *node, // I - Node to set
void *data, // I - New data pointer 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... // Range check input...
if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_CUSTOM) 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) if (data == node->value.custom.data)
{ {
node->value.custom.destroy = destroy; node->value.custom.destroy = destroy_cb;
return (true); return (true);
} }
@ -230,14 +240,16 @@ mxmlSetCustom(
(*(node->value.custom.destroy))(node->value.custom.data); (*(node->value.custom.destroy))(node->value.custom.data);
node->value.custom.data = data; node->value.custom.data = data;
node->value.custom.destroy = destroy; node->value.custom.destroy = destroy_cb;
return (true); 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 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 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 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 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. // '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 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. // '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 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. // '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 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. // '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 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 bool // O - `true` on success, `false` on failure
mxmlSetReal(mxml_node_t *node, // I - Node to set mxmlSetReal(mxml_node_t *node, // I - Node to set
double real) // I - Real number value 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) if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_REAL)
node = node->child; node = node->child;
@ -613,7 +634,8 @@ mxmlSetReal(mxml_node_t *node, // I - Node to set
// //
// 'mxmlSetText()' - Set the value of a text node. // '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 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. // '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. // The node is not changed if it (or its first child) is not a text node.
// //