The Expat XML Parser

Update of /cvsroot/expat/expat/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16507 Modified Files: reference.html Log Message: added more detail about XML_CONTEXT_BYTES Index: reference.html =================================================================== RCS file: /cvsroot/expat/expat/doc/reference.html,v retrieving revision 1.59 retrieving revision 1.60 diff -u -d -r1.59 -r1.60 --- reference.html 16 Jul 2004 02:10:57 -0000 1.59 +++ reference.html 16 Jul 2004 02:31:27 -0000 1.60 @@ -345,10 +345,11 @@

In order to read an external DTD, you also have to set an external entity reference handler as described above.

Temporarily Stopping Parsing

Expat 1.95.8 introduces a new feature: its now possible to stop +parsing temporarily from within a handler function, even if more data +has already been passed into the parser. Applications for this +include

To take advantage of this feature, the main parsing loop of an +application needs to support this specifically. It cannot be +supported with a parsing loop compatible with Expat 1.95.7 or +earlier (though existing loops will continue to work without +supporting the stop/resume feature).

An application that uses this feature for a single parser will have +the rough structure (in pseudo-code):

+fd = open_input() +p = create_parser() + +if parse_xml(p, fd) { + /* suspended */ + + int suspended = 1; + + while (suspended) { + do_something_else() + if ready_to_resume() { + suspended = continue_parsing(p, fd); + } + } +} +

An application that may resume any of several parsers based on +input (either from the XML being parsed or some other source) will +certainly have more interesting control structures.

This C function could be used for the parse_xml +function mentioned in the pseudo-code above:

+#define BUFF_SIZE 10240 + +/* Parse a document from the open file descriptor 'fd' until the parse + is complete (the document has been completely parsed, or there's + been an error), or the parse is stopped. Return non-zero when + the parse is merely suspended. +*/ +int +parse_xml(XML_Parser p, int fd) +{ + for (;;) { + int last_chunk; + int bytes_read; + enum XML_Status status; + + void *buff = XML_GetBuffer(p, BUFF_SIZE); + if (buff == NULL) { + /* handle error... */ + return 0; + } + bytes_read = read(fd, buff, BUFF_SIZE); + if (bytes_read < 0) { + /* handle error... */ + return 0; + } + status = XML_ParseBuffer(p, bytes_read, bytes_read == 0); + switch (status) { + case XML_STATUS_ERROR: + /* handle error... */ + return 0; + case XML_STATUS_SUSPENDED: + return 1; + } + if (bytes_read == 0) + return 0; + } +} +

The corresponding continue_parsing function is +somewhat simpler, since it only need deal with the return code from +XML_ResumeParser; it can +delegate the input handling to the parse_xml +function:

+/* Continue parsing a document which had been suspended. The 'p' and + 'fd' arguments are the same as passed to parse_xml(). Return + non-zero when the parse is suspended. +*/ +int +continue_parsing(XML_Parser p, int fd) +{ + enum XML_Status status = XML_ResumeParser(p); + switch (status) { + case XML_STATUS_ERROR: + /* handle error... */ + return 0; + case XML_ERROR_NOT_SUSPENDED: + /* handle error... */ + return 0;. + case XML_STATUS_SUSPENDED: + return 1; + } + return parse_xml(p, fd); +} +

Now that we've seen what a mess the top-level parsing loop can +become, what have we gained? Very simply, we can now use the XML_StopParser function to stop +parsing, without having to go to great lengths to avoid additional +processing that we're expecting to ignore. As a bonus, we get to stop +parsing temporarily, and come back to it when we're +ready.

To stop parsing from a handler function, use the XML_StopParser function. This function +takes two arguments; the parser being stopped and a flag indicating +whether the parse can be resumed in the future.

+ +

Stops parsing, causing XML_Parse or XML_ParseBuffer to return. Must be called from within a +call-back handler, except when aborting (when resumable +is XML_FALSE) an already suspended parser. Some +call-backs may still follow because they would otherwise get +lost, including +

the end element handler for empty elements when stopped in the + start element handler,
end namespace declaration handler when stopped in the end + element handler,

+and possibly others.

+ +

This can be called from most handlers, including DTD related +call-backs, except when parsing an external parameter entity and +resumable is XML_TRUE. Returns +XML_STATUS_OK when successful, +XML_STATUS_ERROR otherwise. The possible error codes +are:

XML_ERROR_SUSPENDED: when suspending an already suspended parser.
XML_ERROR_FINISHED: when the parser has already finished.
XML_ERROR_SUSPEND_PE: when suspending while parsing an external PE.

+ +

Since the stop/resume feature requires application support in the +outer parsing loop, it is an error to call this function for a parser +not being handled appropriately; see Temporarily Stopping Parsing for more information.

+ +

When resumable is XML_TRUE then parsing +is suspended, that is, XML_Parse and XML_ParseBuffer return XML_STATUS_SUSPENDED. +Otherwise, parsing is aborted, that is, XML_Parse and XML_ParseBuffer return +XML_STATUS_ERROR with error code +XML_ERROR_ABORTED.

+ +

