gopls integrator FAQ

This page is meant to provide information to those who are developing LSP clients to integrate with gopls. Examples of such clients include VSCode-Go, vim-go, govim, emacs-lsp, and many others. For a more complete list, see all of the editors that support gopls here.

The best starting point for any integrator is the Language Service Protocol Specification. The same specification can be found as a markdown document on Github here. golang.org/x/tools/internal/lsp/protocol represents a Go definition of the spec.

Feel free to add additional questions and answers here as they come up. To ask a question that isn't answered here, please reach out to the gopls developers either by filing an issue in the Go issue tracker or by sending a message to the #gopls channel in the Gophers Slack.

Table of Contents

• Supported features
• UTF-8, UTF-16 and position information
• []TextEdit responses
• RPC response errors
• Files that change outside of the editor

Supported features

gopls is in active development, so the set of supported features is in flux. A basic overview of supported features can be found on the gopls wiki page.

For the most current answer, see the InitializeResult response to the Initialize request. The server enumerates its capabilities in the ServerCapabilities, so it explicitly states which features it does support.

At the time of writing (2019-08-06), gopls returns the InitializeResult in the server.initialize function which can be found in golang.org/x/tools/internal/lsp/general.go. All of the exported gopls server functions can be found in golang.org/x/tools/internal/lsp/server.go.

UTF-8, UTF-16 and position information

The majority of LSP requests require the client to pass position information to the server. This is described in the LSP specification. Specifically, it is important to note that:

A position inside a document (see Position definition below) is expressed as a zero-based line and character offset. The offsets are based on a UTF-16 string representation. So a string of the form a𐐀b the character offset of the character a is 0, the character offset of 𐐀 is 1 and the character offset of b is 3 since 𐐀 is represented using two code units in UTF-16.

This means that integrators will need to calculate UTF-16 based column offsets.

For Go-based integrators, the golang.org/x/tools/internal/span will be of use. #31080 tracks making span and other useful packages non-internal.

[]TextEdit responses

At the time of writing (2019-07-15) the []TextEdit response to textDocument/formatting and the WorkspaceEdit response to textDocument/rename comprises range-based deltas. The spec is not explicit about how these deltas should be applied, instead simply stating:

If multiple inserts have the same position, the order in the array defines the order in which the inserted strings appear in the resulting text.

All []TextEdit are sorted such that applying the array of deltas received in reverse order achieves the desired result that holds with the spec.

RPC response errors

https://go-review.googlesource.com/c/tools/+/170958 and related discussions are looking to help shape what it means for a server method to return an error. i.e.

• Under what conditions would the Format method return an error?
• On a syntax error, or just for low-level LSP/transport issues?
• What should editors do in response to such errors?

This answer is therefore a WIP.

Files that change outside of the editor

For example, files that are created/modified/removed as a result of go generate. Per @ianthehat:

The plan is to have the client do all the work for us. Specifically we are going to start using workspace/didChangeWatchedFiles to monitor all the files we are caching AST's for

This is currently not implemented (see #31553).