-- 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 (http://expat.sourceforge.net/ - a fast
--   stream-oriented XML parser written in C). It is extensible to any
--   string type, with String, ByteString and
--   Text provided out of the box.
--   
--   Basic usage: Parsing a tree (Tree), formatting a tree
--   (Format). Other features: Helpers for processing XML trees
--   (Proc), trees annotated with XML source location
--   (Annotated), extended XML trees with comments, processing
--   instructions, etc (Extended), XML cursors (Cursor),
--   SAX-style parse (SAX), and access to the low-level interface in
--   case speed is paramount (Internal.IO).
--   
--   The design goals are speed, speed, speed, interface simplicity and
--   modularity.
--   
--   For introduction and examples, see the Text.XML.Expat.Tree
--   module. For benchmarks, http://haskell.org/haskellwiki/Hexpat/
--   
--   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.
--   
--   IO is filed under Internal because it's low-level and
--   most users won't want it. The other Internal modules are
--   re-exported by Annotated, Tree and Extended, 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 xml (XML.Light) package for
--   Proc and Cursor. 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 & 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 < 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 > 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 SAX
--   and Tree, 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.XMLParseLocation
instance GHC.Classes.Eq Text.XML.Expat.Internal.IO.XMLParseLocation
instance GHC.Show.Show Text.XML.Expat.Internal.IO.XMLParseError
instance GHC.Classes.Eq Text.XML.Expat.Internal.IO.XMLParseError
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. &nbsp; 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 XMLParseException.
--   
--   parseLocationsThrowing 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
--   XMLParseException.
--   
--   parseThrowing 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
--   ..Throwing 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 hexpat, you must make it an instance of
--   GenericXMLString.
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.SAX.SAXEvent tag text)
instance (GHC.Classes.Eq tag, GHC.Classes.Eq text) => GHC.Classes.Eq (Text.XML.Expat.SAX.SAXEvent tag text)
instance GHC.Show.Show Text.XML.Expat.SAX.XMLParseException
instance GHC.Classes.Eq Text.XML.Expat.SAX.XMLParseException
instance GHC.Exception.Type.Exception Text.XML.Expat.SAX.XMLParseException
instance (Control.DeepSeq.NFData tag, Control.DeepSeq.NFData text) => Control.DeepSeq.NFData (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.Type.ByteString
instance Text.XML.Expat.SAX.GenericXMLString Data.Text.Internal.Text

-- | Type classes to allow for XML handling functions to be generalized to
--   work with different node types, including the ones defined in
--   Tree and Annotated.
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 excludes the
--   contents of comments or processing instructions. To get
--   the text for these node types, use getText.
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. ListOf
--   (UNode Text)
type family ListOf n
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 excludes the
--   contents of comments or processing instructions. To get
--   the text for these node types, use getText.
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
--   hexpat-iteratee 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 hexpat-iteratee 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 Just, deleteAttribute if Nothing.
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)

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

-- | In the default representation, qualified tag and attribute names such
--   as <abc:hello> 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)

-- | 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 (c :: * -> *) tag text
data Misc text
Comment :: !text -> Misc text
ProcessingInstruction :: !text -> !text -> Misc text
type family NodeType (d :: (* -> *) -> * -> * -> *) :: (* -> *) -> * -> * -> *
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 Misc 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 => 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.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.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)

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)

-- | An extended variant of Node intended to implement the entire
--   XML specification. DTDs are not yet supported, however.
--   
--   The names conflict with those in Tree 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 hexpat package, a list of nodes has the type [Node
--   tag text], but note that you can also use the more general type
--   function ListOf to give a list of any node type, using that
--   node's associated list type, e.g. ListOf (UNode Text).
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.
--   
--   c is the container type for the element's children, which is
--   [] in the hexpat package, and a monadic list type for
--   hexpat-iteratee.
--   
--   tag is the tag type, which can either be one of several
--   string types, or a special type from the
--   Text.XML.Expat.Namespaced or
--   Text.XML.Expat.Qualified modules.
--   
--   text is the string type for text content.
--   
--   a 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 Text.XML.Expat.Cursor module
--   need to create new nodes through the MkElementClass type class.
--   Normally this can only be done if a 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 MkElementClass instance.
--   Apart from that, there is no requirement for a 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. &nbsp; 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
--   XMLParseException.
--   
--   parseThrowing 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
--   ..Throwing 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 hexpat, you must make it an instance of
--   GenericXMLString.
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.Maybe.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

