Data.Type.BitRecords.Structure

NamedStructure definition for sequences of bits.

This module provides the core data types and functions for conversion of finite bit sequences from an to conventional (Haskell) data types.

Non-compressed, non-random finite bit sequences generated by programs are usually compositions of bytes and multi byte words, and a ton of Haskell libraries exist for the serialization and deserialization of ByteStrings.

This module allows the definition of a structure i.e. a very simple grammar, which allows functions in this library to read and write single bytes, words and bits.

Also complete bit sequence may be constructed or destructed from and to Haskell types.

Further more, the Record may contain dependent sub-sequences, for example to express Record that precede a length field before a repetitive block data.

Antother example for dependent sequences is fields whose presence depends on flags preceding them.

This library is also designed with zero copying in mind.

It should be emphasized that binary deserialization is not to be confused with binary destructuring. While the former usually involves copying all regular sub sequences from the input to a value of a certain type, the later merely requires to peek into the sequeuence at a certain position and deserializing a sub sequence. The starting position and the interpretation are governed by the strucuture applied to the sequence.

Documentation

data Structure (sizeType :: StructureSizeType) where

Phantom type for structures

Constructors

MkVariableStructure :: Structure VarSize

MkFixStructure :: Structure FixSize

Instances

type PrettyStructure (Anonymous (Name name struct) :: Structure sizeType -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Anonymous (Name name struct) :: Structure sizeType -> Type) = name <:> PrettyStructure struct

type ToPretty (struct :: Extends (Structure sizeType))

Defined in Data.Type.BitRecords.Structure

type ToPretty (struct :: Extends (Structure sizeType)) = PrettyStructure struct

type GetStructureSize (Anonymous (Name name struct))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Anonymous (Name name struct)) = GetStructureSize struct

type GetStructureSize (Record (x ': xs))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record (x ': xs)) = GetStructureSize (Anonymous x) + GetStructureSize (Record xs)

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))]))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))])) = 0

type FixStructure = Structure FixSize

Structures that have statically known fixed size.

type VariableStructure = Structure VarSize

Structures that have no statically known fixed size.

data StructureSizeType

Phantom type indicating that if a Structure has a statically known size.

Constructors

VarSize

FixSize

type family GetStructureSize (t :: Extends (Structure FixSize)) :: Nat

The number of bits that a structure with a predetermined fixed size requires.

Instances

type GetStructureSize EmptyStructure

Defined in Data.Type.BitRecords.Structure

type GetStructureSize EmptyStructure = 0

type GetStructureSize (TypeStructure Bool)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Bool) = 1

type GetStructureSize (TypeStructure Int8)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Int8) = 8

type GetStructureSize (TypeStructure Word8)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Word8) = 8

type GetStructureSize (BitSequence length)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (BitSequence length) = WithValidBitSequenceLength length length

type GetStructureSize (FixSizeStringStructure size)

Defined in Data.Type.BitRecords.Structure.String

type GetStructureSize (FixSizeStringStructure size) = size

type GetStructureSize (Anonymous (Name name struct))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Anonymous (Name name struct)) = GetStructureSize struct

type GetStructureSize (Alias lhs rhs)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Alias lhs rhs) = AliasStructureValidateSize lhs rhs (GetStructureSize lhs)

type GetStructureSize (LiteralStructure (Value s k1 x))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (LiteralStructure (Value s k1 x)) = SizeOf s x

type GetStructureSize (Record (x ': xs))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record (x ': xs)) = GetStructureSize (Anonymous x) + GetStructureSize (Record xs)

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))]))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))])) = 0

type GetStructureSize (ConditionalStructure False l r)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (ConditionalStructure False l r) = GetStructureSize r

type GetStructureSize (ConditionalStructure True l r)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (ConditionalStructure True l r) = GetStructureSize l

type GetStructureSize (IntegerStructure n s e)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (IntegerStructure n s e) = IntegerStructureValidateLength n n

