yum/yaml

Parse, resolve, query, decode, and emit YAML documents.

This is the main public module. It parses strings into opaque YAML documents, resolves YAML-level metadata such as aliases and tags, retrieves nested nodes by path, decodes documents with gleam/dynamic/decode, and emits YAML strings from parsed or built documents.

import gleam/option
import yum/yaml
import yum/yaml/node

pub fn example() {
  let assert Ok(document) = yaml.parse("name: yum")

  let name =
    document
    |> yaml.get([node.Key("name")])
    |> option.map(node.as_string)

  assert name == option.Some(Ok("yum"))
}

Use parse when you want a single YAML document value. Use parse_stream for YAML streams containing zero or more explicit documents.

Parsed YAML is raw syntax. Pipe it into resolve to run the semantic YAML phase that validates anchors, aliases, directives, and tags.

Types

DecodeError

</>

Errors returned by decode.

Decoding runs three phases: parsing, YAML resolution, and then the supplied gleam/dynamic/decode decoder. This type identifies which phase failed.

pub type DecodeError {
  ParseError(error.YamlError)
  ResolveError(List(diagnostic.Diagnostic))
  UnableToDecode(List(decode.DecodeError))
}

Constructors

```
ParseError(error.YamlError)
```
The input could not be parsed as YAML.
```
ResolveError(List(diagnostic.Diagnostic))
```
The input parsed, but YAML resolution found fatal diagnostics.
```
UnableToDecode(List(decode.DecodeError))
```
YAML resolution succeeded, but the dynamic decoder rejected the value.

Directive

</>

A YAML directive from the beginning of a document.

Directives are preserved for tooling and semantic resolution. For example, a TAG directive contributes a tag handle that resolution can use.

pub type Directive {
  Directive(
    name: String,
    parameters: List(String),
    span: node.Span,
  )
}

Constructors

Directive(
  name: String,
  parameters: List(String),
  span: node.Span,
)

The directive name, its whitespace-separated parameters, and source span.

Yaml

opaque </>

A YAML document.

Raw YAML has passed syntax parsing. Resolved YAML has also passed the semantic YAML phase, which validates anchors, aliases, directives, and tags. The type is opaque so callers use accessors rather than depending on the internal document representation.

pub opaque type Yaml

Values

decode

</>

pub fn decode(
  from input: String,
  using decoder: decode.Decoder(t),
) -> Result(t, DecodeError)

Parses YAML and decodes it using a gleam/dynamic/decode decoder.

diagnostics

</>

pub fn diagnostics(
  from yaml: Yaml,
) -> List(diagnostic.Diagnostic)

Returns non-fatal diagnostics collected while resolving the document.

directives

</>

pub fn directives(from yaml: Yaml) -> List(Directive)

Returns the document directives.

from_node

</>

pub fn from_node(node: node.Node) -> Yaml

Creates a raw YAML document from a node.

This is useful with yum/yaml/builder, which builds node trees.

get

</>

pub fn get(
  from yaml: Yaml,
  at path: List(node.PathSegment),
) -> option.Option(node.Node)

Returns a nested node by mapping key or sequence index.

get_keys

</>

pub fn get_keys(
  from yaml: Yaml,
) -> Result(List(node.Node), node.AccessError)

Returns all keys from the root mapping.

The keys are returned as nodes because YAML mappings can use scalar, sequence, or mapping nodes as keys. Returns ExpectedKind when the document root is not a mapping.

get_values

</>

pub fn get_values(
  from yaml: Yaml,
) -> Result(List(node.Node), node.AccessError)

Returns all values from the root mapping.

Values are returned in source order. Returns ExpectedKind when the document root is not a mapping.

parse

</>

pub fn parse(input: String) -> Result(Yaml, error.YamlError)

Parses a YAML file into a YAML document.

Follows the YAML 1.2 specification

parse_stream

</>

pub fn parse_stream(
  input: String,
) -> Result(List(Yaml), error.YamlError)

Parses a YAML stream into a list of YAML documents.

resolve

</>

pub fn resolve(
  yaml: Yaml,
) -> Result(Yaml, List(diagnostic.Diagnostic))

Resolves raw YAML into composed YAML.

Calling this on already-resolved YAML is a no-op.

root

</>

pub fn root(yaml: Yaml) -> node.Node

Returns the document root node.

to_string

</>

pub fn to_string(yaml: Yaml) -> String

Emits a deterministic YAML string from a YAML document.