Yaml

Compare two parsed YAML values structurally.

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

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 })
}