type GetStructureSize (Padded (either literal) struct)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Padded (either literal) struct) = PaddedStructureValidateSize literal struct (GetPaddingSize literal struct + GetStructureSize struct)

type family PrettyStructure (struct :: Extends (Structure sizeType)) :: PrettyType

Support for Pretty Printing Structure Types

Instances

type PrettyStructure EmptyStructure

Defined in Data.Type.BitRecords.Structure

type PrettyStructure EmptyStructure = PrettyEmpty

type PrettyStructure (TypeStructure Bool)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Bool) = ToPretty Bool

type PrettyStructure (TypeStructure Int8)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Int8) = ToPretty Int8

type PrettyStructure (TypeStructure Word8)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Word8) = ToPretty Word8

type PrettyStructure (BitSequence length :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (BitSequence length :: Structure FixSize -> Type) = WithValidBitSequenceLength length (PutStr "BitSequence " <+> PutNat length)

type PrettyStructure (FixSizeStringStructure size :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure.String

type PrettyStructure (FixSizeStringStructure size :: Structure FixSize -> Type) = "FixSizeStringStructure" <:> (PutNat size <++> PutStr "bits")

type PrettyStructure (Anonymous (Name name struct) :: Structure sizeType -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Anonymous (Name name struct) :: Structure sizeType -> Type) = name <:> PrettyStructure struct

type PrettyStructure (Record xs :: Structure sizeType -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Record xs :: Structure sizeType -> Type) = "Record" <:$$--> PrettyRecord xs

type PrettyStructure (Alias lhs rhs :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Alias lhs rhs :: Structure FixSize -> Type) = AliasStructureValidateSize lhs rhs ("Alias" <:$$--> (PrettyStructure lhs <$$> PrettyStructure rhs))

type PrettyStructure (LiteralStructure (Value s k1 x) :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (LiteralStructure (Value s k1 x) :: Structure FixSize -> Type) = "LiteralStructure" <:> Pretty s x

type PrettyStructure (ConditionalStructure False l r :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (ConditionalStructure False l r :: Structure FixSize -> Type) = PrettyStructure r

type PrettyStructure (ConditionalStructure True l r :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (ConditionalStructure True l r :: Structure FixSize -> Type) = PrettyStructure l

type PrettyStructure (IntegerStructure n s e :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (IntegerStructure n s e :: Structure FixSize -> Type) = IntegerStructureValidateLength n (((PutStr "IntegerStructure" <+> PutNat n) <+> If (s == Signed) (PutStr "Signed") (PutStr "Unsigned")) <+> If (e == BE) (PutStr "BE") (PutStr "LE"))

type PrettyStructure (Padded (either literal) struct :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Padded (either literal) struct :: Structure FixSize -> Type) = PrettyParens (PrettyStructure struct) <+> (("padded with" <:> PutNat (GetPaddingSize literal struct)) <+> PutStr "bits.")

data EmptyStructure :: Extends (Structure FixSize)

Empty Structure

Instances

type GetStructureSize EmptyStructure

Defined in Data.Type.BitRecords.Structure

type GetStructureSize EmptyStructure = 0

type PrettyStructure EmptyStructure

Defined in Data.Type.BitRecords.Structure

type PrettyStructure EmptyStructure = PrettyEmpty

data Record :: [Extends (Named (Structure sizeType))] -> Extends (Structure sizeType)

A record is a list of fields, Name Structure composed of a list of other Record in natural order.

Instances

type PrettyStructure (Record xs :: Structure sizeType -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Record xs :: Structure sizeType -> Type) = "Record" <:$$--> PrettyRecord xs

type GetStructureSize (Record (x ': xs))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record (x ': xs)) = GetStructureSize (Anonymous x) + GetStructureSize (Record xs)

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))]))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Record ([] :: [Extends (Named (Structure FixSize))])) = 0

