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


-- | Fast combinator parsing for bytestrings and text
--   
--   A fast parser combinator library, aimed particularly at dealing
--   efficiently with network protocols and complicated text/binary file
--   formats.
@package attoparsec
@version 0.11.3.4


-- | A tiny, highly specialized combinator parser for <a>ByteString</a>
--   strings.
--   
--   While the main Attoparsec module generally performs well, this module
--   is particularly fast for simple non-recursive loops that should not
--   normally result in failed parses.
--   
--   <i>Warning</i>: on more complex inputs involving recursion or failure,
--   parsers based on this module may be as much as <i>ten times slower</i>
--   than regular Attoparsec! You should <i>only</i> use this module when
--   you have benchmarks that prove that its use speeds your code up.
module Data.Attoparsec.Zepto

-- | A simple parser.
--   
--   This monad is strict in its state, and the monadic bind operator
--   (<a>&gt;&gt;=</a>) evaluates each result to weak head normal form
--   before passing it along.
data Parser a

-- | Run a parser.
parse :: Parser a -> ByteString -> Either String a

-- | Indicate whether the end of the input has been reached.
atEnd :: Parser Bool

-- | Match a string exactly.
string :: ByteString -> Parser ()

-- | Consume <tt>n</tt> bytes of input.
take :: Int -> Parser ByteString

-- | Consume input while the predicate returns <a>True</a>.
takeWhile :: (Word8 -> Bool) -> Parser ByteString
instance Alternative Parser
instance Monoid (Parser a)
instance Applicative Parser
instance MonadPlus Parser
instance Monad Parser
instance Functor Parser


-- | A simple number type, useful for parsing both exact and inexact
--   quantities without losing much precision.
module Data.Attoparsec.Number

