ktav

README

ktav — Go bindings

Languages: English · Русский · 简体中文

Go bindings for the Ktav configuration format. Thin wrapper around the reference Rust parser, loaded at runtime through purego — so no cgo on the consumer side, standard go build just works.

go get github.com/ktav-lang/golang

Quick start

Parse — decode straight into a typed struct

package main

import (
    "fmt"

    ktav "github.com/ktav-lang/golang"
)

const src = `
service: web
port:i 8080
ratio:f 0.75
tls: true
tags: [
    prod
    eu-west-1
]
db.host: primary.internal
db.timeout:i 30
`

type Config struct {
    Service string   `json:"service"`
    Port    int64    `json:"port"`
    Ratio   float64  `json:"ratio"`
    TLS     bool     `json:"tls"`
    Tags    []string `json:"tags"`
    DB      struct {
        Host    string `json:"host"`
        Timeout int64  `json:"timeout"`
    } `json:"db"`
}

func main() {
    var cfg Config
    if err := ktav.LoadsInto(src, &cfg); err != nil {
        panic(err)
    }
    fmt.Printf("port=%d host=%s timeout=%ds\n",
        cfg.Port, cfg.DB.Host, cfg.DB.Timeout)
}

Walk — work with the dynamic shape, dispatch on type

dyn, _ := ktav.Loads(src)
for k, v := range dyn.(map[string]any) {
    switch x := v.(type) {
    case bool:           fmt.Printf("%s is bool=%v\n", k, x)
    case int64:          fmt.Printf("%s is int=%d\n", k, x)
    case float64:        fmt.Printf("%s is float=%g\n", k, x)
    case string:         fmt.Printf("%s is str=%q\n", k, x)
    case []any:          fmt.Printf("%s is array(%d)\n", k, len(x))
    case map[string]any: fmt.Printf("%s is object(%d)\n", k, len(x))
    case nil:            fmt.Printf("%s is null\n", k)
    }
}

Build & render — construct a document in code

doc := map[string]any{
    "name":  "frontend",
    "port":  int64(8443),
    "tls":   true,
    "ratio": 0.95,
    "upstreams": []any{
        map[string]any{"host": "a.example", "port": int64(1080)},
        map[string]any{"host": "b.example", "port": int64(1080)},
    },
    "notes": nil,
}
out, _ := ktav.Dumps(doc)
fmt.Print(out)
// name: frontend
// port:i 8443
// tls: true
// ratio:f 0.95
// upstreams: [
//     { host: a.example  port:i 1080 }
//     { host: b.example  port:i 1080 }
// ]
// notes: null

A complete runnable version lives in examples/basic.

API

Function	Purpose
Loads(s string) (any, error)	Parse a Ktav document into native Go values. Top-level may be an Object (map[string]any) or an Array ([]any) per spec § 5.0.1.
LoadsInto(s string, target any) error	Parse into an arbitrary target (struct, map, …) via encoding/json.
Dumps(v any) (string, error)	Render a Go value as Ktav text. Top-level must encode to an object or array.
DumpsForceStrings(v any) (string, error)	Like Dumps, but coerces every leaf scalar (:i, :f, bool, null) to a String via the raw :: marker. Compounds preserve their structure.

Type mapping

Ktav	Go
null	nil
true / false	bool
:i <digits>	int64 if it fits, else *big.Int
:f <number>	float64
bare scalar	string
[ ... ]	[]any
{ ... }	map[string]any (insertion order preserved)

On encode, Go int* / uint* / *big.Int become :i; float32 / float64 become :f; string stays a bare scalar. NaN and ±Inf are rejected. Structs are serialized through encoding/json first, so json:"..." tags are honoured.

How the native library is resolved

At first call the Go package resolves ktav_cabi in this order:

1. $KTAV_LIB_PATH — absolute path to a local build. Most useful for development.
2. User cache — <os.UserCacheDir>/ktav-go/v<version>/…, downloaded on a previous call.
3. GitHub Release download — the matching asset is fetched once from github.com/ktav-lang/golang/releases/download/v<version>/<name> and cached under (2). Requires network on first call after install.

Runtime support

