Documentation
¶
Overview ¶
Package lsp serves the Language Server Protocol over a TDL model being edited: what is wrong with a file, where a name under the cursor was declared, what it is, the file's outline, and its canonical form.
It is private for the reason internal/sema is. `ir` and `proto` are the compatibility surface, and an editor integration is not.
See docs/design/lsp.md for the reasoning and docs/design/lsp-plan.md for what each phase adds.
Index ¶
- func Serve(ctx context.Context, rwc io.ReadWriteCloser, opts ...sema.Option) error
- type Server
- func (s *Server) Definition(_ context.Context, params *protocol.DefinitionParams) (protocol.DefinitionResult, error)
- func (s *Server) DidChange(ctx context.Context, params *protocol.DidChangeTextDocumentParams) error
- func (s *Server) DidClose(ctx context.Context, params *protocol.DidCloseTextDocumentParams) error
- func (s *Server) DidOpen(ctx context.Context, params *protocol.DidOpenTextDocumentParams) error
- func (s *Server) DidSave(ctx context.Context, params *protocol.DidSaveTextDocumentParams) error
- func (s *Server) DocumentSymbol(_ context.Context, params *protocol.DocumentSymbolParams) (protocol.DocumentSymbolResult, error)
- func (s *Server) Exit(context.Context) error
- func (s *Server) Formatting(_ context.Context, params *protocol.DocumentFormattingParams) ([]protocol.TextEdit, error)
- func (s *Server) Hover(_ context.Context, params *protocol.HoverParams) (*protocol.Hover, error)
- func (s *Server) Initialize(context.Context, *protocol.InitializeParams) (*protocol.InitializeResult, error)
- func (s *Server) Initialized(context.Context, *protocol.InitializedParams) error
- func (s *Server) SetTrace(context.Context, *protocol.SetTraceParams) error
- func (s *Server) Shutdown(context.Context) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
Serve runs a server over one connection and returns when it ends.
The connection is built by protocol.NewServer rather than by hand, because the codec it installs is what decodes a union-typed parameter and is not exported to be installed separately. It puts the client in the context every request is answered under, which is where this server reads the one it publishes to.
Nothing is logged. Anything written to stdout on a stdio server corrupts the stream, and a library that logs by default is a library that will.
Types ¶
type Server ¶
type Server struct {
protocol.UnimplementedServer
// contains filtered or unexported fields
}
Server answers protocol requests about the documents an editor has open.
It embeds protocol.UnimplementedServer, so a request it does not serve is answered with "method not found" rather than with a panic, and adding a feature is writing the method for it.
func NewServer ¶
NewServer returns a server.
The client it publishes to comes from each request's context rather than from a field, which is how protocol.NewServer hands one over: the connection exists before the client dispatching across it, and the server exists before the connection.
opts are the lowering options every document is analyzed with, which is how a caller replaces the prelude. The loader is not among them: the server supplies its own, so an open document's unsaved text is what an import of it resolves to.
func (*Server) Definition ¶
func (s *Server) Definition(_ context.Context, params *protocol.DefinitionParams) (protocol.DefinitionResult, error)
Definition answers where the name under the cursor was declared.
The answer comes from the index internal/sema records while it resolves, so shadowing, the prelude, and `_` imports are decided by the code that already decides them and are not restated here.
Three cases return nothing, and all three are an answer rather than a failure: the cursor is not on a name, the name did not resolve, or it resolved into the prelude, which is embedded and has no file an editor can open. docs/design/lsp.md argues the last one.
func (*Server) DidChange ¶
DidChange replaces a document's text and re-analyzes it.
Synchronization is full, so the last change carries the whole document, which is the arm of the change union this reads. A range change is a thing the server never advertised, and applying one as whole text would replace the document with a fragment of itself.
A change for a file that was never opened is dropped: the editor and the server disagree about what is open, and guessing at the text is worse than reporting nothing until the next didOpen.
func (*Server) DidClose ¶
DidClose forgets a document and clears what it published.
An import of it reads the disk from here, so every other open document is re-analyzed: one of them may import this file and have been resolving it against text that is no longer the server's to know.
func (*Server) DidSave ¶
DidSave re-analyzes, because a file this document imports may have been written by something other than the editor.
func (*Server) DocumentSymbol ¶
func (s *Server) DocumentSymbol(_ context.Context, params *protocol.DocumentSymbolParams) (protocol.DocumentSymbolResult, error)
DocumentSymbol is the outline of a document: each declaration, with its fields and variants as children, and a variant's fields under it.
It reads the tree rather than the model, so a file that does not parse still outlines whatever the parser recovered.
func (*Server) Formatting ¶
func (s *Server) Formatting(_ context.Context, params *protocol.DocumentFormattingParams) ([]protocol.TextEdit, error)
Formatting is `tdl fmt` over the editor's text, returned as one edit replacing the whole document.
The formatter owns layout entirely, so the client's tab size and whitespace preferences are not read: formatting in an editor has to produce what `tdl fmt --check` accepts.
A file that does not parse is left alone. The tree has holes in it, and printing one would delete whatever the parser could not read.
func (*Server) Hover ¶
Hover describes the name under the cursor: the declaration it refers to in canonical form, its deprecation, and its doc comment.
A name that refers to something is answered from the index definition reads, so the two cannot disagree about what a name means. The name a declaration declares is not a reference, so it is found in the tree.
A reference into the prelude hovers, which is the answer docs/design/lsp.md gives for a declaration with no file to jump to: the prelude is embedded, and its source is here to print.
func (*Server) Initialize ¶
func (s *Server) Initialize(context.Context, *protocol.InitializeParams) (*protocol.InitializeResult, error)
Initialize reports what this server serves.
Text synchronization is full rather than incremental. A .tdl file is a description of a domain model, the parser is one pass over it, and incremental sync would save nothing worth measuring while adding a second way for the server's copy of the text to drift from the editor's.
Source Files