iksemel.texi

linux平台或者windwos平台通用xml 解析器

@deftypefun {void *} iks_stack_alloc (ikstack * @var{stack}, size_t @var{size});
Allocates @var{size} bytes of space from the object stack's meta chunk.
Allocated space is aligned on platform's default alignment boundary and
isn't initialized. Returns a pointer to the space, or NULL if there isn't enough
space available and allocating a new block fails.
@end deftypefun

@deftypefun {void *} iks_stack_strdup (ikstack * @var{stack}, const char * @var{src}, size_t @var{len});
Copies given string @var{src} into the object stack's data chunk. Returns a
pointer to the new string, or NULL if there isn't enough space in the stack.
If @var{len} is zero string must be null terminated.
@end deftypefun

@deftypefun void iks_stack_delete (ikstack * @var{stack});
Gives all memory associated with object stack to the system.
@end deftypefun

Since character data sections are usually parsed in separate blocks,
a growable string implementation is necessary for saving memory.

@deftypefun {char *} iks_stack_strcat (ikstack *@var{stack}, char *@var{old}, size_t @var{old_len}, const char *@var{src}, size_t @var{src_len});
This function appends the string @var{src} to the string @var{old} in the
stack's data chunk. If  @var{old} is NULL it behaves like @code{iks_stack_strdup}.
Otherwise @var{old} has to be a string created with @code{iks_stack_strdup}
or @code{iks_stack_strcat} functions.

If @var{old_len} or @var{src_len} is zero, corresponding string must be null
terminated.

Since string can be moved into another block of the data chunk, you must use the
returned value for new string, and must not reference to @var{old} anymore.
Return value can be NULL if there isn't enough space in stack, and allocating a
new block fails.
@end deftypefun


@comment ============================================================
@node Creating a Tree,Accessing the Tree,Memory Management,Working with XML Trees
@subsection Creating a Tree

@deftp Typedef iks
This is a structure defining a XML node. Its fields are private and only
accessed by following functions.
@end deftp

@deftypefun iks* iks_new (const char *@var{name});
Creates an object stack and creates a IKS_TAG type of node with given
tag name inside the stack. Tag name is also copied into the stack.
Returns the node pointer, or NULL if there isn't enough memory.
@end deftypefun

@deftypefun iks* iks_new_within (const char *@var{name}, ikstack* @var{stack});
Creates a IKS_TAG type of node with the given tag name. Node and tag
name is allocated inside the given object stack. Returns the node
pointer, or NULL if there isn't enough memory.
@end deftypefun

@deftypefun iks* iks_insert (iks *@var{x}, const char *@var{name});
Creates a IKS_TAG type of node with the given tag name. Node and tag
name is allocated inside the @var{x} node's object stack and linked
to @var{x} as a child node. Returns the node pointer, or NULL if there
isn't enough memory.
@end deftypefun

@deftypefun iks* iks_insert_cdata (iks* @var{x}, const char* @var{data}, size_t @var{len});
Creates a IKS_CDATA type of node with given character data. Node is
allocated inside the @var{x} node's object stack and linked to @var{x}
as a child node. Data is copied as well. If @var{len} is zero data must
be a null terminated string. Returns the node pointer, or NULL if
there isn't enough memory.
@end deftypefun

@deftypefun iks* iks_insert_attrib (iks* @var{x}, const char* @var{name}, const char* @var{value});
Creates a IKS_ATTRIBUTE type of node with given attribute name and the
value. Node is allocated inside the @var{x} node's object stack and
linked to @var{x} as an attribute node. Attribute name and value is
copied as well. Returns the node pointer, or NULL if there isn't
enough memory.

Reinserting another value with same attribute name changes an attribute's
value. If @var{value} is NULL, attribute is removed from the tag.
@end deftypefun

@deftypefun iks* iks_insert_node (iks* @var{x}, iks* @var{y});
Links node @var{y} to node @var{x} as a child node. Nodes are not copied
between object stacks, be careful.
@end deftypefun

@deftypefun void iks_hide (iks *@var{x});
Changes the links of the other nodes so that @var{x} becomes invisible.
It stays in the same object stack with neighbour nodes, be careful.
@end deftypefun

@deftypefun void iks_delete (iks *@var{x});
Frees the object stack of the node @var{x}.
@end deftypefun

Now lets create a tree representation of following XML document:

@example
<message type='chat' from='bob@@bd.com'>
<subject>song lyric</subject><priority>high</priority>
<body>
<em style='underline'>here is the correct version:</em>
i just don't see why i should even care
it's not dark yet, but it's getting there
</body>
</message>
@end example

