golang.org/x/tools/gopls@v0.15.3/doc/design/integrating.md (about)

     1  # Documentation for plugin authors
     2  
     3  If 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].
     4  
     5  We attempt to document those details along with any other information that has been helpful to other plugin authors here.
     6  
     7  If 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  
    11  For 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.
    12  For 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  
    17  Many 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  
    21  This means that integrators will need to calculate UTF-16 based column offsets.
    22  Use `protocol.Mapper` for all the conversions.
    23  
    24  ## Edits
    25  
    26  In order to deliver changes from gopls to the editor, the LSP supports arrays of [`TextEdit`][lsp-textedit]s in responses.
    27  The spec specifies exactly how these should be applied:
    28  
    29  > 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.
    30  
    31  All `[]TextEdit` are sorted such that applying the array of deltas received in reverse order achieves the desired result that holds with the spec.
    32  
    33  ## Errors
    34  
    35  Various 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].
    36  
    37  The 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.
    38  
    39  * [`textDocument/codeAction`]: Return error if there was an error computing code actions.
    40  * [`textDocument/completion`]: Log errors, return empty result list.
    41  * [`textDocument/definition`]: Return error if there was an error computing the definition for the position.
    42  * [`textDocument/typeDefinition`]: Return error if there was an error computing the type definition for the position.
    43  * [`textDocument/formatting`]: Return error if there was an error formatting the file.
    44  * [`textDocument/highlight`]: Log errors, return empty result.
    45  * [`textDocument/hover`]: Return empty result.
    46  * [`textDocument/documentLink`]: Log errors, return nil result.
    47  * [`textDocument/publishDiagnostics`]: Log errors if there were any while computing diagnostics.
    48  * [`textDocument/references`]: Log errors, return empty result.
    49  * [`textDocument/rename`]: Return error if there was an error computing renames.
    50  * [`textDocument/signatureHelp`]: Log errors, return nil result.
    51  * [`textDocument/documentSymbols`]: Return error if there was an error computing document symbols.
    52  
    53  ## Watching files
    54  
    55  It is fairly normal for files that affect `gopls` to be modified outside of the editor it is associated with.
    56  
    57  For instance, files that are needed to do correct type checking are modified by switching branches in git, or updated by a code generator.
    58  
    59  Monitoring 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`].
    60  This is currently being added to gopls by a community member, and tracked in [#31553]
    61  
    62  [InitializeResult]: https://pkg.go.dev/golang.org/x/tools/gopls/internal/protocol#InitializeResult
    63  [ServerCapabilities]: https://pkg.go.dev/golang.org/x/tools/gopls/internal/protocol#ServerCapabilities
    64  [`golang.org/x/tools/gopls/internal/protocol`]: https://pkg.go.dev/golang.org/x/tools/internal/protocol#NewPoint
    65  
    66  [LSP specification]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/
    67  [lsp-response]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#response-message
    68  [initialize]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/#initialize
    69  [lsp-text-documents]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#text-documents
    70  [lsp-textedit]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textedit
    71  
    72  [`textDocument/codeAction`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_codeAction
    73  [`textDocument/completion`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_completion
    74  [`textDocument/definition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_definition
    75  [`textDocument/typeDefinition`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_typeDefinition
    76  [`textDocument/formatting`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_formatting
    77  [`textDocument/highlight`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_highlight
    78  [`textDocument/hover`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_hover
    79  [`textDocument/documentLink`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentLink
    80  [`textDocument/publishDiagnostics`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_publishDiagnostics
    81  [`textDocument/references`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_references
    82  [`textDocument/rename`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_rename
    83  [`textDocument/signatureHelp`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_signatureHelp
    84  [`textDocument/documentSymbols`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_documentSymbols
    85  [`workspace/didChangeWatchedFiles`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#workspace_didChangeWatchedFiles
    86  
    87  [#31080]: https://github.com/golang/go/issues/31080
    88  [#31553]: https://github.com/golang/go/issues/31553
    89  [#31526]: https://github.com/golang/go/issues/31526