yaml

import yaml

A complete, YAML 1.2.2-compliant library for parsing and emitting YAML (YAML Ain’t Markup Language) documents.

This module implements the YAML 1.2.2 specification published at https://yaml.org/spec/1.2.2/ using the Core Schema for implicit type resolution, which is the schema used by most modern YAML implementations.

Supported features

Scalars

• Plain (unquoted) scalars with Core Schema type resolution - Single-quoted scalars (no escape processing; '' → ') - Double-quoted scalars with full escape sequence processing (\n \t \r \\ \" \/ \b \f \a \v \e \0 \xNN \uNNNN \UNNNNNNNN \N \_ \L \P)
• Literal block scalars (|) with clip, strip, and keep chomping
• Folded block scalars (>) with clip, strip, and keep chomping

Collections

• Block mappings (key: value pairs, indented) - Block sequences (dash-prefixed lists, indented) - Flow mappings ({ key: value, ... })
• Flow sequences ([ item, item, ... ]) - Nested collections of any depth - Complex (non-scalar) mapping keys with ? indicator

Document structure

• Multi-document streams separated by --- - Document end markers ... - %YAML directives (parsed; the major version must be 1, and the version string must be well-formed, or parsing raises: the minor version isn’t otherwise checked) - %TAG directives (parsed and consumed; custom tag handles registered this way are not yet substituted into !handle!suffix tags) - UTF-8 input only, with BOM detection/stripping for that encoding. UTF-16/UTF-32 input is not supported.

Node properties

• Anchors (&name) and aliases (*name) with full reference resolution - Merge keys (<<: *anchor) for dict merging - Explicit tags (!!str, !!int, !!float, !!bool, !!null, !!seq, !!map, !!binary, !<tag:yaml.org,2002:type>)

Core Schema type resolution (implicit)

• null / Null / NULL / ~ / empty → nil - true / True / TRUE / false / False / FALSE → bool - Decimal integers (with optional +/- sign) → number - Octal integers 0o[0-7]+ → number - Hexadecimal integers 0x[0-9A-Fa-f]+ → number - Decimal floats (with exponent) → number - .inf / .Inf / .INF / ±.inf → math.Infinity / -math.Infinity - .nan / .NaN / .NAN → 0/0 (NaN) - Everything else → string

Emitter features

• Round-trips scalars correctly (chooses minimal quoting) - Emits block or flow style per value type - Anchors and aliases for repeated object references - Configurable indentation (default: 2) - Configurable line width for scalar wrapping (default: 80)

Quick start

import yaml

# Parse a YAML string.
var data = yaml.parse('name: Alice\nage: 30\nscores: [98, 72, 85]')
echo data['name']      # Alice
echo data['age']       # 30
echo data['scores'][0] # 98

# Parse multiple documents.
var docs = yaml.parse_all('---\na: 1\n---\nb: 2\n')
echo docs.length()  # 2

# Emit a Zuri value as YAML.
echo yaml.dump({ name: 'Bob', active: true, tags: ['x', 'y'] })
# name: Bob
# active: true
# tags: [x, y]

# Parse a YAML file.
var config = yaml.load_file('config.yaml')

# Emit to a file.
yaml.dump_file('out.yaml', data)

The yaml API

Every public name in yaml, wherever it is declared. Each links to the page that documents it.

Functions

parse()

yaml.parse(text: string) -> any

Parses a YAML string and returns the value of the first (or only) document.

Uses the Core Schema for implicit type resolution (see module description).

Examples

import yaml

# Scalar
yaml.parse('42')              # 42 (number)
yaml.parse('hello')           # 'hello' (string)
yaml.parse('true')            # true (bool)
yaml.parse('~')               # nil

# Mapping
yaml.parse('a: 1\nb: two')   # { a: 1, b: 'two' }

# Sequence
yaml.parse('- x\n- y\n- z')  # ['x', 'y', 'z']

# Flow styles
yaml.parse('{x: 1, y: [2, 3]}')  # { x: 1, y: [2, 3] }

# Anchors and aliases
yaml.parse('a: &ref hello\nb: *ref')  # { a: 'hello', b: 'hello' }

# Multi-line string
yaml.parse("msg: |\n  hello\n  world\n")  # { msg: "hello\nworld\n" }

Parameters

• text (string) — The YAML text to parse.

Returns any — The parsed Zuri value.

Raises YamlError On any YAML syntax or structural error.

parse_all()

yaml.parse_all(text: string) -> list

Parses a YAML stream containing one or more documents and returns a list of all document values.

Documents are separated by --- markers. A stream with a single document and no --- marker returns a single-element list.

import yaml

var docs = yaml.parse_all("---\na: 1\n---\nb: 2\n")
echo docs.length()  # 2
echo docs[0]        # { a: 1 }
echo docs[1]        # { b: 2 }

Parameters

• text (string) — The YAML stream text.

Returns list — List of parsed document values (one per document).

Raises YamlError On any YAML syntax or structural error.

load_single_file()

yaml.load_single_file(path: string) -> any

Reads a YAML file from path and parses the first document.

import yaml

var config = yaml.load_file('config.yaml')
echo config['database']['host']

Parameters

• path (string) — Filesystem path to the YAML file.

Returns any — The parsed value of the first document.

Raises YamlError On parse error.

Raises Error On file I/O error.

load_file()

yaml.load_file(path: string) -> list

Reads a YAML file from path and parses all documents in the stream.

Parameters

• path (string) — Filesystem path to the YAML file.

Returns list — List of parsed document values.

Raises YamlError On parse error.

Raises Error On file I/O error.

dump()

yaml.dump(value, indent: ?int, width: ?int) -> string

Serialises a Zuri value to a YAML string.

The output is a valid YAML 1.2 document terminated by a newline. Collections use block style by default; small flat sequences may be emitted in flow style when they fit within the line width.

Examples

import yaml

yaml.dump(nil)             # 'null\n'
yaml.dump(true)            # 'true\n'
yaml.dump(42)              # '42\n'
yaml.dump('hello world')  # 'hello world\n'
yaml.dump('null')         # "'null'\n"  (quoted to avoid misparse)

yaml.dump({ name: 'Alice', age: 30 })
# name: Alice
# age: 30

yaml.dump(['a', 'b', 'c'])
# - a
# - b
# - c

# Nested structure.
yaml.dump({ servers: [{ host: 'a', port: 80 }, { host: 'b', port: 443 }] })
# servers:
#   -
#     host: a
#     port: 80
#   -
#     host: b
#     port: 443

Parameters

• value (any) — The Zuri value to serialise.
• indent (?int) — Spaces per indentation level (default: 2).
• width (?int) — Target line width for flow-style decisions (default: 80).

Returns string — The YAML text (always ends with \n).

Raises YamlError On emission error (e.g. unserializable value).

dump_all()

yaml.dump_all(values: list, indent: ?int, width: ?int) -> string

Serialises a list of values as a multi-document YAML stream.

Each value is emitted as a separate YAML document, separated by ---.

import yaml

yaml.dump_all([{ a: 1 }, { b: 2 }])
# ---
# a: 1
# ---
# b: 2

Parameters

• values (list) — List of Zuri values to serialise.
• indent (?int) — Spaces per indentation level (default: 2).
• width (?int) — Target line width (default: 80).

Returns string — The YAML stream text.

Raises YamlError On emission error.

dump_file()

yaml.dump_file(path: string, value, indent: ?int, width: ?int)

Serialises value to YAML and writes it to the file at path.

Creates or overwrites the file.

import yaml

yaml.dump_file('config.yaml', {
  host: 'localhost',
  port: 5432,
  debug: false,
})

Parameters

• path (string) — Filesystem path to write to.
• value (any) — The value to serialise.
• indent (?int) — Indentation level (default: 2).
• width (?int) — Line width (default: 80).

Raises YamlError On emission error.

Raises Error On file I/O error.

Classes

YamlError

class yaml.YamlError < Error

Error raised when a YAML parsing or emission error occurs.

Fields

Constructor

yaml.YamlError(message, line, column, context)

Parameters

• message (string) — Error description.
• line (number) — Line number (1-based), or nil.
• column (number) — Column number (1-based), or nil.
• context (string) — Optional context (surrounding text), or nil.

2026, Richard Ore and The Zuri Contributors