Page
Library
Module
Module type
Parameter
Class
Class type
Source
mattjbray/ocaml-decoders is an excellent library for writing decoders using decoding combinators. However, writing out decoders by hand for more complicated types can be quite time-intensive.
This library helps by automatically producing the appropriate decoder for a particular type.
There are two primary ways in which this library can be of use. (More details of both follows.)
[@@deriving decoders]
applied to your types.[@@deriving_inline decoders]
applied to your types to generate the implementation in place.opam install ppx_deriving_decoders
The implementation is agnostic to the underlying decoders back-end. The only requirement is the presence of a module with the signature Decoders.Decode.S
as specified in mattjbray/ocaml-decoders, which is aliased to module D
.
E.g., if you wanted to decode using yojson
, you could use
opam install decoders-yojson
Suppose we have the following file:
(* In file foo.ml *)
type bar = Int of int | String of string
To generate a decoder for bar
, first add the preprocessing directive to the appropriate dune file:
(preprocess (pps ppx_deriving_decoders))
Then just add an implementer of Decoders.Decode.S
to the file, aliased to D
, and add the deriving extension:
(* In file foo.ml *)
module D = Decoders_yojson.Safe.Decode
type bar = Int of int | String of string [@@deriving decoders]
After doing this, you will have available in this module a value bar_decoder
of type bar D.decoder
. Then you'll be able to use this decoder freely, e.g.:
let () = assert (
match D.decode_string my_basic_cstr_decoder {|{"Int": [10]}|} with
| Ok b -> b = Int 10
| Error _ -> false
)
Suppose we have the same file again:
(* In file foo.ml *)
type bar = Int of int | String of string
To generate a decoder for bar
, we again first add the preprocessing directive to the appropriate dune file:
(preprocess (pps ppx_deriving_decoders))
We change the file to be
(* In file foo.ml *)
module D = Decoders_yojson.Safe.Decode
type bar = Int of int | String of string [@@deriving_inline decoders]
[@@@deriving.end]
Then, after running dune build --auto-promote
, our file will become:
(* In file foo.ml *)
module D = Decoders_yojson.Safe.Decode
type bar = Int of int | String of string [@@deriving_inline decoders]
let _ = fun (_ : bar) -> ()
let bar_decoder =
let open D in
one_of
[("Int",
(D.field "Int"
(let open D in
let (>>=::) fst rest = uncons rest fst in
D.int >>=:: (fun arg0 -> succeed (Int arg0)))));
("String",
(D.field "String"
(let open D in
let (>>=::) fst rest = uncons rest fst in
D.string >>=:: (fun arg0 -> succeed (String arg0)))))]
let _ = bar_decoder
[@@@deriving.end]
You can now freely remove the deriving attributes, and edit the decoder as you see fit!
The following file:
(* In file foo.ml *)
module D = Decoders_yojson.Safe.Decode
type expr = Num of int | BinOp of op * expr * expr
and op = Add | Sub | Mul | Div
[@@@deriving.end]
after invoking dune build --auto-promote
will yield:
(* In file foo.ml *)
module D = Decoders_yojson.Safe.Decode
type expr = Num of int | BinOp of op * expr * expr
and op = Add | Sub | Mul | Div
[@@deriving decoders] [@@deriving_inline decoders]
let _ = fun (_ : expr) -> ()
let _ = fun (_ : op) -> ()
[@@@ocaml.warning "-27"]
let expr_decoder op_decoder =
D.fix
(fun expr_decoder_aux ->
let open D in
one_of
[("Num",
(D.field "Num"
(let open D in
let (>>=::) fst rest = uncons rest fst in
D.int >>=:: (fun arg0 -> succeed (Num arg0)))));
("BinOp",
(D.field "BinOp"
(let open D in
let (>>=::) fst rest = uncons rest fst in
op_decoder >>=::
(fun arg0 ->
expr_decoder_aux >>=::
(fun arg1 ->
expr_decoder_aux >>=::
(fun arg2 ->
succeed (BinOp (arg0, arg1, arg2))))))))])
let _ = expr_decoder
let op_decoder op_decoder =
let open D in
one_of
[("Add",
(D.string >>=
((function | "Add" -> succeed Add | _ -> fail "Failure"))));
("Sub",
(D.string >>=
((function | "Sub" -> succeed Sub | _ -> fail "Failure"))));
("Mul",
(D.string >>=
((function | "Mul" -> succeed Mul | _ -> fail "Failure"))));
("Div",
(D.string >>=
((function | "Div" -> succeed Div | _ -> fail "Failure"))))]
let _ = op_decoder
let op_decoder = D.fix op_decoder
let _ = op_decoder
let expr_decoder = expr_decoder op_decoder
let _ = expr_decoder
[@@@ocaml.warning "+27"]
[@@@deriving.end]
Notice that the mutual recursion is handled for you!
There are a lot of rough edges in places like:
loc
Contributions are always welcome. Please create an issue as appropriate, and open a PR into the main
branch and I'll have a look :)