Skip to content
starpkgPublic

About

πŸ“‹ TOML decode/encode for Starlark, hardened like its YAML sibling

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

15 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“‘ toml β€” TOML for Starlark

Go Reference codecov binary footprint

Decode and encode TOML from Starlark, built on BurntSushi/toml.

Both directions are hardened: nesting depth is bounded before the recursive codec runs (a deeply nested document would otherwise overflow the stack β€” a fatal error recover() cannot catch); decode also bounds input size and node count; the caps are host-only (a script cannot widen them); panics become errors; and TOML's native date/time values are surfaced as strings.

Overview

starpkg modules give Starlark scripts support for necessary local operations plus simple abstractions over common online services, for ease of use. toml is a local capability: it is a pure in-process codec β€” no network, no filesystem, no host services β€” turning TOML text into Starlark values and back.

  • decode(text) β€” parse a TOML document (string or bytes) into Starlark values (a dict).
  • encode(value) β€” serialize a dict to TOML text.
  • Hardened both ways β€” nesting depth bounded before the recursive codec runs (decode caps the text's bracket-opener count; encode walks the value), plus bounded input size and node count on decode; host-only caps; panics recovered into errors; date/time surfaced as strings; deterministic key order.

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/toml

Quickstart

load("toml", "decode", "encode")

doc = decode("""
name = "Ada"
langs = ["go", "python"]

[nested]
k = "v"
""")
doc["name"]            # => "Ada"
doc["langs"][0]        # => "go"
doc["nested"]["k"]     # => "v"

encode({"a": 1, "b": [1, 2]})   # => "a = 1\nb = [1, 2]\n"

Starlark API at a glance

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

  • decode(text) β€” parse a TOML document (string or bytes) into a dict.
  • encode(value) β€” serialize a dict to TOML text (the top-level value must be a dict, since TOML documents are tables).

See docs/API.md for the full signatures, decoded value types, return values, errors, and examples of both builtins.

Configuration

The codec caps (max_depth, used by both decode and encode; max_nodes and max_input_bytes, used by decode) are host-only β€” they are DoS limits the module enforces against untrusted scripts, so each has a read-only get_<key> but no set_<key>, and a script cannot raise it. Configure them host-side via the TOML_* environment variables. See the Configuration section of docs/API.md for the full option table, defaults, and accessors.

License

MIT

About

πŸ“‹ TOML decode/encode for Starlark, hardened like its YAML sibling

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages