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


-- | XML parser/formatter based on expat
--   
--   This package provides a general purpose Haskell XML library using
--   Expat to do its parsing (<a>http://expat.sourceforge.net/</a> - a fast
--   stream-oriented XML parser written in C). It is extensible to any
--   string type, with <tt>String</tt>, <tt>ByteString</tt> and
--   <tt>Text</tt> provided out of the box.
--   
--   Basic usage: Parsing a tree (<i>Tree</i>), formatting a tree
--   (<i>Format</i>). Other features: Helpers for processing XML trees
--   (<i>Proc</i>), trees annotated with XML source location
--   (<i>Annotated</i>), XML cursors (<i>Cursor</i>), SAX-style parse
--   (<i>SAX</i>), and access to the low-level interface in case speed is
--   paramount (<i>Internal.IO</i>).
--   
--   The design goals are speed, speed, speed, interface simplicity and
--   modularity.
--   
--   For introduction and examples, see the <i>Text.XML.Expat.Tree</i>
--   module. For benchmarks, <a>http://haskell.org/haskellwiki/Hexpat/</a>
--   
--   If you want to do interactive I/O, an obvious option is to use lazy
--   parsing with one of the lazy I/O functions such as hGetContents.
--   However, this can be problematic in some applications because it
--   doesn't handle I/O errors properly and can give no guarantee of timely
--   resource cleanup. In these cases, chunked I/O is a better approach:
--   Take a look at the <i>hexpat-iteratee</i> package.
--   
--   <i>IO</i> is filed under <i>Internal</i> because it's low-level and
--   most users won't want it. The other <i>Internal</i> modules are
--   re-exported by <i>Annotated</i> and <i>Tree</i>, so you won't need to
--   import them directly.
--   
--   Credits to Iavor Diatchki and the <tt>xml</tt> (XML.Light) package for
--   <i>Proc</i> and <i>Cursor</i>.
--   
--   INSTALLATION: Unix install requires an OS package called something
--   like <tt>libexpat-dev</tt>. On MacOSX, expat comes with Apple's
--   optional X11 package, or you can install it from source. To install on
--   Windows, first install the Windows binary that's available from
--   <a>http://expat.sourceforge.net/</a>, then type (assuming you're using
--   v2.0.1):
--   
--   <pre>
--   cabal install hexpat --extra-lib-dirs=<a>C:\Program Files\Expat 2.0.1\Bin</a> --extra-include-dirs=<a>C:\Program Files\Expat 2.0.1\Source\Lib</a>
--   </pre>
--   
--   Ensure <tt>libexpat.dll</tt> can be found in your system PATH (or copy
--   it into your executable's directory).
--   
--   ChangeLog: 0.15 changes intended to fix a (rare) "error: a C finalizer
--   called back into Haskell." that seemed only to happen only on
--   ghc6.12.X; 0.15.1 Fix broken Annotated parse; 0.16 switch from mtl to
--   transformers
@package hexpat
@version 0.16


-- | Low-level interface to Expat. Unless speed is paramount, this should
--   normally be avoided in favour of the interfaces provided by
--   Text.XML.Expat.SAX and Text.XML.Expat.Tree. 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>, <a>parse'</a> or
--   <a>parseChunk</a>. Some of these functions must be wrapped in
--   <a>withParser</a>.</li>
--   </ol>
module Text.XML.Expat.Internal.IO
data Parser

-- | Create a <a>Parser</a>.
newParser :: Maybe Encoding -> IO Parser

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

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

-- | Most of the low-level functions take a ParserPtr so are required to be
--   called inside <tt>withParser</tt>.
withParser :: Parser -> (ParserPtr -> IO a) -> IO a
type ParserPtr = Ptr Parser_struct

-- | Opaque parser type.
data Parser_struct

-- | <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 :: ParserPtr -> 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 and error location
data XMLParseError
XMLParseError :: String -> XMLParseLocation -> XMLParseError
getParseLocation :: ParserPtr -> IO XMLParseLocation

-- | Specifies a location of an event within the input text
data XMLParseLocation
XMLParseLocation :: Int64 -> Int64 -> Int64 -> Int64 -> XMLParseLocation

-- | Line number of the event
xmlLineNumber :: XMLParseLocation -> Int64

-- | Column number of the event
xmlColumnNumber :: XMLParseLocation -> Int64

-- | Byte index of event from start of document
xmlByteIndex :: XMLParseLocation -> Int64

-- | The number of bytes in the event
xmlByteCount :: XMLParseLocation -> Int64

-- | 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 = ParserPtr -> 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 = ParserPtr -> 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 = ParserPtr -> CStringLen -> IO Bool

-- | The type of the "external entity reference" callback. See the expat
--   documentation.
type ExternalEntityRefHandler = Parser -> CString -> CString -> CString -> CString -> IO Bool

-- | Set a skipped entity handler. This is called in two situations:
--   
--   1. An entity reference is encountered for which no declaration has
--   been read and this is not an error.
--   
--   2. An internal entity reference is read, but not expanded, because
--   <tt>XML_SetDefaultHandler</tt> has been called.
type SkippedEntityHandler = ParserPtr -> CString -> Int -> 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 ()
setExternalEntityRefHandler :: Parser -> ExternalEntityRefHandler -> IO ()
setSkippedEntityHandler :: Parser -> SkippedEntityHandler -> IO ()
setUseForeignDTD :: Parser -> Bool -> IO ()
parseExternalEntityReference :: Parser -> CString -> Maybe Encoding -> CStringLen -> IO Bool
data ExpatHandlers
encodingToString :: Encoding -> String
instance Eq XMLParseLocation
instance Show XMLParseLocation
instance Eq XMLParseError
instance Show XMLParseError
instance NFData XMLParseLocation
instance NFData XMLParseError
instance Show Parser


-- | This module provides functions to parse an XML document to a lazy
--   stream of SAX events.
module Text.XML.Expat.SAX

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

-- | Parse error, consisting of message text and error location
data XMLParseError
XMLParseError :: String -> XMLParseLocation -> XMLParseError

-- | Specifies a location of an event within the input text
data XMLParseLocation
XMLParseLocation :: Int64 -> Int64 -> Int64 -> Int64 -> XMLParseLocation

-- | Line number of the event
xmlLineNumber :: XMLParseLocation -> Int64

-- | Column number of the event
xmlColumnNumber :: XMLParseLocation -> Int64

-- | Byte index of event from start of document
xmlByteIndex :: XMLParseLocation -> Int64

-- | The number of bytes in the event
xmlByteCount :: XMLParseLocation -> Int64
data ParserOptions tag text
ParserOptions :: Maybe Encoding -> Maybe (tag -> Maybe text) -> ParserOptions tag text

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
parserEncoding :: ParserOptions tag text -> Maybe Encoding

-- | If provided, entity references (i.e. <tt>&amp;nbsp;</tt> and friends)
--   will be decoded into text using the supplied lookup function
entityDecoder :: ParserOptions tag text -> Maybe (tag -> Maybe 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

-- | Converts a <a>CString</a> to a <a>GenericXMLString</a> type.
textFromCString :: (GenericXMLString text) => CString -> IO text

-- | Lazily parse XML to SAX events. In the event of an error, FailDocument
--   is the last element of the output list.
parse :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> [SAXEvent tag text]

-- | A variant of parseSAX that gives a document location with each SAX
--   event.
parseLocations :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | A variant of parseSAX that gives a document location with each SAX
--   event. In the event of an error, throw <a>XMLParseException</a>.
--   
--   <tt>parseLocationsThrowing</tt> can throw an exception from pure code,
--   which is generally a bad way to handle errors, because Haskell's lazy
--   evaluation means it's hard to predict where it will be thrown from.
--   However, it may be acceptable in situations where it's not expected
--   during normal operation, depending on the design of your program.
parseLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | Lazily parse XML to SAX events. In the event of an error, throw
--   <a>XMLParseException</a>.
--   
--   <tt>parseThrowing</tt> can throw an exception from pure code, which is
--   generally a bad way to handle errors, because Haskell's lazy
--   evaluation means it's hard to predict where it will be thrown from.
--   However, it may be acceptable in situations where it's not expected
--   during normal operation, depending on the design of your program.
parseThrowing :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> [SAXEvent tag text]
defaultParserOptions :: ParserOptions tag text

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

-- | DEPRECATED: Use <a>parse</a> instead.
--   
--   Lazily parse XML to SAX events. In the event of an error, FailDocument
--   is the last element of the output list. Deprecated in favour of new
--   <a>parse</a>
parseSAX :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]

-- | DEPRECATED: Use <a>parseLocations</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event.
parseSAXLocations :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | DEPRECATED: Used <a>parseLocationsThrowing</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event. In the event of an error, throw <a>XMLParseException</a>.
parseSAXLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | DEPRECATED: Use <a>parseThrowing</a> instead.
--   
--   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]

