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

5.2.0.tar.gz
md5=e71abaeffcf8596d49a04acb27e00f24
sha512=b0322030fa81af86cbe7b8b502c743768daf60c73f0219d4ce12b175c9612b1fc34bb10bf2dbbcdf9743ab321157e2ffdd8e3160f92372c7b59785ae87fbbebd

Description

Ppx_protocol_conv generates code to serialize and de-serialize 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) ppx_protocol_conv_xml-light (Xml.xml) ppx_protocol_conv_xmlm (Xmlm.node) ppx_protocol_conv_yaml (Yaml.value)

Published: 05 Aug 2021

README

Ppx Protocol Conv

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

This page contains an simple overview of functionality provided. More information is available in the wiki pages

Table of contents

  1. Features

  2. Examples

  3. Drivers

  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 serializes to Yojson.Safe.t

  • Jsonm which serializes to Ezjsonm.value

  • Msgpack which serializes to Msgpck.t

  • Yaml which serializes to Yaml.t

  • Xml_light which serializes to Xml.xml list

  • Xmlm which serializes to Ezxmlm.node

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_exn: Json.t -> a
val a_of_json: Json.t -> (a, exn) result

val b_to_json: a -> Json.t
val b_of_json_exn: Json.t -> a
val b_of_json: Json.t -> (b, exn) result
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 serializes to Yojson.Safe.t

  • Jsonm which serializes to Ezjsonm.value

  • Msgpack which serializes to Msgpck.t

  • Yaml which serializes to Yaml.t

  • Xml_light which serializes to Xml.xml list

  • Xmlm which serializes to Ezxmlm.node

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

Dependencies (4)

  1. ppxlib >= "0.9.0"
  2. dune >= "1.2"
  3. base >= "v0.14.0" & < "v0.17"
  4. ocaml >= "4.07"

Dev Dependencies (3)

  1. alcotest with-test & >= "0.8.0"
  2. sexplib with-test
  3. ppx_sexp_conv with-test

Conflicts

None

OCaml

Innovation. Community. Security.