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


-- | Extends binary with parsec/attoparsec style parsing combinators.
--   
--   Extends binary with parsec/attoparsec style parsing combinators.
@package binary-parsers
@version 0.2.3.0


-- | Simple, efficient combinator parsing for <a>ByteString</a> strings.
module Data.Binary.Parser.Word8

-- | Match any byte, to perform lookahead. Returns <a>Nothing</a> if end of
--   input has been reached. Does not consume any input.
peekMaybe :: Get (Maybe Word8)

-- | Match any byte, to perform lookahead. Does not consume any input, but
--   will fail if end of input has been reached.
peek :: Get 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) -> Get 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) -> Get a

-- | Match a specific byte.
word8 :: Word8 -> Get ()

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

-- | The parser <tt>skipWord8 p</tt> succeeds for any byte for which the
--   predicate <tt>p</tt> returns <a>True</a>.
skipWord8 :: (Word8 -> Bool) -> Get ()

-- | This is a faster version of <a>skip</a> for small N (smaller than
--   chunk size).
skipN :: Int -> Get ()

-- | Consume input as long as the predicate returns <a>False</a> or reach
--   the end of input, and return the consumed input.
takeTill :: (Word8 -> Bool) -> Get ByteString

-- | Consume input as long as the predicate returns <a>True</a> or reach
--   the end of input, and return the consumed input.
takeWhile :: (Word8 -> Bool) -> Get ByteString

-- | Similar to <a>takeWhile</a>, but requires the predicate to succeed on
--   at least one byte of input: it will fail if the predicate never
--   returns <a>True</a> or reach the end of input
takeWhile1 :: (Word8 -> Bool) -> Get ByteString

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

-- | Skip over white space using <a>isSpace</a>.
skipSpaces :: Get ()

-- | <tt>string s</tt> parses a sequence of bytes that identically match
--   <tt>s</tt>.
string :: ByteString -> Get ()

-- | 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.
scan :: s -> (s -> Word8 -> Maybe s) -> Get ByteString

-- | Similar to <a>scan</a>, but working on <a>ByteString</a> chunks, The
--   predicate consumes a <a>ByteString</a> chunk and transforms a state
--   argument, and each transformed state is passed to successive
--   invocations of the predicate on each chunk of the input until one
--   chunk got splited to <tt>Right (ByteString, ByteString)</tt> or the
--   input ends.
scanChunks :: s -> Consume s -> Get ByteString

-- | Fast <a>Word8</a> predicate for matching ASCII space characters
--   
--   <pre>
--   isSpace w = w == 32 || w - 9 &lt;= 4
--   </pre>
isSpace :: Word8 -> Bool

-- | Decimal digit predicate.
isDigit :: Word8 -> Bool

-- | Hex digit predicate.
isHexDigit :: Word8 -> Bool

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

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

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


-- | Simple, efficient combinator parsing for numeric values.
module Data.Binary.Parser.Numeric

-- | 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) => Get a

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

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

-- | Parse a rational number.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
--   
--   <i>Note</i>: this parser is not safe for use with inputs from
--   untrusted sources. An input with a suitably large exponent such as
--   <tt>"1e1000000000"</tt> will cause a huge <a>Integer</a> to be
--   allocated, resulting in what is effectively a denial-of-service
--   attack.
--   
--   In most cases, it is better to use <a>double</a> or <a>scientific</a>
--   instead.
rational :: Fractional a => Get a

-- | Parse a rational number and round to <a>Double</a>.
--   
--   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>:
--   
--   <pre>
--   parseOnly double "3"     == Right ("",1,3.0)
--   parseOnly double "3.1"   == Right ("",3,3.1)
--   parseOnly double "3e4"   == Right ("",3,30000.0)
--   parseOnly double "3.1e4" == Right ("",5,31000.0)
--   </pre>
--   
--   <pre>
--   parseOnly double ".3"    == Left (".3",0,"takeWhile1")
--   parseOnly double "e3"    == Left ("e3",0,"takeWhile1")
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   parseOnly double "3.foo" == Right (".foo",1,3.0)
--   parseOnly double "3e"    == Right ("e",1,3.0)
--   </pre>
--   
--   This function does not accept string representations of "NaN" or
--   "Infinity".
double :: Get Double

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

