README

Ppx Protocol Conv

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

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 toYojson.Safe.t

• Jsonm which serialises toEzjsonm.value

• Xml_light which serialises toXml.xml list

• Msgpack which serialises toMsgpck.t

• Yaml which serialises toYaml.t

Example Usage

open Protocol_convopen Protocol_conv_jsontype a = {  x: int;  y: string [@key "Y"]} [@@deriving protocol ~driver:(module Json) ~flags:(`Mangle Json.mangle)]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.tval a_of_json: Json.t -> aval b_to_json: a -> Json.tval b_of_json: Json.t -> a

a_to_json { x=42; y:"really" }

Evaluates to

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

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

Flags can be specified using the driver argument ~flags. For the json and msgpack drivers, themangle function transforms record label names to be lower camelcase: a_bc_de -> aBcDe and a_bc_de_ -> aBcDe. Beware that this may cause name collisions, which can only be determined at runtime.

Attributes

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

Variant constructors names can also be changed using the[@key <string>] attribute.

Signatures

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

Drivers

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 fromYojson.Safe.t

Options

the Msgpack driver accepts the following options:

Types

Jsonm

Converts to and fromEzjsonm.value. Types and arguments are the same as for the Json implementation.

Msgpack

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

Options

The Msgpack driver accepts the following options:

Types

Yaml

Converts to and fromYaml.value

Types

(*) Expectsabs(round(f) - f) < 0.000001

Custom drivers

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

include Protocol_conv.Runtime.Driver with  type t = ... and  type 'a flags = ...

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

Not supported

• Generalised algebraic datatypes

• Extensible types

• Extensible polymorphic variants

• nativeint

1. dune
2. msgpck>= "1.3"
3. ppx_protocol_conv= "3.1.3"
4. ocaml>= "4.04.0"

1. ounitwith-test
2. sexplibwith-test
3. ppx_sexp_convwith-test
4. msgpckwith-test & < "1.7"

None

None