My own corner of monopam
Fix nox-toml/nox-yaml docs and propagate nox-json through hermest
Doc review surfaced five issues; this commit addresses all of them.
nox-toml/doc/index.mld:
- Drop the dead {!Toml_jsont} library reference. The toml-test JSON
bridge lives only in test_json/ as a private test helper, not as a
public library.
- Correct the design note: codecs are 'a Toml.codec (alias for
'a Toml.Codec.t), not 'a Toml.t (which is the value type).
nox-toml/doc/cookbook.mld:
- The recursive-codec example called Toml.Codec.rec'; the actual API
is Toml.Codec.fix. Fix the page so copy-pasted examples compile.
nox-yaml/doc/: didn't exist. Add a Quick Start / Library Structure /
Design landing page mirroring nox-toml's, with a (documentation ...)
stanza so odoc actually picks it up.
READMEs: update both nox-toml and nox-yaml to use the post-rename
package names ('opam install nox-toml', 'nox-toml.eio', etc.) so users
following the README don't get a missing-package error.
hermest: the lexicon code generator was hard-coded to emit
'(libraries atp json)' in every generated dune.inc, which dune
re-promotes on each build — undoing any manual rename. Update the
emitter to write 'nox-json' and re-promote the four atp/scitt
lexicon dune.inc files. Without this fix, dune build @install hits
'Library "json" not found' inside lexicon subtrees.
+94
-27
+2
-1
ocaml-atp/hermest/bin/main.ml
+2
-1
ocaml-atp/hermest/bin/main.ml
+1
-1
ocaml-atp/lexicons/atproto/dune.inc
+1
-1
ocaml-atp/lexicons/atproto/dune.inc
+1
-1
ocaml-atp/lexicons/bsky/dune.inc
+1
-1
ocaml-atp/lexicons/bsky/dune.inc
+1
-1
ocaml-atp/lexicons/standard-site/dune.inc
+1
-1
ocaml-atp/lexicons/standard-site/dune.inc
+1
-1
ocaml-atp/lexicons/tangled/dune.inc
+1
-1
ocaml-atp/lexicons/tangled/dune.inc
+1
-1
ocaml-scitt/lexicons/dune.inc
+1
-1
ocaml-scitt/lexicons/dune.inc
+6
-7
ocaml-toml/README.md
+6
-7
ocaml-toml/README.md
···
20
20
Install with opam:
21
21
22
22
```sh
23
-
opam install toml
23
+
opam install nox-toml
24
24
```
25
25
26
26
If opam cannot find the package, it may not yet be released in the public
···
29
29
```sh
30
30
opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
31
31
opam update
32
-
opam install toml
32
+
opam install nox-toml
33
33
```
34
34
35
35
## Quick Start
···
66
66
67
67
## Packages
68
68
69
-
- `toml` - Core library with value types, codec combinators, and streaming
70
-
parser/encoder (on top of Bytesrw)
71
-
- `toml.eio` - Eio integration with system clock
72
-
- `toml.unix` - Unix I/O with system clock
73
-
- `toml.jsont` - Jsont codecs for toml-test JSON format
69
+
- `nox-toml` - Core library with value types, codec combinators, and streaming
70
+
parser/encoder (on top of Bytesrw). Modules are exposed as `Toml.*`.
71
+
- `nox-toml.eio` - Eio integration with system clock (`Toml_eio`)
72
+
- `nox-toml.unix` - Unix I/O with system clock (`Toml_unix`)
74
73
75
74
## Licence
76
75
+3
-3
ocaml-toml/doc/cookbook.mld
+3
-3
ocaml-toml/doc/cookbook.mld
···
787
787
788
788
{1:recursion Recursive Types}
789
789
790
-
Use {!Toml.Codec.rec'} for self-referential types:
790
+
Use {!Toml.Codec.fix} for self-referential types:
791
791
792
792
{[
793
793
type tree = Node of int * tree list
794
794
795
-
let rec tree_codec = lazy Toml.(
795
+
let rec tree_codec = lazy Toml.Codec.(
796
796
Table.(
797
797
obj (fun value children -> Node (value, children))
798
798
|> mem "value" int ~enc:(function Node (v, _) -> v)
799
-
|> mem "children" (list (rec' tree_codec))
799
+
|> mem "children" (list (fix tree_codec))
800
800
~enc:(function Node (_, cs) -> cs)
801
801
~dec_absent:[]
802
802
|> finish
+2
-2
ocaml-toml/doc/index.mld
+2
-2
ocaml-toml/doc/index.mld
···
42
42
- {!Toml.Parser} - Streaming parser and encoder
43
43
- {!Toml_eio} - Eio-native I/O integration
44
44
- {!Toml_unix} - Unix I/O integration
45
-
- {!Toml_jsont} - JSON codec for toml-test format
46
45
47
46
{2 Cookbook}
48
47
···
62
61
{2 Design}
63
62
64
63
Toml is inspired by {{:https://erratique.ch/software/jsont}Jsont}'s approach
65
-
to JSON codecs. Each codec ['a Toml.t] defines both:
64
+
to JSON codecs. Each codec ['a Toml.codec] (an alias for ['a Toml.Codec.t])
65
+
defines both:
66
66
67
67
- A decoder: [Toml.t -> ('a, error) result]
68
68
- An encoder: ['a -> Toml.t]
+10
-9
ocaml-yaml/README.md
+10
-9
ocaml-yaml/README.md
···
18
18
19
19
## Packages
20
20
21
-
- `yaml` — core value types, codec combinators, encode/decode API.
22
-
- `yaml.bytesrw` — streaming YAML 1.2 parser and emitter using
23
-
Bytesrw.
24
-
- `yaml.json` — use existing `Json.Codec.t` codecs (from the
25
-
[`json`](https://tangled.org/gazagnaire.org/ocaml-json) library) to
26
-
decode and encode YAML. Replacement for the deprecated `yamlt`
27
-
package.
21
+
- `nox-yaml` — core value types, codec combinators, encode/decode API.
22
+
Modules are exposed as `Yaml.*`.
23
+
- `nox-yaml.bytesrw` — streaming YAML 1.2 parser and emitter using
24
+
Bytesrw (`Yaml_bytesrw`).
25
+
- `nox-yaml.json` — use existing `Json.Codec.t` codecs (from the
26
+
[`nox-json`](https://tangled.org/gazagnaire.org/ocaml-json) library)
27
+
to decode and encode YAML (`Yaml_json`). Replacement for the
28
+
deprecated `yamlt` package.
28
29
29
30
## Installation
30
31
···
32
33
33
34
<!-- $MDX non-deterministic=command -->
34
35
```sh
35
-
$ opam install yaml
36
+
$ opam install nox-yaml
36
37
```
37
38
38
39
If opam cannot find the package, it may not yet be released in the public
···
42
43
```sh
43
44
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
44
45
$ opam update
45
-
$ opam install yaml
46
+
$ opam install nox-yaml
46
47
```
47
48
48
49
For Eio integration, wrap an Eio flow as a Bytesrw reader/writer with
+63
ocaml-yaml/doc/index.mld
+63
ocaml-yaml/doc/index.mld
···
1
+
{0 Yaml}
2
+
3
+
{1 YAML 1.2 Codec Library}
4
+
5
+
Yaml is a bidirectional codec library for {{:https://yaml.org/spec/1.2.2/}YAML 1.2}
6
+
documents. It provides type-safe encoding and decoding between OCaml types
7
+
and YAML values, mirroring the design of the
8
+
{{:https://tangled.org/gazagnaire.org/ocaml-toml}nox-toml} and
9
+
{{:https://tangled.org/gazagnaire.org/ocaml-json}nox-json} libraries.
10
+
11
+
{2 Quick Start}
12
+
13
+
Define a codec for your configuration type:
14
+
15
+
{[
16
+
type config = { host : string; port : int; debug : bool }
17
+
18
+
let config_codec =
19
+
Yaml.Codec.(Mapping.(
20
+
obj (fun host port debug -> { host; port; debug })
21
+
|> mem "host" string ~enc:(fun c -> c.host)
22
+
|> mem "port" int ~enc:(fun c -> c.port)
23
+
|> mem "debug" bool ~enc:(fun c -> c.debug) ~dec_absent:false
24
+
|> finish
25
+
))
26
+
]}
27
+
28
+
Decode a YAML string:
29
+
30
+
{[
31
+
let () =
32
+
match Yaml.decode_string config_codec {|
33
+
host: localhost
34
+
port: 8080
35
+
|} with
36
+
| Ok config -> Printf.printf "Host: %s\n" config.host
37
+
| Error e -> prerr_endline (Yaml.Error.to_string e)
38
+
]}
39
+
40
+
{2 Library Structure}
41
+
42
+
- {!Yaml.Value} - Core YAML value types and operations
43
+
- {!Yaml.Codec} - Codec combinators for bidirectional YAML encoding/decoding
44
+
- {!Yaml} - Top-level decode/encode entry points
45
+
- {!Yaml_bytesrw} - Streaming parser and emitter on top of Bytesrw
46
+
- {!Yaml_json} - Reuse {!module:Json.Codec} codecs for YAML I/O
47
+
48
+
{2 Installation}
49
+
50
+
{@sh[
51
+
opam install nox-yaml
52
+
]}
53
+
54
+
{2 Design}
55
+
56
+
Yaml is inspired by {{:https://erratique.ch/software/jsont}Jsont}'s approach
57
+
to JSON codecs. Each codec ['a Yaml.Codec.t] defines both:
58
+
59
+
- A decoder: [Yaml.t -> ('a, error) result]
60
+
- An encoder: ['a -> Yaml.t]
61
+
62
+
Codecs compose through combinators, so complex types are built from simple
63
+
primitives while staying bidirectional.