mirror of
https://github.com/michaelrsweet/mxml.git
synced 2024-11-24 03:15:30 +00:00
Add migration chapter and update examples.
This commit is contained in:
Michael R Sweet
parent
0cd995c772
commit
bc28dde728
1352
doc/body.md
1352
doc/body.md
File diff suppressed because it is too large
Load Diff
439
doc/mxml.3
439
doc/mxml.3
@ -1,4 +1,4 @@
|
||||
.TH mxml 3 "Mini-XML API" "2022-07-25" "Mini-XML API"
|
||||
.TH mxml 3 "Mini-XML API" "2024-03-02" "Mini-XML API"
|
||||
.SH NAME
|
||||
mxml \- Mini-XML API
|
||||
.SH INCLUDE FILE
|
||||
@ -178,57 +178,85 @@ is used for a particular node or the entire tree:
|
||||
.SS mxml_sax_event_e
|
||||
SAX event type.
|
||||
.TP 5
|
||||
MXML_SAX_CDATA
|
||||
MXML_SAX_EVENT_CDATA
|
||||
.br
|
||||
CDATA node
|
||||
.TP 5
|
||||
MXML_SAX_COMMENT
|
||||
MXML_SAX_EVENT_COMMENT
|
||||
.br
|
||||
Comment node
|
||||
.TP 5
|
||||
MXML_SAX_DATA
|
||||
MXML_SAX_EVENT_DATA
|
||||
.br
|
||||
Data node
|
||||
.TP 5
|
||||
MXML_SAX_DIRECTIVE
|
||||
MXML_SAX_EVENT_DECLARATION
|
||||
.br
|
||||
Processing directive node
|
||||
Declaration node
|
||||
.TP 5
|
||||
MXML_SAX_ELEMENT_CLOSE
|
||||
MXML_SAX_EVENT_DIRECTIVE
|
||||
.br
|
||||
Processing instruction node
|
||||
.TP 5
|
||||
MXML_SAX_EVENT_ELEMENT_CLOSE
|
||||
.br
|
||||
Element closed
|
||||
.TP 5
|
||||
MXML_SAX_ELEMENT_OPEN
|
||||
MXML_SAX_EVENT_ELEMENT_OPEN
|
||||
.br
|
||||
Element opened
|
||||
.SS mxml_type_e
|
||||
The XML node type.
|
||||
.TP 5
|
||||
MXML_CUSTOM
|
||||
MXML_TYPE_CDATA
|
||||
.br
|
||||
Custom data
|
||||
CDATA value ("
|
||||
.URL [CDATA[...]] [CDATA[...]]
|
||||
")
|
||||
.TP 5
|
||||
MXML_ELEMENT
|
||||
MXML_TYPE_COMMENT
|
||||
.br
|
||||
Comment ("
|
||||
.URL !--...-- !--...--
|
||||
")
|
||||
.TP 5
|
||||
MXML_TYPE_CUSTOM
|
||||
.br
|
||||
Custom data
|
||||
.TP 5
|
||||
MXML_TYPE_DECLARATION
|
||||
.br
|
||||
Declaration ("
|
||||
.URL !... !...
|
||||
")
|
||||
.TP 5
|
||||
MXML_TYPE_DIRECTIVE
|
||||
.br
|
||||
Processing instruction ("
|
||||
.URL ?...? ?...?
|
||||
")
|
||||
.TP 5
|
||||
MXML_TYPE_ELEMENT
|
||||
.br
|
||||
XML element with attributes
|
||||
.TP 5
|
||||
MXML_IGNORE
|
||||
MXML_TYPE_IGNORE
|
||||
.br
|
||||
Ignore/throw away node
|
||||
Ignore/throw away node
|
||||
.TP 5
|
||||
MXML_INTEGER
|
||||
MXML_TYPE_INTEGER
|
||||
.br
|
||||
Integer value
|
||||
.TP 5
|
||||
MXML_OPAQUE
|
||||
MXML_TYPE_OPAQUE
|
||||
.br
|
||||
Opaque string
|
||||
.TP 5
|
||||
MXML_REAL
|
||||
MXML_TYPE_REAL
|
||||
.br
|
||||
Real value
|
||||
.TP 5
|
||||
MXML_TEXT
|
||||
MXML_TYPE_TEXT
|
||||
.br
|
||||
Text fragment
|
||||
.SH FUNCTIONS
|
||||
@ -270,8 +298,6 @@ void mxmlElementDeleteAttr (
|
||||
const char *name
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlElementGetAttr
|
||||
Get an attribute.
|
||||
.PP
|
||||
@ -297,18 +323,14 @@ const char * mxmlElementGetAttrByIndex (
|
||||
.PP
|
||||
The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index
|
||||
is out of range.
|
||||
|
||||
|
||||
.SS mxmlElementGetAttrCount
|
||||
Get the number of element attributes.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlElementGetAttrCount (
|
||||
size_t mxmlElementGetAttrCount (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlElementSetAttr
|
||||
Set an attribute.
|
||||
.PP
|
||||
@ -340,13 +362,11 @@ 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.
|
||||
|
||||
|
||||
.SS mxmlEntityAddCallback
|
||||
Add a callback to convert entities to Unicode.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlEntityAddCallback (
|
||||
bool mxmlEntityAddCallback (
|
||||
mxml_entity_cb_t cb
|
||||
);
|
||||
.fi
|
||||
@ -369,7 +389,7 @@ int mxmlEntityGetValue (
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The entity name can also be a numeric constant. -1 is returned if the
|
||||
The entity name can also be a numeric constant. \fB-1\fR is returned if the
|
||||
name is not known.
|
||||
.SS mxmlEntityRemoveCallback
|
||||
Remove a callback.
|
||||
@ -417,8 +437,6 @@ considered a wildcard for one or more levels of elements. For example,
|
||||
.PP
|
||||
The first child node of the found node is returned if the given node has
|
||||
children and the first child is a value node.
|
||||
|
||||
|
||||
.SS mxmlGetCDATA
|
||||
Get the value for a CDATA node.
|
||||
.PP
|
||||
@ -429,8 +447,16 @@ const char * mxmlGetCDATA (
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not a CDATA element.
|
||||
|
||||
|
||||
.SS mxmlGetComment
|
||||
Get the value for a comment node.
|
||||
.PP
|
||||
.nf
|
||||
const char * mxmlGetComment (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not a comment.
|
||||
.SS mxmlGetCustom
|
||||
Get the value for a custom node.
|
||||
.PP
|
||||
@ -442,8 +468,26 @@ const void * mxmlGetCustom (
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node (or its first child) is not a custom
|
||||
value node.
|
||||
|
||||
|
||||
.SS mxmlGetDeclaration
|
||||
Get the value for a declaration node.
|
||||
.PP
|
||||
.nf
|
||||
const char * mxmlGetDeclaration (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not a declaration.
|
||||
.SS mxmlGetDirective
|
||||
Get the value for a processing instruction node.
|
||||
.PP
|
||||
.nf
|
||||
const char * mxmlGetDirective (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not a processing instruction.
|
||||
.SS mxmlGetElement
|
||||
Get the name for an element node.
|
||||
.PP
|
||||
@ -454,8 +498,6 @@ const char * mxmlGetElement (
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not an element node.
|
||||
|
||||
|
||||
.SS mxmlGetFirstChild
|
||||
Get the first child of an element node.
|
||||
.PP
|
||||
@ -467,21 +509,17 @@ mxml_node_t * mxmlGetFirstChild (
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not an element node or if the node
|
||||
has no children.
|
||||
|
||||
|
||||
.SS mxmlGetInteger
|
||||
Get the integer value from the specified node or its
|
||||
first child.
|
||||
first child.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlGetInteger (
|
||||
long mxmlGetInteger (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
0 is returned if the node (or its first child) is not an integer value 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.
|
||||
.PP
|
||||
@ -493,8 +531,6 @@ mxml_node_t * mxmlGetLastChild (
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node is not an element node or if the node
|
||||
has no children.
|
||||
|
||||
|
||||
.SS mxmlGetNextSibling
|
||||
|
||||
.PP
|
||||
@ -514,8 +550,6 @@ const char * mxmlGetOpaque (
|
||||
.PP
|
||||
\fBNULL\fR is returned if the node (or its first child) is not an opaque
|
||||
value node.
|
||||
|
||||
|
||||
.SS mxmlGetParent
|
||||
Get the parent node.
|
||||
.PP
|
||||
@ -526,8 +560,6 @@ mxml_node_t * mxmlGetParent (
|
||||
.fi
|
||||
.PP
|
||||
\fBNULL\fR is returned for a root node.
|
||||
|
||||
|
||||
.SS mxmlGetPrevSibling
|
||||
Get the previous node for the current parent.
|
||||
.PP
|
||||
@ -538,8 +570,6 @@ mxml_node_t * mxmlGetPrevSibling (
|
||||
.fi
|
||||
.PP
|
||||
\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
|
||||
@ -550,13 +580,11 @@ double mxmlGetReal (
|
||||
.fi
|
||||
.PP
|
||||
0.0 is returned if the node (or its first child) is not a real value node.
|
||||
|
||||
|
||||
.SS mxmlGetRefCount
|
||||
Get the current reference (use) count for a node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlGetRefCount (
|
||||
size_t mxmlGetRefCount (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
@ -564,15 +592,13 @@ int mxmlGetRefCount (
|
||||
The initial reference count of new nodes is 1. Use the \fImxmlRetain\fR
|
||||
and \fImxmlRelease\fR functions to increment and decrement a node's
|
||||
reference count.
|
||||
|
||||
\.
|
||||
.SS mxmlGetText
|
||||
Get the text value for a node or its first child.
|
||||
.PP
|
||||
.nf
|
||||
const char * mxmlGetText (
|
||||
mxml_node_t *node,
|
||||
int *whitespace
|
||||
bool *whitespace
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
@ -580,12 +606,10 @@ const char * mxmlGetText (
|
||||
The "whitespace" argument can be \fBNULL\fR.
|
||||
.PP
|
||||
Note: Text nodes consist of whitespace-delimited words. You will only get
|
||||
single words of text when reading an XML file with \fBMXML_TEXT\fR nodes.
|
||||
single words of text when reading an XML file with \fBMXML_TYPE_TEXT\fR nodes.
|
||||
If you want the entire string between elements in the XML file, you MUST read
|
||||
the XML file with \fBMXML_OPAQUE\fR nodes and get the resulting strings
|
||||
the XML file with \fBMXML_TYPE_OPAQUE\fR nodes and get the resulting strings
|
||||
using the \fImxmlGetOpaque\fR function instead.
|
||||
|
||||
|
||||
.SS mxmlGetType
|
||||
Get the node type.
|
||||
.PP
|
||||
@ -595,9 +619,7 @@ mxml_type_t mxmlGetType (
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
\fBMXML_IGNORE\fR is returned if "node" is \fBNULL\fR.
|
||||
|
||||
|
||||
\fBMXML_TYPE_IGNORE\fR is returned if "node" is \fBNULL\fR.
|
||||
.SS mxmlGetUserData
|
||||
Get the user data pointer for a node.
|
||||
.PP
|
||||
@ -606,8 +628,6 @@ void * mxmlGetUserData (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlIndexDelete
|
||||
Delete an index.
|
||||
.PP
|
||||
@ -651,8 +671,6 @@ int mxmlIndexGetCount (
|
||||
mxml_index_t *ind
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlIndexNew
|
||||
Create a new index.
|
||||
.PP
|
||||
@ -671,7 +689,7 @@ sorted by element name and optionally by attribute value if the "attr"
|
||||
argument is not NULL.
|
||||
.SS mxmlIndexReset
|
||||
Reset the enumeration/find pointer in the index and
|
||||
return the first node in the index.
|
||||
return the first node in the index.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlIndexReset (
|
||||
@ -698,8 +716,8 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child (data) nodes of the specified type.
|
||||
.PP
|
||||
Note: The most common programming error when using the Mini-XML library is
|
||||
@ -724,8 +742,8 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child (data) nodes of the specified type.
|
||||
.PP
|
||||
Note: The most common programming error when using the Mini-XML library is
|
||||
@ -750,8 +768,8 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child (data) nodes of the specified type.
|
||||
.PP
|
||||
Note: The most common programming error when using the Mini-XML library is
|
||||
@ -773,9 +791,51 @@ The new CDATA node is added to the end of the specified parent's child
|
||||
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
||||
CDATA node has no parent. The data string must be nul-terminated and
|
||||
is copied into the new node. CDATA nodes currently use the
|
||||
\fBMXML_ELEMENT\fR type.
|
||||
|
||||
|
||||
\fBMXML_TYPE_ELEMENT\fR type.
|
||||
.SS mxmlNewCDATAf
|
||||
Create a new formatted CDATA node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewCDATAf (
|
||||
mxml_node_t *parent,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new CDATA node is added to the end of the specified parent's
|
||||
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
||||
the new opaque string node has no parent. The format string must be
|
||||
nul-terminated and is formatted into the new node.
|
||||
.SS mxmlNewComment
|
||||
Create a new comment node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewComment (
|
||||
mxml_node_t *parent,
|
||||
const char *comment
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new comment node is added to the end of the specified parent's child
|
||||
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
||||
comment node has no parent. The comment string must be nul-terminated and
|
||||
is copied into the new node.
|
||||
.SS mxmlNewCommentf
|
||||
Create a new formatted comment string node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewCommentf (
|
||||
mxml_node_t *parent,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new comment string node is added to the end of the specified parent's
|
||||
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
||||
the new opaque string node has no parent. The format string must be
|
||||
nul-terminated and is formatted into the new node.
|
||||
.SS mxmlNewCustom
|
||||
Create a new custom data node.
|
||||
.PP
|
||||
@ -791,8 +851,64 @@ The new custom node is added to the end of the specified parent's child
|
||||
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
||||
element node has no parent. \fBNULL\fR can be passed when the data in the
|
||||
node is not dynamically allocated or is separately managed.
|
||||
|
||||
|
||||
.SS mxmlNewDeclaration
|
||||
Create a new declaraction node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewDeclaration (
|
||||
mxml_node_t *parent,
|
||||
const char *declaration
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new declaration node is added to the end of the specified parent's child
|
||||
list. The constant \fBMXML_NO_PARENT\fR can be used to specify that the new
|
||||
declaration node has no parent. The declaration string must be nul-
|
||||
terminated and is copied into the new node.
|
||||
.SS mxmlNewDeclarationf
|
||||
Create a new formatted declaration node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewDeclarationf (
|
||||
mxml_node_t *parent,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new declaration node is added to the end of the specified parent's
|
||||
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
||||
the new opaque string node has no parent. The format string must be
|
||||
nul-terminated and is formatted into the new node.
|
||||
.SS mxmlNewDirective
|
||||
Create a new processing instruction node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewDirective (
|
||||
mxml_node_t *parent,
|
||||
const char *directive
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new processing instruction node is added to the end of the specified
|
||||
parent's child list. The constant \fBMXML_NO_PARENT\fR can be used to specify
|
||||
that the new processing instruction node has no parent. The data string must
|
||||
be nul-terminated and is copied into the new node.
|
||||
.SS mxmlNewDirectivef
|
||||
Create a new formatted processing instruction node.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlNewDirectivef (
|
||||
mxml_node_t *parent,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The new processing instruction node is added to the end of the specified parent's
|
||||
child list. The constant \fBMXML_NO_PARENT\fR can be used to specify that
|
||||
the new opaque string node has no parent. The format string must be
|
||||
nul-terminated and is formatted into the new node.
|
||||
.SS mxmlNewElement
|
||||
Create a new element node.
|
||||
.PP
|
||||
@ -812,7 +928,7 @@ Create a new integer node.
|
||||
.nf
|
||||
mxml_node_t * mxmlNewInteger (
|
||||
mxml_node_t *parent,
|
||||
int integer
|
||||
long integer
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
@ -867,7 +983,7 @@ Create a new text fragment node.
|
||||
.nf
|
||||
mxml_node_t * mxmlNewText (
|
||||
mxml_node_t *parent,
|
||||
int whitespace,
|
||||
bool whitespace,
|
||||
const char *string
|
||||
);
|
||||
.fi
|
||||
@ -883,7 +999,7 @@ Create a new formatted text fragment node.
|
||||
.nf
|
||||
mxml_node_t * mxmlNewTextf (
|
||||
mxml_node_t *parent,
|
||||
int whitespace,
|
||||
bool whitespace,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
@ -904,9 +1020,7 @@ mxml_node_t * mxmlNewXML (
|
||||
.fi
|
||||
.PP
|
||||
The "version" argument specifies the version number to put in the
|
||||
?xml element node. If \fBNULL\fR, version "1.0" is assumed.
|
||||
|
||||
|
||||
?xml directive node. If \fBNULL\fR, version "1.0" is assumed.
|
||||
.SS mxmlRelease
|
||||
Release a node.
|
||||
.PP
|
||||
@ -918,8 +1032,6 @@ int mxmlRelease (
|
||||
.PP
|
||||
When the reference count reaches zero, the node (and any children)
|
||||
is deleted via \fImxmlDelete\fR.
|
||||
|
||||
|
||||
.SS mxmlRemove
|
||||
Remove a node from its parent.
|
||||
.PP
|
||||
@ -939,11 +1051,9 @@ int mxmlRetain (
|
||||
mxml_node_t *node
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlSAXLoadFd
|
||||
Load a file descriptor into an XML node tree
|
||||
using a SAX callback.
|
||||
using a SAX callback.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlSAXLoadFd (
|
||||
@ -961,18 +1071,16 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child nodes of the specified type.
|
||||
.PP
|
||||
The SAX callback must call \fImxmlRetain\fR for any nodes that need to
|
||||
be kept for later use. Otherwise, nodes are deleted when the parent
|
||||
node is closed or after each data, comment, CDATA, or directive node.
|
||||
|
||||
|
||||
.SS mxmlSAXLoadFile
|
||||
Load a file into an XML node tree
|
||||
using a SAX callback.
|
||||
using a SAX callback.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlSAXLoadFile (
|
||||
@ -990,18 +1098,16 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child nodes of the specified type.
|
||||
.PP
|
||||
The SAX callback must call \fImxmlRetain\fR for any nodes that need to
|
||||
be kept for later use. Otherwise, nodes are deleted when the parent
|
||||
node is closed or after each data, comment, CDATA, or directive node.
|
||||
|
||||
|
||||
.SS mxmlSAXLoadString
|
||||
Load a string into an XML node tree
|
||||
using a SAX callback.
|
||||
using a SAX callback.
|
||||
.PP
|
||||
.nf
|
||||
mxml_node_t * mxmlSAXLoadString (
|
||||
@ -1019,15 +1125,13 @@ 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
|
||||
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
|
||||
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
|
||||
loading child nodes of the specified type.
|
||||
.PP
|
||||
The SAX callback must call \fImxmlRetain\fR for any nodes that need to
|
||||
be kept for later use. Otherwise, nodes are deleted when the parent
|
||||
node is closed or after each data, comment, CDATA, or directive node.
|
||||
|
||||
|
||||
.SS mxmlSaveAllocString
|
||||
Save an XML tree to an allocated string.
|
||||
.PP
|
||||
@ -1045,14 +1149,14 @@ would produce an empty string or if the string cannot be allocated.
|
||||
.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_TEXT\fR nodes
|
||||
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
|
||||
with leading whitespace and before attribute names inside opening
|
||||
element tags.
|
||||
.SS mxmlSaveFd
|
||||
Save an XML tree to a file descriptor.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSaveFd (
|
||||
bool mxmlSaveFd (
|
||||
mxml_node_t *node,
|
||||
int fd,
|
||||
mxml_save_cb_t cb
|
||||
@ -1061,14 +1165,14 @@ int mxmlSaveFd (
|
||||
.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_TEXT\fR nodes
|
||||
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
|
||||
with leading whitespace and before attribute names inside opening
|
||||
element tags.
|
||||
.SS mxmlSaveFile
|
||||
Save an XML tree to a file.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSaveFile (
|
||||
bool mxmlSaveFile (
|
||||
mxml_node_t *node,
|
||||
FILE *fp,
|
||||
mxml_save_cb_t cb
|
||||
@ -1077,17 +1181,17 @@ int mxmlSaveFile (
|
||||
.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_TEXT\fR nodes
|
||||
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
|
||||
with leading whitespace and before attribute names inside opening
|
||||
element tags.
|
||||
.SS mxmlSaveString
|
||||
Save an XML node tree to a string.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSaveString (
|
||||
size_t mxmlSaveString (
|
||||
mxml_node_t *node,
|
||||
char *buffer,
|
||||
int bufsize,
|
||||
size_t bufsize,
|
||||
mxml_save_cb_t cb
|
||||
);
|
||||
.fi
|
||||
@ -1098,27 +1202,54 @@ into the specified 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_TEXT\fR nodes
|
||||
is specified, whitespace will only be added before \fBMXML_TYPE_TEXT\fR nodes
|
||||
with leading whitespace and before attribute names inside opening
|
||||
element tags.
|
||||
.SS mxmlSetCDATA
|
||||
Set the element name of a CDATA node.
|
||||
Set the data for a CDATA node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetCDATA (
|
||||
bool mxmlSetCDATA (
|
||||
mxml_node_t *node,
|
||||
const char *data
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
The node is not changed if it (or its first child) is not a CDATA element node.
|
||||
|
||||
|
||||
The node is not changed if it (or its first child) is not a CDATA node.
|
||||
.SS mxmlSetCDATAf
|
||||
Set the data for a CDATA to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetCDATAf (
|
||||
mxml_node_t *node,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetComment
|
||||
Set a comment to a literal string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetComment (
|
||||
mxml_node_t *node,
|
||||
const char *comment
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetCommentf
|
||||
Set a comment to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetCommentf (
|
||||
mxml_node_t *node,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetCustom
|
||||
Set the data and destructor of a custom data node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetCustom (
|
||||
bool mxmlSetCustom (
|
||||
mxml_node_t *node,
|
||||
void *data,
|
||||
mxml_custom_destroy_cb_t destroy
|
||||
@ -1126,8 +1257,6 @@ int mxmlSetCustom (
|
||||
.fi
|
||||
.PP
|
||||
The node is not changed if it (or its first child) is not a custom node.
|
||||
|
||||
|
||||
.SS mxmlSetCustomHandlers
|
||||
Set the handling functions for custom data.
|
||||
.PP
|
||||
@ -1143,11 +1272,49 @@ return 0 on success and non-zero on error.
|
||||
.PP
|
||||
The save function accepts a node pointer and must return a malloc'd
|
||||
string on success and \fBNULL\fR on error.
|
||||
.SS mxmlSetDeclaration
|
||||
Set a comment to a literal string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetDeclaration (
|
||||
mxml_node_t *node,
|
||||
const char *declaration
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetDeclarationf
|
||||
Set a comment to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetDeclarationf (
|
||||
mxml_node_t *node,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetDirective
|
||||
Set a directive to a literal string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetDirective (
|
||||
mxml_node_t *node,
|
||||
const char *directive
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetDirectivef
|
||||
Set a directive to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
bool mxmlSetDirectivef (
|
||||
mxml_node_t *node,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
.fi
|
||||
.SS mxmlSetElement
|
||||
Set the name of an element node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetElement (
|
||||
bool mxmlSetElement (
|
||||
mxml_node_t *node,
|
||||
const char *name
|
||||
);
|
||||
@ -1166,9 +1333,9 @@ void mxmlSetErrorCallback (
|
||||
Set the value of an integer node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetInteger (
|
||||
bool mxmlSetInteger (
|
||||
mxml_node_t *node,
|
||||
int integer
|
||||
long integer
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
@ -1177,7 +1344,7 @@ The node is not changed if it (or its first child) is not an integer node.
|
||||
Set the value of an opaque node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetOpaque (
|
||||
bool mxmlSetOpaque (
|
||||
mxml_node_t *node,
|
||||
const char *opaque
|
||||
);
|
||||
@ -1188,7 +1355,7 @@ The node is not changed if it (or its first child) is not an opaque node.
|
||||
Set the value of an opaque string node to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetOpaquef (
|
||||
bool mxmlSetOpaquef (
|
||||
mxml_node_t *node,
|
||||
const char *format,
|
||||
...
|
||||
@ -1196,13 +1363,11 @@ int mxmlSetOpaquef (
|
||||
.fi
|
||||
.PP
|
||||
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.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetReal (
|
||||
bool mxmlSetReal (
|
||||
mxml_node_t *node,
|
||||
double real
|
||||
);
|
||||
@ -1213,9 +1378,9 @@ The node is not changed if it (or its first child) is not a real number node.
|
||||
Set the value of a text node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetText (
|
||||
bool mxmlSetText (
|
||||
mxml_node_t *node,
|
||||
int whitespace,
|
||||
bool whitespace,
|
||||
const char *string
|
||||
);
|
||||
.fi
|
||||
@ -1225,9 +1390,9 @@ The node is not changed if it (or its first child) is not a text node.
|
||||
Set the value of a text node to a formatted string.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetTextf (
|
||||
bool mxmlSetTextf (
|
||||
mxml_node_t *node,
|
||||
int whitespace,
|
||||
bool whitespace,
|
||||
const char *format,
|
||||
...
|
||||
);
|
||||
@ -1238,13 +1403,11 @@ The node is not changed if it (or its first child) is not a text node.
|
||||
Set the user data pointer for a node.
|
||||
.PP
|
||||
.nf
|
||||
int mxmlSetUserData (
|
||||
bool mxmlSetUserData (
|
||||
mxml_node_t *node,
|
||||
void *data
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS mxmlSetWrapMargin
|
||||
Set the wrap margin when saving XML data.
|
||||
.PP
|
||||
@ -1255,8 +1418,6 @@ void mxmlSetWrapMargin (
|
||||
.fi
|
||||
.PP
|
||||
Wrapping is disabled when "column" is 0.
|
||||
|
||||
|
||||
.SS mxmlWalkNext
|
||||
Walk to the next logical node in the tree.
|
||||
.PP
|
||||
@ -1296,7 +1457,7 @@ typedef void(*)(void *) mxml_custom_destroy_cb_t;
|
||||
Custom data load callback function
|
||||
.PP
|
||||
.nf
|
||||
typedef int(*)(mxml_node_t *, const char *) mxml_custom_load_cb_t;
|
||||
typedef bool(*)(mxml_node_t *, const char *) mxml_custom_load_cb_t;
|
||||
.fi
|
||||
.SS mxml_custom_save_cb_t
|
||||
Custom data save callback function
|
||||
|
||||
BIN
doc/mxml.epub
BIN
doc/mxml.epub
Binary file not shown.
1395
doc/mxml.html
1395
doc/mxml.html
File diff suppressed because it is too large
Load Diff
12
mxml-file.c
12
mxml-file.c
@ -223,7 +223,7 @@ mxmlSaveAllocString(
|
||||
// element tags.
|
||||
//
|
||||
|
||||
int // O - 0 on success, -1 on error.
|
||||
bool // O - `true` on success, `false` on error.
|
||||
mxmlSaveFd(mxml_node_t *node, // I - Node to write
|
||||
int fd, // I - File descriptor to write to
|
||||
mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK`
|
||||
@ -264,7 +264,7 @@ mxmlSaveFd(mxml_node_t *node, // I - Node to write
|
||||
// element tags.
|
||||
//
|
||||
|
||||
int // O - 0 on success, -1 on error.
|
||||
bool // O - `true` on success, `false` on error.
|
||||
mxmlSaveFile(mxml_node_t *node, // I - Node to write
|
||||
FILE *fp, // I - File to write to
|
||||
mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK`
|
||||
@ -303,10 +303,10 @@ mxmlSaveFile(mxml_node_t *node, // I - Node to write
|
||||
// element tags.
|
||||
//
|
||||
|
||||
int // O - Size of string
|
||||
size_t // O - Size of string
|
||||
mxmlSaveString(mxml_node_t *node, // I - Node to write
|
||||
char *buffer, // I - String buffer
|
||||
int bufsize, // I - Size of string buffer
|
||||
size_t bufsize, // I - Size of string buffer
|
||||
mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK`
|
||||
{
|
||||
int col; // Final column
|
||||
@ -337,7 +337,7 @@ mxmlSaveString(mxml_node_t *node, // I - Node to write
|
||||
}
|
||||
|
||||
// Return the number of characters...
|
||||
return ((int)(ptr[0] - buffer));
|
||||
return ((size_t)(ptr[0] - buffer));
|
||||
}
|
||||
|
||||
|
||||
@ -1308,7 +1308,7 @@ mxml_load_data(
|
||||
// Use the callback to fill in the custom data...
|
||||
node = mxmlNewCustom(parent, NULL, NULL);
|
||||
|
||||
if ((*global->custom_load_cb)(node, buffer))
|
||||
if (!(*global->custom_load_cb)(node, buffer))
|
||||
{
|
||||
mxml_error("Bad custom value '%s' in parent <%s> on line %d.", buffer, parent ? parent->value.element.name : "null", line);
|
||||
mxmlDelete(node);
|
||||
|
||||
8
mxml.h
8
mxml.h
@ -105,7 +105,7 @@ typedef struct _mxml_node_s mxml_node_t;// An XML node.
|
||||
typedef struct _mxml_index_s mxml_index_t;
|
||||
// An XML node index.
|
||||
|
||||
typedef int (*mxml_custom_load_cb_t)(mxml_node_t *, const char *);
|
||||
typedef bool (*mxml_custom_load_cb_t)(mxml_node_t *, const char *);
|
||||
// Custom data load callback function
|
||||
|
||||
typedef char *(*mxml_custom_save_cb_t)(mxml_node_t *);
|
||||
@ -186,9 +186,9 @@ extern int mxmlRelease(mxml_node_t *node);
|
||||
extern void mxmlRemove(mxml_node_t *node);
|
||||
extern int mxmlRetain(mxml_node_t *node);
|
||||
extern char *mxmlSaveAllocString(mxml_node_t *node, mxml_save_cb_t cb);
|
||||
extern int mxmlSaveFd(mxml_node_t *node, int fd, mxml_save_cb_t cb);
|
||||
extern int mxmlSaveFile(mxml_node_t *node, FILE *fp, mxml_save_cb_t cb);
|
||||
extern int mxmlSaveString(mxml_node_t *node, char *buffer, int bufsize, mxml_save_cb_t cb);
|
||||
extern bool mxmlSaveFd(mxml_node_t *node, int fd, mxml_save_cb_t cb);
|
||||
extern bool mxmlSaveFile(mxml_node_t *node, FILE *fp, mxml_save_cb_t cb);
|
||||
extern size_t mxmlSaveString(mxml_node_t *node, char *buffer, size_t bufsize, mxml_save_cb_t cb);
|
||||
extern mxml_node_t *mxmlSAXLoadFd(mxml_node_t *top, int fd, mxml_load_cb_t cb, mxml_sax_cb_t sax, void *sax_data);
|
||||
extern mxml_node_t *mxmlSAXLoadFile(mxml_node_t *top, FILE *fp, mxml_load_cb_t cb, mxml_sax_cb_t sax, void *sax_data);
|
||||
extern mxml_node_t *mxmlSAXLoadString(mxml_node_t *top, const char *s, mxml_load_cb_t cb, mxml_sax_cb_t sax, void *sax_data);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user