type family (a :: Extends (Named (Structure sizeType))) <> (b :: k) :: Extends (Structure sizeType) where ... infixr 6

Compose Named Structures to a Record.

Equations

a <> (b :: Extends (Named (Structure sizeType))) = Record '[a, b]

a <> (Record xs) = Record (a ': xs)

type family PrettyRecord (xs :: [Extends (Named (Structure sizeType))]) :: PrettyType where ...

Internal function to render Records

Equations

PrettyRecord '[] = PrettyEmpty

PrettyRecord (x ': xs) = (PutStr "-" <+> PrettyStructure (Anonymous x)) <$$> PrettyRecord xs

data BitSequence (length :: Nat) :: Extends (Structure FixSize)

A fixed length sequence of bits.

Instances

type PrettyStructure (BitSequence length :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (BitSequence length :: Structure FixSize -> Type) = WithValidBitSequenceLength length (PutStr "BitSequence " <+> PutNat length)

type GetStructureSize (BitSequence length)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (BitSequence length) = WithValidBitSequenceLength length length

type family WithValidBitSequenceLength (length :: Nat) (out :: k) :: k where ...

Internal function to validate that a BitSequence has a valid length.

Equations

WithValidBitSequenceLength length out = If ((length <=? 64) && (1 <=? length)) out (TypeError (Text "invalid bit sequence length: " :<>: ShowType length))

type family (name :: Symbol) // (length :: Nat) :: Extends (Named (Structure FixSize)) where ... infixr 7

An alias to construct a Named BitSequence with the given number of bits

Equations

name // length = WithValidBitSequenceLength length (Name name (BitSequence length))

data LiteralStructure a :: Extends (Structure FixSize)

A constant, fixed length sequence of bits, generated by a type level LiteralFamily.

Instances

type PrettyStructure (LiteralStructure (Value s k1 x) :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (LiteralStructure (Value s k1 x) :: Structure FixSize -> Type) = "LiteralStructure" <:> Pretty s x

type GetStructureSize (LiteralStructure (Value s k1 x))

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (LiteralStructure (Value s k1 x)) = SizeOf s x

data Padded (literal :: Either j j) (struct :: Extends (Structure FixSize)) :: Extends (Structure FixSize)

Pad a Structure to a structure with a length being a multiple of the length of the literal.

Instances

type PrettyStructure (Padded (either literal) struct :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Padded (either literal) struct :: Structure FixSize -> Type) = PrettyParens (PrettyStructure struct) <+> (("padded with" <:> PutNat (GetPaddingSize literal struct)) <+> PutStr "bits.")

type GetStructureSize (Padded (either literal) struct)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Padded (either literal) struct) = PaddedStructureValidateSize literal struct (GetPaddingSize literal struct + GetStructureSize struct)

type family GetPaddingSize literal (struct :: Extends (Structure FixSize)) :: Nat where ...

Type function calculating the number of padding bits requred to pad struct to a multiple of literal size.

Equations

GetPaddingSize (Value s k (x :: k)) y = (SizeOf s x - (GetStructureSize y `Mod` SizeOf s x)) `Mod` SizeOf s x

type family PaddedStructureValidateSize literal (rhs :: Extends (Structure FixSize)) (out :: k) :: k where ...

Type function to validate that both arguments to Alias have a valid length. The lengths are valid iff the right hand side requires the same amount of bits as the left hand side. If necessary, one can always pad the right hand side to match the left hand side using Padded.

Equations

PaddedStructureValidateSize (Value s k (x :: k)) rhs out = If (SizeOf s x == 0) (TypeError (((Text "Cannot use a literal of size 0: " :<>: ShowType (Value s k (x :: k))) :<>: Text " to pad the structure: ") :<>: ShowType rhs)) out

data Alias :: Extends (Structure FixSize) -> Extends (Structure FixSize) -> Extends (Structure FixSize)

Alias structures, the size of the an alias structure is equal to the size of both elements.

Instances

type PrettyStructure (Alias lhs rhs :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (Alias lhs rhs :: Structure FixSize -> Type) = AliasStructureValidateSize lhs rhs ("Alias" <:$$--> (PrettyStructure lhs <$$> PrettyStructure rhs))

type GetStructureSize (Alias lhs rhs)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (Alias lhs rhs) = AliasStructureValidateSize lhs rhs (GetStructureSize lhs)

type family AliasStructureValidateSize (lhs :: Extends (Structure FixSize)) (rhs :: Extends (Structure FixSize)) (out :: k) :: k where ...

Internal function to validate that both arguments to Alias have a valid length. The lengths are valid iff the right hand side requires the same amount of bits as the left hand side. If necessary, one can always pad the right hand side to match the left hand side using Padded.

Equations

AliasStructureValidateSize lhs rhs out = If (GetStructureSize rhs == GetStructureSize lhs) out (TypeError ((((((((Text "Cannot alias structures of different size " :<>: ShowType rhs) :<>: Text " requires ") :<>: ShowType (GetStructureSize rhs)) :<>: Text " bits, but ") :<>: ShowType lhs) :<>: Text " requires ") :<>: ShowType (GetStructureSize lhs)) :<>: Text " bits."))

Integer Sequences

data TypeStructure :: Type -> Extends (Structure FixSize)

A Wrapper for Haskell types. Users should implement the GetStructureSize and Constructor instances.

Instances

type PrettyStructure (TypeStructure Bool)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Bool) = ToPretty Bool

type PrettyStructure (TypeStructure Int8)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Int8) = ToPretty Int8

type PrettyStructure (TypeStructure Word8)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (TypeStructure Word8) = ToPretty Word8

type GetStructureSize (TypeStructure Bool)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Bool) = 1

type GetStructureSize (TypeStructure Int8)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Int8) = 8

