blob: 845f9eb007f67a3f4f79b2eda775f02e0de265ec [file] [log] [blame] [view]
Rebecca Stambler96954832019-09-15 20:25:54 -04001# Documentation for plugin authors
Ian Cottrell062dbae2019-05-09 10:35:27 -04002
Rebecca Stambler96954832019-09-15 20:25:54 -04003If you are integrating `gopls` into an editor by writing an editor plugin, there are quite a few semantics of the communication between the editor and `gopls` that are not specified by the [LSP specification].
Ian Cottrell062dbae2019-05-09 10:35:27 -04004
5We attempt to document those details along with any other information that has been helpful to other plugin authors here.
6
7If you are implementing a plugin yourself and have questions this page does not answer, please reach out to us to ask, and then also contribute your findings back to this page.
8
9## Supported features
10
11For the most part you should look at the [list](status.md#supported-features) in the current status document to know if gopls supports a feature.
12For a truly authoritative answer you should check the [result][InitializeResult] of the [initialize] request, where gopls enumerates its support in the [ServerCapabilities].
13
14
15## Positions and ranges
16
17Many LSP requests pass position or range information. This is described in the [LSP specification][lsp-text-documents]:
18
19> 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.
20
21This means that integrators will need to calculate UTF-16 based column offsets.
22
23[`golang.org/x/tools/internal/span`] has the code to do this in go.
24[#31080] tracks making `span` and other useful packages non-internal.
25
26## Edits
27
28In order to deliver changes from gopls to the editor, the LSP supports arrays of [`TextEdit`][lsp-textedit]s in responses.
29The spec specifies exactly how these should be applied:
30
31> All text edits ranges refer to positions in the original document. Text edits ranges must never overlap, that means no part of the original document must be manipulated by more than one edit. However, it is possible that multiple edits have the same start position: multiple inserts, or any number of inserts followed by a single remove or replace edit. 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.
32
33All `[]TextEdit` are sorted such that applying the array of deltas received in reverse order achieves the desired result that holds with the spec.
34
35## Errors
36
37Various error codes are described in the [LSP specification][lsp-response]. We are still determining what it means for a method to return an error; are errors only for low-level LSP/transport issues or can other conditions cause errors to be returned? See some of this discussion on [#31526].
38
39The method chosen is currently influenced by the exact treatment in the currently popular editor integrations. It may well change, and ideally would become more coherent across requests.
40
41* [`textDocument/codeAction`]: Return error if there was an error computing code actions.
42* [`textDocument/completion`]: Log errors, return empty result list.
43* [`textDocument/definition`]: Return error if there was an error computing the definition for the position.
44* [`textDocument/typeDefinition`]: Return error if there was an error computing the type definition for the position.
45* [`textDocument/formatting`]: Return error if there was an error formatting the file.
46* [`textDocument/highlight`]: Log errors, return empty result.
47* [`textDocument/hover`]: Return empty result.
48* [`textDocument/documentLink`]: Log errors, return nil result.
49* [`textDocument/publishDiagnostics`]: Log errors if there were any while computing diagnostics.
50* [`textDocument/references`]: Log errors, return empty result.
51* [`textDocument/rename`]: Return error if there was an error computing renames.
52* [`textDocument/signatureHelp`]: Log errors, return nil result.
53* [`textDocument/documentSymbols`]: Return error if there was an error computing document symbols.
54
55## Watching files
56
57It is fairly normal for files that affect `gopls` to be modified outside of the editor it is associated with.
58
59For instance, files that are needed to do correct type checking are modified by switching branches in git, or updated by a code generator.
60
61Monitoring files inside gopls directly has a lot of awkward problems, but the [LSP specification] has methods that allow gopls to request that the client notify it of file system changes, specifically [`workspace/didChangeWatchedFiles`].
62This is currently being added to gopls by a community member, and tracked in [#31553]
63
Rob Findley0dcbe362020-10-25 15:13:56 -040064[InitializeResult]: https://pkg.go.dev/golang.org/x/tools/internal/lsp/protocol#InitializeResult
65[ServerCapabilities]: https://pkg.go.dev/golang.org/x/tools/internal/lsp/protocol#ServerCapabilities
66[`golang.org/x/tools/internal/span`]: https://pkg.go.dev/golang.org/x/tools/internal/span#NewPoint
Ian Cottrell062dbae2019-05-09 10:35:27 -040067
Fazlul Shahriar8a18b872019-10-02 02:23:42 -040068[LSP specification]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/
69[lsp-response]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#response-message
70[initialize]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/#initialize
71[lsp-text-documents]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#text-documents
72[lsp-textedit]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textedit
Ian Cottrell062dbae2019-05-09 10:35:27 -040073
Fazlul Shahriar8a18b872019-10-02 02:23:42 -040074[`textDocument/codeAction`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_codeAction
75[`textDocument/completion`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_completion
76[`textDocument/definition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_definition
77[`textDocument/typeDefinition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_typeDefinition
78[`textDocument/formatting`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_formatting
79[`textDocument/highlight`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_highlight
80[`textDocument/hover`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_hover
81[`textDocument/documentLink`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentLink
82[`textDocument/publishDiagnostics`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_publishDiagnostics
83[`textDocument/references`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_references
84[`textDocument/rename`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_rename
85[`textDocument/signatureHelp`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_signatureHelp
86[`textDocument/documentSymbols`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentSymbols
87[`workspace/didChangeWatchedFiles`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#workspace_didChangeWatchedFiles
Ian Cottrell062dbae2019-05-09 10:35:27 -040088
89[#31080]: https://github.com/golang/go/issues/31080
90[#31553]: https://github.com/golang/go/issues/31553
Rob Findley0dcbe362020-10-25 15:13:56 -040091[#31526]: https://github.com/golang/go/issues/31526