Raaz.Core.Transfer

Transfer actions.

type Transfer t = SemiR (TransferAction t) (BYTES Int)

An element of type `Tranfer t m` is an action which when executed transfers bytes into or out of its input buffer. The type Transfer t m forms a monoid and hence can be concatenated using the <> operator.

type ReadFrom = Transfer 'ReadFromBuffer

The ReadFrom is the type that captures the act of reading from a buffer and possibly doing some action on the bytes read. Although inaccurate, it is helpful to think of elements of ReadFromM as action that on an input buffer transfers data from it to some unspecified source.

ReadFrom actions form a monoid with the following semantics: if r1 and r2 are two read actions then r1 <> r2 first reads the the data associated with r1 and then reads the data associated with r2.

type WriteTo = Transfer 'WriteToBuffer

The Write is the type that captures the act of writing to a buffer. Although inaccurate, it is helpful to think of elements of Write as source of bytes of a fixed size.

Write actions form a monoid with the following semantics: if w1 and w2 are two write actions then w1 <> w2 first writes the data associated from w1 and then the writes the data associated with w2.

consume :: EndianStore a => (a -> IO b) -> ReadFrom

Reads a from the buffer and supplies it to the action. The value read is independent of the endianness of the underlying.

consumeStorable :: Storable a => (a -> IO b) -> ReadFrom

Similar to consume but does not take care of adjusting for endianness. Use therefore limited to internal buffers.

consumeParse :: Parser a -> (a -> IO b) -> ReadFrom

Given a parser p :: Parser a for parsing a and act :: a -> m b consuming a, consumeParse p act, gives a reader that parses a from the input buffer passing it to the action act.

writeEncodable :: Encodable a => a -> WriteTo

Write any encodable elements

write :: EndianStore a => a -> WriteTo

The expression write a gives a write action that stores a value a. One needs the type of the value a to be an instance of EndianStore. Proper endian conversion is done irrespective of what the machine endianness is. The man use of this write is to serialize data for the consumption of the outside world.

writeStorable :: Storable a => a -> WriteTo

The expression writeStorable a gives a write action that stores a value a in machine endian. The type of the value a has to be an instance of Storable. This should be used when we want to talk with C functions and not when talking to the outside world (otherwise this could lead to endian confusion). To take care of endianness use the write combinator.

writeVector :: (EndianStore a, Vector v a) => v a -> WriteTo

The vector version of write.

writeStorableVector :: (Storable a, Vector v a) => v a -> WriteTo

The vector version of writeStorable.

writeBytes

Arguments

:: LengthUnit n

=> Word8

Byte to write

-> n

How much to write

-> WriteTo

The combinator writeBytes b n writes b as the next n consecutive bytes.

padWrite

Arguments

:: LengthUnit n

=> Word8

the padding byte to use

-> n

the length to align message to

-> WriteTo

the message that needs padding

-> WriteTo

The write action padWrite w n wr is wr padded with the byte w so that the total length ends at a multiple of n.

prependWrite

Arguments

:: LengthUnit n

=> Word8

the byte to pre-pend with.

-> n

the length to align the message to

-> WriteTo

the message that needs pre-pending

-> WriteTo

The write action prependWrite w n wr is wr pre-pended with the byte w so that the total length ends at a multiple of n.

glueWrites

Arguments

:: LengthUnit n

=> Word8

The bytes to use in the glue

-> n

The length boundary to align to.

-> WriteTo

The header write

-> WriteTo

The footer write

-> WriteTo

The combinator glueWrites w n hdr ftr is equivalent to hdr <> glue <> ftr where the write glue writes just enough bytes w so that the total length is aligned to the boundary n.

writeByteString :: ByteString -> WriteTo

Writes a strict bytestring.

transferSize :: Transfer t -> BYTES Int

Returns the bytes that will be written when the write action is performed.

skip :: LengthUnit l => l -> Transfer t

The transfer skip l skip ahead by an offset l. If it is a read, it does not read the next l positions. If it is a write it does not mutate the next l positions.