Yamlrw#

A pure OCaml implementation of YAML 1.2 parsing and emission.

Features#

Pure OCaml: No C bindings, works on all OCaml platforms
YAML 1.2 Compliant: Full support for the YAML 1.2 specification
High-level API: JSON-compatible value representation for simple use cases
Low-level Streaming: Event-based parsing for fine-grained control
Multiple I/O Backends:
- yamlrw: Core library with bytesrw-based I/O
- yamlrw-unix: Unix file and channel operations
- yamlrw-eio: Eio-based streaming I/O (OCaml 5.0+)

Installation#

opam install yamlrw
# For Eio support:
opam install yamlrw-eio
# For Unix support:
opam install yamlrw-unix

Quick Start#

Parsing YAML#

let value = Yamlrw.of_string "name: Alice\nage: 30" in
match value with
| `O [("name", `String "Alice"); ("age", `Float 30.)] ->
    print_endline "Parsed successfully"
| _ ->
    print_endline "Unexpected structure"

Emitting YAML#

let yaml = `O [
  ("name", `String "Bob");
  ("active", `Bool true);
  ("tags", `A [`String "developer"; `String "ocaml"])
] in
let s = Yamlrw.to_string yaml in
print_endline s
(* Output:
   name: Bob
   active: true
   tags:
     - developer
     - ocaml
*)

Using the Utility Functions#

open Yamlrw.Util

let config = Yamlrw.of_string_exn "
server:
  host: localhost
  port: 8080
" in

let host = get_string (get "host" (get "server" config)) in
let port = get_int (get "port" (get "server" config)) in
Printf.printf "Server: %s:%d\n" host port

Command-line Tool#

The yamlcat binary validates and pretty-prints YAML files:

yamlcat input.yaml

Testing#

Yamlrw is tested against the official YAML Test Suite, a comprehensive collection of YAML test cases.

Running the Full Test Suite#

To run the complete YAML test suite with HTML report generation:

Clone the test suite (one-time setup):

cd tests
git clone --depth 1 --branch data https://github.com/yaml/yaml-test-suite
cd ..

Run the tests:

# Standard tests with HTML report
opam exec -- dune build @yaml-test-suite

# Eio-based tests with HTML report
opam exec -- dune build @yaml-test-suite-eio

View the results:

The HTML reports are generated in _build/default/tests/yaml-test-results.html and _build/default/tests/yaml-test-results-eio.html
Open them in a browser to see detailed test results with filtering and search capabilities

Running Unit Tests#

Run the standard unit tests:

opam exec -- dune runtest

API Documentation#

Build the documentation with:

opam exec -- dune build @doc

License#

ISC License - see LICENSE.md for details.

Clone this repository