lsp

Documentation

Overview

Package lsp is a minimal Language Server Protocol client speaking JSON-RPC over a server's stdio. It supports the handful of requests the editor needs: document sync, formatting, definition, hover, rename, and receiving diagnostics. Positions are 0-based; character offsets are treated as rune indices (an approximation of LSP's UTF-16 offsets, fine for BMP text).

Index

• func PathToURI(path string) string
• func URIToPath(uri string) string
• type CallHierarchyItem
• type Client
  • func Start(command []string, rootURI string, initOpts any, ...) (*Client, error)
  • func (c *Client) Call(method string, params any) (json.RawMessage, error)
  • func (c *Client) Close()
  • func (c *Client) CodeAction(uri string, rng Range, diags []Diagnostic, only []string) ([]CodeAction, error)
  • func (c *Client) Completion(uri string, pos Position) ([]CompletionItem, error)
  • func (c *Client) Definition(uri string, pos Position) ([]Location, error)
  • func (c *Client) DidChange(uri string, version int, text string)
  • func (c *Client) DidOpen(uri, languageID string, version int, text string)
  • func (c *Client) DocumentHighlight(uri string, pos Position) ([]Range, error)
  • func (c *Client) DocumentSymbols(uri string) ([]Symbol, error)
  • func (c *Client) ExecuteCommand(command string, args []json.RawMessage) error
  • func (c *Client) Formatting(uri string, tabSize int, insertSpaces bool) ([]TextEdit, error)
  • func (c *Client) Hover(uri string, pos Position) (string, error)
  • func (c *Client) Implementation(uri string, pos Position) ([]Location, error)
  • func (c *Client) IncomingCalls(item CallHierarchyItem) ([]Location, error)
  • func (c *Client) Notify(method string, params any) error
  • func (c *Client) OnApplyEdit(fn func(map[string][]TextEdit) bool)
  • func (c *Client) OutgoingCalls(item CallHierarchyItem) ([]Location, error)
  • func (c *Client) PrepareCallHierarchy(uri string, pos Position) ([]CallHierarchyItem, error)
  • func (c *Client) References(uri string, pos Position) ([]Location, error)
  • func (c *Client) Rename(uri string, pos Position, newName string) (map[string][]TextEdit, error)
  • func (c *Client) SignatureHelp(uri string, pos Position) (*SignatureHelp, error)
  • func (c *Client) TypeDefinition(uri string, pos Position) ([]Location, error)
  • func (c *Client) WorkspaceSymbols(query string) ([]Symbol, error)
• type CodeAction
• type Command
• type CompletionItem
• type Diagnostic
• type Location
• type Position
• type Range
• type SignatureHelp
• type SignatureInfo
• type Symbol
• type TextEdit
• type WorkspaceEdit
  • func (w *WorkspaceEdit) Flatten() map[string][]TextEdit

Functions

func PathToURI

func PathToURI(path string) string

PathToURI converts a filesystem path to a file:// URI.

func URIToPath

func URIToPath(uri string) string

URIToPath converts a file:// URI back to a filesystem path.

Types

type CallHierarchyItem

type CallHierarchyItem struct {
	Name           string `json:"name"`
	URI            string `json:"uri"`
	Range          Range  `json:"range"`
	SelectionRange Range  `json:"selectionRange"`
	// contains filtered or unexported fields
}

CallHierarchyItem identifies a callable in a call hierarchy. raw keeps the server's original object so it can be sent back verbatim (it may carry an opaque data field the server needs) to the incoming/outgoing-calls requests.

type Client

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

Client is a running language-server connection.

func Start

func Start(command []string, rootURI string, initOpts any, onDiag func(string, []Diagnostic)) (*Client, error)

