Safe Haskell	None
Language	GHC2024

Circuit.Parser

Contents

Result type
Stream coalgebra
Parser syntax
Running
Result extraction
Primitives
Choice
Repetition
Capture
Inspection
Backtracking
Post-filter
Continuation
Line endings

Description

Unified parser over Body (,) f (K m), with the stream f as ambient state.

The stream f is carried as the explicit thread state; the parser takes no positional input (unit direction) and produces a These a f output: a result (This), a failure returning the stream (That), or a partial result plus remainder (These).

The base monad m selects the parser family:

m = Identity — attoparsec-style pure parser
m = StateT s (ExceptT e n) — megaparsec-style state + errors

First-line libraries add Applicative, Alternative, Monad, and MonadLogic instances on top of this syntax.

the intact-stream law

Every parser that fails returns That carrying the intact original stream. This is the invariant that makes <|> backtrack: the next alternative receives the same stream the previous one started with. If a composite parser consumes input before failing, its That carries the stream at the point of failure, so the next alternative will silently start from a partially consumed position. try repairs exactly that: wrap a composite alternative when it may consume input and then fail.

doctests

>>> runParserIdentity (char 'a') "abc"
These 'a' "bc"

>>> runParserIdentity (char 'x') "abc"
That "abc"

>>> runParserIdentity (string "ab") "abc"
These "ab" "c"

>>> runParserIdentity (string "ab") "ab"
These "ab" ""

>>> runParserIdentity (many (char 'a')) "aaab"
These "aaa" "b"

>>> runParserIdentity (char 'a' *> char 'b') "ab"
This 'b'

>>> runParserIdentity (char 'a' *> char 'b') "a"
That "a"

>>> runParserIdentity (endOfInput :: Parser Identity String Char ()) ""
These () ""

>>> runParserIdentity (endOfInput :: Parser Identity String Char ()) "a"
That "a"

Synopsis

data These a b
- = This a
- | That b
- | These a b
class Uncons f s where
- uncons :: f -> These s f
- nil :: f
newtype Parser (m :: Type -> Type) f (s :: k) a = Parser {
- unParser :: Body (,) f (K m) () (These a f)
}
runParser :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m (These a f)
runParserIdentity :: forall {k} f (s :: k) a. Parser Identity f s a -> f -> These a f
runParserMaybe :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m (Maybe a)
runParserError :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m a
asThese :: These a f -> a
asMaybe' :: These a f -> Maybe a
asEither :: These a f -> Either f a
next :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s
anyToken :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s
satisfy :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s s
satisfyAscii :: forall (m :: Type -> Type) f. (Monad m, Uncons f Char) => (Char -> Bool) -> Parser m f Char Char
char :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s, Eq s) => s -> Parser m f s s
string :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s, Eq s) => [s] -> Parser m f s [s]
endOfInput :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s ()
takeRest :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s f
skipWhile :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s ()
empty :: Alternative f => f a
(<|>) :: Alternative f => f a -> f a -> f a
many :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s [a]
some :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s [a]
optional :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s (Maybe a)
skipMany :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s ()
count :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Int -> Parser m f s a -> Parser m f s [a]
sepBy :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s b -> Parser m f s [a]
sepBy1 :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s b -> Parser m f s [a]
chainr :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => (a -> b -> b) -> Parser m f s a -> Parser m f s b -> Parser m f s b
capturedBS :: forall (m :: Type -> Type) a. Monad m => Parser m ByteString Char a -> Parser m ByteString Char (ByteString, a)
bs :: forall (m :: Type -> Type) a. Monad m => Parser m ByteString Char a -> Parser m ByteString Char ByteString
span :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s [s]
span1 :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s [s]
peek :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s
try :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s a
filterP :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> (a -> Bool) -> Parser m f s a
withOption :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> (a -> Parser m f s b) -> Parser m f s b -> Parser m f s b
lineEnd :: forall (m :: Type -> Type) f. (Monad m, Uncons f Char) => Parser m f Char Char

Result type

data These a b #

The These type represents values with two non-exclusive possibilities.

This can be useful to represent combinations of two values, where the combination is defined if either input is. Algebraically, the type These A B represents (A + B + AB), which doesn't factor easily into sums and products--a type like Either A (B, Maybe A) is unclear and awkward to use.

