[@@deriving sexp]

ppx_sexp_conv is a PPX syntax extension that generates code for converting OCaml types to and from s-expressions, as defined in the =sexplib= library. S-expressions are defined by the following type:

type sexp = Atom of string | List of sexp list

and are rendered as parenthesized lists of strings, e.g. (This (is an) (s expression)).

ppx_sexp_conv fits into the =ppx_deriving= framework, so you can invoke it the same way you invoke any other deriving plug-in. Thus, we can write

type int_pair = (int * int) [@@deriving sexp]

to get two values defined automatically, sexp_of_int_pair and int_pair_of_sexp. If we only want one direction, we can write one of the following.

type int_pair = (int * int) [@@deriving sexp_of]
type int_pair = (int * int) [@@deriving of_sexp]

These sexp-converters depend on having a set of converters for basic values (e.g., int_of_sexp) already in scope. This can be done by writing:

open Sexplib.Std

If you’re using =Core= or =Core_kernel=, you can get the same effect with open Core.Std or open Core_kernel.Std.

It’s also possible to construct converters based on type expressions, i.e.:

[%sexp_of: (int * string) list] [1,"one"; 2,"two"]
|> Sexp.to_string;;
=> "((1 one) (2 two))"

[%sexp_of: (int * string) list] [1,"one"; 2,"two"]
|> [%of_sexp: (int * string) list];;
=> [1,"one"; 2,"two"]

For %sexp_of, we can also omit the conversion of some types by putting underscores for that type name.

[%sexp_of: (int * _) list] [1,"one"; 2,"two"]
|> Sexp.to_string;;
=> "((1 _)(2 _))"  

Conversion rules

In the following, we’ll review the serialization rules for different OCaml types.

Basic types

Basic types are represented as atoms. For numbers like int, int32, int64, float, the string in the atom is what is accepted the standard ocaml functions int_of_string, Int32.of_string, etc. For the types char or string, the string in the atom is respectively a one character string or the string itself.

Lists and arrays

OCaml-lists and arrays are represented as s-expression lists.

Tuples and unit

OCaml tuples are treated as lists of values in the same order as in the tuple. The type unit is treated like a 0-tuple. e.g.:

(3.14, "foo", "bar bla", 27)  =>  (3.14 foo "bar bla" 27)

Options

With options, None is treated as a zero-element list, and Some is treated as a singleton list, as shown below.

None        =>  ()
Some value  =>  (value)

We also support reading options following the ordinary rules for variants i.e.:

None        =>  None
Some value  =>  (Some value)

The rules for variants are described below.

Records

Records are represented as lists of lists, where each inner list is a key-value pair. Each pair consists of the name of the record field (first element), and its value (second element). e.g.:

{ foo = (3,4);
  bar = "some string"; }
=> ((foo (3 4)) (bar "some string"))

Type specifications of records allow the use of a special type sexp_option which indicates that a record field should be optional. e.g.:

type t =
  { x : int option;
    y : int sexp_option;
  } with sexp

The type sexp_option is equivalent to ordinary options, but is treated specially by the code generator. The following examples show how this works.

{ x = Some 1; y = Some 2; } => ((x (1)) (y 2))
{ x = None  ; y = None;   } => ((x ()))

Note that, when present, on optional value is represented as the bare value, rather than explicitly as an option.

The types sexp_list and sexp_array can be used in ways similar to the type sexp_option. They assume the empty list and empty array respectively as default values.

Defaults

More complex default values can be specified explicitly using several constructs, e.g.:

let z_test v = v > 42
type t =
  { x : int [@default 42];
    y : int [@default 3] [@sexp_drop_default];
    z : int [@default 3] [@sexp_drop_if fun x -> x = 3];
  } [@@deriving sexp]

The @default annotation lets one specify a default value to be selected if the field is not specified, when converting from an s-expression. The @sexp_drop_default annotation implies that the field will be dropped when generating the s-expression if the value being serialized is equal to the default according to polymorphic equality. Finally, @sexp_drop_if is like @sexp_drop_default, except that it lets you specify the condition under which the field is dropped.

Variants

Constant constructors in variants are represented as strings. Constructors with arguments are represented as lists, the first element being the constructor name, the rest being its arguments. Constructors may also be started in lowercase in S-expressions, but will always be converted to uppercase when converting from OCaml values.

For example:

type t = A | B of int * float * t with sexp
B (42, 3.14, B (-1, 2.72, A))  =>  (B 42 3.14 (B -1 2.72 A))

The above example also demonstrates recursion in data structures.

Polymorphic variants

Polymorphic variants behave almost the same as ordinary variants. The notable difference is that polymorphic variant constructors must always start with an either lower- or uppercase character, matching the way it was specified in the type definition. This is because OCaml distinguishes between upper and lowercase variant constructors. Note that type specifications containing unions of variant types are also supported by the S-expression converter, for example as in:

type ab = [ `A | `B ] [@@deriving sexp]
type cd = [ `C | `D ] [@@deriving sexp]
type abcd = [ ab | cd ] [@@deriving sexp]

Polymorphic values

There is nothing special about polymorphic values as long as there are conversion functions for the type parameters. e.g.:

type 'a t = A | B of 'a [@@deriving sexp]
type foo = int t [@@deriving sexp]

In the above case the conversion functions will behave as if foo had been defined as a monomorphic version of t with 'a replaced by int on the right hand side.

If a data structure is indeed polymorphic and you want to convert it, you will have to supply the conversion functions for the type parameters at runtime. If you wanted to convert a value of type 'a t as in the above example, you would have to write something like this:

sexp_of_t sexp_of_a v

where sexp_of_a, which may also be named differently in this particular case, is a function that converts values of type 'a to an S-expression. Types with more than one parameter require passing conversion functions for those parameters in the order of their appearance on the left hand side of the type definition.

Opaque values

Opaque values are ones for which we do not want to perform conversions. This may be, because we do not have S-expression converters for them, or because we do not want to apply them in a particular type context. e.g. to hide large, unimportant parts of configurations. To prevent the preprocessor from generating calls to converters, simply apply the qualifier sexp_opaque as if it were a type constructor, e.g.:

type foo = int * stuff sexp_opaque [@@deriving sexp]

Thus, there is no need to specify converters for type stuff, and if there are any, they will not be used in this particular context. Needless to say, it is not possible to convert such an S-expression back to the original value. Here is an example conversion:

(42, some_stuff)  =>  (42 <opaque>)

Exceptions

S-expression converters for exceptions can be automatically registered.

module M = struct
  exception Foo of int [@@deriving sexp]
end

Such exceptions will be translated in a similar way as sum types, but their constructor will be prefixed with the fully qualified module path (here: M.Foo) so as to be able to discriminate between them without problems.

The user can then easily convert an exception matching the above one to an S-expression using sexp_of_exn. User-defined conversion functions can be registered, too, by calling add_exn_converter. This should make it very convenient for users to catch arbitrary exceptions escaping their program and pretty-printing them, including all arguments, as S-expressions. The library already contains mappings for all known exceptions that can escape functions in the OCaml standard library.

Hash tables

The Stdlib’s Hash tables, which are abstract values in OCaml, are represented as association lists, i.e. lists of key-value pairs, e.g.:

((foo 42) (bar 3))

Reading in the above S-expression as hash table mapping strings to integers ((string, int) Hashtbl.t) will map foo to 42 and bar to 3.

Note that the order of elements in the list may matter, because the OCaml-implementation of hash tables keeps duplicates. Bindings will be inserted into the hash table in the order of appearance. Therefore, the last binding of a key will be the “visible” one, the others are “hidden”. See the OCaml documentation on hash tables for details.