package ppx_protocol_conv

Ppx Protocol Conv

Ppx protocol conv (de)serialisers using deriving, which allows for plugable (de)serialisers. Api.

Table of contents

1. Features

2. Examples

3. Drivers

   1. Json

   2. Jsonm

   3. Msgpack

   4. Yaml

   5. Xml_light

4. Custom drivers

5. Not supported

Features

The ppx supports the following features:

• records

• recursive and non-recursive types

• variants

• polymophic variants

• All primitive types (except nativeint)

The following drivers exists

• Json which serialises to Yojson.Safe.t

• Jsonm which serialises to Ezjsonm.value

• Msgpack which serialises to Msgpck.t

• Yaml which serialises to Yaml.t

• Xml_light which serialises to Xml.xml list

Examples

open Protocol_conv_json
type a = {
  x: int;
  y: string [@key "Y"]
  z: int list [@default [2;3]]
} [@@deriving protocol ~driver:(module Json)]

type b = A of int
       | B of int [@key "b"]
       | C
[@@deriving protocol ~driver:(module Json)]

will generate the functions:

val a_to_json: a -> Json.t
val a_of_json: Json.t -> a

val b_to_json: a -> Json.t
val b_of_json: Json.t -> a

a_to_json { x=42; y:"really"; z:[6;7] }

Evaluates to

[ "x", `Int 42; "Y", `String "really"; "z", `List [ `Int 6; `Int 7 ] ] (* Yojson.Safe.json *)

to_protocol deriver will generate serilisation of the type. of_protocol deriver generates de-serilisation of the type, while protocol deriver will generate both serilisation and de-serilisation functions.

Attributes

Record label names can be changed using [@key <string>]

Variant and polymorphic variant constructors names can be changed using the [@name <string>] attribute.

If a record field is not present in the input when deserialising, as default value can be assigned using [@default <expr>]. If the value to be serialized matches the default value, the field will be omitted (Some drivers allow disabling this functonality. Comparrison uses polymorphic compare, so be careful.

Signatures

The ppx also handles signature, but disallows [@key ...], [@default ...] and [@name] .... as these does not impact signatures.

Drivers

Drivers specify concrete serialization and deserialization. Users of the library can elect to implement their own driver see custom drivers, or use predefined drivers:

• Json which serialises to Yojson.Safe.t

• Jsonm which serialises to Ezjsonm.value

• Msgpack which serialises to Msgpck.t

• Yaml which serialises to Yaml.t

• Xml_light which serialises to Xml.xml list

Notes on type mappings

All included driver allow for the identity mapping by using the <driver>.t type, i.e.:

type example = {
  json: Json.t; (* This has type Yojson.Safe.t *)
}

Json

Maps to and from Yojson.Safe.t. Package ppx_protocol_conv_json

Options

Standard options mimics that of ppx_deriving_yojson, except that Constructors without arguments are serialized to a string rather than a list.

To set options to create output compatible with ppx_deriving_yojson use

module Json = Json.Make(
  struct
    let field_name str = str
    let singleton_constr_as_string = false
    let omit_default_values: true
  end)

See Parameters for a description of possible options.

Types

Notes

Serialization differs from ppx_deriving_yojson when serializing in that constructors without arguments are serialized to strings, rather than a list. Constructors with arguments are serialized to lists.

This allows for deserialising a string directly into a ADT:

type country = Denmark | France
and t = {
  name: string;
  country: country;
}  [@@deriving protocol ~driver:(module Json)]

{ name = "Anders"; country = Denmark } |> to_json |> Yojson.Safe.to_string

produces: { "name": "Anders", "country": "Denmark" }

Jsonm

Converts to and from Ezjsonm.value. Types and arguments are the same as for the Json implementation. Package ppx_protocol_conv_jsonm

Msgpack

Msgpack driver maps to and from Msgpck.t. To allow more finegrained control over generated type, the msgpack module defines extra types. See table in #types section. Package ppx_protocol_conv_msgpack

Options

The module Also provides means for chaning default attribute behaviour and record field naming convensions, by using the functor Msgpack.Make(P:Parameters)

Types

Yaml

Converts to and from Yaml.value Package ppx_protocol_conv_yaml

Options

The module Also provides means for chaning default attribute behaviour and record field naming convensions, by using the functor Yaml.Make(P:Parameters)

Types

(*) Expects abs(round(f) - f) < 0.000001

Xml_light

Converts to and from Xml_light.xml. The serialization is implemented to be compatible with the xml returned from Amazon S3 api, and the implementation is feature complete, and the implementation tries to produce as slim xml as possible.

Package ppx_protocol_conv_xml_light

Custom drivers

It is easy to provide custom drivers by implementing the signature:

include Protocol_conv.Runtime.Driver with
  type t = ...

See the drivers directory for examples on how to implemented new drivers. Submissions of new drivers are more than welcome.

Not supported

• Generalised algebraic datatypes

• Extensible types

• Extensible polymorphic variants

• nativeint