Docs 2.0.0 · 7 min read

Editors and developer tools

Apsi works in the editors people already use. Each one gets Apsi's own colours, the Apsi file icon where the editor supports one, run/test commands and — through the language server — live errors, hover, go to definition, completion and formatting.

Supported editors

apsi editors

apsi editors                        list editors: found on this computer? Apsi installed?
apsi editors install                add Apsi to every editor that was found
apsi editors install cursor vscode  only these (ids: vscode vscode-insiders cursor windsurf vscodium trae
                                    sublime neovim vim notepadpp, or all)
apsi editors uninstall [NAMES]      remove it again
apsi editors path                   the folder that holds the integrations (…/editors)

The setup wizard runs the same command: its Code editor support component lists the editors it found, and the uninstaller removes Apsi from them again. Nothing outside each editor's own extension/package folder is touched. Restart editors that were open so they load Apsi.

How each one is installed:

• VS Code family — with the editor's command-line tool (code, cursor, windsurf, codium, …) when it is available; otherwise the extension is unpacked straight into the editor's extension folder (~/.vscode/extensions, ~/.cursor/extensions, ~/.windsurf/extensions, ~/.vscode-oss/extensions, …), so it also works when the CLI is not on PATH.
• Sublime Text — Packages/Apsi in the Sublime data folder.
• Neovim / Vim — a native package in …/site/pack/apsi/start/apsi (Neovim) or ~/.vim/pack/apsi/start/apsi (~/vimfiles/… on Windows); no plugin manager and no change to your init.lua/.vimrc.
• Notepad++ — %APPDATA%\Notepad++\userDefineLangs\Apsi.xml.

Manual steps

apsi editors prints these steps with the real paths of your installation.

Neovim and Vim details

Neovim settings: vim.g.apsi_lsp = false keeps the language server off; vim.g.apsi_command = { "py", "-3", "-m", "apsi" } starts Apsi another way. :help apsi has the details.

Sublime Text details

Ctrl+B runs the file, Ctrl+Shift+B chooses Test, Check, Format, Benchmark, Run Project or Test Project, F4 jumps to the next error. For the language server, install the LSP package and add { "clients": { "apsi": { "enabled": true, "command": ["apsi", "lsp"], "selector": "source.apsi" } } } to its settings.

One grammar everywhere

editors/vscode/syntaxes/apsi.tmLanguage.json and editors/vscode/snippets/apsi.json are the source of truth; python tools/build_editors.py regenerates the Sublime Text and TextMate/JetBrains versions from them, so every editor colours Apsi the same way. Vim, Notepad++ and Emacs use hand-written equivalents.

Language server (apsi lsp)

Apsi has a standard LSP language server built in, so it works with almost every editor:

• errors while you type: unit mismatches, undeclared names, assignments to let, wrong arguments, evolve rules, syntax errors
• hover: a variable shows its physical type, e.g. let speed: Velocity [m/s]; a function shows its signature
• go to definition
• completion: names in the file, built-ins, modules, physical types, and unit names inside [...]
• format document (the same formatter as apsi fmt)
• outline (document symbols)

VS Code, Cursor, Windsurf, VSCodium

Everything in this section applies to all editors of the VS Code family — they share one extension. The setup wizard installs it automatically into every one it finds. To install it by hand: Extensions → … → Install from VSIX… → dist/apsi-language-2.0.0.vsix.

The extension finds Apsi by itself, in this order: apsi.command from Settings, the wizard's install (%LOCALAPPDATA%\Programs\Apsi / ~/.local/share/apsi), the script install (%LOCALAPPDATA%\Apsi / ~/.apsi), apsi on PATH, py -3 -m apsi, python -m apsi. Set it yourself with Settings → apsi.command, e.g. ["C:\\tools\\python\\python.exe", "-m", "apsi"].

What you get

Commands and keys

Settings

Tasks in tasks.json

{
  "version": "2.0.0",
  "tasks": [
    { "type": "apsi", "command": "run", "file": "src/main.apsi", "args": ["--allow-net"], "label": "serve" },
    { "type": "apsi", "command": "task", "task": "ci", "label": "ci", "group": "test" }
  ]
}

apsi new writes a ready .vscode/tasks.json (run, test, check, format, watch) for every new project.

Build the .vsix from source:

cd editors/vscode && npm install && npx @vscode/vsce package

Formatter (apsi fmt)

apsi fmt                     # every .apsi file under the current folder
apsi fmt examples            # one folder
apsi fmt --check src         # check only (for CI): exit code 1 when a file would change

• 4-space indentation, a space after ,, spaces around = == -> => |> ±, two spaces before an end-of-line comment
• unit literals (9.81[m/s^2]), ranges (0..10) and keyword arguments (f(x=1)) have no spaces
• 100 % safe: a file is written only when its syntax tree after formatting is identical to the one before

Other highlighters

The TextMate grammar editors/vscode/syntaxes/apsi.tmLanguage.json also works in Sublime Text, JetBrains (TextMate Bundles plugin), GitHub Linguist and Shiki (for highlighting on a website).

Found a mistake? Report it · Markdown source