-- | A numeric type that can represent integers accurately, and floating
--   point numbers to the precision of a <a>Double</a>.
data Number
I :: !Integer -> Number
D :: {-# UNPACK #-} !Double -> Number
instance Typeable Number
instance Data Number
instance RealFrac Number
instance Fractional Number
instance Real Number
instance Num Number
instance Ord Number
instance Eq Number
instance NFData Number
instance Show Number


-- | Simple, efficient parser combinators for strings, loosely based on the
--   Parsec library.
module Data.Attoparsec.Types

-- | The core parser type. This is parameterised over the type <tt>t</tt>
--   of string being processed.
--   
--   This type is an instance of the following classes:
--   
--   <ul>
--   <li><a>Monad</a>, where <a>fail</a> throws an exception (i.e. fails)
--   with an error message.</li>
--   <li><a>Functor</a> and <a>Applicative</a>, which follow the usual
--   definitions.</li>
--   <li><a>MonadPlus</a>, where <a>mzero</a> fails (with no error message)
--   and <a>mplus</a> executes the right-hand parser if the left-hand one
--   fails. When the parser on the right executes, the input is reset to
--   the same state as the parser on the left started with. (In other
--   words, Attoparsec is a backtracking parser that supports arbitrary
--   lookahead.)</li>
--   <li><a>Alternative</a>, which follows <a>MonadPlus</a>.</li>
--   </ul>
data Parser t a

-- | The result of a parse. This is parameterised over the type <tt>t</tt>
--   of string that was processed.
--   
--   This type is an instance of <a>Functor</a>, where <a>fmap</a>
--   transforms the value in a <a>Done</a> result.
data IResult t r

-- | The parse failed. The <tt>t</tt> parameter is the input that had not
--   yet been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: t -> [String] -> String -> IResult t r

-- | Supply this continuation with more input so that the parser can
--   resume. To indicate that no more input is available, use an empty
--   string.
Partial :: (t -> IResult t r) -> IResult t r

-- | The parse succeeded. The <tt>t</tt> parameter is the input that had
--   not yet been consumed (if any) when the parse succeeded.
Done :: t -> r -> IResult t r

-- | A common interface for input chunks.
class Monoid c => Chunk c where type family ChunkElem c
nullChunk :: Chunk c => c -> Bool
unsafeChunkHead :: Chunk c => c -> ChunkElem c
unsafeChunkTail :: Chunk c => c -> c
chunkLengthAtLeast :: Chunk c => c -> Int -> Bool
chunkElemToChar :: Chunk c => c -> ChunkElem c -> Char


-- | Useful parser combinators, similar to those provided by Parsec.
module Data.Attoparsec.Combinator

-- | Attempt a parse, and if it fails, rewind the input so that no input
--   appears to have been consumed.
--   
--   This combinator is provided for compatibility with Parsec. Attoparsec
--   parsers always backtrack on failure.
try :: Parser t a -> Parser t a

-- | Name the parser, in case failure occurs.
(<?>) :: Parser t a -> String -> Parser t a

-- | <tt>choice ps</tt> tries to apply the actions in the list <tt>ps</tt>
--   in order, until one of them succeeds. Returns the value of the
--   succeeding action.
choice :: Alternative f => [f a] -> f a

-- | Apply the given action repeatedly, returning every result.
count :: Monad m => Int -> m a -> m [a]

-- | <tt>option x p</tt> tries to apply action <tt>p</tt>. If <tt>p</tt>
--   fails without consuming input, it returns the value <tt>x</tt>,
--   otherwise the value returned by <tt>p</tt>.
--   
--   <pre>
--   priority  = option 0 (digitToInt &lt;$&gt; digit)
--   </pre>
option :: Alternative f => a -> f a -> f a

-- | <tt>many' p</tt> applies the action <tt>p</tt> <i>zero</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>. The value
--   returned by <tt>p</tt> is forced to WHNF.
--   
--   <pre>
--   word  = many' letter
--   </pre>
many' :: MonadPlus m => m a -> m [a]

-- | <tt>many1 p</tt> applies the action <tt>p</tt> <i>one</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>.
--   
--   <pre>
--   word  = many1 letter
--   </pre>
many1 :: Alternative f => f a -> f [a]

-- | <tt>many1' p</tt> applies the action <tt>p</tt> <i>one</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>. The value
--   returned by <tt>p</tt> is forced to WHNF.
--   
--   <pre>
--   word  = many1' letter
--   </pre>
many1' :: MonadPlus m => m a -> m [a]

-- | <tt>manyTill p end</tt> applies action <tt>p</tt> <i>zero</i> or more
--   times until action <tt>end</tt> succeeds, and returns the list of
--   values returned by <tt>p</tt>. This can be used to scan comments:
--   
--   <pre>
--   simpleComment   = string "&lt;!--" *&gt; manyTill anyChar (string "--&gt;")
--   </pre>
--   
--   (Note the overlapping parsers <tt>anyChar</tt> and <tt>string
--   "--&gt;"</tt>. While this will work, it is not very efficient, as it
--   will cause a lot of backtracking.)
manyTill :: Alternative f => f a -> f b -> f [a]

-- | <tt>manyTill' p end</tt> applies action <tt>p</tt> <i>zero</i> or more
--   times until action <tt>end</tt> succeeds, and returns the list of
--   values returned by <tt>p</tt>. This can be used to scan comments:
--   
--   <pre>
--   simpleComment   = string "&lt;!--" *&gt; manyTill' anyChar (string "--&gt;")
--   </pre>
--   
--   (Note the overlapping parsers <tt>anyChar</tt> and <tt>string
--   "--&gt;"</tt>. While this will work, it is not very efficient, as it
--   will cause a lot of backtracking.)
--   
--   The value returned by <tt>p</tt> is forced to WHNF.
manyTill' :: MonadPlus m => m a -> m b -> m [a]

-- | <tt>sepBy p sep</tt> applies <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p  = p `sepBy` (symbol ",")
--   </pre>
sepBy :: Alternative f => f a -> f s -> f [a]

-- | <tt>sepBy' p sep</tt> applies <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>. The value returned by <tt>p</tt> is forced to
--   WHNF.
--   
--   <pre>
--   commaSep p  = p `sepBy'` (symbol ",")
--   </pre>
sepBy' :: MonadPlus m => m a -> m s -> m [a]

-- | <tt>sepBy1 p sep</tt> applies <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p  = p `sepBy1` (symbol ",")
--   </pre>
sepBy1 :: Alternative f => f a -> f s -> f [a]

-- | <tt>sepBy1' p sep</tt> applies <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>. The value returned by <tt>p</tt> is forced to
--   WHNF.
--   
--   <pre>
--   commaSep p  = p `sepBy1'` (symbol ",")
--   </pre>
sepBy1' :: MonadPlus m => m a -> m s -> m [a]

-- | Skip zero or more instances of an action.
skipMany :: Alternative f => f a -> f ()

-- | Skip one or more instances of an action.
skipMany1 :: Alternative f => f a -> f ()

-- | Combine two alternatives.
eitherP :: Alternative f => f a -> f b -> f (Either a b)

-- | The parser <tt>satisfyElem p</tt> succeeds for any chunk element for
--   which the predicate <tt>p</tt> returns <a>True</a>. Returns the
--   element that is actually parsed.
--   
--   <pre>
--   digit = satisfyElem isDigit
--       where isDigit c = c &gt;= '0' &amp;&amp; c &lt;= '9'
--   </pre>
satisfyElem :: Chunk t => (ChunkElem t -> Bool) -> Parser t (ChunkElem t)

-- | Match only if all input has been consumed.
endOfInput :: Chunk t => Parser t ()

-- | Return an indication of whether the end of input has been reached.
atEnd :: Chunk t => Parser t Bool


-- | Simple, efficient combinator parsing for <a>Text</a> strings, loosely
--   based on the Parsec library.
module Data.Attoparsec.Text
type Parser = Parser Text
type Result = IResult Text

-- | The result of a parse. This is parameterised over the type <tt>t</tt>
--   of string that was processed.
--   
--   This type is an instance of <a>Functor</a>, where <a>fmap</a>
--   transforms the value in a <a>Done</a> result.
data IResult t r

-- | The parse failed. The <tt>t</tt> parameter is the input that had not
--   yet been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: t -> [String] -> String -> IResult t r

-- | Supply this continuation with more input so that the parser can
--   resume. To indicate that no more input is available, use an empty
--   string.
Partial :: (t -> IResult t r) -> IResult t r

-- | The parse succeeded. The <tt>t</tt> parameter is the input that had
--   not yet been consumed (if any) when the parse succeeded.
Done :: t -> r -> IResult t r

-- | Compare two <a>IResult</a> values for equality.
--   
--   If both <a>IResult</a>s are <a>Partial</a>, the result will be
--   <a>Nothing</a>, as they are incomplete and hence their equality cannot
--   be known. (This is why there is no <a>Eq</a> instance for
--   <a>IResult</a>.)
compareResults :: (Eq t, Eq r) => IResult t r -> IResult t r -> Maybe Bool

-- | Run a parser.
parse :: Parser a -> Text -> Result a

-- | If a parser has returned a <tt>Partial</tt> result, supply it with
--   more input.
feed :: Result r -> Text -> Result r

-- | Run a parser that cannot be resupplied via a <a>Partial</a> result.
parseOnly :: Parser a -> Text -> Either String a

-- | Run a parser with an initial input string, and a monadic action that
--   can supply more input if needed.
parseWith :: Monad m => (m Text) -> Parser a -> Text -> m (Result a)

-- | Run a parser and print its result to standard output.
parseTest :: Show a => Parser a -> Text -> IO ()

-- | Convert a <a>Result</a> value to a <a>Maybe</a> value. A
--   <tt>Partial</tt> result is treated as failure.
maybeResult :: Result r -> Maybe r

-- | Convert a <a>Result</a> value to an <a>Either</a> value. A
--   <tt>Partial</tt> result is treated as failure.
eitherResult :: Result r -> Either String r

-- | Match a specific character.
char :: Char -> Parser Char

-- | Match any character.
anyChar :: Parser Char

-- | Match any character except the given one.
notChar :: Char -> Parser Char

-- | The parser <tt>satisfy p</tt> succeeds for any character for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the character that
--   is actually parsed.
--   
--   <pre>
--   digit = satisfy isDigit
--       where isDigit c = c &gt;= '0' &amp;&amp; c &lt;= '9'
--   </pre>
satisfy :: (Char -> Bool) -> Parser Char

-- | The parser <tt>satisfyWith f p</tt> transforms a character, and
--   succeeds if the predicate <tt>p</tt> returns <a>True</a> on the
--   transformed value. The parser returns the transformed character that
--   was parsed.
satisfyWith :: (Char -> a) -> (a -> Bool) -> Parser a

-- | The parser <tt>skip p</tt> succeeds for any character for which the
--   predicate <tt>p</tt> returns <a>True</a>.
--   
--   <pre>
--   skipDigit = skip isDigit
--       where isDigit c = c &gt;= '0' &amp;&amp; c &lt;= '9'
--   </pre>
skip :: (Char -> Bool) -> Parser ()

-- | Match any character, to perform lookahead. Returns <a>Nothing</a> if
--   end of input has been reached. Does not consume any input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
peekChar :: Parser (Maybe Char)

-- | Match any character, to perform lookahead. Does not consume any input,
--   but will fail if end of input has been reached.
peekChar' :: Parser Char

-- | Parse a single digit, as recognised by <a>isDigit</a>.
digit :: Parser Char

-- | Parse a letter, as recognised by <a>isAlpha</a>.
letter :: Parser Char

-- | Parse a space character, as recognised by <a>isSpace</a>.
space :: Parser Char

-- | Match any character in a set.
--   
--   <pre>
--   vowel = inClass "aeiou"
--   </pre>
--   
--   Range notation is supported.
--   
--   <pre>
--   halfAlphabet = inClass "a-nA-N"
--   </pre>
--   
--   To add a literal <tt>'-'</tt> to a set, place it at the beginning or
--   end of the string.
inClass :: String -> Char -> Bool

-- | Match any character not in a set.
notInClass :: String -> Char -> Bool

-- | <tt>string s</tt> parses a sequence of characters that identically
--   match <tt>s</tt>. Returns the parsed string (i.e. <tt>s</tt>). This
--   parser consumes no input if it fails (even if a partial match).
--   
--   <i>Note</i>: The behaviour of this parser is different to that of the
--   similarly-named parser in Parsec, as this one is all-or-nothing. To
--   illustrate the difference, the following parser will fail under Parsec
--   given an input of <tt>"for"</tt>:
--   
--   <pre>
--   string "foo" &lt;|&gt; string "for"
--   </pre>
--   
--   The reason for its failure is that the first branch is a partial
--   match, and will consume the letters <tt>'f'</tt> and <tt>'o'</tt>
--   before failing. In Attoparsec, the above parser will <i>succeed</i> on
--   that input, because the failed first branch will consume nothing.
string :: Text -> Parser Text

-- | Satisfy a literal string, ignoring case.
--   
--   Note: this function is currently quite inefficient. Unicode case
--   folding can change the length of a string ("ß" becomes "ss"), which
--   makes a simple, efficient implementation tricky. We have (for now)
--   chosen simplicity over efficiency.

-- | <i>Deprecated: this is very inefficient, use asciiCI instead</i>
stringCI :: Text -> Parser Text

-- | Satisfy a literal string, ignoring case for characters in the ASCII
--   range.
asciiCI :: Text -> Parser Text

-- | Skip over white space.
skipSpace :: Parser ()

-- | Skip past input for as long as the predicate returns <a>True</a>.
skipWhile :: (Char -> Bool) -> Parser ()

-- | A stateful scanner. The predicate consumes and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each character of the input until one
--   returns <a>Nothing</a> or the input ends.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>Nothing</a> on the first character of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
scan :: s -> (s -> Char -> Maybe s) -> Parser Text

-- | Consume exactly <tt>n</tt> characters of input.
take :: Int -> Parser Text

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>False</a> on the first character of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeWhile :: (Char -> Bool) -> Parser Text

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser requires the predicate to succeed on at least one
--   character of input: it will fail if the predicate never returns
--   <a>True</a> or if there is no input left.
takeWhile1 :: (Char -> Bool) -> Parser Text

-- | Consume input as long as the predicate returns <a>False</a> (i.e.
--   until it returns <a>True</a>), and return the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>True</a> on the first character of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeTill :: (Char -> Bool) -> Parser Text

-- | Type-specialized version of <a>*&gt;</a> for <a>Text</a>.
(.*>) :: Text -> Parser a -> Parser a

-- | Type-specialized version of <a>&lt;*</a> for <a>Text</a>.
(<*.) :: Parser a -> Text -> Parser a

-- | Consume all remaining input and return it as a single string.
takeText :: Parser Text

-- | Consume all remaining input and return it as a single string.
takeLazyText :: Parser Text

-- | Match either a single newline character <tt>'\n'</tt>, or a carriage
--   return followed by a newline character <tt>"\r\n"</tt>.
endOfLine :: Parser ()

-- | A predicate that matches either a carriage return <tt>'\r'</tt> or
--   newline <tt>'\n'</tt> character.
isEndOfLine :: Char -> Bool

-- | A predicate that matches either a space <tt>' '</tt> or horizontal tab
--   <tt>'\t'</tt> character.
isHorizontalSpace :: Char -> Bool

-- | Parse and decode an unsigned decimal number.
decimal :: Integral a => Parser a

-- | Parse and decode an unsigned hexadecimal number. The hex digits
--   <tt>'a'</tt> through <tt>'f'</tt> may be upper or lower case.
--   
--   This parser does not accept a leading <tt>"0x"</tt> string.
hexadecimal :: (Integral a, Bits a) => Parser a

-- | Parse a number with an optional leading <tt>'+'</tt> or <tt>'-'</tt>
--   sign character.
signed :: Num a => Parser a -> Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>, but is slightly less accurate.
--   
--   The <a>Double</a> type supports about 16 decimal places of accuracy.
--   For 94.2% of numbers, this function and <a>rational</a> give identical
--   results, but for the remaining 5.8%, this function loses precision
--   around the 15th decimal place. For 0.001% of numbers, this function
--   will lose precision at the 13th or 14th decimal place.
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
double :: Parser Double

-- | A numeric type that can represent integers accurately, and floating
--   point numbers to the precision of a <a>Double</a>.
data Number
I :: !Integer -> Number
D :: {-# UNPACK #-} !Double -> Number

-- | Parse a number, attempting to preserve both speed and precision.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>. On integral inputs, it gives perfectly accurate
--   answers, and on floating point inputs, it is slightly less accurate
--   than <a>rational</a>.
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
number :: Parser Number

-- | Parse a rational number.
--   
--   This parser accepts an optional leading sign character, followed by at
--   least one decimal digit. The syntax similar to that accepted by the
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples with behaviour identical to <a>read</a>, if you feed an empty
--   continuation to the first result:
--   
--   <pre>
--   rational "3"     == Done 3.0 ""
--   rational "3.1"   == Done 3.1 ""
--   rational "3e4"   == Done 30000.0 ""
--   rational "3.1e4" == Done 31000.0, ""
--   </pre>
--   
--   Examples with behaviour identical to <a>read</a>:
--   
--   <pre>
--   rational ".3"    == Fail "input does not start with a digit"
--   rational "e3"    == Fail "input does not start with a digit"
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   rational "3.foo" == Done 3.0 ".foo"
--   rational "3e"    == Done 3.0 "e"
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
rational :: Fractional a => Parser a

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
scientific :: Parser Scientific


-- | Simple, efficient combinator parsing that can consume lazy <a>Text</a>
--   strings, loosely based on the Parsec library.
--   
--   This is essentially the same code as in the <a>Text</a> module, only
--   with a <a>parse</a> function that can consume a lazy <a>Text</a>
--   incrementally, and a <a>Result</a> type that does not allow more input
--   to be fed in. Think of this as suitable for use with a lazily read
--   file, e.g. via <a>readFile</a> or <a>hGetContents</a>.
--   
--   <i>Note:</i> The various parser functions and combinators such as
--   <a>string</a> still expect <i>strict</i> <a>Text</a> parameters, and
--   return strict <a>Text</a> results. Behind the scenes, strict
--   <a>Text</a> values are still used internally to store parser input and
--   manipulate it efficiently.
module Data.Attoparsec.Text.Lazy

-- | The result of a parse.
data Result r

-- | The parse failed. The <tt>ByteString</tt> is the input that had not
--   yet been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: Text -> [String] -> String -> Result r

-- | The parse succeeded. The <tt>ByteString</tt> is the input that had not
--   yet been consumed (if any) when the parse succeeded.
Done :: Text -> r -> Result r

-- | Run a parser and return its result.
parse :: Parser a -> Text -> Result a

-- | Run a parser and print its result to standard output.
parseTest :: Show a => Parser a -> Text -> IO ()

-- | Convert a <a>Result</a> value to a <a>Maybe</a> value.
maybeResult :: Result r -> Maybe r

-- | Convert a <a>Result</a> value to an <a>Either</a> value.
eitherResult :: Result r -> Either String r
instance Functor Result
instance NFData r => NFData (Result r)
instance Show r => Show (Result r)


-- | Simple, efficient combinator parsing for <a>ByteString</a> strings,
--   loosely based on the Parsec library.
module Data.Attoparsec.ByteString
type Parser = Parser ByteString
type Result = IResult ByteString

-- | The result of a parse. This is parameterised over the type <tt>t</tt>
--   of string that was processed.
--   
--   This type is an instance of <a>Functor</a>, where <a>fmap</a>
--   transforms the value in a <a>Done</a> result.
data IResult t r

-- | The parse failed. The <tt>t</tt> parameter is the input that had not
--   yet been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: t -> [String] -> String -> IResult t r

-- | Supply this continuation with more input so that the parser can
--   resume. To indicate that no more input is available, use an empty
--   string.
Partial :: (t -> IResult t r) -> IResult t r

-- | The parse succeeded. The <tt>t</tt> parameter is the input that had
--   not yet been consumed (if any) when the parse succeeded.
Done :: t -> r -> IResult t r

-- | Compare two <a>IResult</a> values for equality.
--   
--   If both <a>IResult</a>s are <a>Partial</a>, the result will be
--   <a>Nothing</a>, as they are incomplete and hence their equality cannot
--   be known. (This is why there is no <a>Eq</a> instance for
--   <a>IResult</a>.)
compareResults :: (Eq t, Eq r) => IResult t r -> IResult t r -> Maybe Bool

-- | Run a parser.
parse :: Parser a -> ByteString -> Result a

-- | If a parser has returned a <a>Partial</a> result, supply it with more
--   input.
feed :: Result r -> ByteString -> Result r

-- | Run a parser that cannot be resupplied via a <a>Partial</a> result.
parseOnly :: Parser a -> ByteString -> Either String a

-- | Run a parser with an initial input string, and a monadic action that
--   can supply more input if needed.
parseWith :: Monad m => (m ByteString) -> Parser a -> ByteString -> m (Result a)

-- | Run a parser and print its result to standard output.
parseTest :: Show a => Parser a -> ByteString -> IO ()

-- | Convert a <a>Result</a> value to a <a>Maybe</a> value. A
--   <a>Partial</a> result is treated as failure.
maybeResult :: Result r -> Maybe r

-- | Convert a <a>Result</a> value to an <a>Either</a> value. A
--   <a>Partial</a> result is treated as failure.
eitherResult :: Result r -> Either String r

-- | Match a specific byte.
word8 :: Word8 -> Parser Word8

-- | Match any byte.
anyWord8 :: Parser Word8

-- | Match any byte except the given one.
notWord8 :: Word8 -> Parser Word8

-- | The parser <tt>satisfy p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the byte that is
--   actually parsed.
--   
--   <pre>
--   digit = satisfy isDigit
--       where isDigit w = w &gt;= 48 &amp;&amp; w &lt;= 57
--   </pre>
satisfy :: (Word8 -> Bool) -> Parser Word8

-- | The parser <tt>satisfyWith f p</tt> transforms a byte, and succeeds if
--   the predicate <tt>p</tt> returns <a>True</a> on the transformed value.
--   The parser returns the transformed byte that was parsed.
satisfyWith :: (Word8 -> a) -> (a -> Bool) -> Parser a

-- | The parser <tt>skip p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>.
--   
--   <pre>
--   skipDigit = skip isDigit
--       where isDigit w = w &gt;= 48 &amp;&amp; w &lt;= 57
--   </pre>
skip :: (Word8 -> Bool) -> Parser ()

-- | Match any byte, to perform lookahead. Returns <a>Nothing</a> if end of
--   input has been reached. Does not consume any input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
peekWord8 :: Parser (Maybe Word8)

-- | Match any byte, to perform lookahead. Does not consume any input, but
--   will fail if end of input has been reached.
peekWord8' :: Parser Word8

-- | Match any byte in a set.
--   
--   <pre>
--   vowel = inClass "aeiou"
--   </pre>
--   
--   Range notation is supported.
--   
--   <pre>
--   halfAlphabet = inClass "a-nA-N"
--   </pre>
--   
--   To add a literal <tt>'-'</tt> to a set, place it at the beginning or
--   end of the string.
inClass :: String -> Word8 -> Bool

-- | Match any byte not in a set.
notInClass :: String -> Word8 -> Bool

-- | <tt>string s</tt> parses a sequence of bytes that identically match
--   <tt>s</tt>. Returns the parsed string (i.e. <tt>s</tt>). This parser
--   consumes no input if it fails (even if a partial match).
--   
--   <i>Note</i>: The behaviour of this parser is different to that of the
--   similarly-named parser in Parsec, as this one is all-or-nothing. To
--   illustrate the difference, the following parser will fail under Parsec
--   given an input of <tt>"for"</tt>:
--   
--   <pre>
--   string "foo" &lt;|&gt; string "for"
--   </pre>
--   
--   The reason for its failure is that the first branch is a partial
--   match, and will consume the letters <tt>'f'</tt> and <tt>'o'</tt>
--   before failing. In Attoparsec, the above parser will <i>succeed</i> on
--   that input, because the failed first branch will consume nothing.
string :: ByteString -> Parser ByteString

-- | Skip past input for as long as the predicate returns <a>True</a>.
skipWhile :: (Word8 -> Bool) -> Parser ()

-- | Consume exactly <tt>n</tt> bytes of input.
take :: Int -> Parser ByteString

-- | A stateful scanner. The predicate consumes and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each byte of the input until one
--   returns <a>Nothing</a> or the input ends.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>Nothing</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
scan :: s -> (s -> Word8 -> Maybe s) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>False</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeWhile :: (Word8 -> Bool) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser requires the predicate to succeed on at least one byte of
--   input: it will fail if the predicate never returns <a>True</a> or if
--   there is no input left.
takeWhile1 :: (Word8 -> Bool) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>False</a> (i.e.
--   until it returns <a>True</a>), and return the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>True</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeTill :: (Word8 -> Bool) -> Parser ByteString

-- | Consume all remaining input and return it as a single string.
takeByteString :: Parser ByteString

-- | Consume all remaining input and return it as a single string.
takeLazyByteString :: Parser ByteString


-- | Simple, efficient, character-oriented combinator parsing for
--   <a>ByteString</a> strings, loosely based on the Parsec library.
module Data.Attoparsec.ByteString.Char8
type Parser = Parser ByteString
type Result = IResult ByteString

-- | The result of a parse. This is parameterised over the type <tt>t</tt>
--   of string that was processed.
--   
--   This type is an instance of <a>Functor</a>, where <a>fmap</a>
--   transforms the value in a <a>Done</a> result.
data IResult t r

-- | The parse failed. The <tt>t</tt> parameter is the input that had not
--   yet been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: t -> [String] -> String -> IResult t r

-- | Supply this continuation with more input so that the parser can
--   resume. To indicate that no more input is available, use an empty
--   string.
Partial :: (t -> IResult t r) -> IResult t r

-- | The parse succeeded. The <tt>t</tt> parameter is the input that had
--   not yet been consumed (if any) when the parse succeeded.
Done :: t -> r -> IResult t r

-- | Compare two <a>IResult</a> values for equality.
--   
--   If both <a>IResult</a>s are <a>Partial</a>, the result will be
--   <a>Nothing</a>, as they are incomplete and hence their equality cannot
--   be known. (This is why there is no <a>Eq</a> instance for
--   <a>IResult</a>.)
compareResults :: (Eq t, Eq r) => IResult t r -> IResult t r -> Maybe Bool

-- | Run a parser.
parse :: Parser a -> ByteString -> Result a

-- | If a parser has returned a <a>Partial</a> result, supply it with more
--   input.
feed :: Result r -> ByteString -> Result r

-- | Run a parser that cannot be resupplied via a <a>Partial</a> result.
parseOnly :: Parser a -> ByteString -> Either String a

-- | Run a parser and print its result to standard output.
parseTest :: Show a => Parser a -> ByteString -> IO ()

-- | Run a parser with an initial input string, and a monadic action that
--   can supply more input if needed.
parseWith :: Monad m => (m ByteString) -> Parser a -> ByteString -> m (Result a)

-- | Convert a <a>Result</a> value to a <a>Maybe</a> value. A
--   <a>Partial</a> result is treated as failure.
maybeResult :: Result r -> Maybe r

-- | Convert a <a>Result</a> value to an <a>Either</a> value. A
--   <a>Partial</a> result is treated as failure.
eitherResult :: Result r -> Either String r

-- | Match a specific character.
char :: Char -> Parser Char

-- | Match a specific character, but return its <a>Word8</a> value.
char8 :: Char -> Parser Word8

-- | Match any character.
anyChar :: Parser Char

-- | Match any character except the given one.
notChar :: Char -> Parser Char

-- | The parser <tt>satisfy p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the byte that is
--   actually parsed.
--   
--   <pre>
--   digit = satisfy isDigit
--       where isDigit c = c &gt;= '0' &amp;&amp; c &lt;= '9'
--   </pre>
satisfy :: (Char -> Bool) -> Parser Char

-- | Match any character, to perform lookahead. Returns <a>Nothing</a> if
--   end of input has been reached. Does not consume any input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
peekChar :: Parser (Maybe Char)

-- | Match any character, to perform lookahead. Does not consume any input,
--   but will fail if end of input has been reached.
peekChar' :: Parser Char

-- | Parse a single digit.
digit :: Parser Char

-- | Match a letter, in the ISO-8859-15 encoding.
letter_iso8859_15 :: Parser Char

-- | Match a letter, in the ASCII encoding.
letter_ascii :: Parser Char

-- | Parse a space character.
--   
--   <i>Note</i>: This parser only gives correct answers for the ASCII
--   encoding. For instance, it does not recognise U+00A0 (non-breaking
--   space) as a space character, even though it is a valid ISO-8859-15
--   byte.
space :: Parser Char

-- | A fast digit predicate.
isDigit :: Char -> Bool

-- | A fast digit predicate.
isDigit_w8 :: Word8 -> Bool

-- | A fast alphabetic predicate for the ISO-8859-15 encoding
--   
--   <i>Note</i>: For all character encodings other than ISO-8859-15, and
--   almost all Unicode code points above U+00A3, this predicate gives
--   <i>wrong answers</i>.
isAlpha_iso8859_15 :: Char -> Bool

-- | A fast alphabetic predicate for the ASCII encoding
--   
--   <i>Note</i>: For all character encodings other than ASCII, and almost
--   all Unicode code points above U+007F, this predicate gives <i>wrong
--   answers</i>.
isAlpha_ascii :: Char -> Bool

-- | Fast predicate for matching ASCII space characters.
--   
--   <i>Note</i>: This predicate only gives correct answers for the ASCII
--   encoding. For instance, it does not recognise U+00A0 (non-breaking
--   space) as a space character, even though it is a valid ISO-8859-15
--   byte. For a Unicode-aware and only slightly slower predicate, use
--   <a>isSpace</a>
isSpace :: Char -> Bool

-- | Fast <a>Word8</a> predicate for matching ASCII space characters.
isSpace_w8 :: Word8 -> Bool

-- | Match any character in a set.
--   
--   <pre>
--   vowel = inClass "aeiou"
--   </pre>
--   
--   Range notation is supported.
--   
--   <pre>
--   halfAlphabet = inClass "a-nA-N"
--   </pre>
--   
--   To add a literal '-' to a set, place it at the beginning or end of the
--   string.
inClass :: String -> Char -> Bool

-- | Match any character not in a set.
notInClass :: String -> Char -> Bool

-- | <tt>string s</tt> parses a sequence of bytes that identically match
--   <tt>s</tt>. Returns the parsed string (i.e. <tt>s</tt>). This parser
--   consumes no input if it fails (even if a partial match).
--   
--   <i>Note</i>: The behaviour of this parser is different to that of the
--   similarly-named parser in Parsec, as this one is all-or-nothing. To
--   illustrate the difference, the following parser will fail under Parsec
--   given an input of <tt>"for"</tt>:
--   
--   <pre>
--   string "foo" &lt;|&gt; string "for"
--   </pre>
--   
--   The reason for its failure is that the first branch is a partial
--   match, and will consume the letters <tt>'f'</tt> and <tt>'o'</tt>
--   before failing. In Attoparsec, the above parser will <i>succeed</i> on
--   that input, because the failed first branch will consume nothing.
string :: ByteString -> Parser ByteString

-- | Satisfy a literal string, ignoring case.
stringCI :: ByteString -> Parser ByteString

-- | Skip over white space.
skipSpace :: Parser ()

-- | Skip past input for as long as the predicate returns <a>True</a>.
skipWhile :: (Char -> Bool) -> Parser ()

-- | Consume exactly <tt>n</tt> bytes of input.
take :: Int -> Parser ByteString

-- | A stateful scanner. The predicate consumes and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each byte of the input until one
--   returns <a>Nothing</a> or the input ends.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>Nothing</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
scan :: s -> (s -> Char -> Maybe s) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>False</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeWhile :: (Char -> Bool) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>True</a>, and return
--   the consumed input.
--   
--   This parser requires the predicate to succeed on at least one byte of
--   input: it will fail if the predicate never returns <a>True</a> or if
--   there is no input left.
takeWhile1 :: (Char -> Bool) -> Parser ByteString

-- | Consume input as long as the predicate returns <a>False</a> (i.e.
--   until it returns <a>True</a>), and return the consumed input.
--   
--   This parser does not fail. It will return an empty string if the
--   predicate returns <a>True</a> on the first byte of input.
--   
--   <i>Note</i>: Because this parser does not fail, do not use it with
--   combinators such as <tt>many</tt>, because such parsers loop until a
--   failure occurs. Careless use will thus result in an infinite loop.
takeTill :: (Char -> Bool) -> Parser ByteString

-- | Type-specialized version of <a>*&gt;</a> for <a>ByteString</a>.
(.*>) :: ByteString -> Parser a -> Parser a

-- | Type-specialized version of <a>&lt;*</a> for <a>ByteString</a>.
(<*.) :: Parser a -> ByteString -> Parser a

-- | Consume all remaining input and return it as a single string.
takeByteString :: Parser ByteString

-- | Consume all remaining input and return it as a single string.
takeLazyByteString :: Parser ByteString

-- | Match either a single newline character <tt>'\n'</tt>, or a carriage
--   return followed by a newline character <tt>"\r\n"</tt>.
endOfLine :: Parser ()

-- | A predicate that matches either a carriage return <tt>'\r'</tt> or
--   newline <tt>'\n'</tt> character.
isEndOfLine :: Word8 -> Bool

-- | A predicate that matches either a space <tt>' '</tt> or horizontal tab
--   <tt>'\t'</tt> character.
isHorizontalSpace :: Word8 -> Bool

-- | Parse and decode an unsigned decimal number.
decimal :: Integral a => Parser a

-- | Parse and decode an unsigned hexadecimal number. The hex digits
--   <tt>'a'</tt> through <tt>'f'</tt> may be upper or lower case.
--   
--   This parser does not accept a leading <tt>"0x"</tt> string.
hexadecimal :: (Integral a, Bits a) => Parser a

-- | Parse a number with an optional leading <tt>'+'</tt> or <tt>'-'</tt>
--   sign character.
signed :: Num a => Parser a -> Parser a

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>, but is slightly less accurate.
--   
--   The <a>Double</a> type supports about 16 decimal places of accuracy.
--   For 94.2% of numbers, this function and <a>rational</a> give identical
--   results, but for the remaining 5.8%, this function loses precision
--   around the 15th decimal place. For 0.001% of numbers, this function
--   will lose precision at the 13th or 14th decimal place.
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
double :: Parser Double

-- | A numeric type that can represent integers accurately, and floating
--   point numbers to the precision of a <a>Double</a>.
data Number
I :: !Integer -> Number
D :: {-# UNPACK #-} !Double -> Number

-- | Parse a number, attempting to preserve both speed and precision.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>. On integral inputs, it gives perfectly accurate
--   answers, and on floating point inputs, it is slightly less accurate
--   than <a>rational</a>.
--   
--   This function does not accept string representations of "NaN" or "
number :: Parser Number

-- | Parse a rational number.
--   
--   This parser accepts an optional leading sign character, followed by at
--   least one decimal digit. The syntax similar to that accepted by the
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples with behaviour identical to <a>read</a>, if you feed an empty
--   continuation to the first result:
--   
--   <pre>
--   rational "3"     == Done 3.0 ""
--   rational "3.1"   == Done 3.1 ""
--   rational "3e4"   == Done 30000.0 ""
--   rational "3.1e4" == Done 31000.0, ""
--   </pre>
--   
--   Examples with behaviour identical to <a>read</a>:
--   
--   <pre>
--   rational ".3"    == Fail "input does not start with a digit"
--   rational "e3"    == Fail "input does not start with a digit"
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   rational "3.foo" == Done 3.0 ".foo"
--   rational "3e"    == Done 3.0 "e"
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
rational :: Fractional a => Parser a

-- | Parse a scientific number.
--   
--   The syntax accepted by this parser is the same as for <a>rational</a>.
scientific :: Parser Scientific
instance a ~ ByteString => IsString (Parser a)


-- | Simple, efficient, character-oriented combinator parsing for
--   <tt>ByteString</tt> strings, loosely based on the Parsec library.
module Data.Attoparsec.Char8


-- | Simple, efficient combinator parsing that can consume lazy
--   <a>ByteString</a> strings, loosely based on the Parsec library.
--   
--   This is essentially the same code as in the <a>Attoparsec</a> module,
--   only with a <a>parse</a> function that can consume a lazy
--   <a>ByteString</a> incrementally, and a <a>Result</a> type that does
--   not allow more input to be fed in. Think of this as suitable for use
--   with a lazily read file, e.g. via <a>readFile</a> or
--   <a>hGetContents</a>.
--   
--   <i>Note:</i> The various parser functions and combinators such as
--   <a>string</a> still expect <i>strict</i> <a>ByteString</a> parameters,
--   and return strict <a>ByteString</a> results. Behind the scenes, strict
--   <a>ByteString</a> values are still used internally to store parser
--   input and manipulate it efficiently.
module Data.Attoparsec.ByteString.Lazy

-- | The result of a parse.
data Result r

-- | The parse failed. The <a>ByteString</a> is the input that had not yet
--   been consumed when the failure occurred. The
--   <tt>[</tt><a>String</a><tt>]</tt> is a list of contexts in which the
--   error occurred. The <a>String</a> is the message describing the error,
--   if any.
Fail :: ByteString -> [String] -> String -> Result r

-- | The parse succeeded. The <a>ByteString</a> is the input that had not
--   yet been consumed (if any) when the parse succeeded.
Done :: ByteString -> r -> Result r

-- | Run a parser and return its result.
parse :: Parser a -> ByteString -> Result a

-- | Run a parser and print its result to standard output.
parseTest :: Show a => Parser a -> ByteString -> IO ()

-- | Convert a <a>Result</a> value to a <a>Maybe</a> value.
maybeResult :: Result r -> Maybe r

-- | Convert a <a>Result</a> value to an <a>Either</a> value.
eitherResult :: Result r -> Either String r
instance Functor Result
instance Show r => Show (Result r)
instance NFData r => NFData (Result r)


-- | Simple, efficient combinator parsing for lazy <tt>ByteString</tt>
--   strings, loosely based on the Parsec library.
--   
--   This is essentially the same code as in the <a>Attoparsec</a> module,
--   only with a <a>parse</a> function that can consume a lazy
--   <tt>ByteString</tt> incrementally, and a <a>Result</a> type that does
--   not allow more input to be fed in. Think of this as suitable for use
--   with a lazily read file, e.g. via <a>readFile</a> or
--   <a>hGetContents</a>.
--   
--   Behind the scenes, strict <a>ByteString</a> values are still used
--   internally to store parser input and manipulate it efficiently.
--   High-performance parsers such as <a>string</a> still expect strict
--   <a>ByteString</a> parameters.
module Data.Attoparsec.Lazy


-- | Simple, efficient combinator parsing for <tt>ByteString</tt> strings,
--   loosely based on the Parsec library.
module Data.Attoparsec
