ack
ee8bcf5300
Assembled from development commit c3c40f6c8fca. Since 830b193: on Windows the
products carry Windows names (ktext.exe, klammertext.dll, document.dll,
reflect.dll) and the console's output code page is UTF-8 for a run; the
editor tooling works on Windows (VS Code, Sublime Text, Vim, with the
interpreter's name chosen by platform) and Notepad++ joins it
(doc/edit/notepadpp: a User Defined Language and two Run-menu commands);
a sixth install page, doc/install/windows_wsl_install.md, for Linux
inside WSL; the Windows page opens with the three routes and gains its
editor section, the PowerShell quoting and Path notes; the Linux page
installs OpenImageIO from the python3-openimageio package and verifies
with kdiag --machine; the README lists all six install pages. Linux and
macOS behaviour is unchanged.
90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
# Klammertext editor support
|
|
|
|
Editing support for Klammertext files (`.kt` documents and `.k` klammer
|
|
definitions) in five editors, built around one shared implementation.
|
|
|
|
| Directory | Contents |
|
|
|---|---|
|
|
| `shared/` | **The shared editor core** (`klammertext_edit.py`) and the **Klammertext language server** (`klammertext_ls.py`). Everything structure-aware — indentation, table alignment, delimiter matching, delimiter diagnostics — implemented once, in dependency-free Python. |
|
|
| `emacs/` | Emacs major mode. An independent elisp implementation of the same algorithms (Emacs cannot call Python per keystroke), held byte-equal to the shared core by the test suite. |
|
|
| `sublime/` | Sublime Text package. Syntax file plus thin plugin wrappers that import the shared core directly (Sublime's plugin host is Python). |
|
|
| `vim/` | Vim plugin. Syntax/ftplugin files plus commands that run the shared core's CLI; with `+python3`, the core also runs in-process (`=` operator, live match highlighting). |
|
|
| `vscode/` | Visual Studio Code extension. TextMate grammar plus a dependency-free extension that spawns the language server and speaks LSP to it. |
|
|
| `notepadpp/` | Notepad++ (Windows). A User Defined Language for the highlighting, and two Run-menu commands that pass the current file through the shared core's CLI (delimiter check, reindent). No plugin host, so nothing structural runs in-process. |
|
|
|
|
## The architecture
|
|
|
|
Klammertext's *structural layer* — @-run tiers, bar-run dimension,
|
|
`^`-escapes, `#` removal, literal spans, nesting depth — is independent of
|
|
both the Klammermachine and any klammer set, and every editor needs the
|
|
same operations on it. Those operations live in
|
|
**`shared/klammertext_edit.py`**:
|
|
|
|
- **Indentation** — 2 spaces per nesting level; bar runs and closing
|
|
delimiters sit at their opener's column; `@document` is transparent;
|
|
verbatim/`@eval`/removed content is never touched. Explicit-only in
|
|
every editor: whitespace is content in Klammertext.
|
|
- **Table alignment** — pad a `@table`'s rows so the depth-0 `|`
|
|
separators line up (rows end with `||`; cells over 30 characters or
|
|
spanning lines opt their row out; over 100 columns the command declines;
|
|
never a space inside a bar run).
|
|
- **Delimiter matching** — open ↔ close for klammer applications, literal
|
|
klammers matched by name with opaque content, everything else by depth.
|
|
- **Diagnostics** — whole-buffer balance check over all three `@`-tiers:
|
|
unclosed openings, extra closes, name and tier mismatches, unclosed
|
|
literal spans and `#[` blocks.
|
|
- **A CLI** (`indent | align | match | check` over stdin/stdout) for
|
|
editors that shell out (Vim), and for scripts.
|
|
|
|
**`shared/klammertext_ls.py`** puts a language server in front of the same
|
|
core: JSON-RPC over stdio, no dependencies. It serves publishDiagnostics,
|
|
document/range formatting (reindentation), documentHighlight and
|
|
definition (the matcher), and a `klammertext.alignTable` command. The
|
|
VS Code extension is its first client; any LSP client works — Neovim's
|
|
built-in LSP, Emacs eglot, Sublime's LSP package — with a one-line
|
|
configuration pointing at `python3 klammertext_ls.py` (on Windows
|
|
`python klammertext_ls.py`).
|
|
|
|
Syntax highlighting and cursor-latency features stay native in each editor
|
|
(a tokenizer or a per-keystroke matcher cannot round-trip to Python), so
|
|
each editor directory carries its own syntax artifact and, where relevant,
|
|
its own thin glue.
|
|
|
|
## Locating the shared core
|
|
|
|
The Sublime, Vim, and VS Code integrations find `klammertext_edit.py` (and
|
|
VS Code additionally `klammertext_ls.py`) in this order: a copy at the
|
|
integration's own root (the **editing zip** vendors one there, so each
|
|
unpacked folder is self-contained), `../shared/` relative to the
|
|
integration (this repository's layout — using an editor directory straight
|
|
from a checkout just works), then `$KLAMMERTEXT_HOME/doc/edit/shared/`.
|
|
|
|
## Keeping things in sync
|
|
|
|
`klammertext_edit.py` is the source of truth for the policy lists
|
|
(`LITERAL_KLAMMERS`, `TRANSPARENT_KLAMMERS`, `CODE_KLAMMERS`,
|
|
`ALIGN_KLAMMERS`) and limits (`INDENT_OFFSET`, `CELL_MAX`, `ROW_MAX`).
|
|
Two kinds of artifact cannot read it and restate parts of it by hand:
|
|
|
|
1. **The Emacs mode** — a full independent implementation with its own
|
|
defcustoms, checked byte-for-byte against the shared core by
|
|
`tst/editor_test.sh`.
|
|
2. **The static syntax files** — the literal-klammer set (`@code`) appears
|
|
in the Sublime `.sublime-syntax`, the Vim `syntax/klammertext.vim`, the
|
|
VS Code `tmLanguage.json` grammar, and the Notepad++ `Klammertext.udl.xml`
|
|
(and the Emacs defcustom). When you add a literal klammer, change them
|
|
together; each file's header carries the same SYNC note. The UDL can
|
|
hold only names that are not prefixes of other klammer names (it has
|
|
no word boundary), so it carries `code` and not `c`.
|
|
|
|
## Testing
|
|
|
|
`tst/editor_test.sh` (run by `dev/rebuild.sh` and `make -C tst test`)
|
|
drives the fixture pairs in `tst/editor/` through the shared core's API
|
|
and CLI, checks idempotence, checks the Emacs implementation for
|
|
byte-equality, runs the language server through a scripted LSP client
|
|
(`ls_test.py`), exercises the VS Code extension against the real server
|
|
under a stubbed VS Code API (`vscode_ext_test.js`), and runs the Vim
|
|
plugin's commands headlessly. Emacs, Vim, and Node/VS Code halves skip
|
|
gracefully where not installed.
|