-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | wrapper for expat, the fast XML parser
--   
--   Expat (<a>http://expat.sourceforge.net/</a>) is a stream-oriented XML
--   parser written in C.
--   
--   This package provides a Haskell binding for Expat, with a choice of
--   tree or SAX-style representation, and it includes an XML formatter. It
--   is extensible to any string type, with String, ByteString and Text
--   provided out of the box.
--   
--   The emphasis is on speed and simplicity. If you want more complete and
--   powerful XML libraries, consider using HaXml or HXT instead.
--   
--   Note that hexpat has undergone a major API change since 0.3.x.
--   
--   Benchmark results on ghc 6.10.1 against HaXml for parsing a 4K xml
--   file with non-threading runtime: HAXML: 2683 us, HEXPAT: low-level
--   parse-no tree: 243 us, lazy-String: 1340 us, lazy-Text: 814 us,
--   strict-String: 1194 us, strict-Text: 732 us
--   
--   With -threaded: HAXML: 2691 us, HEXPAT: low-level parse-no tree: 472
--   us, lazy-String: 1575 us, lazy-Text: 1068 us, strict-String: 1396 us,
--   strict-Text: 964 us
@package hexpat
@version 0.4


-- | Low-level interface to Expat. Unless speed is paramount, this should
--   normally be avoided in favour of the interface provided by
--   <a>Text-XML-Expat-Tree</a>. Basic usage is:
--   
--   <ol>
--   <li>Make a new parser: <a>newParser</a>.</li>
--   <li>Set up callbacks on the parser: <a>setStartElementHandler</a>,
--   etc.</li>
--   <li>Feed data into the parser: <a>parse</a> or <a>parseChunk</a>.</li>
--   </ol>
module Text.XML.Expat.IO
data Parser

-- | Create a <a>Parser</a>. The encoding parameter, if provided, overrides
--   the document's encoding declaration.
newParser :: Maybe Encoding -> IO Parser

-- | <tt>parse data</tt> feeds <i>lazy</i> bytestring data into a parser.
--   It returns Nothing on success, or Just the parse error.
parse :: Parser -> ByteString -> IO (Maybe XMLParseError)

-- | <tt>parseChunk data False</tt> feeds <i>strict</i> ByteString data
--   into a <a>Parser</a>. The end of the data is indicated by passing
--   <tt>True</tt> for the final parameter. It returns Nothing on success,
--   or Just the parse error.
parseChunk :: Parser -> ByteString -> Bool -> IO (Maybe XMLParseError)

-- | Encoding types available for the document encoding.
data Encoding
ASCII :: Encoding
UTF8 :: Encoding
UTF16 :: Encoding
ISO88591 :: Encoding

-- | Parse error, consisting of message text, line number, and column
--   number
data XMLParseError
XMLParseError :: String -> Integer -> Integer -> XMLParseError

-- | The type of the "element started" callback. The first parameter is the
--   element name; the second are the (attribute, value) pairs. Return True
--   to continue parsing as normal, or False to terminate the parse.
type StartElementHandler = CString -> [(CString, CString)] -> IO Bool

-- | The type of the "element ended" callback. The parameter is the element
--   name. Return True to continue parsing as normal, or False to terminate
--   the parse.
type EndElementHandler = CString -> IO Bool

-- | The type of the "character data" callback. The parameter is the
--   character data processed. This callback may be called more than once
--   while processing a single conceptual block of text. Return True to
--   continue parsing as normal, or False to terminate the parse.
type CharacterDataHandler = CStringLen -> IO Bool

-- | Attach a StartElementHandler to a Parser.
setStartElementHandler :: Parser -> StartElementHandler -> IO ()

-- | Attach an EndElementHandler to a Parser.
setEndElementHandler :: Parser -> EndElementHandler -> IO ()

-- | Attach an CharacterDataHandler to a Parser.
setCharacterDataHandler :: Parser -> CharacterDataHandler -> IO ()

-- | This variant of <a>parseChunk</a> must either be called inside
--   <a>withHandlers</a> (safest), or between <a>unsafeSetHandlers</a> and
--   <a>unsafeReleaseHandlers</a>, and this will give you better
--   performance than <a>parseChunk</a> if you process multiple chunks
--   inside.
unsafeParseChunk :: Parser -> ByteString -> Bool -> IO (Maybe XMLParseError)

-- | <a>unsafeParseChunk</a> is required to be called inside
--   <tt>withHandlers</tt>. Safer than using <a>unsafeSetHandlers</a> /
--   <a>unsafeReleaseHandlers</a>.
withHandlers :: Parser -> IO a -> IO a
unsafeSetHandlers :: Parser -> IO ExpatHandlers
unsafeReleaseHandlers :: ExpatHandlers -> IO ()
data ExpatHandlers
encodingToString :: Encoding -> String
instance Eq XMLParseError
instance Show XMLParseError
instance NFData XMLParseError
instance Show Parser


-- | This module provides functions to parse an XML document to a tree
--   structure, either strictly or lazily, as well as a lazy SAX-style
--   interface.
--   
--   Extensible "flavors" give you the ability to use any string type.
--   Three are provided here: String, ByteString and Text.
module Text.XML.Expat.Tree

-- | The tree representation of the XML document.
data Node tag text
Element :: !tag -> ![(tag, text)] -> [Node tag text] -> Node tag text
eName :: Node tag text -> !tag
eAttrs :: Node tag text -> ![(tag, text)]
eChildren :: Node tag text -> [Node tag text]
Text :: !text -> Node tag text

-- | Lazily parse XML to tree. Note that forcing the XMLParseError return
--   value will force the entire parse. Therefore, to ensure lazy
--   operation, don't check the error status until you have processed the
--   tree.
parseTree :: TreeFlavor tag text -> Maybe Encoding -> ByteString -> (Node tag text, Maybe XMLParseError)

-- | Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parseTree' :: TreeFlavor tag text -> Maybe Encoding -> ByteString -> Either XMLParseError (Node tag text)

-- | Encoding types available for the document encoding.
data Encoding
ASCII :: Encoding
UTF8 :: Encoding
UTF16 :: Encoding
ISO88591 :: Encoding

-- | Parse error, consisting of message text, line number, and column
--   number
data XMLParseError
XMLParseError :: String -> Integer -> Integer -> XMLParseError

-- | Lazily parse XML to SAX events. In the event of an error, FailDocument
--   is the last element of the output list.
parseSAX :: TreeFlavor tag text -> Maybe Encoding -> ByteString -> [SAXEvent tag text]
data SAXEvent tag text
StartElement :: tag -> [(tag, text)] -> SAXEvent tag text
EndElement :: tag -> SAXEvent tag text
CharacterData :: text -> SAXEvent tag text
FailDocument :: XMLParseError -> SAXEvent tag text
data TreeFlavor tag text
TreeFlavor :: (CString -> IO tag) -> (CStringLen -> IO text) -> (tag -> Put) -> (text -> ByteString) -> TreeFlavor tag text

-- | Flavor for String data type.
stringFlavor :: TreeFlavor String String

-- | Flavor for ByteString data type, containing UTF-8 encoded Unicode.
byteStringFlavor :: TreeFlavor ByteString ByteString

-- | Flavor for Text data type.
textFlavor :: TreeFlavor Text Text
instance (Eq tag, Eq text) => Eq (SAXEvent tag text)
instance (Show tag, Show text) => Show (SAXEvent tag text)
instance (Eq tag, Eq text) => Eq (Node tag text)
instance (Show tag, Show text) => Show (Node tag text)
instance (NFData tag, NFData text) => NFData (SAXEvent tag text)
instance (NFData tag, NFData text) => NFData (Node tag text)


-- | This module provides lazy functions to format a tree structure as
--   UTF-8 encoded XML.
module Text.XML.Expat.Format

-- | Format document with &lt;?xml.. header.
formatTree :: TreeFlavor tag text -> Node tag text -> ByteString

-- | Format XML node with no header.
formatNode :: TreeFlavor tag text -> Node tag text -> ByteString

-- | <a>Put</a> interface for formatting a tree with &lt;?xml.. header.
putTree :: TreeFlavor tag text -> Node tag text -> Put

-- | <a>Put</a> interface for formatting a node with no header.
putNode :: TreeFlavor tag text -> Node tag text -> Put


-- | With the default flavors for <a>parseTree</a> and <a>formatTree</a>,
--   qualified tag and attribute names such as &lt;abc:hello&gt; are
--   represented just as a string containing a colon, e.g. "abc:hello".
--   
--   This module provides flavors that handle these more intelligently,
--   splitting all tag and attribute names into their Prefix and LocalPart
--   components.
module Text.XML.Expat.Qualified
data QName text
QName :: Maybe text -> !text -> QName text
qnPrefix :: QName text -> Maybe text
qnLocalPart :: QName text -> !text

-- | Make a new QName from a prefix and localPart.
mkQName :: text -> text -> QName text

-- | Make a new QName with no prefix.
mkAnName :: text -> QName text

-- | Flavor for qualified tags, using String data type.
qualifiedStringFlavor :: TreeFlavor (QName String) String

-- | Flavor for qualified tags, using ByteString data type, containing
--   UTF-8 encoded Unicode.
qualifiedByteStringFlavor :: TreeFlavor (QName ByteString) ByteString

-- | Flavor for qualified tags, using Text data type.
qualifiedTextFlavor :: TreeFlavor (QName Text) Text
instance (Eq text) => Eq (QName text)
instance (Show text) => Show (QName text)
instance (NFData text) => NFData (QName text)