The Dhall language integration consists of the following parts:
The VSCode/ium plugin "Dhall Language Support" (vscode-language-dhall) adds syntax highlighting for Dhall files.
The VSCode/ium plugin "Dhall LSP Server" (vscode-dhall-lsp-server) implements the LSP client – yes, there is a naming issue here – that communicates with the backend via the LSP protocol to provide advanced language features like error diagnostics or type information, etc.
dhall-lsp-server, which is part of the dhall-haskell project, implements the actual LSP server (i.e. the backend) that implements those language features in an editor agnostic way, though at the moment only a VSCode/ium frontend exists.
Installation
The "official" releases can be installed as follows:
vscode-language-dhall should be installed directly from VSCode/ium via the extensions marketplace.
vscode-dhall-lsp-server can also be installed directly from the marketplace.
dhall-lsp-server can be installed from hackage with cabal install dhall-lsp-server.
Installing the latest development versions
Note The versions of vscode-dhall-lsp-server and dhall-lsp-server need not necessarily match: an older client version will simply not expose all commands available in the backend, while an older server might not implement all commands exposed in the UI.
vscode-dhall-lsp-server
You need to have npm installed (e.g. using your favourite package manager).
Clone git@github.com:PanAeon/vscode-dhall-lsp-server.git into a folder under ~/.vscode-oss/extensions/ (or ~/.vscode/extensions/ if you VSCode rather than VSCodium).
Inside the checked out folder run npm install to fetch any dependencies.
Inside the checked out repository run stack install dhall-lsp-server.
Usage / Features
Diagnostics
Every time you save a Dhall file it is parsed and typechecked, and any errors are marked. You can hover over the offending code to see the error message; to see a detailed explanation in the case of type errors, click the Explain link in the hover box.
Clickable imports
As long as the file parses successfully, all (local file and remote) imports will be underlined and clickable.
Type on hover
You can hover over any part of the code and it will tell you the type of the subexpression at that point – if you highlight an identifier you see its type; if you highlight the -> in a function you will see the type of the entire function. This feature only works if the code passes the typechecker!
Code completion
As you type you will be offered completions for:
environment variables
local imports
identifiers in scope (as well as built-ins)
record projections from 'easy-to-parse' records (of the form ident1.ident2[.ident3...])
union constructors from 'easy-to-parse' unions
This is the only feature that works even when the file does not parse (or typecheck).
Formatting and Linting
Right click and select "Format Document" to run the file through the Dhall formatter. The command "Lint and Format" can be selected via the Command Palette (Ctrl+Shift+P); this will run the linter over the file, removing unused let bindings and formatting the result.
Annotate lets
Right-click the bound identifier in a let binding and select "Annotate Let binding with its type" to do exactly that.
Freeze imports
Right-click an import statement and select "Freeze (refreeze) import" to add (or update) a semantic hash annotation to the import. You can also select "Freee (refreeze) all imports" from the Command Palette to freeze all imports at once.
Note that this feature behaves slightly differently from the dhall freeze command in that the hash annotations are inserted without re-formatting the rest of the code!
Developer notes
dhall-lsp-server
You can also use stack build dhall-lsp-server and point vscode-dhall-lsp-server.executable in the VSCode/ium settings to the stack build directory, to avoid overriding the installed version of the LSP server.
You can use standard Debug.Trace/putStrLn debugging; the output will show up in the "Output" panel in VSCode/ium.
To log all LSP communication set vscode-dhall-lsp-server.trace.server to verbose in VSCode/ium.
vscode-dhall-lsp-server
Instead of working in ~/vscode-oss/extensions/... directly, you can open a clone of the git repository in VSCode/ium and use the built-in debugging capabilities for extensions: press F5 (or click the green play button in the debugging tab) to launch a new VSCode/ium window with the modified extension (potentially shadowing the installed version).
To package a release:
Use npm install -g vsce to install the vsce executable. I recommend running npm config set prefix '~/.local' first to have npm install the executable in ~/.local/bin; this avoids having to use sudo and polluting the rest of the system.
Run vsce package inside the git repo to package the extension, resulting in a file vscode-dhall-lsp-server-x.x.x.vsix.
You can install the packaged extension directly by opening the .vsix file from within VSCod/ium.
New contents:
vscode-dhall-lsp-server
This is a Language Server Protocol VSCode plugin for the Dhall programming language.
Dhall language support in VSCode/ium
The Dhall language integration consists of the following parts:
Installation
The "official" releases can be installed as follows:
cabal install dhall-lsp-server.Installing the latest development versions
Note The versions of vscode-dhall-lsp-server and dhall-lsp-server need not necessarily match: an older client version will simply not expose all commands available in the backend, while an older server might not implement all commands exposed in the UI.
vscode-dhall-lsp-server
git@github.com:PanAeon/vscode-dhall-lsp-server.gitinto a folder under~/.vscode-oss/extensions/(or~/.vscode/extensions/if you VSCode rather than VSCodium).npm installto fetch any dependencies.dhall-lsp-server
git@github.com:dhall-lang/dhall-haskell.git.stack install dhall-lsp-server.Usage / Features
Diagnostics Every time you save a Dhall file it is parsed and typechecked, and any errors are marked. You can hover over the offending code to see the error message; to see a detailed explanation in the case of type errors, click the Explain link in the hover box.
Clickable imports As long as the file parses successfully, all (local file and remote) imports will be underlined and clickable.
Type on hover You can hover over any part of the code and it will tell you the type of the subexpression at that point – if you highlight an identifier you see its type; if you highlight the
->in a function you will see the type of the entire function. This feature only works if the code passes the typechecker!Code completion As you type you will be offered completions for:
ident1.ident2[.ident3...])This is the only feature that works even when the file does not parse (or typecheck).
Formatting and Linting Right click and select "Format Document" to run the file through the Dhall formatter. The command "Lint and Format" can be selected via the Command Palette (Ctrl+Shift+P); this will run the linter over the file, removing unused let bindings and formatting the result.
Annotate lets Right-click the bound identifier in a
letbinding and select "Annotate Let binding with its type" to do exactly that.Freeze imports Right-click an import statement and select "Freeze (refreeze) import" to add (or update) a semantic hash annotation to the import. You can also select "Freee (refreeze) all imports" from the Command Palette to freeze all imports at once.
Note that this feature behaves slightly differently from the
dhall freezecommand in that the hash annotations are inserted without re-formatting the rest of the code!Developer notes
dhall-lsp-server
stack build dhall-lsp-serverand pointvscode-dhall-lsp-server.executablein the VSCode/ium settings to the stack build directory, to avoid overriding the installed version of the LSP server.Debug.Trace/putStrLndebugging; the output will show up in the "Output" panel in VSCode/ium.vscode-dhall-lsp-server.trace.servertoverbosein VSCode/ium.vscode-dhall-lsp-server
~/vscode-oss/extensions/...directly, you can open a clone of the git repository in VSCode/ium and use the built-in debugging capabilities for extensions: press F5 (or click the green play button in the debugging tab) to launch a new VSCode/ium window with the modified extension (potentially shadowing the installed version).npm install -g vsceto install the vsce executable. I recommend runningnpm config set prefix '~/.local'first to have npm install the executable in~/.local/bin; this avoids having to use sudo and polluting the rest of the system.vsce packageinside the git repo to package the extension, resulting in a filevscode-dhall-lsp-server-x.x.x.vsix..vsixfile from within VSCod/ium.