README

What

To view rustc --explain output in a popup window inside Vim.

Why

rustc provides detailed and helpful information, it will be nice to be able to access it without leaving Vim, and even better with only a key mapping at an error/diagnostic message entry.

How

In command mode, execute :RustcExplain E0308, or without E as :RustcExplain 0433, or even :RustcExplain 433, a popup/float window will appear with rustc --explain output in it.

It can be easier with a key mapping if linter/maker engine like ALE, Neomake, or LSP client like vim-lsp is used. First, put the following snippet in the Vim config file to set the mapping, in this example <leader>E, to your liking.

augroup rustcexplain
  autocmd!
  autocmd Filetype qf
        \ nmap <silent> <buffer> <leader>E <CR><Plug>(rustcexplain_open)
  autocmd Filetype rust
        \ nmap <silent> <buffer> <leader>E <Plug>(rustcexplain_open)
augroup END

After diagnostic messages are populated in the location list, move to the line with error, and <leader>E will bring up the popup window.

Note: the preceeding <CR> in the above autocmd for Filetype qf is to select the entry in the location list because moving cursor up or down does not select the line, <CR> does that.

How in more detail

Under the hood, what this plugin does is run the rustc --explain command and pipe the output from stdout/stderr and put it in a popup/float window.

Some more details:

• When focus is on an error entry in location list
  • <leader>E will jump to the line and show rustc explain output of the error at the line.
  • :RustcExplain will show rustc explain output of that error, focus stays at the location entry.
• When focus is in source code window and cursor line has corresponding error message in location list
  • <leader>E and :RustcExplain will show rustc explain output of that error.
• When focus is in source code window and cursor line has no corresponding error message in location list window
  • <leader>E and :RustcExplain will show rustc explain output of error at the currently selected entry in location list.

Install

This is a regular Vim plugin, install with your choice of plugin manager as you normally do with any plugin.

Depedency

• Vim: popup window is used, so Vim of version >= 8.2 with +popupwin enabled is required.
• Neovim: version >= 0.6.0 should work.
• Development dependencies:
  • vader.vim and vim-themis for unit test;
  • poetry for managing tools built with Python

Known Limitation/Issues

• only tested with ALE, Neomake, and vim-lsp;
• only works on diagnostic message reported to Vim as error, other levels are ignored;

Configuration

g:rustcexplain_rustc_bin

the rustc binary used to generate --explain output, for example:

let g:rustcexplain_rustc_bin = 'rustup run nightly rustc'

default is 'rustc', assuming it is available from the $PATH

g:rustcexplain_rustc_options

add extra options to the rustc command, for example:

let g:rustcexplain_rustc_options = '--edition 2015'

default is ''

g:rustcexplain_keymaps

customize the key mapping to your finger muscle habits for navigating in the popup window.

default is:

let g:rustcexplain_keymaps = {
        \ 'q':      'QUIT',
        \ "\<c-y>": 'UP',
        \ "\<c-e">: 'DOWN',
        \ "\<c-u>": 'PAGEUP',
        \ "\<c-d>": 'PAGEDOWN',
        \ "\<c-t>": 'TOP',
        \ "\<c-g>": 'BOTTOM',
        \}

Vim's popup-filter has detailed info (for example the issue on using ESC) on setting keys on popup window.

Note: This setting is for Vim only. I have not been able to find information on such customization for Neovim's float window.

Acknowledgement

• rustc for friendly and useful compiler messages
• vader.vim and vim-themis for ease of writing tests for Vim plugins.
• rhysd/action-setup-vim for GitHub Action to setup Vim/Neovim.