Orkuncakilkaya
2ad6edaae3
`ludic syntax [--json] [-o FILE]` prints what `ludicc --emit-syntax` does (a line per entry, or the JSON). `ludic-dev syntax` writes, between "ludic-dev syntax: begin" / "end" lines, the keyword, type, phase and attribute tables of ludic_syntax.h, LudicVocabulary's sets (JetBrains), ludic-mode.el's lists and the language server's word tests (is_keyword_word and the rest; is_contextual_word is every word the parser does not reserve, and every declaring or modifying one), and every TextMate pattern marked "comment": "ludic-dev syntax: <group>" (shared and the VS Code copy). The grammars gain module uses port bind action reducer dispatch registry def open component prop view alias friend unsafe numbers of as from mut system; import and extern colour as declarations; the phase clause knows Overlay; the bitwise pattern matches | and ^ on their own again. `ludic-dev syntax --check` - and check-vocabulary, whose old parser comparison it replaces, and the regression suite (syntax_cases, one line per file) - fails when a written list is behind, when a grammar lacks a keyword, type or phase, when docs/language has no page for a keyword, type, phase or attribute, or when the parser (a scan of selfhost/frontend: is_id / text == words, a == / ann == attributes) tests a word or reads an attribute vocab.ludic lacks, or the reverse. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
166 lines
8.2 KiB
Markdown
166 lines
8.2 KiB
Markdown
# Ludic in your editor
|
|
|
|
Everything here is built on one idea: **write the language knowledge once, in
|
|
Ludic, and let every editor talk to it.** There is one vocabulary, one
|
|
formatter and one language server. VS Code and JetBrains get first-class plugins
|
|
because those are the two that were asked for; every other editor gets the same
|
|
capabilities by pointing at the same binary.
|
|
|
|
```
|
|
tools/ludic-tools/ the actual language knowledge, in Ludic
|
|
ludic_syntax.h the vocabulary tables (keywords, operators, builtins)
|
|
that the formatter, the server and the vocabulary
|
|
check all read — the source of truth
|
|
fmt.ludic -> bin/ludic-fmt token-based, comment-preserving formatter
|
|
lsp.ludic -> bin/ludic-lsp the language server (LSP 3.17)
|
|
|
|
tools/editors/
|
|
shared/ TextMate grammar + Markdown injection + language config
|
|
vscode/ VS Code extension
|
|
jetbrains/ IntelliJ Platform plugin (Community editions included)
|
|
neovim/ helix/ emacs/ sublime/ zed/ configuration, no plugin needed
|
|
```
|
|
|
|
## Getting the server
|
|
|
|
An installed toolchain already has it: `curl -fsSL https://workshopsoft.pages.workshopsoft.io/ludic/install.sh | sh`
|
|
puts `ludic-lsp` and `ludic-fmt` in `~/.ludic/bin`, on your `PATH`, and
|
|
`ludic lsp` runs the server on stdio — that is what an editor should spawn, since
|
|
it needs no path configuration.
|
|
|
|
From a checkout, build them with:
|
|
|
|
```bash
|
|
bin/ludic-dev tools
|
|
```
|
|
|
|
Produces `bin/ludic-fmt` and `bin/ludic-lsp`. Add `--install` to symlink both
|
|
into `~/.local/bin`, `--test` to run `bin/ludic-dev test-tools` afterwards.
|
|
|
|
## What you get, in any editor
|
|
|
|
| Feature | How |
|
|
|---|---|
|
|
| Syntax highlighting | LSP semantic tokens, or the TextMate grammar with no server at all |
|
|
| Diagnostics | structural errors as you type; `ludicc`'s own errors on save |
|
|
| Completion | context-aware — see below |
|
|
| Hover | signature + docs for builtins, intrinsics, and everything you declared |
|
|
| Go to definition, find usages, rename | across the whole compilation unit, following `import` — by resolving each occurrence, not by matching text, so renaming a component's `x` leaves every other `x` alone |
|
|
| Formatting | whole-file, comment-preserving, idempotent |
|
|
| Outline, folding, inlay hints, signature help, document links | |
|
|
| ` ```ludic ` in Markdown | highlighted, checked and formatted |
|
|
|
|
Completion knows where the caret is: fields after `.`, components inside
|
|
`query [...]` and after `spawn`, phase names after `phase`, scene names after
|
|
`enter`, widget types and props inside a `ui` block, types after `:` and `->`,
|
|
and otherwise keywords, builtins, and everything in scope.
|
|
|
|
## Per-editor setup
|
|
|
|
- **VS Code** — [`vscode/`](vscode/). `npm install && npx @vscode/vsce package`, then
|
|
install the `.vsix`. Finds the binaries under `bin/` on its own.
|
|
- **JetBrains** — [`jetbrains/`](jetbrains/). `./gradlew buildPlugin`, then install the
|
|
zip from disk. Uses LSP4IJ rather than the paid-IDE LSP API, so it works in
|
|
Community editions too.
|
|
- **Neovim** — `require('ludic').setup()` from [`neovim/`](neovim/lua/ludic.lua).
|
|
- **Helix** — merge [`helix/languages.toml`](helix/languages.toml) into your config.
|
|
- **Emacs** — [`emacs/ludic-mode.el`](emacs/ludic-mode.el); eglot is wired up in one line.
|
|
- **Sublime** — [`sublime/README.md`](sublime/README.md); the TextMate grammar loads as-is.
|
|
- **Zed** — [`zed/README.md`](zed/README.md); LSP-only, no grammar to build.
|
|
- **Anything else** that speaks LSP:
|
|
|
|
```
|
|
command: ludic lsp
|
|
languages: ludic, markdown
|
|
initializationOptions: { "compilerDiagnostics": true, "indentSize": 2 }
|
|
```
|
|
|
|
(`ludic lsp` is on `PATH` after an install; from a checkout it is
|
|
`bin/ludic lsp`, and the server finds `ludicc` next to itself.)
|
|
|
|
## Markdown
|
|
|
|
Markdown fenced-code highlighting is not one standard — it is three mechanisms,
|
|
and this ships all three so that a ` ```ludic ` block works wherever you write
|
|
prose:
|
|
|
|
1. **TextMate injection** (`shared/ludic.markdown-injection.json`) — what VS Code,
|
|
Sublime and other TextMate-based editors use. It is a plain grammar file with
|
|
an `injectionSelector`, so it is portable rather than VS Code-specific.
|
|
2. **Language-ID resolution** — JetBrains' Markdown support matches a fence's
|
|
info string against registered language IDs, so the plugin registering as
|
|
`Ludic` is all that is needed; no Markdown-specific code exists in the plugin.
|
|
3. **The language server** — `ludic-lsp` accepts Markdown documents directly. It
|
|
copies the buffer, blanks every byte outside a ` ```ludic ` fence, and
|
|
analyses the result; offsets still line up with the real file, so semantic
|
|
highlighting, hover, completion and go-to-definition all work inside fences
|
|
with no editor-side support at all. This is the fallback that works even
|
|
where the other two do not.
|
|
|
|
It reports **no diagnostics** in Markdown, deliberately. A fence is a
|
|
snippet — an elision mark, or a body shown without its enclosing `game`
|
|
block — so nearly every error found there would be the documentation doing
|
|
its job. `ludic-fmt --check` still keeps the fences formatted, which is the
|
|
part of "is this doc correct" that can be answered without guessing.
|
|
|
|
The formatter handles Markdown too, which keeps documentation honest:
|
|
|
|
```bash
|
|
bin/ludic-fmt --check LANGUAGE.md README.md # CI: fail if a fence is unformatted
|
|
bin/ludic-fmt -w LANGUAGE.md # reformat the fences, leave the prose
|
|
```
|
|
|
|
## Keeping a tree formatted
|
|
|
|
```bash
|
|
ln -sf ../../tools/git-hooks/pre-commit .git/hooks/pre-commit
|
|
```
|
|
|
|
The hook runs `ludic-fmt --check` over the staged `.ludic` and `.md` files only,
|
|
and does nothing at all when `bin/ludic-fmt` has not been built — so it never
|
|
blocks a commit on a machine that has not run `bin/ludic-dev tools`.
|
|
|
|
## Why the formatter is not `ludicc --fmt`
|
|
|
|
The compiler has a canonical printer, and it is the right tool for seeing what
|
|
the compiler parsed. It is the wrong tool for an editor: it walks the AST *after*
|
|
import splicing, so it drops every comment and inlines every imported file into
|
|
whichever file you pointed it at. Running it as format-on-save on
|
|
`chronorift/combat.ludic` would replace that file with the whole game.
|
|
|
|
`ludic-fmt` works on the token stream instead. Nothing is dropped or reordered —
|
|
every token is re-emitted in order, and the only freedom taken is the whitespace
|
|
between them. Lines are re-indented and respaced but never joined or split, so
|
|
you keep control of line structure.
|
|
|
|
Two carve-outs keep the output idiomatic rather than merely uniform, because
|
|
both spellings are what the language documents and uses:
|
|
|
|
- runs of two or more spaces are preserved, so hand-aligned columns
|
|
(`const R_DIR: int = 0 # 0 up`) survive a save;
|
|
- `id=Root` inside a `ui` block and `{Enemy}` inside a query stay tight.
|
|
|
|
`bin/ludic-dev test-tools` checks the property that matters: formatting every file in
|
|
the tree and re-running the *compiler's* canonical dump produces byte-identical
|
|
output. The formatter cannot change what a program means.
|
|
|
|
## Keeping it honest
|
|
|
|
The language's words come from one place: the compiler's vocabulary table
|
|
(`selfhost/frontend/vocab.ludic`), printed by `ludic syntax --json` (`ludicc
|
|
--emit-syntax`) and held to the parser's own recognisers. The keyword, type and
|
|
phase lists in `ludic_syntax.h`, the TextMate grammar (every pattern marked
|
|
`"comment": "ludic-dev syntax: <group>"`), the JetBrains lexer's
|
|
`LudicVocabulary`, `ludic-mode.el` and the language server are written from it
|
|
between `ludic-dev syntax: begin` / `end` lines by `bin/ludic-dev syntax`; do not
|
|
edit inside them.
|
|
|
|
`bin/ludic-dev syntax --check` (and `check-vocabulary`, which `test-tools` runs,
|
|
and the regression suite) fails when a generated list is behind, when a grammar
|
|
lacks a word, when docs/language has no page for a keyword, type, phase or
|
|
attribute, or when the parser (`selfhost/frontend`) tests a word or reads an
|
|
attribute the vocabulary lacks. Builtins are still listed in `ludic_syntax.h`,
|
|
and `check-vocabulary` compares them with the grammar and the Kotlin lexer.
|
|
|
|
When you add a keyword or an attribute: add its row to `vocab.ludic`, rebuild the
|
|
compiler, run `bin/ludic-dev syntax`, and write its docs/language page.
|