A first-order domain specific langage for describing EncCBOR instances. Applying the interpreter encode to a well-typed (Encode w T) always produces a valid encoding for T. Constructing an Encode of type T is just like building a value of type T, applying a constructor of T to the correctly typed arguments. For example

data T = T Bool Word

instance EncCBOR T where
  encCBOR (T b w) = encode (Rec T !> To b !> To w)

Note the similarity of

(T b w) and (T $ b $ w) and (Rec T !> To b !> To w)

Where (!>) is the infx version of ApplyE with the same infixity and precedence as ($). Note how the constructor and each (component, field, argument) is labeled with one of the constructors of Encode, and are combined with the application operator (!>). Using different constructors supports different styles of encoding.

Infix operator version of ApplyE. Has the same infxity and operator precedence as $

Translate a first-order @(Encode w d) domain specific langage program, into an Encoding .

Use encodeDual and decodeDual, when you want to guarantee that a type has both EncCBOR and FromCBR instances.

The type (Decode t) is designed to be dual to (Encode t). It was designed so that in many cases a decoder can be extracted from an encoder by visual inspection. We now give some example of (Decode t) and (Encode t) pairs.

An example with 1 constructor (a record) uses Rec and RecD

In this example, let Int and C have EncCBOR instances.

data C = C { unC :: Text.Text }
instance EncCBOR C where
  encCBOR (C t) = encCBOR t
instance DecCBOR C where
  decCBOR = C $ decCBOR

data B = B { unB :: Text.Text }

data A = ACon Int B C

encodeA :: A -> Encode ('Closed 'Dense) A
encodeA (ACon i b c) = Rec ACon !> To i !> E (encCBOR . unB) b !> To c

decodeA :: Decode ('Closed 'Dense) A
decodeA = RecD ACon From <! D (B <$ decCBOR) <! From

instance EncCBOR A where
  encCBOR = encode . encodeA
instance DecCBOR A where
  decCBOR = decode decodeA

An example with multiple constructors uses Sum, SumD, and Summands.

data N = N1 Int | N2 B Bool | N3 A

encodeN :: N -> Encode 'Open N
encodeN (N1 i)    = Sum N1 0 !> To i
encodeN (N2 b tf) = Sum N2 1 !> E (encCBOR . unB) b !> To tf
encodeN (N3 a)    = Sum N3 2 !> To a

decodeN :: Decode ('Closed 'Dense) N    -- Note each clause has an 'Open decoder,
decodeN = Summands N decodeNx           -- But Summands returns a ('Closed 'Dense) decoder
  where decodeNx 0 = SumD N1 <! From
        decodeNx 1 = SumD N2 D (B <$ decCBOR) <! From
        decodeNx 3 = SumD N3 <! From
        decodeNx k = Invalid k

instance EncCBOR N   where encCBOR x = encode(encodeN x)
instance DecCBOR N where decCBOR = decode decodeN

Two examples using variants of sparse encoding for records, i.e. those datatypes with only one constructor. The Virtual constructor approach using Summands, OmitC, Emit. The Sparse field approach using Keyed, Key and Omit. The approaches work because encoders and decoders don't put fields with default values in the Encoding, and reconstruct the default values on the decoding side. We will illustrate the two approaches using the datatype M

data M = M Int [Bool] Text.Text
  deriving (Show, Typeable)

a0, a1, a2, a3 :: M  -- Some illustrative examples, using things that might be given default values.
a0 = M 0 [] ABC
a1 = M 0 [True] ABC
a2 = M 9 [] ABC
a3 = M 9 [False] ABC

The virtual constructor strategy pretends there are mutiple constructors Even though there is only one. We use invariants about the data to avoid encoding some of the values. Note the use of Sum with virtual constructor tags 0,1,2,3

