cybercyst/go
1
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-05-05 15:43:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

gopls: separate integrator FAQ into its own wiki page

Rebecca Stambler 2019-06-18 12:53:43 -04:00
parent 43ba1fe787
commit 4f40d2f096
1 changed files with 4 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
gopls.md

@ -1,5 +1,7 @@
`gopls` (pronounced: "go please") is an implementation of the Language Server Protocol (LSP) server for Go.
The LSP allows any text editor to be extended with IDE-like features (see https://langserver.org/ for details). It is currently in alpha, so it is not stable.
The LSP allows any text editor to be extended with IDE-like features (see https://langserver.org/ for details). It is currently in alpha, so it is not stable.
For folks with questions about integrating gopls within an editor, see https://github.com/golang/go/wiki/gopls-integrator-FAQ.
# Table of Contents
[Status](#status)
@ -7,8 +9,7 @@ The LSP allows any text editor to be extended with IDE-like features (see https:
[Installation](#installation)
[Known Issues](#known-issues)
[Contributing](#contributing)
[FAQ](#faq)
[Integrator FAQ](#integrator-faq)
[FAQ](#faq)
[Additional Information](#additional-information)
## Status
@ -221,52 +222,6 @@ Please see all available issues under the [gopls label](https://github.com/golan
- **Why is it called `gopls`?** Since `gopls` works both as a language server and as a command line tool, we wanted a name that could be used as a verb. For example, `gopls check` should read as "go please check." See: [golang.org/cl/158197](https://golang.org/cl/158197).
## 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](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md). [`golang.org/x/tools/internal/lsp/protocol`](https://godoc.org/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`](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#initialize-request-leftwards_arrow_with_hook), specifically the `capabilities` field of type `ServerCapabilities`
#### UTF-8, UTF-16 and position information
As an example, the [`Hover`](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#hover-request-leftwards_arrow_with_hook) method takes [`TextDocumentPositionParams `](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#textdocumentpositionparams) which has a `position` field of type [`Position`](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#text-documents). 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`](https://godoc.org/golang.org/x/tools/internal/span#NewPoint) will be of use. [#31080](https://github.com/golang/go/issues/31080) tracks making `span` and other useful packages non-internal.
#### `textDocument/formatting` response
At the time of writing (2019-03-28) the [`[]TextEdit`](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#textedit) response to [`textDocument/formatting`](https://github.com/Microsoft/language-server-protocol/blob/gh-pages/specification.md#document-formatting-request--leftwards_arrow_with_hook) 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](https://github.com/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](https://github.com/golang/go/issues/31553)).
## Additional Information
Questions can be directed toward [@stamblerre](https://github.com/stamblerre) or [@ianthehat](https://github.com/ianthehat). For consistent updates on the development progress of gopls, see the notes from the golang-tools meetings (https://github.com/golang/go/wiki/golang-tools).