101 lines
4.7 KiB
Markdown
101 lines
4.7 KiB
Markdown
|
# 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) |
|