encM :: M -> Encode 'Open M
encM (M 0 [] t) = Sum M 0 !> OmitC 0 !> OmitC [] !> To t
encM (M 0 bs t) = Sum M 1 !> OmitC 0 !> To bs !> To t
encM (M n [] t) = Sum M 2 !> To n !> OmitC [] !> To t
encM (M n bs t) = Sum M 3 !> To n !> To bs !> To t

decM :: Word -> Decode 'Open M
decM 0 = SumD M <! Emit 0 <! Emit [] <! From  -- The virtual constructors tell which fields have been Omited
decM 1 = SumD M <! Emit 0 <! From <! From     -- So those fields are reconstructed using Emit.
decM 2 = SumD M <! From <! Emit [] <! From
decM 3 = SumD M <! From <! From <! From
decM n = Invalid n

instance EncCBOR M where
  encCBOR m = encode (encM m)

instance DecCBOR M where
  decCBOR = decode (Summands M decM)

The Sparse field approach uses N keys, one for each field that is not defaulted. For example (M 9 [True] (pack "hi"))). Here zero fields are defaulted, so there should be 3 keys. Encoding this example would look something like this.

[TkMapLen 3,TkInt 0,TkInt 9,TkInt 1,TkListBegin,TkBool True,TkBreak,TkInt 2,TkString "hi"]
                  ^key            ^key                                    ^key

So the user supplies a function, that encodes every field, each field must use a unique key, and fields with default values have Omit wrapped around the Key encoding. The user must ensure that there is NOT an Omit on a required field. encM2 is an example.

encM2:: M -> Encode ('Closed 'Sparse) M
encM2 (M n xs t) =
    Keyed M
       !> Omit (== 0) (Key 0 (To n))    -- Omit if n is zero
       !> Omit null (Key 1 (To xs))     -- Omit if xs is null
       !> Key 2 (To t)                  -- Always encode t

To write an Decoder we must pair a decoder for each field, with a function that updates only that field. We use the Field GADT to construct these pairs, and we must write a function, that for each field tag, picks out the correct pair. If the Encode and Decode don't agree on how the tags correspond to a particular field, things will fail.

boxM :: Word -> Field M
boxM 0 = field update0 From
  where
    update0 n (M _ xs t) = M n xs t
boxM 1 = field update1 From
  where
    update1 xs (M n _ t) = M n xs t
boxM 2 = field update2 From
  where
    update2 t (M n xs _) = M n xs t
boxM n = invalidField n

Finally there is a new constructor for Decode, called SparseKeyed, that decodes field keyed sparse objects. The user supplies an initial value and field function, and a list of tags of the required fields. The initial value should have default values and any well type value in required fields. If the encode function (baz above) is encoded properly the required fields in the initial value should always be over overwritten. If it is not written properly, or a bad encoding comes from somewhere else, the intial values in the required fields might survive decoding. The list of required fields is checked.

instance DecCBOR M where
  decCBOR = decode (SparseKeyed
                      TT                        -- ^ Name of the type being decoded
                      (M 0 [] (Text.pack "a"))  -- ^ The default value
                      boxM                      -- ^ The Field function
                      [(2, Stringpart)]         -- ^ The required Fields
                    )

instance EncCBOR M where
  encCBOR m = encode(encM2 m)

Infix form of ApplyD with the same infixity and precedence as ($).

Infix form of ApplyAnn with the same infixity and precedence as ($).

Infix form of ApplyErr with the same infixity and precedence as ($).

Index for record density. Distinguishing (all the fields) from (some of the fields).

Index for a wrapped Coder. Wrapping is necessary for Summands and SparseKeyed.

A Field pairs an update function and a decoder for one field of a Sparse record.

Sparse decode something with a (DecCBOR (Annotator t)) instance A special case of field

Sparse decode something with a (DecCBOR (Annotator t)) instance

Use encodeDual and decodeDual, when you want to guarantee that a type has both EncCBOR and FromCBR instances.

Report an error when a numeric key of the type constructor doesn't match.

Prevent decoding until the Version is at least the provided version.