Codec.Libevent

Tagged data structures are an extensible way of serialising data in a platform independent way for transmission across a network etc. This package implements the tagged structures from libevent 1.4.0-beta.

A tagged structure is described in a text file and might look like this:

 struct foo {
   required int count = 1;
   optional struct[bar] names = 2;
 }

 struct bar {
   repeated string s = 1;
 }

The numbers after the equals signs are the tag numbers for each element of a structure. The tag numbers must be unique within a structure and should be sequenctial (but are not required to be).

The tag numbers must also be fixed for all time. When deserialising, unknown tags are ignored. Thus one can add a new (non-required) element to foo in the future and still interoperate with older code which knows nothing of the new element.

Each element in the description looks like:

 <presence> <type> <name> = <tag number> ;

The possible presence values are: required, optional and repeated. The types are (currently): int, string, struct[NAME] and bytes.

Other modules in this package parse these descriptions and automatically generate Haskell code for them. You should have a binary called codec-libevent-generate which does this. See the documentation for Codec.Libevent.Generate about the structure of the generated code.

Once you have generated the code, you can import it as a regular Haskell module and serialise/deserialise these structures. You can also use the libevent library to process them in C.

This module contains helper functions and is imported by the code generated by Codec.Libevent.Generate. Apart from the TaggedStructure class, there's probably not anything generally useful here.

Documentation

getBase128 :: Get Word32

Decode a base128 encoded integer. This is a variable length encoded int where the last byte has the MSB set to 0.

putBase128 :: Word32 -> Put

Encode a integer in Base128 form

getLengthPrefixed :: Get Word32

Decode a number where the first nibble of the first byte is the number of nibbles in the number. The remaining nibbles appear in little-endian order following, with 0 padding to the nearest byte.

nibbleLength :: Word32 -> Int

Return the number of nibbles, n, required to encode a given number. n >= 1

putLengthPrefixed :: Word32 -> Put

Encode a Word32 by prefixing the number of nibbles and following with the nibbles of the number in little-endian order

lengthPrefixedLength :: Word32 -> Int

Return the length of the length-prefixed representation of a Word32

putTaggedWord32 :: Word32 -> Word32 -> Put

putTaggedString :: Word32 -> String -> Put

putTaggedVarBytes :: Word32 -> ByteString -> Put

decodeString :: ByteString -> String