-- 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>), extended XML trees with comments, processing
--   instructions, etc (<i>Extended</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. Because of the generalized list, Hexpat is designed
--   to allow for chunked I/O, but as of this writing I haven't done a nice
--   integration with enumerator and friends.
--   
--   <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>, <i>Tree</i> and <i>Extended</i>, so
--   you won't need to import them directly.
--   
--   If you have trouble building on Windows, you can try the bundle flag.
--   This will make it build from the source of libexpat bundled inside the
--   hexpat package: cabal install -f bundle hexpat
--   
--   Credits to Iavor Diatchki and the <tt>xml</tt> (XML.Light) package for
--   <i>Proc</i> and <i>Cursor</i>. Thanks to the many contributors.
--   
--   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; 0.17 fix mapNodeContainer &amp; rename some things.;
--   0.18 rename defaultEncoding to overrideEncoding. 0.18.3 formatG and
--   indent were demanding list items more than once (inefficient in
--   chunked processing); 0.19 add Extended.hs; 0.19.1 fix a memory leak
--   introduced in 0.19, delegate parsing to bound thread if unbound (see
--   note above); 0.19.2 include expat source code so 'cabal install' just
--   works on Linux, Mac and Windows (thanks Jacob Stanley); 0.19.3 fix
--   misconfiguration of expat which broke entity parsing; 0.19.4 bump
--   version constraint for text; 0.19.5 bump text to &lt; 0.12 and fix
--   text-0.10.0.1 breakage; 0.19.6 dependency breakage with List; 0.19.7
--   ghc-7.2.1 compatibility; 0.19.8 fix space leak on lazy parse under
--   ghc-7.2.1; 0.19.9 fix formatting of &gt; character + improve
--   performance; 0.19.10 ghc-7.4.x compatibility; 0.20.1 fix an
--   unfortunate crash when used in parallel processing and greatly improve
--   performance; 0.20.2 make parseSaxG lazier; 0.20.3 minor build issues;
--   0.20.4 remove dependency on extensible-exceptions; 0.20.5 bump text
--   upper bound; 0.20.6 bump text again to include 1.1.x.x; 0.20.7 bump
--   text again for 1.2.x.x; 0.20.8 bump utf8-string dep; 0.20.9 bump
--   deepseq dep/ghc-7.10 compatibility.; 0.20.10 increase dependency upper
--   bounds; 0.20.11 update to libexpat-2.2.1 which includes several
--   security fixes; 0.20.12 use the system libexpat by default, but
--   provide a bundle flag to allow a bundled copy of expat to be used,
--   which might make life easier on Windows: cabal install -f bundle
--   hexpat; 0.20.13 Fix some mistakes made in 0.20.12 cabal file.
@package hexpat
@version 0.20.13


-- | Low-level interface to Expat. Unless speed is paramount, this should
--   normally be avoided in favour of the interfaces provided by <a>SAX</a>
--   and <a>Tree</a>, etc.
module Text.XML.Expat.Internal.IO
type HParser = ByteString -> Bool -> IO (ForeignPtr Word8, CInt, Maybe XMLParseError)
hexpatNewParser :: Maybe Encoding -> Maybe (ByteString -> Maybe ByteString) -> Bool -> IO (HParser, IO XMLParseLocation)
encodingToString :: Encoding -> String
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
instance GHC.Show.Show Text.XML.Expat.Internal.IO.XMLParseError
instance GHC.Classes.Eq Text.XML.Expat.Internal.IO.XMLParseError
instance GHC.Show.Show Text.XML.Expat.Internal.IO.XMLParseLocation
instance GHC.Classes.Eq Text.XML.Expat.Internal.IO.XMLParseLocation
instance Control.DeepSeq.NFData Text.XML.Expat.Internal.IO.XMLParseError
instance Control.DeepSeq.NFData Text.XML.Expat.Internal.IO.XMLParseLocation


-- | This module provides functions to parse an XML document to a lazy
--   stream of SAX events.
module Text.XML.Expat.SAX
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 ParseOptions tag text
ParseOptions :: Maybe Encoding -> Maybe (tag -> Maybe text) -> ParseOptions tag text

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
[overrideEncoding] :: ParseOptions 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] :: ParseOptions tag text -> Maybe (tag -> Maybe text)
data SAXEvent tag text
XMLDeclaration :: text -> (Maybe text) -> (Maybe Bool) -> SAXEvent tag text
StartElement :: tag -> [(tag, text)] -> SAXEvent tag text
EndElement :: tag -> SAXEvent tag text
CharacterData :: text -> SAXEvent tag text
StartCData :: SAXEvent tag text
EndCData :: SAXEvent tag text
ProcessingInstruction :: text -> text -> SAXEvent tag text
Comment :: text -> SAXEvent tag text
FailDocument :: XMLParseError -> SAXEvent tag 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) => ParseOptions tag text -> ByteString -> [SAXEvent tag text]

