Mercury Language Plugin
Full language support for the Mercury logic/functional
programming language — the first VS Code extension to provide live diagnostics
straight from the mmc compiler, alongside a complete editing experience.
Features
- Live diagnostics from
mmc — errors and warnings appear as you save (or as
you type), grouped correctly across the compiler's multi-line messages, with
the right severity and relatedInformation for secondary locations. Two
strategies:
- single (default) — fast per-file
--errorcheck-only (runs
--make-interface first so imports resolve).
- make — whole-program
mmc --make, reading the generated .err files;
the reliable choice for multi-module projects.
- Syntax highlighting — a TextMate grammar ported from the official Vim
syntax file, including embedded C / C# / Java / Erlang highlighting inside
pragma foreign_proc/foreign_code/foreign_decl.
- Outline / document symbols — predicates, functions, types (with
constructors and fields nested), insts, modes, type classes and instances
(with their methods).
- Workspace symbols, with module-qualified names.
- Go to definition — to
:- pred/:- func declarations and clause heads.
- Hover — the declaration plus its leading
% doc comment.
- Completion — workspace symbols, keywords, determinism categories,
pragmas, purity annotations, module names in
import_module context, and an
optional Mercury standard-library set.
- Semantic tokens — consistent colouring of declared types, predicates,
functions and constructors.
- Formatting (document and range) — whitespace-only normalisation to the
Mercury coding standard: 4-space indentation (clause bodies one level;
bracket contents one past their opening line;
;/then/else at the
opening line's indent; ---> constructor blocks anchored on the constructor
column; clause-head continuations two levels), trailing-whitespace removal
and a single final newline. Comment lines, multi-line strings
(foreign_proc bodies) and hand-aligned continuations are preserved; it
never reflows tokens.
- Snippets for modules, predicates, functions, types, type classes,
foreign_proc, DCG rules and more.
- Build tasks (
mercury task type) and a problem matcher for mmc
output.
Requirements
- The Mercury compiler (
mmc) must be installed and on your PATH, or set
mercury.mmc.path. Diagnostics shell out to mmc.
mmake is optional; used by the build task when an Mmakefile is present.
.m also denotes Objective-C and MATLAB files. This extension registers the
.m extension for Mercury unconditionally; the first-line pattern
(:- module …) only breaks ties when another installed extension also claims
.m. If a file is misdetected, use Mercury: Mark File as Mercury (or the
language picker in the status bar) to switch it.
Settings
| Setting |
Default |
Description |
mercury.mmc.path |
mmc |
Path to the compiler. |
mercury.mmc.args |
[] |
Extra args appended to every mmc invocation. |
mercury.mmake.path |
mmake |
Path to mmake. |
mercury.diagnostics.enable |
true |
Enable compiler diagnostics. |
mercury.diagnostics.run |
onSave |
onSave | onType | off. |
mercury.diagnostics.mode |
single |
single (fast) | make (multi-module). |
mercury.diagnostics.makeInterfaceFirst |
true |
Run --make-interface before the single-file check. |
mercury.diagnostics.mainModule |
"" |
Main module (no .m) for make mode. |
mercury.diagnostics.debounce |
500 |
Debounce (ms) for onType. |
mercury.grade |
"" |
Grade passed as --grade. |
mercury.useSubdirs / mercury.useGradeSubdirs |
false |
Pass --use-subdirs / --use-grade-subdirs. |
mercury.includeDirs |
[] |
Directories passed with -I. |
mercury.workingDirectory |
"" |
Override the compiler's working directory. |
mercury.maxNumberOfProblems |
1000 |
Cap on reported diagnostics per file. |
mercury.symbols.moduleQualifiedNames |
true |
Module-qualified workspace symbols. |
mercury.completion.enableStdlib |
true |
Offer stdlib names in completion. |
mercury.semanticTokens.enable |
true |
Enable semantic-token highlighting. |
mercury.format.enable |
true |
Enable document/range formatting. |
The server always injects --no-color-diagnostics --no-max-error-line-width
(and forces MERCURY_ENABLE_COLOR=never, LC_ALL=C) so that diagnostics are
machine-parsable and never leak ANSI colour codes; mercury.mmc.args is
appended on top.
Commands
- Mercury: Build —
mmc --make (or mmake when an Mmakefile exists, or
a custom mercury.build.command).
- Mercury: Check Current File — save and re-run diagnostics.
- Mercury: Mark File as Mercury — set a
.m buffer's language.
- Mercury: Restart Language Server / Show Language Server Output.
Development
npm install
npm run build # bundle client + server (esbuild)
npm run watch # rebuild on change
npm run typecheck # tsc --noEmit
npm run lint
npm test # unit + grammar tokenization + live-server (needs mmc)
npm run test:vscode # full VS Code host suite (needs a compatible VS Code + display)
npm run package # produce mercury-lang.vsix
Press F5 (Run Extension) to launch an Extension Development Host.
The compound Run Extension + Attach to Server also attaches the debugger to
the language server on port 6009.
Tests
npm run test:unit — Mocha unit tests for the diagnostics parser (checked
against the compiler's own .err_exp golden files) and the symbol scanner.npm run test:grammar — tokenizes the sample files with vscode-textmate,
asserting scopes and embedded-language regions.npm run test:server — spins up the built language server over LSP stdio and
drives real mmc diagnostics, outline, definition, hover, completion and
semantic tokens end-to-end.
Acknowledgements
The syntax grammar is ported from vim/syntax/mercury.vim and the symbol
scanner from scripts/mtags, both part of the Mercury distribution.
License
MIT. See the LICENSE file in this repository.
| |