-- | A helper for configuring the hexpat parser to use the specified entity
--   decoder.
setEntityDecoder :: (GenericXMLString tag, GenericXMLString text) => Parser -> (tag -> Maybe text) -> (ParserPtr -> text -> IO ()) -> IO ()

-- | 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 Exception XMLParseException
instance (NFData tag, NFData text) => NFData (SAXEvent tag text)
instance GenericXMLString Text
instance GenericXMLString ByteString
instance GenericXMLString String


-- | Type classes to allow for XML handling functions to be generalized to
--   work with different node types, including the ones defined in
--   <i>Tree</i> and <i>Annotated</i>.
module Text.XML.Expat.Internal.NodeClass

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

-- | Type shortcut for attributes with unqualified names where tag and text
--   are the same string type.
type UAttributes text = Attributes text text

-- | Extract all text content from inside a tag into a single string,
--   including any text contained in children.
textContent :: (NodeClass n [], Monoid text) => n [] tag text -> text

-- | A type function to give the type of a list of nodes, using the
--   appropriate list type for the specified node type, e.g. <tt>ListOf
--   (UNode Text)</tt>
class (Functor c, List c) => NodeClass n c
isElement :: (NodeClass n c) => n c tag text -> Bool
isText :: (NodeClass n c) => n c tag text -> Bool
textContentM :: (NodeClass n c, Monoid text) => n c tag text -> ItemM c text
isNamed :: (NodeClass n c, Eq tag) => tag -> n c tag text -> Bool
getName :: (NodeClass n c, Monoid tag) => n c tag text -> tag
getAttributes :: (NodeClass n c) => n c tag text -> [(tag, text)]
getChildren :: (NodeClass n c) => n c tag text -> c (n c tag text)
getText :: (NodeClass n c, Monoid text) => n c tag text -> text
modifyName :: (NodeClass n c) => (tag -> tag) -> n c tag text -> n c tag text
modifyAttributes :: (NodeClass n c) => ([(tag, text)] -> [(tag, text)]) -> n c tag text -> n c tag text
modifyChildren :: (NodeClass n c) => (c (n c tag text) -> c (n c tag text)) -> n c tag text -> n c tag text
mapAllTags :: (NodeClass n c) => (tag -> tag') -> n c tag text -> n c tag' text
mapElement :: (NodeClass n c) => ((tag, [(tag, text)], c (n c tag text)) -> (tag', [(tag', text)], c (n c tag' text))) -> n c tag text -> n c tag' text
mapNodeContainer :: (NodeClass n c) => (c (n c tag text) -> ItemM c (c' (n c' tag text))) -> n c tag text -> ItemM c (n c' tag text)
mkText :: (NodeClass n c) => text -> n c tag text

-- | A class of node types where an Element can be constructed given a tag,
--   attributes and children.
class (NodeClass n c) => MkElementClass n c
mkElement :: (MkElementClass n c) => tag -> Attributes tag text -> c (n c tag text) -> n c tag text

-- | Get the value of the attribute having the specified name.
getAttribute :: (NodeClass n c, GenericXMLString tag) => n c tag text -> tag -> Maybe text

-- | Set the value of the attribute with the specified name to the value,
--   overwriting the first existing attribute with that name if present.
setAttribute :: (Eq tag, NodeClass n c, GenericXMLString tag) => tag -> text -> n c tag text -> n c tag text

-- | Delete the first attribute matching the specified name.
deleteAttribute :: (Eq tag, NodeClass n c, GenericXMLString tag) => tag -> n c tag text -> n c tag text

-- | setAttribute if <i>Just</i>, deleteAttribute if <i>Nothing</i>.
alterAttribute :: (Eq tag, NodeClass n c, GenericXMLString tag) => tag -> Maybe text -> n c tag text -> n c tag text

-- | Generically convert an element of one node type to another. Useful for
--   adding or removing annotations.
fromElement :: (NodeClass n c, MkElementClass n' c, Monoid tag, Monoid text) => n c tag text -> n' c tag text

-- | Generically convert an element of one node type to another, using the
--   specified element constructor. Useful for adding or removing
--   annotations.
fromElement_ :: (NodeClass n c, NodeClass n' c, Monoid tag, Monoid text) => (tag -> Attributes tag text -> c (n' c tag text) -> n' c tag text) -> n c tag text -> n' c tag text

-- | Generically convert a list of nodes from one node type to another.
--   Useful for adding or removing annotations.
fromNodes :: (NodeClass n c, MkElementClass n' c, Monoid tag, Monoid text) => c (n c tag text) -> c (n' c tag text)

-- | Generically convert a list of nodes from one node type to another,
--   using the specified element constructor. Useful for adding or removing
--   annotations.
fromNodes_ :: (NodeClass n c, NodeClass n' c, Monoid tag, Monoid text) => (tag -> Attributes tag text -> c (n' c tag text) -> n' c tag text) -> c (n c tag text) -> c (n' c tag text)


-- | 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.Internal.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 attributes with qualified names
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 :: (NodeClass n c, GenericXMLString text) => n c text text -> n c (QName text) text
fromQualified :: (NodeClass n c, GenericXMLString text) => n c (QName text) text -> n c text text
instance (Eq text) => Eq (QName text)
instance (Show text) => Show (QName text)
instance (NFData text) => NFData (QName text)

module Text.XML.Expat.Internal.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 attributes with namespaced names
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 :: (NodeClass n c, GenericXMLString text, Ord text, Show text) => n c (QName text) text -> n c (NName text) text
fromNamespaced :: (NodeClass n c, GenericXMLString text, Ord text, Functor c) => n c (NName text) text -> n c (QName text) 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)


-- | This module provides functions to parse an XML document to a tree
--   structure, either strictly or lazily.
--   
--   The <a>GenericXMLString</a> type class allows you to use any string
--   type. Three string types are provided for here: <a>String</a>,
--   <a>ByteString</a> and <a>Text</a>.
--   
--   Here is a complete example to get you started:
--   
--   <pre>
--   -- | A "hello world" example of hexpat that lazily parses a document, printing
--   -- it to standard out.
--   
--   import Text.XML.Expat.Tree
--   import Text.XML.Expat.Format
--   import System.Environment
--   import System.Exit
--   import System.IO
--   import qualified Data.ByteString.Lazy as L
--   
--   main = do
--       args &lt;- getArgs
--       case args of
--           [filename] -&gt; process filename
--           otherwise  -&gt; do
--               hPutStrLn stderr "Usage: helloworld &lt;file.xml&gt;"
--               exitWith $ ExitFailure 1
--   
--   process :: String -&gt; IO ()
--   process filename = do
--       inputText &lt;- L.readFile filename
--       -- Note: Because we're not using the tree, Haskell can't infer the type of
--       -- strings we're using so we need to tell it explicitly with a type signature.
--       let (xml, mErr) = parse defaultParserOptions inputText :: (UNode String, Maybe XMLParseError)
--       -- Process document before handling error, so we get lazy processing.
--       L.hPutStr stdout $ format xml
--       putStrLn ""
--       case mErr of
--           Nothing -&gt; return ()
--           Just err -&gt; do
--               hPutStrLn stderr $ "XML parse failed: "++show err
--               exitWith $ ExitFailure 2
--   </pre>
--   
--   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 - Using a Maybe value
--   
--   <pre>
--   import Text.XML.Expat.Tree
--   import qualified Data.ByteString.Lazy as L
--   import Data.ByteString.Internal (c2w)
--   
--   -- This is the recommended way to handle errors in lazy parses
--   main = do
--       let (tree, mError) = parse defaultParserOptions
--                      (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 - Using exceptions
--   
--   <a>parseThrowing</a> can throw an exception from pure code, which is
--   generally a bad way to handle errors, because Haskell's lazy
--   evaluation means it's hard to predict where it will be thrown from.
--   However, it may be acceptable in situations where it's not expected
--   during normal operation, depending on the design of your program.
--   
--   <pre>
--   ...
--   import Control.Exception.Extensible as E
--   
--   -- This is not the recommended way to handle errors.
--   main = do
--       do
--           let tree = parseThrowing defaultParserOptions
--                          (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

-- | A pure tree representation that uses a list as its container type.
--   
--   In the <tt>hexpat</tt> package, a list of nodes has the type <tt>[Node
--   tag text]</tt>, but note that you can also use the more general type
--   function <a>ListOf</a> to give a list of any node type, using that
--   node's associated list type, e.g. <tt>ListOf (UNode Text)</tt>.
type Node tag text = NodeG [] tag text

-- | The tree representation of the XML document.
--   
--   <tt>c</tt> is the container type for the element's children, which is
--   [] in the <tt>hexpat</tt> package, and a monadic list type for
--   <tt>hexpat-iteratee</tt>.
--   
--   <tt>tag</tt> is the tag type, which can either be one of several
--   string types, or a special type from the
--   <tt>Text.XML.Expat.Namespaced</tt> or
--   <tt>Text.XML.Expat.Qualified</tt> modules.
--   
--   <tt>text</tt> is the string type for text content.
data NodeG c tag text
Element :: !tag -> ![(tag, text)] -> c (NodeG c tag text) -> NodeG c tag text
eName :: NodeG c tag text -> !tag
eAttributes :: NodeG c tag text -> ![(tag, text)]
eChildren :: NodeG c tag text -> c (NodeG c tag text)
Text :: !text -> NodeG c tag text

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

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

-- | Type alias for a single node where namespaced names are used for tags
type NNode text = Node (NName text) text
data ParserOptions tag text
ParserOptions :: Maybe Encoding -> Maybe (tag -> Maybe text) -> ParserOptions tag text

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
parserEncoding :: ParserOptions tag text -> Maybe Encoding

-- | If provided, entity references (i.e. <tt>&amp;nbsp;</tt> and friends)
--   will be decoded into text using the supplied lookup function
entityDecoder :: ParserOptions tag text -> Maybe (tag -> Maybe text)
defaultParserOptions :: ParserOptions tag text

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

-- | 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.
parse :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> (Node tag text, Maybe XMLParseError)

-- | Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parse' :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> Either XMLParseError (Node tag text)

-- | Parse error, consisting of message text and error location
data XMLParseError
XMLParseError :: String -> XMLParseLocation -> XMLParseError

-- | Specifies a location of an event within the input text
data XMLParseLocation
XMLParseLocation :: Int64 -> Int64 -> Int64 -> Int64 -> XMLParseLocation

-- | Line number of the event
xmlLineNumber :: XMLParseLocation -> Int64

-- | Column number of the event
xmlColumnNumber :: XMLParseLocation -> Int64

-- | Byte index of event from start of document
xmlByteIndex :: XMLParseLocation -> Int64

-- | The number of bytes in the event
xmlByteCount :: XMLParseLocation -> Int64

-- | Lazily parse XML to tree. In the event of an error, throw
--   <a>XMLParseException</a>.
--   
--   <tt>parseThrowing</tt> can throw an exception from pure code, which is
--   generally a bad way to handle errors, because Haskell's lazy
--   evaluation means it's hard to predict where it will be thrown from.
--   However, it may be acceptable in situations where it's not expected
--   during normal operation, depending on the design of your program.
parseThrowing :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> Node tag text

-- | An exception indicating an XML parse error, used by the
--   <i>..Throwing</i> variants.
data XMLParseException
XMLParseException :: XMLParseError -> XMLParseException
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 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
eAttrs :: Node tag text -> [(tag, text)]

-- | DEPRECATED: Use [Node tag text] instead.
--   
--   Type alias for nodes.
type Nodes tag text = [Node tag text]

-- | DEPRECATED: Use [UNode text] instead.
--   
--   Type alias for nodes with unqualified tag names where tag and text are
--   the same string type. DEPRECATED.
type UNodes text = Nodes text text

-- | DEPRECATED: Use [QNode text] instead.
--   
--   Type alias for nodes where qualified names are used for tags
type QNodes text = [Node (QName text) text]

-- | DEPRECATED: Use [NNode text] instead.
--   
--   Type alias for nodes where namespaced names are used for tags.
type NNodes text = [Node (NName text) text]

-- | DEPREACTED: Use <a>parse</a> instead.
--   
--   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)

-- | DEPRECATED: use <a>parse</a> instead.
--   
--   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)

-- | DEPRECATED: Use <a>parse</a> instead.
--   
--   Lazily parse XML to SAX events. In the event of an error, FailDocument
--   is the last element of the output list. Deprecated in favour of new
--   <a>parse</a>
parseSAX :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]