Start launches command, performs the initialize handshake (passing initOpts as initializationOptions, e.g. gopls's {gofumpt: true}), and returns a ready client. onDiag is called (from an internal goroutine) for every published diagnostics notification.

func (*Client) Call

func (c *Client) Call(method string, params any) (json.RawMessage, error)

Call sends a request and blocks until the response arrives.

func (*Client) Close

func (c *Client) Close()

Close terminates the server process.

func (*Client) CodeAction

func (c *Client) CodeAction(uri string, rng Range, diags []Diagnostic, only []string) ([]CodeAction, error)

CodeAction requests the actions available for rng (quick-fixes, refactors, source actions), passing the overlapping diagnostics as context. only, when non-empty, restricts the result to those CodeActionKinds (e.g. "source.organizeImports"); nil requests all applicable actions.

func (*Client) Completion

func (c *Client) Completion(uri string, pos Position) ([]CompletionItem, error)

Completion returns the completion items at a position.

func (*Client) Definition

func (c *Client) Definition(uri string, pos Position) ([]Location, error)

Definition resolves the definition location(s) for a position.

func (*Client) DidChange

func (c *Client) DidChange(uri string, version int, text string)

DidChange sends a full-text document update.

func (*Client) DidOpen

func (c *Client) DidOpen(uri, languageID string, version int, text string)

DidOpen tells the server a document is now open.

func (*Client) DocumentHighlight

func (c *Client) DocumentHighlight(uri string, pos Position) ([]Range, error)

DocumentHighlight returns the ranges of the occurrences of the symbol at pos within the document (for highlighting all uses).

func (*Client) DocumentSymbols

func (c *Client) DocumentSymbols(uri string) ([]Symbol, error)

DocumentSymbols returns the symbols declared in a document (flattened).

func (*Client) ExecuteCommand

func (c *Client) ExecuteCommand(command string, args []json.RawMessage) error

ExecuteCommand runs a server command (workspace/executeCommand). The server may respond by sending workspace/applyEdit (see OnApplyEdit).

func (*Client) Formatting

func (c *Client) Formatting(uri string, tabSize int, insertSpaces bool) ([]TextEdit, error)

Formatting requests whole-document formatting edits.

func (*Client) Hover

func (c *Client) Hover(uri string, pos Position) (string, error)

Hover returns hover text for a position (markdown/plaintext flattened).

func (*Client) Implementation

func (c *Client) Implementation(uri string, pos Position) ([]Location, error)

Implementation resolves implementation location(s) for a position.

func (*Client) IncomingCalls

func (c *Client) IncomingCalls(item CallHierarchyItem) ([]Location, error)

IncomingCalls returns the call sites (caller locations) that call item.

func (*Client) Notify

func (c *Client) Notify(method string, params any) error

Notify sends a notification (no response expected).

func (*Client) OnApplyEdit

func (c *Client) OnApplyEdit(fn func(map[string][]TextEdit) bool)

OnApplyEdit registers the handler for server-initiated workspace/applyEdit requests (used by code-action commands that edit via executeCommand). It should apply the edit and report whether it succeeded.

func (*Client) OutgoingCalls

func (c *Client) OutgoingCalls(item CallHierarchyItem) ([]Location, error)

OutgoingCalls returns the callees invoked from item (their definitions).

func (*Client) PrepareCallHierarchy

func (c *Client) PrepareCallHierarchy(uri string, pos Position) ([]CallHierarchyItem, error)

PrepareCallHierarchy resolves the call-hierarchy item(s) at pos.

func (*Client) References

func (c *Client) References(uri string, pos Position) ([]Location, error)

References resolves all references to the symbol at pos (including its declaration).

func (*Client) Rename

func (c *Client) Rename(uri string, pos Position, newName string) (map[string][]TextEdit, error)

Rename requests a workspace edit renaming the symbol at pos to newName. It returns edits keyed by document URI.

func (*Client) SignatureHelp

func (c *Client) SignatureHelp(uri string, pos Position) (*SignatureHelp, error)

SignatureHelp resolves the signature help at pos. It returns nil (no error) when the server has nothing to show.

func (*Client) TypeDefinition

func (c *Client) TypeDefinition(uri string, pos Position) ([]Location, error)

TypeDefinition resolves the type-definition location(s) for a position.

func (*Client) WorkspaceSymbols

func (c *Client) WorkspaceSymbols(query string) ([]Symbol, error)

WorkspaceSymbols searches symbols across the workspace.

type CodeAction

type CodeAction struct {
	Title   string
	Kind    string
	Edit    *WorkspaceEdit
	Command *Command
}

CodeAction is a resolved code action: a title (and kind) plus an optional inline edit and/or a command to run via executeCommand.

type Command

type Command struct {
	Title     string            `json:"title"`
	Command   string            `json:"command"`
	Arguments []json.RawMessage `json:"arguments,omitempty"`
}

Command is an LSP command: a title, an identifier the server understands, and opaque arguments passed back verbatim to workspace/executeCommand.

type CompletionItem

type CompletionItem struct {
	Label      string `json:"label"`
	Detail     string `json:"detail"`
	InsertText string `json:"insertText"`
}

CompletionItem is one completion candidate.

type Diagnostic

type Diagnostic struct {
	Range    Range  `json:"range"`
	Severity int    `json:"severity"`
	Message  string `json:"message"`
}

Diagnostic is a problem reported by the server.

type Location

type Location struct {
	URI   string `json:"uri"`
	Range Range  `json:"range"`
}

Location is a range within a document.

type Position

type Position struct {
	Line      int `json:"line"`
	Character int `json:"character"`
}

Position is a 0-based line/character location.

type Range

type Range struct {
	Start Position `json:"start"`
	End   Position `json:"end"`
}

Range is a span between two positions.

type SignatureHelp

type SignatureHelp struct {
	Signatures      []SignatureInfo
	ActiveSignature int
	ActiveParameter int
}

SignatureHelp describes the signatures applicable at a call site, plus which one and which parameter are active.

type SignatureInfo

type SignatureInfo struct {
	Label      string
	Parameters []string
}

SignatureInfo is one candidate signature: its full label and its parameter labels (as strings; offset-form labels are dropped).

type Symbol

type Symbol struct {
	Name     string
	Kind     int
	Location Location
}

Symbol is a flattened document/workspace symbol.

type TextEdit

type TextEdit struct {
	Range   Range  `json:"range"`
	NewText string `json:"newText"`
}

TextEdit is a replacement of Range with NewText.

type WorkspaceEdit

type WorkspaceEdit struct {
	Changes         map[string][]TextEdit `json:"changes"`
	DocumentChanges []struct {
		TextDocument struct {
			URI string `json:"uri"`
		} `json:"textDocument"`
		Edits []TextEdit `json:"edits"`
	} `json:"documentChanges"`
}

WorkspaceEdit groups text edits either by document URI (changes) or as ordered documentChanges; Flatten reduces both to a uri→edits map.

func (*WorkspaceEdit) Flatten

func (w *WorkspaceEdit) Flatten() map[string][]TextEdit

Flatten returns the edit as a uri→edits map, from whichever form the server used.