node

Inspect and query YAML nodes.

A Node is one value inside a YAML document: a scalar, sequence, or mapping. This module provides accessors for the node kind, source span, source style, tags, anchors, aliases, typed scalar values, and nested path lookup.

Nodes are used by both raw and resolved YAML documents. Parsing creates nodes with the structure and metadata found in the source. Resolving validates YAML-level metadata such as aliases and tags, and may expand or compose parts of the tree, but a resolved document still contains nodes.

For example, tag, anchor, and alias expose YAML metadata attached to a node. That metadata is not the same as the node’s semantic Kind. Nodes created with yum/yaml/builder are synthetic and use synthetic_span.

Types

AccessError

</>

An error returned by strict node accessors.

pub type AccessError {
  ExpectedKind(expected: KindName, found: KindName, span: Span)
}

Constructors

ExpectedKind(expected: KindName, found: KindName, span: Span)

The node had a different kind than the accessor required.

Kind

</>

The semantic kind of a YAML node.

This describes the value after scalar parsing, not necessarily the exact source spelling. Use style when source presentation matters.

pub type Kind {
  Null
  Bool(Bool)
  Int(Int)
  Float(Float)
  PosInf
  NegInf
  Nan
  String(String)
  Sequence(List(Node))
  Mapping(List(#(Node, Node)))
}

Constructors

```
Null
```
A YAML null value.

Example YAML: null
```
Bool(Bool)
```
A boolean scalar.

Example YAML: true
```
Int(Int)
```
An integer scalar.

Example YAML: 42
```
Float(Float)
```
A finite floating-point scalar.

Example YAML: 3.14
```
PosInf
```
Positive infinity.

Example YAML: .inf
```
NegInf
```
Negative infinity.

Example YAML: -.inf
```
Nan
```
Not-a-number.

Example YAML: .nan
```
String(String)
```
A string scalar.

Example YAML: hello
```
Sequence(List(Node))
```
A YAML sequence.

Example YAML: - one
```
Mapping(List(#(Node, Node)))
```
A YAML mapping.

Example YAML: name: yum

KindName

</>

A lightweight name for a YAML node kind.

This is useful in diagnostics and access errors where carrying the full node value would be noisy.

pub type KindName {
  NullKind
  BoolKind
  IntKind
  FloatKind
  PosInfKind
  NegInfKind
  NanKind
  StringKind
  SequenceKind
  MappingKind
}

Constructors

```
NullKind
```
The lightweight name for Null.
```
BoolKind
```
The lightweight name for Bool.
```
IntKind
```
The lightweight name for Int.
```
FloatKind
```
The lightweight name for Float.
```
PosInfKind
```
The lightweight name for PosInf.
```
NegInfKind
```
The lightweight name for NegInf.
```
NanKind
```
The lightweight name for Nan.
```
StringKind
```
The lightweight name for String.
```
SequenceKind
```
The lightweight name for Sequence.
```
MappingKind
```
The lightweight name for Mapping.

Node

opaque </>

A YAML value with source metadata.

Nodes can represent scalars, sequences, and mappings. Parsed nodes carry their source span and presentation style. Builder-created nodes are synthetic and use Synthetic style plus synthetic_span.

pub opaque type Node

PathSegment

</>

One step in a nested YAML lookup path.

pub type PathSegment {
  Key(String)
  Index(Int)
}

Constructors

```
Key(String)
```
Selects a value from a mapping by string key.

Example path segment for YAML name: yum is Key(“name”).
```
Index(Int)
```
Selects a value from a sequence by zero-based index.

Example path segment for the first item is Index(0).

Position

</>

A 1-based source position.

pub type Position {
  Position(row: Int, column: Int)
}

Constructors

```
Position(row: Int, column: Int)
```

Span

</>

A half-open source span for a parsed YAML node.

Parsed spans use 1-based row and column positions. Builder-created nodes use synthetic_span.

pub type Span {
  Span(start: Position, end: Position)
}

Constructors

```
Span(start: Position, end: Position)
```

Style

</>

The source style used to write a YAML node.

Style records presentation details that are useful for tooling and diagnostics. It does not change the semantic Kind.

pub type Style {
  PlainScalar
  SingleQuotedScalar
  DoubleQuotedScalar
  LiteralBlockScalar
  FoldedBlockScalar
  BlockSequence
  FlowSequence
  BlockMapping
  FlowMapping
  Synthetic
}

Constructors

```
PlainScalar
```
A plain scalar with no quotes or block marker.

Example YAML:
```
hello
```
```
SingleQuotedScalar
```
A single-quoted scalar.

Example YAML:
```
'hello'
```
```
DoubleQuotedScalar
```
A double-quoted scalar.

Example YAML:
```
"hello"
```
```
LiteralBlockScalar
```
A literal block scalar introduced with the vertical bar marker.

Example YAML:
```
script: |
  hello
```
```
FoldedBlockScalar
```
A folded block scalar introduced with the greater-than marker.

Example YAML:
```
description: >
  hello
```
```
BlockSequence
```
A block-style sequence.

Example YAML:
```
- one
```
```
FlowSequence
```
A flow-style sequence.

Example YAML:
```
[one, two]
```
```
BlockMapping
```
A block-style mapping.

Example YAML:
```
name: yum
```
```
FlowMapping
```
A flow-style mapping.

Example YAML:
```
{name: yum}
```
```
Synthetic
```
A generated node with no original source spelling.

Builder-created nodes use this style.

Values

alias

</>

pub fn alias(node: Node) -> option.Option(String)

Returns the YAML alias name attached to a node, if one was written or added.

For source YAML like copy: *base, the value node under copy has alias base. Resolving checks that aliases refer to anchors seen earlier in the document, but alias metadata can still be inspected on the node.

anchor

</>

pub fn anchor(node: Node) -> option.Option(String)

Returns the YAML anchor name attached to a node, if one was written or added.

For source YAML like defaults: &base { retries: 1 }, the value node under defaults has anchor base. Resolving validates duplicate anchors but does not remove anchor metadata from nodes.

as_bool

</>

pub fn as_bool(node: Node) -> Result(Bool, AccessError)

Returns the boolean value when the node is a boolean.

Returns ExpectedKind when the node is not a boolean.

as_float

</>

pub fn as_float(node: Node) -> Result(Float, AccessError)

Returns the finite float value when the node is a float.

Returns ExpectedKind when the node is not a finite float. Special float values have separate kinds: PosInf, NegInf, and Nan.

as_int

</>

pub fn as_int(node: Node) -> Result(Int, AccessError)

Returns the integer value when the node is an integer.

Returns ExpectedKind when the node is not an integer.

as_mapping

</>

pub fn as_mapping(
  node: Node,
) -> Result(List(#(Node, Node)), AccessError)

Returns mapping entries when the node is a mapping.

Returns ExpectedKind when the node is not a mapping.

as_null

</>

pub fn as_null(node: Node) -> Result(Nil, AccessError)

Returns Nil when the node is null.

Returns ExpectedKind when the node is not null.

as_sequence

</>

pub fn as_sequence(node: Node) -> Result(List(Node), AccessError)

Returns sequence entries when the node is a sequence.

Returns ExpectedKind when the node is not a sequence.

as_string

</>

pub fn as_string(node: Node) -> Result(String, AccessError)

Returns the string value when the node is a string.

Returns ExpectedKind when the node is not a string.

get

</>

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

Returns a nested node by following mapping keys and sequence indexes.

This is a convenience wrapper around get_key and get_index. It returns None when any path segment does not match the current node.

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

pub fn example() {
  let assert Ok(document) = yaml.parse("jobs:\n  test:\n    run: gleam test")
  let root = yaml.root(document)

  let run = root |> node.get([
    node.Key("jobs"),
    node.Key("test"),
    node.Key("run"),
  ])

  let value = run |> option.map(node.as_string)

  assert value == option.Some(Ok("gleam test"))
}

get_index

</>

pub fn get_index(node: Node, index: Int) -> option.Option(Node)

Returns a sequence item by zero-based index.

Returns None when the node is not a sequence or when the index is out of bounds. Negative indexes always return None.

get_key

</>

pub fn get_key(node: Node, key: String) -> option.Option(Node)

Returns a mapping value by string key.

Only string keys are matched. Returns None when the node is not a mapping, when the key is not present, or when a mapping entry uses a non-string key.

get_keys

</>

pub fn get_keys(node: Node) -> Result(List(Node), AccessError)

Returns all keys from a mapping node.

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

get_values

</>

pub fn get_values(node: Node) -> Result(List(Node), AccessError)

Returns all values from a mapping node.

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

kind

</>

pub fn kind(node: Node) -> Kind

Returns the semantic kind and value of a node.

This is the broadest accessor. Prefer the stricter as_* functions when a caller expects one specific YAML kind and wants a typed error for mismatches.

kind_name

</>

pub fn kind_name(node: Node) -> KindName

Returns the node kind without its associated value.

new

</>

pub fn new(
  kind: Kind,
  span span: Span,
  style style: Style,
) -> Node

Creates a YAML node with explicit metadata.

Most callers should prefer yum/yaml.parse plus yum/yaml.root for parsed input or yum/yaml/builder for generated YAML. This constructor is public for tools that need to synthesize nodes while preserving their own source metadata.

span

</>

pub fn span(node: Node) -> Span

Returns the source span for a node.

Parsed nodes use 1-based row and column positions. Synthetic nodes created with yum/yaml/builder use synthetic_span.

style

</>

pub fn style(node: Node) -> Style

Returns the source style used to write a node.

Style describes presentation, such as plain versus quoted scalars or block versus flow collections. It does not change the node’s semantic kind.

synthetic

</>

pub fn synthetic(kind: Kind) -> Node

Creates a generated node with no original source location.

This is the lower-level constructor used by yum/yaml/builder.

synthetic_span

</>

pub fn synthetic_span() -> Span

Returns the placeholder span used for generated nodes with no source.

tag

</>

pub fn tag(node: Node) -> option.Option(String)

Returns the YAML tag attached to a node, if one was written or added.

Tags are metadata, not value casts. A tagged scalar keeps its parsed Kind; for example !!str 123 is still parsed as an integer today, while the tag is available through this function.

On raw YAML, this returns the tag form captured by the parser. On resolved YAML, tag handles are expanded where possible. For example:

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

pub fn example() {
  let assert Ok(document) = yaml.parse("value: !!str 123")
  let assert option.Some(value) = document |> yaml.get([node.Key("value")])

  assert node.tag(value) == option.Some("!str")

  let assert Ok(document) = yaml.resolve(document)
  let assert option.Some(value) = document |> yaml.get([node.Key("value")])

  assert node.tag(value) == option.Some("tag:yaml.org,2002:str")
}

with_alias

</>

pub fn with_alias(node: Node, alias: String) -> Node

Returns a copy of the node with alias metadata.

This function only sets metadata. Use yum/yaml.resolve to check whether the alias refers to a known anchor.

with_anchor

</>

pub fn with_anchor(node: Node, anchor: String) -> Node

Returns a copy of the node with anchor metadata.

This function only sets metadata. Use yum/yaml.resolve to validate anchor and alias relationships.

with_tag

</>

pub fn with_tag(node: Node, tag: String) -> Node

Returns a copy of the node with tag metadata.

This function only sets metadata. It does not validate tag syntax or change the node’s Kind.