diff --git a/documentation.html b/documentation.html index 9f30908..083302d 100644 --- a/documentation.html +++ b/documentation.html @@ -70,18 +70,12 @@ MXML_ADD_TO_PARENT can be used to specify a NULL child pointer.

 void
 mxmlAdd(
-    mxml_node_t * parent,
-    int where,
-    mxml_node_t * child,
-    mxml_node_t * node);
+    mxml_node_t *parent, int where, mxml_node_t *child, mxml_node_t * node);

Arguments

- - -
NameDescription
parentParent node
whereWhere to add, MXML_ADD_BEFORE or MXML_ADD_AFTER
childChild node for where or MXML_ADD_TO_PARENT
nodeNode to add

Returns

@@ -116,14 +110,12 @@ named attribute does not exist.

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

Arguments

-
NameDescription
nodeElement node
nameName of attribute

Returns

@@ -140,16 +132,12 @@ not an element.

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

Arguments

- -
NameDescription
nodeElement node
nameName of attribute
valueAttribute value

Returns

@@ -170,22 +158,12 @@ constrains the search to a particular node's children.

 mxml_node_t *
 mxmlFindElement(
-    mxml_node_t * node,
-    mxml_node_t * top,
-    const char * name,
-    const char * attr,
-    const char * value,
-    int descend);
+    mxml_node_t *node, mxml_node_t *top, const char *name, const char *attr, const char *value, int descend);

Arguments

- - - - -
NameDescription
nodeCurrent node
topTop node
nameElement name or NULL for any
attrAttribute name, or NULL for none
valueAttribute value, or NULL for any
descendDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST

Returns

@@ -204,17 +182,13 @@ MXML_ELEMENT or MXML_TEXT nodes.

 mxml_node_t *
 mxmlLoadFile(
-    mxml_node_t * top,
-    FILE * fp,
-    mxml_type_t (*cb)(mxml_node_t *));
+    mxml_node_t *top, FILE *fp, mxml_type_t (*cb)(mxml_node_t *node));

Arguments

- - - +
NameDescription
topTop node
fpFile to read from
(*cb)(mxml_node_t *)Callback function or MXML_NO_CALLBACK
(*cb)(mxml_node_t *node)Callback function or MXML_NO_CALLBACK

Returns

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

@@ -232,17 +206,13 @@ MXML_ELEMENT or MXML_TEXT nodes.

 mxml_node_t *
 mxmlLoadString(
-    mxml_node_t * top,
-    const char * s,
-    mxml_type_t (*cb)(mxml_node_t *));
+    mxml_node_t *top, const char *s, mxml_type_t (*cb)(mxml_node_t *node));

Arguments

- - - +
NameDescription
topTop node
sString to load
(*cb)(mxml_node_t *)Callback function or MXML_NO_CALLBACK
(*cb)(mxml_node_t *node)Callback function or MXML_NO_CALLBACK

Returns

First node or NULL if the string has errors.

@@ -257,14 +227,12 @@ element node has no parent.

 mxml_node_t *
 mxmlNewElement(
-    mxml_node_t * parent,
-    const char * name);
+    mxml_node_t *parent, const char * name);

Arguments

-
NameDescription
parentParent node or MXML_NO_PARENT
nameName of element

Returns

@@ -280,14 +248,12 @@ integer node has no parent.

 mxml_node_t *
 mxmlNewInteger(
-    mxml_node_t * parent,
-    int integer);
+    mxml_node_t *parent, int integer);

Arguments

-
NameDescription
parentParent node or MXML_NO_PARENT
integerInteger value

Returns

@@ -304,14 +270,12 @@ is copied into the new node.

 mxml_node_t *
 mxmlNewOpaque(
-    mxml_node_t * parent,
-    const char * opaque);
+    mxml_node_t *parent, const char * opaque);

Arguments

-
NameDescription
parentParent node or MXML_NO_PARENT
opaqueOpaque string

Returns

@@ -327,14 +291,12 @@ the new real number node has no parent.

 mxml_node_t *
 mxmlNewReal(
-    mxml_node_t * parent,
-    double real);
+    mxml_node_t *parent, double real);

Arguments

-
NameDescription
parentParent node or MXML_NO_PARENT
realReal number value

Returns

@@ -352,16 +314,12 @@ string must be nul-terminated and is copied into the new node.

 mxml_node_t *
 mxmlNewText(
-    mxml_node_t * parent,
-    int whitespace,
-    const char * string);
+    mxml_node_t *parent, int whitespace, const char * string);

