[xml] new SAX2 API

[Graham Bennett <graham-libxml simulcra org>]

Here's some more summarisation of my experiences of coding against the
SAX2 API so far..

In order to initialise the SAX handler struct, I had to do something
like:

::memset(ctxt->sax, 0, sizeof(xmlSAXHandler)); // set some callbacks
ctxt->sax->initialized = XML_SAX2_MAGIC;

Daniel is going to provide a function which initialises the struct for
the correct SAX API version so people don't have to know about
XML_SAX2_MAGIC.

In general, the new API seems pretty nice.  The changes I had to make
were obviously to override startElementNs and endElementNs instead of
the startElement and endElement callbacks.  Getting namespace
information in these callbacks is pretty painless, much more pleasant to
my mind than in Expat.  (In Expat you have to run through the strings
looking for a separator, in the new libxml API everything is a separate
array element or parameter.)

Error handling: this has been discussed quite a bit already.  My
application is a library that builds a DOM-style tree and is used by
others, so I can't really impose error-handling semantics too much on
client code.  Therefore, what I really want to do is this:

 - if the error is fatal, stop parsing asap, unwind to where I first
   called the parse function and throw an exception (it's C++)  with a
decent error message.

 - if the error is non-fatal (whatever that means :) ), then I would
   still like to know about it, but I will have to leave it up to the
user whether to stop or not.  Therefore I will probably let the user set
a functor which, if present, my lib will call with the error message as
a parameter, so that they can choose what to do.  If they don't set the
functor then I just carry on regardless.  I suppose the functor could
return a boolean indicating whether to stop or not.

 - I would treat warnings much the same as non-fatal errors.

Now, I think the current API allows me to do what I want, with a few
caveats:

 - I would rather have a string error message and some location
   information than the varargs list that is there currently.  At the
moment I have to run through the args building up a string message
myself.

 - How best to stop the parser?  I think there is an xmlStopParser (or
   similar) function that I should be using.  Is there anything else I
need to worry about when stopping the parse?

cheers,

Graham.

-- 
Graham Bennett