type GetStructureSize (TypeStructure Word8)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (TypeStructure Word8) = 8

type U8 = TypeStructure Word8

An usigned 8-bit integer

type S8 = TypeStructure Int8

A signed 8-bit integer

type FlagStructure = TypeStructure Bool

A single bit structure

data IntegerStructure :: Nat -> Sign -> Endianess -> Extends (Structure FixSize) where

(Structure 'FixSize) holding integral numbers

Constructors

S16LE :: Int16 -> IntegerStructure 16 Signed LE MkFixStructure

S16BE :: Int16 -> IntegerStructure 16 Signed BE MkFixStructure

U16LE :: Word16 -> IntegerStructure 16 Unsigned LE MkFixStructure

U16BE :: Word16 -> IntegerStructure 16 Unsigned BE MkFixStructure

S32LE :: Int32 -> IntegerStructure 32 Signed LE MkFixStructure

S32BE :: Int32 -> IntegerStructure 32 Signed BE MkFixStructure

U32LE :: Word32 -> IntegerStructure 32 Unsigned LE MkFixStructure

U32BE :: Word32 -> IntegerStructure 32 Unsigned BE MkFixStructure

S64LE :: Int64 -> IntegerStructure 64 Signed LE MkFixStructure

S64BE :: Int64 -> IntegerStructure 64 Signed BE MkFixStructure

U64LE :: Word64 -> IntegerStructure 64 Unsigned LE MkFixStructure

U64BE :: Word64 -> IntegerStructure 64 Unsigned BE MkFixStructure

Instances

type PrettyStructure (IntegerStructure n s e :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (IntegerStructure n s e :: Structure FixSize -> Type) = IntegerStructureValidateLength n (((PutStr "IntegerStructure" <+> PutNat n) <+> If (s == Signed) (PutStr "Signed") (PutStr "Unsigned")) <+> If (e == BE) (PutStr "BE") (PutStr "LE"))

type GetStructureSize (IntegerStructure n s e)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (IntegerStructure n s e) = IntegerStructureValidateLength n n

data Endianess

Endianess of an IntegerStructure

Constructors

LE

BE

data Sign

Integer sign of an IntegerStructure

Constructors

Signed

Unsigned

type family IntegerStructureValidateLength (n :: Nat) (out :: k) where ...

Internal function to ensure that the length of an IntegerStructure is 16,32 or 64

Equations

IntegerStructureValidateLength n out = If (n == 16) out (If (n == 32) out (If (n == 64) out (TypeError (Text "Invalid IntegerStructure size: " :<>: ShowType n))))

type U n e = IntegerStructure n Unsigned e

An unsigned integer structure

type S n e = IntegerStructure n Signed e

data ConditionalStructure (condition :: Bool) (ifStruct :: Extends (Structure FixSize)) (elseStruct :: Extends (Structure FixSize)) :: Extends (Structure FixSize)

Conditional structure, since this is equivalent to If this might be removed (TODO)

Instances

type PrettyStructure (ConditionalStructure False l r :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (ConditionalStructure False l r :: Structure FixSize -> Type) = PrettyStructure r

type PrettyStructure (ConditionalStructure True l r :: Structure FixSize -> Type)

Defined in Data.Type.BitRecords.Structure

type PrettyStructure (ConditionalStructure True l r :: Structure FixSize -> Type) = PrettyStructure l

type GetStructureSize (ConditionalStructure False l r)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (ConditionalStructure False l r) = GetStructureSize r

type GetStructureSize (ConditionalStructure True l r)

Defined in Data.Type.BitRecords.Structure

type GetStructureSize (ConditionalStructure True l r) = GetStructureSize l

Structure PrettyType Printing

showStructure :: forall proxy (struct :: Extends (Structure FixSize)). PrettyTypeShow (PrettyStructure struct) => proxy struct -> String

Render struct to a pretty, human readable form. Internally this is a wrapper around ptShow using PrettyStructure.

data BoolProxy (t :: Bool) where

Internal type used for unit tests

Constructors

TrueProxy :: BoolProxy True

FalseProxy :: BoolProxy False

_typeSpecGetStructureSize :: BoolProxy (testBool :: Bool) -> Expect [GetStructureSize U8 `ShouldBe` 8, GetStructureSize EmptyStructure `ShouldBe` 0, GetStructureSize (Record [Name "x" U8, Name "y" U8]) `ShouldBe` 16, GetStructureSize (S 16 BE) `ShouldBe` 16, GetStructureSize (ConditionalStructure testBool (U 32 LE) S8) `ShouldBe` If testBool 32 8, GetStructureSize (("field 1" // 3) <> (("field 2" // 2) <> (("field 3" // 5) <> Name "field 4" (("field 4.1" // 3) <> ("field 4.2" // 6))))) `ShouldBe` 19, GetStructureSize (Alias (BitSequence 4) (LiteralStructure (Bits '[1, 0, 0, 1]))) `ShouldBe` 4, GetStructureSize (Padded (Left (Bits '[1, 0, 1, 0, 1, 0, 1, 0])) (("x" // 1) <> ("y" // 2))) `ShouldBe` 8, GetStructureSize (Padded (Right (Bits '[1, 0, 1, 0, 1, 0, 1, 0])) (Anonymous ("x" // 9))) `ShouldBe` 16, GetStructureSize (Padded (Left (Bits '[1, 0, 1, 0, 1, 0, 1, 0])) (Anonymous ("x" // 22))) `ShouldBe` 24, GetStructureSize (Padded (Right (Bits '[1, 0, 1, 0, 1, 0, 1, 0])) (Anonymous ("x" // 33))) `ShouldBe` 40, GetStructureSize (Padded (Right (To (Sequence Word8 Nat) '[0, 255, 0, 255])) (Anonymous ("x" // 10))) `ShouldBe` 32]

_prettySpec :: String