Data.Serialize.Get

The Get monad. A monad for efficiently building structures from strict ByteStrings

The Get type

data Get a

The Get monad is an Exception and State monad.

Instances

Monad Get

Functor Get

MonadPlus Get

Applicative Get

Alternative Get

runGet :: Get a -> ByteString -> Either String a

Run the Get monad applies a get-based parser on the input ByteString

runGetLazy :: Get a -> ByteString -> Either String a

Run the Get monad over a Lazy ByteString. Note that this will not run the Get parser lazily, but will operate on lazy ByteStrings.

runGetState :: Get a -> ByteString -> Int -> Either String (a, ByteString)

Run the Get monad applies a get-based parser on the input ByteString. Additional to the result of get it returns the number of consumed bytes and the rest of the input.

runGetLazyState :: Get a -> ByteString -> Either String (a, ByteString)

Run the Get monad over a Lazy ByteString. Note that this does not run the Get parser lazily, but will operate on lazy ByteStrings.

data Result r

The result of a parse.

Constructors

Fail String

The parse failed. The String is the message describing the error, if any.

Partial (ByteString -> Result r)

Supply this continuation with more input so that the parser can resume. To indicate that no more input is available, use an empty string.

Done r ByteString

The parse succeeded. The ByteString is the input that had not yet been consumed (if any) when the parse succeeded.

Instances

Functor Result

Show r => Show (Result r)

runGetPartial :: Get a -> ByteString -> Result a

Run the Get monad applies a get-based parser on the input ByteString

Parsing

ensure :: Int -> Get ByteString

If at least n bytes of input are available, return the current input, otherwise fail.

isolate :: Int -> Get a -> Get a

Isolate an action to operating within a fixed block of bytes. The action is required to consume all the bytes that it is isolated to.

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

skip :: Int -> Get ()

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

uncheckedSkip :: Int -> Get ()

Skip ahead n bytes. No error if there isn't enough bytes.

lookAhead :: Get a -> Get a

Run ga, but return without consuming its input. Fails if ga fails.

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

Like lookAhead, but consume the input if gma returns 'Just _'. Fails if gma fails.

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

Like lookAhead, but consume the input if gea returns 'Right _'. Fails if gea fails.

uncheckedLookAhead :: Int -> Get ByteString

Get the next up to n bytes as a ByteString, without consuming them.

Utility

getBytes :: Int -> Get ByteString

Pull n bytes from the input, as a strict ByteString.

remaining :: Get Int

Get the number of remaining unparsed bytes. Useful for checking whether all input has been consumed.

WARNING: when run with runGetPartial, remaining will only return the number of bytes that are remaining in the current input.

isEmpty :: Get Bool

Test whether all input has been consumed.

WARNING: when run with runGetPartial, isEmpty will only tell you if you're at the end of the current chunk.

Parsing particular types

getWord8 :: Get Word8

Read a Word8 from the monad state

ByteStrings

getByteString :: Int -> Get ByteString

An efficient get method for strict ByteStrings. Fails if fewer than n bytes are left in the input. This function creates a fresh copy of the underlying bytes.

getLazyByteString :: Int64 -> Get ByteString

Big-endian reads

getWord16be :: Get Word16

Read a Word16 in big endian format

getWord32be :: Get Word32

Read a Word32 in big endian format

getWord64be :: Get Word64

Read a Word64 in big endian format

Little-endian reads

getWord16le :: Get Word16

Read a Word16 in little endian format

getWord32le :: Get Word32

Read a Word32 in little endian format

getWord64le :: Get Word64

Read a Word64 in little endian format

Host-endian, unaligned reads

getWordhost :: Get Word

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

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

getWord32host :: Get Word32

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

getWord64host :: Get Word64

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

Containers

getTwoOf :: Get a -> Get b -> Get (a, b)

getListOf :: Get a -> Get [a]

Get a list in the following format: Word64 (big endian format) element 1 ... element n

getIArrayOf :: (Ix i, IArray a e) => Get i -> Get e -> Get (a i e)

Get an IArray in the following format: index (lower bound) index (upper bound) Word64 (big endian format) element 1 ... element n

getTreeOf :: Get a -> Get (Tree a)

Read as a list of lists.

getSeqOf :: Get a -> Get (Seq a)

Get a sequence in the following format: Word64 (big endian format) element 1 ... element n

getMapOf :: Ord k => Get k -> Get a -> Get (Map k a)

Read as a list of pairs of key and element.

getIntMapOf :: Get Int -> Get a -> Get (IntMap a)

Read as a list of pairs of int and element.

getSetOf :: Ord a => Get a -> Get (Set a)

Read as a list of elements.

getIntSetOf :: Get Int -> Get IntSet

Read as a list of ints.

getMaybeOf :: Get a -> Get (Maybe a)

Read in a Maybe in the following format: Word8 (0 for Nothing, anything else for Just) element (when Just)

getEitherOf :: Get a -> Get b -> Get (Either a b)

Read an Either, in the following format: Word8 (0 for Left, anything else for Right) element a when 0, element b otherwise