tree-sitter-ktav

A tree-sitter grammar for Ktav (כְּתָב) — the Written Configuration Format.

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

Playground: convert JSON / YAML / TOML / INI ⇄ Ktav in your browser at ktav-lang.github.io.

What is Ktav?

Ktav (Hebrew כְּתָב, "writing") is a plain-text configuration format. JSON-shape (scalars, arrays, objects, null, booleans), but without quotes around strings, without commas, and with dotted keys (server.port: 8080) for nesting. The full specification — the same one all official Ktav implementations target — lives in the ktav-lang/spec repository.

What is tree-sitter?

Tree-sitter is an incremental parser generator. Editors (Neovim, Helix, Emacs, VS Code, Zed, …) use it for syntax highlighting, code folding, structural selection, and other features that need a real parse tree rather than a regex-based tokenizer. Each language ships its own grammar package; this crate / npm package is the one for Ktav.

Installation

Rust (`tree-sitter` crate)

[dependencies]
tree-sitter         = "0.25"
tree-sitter-ktav    = "0.6.0"

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut parser = tree_sitter::Parser::new();
    parser.set_language(&tree_sitter_ktav::LANGUAGE.into())?;

    let source = "name: Russia\nport: 8080\n";
    let tree = parser.parse(source, None).unwrap();
    println!("{}", tree.root_node().to_sexp());
    Ok(())
}

Node.js (`tree-sitter` package)

npm install tree-sitter tree-sitter-ktav

const Parser = require("tree-sitter");
const Ktav   = require("tree-sitter-ktav");

const parser = new Parser();
parser.setLanguage(Ktav);

const tree = parser.parse("name: Russia\nport: 8080\n");
console.log(tree.rootNode.toString());

Editor integration

Neovim (with `nvim-treesitter`)

Until the grammar is upstreamed, register it manually in your config:

require("nvim-treesitter.parsers").get_parser_configs().ktav = {
  install_info = {
    url = "https://github.com/ktav-lang/tree-sitter-ktav",
    files = { "src/parser.c" },
    branch = "main",
  },
  filetype = "ktav",
}

vim.filetype.add({ extension = { ktav = "ktav" } })

Then :TSInstall ktav. Drop queries/highlights.scm, queries/locals.scm, and queries/injections.scm into your ~/.config/nvim/queries/ktav/ directory (or let nvim-treesitter pick them up from the parser repo).

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name      = "ktav"
scope     = "source.ktav"
file-types = ["ktav"]
roots     = []
comment-token = "#"
indent    = { tab-width = 4, unit = "    " }

[[grammar]]
name   = "ktav"
source = { git = "https://github.com/ktav-lang/tree-sitter-ktav", rev = "main" }

Then hx --grammar fetch && hx --grammar build.

Other editors

The grammar exports the standard tree-sitter node-type metadata (src/node-types.json) and queries (queries/*.scm), so any editor with tree-sitter support can consume it once the parser is built.

Node types

The grammar produces the following named nodes:

Node	What it captures
`source_file`	the whole document
`comment`	a `#`-line comment
`blank_line`	an empty line
`object_pair`	`key SEP value` line
`key` / `dotted_key`	the key portion (with optional `.` separators)
`sep_string` / `sep_raw` / `sep_int` / `sep_float`	the four separators
`keyword` / `kw_null` / `kw_true` / `kw_false`	keywords
`scalar`	the catch-all single-line value body
`compound_object`	`{` … `}` block
`compound_array`	`[` … `]` block
`array_item`	a single item in an array
`multiline_stripped`	`(` … `)` block
`multiline_verbatim`	`((` … `))` block
`multiline_content_line`	a single line inside a multi-line string
`empty_object` / `empty_array` / `empty_paren` / `empty_double_paren`	inline empty forms
`empty_value`	separator immediately followed by EOL

object_pair exposes key, separator, and value as fields; array_item exposes marker (optional) and value.

Building from source

git clone https://github.com/ktav-lang/tree-sitter-ktav.git
cd tree-sitter-ktav
npm install
npx tree-sitter generate     # writes src/parser.c
npx tree-sitter test         # runs the corpus

The generated src/parser.c, src/grammar.json, src/node-types.json, and src/tree_sitter/* are checked into git per tree-sitter convention, so consumers do not need the CLI to build.

Status

0.6.0 — implements Ktav 0.6.0. The grammar accepts every valid Ktav 0.6.0 document (verified against all tests/valid/*.ktav fixtures from the spec repo). It is a syntactic accepter, not a strict spec validator — see CHANGELOG.md "Known limitations" for the small number of pathological cases the grammar accepts that the spec rejects (mostly missing-whitespace-after-marker — § 6.10).

License

Dual-licensed under MIT OR Apache-2.0 — see LICENSE-MIT and LICENSE-APACHE.

Other Ktav repositories

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

tree-sitter-ktav 0.6.1