Editor support generalized: shared core, language server, Vim and VS Code (from dev eb5baf9cbe59)
doc/edit/ now holds a shared Python implementation of the language's structural layer (klammertext_edit.py) and a dependency-free language server (klammertext_ls.py), with integrations for Emacs, Sublime Text, Vim, and Visual Studio Code. The editor test suite in tst/ covers the core's API and CLI, the language server protocol, the VS Code extension, headless Vim, and Emacs byte-equality. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
100
doc/edit/vscode/README.md
Normal file
100
doc/edit/vscode/README.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Klammertext support for Visual Studio Code
|
||||
|
||||
VS Code support for editing Klammertext files (`.kt` documents and `.k`
|
||||
klammer definitions): syntax highlighting, delimiter matching and jumping,
|
||||
structural reindentation, table alignment, and delimiter diagnostics in the
|
||||
Problems panel.
|
||||
|
||||
The extension has **no npm dependencies and no build step**. Highlighting
|
||||
is a TextMate grammar (converted from the Sublime Text syntax); everything
|
||||
structural comes from the **Klammertext language server**
|
||||
(`klammertext_ls.py`), a dependency-free Python process the extension
|
||||
spawns, which itself runs the shared editor core (`klammertext_edit.py`)
|
||||
used by the Sublime Text and Vim integrations. One implementation of the
|
||||
language's structure, everywhere.
|
||||
|
||||
## Requirements
|
||||
|
||||
- VS Code 1.75 or later — a minimum, not a target: VS Code's monthly
|
||||
releases count 1.75, 1.76, … (1.75 is from January 2023), so any
|
||||
version from the last few years qualifies.
|
||||
- `python3` on `PATH` (or set `klammertext.pythonPath`); Klammertext itself
|
||||
already requires Python.
|
||||
- The language server, found automatically in this order:
|
||||
1. the `klammertext.serverPath` setting, if set;
|
||||
2. `klammertext_ls.py` vendored next to `extension.js` (the layout the
|
||||
Klammertext editing zip ships);
|
||||
3. `../shared/klammertext_ls.py` relative to the extension directory (the
|
||||
layout of the Klammertext repository — using the extension straight
|
||||
from a checkout just works);
|
||||
4. `$KLAMMERTEXT_HOME/doc/edit/shared/klammertext_ls.py`.
|
||||
|
||||
## Install
|
||||
|
||||
Copy this `vscode/` directory into your VS Code extensions folder:
|
||||
|
||||
cp -R vscode ~/.vscode/extensions/klammertext
|
||||
|
||||
then restart VS Code (or run the **Developer: Reload Window** command). If
|
||||
you copy the directory out of the Klammertext tree, also copy
|
||||
`shared/klammertext_ls.py` and `shared/klammertext_edit.py` into the copied
|
||||
folder — or set `klammertext.serverPath`. The editing zip from the
|
||||
Klammertext website ships the vendored copies already in place.
|
||||
|
||||
**Note:** `.kt` is also Kotlin's extension. Stock VS Code has no Kotlin
|
||||
support built in, so there is no conflict out of the box; if you install a
|
||||
Kotlin extension, the two will contend for `.kt` and you can decide per
|
||||
file with the language-mode picker (or `files.associations`).
|
||||
|
||||
## What you get
|
||||
|
||||
**Syntax highlighting** — the same token classes as the Emacs, Sublime
|
||||
Text, and Vim support: text removal (`#`, `##`, nestable `#[ ... ]#`), the
|
||||
three `@`-tiers — application (`@`), definition (`@@`), system (`@@@`) —
|
||||
each as an opening (`@name`, one unit) or a close (`name@`, bare `@`),
|
||||
`^`-escapes, and verbatim `@code ... code@` interiors. Colors come from
|
||||
your theme (applications as functions, definitions as types, system
|
||||
commands as keywords, removed text as comments). To adopt the full
|
||||
Klammertext palette (application blue / definition green / system orange,
|
||||
opens bright and closes darker), add `editor.tokenColorCustomizations`
|
||||
rules for the `*.klammertext` scopes in your settings.
|
||||
|
||||
**Diagnostics** — unclosed and mismatched delimiters appear in the
|
||||
Problems panel as you type.
|
||||
|
||||
**Formatting** — **Format Document** / **Format Selection** reindent
|
||||
structurally (2 spaces per nesting level; bar runs and closing delimiters
|
||||
sit at their opener's column; `@document` content stays at the margin;
|
||||
verbatim `@code` interiors, `@eval` code, and removed text are never
|
||||
touched). Reindentation is **explicit-only**: there is deliberately no
|
||||
format-on-type, because whitespace is content in Klammertext.
|
||||
|
||||
**Delimiter matching** — with the cursor on an application delimiter, the
|
||||
matching delimiter highlights (occurrences highlighting); **Go to
|
||||
Definition** on a delimiter goes to its match. Literal klammers match by
|
||||
name (`@code` ↔ `code@`) with their verbatim content opaque; everything
|
||||
else matches by depth.
|
||||
|
||||
**Commands and keybindings** (when editing Klammertext):
|
||||
|
||||
| Key | Command |
|
||||
|---|---|
|
||||
| `Ctrl+Alt+J` (`Cmd+Alt+J`) | Klammertext: Jump to Matching Delimiter |
|
||||
| `Ctrl+Alt+A` (`Cmd+Alt+A`) | Klammertext: Align Table |
|
||||
|
||||
Table alignment pads the cells of the `@table` enclosing the cursor so the
|
||||
`|` separators line up, with the shared rules: rows end with `||`; a row
|
||||
with a cell over 30 characters or spanning lines is left untouched; beyond
|
||||
100 columns the command declines; bars inside a nested klammer are not
|
||||
separators; no whitespace is ever inserted inside a bar run.
|
||||
|
||||
**Text removal toggling** — `Ctrl+/` toggles `#` line removal and
|
||||
`Shift+Alt+A` wraps the selection in `#[ ... ]#`, via the standard VS Code
|
||||
comment commands.
|
||||
|
||||
## Settings
|
||||
|
||||
| Setting | Meaning (default) |
|
||||
|---|---|
|
||||
| `klammertext.pythonPath` | Python interpreter for the server (`python3`) |
|
||||
| `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |
|
||||
Reference in New Issue
Block a user