package ppx_protocol_conv

  1. Overview
  2. Docs
Ppx for generating serialisation and de-serialisation functions of ocaml types

Install

Dune Dependency

Authors

Maintainers

Sources

4.0.0.tar.gz
md5=fea7b25f51a02d5170ed52146f151c6f
sha512=f9bffcac11fd7b690d924b204747783bc912e655c36f5be00dc9bd63a781e0c9f4723f6c4a732566c6b1760375ccc53098de0119958223c4293fd0c714b2bf5f

Description

Ppx_protocol_conv generates code to serialise and de-serialise types. The ppx itself does not contain any protocol specific code, but relies on 'drivers' that defines serialisation and de-serialisation of basic types and structures.

Pre-defined drivers are available in separate packages: ppx_protocol_conv_json (Yojson.Safe.json) ppx_protocol_conv_jsonm (Ezjson.value) ppx_protocol_conv_msgpack (Msgpck.t)(Xml.xml) ppx_protocol_conv_xml-light (Xml.xml) ppx_protocol_conv_yaml (Yaml.t)

Published: 26 Mar 2019

README

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
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

Dependencies (4)

  1. ppxlib >= "0.3.0" & < "0.9.0"
  2. dune
  3. base < "v0.12"
  4. ocaml >= "4.04"

Dev Dependencies (3)

  1. ounit with-test
  2. sexplib with-test & < "v0.12"
  3. ppx_sexp_conv with-test & < "v0.12"

Conflicts

None

OCaml

Innovation. Community. Security.