package sexp_decode
Install
Dune Dependency
Authors
Maintainers
Sources
md5=55cd3a54d076831d680b33a9caf27a3b
sha512=f9e1936165aa3a8536ba05ddfe7bfdbe63ce1e7a8162b8e8246e5debd581e5f1b3bc935a43f6ed6b5a931219de8185a2e71a072af4a2bf8bdda78bea46808b95
README.md.html
Sexp_decode
Sexp_decode
is a library of monadic combinators for decoding S-expressions (as defined in the Csexp library) into structured data.
Important remark: the current API is well suited to the complete parsing of S-expressions. Partial parsing (e.g., parsing only some fields of an S-expression encoded record) is doable, but remains convoluted with the current API.
Example
The purpose of the library is to help the translation of S-expressions into structured data.
For example, you may want to transform an address book encoded as an S-expression into structured data, that is easier to process.
Let's assume your address book looks like the following:
open Sexp_decode
let address_book : sexp =
List
[
List
[
Atom "entry";
List [ Atom "name"; Atom "John Doe" ];
List [ Atom "country"; Atom "New Zealand" ];
];
List
[
Atom "entry";
List [ Atom "name"; Atom "Mary Poppins" ];
List [ Atom "email"; Atom "umbrella@imaginary-domain.uk" ];
];
List
[
Atom "entry";
List [ Atom "name"; Atom "Groot" ];
List [ Atom "country"; Atom "Groot" ];
];
]
A representation as an OCaml value that is probably easier to work with, is by using the following entry
type:
type entry =
{ name : string; country : string option; email : string option }
type address_book = entry list
It is easy to define decoders that produce values of types entry
and address_book
:
let entry_decoder : entry decoder =
field "entry"
@@ let* name = field "name" atom in
let* country = maybe @@ field "country" atom in
let+ email = maybe @@ field "email" atom in
{ name; country; email }
let address_book_decoder : address_book decoder = list entry_decoder
Then, you can execute the run
function, that has type 'a decoder -> sexp -> 'a option
. It produces the following result on our address_book
example:
let result = run address_book_decoder address_book
(* result =
Some
[{name = "John Doe"; country = Some "New Zealand"; email = None};
{name = "Mary Poppins"; country = None;
email = Some "umbrella@imaginary-domain.uk"};
{name = "Groot"; country = Some "Groot"; email = None}]
*)
In addition to the field
, maybe
, atom
and list
decoders, the Sexp_decode
library provides combinators to build compound decoders from basic ones, and compose them together. In particular, decoders for variants and records are provided.
For example, with the fields
combinator, you could define entry_decoder
as follows:
let entry_decoder_alt : entry decoder =
field "entry"
@@ fields
~default:{ name = ""; country = None; email = None }
[
("name", atom >>| fun name entry -> { entry with name });
("country", atom >>| fun country entry -> { entry with country = Some country });
("email", atom >>| fun email entry -> { entry with email = Some email });
]
With this alternative decoder for entries, the fields "name"
"country"
and "email"
might occur in any order, and any number of times.
How to install the library
Sexp_decode
is available on opam
and can be installed with the following command:
opam install sexp_decode
Alternatively, you can install the development version as follows:
git clone https://gitlab.inria.fr/bmontagu/sexp_decode.git
cd sexp_decode
opam pin add .
Author: Benoît Montagu benoit.montagu@inria.fr
Copyright Inria 2022