Note: +This will be applied to the current parser instance only, that is, if +there is a parent parser then it will continue parsing when the +external entity reference handler returns. It is up to the +implementation of that handler to call XML_StopParser on the parent parser +(recursively), if one wants to stop parsing altogether.

+ +

When suspended, parsing can be resumed by calling XML_ResumeParser.

+ +

New in Expat 1.95.8.

Resumes parsing after it has been suspended with XML_StopParser. Must not be called from +within a handler call-back. Returns same status codes as XML_Parse or XML_ParseBuffer. An additional error +code, XML_ERROR_NOT_SUSPENDED, will be returned if the +parser was not currently suspended.

+ +

Note: +This must be called on the most deeply nested child parser instance +first, and on its parent parser only after the child parser has +finished, to be applied recursively until the document entity's parser +is restarted. That is, the parent parser will not resume by itself +and it is up to the application to call XML_ResumeParser on it at the +appropriate moment.

+ +

New in Expat 1.95.8.

Returns status of parser with respect to being initialized, +parsing, finished, or suspended, and whether the final buffer is being +processed. The status parameter must not be +NULL.

+ +

New in Expat 1.95.8.

Handler Setting

Although handlers are typically set prior to parsing and left alone, an Index: style.css =================================================================== RCS file: /cvsroot/expat/expat/doc/style.css,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- style.css 20 Oct 2003 14:40:44 -0000 1.6 +++ style.css 23 Jul 2004 03:28:09 -0000 1.7 @@ -49,6 +49,17 @@ margin-right: 10%; } +.pseudocode { + padding-left: 1em; + padding-top: .5em; + padding-bottom: .5em; + border: solid thin; + margin: 1em 0; + background-color: rgb(250,220,180); + margin-left: 2em; + margin-right: 10%; +} + .handler { width: 100%; border-top-width: thin; From fdrake at users.sourceforge.net Fri Jul 23 05:38:45 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Fri Jul 23 05:38:48 2004 Subject: [Expat-checkins] expat MANIFEST,1.20,1.21 Message-ID: Update of /cvsroot/expat/expat In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28821 Modified Files: MANIFEST Log Message: added missing files Index: MANIFEST =================================================================== RCS file: /cvsroot/expat/expat/MANIFEST,v retrieving revision 1.20 retrieving revision 1.21 diff -u -d -r1.20 -r1.21 --- MANIFEST 21 Jan 2004 21:30:54 -0000 1.20 +++ MANIFEST 23 Jul 2004 03:38:43 -0000 1.21 @@ -51,9 +51,11 @@ examples/elements.dsp examples/outline.c examples/outline.dsp +lib/Makefile.MPW lib/ascii.h lib/asciitab.h lib/expat.dsp +lib/expat_external.h lib/expat.h lib/expatw.dsp lib/expat_static.dsp From fdrake at users.sourceforge.net Fri Jul 23 05:42:25 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Fri Jul 23 05:42:28 2004 Subject: [Expat-checkins] expat make-release.sh,1.6,1.7 Message-ID: Update of /cvsroot/expat/expat In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29214 Modified Files: make-release.sh Log Message: when controlling the CVS client from a script, we should always disable the personal CVS config file to avoid any unpredictable behavior Index: make-release.sh =================================================================== RCS file: /cvsroot/expat/expat/make-release.sh,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- make-release.sh 11 Oct 2003 17:50:22 -0000 1.6 +++ make-release.sh 23 Jul 2004 03:42:23 -0000 1.7 @@ -22,7 +22,7 @@ fi echo "Checking out into temporary area: $tmpdir" -cvs -d "$CVSROOT" export -r "$1" -d $tmpdir expat || exit 1 +cvs -f -d "$CVSROOT" export -r "$1" -d $tmpdir expat || exit 1 echo "" echo "----------------------------------------------------------------------" From fdrake at users.sourceforge.net Fri Jul 23 05:59:42 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Fri Jul 23 05:59:45 2004 Subject: [Expat-checkins] expat MANIFEST,1.21,1.22 Message-ID: Update of /cvsroot/expat/expat In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31143 Modified Files: MANIFEST Log Message: - add some missing files - re-arrange to make comparison with the actual list of files easier Index: MANIFEST =================================================================== RCS file: /cvsroot/expat/expat/MANIFEST,v retrieving revision 1.21 retrieving revision 1.22 diff -u -d -r1.21 -r1.22 --- MANIFEST 23 Jul 2004 03:38:43 -0000 1.21 +++ MANIFEST 23 Jul 2004 03:59:40 -0000 1.22 @@ -1,13 +1,5 @@ -Changes -COPYING -MANIFEST -Makefile.in -README -configure -configure.in -expat_config.h.in -expat.dsw bcb5/README.txt +bcb5/all_projects.bpg bcb5/elements.bpf bcb5/elements.bpr bcb5/elements.mak @@ -33,20 +25,31 @@ bcb5/xmlwf.bpf bcb5/xmlwf.bpr bcb5/xmlwf.mak +doc/expat.png +doc/reference.html +doc/style.css +doc/valid-xhtml10.png +doc/xmlwf.1 +doc/xmlwf.sgml +COPYING +Changes +MANIFEST +Makefile.in +README +configure +configure.in +expat_config.h.in +expat.dsw conftools/PrintPath conftools/ac_c_bigendian_cross.m4 conftools/config.guess conftools/config.sub conftools/expat.m4 +conftools/get-version.sh conftools/install-sh conftools/libtool.m4 conftools/ltmain.sh conftools/mkinstalldirs -doc/reference.html -doc/style.css -doc/valid-xhtml10.png -doc/xmlwf.1 -doc/xmlwf.sgml examples/elements.c examples/elements.dsp examples/outline.c @@ -55,17 +58,20 @@ lib/ascii.h lib/asciitab.h lib/expat.dsp -lib/expat_external.h lib/expat.h -lib/expatw.dsp +lib/expat_external.h lib/expat_static.dsp +lib/expatw.dsp lib/expatw_static.dsp lib/iasciitab.h lib/internal.h lib/latin1tab.h +lib/libexpat.def lib/libexpatw.def +lib/macconfig.h lib/nametab.h lib/utf8tab.h +lib/winconfig.h lib/xmlparse.c lib/xmlrole.c lib/xmlrole.h @@ -74,17 +80,23 @@ lib/xmltok_impl.c lib/xmltok_impl.h lib/xmltok_ns.c -lib/winconfig.h +tests/benchmark/README.txt +tests/benchmark/benchmark.c +tests/benchmark/benchmark.dsp +tests/benchmark/benchmark.dsw tests/README.txt tests/chardata.c tests/chardata.h +tests/minicheck.c +tests/minicheck.h tests/runtests.c tests/xmltest.sh +vms/README.vms vms/descrip.mms vms/expat_config.h -vms/README.vms -win32/expat.iss win32/MANIFEST.txt +win32/README.txt +win32/expat.iss xmlwf/codepage.c xmlwf/codepage.h xmlwf/ct.c From fdrake at users.sourceforge.net Fri Jul 23 06:48:39 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Fri Jul 23 06:48:42 2004 Subject: [Expat-checkins] expat Changes,1.40,1.41 Message-ID: Update of /cvsroot/expat/expat In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4109 Modified Files: Changes Log Message: add notes for 1.95.8 release Index: Changes =================================================================== RCS file: /cvsroot/expat/expat/Changes,v retrieving revision 1.40 retrieving revision 1.41 diff -u -d -r1.40 -r1.41 --- Changes 20 Oct 2003 21:11:27 -0000 1.40 +++ Changes 23 Jul 2004 04:48:36 -0000 1.41 @@ -1,3 +1,13 @@ +Release 1.95.8 Fri Jul 23 2004 + - Major new feature: suspend/resume. Handlers can now request + that a parse be suspended for later resumption or aborted + altogether. See "Temporarily Stopping Parsing" in the + documentation for more details. + - Some mostly minor bug fixes, but compilation should no + longer generate warnings on most platforms. SF issues + include: 827319, 840173, 846309, 888329, 896188, 923913, + 928113, 961698, 985192. + Release 1.95.7 Mon Oct 20 2003 - Fixed enum XML_Status issue (reported on SourceForge many times), so compilers that are properly picky will be happy. From fdrake at users.sourceforge.net Sat Jul 24 07:26:50 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Sat Jul 24 07:26:54 2004 Subject: [Expat-checkins] expat expat.spec,1.14,1.15 Message-ID: Update of /cvsroot/expat/expat In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29518 Modified Files: expat.spec Log Message: fix busted %changelog entry Index: expat.spec =================================================================== RCS file: /cvsroot/expat/expat/expat.spec,v retrieving revision 1.14 retrieving revision 1.15 diff -u -d -r1.14 -r1.15 --- expat.spec 16 Jul 2004 02:10:56 -0000 1.14 +++ expat.spec 24 Jul 2004 05:26:48 -0000 1.15 @@ -39,8 +39,8 @@ /usr/man/man1/xmlwf.1.gz %changelog -[Release 1.95.8-1] * Fri Jul 16 2004 Fred L. Drake, Jr. +[Release 1.95.8-1] - Update for the 1.95.8 release. - Add the expat_external.h header to the installed files. From fdrake at users.sourceforge.net Mon Jul 26 16:53:42 2004 From: fdrake at users.sourceforge.net (Fred L. Drake) Date: Mon Jul 26 16:53:46 2004 Subject: [Expat-checkins] htdocs index.html,1.51,1.52 Message-ID: Update of /cvsroot/expat/htdocs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20599 Modified Files: index.html Log Message: add news of the 1.95.8 release Index: index.html =================================================================== RCS file: /cvsroot/expat/htdocs/index.html,v retrieving revision 1.51 retrieving revision 1.52 diff -u -d -r1.51 -r1.52 --- index.html 26 Apr 2004 20:36:10 -0000 1.51 +++ index.html 26 Jul 2004 14:53:39 -0000 1.52 @@ -51,6 +51,25 @@

The Expat XML Parser

Miscellaneous functions

Temporarily Stopping Parsing

Handler Setting

News