These has straightforward instances of Functor, Monad, &c., and behaves like a hybrid error/writer monad, as would be expected.

For zipping and unzipping of structures with These values, see Data.Align.

Constructors

This a
That b
These a b

Instances

Instances details

Bifoldable These #

Instance details

Defined in Data.These

Methods

bifold :: Monoid m => These m m -> m #

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> These a b -> m #

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> These a b -> c #

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> These a b -> c #

Bifoldable1 These #

Since: these-1.2

Instance details

Defined in Data.These

Methods

bifold1 :: Semigroup m => These m m -> m #

bifoldMap1 :: Semigroup m => (a -> m) -> (b -> m) -> These a b -> m #

Bifunctor These #

Instance details

Defined in Data.These

Methods

bimap :: (a -> b) -> (c -> d) -> These a c -> These b d #

first :: (a -> b) -> These a c -> These b c #

second :: (b -> c) -> These a b -> These a c #

Bitraversable These #

Instance details

Defined in Data.These

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> These a b -> f (These c d) #

Eq2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftEq2 :: (a -> b -> Bool) -> (c -> d -> Bool) -> These a c -> These b d -> Bool #

Ord2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftCompare2 :: (a -> b -> Ordering) -> (c -> d -> Ordering) -> These a c -> These b d -> Ordering #

Read2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftReadsPrec2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> Int -> ReadS (These a b) #

liftReadList2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> ReadS [These a b] #

liftReadPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec (These a b) #

liftReadListPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec [These a b] #

Show2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftShowsPrec2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> Int -> These a b -> ShowS #

liftShowList2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> [These a b] -> ShowS #

NFData2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftRnf2 :: (a -> ()) -> (b -> ()) -> These a b -> () #

Hashable2 These #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftHashWithSalt2 :: (Int -> a -> Int) -> (Int -> b -> Int) -> Int -> These a b -> Int #

Assoc These #

Since: these-0.8

Instance details

Defined in Data.These

Methods

assoc :: These (These a b) c -> These a (These b c) #

unassoc :: These a (These b c) -> These (These a b) c #

Swap These #

Since: these-0.8

Instance details

Defined in Data.These

Methods

swap :: These a b -> These b a #

Monad m => Channel These (K m :: Type -> Type -> Type) #

Inclusive monoidal structure for K m with These.

Instance details

Defined in Circuit.Channel

Methods

assoc :: K m (These (These a b) c) (These a (These b c)) #

assoc' :: K m (These a (These b c)) (These (These a b) c) #

slide :: K m (These a (These b c)) (These b (These a c)) #

Channel These (->) #

Inclusive monoidal structure for These.

These sits above both (,) and Either: This is the residual-only branch, That is the payload-only branch, and These carries both.

Instance details

Defined in Circuit.Channel

Methods

assoc :: These (These a b) c -> These a (These b c) #

assoc' :: These a (These b c) -> These (These a b) c #

slide :: These a (These b c) -> These b (These a c) #

Monad m => Strength These (K m :: Type -> Type -> Type) #

Inclusive tensorial strength for K m with These.

Instance details

Defined in Circuit.Channel

Methods

strength :: K m b c -> K m (These a b) (These a c) #

Strength These (->) #

Inclusive tensorial strength for These.

strength applies the payload morphism to the That branch and the These branch, leaving the This residual branch untouched.

Instance details

Defined in Circuit.Channel

Methods

strength :: (b -> c) -> These a b -> These a c #

Monad m => Action These (K m :: Type -> Type -> Type) #

Inclusive symmetry on K m.

Instance details

Defined in Circuit.Tensor

Methods

braid :: K m (These a b) (These b a) #

Action These (->) #

Inclusive symmetry on functions.

Instance details

Defined in Circuit.Tensor

Methods

braid :: These a b -> These b a #

Monad m => Tensor These (K m :: Type -> Type -> Type) #

Inclusive tensor action on K m.

Instance details

Defined in Circuit.Tensor

Methods

tensor :: K m a b -> K m c d -> K m (These a c) (These b d) #

Tensor These (->) #

Inclusive tensor action on functions.

Instance details

Defined in Circuit.Tensor

Methods

tensor :: (a -> b) -> (c -> d) -> These a c -> These b d #

