Encoding of binary data.

The type class Encodable captures all the types that can be encoded into a stream of bytes. For a user defined type say Foo, defining an instance Encodable is all that is required to make use of encode and decode for any of the supported encoding formats (i.e. instances of the class Format).

Minimum complete definition for this class is toByteString and fromByteString. Instances of EndianStore have default definitions for both these functions and hence a trivial instance declaration is sufficient for such types.

newtype Foo = Foo (LE Word64) deriving (Storable, EndianStore)

instance EndianStore Foo where
  ...

instance Encodable Foo

In particular, all the endian encoded versions of Haskell's word, i.e types like LE Word32, LE Word64 etc, are instances of Encodable. Note that the corresponding plain type is not an instance of Encodable because encoding of say Word32 without specifying whether the endianness is meaningless.

Laws for encoding

Note that not all byte strings can be valid encodings and fromByteString might fail and return Nothing on certain inputs. However, we require the minimum guarantee that fromByteString for actual encodings of elements, i.e. we require the instances to satisfy the law.

fromByteString . toByteString = Just

TODO: Write test cases for encoding laws.

A binary format is a representation of binary data often in printable form. We distinguish between various binary formats at the type level and each supported format corresponds to an instance of the the class Format. The encodeByteString and decodeFormat are required to satisfy the laws

decodeFormat . encodeByteString = id

For type safety, the formats themselves are opaque types and hence it is not possible to obtain the underlying binary data directly. We require binary formats to be instances of the class Encodable, with the combinators toByteString and fromByteString of the Encodable class performing the actual encoding and decoding.

Instances of Format are required to be instances of Show and so that the encoded format can be easily printed. They are also required to be instances of IsString so that they can be easily represented in Haskell source using the OverloadedStrings extension. However, be careful when using this due to the fact that invalid encodings can lead to runtime errors.

Encode in a given format.

Decode from a given format. It results in Nothing if there is a parse error.

Translate from one format to another.

The unsafe version of decode.

The type corresponding to base-16 or hexadecimal encoding. The Base16 encoding has a special place in this library: most cryptographic types use Base16 encoding for their Show and IsString instance. The combinators fromBase16 and showBase16 are exposed mainly to make these definitions easy.

Base16 variant of fromString. Useful in definition of IsString instances as well as in cases where the default IsString instance does not parse from a base16 encoding.

Base16 variant of show.

The type corresponding to the standard padded base-64 binary encoding.