-- 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
--   <i>tree</i> or <i>SAX-style</i> representation, and it includes an
--   <i>XML formatter</i>. It is extensible to any string type, with
--   <tt>String</tt>, <tt>ByteString</tt> and <tt>Text</tt> provided out of
--   the box.
--   
--   The emphasis is on speed and simplicity. If you want more complete and
--   powerful XML libraries, consider using <i>HaXml</i> or <i>HXT</i>
--   instead.
--   
--   Note that <i>hexpat</i> 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: 2631 us, HEXPAT: low-level
--   parse-no tree: 243 us, lazy-String: 1240 us, lazy-Text: 782 us,
--   strict-String: 1125 us, strict-Text: 770 us
--   
--   With -threaded: HAXML: 2667 us, HEXPAT: low-level parse-no tree: 472
--   us, lazy-String: 1453 us, lazy-Text: 1057 us, strict-String: 1342 us,
--   strict-Text: 943 us
@package hexpat
@version 0.5


-- | 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.
--   
--   The GenericXMLString type class allows you to use any string type.
--   Three string types are provided for here: <tt>String</tt>,
--   <tt>ByteString</tt> and <tt>Text</tt>.
--   
--   Error handling in strict parses is very straight forward - just check
--   the <a>Either</a> return value. Lazy parses are not so simple. Here
--   are two working examples that illustrate the ways to handle errors.
--   Here they are:
--   
--   Way no. 1
--   
--   <pre>
--   import Text.XML.Expat.Tree
--   import qualified Data.ByteString.Lazy as L
--   import Data.ByteString.Internal (c2w)
--   import Control.Exception.Extensible as E
--   
--   -- This is the recommended way to handle errors in lazy parses
--   main = do
--       let (tree, mError) = parseTree Nothing (L.pack $ map c2w $ "&lt;top&gt;&lt;banana&gt;&lt;/apple&gt;&lt;/top&gt;")
--       print (tree :: UNode String)
--       -- Note: We check the error _after_ we have finished our processing on the tree.
--       case mError of
--           Just err -&gt; putStrLn $ "It failed : "++show err
--           Nothing -&gt; putStrLn "Success!"
--   </pre>
--   
--   Way no. 2
--   
--   <pre>
--   ...
--   import Control.Exception.Extensible as E
--   
--   -- This is not the recommended way to handle errors.
--   main = do
--       do
--           let tree = parseTreeThrowing Nothing (L.pack $ map c2w $ "&lt;top&gt;&lt;banana&gt;&lt;/apple&gt;&lt;/top&gt;")
--           print (tree :: UNode String)
--           -- Because of lazy evaluation, you should not process the tree outside the 'do' block,
--           -- or exceptions could be thrown that won't get caught.
--       `E.catch` (\exc -&gt;
--           case E.fromException exc of
--               Just (XMLParseException err) -&gt; putStrLn $ "It failed : "++show err
--               Nothing -&gt; E.throwIO exc)
--   </pre>
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

-- | Type shortcut for nodes
type Nodes tag text = [Node tag text]

-- | Type shortcut for attributes
type Attributes tag text = [(tag, text)]

-- | Type shortcut for a single node with unqualified tag names where tag
--   and text are the same string type.
type UNode text = Node text text

-- | Type shortcut for nodes with unqualified tag names where tag and text
--   are the same string type.
type UNodes text = Nodes text text

-- | Type shortcut for attributes with unqualified tag names where tag and
--   text are the same string type.
type UAttributes text = Attributes text 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 :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> (Node tag text, Maybe XMLParseError)

-- | Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parseTree' :: (GenericXMLString tag, GenericXMLString 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 :: (GenericXMLString tag, GenericXMLString 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

-- | A lower level function that lazily converts a SAX stream into a tree
--   structure.
saxToTree :: (GenericXMLString tag) => [SAXEvent tag text] -> (Node tag text, Maybe XMLParseError)

-- | An exception indicating an XML parse error, used by the
--   <i>..Throwing</i> variants.
data XMLParseException
XMLParseException :: XMLParseError -> XMLParseException

-- | Lazily parse XML to SAX events. In the event of an error, throw
--   <a>XMLParseException</a>.
parseSAXThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]

-- | Lazily parse XML to tree. In the event of an error, throw
--   <a>XMLParseException</a>.
parseTreeThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> Node tag text

