Yaml

Tokenize source text for highlighting, including incomplete YAML snippets. Slicing each token interval from source and concatenating them reproduces the input exactly, including comments, whitespace, CRLF, and Unicode. Anchors, aliases, tags, directives and document markers are recognized lexically even when Yaml.parse_str rejects the document.

Tokenize arbitrary bytes without discarding invalid UTF-8. Diagnostics report malformed encoding; tokens still retain every original byte.

Map a token to a theme category without rendering or changing its text. Mapping keys use PropertyName; scalar values use their core-schema category. Quoted values and block-scalar scripts remain StringText.

Compare two parsed YAML values structurally.

Hash a parsed YAML value, so trees can be Dict keys or Set members.

Read a quoted YAML tree during compilation, rejecting invalid input and unquoted legacy boolean values such as yes and off.

Validate one complete document, reporting its source name and position. Unlike Yaml.parse_str, this also rejects enabled lint checks. Legacy boolean checks inspect unquoted values, never mapping keys or quoted text.

Validate and decode one document into the inferred Roc type. All existing decoder types, including U128 and strings such as 1.10, are preserved. Use unknown_keys: Reject to reject fields the result type does not have.

Parse one YAML configuration document from a string.

Empty input produces Null. Invalid input returns InvalidYaml with a one-based line and column. See the module description for the supported subset.

expect Yaml.parse_str("draft: false") == Ok(Mapping([{ key: "draft", value: Bool(False) }]))

A Parser that reads the rest of its input as one YAML document, for composing YAML with other parsers.

It always consumes all of its input. A failure is a ParseError whose offset is the byte offset of the reported line and column.

expect Utf8.parse_str(Yaml.parser, "a: 1") == Ok(Mapping([{ key: "a", value: Int(1) }]))

The value stored under key in a mapping. Anything else, or a mapping without that key, is Err(Missing).

expect Yaml.parse_str("title: Post").map_ok(|doc| doc.get("title")) == Ok(Ok(Text("Post")))

The item at a zero-based index of a sequence. Anything else, or an index past the end, is Err(Missing).

expect Yaml.parse_str("[a, b]").map_ok(|doc| doc.at(1)) == Ok(Ok(Text("b")))

Follow a path of mapping keys and sequence indexes. A segment applied to a sequence must be a decimal index such as "0".

expect {
    doc = Yaml.parse_str("jobs:\n  build:\n    steps: [checkout, test]\n")?
    doc.get_path(["jobs", "build", "steps", "1"]) == Ok(Text("test"))
}

The text of a Text value. Other values, including numbers and booleans, are Err(WrongType); use Yaml.decode to read a plain scalar such as 1.10 as text.

The integer of an Int value, or Err(WrongType).

The boolean of a Bool value, or Err(WrongType).

The items of a Sequence value, or Err(WrongType).

expect Yaml.parse_str("[1, 2]").map_ok(|doc| doc.as_list()) == Ok(Ok([Int(1), Int(2)]))

Render a parsed YAML value in Roc source-like notation for inspection.

The output is meant for debugging and test messages, not for writing YAML. Control characters in text and keys are escaped, so the output is always printable on one line.

expect Yaml.to_inspect(Sequence([Int(1), Text("a")])) == "Sequence([Int(1), Text(\"a\")])"

Decode one YAML document straight into a Roc type, chosen by type inference.

• A mapping decodes into a record (by field name), or a Dict with Str or integer keys. Unknown keys are skipped; use Yaml.decoder with unknown_keys: Reject to make them an error.
• A sequence decodes into a List or, when it has exactly the right number of items, a tuple.
• A scalar is resolved for the type that asks for it, using the YAML 1.2 core schema: Str takes any quoted or block scalar and any plain scalar except a null, so version: 1.10 stays "1.10"; Bool, the integer types, F32, F64 and Dec take the matching core-schema forms; a tag union without payloads takes the tag's name.
• A null (null, ~ or an empty value) decodes as an empty list, dict or record, and fills a Try(_, [Null]) field with Err(Null).
• A Try(_, [Missing]) field is Err(Missing) when its key is absent. Any other absent field fails with MissingRequiredField(name), a tag the compiler adds to the error type.

Invalid YAML and values that do not fit the type both fail with InvalidYaml, at the line and column of the offending value.

Config : { name : Str, version : Str, port : U16, debug : Try(Bool, [Missing]) }

expect {
    config : Try(Config, [InvalidYaml(Yaml.Error), MissingRequiredField(Str)])
    config = Yaml.decode("name: app\nversion: 1.10\nport: 8080\n")
    config == Ok({ name: "app", version: "1.10", port: 8080, debug: Err(Missing) })
}

Build a decoder like Yaml.decode with other conventions.

• keys says how YAML keys spell Roc's snake_case field names: SnakeCase as written, KebabCase with dashes (user-id) or CamelCase (userId).
• unknown_keys is Skip to ignore keys the record does not have, or Reject to fail with InvalidYaml at the first one.

Build the decoder once, for example as a top-level constant, and call it for each document.

decode_strict = Yaml.decoder({ keys: KebabCase, unknown_keys: Reject })

expect {
    result : Try({ user_id : U64 }, [InvalidYaml(Yaml.Error), MissingRequiredField(Str)])
    result = decode_strict("user-id: 7\n")
    result == Ok({ user_id: 7 })
}