Parser.Lathe

Pure incremental byte parser.

Laziness

Parser functions that return concrete types in this library fully evaluate their results before returning unless their documentation specifies otherwise.

Itself

data Parser e a

The parser type, parametrized by an error type e and a return type a.

Note that there is no Alternative instance for this parser, see instead catch.

Instances

Applicative (Parser e)

Defined in Parser.Lathe.Internal

Methods

pure :: a -> Parser e a

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

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

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

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

Functor (Parser e)

Defined in Parser.Lathe.Internal

Methods

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

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

Monad (Parser e)

Defined in Parser.Lathe.Internal

Methods

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

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

return :: a -> Parser e a

Run

Immediate

type ByteOffset = Int64

An offset, counted in bytes.

data More

Whether more input can be supplied.

Constructors

More

Can prompt for more state.

End

End has been reached.

Instances

Show More

Defined in Parser.Lathe.Internal

Methods

showsPrec :: Int -> More -> ShowS

show :: More -> String

showList :: [More] -> ShowS

Eq More

Defined in Parser.Lathe.Internal

Methods

(==) :: More -> More -> Bool

(/=) :: More -> More -> Bool

data Scrap

Remaining bits of state.

Constructors

Scrap

Fields

• !ByteOffset

  Number of bytes consumed.

• !ByteString

  Remaining input.

• !More

  Whether more input could still be requested.

Instances

Show Scrap

Defined in Parser.Lathe.Internal

Methods

showsPrec :: Int -> Scrap -> ShowS

show :: Scrap -> String

showList :: [Scrap] -> ShowS

parse :: Parser e a -> ByteString -> (Scrap, Either e a)

Run a parser by providing all of the input immediately.

Incremental

data Blank

Internal processing state.

data Result a

Final parsing outcome.

Constructors

Result

Fields

• ByteString

  Remaining unconsumed input.

• !ByteOffset

  Total number of bytes consumed.

• a

Instances

Functor Result

Defined in Parser.Lathe.Internal

Methods

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

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

Show a => Show (Result a)

Defined in Parser.Lathe.Internal

Methods

showsPrec :: Int -> Result a -> ShowS

show :: Result a -> String

showList :: [Result a] -> ShowS

data Resupply

Providing additional input to the decoder.

Constructors

Supply !ByteString

A chunk of the input. It should not be empty.

N.B.: Lazy ByteStrings have an internal "no empty chunks" invariant. While this parser does not malfunction when encountering an empty chunk, it does not purge empty chunks and will faithfully relay them in lazy ByteStrings it produces. This may in turn break downstream consumers.

EndOfInput

data Partial a

Intermediate parsing outcome.

Constructors

Partial (Resupply -> Partial a)

Done a

Instances

Functor Partial

Defined in Parser.Lathe.Internal

Methods

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

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

Show a => Show (Partial a)

Defined in Parser.Lathe.Internal

Methods

showsPrec :: Int -> Partial a -> ShowS

show :: Partial a -> String

showList :: [Partial a] -> ShowS

prepare

Arguments

:: ByteOffset

Initial byte offset.

-> ByteString

First chunk of the stream. It may be empty.

-> ByteString

Rest of the known stream.

-> More

Whether more input can be requested.

-> Blank

Define the initial parser state.

draw :: Parser e a -> Blank -> Partial (Blank, Either e a)

Run a parser incrementally.

scrap :: Blank -> Scrap

Convert excess input into readable form.

Manage

bytesRead :: Parser never ByteOffset

Get the total number of bytes read to this point.

atEnd :: Parser never Bool

Test whether all input has been consumed.

Err

err :: e -> Parser e a

Fail with the given error.

mapError :: (e -> Either x a) -> Parser e a -> Parser x a

Modify the error type, or forget an error.

catch :: Parser e a -> (e -> Parser x a) -> Parser x a

Execute the left parser; should an error occur, backtrack and execute the right parser.

References to all new input chunks consumed by the left parser are kept until it completes.

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

Execute the supplied parser, returning the slice of input consumed in the process alongside the result.

References to all new input chunks consumed by the supplied parser are kept until it completes.

Parse

No output

skip1 :: end -> Parser end ()

Skip ahead 1 byte.

skip :: Int64 -> end -> Parser end ()

Skip ahead \(n\) bytes.

Does nothing if \(n \le 0\).

skipNul :: end -> Parser end ()

Skip ahead until a NUL byte is reached (inclusive).

skipUntil :: (Word8 -> Bool) -> end -> Parser end ()

Skip ahead until the predicate holds (exclusive).

Optional

skipEndOr1 :: Parser never ()

Skip ahead 1 byte or do nothing.

skipEndOr :: Int64 -> Parser never ()

Skip ahead \(n\) or fewer bytes.

Does nothing if \(n \le 0\).

skipUntilEndOr :: (Word8 -> Bool) -> Parser never ()

Skip ahead until either the end is reached or the predicate holds (exclusive).

Strict ByteString

byteString :: Int -> end -> Parser end ByteString

Consume \(n\) bytes into a strict ByteString.

Returns an empty string if \(n \le 0\).

byteStringNul :: end -> Parser end ByteString

Consume input into a strict ByteString until a NUL byte (inclusive) is reached. The returned string does not contain the NUL byte.

byteStringUntil :: (Word8 -> Bool) -> end -> Parser end ByteString

Consume input into a strict ByteString until the predicate holds (exclusive).

Short ByteString

shortByteString :: Int -> end -> Parser end ShortByteString

Consume \(n\) bytes into a ShortByteString.

Returns an empty string if \(n \le 0\).

shortByteStringNul :: end -> Parser end ShortByteString

Consume input into a ShortByteString until a NUL byte (inclusive) is reached. The returned string does not contain the NUL byte.

shortByteStringUntil :: (Word8 -> Bool) -> end -> Parser end ShortByteString

Consume input into a ShortByteString until the predicate holds (exclusive).

Lazy ByteString

lazyByteString :: Int -> end -> Parser end ByteString

Consume \(n\) bytes into a lazy ByteString.

Returns an empty string if \(n \le 0\).

lazyByteStringNul :: end -> Parser end ByteString

Consume input into a lazy ByteString until a NUL byte (inclusive) is reached. The returned string does not contain the NUL byte.

lazyByteStringUntil :: (Word8 -> Bool) -> end -> Parser end ByteString

Consume input into a lazy ByteString until the predicate holds (exclusive).

lazyByteStringRest :: Parser never ByteString

Consume all remaining input into a lazy ByteString.