[ANN] ppx_deriving_yaml 0.1.0

Hi :wave:

I’m proud to announce the first release (and my first release) of ppx_deriving_yaml. If you are familiar with the excellent ppx_deriving_yojson then this library should come as no surprise. In fact it helped me a lot in writing this ppx, so thank you to its creators/maintainers.

Installation

$ opam update 
$ opam install ppx_deriving_yaml

Usage

Ppx_deriving_yaml converts your OCaml types to the “basic” OCaml Yaml value type (the one that is currently compatible with ezjsonm). So for example you can have:

type t = { title: string; authors: string list } [@@deriving yaml]

let () = 
  let v = { title = "Yaml PPX!"; authors = [ "Patrick Ferris" ] } in 
  let yaml = to_yaml v in 
  Yaml.pp Format.std_formatter yaml;
  match of_yaml yaml with 
    | Ok t -> Format.print_string t.title 
    | Error (`Msg m) -> failwith m

The ppx generates two functions:

val of_yaml : Yaml.value -> t Yaml.res 
val to_yaml : t -> Yaml.value

And when built with this dune file:

(executable
 (name main)
 (libraries yaml)
 (preprocess
  (pps ppx_deriving_yaml)))

The following output is generated:

title: Yaml PPX!     
authors:
- Patrick Ferris
Yaml PPX!

The README contains some more information and the library is still a little rough around the edges, especially with error reporting, but I’m currently using it in a few places such as an “ocaml-ified” github actions library (ppx_deriving_yaml’s test workflow was automatically generated with it :sparkles:). This is a nice example of how it can be used in a fairly straightforward way to generate OCaml versions of the many projects that use Yaml for configuration files.

Happy yaml-ing :slight_smile:

24 Likes

A new 0.2.0 version has just been released. Thanks to all the contributors (including Outreachy applicants!), there’s a lot of nice additions including:

  • to_yaml and of_yaml attributes allowing you to add custom encoders and decoders
  • a skip_unknown flag for ignoring yaml keys so you can partially decode yaml values
  • a default attribute
  • [@@deriving yaml] is now an alias to [@@deriving to_yaml] and [@@ deriving of_yaml] so you can get decoders, encoders or both.

See the documentation in the README: GitHub - patricoferris/ppx_deriving_yaml: OCaml types to Yaml types and back again

3 Likes

A new 0.2.2 version has just been PRed to the opam-repository. It changes the ppx to embed errors in the AST following the guidance in the excellent ppxlib documentation: ppxlib 0.31.0 (latest) · OCaml Package. Hopefully this makes the ppx a little more user-friendly with tools like Merlin and friends.

There was a 0.2.1 version a while back which added support for recursive type definitions too.

Happy Yaml-ing !

3 Likes