-- | DEPRECATED: Use <a>parseLocations</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event.
parseSAXLocations :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | DEPRECATED: Use <a>parseThrowing</a> instead.
--   
--   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

-- | DEPRECATED: Use <a>parseThrowing</a> instead.
--   
--   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]

-- | DEPRECATED: Used <a>parseLocationsThrowing</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event. In the event of an error, throw <a>XMLParseException</a>.
parseSAXLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]
instance (Functor c, List c) => MkElementClass NodeG c
instance (Functor c, List c) => NodeClass NodeG c
instance (NFData tag, NFData text) => NFData (NodeG [] tag text)
instance (Eq tag, Eq text) => Eq (NodeG [] tag text)
instance (Show tag, Show text) => Show (NodeG [] tag text)


-- | This module ported from Text.XML.Light.Cursor
--   
--   XML cursors for working XML content withing the context of an XML
--   document. This implementation is based on the general tree zipper
--   written by Krasimir Angelov and Iavor S. Diatchki.
--   
--   With the exception of <a>modifyContentM</a>, then M-suffixed functions
--   are for use with monadic node types, as used when dealing with chunked
--   I/O with the <i>hexpat-iteratee</i> package. In the more common pure
--   case, you wouldn't need these *M functions.
module Text.XML.Expat.Cursor