-- | A variant of Node 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 Tree 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 hexpat package, a list of nodes has the type [Node
--   tag text], but note that you can also use the more general type
--   function ListOf to give a list of any node type, using that
--   node's associated list type, e.g. ListOf (UNode Text).
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.
--   
--   c 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.
--   
--   tag is the tag type, which can either be one of several
--   string types, or a special type from the
--   Text.XML.Expat.Namespaced or
--   Text.XML.Expat.Qualified modules.
--   
--   text is the string type for text content.
--   
--   a 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 Text.XML.Expat.Cursor module
--   need to create new nodes through the MkElementClass type class.
--   Normally this can only be done if a 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 MkElementClass instance.
--   Apart from that, there is no requirement for a 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. &nbsp; 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 List-enumerator 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
--   XMLParseException.
--   
--   parseThrowing 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
--   ..Throwing 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 hexpat, you must make it an instance of
--   GenericXMLString.
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.Maybe.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

-- | This module provides functions to parse an XML document to a tree
--   structure, either strictly or lazily.
--   
--   The GenericXMLString type class allows you to use any string
--   type. Three string types are provided for here: String,
--   ByteString and Text.
--   
--   Here is a complete example to get you started:
--   
--   
--   -- | 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 <- getArgs
--       case args of
--           [filename] -> process filename
--           otherwise  -> do
--               hPutStrLn stderr "Usage: helloworld <file.xml>"
--               exitWith $ ExitFailure 1
--   
--   process :: String -> IO ()
--   process filename = do
--       inputText <- 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 -> return ()
--           Just err -> do
--               hPutStrLn stderr $ "XML parse failed: "++show err
--               exitWith $ ExitFailure 2
--   
--   
--   Error handling in strict parses is very straightforward - just check
--   the Either 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
--   
--   
--   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 $ "<top><banana></apple></top>")
--       print (tree :: UNode String)
--   
--       -- Note: We check the error _after_ we have finished our processing
--       -- on the tree.
--       case mError of
--           Just err -> putStrLn $ "It failed : "++show err
--           Nothing -> putStrLn "Success!"
--   
--   
--   Way no. 2 - Using exceptions
--   
--   parseThrowing 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.
--   
--   
--   ...
--   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 $ "<top><banana></apple></top>")
--           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 ->
--           case E.fromException exc of
--               Just (XMLParseException err) -> putStrLn $ "It failed : "++show err
--               Nothing -> E.throwIO exc)
--   
module Text.XML.Expat.Tree

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

-- | The tree representation of the XML document.
--   
--   c 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.
--   
--   tag is the tag type, which can either be one of several
--   string types, or a special type from the
--   Text.XML.Expat.Namespaced or
--   Text.XML.Expat.Qualified modules.
--   
--   text 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. &nbsp; 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 List-enumerator 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
--   XMLParseException.
--   
--   parseThrowing 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
--   ..Throwing 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 hexpat, you must make it an instance of
--   GenericXMLString.
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

-- | 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 XMLDeclaration. If you
--   want to output a document in another encoding, then make sure the
--   XMLDeclaration 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 ByteString 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 <?xml.. header - lazy variant that returns
--   lazy ByteString.
format :: (NodeClass n [], GenericXMLString tag, GenericXMLString text) => n [] tag text -> ByteString

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

-- | Format document with <?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

-- | 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 modifyContentM, then M-suffixed functions
--   are for use with monadic node types, as used when dealing with chunked
--   I/O with the hexpat-iteratee package. In the more common pure
--   case, you wouldn't need these *M functions.
module Text.XML.Expat.Cursor

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

-- | Generalized cursor: The position of a piece of content in an XML
--   document. n is the Node type and c 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 Text.XML.Expat.Tree.Node 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 tag, GHC.Show.Show text) => 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)