here is the code:

@example
iks *x, *y, *z;

x = iks_new ("message");
iks_insert_attrib (x, "type", "chat");
iks_insert_attrib (x, "from", "bob@@bd.com");
iks_insert_cdata (x, "\n", 1);
iks_insert_cdata (iks_insert (x, "subject"), "song lyric", 10);
iks_insert_cdata (iks_insert (x, "priority"), "high", 4);
iks_insert_cdata (x, "\n", 1);
y = iks_insert (x, "body");
iks_insert_cdata (y, "\n", 1);
z = iks_insert (y, "em");
iks_insert_attrib (z, "style", "underline");
iks_insert_cdata (z, "here is the correct version", 0);
iks_insert_cdata (y, "\n", 1);
iks_insert_cdata (y, "i just don't see why", 0);
iks_insert_cdata (y, "i should even care\n", 0);
iks_insert_cdata (y, "it's not dark yet,", 0);
iks_insert_cdata (y, "but it's getting there\n", 0);
iks_insert_cdata (x, "\n", 1);
@end example

Notice how newlines are inserted for proper formatting of document. They aren't
necessary for representing data, but they make it easier to read document for
humans.

Also notice how @code{iks_insert} and @code{iks_insert_cdata} chained.

There are also functions for duplicating xml trees. They are:

@deftypefun {iks *} iks_copy (iks* @var{x});
Creates a full copy of the tree in a newly created object stack.
@end deftypefun

@deftypefun {iks *} iks_copy_within (iks* @var{x}, ikstack *@var{s});
Creates a full copy of the tree in given object stack.
@end deftypefun

@comment ============================================================
@node Accessing the Tree,Converting a Tree into an XML Document,Creating a Tree,Working with XML Trees
@subsection Accessing a Tree

Basic access functions allow you to move on the tree:

@deftypefun iks* iks_next (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_prev (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_parent (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_child (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_attrib (iks* @var{x});
@end deftypefun

These functions return a pointer to the next, previous, parent, first child,
and first attribute node of the given node @var{x}. If that node doesn't
exist or @var{x} is NULL, a NULL value is returned.

@deftypefun {iks *} iks_root (iks *@var{x});
Returns the topmost parent node of the @var{x}.
@end deftypefun

@deftypefun iks* iks_next_tag (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_prev_tag (iks* @var{x});
@end deftypefun
@deftypefun iks* iks_first_tag (iks* @var{x});
@end deftypefun

These functions return a pointer to the next, previous, first child node
of the given node @var{x}. Only tag nodes are considered, other type
of the nodes are skipped. If such a node doesn't exist or @var{x} is NULL,
a NULL value is returned.

Another group of functions allow you to access specific information and
content of the nodes:

@deftypefun ikstack* iks_stack (iks* @var{x});
Returns the object stack which node @var{x} stays.
@end deftypefun

@deftypefun {enum ikstype} iks_type (iks* @var{x});
Returns the type of the node.

@tindex ikstype
@table @code
@item IKS_TAG
Node is a tag and can contain child nodes and attributes.
@item IKS_CDATA
Node contains character data.
@item IKS_ATTRIBUTE
Node contains an attribute and its value.
@end table
@end deftypefun

@deftypefun char* iks_name (iks* @var{x});
Returns the name of the tag for nodes with the type @var{IKS_TAG}.
Returns an attribute's name for nodes of type IKS_ATTRIBUTE.
@end deftypefun

@deftypefun char* iks_cdata (iks* @var{x});
Returns a pointer to node's character data if available, NULL otherwise.
Returns an attribute's value for nodes of type IKS_ATTRIBUTE.
@end deftypefun

@deftypefun size_t iks_cdata_size (iks *@var{x});
Returns the size of the node's character data in bytes.
@end deftypefun

@deftypefun int iks_has_children (iks *@var{x});
Returns a non-zero value if node @var{x} has a child node.
@end deftypefun

@deftypefun int iks_has_attribs (iks *@var{x});
Returns a non-zero value if node @var{x} has attributes.
@end deftypefun

Last group of the functions simplifies finding and accessing the content
of a specific node:

@deftypefun iks* iks_find (iks *@var{x}, const char *@var{name});
Searches a IKS_TAG type of node with @var{name} as tag name in child
nodes of @var{x}. Returns a pointer to the node if found, NULL otherwise.
@end deftypefun

@deftypefun char* iks_find_cdata (iks* @var{x}, const char* @var{name});
Searches a IKS_TAG type of node with @var{name} as tag name in child
nodes of @var{x}. Returns a pointer to the character data of the node's
first child node if found, NULL otherwise.
@end deftypefun

@deftypefun char* iks_find_attrib (iks* @var{x}, const char* @var{name});
Searches an attribute with given name in attributes of the @var{x}.
Returns a pointer to attribute value if found, NULL otherwise.
@end deftypefun

@deftypefun {iks *} iks_find_with_attrib (iks *@var{x}, const char *@var{tagname}, const char *@var{attrname}, const char *@var{value});
Searches for a child tag of @var{x} which has an attribute with name
@var{attrname} and value @var{value}. If @var{tagname} isn't NULL,
name of the tag must also match. Returns a pointer to the node if found,
NULL otherwise.
@end deftypefun

Here is an example which demonstrates accessing file names in a fictitious
XML playlist file:

@example
<playlist>
    <item type='mpg'>
        <name>/home/madcat/download/matrix_rev_trailer.mpg</name>
        <duration>1:17</duration>
    </item>
    <item type='rm'>
        <name>/home/madcat/anim/clementine_ep1.rm</name>
        <duration>22:00</duration>
    </item>
    <item type='avi'>
        <name>/home/madcat/anim/futurama/ep101.avi</name>
        <subtitle>/home/madcat/subs/futurama/ep101.txt</subtitle>
        <duration>30:00</duration>
    </item>
    <repeat/>
    <fullscreen/>
    <noui/>
</playlist>
@end example

and here is the code:

@example
#include <stdio.h>
#include <iksemel.h>

int main (int argc, char *argv[])
@{
    iks *x, *y;
    int e;

    if (argc < 2) @{
        printf ("usage: %s <playlistfile>", argv[0]);
        return 0;
    @}
    e = iks_load (argv[1], &x);
    if (e != IKS_OK) @{
    	printf ("parse error %d\n", e);
        return 1;
    @}
    if (iks_find (x, "repeat")) puts ("repeat mode enabled");
    y = iks_child (x);
    while (y) @{
        if (iks_type (y) == IKS_TAG
            && strcmp (iks_name (y), "item") == 0) @{
	        printf ("Filename: [%s]\n", iks_find_cdata (y, "name"));
        @}
        y = iks_next (y);
     @}
    iks_delete (x);
    return 0;
@}
@end example


@comment ============================================================
@node Converting a Tree into an XML Document,Parsing an XML Document into a Tree,Accessing the Tree,Working with XML Trees
@subsection Converting a Tree to an XML Document

There is a function for converting given XML tree into a null terminated string.

@deftypefun {char *} iks_string (ikstack* @var{stack}, iks* @var{x});
Converts given tree into a string. String is created inside the given object
stack. Returns a pointer to the string, or NULL if there isn't enough memory
available.

If @var{stack} is NULL, string is created inside an @code{iks_malloc}ed buffer.
You can free it later with @code{iks_free} function.
@end deftypefun

Here is an example which builds a tree and print it.

@example
iks *x;
char *t;

x = iks_new ("test");
iks_insert_cdata (iks_insert (x, "a"), "1234", 4);
iks_insert (x, "br");
iks_insert_cdata (x, "1234", 4);
t = iks_string (iks_stack (x), x);
puts (t);
iks_delete (x);
@end example


@comment ============================================================
@node Parsing an XML Document into a Tree,,Converting a Tree into an XML Document,Working with XML Trees
@subsection Parsing a Document into a Tree

If you want to automatically convert an XML document into a tree, you can use
iksemel's DOM parser. It is created with following function:

@deftypefun iksparser* iks_dom_new (iks **@var{iksptr});
Creates a DOM parser. A pointer to the created XML tree is put into the
variable pointed by @var{iksptr}. Returns a pointer to the parser, or NULL
is there isn't enough memory.
@end deftypefun

Usage is same as SAX parser. You feed the data with @code{iks_parse}, and if
there isn't an error, you can access to your tree from variable @code{*iksptr}.

Here is a simple example:

@example
iks *x;
iksparser *p;

p = iks_dom_new (&x);
if (IKS_OK != iks_parse (p, "<a>bcd</a>", 9, 1)) @{
    puts ("parse error");
@}
/* x is useable after that point */

/* this will print 'bcd' */
printf ("%s\n", iks_cdata (iks_child (x)));
@end example

If you know the size of the file ahead, or you have an approximate idea,
you can tell this to the dom parser for choosing a better memory allocation
strategy. Here is the function for this.