-- | A cursor specific to <tt>Text.XML.Expat.Tree.Node</tt> trees.
type Cursor tag text = CursorG NodeG [] tag text

-- | Generalized cursor: The position of a piece of content in an XML
--   document. <tt>n</tt> is the Node type and <tt>c</tt> is the list type,
--   which would usually be [], except when you're using chunked I/O.
data CursorG n c tag text
Cur :: n c tag text -> c (n c tag text) -> c (n c tag text) -> PathG n c tag text -> CursorG n c tag text

-- | The currently selected content.
current :: CursorG n c tag text -> n c tag text

-- | Siblings on the left, closest first.
lefts :: CursorG n c tag text -> c (n c tag text)

-- | Siblings on the right, closest first.
rights :: CursorG n c tag text -> c (n c tag text)

-- | The contexts of the parent elements of this location.
parents :: CursorG n c tag text -> PathG n c tag text

-- | A path specific to <tt>Text.XML.Expat.Tree.Node</tt> trees.
type Path tag text = PathG NodeG [] tag text

-- | Generalized path within an XML document.
type PathG n c tag text = [(c (n c tag text), Tag tag text, c (n c tag text))]
data Tag tag text
Tag :: tag -> Attributes tag text -> Tag tag text
tagName :: Tag tag text -> tag
tagAttribs :: Tag tag text -> Attributes tag text
getTag :: Node tag text -> Tag tag text
fromTag :: (MkElementClass n c) => Tag tag text -> c (n c tag text) -> n c tag text

