From 143fa436ca3ba642e1edf46cc4e75eddbd4db209 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Sat, 16 Mar 2024 22:20:24 -0400 Subject: [PATCH] More doco updates. --- doc/mxml.3 | 552 ++++++++++++++++++++++++++++++++----------------- doc/mxml.epub | Bin 720900 -> 722302 bytes doc/mxml.html | 553 ++++++++++++++++++++++++++++++++++---------------- mxml-attr.c | 44 ++-- mxml-entity.c | 16 ++ mxml-file.c | 299 +++++++++++++++++++-------- mxml-get.c | 56 +++-- mxml-index.c | 21 +- mxml-node.c | 15 +- mxml-search.c | 36 ++-- mxml-set.c | 63 ++++-- 11 files changed, 1116 insertions(+), 539 deletions(-) diff --git a/doc/mxml.3 b/doc/mxml.3 index 8578aa1..0fdfd7e 100644 --- a/doc/mxml.3 +++ b/doc/mxml.3 @@ -1,4 +1,4 @@ -.TH mxml 3 "Mini-XML API" "2024-03-13" "Mini-XML API" +.TH mxml 3 "Mini-XML API" "2024-03-16" "Mini-XML API" .SH NAME mxml \- Mini-XML API .SH INCLUDE FILE @@ -314,11 +314,11 @@ void mxmlAdd ( ); .fi .PP -Adds the specified node to the parent. If the child argument is not -\fBNULL\fR, puts the new node before or after the specified child depending -on the value of the \fBadd\fR argument. If the child argument is \fBNULL\fR, -puts the new node at the beginning of the child list (\fBMXML_ADD_BEFORE\fR) -or at the end of the child list (\fBMXML_ADD_AFTER\fR). +This function adds the specified node \fBnode\fR to the parent. If the \fBchild\fR +argument is not \fBNULL\fR, the new node is added before or after the specified +child depending on the value of the \fBadd\fR argument. If the \fBchild\fR argument +is \fBNULL\fR, the new node is placed at the beginning of the child list +(\fBMXML_ADD_BEFORE\fR) or at the end of the child list (\fBMXML_ADD_AFTER\fR). .SS mxmlDelete Delete a node and all of its children. .PP @@ -328,10 +328,11 @@ void mxmlDelete ( ); .fi .PP -If the specified node has a parent, this function first removes the -node from its parent using the \fImxmlRemove\fR function. +This function deletes the node \fBnode\fR and all of its children. If the +specified node has a parent, this function first removes the node from its +parent using the \fImxmlRemove\fR function. .SS mxmlElementClearAttr -Delete an attribute. +Remove an attribute from an element. .PP .nf void mxmlElementClearAttr ( @@ -339,8 +340,10 @@ void mxmlElementClearAttr ( const char *name ); .fi +.PP +This function removes the attribute \fBname\fR from the element \fBnode\fR. .SS mxmlElementGetAttr -Get an attribute. +Get the value of an attribute. .PP .nf const char * mxmlElementGetAttr ( @@ -349,10 +352,11 @@ const char * mxmlElementGetAttr ( ); .fi .PP -This function returns \fBNULL\fR if the node is not an element or the -named attribute does not exist. +This function gets the value for the attribute \fBname\fR from the element +\fBnode\fR. \fBNULL\fR is returned if the node is not an element or the named +attribute does not exist. .SS mxmlElementGetAttrByIndex -Get an element attribute by index. +Get an attribute by index. .PP .nf const char * mxmlElementGetAttrByIndex ( @@ -362,8 +366,9 @@ const char * mxmlElementGetAttrByIndex ( ); .fi .PP -The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index -is out of range. +This function returned the Nth (\fBidx\fR) attribute for element \fBnode\fR. The +attribute name is optionallly returned in the \fBname\fR argument. \fBNULL\fR is +returned if node is not an element or the specified index is out of range. .SS mxmlElementGetAttrCount Get the number of element attributes. .PP @@ -372,8 +377,12 @@ size_t mxmlElementGetAttrCount ( mxml_node_t *node ); .fi +.PP +This function returns the number of attributes for the element \fBnode\fR. \fB0\fR +is returned if the node is not an element or there are no attributes for the +element. .SS mxmlElementSetAttr -Set an attribute. +Set an attribute for an element. .PP .nf void mxmlElementSetAttr ( @@ -383,10 +392,9 @@ void mxmlElementSetAttr ( ); .fi .PP -If the named attribute already exists, the value of the attribute -is replaced by the new string value. The string value is copied -into the element node. This function does nothing if the node is -not an element. +This function sets attribute \fBname\fR to the string \fBvalue\fR for the element +\fBnode\fR. If the named attribute already exists, the value of the attribute +is replaced by the new string value. The string value is copied. .SS mxmlElementSetAttrf Set an attribute with a formatted value. .PP @@ -399,10 +407,9 @@ void mxmlElementSetAttrf ( ); .fi .PP -If the named attribute already exists, the value of the attribute -is replaced by the new formatted string. The formatted string value is -copied into the element node. This function does nothing if the node -is not an element. +This function sets attribute \fBname\fR to the formatted value of \fBformat\fR for +the element \fBnode\fR. If the named attribute already exists, the value of the +attribute is replaced by the new formatted string value. .SS mxmlEntityAddCallback Add a callback to convert entities to Unicode. .PP @@ -412,6 +419,22 @@ bool mxmlEntityAddCallback ( void *cbdata ); .fi +.PP +This function adds a callback to the current thread that converts named +XML character entities to Unicode characters. The callback function \fBcb\fR +accepts the callback data pointer \fBcbdata\fR and the entity name and returns a +Unicode character value or \fB-1\fR if the entity is not known. For example, the +following entity callback supports the "euro" entity: +.PP +\fB`\fRc +int my_entity_cb(void \fIcbdata, const char \fRname) +{ + if (!strcmp(name, "euro")) + return (0x20ac); + else + return (-1); +} +\fB`\fR .SS mxmlEntityGetValue Get the character corresponding to a named entity. .PP @@ -445,14 +468,15 @@ mxml_node_t * mxmlFindElement ( ); .fi .PP -The search is constrained by the name, attribute name, and value; any -\fBNULL\fR names or values are treated as wildcards, so different kinds of -searches can be implemented by looking for all elements of a given name -or all elements with a specific attribute. The descend argument determines -whether the search descends into child nodes; normally you will use -\fBMXML_DESCEND_FIRST\fR for the initial search and \fBMXML_NO_DESCEND\fR -to find additional direct descendents of the node. The top node argument -constrains the search to a particular node's children. +This function finds the named element \fBelement\fR in XML tree \fBtop\fR starting at +node \fBnode\fR. The search is constrained by element name \fBelement\fR, attribute +name \fBattr\fR, and attribute value \fBvalue\fR - \fBNULL\fR names or values are treated +as wildcards, so different kinds of searches can be implemented by looking +for all elements of a given name or all elements with a specific attribute. +.PP +The \fBdescend\fR argument determines whether the search descends into child +nodes; normally you will use \fBMXML_DESCEND_FIRST\fR for the initial search and +\fBMXML_DESCEND_NONE\fR to find additional direct descendents of the node. .SS mxmlFindPath Find a node with the given path. .PP @@ -463,9 +487,10 @@ mxml_node_t * mxmlFindPath ( ); .fi .PP -The "path" is a slash-separated list of element names. The name "\fI" is -considered a wildcard for one or more levels of elements. For example, -"foo/one/two", "bar/two/one", "\fR/one", and so forth. +This function finds a node in XML tree \fBtop\fR using a slash-separated list of +element names in \fBpath\fR. The name "\fI" is considered a wildcard for one or +more levels of elements, for example, "foo/one/two", "bar/two/one", "\fR/one", +and so forth. .PP The first child node of the found node is returned if the given node has children and the first child is a value node. @@ -478,7 +503,8 @@ const char * mxmlGetCDATA ( ); .fi .PP -\fBNULL\fR is returned if the node is not a CDATA element. +This function gets the string value of a CDATA node. \fBNULL\fR is returned if +the node is not a CDATA element. .SS mxmlGetComment Get the value for a comment node. .PP @@ -488,7 +514,8 @@ const char * mxmlGetComment ( ); .fi .PP -\fBNULL\fR is returned if the node is not a comment. +This function gets the string value of a comment node. \fBNULL\fR is returned +if the node is not a comment. .SS mxmlGetCustom Get the value for a custom node. .PP @@ -498,8 +525,8 @@ const void * mxmlGetCustom ( ); .fi .PP -\fBNULL\fR is returned if the node (or its first child) is not a custom -value node. +This function gets the binary value of a custom node. \fBNULL\fR is returned if +the node (or its first child) is not a custom value node. .SS mxmlGetDeclaration Get the value for a declaration node. .PP @@ -509,7 +536,8 @@ const char * mxmlGetDeclaration ( ); .fi .PP -\fBNULL\fR is returned if the node is not a declaration. +This function gets the string value of a declaraction node. \fBNULL\fR is +returned if the node is not a declaration. .SS mxmlGetDirective Get the value for a processing instruction node. .PP @@ -519,7 +547,8 @@ const char * mxmlGetDirective ( ); .fi .PP -\fBNULL\fR is returned if the node is not a processing instruction. +This function gets the string value of a processing instruction. \fBNULL\fR is +returned if the node is not a processing instruction. .SS mxmlGetElement Get the name for an element node. .PP @@ -529,9 +558,10 @@ const char * mxmlGetElement ( ); .fi .PP -\fBNULL\fR is returned if the node is not an element node. +This function gets the name of an element node. \fBNULL\fR is returned if the +node is not an element node. .SS mxmlGetFirstChild -Get the first child of an element node. +Get the first child of a node. .PP .nf mxml_node_t * mxmlGetFirstChild ( @@ -539,7 +569,7 @@ mxml_node_t * mxmlGetFirstChild ( ); .fi .PP -\fBNULL\fR is returned if the node is not an element node or if the node +This function gets the first child of a node. \fBNULL\fR is returned if the node has no children. .SS mxmlGetInteger Get the integer value from the specified node or its @@ -551,9 +581,10 @@ long mxmlGetInteger ( ); .fi .PP -\fB0\fR is returned if the node (or its first child) is not an integer value node. +This function gets the value of an integer node. \fB0\fR is returned if the node +(or its first child) is not an integer value node. .SS mxmlGetLastChild -Get the last child of an element node. +Get the last child of a node. .PP .nf mxml_node_t * mxmlGetLastChild ( @@ -561,7 +592,7 @@ mxml_node_t * mxmlGetLastChild ( ); .fi .PP -\fBNULL\fR is returned if the node is not an element node or if the node +This function gets the last child of a node. \fBNULL\fR is returned if the node has no children. .SS mxmlGetNextSibling @@ -580,8 +611,8 @@ const char * mxmlGetOpaque ( ); .fi .PP -\fBNULL\fR is returned if the node (or its first child) is not an opaque -value node. +This function gets the string value of an opaque node. \fBNULL\fR is returned if +the node (or its first child) is not an opaque value node. .SS mxmlGetParent Get the parent node. .PP @@ -591,7 +622,7 @@ mxml_node_t * mxmlGetParent ( ); .fi .PP -\fBNULL\fR is returned for a root node. +This function gets the parent of a node. \fBNULL\fR is returned for a root node. .SS mxmlGetPrevSibling Get the previous node for the current parent. .PP @@ -601,7 +632,8 @@ mxml_node_t * mxmlGetPrevSibling ( ); .fi .PP -\fBNULL\fR is returned if this is the first child for the current parent. +This function gets the previous node for the current parent. \fBNULL\fR is +returned if this is the first child for the current parent. .SS mxmlGetReal Get the real value for a node or its first child. .PP @@ -611,7 +643,8 @@ double mxmlGetReal ( ); .fi .PP -0.0 is returned if the node (or its first child) is not a real value node. +This function gets the value of a real value node. \fB0.0\fR is returned if the +node (or its first child) is not a real value node. .SS mxmlGetRefCount Get the current reference (use) count for a node. .PP @@ -634,8 +667,10 @@ const char * mxmlGetText ( ); .fi .PP -\fBNULL\fR is returned if the node (or its first child) is not a text node. -The "whitespace" argument can be \fBNULL\fR. +This function gets the string and whitespace values of a text node. \fBNULL\fR +and \fBfalse\fR are returned if the node (or its first child) is not a text node. +The \fBwhitespace\fR argument can be \fBNULL\fR if you don't want to know the +whitespace value. .PP Note: Text nodes consist of whitespace-delimited words. You will only get single words of text when reading an XML file with \fBMXML_TYPE_TEXT\fR nodes. @@ -651,7 +686,8 @@ mxml_type_t mxmlGetType ( ); .fi .PP -\fBMXML_TYPE_IGNORE\fR is returned if "node" is \fBNULL\fR. +This function gets the type of \fBnode\fR. \fBMXML_TYPE_IGNORE\fR is returned if +\fBnode\fR is \fBNULL\fR. .SS mxmlGetUserData Get the user data pointer for a node. .PP @@ -660,6 +696,8 @@ void * mxmlGetUserData ( mxml_node_t *node ); .fi +.PP +This function gets the user data pointer associated with \fBnode\fR. .SS mxmlIndexDelete Delete an index. .PP @@ -677,6 +715,8 @@ mxml_node_t * mxmlIndexEnum ( ); .fi .PP +This function returns the next node in index \fBind\fR. +.PP You should call \fImxmlIndexReset\fR prior to using this function to get the first node in the index. Nodes are returned in the sorted order of the index. @@ -691,9 +731,11 @@ mxml_node_t * mxmlIndexFind ( ); .fi .PP +This function finds the next matching node in index \fBind\fR. +.PP You should call \fImxmlIndexReset\fR prior to using this function for -the first time with a particular set of "element" and "value" -strings. Passing \fBNULL\fR for both "element" and "value" is equivalent +the first time with a particular set of \fBelement\fR and \fBvalue\fR +strings. Passing \fBNULL\fR for both \fBelement\fR and \fBvalue\fR is equivalent to calling \fImxmlIndexEnum\fR. .SS mxmlIndexGetCount Get the number of nodes in an index. @@ -714,11 +756,13 @@ mxml_index_t * mxmlIndexNew ( ); .fi .PP +This function creates a new index for XML tree \fBnode\fR. +.PP The index will contain all nodes that contain the named element and/or -attribute. If both "element" and "attr" are \fBNULL\fR, then the index will +attribute. If both \fBelement\fR and \fBattr\fR are \fBNULL\fR, then the index will contain a sorted list of the elements in the node tree. Nodes are -sorted by element name and optionally by attribute value if the "attr" -argument is not NULL. +sorted by element name and optionally by attribute value if the \fBattr\fR +argument is not \fBNULL\fR. .SS mxmlIndexReset Reset the enumeration/find pointer in the index and return the first node in the index. @@ -729,8 +773,9 @@ mxml_node_t * mxmlIndexReset ( ); .fi .PP -This function should be called prior to using \fImxmlIndexEnum\fR or -\fImxmlIndexFind\fR for the first time. +This function resets the enumeration/find pointer in index \fBind\fR and should +be called prior to using \fImxmlIndexEnum\fR or \fImxmlIndexFind\fR for the +first time. .SS mxmlLoadFd Load a file descriptor into an XML node tree. .PP @@ -745,20 +790,24 @@ mxml_node_t * mxmlLoadFd ( ); .fi .PP -The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like -.URL ?xml ?xml - for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, -\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for -loading child (data) nodes of the specified type. +This function loads the file descriptor \fBfd\fR into an XML node tree. The +nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like \fB\fR at the start of the file. +.PP +The load callback function \fBload_cb\fR is called to obtain the node type that +should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points +to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR +if that argument is also \fBNULL\fR. +.PP +The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed. .PP Note: The most common programming error when using the Mini-XML library is -to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline -text as a series of whitespace-delimited words, instead of using the -\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string +to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string (including whitespace). .SS mxmlLoadFile Load a file into an XML node tree. @@ -774,20 +823,24 @@ mxml_node_t * mxmlLoadFile ( ); .fi .PP -The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like -.URL ?xml ?xml - for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, -\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for -loading child (data) nodes of the specified type. +This function loads the \fBFILE\fR pointer \fBfp\fR into an XML node tree. The +nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like \fB\fR at the start of the file. +.PP +The load callback function \fBload_cb\fR is called to obtain the node type that +should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points +to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR +if that argument is also \fBNULL\fR. +.PP +The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed. .PP Note: The most common programming error when using the Mini-XML library is -to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline -text as a series of whitespace-delimited words, instead of using the -\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string +to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string (including whitespace). .SS mxmlLoadFilename Load a file into an XML node tree. @@ -803,20 +856,24 @@ mxml_node_t * mxmlLoadFilename ( ); .fi .PP -The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like -.URL ?xml ?xml - for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, -\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for -loading child (data) nodes of the specified type. +This function loads the named file \fBfilename\fR into an XML node tree. The +nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like \fB\fR at the start of the file. +.PP +The load callback function \fBload_cb\fR is called to obtain the node type that +should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points +to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR +if that argument is also \fBNULL\fR. +.PP +The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed. .PP Note: The most common programming error when using the Mini-XML library is -to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline -text as a series of whitespace-delimited words, instead of using the -\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string +to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string (including whitespace). .SS mxmlLoadIO Load an XML node tree using a read callback. @@ -833,21 +890,40 @@ mxml_node_t * mxmlLoadIO ( ); .fi .PP -The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like -.URL ?xml ?xml - for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, -\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for -loading child (data) nodes of the specified type. +This function loads data into an XML node tree using a read callback. The +nodes in the specified file are added to the specified node \fBtop\fR. If \fBNULL\fR +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like \fB\fR at the start of the file. .PP -Note: The most common programming error when using the Mini-XML library is -to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline -text as a series of whitespace-delimited words, instead of using the -\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string -(including whitespace). +The read callback function \fBread_cb\fR is called to read a number of bytes from +the source. The callback data pointer \fBread_cbdata\fR is passed to the read +callback with a pointer to a buffer and the maximum number of bytes to read, +for example: +.PP +\fB`\fRc +ssize_t my_read_cb(void \fIcbdata, void \fRbuffer, size_t bytes) +{ + ... copy up to "bytes" bytes into buffer ... + ... return the number of bytes "read" or -1 on error ... +} +.nf + + The load callback function `load_cb` is called to obtain the node type that + should be used for child nodes. If `NULL`, the `load_cbdata` argument points + to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` + if that argument is also `NULL`. + + The SAX callback function `sax_cb` and associated callback data `sax_cbdata` + are used to enable the Simple API for XML streaming mode. The callback is + called as the XML node tree is parsed. + + Note: The most common programming error when using the Mini-XML library is + to load an XML file using the `MXML_TYPE_TEXT` node type, which returns + inline text as a series of whitespace-delimited words, instead of using the + `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string + (including whitespace). +.fi + .SS mxmlLoadString Load a string into an XML node tree. .PP @@ -862,20 +938,24 @@ mxml_node_t * mxmlLoadString ( ); .fi .PP -The nodes in the specified string are added to the specified top node. -If no top node is provided, the XML string MUST be well-formed with a -single parent node like -.URL ?xml ?xml - for the entire string. The callback -function returns the value type that should be used for child nodes. -The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, -\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for -loading child (data) nodes of the specified type. +This function loads the string into an XML node tree. The nodes in the +specified file are added to the specified node \fBtop\fR. If \fBNULL\fR is provided, +the XML file MUST be well-formed with a single parent processing instruction +node like \fB\fR at the start of the file. +.PP +The load callback function \fBload_cb\fR is called to obtain the node type that +should be used for child nodes. If \fBNULL\fR, the \fBload_cbdata\fR argument points +to a \fBmmd_type_t\fR variable that specifies the value type or \fBMMD_TYPE_TEXT\fR +if that argument is also \fBNULL\fR. +.PP +The SAX callback function \fBsax_cb\fR and associated callback data \fBsax_cbdata\fR +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed. .PP Note: The most common programming error when using the Mini-XML library is -to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline -text as a series of whitespace-delimited words, instead of using the -\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string +to load an XML file using the \fBMXML_TYPE_TEXT\fR node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +\fBMXML_TYPE_OPAQUE\fR node type which returns the inline text as a single string (including whitespace). .SS mxmlNewCDATA Create a new CDATA node. @@ -1162,16 +1242,28 @@ char * mxmlSaveAllocString ( ); .fi .PP -This function returns a pointer to a string containing the textual -representation of the XML node tree. The string should be freed -using \fBfree()\fR when you are done with it. \fBNULL\fR is returned if the node -would produce an empty string or if the string cannot be allocated. +This function saves the XML tree \fBnode\fR to an allocated string. The string +should be freed using \fBfree\fR (or the string free callback set using +\fImxmlSetStringCallbacks\fR) when you are done with it. .PP -The callback argument specifies a function that returns a whitespace -string or \fBNULL\fR before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +\fBNULL\fR is returned if the node would produce an empty string or if the string +cannot be allocated. +.PP +The callback function \fBsave_cb\fR specifies a function that returns a +whitespace string or \fBNULL\fR before and after each element. The function +receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer, +and a "when" value indicating where the whitespace is being added, for +example: +.PP +\fB`\fRc +const char \fImy_save_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +\fB`\fR .SS mxmlSaveFd Save an XML tree to a file descriptor. .PP @@ -1184,11 +1276,23 @@ bool mxmlSaveFd ( ); .fi .PP -The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +This function saves the XML tree \fBnode\fR to a file descriptor. +.PP +The callback function \fBsave_cb\fR specifies a function that returns a +whitespace string or \fBNULL\fR before and after each element. The function +receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer, +and a "when" value indicating where the whitespace is being added, for +example: +.PP +\fB`\fRc +const char \fImy_save_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +\fB`\fR .SS mxmlSaveFile Save an XML tree to a file. .PP @@ -1201,11 +1305,23 @@ bool mxmlSaveFile ( ); .fi .PP -The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +This function saves the XML tree \fBnode\fR to a stdio \fBFILE\fR. +.PP +The callback function \fBsave_cb\fR specifies a function that returns a +whitespace string or \fBNULL\fR before and after each element. The function +receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer, +and a "when" value indicating where the whitespace is being added, for +example: +.PP +\fB`\fRc +const char \fImy_save_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +\fB`\fR .SS mxmlSaveFilename Save an XML tree to a file. .PP @@ -1218,11 +1334,23 @@ bool mxmlSaveFilename ( ); .fi .PP -The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +This function saves the XML tree \fBnode\fR to a named file. +.PP +The callback function \fBsave_cb\fR specifies a function that returns a +whitespace string or \fBNULL\fR before and after each element. The function +receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer, +and a "when" value indicating where the whitespace is being added, for +example: +.PP +\fB`\fRc +const char \fImy_save_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +\fB`\fR .SS mxmlSaveIO Save an XML tree using a callback. .PP @@ -1236,11 +1364,36 @@ bool mxmlSaveIO ( ); .fi .PP -The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +This function saves the XML tree \fBnode\fR using a write callback function +\fBwrite_cb\fR. The write callback is called with the callback data pointer +\fBwrite_cbdata\fR, a buffer pointer, and the number of bytes to write, for +example: +.PP +\fB`\fRc +ssize_t my_write_cb(void \fIcbdata, const void \fRbuffer, size_t bytes) +{ + ... write/copy bytes from buffer to the output ... + ... return the number of bytes written/copied or -1 on error ... +} +.nf + + The callback function `save_cb` specifies a function that returns a + whitespace string or `NULL` before and after each element. The function + receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, + and a "when" value indicating where the whitespace is being added, for + example: + + ```c + const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) + { + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); + } + +.fi + .SS mxmlSaveString Save an XML node tree to a string. .PP @@ -1254,15 +1407,23 @@ size_t mxmlSaveString ( ); .fi .PP -This function returns the total number of bytes that would be -required for the string but only copies (bufsize - 1) characters -into the specified buffer. +This function saves the XML tree \fBnode\fR to a string buffer. .PP -The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR -is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes -with leading whitespace and before attribute names inside opening -element tags. +The callback function \fBsave_cb\fR specifies a function that returns a +whitespace string or \fBNULL\fR before and after each element. The function +receives the callback data pointer \fBsave_cbdata\fR, the \fBmxml_node_t\fR pointer, +and a "when" value indicating where the whitespace is being added, for +example: +.PP +\fB`\fRc +const char \fImy_save_cb(void \fRcbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +\fB`\fR .SS mxmlSetCDATA Set the data for a CDATA node. .PP @@ -1273,7 +1434,8 @@ bool mxmlSetCDATA ( ); .fi .PP -The node is not changed if it (or its first child) is not a CDATA node. +This function sets the value string for a CDATA node. The node is not +changed if it (or its first child) is not a CDATA node. .SS mxmlSetCDATAf Set the data for a CDATA to a formatted string. .PP @@ -1284,6 +1446,9 @@ bool mxmlSetCDATAf ( ... ); .fi +.PP +This function sets the formatted string value of a CDATA node. The node is +not changed if it (or its first child) is not a CDATA node. .SS mxmlSetComment Set a comment to a literal string. .PP @@ -1293,6 +1458,8 @@ bool mxmlSetComment ( const char *comment ); .fi +.PP +This function sets the string value of a comment node. .SS mxmlSetCommentf Set a comment to a formatted string. .PP @@ -1303,6 +1470,8 @@ bool mxmlSetCommentf ( ... ); .fi +.PP +This function sets the formatted string value of a comment node. .SS mxmlSetCustom Set the data and destructor of a custom data node. .PP @@ -1310,13 +1479,15 @@ Set the data and destructor of a custom data node. bool mxmlSetCustom ( mxml_node_t *node, void *data, - mxml_custom_destroy_cb_t destroy + mxml_custom_destroy_cb_t destroy_cb ); .fi .PP -The node is not changed if it (or its first child) is not a custom node. +This function sets the data pointer \fBdata\fR and destructor callback +\fBdestroy_cb\fR of a custom data node. The node is not changed if it (or its +first child) is not a custom node. .SS mxmlSetDeclaration -Set a comment to a literal string. +Set a declaration to a literal string. .PP .nf bool mxmlSetDeclaration ( @@ -1324,8 +1495,10 @@ bool mxmlSetDeclaration ( const char *declaration ); .fi +.PP +This function sets the string value of a declaration node. .SS mxmlSetDeclarationf -Set a comment to a formatted string. +Set a declaration to a formatted string. .PP .nf bool mxmlSetDeclarationf ( @@ -1334,8 +1507,10 @@ bool mxmlSetDeclarationf ( ... ); .fi +.PP +This function sets the formatted string value of a declaration node. .SS mxmlSetDirective -Set a directive to a literal string. +Set a processing instruction to a literal string. .PP .nf bool mxmlSetDirective ( @@ -1343,8 +1518,10 @@ bool mxmlSetDirective ( const char *directive ); .fi +.PP +This function sets the string value of a processing instruction node. .SS mxmlSetDirectivef -Set a directive to a formatted string. +Set a processing instruction to a formatted string. .PP .nf bool mxmlSetDirectivef ( @@ -1353,6 +1530,9 @@ bool mxmlSetDirectivef ( ... ); .fi +.PP +This function sets the formatted string value of a processing instruction +node. .SS mxmlSetElement Set the name of an element node. .PP @@ -1363,7 +1543,8 @@ bool mxmlSetElement ( ); .fi .PP -The node is not changed if it is not an element node. +This function sets the name of an element node. The node is not changed if +it is not an element node. .SS mxmlSetInteger Set the value of an integer node. .PP @@ -1374,7 +1555,8 @@ bool mxmlSetInteger ( ); .fi .PP -The node is not changed if it (or its first child) is not an integer node. +This function sets the value of an integer node. The node is not changed if +it (or its first child) is not an integer node. .SS mxmlSetOpaque Set the value of an opaque node. .PP @@ -1385,7 +1567,8 @@ bool mxmlSetOpaque ( ); .fi .PP -The node is not changed if it (or its first child) is not an opaque node. +This function sets the string value of an opaque node. The node is not +changed if it (or its first child) is not an opaque node. .SS mxmlSetOpaquef Set the value of an opaque string node to a formatted string. .PP @@ -1397,9 +1580,10 @@ bool mxmlSetOpaquef ( ); .fi .PP -The node is not changed if it (or its first child) is not an opaque node. +This function sets the formatted string value of an opaque node. The node is +not changed if it (or its first child) is not an opaque node. .SS mxmlSetReal -Set the value of a real number node. +Set the value of a real value node. .PP .nf bool mxmlSetReal ( @@ -1408,7 +1592,8 @@ bool mxmlSetReal ( ); .fi .PP -The node is not changed if it (or its first child) is not a real number node. +This function sets the value of a real value node. The node is not changed +if it (or its first child) is not a real value node. .SS mxmlSetText Set the value of a text node. .PP @@ -1420,7 +1605,8 @@ bool mxmlSetText ( ); .fi .PP -The node is not changed if it (or its first child) is not a text node. +This function sets the string and whitespace values of a text node. The node +is not changed if it (or its first child) is not a text node. .SS mxmlSetTextf Set the value of a text node to a formatted string. .PP @@ -1433,6 +1619,7 @@ bool mxmlSetTextf ( ); .fi .PP +This function sets the formatted string and whitespace values of a text node. The node is not changed if it (or its first child) is not a text node. .SS mxmlSetUserData Set the user data pointer for a node. @@ -1452,7 +1639,8 @@ void mxmlSetWrapMargin ( ); .fi .PP -Wrapping is disabled when "column" is 0. +This function sets the wrap margin used when saving XML data for the current +thread. Wrapping is disabled when \fBcolumn\fR is \fB0\fR. .SS mxmlWalkNext Walk to the next logical node in the tree. .PP @@ -1464,9 +1652,9 @@ mxml_node_t * mxmlWalkNext ( ); .fi .PP -The descend argument controls whether the first child is considered -to be the next node. The top node argument constrains the walk to -the node's children. +This function walks to the next logical node in the tree. The \fBdescend\fR +argument controls whether the first child is considered to be the next node. +The \fBtop\fR argument constrains the walk to that node's children. .SS mxmlWalkPrev Walk to the previous logical node in the tree. .PP @@ -1478,9 +1666,9 @@ mxml_node_t * mxmlWalkPrev ( ); .fi .PP -The descend argument controls whether the previous node's last child -is considered to be the previous node. The top node argument constrains -the walk to the node's children. +This function walks to the previous logical node in the tree. The \fBdescend\fR +argument controls whether the first child is considered to be the next node. +The \fBtop\fR argument constrains the walk to that node's children. .SH TYPES .SS mxml_add_t \fImxmlAdd\fR add values diff --git a/doc/mxml.epub b/doc/mxml.epub index 6101673b001962245daf4ec4770192c887ab2c1b..99721bc824e0c0431bf025f1bff2972692f856c1 100644 GIT binary patch delta 23315 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 LAsQC-t>J$F#ofl5 delta 21873 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 *parent, Node to add

Discussion

-

Adds the specified node to the parent. If the child argument is not -NULL, puts the new node before or after the specified child depending -on the value of the add argument. If the child argument is NULL, -puts the new node at the beginning of the child list (MXML_ADD_BEFORE) -or at the end of the child list (MXML_ADD_AFTER).

+

This function adds the specified node node to the parent. If the child +argument is not NULL, the new node is added before or after the specified +child depending on the value of the add argument. If the child argument +is NULL, the new node is placed at the beginning of the child list +(MXML_ADD_BEFORE) or at the end of the child list (MXML_ADD_AFTER).

mxmlDelete

Delete a node and all of its children.

@@ -1341,10 +1341,11 @@ void mxmlDelete(mxml_node_t *node);

Node to delete

Discussion

-

If the specified node has a parent, this function first removes the -node from its parent using the mxmlRemove function.

+

This function deletes the node node and all of its children. If the +specified node has a parent, this function first removes the node from its +parent using the mxmlRemove function.

mxmlElementClearAttr

-

Delete an attribute.

+

Remove an attribute from an element.

void mxmlElementClearAttr(mxml_node_t *node, const char *name);

Parameters

@@ -1354,8 +1355,10 @@ void mxmlElementClearAttr(mxml_node_t *node, const ch name Attribute name +

Discussion

+

This function removes the attribute name from the element node.

mxmlElementGetAttr

-

Get an attribute.

+

Get the value of an attribute.

const char *mxmlElementGetAttr(mxml_node_t *node, const char *name);

Parameters

@@ -1368,10 +1371,11 @@ const char *mxmlElementGetAttr(mxml_node_t *node, con

Return Value

Attribute value or NULL

Discussion

-

This function returns NULL if the node is not an element or the -named attribute does not exist.

+

This function gets the value for the attribute name from the element +node. NULL is returned if the node is not an element or the named +attribute does not exist.

mxmlElementGetAttrByIndex

-

Get an element attribute by index.

+

Get an attribute by index.

const char *mxmlElementGetAttrByIndex(mxml_node_t *node, int idx, const char **name);

Parameters

@@ -1379,15 +1383,16 @@ const char *mxmlElementGetAttrByIndex(mxml_node_t *no node Node idx -Attribute index, starting at 0 +Attribute index, starting at 0 name -Attribute name +Attribute name or NULL to not return it

Return Value

Attribute value

Discussion

-

The index ("idx") is 0-based. NULL is returned if the specified index -is out of range.

+

This function returned the Nth (idx) attribute for element node. The +attribute name is optionallly returned in the name argument. NULL is +returned if node is not an element or the specified index is out of range.

mxmlElementGetAttrCount

Get the number of element attributes.

@@ -1399,8 +1404,12 @@ size_t mxmlElementGetAttrCount(mxml_node_t *node);

Return Value

Number of attributes

+

Discussion

+

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.

mxmlElementSetAttr

-

Set an attribute.

+

Set an attribute for an element.

void mxmlElementSetAttr(mxml_node_t *node, const char *name, const char *value);

Parameters

@@ -1413,10 +1422,9 @@ void mxmlElementSetAttr(mxml_node_t *node, const char Attribute value

Discussion

-

If the named attribute already exists, the value of the attribute -is replaced by the new string value. The string value is copied -into the element node. This function does nothing if the node is -not an element.

+

This function sets attribute name to the string value for the element +node. If the named attribute already exists, the value of the attribute +is replaced by the new string value. The string value is copied.

mxmlElementSetAttrf

Set an attribute with a formatted value.

@@ -1433,10 +1441,9 @@ void mxmlElementSetAttrf(mxml_node_t *node, const cha Additional arguments as needed

Discussion

-

If the named attribute already exists, the value of the attribute -is replaced by the new formatted string. The formatted string value is -copied into the element node. This function does nothing if the node -is not an element.

+

This function sets attribute name to the formatted value of format for +the element node. If the named attribute already exists, the value of the +attribute is replaced by the new formatted string value.

mxmlEntityAddCallback

Add a callback to convert entities to Unicode.

@@ -1450,6 +1457,22 @@ bool mxmlEntityAddCallback(mxml_entity_cb_t cb,

Return Value

true on success, false on failure

+

Discussion

+

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); +} +`

mxmlEntityGetValue

Get the character corresponding to a named entity.

@@ -1495,14 +1518,15 @@ void mxmlEntityRemoveCallback(mxml_entity_cb_t c

Return Value

Element node or NULL

Discussion

-

The search is constrained by the name, attribute name, and value; any -NULL names or values are treated as wildcards, so different kinds of -searches can be implemented by looking for all elements of a given name -or all elements with a specific attribute. The descend argument determines -whether the search descends into child nodes; normally you will use -MXML_DESCEND_FIRST for the initial search and MXML_NO_DESCEND -to find additional direct descendents of the node. The top node argument -constrains the search to a particular node's children.

+

This function finds the named element element in XML tree top starting at +node node. The search is constrained by element name element, attribute +name attr, and attribute value value - NULL names or values are treated +as wildcards, so different kinds of searches can be implemented by looking +for all elements of a given name or all elements with a specific attribute.
+
+The descend argument determines whether the search descends into child +nodes; normally you will use MXML_DESCEND_FIRST for the initial search and +MXML_DESCEND_NONE to find additional direct descendents of the node.

mxmlFindPath

Find a node with the given path.

@@ -1517,9 +1541,10 @@ constrains the search to a particular node's children.

Return Value

Found node or NULL

Discussion

-

The "path" is a slash-separated list of element names. The name "" is -considered a wildcard for one or more levels of elements. For example, -"foo/one/two", "bar/two/one", "/one", and so forth.
+

This function finds a node in XML tree top using a slash-separated list of +element names in path. The name "" is considered a wildcard for one or +more levels of elements, for example, "foo/one/two", "bar/two/one", "/one", +and so forth.

The first child node of the found node is returned if the given node has children and the first child is a value node.

@@ -1535,7 +1560,8 @@ const char *mxmlGetCDATA(mxml_node_t *node);

Return Value

CDATA value or NULL

Discussion

-

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.

mxmlGetComment

Get the value for a comment node.

@@ -1548,7 +1574,8 @@ const char *mxmlGetComment(mxml_node_t *node);

Return Value

Comment value or NULL

Discussion

-

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.

mxmlGetCustom

Get the value for a custom node.

@@ -1561,8 +1588,8 @@ const void *mxmlGetCustom(mxml_node_t *node);

Return Value

Custom value or NULL

Discussion

-

NULL is returned if the node (or its first child) is not a custom -value node.

+

This function gets the binary value of a custom node. NULL is returned if +the node (or its first child) is not a custom value node.

mxmlGetDeclaration

Get the value for a declaration node.

@@ -1575,7 +1602,8 @@ const char *mxmlGetDeclaration(mxml_node_t *node);

Return Value

Declaraction value or NULL

Discussion

-

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.

mxmlGetDirective

Get the value for a processing instruction node.

@@ -1588,7 +1616,8 @@ const char *mxmlGetDirective(mxml_node_t *node);

Return Value

Comment value or NULL

Discussion

-

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.

mxmlGetElement

Get the name for an element node.

@@ -1601,9 +1630,10 @@ const char *mxmlGetElement(mxml_node_t *node);

Return Value

Element name or NULL

Discussion

-

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.

mxmlGetFirstChild

-

Get the first child of an element node.

+

Get the first child of a node.

mxml_node_t *mxmlGetFirstChild(mxml_node_t *node);

Parameters

@@ -1614,7 +1644,7 @@ const char *mxmlGetElement(mxml_node_t *node);

Return Value

First child or NULL

Discussion

-

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.

mxmlGetInteger

Get the integer value from the specified node or its @@ -1629,9 +1659,10 @@ long mxmlGetInteger(mxml_node_t *node);

Return Value

Integer value or 0

Discussion

-

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.

mxmlGetLastChild

-

Get the last child of an element node.

+

Get the last child of a node.

mxml_node_t *mxmlGetLastChild(mxml_node_t *node);

Parameters

@@ -1642,7 +1673,7 @@ long mxmlGetInteger(mxml_node_t *node);

Return Value

Last child or NULL

Discussion

-

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.

mxmlGetNextSibling

@@ -1655,7 +1686,8 @@ has no children.

Return Value

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.

mxmlGetOpaque

Get an opaque string value for a node or its first child.

@@ -1668,8 +1700,8 @@ const char *mxmlGetOpaque(mxml_node_t *node);

Return Value

Opaque string or NULL

Discussion

-

NULL is returned if the node (or its first child) is not an opaque -value node.

+

This function gets the string value of an opaque node. NULL is returned if +the node (or its first child) is not an opaque value node.

mxmlGetParent

Get the parent node.

@@ -1682,7 +1714,7 @@ value node.

Return Value

Parent node or NULL

Discussion

-

NULL is returned for a root node.

+

This function gets the parent of a node. NULL is returned for a root node.

mxmlGetPrevSibling

Get the previous node for the current parent.

@@ -1695,7 +1727,8 @@ value node.

Return Value

Previous node or NULL

Discussion

-

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.

mxmlGetReal

Get the real value for a node or its first child.

@@ -1708,7 +1741,8 @@ double mxmlGetReal(mxml_node_t *node);

Return Value

Real value or 0.0

Discussion

-

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.

mxmlGetRefCount

Get the current reference (use) count for a node.

@@ -1738,8 +1772,10 @@ const char *mxmlGetText(mxml_node_t *node, bool *whit

Return Value

Text string or NULL

Discussion

-

NULL is returned if the node (or its first child) is not a text node. -The "whitespace" argument can be NULL.
+

This function gets the string and whitespace values of a text node. NULL +and false are returned if the node (or its first child) is not a text node. +The whitespace argument can be NULL if you don't want to know the +whitespace value.

Note: Text nodes consist of whitespace-delimited words. You will only get single words of text when reading an XML file with MXML_TYPE_TEXT nodes. @@ -1758,7 +1794,8 @@ using the mxmlGetOpaque function inste

Return Value

Type of node

Discussion

-

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.

mxmlGetUserData

Get the user data pointer for a node.

@@ -1770,6 +1807,8 @@ void *mxmlGetUserData(mxml_node_t *node);

Return Value

User data pointer

+

Discussion

+

This function gets the user data pointer associated with node.

mxmlIndexDelete

Delete an index.

@@ -1791,7 +1830,9 @@ void mxmlIndexDelete(mxml_index_t *ind);

Return Value

Next node or NULL if there is none

Discussion

-

You should call mxmlIndexReset prior to using this function to get +

This function returns the next node in index ind.
+
+You should call mxmlIndexReset prior to using this function to get the first node in the index. Nodes are returned in the sorted order of the index.

mxmlIndexFind

@@ -1810,9 +1851,11 @@ index.

Return Value

Node or NULL if none found

Discussion

-

You should call mxmlIndexReset prior to using this function for -the first time with a particular set of "element" and "value" -strings. Passing NULL for both "element" and "value" is equivalent +

This function finds the next matching node in index ind.
+
+You should call mxmlIndexReset prior to using this function for +the first time with a particular set of element and value +strings. Passing NULL for both element and value is equivalent to calling mxmlIndexEnum.

mxmlIndexGetCount

Get the number of nodes in an index.

@@ -1841,11 +1884,13 @@ size_t mxmlIndexGetCount(mxml_index_t *ind);

Return Value

New index

Discussion

-

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 +

This function creates a new index for XML tree node.
+
+The index will contain all nodes that contain the named element and/or +attribute. If both element and attr are NULL, then the index will contain a sorted list of the elements in the node tree. Nodes are -sorted by element name and optionally by attribute value if the "attr" -argument is not NULL.

+sorted by element name and optionally by attribute value if the attr +argument is not NULL.

mxmlIndexReset

Reset the enumeration/find pointer in the index and return the first node in the index.

@@ -1859,8 +1904,9 @@ argument is not NULL.

Return Value

First node or NULL if there is none

Discussion

-

This function should be called prior to using mxmlIndexEnum or -mxmlIndexFind for the first time.

+

This function resets the enumeration/find pointer in index ind and should +be called prior to using mxmlIndexEnum or mxmlIndexFind for the +first time.

mxmlLoadFd

Load a file descriptor into an XML node tree.

@@ -1883,18 +1929,24 @@ argument is not NULL.

Return Value

First node or NULL if the file could not be read.

Discussion

-

The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like ?xml for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, -MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for -loading child (data) nodes of the specified type.
+

This function loads the file descriptor fd into an XML node tree. The +nodes in the specified file are added to the specified node top. If NULL +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like <?xml version="1.0"?> at the start of the file.
+
+The load callback function load_cb is called to obtain the node type that +should be used for child nodes. If NULL, the load_cbdata argument points +to a mmd_type_t variable that specifies the value type or MMD_TYPE_TEXT +if that argument is also NULL.
+
+The SAX callback function sax_cb and associated callback data sax_cbdata +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed.

Note: The most common programming error when using the Mini-XML library is -to load an XML file using the MXML_TEXT_CALLBACK, which returns inline -text as a series of whitespace-delimited words, instead of using the -MXML_OPAQUE_CALLBACK which returns the inline text as a single string +to load an XML file using the MXML_TYPE_TEXT node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +MXML_TYPE_OPAQUE node type which returns the inline text as a single string (including whitespace).

mxmlLoadFile

Load a file into an XML node tree.

@@ -1918,18 +1970,24 @@ text as a series of whitespace-delimited words, instead of using the

Return Value

First node or NULL if the file could not be read.

Discussion

-

The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like ?xml for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, -MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for -loading child (data) nodes of the specified type.
+

This function loads the FILE pointer fp into an XML node tree. The +nodes in the specified file are added to the specified node top. If NULL +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like <?xml version="1.0"?> at the start of the file.
+
+The load callback function load_cb is called to obtain the node type that +should be used for child nodes. If NULL, the load_cbdata argument points +to a mmd_type_t variable that specifies the value type or MMD_TYPE_TEXT +if that argument is also NULL.
+
+The SAX callback function sax_cb and associated callback data sax_cbdata +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed.

Note: The most common programming error when using the Mini-XML library is -to load an XML file using the MXML_TEXT_CALLBACK, which returns inline -text as a series of whitespace-delimited words, instead of using the -MXML_OPAQUE_CALLBACK which returns the inline text as a single string +to load an XML file using the MXML_TYPE_TEXT node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +MXML_TYPE_OPAQUE node type which returns the inline text as a single string (including whitespace).

mxmlLoadFilename

Load a file into an XML node tree.

@@ -1953,18 +2011,24 @@ text as a series of whitespace-delimited words, instead of using the

Return Value

First node or NULL if the file could not be read.

Discussion

-

The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like ?xml for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, -MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for -loading child (data) nodes of the specified type.
+

This function loads the named file filename into an XML node tree. The +nodes in the specified file are added to the specified node top. If NULL +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like <?xml version="1.0"?> at the start of the file.
+
+The load callback function load_cb is called to obtain the node type that +should be used for child nodes. If NULL, the load_cbdata argument points +to a mmd_type_t variable that specifies the value type or MMD_TYPE_TEXT +if that argument is also NULL.
+
+The SAX callback function sax_cb and associated callback data sax_cbdata +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed.

Note: The most common programming error when using the Mini-XML library is -to load an XML file using the MXML_TEXT_CALLBACK, which returns inline -text as a series of whitespace-delimited words, instead of using the -MXML_OPAQUE_CALLBACK which returns the inline text as a single string +to load an XML file using the MXML_TYPE_TEXT node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +MXML_TYPE_OPAQUE node type which returns the inline text as a single string (including whitespace).

mxmlLoadIO

Load an XML node tree using a read callback.

@@ -1990,19 +2054,39 @@ text as a series of whitespace-delimited words, instead of using the

Return Value

First node or NULL if the file could not be read.

Discussion

-

The nodes in the specified file are added to the specified top node. -If no top node is provided, the XML file MUST be well-formed with a -single parent node like ?xml for the entire file. The callback -function returns the value type that should be used for child nodes. -The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, -MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for -loading child (data) nodes of the specified type.
+

This function loads data into an XML node tree using a read callback. The +nodes in the specified file are added to the specified node top. If NULL +is provided, the XML file MUST be well-formed with a single parent processing +instruction node like <?xml version="1.0"?> at the start of the file.

+The read callback function read_cb is called to read a number of bytes from +the source. The callback data pointer read_cbdata is passed to the read +callback with a pointer to a buffer and the maximum number of bytes to read, +for example:
+
+`c +ssize_t my_read_cb(void cbdata, void buffer, size_t bytes) +{ + ... copy up to "bytes" bytes into buffer ... + ... return the number of bytes "read" or -1 on error ... +} +

+
+The load callback function `load_cb` is called to obtain the node type that
+should be used for child nodes.  If `NULL`, the `load_cbdata` argument points
+to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT`
+if that argument is also `NULL`.
+
+The SAX callback function `sax_cb` and associated callback data `sax_cbdata`
+are used to enable the Simple API for XML streaming mode.  The callback is
+called as the XML node tree is parsed.
+
 Note: The most common programming error when using the Mini-XML library is
-to load an XML file using the MXML_TEXT_CALLBACK, which returns inline
-text as a series of whitespace-delimited words, instead of using the
-MXML_OPAQUE_CALLBACK which returns the inline text as a single string
-(including whitespace).

+to load an XML file using the `MXML_TYPE_TEXT` node type, which returns
+inline text as a series of whitespace-delimited words, instead of using the
+`MXML_TYPE_OPAQUE` node type which returns the inline text as a single string
+(including whitespace).
+

mxmlLoadString

Load a string into an XML node tree.

@@ -2025,18 +2109,24 @@ text as a series of whitespace-delimited words, instead of using the

Return Value

First node or NULL if the string has errors.

Discussion

-

The nodes in the specified string are added to the specified top node. -If no top node is provided, the XML string MUST be well-formed with a -single parent node like ?xml for the entire string. The callback -function returns the value type that should be used for child nodes. -The constants MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, -MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are defined for -loading child (data) nodes of the specified type.
+

This function loads the string into an XML node tree. The nodes in the +specified file are added to the specified node top. If NULL is provided, +the XML file MUST be well-formed with a single parent processing instruction +node like <?xml version="1.0"?> at the start of the file.
+
+The load callback function load_cb is called to obtain the node type that +should be used for child nodes. If NULL, the load_cbdata argument points +to a mmd_type_t variable that specifies the value type or MMD_TYPE_TEXT +if that argument is also NULL.
+
+The SAX callback function sax_cb and associated callback data sax_cbdata +are used to enable the Simple API for XML streaming mode. The callback is +called as the XML node tree is parsed.

Note: The most common programming error when using the Mini-XML library is -to load an XML file using the MXML_TEXT_CALLBACK, which returns inline -text as a series of whitespace-delimited words, instead of using the -MXML_OPAQUE_CALLBACK which returns the inline text as a single string +to load an XML file using the MXML_TYPE_TEXT node type, which returns +inline text as a series of whitespace-delimited words, instead of using the +MXML_TYPE_OPAQUE node type which returns the inline text as a single string (including whitespace).

mxmlNewCDATA

Create a new CDATA node.

@@ -2411,16 +2501,28 @@ char *mxmlSaveAllocString(mxml_node_t *node, Return Value

Allocated string or NULL

Discussion

-

This function returns a pointer to a string containing the textual -representation of the XML node tree. The string should be freed -using free() when you are done with it. NULL is returned if the node -would produce an empty string or if the string cannot be allocated.
+

This function saves the XML tree node to an allocated string. The string +should be freed using free (or the string free callback set using +mxmlSetStringCallbacks) when you are done with it.

-The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+NULL is returned if the node would produce an empty string or if the string +cannot be allocated.
+
+The callback function save_cb specifies a function that returns a +whitespace string or NULL before and after each element. The function +receives the callback data pointer save_cbdata, the mxml_node_t pointer, +and a "when" value indicating where the whitespace is being added, for +example:
+
+`c +const char my_save_cb(void cbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +`

mxmlSaveFd

Save an XML tree to a file descriptor.

@@ -2439,11 +2541,23 @@ bool mxmlSaveFd(mxml_node_t *node, int fd, Return Value

true on success, false on error.

Discussion

-

The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+

This function saves the XML tree node to a file descriptor.
+
+The callback function save_cb specifies a function that returns a +whitespace string or NULL before and after each element. The function +receives the callback data pointer save_cbdata, the mxml_node_t pointer, +and a "when" value indicating where the whitespace is being added, for +example:
+
+`c +const char my_save_cb(void cbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +`

mxmlSaveFile

Save an XML tree to a file.

@@ -2462,11 +2576,23 @@ bool mxmlSaveFile(mxml_node_t *node, FILE *fp, Return Value

true on success, false on error.

Discussion

-

The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+

This function saves the XML tree node to a stdio FILE.
+
+The callback function save_cb specifies a function that returns a +whitespace string or NULL before and after each element. The function +receives the callback data pointer save_cbdata, the mxml_node_t pointer, +and a "when" value indicating where the whitespace is being added, for +example:
+
+`c +const char my_save_cb(void cbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +`

mxmlSaveFilename

Save an XML tree to a file.

@@ -2485,11 +2611,23 @@ bool mxmlSaveFilename(mxml_node_t *node, const char *

Return Value

true on success, false on error.

Discussion

-

The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+

This function saves the XML tree node to a named file.
+
+The callback function save_cb specifies a function that returns a +whitespace string or NULL before and after each element. The function +receives the callback data pointer save_cbdata, the mxml_node_t pointer, +and a "when" value indicating where the whitespace is being added, for +example:
+
+`c +const char my_save_cb(void cbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +`

mxmlSaveIO

Save an XML tree using a callback.

@@ -2510,11 +2648,35 @@ bool mxmlSaveIO(mxml_node_t *node, Return Value

true on success, false on error.

Discussion

-

The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+

This function saves the XML tree node using a write callback function +write_cb. The write callback is called with the callback data pointer +write_cbdata, a buffer pointer, and the number of bytes to write, for +example:
+
+`c +ssize_t my_write_cb(void cbdata, const void buffer, size_t bytes) +{ + ... write/copy bytes from buffer to the output ... + ... return the number of bytes written/copied or -1 on error ... +} +

+
+The callback function `save_cb` specifies a function that returns a
+whitespace string or `NULL` before and after each element.  The function
+receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer,
+and a "when" value indicating where the whitespace is being added, for
+example:
+
+```c
+const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when)
+{
+  if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE)
+    return ("n");
+  else
+    return (NULL);
+}
+
+

mxmlSaveString

Save an XML node tree to a string.

@@ -2535,15 +2697,23 @@ size_t mxmlSaveString(mxml_node_t *node, char *buffer

Return Value

Size of string

Discussion

-

This function returns the total number of bytes that would be -required for the string but only copies (bufsize - 1) characters -into the specified buffer.
+

This function saves the XML tree node to a string buffer.

-The callback argument specifies a function that returns a whitespace -string or NULL before and after each element. If MXML_NO_CALLBACK -is specified, whitespace will only be added before MXML_TYPE_TEXT nodes -with leading whitespace and before attribute names inside opening -element tags.

+The callback function save_cb specifies a function that returns a +whitespace string or NULL before and after each element. The function +receives the callback data pointer save_cbdata, the mxml_node_t pointer, +and a "when" value indicating where the whitespace is being added, for +example:
+
+`c +const char my_save_cb(void cbdata, mxml_node_t *node, mxml_ws_t when) +{ + if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) + return ("n"); + else + return (NULL); +} +`

mxmlSetCDATA

Set the data for a CDATA node.

@@ -2558,7 +2728,8 @@ bool mxmlSetCDATA(mxml_node_t *node, const char *data

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetCDATAf

Set the data for a CDATA to a formatted string.

@@ -2574,6 +2745,9 @@ bool mxmlSetCDATAf(mxml_node_t *node, const char *for

Return Value

true on success, false on failure

+

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.

mxmlSetComment

Set a comment to a literal string.

@@ -2587,6 +2761,8 @@ bool mxmlSetComment(mxml_node_t *node, const char *co

Return Value

true on success, false on failure

+

Discussion

+

This function sets the string value of a comment node.

mxmlSetCommentf

Set a comment to a formatted string.

@@ -2602,25 +2778,29 @@ bool mxmlSetCommentf(mxml_node_t *node, const char *f

Return Value

true on success, false on failure

+

Discussion

+

This function sets the formatted string value of a comment node.

mxmlSetCustom

Set the data and destructor of a custom data node.

-bool mxmlSetCustom(mxml_node_t *node, void *data, mxml_custom_destroy_cb_t destroy);

+bool mxmlSetCustom(mxml_node_t *node, void *data, mxml_custom_destroy_cb_t destroy_cb);

Parameters

- +
node Node to set
data New data pointer
destroy
destroy_cb New destructor function

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetDeclaration

-

Set a comment to a literal string.

+

Set a declaration to a literal string.

bool mxmlSetDeclaration(mxml_node_t *node, const char *declaration);

Parameters

@@ -2632,8 +2812,10 @@ bool mxmlSetDeclaration(mxml_node_t *node, const char

Return Value

true on success, false on failure

+

Discussion

+

This function sets the string value of a declaration node.

mxmlSetDeclarationf

-

Set a comment to a formatted string.

+

Set a declaration to a formatted string.

bool mxmlSetDeclarationf(mxml_node_t *node, const char *format, ...);

Parameters

@@ -2647,8 +2829,10 @@ bool mxmlSetDeclarationf(mxml_node_t *node, const cha

Return Value

true on success, false on failure

+

Discussion

+

This function sets the formatted string value of a declaration node.

mxmlSetDirective

-

Set a directive to a literal string.

+

Set a processing instruction to a literal string.

bool mxmlSetDirective(mxml_node_t *node, const char *directive);

Parameters

@@ -2660,8 +2844,10 @@ bool mxmlSetDirective(mxml_node_t *node, const char *

Return Value

true on success, false on failure

+

Discussion

+

This function sets the string value of a processing instruction node.

mxmlSetDirectivef

-

Set a directive to a formatted string.

+

Set a processing instruction to a formatted string.

bool mxmlSetDirectivef(mxml_node_t *node, const char *format, ...);

Parameters

@@ -2675,6 +2861,9 @@ bool mxmlSetDirectivef(mxml_node_t *node, const char

Return Value

true on success, false on failure

+

Discussion

+

This function sets the formatted string value of a processing instruction +node.

mxmlSetElement

Set the name of an element node.

@@ -2689,7 +2878,8 @@ bool mxmlSetElement(mxml_node_t *node, const char *na

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetInteger

Set the value of an integer node.

@@ -2704,7 +2894,8 @@ bool mxmlSetInteger(mxml_node_t *node, long integer);

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetOpaque

Set the value of an opaque node.

@@ -2719,7 +2910,8 @@ bool mxmlSetOpaque(mxml_node_t *node, const char *opa

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetOpaquef

Set the value of an opaque string node to a formatted string.

@@ -2736,9 +2928,10 @@ bool mxmlSetOpaquef(mxml_node_t *node, const char *fo

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetReal

-

Set the value of a real number node.

+

Set the value of a real value node.

bool mxmlSetReal(mxml_node_t *node, double real);

Parameters

@@ -2751,7 +2944,8 @@ bool mxmlSetReal(mxml_node_t *node, double real);

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetText

Set the value of a text node.

@@ -2768,7 +2962,8 @@ bool mxmlSetText(mxml_node_t *node, bool whitespace,

Return Value

true on success, false on failure

Discussion

-

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.

mxmlSetTextf

Set the value of a text node to a formatted string.

@@ -2787,7 +2982,8 @@ bool mxmlSetTextf(mxml_node_t *node, bool whitespace,

Return Value

true on success, false on failure

Discussion

-

The node is not changed if it (or its first child) is not a text node.

+

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.

mxmlSetUserData

Set the user data pointer for a node.

@@ -2811,7 +3007,8 @@ void mxmlSetWrapMargin(int column);

Column for wrapping, 0 to disable wrapping

Discussion

-

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.

mxmlWalkNext

Walk to the next logical node in the tree.

@@ -2828,9 +3025,9 @@ void mxmlSetWrapMargin(int column);

Return Value

Next node or NULL

Discussion

-

The descend argument controls whether the first child is considered -to be the next node. The top node argument constrains the walk to -the node's children.

+

This function walks to the next logical node in the tree. The descend +argument controls whether the first child is considered to be the next node. +The top argument constrains the walk to that node's children.

mxmlWalkPrev

Walk to the previous logical node in the tree.

@@ -2847,9 +3044,9 @@ the node's children.

Return Value

Previous node or NULL

Discussion

-

The descend argument controls whether the previous node's last child -is considered to be the previous node. The top node argument constrains -the walk to the node's children.

+

This function walks to the previous logical node in the tree. The descend +argument controls whether the first child is considered to be the next node. +The top argument constrains the walk to that node's children.

Data Types

mxml_add_t

mxmlAdd add values

diff --git a/mxml-attr.c b/mxml-attr.c index 79d98e2..7af4c1e 100644 --- a/mxml-attr.c +++ b/mxml-attr.c @@ -20,7 +20,9 @@ static bool mxml_set_attr(mxml_node_t *node, const char *name, char *value); // -// 'mxmlElementClearAttr()' - Delete an attribute. +// 'mxmlElementClearAttr()' - Remove an attribute from an element. +// +// This function removes the attribute `name` from the element `node`. // void @@ -63,13 +65,14 @@ mxmlElementClearAttr(mxml_node_t *node, // I - Element // -// 'mxmlElementGetAttr()' - Get an attribute. +// 'mxmlElementGetAttr()' - Get the value of an attribute. // -// This function returns @code NULL@ if the node is not an element or the -// named attribute does not exist. +// This function gets the value for the attribute `name` from the element +// `node`. `NULL` is returned if the node is not an element or the named +// attribute does not exist. // -const char * // O - Attribute value or @code NULL@ +const char * // O - Attribute value or `NULL` mxmlElementGetAttr(mxml_node_t *node, // I - Element node const char *name) // I - Name of attribute { @@ -103,17 +106,18 @@ mxmlElementGetAttr(mxml_node_t *node, // I - Element node // -// 'mxmlElementGetAttrByIndex()' - Get an element attribute by index. +// 'mxmlElementGetAttrByIndex()' - Get an attribute by index. // -// The index ("idx") is 0-based. @code NULL@ is returned if the specified index -// is out of range. +// This function returned the Nth (`idx`) attribute for element `node`. The +// attribute name is optionallly returned in the `name` argument. `NULL` is +// returned if node is not an element or the specified index is out of range. // const char * // O - Attribute value mxmlElementGetAttrByIndex( mxml_node_t *node, // I - Node - int idx, // I - Attribute index, starting at 0 - const char **name) // O - Attribute name + int idx, // I - Attribute index, starting at `0` + const char **name) // O - Attribute name or `NULL` to not return it { if (!node || node->type != MXML_TYPE_ELEMENT || idx < 0 || idx >= node->value.element.num_attrs) return (NULL); @@ -128,6 +132,10 @@ mxmlElementGetAttrByIndex( // // 'mxmlElementGetAttrCount()' - Get the number of element attributes. // +// This function returns the number of attributes for the element `node`. `0` +// is returned if the node is not an element or there are no attributes for the +// element. +// size_t // O - Number of attributes mxmlElementGetAttrCount( @@ -141,12 +149,11 @@ mxmlElementGetAttrCount( // -// 'mxmlElementSetAttr()' - Set an attribute. +// 'mxmlElementSetAttr()' - Set an attribute for an element. // -// If the named attribute already exists, the value of the attribute -// is replaced by the new string value. The string value is copied -// into the element node. This function does nothing if the node is -// not an element. +// This function sets attribute `name` to the string `value` for the element +// `node`. If the named attribute already exists, the value of the attribute +// is replaced by the new string value. The string value is copied. // void @@ -184,10 +191,9 @@ mxmlElementSetAttr(mxml_node_t *node, // I - Element node // // 'mxmlElementSetAttrf()' - Set an attribute with a formatted value. // -// If the named attribute already exists, the value of the attribute -// is replaced by the new formatted string. The formatted string value is -// copied into the element node. This function does nothing if the node -// is not an element. +// This function sets attribute `name` to the formatted value of `format` for +// the element `node`. If the named attribute already exists, the value of the +// attribute is replaced by the new formatted string value. // void diff --git a/mxml-entity.c b/mxml-entity.c index 48ada9d..6fb03a1 100644 --- a/mxml-entity.c +++ b/mxml-entity.c @@ -15,6 +15,22 @@ // // 'mxmlEntityAddCallback()' - Add a callback to convert entities to Unicode. // +// This function adds a callback to the current thread that converts named +// XML character entities to Unicode characters. The callback function `cb` +// accepts the callback data pointer `cbdata` and the entity name and returns a +// Unicode character value or `-1` if the entity is not known. For example, the +// following entity callback supports the "euro" entity: +// +// ```c +// int my_entity_cb(void *cbdata, const char *name) +// { +// if (!strcmp(name, "euro")) +// return (0x20ac); +// else +// return (-1); +// } +// ``` +// bool // O - `true` on success, `false` on failure mxmlEntityAddCallback( diff --git a/mxml-file.c b/mxml-file.c index b58c6e0..2c80c93 100644 --- a/mxml-file.c +++ b/mxml-file.c @@ -71,18 +71,24 @@ static int mxml_write_ws(mxml_write_cb_t write_cb, void *write_cbdata, mxml_nod // // 'mxmlLoadFd()' - Load a file descriptor into an XML node tree. // -// The nodes in the specified file are added to the specified top node. -// If no top node is provided, the XML file MUST be well-formed with a -// single parent node like for the entire file. The callback -// function returns the value type that should be used for child nodes. -// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, -// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for -// loading child (data) nodes of the specified type. +// This function loads the file descriptor `fd` into an XML node tree. The +// nodes in the specified file are added to the specified node `top`. If `NULL` +// is provided, the XML file MUST be well-formed with a single parent processing +// instruction node like `` at the start of the file. +// +// The load callback function `load_cb` is called to obtain the node type that +// should be used for child nodes. If `NULL`, the `load_cbdata` argument points +// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` +// if that argument is also `NULL`. +// +// The SAX callback function `sax_cb` and associated callback data `sax_cbdata` +// are used to enable the Simple API for XML streaming mode. The callback is +// called as the XML node tree is parsed. // // Note: The most common programming error when using the Mini-XML library is -// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline -// text as a series of whitespace-delimited words, instead of using the -// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string +// to load an XML file using the `MXML_TYPE_TEXT` node type, which returns +// inline text as a series of whitespace-delimited words, instead of using the +// `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string // (including whitespace). // @@ -107,18 +113,24 @@ mxmlLoadFd( // // 'mxmlLoadFile()' - Load a file into an XML node tree. // -// The nodes in the specified file are added to the specified top node. -// If no top node is provided, the XML file MUST be well-formed with a -// single parent node like for the entire file. The callback -// function returns the value type that should be used for child nodes. -// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, -// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for -// loading child (data) nodes of the specified type. +// This function loads the `FILE` pointer `fp` into an XML node tree. The +// nodes in the specified file are added to the specified node `top`. If `NULL` +// is provided, the XML file MUST be well-formed with a single parent processing +// instruction node like `` at the start of the file. +// +// The load callback function `load_cb` is called to obtain the node type that +// should be used for child nodes. If `NULL`, the `load_cbdata` argument points +// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` +// if that argument is also `NULL`. +// +// The SAX callback function `sax_cb` and associated callback data `sax_cbdata` +// are used to enable the Simple API for XML streaming mode. The callback is +// called as the XML node tree is parsed. // // Note: The most common programming error when using the Mini-XML library is -// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline -// text as a series of whitespace-delimited words, instead of using the -// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string +// to load an XML file using the `MXML_TYPE_TEXT` node type, which returns +// inline text as a series of whitespace-delimited words, instead of using the +// `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string // (including whitespace). // @@ -143,18 +155,24 @@ mxmlLoadFile( // // 'mxmlLoadFilename()' - Load a file into an XML node tree. // -// The nodes in the specified file are added to the specified top node. -// If no top node is provided, the XML file MUST be well-formed with a -// single parent node like for the entire file. The callback -// function returns the value type that should be used for child nodes. -// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, -// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for -// loading child (data) nodes of the specified type. +// This function loads the named file `filename` into an XML node tree. The +// nodes in the specified file are added to the specified node `top`. If `NULL` +// is provided, the XML file MUST be well-formed with a single parent processing +// instruction node like `` at the start of the file. +// +// The load callback function `load_cb` is called to obtain the node type that +// should be used for child nodes. If `NULL`, the `load_cbdata` argument points +// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` +// if that argument is also `NULL`. +// +// The SAX callback function `sax_cb` and associated callback data `sax_cbdata` +// are used to enable the Simple API for XML streaming mode. The callback is +// called as the XML node tree is parsed. // // Note: The most common programming error when using the Mini-XML library is -// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline -// text as a series of whitespace-delimited words, instead of using the -// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string +// to load an XML file using the `MXML_TYPE_TEXT` node type, which returns +// inline text as a series of whitespace-delimited words, instead of using the +// `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string // (including whitespace). // @@ -192,18 +210,37 @@ mxmlLoadFilename( // // 'mxmlLoadIO()' - Load an XML node tree using a read callback. // -// The nodes in the specified file are added to the specified top node. -// If no top node is provided, the XML file MUST be well-formed with a -// single parent node like for the entire file. The callback -// function returns the value type that should be used for child nodes. -// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, -// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for -// loading child (data) nodes of the specified type. +// This function loads data into an XML node tree using a read callback. The +// nodes in the specified file are added to the specified node `top`. If `NULL` +// is provided, the XML file MUST be well-formed with a single parent processing +// instruction node like `` at the start of the file. +// +// The read callback function `read_cb` is called to read a number of bytes from +// the source. The callback data pointer `read_cbdata` is passed to the read +// callback with a pointer to a buffer and the maximum number of bytes to read, +// for example: +// +// ```c +// ssize_t my_read_cb(void *cbdata, void *buffer, size_t bytes) +// { +// ... copy up to "bytes" bytes into buffer ... +// ... return the number of bytes "read" or -1 on error ... +// } +// ``` +// +// The load callback function `load_cb` is called to obtain the node type that +// should be used for child nodes. If `NULL`, the `load_cbdata` argument points +// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` +// if that argument is also `NULL`. +// +// The SAX callback function `sax_cb` and associated callback data `sax_cbdata` +// are used to enable the Simple API for XML streaming mode. The callback is +// called as the XML node tree is parsed. // // Note: The most common programming error when using the Mini-XML library is -// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline -// text as a series of whitespace-delimited words, instead of using the -// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string +// to load an XML file using the `MXML_TYPE_TEXT` node type, which returns +// inline text as a series of whitespace-delimited words, instead of using the +// `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string // (including whitespace). // @@ -229,18 +266,24 @@ mxmlLoadIO( // // 'mxmlLoadString()' - Load a string into an XML node tree. // -// The nodes in the specified string are added to the specified top node. -// If no top node is provided, the XML string MUST be well-formed with a -// single parent node like for the entire string. The callback -// function returns the value type that should be used for child nodes. -// The constants `MXML_INTEGER_CALLBACK`, `MXML_OPAQUE_CALLBACK`, -// `MXML_REAL_CALLBACK`, and `MXML_TEXT_CALLBACK` are defined for -// loading child (data) nodes of the specified type. +// This function loads the string into an XML node tree. The nodes in the +// specified file are added to the specified node `top`. If `NULL` is provided, +// the XML file MUST be well-formed with a single parent processing instruction +// node like `` at the start of the file. +// +// The load callback function `load_cb` is called to obtain the node type that +// should be used for child nodes. If `NULL`, the `load_cbdata` argument points +// to a `mmd_type_t` variable that specifies the value type or `MMD_TYPE_TEXT` +// if that argument is also `NULL`. +// +// The SAX callback function `sax_cb` and associated callback data `sax_cbdata` +// are used to enable the Simple API for XML streaming mode. The callback is +// called as the XML node tree is parsed. // // Note: The most common programming error when using the Mini-XML library is -// to load an XML file using the `MXML_TEXT_CALLBACK`, which returns inline -// text as a series of whitespace-delimited words, instead of using the -// `MXML_OPAQUE_CALLBACK` which returns the inline text as a single string +// to load an XML file using the `MXML_TYPE_TEXT` node type, which returns +// inline text as a series of whitespace-delimited words, instead of using the +// `MXML_TYPE_OPAQUE` node type which returns the inline text as a single string // (including whitespace). // @@ -274,16 +317,28 @@ mxmlLoadString( // // 'mxmlSaveAllocString()' - Save an XML tree to an allocated string. // -// This function returns a pointer to a string containing the textual -// representation of the XML node tree. The string should be freed -// using `free()` when you are done with it. `NULL` is returned if the node -// would produce an empty string or if the string cannot be allocated. +// This function saves the XML tree `node` to an allocated string. The string +// should be freed using `free` (or the string free callback set using +// @link mxmlSetStringCallbacks@) when you are done with it. // -// The callback argument specifies a function that returns a whitespace -// string or `NULL` before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// `NULL` is returned if the node would produce an empty string or if the string +// cannot be allocated. +// +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // char * // O - Allocated string or `NULL` @@ -323,11 +378,23 @@ mxmlSaveAllocString( // // 'mxmlSaveFd()' - Save an XML tree to a file descriptor. // -// The callback argument specifies a function that returns a whitespace -// string or NULL before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// This function saves the XML tree `node` to a file descriptor. +// +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // bool // O - `true` on success, `false` on error. @@ -359,11 +426,23 @@ mxmlSaveFd(mxml_node_t *node, // I - Node to write // // 'mxmlSaveFile()' - Save an XML tree to a file. // -// The callback argument specifies a function that returns a whitespace -// string or NULL before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// This function saves the XML tree `node` to a stdio `FILE`. +// +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // bool // O - `true` on success, `false` on error. @@ -396,11 +475,23 @@ mxmlSaveFile( // // 'mxmlSaveFilename()' - Save an XML tree to a file. // -// The callback argument specifies a function that returns a whitespace -// string or NULL before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// This function saves the XML tree `node` to a named file. +// +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // bool // O - `true` on success, `false` on error. @@ -442,11 +533,34 @@ mxmlSaveFilename( // // 'mxmlSaveIO()' - Save an XML tree using a callback. // -// The callback argument specifies a function that returns a whitespace -// string or NULL before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// This function saves the XML tree `node` using a write callback function +// `write_cb`. The write callback is called with the callback data pointer +// `write_cbdata`, a buffer pointer, and the number of bytes to write, for +// example: +// +// ```c +// ssize_t my_write_cb(void *cbdata, const void *buffer, size_t bytes) +// { +// ... write/copy bytes from buffer to the output ... +// ... return the number of bytes written/copied or -1 on error ... +// } +// ``` +// +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // bool // O - `true` on success, `false` on error. @@ -484,15 +598,23 @@ mxmlSaveIO( // // 'mxmlSaveString()' - Save an XML node tree to a string. // -// This function returns the total number of bytes that would be -// required for the string but only copies (bufsize - 1) characters -// into the specified buffer. +// This function saves the XML tree `node` to a string buffer. // -// The callback argument specifies a function that returns a whitespace -// string or NULL before and after each element. If `MXML_NO_CALLBACK` -// is specified, whitespace will only be added before `MXML_TYPE_TEXT` nodes -// with leading whitespace and before attribute names inside opening -// element tags. +// The callback function `save_cb` specifies a function that returns a +// whitespace string or `NULL` before and after each element. The function +// receives the callback data pointer `save_cbdata`, the `mxml_node_t` pointer, +// and a "when" value indicating where the whitespace is being added, for +// example: +// +// ```c +// const char *my_save_cb(void *cbdata, mxml_node_t *node, mxml_ws_t when) +// { +// if (when == MXML_WS_BEFORE_OPEN || when == MXML_WS_AFTER_CLOSE) +// return ("\n"); +// else +// return (NULL); +// } +// ``` // size_t // O - Size of string @@ -530,7 +652,8 @@ mxmlSaveString( // // 'mxmlSetWrapMargin()' - Set the wrap margin when saving XML data. // -// Wrapping is disabled when "column" is 0. +// This function sets the wrap margin used when saving XML data for the current +// thread. Wrapping is disabled when `column` is `0`. // void diff --git a/mxml-get.c b/mxml-get.c index 9a809ef..384bc8d 100644 --- a/mxml-get.c +++ b/mxml-get.c @@ -15,7 +15,8 @@ // // 'mxmlGetCDATA()' - Get the value for a CDATA node. // -// `NULL` is returned if the node is not a CDATA element. +// This function gets the string value of a CDATA node. `NULL` is returned if +// the node is not a CDATA element. // const char * // O - CDATA value or `NULL` @@ -33,7 +34,8 @@ mxmlGetCDATA(mxml_node_t *node) // I - Node to get // // 'mxmlGetComment()' - Get the value for a comment node. // -// `NULL` is returned if the node is not a comment. +// This function gets the string value of a comment node. `NULL` is returned +// if the node is not a comment. // const char * // O - Comment value or `NULL` @@ -51,8 +53,8 @@ mxmlGetComment(mxml_node_t *node) // I - Node to get // // 'mxmlGetCustom()' - Get the value for a custom node. // -// `NULL` is returned if the node (or its first child) is not a custom -// value node. +// This function gets the binary value of a custom node. `NULL` is returned if +// the node (or its first child) is not a custom value node. // const void * // O - Custom value or `NULL` @@ -75,7 +77,8 @@ mxmlGetCustom(mxml_node_t *node) // I - Node to get // // 'mxmlGetDeclaration()' - Get the value for a declaration node. // -// `NULL` is returned if the node is not a declaration. +// This function gets the string value of a declaraction node. `NULL` is +// returned if the node is not a declaration. // const char * // O - Declaraction value or `NULL` @@ -93,7 +96,8 @@ mxmlGetDeclaration(mxml_node_t *node) // I - Node to get // // 'mxmlGetDirective()' - Get the value for a processing instruction node. // -// `NULL` is returned if the node is not a processing instruction. +// This function gets the string value of a processing instruction. `NULL` is +// returned if the node is not a processing instruction. // const char * // O - Comment value or `NULL` @@ -111,7 +115,8 @@ mxmlGetDirective(mxml_node_t *node) // I - Node to get // // 'mxmlGetElement()' - Get the name for an element node. // -// `NULL` is returned if the node is not an element node. +// This function gets the name of an element node. `NULL` is returned if the +// node is not an element node. // const char * // O - Element name or `NULL` @@ -127,9 +132,9 @@ mxmlGetElement(mxml_node_t *node) // I - Node to get // -// 'mxmlGetFirstChild()' - Get the first child of an element node. +// 'mxmlGetFirstChild()' - Get the first child of a node. // -// `NULL` is returned if the node is not an element node or if the node +// This function gets the first child of a node. `NULL` is returned if the node // has no children. // @@ -145,7 +150,8 @@ mxmlGetFirstChild(mxml_node_t *node) // I - Node to get // 'mxmlGetInteger()' - Get the integer value from the specified node or its // first child. // -// `0` is returned if the node (or its first child) is not an integer value node. +// This function gets the value of an integer node. `0` is returned if the node +// (or its first child) is not an integer value node. // long // O - Integer value or `0` @@ -166,9 +172,9 @@ mxmlGetInteger(mxml_node_t *node) // I - Node to get // -// 'mxmlGetLastChild()' - Get the last child of an element node. +// 'mxmlGetLastChild()' - Get the last child of a node. // -// `NULL` is returned if the node is not an element node or if the node +// This function gets the last child of a node. `NULL` is returned if the node // has no children. // @@ -182,7 +188,8 @@ mxmlGetLastChild(mxml_node_t *node) // I - Node to get // // 'mxmlGetNextSibling()' - Get the next node for the current parent. // -// `NULL` is returned if this is the last child for the current parent. +// This function gets the next node for the current parent. `NULL` is returned +// if this is the last child for the current parent. // mxml_node_t * @@ -195,8 +202,8 @@ mxmlGetNextSibling(mxml_node_t *node) // I - Node to get // // 'mxmlGetOpaque()' - Get an opaque string value for a node or its first child. // -// `NULL` is returned if the node (or its first child) is not an opaque -// value node. +// This function gets the string value of an opaque node. `NULL` is returned if +// the node (or its first child) is not an opaque value node. // const char * // O - Opaque string or `NULL` @@ -219,7 +226,7 @@ mxmlGetOpaque(mxml_node_t *node) // I - Node to get // // 'mxmlGetParent()' - Get the parent node. // -// `NULL` is returned for a root node. +// This function gets the parent of a node. `NULL` is returned for a root node. // mxml_node_t * // O - Parent node or `NULL` @@ -232,7 +239,8 @@ mxmlGetParent(mxml_node_t *node) // I - Node to get // // 'mxmlGetPrevSibling()' - Get the previous node for the current parent. // -// `NULL` is returned if this is the first child for the current parent. +// This function gets the previous node for the current parent. `NULL` is +// returned if this is the first child for the current parent. // mxml_node_t * // O - Previous node or `NULL` @@ -245,7 +253,8 @@ mxmlGetPrevSibling(mxml_node_t *node) // I - Node to get // // 'mxmlGetReal()' - Get the real value for a node or its first child. // -// 0.0 is returned if the node (or its first child) is not a real value node. +// This function gets the value of a real value node. `0.0` is returned if the +// node (or its first child) is not a real value node. // double // O - Real value or 0.0 @@ -268,8 +277,10 @@ mxmlGetReal(mxml_node_t *node) // I - Node to get // // 'mxmlGetText()' - Get the text value for a node or its first child. // -// `NULL` is returned if the node (or its first child) is not a text node. -// The "whitespace" argument can be `NULL`. +// This function gets the string and whitespace values of a text node. `NULL` +// and `false` are returned if the node (or its first child) is not a text node. +// The `whitespace` argument can be `NULL` if you don't want to know the +// whitespace value. // // Note: Text nodes consist of whitespace-delimited words. You will only get // single words of text when reading an XML file with `MXML_TYPE_TEXT` nodes. @@ -319,7 +330,8 @@ mxmlGetText(mxml_node_t *node, // I - Node to get // // 'mxmlGetType()' - Get the node type. // -// `MXML_TYPE_IGNORE` is returned if "node" is `NULL`. +// This function gets the type of `node`. `MXML_TYPE_IGNORE` is returned if +// `node` is `NULL`. // mxml_type_t // O - Type of node @@ -337,6 +349,8 @@ mxmlGetType(mxml_node_t *node) // I - Node to get // // 'mxmlGetUserData()' - Get the user data pointer for a node. // +// This function gets the user data pointer associated with `node`. +// void * // O - User data pointer mxmlGetUserData(mxml_node_t *node) // I - Node to get diff --git a/mxml-index.c b/mxml-index.c index d4d960d..f5ebe94 100644 --- a/mxml-index.c +++ b/mxml-index.c @@ -42,6 +42,8 @@ mxmlIndexDelete(mxml_index_t *ind) // I - Index to delete // // 'mxmlIndexEnum()' - Return the next node in the index. // +// This function returns the next node in index `ind`. +// // You should call @link mxmlIndexReset@ prior to using this function to get // the first node in the index. Nodes are returned in the sorted order of the // index. @@ -65,9 +67,11 @@ mxmlIndexEnum(mxml_index_t *ind) // I - Index to enumerate // // 'mxmlIndexFind()' - Find the next matching node. // +// This function finds the next matching node in index `ind`. +// // You should call @link mxmlIndexReset@ prior to using this function for -// the first time with a particular set of "element" and "value" -// strings. Passing `NULL` for both "element" and "value" is equivalent +// the first time with a particular set of `element` and `value` +// strings. Passing `NULL` for both `element` and `value` is equivalent // to calling @link mxmlIndexEnum@. // @@ -196,11 +200,13 @@ mxmlIndexGetCount(mxml_index_t *ind) // I - Index of nodes // // 'mxmlIndexNew()' - Create a new index. // +// This function creates a new index for XML tree `node`. +// // The index will contain all nodes that contain the named element and/or -// attribute. If both "element" and "attr" are `NULL`, then the index will +// attribute. If both `element` and `attr` are `NULL`, then the index will // contain a sorted list of the elements in the node tree. Nodes are -// sorted by element name and optionally by attribute value if the "attr" -// argument is not NULL. +// sorted by element name and optionally by attribute value if the `attr` +// argument is not `NULL`. // mxml_index_t * // O - New index @@ -275,8 +281,9 @@ mxmlIndexNew(mxml_node_t *node, // I - XML node tree // 'mxmlIndexReset()' - Reset the enumeration/find pointer in the index and // return the first node in the index. // -// This function should be called prior to using @link mxmlIndexEnum@ or -// @link mxmlIndexFind@ for the first time. +// This function resets the enumeration/find pointer in index `ind` and should +// be called prior to using @link mxmlIndexEnum@ or @link mxmlIndexFind@ for the +// first time. // mxml_node_t * // O - First node or `NULL` if there is none diff --git a/mxml-node.c b/mxml-node.c index 12b0758..ea9153d 100644 --- a/mxml-node.c +++ b/mxml-node.c @@ -23,11 +23,11 @@ static mxml_node_t *mxml_new(mxml_node_t *parent, mxml_type_t type); // // 'mxmlAdd()' - Add a node to a tree. // -// Adds the specified node to the parent. If the child argument is not -// `NULL`, puts the new node before or after the specified child depending -// on the value of the `add` argument. If the child argument is `NULL`, -// puts the new node at the beginning of the child list (`MXML_ADD_BEFORE`) -// or at the end of the child list (`MXML_ADD_AFTER`). +// This function adds the specified node `node` to the parent. If the `child` +// argument is not `NULL`, the new node is added before or after the specified +// child depending on the value of the `add` argument. If the `child` argument +// is `NULL`, the new node is placed at the beginning of the child list +// (`MXML_ADD_BEFORE`) or at the end of the child list (`MXML_ADD_AFTER`). // void @@ -114,8 +114,9 @@ mxmlAdd(mxml_node_t *parent, // I - Parent node // // 'mxmlDelete()' - Delete a node and all of its children. // -// If the specified node has a parent, this function first removes the -// node from its parent using the @link mxmlRemove@ function. +// This function deletes the node `node` and all of its children. If the +// specified node has a parent, this function first removes the node from its +// parent using the @link mxmlRemove@ function. // void diff --git a/mxml-search.c b/mxml-search.c index 7a7d03a..8907256 100644 --- a/mxml-search.c +++ b/mxml-search.c @@ -15,14 +15,15 @@ // // 'mxmlFindElement()' - Find the named element. // -// The search is constrained by the name, attribute name, and value; any -// `NULL` names or values are treated as wildcards, so different kinds of -// searches can be implemented by looking for all elements of a given name -// or all elements with a specific attribute. The descend argument determines -// whether the search descends into child nodes; normally you will use -// `MXML_DESCEND_FIRST` for the initial search and `MXML_NO_DESCEND` -// to find additional direct descendents of the node. The top node argument -// constrains the search to a particular node's children. +// This function finds the named element `element` in XML tree `top` starting at +// node `node`. The search is constrained by element name `element`, attribute +// name `attr`, and attribute value `value` - `NULL` names or values are treated +// as wildcards, so different kinds of searches can be implemented by looking +// for all elements of a given name or all elements with a specific attribute. +// +// The `descend` argument determines whether the search descends into child +// nodes; normally you will use `MXML_DESCEND_FIRST` for the initial search and +// `MXML_DESCEND_NONE` to find additional direct descendents of the node. // mxml_node_t * // O - Element node or `NULL` @@ -76,9 +77,10 @@ mxmlFindElement(mxml_node_t *node, // I - Current node // // 'mxmlFindPath()' - Find a node with the given path. // -// The "path" is a slash-separated list of element names. The name "*" is -// considered a wildcard for one or more levels of elements. For example, -// "foo/one/two", "bar/two/one", "*\/one", and so forth. +// This function finds a node in XML tree `top` using a slash-separated list of +// element names in `path`. The name "*" is considered a wildcard for one or +// more levels of elements, for example, "foo/one/two", "bar/two/one", "*\/one", +// and so forth. // // The first child node of the found node is returned if the given node has // children and the first child is a value node. @@ -144,9 +146,9 @@ mxmlFindPath(mxml_node_t *top, // I - Top node // // 'mxmlWalkNext()' - Walk to the next logical node in the tree. // -// The descend argument controls whether the first child is considered -// to be the next node. The top node argument constrains the walk to -// the node's children. +// This function walks to the next logical node in the tree. The `descend` +// argument controls whether the first child is considered to be the next node. +// The `top` argument constrains the walk to that node's children. // mxml_node_t * // O - Next node or `NULL` @@ -194,9 +196,9 @@ mxmlWalkNext(mxml_node_t *node, // I - Current node // // 'mxmlWalkPrev()' - Walk to the previous logical node in the tree. // -// The descend argument controls whether the previous node's last child -// is considered to be the previous node. The top node argument constrains -// the walk to the node's children. +// This function walks to the previous logical node in the tree. The `descend` +// argument controls whether the first child is considered to be the next node. +// The `top` argument constrains the walk to that node's children. // mxml_node_t * // O - Previous node or `NULL` diff --git a/mxml-set.c b/mxml-set.c index 6cd45dd..7fc33e0 100644 --- a/mxml-set.c +++ b/mxml-set.c @@ -15,7 +15,8 @@ // // 'mxmlSetCDATA()' - Set the data for a CDATA node. // -// The node is not changed if it (or its first child) is not a CDATA node. +// This function sets the value string for a CDATA node. The node is not +// changed if it (or its first child) is not a CDATA node. // bool // O - `true` on success, `false` on failure @@ -63,6 +64,9 @@ mxmlSetCDATA(mxml_node_t *node, // I - Node to set // // 'mxmlSetCDATAf()' - Set the data for a CDATA to a formatted string. // +// This function sets the formatted string value of a CDATA node. The node is +// not changed if it (or its first child) is not a CDATA node. +// bool // O - `true` on success, `false` on failure mxmlSetCDATAf(mxml_node_t *node, // I - Node @@ -110,6 +114,8 @@ mxmlSetCDATAf(mxml_node_t *node, // I - Node // // 'mxmlSetComment()' - Set a comment to a literal string. // +// This function sets the string value of a comment node. +// bool // O - `true` on success, `false` on failure mxmlSetComment(mxml_node_t *node, // I - Node @@ -153,6 +159,8 @@ mxmlSetComment(mxml_node_t *node, // I - Node // // 'mxmlSetCommentf()' - Set a comment to a formatted string. // +// This function sets the formatted string value of a comment node. +// bool // O - `true` on success, `false` on failure mxmlSetCommentf(mxml_node_t *node, // I - Node @@ -200,14 +208,16 @@ mxmlSetCommentf(mxml_node_t *node, // I - Node // // 'mxmlSetCustom()' - Set the data and destructor of a custom data node. // -// The node is not changed if it (or its first child) is not a custom node. +// This function sets the data pointer `data` and destructor callback +// `destroy_cb` of a custom data node. The node is not changed if it (or its +// first child) is not a custom node. // bool // O - `true` on success, `false` on failure mxmlSetCustom( mxml_node_t *node, // I - Node to set void *data, // I - New data pointer - mxml_custom_destroy_cb_t destroy) // I - New destructor function + mxml_custom_destroy_cb_t destroy_cb)// I - New destructor function { // Range check input... if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_CUSTOM) @@ -221,7 +231,7 @@ mxmlSetCustom( if (data == node->value.custom.data) { - node->value.custom.destroy = destroy; + node->value.custom.destroy = destroy_cb; return (true); } @@ -230,14 +240,16 @@ mxmlSetCustom( (*(node->value.custom.destroy))(node->value.custom.data); node->value.custom.data = data; - node->value.custom.destroy = destroy; + node->value.custom.destroy = destroy_cb; return (true); } // -// 'mxmlSetDeclaration()' - Set a comment to a literal string. +// 'mxmlSetDeclaration()' - Set a declaration to a literal string. +// +// This function sets the string value of a declaration node. // bool // O - `true` on success, `false` on failure @@ -281,7 +293,9 @@ mxmlSetDeclaration( // -// 'mxmlSetDeclarationf()' - Set a comment to a formatted string. +// 'mxmlSetDeclarationf()' - Set a declaration to a formatted string. +// +// This function sets the formatted string value of a declaration node. // bool // O - `true` on success, `false` on failure @@ -328,7 +342,9 @@ mxmlSetDeclarationf(mxml_node_t *node, // I - Node // -// 'mxmlSetDirective()' - Set a directive to a literal string. +// 'mxmlSetDirective()' - Set a processing instruction to a literal string. +// +// This function sets the string value of a processing instruction node. // bool // O - `true` on success, `false` on failure @@ -371,7 +387,10 @@ mxmlSetDirective(mxml_node_t *node, // I - Node // -// 'mxmlSetDirectivef()' - Set a directive to a formatted string. +// 'mxmlSetDirectivef()' - Set a processing instruction to a formatted string. +// +// This function sets the formatted string value of a processing instruction +// node. // bool // O - `true` on success, `false` on failure @@ -420,7 +439,8 @@ mxmlSetDirectivef(mxml_node_t *node, // I - Node // // 'mxmlSetElement()' - Set the name of an element node. // -// The node is not changed if it is not an element node. +// This function sets the name of an element node. The node is not changed if +// it is not an element node. // bool // O - `true` on success, `false` on failure @@ -462,7 +482,8 @@ mxmlSetElement(mxml_node_t *node, // I - Node to set // // 'mxmlSetInteger()' - Set the value of an integer node. // -// The node is not changed if it (or its first child) is not an integer node. +// This function sets the value of an integer node. The node is not changed if +// it (or its first child) is not an integer node. // bool // O - `true` on success, `false` on failure @@ -489,7 +510,8 @@ mxmlSetInteger(mxml_node_t *node, // I - Node to set // // 'mxmlSetOpaque()' - Set the value of an opaque node. // -// The node is not changed if it (or its first child) is not an opaque node. +// This function sets the string value of an opaque node. The node is not +// changed if it (or its first child) is not an opaque node. // bool // O - `true` on success, `false` on failure @@ -534,7 +556,8 @@ mxmlSetOpaque(mxml_node_t *node, // I - Node to set // // 'mxmlSetOpaquef()' - Set the value of an opaque string node to a formatted string. // -// The node is not changed if it (or its first child) is not an opaque node. +// This function sets the formatted string value of an opaque node. The node is +// not changed if it (or its first child) is not an opaque node. // bool // O - `true` on success, `false` on failure @@ -581,19 +604,17 @@ mxmlSetOpaquef(mxml_node_t *node, // I - Node to set // -// 'mxmlSetReal()' - Set the value of a real number node. +// 'mxmlSetReal()' - Set the value of a real value node. // -// The node is not changed if it (or its first child) is not a real number node. +// This function sets the value of a real value node. The node is not changed +// if it (or its first child) is not a real value node. // bool // O - `true` on success, `false` on failure mxmlSetReal(mxml_node_t *node, // I - Node to set double real) // I - Real number value { - /* - * Range check input... - */ - + // Range check input... if (node && node->type == MXML_TYPE_ELEMENT && node->child && node->child->type == MXML_TYPE_REAL) node = node->child; @@ -613,7 +634,8 @@ mxmlSetReal(mxml_node_t *node, // I - Node to set // // 'mxmlSetText()' - Set the value of a text node. // -// The node is not changed if it (or its first child) is not a text node. +// This function sets the string and whitespace values of a text node. The node +// is not changed if it (or its first child) is not a text node. // bool // O - `true` on success, `false` on failure @@ -664,6 +686,7 @@ mxmlSetText(mxml_node_t *node, // I - Node to set // // 'mxmlSetTextf()' - Set the value of a text node to a formatted string. // +// This function sets the formatted string and whitespace values of a text node. // The node is not changed if it (or its first child) is not a text node. //