Modulefoundation-0.0.30Haskell2010

Foundation.Parser

The current implementation is mainly, if not copy/pasted, inspired from memory's Parser.

Foundation Parser makes use of the Foundation's Collection and Sequential classes to allow you to define generic parsers over any Sequential of inpu.

This way you can easily implements parsers over LString, String.

flip parseOnly "my.email@address.com" $ do
   EmailAddress
     <$> (takeWhile ((/=) '@' <*  element '@')
     <*> takeAll

5 types
1 class
19 values

Packagefoundation-0.0.30
Exports28
LanguageHaskell2010
LicenceBSD-3-Clause
SourceParser.hs

newtypenewtype Parser input result

Foundation's Parser monad.

Its implementation is based on the parser in memory.

Instances5Monad, Functor, Applicative, Alternative, MonadPlus

ParserSource input => Monad (Parser input)Defined in foundation-0.0.30 · Foundation.Parser
Functor (Parser input)Defined in foundation-0.0.30 · Foundation.Parser
ParserSource input => Applicative (Parser input)Defined in foundation-0.0.30 · Foundation.Parser
ParserSource input => Alternative (Parser input)Defined in foundation-0.0.30 · Foundation.Parser
ParserSource input => MonadPlus (Parser input)Defined in foundation-0.0.30 · Foundation.Parser

valueparse :: ParserSource input => Parser input a -> input -> Result input a

Run a Parser on a ByteString and return a Result

valueparseFeed

:: (ParserSource input, Monad m)
=> m (Chunk input)
-> Parser input a
-> input
-> m (Result input a)

Run a parser on an @initial input.

If the Parser need more data than available, the @feeder function is automatically called and fed to the More continuation.

valueparseOnly

:: (ParserSource input, Monoid (Chunk input))
=> Parser input a
-> input
-> Either (ParseError input) a

parse only the given input

The left-over `Element input` will be ignored, if the parser call for more data it will be continuously fed with Nothing (up to 256 iterations).

Result

3 declarations

datadata Result input result

result of executing the parser over the given input

Constructors

ParseFailed (ParseError input)
the parser failed with the given ParserError
ParseOk (Chunk input) result
the parser complete successfuly with the remaining Chunk
ParseMore (Chunk input -> Result input result)
the parser needs more input, pass an empty Chunk or mempty to tell the parser you don't have anymore inputs.

Instances2Functor, Show

Functor (Result input)Defined in foundation-0.0.30 · Foundation.Parser
(Show k, Show input) => Show (Result input k)Defined in foundation-0.0.30 · Foundation.Parser

datadata ParseError input

common parser error definition

Constructors

NotEnough (CountOf (Element input))
meaning the parser was short of CountOf Element of input.
NotEnoughParseOnly
The parser needed more data, only when using parseOnly
ExpectedElement (Element input) (Element input)
when using element
Expected (Chunk input) (Chunk input)
when using elements or string
Satisfy (Maybe String)
the satisfy or satisfy_ function failed,

Instances3Show, Exception

Show (ParseError String)Defined in foundation-0.0.30 · Foundation.Parser
Show input => Show (ParseError input)Defined in foundation-0.0.30 · Foundation.Parser
(Typeable input, Show input) => Exception (ParseError input)Defined in foundation-0.0.30 · Foundation.Parser

valuereportError :: ParseError input -> Parser input a

helper function to report error when writing parsers

This way we can provide more detailed error when building custom parsers and still avoid to use the naughty _fail_.

myParser :: Parser input Int
myParser = reportError $ Satisfy (Just "this function is not implemented...")

Parser source

1 declaration

classclass (Sequential input, IndexedCollection input) => ParserSource input where

Associated types

type family Chunk input

Methods

nullChunk :: input -> Chunk input -> Bool
appendChunk :: input -> Chunk input -> input
subChunk :: input -> Offset (Element input) -> CountOf (Element input) -> Chunk input
spanChunk :: input -> Offset (Element input) -> (Element input -> Bool) -> (Chunk input, Offset (Element input))

Instances2ParserSource

ParserSource StringDefined in foundation-0.0.30 · Foundation.Parser
ParserSource [a]Defined in foundation-0.0.30 · Foundation.Parser

combinator

20 declarations

valuepeek :: ParserSource input => Parser input (Maybe (Element input))

peek the first element from the input source without consuming it

Returns Nothing if there is no more input to parse.

valueelement

:: (ParserSource input, Eq (Element input), Element input ~ Element (Chunk input))
=> Element input
-> Parser input ()

valueanyElement :: ParserSource input => Parser input (Element input)

Get the next `Element input` from the parser

valueelements

:: (ParserSource input, Sequential (Chunk input), Element (Chunk input) ~ Element input, Eq (Chunk input))
=> Chunk input
-> Parser input ()

valuestring :: String -> Parser String ()

valuesatisfy

:: ParserSource input
=> Maybe String
-> Element input -> Bool
-> Parser input (Element input)

take one element if satisfy the given predicate

valuesatisfy_

:: ParserSource input
=> Element input -> Bool
-> Parser input (Element input)

take one element if satisfy the given predicate

valuetake

:: (ParserSource input, Sequential (Chunk input), Element input ~ Element (Chunk input))
=> CountOf (Element (Chunk input))
-> Parser input (Chunk input)

valuetakeWhile

:: (ParserSource input, Sequential (Chunk input))
=> Element input -> Bool
-> Parser input (Chunk input)

valuetakeAll :: (ParserSource input, Sequential (Chunk input)) => Parser input (Chunk input)

Take the remaining elements from the current position in the stream

valueskip :: ParserSource input => CountOf (Element input) -> Parser input ()

valueskipWhile

:: (ParserSource input, Sequential (Chunk input))
=> Element input -> Bool
-> Parser input ()

valueskipAll :: (ParserSource input, Collection (Chunk input)) => Parser input ()

consume every chunk of the stream

method(<|>) :: f a -> f a -> f a

An associative binary operation

methodmany :: f a -> f [a]

Zero or more.

Examples

Example1 expression

>>> many (putStr "la")lalalalalalalalala... * goes on forever *

Example1 expression

>>> many NothingJust []

Example1 expression

>>> take 5 <$> many (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case many parser will attempt to parse parser zero or more times until it fails.

methodsome :: f a -> f [a]

One or more.

Examples

Example1 expression

>>> some (putStr "la")lalalalalalalalala... * goes on forever *

Example1 expression

>>> some Nothingnothing

Example1 expression

>>> take 5 <$> some (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case some parser will attempt to parse parser one or more times until it fails.

valueoptional :: Alternative f => f a -> f (Maybe 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:

Example1 expression

>>> import Control.Monad.Except

Example2 expressions

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

Example1 expression

>>> runExcept $ canFail *> finalLeft "it failed"

Example1 expression

>>> runExcept $ optional canFail *> finalRight 42

valuerepeat

:: ParserSource input
=> Condition
-> Parser input a
-> Parser input [a]

repeat the given parser a given amount of time

Unlike some or many, this operation will bring more precision on how many times you wish a parser to be sequenced.

## Repeat Exactly a number of time

repeat (Exactly 6) (takeWhile ((/=) ',') <* element ',')

## Repeat Between lower `And` upper times

repeat (Between $ 1 `And` 10) (takeWhile ((/=) ',') <* element ',')

datadata Condition

Constructors

Between !And
Exactly !Word

Instances2Eq, Show

Eq ConditionDefined in foundation-0.0.30 · Foundation.Parser
Show ConditionDefined in foundation-0.0.30 · Foundation.Parser

datadata And

Constructors

And !Word !Word

Instances2Eq, Show

Eq AndDefined in foundation-0.0.30 · Foundation.Parser
Show AndDefined in foundation-0.0.30 · Foundation.Parser