-- | A cursor for the given content.
fromTree :: (List c) => n c tag text -> CursorG n c tag text

-- | The location of the first tree in a forest - pure version.
fromForest :: (NodeClass n []) => [n [] tag text] -> Maybe (CursorG n [] tag text)

-- | Computes the forest containing this location.
toForest :: (MkElementClass n c) => CursorG n c tag text -> c (n c tag text)

-- | Computes the tree containing this location.
toTree :: (MkElementClass n c) => CursorG n c tag text -> n c tag text

-- | The parent of the given location.
parent :: (MkElementClass n c) => CursorG n c tag text -> Maybe (CursorG n c tag text)

-- | The top-most parent of the given location.
root :: (MkElementClass n c) => CursorG n c tag text -> CursorG n c tag text

-- | The child with the given index (starting from 0). - pure version.
getChild :: (NodeClass n [], Monoid tag) => Int -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The child with the given index (starting from 0) - used for monadic
--   node types.
getChildM :: (NodeClass n c, Monoid tag) => Int -> CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The first child of the given location - pure version.
firstChild :: (NodeClass n [], Monoid tag) => CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The first child of the given location - used for monadic node types.
firstChildM :: (NodeClass n c, Monoid tag) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The last child of the given location - pure version.
lastChild :: (NodeClass n [], Monoid tag) => CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The last child of the given location - used for monadic node types.
lastChildM :: (NodeClass n c, Monoid tag) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The left sibling of the given location - pure version.
left :: CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The left sibling of the given location - used for monadic node types.
leftM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The right sibling of the given location - pure version.
right :: CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The right sibling of the given location - used for monadic node types.
rightM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The next position in a left-to-right depth-first traversal of a
--   document: either the first child, right sibling, or the right sibling
--   of a parent that has one. Pure version.
nextDF :: (MkElementClass n [], Monoid tag) => CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | The next position in a left-to-right depth-first traversal of a
--   document: either the first child, right sibling, or the right sibling
--   of a parent that has one. Used for monadic node types.
nextDFM :: (MkElementClass n c, Monoid tag) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | The first child that satisfies a predicate - pure version.
findChild :: (NodeClass n [], Monoid tag) => (CursorG n [] tag text -> Bool) -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Find the next left sibling that satisfies a predicate.
findLeft :: (NodeClass n []) => (CursorG n [] tag text -> Bool) -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Find the next right sibling that satisfies a predicate - pure version.
findRight :: (CursorG n [] tag text -> Bool) -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Perform a depth first search for a descendant that satisfies the given
--   predicate. Pure version.
findRec :: (MkElementClass n [], Monoid tag) => (CursorG n [] tag text -> Bool) -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Perform a depth first search for a descendant that satisfies the given
--   predicate. Used for monadic node types.
findRecM :: (MkElementClass n c, Monoid tag) => (CursorG n c tag text -> ItemM c Bool) -> CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | Are we at the top of the document?
isRoot :: CursorG n c tag text -> Bool

-- | Are we at the left end of the the document? (Pure version.)
isFirst :: CursorG n [] tag text -> Bool

-- | Are we at the left end of the the document? (Used for monadic node
--   types.)
isFirstM :: (List c) => CursorG n c tag text -> ItemM c Bool

-- | Are we at the right end of the document? (Pure version.)
isLast :: CursorG n [] tag text -> Bool

-- | Are we at the right end of the document? (Used for monadic node
--   types.)
isLastM :: (List c) => CursorG n c tag text -> ItemM c Bool

