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


-- | Nonresumable byte parser
--   
--   Parse bytes as fast as possible. This is a nonresumable parser that
--   aggresively uses <a>UnboxedSums</a> to avoid performing any
--   allocations.
@package bytesmith
@version 0.2.0.1


-- | Everything in this module is unsafe and can lead to nondeterministic
--   output or segfaults if used incorrectly.
module Data.Bytes.Parser.Unsafe

-- | Get the current offset into the chunk. Using this makes it possible to
--   observe the internal difference between <a>Bytes</a> that refer to
--   equivalent slices. Be careful.
cursor :: Parser e s Int

-- | Return the byte array being parsed. This includes bytes that preceed
--   the current offset and may include bytes that go beyond the length.
--   This is somewhat dangerous, so only use this is you know what you're
--   doing.
expose :: Parser e s ByteArray

-- | Move the cursor back by <tt>n</tt> bytes. Precondition: you must have
--   previously consumed at least <tt>n</tt> bytes.
unconsume :: Int -> Parser e s ()

-- | Set the position to the given index. Precondition: the index must be
--   valid. It should be the result of an earlier call to <a>cursor</a>.
jump :: Int -> Parser e s ()


-- | Parse non-resumable sequence of bytes. To parse a byte sequence as
--   text, use the <tt>Ascii</tt>, <tt>Latin</tt>, and <tt>Utf8</tt>
--   modules instead. Functions for parsing decimal-encoded numbers are
--   found in those modules.
module Data.Bytes.Parser

