iksemel.texi

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

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename iksemel
@setcontentsaftertitlepage
@settitle Iksemel Programmers Manual
@set VERSION 1.2
@c %**end of header

@titlepage
@title iksemel programmers manual
@subtitle A tutorial and API reference for the iksemel library @value{VERSION}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001-2003 G@"urer @"Ozen

This is a free document; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or
(at your option) any later version.You may obtain a copy of the
GNU General Public License from the Free Software Foundation
by visiting their Web site or by writing to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA.

@end titlepage

@ifinfo
@node Top, , , (dir)
@top iksemel Programmers Manual

Copyright @copyright{} 2001-2003 G@"urer @"Ozen

This is a free document; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or
(at your option) any later version.You may obtain a copy of the
GNU General Public License from the Free Software Foundation
by visiting their Web site or by writing to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA.

@menu
* Introduction::

* Tutorials::

* Development::

* Datatype Index::

* Function Index::
@end menu
@end ifinfo

@node Introduction, Tutorials, ,Top
@chapter Introduction

iksemel is an XML (eXtensible Markup Language) parser library
designed for Jabber applications. It is coded in ANSI C for POSIX
compatible environments, thus highly portable. It is free software
released under the GNU Lesser General Public License.

The purprose of this manual is to tell you how to use the facilities
of the iksemel library. Manual is written with the assumption that you
are familiar with the C programming language, basic programming
concepts, XML and Jabber protocol.

@section Compiling the Library