-- | Parse a generalized list of ByteStrings containing XML to SAX events.
--   In the event of an error, FailDocument is the last element of the
--   output list.
parseG :: forall tag text l. (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> l (SAXEvent tag text)

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

-- | Parse a generalized list of ByteStrings containing XML to SAX events.
--   In the event of an error, FailDocument is the last element of the
--   output list.
parseLocationsG :: forall tag text l. (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> l (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) => ParseOptions 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) => ParseOptions tag text -> ByteString -> [SAXEvent tag text]
defaultParseOptions :: ParseOptions tag text

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

-- | 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)
gxFromByteString :: GenericXMLString s => ByteString -> s
gxToByteString :: GenericXMLString s => s -> ByteString
instance GHC.Show.Show Text.XML.Expat.SAX.XMLParseException
instance GHC.Classes.Eq Text.XML.Expat.SAX.XMLParseException
instance (GHC.Show.Show tag, GHC.Show.Show text) => GHC.Show.Show (Text.XML.Expat.SAX.SAXEvent tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text) => GHC.Classes.Eq (Text.XML.Expat.SAX.SAXEvent tag text)
instance Text.XML.Expat.SAX.GenericXMLString GHC.Base.String
instance Text.XML.Expat.SAX.GenericXMLString Data.ByteString.Internal.ByteString
instance Text.XML.Expat.SAX.GenericXMLString Data.Text.Internal.Text
instance (Control.DeepSeq.NFData tag, Control.DeepSeq.NFData text) => Control.DeepSeq.NFData (Text.XML.Expat.SAX.SAXEvent tag text)
instance GHC.Exception.Exception Text.XML.Expat.SAX.XMLParseException


-- | 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. This <i>excludes</i> the
--   contents of <i>comments</i> or <i>processing instructions</i>. To get
--   the text for these node types, use <a>getText</a>.
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

-- | Is the given node an element?
isElement :: NodeClass n c => n c tag text -> Bool

-- | Is the given node text?
isText :: NodeClass n c => n c tag text -> Bool

-- | Is the given node CData?
isCData :: NodeClass n c => n c tag text -> Bool

-- | Is the given node a processing instruction?
isProcessingInstruction :: NodeClass n c => n c tag text -> Bool

-- | Is the given node a comment?
isComment :: NodeClass n c => n c tag text -> Bool

-- | Extract all text content from inside a tag into a single string,
--   including any text contained in children. This <i>excludes</i> the
--   contents of <i>comments</i> or <i>processing instructions</i>. To get
--   the text for these node types, use <a>getText</a>.
textContentM :: (NodeClass n c, Monoid text) => n c tag text -> ItemM c text

-- | Is the given node a tag with the given name?
isNamed :: (NodeClass n c, Eq tag) => tag -> n c tag text -> Bool

-- | Get the name of this node if it's an element, return empty string
--   otherwise.
getName :: (NodeClass n c, Monoid tag) => n c tag text -> tag

-- | Is the given node a Processing Instruction with the given target?
hasTarget :: (NodeClass n c, Eq text) => text -> n c tag text -> Bool

-- | Get the target of this node if it's a Processing Instruction, return
--   empty string otherwise.
getTarget :: (NodeClass n c, Monoid text) => n c tag text -> text

-- | Get the attributes of a node if it's an element, return empty list
--   otherwise.
getAttributes :: NodeClass n c => n c tag text -> [(tag, text)]

-- | Get children of a node if it's an element, return empty list
--   otherwise.
getChildren :: NodeClass n c => n c tag text -> c (n c tag text)

-- | Get this node's text if it's a text node, comment, or processing
--   instruction, return empty text otherwise.
getText :: (NodeClass n c, Monoid text) => n c tag text -> text

-- | Modify name if it's an element, no-op otherwise.
modifyName :: NodeClass n c => (tag -> tag) -> n c tag text -> n c tag text

