+------------------+--------------+-----------------+
| 32 bit timestamp | 32 bit price | 16 bit quantity |
+------------------+--------------+-----------------+

data Trade = Trade
  { timestamp :: !Word32
  , price     :: !Word32
  , qty       :: !Word16
  } deriving (Show)
 

getTrade :: Get Trade
getTrade = do
  timestamp <- getWord32le
  price     <- getWord32le
  quantity  <- getWord16le
  return $! Trade timestamp price quantity
 

getTrade' :: Get Trade
getTrade' = Trade <$> getWord32le <*> getWord32le <*> getWord16le
 

getTrades :: Get [Trade]
getTrades = do
  empty <- isEmpty
  if empty
    then return []
    else do trade <- getTrade
            trades <- getTrades
            return (trade:trades)
 

lazyIOExample :: IO [Trade]
lazyIOExample = do
  input <- BL.readFile "trades.bin"
  return (runGet getTrades input)
 

incrementalExample :: BL.ByteString -> [Trade]
incrementalExample input0 = go decoder input0
  where
    decoder = runGetIncremental getTrade
    go :: Decoder Trade -> BL.ByteString -> [Trade]
    go (Done leftover _consumed trade) input =
      trade : go decoder (BL.chunk leftover input)
    go (Partial k) input                     =
      go (k . takeHeadChunk $ input) (dropHeadChunk input)
    go (Fail _leftover _consumed msg) _input =
      error msg

takeHeadChunk :: BL.ByteString -> Maybe BS.ByteString
takeHeadChunk lbs =
  case lbs of
    (BL.Chunk bs _) -> Just bs
    _ -> Nothing

dropHeadChunk :: BL.ByteString -> BL.ByteString
dropHeadChunk lbs =
  case lbs of
    (BL.Chunk _ lbs') -> lbs'
    _ -> BL.Empty
 

The Get monad

data Get a Source

The lazy input interface

The lazy interface consumes a single lazy ByteString. It's the easiest interface to get started with, but it doesn't support interleaving I/O and parsing, unless lazy I/O is used.

There is no way to provide more input other than the initial data. To be able to incrementally give more data, see the incremental input interface.

runGet :: Get a -> ByteString -> a Source

The simplest interface to run a Get decoder. If the decoder runs into an error, calls fail, or runs out of input, it will call error.

runGetOrFail :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) Source

Run a Get monad and return Left on failure and Right on success. In both cases any unconsumed input and the number of bytes consumed is returned. In the case of failure, a human-readable error message is included as well.

type ByteOffset = Int64 Source

An offset, counted in bytes.

The incremental input interface

The incremental interface gives you more control over how input is provided during parsing. This lets you e.g. interleave parsing and I/O.

The incremental interface consumes a strict ByteString at a time, each being part of the total amount of input. If your decoder needs more input to finish it will return a Partial with a continuation. If there is no more input, provide it Nothing.

Fail will be returned if it runs into an error, together with a message, the position and the remaining input. If it succeeds it will return Done with the resulting value, the position and the remaining input.

data Decoder a Source

A decoder procuced by running a Get monad.

runGetIncremental :: Get a -> Decoder a Source

Run a Get monad. See Decoder for what to do next, like providing input, handling decoder errors and to get the output value. Hint: Use the helper functions pushChunk, pushChunks and pushEndOfInput.

Providing input

pushChunk :: Decoder a -> ByteString -> Decoder a Source

Feed a Decoder with more input. If the Decoder is Done or Fail it will add the input to ByteString of unconsumed input.

   runGetIncremental myParser `pushChunk` myInput1 `pushChunk` myInput2

pushChunks :: Decoder a -> ByteString -> Decoder a Source

Feed a Decoder with more input. If the Decoder is Done or Fail it will add the input to ByteString of unconsumed input.

   runGetIncremental myParser `pushChunks` myLazyByteString

pushEndOfInput :: Decoder a -> Decoder a Source

Tell a Decoder that there is no more input. This passes Nothing to a Partial decoder, otherwise returns the decoder unchanged.

Decoding

skip :: Int -> Get () Source

Skip ahead n bytes. Fails if fewer than n bytes are available.

isEmpty :: Get Bool Source

Test whether all input has been consumed, i.e. there are no remaining undecoded bytes.

bytesRead :: Get Int64 Source

Get the total number of bytes read to this point.

isolate Source

Isolate a decoder to operate with a fixed number of bytes, and fail if fewer bytes were consumed, or more bytes were attempted to be consumed. If the given decoder fails, isolate will also fail. Offset from bytesRead will be relative to the start of isolate, not the absolute of the input.

lookAhead :: Get a -> Get a Source

Run the given decoder, but without consuming its input. If the given decoder fails, then so will this function.

lookAheadM :: Get (Maybe a) -> Get (Maybe a) Source

Run the given decoder, and only consume its input if it returns Just. If Nothing is returned, the input will be unconsumed. If the given decoder fails, then so will this function.

lookAheadE :: Get (Either a b) -> Get (Either a b) Source

Run the given decoder, and only consume its input if it returns Right. If Left is returned, the input will be unconsumed. If the given decoder fails, then so will this function.

label :: String -> Get a -> Get a Source

ByteStrings

getByteString :: Int -> Get ByteString Source

An efficient get method for strict ByteStrings. Fails if fewer than n bytes are left in the input. If n <= 0 then the empty string is returned.

getLazyByteString :: Int64 -> Get ByteString Source

An efficient get method for lazy ByteStrings. Fails if fewer than n bytes are left in the input.

getLazyByteStringNul :: Get ByteString Source

Get a lazy ByteString that is terminated with a NUL byte. The returned string does not contain the NUL byte. Fails if it reaches the end of input without finding a NUL.

getRemainingLazyByteString :: Get ByteString Source

Get the remaining bytes as a lazy ByteString. Note that this can be an expensive function to use as it forces reading all input and keeping the string in-memory.

Decoding words

getWord8 :: Get Word8 Source

Read a Word8 from the monad state

Big-endian decoding

getWord16be :: Get Word16 Source

Read a Word16 in big endian format

getWord32be :: Get Word32 Source

Read a Word32 in big endian format

getWord64be :: Get Word64 Source

Read a Word64 in big endian format

Little-endian decoding

getWord16le :: Get Word16 Source

Read a Word16 in little endian format

getWord32le :: Get Word32 Source

Read a Word32 in little endian format

getWord64le :: Get Word64 Source

Read a Word64 in little endian format

Host-endian, unaligned decoding

getWordhost :: Get Word Source

O(1). Read a single native machine word. The word is read in host order, host endian form, for the machine you're on. On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.

getWord16host :: Get Word16 Source

O(1). Read a 2 byte Word16 in native host order and host endianness.

getWord32host :: Get Word32 Source

O(1). Read a Word32 in native host order and host endianness.

getWord64host :: Get Word64 Source

O(1). Read a Word64 in native host order and host endianess.

Deprecated functions

runGetState :: Get a -> ByteString -> ByteOffset -> (a, ByteString, ByteOffset) Source

DEPRECATED. Provides compatibility with previous versions of this library. Run a Get monad and return a tuple with three values. The first value is the result of the decoder. The second and third are the unused input, and the number of consumed bytes.

remaining :: Get Int64 Source

DEPRECATED. Get the number of bytes of remaining input. Note that this is an expensive function to use as in order to calculate how much input remains, all input has to be read and kept in-memory. The decoder keeps the input as a strict bytestring, so you are likely better off by calculating the remaining input in another way.

getBytes :: Int -> Get ByteString Source

DEPRECATED. Same as getByteString.