-- | Are we at the bottom of the document?
isLeaf :: (NodeClass n c, Monoid tag) => CursorG n c tag text -> Bool

-- | Do we have a parent?
isChild :: CursorG n c tag text -> Bool

-- | Do we have children?
hasChildren :: (NodeClass n c, Monoid tag) => CursorG n c tag text -> Bool

-- | Get the node index inside the sequence of children - pure version.
getNodeIndex :: CursorG n [] tag text -> Int

-- | Change the current content.
setContent :: n c tag text -> CursorG n c tag text -> CursorG n c tag text

-- | Modify the current content.
modifyContent :: (n c tag text -> n c tag text) -> CursorG n c tag text -> CursorG n c tag text

-- | Modify the current content - pure version.
modifyContentList :: (NodeClass n []) => (n [] tag text -> [n [] tag text]) -> CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Modify the current content - used for monadic node types.
modifyContentListM :: (NodeClass n c) => (n c tag text -> c (n c tag text)) -> CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | Modify the current content, allowing for an effect.
modifyContentM :: (Monad m) => (n [] tag text -> m (n [] tag text)) -> CursorG n [] tag text -> m (CursorG n [] tag text)

-- | Insert content to the left of the current position.
insertLeft :: (List c) => n c tag text -> CursorG n c tag text -> CursorG n c tag text

-- | Insert content to the right of the current position.
insertRight :: (List c) => n c tag text -> CursorG n c tag text -> CursorG n c tag text

-- | Insert content to the left of the current position.
insertManyLeft :: (List c) => c (n c tag text) -> CursorG n c tag text -> CursorG n c tag text

-- | Insert content to the right of the current position.
insertManyRight :: (List c) => c (n c tag text) -> CursorG n c tag text -> CursorG n c tag text

-- | Insert content as the first child of the current position.
insertFirstChild :: (NodeClass n c) => n c tag text -> CursorG n c tag text -> Maybe (CursorG n c tag text)

-- | Insert content as the first child of the current position.
insertLastChild :: (NodeClass n c) => n c tag text -> CursorG n c tag text -> Maybe (CursorG n c tag text)

-- | Insert content as the first child of the current position.
insertManyFirstChild :: (NodeClass n c) => c (n c tag text) -> CursorG n c tag text -> Maybe (CursorG n c tag text)

-- | Insert content as the first child of the current position.
insertManyLastChild :: (NodeClass n c) => c (n c tag text) -> CursorG n c tag text -> Maybe (CursorG n c tag text)

-- | Insert content to the left of the current position. The new content
--   becomes the current position.
insertGoLeft :: (List c) => n c tag text -> CursorG n c tag text -> CursorG n c tag text

-- | Insert content to the right of the current position. The new content
--   becomes the current position.
insertGoRight :: (List c) => n c tag text -> CursorG n c tag text -> CursorG n c tag text

-- | Remove the content on the left of the current position, if any - pure
--   version.
removeLeft :: CursorG n [] tag text -> Maybe (n [] tag text, CursorG n [] tag text)

-- | Remove the content on the left of the current position, if any - used
--   for monadic node types.
removeLeftM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (n c tag text, CursorG n c tag text))

-- | Remove the content on the right of the current position, if any - pure
--   version.
removeRight :: CursorG n [] tag text -> Maybe (n [] tag text, CursorG n [] tag text)

-- | Remove the content on the left of the current position, if any - used
--   for monadic node types.
removeRightM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (n c tag text, CursorG n c tag text))

-- | Remove the current element. The new position is the one on the left.
--   Pure version.
removeGoLeft :: CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Remove the current element. The new position is the one on the left.
--   Pure version.
removeGoLeftM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | Remove the current element. The new position is the one on the right.
--   Pure version.
removeGoRight :: CursorG n [] tag text -> Maybe (CursorG n [] tag text)

-- | Remove the current element. The new position is the one on the right.
--   Used for monadic node types.
removeGoRightM :: (List c) => CursorG n c tag text -> ItemM c (Maybe (CursorG n c tag text))

-- | Remove the current element. The new position is the parent of the old
--   position.
removeGoUp :: (MkElementClass n c) => CursorG n c tag text -> Maybe (CursorG n c tag text)
instance (Show tag, Show text) => Show (Tag tag text)
instance (Show (n c tag text), Show (c (n c tag text)), Show tag, Show text) => Show (CursorG n c tag text)


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

-- | Format document with &lt;?xml.. header - lazy variant that returns
--   lazy ByteString.
format :: (NodeClass n [], GenericXMLString tag, GenericXMLString text) => n [] tag text -> ByteString

-- | Format document with &lt;?xml.. header - strict variant that returns
--   strict ByteString.
format' :: (NodeClass n [], GenericXMLString tag, GenericXMLString text) => n [] tag text -> ByteString

-- | Format document with &lt;?xml.. header - generalized variant that
--   returns a generic list of strict ByteStrings.
formatG :: (NodeClass n c, GenericXMLString tag, GenericXMLString text) => n c tag text -> c ByteString

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

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

-- | Format XML node with no header - generalized variant that returns a
--   generic list of strict ByteStrings.
formatNodeG :: (NodeClass n c, GenericXMLString tag, GenericXMLString text) => n c tag text -> c ByteString

-- | DEPRECATED: Renamed to <a>format</a>.
formatTree :: (NodeClass n [], GenericXMLString tag, GenericXMLString text) => n [] tag text -> ByteString

-- | DEPRECATED: Renamed to <a>format'</a>.
formatTree' :: (NodeClass n [], GenericXMLString tag, GenericXMLString text) => n [] tag text -> ByteString