-- | Modify attributes if it's an element, no-op otherwise.
modifyAttributes :: NodeClass n c => ([(tag, text)] -> [(tag, text)]) -> n c tag text -> n c tag text

-- | Modify children (non-recursively) if it's an element, no-op otherwise.
modifyChildren :: NodeClass n c => (c (n c tag text) -> c (n c tag text)) -> n c tag text -> n c tag text

-- | Map an element non-recursively, allowing the tag type to be changed.
modifyElement :: 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

-- | Map all tags (both tag names and attribute names) recursively.
mapAllTags :: NodeClass n c => (tag -> tag') -> n c tag text -> n c tag' text

-- | Change a node recursively from one container type to another, with a
--   specified function to convert the container type.
mapNodeContainer :: (NodeClass n c, List c') => (forall a. c a -> ItemM c (c' a)) -> n c tag text -> ItemM c (n c' tag text)

-- | Generic text node constructor.
mkText :: NodeClass n c => text -> n c tag text

-- | Change a list of nodes recursively from one container type to another,
--   with a specified function to convert the container type.
mapNodeListContainer :: (NodeClass n c, List c') => (forall a. c a -> ItemM c (c' a)) -> c (n c tag text) -> ItemM c (c' (n c' tag text))

-- | Change a node recursively from one container type to another. This
--   extracts the entire tree contents to standard lists and re-constructs
--   them with the new container type. For monadic list types used in
--   <tt>hexpat-iteratee</tt> this operation forces evaluation.
fromNodeContainer :: (NodeClass n c, List c') => n c tag text -> ItemM c (n c' tag text)

