AIR
/
mxml
mirror of https://github.com/michaelrsweet/mxml.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add migration chapter and update examples.

Browse Source
pull/329/head
Michael R Sweet 4 months ago
parent 0cd995c772
commit bc28dde728
No known key found for this signature in database
GPG Key ID: BE67C75EC81F3244
6 changed files with 1977 additions and 1331 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 1442
      doc/body.md
  2. 439
      doc/mxml.3
  3. BIN
      doc/mxml.epub
  4. 1407
      doc/mxml.html
  5. 12
      mxml-file.c
  6. 8
      mxml.h

1442
doc/body.md
View File

File diff suppressed because it is too large Load Diff

439
doc/mxml.3
Unescape View File

@ -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 .SH NAME
mxml \- Mini-XML API mxml \- Mini-XML API
.SH INCLUDE FILE .SH INCLUDE FILE
@ -178,57 +178,85 @@ is used for a particular node or the entire tree:
.SS mxml_sax_event_e .SS mxml_sax_event_e
SAX event type. SAX event type.
.TP 5 .TP 5
MXML_SAX_CDATA MXML_SAX_EVENT_CDATA
.br .br
CDATA node CDATA node
.TP 5 .TP 5
MXML_SAX_COMMENT MXML_SAX_EVENT_COMMENT
.br .br
Comment node Comment node
.TP 5 .TP 5
MXML_SAX_DATA MXML_SAX_EVENT_DATA
.br .br
Data node Data node
.TP 5 .TP 5
MXML_SAX_DIRECTIVE MXML_SAX_EVENT_DECLARATION
.br .br
Processing directive node Declaration node
.TP 5 .TP 5
MXML_SAX_ELEMENT_CLOSE MXML_SAX_EVENT_DIRECTIVE
.br
Processing instruction node
.TP 5
MXML_SAX_EVENT_ELEMENT_CLOSE
.br .br
Element closed Element closed
.TP 5 .TP 5
MXML_SAX_ELEMENT_OPEN MXML_SAX_EVENT_ELEMENT_OPEN
.br .br
Element opened Element opened
.SS mxml_type_e .SS mxml_type_e
The XML node type. The XML node type.
.TP 5 .TP 5
MXML_CUSTOM MXML_TYPE_CDATA
.br
CDATA value ("
.URL [CDATA[...]] [CDATA[...]]
")
.TP 5
MXML_TYPE_COMMENT
.br .br
Custom data Comment ("
.URL !--...-- !--...--
")
.TP 5 .TP 5
MXML_ELEMENT 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 .br
XML element with attributes XML element with attributes
.TP 5 .TP 5
MXML_IGNORE MXML_TYPE_IGNORE
.br .br
Ignore/throw away node Ignore/throw away node
.TP 5 .TP 5
MXML_INTEGER MXML_TYPE_INTEGER
.br .br
Integer value Integer value
.TP 5 .TP 5
MXML_OPAQUE MXML_TYPE_OPAQUE
.br .br
Opaque string Opaque string
.TP 5 .TP 5
MXML_REAL MXML_TYPE_REAL
.br .br
Real value Real value
.TP 5 .TP 5
MXML_TEXT MXML_TYPE_TEXT
.br .br
Text fragment Text fragment
.SH FUNCTIONS .SH FUNCTIONS
@ -270,8 +298,6 @@ void mxmlElementDeleteAttr (
const char *name const char *name
); );
.fi .fi
.PP
.SS mxmlElementGetAttr .SS mxmlElementGetAttr
Get an attribute. Get an attribute.
.PP .PP
@ -297,18 +323,14 @@ const char * mxmlElementGetAttrByIndex (
.PP .PP
The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index The index ("idx") is 0-based. \fBNULL\fR is returned if the specified index
is out of range. is out of range.
.SS mxmlElementGetAttrCount .SS mxmlElementGetAttrCount
Get the number of element attributes. Get the number of element attributes.
.PP .PP
.nf .nf
int mxmlElementGetAttrCount ( size_t mxmlElementGetAttrCount (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
.PP
.SS mxmlElementSetAttr .SS mxmlElementSetAttr
Set an attribute. Set an attribute.
.PP .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 is replaced by the new formatted string. The formatted string value is
copied into the element node. This function does nothing if the node copied into the element node. This function does nothing if the node
is not an element. is not an element.
.SS mxmlEntityAddCallback .SS mxmlEntityAddCallback
Add a callback to convert entities to Unicode. Add a callback to convert entities to Unicode.
.PP .PP
.nf .nf
int mxmlEntityAddCallback ( bool mxmlEntityAddCallback (
mxml_entity_cb_t cb mxml_entity_cb_t cb
); );
.fi .fi
@ -369,7 +389,7 @@ int mxmlEntityGetValue (
); );
.fi .fi
.PP .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. name is not known.
.SS mxmlEntityRemoveCallback .SS mxmlEntityRemoveCallback
Remove a callback. Remove a callback.
@ -417,8 +437,6 @@ considered a wildcard for one or more levels of elements. For example,
.PP .PP
The first child node of the found node is returned if the given node has The first child node of the found node is returned if the given node has
children and the first child is a value node. children and the first child is a value node.
.SS mxmlGetCDATA .SS mxmlGetCDATA
Get the value for a CDATA node. Get the value for a CDATA node.
.PP .PP
@ -429,8 +447,16 @@ const char * mxmlGetCDATA (
.fi .fi
.PP .PP
\fBNULL\fR is returned if the node is not a CDATA element. \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 .SS mxmlGetCustom
Get the value for a custom node. Get the value for a custom node.
.PP .PP
@ -442,8 +468,26 @@ const void * mxmlGetCustom (
.PP .PP
\fBNULL\fR is returned if the node (or its first child) is not a custom \fBNULL\fR is returned if the node (or its first child) is not a custom
value node. 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 .SS mxmlGetElement
Get the name for an element node. Get the name for an element node.
.PP .PP
@ -454,8 +498,6 @@ const char * mxmlGetElement (
.fi .fi
.PP .PP
\fBNULL\fR is returned if the node is not an element node. \fBNULL\fR is returned if the node is not an element node.
.SS mxmlGetFirstChild .SS mxmlGetFirstChild
Get the first child of an element node. Get the first child of an element node.
.PP .PP
@ -467,21 +509,17 @@ mxml_node_t * mxmlGetFirstChild (
.PP .PP
\fBNULL\fR is returned if the node is not an element node or if the node \fBNULL\fR is returned if the node is not an element node or if the node
has no children. has no children.
.SS mxmlGetInteger .SS mxmlGetInteger
Get the integer value from the specified node or its Get the integer value from the specified node or its
first child. first child.
.PP .PP
.nf .nf
int mxmlGetInteger ( long mxmlGetInteger (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
.PP .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 .SS mxmlGetLastChild
Get the last child of an element node. Get the last child of an element node.
.PP .PP
@ -493,8 +531,6 @@ mxml_node_t * mxmlGetLastChild (
.PP .PP
\fBNULL\fR is returned if the node is not an element node or if the node \fBNULL\fR is returned if the node is not an element node or if the node
has no children. has no children.
.SS mxmlGetNextSibling .SS mxmlGetNextSibling
.PP .PP
@ -514,8 +550,6 @@ const char * mxmlGetOpaque (
.PP .PP
\fBNULL\fR is returned if the node (or its first child) is not an opaque \fBNULL\fR is returned if the node (or its first child) is not an opaque
value node. value node.
.SS mxmlGetParent .SS mxmlGetParent
Get the parent node. Get the parent node.
.PP .PP
@ -526,8 +560,6 @@ mxml_node_t * mxmlGetParent (
.fi .fi
.PP .PP
\fBNULL\fR is returned for a root node. \fBNULL\fR is returned for a root node.
.SS mxmlGetPrevSibling .SS mxmlGetPrevSibling
Get the previous node for the current parent. Get the previous node for the current parent.
.PP .PP
@ -538,8 +570,6 @@ mxml_node_t * mxmlGetPrevSibling (
.fi .fi
.PP .PP
\fBNULL\fR is returned if this is the first child for the current parent. \fBNULL\fR is returned if this is the first child for the current parent.
.SS mxmlGetReal .SS mxmlGetReal
Get the real value for a node or its first child. Get the real value for a node or its first child.
.PP .PP
@ -550,13 +580,11 @@ double mxmlGetReal (
.fi .fi
.PP .PP
0.0 is returned if the node (or its first child) is not a real value node. 0.0 is returned if the node (or its first child) is not a real value node.
.SS mxmlGetRefCount .SS mxmlGetRefCount
Get the current reference (use) count for a node. Get the current reference (use) count for a node.
.PP .PP
.nf .nf
int mxmlGetRefCount ( size_t mxmlGetRefCount (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
@ -564,15 +592,13 @@ int mxmlGetRefCount (
The initial reference count of new nodes is 1. Use the \fImxmlRetain\fR The initial reference count of new nodes is 1. Use the \fImxmlRetain\fR
and \fImxmlRelease\fR functions to increment and decrement a node's and \fImxmlRelease\fR functions to increment and decrement a node's
reference count. reference count.
\.
.SS mxmlGetText .SS mxmlGetText
Get the text value for a node or its first child. Get the text value for a node or its first child.
.PP .PP
.nf .nf
const char * mxmlGetText ( const char * mxmlGetText (
mxml_node_t *node, mxml_node_t *node,
int *whitespace bool *whitespace
); );
.fi .fi
.PP .PP
@ -580,12 +606,10 @@ const char * mxmlGetText (
The "whitespace" argument can be \fBNULL\fR. The "whitespace" argument can be \fBNULL\fR.
.PP .PP
Note: Text nodes consist of whitespace-delimited words. You will only get Note: Text nodes consist of whitespace-delimited words. You will only get
single words of text when reading an XML file with \fBMXML_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 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. using the \fImxmlGetOpaque\fR function instead.
.SS mxmlGetType .SS mxmlGetType
Get the node type. Get the node type.
.PP .PP
@ -595,9 +619,7 @@ mxml_type_t mxmlGetType (
); );
.fi .fi
.PP .PP
\fBMXML_IGNORE\fR is returned if "node" is \fBNULL\fR. \fBMXML_TYPE_IGNORE\fR is returned if "node" is \fBNULL\fR.
.SS mxmlGetUserData .SS mxmlGetUserData
Get the user data pointer for a node. Get the user data pointer for a node.
.PP .PP
@ -606,8 +628,6 @@ void * mxmlGetUserData (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
.PP
.SS mxmlIndexDelete .SS mxmlIndexDelete
Delete an index. Delete an index.
.PP .PP
@ -651,8 +671,6 @@ int mxmlIndexGetCount (
mxml_index_t *ind mxml_index_t *ind
); );
.fi .fi
.PP
.SS mxmlIndexNew .SS mxmlIndexNew
Create a new index. Create a new index.
.PP .PP
@ -671,7 +689,7 @@ sorted by element name and optionally by attribute value if the "attr"
argument is not NULL. argument is not NULL.
.SS mxmlIndexReset .SS mxmlIndexReset
Reset the enumeration/find pointer in the index and Reset the enumeration/find pointer in the index and
return the first node in the index. return the first node in the index.
.PP .PP
.nf .nf
mxml_node_t * mxmlIndexReset ( mxml_node_t * mxmlIndexReset (
@ -698,8 +716,8 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire file. The callback for the entire file. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type. loading child (data) nodes of the specified type.
.PP .PP
Note: The most common programming error when using the Mini-XML library is Note: The most common programming error when using the Mini-XML library is
@ -724,8 +742,8 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire file. The callback for the entire file. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type. loading child (data) nodes of the specified type.
.PP .PP
Note: The most common programming error when using the Mini-XML library is Note: The most common programming error when using the Mini-XML library is
@ -750,8 +768,8 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire string. The callback for the entire string. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child (data) nodes of the specified type. loading child (data) nodes of the specified type.
.PP .PP
Note: The most common programming error when using the Mini-XML library is Note: The most common programming error when using the Mini-XML library is
@ -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 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 CDATA node has no parent. The data string must be nul-terminated and
is copied into the new node. CDATA nodes currently use the 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 .SS mxmlNewCustom
Create a new custom data node. Create a new custom data node.
.PP .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 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 element node has no parent. \fBNULL\fR can be passed when the data in the
node is not dynamically allocated or is separately managed. 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 .SS mxmlNewElement
Create a new element node. Create a new element node.
.PP .PP
@ -812,7 +928,7 @@ Create a new integer node.
.nf .nf
mxml_node_t * mxmlNewInteger ( mxml_node_t * mxmlNewInteger (
mxml_node_t *parent, mxml_node_t *parent,
int integer long integer
); );
.fi .fi
.PP .PP
@ -867,7 +983,7 @@ Create a new text fragment node.
.nf .nf
mxml_node_t * mxmlNewText ( mxml_node_t * mxmlNewText (
mxml_node_t *parent, mxml_node_t *parent,
int whitespace, bool whitespace,
const char *string const char *string
); );
.fi .fi
@ -883,7 +999,7 @@ Create a new formatted text fragment node.
.nf .nf
mxml_node_t * mxmlNewTextf ( mxml_node_t * mxmlNewTextf (
mxml_node_t *parent, mxml_node_t *parent,
int whitespace, bool whitespace,
const char *format, const char *format,
... ...
); );
@ -904,9 +1020,7 @@ mxml_node_t * mxmlNewXML (
.fi .fi
.PP .PP
The "version" argument specifies the version number to put in the 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 .SS mxmlRelease
Release a node. Release a node.
.PP .PP
@ -918,8 +1032,6 @@ int mxmlRelease (
.PP .PP
When the reference count reaches zero, the node (and any children) When the reference count reaches zero, the node (and any children)
is deleted via \fImxmlDelete\fR. is deleted via \fImxmlDelete\fR.
.SS mxmlRemove .SS mxmlRemove
Remove a node from its parent. Remove a node from its parent.
.PP .PP
@ -939,11 +1051,9 @@ int mxmlRetain (
mxml_node_t *node mxml_node_t *node
); );
.fi .fi
.PP
.SS mxmlSAXLoadFd .SS mxmlSAXLoadFd
Load a file descriptor into an XML node tree Load a file descriptor into an XML node tree
using a SAX callback. using a SAX callback.
.PP .PP
.nf .nf
mxml_node_t * mxmlSAXLoadFd ( mxml_node_t * mxmlSAXLoadFd (
@ -961,18 +1071,16 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire file. The callback for the entire file. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child nodes of the specified type. loading child nodes of the specified type.
.PP .PP
The SAX callback must call \fImxmlRetain\fR for any nodes that need to 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 be kept for later use. Otherwise, nodes are deleted when the parent
node is closed or after each data, comment, CDATA, or directive node. node is closed or after each data, comment, CDATA, or directive node.
.SS mxmlSAXLoadFile .SS mxmlSAXLoadFile
Load a file into an XML node tree Load a file into an XML node tree
using a SAX callback. using a SAX callback.
.PP .PP
.nf .nf
mxml_node_t * mxmlSAXLoadFile ( mxml_node_t * mxmlSAXLoadFile (
@ -990,18 +1098,16 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire file. The callback for the entire file. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child nodes of the specified type. loading child nodes of the specified type.
.PP .PP
The SAX callback must call \fImxmlRetain\fR for any nodes that need to 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 be kept for later use. Otherwise, nodes are deleted when the parent
node is closed or after each data, comment, CDATA, or directive node. node is closed or after each data, comment, CDATA, or directive node.
.SS mxmlSAXLoadString .SS mxmlSAXLoadString
Load a string into an XML node tree Load a string into an XML node tree
using a SAX callback. using a SAX callback.
.PP .PP
.nf .nf
mxml_node_t * mxmlSAXLoadString ( mxml_node_t * mxmlSAXLoadString (
@ -1019,15 +1125,13 @@ single parent node like
.URL ?xml ?xml .URL ?xml ?xml
for the entire string. The callback for the entire string. The callback
function returns the value type that should be used for child nodes. function returns the value type that should be used for child nodes.
The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR, The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_TYPE_OPAQUE_CALLBACK\fR,
\fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TYPE_TEXT_CALLBACK\fR are defined for
loading child nodes of the specified type. loading child nodes of the specified type.
.PP .PP
The SAX callback must call \fImxmlRetain\fR for any nodes that need to 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 be kept for later use. Otherwise, nodes are deleted when the parent
node is closed or after each data, comment, CDATA, or directive node. node is closed or after each data, comment, CDATA, or directive node.
.SS mxmlSaveAllocString .SS mxmlSaveAllocString
Save an XML tree to an allocated string. Save an XML tree to an allocated string.
.PP .PP
@ -1045,14 +1149,14 @@ would produce an empty string or if the string cannot be allocated.
.PP .PP
The callback argument specifies a function that returns a whitespace The callback argument specifies a function that returns a whitespace
string or \fBNULL\fR before and after each element. If \fBMXML_NO_CALLBACK\fR 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 with leading whitespace and before attribute names inside opening
element tags. element tags.
.SS mxmlSaveFd .SS mxmlSaveFd
Save an XML tree to a file descriptor. Save an XML tree to a file descriptor.
.PP .PP
.nf .nf
int mxmlSaveFd ( bool mxmlSaveFd (
mxml_node_t *node, mxml_node_t *node,
int fd, int fd,
mxml_save_cb_t cb mxml_save_cb_t cb
@ -1061,14 +1165,14 @@ int mxmlSaveFd (
.PP .PP
The callback argument specifies a function that returns a whitespace The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR 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 with leading whitespace and before attribute names inside opening
element tags. element tags.
.SS mxmlSaveFile .SS mxmlSaveFile
Save an XML tree to a file. Save an XML tree to a file.
.PP .PP
.nf .nf
int mxmlSaveFile ( bool mxmlSaveFile (
mxml_node_t *node, mxml_node_t *node,
FILE *fp, FILE *fp,
mxml_save_cb_t cb mxml_save_cb_t cb
@ -1077,17 +1181,17 @@ int mxmlSaveFile (
.PP .PP
The callback argument specifies a function that returns a whitespace The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR 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 with leading whitespace and before attribute names inside opening
element tags. element tags.
.SS mxmlSaveString .SS mxmlSaveString
Save an XML node tree to a string. Save an XML node tree to a string.
.PP .PP
.nf .nf
int mxmlSaveString ( size_t mxmlSaveString (
mxml_node_t *node, mxml_node_t *node,
char *buffer, char *buffer,
int bufsize, size_t bufsize,
mxml_save_cb_t cb mxml_save_cb_t cb
); );
.fi .fi
@ -1098,27 +1202,54 @@ into the specified buffer.
.PP .PP
The callback argument specifies a function that returns a whitespace The callback argument specifies a function that returns a whitespace
string or NULL before and after each element. If \fBMXML_NO_CALLBACK\fR 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 with leading whitespace and before attribute names inside opening
element tags. element tags.
.SS mxmlSetCDATA .SS mxmlSetCDATA
Set the element name of a CDATA node. Set the data for a CDATA node.
.PP .PP
.nf .nf
int mxmlSetCDATA ( bool mxmlSetCDATA (
mxml_node_t *node, mxml_node_t *node,
const char *data const char *data
); );
.fi .fi
.PP .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 .SS mxmlSetCustom
Set the data and destructor of a custom data node. Set the data and destructor of a custom data node.
.PP .PP
.nf .nf
int mxmlSetCustom ( bool mxmlSetCustom (
mxml_node_t *node, mxml_node_t *node,
void *data, void *data,
mxml_custom_destroy_cb_t destroy mxml_custom_destroy_cb_t destroy
@ -1126,8 +1257,6 @@ int mxmlSetCustom (
.fi .fi
.PP .PP
The node is not changed if it (or its first child) is not a custom node. The node is not changed if it (or its first child) is not a custom node.
.SS mxmlSetCustomHandlers .SS mxmlSetCustomHandlers
Set the handling functions for custom data. Set the handling functions for custom data.
.PP .PP
@ -1143,11 +1272,49 @@ return 0 on success and non-zero on error.
.PP .PP
The save function accepts a node pointer and must return a malloc'd The save function accepts a node pointer and must return a malloc'd
string on success and \fBNULL\fR on error. 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 .SS mxmlSetElement
Set the name of an element node. Set the name of an element node.
.PP .PP
.nf .nf
int mxmlSetElement ( bool mxmlSetElement (
mxml_node_t *node, mxml_node_t *node,
const char *name const char *name
); );
@ -1166,9 +1333,9 @@ void mxmlSetErrorCallback (
Set the value of an integer node. Set the value of an integer node.
.PP .PP
.nf .nf
int mxmlSetInteger ( bool mxmlSetInteger (
mxml_node_t *node, mxml_node_t *node,
int integer long integer
); );
.fi .fi
.PP .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. Set the value of an opaque node.
.PP .PP
.nf .nf
int mxmlSetOpaque ( bool mxmlSetOpaque (
mxml_node_t *node, mxml_node_t *node,
const char *opaque 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. Set the value of an opaque string node to a formatted string.
.PP .PP
.nf .nf
int mxmlSetOpaquef ( bool mxmlSetOpaquef (
mxml_node_t *node, mxml_node_t *node,
const char *format, const char *format,
... ...
@ -1196,13 +1363,11 @@ int mxmlSetOpaquef (
.fi .fi
.PP .PP
The node is not changed if it (or its first child) is not an opaque node. The node is not changed if it (or its first child) is not an opaque node.
.SS mxmlSetReal .SS mxmlSetReal
Set the value of a real number node. Set the value of a real number node.
.PP .PP
.nf .nf
int mxmlSetReal ( bool mxmlSetReal (
mxml_node_t *node, mxml_node_t *node,
double real 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. Set the value of a text node.
.PP .PP
.nf .nf
int mxmlSetText ( bool mxmlSetText (
mxml_node_t *node, mxml_node_t *node,
int whitespace, bool whitespace,
const char *string const char *string
); );
.fi .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. Set the value of a text node to a formatted string.
.PP .PP
.nf .nf
int mxmlSetTextf ( bool mxmlSetTextf (
mxml_node_t *node, mxml_node_t *node,
int whitespace, bool whitespace,
const char *format, 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. Set the user data pointer for a node.
.PP .PP
.nf .nf
int mxmlSetUserData ( bool mxmlSetUserData (
mxml_node_t *node, mxml_node_t *node,
void *data void *data
); );
.fi .fi
.PP
.SS mxmlSetWrapMargin .SS mxmlSetWrapMargin
Set the wrap margin when saving XML data. Set the wrap margin when saving XML data.
.PP .PP
@ -1255,8 +1418,6 @@ void mxmlSetWrapMargin (
.fi .fi
.PP .PP
Wrapping is disabled when "column" is 0. Wrapping is disabled when "column" is 0.
.SS mxmlWalkNext .SS mxmlWalkNext
Walk to the next logical node in the tree. Walk to the next logical node in the tree.
.PP .PP
@ -1296,7 +1457,7 @@ typedef void(*)(void *) mxml_custom_destroy_cb_t;
Custom data load callback function Custom data load callback function
.PP .PP
.nf .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 .fi
.SS mxml_custom_save_cb_t .SS mxml_custom_save_cb_t
Custom data save callback function Custom data save callback function

BIN
doc/mxml.epub
View File

Binary file not shown.

1407
doc/mxml.html
View File

File diff suppressed because it is too large Load Diff

12
mxml-file.c
Unescape View File

@ -223,7 +223,7 @@ mxmlSaveAllocString(
// element tags. // 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 mxmlSaveFd(mxml_node_t *node, // I - Node to write
int fd, // I - File descriptor to write to int fd, // I - File descriptor to write to
mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK` 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. // 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 mxmlSaveFile(mxml_node_t *node, // I - Node to write
FILE *fp, // I - File to write to FILE *fp, // I - File to write to
mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK` 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. // element tags.
// //
int // O - Size of string size_t // O - Size of string
mxmlSaveString(mxml_node_t *node, // I - Node to write mxmlSaveString(mxml_node_t *node, // I - Node to write
char *buffer, // I - String buffer 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` mxml_save_cb_t cb) // I - Whitespace callback or `MXML_NO_CALLBACK`
{ {
int col; // Final column int col; // Final column
@ -337,7 +337,7 @@ mxmlSaveString(mxml_node_t *node, // I - Node to write
} }
// Return the number of characters... // 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... // Use the callback to fill in the custom data...
node = mxmlNewCustom(parent, NULL, NULL); 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); mxml_error("Bad custom value '%s' in parent <%s> on line %d.", buffer, parent ? parent->value.element.name : "null", line);
mxmlDelete(node); mxmlDelete(node);

8
mxml.h
Unescape View File

@ -105,7 +105,7 @@ typedef struct _mxml_node_s mxml_node_t;// An XML node.
typedef struct _mxml_index_s mxml_index_t; typedef struct _mxml_index_s mxml_index_t;
// An XML node index. // 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 // Custom data load callback function
typedef char *(*mxml_custom_save_cb_t)(mxml_node_t *); 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 void mxmlRemove(mxml_node_t *node);
extern int mxmlRetain(mxml_node_t *node); extern int mxmlRetain(mxml_node_t *node);
extern char *mxmlSaveAllocString(mxml_node_t *node, mxml_save_cb_t cb); 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 bool 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 bool 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 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 *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 *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); 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);

Write Preview
Loading…
Cancel
Save