You need to install MinGW (@url{http://mingw.org}) under Windows to be able
to compile iksemel. Although not tested by the author, Cygwin should
work equally well.

Library can be built with:

@example
./configure
make
@end example

If you want to make a self test:

@example
make test
@end example

Now you can install it with:

@example
make install
@end example


@section Using iksemel in Applications

You need to include @file{iksemel.h} file in your source to access library API.
You can do this with:

@code{#include "iksemel.h"}

Now you can use iksemel functions and compile your source. In able to link
your compiled object files and generate your executable program, you have to
link with iksemel library. This can be done with:

@example
gcc -o myprg src1.o src2.o src3.o -liksemel
@end example

iksemel registers itself with pkg-config while installing, so if you are using
autotools in your program, you can simply check the availability of iksemel
and configure your build process accordingly with:

@example
PKG_CHECK_MODULES(IKSEMEL,iksemel,,exit)
@end example

This would result in IKSEMEL_LIBS and IKSEMEL_CFLAGS substitution variables
set to correct values.

@node Tutorials,Development,Introduction,Top
@chapter Tutorials

@ifinfo
@menu
* Parsing an XML Document::

* Working with XML Trees::

* XML Streams::

* Writing a Jabber Client::

* Utility Functions::
@end menu
@end ifinfo


@comment ============================================================
@node Parsing an XML Document,Working with XML Trees,,Tutorials
@section Parsing an XML Document

iksemel parser sequentally processes the XML document. Each encountered XML
element (i.e. tags, character data, comments, processing instructions, etc.)
is reported to your application by calling the hook functions you have provided.
This type of interface is called SAX (serial access) interface.

@tindex iksparser
Parser stores its state in a small structure. This structure is referenced by
@code{iksparser} type, and managed with following functions:

@deftypefun iksparser* iks_sax_new (void* @var{user_data}, iksTagHook* @var{tagHook}, iksCDataHook* @var{cdataHook});
This function allocates and initializes a parser structure. If allocation fails,
NULL value is returned. @var{user_data} is passed directly to hook functions.
@end deftypefun

@deftp Typedef iksTagHook
int iksTagHook (void* @var{user_data}, char* @var{name}, char** @var{atts}, int @var{type});

This function is called when a tag parsed. @var{name} is the name of the tag. If tag has
no attributes @var{atts} is NULL, otherwise it contains a null terminated list of
pointers to tag's attributes and their values. If return value isn't @code{IKS_OK},
it is passed immediately to the caller of the @code{iks_parse}.

@var{type} is one of the following:
@table @code
@item IKS_OPEN
Opening tag, i.e. <tag attr='value'>
@item IKS_CLOSE
Closing tag, i.e. </tag>
@item IKS_SINGLE
Standalone tag, i.e. <tag attr='value'/>
@end table
@end deftp

@deftp Typedef iksCDataHook
int iksCDataHook (void* @var{user_data}, char* @var{data}, size_t @var{len});

@var{data} is a pointer to the character data. Encoding is UTF-8 and it isn't terminated
with a null character. Size of the data is given with @var{len} in bytes. This function
can be called several times with smaller sized data for a single string. If
return value isn't @code{IKS_OK}, it is passed immediately to the caller of the
@code{iks_parse}.
@end deftp

@deftypefun int iks_parse (iksparser* @var{prs}, char *@var{data}, size_t @var{len}, int @var{finish});
You give XML document to the parser with this function. @var{data}
is a @var{len} bytes string. If @var{len} is zero, data must be a null
terminated string.

If @var{finish} value is zero, parser waits for more data later. If you
want to finish parsing without giving data, call it like:
@example
iks_parse (my_parser, NULL, 0, 1);
@end example

You should check the return value for following conditions:
@table @code
@item IKS_OK
There isn't any problem.
@item IKS_NOMEM
Not enough memory.
@item IKS_BADXML
Document is not well-formed.
@item IKS_HOOK
Your hook decided that there is an error.
@end table
@end deftypefun

@deftypefun void iks_parser_delete (iksparser* @var{prs});
This function frees parser structure and associated data.
@end deftypefun

Now we have learned how to create and use a sax parser. Lets parse a simple
XML document. Write following code into a @file{test.c} file.

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

int pr_tag (void *udata, char *name, char **atts, int type)
@{
    switch (type) @{
        case IKS_OPEN:
            printf ("TAG <%s>\n", name);
            break;
        case IKS_CLOSE:
            printf ("TAG </%s>\n", name);
            break;
        case IKS_SINGLE:
            printf ("TAG <%s/>\n", name);
            break;
    @}
    if (atts) @{
        int i = 0;
        while (atts[i]) @{
            printf ("  ATTRIB %s='%s'\n", atts[i], atts[i+1]);
            i += 2;
        @}
    @}
    return IKS_OK;
@}

enum ikserror pr_cdata (void *udata, char *data, size_t len)
@{
    int i;
    printf ("CDATA [");
    for (i = 0; i < len; i++)
        putchar (data[i]);
    printf ("]\n");
    return IKS_OK;
@}

int main (int argc, char *argv[])
@{
    iksparser *p;
    p = iks_sax_new (NULL, pr_tag, pr_cdata);
    switch (iks_parse (p, argv[1], 0, 1)) @{
        case IKS_OK:
            puts ("OK");
            break;
        case IKS_NOMEM:
            puts ("Not enough memory");
            exit (1);
        case IKS_BADXML:
            puts ("XML document is not well-formed");
            exit (2);
        case IKS_HOOK:
            puts ("Our hooks didn't like something");
            exit (2);
    @}
    iks_parser_delete (p);
    return 0;
@}
@end smallexample

Now compile and test it with:

@example
gcc -o test test.c -liksemel
./test "<test>Hello<br/>World!</test>"
./test "<lala a='12' b='42'/>"
@end example

@heading Error Handling

XML standart states that once an error is detected, the processor must not continue
normal processing (i.e. it must not pass character data or markup information to
the application). So iksemel stops processing immediately when it encounters a
syntax error, or one of your hook functions return any one value than @code{IKS_OK},
and @code{iks_parse} function returns with the error code.

Since it is useful for debugging, iksemel provides functions to get position of
the error. Position is usually at the starting character for syntax errors. Since
your hooks are called after whole element (i.e. markup or character data) is
passed, position is at the end of the erroneous element for @code{IKS_HOOK} errors.

@deftypefun {unsigned long} iks_nr_bytes (iksparser* @var{prs});
Returns how many number of bytes parsed.
@end deftypefun

@deftypefun {unsigned long} iks_nr_lines (iksparser* @var{prs});
Returns how many number of lines parsed.
@end deftypefun

If you want to parse another document with your parser again, you should use
the following function to reset your parser.

@deftypefun void iks_parser_reset (iksparser* @var{prs});
Resets the parser's internal state.
@end deftypefun


@comment ============================================================
@node Working with XML Trees,XML Streams,Parsing an XML Document,Tutorials
@section Working with XML Trees

SAX interface uses very little memory, but it forces you to access XML
documents sequentally. In many cases you want to keep a tree like
representation of XML document in memory and want to access and
modify its content randomly.

iksemel provides functions for efficiently creating such trees either
from documents or programmaticaly. You can access and modify this
tree and can easily generate a new XML document from the tree.

This is called DOM (Document Object Model) interface.

@ifinfo
@menu
* Memory Management::

* Creating a Tree::

* Accessing the Tree::

* Converting a Tree into an XML Document::

* Parsing an XML Document into a Tree::
@end menu
@end ifinfo


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

Since keeping whole document content uses a lot of memory and requires
many calls to OS's memory allocation layer, iksemel uses a simple object
stack system for minimizing calls to the @code{malloc} function and releasing
all the memory associated with a tree in a single step.

A parsed XML tree contains following objects:
@table @samp
@item Nodes
These are basic blocks of document. They can contain a tag, attribute pair
of a tag, or character data. Tag nodes can also contain other nodes as
children. Node structure has a small fixed size depending on the node type.
@item Names
Names of tags and attributes. They are utf-8 encoded small strings.
@item Character Data
They are similar to names but usually much bigger.
@end table

iksemel's object stack has two separate areas for keeping these data objects.
Meta chunk contains all the structures and aligned data, while the data chunk
contains strings. Each chunk starts with a choosen size memory block, then
when necessary more blocks allocated for providing space. Unless there is a big
request, each block is double the size of the previous block, thus real memory
needs are quickly reached without allocating too many blocks, or wasting
memory with too big blocks.

@deftp Typedef ikstack
This is a structure defining the object stack. Its fields are private
and subject to change with new iksemel releases.
@end deftp

@deftypefun {ikstack *} iks_stack_new (size_t @var{meta_chunk}, size_t @var{data_chunk});
Creates an object stack. @var{meta_chunk} is the initial size of the
data block used for structures and aligned data. @var{data_chunk} is
the initial size of the data block used for strings. They are both in byte units.

These two initial chunks and a small object stack structure is allocated in
one @code{malloc} call for optimization purproses.
@end deftypefun