166 lines
6.1 KiB
Text
166 lines
6.1 KiB
Text
=pod
|
|
|
|
I<*But see the L<Bugs and Limitations|/Bugs and Limitations> below.>
|
|
|
|
Yxml is a small (C<6 KiB>) non-validating yet mostly conforming XML parser
|
|
written in C. Its primary goals are small binary size, simplicity and
|
|
correctness. It also happens to be L<pretty fast|/Comparison>.
|
|
|
|
The code can be obtained from the L<git repo|http://g.blicky.net/yxml.git> and
|
|
is available under a permissive MIT license. The only two files you need are
|
|
L<yxml.c|http://g.blicky.net/yxml.git/plain/yxml.c> and
|
|
L<yxml.h|http://g.blicky.net/yxml.git/plain/yxml.h>, which can easily be
|
|
included and compiled as part of your project. Minimal documentation is
|
|
included in yxml.h, more complete documentation is pending.
|
|
|
|
The API follows a simple, mostly buffer-less design and only consists of two
|
|
functions:
|
|
|
|
void yxml_init(yxml_t *x, char *stack, size_t stacksize);
|
|
yxml_ret_t yxml_parse(yxml_t *x, int ch);
|
|
|
|
Be aware that I<simple> is not necessarily I<easy> or I<convenient>. The API is
|
|
relatively low-level and designed to integrate into pretty much any application
|
|
and for any use case. This includes incrementally parsing data from a socket in
|
|
an event-driven fashion and parsing large XML files on memory-restricted
|
|
devices. It is possible to implement a more convenient and high-level API on
|
|
top of yxml, but I'm not very fond of libraries that do more than what I
|
|
strictly need.
|
|
|
|
Yxml is still in a beta stage and hasn't been very thoroughly tested yet. There
|
|
are no tarball releases available at the moment. The API and ABI may still
|
|
change a bit, so I strongly advise against dynamic linking (I'm not sure if
|
|
I'll ever promise a stable ABI, but the API should certainly get stabilized at
|
|
some point).
|
|
|
|
=head3 Features
|
|
|
|
=over
|
|
|
|
=item * Simple and low-level API.
|
|
|
|
=item * Does not require C<malloc()>.
|
|
|
|
=item * Pure C, should be very portable.
|
|
|
|
=item * Recognizes and consumes the UTF-8 BOM.
|
|
|
|
=item * Parses entity references (C<&>) and character references (C<&>).
|
|
|
|
=item * Verifies most well-formedness constraints, including the correct
|
|
nesting of elements.
|
|
|
|
=item * Parses XML documents in any ASCII-compatible encoding.
|
|
|
|
=back
|
|
|
|
But let's not be I<too> optimistic, because there are also...
|
|
|
|
=head3 Bugs and Limitations
|
|
|
|
=over
|
|
|
|
=item * Element and Attribute names may only consist of ASCII characters.
|
|
|
|
=item * Does not verify that non-ASCII characters in attribute values or
|
|
element contents are within the allowed character ranges.
|
|
|
|
=item * A conditional section in a C<< <!DOCTYPE ..> >> declaration will result
|
|
in a parse error.
|
|
|
|
=item * Allows multiple C<< <!DOCTYPE ..> >> declarations.
|
|
|
|
=item * Information encoded in the XML and doctype declarations is currently
|
|
not available through the API.
|
|
|
|
=back
|
|
|
|
I hope to have these issues fixed in the near future.
|
|
|
|
=head3 Non-features
|
|
|
|
And now follows a list of things that are not supported and probably never will
|
|
be. Most items on this list can be implemented on top of yxml.
|
|
|
|
=over
|
|
|
|
=item * Does not verify all well-formedness constraints. In particular, does
|
|
not verify that attribute names within the same element are unique, and does
|
|
not verify that the contents of a C<< <!DOCTYPE ..> >> declaration follow the
|
|
XML grammar.
|
|
|
|
=item * No helper functions to deal with namespaces. Yxml will parse XML files
|
|
with namespaces just fine, but it's up to the application to do the rest.
|
|
|
|
=item * No support for custom entity references, neither through the API nor
|
|
using C<< <!ENTITY> >>.
|
|
|
|
=item * No DTD or XML Schema validation.
|
|
|
|
=item * No XSLT.
|
|
|
|
=item * No XPath.
|
|
|
|
=item * Can't parse documents in a non-ASCII-compatible encoding. You'll have
|
|
to convert it to UTF-8 or something similar first.
|
|
|
|
=item * Doesn't do your household chores.
|
|
|
|
=back
|
|
|
|
|
|
=head2 Comparison
|
|
|
|
The following benchmark compares L<expat|http://expat.sourceforge.net/>,
|
|
L<libxml2|http://xmlsoft.org/> and
|
|
L<Mini-XML|http://www.msweet.org/projects.php?Z3> with yxml. A L<strlen(3)>
|
|
implementation is also included as an indication of the "theoretical" minimum.
|
|
|
|
SIZE PERFORMANCE
|
|
LIB VER LICENSE OBJ STATIC WIKI DISCOGS
|
|
strlen 25 816 0.16 0.09
|
|
expat 2.1.0 MIT 162 139 194 432 1.47 1.09
|
|
libxml2 2.9.1 MIT 464 328 518 816 2.53 1.75
|
|
mxml 2.7 LGPL2+static 32 733 75 832 12.38 7.80
|
|
yxml git MIT 6 015 31 448 1.18 0.73
|
|
|
|
The code for these benchmarks is available in the
|
|
L<bench/|http://g.blicky.net/yxml.git/tree/bench> directory on git. Some
|
|
explanatory notes:
|
|
|
|
=over
|
|
|
|
=item * C<OBJ> is the total size of all object code of the library, measured
|
|
with L<size(1)>.
|
|
|
|
=item * C<STATIC> is the file size of a minimal statically linked binary when
|
|
linked against L<musl|http://www.musl-libc.org/> 0.9.13, measured with
|
|
L<wc(1)> after running L<strip(1)>.
|
|
|
|
=item * The performance is the time, in seconds, to load a large XML file.
|
|
C<WIKI> refers to C<enwiki-20130805-abstract5.xml> (162 MiB) from a L<Wikipedia
|
|
Dump|http://dumps.wikimedia.org/enwiki/>, C<DISCOGS> refers to
|
|
C<discogs_20130801_labels.xml> (94 MiB) from a L<Discogs Data
|
|
Dump|http://www.discogs.com/data/>.
|
|
|
|
=item * Libxml2 has been compiled with most of its features disabled with
|
|
C<./configure>, but it still manages to be the very definition of bloat.
|
|
|
|
=item * Everything has been compiled with gcc 4.8.1 at C<-O2>.
|
|
|
|
=item * Benchmarks are run on Linux 3.10.7 with a 3 Ghz Intel Core Duo E8400
|
|
and with 4GB RAM.
|
|
|
|
=back
|
|
|
|
And just for fun, here's the same comparison when compiled with C<-Os>, i.e.
|
|
optimized for small size. Interestingly enough, Mini-XML actually runs faster
|
|
with C<-Os> than with C<-O2>.
|
|
|
|
SIZE PERFORMANCE
|
|
LIB VER LICENSE OBJ STATIC WIKI DISCOGS
|
|
strlen 25 816 0.16 0.09
|
|
expat 2.1.0 MIT 113 314 145 632 1.58 1.20
|
|
libxml2 2.9.1 MIT 356 948 412 256 3.01 2.08
|
|
mxml 2.7 LGPL2+static 27 725 71 704 11.70 7.44
|
|
yxml git MIT 4 835 30 264 1.72 1.05
|