Skip to content

gopls integrator FAQ

Jump to bottom
Rebecca Stambler edited this page Jun 18, 2019 · 10 revisions

gopls Integrator FAQ

What follows is a list of questions/ideas/suggestions for folks looking to integrate gopls within an editor/similar.

A good starting point for any integrator is the Language Service Protocol Specification. golang.org/x/tools/internal/lsp/protocol represents a Go definition of the spec.

What does gopls support?

The most accurate answer to this question is to examine the InitializeResult response to Initialize, specifically the capabilities field of type ServerCapabilities

UTF-8, UTF-16 and position information

As an example, the Hover method takes TextDocumentPositionParams which has a position field of type Position. The key point to note from that last link is the following:

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.

i.e. 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.

textDocument/formatting response

At the time of writing (2019-03-28) the []TextEdit response to textDocument/formatting 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.

i.e. it specifies only the resulting state of the document.

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 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).

Clone this wiki locally