Data.Packer

Simple packing module.

This is a tradeoff between a more pure / builder (binary, cereal, builder) and direct access to Storable or pointer manipulation

Types

data Packing a

Packing monad

Instances

Monad Packing

Functor Packing

Applicative Packing

MonadIO Packing

data Unpacking a

Unpacking monad

Instances

Monad Unpacking

Functor Unpacking

Applicative Unpacking

Alternative Unpacking

MonadIO Unpacking

data OutOfBoundUnpacking

Exception when trying to get bytes out of the memory bounds.

Constructors

OutOfBoundUnpacking Int Int

Instances

Eq OutOfBoundUnpacking

Data OutOfBoundUnpacking

Show OutOfBoundUnpacking

Exception OutOfBoundUnpacking

data OutOfBoundPacking

Exception when trying to put bytes out of the memory bounds.

Constructors

OutOfBoundPacking Int Int

Instances

Eq OutOfBoundPacking

Data OutOfBoundPacking

Show OutOfBoundPacking

Exception OutOfBoundPacking

data IsolationNotFullyConsumed

Exception when isolate doesn't consume all the bytes passed in the sub unpacker

Constructors

IsolationNotFullyConsumed Int Int

Instances

Eq IsolationNotFullyConsumed

Data IsolationNotFullyConsumed

Show IsolationNotFullyConsumed

Exception IsolationNotFullyConsumed

data Hole a

A Hole represent something that need to be filled later, for example a CRC, a prefixed size, etc.

They need to be filled before the end of the package, otherwise an exception will be raised.

Main methods

runUnpacking :: Unpacking a -> ByteString -> a

Unpack a bytestring using a monadic unpack action.

tryUnpacking :: Unpacking a -> ByteString -> Either SomeException a

Similar to runUnpacking but returns an Either type with an exception type in case of failure.

runPacking :: Int -> Packing a -> ByteString

Run packing with a buffer created internally with a monadic action and return the bytestring

runPackingRes :: Int -> Packing a -> (a, ByteString)

Run packing with a buffer created internally with a monadic action and return the bytestring

Unpacking functions

unpackSkip :: Int -> Unpacking ()

Skip bytes

unpackSetPosition :: Int -> Unpacking ()

Set the new position from the beginning in the memory block. This is useful to skip bytes or when using absolute offsets from a header or some such.

unpackGetPosition :: Unpacking Int

Get the position in the memory block.

getWord8 :: Unpacking Word8

Get a Word8

getWord16 :: Unpacking Word16

Get a Word16 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord16LE :: Unpacking Word16

Get a Word16 serialized in little endian.

getWord16BE :: Unpacking Word16

Get a Word16 serialized in big endian.

getWord32 :: Unpacking Word32

Get a Word32 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord32LE :: Unpacking Word32

Get a Word32 serialized in little endian.

getWord32BE :: Unpacking Word32

Get a Word32 serialized in big endian.

getWord64 :: Unpacking Word64

Get a Word64 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when unserializing format.

getWord64LE :: Unpacking Word64

Get a Word64 serialized in little endian.

getWord64BE :: Unpacking Word64

Get a Word64 serialized in big endian.

getBytes :: Int -> Unpacking ByteString

Get a number of bytes in bytestring format.

The original block of memory is expected to live for the life of this bytestring, and this is done so by holding the original ForeignPtr.

getBytesCopy :: Int -> Unpacking ByteString

Similar to getBytes but copy the bytes to a new bytestring without making reference to the original memory after the copy. this allow the original block of memory to go away.

getBytesWhile :: (Word8 -> Bool) -> Unpacking (Maybe ByteString)

Get a number of bytes until in bytestring format.

this could be made more efficient

getRemaining :: Unpacking ByteString

Get the remaining bytes.

getRemainingCopy :: Unpacking ByteString

Get the remaining bytes but copy the bytestring and drop any reference from the original function.

getStorable :: Storable a => Unpacking a

Get an arbitrary type with the Storable class constraint.

The Storage method for sizeOf need to be constant size related to the type. It cannot use any fields to define its size.

The sizeOf method is always going to be called with undefined, so make sure sizeOf doesn't need the value of the type.

getFloat32LE :: Unpacking Float

Read a Float in little endian IEEE-754 format

getFloat32BE :: Unpacking Float

Read a Float in big endian IEEE-754 format

getFloat64LE :: Unpacking Double

Read a Double in little endian IEEE-754 format

getFloat64BE :: Unpacking Double

Read a Double in big endian IEEE-754 format

isolate :: Int -> Unpacking a -> Unpacking a

Isolate N bytes from the unpacking, and create an isolated context where only those N bytes are available.

If the sub unpacker doesn't consume all the bytes available, this function will raises an exception

endOfInput :: Unpacking Bool

Return True if there are no more bytes to be unpacked.

No input is consumed.

countRemaining :: Unpacking Int

Return the number of bytes remaining in the current Unpacking.

No input is consumed.

Packing functions

packGetPosition :: Packing Int

Get the position in the memory block.

putWord8 :: Word8 -> Packing ()

Put a Word8

putHoleWord8 :: Packing (Hole Word8)

Put a Word8 Hole

putWord16 :: Word16 -> Packing ()

Put a Word16 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord16LE :: Word16 -> Packing ()

Put a Word16 serialized in little endian.

putWord16BE :: Word16 -> Packing ()

Put a Word16 serialized in big endian.

putHoleWord16 :: Packing (Hole Word16)

Put a Word16 Hole in host endian

putHoleWord16LE :: Packing (Hole Word16)

Put a Word16 Hole in little endian

putHoleWord16BE :: Packing (Hole Word16)

Put a Word16 Hole in big endian

putWord32 :: Word32 -> Packing ()

Put a Word32 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord32LE :: Word32 -> Packing ()

Put a Word32 serialized in little endian.

putWord32BE :: Word32 -> Packing ()

Put a Word32 serialized in big endian.

putHoleWord32 :: Packing (Hole Word32)

Put a Word32 Hole in host endian

putHoleWord32LE :: Packing (Hole Word32)

Put a Word32 Hole in little endian

putHoleWord32BE :: Packing (Hole Word32)

Put a Word32 Hole in big endian

putWord64 :: Word64 -> Packing ()

Put a Word64 in the host endianess.

It's recommended to use an explicit endianness (LE or BE) when serializing format.

putWord64LE :: Word64 -> Packing ()

Put a Word64 serialized in little endian.

putWord64BE :: Word64 -> Packing ()

Put a Word64 serialized in big endian.

putHoleWord64 :: Packing (Hole Word64)

Put a Word64 Hole in host endian

putHoleWord64LE :: Packing (Hole Word64)

Put a Word64 Hole in little endian

putHoleWord64BE :: Packing (Hole Word64)

Put a Word64 Hole in big endian

putBytes :: ByteString -> Packing ()

Put a Bytestring.

putStorable :: Storable a => a -> Packing ()

Put an arbitrary type with the Storable class constraint.

putFloat32LE :: Float -> Packing ()

Write a Float in little endian IEEE-754 format

putFloat32BE :: Float -> Packing ()

Write a Float in big endian IEEE-754 format

putFloat64LE :: Double -> Packing ()

Write a Double in little endian IEEE-754 format

putFloat64BE :: Double -> Packing ()

Write a Double in big endian IEEE-754 format

fillHole :: Hole a -> a -> Packing ()

Fill a hole with a value

TODO: user can use one hole many times leading to wrong counting.