craigfe / ppx_irmin

OCaml PPX extension for automatically generating Irmin types

ppx_irmin (ARCHIVED)

This repository has been upstreamed to mirage/irmin.

PPX extension for automatically generating Irmin generics.

Overview

ppx_irmin automatically generates Irmin generics (values of type _ Irmin.Type.t) corresponding to type declarations in your code. For example:

type tree =
  | Branch of tree * bool option * tree
  | Leaf of int32 * string [@@deriving irmin]

will be expanded to:

type tree = (* as above *)

let tree_t =
  let open Irmin.Type in
  mu (fun tree_t ->
      variant "tree" (fun branch leaf -> function
          | Branch (x1, x2, x3) -> branch (x1, x2, x3)
          | Leaf   (x1, x2)     -> leaf (x1, x2))
      |~ case1 "Branch" (triple tree_t (option bool) tree_t) (fun (x1, x2, x3) -> Branch (x1, x2, x3))
      |~ case1 "Leaf"   (pair int32 string)                  (fun (x1, x2) -> Leaf (x1, x2))
      |> sealv)

Installation and usage

You can install ppx_irmin using opam:

$ git clone [email protected]:CraigFe/ppx_irmin
$ opam pin --yes ./ppx_irmin

If you're using the dune build system, add the following field to your library, executable or test stanza:

(preprocess (pps ppx_irmin))

You can now use [@@deriving irmin] after a type declaration in your code to automatically derive an Irmin generic with the same name.

Specifics

ppx_irmin supports all of the type combinators exposed in the Irmin.Type module (basic types, records, variants (plain and closed polymorphic), recursive types etc.). Irmin types must fully grounded (no polymorphic type variables).

Naming scheme

The generated generics will be called <type-name>_t, unless the type-name is t, in which case the generic is simply t. This behaviour can be overridden using the name argument, as in:

type foo = string list * int32 [@@deriving irmin { name = "foo_generic" }]

(* generates the value *)
val foo_generic = Irmin.Type.(pair (list string) int32)

If the type references another user-defined type, ppx_irmin will expect the generic for that type to use the standard naming scheme. This can be overridden using the [@generic ...] attribute, as in:

type bar = (foo [@generic foo_generic], string) result [@@deriving irmin]

(* generates the value *)
val bar_t = Irmin.Type.(result foo_generic string)

Signature type definitions

The ppx_irmin deriver can also be used in signatures to expose the auto-generated value:

module Contents : sig
  type t = int32 [@@deriving irmin]

  (* exposes generic in signature *)
  val t : t Irmin.Type.t

end = struct
  type t = int32 [@@deriving irmin]

  (* generates generic value *)
  val t = Irmin.Type.int32
end

ppx_irmin's Issues

User-defined witnesses in Json module are shadowed

Because of the global open of Irmin.Type in the deriver, any user-defined witnesses in a Json module will be shadowed by the Irmin.Type.Json module.

module Json = struct
  include Yojson.Safe
  let t = Irmin.Type.(map string) from_string to_string
end

type bench_data = {
  uuid: Uuidm.t;
  data: Json.t
} [@@deriving irmin]

gives

32 | ..type bench_data = {
33 |     uuid: Uuidm.t;
34 |     data: Json.t
35 |   } [@@deriving irmin]
Error: Unbound value Json.t

Polymorphic variant support

It would be great to support polymorphic variants, if possible 😄

Type qualified by structure name not supported

When trying to use ppx_irmin with a type qualified with a structure name I get an error. Here's a simple example to reproduce the error:

module X = struct
  type t = int [@@deriving irmin]
end

type t = X.t [@@deriving irmin]

Here's an example stack trace:

Fatal error: exception (Invalid_argument unsupported)
Raised at file "stdlib.ml", line 34, characters 20-45
Called from file "ppx_irmin/lib/deriver.ml", line 277, characters 23-85
Called from file "src/list.ml", line 333, characters 13-17
Called from file "src/list.ml" (inlined), line 361, characters 15-31
Called from file "src/deriving.ml" (inlined), line 48, characters 32-43
Called from file "src/deriving.ml", line 195, characters 4-89
Called from file "src/list.ml", line 333, characters 13-17
Called from file "src/list.ml" (inlined), line 361, characters 15-31
Called from file "src/deriving.ml" (inlined), line 48, characters 32-43
Called from file "src/deriving.ml", line 199, characters 4-62
Called from file "src/deriving.ml", line 610, characters 6-63
Called from file "src/context_free.ml", line 325, characters 27-66
Called from file "list.ml", line 117, characters 24-34
Called from file "src/context_free.ml", line 563, characters 14-76
Called from file "src/context_free.ml", line 586, characters 23-37
Called from file "src/driver.ml", line 175, characters 17-30
Called from file "src/driver.ml", line 395, characters 16-19
Called from file "list.ml", line 117, characters 24-34
Called from file "src/list0.ml" (inlined), line 22, characters 40-81
Called from file "src/driver.ml", line 385, characters 2-642
Called from file "src/driver.ml", line 466, characters 4-219
Called from file "src/migrate_parsetree_driver.ml", line 249, characters 21-60
Called from file "src/migrate_parsetree_driver.ml", line 255, characters 4-82
Called from file "src/driver.ml", line 853, characters 53-82
Called from file "src/driver.ml", line 1248, characters 6-24
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Re-raised at file "parsing/location.ml", line 494, characters 14-25
Called from file "parsing/location.ml" (inlined), line 499, characters 31-61
Called from file "src/driver.ml", line 1251, characters 4-59

ppx_irmin is otherwise super helpful and allows getting rid of a lot of boilerplate! It would be great to expand the amount of types supported.

Support mutually recursive types

Currently mutually recursive types such as this one are unsupported:

type odd = Odd of even option
and even = Even of odd option [@@deriving irmin]

However, it's possible to encode these types using the mu2 combinator presented by Irmin. We should support deriving such encodings.