-- 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. It is known for being simple and fast.
--   
--   There are already nice XML libraries in the Text.XML hierarchy. The
--   reason to use Expat is when speed is of concern. From a benchmark that
--   compares getting the length of the root node of a HaXml tree
--   (presumably forcing parsing the entire file) against running an Expat
--   parser with a registered start node handler, Expat is about 12 times
--   faster. This is not a fair benchmark; HaXml does a lot more than this
--   Expat library. But if Expat suffices, it is good for what it does.
@package hexpat
@version 0.2


-- | This module wraps the Expat API directly with IO operations
--   everywhere. 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
--   and returns <tt>True</tt> if there was no parse error.
parse :: Parser -> ByteString -> IO Bool

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

-- | The type of the "element started" callback. The first parameter is the
--   element name; the second are the (attribute, value) pairs.
type StartElementHandler = String -> [(String, String)] -> IO ()

-- | The type of the "element ended" callback. The parameter is the element
--   name.
type EndElementHandler = String -> IO ()

-- | 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.
type CharacterDataHandler = String -> IO ()

-- | 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 ()

-- | <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. <tt>parse</tt> returns
--   <tt>False</tt> on a parse error.
parseChunk :: Parser -> ByteString -> Bool -> IO (Bool)


-- | The Expat.Tree module provides a simplified interface to parsing, that
--   returns a tree of the XML structure. It is written using the
--   lower-level bindings in the <a>Text.XML.Expat.IO</a> module. (Note
--   that this is not a lazy parse of the document: as soon as the root
--   node is accessed, the entire document is parsed.)
module Text.XML.Expat.Tree

-- | <tt>parse enc doc</tt> parses <i>lazy</i> bytestring XML content
--   <tt>doc</tt> with optional encoding override <tt>enc</tt> and returns
--   the root <a>Node</a> of the document if there were no parsing errors.
parse :: Maybe Encoding -> ByteString -> Maybe Node

-- | Simplistic XML tree representation.
data Node
Element :: String -> [(String, String)] -> [Node] -> Node
eName :: Node -> String
eAttrs :: Node -> [(String, String)]
eChildren :: Node -> [Node]
Text :: String -> Node

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