This plugin requires Neovim 0.11 or later and has no other dependencies.
Use a plugin manager such as paq and pass the name of this repository:
paq 'ashinkarov/nvim-agda'With lazy.nvim, add this to your
plugin specs (ft and init are optional):
{
"ashinkarov/nvim-agda",
ft = "agda", -- load the plugin when an Agda file is opened
init = function()
-- Settings (see Configuration) must be set before the plugin loads.
vim.g.nvim_agda_settings = { agda = "/path/to/agda" }
end,
}With ft = "agda" the plugin is loaded for .agda, .lagda and
.lagda.md files.
Alternatively, you can install the plugin manually as follows:
$ mkdir -p ~/.local/share/nvim/site/pack/git-plugins/start
$ git clone https://github.com/ashinkarov/nvim-agda.git --depth=1 ~/.local/share/nvim/site/pack/git-plugins/start/nvim-agdaThe plugin follows semantic versioning; releases
are tagged vX.Y.Z and their changes are listed in
CHANGELOG.md. :AgdaVersion shows the version you
have. The plugin managers install master by default; to install the
latest release instead, add version = "*" to the lazy.nvim spec, or
clone with --branch vX.Y.Z.
The plugin is configured with the global dictionary
g:nvim_agda_settings, for example in Lua:
vim.g.nvim_agda_settings = {
agda = "/usr/local/bin/agda", -- the Agda binary (default: agda)
agda_args = { "--arg1", "--arg2" }, -- arguments to pass to Agda
diagnostics = "all", -- "all", "structured" or "none" (see Diagnostics)
diagnostic_severity = { UnsolvedMeta = "hint" }, -- (see Diagnostics)
debug_p = true, -- print debug messages
}or in Vimscript, let g:nvim_agda_settings = {'agda': '/usr/local/bin/agda'}.
Every entry may be omitted, as may the variable itself. The settings
are read when an Agda buffer is opened.
Neovim comes with built-in Lua support, which makes it much simpler to write complex plugins. This plugin is written almost entirely in Lua, which handles the asynchronous interaction with Agda and the state of the editor.
- Use asynchronous communication so that we can use the editor when Agda is working.
- Avoid goal commands when the file has not been typechecked.
- Use popup windows to show location-specific information.
- Don't treat Agda as a black box; change the way it interacts in case it makes sense.
- Try to be efficient.
The plugin covers most of the interaction of Agda's Emacs mode: loading and highlighting, the goal commands, case splitting, going to definitions and the input of Unicode characters. It does not try to copy the Emacs mode exactly; doc/emacs-mode.md compares the two command by command, with what is missing, what works differently and what we decided against.
Information about a goal (its type and context, inferred types, normal
forms) is shown in a popup at the goal; other messages go to the
message area, with the full text in :messages. The content of a goal
can be edited in a separate window (\e), so that the file does not
change, and the goal commands work there too. Goal commands on a file
that was changed reload it first, so that the goals are up to date.
Both ? and {! !} goals work; typing into a {! !} goal changes the
file, so the next goal command reloads it.
The keys are <LocalLeader> mappings (\ by default) in Agda buffers.
| Key | Command | What it does |
|---|---|---|
| l | :AgdaLoad |
Load (type-check) the file |
| , | :AgdaTypeContext |
Show the goal type and context, and the constraints on the goal |
| . | :AgdaTypeContextInfer |
The same, with the type of the goal's content |
| d | :AgdaInfer |
Infer the type of the goal's content, or of an expression |
| n | :AgdaCompute |
Compute the normal form of the goal's content, or of an expression (also copied to the clipboard) |
| r | :AgdaRefine |
Refine the goal: give its content if it fits, otherwise apply it, or introduce a constructor or lambda in an empty goal |
| m | :AgdaElaborateGive |
Elaborate and give: fill the goal with its content, checked and simplified (e.g. not tt becomes ff) |
| c | :AgdaMakeCase |
Case split on the variables in the goal |
| a | :AgdaAuto |
Search for a solution of the goal (or of all goals in the file) |
| s | :AgdaSolve |
Solve the constraints of the goal (or of all goals in the file) |
| h | :AgdaHelperFun |
Show the type of a helper function for the goal's content (also copied to the clipboard) |
| o | :AgdaModuleContents |
Show the contents of a module |
| w | :AgdaWhyInscope |
Explain why a name is in scope: the goal's content in a goal, otherwise the name under the cursor (an operator part such as ∧ stands for _∧_) |
| z | :AgdaSearchAbout |
Search about: the definitions whose types mention all the given names, and whose names contain the given "quoted" parts (e.g. ℕ _+_ "comm"); not a search by type |
| ? | :PrintGoals |
Show the goals with their types, and the warnings and errors |
| f | :GoalNext |
Go to the next goal |
| b | :GoalPrev |
Go to the previous goal |
| e | :MkPrompt |
Edit the goal's content in a window |
| q | :AgdaCloseMsg |
Close the popup |
In the goal-edit window, the keys , . d n r m c a s h work on the
goal with the content of the window, \q closes the popup and q
closes the window (as does :q).
Commands without keys: :AgdaContext (the context of the goal alone),
:AgdaShowConstraints, :ShowImplicit and :HideImplicit,
:ShowIrrelevant and :HideIrrelevant (show or hide implicit or
irrelevant arguments; the choice lasts across reloads), :AgdaVersion
(the versions of the plugin and of Agda),
and :AgdaStart and :AgdaStop (start or stop the Agda process; any
command starts it when needed).
Outside goals, why in scope, search about, module contents, infer and
compute work in the scope at the top level of the file, as in the Emacs
mode: names that a nested module opens or imports are not in scope
there. To ask in the scope of a place inside a module, put a goal (?)
there and use the command in the goal.
A number between <LocalLeader> and the key chooses how far Agda
normalises what it shows: \1, as is, \2, instantiated, \3, head
normal form, \4, simplified and \5, normalised. This works for
, . d m a s h o z ? (also in the goal-edit window) and for
:AgdaContext; the commands take the number as an argument, as in
:AgdaInfer 5. Without a number each command uses its default:
simplified, except for the context (head normal form), infer
(normalised), and helper functions and auto (as is). \u, is the same
as \5,.
For compute (n) the number chooses the mode instead: \1n ignores
abstract, \2n uses the Show instance of the type to print the
result, and \3n computes only the head normal form. \1r refines an
empty goal of function type with a pattern-matching lambda
(λ { x → ? }) rather than λ x → ?.
After a load, the error, the warnings (termination and coverage
problems, unreachable clauses, ...) and the unsolved metas are also
Neovim diagnostics, with Agda's message. CTRL-W d shows the message
at the cursor, ]d and [d go to the next and previous one, and
:lua vim.diagnostic.setloclist() lists them. They are not underlined,
as the highlighting marks these places already; virtual text and signs
follow your vim.diagnostic.config(). Unsolved constraints have no
diagnostics, as Agda does not say where they are. Where a line has
several diagnostics, its sign is that of the most severe one.
The diagnostics have Agda's level, error or warning. Missing
definitions have none: Agda reports them as errors, but a module being
written usually has some, so they are only in the message of the load
(and :messages) and highlighted with NoDefinition. The setting
diagnostic_severity sets the severity by the name of the warning,
"error", "warn", "info", "hint", or false for no diagnostic:
vim.g.nvim_agda_settings = {
diagnostic_severity = { MissingDefinitions = "hint", UnsolvedMeta = "hint" },
}The names are those in Agda's messages, e.g. [CoverageIssue] or
-W[no]UnreachableClauses, which are also the diagnostics' codes;
agda --help=warning lists them. Unsolved metas are UnsolvedMeta.
The error that stops a load has no name and is always an error.
Anything else that depends on the severity is set with Neovim's
vim.diagnostic.config() for the plugin's namespace, for example to
show signs only for warnings and errors:
vim.diagnostic.config({ signs = { severity = { min = vim.diagnostic.severity.WARN } } },
require("agda.diagnostics").ns)Agda sends the places of the error and of unsolved metas as data, but
those of warnings only at the start of their messages, in a format that
may change. If the diagnostics of warnings ever go wrong, set
diagnostics to "structured" in g:nvim_agda_settings to keep only
the error and unsolved metas, or to "none" for no diagnostics.
The names of warnings come from their messages too, so with
"structured" only UnsolvedMeta in diagnostic_severity applies.
In insert and command-line mode, <LocalLeader> (\ by default)
starts an input sequence, many of them as in the Emacs mode: \to
gives →, \ga α, \bN ℕ, \McC 𝒞, \1 ₁; see
lua/agda/input.lua for the full list. In other buffers,
:runtime agda-input.vim sets them too.
On the command line, where some sequences are also Vim's regex syntax
(\<, \., \1, ...), type CTRL-V before the backslash to get the
backslash itself: / CTRL-V \<foo searches for \<foo.
While you type a sequence Neovim shows the keys typed so far, but not
how the sequence can continue. A plugin that shows the possible
continuations of a mapping can do that, as the sequences are ordinary
buffer-local mappings. We have not tried these, but they should work:
- which-key.nvim: its
automatic triggers include insert mode, so after
\it lists the next keys with the characters they give. - mini.clue needs a trigger
for
<LocalLeader>in insert mode:require('mini.clue').setup({ triggers = { { mode = 'i', keys = '<LocalLeader>' } } })
The plugin does not change your status line, but keeps a short
description of what Agda is doing in b:agda_status, e.g.
Agda: checking…, Agda: 2 goals, Agda: checked (no goals or
unsolved metas left) or Agda: error, followed by (implicit) or
(irrelevant) when those arguments are shown. It is empty in other
buffers and when Agda is not running. To show it, add AgdaStatus()
to your status line:
set statusline+=%{AgdaStatus()}With a statusline plugin, use a component that returns
vim.b.agda_status, e.g. for lualine:
sections = { lualine_x = { function() return vim.b.agda_status or "" end } }The User AgdaStatus autocommand runs whenever the status changes, for
status lines that need to be told to refresh.
After the file has been loaded, CTRL-] jumps to the definition of the
name under the cursor, also in other files such as imported modules or
the standard library, and CTRL-T jumps back, as with tags (the plugin
sets 'tagfunc'). CTRL-W ] opens the definition in a new window,
and with the mouse, CTRL-LeftMouse and g<LeftMouse> jump to the
definition of the name clicked on. The plugin maps these keys in Agda
buffers, so that they also work on operators such as + in x + ?,
where Vim's own commands find no identifier; elsewhere they do what
they do in Vim.
The definitions come from Agda's highlighting, as in the Emacs mode
(M-.), so they are those of the last load; names added since then are
not found.
Agda's highlighting uses the standard highlight groups (Keyword,
Type, ...) and groups of its own. By default these are links to
standard groups, so that they take their colours from your colour
scheme: goals have the background of DiffAdd (greenish in most colour
schemes), and problems are underlined like diagnostics.
| Group | Highlights | Default |
|---|---|---|
AgdaHole |
Goals | DiffAdd |
AgdaUnsolvedMeta |
Unsolved metas | DiagnosticUnderlineWarn |
AgdaUnsolvedConstraint |
Unsolved constraints | AgdaUnsolvedMeta |
NonTerminating |
Termination problems | DiagnosticUnderlineWarn |
NoDefinition |
Missing definitions | DiagnosticUnderlineWarn |
AgdaCoverageProblem |
Missing cases | DiagnosticUnderlineWarn |
AgdaIncompletePattern |
Incomplete patterns | DiagnosticUnderlineWarn |
AgdaPositivityProblem |
Positivity problems | DiagnosticUnderlineWarn |
AgdaInstanceProblem |
Instance problems | DiagnosticUnderlineWarn |
AgdaConfluenceProblem |
Confluence problems | DiagnosticUnderlineWarn |
AgdaErrorWarning |
Warnings that are errors | DiagnosticUnderlineError |
AgdaShadowingInTelescope |
Shadowed names in telescopes | DiagnosticUnderlineHint |
AgdaCosmeticProblem |
Cosmetic problems | DiagnosticUnderlineHint |
AgdaDeadcode |
Unreachable clauses | DiagnosticUnnecessary |
Problems are highlighted on top of the highlighting of names, so that for example a name keeps its colour in a clause with missing cases.
You can set the groups in your colour scheme or configuration.
:colorscheme clears them, so set them after it, or in a ColorScheme
autocommand:
vim.api.nvim_create_autocmd("ColorScheme", {
callback = function()
vim.api.nvim_set_hl(0, "NonTerminating", { bg = "#5f2f2f" })
end,
})Some colour schemes have an option for this. With
catppuccin, custom_highlights
sets groups with the colours of the flavour in use:
require("catppuccin").setup({
custom_highlights = function(colors)
return {
AgdaHole = { bg = colors.surface1 },
NonTerminating = { bg = colors.maroon, fg = colors.base },
NoDefinition = { sp = colors.peach, undercurl = true },
}
end,
})If you edit the file while Agda checks it, the highlighting that arrives afterwards is applied to the lines that you did not edit, and a warning says how many places were left out until the next load.
Compared with the Emacs mode, the plugin does not have aborting a
command (use :AgdaStop, which has the same effect), compiling, or
backend commands. Unsolved constraints are not shown at their places
(see "Diagnostics"), and while typing an input sequence such as \ga
the possible continuations are shown only with a plugin (see "Typing
Unicode"). See doc/emacs-mode.md for a comparison
with the Emacs mode.
make test runs the test-suite; see tests/README.md.
GitHub runs it for every pull request.
Changes are listed under "Unreleased" in CHANGELOG.md. To release them
as version X.Y.Z, run make release VERSION=X.Y.Z on master (see
scripts/release.sh): it gives the section the
version and the date, sets M.version in lua/agda/init.lua, runs the
tests, commits, and tags the commit vX.Y.Z with the section as the
message of the tag (for the release notes). Then push the commit and
the tag with git push origin master vX.Y.Z.