Module Yaml

A library for parsing and emitting YAML.

It is based on a binding to libyaml which covers the generation and parsing processes.

Most simple use cases can simply use the of_string and to_string functions, which are compatible with the Ezjsonm types. This means that you can convert between JSON and Yaml format easily.

If you use more advanced Yaml features such as aliases or anchors, then the yaml type and yaml_of_string and yaml_to_string functions will be more useful. The library does not yet support expanding aliases into the JSON format from YAML, so that will currently result in an error.

Types

type value = [
| `Null
| `Bool of bool
| `Float of float
| `String of string
| `A of value list
| `O of (string * value) list
]

value is the subset of a Yaml document that is compatible with JSON. This type is the same as Ezjsonm.value, and so most simple uses of Yaml can be interchanged with JSON.

val sexp_of_value : value -> Ppx_sexp_conv_lib.Sexp.t
val value_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> value
val __value_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> value
type yaml = [
| `Scalar of scalar
| `Alias of string
| `A of yaml list
| `O of (scalar * yaml) list
]

yaml is the representation of a Yaml document that preserves alias information and other Yaml-specific metadata that cannot be represented in JSON. It is not recommended to convert untrusted Yaml with aliases into JSON due to the risk of denial-of-service via a Billion Laughs attack.

and scalar = {
anchor : string option;
tag : string option;
value : string;
plain_implicit : bool;
quoted_implicit : bool;
style : scalar_style;
}

scalar is the description of a Yaml scalar.

Scalar values are represented as strings. A scalar can optionally have an anchor and a tag. The flow style of the scalar is defined by the style field. If plain_implicit is true, the tag is optional for the plain style. If quoted_implicit is true, the tag is optional for any non-plain style.

and scalar_style = [
| `Any
| `Plain
| `Single_quoted
| `Double_quoted
| `Literal
| `Folded
]

YAML provides three flow scalar styles: double-quoted, single-quoted and plain (unquoted). Each provides a different trade-off between readability and expressive power. The Yaml spec section 7.3 has more details.

val sexp_of_yaml : yaml -> Ppx_sexp_conv_lib.Sexp.t
val sexp_of_scalar : scalar -> Ppx_sexp_conv_lib.Sexp.t
val sexp_of_scalar_style : scalar_style -> Ppx_sexp_conv_lib.Sexp.t
val yaml_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> yaml
val __yaml_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> yaml
val scalar_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> scalar
val scalar_style_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> scalar_style
val __scalar_style_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> scalar_style
val sexp_of_yaml : yaml -> Ppx_sexp_conv_lib.Sexp.t
val sexp_of_scalar : scalar -> Ppx_sexp_conv_lib.Sexp.t
val sexp_of_scalar_style : scalar_style -> Ppx_sexp_conv_lib.Sexp.t
val yaml_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> yaml
val __yaml_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> yaml
val scalar_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> scalar
val scalar_style_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> scalar_style
val __scalar_style_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> scalar_style
type version = [
| `V1_0
| `V1_1
]

Version of the YAML spec of a document. Refer to the Yaml specification for details of the differences between versions.

val sexp_of_version : version -> Ppx_sexp_conv_lib.Sexp.t
val version_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> version
val __version_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> version
type encoding = [
| `Any
| `Utf16be
| `Utf16le
| `Utf8
]

Document encoding. The recommended format is Utf8.

val sexp_of_encoding : encoding -> Ppx_sexp_conv_lib.Sexp.t
val encoding_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> encoding
val __encoding_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> encoding
type layout_style = [
| `Any
| `Block
| `Flow
]

Mappings and sequences can be rendered in two different ways:

  • Flow styles can be thought of as the natural extension of JSON to cover folding long content lines for readability, tagging nodes to control construction of native data structures, and using anchors and aliases to reuse constructed object instances.
  • Block styles employ indentation rather than indicators to denote structure. This results in a more human readable (though less compact) notation.
val sexp_of_layout_style : layout_style -> Ppx_sexp_conv_lib.Sexp.t
val layout_style_of_sexp : Ppx_sexp_conv_lib.Sexp.t -> layout_style
val __layout_style_of_sexp__ : Ppx_sexp_conv_lib.Sexp.t -> layout_style
type 'a res = ('a, Rresult.R.msg) Result.result

This library uses the Rresult.R.msg conventions for returning errors rather than raising exceptions.

Serialisers and deserialisers

JSON-compatible functions

val of_string : string -> value res

of_string s parses s into a JSON value representation, discarding any Yaml-specific information such as anchors or tags.

val of_string_exn : string -> value

of_string_exn s acts as of_string, but raises Invalid_argument if there is an error.

val to_string : ?⁠len:int -> ?⁠encoding:encoding -> ?⁠scalar_style:scalar_style -> ?⁠layout_style:layout_style -> value -> string res

to_string v converts the JSON value to a Yaml string representation. The encoding, scalar_style and layout_style control the various output parameters. The current implementation uses a non-resizable internal string buffer of 64KB, which can be increased via len.

val to_string_exn : ?⁠len:int -> ?⁠encoding:encoding -> ?⁠scalar_style:scalar_style -> ?⁠layout_style:layout_style -> value -> string

to_string_exn v acts as to_string, but raises Invalid_argument in if there is an error.

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

pp ppf s will output the Yaml value s to the formatter ppf.

val equal : value -> value -> bool

equal v1 v2 is true iff v1 and v2 are equal.

Yaml-specific functions

val yaml_of_string : string -> yaml res

yaml_of_string s parses s into a Yaml yaml representation, preserving Yaml-specific information such as anchors.

val yaml_to_string : ?⁠encoding:encoding -> ?⁠scalar_style:scalar_style -> ?⁠layout_style:layout_style -> yaml -> string res

yaml_to_string v converts the Yaml value to a string representation. The encoding, scalar_style and layout_style control the various output parameters. The current implementation uses a non-resizable internal string buffer of 16KB, which can be increased via len.

JSON/Yaml conversion functions

val to_json : yaml -> value res

to_json yaml will convert the Yaml document into a simpler JSON representation, discarding any anchors or tags from the original. Returns an error if any aliases are used within the body of the Yaml input.

val of_json : value -> yaml res

of_json j converts the JSON representation into a Yaml representation.

module Stream : sig ... end

Low-level event streaming interface for parsing and emitting YAML files.