Editor integration
Drive your editor from pickle-cli check --json, the supported integration point.
PickleScript integrates with an editor through pickle check --json. It emits
every diagnostic with a file, a line, a column and a span, which is all an
editor needs to render errors and quick fixes.
The supported approach: check --json
check emits every diagnostic as machine-readable JSON on stdout and exits
non-zero when there is at least one error. That is enough to drive diagnostics
in any editor that can run an external command.
pickle-cli check --json src/main.pkl
Diagnostics carry a stable code, a message, a line and column, and often a note explaining the fix:
error: src/main.pkl:1:1: [E0308] type mismatch in binding: expected `byte`, found `int`
= note: `int` does not satisfy `byte`; use `as` for an explicit conversion
Every code is documented, and pickle-cli explain will print the catalogue entry
for any of them:
pickle-cli explain E0308
Wiring it into an editor
Any editor with a task runner can surface the output. For a VS Code
tasks.json:
{
"version": "2.0.0",
"tasks": [
{
"label": "pickle: check",
"type": "shell",
"command": "pickle-cli check --json ${file}",
"problemMatcher": {
"owner": "pickle",
"fileLocation": ["absolute"],
"pattern": {
"regexp": "^(.*?):(\\d+):(\\d+): \\[(E\\d+)\\] (.*)$",
"file": 1,
"line": 2,
"column": 3,
"code": 4,
"message": 5
}
},
"group": "build",
"problemMatcher": []
}
]
}
Save this as .vscode/tasks.json. Bind it to save-on-type and the problem list
will track the open file.
The same trick works in Neovim with vim.system(), in Helix with a
[language-server]-style external command wrapper, and in Emacs with
compilation-mode.
Syntax highlighting
pickle-cli lex prints a canonical token stream, one token per line, which is
a stable serialization contract. A highlighter grammar can be checked against it:
pickle-cli lex main.pkl
Because the format is a stable contract, a grammar that agrees with it stays correct as the compiler changes.
What a language server would need
The compiler exposes the pieces a language server is built from:
| Capability | Command |
|---|---|
| Parse, resolve and type-check without executing | check |
| Machine-readable diagnostics | check --json |
| Stable diagnostic codes | E0101 upward |
| Token stream | lex |
| Syntax tree | ast |
Next steps
- Diagnostics and error codes: the catalogue your tooling should key off.
- Language overview: the syntax a grammar needs to cover.