-- | An abstraction for any string type you want to use as xml text (that
--   is, attribute values or element text content). If you want to use a
--   new string type with <i>hexpat</i>, you must make it an instance of
--   <a>GenericXMLString</a>.
class (Monoid s, Eq s) => GenericXMLString s
gxNullString :: (GenericXMLString s) => s -> Bool
gxToString :: (GenericXMLString s) => s -> String
gxFromString :: (GenericXMLString s) => String -> s
gxFromChar :: (GenericXMLString s) => Char -> s
gxHead :: (GenericXMLString s) => s -> Char
gxTail :: (GenericXMLString s) => s -> s
gxBreakOn :: (GenericXMLString s) => Char -> s -> (s, s)
gxFromCStringLen :: (GenericXMLString s) => CStringLen -> IO s
gxToByteString :: (GenericXMLString s) => s -> ByteString
instance Typeable XMLParseException
instance Eq XMLParseException
instance Show XMLParseException
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 Exception XMLParseException
instance (NFData tag, NFData text) => NFData (SAXEvent tag text)
instance (NFData tag, NFData text) => NFData (Node tag text)
instance GenericXMLString Text
instance GenericXMLString ByteString
instance GenericXMLString String


-- | 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 - lazy variant that returns
--   lazy ByteString.
formatTree :: (GenericXMLString tag, GenericXMLString text) => Node tag text -> ByteString

-- | Format document with &lt;?xml.. header - strict variant that returns
--   strict ByteString.
formatTree' :: (GenericXMLString tag, GenericXMLString text) => Node tag text -> ByteString

-- | Format XML node with no header - lazy variant that returns lazy
--   ByteString.
formatNode :: (GenericXMLString tag, GenericXMLString text) => Node tag text -> ByteString

-- | Format XML node with no header - strict variant that returns strict
--   ByteString.
formatNode' :: (GenericXMLString tag, GenericXMLString text) => Node tag text -> ByteString

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

-- | <a>Put</a> interface for formatting a node with no header.
putNode :: (GenericXMLString tag, GenericXMLString text) => Node tag text -> Put


-- | In the default representation, 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 functionality to handle these more intelligently,
--   splitting all tag and attribute names into their Prefix and LocalPart
--   components.
module Text.XML.Expat.Qualified

-- | A qualified name.
--   
--   Qualified names have two parts, a prefix and a local part. The local
--   part is the name of the tag. The prefix scopes that name to a
--   particular group of legal tags.
--   
--   The prefix will usually be associated with a namespace URI. This is
--   usually achieved by using xmlns attributes to bind prefixes to URIs.
data QName text
QName :: Maybe text -> !text -> QName text
qnPrefix :: QName text -> Maybe text
qnLocalPart :: QName text -> !text

-- | Type shortcut for a single node where qualified names are used for
--   tags
type QNode text = Node (QName text) text

-- | Type shortcut for nodes where qualified names are used for tags
type QNodes text = Nodes (QName text) text

-- | Type shortcut for attributes where qualified names are used for tags
type QAttributes text = Attributes (QName text) text

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

-- | Make a new QName with no prefix.
mkAnQName :: text -> QName text
toQualified :: (GenericXMLString text) => UNode text -> QNode text
fromQualified :: (GenericXMLString text) => QNode text -> UNode text
instance (Eq text) => Eq (QName text)
instance (Show text) => Show (QName text)
instance (NFData text) => NFData (QName text)

module Text.XML.Expat.Namespaced

-- | A namespace-qualified tag.
--   
--   NName has two components, a local part and an optional namespace. The
--   local part is the name of the tag. The namespace is the URI
--   identifying collections of declared tags. Tags with the same local
--   part but from different namespaces are distinct. Unqualified tags are
--   those with no namespace. They are in the default namespace, and all
--   uses of an unqualified tag are equivalent.
data NName text
NName :: Maybe text -> !text -> NName text
nnNamespace :: NName text -> Maybe text
nnLocalPart :: NName text -> !text

-- | Type shortcut for a single node where namespaced names are used for
--   tags
type NNode text = Node (NName text) text

-- | Type shortcut for nodes where namespaced names are used for tags
type NNodes text = Nodes (NName text) text

-- | Type shortcut for attributes where namespaced names are used for tags
type NAttributes text = Attributes (NName text) text

-- | Make a new NName from a prefix and localPart.
mkNName :: text -> text -> NName text

-- | Make a new NName with no prefix.
mkAnNName :: text -> NName text
toNamespaced :: (GenericXMLString text, Ord text, Show text) => QNode text -> NNode text
fromNamespaced :: (GenericXMLString text, Ord text) => NNode text -> QNode text
xmlnsUri :: (GenericXMLString text) => text
xmlns :: (GenericXMLString text) => text
instance (Eq text) => Eq (NName text)
instance (Show text) => Show (NName text)
instance (NFData text) => NFData (NName text)