-- | The standard XML header with UTF-8 encoding.
xmlHeader :: ByteString

-- | Flatten a tree structure into SAX events, monadic version.
treeToSAX :: (GenericXMLString tag, GenericXMLString text, Monoid text, NodeClass n c) => n c tag text -> c (SAXEvent tag text)

-- | Format SAX events with no header - lazy variant that returns lazy
--   ByteString.
formatSAX :: (GenericXMLString tag, GenericXMLString text) => [SAXEvent tag text] -> ByteString

-- | Format SAX events with no header - strict variant that returns strict
--   ByteString.
formatSAX' :: (GenericXMLString tag, GenericXMLString text) => [SAXEvent tag text] -> ByteString

-- | Format SAX events with no header - generalized variant that uses
--   generic list.
formatSAXG :: (List c, GenericXMLString tag, GenericXMLString text) => c (SAXEvent tag text) -> c ByteString

-- | Make the output prettier by adding indentation.
indent :: (NodeClass n c, GenericXMLString tag, GenericXMLString text) => Int -> n c tag text -> n c tag text

-- | Make the output prettier by adding indentation, specifying initial
--   indent.
indent_ :: (NodeClass n c, GenericXMLString tag, GenericXMLString text) => Int -> Int -> n c tag text -> n c tag text


-- | This module ported from Text.XML.Light.Proc
module Text.XML.Expat.Proc

-- | Select only the elements from a list of XML content.
onlyElems :: (NodeClass n c) => c (n c tag text) -> c (n c tag text)

-- | Select only the text from a list of XML content.
onlyText :: (NodeClass n c, Monoid text) => c (n c tag text) -> c text

-- | Find all immediate children with the given name.
findChildren :: (NodeClass n c, Eq tag, Monoid tag) => tag -> n c tag text -> c (n c tag text)

-- | Filter all immediate children wrt a given predicate.
filterChildren :: (NodeClass n c) => (n c tag text -> Bool) -> n c tag text -> c (n c tag text)

-- | Filter all immediate children wrt a given predicate over their names.
filterChildrenName :: (NodeClass n c, Monoid tag) => (tag -> Bool) -> n c tag text -> c (n c tag text)

-- | Find an immediate child with the given name.
findChild :: (NodeClass n [], GenericXMLString tag) => tag -> n [] tag text -> Maybe (n [] tag text)

-- | Find an immediate child with the given name.
filterChild :: (NodeClass n []) => (n [] tag text -> Bool) -> n [] tag text -> Maybe (n [] tag text)

-- | Find an immediate child with name matching a predicate.
filterChildName :: (NodeClass n [], Monoid tag) => (tag -> Bool) -> n [] tag text -> Maybe (n [] tag text)

-- | Find the left-most occurrence of an element matching given name.
findElement :: (NodeClass n [], Eq tag, Monoid tag) => tag -> n [] tag text -> Maybe (n [] tag text)

-- | Filter the left-most occurrence of an element wrt. given predicate.
filterElement :: (NodeClass n []) => (n [] tag text -> Bool) -> n [] tag text -> Maybe (n [] tag text)

-- | Filter the left-most occurrence of an element wrt. given predicate.
filterElementName :: (NodeClass n [], Monoid tag) => (tag -> Bool) -> n [] tag text -> Maybe (n [] tag text)

