YAML 1.2 codec
README.md

nox-yaml #

Warning. This is a work-in-progress experimental fork of ocaml-yamlrw. Do not use it in production; use ocaml-yamlrw instead.

Type-safe YAML 1.2 codecs for OCaml.

Many configuration files are YAML, including Kubernetes manifests and CI pipelines. (Kubernetes runs containers on a cluster of machines, and each manifest is a YAML document describing one resource it should create, such as a deployment with its image and number of replicas.) A program that reads such a file usually decodes it into a generic tree and converts each field by hand, and its error messages rarely say where in the file the problem is. With this library you write the mapping once, as a value of type 'a Yaml.codec, and use it to decode and to encode. The combinators follow the design of jsont. The nox-toml and nox-json libraries have the same shape, so a codec looks alike in all three.

The parser reads from a string or a bytesrw reader, and the emitter writes to a string or a bytesrw writer. One YAML stream can hold several documents separated by ---, or none, so the decoders return a list.

Libraries #

  • nox-yaml has the value type, the codec combinators, the parser and the emitter, all in the Yaml module.
  • nox-yaml.json, module Yaml_json, turns a Json.Codec.t from nox-json into a YAML codec, so that one description covers both formats.

Installation #

$ opam install nox-yaml

The package may not be in the public opam-repository yet. If opam cannot find it, add the overlay repository first:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-yaml

For an Eio flow, use bytesrw-eio to wrap it as a bytesrw reader or writer, then call Yaml.of_reader or Yaml.to_writer.

Usage #

A codec gives the shape of the YAML and the OCaml value it maps to. Here example is Ok of a list that holds one service:

type service = { hostname : string; port : int }

let service_codec =
  let open Yaml.Codec in
  Mapping.(
    map (fun hostname port -> { hostname; port })
    |> mem "hostname" string ~enc:(fun s -> s.hostname)
    |> mem "port" int ~enc:(fun s -> s.port)
    |> seal)

let example =
  Yaml.of_string service_codec "hostname: localhost\nport: 8080"

License #

ISC. See LICENSE.md.