ppx_protocol_conv

Ppx for generating serialisation and de-serialisation functions of ocaml types
README

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

| Ocaml type | Generates | Accepts |
|--------------------|---------------|---------------|
| string, char,bytes | `String | `String |
| int, int32, int64 | `Int | `Int |
| float | `Float | `Float |
| bool | `Bool | `Bool |
| unit | `List [] | `List [] |
| 'a list, 'a array | `List 'a list| `List 'a list |
| 'a option | `Null or 'a | `Null or 'a |
| 'a ref, lazy 'a | 'a | 'a |
| Json.t | Yojson.Safe.t | Yojson.Safe.t |

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

| Ocaml type | Generates | Accepts |
|--------------------|---------------|-----------------------------------|
| string | String | String, Bytes |
| bytes | Bytes | String, Bytes |
| char | String | String, Bytes |
| int | Int | Int, Int32, Int64, Uint32, Uint64 |
| int32 | Int32 | Int32 |
| int64 | Int64 | Int64 |
| float | Float64 | Float64, Float32 |
| unit | List [] | List [] |
| bool | Bool | Bool |
| 'a list, 'a array | List 'a list | `List 'a list |
| 'a option | Nil or 'a | Nil or 'a |
| 'a ref, lazy 'a | 'a | 'a |
| Msgpack.uint32 | Uint32 | Uint32 |
| Msgpack.uint64 | Uint64 | Uint64 |
| Msgpack.bytes | Bytes | Bytes, String |
| Msgpack.float32 | Float32 | Float32 |
| Msgpack.t | MsgPck.t | MsgPck.t |

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

| Ocaml type | Generates | Accepts |
|---------------------|---------------|-----------|
| string, char, bytes | `String | `String |
| int,int32,int64 | `Float | `Float* |
| float | `Float | `Float |
| bool | `Bool | `Boolt |
| unit | `List [] | `List [] |
| 'a list, 'a array | `List 'a list| `List 'a list |
| 'a option | `Null or 'a | `Null or 'a |
| 'a ref, lazy 'a | 'a | 'a |
| Yaml.t | Yaml.t | Yaml.t |

(*) 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

Install
Sources
4.0.0.tar.gz
md5=fea7b25f51a02d5170ed52146f151c6f
sha512=f9bffcac11fd7b690d924b204747783bc912e655c36f5be00dc9bd63a781e0c9f4723f6c4a732566c6b1760375ccc53098de0119958223c4293fd0c714b2bf5f
Dependencies
ounit
with-test
sexplib
with-test & < "v0.12"
ppx_sexp_conv
with-test & < "v0.12"
ppxlib
>= "0.3.0" & < "0.9.0"
base
< "v0.12"
ocaml
>= "4.04"
Reverse Dependencies