tree-sitter-eskip

Tree-sitter grammar for eskip — the routing configuration language used by Skipper.

Language overview

Eskip is a DSL for defining HTTP routing rules. Each rule is a route definition: a named predicate expression, an optional chain of filters, and a backend target.

// Route with predicates, filters, and a network backend
api: Method("GET") && Host(/^api\.example\.org$/) && Path("/api/:id")
  -> setRequestHeader("X-Foo", "bar")
  -> ratelimit(10, "1m")
  -> "https://backend.example.org";

// Catch-all that shunts (terminates) the request
catchall: * -> inlineContent("not found") -> status(404) -> <shunt>;

// Load-balanced backend with explicit algorithm
lb: Path("/lb")
  -> <roundRobin, "https://a.example.org", "https://b.example.org">;

Supported constructs

Construct	Example
Route definition	name: predicates -> backend ;
Predicate	Path("/foo"), Method("GET")
Multiple predicates	Method("GET") && Path("/foo")
Wildcard predicate	*
Filter chain	-> setRequestHeader("X-A", "b") -> ratelimit(10, "1m")
String backend	-> "https://example.org"
Shunt backend	-> <shunt>
Loopback backend	-> <loopback>
Dynamic backend	-> <dynamic>
Load-balanced backend	-> <roundRobin, "https://a.org", "https://b.org">
String arguments	"double-quoted", `backtick raw`
Regexp arguments	/^pattern$/
Number arguments	404, 3.14, -1
Comments	// line comment

Load-balancing algorithms: roundRobin, random, consistentHash, powerOfRandomNChoices

Syntax highlighting

The queries/highlights.scm file maps grammar nodes to standard Tree-sitter capture names:

Capture	Node
@function	route identifier
@function.method	predicate / filter name
@keyword	lb algorithm
@constant.builtin	shunt, loopback, dynamic
@operator	->, &&, *
@string / @string.regexp / @string.escape	string / regexp / escape
@number	number
@comment	line comment
@punctuation.delimiter	:, ;, ,
@punctuation.bracket	(, ), <, >

Installation

Node.js

npm install tree-sitter-eskip

import Parser from "tree-sitter";
import Eskip from "tree-sitter-eskip";

const parser = new Parser();
parser.setLanguage(Eskip);
const tree = parser.parse(`hello: Path("/hello") -> "https://example.org";`);

Rust

[dependencies]
tree-sitter-eskip = "0.1"

let language = tree_sitter_eskip::LANGUAGE;

Python

pip install tree-sitter-eskip

import tree_sitter_eskip
from tree_sitter import Language, Parser

lang = Language(tree_sitter_eskip.language())
parser = Parser(lang)

Go

go get github.com/carloluis/tree-sitter-eskip

import (
    "github.com/tree-sitter/go-tree-sitter"
    tree_sitter_eskip "github.com/carloluis/tree-sitter-eskip/bindings/go"
)

language := tree_sitter.NewLanguage(tree_sitter_eskip.Language())

C

#include "tree_sitter/parser.h"

const TSLanguage *tree_sitter_eskip(void);

Build with make or cmake.

Neovim

This repo ships as a Neovim plugin. Install it with your plugin manager, then call setup() to register the parser and enable highlighting.

vim.pack (built-in, no plugin manager required)

-- in your init.lua:
vim.pack.add({ "https://github.com/carloluis/tree-sitter-eskip" })
require("tree-sitter-eskip").setup()

vim.pack.add downloads and installs the plugin on first run, then calls :packadd so it is available immediately in the same session.

lazy.nvim

{
  "carloluis/tree-sitter-eskip",
  ft = "eskip",
  config = function()
    require("tree-sitter-eskip").setup()
    -- then install the parser the first time:
    -- :TSInstall eskip
  end,
}

lazy.nvim / vim-plug / packer

-- in your init.lua, after the plugin is on the runtimepath:
require("tree-sitter-eskip").setup()

setup() does three things:

1. Registers the parser source with nvim-treesitter so :TSInstall eskip works.
2. Calls vim.treesitter.language.register to bind the eskip language to the eskip filetype.
3. Creates a FileType eskip autocommand that starts tree-sitter highlighting for every eskip buffer.

Filetype detection for *.eskip files is handled automatically via ftdetect/eskip.lua, which is sourced by Neovim's runtimepath on startup — no extra configuration needed.

After installing the plugin, run :TSInstall eskip once to compile the parser. Verify with:

:checkhealth nvim-treesitter
:InspectTree       " parse tree for the current buffer
:Inspect           " highlight captures under cursor

Development

# Regenerate parser from grammar.js
tree-sitter generate

# Run corpus tests
tree-sitter test

# Parse example files
tree-sitter parse examples/*.eskip --quiet --stat

# Launch the playground (builds WASM first)
npm start

License

MIT