yaml reads YAML 1.2 text into Agentica's JSON.Value. From there, JSON.decode turns it into your records, so a configuration file or a test fixture can be YAML. It is pure Agentica and does no I/O: give it the text.

It is safe by design. It reads the core schema only, so a document gives data and nothing else: any tag other than the core ones is an error, and limits stop deep nesting, alias bombs and huge texts before they use the stack or the memory.

import YAML from "pkg/yaml/yaml"

TEXT = <<~YAML
  # The settings of the app
  name: shop
  debug: false
  servers:
    - host: a.example.com
      port: 8080
      tags: &web [web, eu]
    - {host: b.example.com, port: 0x1F90, tags: *web}
YAML

struct Server
  host: String
  port: Int
  tags: List[String]
end

struct Config
  name: String
  debug: Bool
  servers: List[Server]
end

def load(text: String) -> Result[Config]
  value = try YAML.parse(text)
  JSON.decode(value, Config)
end

def main() -> Void
  case load(TEXT)
    ok(config) -> puts("#{config.name}: #{config.servers.map(->(s) { "#{s.host}:#{s.port} #{s.tags}" }).join(", ")}")
    error(e) -> puts(e.message)
  end

  case YAML.parse("name: shop\n  debug: [true")
    ok(value) -> puts(value)
    error(e) -> puts("#{e.kind} at #{e.details["line"]}:#{e.details["column"]}: #{e.message}")
  end
end
Output
shop: a.example.com:8080 ["web", "eu"], b.example.com:8080 ["web", "eu"]
yaml.parse at 2:8: line 2, column 8: mapping values are not allowed here

Install #

Needs Agentica 0.32.0 or later. Add it with the prefixed tag of the release, in a project with an agentica.toml:

agentica add yaml https://github.com/agentica-lang/packages --tag yaml-0.1.0 --subdir yaml

That writes this line of agentica.toml, and the entry of agentica.lock:

[dependencies]
yaml = { git = "https://github.com/agentica-lang/packages", tag = "yaml-0.1.0", subdir = "yaml" }

The releases and their notes are in the changelog.

Reference #

Everything is under YAML, from import YAML from "pkg/yaml/yaml".

YAML.parse(text: String, options: YAML.Options = YAML.Options()) -> Result[JSON.Value]
YAML.parse_all(text: String, options: YAML.Options = YAML.Options()) -> Result[List[JSON.Value]]
  • YAML.parse reads a text of one document. A text with no document (empty, or only comments) is null; a second document is an error.
  • YAML.parse_all reads a stream: the documents between --- and ... markers, in order, with their %YAML and %TAG directives.

YAML.Options holds the limits; give only the ones you change, as in YAML.Options(max_bytes: 16_777_216):

FieldDefaultWhat it limits
max_depth256the nested collections, aliases included, 1 to 1000 (another value is an argument error)
max_alias_nodes100,000the nodes that aliases add, counted as if each alias were a copy of its anchor
max_alias_bytes10,485,760the bytes of scalars and keys that aliases add, counted the same way
max_bytes4,194,304the bytes of the text, checked before any parsing

What it reads #

All of YAML 1.2 that has a JSON value:

  • block and flow mappings and sequences, explicit keys (? key), and compact forms (- name: x);
  • every scalar style: plain, single-quoted, double-quoted with all its escapes, literal | and folded > with the chomping (-, +) and indentation indicators;
  • comments, anchors &a and aliases *a, documents, and the %YAML and %TAG directives.

A plain scalar takes its type from the core schema: null, ~ and an empty value are null; true and false (also True, TRUE, ...) are booleans; 42, -7, 0x1F and 0o17 are integers (one past 64 bits keeps its exact digits, up to 256 digits for 0x and 0o, and a longer one is an error); 1.5, .5 and 1e3 are floats; anything else is a string. yes, no, on and off are strings, as in YAML 1.2. A quoted or block scalar is always a string. The core tags pick a type: !!str, !!int, !!float, !!bool, !!null, !!seq, !!map, and ! (a string).

Errors #

A failure is an error whose message starts with the line and the column (from 1, in characters), which e.details also has as "line" and "column". Its kind is yaml.parse for a text that is not valid, or that has no JSON value, and yaml.limit for a text over a limit of the options. These are errors:

  • a tag other than the core ones (!foo, !!set, !!binary, !!timestamp): no document builds anything but data;
  • a mapping key that is not a string (200: ok, [a, b]: c, an empty key), since JSON keys are strings: quote it ("200": ok);
  • a key given twice in one mapping;
  • .inf, -.inf and .nan, and a float that does not fit, since JSON has no infinity or NaN;
  • an alias with no anchor before it.

Not read, for now: writing YAML, the YAML 1.1 extras (yes and no as booleans, << merge keys, sexagesimal numbers) and custom tags.