govim plugin API

Status

Alpha: largely working, but there are a number of gopls issues to be worked through/out.

So what can the govim plugin do?

govim is largely driven by gopls, the Language Server Protocol server for Go.

❇️ Hover information

Provide the user with more context on the item under the mouse. Simply hover over an identifier with the mouse to see a popup with type/signature details. To trigger hover information via a key mapping, see this tip.

^_🎬 Demo

❇️ Format-on-save

Automatically format .go files as they are saved. Configure which tool to use via the govim config function using the "FormatOnSave" key.

The plugin default is:

call govim#config#Set("FormatOnSave", "goimports")

For the list of valid values see the go doc for FormatOnSave

See the config package for more all valid options and more details.

^_🎬 Demo

❇️ Code completion

Provide completion suggestions at the cursor. Code completion is triggered by the key combination <C-x><C-o> (see :help i_CTRL-X_CTRL-O) which translates as "holding down the left control key, press x and then o". If you prefer you can define a different key combination to trigger completion, or alternatively some plugins allow you to have completion be auto-triggered as you type. Unimported completions are also available, for example:

package main

func main() {
    fmt.Prin_
}

Attempting completion with the cursor at the position indicated by _ will result in the candidates Print, Printf and Println being offered. On selecting one of the options, the "fmt" import will automatically be added.

^_🎬 Demo

❇️ Go-to definition

Jump to the definition of the identifier under the cursor. Go-to definition is triggered by the <C-]> combination which translates as "holding down the left control key, press ]". Alternatively you can use <C-LeftMouse>. To jump back to the usage site, use <C-t> or <C-RightMouse>. These default mappings are defined here.

^_🎬 Demo

❇️ Quickfix diagnostics

Code diagnostics (compile, vet errors and the like) in the quickfix window. The quickfix window does not open by default. Instead you need to use :cwindow, which will open the quickfix window but only if there are errors. If the focus shifting of :cwindow and :copen is frustrating for you, see this tip

^_🎬 Demo

❇️ Find references

Find references to the identifier under the cursor. Simply call the :GOVIMReferences command, and the quickfix window will be populated with all references to the identifier, with the definition always listed first.

^_🎬 Demo to follow

❇️ Renaming symbols

Rename the symbol under the cursor. Simply call the :GOVIMRename command and you will be prompted for a new name.

^_🎬 Demo to follow

❇️ Using standard library string functions

When working in Vim, it's common to find yourself thinking "if only I could call function X from the standard library on the text I have selected."

With the GOVIMStringFn that's possible. Consider the following example:

var r = regexp.MustCompile(`This is a test. What happens to / in here?`)

If we visually select (using <C-v> in normal mode) the text block between the back-ticks and then call:

:'<,'>GOVIMStringFn regexp.QuoteMeta

we will be left with:

var r = regexp.MustCompile(`This is a test\. What happens to / in here\?`)

A limited number of string and []byte-based standard library functions are currently supported. Please raise issues if you find critical functions missing.

^_🎬 Demo to follow

❇️ AST-oriented motions

Move the cursor relative to the Go AST representation of the buffer contents. Vim defines some useful motions, for example ]] (which can take a count) moves the cursor forward to the next { character in the first column (see :help object-motions for more information). However, we can be more precise with these motion definitions and talk in terms of the AST representation of the buffer we are editing. The go/ast package declares the types used to represent syntax trees for Go packages. govim now defines ]] to be "move forward to the next start of a file-level declaration, i.e. general (import, const, var or type) or function declaration. For the full list of motions currently defined, see here.

^_🎬 Demo to follow

❇️ Suggested fixes

Popup with suggested fixes to diagnostics. Some diagnostics also comes with suggested fixes, for example if you try to assign a variable itself a diagnostics warning "self-assignment of x to x" will appear. If you call ":GOVIMSuggestedEdits" with the cursor on that line, a popup will show a list of suggested edits. Press <Enter> to apply the edit or <Esc> to close the popup without applying. If there are more than one diagnostic with suggested fixes on the same row, <C-n> and <C-p> cycle between the popups.

Configuration

govim supports user-set configuration, via a .vimrc or similar. The variables that can be set are described in the config package.

Work-in-progress

The following features are work-in-progress.

✴️ Formatting a range

To follow in #42

^_🎬 Demo to follow

✴️ AST-based syntax highlighting

To follow in #24. Use go/ast to syntax highlight a file instead of Vim's regex-based syntax definitions. More accurate and potentially faster for very files.

^_🎬 Demo to follow