-- | A non-resumable parser.
newtype Parser :: forall (r :: RuntimeRep). Type -> Type -> TYPE r -> Type
[Parser] :: forall (r :: RuntimeRep) (e :: Type) (s :: Type) (a :: TYPE r). {runParser :: (# ByteArray#, Int#, Int# #) -> ST# s (Result# e a)} -> Parser e s a

-- | The result of running a parser.
data Result e a

-- | An error message indicating what went wrong.
Failure :: e -> Result e a

-- | The parsed value and the number of bytes remaining in parsed slice.
Success :: !a -> !Int -> Result e a

-- | Variant of <a>parseBytes</a> that accepts an unsliced
--   <a>ByteArray</a>.
parseByteArray :: (forall s. Parser e s a) -> ByteArray -> Result e a

-- | Parse a slice of a byte array. This can succeed even if the entire
--   slice was not consumed by the parser.
parseBytes :: forall e a. (forall s. Parser e s a) -> Bytes -> Result e a

-- | Variant of <a>parseBytes</a> that allows the parser to be run as part
--   of an existing effectful context.
parseBytesST :: Parser e s a -> Bytes -> ST s (Result e a)

-- | Consumes and returns the next byte in the input. Fails if no
--   characters are left.
any :: e -> Parser e s Word8

-- | Take the given number of bytes. Fails if there is not enough remaining
--   input.
take :: e -> Int -> Parser e s Bytes

-- | Take while the predicate is matched. This is always inlined.
takeWhile :: (Word8 -> Bool) -> Parser e s Bytes

-- | Skip while the predicate is matched. This is always inlined.
skipWhile :: (Word8 -> Bool) -> Parser e s ()
byteArray :: e -> ByteArray -> Parser e s ()
bytes :: e -> Bytes -> Parser e s ()

-- | Fails if there is still more input remaining.
endOfInput :: e -> Parser e s ()

-- | Returns true if there are no more bytes in the input. Returns false
--   otherwise. Always succeeds.
isEndOfInput :: Parser e s Bool

-- | Consume all remaining bytes in the input.
remaining :: Parser e s Bytes

-- | Fail with the provided error message.
fail :: e -> Parser e s a

-- | There is a law-abiding instance of <tt>Alternative</tt> for
--   <a>Parser</a>. However, it is not terribly useful since error messages
--   seldom have a <a>Monoid</a> instance. This function is a variant of
--   <tt>&lt;|&gt;</tt> that is right-biased in its treatment of error
--   messages. Consequently, <tt>orElse</tt> lacks an identity. See
--   <a>attoparsec issue #122</a> for more discussion of this topic.
orElse :: Parser x s a -> Parser e s a -> Parser e s a
infixl 3 `orElse`

-- | Annotate a parser. If the parser fails, the error will be returned.
annotate :: Parser x s a -> e -> Parser e s a

-- | Infix version of <a>annotate</a>.
(<?>) :: Parser x s a -> e -> Parser e s a
infix 0 <?>

-- | Replicate a parser <tt>n</tt> times, writing the results into an array
--   of length <tt>n</tt>. For <tt>Array</tt> and <tt>SmallArray</tt>, this
--   is lazy in the elements, so be sure the they result of the parser is
--   evaluated appropriately to avoid unwanted thunks.
replicate :: forall arr e s a. (Contiguous arr, Element arr a) => Int -> Parser e s a -> Parser e s (arr a)

-- | Run a parser in a delimited context, failing if the requested number
--   of bytes are not available or if the delimited parser does not consume
--   all input. This combinator can be understood as a composition of
--   <a>take</a>, <a>effect</a>, <a>parseBytesST</a>, and
--   <a>endOfInput</a>. It is provided as a single combinator because for
--   convenience and because it is easy make mistakes when manually
--   assembling the aforementioned parsers. The pattern of prefixing an
--   encoding with its length is common. This is discussed more in
--   <a>attoparsec issue #129</a>.
--   
--   <pre>
--   delimit e1 e2 n remaining === take e1 n
--   </pre>
delimit :: e -> e -> Int -> Parser e s a -> Parser e s a

-- | Augment a parser with the number of bytes that were consume while it
--   executed.
measure :: Parser e s a -> Parser e s (Int, a)

-- | Lift an effectful computation into a parser.
effect :: ST s a -> Parser e s a

-- | Convert a <a>Word#</a> parser to a <a>Word32</a> parser. Precondition:
--   the argument parser only returns words less than 4294967296.
boxWord32 :: Parser e s Word# -> Parser e s Word32

-- | Convert a <tt>(, Int)</tt> parser to a <tt>(Int,Int)</tt> parser.
boxIntPair :: Parser e s (# Int#, Int# #) -> Parser e s (Int, Int)

-- | Convert a <a>Word32</a> parser to a <a>Word#</a> parser.
unboxWord32 :: Parser e s Word32 -> Parser e s Word#

-- | Convert a <tt>(Int,Int)</tt> parser to a <tt>(, Int)</tt> parser.
unboxIntPair :: Parser e s (Int, Int) -> Parser e s (# Int#, Int# #)
bindFromCharToLifted :: Parser s e Char# -> (Char# -> Parser s e a) -> Parser s e a
bindFromLiftedToIntPair :: Parser s e a -> (a -> Parser s e (# Int#, Int# #)) -> Parser s e (# Int#, Int# #)
bindFromLiftedToInt :: Parser s e a -> (a -> Parser s e Int#) -> Parser s e Int#
bindFromIntToIntPair :: Parser s e Int# -> (Int# -> Parser s e (# Int#, Int# #)) -> Parser s e (# Int#, Int# #)
bindFromCharToIntPair :: Parser s e Char# -> (Char# -> Parser s e (# Int#, Int# #)) -> Parser s e (# Int#, Int# #)
bindFromMaybeCharToIntPair :: Parser s e (# (# #) | Char# #) -> ((# (# #) | Char# #) -> Parser s e (# Int#, Int# #)) -> Parser s e (# Int#, Int# #)
bindFromMaybeCharToLifted :: Parser s e (# (# #) | Char# #) -> ((# (# #) | Char# #) -> Parser s e a) -> Parser s e a
pureIntPair :: (# Int#, Int# #) -> Parser s e (# Int#, Int# #)
failIntPair :: e -> Parser e s (# Int#, Int# #)
instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Data.Bytes.Parser.Result e a)
instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Bytes.Parser.Result e a)


-- | Parse input as though it were text encoded by ISO 8859-1 (Latin-1).
--   All byte sequences are valid text under ISO 8859-1.
module Data.Bytes.Parser.Latin

-- | Consume the next character, failing if it does not match the expected
--   value or if there is no more input.
char :: e -> Char -> Parser e s ()

-- | Consume the next two characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char2 e a b === char e a *&gt; char e b
--   </pre>
char2 :: e -> Char -> Char -> Parser e s ()

-- | Consume the three characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char3 e a b c === char e a *&gt; char e b *&gt; char e c
--   </pre>
char3 :: e -> Char -> Char -> Char -> Parser e s ()

-- | Consume the four characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char4 e a b c d === char e a *&gt; char e b *&gt; char e c *&gt; char e d
--   </pre>
char4 :: e -> Char -> Char -> Char -> Char -> Parser e s ()

-- | Runs the predicate on the next character in the input. If the
--   predicate is matched, this consumes the character. Otherwise, the
--   character is not consumed. This returns <tt>False</tt> if the end of
--   the input has been reached. This never fails.
trySatisfy :: (Char -> Bool) -> Parser e s Bool

-- | Runs the function on the next character in the input. If the function
--   returns <tt>Just</tt>, this consumes the character and then runs the
--   parser on the remaining input. If the function returns
--   <tt>Nothing</tt>, this does not consume the tested character, and it
--   runs the default parser on the input (which includes the tested
--   character). If there is no input remaining, this also runs the default
--   parser. This combinator never fails.
trySatisfyThen :: forall (r :: RuntimeRep) (e :: Type) (s :: Type) (a :: TYPE r). Parser e s a -> (Char -> Maybe (Parser e s a)) -> Parser e s a

-- | Consumes and returns the next character in the input.
any :: e -> Parser e s Char

-- | Consume a character from the input or return Nothing if end of the
--   stream has been reached. Since ISO 8859-1 maps every bytes to a
--   character, this parser never fails.
opt :: Parser e s (Maybe Char)

-- | Variant of <tt>opt</tt> with unboxed result.
opt# :: Parser e s (# (# #) | Char# #)

-- | Skip the characters <tt>0-9</tt> until a non-digit is encountered.
--   This parser does not fail.
skipDigits :: Parser e s ()

-- | Variant of <a>skipDigits</a> that requires at least one digit to be
--   present.
skipDigits1 :: e -> Parser e s ()

-- | Skip the character any number of times. This succeeds even if the
--   character was not present.
skipChar :: Char -> Parser e s ()

-- | Skip the character any number of times. It must occur at least once or
--   else this will fail.
skipChar1 :: e -> Char -> Parser e s ()

-- | Skip all characters until the character from the is encountered and
--   then consume the matching character as well. Visually,
--   <tt>skipTrailedBy 'C'</tt> advances the cursor like this:
--   
--   <pre>
--    A Z B Y C X C W
--   |-&gt;-&gt;-&gt;-&gt;-|
--   </pre>
skipTrailedBy :: e -> Char -> Parser e s ()

-- | Parse a decimal-encoded number. If the number is too large to be
--   represented by a machine word, this fails with the provided error
--   message. This accepts any number of leading zeroes.
decWord :: e -> Parser e s Word

-- | Parse a decimal-encoded 8-bit word. If the number is larger than 255,
--   this parser fails.
decWord8 :: e -> Parser e s Word8

-- | Parse a decimal-encoded 16-bit word. If the number is larger than
--   65535, this parser fails.
decWord16 :: e -> Parser e s Word16

-- | Parse a decimal-encoded 32-bit word. If the number is larger than
--   4294967295, this parser fails.
decWord32 :: e -> Parser e s Word32

-- | Parse a decimal-encoded number. If the number is too large to be
--   represented by a machine integer, this fails with the provided error
--   message. This rejects input with that is preceeded by plus or minus.
--   Consequently, it does not parse negative numbers. Use
--   <a>decStandardInt</a> or <a>decSignedInt</a> for that purpose. On a
--   64-bit platform <a>decWord</a> will successfully parse
--   9223372036854775808 (i.e. <tt>2 ^ 63</tt>), but <a>decUnsignedInt</a>
--   will fail. This parser allows leading zeroes.
decUnsignedInt :: e -> Parser e s Int

-- | Variant of <a>decUnsignedInt</a> with an unboxed result.
decUnsignedInt# :: e -> Parser e s Int#

-- | Parse a decimal-encoded number. If the number is too large to be
--   represented by a machine integer, this fails with the provided error
--   message. This allows the number to optionally be prefixed by plus or
--   minus. If the sign prefix is not present, the number is interpreted as
--   positive. This allows leading zeroes.
decSignedInt :: e -> Parser e s Int

-- | Parse a decimal-encoded number. If the number is too large to be
--   represented by a machine integer, this fails with the provided error
--   message. This allows the number to optionally be prefixed by minus. If
--   the minus prefix is not present, the number is interpreted as
--   positive. The disallows a leading plus sign. For example,
--   <a>decStandardInt</a> rejects <tt>+42</tt>, but <a>decSignedInt</a>
--   allows it.
decStandardInt :: e -> Parser e s Int

-- | Variant of <a>decUnsignedInt</a> that lets the caller supply a leading
--   digit. This is useful when parsing formats like JSON where integers
--   with leading zeroes are considered invalid. The calling context must
--   consume the first digit before calling this parser. Results are always
--   positive numbers.
decTrailingInt :: e -> Int -> Parser e s Int
decTrailingInt# :: e -> Int# -> Parser e s Int#

-- | Parse a decimal-encoded integer of arbitrary size. This accepts input
--   that begins with a plus or minus sign. Input without a sign prefix is
--   interpreted as positive.
decSignedInteger :: e -> Parser e s Integer

-- | Parse a decimal-encoded positive integer of arbitrary size. This
--   rejects input that begins with a plus or minus sign.
decUnsignedInteger :: e -> Parser e s Integer

-- | Variant of <a>decUnsignedInteger</a> that lets the caller supply a
--   leading digit. This is useful when parsing formats like JSON where
--   integers with leading zeroes are considered invalid. The calling
--   context must consume the first digit before calling this parser.
--   Results are always positive numbers.
decTrailingInteger :: Int -> Parser e s Integer

-- | Parse exactly four ASCII-encoded characters, interpretting them as the
--   hexadecimal encoding of a 32-bit number. Note that this rejects a
--   sequence such as <tt>5A9</tt>, requiring <tt>05A9</tt> instead. This
--   is insensitive to case. This is particularly useful when parsing
--   escape sequences in C or JSON, which allow encoding characters in the
--   Basic Multilingual Plane as <tt>\uhhhh</tt>.
hexWord16 :: e -> Parser e s Word16


-- | Parse input as ASCII-encoded text. Some parsers in this module, like
--   <a>any</a> and <a>peek</a>, fail if they encounter a byte above
--   <tt>0x7F</tt>. Others, like numeric parsers and skipping parsers,
--   leave the cursor at the position of the offending byte without
--   failing.
module Data.Bytes.Parser.Ascii

-- | Consume the next character, failing if it does not match the expected
--   value or if there is no more input.
char :: e -> Char -> Parser e s ()

-- | Consume the next two characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char2 e a b === char e a *&gt; char e b
--   </pre>
char2 :: e -> Char -> Char -> Parser e s ()

-- | Consume the three characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char3 e a b c === char e a *&gt; char e b *&gt; char e c
--   </pre>
char3 :: e -> Char -> Char -> Char -> Parser e s ()

-- | Consume the four characters, failing if they do not match they
--   expected values.
--   
--   <pre>
--   char4 e a b c d === char e a *&gt; char e b *&gt; char e c *&gt; char e d
--   </pre>
char4 :: e -> Char -> Char -> Char -> Char -> Parser e s ()

-- | Consumes and returns the next character in the input.
any :: e -> Parser e s Char

-- | Variant of <a>any</a> with unboxed result.
any# :: e -> Parser e s Char#

-- | Examine the next byte without consuming it, interpret it as an
--   ASCII-encoded character. This fails if the byte is above <tt>0x7F</tt>
--   or if the end of input has been reached.
peek :: e -> Parser e s Char

-- | Consume the next byte, interpreting it as an ASCII-encoded character.
--   Fails if the byte is above <tt>0x7F</tt>. Returns <tt>Nothing</tt> if
--   the end of the input has been reached.
opt :: e -> Parser e s (Maybe Char)

-- | Consume input through the next occurrence of the target character and
--   return the consumed input, excluding the target character, as a
--   <a>ShortText</a>. This fails if it encounters any bytes above
--   <tt>0x7F</tt>.
shortTrailedBy :: e -> Char -> Parser e s ShortText

-- | Skip the characters <tt>0-9</tt> until a non-digit is encountered.
--   This parser does not fail.
skipDigits :: Parser e s ()

-- | Variant of <a>skipDigits</a> that requires at least one digit to be
--   present.
skipDigits1 :: e -> Parser e s ()

-- | Skip the character any number of times. This succeeds even if the
--   character was not present.
skipChar :: Char -> Parser e s ()

-- | Skip the character any number of times. It must occur at least once or
--   else this will fail.
skipChar1 :: e -> Char -> Parser e s ()

-- | Skip uppercase and lowercase letters until a non-alpha character is
--   encountered.
skipAlpha :: Parser e s ()

-- | Skip uppercase and lowercase letters until a non-alpha character is
--   encountered.
skipAlpha1 :: e -> Parser e s ()

-- | Consume input until the trailer is found. Then, consume the trailer as
--   well. This fails if the trailer is not found or if any non-ASCII
--   characters are encountered.
skipTrailedBy :: e -> Char -> Parser e s ()

-- | Parse a decimal-encoded number. If the number is too large to be
--   represented by a machine word, this fails with the provided error
--   message. This accepts any number of leading zeroes.
decWord :: e -> Parser e s Word

-- | Parse a decimal-encoded 8-bit word. If the number is larger than 255,
--   this parser fails.
decWord8 :: e -> Parser e s Word8

-- | Parse a decimal-encoded 16-bit word. If the number is larger than
--   65535, this parser fails.
decWord16 :: e -> Parser e s Word16

-- | Parse a decimal-encoded 32-bit word. If the number is larger than
--   4294967295, this parser fails.
decWord32 :: e -> Parser e s Word32


-- | Big-endian fixed-width numbers.
module Data.Bytes.Parser.BigEndian

-- | Unsigned 8-bit word.
word8 :: e -> Parser e s Word8

-- | Unsigned 16-bit word.
word16 :: e -> Parser e s Word16

-- | Unsigned 32-bit word.
word32 :: e -> Parser e s Word32

-- | Unsigned 64-bit word.
word64 :: e -> Parser e s Word64

-- | Signed 8-bit integer.
int8 :: e -> Parser e s Int8

-- | Signed 16-bit integer.
int16 :: e -> Parser e s Int16

-- | Signed 32-bit integer.
int32 :: e -> Parser e s Int32

-- | Signed 64-bit integer.
int64 :: e -> Parser e s Int64


-- | Parse input as UTF-8-encoded text. Parsers in this module will fail if
--   they encounter a byte above <tt>0x7F</tt>.
module Data.Bytes.Parser.Utf8

-- | Interpret the next one to four bytes as a UTF-8-encoded character.
--   Fails if the decoded codepoint is in the range U+D800 through U+DFFF.
any# :: e -> Parser e s Char#

-- | Consume input that matches the argument. Fails if the input does not
--   match.
shortText :: e -> ShortText -> Parser e s ()