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:
@@ -1,18 +1,24 @@
|
||||
# Klammertext for Sublime Text
|
||||
|
||||
A Sublime Text port of the Emacs major mode for Klammertext
|
||||
(`doc/emacs/klammertext-mode.el`). It brings syntax highlighting, delimiter
|
||||
matching, and comment toggling to `.kt` and `.k` files. Behavior mirrors the
|
||||
Emacs mode closely; where the two intentionally differ, the file headers say so.
|
||||
A Sublime Text package for Klammertext: syntax highlighting, delimiter
|
||||
matching, comment toggling, reindentation, and table alignment for `.kt` and
|
||||
`.k` files. The structural features run on the **shared editor core**
|
||||
(`klammertext_edit.py`) — the single Python implementation used by the Vim
|
||||
and VS Code integrations and the Klammertext language server — so all the
|
||||
editors behave identically; the plugin files here are Sublime command
|
||||
wrappers. Behavior mirrors the Emacs mode closely (an independent elisp
|
||||
implementation, held equal by the Klammertext test suite); where the two
|
||||
intentionally differ, the file headers say so.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `Klammertext.sublime-syntax` | Syntax highlighting. Colors the text-removal constructs (`#`, `##`, `#[...]#`) and the three `@`-tiers — application `@`, definition `@@`, system `@@@` — each as an opening vs. a close, plus `^`-escapes and verbatim `@code ... code@` spans. |
|
||||
| `Klammertext.py` | Plugin with two features that share one context-sensitive matcher: jump between an opening and its close, and live highlighting of the matching delimiter as the caret moves (mismatched or unbalanced delimiters flag in red). |
|
||||
| `Klammertext.py` | Jump between an opening and its close, and live highlighting of the matching delimiter as the caret moves (mismatched or unbalanced delimiters flag in red). Both reuse the shared core's context-sensitive matcher. |
|
||||
| `Klammertext_indent.py` | **Experimental.** Reindentation per the Klammertext convention (see below). A separate unit: delete this one file to disable indentation; nothing else is affected. |
|
||||
| `Klammertext_align.py` | **Experimental.** Table alignment (see below). Also a separate, deletable unit. |
|
||||
| `klammertext_edit.py` | The shared editor core the three plugins import. Ships in the editing zip; when you install from the Klammertext repository instead, copy it in from `doc/edit/shared/` (or leave the package inside the repository tree, where the plugins find `../shared/` themselves). |
|
||||
| `Default.sublime-keymap` | Binds jump-to-match to **Ctrl+M**, reindent to **Ctrl+Alt+I**, and table alignment to **Ctrl+Alt+A**, scoped to Klammertext files. |
|
||||
| `Comments.tmPreferences` | Comment toggling: **Ctrl+/** inserts `# ` (line removal), **Ctrl+Shift+/** wraps in `#[ ... ]#` (block removal). |
|
||||
| `Breakers` / `Celeste` / `Mariana` / `Monokai` / `Sixteen` `.sublime-color-scheme` | Color overrides for Sublime's five built-in schemes — one hue system, full intensity on the dark schemes, scaled down on the light ones. Additive: they recolor only the Klammertext delimiters and leave the rest of each scheme unchanged. |
|
||||
@@ -32,7 +38,10 @@ directory:
|
||||
The quickest way to find it: **Preferences ￫ Browse Packages…** opens the
|
||||
`Packages` directory. Create the `Klammertext` folder there and copy the files
|
||||
in. Sublime loads them live — no restart — and applies the syntax to `.kt` and
|
||||
`.k` files automatically.
|
||||
`.k` files automatically. The package must include `klammertext_edit.py`
|
||||
(see the file table above): the editing zip ships it in place; from a
|
||||
repository checkout, copy `doc/edit/shared/klammertext_edit.py` into the
|
||||
folder alongside the plugin files.
|
||||
|
||||
Use a dedicated folder (not `Packages/User/`) so the bundled keymap does not
|
||||
merge into your personal one. If you want highlighting only, the
|
||||
@@ -60,7 +69,7 @@ prefer `super+m` can change it in `Default.sublime-keymap`.
|
||||
## Indentation (experimental)
|
||||
|
||||
`Klammertext_indent.py` ports the Emacs mode's indentation
|
||||
(`doc/emacs/klammertext-indent.el`): **Ctrl+Alt+I** reindents the line(s)
|
||||
(`doc/edit/emacs/klammertext-indent.el`): **Ctrl+Alt+I** reindents the line(s)
|
||||
touched by the selection to reflect the klammer nesting, two spaces per level:
|
||||
|
||||
```
|
||||
@@ -82,8 +91,9 @@ belong to. All three `@`-tiers indent uniformly. Exceptions: `@document`
|
||||
contributes no level (a document's paragraphs stay at the left margin); lines
|
||||
inside verbatim `@code` content, inside `@eval` argument spans (inline Python
|
||||
is indentation-sensitive), and inside removed regions are never touched. The
|
||||
policy lists (`TRANSPARENT_KLAMMERS`, `CODE_KLAMMERS`, `INDENT_OFFSET`) are at
|
||||
the top of `Klammertext_indent.py`, kept in sync with the Emacs defcustoms.
|
||||
policy lists (`TRANSPARENT_KLAMMERS`, `CODE_KLAMMERS`, `INDENT_OFFSET`) are
|
||||
in the shared core (`klammertext_edit.py`), kept in sync with the Emacs
|
||||
defcustoms.
|
||||
|
||||
Sublime's own Reindent (Edit ￫ Line ￫ Reindent) is driven by single-line
|
||||
regex patterns that cannot express Klammertext nesting, so this is a plugin
|
||||
@@ -96,7 +106,7 @@ keep the command available from plugins).
|
||||
## Table alignment (experimental)
|
||||
|
||||
`Klammertext_align.py` ports the Emacs mode's table alignment
|
||||
(`doc/emacs/klammertext-align.el`): **Ctrl+Alt+A** with the caret anywhere
|
||||
(`doc/edit/emacs/klammertext-align.el`): **Ctrl+Alt+A** with the caret anywhere
|
||||
inside a `@table` span pads the cells of its rows so the `|` separators line
|
||||
up:
|
||||
|
||||
@@ -118,8 +128,8 @@ bar run (which would turn a `||` row separator into an empty `| |` cell),
|
||||
and bars inside a nested klammer in a cell (`@frac 1 | 2 @`) belong to that
|
||||
klammer, not the table. Aligned rows adopt the leading whitespace of the
|
||||
first aligned row — run Ctrl+Alt+I first if the rows disagree. The limits
|
||||
sit at the top of `Klammertext_align.py`, mirrored from the Emacs
|
||||
defcustoms.
|
||||
(`ALIGN_KLAMMERS`, `CELL_MAX`, `ROW_MAX`) are in the shared core
|
||||
(`klammertext_edit.py`), mirrored from the Emacs defcustoms.
|
||||
|
||||
## Colors
|
||||
|
||||
@@ -143,25 +153,30 @@ exact values are in each file's header comment.
|
||||
|
||||
## Keeping literal klammers in sync
|
||||
|
||||
Klammers whose content is verbatim (`@code ... code@`) are listed in four
|
||||
places that must agree — a Sublime syntax/plugin cannot read the Emacs
|
||||
defcustom, so the list is duplicated:
|
||||
Klammers whose content is verbatim (`@code ... code@`) are listed in the
|
||||
shared core — `LITERAL_KLAMMERS` in `klammertext_edit.py`, the source of
|
||||
truth — and restated in the static per-editor artifacts, which cannot read
|
||||
Python:
|
||||
|
||||
- `klammertext-literal-klammers` in `doc/emacs/klammertext-mode.el` (the source of truth)
|
||||
- `LITERAL_KLAMMERS` in `Klammertext.py`
|
||||
- `LITERAL_KLAMMERS` in `Klammertext_indent.py`
|
||||
- the `@code` rule and `literal_code` context in `Klammertext.sublime-syntax`
|
||||
- `klammertext-literal-klammers` in `doc/edit/emacs/klammertext-mode.el`
|
||||
(the independent elisp implementation)
|
||||
- the `@code` region in `doc/edit/vim/syntax/klammertext.vim` and the rule
|
||||
in `doc/edit/vscode/syntaxes/klammertext.tmLanguage.json`
|
||||
|
||||
All four are seeded with just `code`. When you add or remove a literal
|
||||
klammer, change all four.
|
||||
All are seeded with just `code`. When you add or remove a literal klammer,
|
||||
change them together.
|
||||
|
||||
## Not included
|
||||
|
||||
Whole-file semantic validation — persistent error underlines when the cursor is
|
||||
elsewhere, klammer-name completion, go-to-definition — is not part of this
|
||||
package. That would need a language server (used through the Sublime LSP
|
||||
package), a separate program, and is unrelated to the highlighting and matching
|
||||
provided here.
|
||||
Whole-file diagnostics (persistent error underlines when the cursor is
|
||||
elsewhere) are not part of this package, but they exist: the **Klammertext
|
||||
language server** (`doc/edit/shared/klammertext_ls.py`, the same program the
|
||||
VS Code extension uses) serves them to Sublime through the community LSP
|
||||
package. Install "LSP" from Package Control and add a client with
|
||||
`command: ["python3", "/path/to/klammertext_ls.py"]` for the
|
||||
`text.klammertext` selector. Everything in this package works the same
|
||||
with or without it.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
Reference in New Issue
Block a user