-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Strict ByteString Parser Combinator
--
-- Simple parser combinator for strict ByteString values.
@package snack
@version 0.2.0.0
-- | This module provides a parser for unicode Text.
--
--
module Data.Text.Parser
-- | Parser for Text inputs.
newtype Parser a
Parser :: (Text -> Result a) -> Parser a
-- | Run the parser on specified input.
[runParser] :: Parser a -> Text -> Result a
-- | Result represents either success or some kind of failure.
--
-- You can find the problematic offset by subtracting length of the
-- remainder from length of the original input.
data Result a
-- | Parser successfully match the input. Produces the parsing result and
-- the remainder of the input.
Success :: a -> {-# UNPACK #-} !Text -> Result a
-- | Parser failed to match the input. Produces list of expected inputs and
-- the corresponding remainder.
Failure :: [String] -> {-# UNPACK #-} !Text -> Result a
-- | fail was called somewhere during the parsing. Produces the
-- reason and the remainder at the corresponding point with length of the
-- problematic extent.
Error :: String -> {-# UNPACK #-} !Text -> {-# UNPACK #-} !Int -> Result a
-- | Discards the remaining input and returns just the parse result. You
-- might want to combine it with endOfInput for the best effect.
--
-- Example:
--
--
-- parseOnly (pContacts <* endOfInput) bstr
--
parseOnly :: Parser a -> Text -> Maybe a
-- | Accepts a single, matching character.
char :: Char -> Parser Char
-- | Accepts a single, differing character.
notChar :: Char -> Parser Char
-- | Accepts a single character.
anyChar :: Parser Char
-- | Accepts a single character matching the predicate.
satisfy :: (Char -> Bool) -> Parser Char
-- | Accepts a single unicode white space character. See isSpace for
-- details.
space :: Parser Char
-- | Returns True for any Unicode space character, and the control
-- characters \t, \n, \r, \f,
-- \v.
isSpace :: Char -> Bool
-- | Accepts multiple unicode white space characters. See isSpace
-- for details.
skipSpace :: Parser ()
-- | Peeks ahead, but does not consume.
--
-- Be careful, peeking behind end of the input fails. You might want to
-- check using atEnd beforehand.
peekChar :: Parser Char
-- | Accepts a matching string.
string :: Text -> Parser Text
-- | Same as string, but case insensitive.
stringCI :: Text -> Parser Text
-- | Accepts given number of characters. Fails when not enough characters
-- are available.
take :: Int -> Parser Text
-- | Scans ahead statefully and then accepts whatever characters the
-- scanner liked. Scanner returns Nothing to mark end of the
-- acceptable extent.
scan :: s -> (s -> Char -> Maybe s) -> Parser Text
-- | Like scan, but also returns the final scanner state.
runScanner :: s -> (s -> Char -> Maybe s) -> Parser (Text, s)
-- | Efficiently consume as long as the input characters match the
-- predicate. An inverse of takeTill.
takeWhile :: (Char -> Bool) -> Parser Text
-- | Like takeWhile, but requires at least a single character.
takeWhile1 :: (Char -> Bool) -> Parser Text
-- | Efficiently consume until a character matching the predicate is found.
-- An inverse of takeWhile.
takeTill :: (Char -> Bool) -> Parser Text
-- | Same as takeTill, but requires at least a single character.
takeTill1 :: (Char -> Bool) -> Parser Text
-- | Accepts optional '+' or '-' character and then
-- applies it to the following parser result.
signed :: Num a => Parser a -> Parser a
-- | Accepts an integral number in the decimal format.
decimal :: Integral a => Parser a
-- | Accepts an integral number in the hexadecimal format in either case.
-- Does not look for 0x or similar prefixes.
hexadecimal :: Integral a => Parser a
-- | Accepts an integral number in the octal format.
octal :: Integral a => Parser a
-- | Accepts a fractional number as a decimal optinally followed by a colon
-- and the fractional part. Does not support exponentiation.
fractional :: Fractional a => Parser a
-- | Fails if the value returned by the parser does not conform to the
-- predicate. Generalized form of string.
--
-- Example:
--
--
-- pInput = takeWhile isLetter `provided` (odd . length)
--
provided :: (Alternative m, Monad m) => m a -> (a -> Bool) -> m a
-- | Tries various parsers, one by one.
--
-- Example:
--
--
-- pExpression = choice [ pConstant
-- , pVariable
-- , pBinaryOperation
-- , pFunctionApplication
-- ]
--
choice :: Alternative f => [f a] -> f a
-- | Replicates the parser given number of times, collecting the results in
-- a list. Fails if any instance of the parser fails.
--
-- Example:
--
--
-- pFourWords = (:) <$> word <*> count 3 (blank *> word)
-- where word = takeWhile1 isLetter
-- blank = takeWhile1 isSpace
--
count :: Monad m => Int -> m a -> m [a]
-- | One or none.
--
-- It is useful for modelling any computation that is allowed to fail.
--
-- Examples
--
-- Using the Alternative instance of Control.Monad.Except,
-- the following functions:
--
--
-- >>> import Control.Monad.Except
--
--
--
-- >>> canFail = throwError "it failed" :: Except String Int
--
-- >>> final = return 42 :: Except String Int
--
--
-- Can be combined by allowing the first function to fail:
--
--
-- >>> runExcept $ canFail *> final
-- Left "it failed"
--
-- >>> runExcept $ optional canFail *> final
-- Right 42
--
optional :: Alternative f => f a -> f (Maybe a)
-- | Captures first parser as Left or the second as
-- Right.
eitherP :: Alternative f => f a -> f b -> f (Either a b)
-- | Shortcut for optional with a default value.
--
-- Example:
--
--
-- data Contact =
-- Contact
-- { contactName :: Text
-- , contactEmail :: Maybe Text
-- }
--
-- pContact = Contact <$> pFullName <*> option pEmail
--
option :: Alternative f => a -> f a -> f a
-- | Zero or more.
many :: Alternative f => f a -> f [a]
-- | Like many1, but requires at least one match.
many1 :: Alternative f => f a -> f [a]
-- | Like many, but stops once the second parser matches the input
-- ahead.
--
-- Example:
--
--
-- pBodyLines = pLine `manyTill` pEnd
-- where pLine = takeTill (== 'n')
-- pEnd = string "n.n"
--
manyTill :: Alternative f => f a -> f a -> f [a]
-- | Similar to many, but interleaves the first parser with the
-- second.
--
-- Example:
--
--
-- pLines = pLine sepBy char 'n'
--
sepBy :: Alternative f => f a -> f b -> f [a]
-- | Like sepBy, but requires at least one match.
sepBy1 :: Alternative f => f a -> f b -> f [a]
-- | Wraps the parser from both sides.
--
-- Example:
--
--
-- pToken = takeWhile1 (inClass "A-Za-z0-9_") `wrap` takeWhile isSpace
--
wrap :: Applicative f => f a -> f b -> f a
-- | Makes the parser not only return the result, but also the original
-- matched extent.
match :: Parser a -> Parser (Text, a)
-- | Names an extent of the parser.
--
-- When the extent returns a Failure, details are discarded and replaced
-- with the extent as a whole.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
--
-- You should strive to make labeled extents as small as possible,
-- approximately of a typical token size. For example:
--
--
-- pString = label "string" $ pStringContents `wrap` char '"'
--
label :: String -> Parser a -> Parser a
-- | Marks an unlabelel extent of the parser.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
extent :: Parser a -> Parser a
-- | Accept whatever input remains.
takeText :: Parser Text
-- | Accepts end of input and fails if we are not there yet.
endOfInput :: Parser ()
-- | Returns whether we are at the end of the input yet.
atEnd :: Parser Bool
-- | The identity of <|>
empty :: Alternative f => f a
-- | Lift a value.
pure :: Applicative f => a -> f a
-- | Conditional failure of Alternative computations. Defined by
--
--
-- guard True = pure ()
-- guard False = empty
--
--
-- Examples
--
-- Common uses of guard include conditionally signaling an error
-- in an error monad and conditionally rejecting the current choice in an
-- Alternative-based parser.
--
-- As an example of signaling an error in the error monad Maybe,
-- consider a safe division function safeDiv x y that returns
-- Nothing when the denominator y is zero and
-- Just (x `div` y) otherwise. For example:
--
--
-- >>> safeDiv 4 0
-- Nothing
--
--
--
-- >>> safeDiv 4 2
-- Just 2
--
--
-- A definition of safeDiv using guards, but not guard:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y | y /= 0 = Just (x `div` y)
-- | otherwise = Nothing
--
--
-- A definition of safeDiv using guard and Monad
-- do-notation:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y = do
-- guard (y /= 0)
-- return (x `div` y)
--
guard :: Alternative f => Bool -> f ()
-- | Conditional execution of Applicative expressions. For example,
--
--
-- when debug (putStrLn "Debugging")
--
--
-- will output the string Debugging if the Boolean value
-- debug is True, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()
-- | The reverse of when.
unless :: Applicative f => Bool -> f () -> f ()
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
--
-- Examples
--
-- Replace the contents of a Maybe Int with unit:
--
--
-- >>> void Nothing
-- Nothing
--
-- >>> void (Just 3)
-- Just ()
--
--
-- Replace the contents of an Either Int
-- Int with unit, resulting in an Either
-- Int ():
--
--
-- >>> void (Left 8675309)
-- Left 8675309
--
-- >>> void (Right 8675309)
-- Right ()
--
--
-- Replace every element of a list with unit:
--
--
-- >>> void [1,2,3]
-- [(),(),()]
--
--
-- Replace the second element of a pair with unit:
--
--
-- >>> void (1,2)
-- (1,())
--
--
-- Discard the result of an IO action:
--
--
-- >>> mapM print [1,2]
-- 1
-- 2
-- [(),()]
--
-- >>> void $ mapM print [1,2]
-- 1
-- 2
--
void :: Functor f => f a -> f ()
instance GHC.Show.Show a => GHC.Show.Show (Data.Text.Parser.Result a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Text.Parser.Result a)
instance GHC.Base.Functor Data.Text.Parser.Parser
instance GHC.Base.Applicative Data.Text.Parser.Parser
instance GHC.Base.Alternative Data.Text.Parser.Parser
instance GHC.Base.Monad Data.Text.Parser.Parser
instance GHC.Base.MonadPlus Data.Text.Parser.Parser
instance Control.Monad.Fail.MonadFail Data.Text.Parser.Parser
instance GHC.Base.Functor Data.Text.Parser.Result
-- | This module provides a parser for ByteString.
--
--
-- - If you'd like to parse ASCII text, you might want to take a look
-- at Data.ByteString.Parser.Char8. It reuses the same
-- Parser, but provides functions working with Char instead
-- of Word8 as well as more string utilities.
-- - If you'd like to parse Unicode text, look instead at the
-- Data.Text.Parser. Is is slower, but in a way more correct.
--
module Data.ByteString.Parser
-- | Parser for ByteString inputs.
newtype Parser a
Parser :: (ByteString -> Result a) -> Parser a
-- | Run the parser on specified input.
[runParser] :: Parser a -> ByteString -> Result a
-- | Result represents either success or some kind of failure.
--
-- You can find the problematic offset by subtracting length of the
-- remainder from length of the original input.
data Result a
-- | Parser successfully match the input. Produces the parsing result and
-- the remainder of the input.
Success :: a -> {-# UNPACK #-} !ByteString -> Result a
-- | Parser failed to match the input. Produces list of expected inputs and
-- the corresponding remainder.
Failure :: [String] -> {-# UNPACK #-} !ByteString -> Result a
-- | fail was called somewhere during the parsing. Produces the
-- reason and the remainder at the corresponding point with length of the
-- problematic extent.
Error :: String -> {-# UNPACK #-} !ByteString -> {-# UNPACK #-} !Int -> Result a
-- | Discards the remaining input and returns just the parse result. You
-- might want to combine it with endOfInput for the best effect.
--
-- Example:
--
--
-- parseOnly (pContacts <* endOfInput) bstr
--
parseOnly :: Parser a -> ByteString -> Maybe a
-- | Accepts a single, matching byte.
byte :: Word8 -> Parser Word8
-- | Accepts a single, differing byte.
notByte :: Word8 -> Parser Word8
-- | Accepts a single byte.
anyByte :: Parser Word8
-- | Accepts a single byte matching the predicate.
satisfy :: (Word8 -> Bool) -> Parser Word8
-- | Peeks ahead, but does not consume.
--
-- Be careful, peeking behind end of the input fails. You might want to
-- check using atEnd beforehand.
peekByte :: Parser Word8
-- | Accepts a matching string.
string :: ByteString -> Parser ByteString
-- | Accepts given number of bytes. Fails when not enough bytes are
-- available.
take :: Int -> Parser ByteString
-- | Scans ahead statefully and then accepts whatever bytes the scanner
-- liked. Scanner returns Nothing to mark end of the acceptable
-- extent.
scan :: s -> (s -> Word8 -> Maybe s) -> Parser ByteString
-- | Like scan, but also returns the final scanner state.
runScanner :: s -> (s -> Word8 -> Maybe s) -> Parser (ByteString, s)
-- | Efficiently consume as long as the input bytes match the predicate. An
-- inverse of takeTill.
takeWhile :: (Word8 -> Bool) -> Parser ByteString
-- | Like takeWhile, but requires at least a single byte.
takeWhile1 :: (Word8 -> Bool) -> Parser ByteString
-- | Efficiently consume until a byte matching the predicate is found. An
-- inverse of takeWhile.
takeTill :: (Word8 -> Bool) -> Parser ByteString
-- | Same as takeTill, but requires at least a single byte.
takeTill1 :: (Word8 -> Bool) -> Parser ByteString
-- | Fails if the value returned by the parser does not conform to the
-- predicate. Generalized form of string.
--
-- Example:
--
--
-- pInput = takeWhile isLetter `provided` (odd . length)
--
provided :: (Alternative m, Monad m) => m a -> (a -> Bool) -> m a
-- | Tries various parsers, one by one.
--
-- Example:
--
--
-- pExpression = choice [ pConstant
-- , pVariable
-- , pBinaryOperation
-- , pFunctionApplication
-- ]
--
choice :: Alternative f => [f a] -> f a
-- | Replicates the parser given number of times, collecting the results in
-- a list. Fails if any instance of the parser fails.
--
-- Example:
--
--
-- pFourWords = (:) <$> word <*> count 3 (blank *> word)
-- where word = takeWhile1 isLetter
-- blank = takeWhile1 isSpace
--
count :: Monad m => Int -> m a -> m [a]
-- | One or none.
--
-- It is useful for modelling any computation that is allowed to fail.
--
-- Examples
--
-- Using the Alternative instance of Control.Monad.Except,
-- the following functions:
--
--
-- >>> import Control.Monad.Except
--
--
--
-- >>> canFail = throwError "it failed" :: Except String Int
--
-- >>> final = return 42 :: Except String Int
--
--
-- Can be combined by allowing the first function to fail:
--
--
-- >>> runExcept $ canFail *> final
-- Left "it failed"
--
-- >>> runExcept $ optional canFail *> final
-- Right 42
--
optional :: Alternative f => f a -> f (Maybe a)
-- | Captures first parser as Left or the second as
-- Right.
eitherP :: Alternative f => f a -> f b -> f (Either a b)
-- | Shortcut for optional with a default value.
--
-- Example:
--
--
-- data Contact =
-- Contact
-- { contactName :: Text
-- , contactEmail :: Maybe Text
-- }
--
-- pContact = Contact <$> pFullName <*> option pEmail
--
option :: Alternative f => a -> f a -> f a
-- | Zero or more.
many :: Alternative f => f a -> f [a]
-- | Like many1, but requires at least one match.
many1 :: Alternative f => f a -> f [a]
-- | Like many, but stops once the second parser matches the input
-- ahead.
--
-- Example:
--
--
-- pBodyLines = pLine `manyTill` pEnd
-- where pLine = takeTill (== 'n')
-- pEnd = string "n.n"
--
manyTill :: Alternative f => f a -> f a -> f [a]
-- | Similar to many, but interleaves the first parser with the
-- second.
--
-- Example:
--
--
-- pLines = pLine sepBy char 'n'
--
sepBy :: Alternative f => f a -> f b -> f [a]
-- | Like sepBy, but requires at least one match.
sepBy1 :: Alternative f => f a -> f b -> f [a]
-- | Wraps the parser from both sides.
--
-- Example:
--
--
-- pToken = takeWhile1 (inClass "A-Za-z0-9_") `wrap` takeWhile isSpace
--
wrap :: Applicative f => f a -> f b -> f a
-- | Makes the parser not only return the result, but also the original
-- matched extent.
match :: Parser a -> Parser (ByteString, a)
-- | Names an extent of the parser.
--
-- When the extent returns a Failure, details are discarded and replaced
-- with the extent as a whole.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
--
-- You should strive to make labeled extents as small as possible,
-- approximately of a typical token size. For example:
--
--
-- pString = label "string" $ pStringContents `wrap` char '"'
--
label :: String -> Parser a -> Parser a
-- | Marks an unlabelel extent of the parser.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
extent :: Parser a -> Parser a
-- | Accept whatever input remains.
takeByteString :: Parser ByteString
-- | Accepts end of input and fails if we are not there yet.
endOfInput :: Parser ()
-- | Returns whether we are at the end of the input yet.
atEnd :: Parser Bool
-- | The identity of <|>
empty :: Alternative f => f a
-- | Lift a value.
pure :: Applicative f => a -> f a
-- | Conditional failure of Alternative computations. Defined by
--
--
-- guard True = pure ()
-- guard False = empty
--
--
-- Examples
--
-- Common uses of guard include conditionally signaling an error
-- in an error monad and conditionally rejecting the current choice in an
-- Alternative-based parser.
--
-- As an example of signaling an error in the error monad Maybe,
-- consider a safe division function safeDiv x y that returns
-- Nothing when the denominator y is zero and
-- Just (x `div` y) otherwise. For example:
--
--
-- >>> safeDiv 4 0
-- Nothing
--
--
--
-- >>> safeDiv 4 2
-- Just 2
--
--
-- A definition of safeDiv using guards, but not guard:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y | y /= 0 = Just (x `div` y)
-- | otherwise = Nothing
--
--
-- A definition of safeDiv using guard and Monad
-- do-notation:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y = do
-- guard (y /= 0)
-- return (x `div` y)
--
guard :: Alternative f => Bool -> f ()
-- | Conditional execution of Applicative expressions. For example,
--
--
-- when debug (putStrLn "Debugging")
--
--
-- will output the string Debugging if the Boolean value
-- debug is True, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()
-- | The reverse of when.
unless :: Applicative f => Bool -> f () -> f ()
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
--
-- Examples
--
-- Replace the contents of a Maybe Int with unit:
--
--
-- >>> void Nothing
-- Nothing
--
-- >>> void (Just 3)
-- Just ()
--
--
-- Replace the contents of an Either Int
-- Int with unit, resulting in an Either
-- Int ():
--
--
-- >>> void (Left 8675309)
-- Left 8675309
--
-- >>> void (Right 8675309)
-- Right ()
--
--
-- Replace every element of a list with unit:
--
--
-- >>> void [1,2,3]
-- [(),(),()]
--
--
-- Replace the second element of a pair with unit:
--
--
-- >>> void (1,2)
-- (1,())
--
--
-- Discard the result of an IO action:
--
--
-- >>> mapM print [1,2]
-- 1
-- 2
-- [(),()]
--
-- >>> void $ mapM print [1,2]
-- 1
-- 2
--
void :: Functor f => f a -> f ()
instance GHC.Show.Show a => GHC.Show.Show (Data.ByteString.Parser.Result a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.ByteString.Parser.Result a)
instance GHC.Base.Functor Data.ByteString.Parser.Parser
instance GHC.Base.Applicative Data.ByteString.Parser.Parser
instance GHC.Base.Alternative Data.ByteString.Parser.Parser
instance GHC.Base.Monad Data.ByteString.Parser.Parser
instance GHC.Base.MonadPlus Data.ByteString.Parser.Parser
instance Control.Monad.Fail.MonadFail Data.ByteString.Parser.Parser
instance GHC.Base.Functor Data.ByteString.Parser.Result
-- | This module provides a parser for ASCII ByteString.
--
--
-- - If you'd like to parse Unicode text, look instead at the
-- Data.Text.Parser. Is is slower, but in a way more correct.
-- - If you'd like to parse byte sequences, look instead at the
-- Data.ByteString.Parser. It reuses the same Parser, but
-- provides functions working with Word8 instead of
-- Char.
--
module Data.ByteString.Parser.Char8
-- | Parser for ByteString inputs.
newtype Parser a
Parser :: (ByteString -> Result a) -> Parser a
-- | Run the parser on specified input.
[runParser] :: Parser a -> ByteString -> Result a
-- | Result represents either success or some kind of failure.
--
-- You can find the problematic offset by subtracting length of the
-- remainder from length of the original input.
data Result a
-- | Parser successfully match the input. Produces the parsing result and
-- the remainder of the input.
Success :: a -> {-# UNPACK #-} !ByteString -> Result a
-- | Parser failed to match the input. Produces list of expected inputs and
-- the corresponding remainder.
Failure :: [String] -> {-# UNPACK #-} !ByteString -> Result a
-- | fail was called somewhere during the parsing. Produces the
-- reason and the remainder at the corresponding point with length of the
-- problematic extent.
Error :: String -> {-# UNPACK #-} !ByteString -> {-# UNPACK #-} !Int -> Result a
-- | Discards the remaining input and returns just the parse result. You
-- might want to combine it with endOfInput for the best effect.
--
-- Example:
--
--
-- parseOnly (pContacts <* endOfInput) bstr
--
parseOnly :: Parser a -> ByteString -> Maybe a
-- | Accepts a single, matching ASCII character.
char :: Char -> Parser Char
-- | Accepts a single, differing ASCII character.
notChar :: Char -> Parser Char
-- | Accepts a single character.
anyChar :: Parser Char
-- | Accepts a single character matching the predicate.
satisfy :: (Char -> Bool) -> Parser Char
-- | Accepts a single ASCII white space character. See isSpace for
-- details.
space :: Parser Char
-- | True for any of the [' ', '\t', '\n', '\v', '\f', '\r']
-- characters.
--
-- Please note that Data.Text.Parser re-exports isString,
-- that considers more unicode codepoints, making it significantly
-- slower.
isSpace :: Char -> Bool
-- | Accepts multiple ASCII white space characters. See isSpace for
-- details.
skipSpace :: Parser ()
-- | Peeks ahead, but does not consume.
--
-- Be careful, peeking behind end of the input fails. You might want to
-- check using atEnd beforehand.
peekChar :: Parser Char
-- | Accepts a matching string.
string :: ByteString -> Parser ByteString
-- | Accepts a matching string. Matching is performed in a case-insensitive
-- manner under ASCII.
stringCI :: ByteString -> Parser ByteString
-- | Accepts given number of bytes. Fails when not enough bytes are
-- available.
take :: Int -> Parser ByteString
-- | Scans ahead statefully and then accepts whatever bytes the scanner
-- liked. Scanner returns Nothing to mark end of the acceptable
-- extent.
scan :: s -> (s -> Char -> Maybe s) -> Parser ByteString
-- | Like scan, but also returns the final scanner state.
runScanner :: s -> (s -> Char -> Maybe s) -> Parser (ByteString, s)
-- | Tests whether the character lies within given range.
--
-- Definition:
--
--
-- inRange lo hi = c -> (lo <= c && c <= hi)
--
inRange :: Char -> Char -> Char -> Bool
-- | Negation of inRange.
--
-- Definition:
--
--
-- notInRange lo hi = c -> (c <= lo || hi <= c)
--
notInRange :: Char -> Char -> Char -> Bool
-- | Efficiently consume as long as the input characters match the
-- predicate. An inverse of takeTill.
takeWhile :: (Char -> Bool) -> Parser ByteString
-- | Like takeWhile, but requires at least a single character.
takeWhile1 :: (Char -> Bool) -> Parser ByteString
-- | Efficiently consume until a character matching the predicate is found.
-- An inverse of takeWhile.
takeTill :: (Char -> Bool) -> Parser ByteString
-- | Same as takeTill, but requires at least a single character.
takeTill1 :: (Char -> Bool) -> Parser ByteString
-- | Accepts optional '+' or '-' character and then
-- applies it to the following parser result.
signed :: Num a => Parser a -> Parser a
-- | Accepts an integral number in the decimal format.
decimal :: Integral a => Parser a
-- | Accepts an integral number in the hexadecimal format in either case.
-- Does not look for 0x or similar prefixes.
hexadecimal :: Integral a => Parser a
-- | Accepts an integral number in the octal format.
octal :: Integral a => Parser a
-- | Accepts a fractional number as a decimal optinally followed by a colon
-- and the fractional part. Does not support exponentiation.
fractional :: Fractional a => Parser a
-- | Fails if the value returned by the parser does not conform to the
-- predicate. Generalized form of string.
--
-- Example:
--
--
-- pInput = takeWhile isLetter `provided` (odd . length)
--
provided :: (Alternative m, Monad m) => m a -> (a -> Bool) -> m a
-- | Tries various parsers, one by one.
--
-- Example:
--
--
-- pExpression = choice [ pConstant
-- , pVariable
-- , pBinaryOperation
-- , pFunctionApplication
-- ]
--
choice :: Alternative f => [f a] -> f a
-- | Replicates the parser given number of times, collecting the results in
-- a list. Fails if any instance of the parser fails.
--
-- Example:
--
--
-- pFourWords = (:) <$> word <*> count 3 (blank *> word)
-- where word = takeWhile1 isLetter
-- blank = takeWhile1 isSpace
--
count :: Monad m => Int -> m a -> m [a]
-- | One or none.
--
-- It is useful for modelling any computation that is allowed to fail.
--
-- Examples
--
-- Using the Alternative instance of Control.Monad.Except,
-- the following functions:
--
--
-- >>> import Control.Monad.Except
--
--
--
-- >>> canFail = throwError "it failed" :: Except String Int
--
-- >>> final = return 42 :: Except String Int
--
--
-- Can be combined by allowing the first function to fail:
--
--
-- >>> runExcept $ canFail *> final
-- Left "it failed"
--
-- >>> runExcept $ optional canFail *> final
-- Right 42
--
optional :: Alternative f => f a -> f (Maybe a)
-- | Captures first parser as Left or the second as
-- Right.
eitherP :: Alternative f => f a -> f b -> f (Either a b)
-- | Shortcut for optional with a default value.
--
-- Example:
--
--
-- data Contact =
-- Contact
-- { contactName :: Text
-- , contactEmail :: Maybe Text
-- }
--
-- pContact = Contact <$> pFullName <*> option pEmail
--
option :: Alternative f => a -> f a -> f a
-- | Zero or more.
many :: Alternative f => f a -> f [a]
-- | Like many1, but requires at least one match.
many1 :: Alternative f => f a -> f [a]
-- | Like many, but stops once the second parser matches the input
-- ahead.
--
-- Example:
--
--
-- pBodyLines = pLine `manyTill` pEnd
-- where pLine = takeTill (== 'n')
-- pEnd = string "n.n"
--
manyTill :: Alternative f => f a -> f a -> f [a]
-- | Similar to many, but interleaves the first parser with the
-- second.
--
-- Example:
--
--
-- pLines = pLine sepBy char 'n'
--
sepBy :: Alternative f => f a -> f b -> f [a]
-- | Like sepBy, but requires at least one match.
sepBy1 :: Alternative f => f a -> f b -> f [a]
-- | Wraps the parser from both sides.
--
-- Example:
--
--
-- pToken = takeWhile1 (inClass "A-Za-z0-9_") `wrap` takeWhile isSpace
--
wrap :: Applicative f => f a -> f b -> f a
-- | Makes the parser not only return the result, but also the original
-- matched extent.
match :: Parser a -> Parser (ByteString, a)
-- | Names an extent of the parser.
--
-- When the extent returns a Failure, details are discarded and replaced
-- with the extent as a whole.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
--
-- You should strive to make labeled extents as small as possible,
-- approximately of a typical token size. For example:
--
--
-- pString = label "string" $ pStringContents `wrap` char '"'
--
label :: String -> Parser a -> Parser a
-- | Marks an unlabelel extent of the parser.
--
-- When the extent returns an Error, it is adjusted to cover the whole
-- extent, but the reason is left intact.
extent :: Parser a -> Parser a
-- | Accept whatever input remains.
takeByteString :: Parser ByteString
-- | Accepts end of input and fails if we are not there yet.
endOfInput :: Parser ()
-- | Returns whether we are at the end of the input yet.
atEnd :: Parser Bool
-- | The identity of <|>
empty :: Alternative f => f a
-- | Lift a value.
pure :: Applicative f => a -> f a
-- | Conditional failure of Alternative computations. Defined by
--
--
-- guard True = pure ()
-- guard False = empty
--
--
-- Examples
--
-- Common uses of guard include conditionally signaling an error
-- in an error monad and conditionally rejecting the current choice in an
-- Alternative-based parser.
--
-- As an example of signaling an error in the error monad Maybe,
-- consider a safe division function safeDiv x y that returns
-- Nothing when the denominator y is zero and
-- Just (x `div` y) otherwise. For example:
--
--
-- >>> safeDiv 4 0
-- Nothing
--
--
--
-- >>> safeDiv 4 2
-- Just 2
--
--
-- A definition of safeDiv using guards, but not guard:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y | y /= 0 = Just (x `div` y)
-- | otherwise = Nothing
--
--
-- A definition of safeDiv using guard and Monad
-- do-notation:
--
--
-- safeDiv :: Int -> Int -> Maybe Int
-- safeDiv x y = do
-- guard (y /= 0)
-- return (x `div` y)
--
guard :: Alternative f => Bool -> f ()
-- | Conditional execution of Applicative expressions. For example,
--
--
-- when debug (putStrLn "Debugging")
--
--
-- will output the string Debugging if the Boolean value
-- debug is True, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()
-- | The reverse of when.
unless :: Applicative f => Bool -> f () -> f ()
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
--
-- Examples
--
-- Replace the contents of a Maybe Int with unit:
--
--
-- >>> void Nothing
-- Nothing
--
-- >>> void (Just 3)
-- Just ()
--
--
-- Replace the contents of an Either Int
-- Int with unit, resulting in an Either
-- Int ():
--
--
-- >>> void (Left 8675309)
-- Left 8675309
--
-- >>> void (Right 8675309)
-- Right ()
--
--
-- Replace every element of a list with unit:
--
--
-- >>> void [1,2,3]
-- [(),(),()]
--
--
-- Replace the second element of a pair with unit:
--
--
-- >>> void (1,2)
-- (1,())
--
--
-- Discard the result of an IO action:
--
--
-- >>> mapM print [1,2]
-- 1
-- 2
-- [(),()]
--
-- >>> void $ mapM print [1,2]
-- 1
-- 2
--
void :: Functor f => f a -> f ()