-- | Parse a scientific number and convert to result using a user supply
--   function.
--   
--   The syntax accepted by this parser is the same as for <a>double</a>.
scientifically :: (Scientific -> a) -> Get a


-- | This module is intended for parsing text that is represented using an
--   8-bit character set, e.g. ASCII or ISO-8859-15. It <i>does not</i>
--   make any attempt to deal with character encodings, multibyte
--   characters, or wide characters. In particular, all attempts to use
--   characters above code point U+00FF will give wrong answers.
--   
--   Code points below U+0100 are simply translated to and from their
--   numeric values, so e.g. the code point U+00A4 becomes the byte
--   <tt>0xA4</tt> (which is the Euro symbol in ISO-8859-15, but the
--   generic currency sign in ISO-8859-1). Haskell <a>Char</a> values above
--   U+00FF are truncated, so e.g. U+1D6B7 is truncated to the byte
--   <tt>0xB7</tt>.
module Data.Binary.Parser.Char8

-- | Match any char, to perform lookahead. Returns <a>Nothing</a> if end of
--   input has been reached. Does not consume any input.
peekMaybe :: Get (Maybe Char)

-- | Match any char, to perform lookahead. Does not consume any input, but
--   will fail if end of input has been reached.
peek :: Get Char

-- | The parser <tt>satisfy p</tt> succeeds for any char for which the
--   predicate <tt>p</tt> returns <a>True</a>. Returns the char that is
--   actually parsed.
satisfy :: (Char -> Bool) -> Get Char

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

-- | Match a specific character.
char :: Char -> Get ()

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

-- | The parser <tt>skipChar p</tt> succeeds for any char for which the
--   predicate <tt>p</tt> returns <a>True</a>.
skipChar :: (Char -> Bool) -> Get ()

-- | Consume input as long as the predicate returns <a>False</a> or reach
--   the end of input, and return the consumed input.
takeTill :: (Char -> Bool) -> Get ByteString

-- | Consume input as long as the predicate returns <a>True</a> or reach
--   the end of input, and return the consumed input.
takeWhile :: (Char -> Bool) -> Get ByteString
takeWhile1 :: (Char -> Bool) -> Get ByteString

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

-- | Satisfy a literal string but ignoring case.
stringCI :: ByteString -> Get ByteString

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

-- | Decimal digit predicate.
isDigit :: Char -> Bool

-- | Hex digit predicate.
isHexDigit :: Char -> Bool

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

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