Arguments

- -
NameDescription
parentParent node or MXML_NO_PARENT
whitespace1 = leading whitespace, 0 = no whitespace
stringString

Returns

@@ -399,15 +357,13 @@ allocated.

 char *
 mxmlSaveAllocString(
-    mxml_node_t * node,
-    int (*cb)(mxml_node_t *int));
+    mxml_node_t *node, int (*cb)(mxml_node_t *node, int ws));

Arguments

- - +
NameDescription
nodeNode to write
(*cb)(mxml_node_t *int)Whitespace callback or MXML_NO_CALLBACK
(*cb)(mxml_node_t *node, int ws)Whitespace callback or MXML_NO_CALLBACK

Returns

Allocated string or NULL

@@ -424,17 +380,13 @@ element tags.

 int
 mxmlSaveFile(
-    mxml_node_t * node,
-    FILE * fp,
-    int (*cb)(mxml_node_t *int));
+    mxml_node_t *node, FILE *fp, int (*cb)(mxml_node_t *node, int ws));

Arguments

- - - +
NameDescription
nodeNode to write
fpFile to write to
(*cb)(mxml_node_t *int)Whitespace callback or MXML_NO_CALLBACK
(*cb)(mxml_node_t *node, int ws)Whitespace callback or MXML_NO_CALLBACK

Returns

0 on success, -1 on error.

@@ -449,19 +401,13 @@ into the specified buffer.

 int
 mxmlSaveString(
-    mxml_node_t * node,
-    char * buffer,
-    int bufsize,
-    int (*cb)(mxml_node_t *int));
+    mxml_node_t *node, char *buffer, int bufsize, int (*cb)(mxml_node_t *node, int ws));

Arguments

- - - - +
NameDescription
nodeNode to write
bufferString buffer
bufsizeSize of string buffer
(*cb)(mxml_node_t *int)Whitespace callback or MXML_NO_CALLBACK
(*cb)(mxml_node_t *node, int ws)Whitespace callback or MXML_NO_CALLBACK

Returns

Size of string

@@ -476,16 +422,12 @@ the node's children.

 mxml_node_t *
 mxmlWalkNext(
-    mxml_node_t * node,
-    mxml_node_t * top,
-    int descend);
+    mxml_node_t *node, mxml_node_t *top, int descend);

Arguments

- -
NameDescription
nodeCurrent node
topTop node
descendDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST

Returns

@@ -501,16 +443,12 @@ the walk to the node's children.

 mxml_node_t *
 mxmlWalkPrev(
-    mxml_node_t * node,
-    mxml_node_t * top,
-    int descend);
+    mxml_node_t *node, mxml_node_t *top, int descend);

Arguments

- -
NameDescription
nodeCurrent node
topTop node
descendDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST

Returns

diff --git a/index.html b/index.html index 01789e8..c5a1592 100644 --- a/index.html +++ b/index.html @@ -103,6 +103,8 @@ href="testmxml.c">testmxml.c and mxmldoc.c source files for examples of using Mini-XML.

+

The Basics

+

Mini-XML provides a single header file which you include:

@@ -129,6 +131,54 @@ href="documentation.html#mxmlNewText">mxmlNewText()
 functions. Only elements can have child nodes, and the top node
 must be an element, usually "?xml".

 
+
Each node has pointers for the node above (parent), below (child),
+to the left (prev), and to the right (next) of the current
+node. If you have an XML file like the following:

+
+
+    <?xml version="1.0"?>
+        <node>val1</node>
+        <node>val2</node>
+        <node>val3</node>
+        <group>
+            <node>val4</node>
+            <node>val5</node>
+            <node>val6</node>
+        </group>
+        <node>val7</node>
+        <node>val8</node>
+        <node>val9</node>
+

+
+
the node tree returned by mxmlLoadFile() would look
+like the following in memory:

+
+
+    ?xml
+      |
+    node - node - node - group - node - node - node
+      |      |      |      |       |      |      |
+    val1   val2   val3     |     val7   val8   val9
+                           |
+                         node - node - node
+                           |      |      |
+                         val4   val5   val6
+

+
+
where "-" is a pointer to the next node and "|" is a pointer
+to the first child node.

+
+
Once you are done with the XML data, use the mxmlDelete()
+function to recursively free the memory that is used for a
+particular node or the entire tree:

+
+
+mxmlDelete(tree);
+

+
+
Loading and Saving XML Files

+
 
You load an XML file using the mxmlLoadFile()
 function:

@@ -142,6 +192,15 @@ tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
 fclose(fp);
+

The third argument specifies a callback function which +returns the value type of the immediate children for a new +element node: MXML_INTEGER, MXML_OPAQUE, +MXML_REAL, or MXML_TEXT. This function is +called after the element and its attributes have been +read, so you can look at the element name, attributes, and +attribute values to determine the proper value type to return. +The default value type is MXML_TEXT if no callback is used.

+

Similarly, you save an XML file using the mxmlSaveFile() function:

@@ -155,6 +214,16 @@ mxmlSaveFile(tree, fp, MXML_NO_CALLBACK); fclose(fp); +

Callback functions for saving are used to optionally insert +whitespace before and after elements in the node tree. Your +function will be called up to four times for each element node +with a pointer to the node and a "where" value of +MXML_WS_BEFORE_OPEN, MXML_WS_AFTER_OPEN, +MXML_WS_BEFORE_CLOSE, or MXML_WS_AFTER_CLOSE. +The callback function should return 0 if no whitespace should be +added and the character to insert (space, tab, newline) +otherwise.

+

The mxmlLoadString(), -

You can find a named element/node using the Finding and Iterating Nodes + +

The mxmlWalkPrev() +and mxmlWalkNext()functions +can be used to iterate through the XML node tree:

+ +
+mxml_node_t *node = mxmlWalkPrev(current, tree, MXML_DESCEND);
+
+mxml_node_t *node = mxmlWalkNext(current, tree, MXML_DESCEND);
+
+ +

In addition, you can find a named element/node using the mxmlFindElement() function:

@@ -223,15 +306,64 @@ for (node = mxmlFindElement(tree, tree, "name", NULL, NULL, MXML_DESCEND); } -

Finally, once you are done with the XML data, use the mxmlDelete() -function to recursively free the memory that is used for a -particular node or the entire tree:

+

The MXML_DESCEND argument can actually be one of three constants:

+ + +

Getting Help and Reporting Problems

