This module provides both a native Haskell solution for parsing XML
documents into a stream of events, and a set of parser combinators for
dealing with a stream of events.

The important thing to know about the combinators is that they do not work
on the fully-powered Event datatype; rather, this module defines an
SEvent datatype which only deals with tags, attributes and content. For
most uses, this is sufficient. If you need to parse doctypes, instructions
or contents, you will not be able to use the combinators.

Parsing XML files

Parses a byte stream into Events. This function is implemented fully in
Haskell using attoparsec-text for parsing. The produced error messages do
not give line/column information, so you may prefer to stick with the parser
provided by libxml-enumerator. However, this has the advantage of not
relying on any C libraries.

This relies on detectUtf to determine character encoding, and parseText
to do the actual parsing.

Parses a character stream into Events. This function is implemented
fully in Haskell using attoparsec-text for parsing. The produced error
messages do not give line/column information, so you may prefer to stick
with the parser provided by libxml-enumerator. However, this has the
advantage of not relying on any C libraries.

Automatically determine which UTF variant is being used. This function
first checks for BOMs, removing them as necessary, and then check for the
equivalent of <?xml for each of UTF-8, UTF-16LEBE, and UTF-32LEBE. It
defaults to assuming UTF-8.

A helper function which reads a file from disk using enumFile, detects
character encoding using detectUtf, parses the XML using parseBytes,
converts to an SEvent stream using simplify and then handing off control
to your supplied parser.

SEvent parsing

The most generic way to parse a tag. It takes a predicate for checking if
this is the correct tag name, an AttrParser for handling attributes, and
then a parser for dealing with content.

This function automatically absorbs its balancing closing tag, and will
throw an exception if not all of the attributes or child elements are
consumed. If you want to allow extra attributes, see ignoreAttrs.

A simplified version of tag which matches for specific tag names instead
of taking a predicate function. This is often sufficient, and when combined
with OverloadedStrings and the IsString instance of Name, can prove to be
very concise.

Attribute parsing

A monad for parsing attributes. By default, it requires you to deal with
all attributes present on an element, and will throw an exception if there
are unhandled attributes. Use the requireAttr, optionalAttr et al
functions for handling an attribute, and ignoreAttrs if you would like to
skip the rest of the attributes on an element.