Getting Started

KSON is a fully self-contained configuration language designed to be an improved interface on plain text data. This guide will help you get started with KSON across different environments and use cases.

Playground

Try KSON directly in your browser without any installation: kson.org/playground

Languages

Python

Install via pip:

pip install kson-lang

Usage:

from kson import Kson, Success
result = Kson.to_json("key: [1, 2, 3, 4]")
assert isinstance(result, Success)
print(result.output())

Rust

Add to your Cargo.toml:

[dependencies]
kson-rs = "0.1.1"

Usage:

use kson_rs::Kson;

fn main() {
    let json = Kson::to_json("key: [1, 2, 3, 4]")
        .map_err(|_| "unreachable: kson input is guaranteed to be valid!")
        .unwrap();
    println!("{}", json.output());
}

Java/JVM

For JVM-only projects, add to your build.gradle:

dependencies {
    implementation("org.kson:kson-jvm:0.1.1")
}

Or with Maven in pom.xml:

<dependency>
    <groupId>org.kson</groupId>
    <artifactId>kson-jvm</artifactId>
    <version>0.1.1</version>
</dependency>

Usage:

import org.kson.Kson;
import org.kson.Result;

public class Main {
    public static void main(String[] args) {
        // Convert KSON to JSON
        Result result = Kson.INSTANCE.toJson(
            "server: {\n" +
            "    host: \"localhost\"\n" +
            "    port: 8080\n" +
            "}"
        );

        if (result instanceof Result.Success) {
            System.out.println(((Result.Success) result).getOutput());
        } else if (result instanceof Result.Failure) {
            Result.Failure failure = (Result.Failure) result;
            failure.getErrors().forEach(System.out::println);
        }
    }
}

Kotlin Multiplatform (JVM, JS, Native)

For Kotlin Multiplatform projects, add to your build.gradle:

dependencies {
    implementation("org.kson:kson:0.1.1")
}

Usage:

import org.kson.Kson
import org.kson.Result

fun main() {
    // Convert KSON to JSON
    val result = Kson.toJson(
        """
            server: {
                host: "localhost"
                port: 8080
            }
        """.trimIndent()
    )
    when (result) {
        is Result.Success -> {
            println(result.output)
        }
        is Result.Failure -> {
            println(
                result.errors.joinToString("\n")
            )
        }
    }
}

JavaScript/TypeScript

Install via npm:

npm i @kson_org/kson

Usage:

import { Kson, Result } from '@kson_org/kson';

const kson = Kson.getInstance();

// Convert KSON to JSON
const result = kson.toJson('key: [1, 2, 3, 4]');
if (result instanceof Result.Success) {
  console.log(result.output);
}

Editor Support

IntelliJ IDEA

Install the KSON plugin directly from the JetBrains Marketplace:

1. Open IntelliJ IDEA
2. Go to Settings/Preferences → Plugins
3. Search for "KSON"
4. Click Install and restart the IDE

Visual Studio Code

Install the KSON extension from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "KSON"
4. Click Install

Or directly download from the VS Code Marketplace

CLI Tool

The KSON CLI provides command-line utilities for working with KSON files.

Installation

Currently the CLI is not published to any package manager yet. However, it is possible to use it by cloning the source code and following the instructions.

git clone github.com/kson-org/kson
cd kson
./gradlew :tooling:cli:buildNativeImage

This will generate the cli-binary in tooling/cli/build/native/nativeCompile/.

Development/Building from Source

If you want to build KSON from source:

# Clone the repository
git clone https://github.com/kson-org/kson.git
cd kson

# Build with Gradle
./gradlew check

Next Steps

• Read the Syntax Guide to learn KSON's syntax
• Join our Zulip community for help and discussions