OCaml Library Collection

Yamlrw - A Pure OCaml YAML Parser and Emitter

Yamlrw is a pure OCaml implementation of YAML 1.1/1.2 parsing and emission. It provides both a high-level JSON-compatible interface and a lower-level streaming API for fine-grained control.

Quick Start

Parse a YAML string:

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

Serialize to YAML:

  let yaml = `O [("name", `String "Bob"); ("active", `Bool true)] in
  let s = Yamlrw.to_string yaml in
  (* "name: Bob\nactive: true\n" *)

Use the Util module for convenient access:

  let name = Yamlrw.Util.(get_string (get "name" value)) in
  let age = Yamlrw.Util.(get_int (get "age" value)) in

Yamlrw_unix - Unix file I/O integration
Yamlrw_eio - Eio async file and flow operations
Yamlt - YAML codec using Jsont type descriptions (higher-level)

Error Handling

module Error : sig ... end

exception Yamlrw_error of Error.t

Raised on parse or emit errors.

Core Types

type value = [

| `Null
(*
YAML null, ~, or empty values
*)
| `Bool of bool
(*
YAML booleans (true, false, yes, no, on, off)
*)
| `Float of float
(*
All YAML numbers (integers stored as floats)
*)
| `String of string
(*
YAML strings
*)
| `A of value list
(*
YAML sequences/arrays
*)
| `O of (string * value) list
(*
YAML mappings/objects with string keys
*)

]

JSON-compatible YAML representation. Use this for simple data interchange.

This type is structurally equivalent to Value.t and compatible with the ezjsonm representation. For additional operations, see Value and Util.

type yaml = [

| `Scalar of Scalar.t
(*
YAML scalar value with style and metadata
*)
| `Alias of string
(*
Alias reference to an anchored node
*)
| `A of yaml Sequence.t
(*
YAML sequence with style and metadata
*)
| `O of (yaml, yaml) Mapping.t
(*
YAML mapping with style and metadata
*)

]

Full YAML representation preserving anchors, tags, and aliases.

This type is structurally equivalent to Yaml.t. Use this when you need access to YAML-specific features like anchors and aliases for node reuse, type tags for custom types, scalar styles (plain, quoted, literal, folded), and collection styles (block vs flow).

For additional operations, see Yaml, Scalar, Sequence, and Mapping.

type document = {

version : (int * int) option;
(*
Optional YAML version directive (e.g., (1, 2) for YAML 1.2)
*)
tags : (string * string) list;
(*
TAG directives mapping handles to prefixes
*)
root : yaml option;
(*
Root content of the document
*)
implicit_start : bool;
(*
Whether the document start marker (---) is implicit
*)
implicit_end : bool;
(*
Whether the document end marker (...) is implicit
*)

}

A YAML document with directives and metadata.

This type is structurally equivalent to Document.t. A YAML stream can contain multiple documents, each separated by document markers.

For additional operations, see Document.

Character Encoding

module Encoding : sig ... end

Character encoding detection and handling

Parsing

type version = [

| `V1_1
| `V1_2

]

YAML specification version.

val default_max_alias_nodes : int

Default maximum nodes during alias expansion (10 million).

val default_max_alias_depth : int

Default maximum alias nesting depth (100).

val of_string : 
  ?resolve_aliases:bool ->
  ?max_nodes:int ->
  ?max_depth:int ->
  string ->
  value

Parse a YAML string into a JSON-compatible value.

parameter resolve_aliases
Whether to expand aliases (default: true)

parameter max_nodes
Maximum nodes during alias expansion (default: 10M)

parameter max_depth
Maximum alias nesting depth (default: 100)

raises Yamlrw_error
on parse error or if multiple documents found

val yaml_of_string : 
  ?resolve_aliases:bool ->
  ?max_nodes:int ->
  ?max_depth:int ->
  string ->
  yaml

Parse a YAML string preserving full YAML metadata (anchors, tags, etc).

By default, aliases are NOT resolved, preserving the document structure.

parameter resolve_aliases
Whether to expand aliases (default: false)

parameter max_nodes
Maximum nodes during alias expansion (default: 10M)

parameter max_depth
Maximum alias nesting depth (default: 100)

raises Yamlrw_error
on parse error or if multiple documents found

val documents_of_string : string -> document list

Parse a multi-document YAML stream.

Use this when your YAML input contains multiple documents separated by document markers (---).

raises Yamlrw_error
on parse error

Formatting Styles

module Scalar_style : sig ... end

Scalar formatting styles

module Layout_style : sig ... end

Collection layout styles

Serialization

val to_buffer : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  ?buffer:Buffer.t ->
  value ->
  Buffer.t

Serialize a value to a buffer.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

parameter buffer
Optional buffer to append to (allocates new one if not provided)

returns
The buffer containing the serialized YAML

val to_string : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  value ->
  string

Serialize a value to a YAML string.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

val yaml_to_buffer : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  ?buffer:Buffer.t ->
  yaml ->
  Buffer.t

Serialize a full YAML value to a buffer.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

parameter buffer
Optional buffer to append to (allocates new one if not provided)

returns
The buffer containing the serialized YAML

val yaml_to_string : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  yaml ->
  string

Serialize a full YAML value to a string.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

val documents_to_buffer : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  ?resolve_aliases:bool ->
  ?buffer:Buffer.t ->
  document list ->
  Buffer.t

Serialize multiple documents to a buffer.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

parameter resolve_aliases
Whether to expand aliases (default: true)

parameter buffer
Optional buffer to append to (allocates new one if not provided)

returns
The buffer containing the serialized YAML

val documents_to_string : 
  ?encoding:Encoding.t ->
  ?scalar_style:Scalar_style.t ->
  ?layout_style:Layout_style.t ->
  ?resolve_aliases:bool ->
  document list ->
  string

Serialize multiple documents to a YAML stream.

parameter encoding
Output encoding (default: UTF-8)

parameter scalar_style
Preferred scalar style (default: Any)

parameter layout_style
Preferred layout style (default: Any)

parameter resolve_aliases
Whether to expand aliases (default: true)

Buffer Parsing

val of_buffer : 
  ?resolve_aliases:bool ->
  ?max_nodes:int ->
  ?max_depth:int ->
  Buffer.t ->
  value

Parse YAML from a buffer into a JSON-compatible value.

parameter resolve_aliases
Whether to expand aliases (default: true)

parameter max_nodes
Maximum nodes during alias expansion (default: 10M)

parameter max_depth
Maximum alias nesting depth (default: 100)

raises Yamlrw_error
on parse error or if multiple documents found

val yaml_of_buffer : 
  ?resolve_aliases:bool ->
  ?max_nodes:int ->
  ?max_depth:int ->
  Buffer.t ->
  yaml

Parse YAML from a buffer preserving full YAML metadata.

parameter resolve_aliases
Whether to expand aliases (default: false)

parameter max_nodes
Maximum nodes during alias expansion (default: 10M)

parameter max_depth
Maximum alias nesting depth (default: 100)

raises Yamlrw_error
on parse error or if multiple documents found

val documents_of_buffer : Buffer.t -> document list

Parse a multi-document YAML stream from a buffer.

raises Yamlrw_error
on parse error

Conversion

val to_json : 
  ?resolve_aliases:bool ->
  ?max_nodes:int ->
  ?max_depth:int ->
  yaml ->
  value

Convert full YAML to JSON-compatible value.

parameter resolve_aliases
Whether to expand aliases (default: true)

parameter max_nodes
Maximum nodes during alias expansion (default: 10M)

parameter max_depth
Maximum alias nesting depth (default: 100)

raises Yamlrw_error
if alias limits exceeded or complex keys found

val of_json : value -> yaml

Convert JSON-compatible value to full YAML representation.

Pretty Printing & Equality

val pp : Format.formatter -> value -> unit

Pretty-print a value.

val equal : value -> value -> bool

Test equality of two values.

Util - Value Combinators

Combinators for working with value values.

This module provides constructors, accessors, and transformations for JSON-compatible YAML values.

module Util : sig ... end

Stream - Low-Level Event API

Low-level streaming API for event-based YAML processing.

This is useful for:

Processing very large YAML files incrementally
Building custom YAML transformers
Fine-grained control over YAML emission

module Stream : sig ... end

Internal Modules

These modules are exposed for advanced use cases requiring fine-grained control over parsing, emission, or data structures.

For typical usage, prefer the top-level functions and Util.

module Position : sig ... end

Source position tracking.

module Span : sig ... end

Source span (range of positions).

module Chomping : sig ... end

Block scalar chomping modes.

module Tag : sig ... end

YAML type tags.

module Value : sig ... end

JSON-compatible value type and operations.

module Scalar : sig ... end

YAML scalar with metadata.

module Sequence : sig ... end

YAML sequence with metadata.

module Mapping : sig ... end

YAML mapping with metadata.

module Yaml : sig ... end

Full YAML value type.

module Document : sig ... end

YAML document with directives.

module Token : sig ... end

Lexical tokens.

module Scanner : sig ... end

Lexical scanner.

module Event : sig ... end

Parser events.

module Parser : sig ... end

Event-based parser.

module Loader : sig ... end

Document loader.

module Emitter : sig ... end

Event-based emitter.

module Input : sig ... end

Input stream utilities.

module Serialize : sig ... end

Buffer serialization utilities.