Skip to main content

YAML API

YAML parsing and serialization helpers are available under ptool.yaml and p.yaml.

ptool.yaml.parse​

v0.4.0 - Introduced.

ptool.yaml.parse(input) parses a YAML string into a Lua value.

  • input (string, required): The YAML text.
  • Returns: The parsed Lua value. The root can be any supported YAML type.

Type mapping:

  • YAML mapping -> Lua table
  • YAML sequence -> Lua sequence table (1-based)
  • YAML string -> Lua string
  • YAML integer that fits in i64 -> Lua integer
  • Other YAML number -> Lua number
  • YAML boolean -> Lua boolean
  • YAML null -> Lua nil

Error behavior:

  • An error is raised if input is not a string.
  • A YAML syntax error raises an error whose message includes parser detail.
  • An error is raised if the YAML value cannot be represented as a Lua value in ptool, such as a mapping with non-string keys or an explicit YAML tag.

Example:

local data = p.yaml.parse([[
name: ptool
features:
  - yaml
  - repl
stars: 42
]])

print(data.name)
print(data.features[1])
print(data.stars)

ptool.yaml.get​

v0.4.0 - Introduced.

ptool.yaml.get(input, path) reads the value at a specified path from YAML text.

  • input (string, required): The YAML text.
  • path ((string|integer)[], required): A non-empty path array, such as {"spec", "template", "metadata", "name"} or {"items", 1, "name"}.
  • Returns: The corresponding Lua value, or nil if the path does not exist.

Behavior:

  • String path segments select mapping keys.
  • Integer path segments select sequence elements using Lua's 1-based indexing.

Example:

local text = [[
items:
  - name: alpha
  - name: beta
]]

local first_name = p.yaml.get(text, {"items", 1, "name"})
print(first_name)

ptool.yaml.stringify​

v0.4.0 - Introduced.

ptool.yaml.stringify(value) converts a Lua value to YAML text.

  • value (YAML-compatible Lua value, required): The value to encode.
  • Returns: The encoded YAML string.

Behavior:

  • Values must be YAML-compatible through the same Lua value mapping used by ptool.json.stringify.
  • Lua sequence tables are encoded as YAML sequences.
  • Lua string-keyed tables are encoded as YAML mappings.

Example:

local text = p.yaml.stringify({
  project = "ptool",
  features = {"yaml", "lua"},
  stable = true,
})

print(text)

Notes:

  • Only single-document YAML is supported.
  • YAML mappings must use string keys.
  • Explicit YAML tags are not supported.
  • The path argument for ptool.yaml.get must be a non-empty array of strings and/or positive integers.
  • Integer path segments are 1-based so they match Lua array indexing.