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


-- | Pure-Haskell utilities for dealing with XML with the enumerator package.
--   
--   Provides the ability to parse and render XML in a streaming manner
--   using the enumerator package.
@package xml-enumerator
@version 0.2.0


-- | <tt>Enumeratee</tt>s to render XML <a>Event</a>s. Unlike
--   libxml-enumerator and expat-enumerator, this module does not provide
--   IO and ST variants, since the underlying rendering operations are pure
--   functions.
module Text.XML.Enumerator.Render

-- | Render a stream of <a>Event</a>s into a stream of <a>Builder</a>s.
--   Builders are from the blaze-builder package, and allow the create of
--   optimally sized <a>ByteString</a>s with minimal buffer copying.
renderBuilder :: Monad m => Enumeratee Event Builder m b

-- | Render a stream of <a>Event</a>s into a stream of <a>ByteString</a>s.
--   This function wraps around <a>renderBuilder</a> and
--   <a>builderToByteString</a>, so it produces optimally sized
--   <a>ByteString</a>s with minimal buffer copying.
--   
--   The output is UTF8 encoded.
renderBytes :: MonadIO m => Enumeratee Event ByteString m b

-- | Render a stream of <a>Event</a>s into a stream of <a>ByteString</a>s.
--   This function wraps around <a>renderBuilder</a>,
--   <a>builderToByteString</a> and <a>renderBytes</a>, so it produces
--   optimally sized <a>ByteString</a>s with minimal buffer copying.
renderText :: MonadIO m => Enumeratee Event Text m b


-- | This module provides both a native Haskell solution for parsing XML
--   documents into a stream of events, and a set of parser combinators for
--   dealing with a stream of events.
--   
--   The important thing to know about the combinators is that they do
--   <i>not</i> work on the fully-powered <a>Event</a> datatype; rather,
--   this module defines an <tt>SEvent</tt> datatype which only deals with
--   tags, attributes and content. For most uses, this is sufficient. If
--   you need to parse doctypes, instructions or contents, you will not be
--   able to use the combinators.
--   
--   As a simple example, if you have the following XML file:
--   
--   <pre>
--   &lt;?xml version="1.0" encoding="utf-8"?&gt;
--   &lt;people&gt;
--       &lt;person age="25"&gt;Michael&lt;/person&gt;
--       &lt;person age="2"&gt;Eliezer&lt;/person&gt;
--   &lt;/people&gt;
--   </pre>
--   
--   Then this code:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   import Text.XML.Enumerator.Parse
--   import Data.Text.Lazy (Text, unpack)
--   
--   data Person = Person { age :: Int, name :: Text }
--       deriving Show
--   
--   parsePerson = tag' "person" (requireAttr "age") $ \age -&gt; do
--       name &lt;- content'
--       return $ Person (read $ unpack age) name
--   
--   parsePeople = tag'' "people" $ many parsePerson
--   
--   main = parseFile_ "people.xml" (const Nothing) $ force "people required" parsePeople
--   </pre>
--   
--   will produce:
--   
--   <pre>
--   [Person {age = 25, name = "Michael"},Person {age = 2, name = "Eliezer"}]
--   </pre>
module Text.XML.Enumerator.Parse

-- | Parses a byte stream into <a>Event</a>s. This function is implemented
--   fully in Haskell using attoparsec-text for parsing. The produced error
--   messages do not give line/column information, so you may prefer to
--   stick with the parser provided by libxml-enumerator. However, this has
--   the advantage of not relying on any C libraries.
--   
--   This relies on <a>detectUtf</a> to determine character encoding, and
--   <a>parseText</a> to do the actual parsing.
parseBytes :: Monad m => DecodeEntities -> Enumeratee ByteString Event m a

-- | Parses a character stream into <a>Event</a>s. This function is
--   implemented fully in Haskell using attoparsec-text for parsing. The
--   produced error messages do not give line/column information, so you
--   may prefer to stick with the parser provided by libxml-enumerator.
--   However, this has the advantage of not relying on any C libraries.
parseText :: Monad m => DecodeEntities -> Enumeratee Text Event m a

-- | Automatically determine which UTF variant is being used. This function
--   first checks for BOMs, removing them as necessary, and then check for
--   the equivalent of &lt;?xml for each of UTF-8, UTF-16LE<i>BE, and
--   UTF-32LE</i>BE. It defaults to assuming UTF-8.
detectUtf :: Monad m => Enumeratee ByteString Text m a

-- | A helper function which reads a file from disk using <a>enumFile</a>,
--   detects character encoding using <a>detectUtf</a>, parses the XML
--   using <a>parseBytes</a>, converts to an <tt>SEvent</tt> stream using
--   <tt>simplify</tt> and then handing off control to your supplied
--   parser.
parseFile :: FilePath -> DecodeEntities -> Iteratee Event IO a -> IO (Either SomeException a)

-- | The same as <a>parseFile</a>, but throws any exceptions.
parseFile_ :: FilePath -> DecodeEntities -> Iteratee Event IO a -> IO a
parseLBS :: ByteString -> DecodeEntities -> Iteratee Event IO a -> IO (Either SomeException a)
parseLBS_ :: ByteString -> DecodeEntities -> Iteratee Event IO a -> IO a
type DecodeEntities = Text -> Content

