Pure OCaml Yaml 1.2 reader and writer using Bytesrw
anil.recoil.org
1# Yamlrw
2
3A pure OCaml implementation of YAML 1.2 parsing and emission.
4
5## Features
6
7- **Pure OCaml**: No C bindings, works on all OCaml platforms
8- **YAML 1.2 Compliant**: Full support for the YAML 1.2 specification
9- **High-level API**: JSON-compatible value representation for simple use cases
10- **Low-level Streaming**: Event-based parsing for fine-grained control
11- **Multiple I/O Backends**:
12 - `yamlrw`: Core library with bytesrw-based I/O
13 - `yamlrw-unix`: Unix file and channel operations
14 - `yamlrw-eio`: Eio-based streaming I/O (OCaml 5.0+)
15
16## Installation
17
18```bash
19opam install yamlrw
20# For Eio support:
21opam install yamlrw-eio
22# For Unix support:
23opam install yamlrw-unix
24```
25
26## Quick Start
27
28### Parsing YAML
29
30```ocaml
31let value = Yamlrw.of_string "name: Alice\nage: 30" in
32match value with
33| `O [("name", `String "Alice"); ("age", `Float 30.)] ->
34 print_endline "Parsed successfully"
35| _ ->
36 print_endline "Unexpected structure"
37```
38
39### Emitting YAML
40
41```ocaml
42let yaml = `O [
43 ("name", `String "Bob");
44 ("active", `Bool true);
45 ("tags", `A [`String "developer"; `String "ocaml"])
46] in
47let s = Yamlrw.to_string yaml in
48print_endline s
49(* Output:
50 name: Bob
51 active: true
52 tags:
53 - developer
54 - ocaml
55*)
56```
57
58### Using the Utility Functions
59
60```ocaml
61open Yamlrw.Util
62
63let config = Yamlrw.of_string_exn "
64server:
65 host: localhost
66 port: 8080
67" in
68
69let host = get_string (get "host" (get "server" config)) in
70let port = get_int (get "port" (get "server" config)) in
71Printf.printf "Server: %s:%d\n" host port
72```
73
74## Command-line Tool
75
76The `yamlcat` binary validates and pretty-prints YAML files:
77
78```bash
79yamlcat input.yaml
80```
81
82## Testing
83
84Yamlrw is tested against the official [YAML Test Suite](https://github.com/yaml/yaml-test-suite), a comprehensive collection of YAML test cases.
85
86### Running the Full Test Suite
87
88To run the complete YAML test suite with HTML report generation:
89
901. **Clone the test suite** (one-time setup):
91 ```bash
92 cd tests
93 git clone --depth 1 --branch data https://github.com/yaml/yaml-test-suite
94 cd ..
95 ```
96
972. **Run the tests**:
98 ```bash
99 # Standard tests with HTML report
100 opam exec -- dune build @yaml-test-suite
101
102 # Eio-based tests with HTML report
103 opam exec -- dune build @yaml-test-suite-eio
104 ```
105
106**View the results**:
107- The HTML reports are generated in `_build/default/tests/yaml-test-results.html` and `_build/default/tests/yaml-test-results-eio.html`
108- Open them in a browser to see detailed test results with filtering and search capabilities
109
110### Running Unit Tests
111
112Run the standard unit tests:
113
114```bash
115opam exec -- dune runtest
116```
117
118## API Documentation
119
120Build the documentation with:
121
122```bash
123opam exec -- dune build @doc
124```
125
126## License
127
128ISC License - see [LICENSE.md](LICENSE.md) for details.
129
130Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>