Monad m => Unital These (K m :: Type -> Type -> Type) #

Inclusive unit structure on K m.

Instance details

Defined in Circuit.Tensor

Methods

unitl :: K m (These (Unit These) a) a #

unitl' :: K m a (These (Unit These) a) #

unitr :: K m (These a (Unit These)) a #

unitr' :: K m a (These a (Unit These)) #

Unital These (->) #

Inclusive unit structure on functions.

Laws: unitl eliminates a vacuous This, unitl' injects with That; unitr eliminates a vacuous That, unitr' injects with This.

Instance details

Defined in Circuit.Tensor

Methods

unitl :: These (Unit These) a -> a #

unitl' :: a -> These (Unit These) a #

unitr :: These a (Unit These) -> a #

unitr' :: a -> These a (Unit These) #

Generic1 (These a :: Type -> Type) #

Instance details

Defined in Data.These

Associated Types

type Rep1 (These a :: Type -> Type)

Instance details

Defined in Data.These

type Rep1 (These a :: Type -> Type) = D1 ('MetaData "These" "Data.These" "ths-1.2.1-19a91f2e" 'False) (C1 ('MetaCons "This" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: (C1 ('MetaCons "That" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1) :+: C1 ('MetaCons "These" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1)))

Methods

from1 :: These a a0 -> Rep1 (These a) a0 #

to1 :: Rep1 (These a) a0 -> These a a0 #

Eq a => Eq1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftEq :: (a0 -> b -> Bool) -> These a a0 -> These a b -> Bool #

Ord a => Ord1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftCompare :: (a0 -> b -> Ordering) -> These a a0 -> These a b -> Ordering #

Read a => Read1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftReadsPrec :: (Int -> ReadS a0) -> ReadS [a0] -> Int -> ReadS (These a a0) #

liftReadList :: (Int -> ReadS a0) -> ReadS [a0] -> ReadS [These a a0] #

liftReadPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec (These a a0) #

liftReadListPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec [These a a0] #

Show a => Show1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftShowsPrec :: (Int -> a0 -> ShowS) -> ([a0] -> ShowS) -> Int -> These a a0 -> ShowS #

liftShowList :: (Int -> a0 -> ShowS) -> ([a0] -> ShowS) -> [These a a0] -> ShowS #

NFData a => NFData1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftRnf :: (a0 -> ()) -> These a a0 -> () #

Semigroup a => Applicative (These a) #

Instance details

Defined in Data.These

Methods

pure :: a0 -> These a a0 #

(<*>) :: These a (a0 -> b) -> These a a0 -> These a b #

liftA2 :: (a0 -> b -> c) -> These a a0 -> These a b -> These a c #

(*>) :: These a a0 -> These a b -> These a b #

(<*) :: These a a0 -> These a b -> These a a0 #

Functor (These a) #

Instance details

Defined in Data.These

Methods

fmap :: (a0 -> b) -> These a a0 -> These a b #

(<$) :: a0 -> These a b -> These a a0 #

Semigroup a => Monad (These a) #

Instance details

Defined in Data.These

Methods

(>>=) :: These a a0 -> (a0 -> These a b) -> These a b #

(>>) :: These a a0 -> These a b -> These a b #

return :: a0 -> These a a0 #

Foldable (These a) #

Instance details

Defined in Data.These

Methods

fold :: Monoid m => These a m -> m #

foldMap :: Monoid m => (a0 -> m) -> These a a0 -> m #

foldMap' :: Monoid m => (a0 -> m) -> These a a0 -> m #

foldr :: (a0 -> b -> b) -> b -> These a a0 -> b #

foldr' :: (a0 -> b -> b) -> b -> These a a0 -> b #

foldl :: (b -> a0 -> b) -> b -> These a a0 -> b #

foldl' :: (b -> a0 -> b) -> b -> These a a0 -> b #

foldr1 :: (a0 -> a0 -> a0) -> These a a0 -> a0 #

foldl1 :: (a0 -> a0 -> a0) -> These a a0 -> a0 #

toList :: These a a0 -> [a0] #

null :: These a a0 -> Bool #

length :: These a a0 -> Int #

elem :: Eq a0 => a0 -> These a a0 -> Bool #

maximum :: Ord a0 => These a a0 -> a0 #

minimum :: Ord a0 => These a a0 -> a0 #

sum :: Num a0 => These a a0 -> a0 #

product :: Num a0 => These a a0 -> a0 #

Traversable (These a) #

Instance details

Defined in Data.These

Methods

traverse :: Applicative f => (a0 -> f b) -> These a a0 -> f (These a b) #

sequenceA :: Applicative f => These a (f a0) -> f (These a a0) #

mapM :: Monad m => (a0 -> m b) -> These a a0 -> m (These a b) #

sequence :: Monad m => These a (m a0) -> m (These a a0) #

Hashable a => Hashable1 (These a) #

Since: these-1.1.1

Instance details

Defined in Data.These

Methods

liftHashWithSalt :: (Int -> a0 -> Int) -> Int -> These a a0 -> Int #

(Binary a, Binary b) => Binary (These a b) #

Since: these-0.7.1

Instance details

Defined in Data.These

Methods

put :: These a b -> Put #

get :: Get (These a b) #

putList :: [These a b] -> Put #

(NFData a, NFData b) => NFData (These a b) #

Since: these-0.7.1

Instance details

Defined in Data.These

Methods

rnf :: These a b -> () #

(Semigroup a, Semigroup b) => Semigroup (These a b) #

Instance details

Defined in Data.These

Methods

(<>) :: These a b -> These a b -> These a b #

sconcat :: NonEmpty (These a b) -> These a b #

stimes :: Integral b0 => b0 -> These a b -> These a b #

(Eq a, Eq b) => Eq (These a b) #

Instance details

Defined in Data.These

Methods

(==) :: These a b -> These a b -> Bool #

(/=) :: These a b -> These a b -> Bool #

(Ord a, Ord b) => Ord (These a b) #

Instance details

Defined in Data.These

Methods

compare :: These a b -> These a b -> Ordering #

(<) :: These a b -> These a b -> Bool #

(<=) :: These a b -> These a b -> Bool #

(>) :: These a b -> These a b -> Bool #

(>=) :: These a b -> These a b -> Bool #

max :: These a b -> These a b -> These a b #

min :: These a b -> These a b -> These a b #

(Data a, Data b) => Data (These a b) #

Instance details

Defined in Data.These

Methods

gfoldl :: (forall d b0. Data d => c (d -> b0) -> d -> c b0) -> (forall g. g -> c g) -> These a b -> c (These a b) #

gunfold :: (forall b0 r. Data b0 => c (b0 -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (These a b) #

toConstr :: These a b -> Constr #

dataTypeOf :: These a b -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (These a b)) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (These a b)) #

gmapT :: (forall b0. Data b0 => b0 -> b0) -> These a b -> These a b #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> These a b -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> These a b -> r #

gmapQ :: (forall d. Data d => d -> u) -> These a b -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> These a b -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> These a b -> m (These a b) #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> These a b -> m (These a b) #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> These a b -> m (These a b) #

Generic (These a b) #

Instance details

Defined in Data.These

Associated Types

type Rep (These a b)

Instance details

Defined in Data.These

type Rep (These a b) = D1 ('MetaData "These" "Data.These" "ths-1.2.1-19a91f2e" 'False) (C1 ('MetaCons "This" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: (C1 ('MetaCons "That" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b)) :+: C1 ('MetaCons "These" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b))))

Methods

from :: These a b -> Rep (These a b) x #

to :: Rep (These a b) x -> These a b #

(Read a, Read b) => Read (These a b) #

Instance details

Defined in Data.These

Methods

readsPrec :: Int -> ReadS (These a b) #

readList :: ReadS [These a b] #

readPrec :: ReadPrec (These a b) #

readListPrec :: ReadPrec [These a b] #

(Show a, Show b) => Show (These a b) #

Instance details

Defined in Data.These

Methods

showsPrec :: Int -> These a b -> ShowS #

show :: These a b -> String #

showList :: [These a b] -> ShowS #

(Hashable a, Hashable b) => Hashable (These a b) #

Instance details

Defined in Data.These

Methods

hashWithSalt :: Int -> These a b -> Int #

hash :: These a b -> Int #

type Unit These #

Instance details

Defined in Circuit.Tensor

type Unit These = Void

type Rep1 (These a :: Type -> Type) #

Instance details

Defined in Data.These

type Rep1 (These a :: Type -> Type) = D1 ('MetaData "These" "Data.These" "ths-1.2.1-19a91f2e" 'False) (C1 ('MetaCons "This" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: (C1 ('MetaCons "That" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1) :+: C1 ('MetaCons "These" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1)))

type Rep (These a b) #

Instance details

Defined in Data.These

type Rep (These a b) = D1 ('MetaData "These" "Data.These" "ths-1.2.1-19a91f2e" 'False) (C1 ('MetaCons "This" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: (C1 ('MetaCons "That" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b)) :+: C1 ('MetaCons "These" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b))))

Stream coalgebra

class Uncons f s where #

Stream coalgebra with explicit boundary.

uncons [x] = This x announces the final element at extraction. The nil value is the stream-specific empty used to continue after a This result.

Methods

uncons :: f -> These s f #

nil :: f #

Instances

Instances details

Uncons ByteString Word8 Source #
Instance details Defined in Circuit.Parser.Stream Methods uncons :: ByteString -> These Word8 ByteString # nil :: ByteString #
Uncons ByteString Char Source #	Strict `ByteString` as a stream of `Char`. Warning: bytes `>= 0x80` are exposed as raw-byte `Char`s via `toEnum . fromIntegral`, not decoded UTF-8. If you parse text content char-wise and convert to `String` or `Text`, multibyte characters will mojibake. The safe pattern is to recognise structure byte-wise and decode complete spans once (see the json/csv dialects for examples).
Instance details Defined in Circuit.Parser.Stream Methods uncons :: ByteString -> These Char ByteString # nil :: ByteString #
Uncons Text Char Source #
Instance details Defined in Circuit.Parser.Stream Methods uncons :: Text -> These Char Text # nil :: Text #
Uncons [a] a #
Instance details Defined in Circuit.Stream Methods uncons :: [a] -> These a [a] # nil :: [a] #

Parser syntax

newtype Parser (m :: Type -> Type) f (s :: k) a Source #

Parser syntax: a Body (,) f (K m) morphism with the stream f as ambient state, unit input, and These a f output.

Constructors

Parser
Fields unParser :: Body (,) f (K m) () (These a f)

Instances

Instances details

(Monad m, Uncons f s) => Alternative (Parser m f s) Source #
Instance details Defined in Circuit.Parser Methods empty :: Parser m f s a # (<\|>) :: Parser m f s a -> Parser m f s a -> Parser m f s a # some :: Parser m f s a -> Parser m f s [a] # many :: Parser m f s a -> Parser m f s [a] #
(Monad m, Uncons f s) => Applicative (Parser m f s) Source #
Instance details Defined in Circuit.Parser Methods pure :: a -> Parser m f s a # (<>) :: Parser m f s (a -> b) -> Parser m f s a -> Parser m f s b # liftA2 :: (a -> b -> c) -> Parser m f s a -> Parser m f s b -> Parser m f s c # (>) :: Parser m f s a -> Parser m f s b -> Parser m f s b # (<*) :: Parser m f s a -> Parser m f s b -> Parser m f s a #
Monad m => Functor (Parser m f s) Source #
Instance details Defined in Circuit.Parser Methods fmap :: (a -> b) -> Parser m f s a -> Parser m f s b # (<$) :: a -> Parser m f s b -> Parser m f s a #
(Monad m, Uncons f s) => Monad (Parser m f s) Source #
Instance details Defined in Circuit.Parser Methods (>>=) :: Parser m f s a -> (a -> Parser m f s b) -> Parser m f s b # (>>) :: Parser m f s a -> Parser m f s b -> Parser m f s b # return :: a -> Parser m f s a #
(Monad m, Uncons f s) => MonadPlus (Parser m f s) Source #
Instance details Defined in Circuit.Parser Methods mzero :: Parser m f s a # mplus :: Parser m f s a -> Parser m f s a -> Parser m f s a #

Running

runParser :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m (These a f) Source #

Run a parser in the base monad, returning the raw These result.

runParserIdentity :: forall {k} f (s :: k) a. Parser Identity f s a -> f -> These a f Source #

Run a pure parser.

runParserMaybe :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m (Maybe a) Source #

Run a parser and convert the result to Maybe.

runParserError :: forall {k} m f (s :: k) a. Monad m => Parser m f s a -> f -> m a Source #

Run a parser and extract the result, erroring on failure.

Result extraction

asThese :: These a f -> a Source #

Extract value from a parse result, erroring on failure.

asMaybe' :: These a f -> Maybe a Source #

Convert a parse result to Maybe.

asEither :: These a f -> Either f a Source #

Convert a parse result to Either (failure returns Left with the leftover stream).

Primitives

next :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s Source #

Consume and return the next element, or That if the stream is empty.

anyToken :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s Source #

Alias for next.

satisfy :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s s Source #

Consume one element if it satisfies the predicate.

satisfyAscii :: forall (m :: Type -> Type) f. (Monad m, Uncons f Char) => (Char -> Bool) -> Parser m f Char Char Source #

ASCII-only version of satisfy.

char :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s, Eq s) => s -> Parser m f s s Source #

Match a specific element.

string :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s, Eq s) => [s] -> Parser m f s [s] Source #

Match a sequence of elements.

endOfInput :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s () Source #

Succeed only at the end of input.

takeRest :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s f Source #

Consume all remaining input as the value.

skipWhile :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s () Source #

Skip zero or more elements matching the predicate.

Choice

empty :: Alternative f => f a #

The identity of <|>

empty <|> a     == a
a     <|> empty == a

(<|>) :: Alternative f => f a -> f a -> f a infixl 3 #

An associative binary operation

Repetition

many :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s [a] Source #

Zero or more repetitions.

some :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s [a] Source #

One or more repetitions.

optional :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s (Maybe a) Source #

Zero or one repetition.

skipMany :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s () Source #

Skip zero or more repetitions.

count :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Int -> Parser m f s a -> Parser m f s [a] Source #

Parse exactly n occurrences of the given parser.

sepBy :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s b -> Parser m f s [a] Source #

Parse zero or more occurrences separated by a separator. The separator is discarded.

sepBy1 :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s b -> Parser m f s [a] Source #

Parse one or more occurrences separated by a separator. The separator is discarded. Trailing separators are rejected: after a separator, the element parser must succeed. Use try on the separator yourself only if you genuinely want to allow trailing separators.

chainr :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => (a -> b -> b) -> Parser m f s a -> Parser m f s b -> Parser m f s b Source #

Right-fold chain combinator.

Capture

capturedBS :: forall (m :: Type -> Type) a. Monad m => Parser m ByteString Char a -> Parser m ByteString Char (ByteString, a) Source #

Capture the matched ByteString prefix of a successful parse.

Flatparse-era specialty: measure consumed length via B.length on the remainder and take a prefix of the original (cheap for strict ByteString).

bs :: forall (m :: Type -> Type) a. Monad m => Parser m ByteString Char a -> Parser m ByteString Char ByteString Source #

Match a span and return it as a ByteString.

span :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s [s] Source #

Capture a (possibly empty) span of elements satisfying the predicate. The result is the list of captured elements; for zero-copy capture of a ByteString span, prefer bs with skipWhile.

span1 :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => (s -> Bool) -> Parser m f s [s] Source #

Capture a non-empty span of elements satisfying the predicate. Fails if the next element does not satisfy the predicate.

Inspection

peek :: forall (m :: Type -> Type) f s. (Monad m, Uncons f s) => Parser m f s s Source #

Return the next element without consuming the stream. Fails at end of input.

Backtracking

try :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> Parser m f s a Source #

Attempt a parser. If it fails with That, restore the original stream.

This matters for composite alternatives consumed by <|>: a parser that consumes input before failing would otherwise hand the next alternative a partially-consumed stream. Wrap the composite in try when that is possible.

Post-filter

filterP :: forall (m :: Type -> Type) f s a. (Monad m, Uncons f s) => Parser m f s a -> (a -> Bool) -> Parser m f s a Source #

Keep only successes matching the predicate.

Continuation

withOption :: forall (m :: Type -> Type) f s a b. (Monad m, Uncons f s) => Parser m f s a -> (a -> Parser m f s b) -> Parser m f s b -> Parser m f s b Source #

Try a parser with a fallback continuation.

Line endings

lineEnd :: forall (m :: Type -> Type) f. (Monad m, Uncons f Char) => Parser m f Char Char Source #

Match a newline character or succeed at end of input.