-- | Default implementation of <a>DecodeEntities</a>: handles numeric
--   entities and the five standard character entities (lt, gt, amp, quot,
--   apos).
decodeEntities :: DecodeEntities

-- | The most generic way to parse a tag. It takes a predicate for checking
--   if this is the correct tag name, an <a>AttrParser</a> for handling
--   attributes, and then a parser for dealing with content.
--   
--   This function automatically absorbs its balancing closing tag, and
--   will throw an exception if not all of the attributes or child elements
--   are consumed. If you want to allow extra attributes, see
--   <a>ignoreAttrs</a>.
tag :: Monad m => (Name -> Maybe a) -> (a -> AttrParser b) -> (b -> Iteratee Event m c) -> Iteratee Event m (Maybe c)

-- | A simplified version of <a>tag</a> which matches for specific tag
--   names instead of taking a predicate function. This is often
--   sufficient, and when combined with OverloadedStrings and the IsString
--   instance of <a>Name</a>, can prove to be very concise.
tagName :: Monad m => Name -> AttrParser a -> (a -> Iteratee Event m b) -> Iteratee Event m (Maybe b)

-- | A further simplified tag parser, which requires that no attributes
--   exist.
tagNoAttr :: Monad m => Name -> Iteratee Event m a -> Iteratee Event m (Maybe a)

-- | Grabs the next piece of content. If none if available, returns
--   <a>empty</a>.
content :: Monad m => Iteratee Event m Text

-- | Grabs the next piece of content if available.
contentMaybe :: Monad m => Iteratee Event m (Maybe Text)

-- | Iteratee to skip the next element.
ignoreElem :: Monad m => Iteratee Event m (Maybe ())

-- | Iteratee to skip the siblings element.
ignoreSiblings :: Monad m => Iteratee Event m ()

-- | A monad for parsing attributes. By default, it requires you to deal
--   with all attributes present on an element, and will throw an exception
--   if there are unhandled attributes. Use the <a>requireAttr</a>,
--   <a>optionalAttr</a> et al functions for handling an attribute, and
--   <a>ignoreAttrs</a> if you would like to skip the rest of the
--   attributes on an element.
data AttrParser a

-- | Require that a certain attribute be present and return its value.
requireAttr :: Name -> AttrParser Text

-- | Return the value for an attribute if present.
optionalAttr :: Name -> AttrParser (Maybe Text)
requireAttrRaw :: String -> ((Name, [Content]) -> Maybe b) -> AttrParser b
optionalAttrRaw :: ((Name, [Content]) -> Maybe b) -> AttrParser (Maybe b)

-- | Skip the remaining attributes on an element. Since this will clear the
--   list of attributes, you must call this <i>after</i> any calls to
--   <a>requireAttr</a>, <a>optionalAttr</a>, etc.
ignoreAttrs :: AttrParser ()

-- | Combinator to skip the attributes.
skipAttrs :: AttrParser a -> AttrParser a

-- | Get the value of the first parser which returns <a>Just</a>. If none
--   return <a>Just</a>, returns <a>Nothing</a>.
choose :: Monad m => [Iteratee Event m (Maybe a)] -> Iteratee Event m (Maybe a)

-- | Keep parsing elements as long as the parser returns <a>Just</a>.
many :: Monad m => Iteratee Event m (Maybe a) -> Iteratee Event m [a]

-- | Force an optional parser into a required parser. All of the <a>tag</a>
--   functions, <a>choose</a> and <a>many</a> deal with <a>Maybe</a>
--   parsers. Use this when you want to finally force something to happen.
force :: Monad m => String -> Iteratee Event m (Maybe a) -> Iteratee Event m a

-- | Skip the siblings elements until iteratee not right.
skipTill :: Monad m => Iteratee Event m (Maybe a) -> Iteratee Event m (Maybe a)

-- | Combinator to skip the siblings element.
skipSiblings :: Monad m => Iteratee Event m a -> Iteratee Event m a
data XmlException
XmlException :: String -> Maybe Event -> XmlException
xmlErrorMessage :: XmlException -> String
xmlBadInput :: XmlException -> Maybe Event
InvalidEndElement :: Name -> XmlException
InvalidEntity :: Text -> XmlException
UnparsedAttributes :: [(Name, [Content])] -> XmlException
instance Typeable XmlException
instance Show XmlException
instance Applicative AttrParser
instance Functor AttrParser
instance Monad AttrParser
instance Exception XmlException

module Text.XML.Enumerator.Document
writeFile :: FilePath -> Document -> IO ()
readFile :: FilePath -> DecodeEntities -> IO (Either SomeException Document)
readFile_ :: FilePath -> DecodeEntities -> IO Document
renderLBS :: Document -> ByteString
parseLBS :: ByteString -> DecodeEntities -> Either SomeException Document
parseLBS_ :: ByteString -> DecodeEntities -> Document
toEvents :: Document -> [Event]
fromEvents :: Monad m => Iteratee Event m Document
renderBuilder :: MonadIO m => Document -> Enumerator Builder m a
renderBytes :: MonadIO m => Document -> Enumerator ByteString m a
renderText :: MonadIO m => Document -> Enumerator Text m a
data InvalidEventStream
InvalidEventStream :: String -> InvalidEventStream
instance Typeable InvalidEventStream
instance Show InvalidEventStream
instance Exception InvalidEventStream