yaml

Kind	kit
Categories	parser data-format config
Keywords	yaml parser config serialization data-format

YAML parsing and generation for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic YAML generation example
`examples/debug.kit`	Example: compact debug output
`examples/parse.kit`	Example: parsing a small YAML config
`examples/yaml.kit`	Example: generated documents and value formatting
`kit.toml`	Package manifest with metadata and tasks
`src/yaml.kit`	kit-yaml: YAML value types, parsing, generation, and formatting helpers
`tests/yaml.test.kit`	Tests for YAML parsing, generation, and value helpers

Dependencies

No Kit package dependencies.

This package is implemented in pure Kit and does not require C, Zig, or system libraries.

Installation

kit add gitlab.com/kit-lang/packages/kit-yaml.git

Usage

import Kit.Yaml as YAML

main = fn =>
  # Generate a flat YAML document from key/value pairs
  pairs = [
    {key: "name", value: YamlString "My Application"},
    {key: "version", value: YamlString "1.0.0"},
    {key: "port", value: YamlInt 8080},
    {key: "debug", value: YamlBool true},
    {key: "rate", value: YamlFloat 3.14},
    {key: "empty", value: YamlNull}
  ]

  yaml = YAML.generate pairs
  println yaml

  # Parse a flat YAML document
  parsed = YAML.parse "name: My Application\nport: 8080\ntags: [kit, yaml]"
  match parsed
    | Ok values -> println "Parsed ${List.length values} values"
    | Err err -> println ("Parse failed: " ++ (show err))

  # Convert individual values to YAML-formatted strings
  println (YAML.value-to-string (YamlString "hello world"))
  println (YAML.value-to-string (YamlList [YamlInt 1, YamlInt 2, YamlInt 3]))

main

Generated output:

name: "My Application"
version: "1.0.0"
port: 8080
debug: true
rate: 3.14
empty: null

Current Scope

kit-yaml supports a deliberately bounded YAML subset:

YamlString
YamlInt
YamlFloat
YamlBool
YamlNull
YamlList

YAML.parse reads flat key: value mappings with quoted and unquoted strings, ints, floats, bools, nulls, inline lists, comments, and blank lines. It reports YamlError variants for malformed lines, indentation, invalid values, unclosed strings/lists, and duplicate keys.

YAML.generate creates simple flat YAML documents from {key, value} records. YAML.value-to-string formats a single YamlValue, including inline list values.

Nested mappings, block lists, anchors, tags, and multiline scalars are intentionally out of scope for this first parser.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/debug.kit
kit run examples/parse.kit
kit run examples/yaml.kit

Compile an example to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Check formatting
Type check source files in src/
Type check examples in examples/
Run tests in tests/ with coverage

Checking All Package Sources

For a direct check of the files used by this package:

kit check src/yaml.kit tests/yaml.test.kit examples/basic.kit examples/debug.kit examples/parse.kit examples/yaml.kit

Running Parity

Check that examples behave the same when interpreted and compiled:

kit parity --failures-only

This runs the examples in examples/, builds them, executes the compiled binaries, and compares output.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/yaml.kit -o docs/yaml.html

Note: Kit sources with doc comments (##) generate HTML documentation.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/yaml/, making it available for import as Kit.Yaml in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`YamlValue`

YAML value types for typed access.

Variants

YamlString {_0}

Text value (quoted or unquoted)

YamlInt {_0}

Integer value

YamlFloat {_0}

Floating-point value

YamlBool {_0}

Boolean value (true/false, yes/no)

YamlNull

Null/empty value (null, ~, or empty)

YamlList {_0}

List of YAML values

`YamlError`

YAML parse error types.

Variants

SyntaxError {line, message}

General syntax error

InvalidIndentation {line, message}

Invalid indentation

InvalidValue {line, key, message}

Invalid value for a key

UnclosedString {line}

Unclosed string literal at line

UnclosedList {line}

Unclosed list at line

DuplicateKey {line, key}

Duplicate key definition

`Yaml`

Marker type for the YAML format. Used with StringEncode/StringDecode traits to distinguish YAML serialization.

Variants

Yaml

`generate`

Generates YAML string from list of {key, value} records.

Creates a simple flat YAML document with key: value pairs.

Parameters:

Returns:

pairs = [
  {key: "name", value: YamlString "MyApp"},
  {key: "port", value: YamlInt 8080},
  {key: "enabled", value: YamlBool true}
]
yaml-str = YAML.generate pairs
# Output:
# name: "MyApp"
# port: 8080
# enabled: true

`value-to-string`

Converts a YamlValue to its string representation.

Parameters:

Returns:

str-val = YAML.value-to-string (YamlString "hello")
# Returns: "hello"

int-val = YAML.value-to-string (YamlInt 42)
# Returns: 42

bool-val = YAML.value-to-string (YamlBool true)
# Returns: true

list-val = YAML.value-to-string (YamlList [YamlInt 1, YamlInt 2])
# Returns: [1, 2]

`parse`

Parses a bounded YAML subset into key/value pairs.

Supported input: - Flat mappings: key: value - Scalars: strings, ints, floats, bools, and nulls - Inline scalar lists: [one, 2, true] - Blank lines and comments

Unsupported YAML features return syntax/indentation/value errors rather than attempting full YAML 1.2 parsing.