kdl-go

Package kdl implements a parser and emitter for the KDL document format (version 1 and 2). It supports reading and writing KDL documents, as well as decoding KDL documents into Go data structures and encoding them back into KDL.

This implementation follows the KDL 1.0.0 and 2.0.0 specifications and passes the upstream test suite for each (see kdl_test.go), as well as the v2 parse-only kdl-test suite. Note that the parser primarily targets the v2 spec and is somewhat more permissive when parsing v1 input.

Other features include:

• Pretty-printing via Format
• KDL Schema validation via ParseSchema & ValidateDocument
• Panic-mode recovery and multi-error diagnostics via ParseWithDiagnostics
• AST traversal via Walk

Visit pkg.go.dev for the full documentation.

Caution

This package's public 0.x API is not stable yet and may change at any time. Use at your own risk.

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/calico32/kdl-go"
)

const configKdl = `
host example1 {
	user root
	hostname example.com
	port 22
}

host example2 {
	user http
	hostname example.org
	port 2022
}
`

type Config struct {
	Hosts []*Host `kdl:"host,multiple"`
}

type Host struct {
	Name     string `kdl:",argument"`
	User     string `kdl:"user"`
	Hostname string `kdl:"hostname"`
	Port     int    `kdl:"port"`
}

func main() {
    // open a KDL document (or, read from a string in this case)
	f := strings.NewReader(configKdl)

    // decode it into a Config
	var config Config
	err := kdl.Decode(f, &config)
	if err != nil {
		panic(err)
	}

    // print out the hosts
	for _, host := range config.Hosts {
		fmt.Printf("%s: %s@%s:%d\n", host.Name, host.User, host.Hostname, host.Port)
		// example1: root@example.com:22
		// example2: http@example.org:2022
	}

    // create an output file
	out, err := os.Create("output.kdl")
	if err != nil {
        panic(err)
	}

    // encode the Config back into KDL
	err = kdl.Encode(config, out)
	if err != nil {
		panic(err)
	}
}

Running Tests

The upstream KDL test suites are included as submodules in internal/test/kdl{1,2}. To run them, first initialize the submodules:

git submodule update --init

Then, run the tests with:

go test -v ./...

To run kdl-test (a v2-only parse-only suite), download and install the test runner from GitHub. Then, from the root of this repository, run:

go build -o kdlgo-test ./bin/kdlgo-test
kdl-test run --decoder ./kdlgo-test

License

kdl-go is licensed under the MIT License. See LICENSE for details.

The KDL Schema schema (schema/kdl-schema.kdl) is licensed under CC-BY-SA-4.0. See schema/LICENSE for details.