-- | Find all non-nested occurances of an element. (i.e., once we have
--   found an element, we do not search for more occurances among the
--   element's children).
findElements :: (NodeClass n c, Eq tag, Monoid tag) => tag -> n c tag text -> c (n c tag text)

-- | Find all non-nested occurrences of an element wrt. given predicate.
--   (i.e., once we have found an element, we do not search for more
--   occurances among the element's children).
filterElements :: (NodeClass n c) => (n c tag text -> Bool) -> n c tag text -> c (n c tag text)

-- | Find all non-nested occurences of an element wrt a predicate over
--   element names. (i.e., once we have found an element, we do not search
--   for more occurances among the element's children).
filterElementsName :: (NodeClass n c, Monoid tag) => (tag -> Bool) -> n c tag text -> c (n c tag text)


-- | A variant of <i>Node</i> in which Element nodes have an annotation of
--   any type, and some concrete functions that annotate with the XML parse
--   location.
--   
--   The names conflict with those in <i>Tree</i> so you must use qualified
--   import if you want to use both modules.
module Text.XML.Expat.Annotated

-- | A pure tree representation that uses a list as its container type,
--   annotated variant.
--   
--   In the <tt>hexpat</tt> package, a list of nodes has the type <tt>[Node
--   tag text]</tt>, but note that you can also use the more general type
--   function <a>ListOf</a> to give a list of any node type, using that
--   node's associated list type, e.g. <tt>ListOf (UNode Text)</tt>.
type Node a tag text = NodeG a [] tag text

-- | Annotated variant of the tree representation of the XML document,
--   meaning that it has an extra piece of information of your choice
--   attached to each Element.
--   
--   <tt>c</tt> is the container type for the element's children, which is
--   [] in the <tt>hexpat</tt> package, and a monadic list type for
--   <tt>hexpat-iteratee</tt>.
--   
--   <tt>tag</tt> is the tag type, which can either be one of several
--   string types, or a special type from the
--   <tt>Text.XML.Expat.Namespaced</tt> or
--   <tt>Text.XML.Expat.Qualified</tt> modules.
--   
--   <tt>text</tt> is the string type for text content.
--   
--   <tt>a</tt> is the type of the annotation. One of the things this can
--   be used for is to store the XML parse location, which is useful for
--   error handling.
--   
--   Note that some functions in the <tt>Text.XML.Expat.Cursor</tt> module
--   need to create new nodes through the <a>MkElementClass</a> type class.
--   Normally this can only be done if <tt>a</tt> is a Maybe type (so it
--   can provide the Nothing value for the annotation on newly created
--   nodes). Or, you can write your own <a>MkElementClass</a> instance.
--   Apart from that, there is no requirement for <tt>a</tt> to be a Maybe
--   type.
data NodeG a c tag text
Element :: !tag -> ![(tag, text)] -> c (NodeG a c tag text) -> a -> NodeG a c tag text
eName :: NodeG a c tag text -> !tag
eAttributes :: NodeG a c tag text -> ![(tag, text)]
eChildren :: NodeG a c tag text -> c (NodeG a c tag text)
eAnn :: NodeG a c tag text -> a
Text :: !text -> NodeG a c tag text

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

-- | Type alias for a single annotated node, annotated with parse location
type LNode tag text = Node XMLParseLocation tag text

-- | Type alias for a single node with unqualified tag names where tag and
--   text are the same string type, annotated with parse location
type ULNode text = LNode text text

-- | Modify this node's annotation (non-recursively) if it's an element,
--   otherwise no-op.
modifyAnnotation :: (a -> a) -> Node a tag text -> Node a tag text

-- | Modify this node's annotation and all its children recursively if it's
--   an element, otherwise no-op.
mapAnnotation :: (a -> b) -> Node a tag text -> Node b tag text

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

-- | Type alias for a single node where qualified names are used for tags,
--   annotated with parse location
type QLNode text = LNode (QName text) text

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

-- | Type alias for a single node where namespaced names are used for tags,
--   annotated with parse location
type NLNode text = LNode (NName text) text
data ParserOptions tag text
ParserOptions :: Maybe Encoding -> Maybe (tag -> Maybe text) -> ParserOptions tag text

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
parserEncoding :: ParserOptions tag text -> Maybe Encoding

-- | If provided, entity references (i.e. <tt>&amp;nbsp;</tt> and friends)
--   will be decoded into text using the supplied lookup function
entityDecoder :: ParserOptions tag text -> Maybe (tag -> Maybe text)
defaultParserOptions :: ParserOptions tag text

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

-- | 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.
parse :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> (LNode tag text, Maybe XMLParseError)

-- | Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parse' :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> Either XMLParseError (LNode tag text)

-- | Parse error, consisting of message text and error location
data XMLParseError
XMLParseError :: String -> XMLParseLocation -> XMLParseError

-- | Specifies a location of an event within the input text
data XMLParseLocation
XMLParseLocation :: Int64 -> Int64 -> Int64 -> Int64 -> XMLParseLocation

-- | Line number of the event
xmlLineNumber :: XMLParseLocation -> Int64

-- | Column number of the event
xmlColumnNumber :: XMLParseLocation -> Int64

-- | Byte index of event from start of document
xmlByteIndex :: XMLParseLocation -> Int64

-- | The number of bytes in the event
xmlByteCount :: XMLParseLocation -> Int64

-- | Lazily parse XML to tree. In the event of an error, throw
--   <a>XMLParseException</a>.
--   
--   <tt>parseThrowing</tt> can throw an exception from pure code, which is
--   generally a bad way to handle errors, because Haskell's lazy
--   evaluation means it's hard to predict where it will be thrown from.
--   However, it may be acceptable in situations where it's not expected
--   during normal operation, depending on the design of your program.
parseThrowing :: (GenericXMLString tag, GenericXMLString text) => ParserOptions tag text -> ByteString -> LNode tag text

-- | An exception indicating an XML parse error, used by the
--   <i>..Throwing</i> variants.
data XMLParseException
XMLParseException :: XMLParseError -> XMLParseException
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. Variant that takes annotations for start tags.
saxToTree :: (GenericXMLString tag) => [(SAXEvent tag text, a)] -> (Node a tag text, Maybe XMLParseError)

-- | 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
eAttrs :: Node a tag text -> [(tag, text)]

-- | DEPRECATED: Use <a>parse</a> instead.
--   
--   Lazily parse XML to SAX events. In the event of an error, FailDocument
--   is the last element of the output list. Deprecated in favour of new
--   <a>parse</a>
parseSAX :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]

-- | DEPRECATED: Use <a>parseThrowing</a> instead.
--   
--   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]

-- | DEPRECATED: Use <a>parseLocations</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event.
parseSAXLocations :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | DEPRECATED: Used <a>parseLocationsThrowing</a> instead.
--   
--   A variant of parseSAX that gives a document location with each SAX
--   event. In the event of an error, throw <a>XMLParseException</a>.
parseSAXLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]

-- | DEPRECATED: Use <a>parse</a> instead.
--   
--   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 -> (LNode tag text, Maybe XMLParseError)

-- | DEPRECATED: use <a>parse</a> instead.
--   
--   Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parseTree' :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> Either XMLParseError (LNode tag text)

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

-- | Convert an annotated tree (<i>Annotated</i> module) into a
--   non-annotated tree (<i>Tree</i> module). DEPRECATED in favour of
--   <a>fromElement</a>.
unannotate :: (Functor c) => NodeG a c tag text -> NodeG c tag text
instance (Functor c, List c) => MkElementClass (NodeG (Maybe a)) c
instance (Functor c, List c) => NodeClass (NodeG a) c
instance (NFData tag, NFData text, NFData a) => NFData (NodeG a [] tag text)
instance (Eq tag, Eq text, Eq a) => Eq (NodeG a [] tag text)
instance (Show tag, Show text, Show a) => Show (NodeG a [] tag text)