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/yaml.kit`	Example: generated documents and value formatting
`kit.toml`	Package manifest with metadata and tasks
`src/yaml.kit`	kit-yaml: YAML value types, generation, and formatting helpers
`tests/yaml.test.kit`	Tests for YAML 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

  # 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 currently supports YAML generation from YamlValue values:

YamlString
YamlInt
YamlFloat
YamlBool
YamlNull
YamlList

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

YAML parsing is temporarily disabled in the source module due to memory constraints in the current Kit interpreter. The package still exposes YamlError constructors for API compatibility and future parser work, but the public runtime API should be treated as generation-focused for now.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/debug.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 --no-spinner

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/yaml.kit --no-spinner

Running Parity

Check that examples behave the same when interpreted and compiled:

kit parity --no-spinner --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 {String}

Text value (quoted or unquoted)

YamlInt {Int}

Integer value

YamlFloat {Float}

Floating-point value

YamlBool {Bool}

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:

[{key: String, value: YamlValue}] -> String

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:

YamlValue -> String

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]