-- | Change a list of nodes recursively from one container type to another.
--   This extracts the entire tree contents to standard lists and
--   re-constructs them with the new container type. For monadic list types
--   used in <tt>hexpat-iteratee</tt> this operation forces evaluation.
fromNodeListContainer :: (NodeClass n c, List c') => c (n c tag text) -> ItemM c (c' (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

-- | Generic element constructor.
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 GHC.Show.Show text => GHC.Show.Show (Text.XML.Expat.Internal.Qualified.QName text)
instance GHC.Classes.Eq text => GHC.Classes.Eq (Text.XML.Expat.Internal.Qualified.QName text)
instance Control.DeepSeq.NFData text => Control.DeepSeq.NFData (Text.XML.Expat.Internal.Qualified.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 GHC.Show.Show text => GHC.Show.Show (Text.XML.Expat.Internal.Namespaced.NName text)
instance GHC.Classes.Eq text => GHC.Classes.Eq (Text.XML.Expat.Internal.Namespaced.NName text)
instance Control.DeepSeq.NFData text => Control.DeepSeq.NFData (Text.XML.Expat.Internal.Namespaced.NName 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)


-- | 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 defaultParseOptions 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 straightforward - 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 defaultParseOptions
--                      (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 defaultParseOptions
--                          (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
--   would normally be [], but could potentially be a monadic list type to
--   allow for chunked I/O.
--   
--   <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 node with unqualified tag names where tag and text
--   are the same string type.
type UNode text = Node text text

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

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

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
[overrideEncoding] :: ParseOptions 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] :: ParseOptions tag text -> Maybe (tag -> Maybe text)
defaultParseOptions :: ParseOptions tag text
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) => ParseOptions 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) => ParseOptions tag text -> ByteString -> Either XMLParseError (Node tag text)

-- | Parse a generalized list to a tree, ignoring parse errors. This
--   function allows for a parse from an enumerator/iteratee to a "lazy"
--   tree structure using the <tt>List-enumerator</tt> package.
parseG :: (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> ItemM l (NodeG l 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) => ParseOptions 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

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

-- | A lower level function that converts a generalized SAX stream into a
--   tree structure. Ignores parse errors.
saxToTreeG :: forall tag text l. (GenericXMLString tag, List l) => l (SAXEvent tag text) -> ItemM l (NodeG l 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)
gxFromByteString :: GenericXMLString s => ByteString -> s
gxToByteString :: GenericXMLString s => s -> ByteString
instance (GHC.Show.Show tag, GHC.Show.Show text) => GHC.Show.Show (Text.XML.Expat.Tree.NodeG [] tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text) => GHC.Classes.Eq (Text.XML.Expat.Tree.NodeG [] tag text)
instance (Control.DeepSeq.NFData tag, Control.DeepSeq.NFData text) => Control.DeepSeq.NFData (Text.XML.Expat.Tree.NodeG [] tag text)
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.NodeClass Text.XML.Expat.Tree.NodeG c
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.MkElementClass Text.XML.Expat.Tree.NodeG c


-- | Type classes to allow for XML handling functions to be generalized to
--   work with different document types.
module Text.XML.Expat.Internal.DocumentClass

-- | XML declaration, consisting of version, encoding and standalone.
--   
--   The formatting functions always outputs only UTF-8, regardless of what
--   encoding is specified here. If you want to produce a document in a
--   different encoding, then set the encoding here, format the document,
--   and then convert the output text from UTF-8 to your desired encoding
--   using some text conversion library.
data XMLDeclaration text
XMLDeclaration :: text -> (Maybe text) -> (Maybe Bool) -> XMLDeclaration text

-- | Stub for future expansion.
data DocumentTypeDeclaration (c :: * -> *) tag text
DocumentTypeDeclaration :: DocumentTypeDeclaration tag text
data Misc text
Comment :: !text -> Misc text
ProcessingInstruction :: !text -> !text -> Misc text
class (Functor c, List c, NodeClass (NodeType d) c) => DocumentClass d (c :: * -> *)

-- | Get the XML declaration for this document.
getXMLDeclaration :: DocumentClass d c => d c tag text -> Maybe (XMLDeclaration text)

-- | Get the Document Type Declaration (DTD) for this document.
getDocumentTypeDeclaration :: DocumentClass d c => d c tag text -> Maybe (DocumentTypeDeclaration c tag text)

-- | Get the top-level <a>Misc</a> nodes for this document.
getTopLevelMiscs :: DocumentClass d c => d c tag text -> c (Misc text)

-- | Get the root element for this document.
getRoot :: DocumentClass d c => d c tag text -> NodeType d c tag text

-- | Make a document with the specified fields.
mkDocument :: DocumentClass d c => Maybe (XMLDeclaration text) -> Maybe (DocumentTypeDeclaration c tag text) -> c (Misc text) -> NodeType d c tag text -> d c tag text

-- | Make a document with the specified root node and all other information
--   set to defaults.
mkPlainDocument :: DocumentClass d c => NodeType d c tag text -> d c tag text
modifyXMLDeclaration :: DocumentClass d c => (Maybe (XMLDeclaration text) -> Maybe (XMLDeclaration text)) -> d c tag text -> d c tag text
modifyDocumentTypeDeclaration :: DocumentClass d c => (Maybe (DocumentTypeDeclaration c tag text) -> Maybe (DocumentTypeDeclaration c tag text)) -> d c tag text -> d c tag text
modifyTopLevelMiscs :: DocumentClass d c => (c (Misc text) -> c (Misc text)) -> d c tag text -> d c tag text
modifyRoot :: DocumentClass d c => (NodeType d c tag text -> NodeType d c tag text) -> d c tag text -> d c tag text
instance GHC.Show.Show (Text.XML.Expat.Internal.DocumentClass.DocumentTypeDeclaration c tag text)
instance GHC.Classes.Eq (Text.XML.Expat.Internal.DocumentClass.DocumentTypeDeclaration c tag text)
instance GHC.Show.Show text => GHC.Show.Show (Text.XML.Expat.Internal.DocumentClass.XMLDeclaration text)
instance GHC.Classes.Eq text => GHC.Classes.Eq (Text.XML.Expat.Internal.DocumentClass.XMLDeclaration text)
instance GHC.Show.Show text => GHC.Show.Show (Text.XML.Expat.Internal.DocumentClass.Misc text)
instance GHC.Classes.Eq text => GHC.Classes.Eq (Text.XML.Expat.Internal.DocumentClass.Misc text)
instance Control.DeepSeq.NFData text => Control.DeepSeq.NFData (Text.XML.Expat.Internal.DocumentClass.Misc text)


-- | This module provides functions to format a tree structure or SAX
--   stream as UTF-8 encoded XML.
--   
--   The formatting functions always outputs only UTF-8, regardless of what
--   encoding is specified in the document's <a>XMLDeclaration</a>. If you
--   want to output a document in another encoding, then make sure the
--   <a>XMLDeclaration</a> agrees with the final output encoding, then
--   format the document, and convert from UTF-8 to your desired encoding
--   using some text conversion library.
--   
--   The lazy <a>ByteString</a> representation of the output in generated
--   with very small chunks, so in some applications you may want to
--   combine them into larger chunks to get better efficiency.
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

-- | Format an XML document - lazy variant that returns lazy ByteString.
formatDocument :: (DocumentClass d [], GenericXMLString tag, GenericXMLString text) => d [] tag text -> ByteString

-- | Format an XML document - strict variant that returns strict
--   ByteString.
formatDocument' :: (DocumentClass d [], GenericXMLString tag, GenericXMLString text) => d [] tag text -> ByteString

-- | Format an XML document - generalized variant that returns a generic
--   list of strict ByteStrings.
formatDocumentG :: (DocumentClass d c, GenericXMLString tag, GenericXMLString text) => d c tag text -> c ByteString

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

-- | Flatten a tree structure into SAX events, monadic version.
treeToSAX :: forall tag text n c. (GenericXMLString tag, GenericXMLString text, Monoid text, NodeClass n c) => n c tag text -> c (SAXEvent tag text)
documentToSAX :: forall tag text d c. (GenericXMLString tag, GenericXMLString text, Monoid text, DocumentClass d c) => d 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 :: forall c tag text. (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_ :: forall n c tag text. (NodeClass n c, GenericXMLString tag, GenericXMLString text) => Int -> Int -> n c tag text -> n c tag text


-- | An extended variant of <i>Node</i> intended to implement the entire
--   XML specification. DTDs are not yet supported, however.
--   
--   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.Extended

-- | A pure representation of an XML document that uses a list as its
--   container type.
type Document a tag text = DocumentG a [] tag text

-- | Document representation of the XML document, intended to support the
--   entire XML specification. DTDs are not yet supported, however.
data DocumentG a c tag text
Document :: Maybe (XMLDeclaration text) -> Maybe (DocumentTypeDeclaration c tag text) -> c (Misc text) -> NodeG a c tag text -> DocumentG a c tag text
[dXMLDeclaration] :: DocumentG a c tag text -> Maybe (XMLDeclaration text)
[dDocumentTypeDeclaration] :: DocumentG a c tag text -> Maybe (DocumentTypeDeclaration c tag text)
[dTopLevelMiscs] :: DocumentG a c tag text -> c (Misc text)
[dRoot] :: DocumentG a c tag text -> NodeG a c tag text

-- | A pure tree representation that uses a list as its container type,
--   extended 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

-- | Extended variant of the tree representation of the XML document,
--   intended to support the entire XML specification. DTDs are not yet
--   supported, however.
--   
--   <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 or () (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
CData :: !text -> NodeG a c tag text
Misc :: (Misc text) -> NodeG a c tag text

-- | Type alias for an extended document with unqualified tag names where
--   tag and text are the same string type
type UDocument a text = Document a text text

-- | Type alias for an extended document, annotated with parse location
type LDocument tag text = Document XMLParseLocation tag text

-- | Type alias for an extended document with unqualified tag names where
--   tag and text are the same string type, annotated with parse location
type ULDocument text = Document XMLParseLocation text text

-- | Type alias for an extended 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 an extended node, annotated with parse location
type LNode tag text = Node XMLParseLocation tag text

-- | Type alias for an extended 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

-- | Modify the annotation of every node in the document recursively.
mapDocumentAnnotation :: (a -> b) -> Document a tag text -> Document b tag text

-- | Type alias for an extended document where qualified names are used for
--   tags
type QDocument a text = Document a (QName text) text

-- | Type alias for an extended document where qualified names are used for
--   tags, annotated with parse location
type QLDocument text = Document XMLParseLocation (QName text) text

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

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

-- | Type alias for an extended document where namespaced names are used
--   for tags
type NDocument a text = Document a (NName text) text

-- | Type alias for an extended document where namespaced names are used
--   for tags, annotated with parse location
type NLDocument text = Document XMLParseLocation (NName text) text

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

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

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
[overrideEncoding] :: ParseOptions 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] :: ParseOptions tag text -> Maybe (tag -> Maybe text)
defaultParseOptions :: ParseOptions tag text
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) => ParseOptions tag text -> ByteString -> (LDocument tag text, Maybe XMLParseError)

-- | Strictly parse XML to tree. Returns error message or valid parsed
--   tree.
parse' :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> Either XMLParseError (LDocument 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) => ParseOptions tag text -> ByteString -> LDocument tag text

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

-- | A lower level function that lazily converts a SAX stream into a tree
--   structure. Variant that takes annotations for start tags.
saxToTree :: (GenericXMLString tag, Monoid text) => [(SAXEvent tag text, a)] -> (Document 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)
gxFromByteString :: GenericXMLString s => ByteString -> s
gxToByteString :: GenericXMLString s => s -> ByteString
instance (GHC.Show.Show tag, GHC.Show.Show text, GHC.Show.Show a) => GHC.Show.Show (Text.XML.Expat.Extended.DocumentG a [] tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text, GHC.Classes.Eq a) => GHC.Classes.Eq (Text.XML.Expat.Extended.DocumentG a [] tag text)
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.DocumentClass.DocumentClass (Text.XML.Expat.Extended.DocumentG ann) c
instance (GHC.Show.Show tag, GHC.Show.Show text, GHC.Show.Show a) => GHC.Show.Show (Text.XML.Expat.Extended.NodeG a [] tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text, GHC.Classes.Eq a) => GHC.Classes.Eq (Text.XML.Expat.Extended.NodeG a [] tag text)
instance (Control.DeepSeq.NFData tag, Control.DeepSeq.NFData text, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Text.XML.Expat.Extended.NodeG a [] tag text)
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.NodeClass (Text.XML.Expat.Extended.NodeG a) c
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.MkElementClass (Text.XML.Expat.Extended.NodeG (GHC.Base.Maybe a)) c
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.MkElementClass (Text.XML.Expat.Extended.NodeG ()) c


-- | 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 (GHC.Show.Show text, GHC.Show.Show tag) => GHC.Show.Show (Text.XML.Expat.Cursor.Tag tag text)
instance (GHC.Show.Show (n c tag text), GHC.Show.Show (c (n c tag text)), GHC.Show.Show tag, GHC.Show.Show text) => GHC.Show.Show (Text.XML.Expat.Cursor.CursorG 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
--   would normally be [], but could potentially be a monadic list type to
--   allow for chunked I/O.
--   
--   <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 or () (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 an 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 an annotated node, annotated with parse location
type LNode tag text = Node XMLParseLocation tag text

-- | Type alias for an annotated 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 an annotated node where qualified names are used for
--   tags
type QNode a text = Node a (QName text) text

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

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

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

-- | The encoding parameter, if provided, overrides the document's encoding
--   declaration.
[overrideEncoding] :: ParseOptions 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] :: ParseOptions tag text -> Maybe (tag -> Maybe text)
defaultParseOptions :: ParseOptions tag text
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) => ParseOptions 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) => ParseOptions tag text -> ByteString -> Either XMLParseError (LNode tag text)

-- | Parse a generalized list to a tree, ignoring parse errors. This
--   function allows for a parse from an enumerator/iteratee to a "lazy"
--   tree structure using the <tt>List-enumerator</tt> package.
parseG :: (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> ItemM l (NodeG XMLParseLocation l 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) => ParseOptions 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

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

-- | A lower level function that converts a generalized SAX stream into a
--   tree structure. Ignores parse errors.
saxToTreeG :: forall l a tag text. (GenericXMLString tag, List l, Monad (ItemM l)) => l (SAXEvent tag text, a) -> ItemM l (NodeG a l 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)
gxFromByteString :: GenericXMLString s => ByteString -> s
gxToByteString :: GenericXMLString s => s -> ByteString
instance (GHC.Show.Show tag, GHC.Show.Show text, GHC.Show.Show a) => GHC.Show.Show (Text.XML.Expat.Annotated.NodeG a [] tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text, GHC.Classes.Eq a) => GHC.Classes.Eq (Text.XML.Expat.Annotated.NodeG a [] tag text)
instance (Control.DeepSeq.NFData tag, Control.DeepSeq.NFData text, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Text.XML.Expat.Annotated.NodeG a [] tag text)
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.NodeClass (Text.XML.Expat.Annotated.NodeG a) c
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.MkElementClass (Text.XML.Expat.Annotated.NodeG (GHC.Base.Maybe a)) c
instance (GHC.Base.Functor c, Data.List.Class.List c) => Text.XML.Expat.Internal.NodeClass.MkElementClass (Text.XML.Expat.Annotated.NodeG ()) c