Reference

std/yaml/yaml

std/yaml/src/yaml.trb

Yaml, the format: a value with the options of YAML, which reads and writes typed values through Encode and Decode, reads documents into the tree of YamlNodes and writes that tree back, and frames a stream of documents for std/stream.

type YamlVersion

type YamlVersion

The version of YAML a document without a %YAML directive is read as.

case Yaml12

case Yaml12

YAML 1.2, the current version, and the default.

case Yaml11

case Yaml11

YAML 1.1: yes, no, on and off are truth values, and 0777 is an octal number.

type Yaml

type Yaml

YAML, with its options. The default reads YAML 1.2 - and YAML 1.1 where a document says %YAML 1.1 - applies the merge key <<, writes every field under the name the type declares, ignores a field no type asked for, and stops a document whose aliases expand to more than 100000 nodes.

A typed decode resolves each scalar by the type it is read as: no is the text "no" in a String field and an error in a Bool field, so YAML's surprises need no schema to be avoided.

Examples

type Service {
  name: String
  replicas: Int = 1
  ports: List<Int> = []
}

const yaml = Yaml()
const service = yaml.decode<Service>("name: web\nports: [80, 443]\n")?
print yaml.encode(service)

Related

  • YamlNode - the tree of a document, with its comments, for a tool that changes a file and keeps the rest.
  • YamlError - what a failed decode or parse says.

field naming

naming: Naming = Naming.Unchanged

How the field names are written and read: Naming.SnakeCase writes logLabel as log_label.

field strict

strict: Bool = false

Whether a field of the document that no type asked for is an error, instead of being ignored.

field schema

schema: YamlSchema? = None

How Yaml.resolved reads a plain scalar where no type says what it is. None reads a document by its version: the core schema, or YAML 1.1's types for a document that says %YAML 1.1.

field version

version: YamlVersion = YamlVersion.Yaml12

The version of a document that has no %YAML directive.

field tags

tags: List<YamlTag> = []

The local tags a typed decode accepts and a typed encode writes, each with the type it stands for.

field aliasLimit

aliasLimit: Int = 100000

How many nodes the aliases of one document may add before reading it fails.

field mergeKeys

mergeKeys: Bool = true

Whether the merge key << merges the mappings it names into the one it stands in.

fn encode

fn encode<Value: Encode>(value: Value): String

value as YAML text: one document, without ---.

fn decode

fn decode<Value: Decode>(text: String): Result<Value, YamlError>

Reads text, which holds one document, as a Value. A text without a document reads as null, which an optional value reads as None and a record as its defaults.

Errors

A YamlError for text that is not YAML, for a document that holds several, and for one that does not fit Value - with the line and the field chain it went wrong in.

fn decodeDocuments

fn decodeDocuments<Value: Decode>(text: String): Result<List<Value>, YamlError>

Every document of text, each read as a Value.

fn decodeDocument

fn decodeDocument<Value: Decode>(document: YamlDocument): Result<Value, YamlError>

A document that was parsed already, read as a Value: its aliases expanded, its merge keys applied.

fn parse

fn parse(text: String): Result<YamlDocument, YamlError>

Parses text, which holds one document, into its tree: every node as it was written, with its tag, its anchor, its style, its comments and its line.

Errors

A syntax error with its line and column, or an error for a text that holds several documents.

fn parseAll

fn parseAll(text: String): Result<List<YamlDocument>, YamlError>

Every document of a stream, as trees.

fn resolved

fn resolved(document: YamlDocument): Result<EncodedValue, YamlError>

A document without a type, as an EncodedValue: its aliases expanded, its merge keys applied, and its plain scalars resolved by Yaml.schema - or by the document's version where no schema is given.

fn value

fn value<Value: Encode>(value: Value): YamlNode

Any Encode value as the tree this format writes it as.

fn write

fn write(document: YamlDocument): String

A document as text, with its anchors, tags, styles and comments.

fn writeAll

fn writeAll(documents: List<YamlDocument>): String

A stream of documents as text; each document after the first starts with ---.

extend Yaml with Format<YamlError>

extend Yaml with Format<YamlError>

Everything a stream needs: a framer that finds where one document ends, and the ordinary Decode for the document itself. The static members use the default options, Yaml().

fn encodeAll

static fn encodeAll<Value: Encode>(value: Value): Bytes

fn decodeAll

static fn decodeAll<Value: Decode>(bytes: Bytes): Result<Value, YamlError>

fn items

static fn items<Item: Decode>(): Stage<Bytes, Result<Item, YamlError>>

Byte chunks to items: every document of the stream is one item. A document ends where a line starts with --- or ..., which YAML allows nowhere else at the start of a line, so the framer needs no parser.

fn encoded

static fn encoded<Item: Encode>(): Stage<Item, Bytes>

Items to bytes, each one a document that starts with ---.