yaml

📄 yaml — YAML for Starlark

Decode and encode YAML from Starlark, built on gopkg.in/yaml.v3.

Decoding is hardened: input size, nesting depth, and total node count are bounded; parse panics become errors; and YAML's bare-timestamp footgun is tamed.

Where this fits. starpkg is support for necessary local operations plus simple abstractions over common online services, for ease of use. yaml is a local capability — a pure in-process text↔value codec with no network, filesystem, or external service involved.

For the complete per-builtin reference — signatures, parameters, returns, errors, examples — and the configuration accessors, see docs/API.md.

Installation

go get github.com/starpkg/yaml

Quickstart

The host constructs a Module and hands its LoadModule() loader to a Starlet machine; the script reaches it through load("yaml", …):

package main

import (
    "github.com/1set/starlet"
    "github.com/starpkg/yaml"
)

func main() {
    m := yaml.NewModule()
    interp := starlet.NewWithLoaders(nil, nil, starlet.ModuleLoaderMap{
        yaml.ModuleName: m.LoadModule(),
    })
    _, _ = interp.RunScript([]byte(`
load("yaml", "decode", "encode")
print(decode("a: 1")["a"])     # => 1
print(encode({"b": [1, 2]}))   # => "b:\n    - 1\n    - 2\n"
`), nil)
}

NewModule() reads the decode caps (max_depth / max_nodes / max_input_bytes) from defaults or the YAML_* environment variables. ModuleName is the constant "yaml".

Starlark API at a glance

Top-level builtins (load("yaml", …)):

• decode(text) — parse a YAML document (string or bytes) into Starlark values.
• encode(value) — serialize a Starlark value to a YAML string.

There are no object methods: decode returns plain Starlark containers/scalars (dict / list / str / int / float / bool / None), and encode returns a str. Bare timestamps decode to RFC 3339 strings; anchors, aliases, and merge keys (<<) resolve through decode.

See docs/API.md for the full signatures, return values, errors, hardening notes, and examples of both builtins.

Configuration

The module's three decode caps (max_depth, max_nodes, max_input_bytes) are configured via environment variables (YAML_*) or per-option get_<key> / set_<key> accessor builtins. See the Configuration section of docs/API.md for the full option table, defaults, and accessors.

License

MIT