• Go 1.21+.
• Prebuilt binaries for: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64.
• Linux distros must use glibc 2.17+ (Rust's default target). Alpine (musl) support is planned.

License

MIT — see LICENSE.

Other Ktav implementations

• spec — specification + conformance suite
• rust — reference Rust crate (cargo add ktav)
• csharp — C# / .NET (dotnet add package Ktav)
• java — Java / JVM (io.github.ktav-lang:ktav on Maven Central)
• js — JS / TS (npm install @ktav-lang/ktav)
• php — PHP (composer require ktav-lang/ktav)
• python — Python (pip install ktav)

Documentation

Overview

Package ktav is the Go binding for the Ktav configuration format.

The implementation loads a prebuilt `ktav_cabi` shared library via purego (no cgo required on the consumer side). On first call the library is downloaded from the matching GitHub Release and cached under the user cache directory; set $KTAV_LIB_PATH to point at a local build instead.

Type mapping

Loads/Dumps convert between Ktav values and Go values as follows:

Ktav              Go
─────────────── ───────────────────────────
null              nil
true / false      bool
:i <digits>       int64 if it fits, else *big.Int
:f <number>       float64
bare scalar       string
[ ... ]           []any
{ ... }           map[string]any (key order not preserved)

Key order from the source is **not** preserved on either side: decode returns a plain `map[string]any`, and encode goes through `encoding/json`, which emits object keys in alphabetical order. If you need a fixed shape, use `LoadsInto` into a struct.

On encode, Go *big.Int always emits `:i`; Go int / int64 / uint64 emit `:i`; Go float64 emits `:f`; Go string emits a bare scalar. NaN / ±Inf are rejected. Top-level value must encode to a Ktav object (i.e. a map[string]any or struct) or a Ktav array (i.e. a []any or any other JSON-encodable slice). Top-level Arrays render as bare item-per-line — no surrounding `[...]` brackets, per spec § 5.0.1 (added in 0.1.1).

Index

• func Dumps(v any) (string, error)
• func DumpsForceStrings(v any) (string, error)
• func Loads(src string) (any, error)
• func LoadsInto(src string, target any) error
• func NativeVersion() (string, error)
• type Error
  • func (e *Error) Error() string

Functions

func Dumps

func Dumps(v any) (string, error)

Dumps renders a Go value as a Ktav document. The top-level must encode to a JSON object (map[string]any, struct, etc.) or a JSON array (a slice). Top-level Arrays render as bare item-per-line — no surrounding `[...]` brackets, per spec § 5.0.1 (added in 0.1.1).

func DumpsForceStrings

func DumpsForceStrings(v any) (string, error)

DumpsForceStrings renders a Go value as a Ktav document with **every scalar coerced to a String**: typed integers (`:i`), typed floats (`:f`), booleans, and null are flattened to their textual form via the raw-marker `::`. Compounds (Object / Array) preserve their structure; only leaf scalars are coerced.

The output round-trips back through `Loads` as the same set of String scalars — useful for environments or downstream consumers that don't understand the `:i` / `:f` typed markers, or for diffs where you want the textual form to be the canonical source of truth.

Top-level shape rules match `Dumps`: object or array.

func Loads

func Loads(src string) (any, error)

Loads parses a Ktav document and returns its Go representation (see package doc for the mapping).

func LoadsInto

func LoadsInto(src string, target any) error

LoadsInto parses a Ktav document and JSON-unmarshals the tagged intermediate into `target`. Handy for struct-typed configs:

var cfg MyConfig
_ = ktav.LoadsInto(src, &cfg)

`:i` scalars become JSON numbers or JSON strings (if they exceed json.Number precision); `:f` scalars become JSON numbers. Custom types wanting bigint precision should unmarshal into a json.Number field.

func NativeVersion

func NativeVersion() (string, error)

NativeVersion returns the version string baked into the loaded `ktav_cabi` shared library. Useful for diagnostics when a stale cache or KTAV_LIB_PATH points at an out-of-sync build.

Types

type Error

type Error struct{ Msg string }

Error is the binding's error type. Returned from every Loads / Dumps failure — both Rust-side parse/render errors and Go-side decode bugs (malformed tagged JSON, bad integer literal, etc.) — so callers can match all ktav failures with one `errors.As`.

func (*Error) Error

func (e *Error) Error() string