Pure OCaml Yaml 1.2 reader and writer using Bytesrw
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Serialize - high-level serialization to buffers and event streams
7
8 This module provides functions to convert YAML values to events and strings.
9 Both {!Emitter.t}-based and function-based emission APIs are provided. *)
10
11(** {1 Emitter.t-based API} *)
12
13val emit_yaml_node : Emitter.t -> Yaml.t -> unit
14(** Emit a YAML node to an emitter *)
15
16val emit_yaml : Emitter.t -> Yaml.t -> unit
17(** Emit a complete YAML document to an emitter (includes stream/document markers) *)
18
19val emit_value_node : Emitter.t -> Value.t -> unit
20(** Emit a Value node to an emitter *)
21
22val emit_value : Emitter.t -> Value.t -> unit
23(** Emit a complete Value document to an emitter (includes stream/document markers) *)
24
25val emit_document : ?resolve_aliases:bool -> Emitter.t -> Document.t -> unit
26(** Emit a document to an emitter
27
28 @param resolve_aliases Whether to resolve aliases before emission (default true) *)
29
30(** {1 Buffer-based API} *)
31
32val value_to_buffer :
33 ?config:Emitter.config ->
34 ?buffer:Buffer.t ->
35 Value.t -> Buffer.t
36(** Serialize a Value to a buffer
37
38 @param config Emitter configuration (default: {!Emitter.default_config})
39 @param buffer Optional buffer to append to; creates new one if not provided *)
40
41val yaml_to_buffer :
42 ?config:Emitter.config ->
43 ?buffer:Buffer.t ->
44 Yaml.t -> Buffer.t
45(** Serialize a Yaml.t to a buffer *)
46
47val documents_to_buffer :
48 ?config:Emitter.config ->
49 ?resolve_aliases:bool ->
50 ?buffer:Buffer.t ->
51 Document.t list -> Buffer.t
52(** Serialize documents to a buffer
53
54 @param resolve_aliases Whether to resolve aliases before emission (default true) *)
55
56(** {1 String-based API} *)
57
58val value_to_string : ?config:Emitter.config -> Value.t -> string
59(** Serialize a Value to a string *)
60
61val yaml_to_string : ?config:Emitter.config -> Yaml.t -> string
62(** Serialize a Yaml.t to a string *)
63
64val documents_to_string :
65 ?config:Emitter.config ->
66 ?resolve_aliases:bool ->
67 Document.t list -> string
68(** Serialize documents to a string *)
69
70(** {1 Writer-based API}
71
72 These functions write directly to a bytesrw [Bytes.Writer.t],
73 enabling true streaming output without intermediate string allocation. *)
74
75val value_to_writer :
76 ?config:Emitter.config ->
77 ?eod:bool ->
78 Bytesrw.Bytes.Writer.t -> Value.t -> unit
79(** Serialize a Value directly to a Bytes.Writer
80
81 @param eod Whether to write end-of-data after serialization (default true) *)
82
83val yaml_to_writer :
84 ?config:Emitter.config ->
85 ?eod:bool ->
86 Bytesrw.Bytes.Writer.t -> Yaml.t -> unit
87(** Serialize a Yaml.t directly to a Bytes.Writer *)
88
89val documents_to_writer :
90 ?config:Emitter.config ->
91 ?resolve_aliases:bool ->
92 ?eod:bool ->
93 Bytesrw.Bytes.Writer.t -> Document.t list -> unit
94(** Serialize documents directly to a Bytes.Writer *)
95
96(** {1 Function-based API}
97
98 These functions accept an emit function [Event.t -> unit] instead of
99 an {!Emitter.t}, allowing them to work with any event sink. *)
100
101val emit_yaml_node_fn : emitter:(Event.t -> unit) -> Yaml.t -> unit
102(** Emit a YAML node using an emitter function *)
103
104val emit_yaml_fn :
105 emitter:(Event.t -> unit) ->
106 config:Emitter.config ->
107 Yaml.t -> unit
108(** Emit a complete YAML stream using an emitter function *)
109
110val emit_value_node_fn :
111 emitter:(Event.t -> unit) ->
112 config:Emitter.config ->
113 Value.t -> unit
114(** Emit a Value node using an emitter function *)
115
116val emit_value_fn :
117 emitter:(Event.t -> unit) ->
118 config:Emitter.config ->
119 Value.t -> unit
120(** Emit a complete Value stream using an emitter function *)
121
122val emit_document_fn :
123 ?resolve_aliases:bool ->
124 emitter:(Event.t -> unit) ->
125 Document.t -> unit
126(** Emit a document using an emitter function *)
127
128val emit_documents :
129 emitter:(Event.t -> unit) ->
130 config:Emitter.config ->
131 ?resolve_aliases:bool ->
132 Document.t list -> unit
133(** Emit multiple documents using an emitter function *)