klammertext/doc/edit/vscode

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

Package the extension as a .vsix and install it (the builder needs only bash and python3; the editing zip from the Klammertext website ships a prebuilt klammertext.vsix, so there the first step is already done):

./make_vsix.sh
code --install-extension klammertext.vsix

then restart VS Code (or run the Developer: Reload Window command). make_vsix.sh vendors the shared core and the language server into the package automatically, from this folder or from ../shared/.

Do not copy this directory into ~/.vscode/extensions/ by hand: modern VS Code loads only registered extensions, so a merely copied folder is silently ignored (and flagged for deletion in that directory's .obsolete file). Installing the .vsix is what registers it.

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).

VS Code commands for Klammertext

Command	Menu	Key	Cursor position
Format Document	Right-click	Ctrl+Shift+I	Anywhere in the document
Format Selection	Right-click	Ctrl+K Ctrl+F	Lines selected
Toggle Line Comment	Edit menu	Ctrl+/	In the line to remove with #
Toggle Block Comment	Edit menu	Ctrl+Shift+A	Region to remove selected (#[ ... ]#)
Klammertext: Jump to Matching Delimiter	Right-click	Ctrl+K J	On the opening @name or the closing name@ / @
Klammertext: Align Table	Right-click	Ctrl+K A	Anywhere inside the @table
Delimiter diagnostics	Problems panel	—	Automatic, as you type

All commands are also in the Command Palette (Ctrl+Shift+P). Keys shown are the Linux defaults: the Klammertext commands use Cmd+K on macOS, and the built-in formatting and comment keys differ per OS.

Features

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.

Structural reindentation — Format Document and Format Selection reindent per the Klammertext convention: 2 spaces per nesting level; a line beginning with a bar run or a closing delimiter sits at its 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 (opening @name, named close name@, or a bare @ close), the delimiter and its match are boxed; a mismatched named close or an unbalanced delimiter is boxed in red with a status-bar message, as in the Emacs, Sublime, and Vim support. Go to Definition on a delimiter goes to its match, so Jump to Matching Delimiter has a second home on F12. Literal klammers match by name (@code ↔ code@) with their verbatim content opaque — a stray @ in the verbatim interior cannot confuse them; everything else matches by depth. Double-click selects a whole delimiter token.

Delimiter diagnostics — the automatic Problems-panel entries cover all three @-tiers: a closing delimiter with no opening, a named close that disagrees with its opening (ul@ closing @ol), a close of the wrong tier (@@ closing @name), openings never closed, and unclosed @code and #[ regions.

Table alignment — pads the cells of the @table enclosing the cursor so the | separators line up, with the rules shared across the editors: rows end with ||; a row with a cell over 30 characters or spanning lines is left untouched; beyond 100 aligned columns the command declines; bars inside a nested klammer belong to that klammer, not the table; and no whitespace is ever inserted inside a bar run (|| is a row separator, | | an empty cell).

Text removal — the Toggle Comment commands are VS Code's names; in Klammertext they toggle # line removal and #[ ... ]# block removal (the # does not "comment out": it removes text from processing).

Keybinding notes — each Klammertext command has two bindings because some environments never deliver Ctrl+Alt+letter chords to VS Code (a right Alt is usually AltGr, not Alt, and some desktops and input methods intercept the chord); the two-step Ctrl+K chords go through everywhere. If a key seems to do nothing, run the command from the Command Palette first: if that works, the chord is being intercepted — open Keyboard Shortcuts (Ctrl+K Ctrl+S), search "klammertext", and rebind.

Settings

A normal installation needs neither setting: the extension runs python3 from PATH and finds the language server automatically (the copy vendored next to extension.js, then ../shared/, then $KLAMMERTEXT_HOME/doc/edit/shared/). They exist for unusual setups. Set them in the Settings UI (Ctrl+,, search "klammertext") or in settings.json; the server is spawned when the extension activates, so reload the window after changing either.

Setting	Meaning (default)
klammertext.pythonPath	Python interpreter for the server (python3)
klammertext.serverPath	full path to klammertext_ls.py (auto-located)

pythonPath matters when python3 is not on the PATH VS Code sees — a VS Code launched from the desktop inherits a different environment than your shell — or when a specific interpreter is wanted. serverPath matters only when the server file lives outside the search chain above. If the server cannot be started at all, the extension says so once at activation; highlighting still works, and everything structural (diagnostics, formatting, matching, alignment) waits until the path is fixed.