-- | This library provide parsec/attoparsec style parsing combinators for
--   <a>binary</a> package. By default, this module export combinators in
--   <a>Data.Binary.Get</a>, <a>Data.Binary.Parser.Word8</a> and
--   <a>Data.Binary.Parser.Numeric</a>, for additional ASCII char parser,
--   please check <a>Data.Binary.Parser.Char8</a> module.
--   
--   The behaviour of parsers here 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 binary-parsers, the above parser will
--   <i>succeed</i> on that input, because the failed first branch will
--   consume nothing.
--   
--   There're some redundant combinators get removed, for example:
--   
--   <pre>
--   choice == asum
--   count == replicateM
--   atEnd == isEmpty
--   take == getByteString
--   many1 == some
--   </pre>
--   
--   For fast byte set operations, please use <a>charset</a> package.
--   
--   It's recommanded to use <a>parseOnly</a>, <a>parseDetail</a>...
--   functions to run your parsers since these functions are faster than
--   binary's counter part by avoiding a small constant overhead. Check
--   <a>parse</a> for detail.
--   
--   <h1>A few words on performance and backtracking</h1>
--   
--   There's a common belief that parsers which support backtracking are
--   slow, but it's not neccessarily true in binary, because binary doesn't
--   do book keeping if you doesn't use <a>&lt;|&gt;</a>, <a>lookAhead</a>
--   or their friends. Combinators in this library like <a>peek</a>,
--   <a>string</a>... also try to avoid backtracking so it's faster to use
--   them rather than do backtracking yourself, for example, <a>peek</a> is
--   faster than <tt><a>lookAhead</a> <a>getWord8</a></tt>. In practice,
--   protocols are often designed to avoid backtracking. For example, if
--   you have following parser:
--   
--   <pre>
--   branch1 &lt;|&gt; branch2 &lt;|&gt; (skipN 1 &gt;&gt; branch3)
--   </pre>
--   
--   And if you can select the right branch just by looking ahead one byte,
--   then you can rewrite it to:
--   
--   <pre>
--   w &lt;- peek
--   if  | w == b1 -&gt; branch1
--       | w == b2 -&gt; branch2
--       | w == b3 -&gt; skipN 1 &gt;&gt; branch3
--   </pre>
--   
--   Binary performs as fast as a non-backtracking parser as long as you
--   construct your parser without using backtracking. And sometime
--   backtracking is indeed neccessary, for example <a>scientifically</a>
--   is almost impossible to implement correctly if you don't do
--   backtracking.
module Data.Binary.Parser

-- | Alias to <a>Get</a> for attoparsec compatibility.
type Parser a = Get a

-- | Run a parser on <a>ByteString</a>.
--   
--   This function does not force a parser to consume all of its input.
--   Instead, any residual input will be discarded. To force a parser to
--   consume all of its input, use something like this:
--   
--   <pre>
--   parseOnly (myParser &lt;* endOfInput)
--   </pre>
parseOnly :: Get a -> ByteString -> Either String a

-- | Similar to <a>parseOnly</a>, but run a parser on lazy
--   <a>ByteString</a>.
parseLazy :: Get a -> ByteString -> Either String a

-- | Run a parser on <a>ByteString</a>.
--   
--   This function return full parsing results: the rest of input, stop
--   offest and fail message or parsing result.
--   
--   <i>Since: 0.2.1.0</i>
parseDetail :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | Similar to <a>parseDetail</a>, but run a parser on lazy
--   <a>ByteString</a>.
--   
--   <i>Since: 0.2.1.0</i>
parseDetailLazy :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | Run a <a>Get</a> monad. See <a>Decoder</a> for what to do next, like
--   providing input, handling decoding errors and to get the output value.
--   
--   This's faster than <a>runGetIncremental</a> becuase it provides an
--   initial chunk rather than feeding <a>empty</a> and waiting for chunks,
--   this overhead is noticeable when you're running small getters over
--   short <tt>ByteString</tt> s.
--   
--   <i>Since: 0.2.1.0</i>
parse :: Get a -> ByteString -> Decoder a

-- | Convert a <a>Decoder</a> value to a <a>Maybe</a> value. A
--   <a>Partial</a> result is treated as failure.
--   
--   <i>Since: 0.2.3.0</i>
maybeDecoder :: Decoder r -> Maybe r

-- | Convert a <a>Decoder</a> value to an <a>Either</a> value. A
--   <a>Partial</a> result is treated as failure.
--   
--   <i>Since: 0.2.3.0</i>
eitherDecoder :: Decoder r -> Either String r

-- | Name the parser, in case failure occurs.
(<?>) :: Get a -> String -> Get a
infix 0 <?>

-- | Match only if all input has been consumed.
endOfInput :: Get ()

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

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

-- | Return both the result of a parse and the portion of the input that
--   was consumed while it was being parsed.
match :: Get a -> Get (ByteString, 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>some' 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  = some' letter
--   </pre>
some' :: (MonadPlus m) => m a -> 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` (char ',')
--   </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'` (char ',')
--   </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` (char ',')
--   </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'` (char ',')
--   </pre>
sepBy1' :: (MonadPlus m) => m a -> m s -> 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]

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