goplsclient

Documentation

Overview

Package goplsclient runs `gopls` (1) in the background uses it to retrieve definitions of symbols and auto-complete.

How to use it:

1. Construct a `*Client` with `New()` It will start it, connect and initialize in the background.
2. Call the various services: currently only `Definition()`.
3. Cache of files that needed retrieving to access definitions.

`gopls` runs a [Language Server Protocol](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/) and it's tricky to get right. Much of the communication seems to be asynchronous (Notify messages) and lots are just dropped for now.

TODO: current implementation is as simple as it can be. No concurrency control is included.

(1) https://github.com/golang/tools/tree/master/gopls

Index

• Variables
• type Client
  • func New(dir string) *Client
  • func (c *Client) Address() string
  • func (c *Client) CallComplete(ctx context.Context, filePath string, line, col int) (items *lsp.CompletionList, err error)
  • func (c *Client) CallDefinition(ctx context.Context, filePath string, line, col int) (results []lsp.Location, err error)
  • func (c *Client) CallHover(ctx context.Context, filePath string, line, col int) (hover lsp.Hover, err error)
  • func (c *Client) Complete(ctx context.Context, filePath string, line, col int) (matches []string, replaceLength int, err error)
  • func (c *Client) ConnClose()
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) ConsumeMessages() []string
  • func (c *Client) Definition(ctx context.Context, filePath string, line, col int) (markdown string, err error)
  • func (c *Client) FileData(filePath string) (content *FileData, updated bool, err error)
  • func (c *Client) NotifyDidOpenOrChange(ctx context.Context, filePath string) (err error)
  • func (c *Client) SetAddress(address string)
  • func (c *Client) Shutdown()
  • func (c *Client) Span(loc lsp.Location) (string, error)
  • func (c *Client) Start() error
  • func (c *Client) Stop()
  • func (c *Client) WaitConnection(ctx context.Context) bool
• type FileData
• type Latch
  • func (l Latch) Enable()
  • func (l Latch) State() bool
  • func (l Latch) Wait()
  • func (l Latch) WaitTimeout(timeout time.Duration) bool

Variables

var (
	ConnectTimeout       = 2000 * time.Millisecond
	CommunicationTimeout = 500 * time.Millisecond
)

var StartTimeout = 5 * time.Second

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func New

func New(dir string) *Client

New returns a new Client in the directory. The returned Client does not yet start a `gopls` instance or connects to one. It should be followed by a call to `Start()` to start a new `gopls` or `Connect()` to connect to an existing `gopls` server.

• dir: directory to be monitored, typically where the `go.mod` of the project we are monitoring resides (assuming there are only one module of interest).

func (*Client) Address

func (c *Client) Address() string

Address used either to start `gopls` or to connect to it.

func (*Client) CallComplete

func (c *Client) CallComplete(ctx context.Context, filePath string, line, col int) (items *lsp.CompletionList, err error)

func (*Client) CallDefinition

func (c *Client) CallDefinition(ctx context.Context, filePath string, line, col int) (results []lsp.Location, err error)

CallDefinition service in `gopls`. This returns just the range of where a symbol, under the cursor, is defined. See `Definition()` for the full definition service.

This will automatically call NotifyDidOpenOrChange, if file hasn't been sent yet.

func (*Client) CallHover

func (c *Client) CallHover(ctx context.Context, filePath string, line, col int) (hover lsp.Hover, err error)

CallHover service in `gopls`. This returns stuff ... defined here: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover

Documentation was not very clear to me, but it's what gopls uses for Definition.

This will automatically call NotifyDidOpenOrChange, if file hasn't been sent yet.

func (*Client) Complete

func (c *Client) Complete(ctx context.Context, filePath string, line, col int) (matches []string, replaceLength int, err error)

Complete request auto-complete suggestions from `gopls`. It returns the text of the matches and the number of characters before the cursor position that should be replaced by the matches (the same value for every entry).

func (*Client) ConnClose

func (c *Client) ConnClose()

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connect to the `gopls` in address given by `c.Address()`. It also starts a goroutine to monitor receiving requests.

func (*Client) ConsumeMessages

func (c *Client) ConsumeMessages() []string

func (*Client) Definition

func (c *Client) Definition(ctx context.Context, filePath string, line, col int) (markdown string, err error)

Definition return the definition for the identifier at the given position, rendered in Markdown. It returns empty if position has no identifier.

func (*Client) FileData

func (c *Client) FileData(filePath string) (content *FileData, updated bool, err error)

FileData retrieves the file data, including its contents. It uses a cache system, so files don't need to be reloaded.

func (*Client) NotifyDidOpenOrChange

func (c *Client) NotifyDidOpenOrChange(ctx context.Context, filePath string) (err error)

NotifyDidOpenOrChange sends a notification to `gopls` with the open file, which also sends the file content (from `Client.fileCache` if available). File version sent is incremented.

func (*Client) SetAddress

func (c *Client) SetAddress(address string)

SetAddress to be used either to start `gopls` or to connect to it. If the address is empty, it defaults to a unix socket configured as `dir+"/gopls_socket".

This may have no effect if `gopls` is already started or connectingLatch to.

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown closes connection and stops `gopls` (if connectingLatch/started).

func (*Client) Span

func (c *Client) Span(loc lsp.Location) (string, error)

Span returns the text spanning the given location (`lsp.Location` represents a range).

func (*Client) Start

func (c *Client) Start() error

Start `gopls` as a server, on `Client.Address()` port. It is started asynchronously (so `Start()` returns immediately) and is followed up by automatically connecting to it.

While it is not started the various services return empty results.

func (*Client) Stop

func (c *Client) Stop()

Stop current `gopls` execution.

func (*Client) WaitConnection

func (c *Client) WaitConnection(ctx context.Context) bool

WaitConnection checks whether connection is up, and if not tries connecting. Returns true if good to proceed.

type FileData

type FileData struct {
	Path        string
	URI         uri.URI
	Content     string
	ContentTime time.Time
	LineStarts  []int
}

FileData holds information about the contents of a file. It's built by `Client.FileContents`.

type Latch

type Latch chan struct{}

Latch based on channels, that can be waited/selected on. It's considered enabled (or "on") if channel is closed.

func (Latch) Enable

func (l Latch) Enable()

Enable latch, triggering anyone waiting for it. It closes the underlying channel.

func (Latch) State

func (l Latch) State() bool

State return true if Latch is enabled (channel closed).

func (Latch) Wait

func (l Latch) Wait()

Wait waits until latch is enabled.

func (Latch) WaitTimeout

func (l Latch) WaitTimeout(timeout time.Duration) bool

WaitTimeout returns true if latch was enabled. If timeout is expired, returns false.