Data.ByteString.Parser

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.

Documentation

newtype Parser a

Parser for ByteString inputs.

Constructors

Parser

Fields

• runParser :: ByteString -> Result a

  Run the parser on specified input.

Instances

Monad Parser

Defined in Data.ByteString.Parser

Methods

(>>=) :: Parser a -> (a -> Parser b) -> Parser b

(>>) :: Parser a -> Parser b -> Parser b

return :: a -> Parser a

Functor Parser

Defined in Data.ByteString.Parser

Methods

fmap :: (a -> b) -> Parser a -> Parser b

(<$) :: a -> Parser b -> Parser a

MonadFail Parser

Defined in Data.ByteString.Parser

Methods

fail :: String -> Parser a

Applicative Parser

Defined in Data.ByteString.Parser

Methods

pure :: a -> Parser a

(<*>) :: Parser (a -> b) -> Parser a -> Parser b

liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c

(*>) :: Parser a -> Parser b -> Parser b

(<*) :: Parser a -> Parser b -> Parser a

Alternative Parser

Defined in Data.ByteString.Parser

Methods

empty :: Parser a

(<|>) :: Parser a -> Parser a -> Parser a

some :: Parser a -> Parser [a]

many :: Parser a -> Parser [a]

MonadPlus Parser

Defined in Data.ByteString.Parser

Methods

mzero :: Parser a

mplus :: Parser a -> Parser a -> Parser a

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

Constructors

Success a !ByteString

Parser successfully matched the input. Produces the parsing result and the remainder of the input.

Failure [String] !ByteString

Parser failed to match the input. Produces list of expected inputs and the corresponding remainder.

Error String !ByteString !Int

Parser ran into an error. Either syntactic or a validation one.

Instances

Functor Result

Defined in Data.ByteString.Parser

Methods

fmap :: (a -> b) -> Result a -> Result b

(<$) :: a -> Result b -> Result a

Eq a => Eq (Result a)

Defined in Data.ByteString.Parser

Methods

(==) :: Result a -> Result a -> Bool

(/=) :: Result a -> Result a -> Bool

Show a => Show (Result a)

Defined in Data.ByteString.Parser

Methods

showsPrec :: Int -> Result a -> ShowS

show :: Result a -> String

showList :: [Result a] -> ShowS

parseOnly :: Parser a -> ByteString -> Either String 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

Bytes

byte :: Word8 -> Parser Word8

Accepts a single, matching byte.

notByte :: Word8 -> Parser Word8

Accepts a single, differing byte.

anyByte :: Parser Word8

Accepts a single byte.

satisfy :: (Word8 -> Bool) -> Parser Word8

Accepts a single byte matching the predicate.

peekByte :: 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.

Strings

string :: ByteString -> Parser ByteString

Accepts a matching string.

take :: Int -> Parser ByteString

Accepts given number of bytes. Fails when not enough bytes are available.

scan :: s -> (s -> Word8 -> Maybe s) -> Parser ByteString

Scans ahead statefully and then accepts whatever bytes the scanner liked. Scanner returns Nothing to mark end of the acceptable extent.

runScanner :: s -> (s -> Word8 -> Maybe s) -> Parser (ByteString, s)

Like scan, but also returns the final scanner state.

takeWhile :: (Word8 -> Bool) -> Parser ByteString

Efficiently consume as long as the input bytes match the predicate. An inverse of takeTill.

takeWhile1 :: (Word8 -> Bool) -> Parser ByteString

Like takeWhile, but requires at least a single byte.

takeTill :: (Word8 -> Bool) -> Parser ByteString

Efficiently consume until a byte matching the predicate is found. An inverse of takeWhile.

takeTill1 :: (Word8 -> Bool) -> Parser ByteString

Same as takeTill, but requires at least a single byte.

Combinators

provided :: (Alternative m, Monad m) => m a -> (a -> Bool) -> m 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)

choice :: Alternative f => [f a] -> f a

Tries various parsers, one by one.

Example:

pExpression = choice [ pConstant
                     , pVariable
                     , pBinaryOperation
                     , pFunctionApplication
                     ]

branch :: [(Parser a, a -> Parser b)] -> Parser b

Given list of matchers and parsers, runs the first parser whose matcher succeeds on the input. This pattern makes for a simpler alternative to try used in other parser combinator libraries.

Example:

pProperty = branch [ ( string "public" <* skipSpace
                     , _ -> Property Public $ pToken
                     )
                   , ( string "private" <* skipSpace
                     , _ -> Property Private $ pToken
                     )
                   ]

count :: Monad m => Int -> m a -> m [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

optional :: Alternative f => f a -> f (Maybe a)

One or none.

eitherP :: Alternative f => f a -> f b -> f (Either a b)

Captures first parser as Left or the second as Right.

option :: Alternative f => a -> f a -> f a

Shortcut for optional with a default value.

Example:

data Contact =
 Contact
   { contactName  :: Text
   , contactEmail :: Maybe Text
   }

pContact = Contact <$> pFullName <*> option pEmail

many :: Alternative f => f a -> f [a]

Zero or more.

many1 :: Alternative f => f a -> f [a]

Like many1, but requires at least one match.

manyTill :: Alternative f => f a -> 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"

sepBy :: Alternative f => f a -> f b -> f [a]

Similar to many, but interleaves the first parser with the second.

Example:

pLines = pLine sepBy char 'n'

sepBy1 :: Alternative f => f a -> f b -> f [a]

Like sepBy, but requires at least one match.

wrap :: Applicative f => f a -> f b -> f a

Wraps the parser from both sides.

Example:

pToken = takeWhile1 (inClass "A-Za-z0-9_") `wrap` takeWhile isSpace

match :: Parser a -> Parser (ByteString, a)

Makes the parser not only return the result, but also the original matched extent.

label :: String -> Parser a -> Parser 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 '"'

unlabel :: Parser a -> Parser a

Un-names an extent of the parser.

Same as label, but removes any expected values upon Failure. Very useful to mark comments and optional whitespace with.

validate :: (a -> Either String b) -> Parser a -> Parser b

Validate parser result and turn it into an Error upon failure.

End Of Input

takeByteString :: Parser ByteString

Accept whatever input remains.

peekByteString :: Parser ByteString

Peek at whatever input remains.

endOfInput :: Parser ()

Accepts end of input and fails if we are not there yet.

atEnd :: Parser Bool

Returns whether we are at the end of the input yet.

Position

offset :: ByteString -> ByteString -> Int

Calculate offset from the original input and the remainder.

Miscelaneous

These are all generic methods, but since I sometimes forget about them, it is nice to have them listed here for reference what writing parsers.

empty :: Alternative f => f a

The identity of <|>

pure :: Applicative f => a -> f a

Lift a value.

guard :: Alternative f => Bool -> f ()

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)

when :: Applicative f => Bool -> f () -> 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.

unless :: Applicative f => Bool -> f () -> f ()

The reverse of when.

void :: Functor f => f a -> f ()

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Using ApplicativeDo: 'void as' can be understood as the do expression

do as
   pure ()

with an inferred Functor constraint.

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