You can email me at "mxml at easysw dot com" to diff --git a/mxml-file.c b/mxml-file.c index 216e9d2..b6e2688 100644 --- a/mxml-file.c +++ b/mxml-file.c @@ -1,5 +1,5 @@ /* - * "$Id: mxml-file.c,v 1.18 2003/07/23 14:47:17 mike Exp $" + * "$Id: mxml-file.c,v 1.19 2003/07/26 17:24:14 mike Exp $" * * File loading code for mini-XML, a small XML-like file parsing library. * @@ -80,7 +80,7 @@ static int mxml_write_ws(mxml_node_t *node, void *p, mxml_node_t * /* O - First node or NULL if the file could not be read. */ mxmlLoadFile(mxml_node_t *top, /* I - Top node */ FILE *fp, /* I - File to read from */ - mxml_type_t (*cb)(mxml_node_t *)) + mxml_type_t (*cb)(mxml_node_t *node)) /* I - Callback function or MXML_NO_CALLBACK */ { return (mxml_load_data(top, fp, cb, mxml_file_getc)); @@ -101,7 +101,7 @@ mxmlLoadFile(mxml_node_t *top, /* I - Top node */ mxml_node_t * /* O - First node or NULL if the string has errors. */ mxmlLoadString(mxml_node_t *top, /* I - Top node */ const char *s, /* I - String to load */ - mxml_type_t (*cb)(mxml_node_t *)) + mxml_type_t (*cb)(mxml_node_t *node)) /* I - Callback function or MXML_NO_CALLBACK */ { return (mxml_load_data(top, &s, cb, mxml_string_getc)); @@ -120,7 +120,7 @@ mxmlLoadString(mxml_node_t *top, /* I - Top node */ char * /* O - Allocated string or NULL */ mxmlSaveAllocString(mxml_node_t *node, /* I - Node to write */ - int (*cb)(mxml_node_t *, int)) + int (*cb)(mxml_node_t *node, int ws)) /* I - Whitespace callback or MXML_NO_CALLBACK */ { int bytes; /* Required bytes */ @@ -178,7 +178,7 @@ mxmlSaveAllocString(mxml_node_t *node, /* I - Node to write */ int /* O - 0 on success, -1 on error. */ mxmlSaveFile(mxml_node_t *node, /* I - Node to write */ FILE *fp, /* I - File to write to */ - int (*cb)(mxml_node_t *, int)) + int (*cb)(mxml_node_t *node, int ws)) /* I - Whitespace callback or MXML_NO_CALLBACK */ { int col; /* Final column */ @@ -215,7 +215,7 @@ int /* 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 */ - int (*cb)(mxml_node_t *, int)) + int (*cb)(mxml_node_t *node, int ws)) /* I - Whitespace callback or MXML_NO_CALLBACK */ { int col; /* Final column */ @@ -1432,5 +1432,5 @@ mxml_write_ws(mxml_node_t *node, /* I - Current node */ /* - * End of "$Id: mxml-file.c,v 1.18 2003/07/23 14:47:17 mike Exp $". + * End of "$Id: mxml-file.c,v 1.19 2003/07/26 17:24:14 mike Exp $". */ diff --git a/mxml.xml b/mxml.xml index b109e8a..aef9fa0 100644 --- a/mxml.xml +++ b/mxml.xml @@ -7,10 +7,8 @@ on the value of the where 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). The constant MXML_ADD_TO_PARENT can be used to specify a NULL child pointer.mxml_node_t *Parent node -intWhere to add, MXML_ADD_BEFORE or MXML_ADD_AFTER -mxml_node_t *Child node for where or MXML_ADD_TO_PARENT -mxml_node_t *Node to add +name="node" direction="I">mxml_node_t *parent, int where, mxml_node_t +*child, mxml_node_t *Node to add Delete a node and all of its children. @@ -24,8 +22,7 @@ char * This function returns NULL if the node is not an element or the named attribute does not exist.mxml_node_t *Element node -const char *Name of attribute +name="name" direction="I">mxml_node_t *node, const char *Name of attribute Set an attribute. @@ -33,9 +30,8 @@ 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.mxml_node_t *Element node -const char *Name of attribute -const char *Attribute value +name="value" direction="I">mxml_node_t *node, const char *name, const +char *Attribute value Element node or NULLmxml_node_t * @@ -49,12 +45,8 @@ 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.mxml_node_t *Current node -mxml_node_t *Top node -const char *Element name or NULL for any -const char *Attribute name, or NULL for none -const char *Attribute value, or NULL for any -intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST +name="descend" direction="I">mxml_node_t *node, mxml_node_t *top, const +char *name, const char *attr, const char *value, intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST First node or NULL if the file could not be read.mxml_node_t * @@ -66,9 +58,8 @@ single parent node like <?xml> for the entire file. The callback function returns the value type that should be used for child nodes. If MXML_NO_CALLBACK is specified then all child nodes will be either MXML_ELEMENT or MXML_TEXT nodes.mxml_node_t *Top node -FILE *File to read from -mxml_type_tCallback function or MXML_NO_CALLBACK +name="(*cb)(mxml_node_t *node)" direction="I">mxml_node_t *top, FILE +*fp, mxml_type_tCallback function or MXML_NO_CALLBACK First node or NULL if the string has errors.mxml_node_t * @@ -80,9 +71,8 @@ single parent node like <?xml> for the entire string. The callback function returns the value type that should be used for child nodes. If MXML_NO_CALLBACK is specified then all child nodes will be either MXML_ELEMENT or MXML_TEXT nodes.mxml_node_t *Top node -const char *String to load -mxml_type_tCallback function or MXML_NO_CALLBACK +name="(*cb)(mxml_node_t *node)" direction="I">mxml_node_t *top, const +char *s, mxml_type_tCallback function or MXML_NO_CALLBACK New nodemxml_node_t * @@ -91,8 +81,7 @@ name="top" direction="I">mxml_node_t *Top nodemxml_node_t *Parent node or MXML_NO_PARENT -const char *Name of element +name="name" direction="I">mxml_node_t *parent, const char *Name of element New nodemxml_node_t * @@ -101,8 +90,7 @@ name="parent" direction="I">mxml_node_t *Parent node o The new integer node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can be used to specify that the new integer node has no parent.mxml_node_t *Parent node or MXML_NO_PARENT -intInteger value +name="integer" direction="I">mxml_node_t *parent, intInteger value New nodemxml_node_t * @@ -112,8 +100,7 @@ The new opaque node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can be used to specify that the new opaque node has no parent. The opaque string must be nul-terminated and is copied into the new node.mxml_node_t *Parent node or MXML_NO_PARENT -const char *Opaque string +name="opaque" direction="I">mxml_node_t *parent, const char *Opaque string New nodemxml_node_t * @@ -122,8 +109,7 @@ name="parent" direction="I">mxml_node_t *Parent node o The new real number node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can be used to specify that the new real number node has no parent.mxml_node_t *Parent node or MXML_NO_PARENT -doubleReal number value +name="real" direction="I">mxml_node_t *parent, doubleReal number value New nodemxml_node_t * @@ -134,9 +120,8 @@ list. The constant MXML_NO_PARENT can be used to specify that the new text node has no parent. The whitespace parameter is used to specify whether leading whitespace is present before the node. The text string must be nul-terminated and is copied into the new node.mxml_node_t *Parent node or MXML_NO_PARENT -int1 = leading whitespace, 0 = no whitespace -const char *String +name="string" direction="I">mxml_node_t *parent, int whitespace, const +char *String Remove a node from its parent. @@ -153,8 +138,8 @@ representation of the XML node tree. The string should be freed using the free() function when you are done with it. NULL is returned if the node would produce an empty string or if the string cannot be allocated.mxml_node_t *Node to write -intWhitespace callback or MXML_NO_CALLBACK +name="(*cb)(mxml_node_t *node, int ws)" direction="I">mxml_node_t *node, +intWhitespace callback or MXML_NO_CALLBACK 0 on success, -1 on error.int Save an XML tree to a file. @@ -164,9 +149,8 @@ character or nul (0) before and after each element. If MXML_NO_CALLBACK is specified, whitespace will only be added before MXML_TEXT nodes with leading whitespace and before attribute names inside opening element tags.mxml_node_t *Node to write -FILE *File to write to -intWhitespace callback or MXML_NO_CALLBACK +name="(*cb)(mxml_node_t *node, int ws)" direction="I">mxml_node_t *node, +FILE *fp, intWhitespace callback or MXML_NO_CALLBACK Size of stringint Save an XML node tree to a string. @@ -174,10 +158,8 @@ name="node" direction="I">mxml_node_t *Node to writemxml_node_t *Node to write -char *String buffer -intSize of string buffer -intWhitespace callback or MXML_NO_CALLBACK +name="(*cb)(mxml_node_t *node, int ws)" direction="I">mxml_node_t *node, +char *buffer, int bufsize, intWhitespace callback or MXML_NO_CALLBACK Next node or NULLmxml_node_t * @@ -186,9 +168,7 @@ name="node" direction="I">mxml_node_t *Node to writemxml_node_t *Current node -mxml_node_t *Top node -intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST +name="descend" direction="I">mxml_node_t *node, mxml_node_t *top, intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST Previous node or NULLmxml_node_t * @@ -197,9 +177,7 @@ name="node" direction="I">mxml_node_t *Current nodemxml_node_t *Current node -mxml_node_t *Top node -intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST +name="descend" direction="I">mxml_node_t *node, mxml_node_t *top, intDescend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST An XML element attribute value.char *Attribute name diff --git a/mxmldoc.c b/mxmldoc.c index 5747d8b..d4be978 100644 --- a/mxmldoc.c +++ b/mxmldoc.c @@ -1,5 +1,5 @@ /* - * "$Id: mxmldoc.c,v 1.14 2003/07/20 14:37:34 mike Exp $" + * "$Id: mxmldoc.c,v 1.15 2003/07/26 17:24:14 mike Exp $" * * Documentation generator using mini-XML, a small XML-like file parsing * library. @@ -961,7 +961,8 @@ scan_file(const char *filename, /* I - Filename */ break; case STATE_IDENTIFIER : /* Inside a keyword or identifier */ - if (isalnum(ch) || ch == '_' || ch == '[' || ch == ']' || ch == ':') + if (isalnum(ch) || ch == '_' || ch == '[' || ch == ']' || ch == ':' || + (parens && ch == ',')) { if (bufptr < (buffer + sizeof(buffer) - 1)) *bufptr++ = ch; @@ -2080,5 +2081,5 @@ ws_cb(mxml_node_t *node, /* I - Element node */ /* - * End of "$Id: mxmldoc.c,v 1.14 2003/07/20 14:37:34 mike Exp $". + * End of "$Id: mxmldoc.c,v 1.15 2003/07/26 17:24:14 mike Exp $". */