source

Documentation

Overview

Package source provides core features for use by Go editors and tools.

Index

• func Completion(ctx context.Context, f GoFile, pos token.Pos) ([]CompletionItem, *Selection, error)
• func Diagnostics(ctx context.Context, v View, f GoFile) (map[span.URI][]Diagnostic, error)
• func EditsToDiff(edits []TextEdit) []*diff.Op
• func Highlight(ctx context.Context, f GoFile, pos token.Pos) []span.Span
• type Action
  • func (act *Action) String() string
• type Cache
• type CompletionItem
  • func (i *CompletionItem) Snippet(usePlaceholders bool) string
• type CompletionItemKind
  • func ParseCompletionItemKind(s string) CompletionItemKind
  • func (e CompletionItemKind) Format(f fmt.State, c rune)
• type Diagnostic
• type DiagnosticSeverity
  • func ParseDiagnosticSeverity(s string) DiagnosticSeverity
  • func (e DiagnosticSeverity) Format(f fmt.State, c rune)
• type File
• type FileContent
• type FileSystem
• type GoFile
• type IdentifierInfo
  • func Identifier(ctx context.Context, v View, f GoFile, pos token.Pos) (*IdentifierInfo, error)
  • func (i *IdentifierInfo) Hover(ctx context.Context, qf types.Qualifier, markdownSupported, wantComments bool) (string, error)
• type ModFile
• type Package
• type ParameterInformation
• type Selection
  • func (p Selection) Prefix() string
• type Session
• type SignatureInformation
  • func SignatureHelp(ctx context.Context, f GoFile, pos token.Pos) (*SignatureInformation, error)
• type SumFile
• type Symbol
  • func DocumentSymbols(ctx context.Context, f GoFile) []Symbol
• type SymbolKind
  • func ParseSymbolKind(s string) SymbolKind
  • func (e SymbolKind) Format(f fmt.State, c rune)
• type TextEdit
  • func DiffToEdits(uri span.URI, ops []*diff.Op) []TextEdit
  • func Format(ctx context.Context, f GoFile, rng span.Range) ([]TextEdit, error)
  • func Imports(ctx context.Context, f GoFile, rng span.Range) ([]TextEdit, error)
• type View

Functions

func Completion

func Completion(ctx context.Context, f GoFile, pos token.Pos) ([]CompletionItem, *Selection, error)

Completion returns a list of possible candidates for completion, given a a file and a position.

The selection is computed based on the preceding identifier and can be used by the client to score the quality of the completion. For instance, some clients may tolerate imperfect matches as valid completion results, since users may make typos.

func Diagnostics

func Diagnostics(ctx context.Context, v View, f GoFile) (map[span.URI][]Diagnostic, error)

func EditsToDiff

func EditsToDiff(edits []TextEdit) []*diff.Op

func Highlight

func Highlight(ctx context.Context, f GoFile, pos token.Pos) []span.Span

Types

type Action

type Action struct {
	Analyzer *analysis.Analyzer
	Pkg      Package
	Deps     []*Action
	// contains filtered or unexported fields
}

An action represents one unit of analysis work: the application of one analysis to one package. Actions form a DAG, both within a package (as different analyzers are applied, either in sequence or parallel), and across packages (as dependencies are analyzed).

func (*Action) String

func (act *Action) String() string

type Cache

type Cache interface {
	// A FileSystem that reads file contents from external storage.
	FileSystem

	// NewSession creates a new Session manager and returns it.
	NewSession(log xlog.Logger) Session

	// FileSet returns the shared fileset used by all files in the system.
	FileSet() *token.FileSet
}

Cache abstracts the core logic of dealing with the environment from the higher level logic that processes the information to produce results. The cache provides access to files and their contents, so the source package does not directly access the file system. A single cache is intended to be process wide, and is the primary point of sharing between all consumers. A cache may have many active sessions at any given time.

type CompletionItem

type CompletionItem struct {
	// Label is the primary text the user sees for this completion item.
	Label string

	// Detail is supplemental information to present to the user.
	// This often contains the type or return type of the completion item.
	Detail string

	// InsertText is the text to insert if this item is selected.
	// Any of the prefix that has already been typed is not trimmed.
	// The insert text does not contain snippets.
	InsertText string

	Kind CompletionItemKind

	// Score is the internal relevance score.
	// A higher score indicates that this completion item is more relevant.
	Score float64
	// contains filtered or unexported fields
}

func (*CompletionItem) Snippet

func (i *CompletionItem) Snippet(usePlaceholders bool) string

Snippet is a convenience function that determines the snippet that should be used for an item, depending on if the callee wants placeholders or not.

type CompletionItemKind

type CompletionItemKind int

const (
	Unknown CompletionItemKind = iota
	InterfaceCompletionItem
	StructCompletionItem
	TypeCompletionItem
	ConstantCompletionItem
	FieldCompletionItem
	ParameterCompletionItem
	VariableCompletionItem
	FunctionCompletionItem
	MethodCompletionItem
	PackageCompletionItem
)

func ParseCompletionItemKind

func ParseCompletionItemKind(s string) CompletionItemKind

func (CompletionItemKind) Format

func (e CompletionItemKind) Format(f fmt.State, c rune)

type Diagnostic

type Diagnostic struct {
	span.Span
	Message  string
	Source   string
	Severity DiagnosticSeverity
}

type DiagnosticSeverity

type DiagnosticSeverity int

const (
	SeverityWarning DiagnosticSeverity = iota
	SeverityError
)

func ParseDiagnosticSeverity

func ParseDiagnosticSeverity(s string) DiagnosticSeverity

func (DiagnosticSeverity) Format

func (e DiagnosticSeverity) Format(f fmt.State, c rune)

type File

type File interface {
	URI() span.URI
	View() View
	Content(ctx context.Context) *FileContent
	FileSet() *token.FileSet
	GetToken(ctx context.Context) *token.File
}

File represents a source file of any type.

type FileContent

type FileContent struct {
	URI   span.URI
	Data  []byte
	Error error
	Hash  string
}

FileContents is returned from FileSystem implementation to represent the contents of a file.

type FileSystem

type FileSystem interface {
	// ReadFile reads the contents of a file and returns it.
	ReadFile(uri span.URI) *FileContent
}

FileSystem is the interface to something that provides file contents.

type GoFile

type GoFile interface {
	File

	// GetTrimmedAST returns an AST that may or may not contain function bodies.
	// It should be used in scenarios where function bodies are not necessary.
	GetTrimmedAST(ctx context.Context) *ast.File

	// GetAST returns the full AST for the file.
	GetAST(ctx context.Context) *ast.File

	// GetPackage returns the package that this file belongs to.
	GetPackage(ctx context.Context) Package

	// GetActiveReverseDeps returns the active files belonging to the reverse
	// dependencies of this file's package.
	GetActiveReverseDeps(ctx context.Context) []GoFile
}

GoFile represents a Go source file that has been type-checked.

type IdentifierInfo

type IdentifierInfo struct {
	Name  string
	Range span.Range
	File  GoFile
	Type  struct {
		Range  span.Range
		Object types.Object
	}
	Declaration struct {
		Range  span.Range
		Node   ast.Node
		Object types.Object
	}
	// contains filtered or unexported fields
}

IdentifierInfo holds information about an identifier in Go source.

func Identifier

func Identifier(ctx context.Context, v View, f GoFile, pos token.Pos) (*IdentifierInfo, error)

Identifier returns identifier information for a position in a file, accounting for a potentially incomplete selector.

func (*IdentifierInfo) Hover

func (i *IdentifierInfo) Hover(ctx context.Context, qf types.Qualifier, markdownSupported, wantComments bool) (string, error)

type ModFile

type ModFile interface {
	File
}

type Package

type Package interface {
	PkgPath() string
	GetFilenames() []string
	GetSyntax() []*ast.File
	GetErrors() []packages.Error
	GetTypes() *types.Package
	GetTypesInfo() *types.Info
	GetTypesSizes() types.Sizes
	IsIllTyped() bool
	GetActionGraph(ctx context.Context, a *analysis.Analyzer) (*Action, error)
	GetImport(pkgPath string) Package
}

Package represents a Go package that has been type-checked. It maintains only the relevant fields of a *go/packages.Package.

type ParameterInformation

type ParameterInformation struct {
	Label string
}

type Selection

type Selection struct {
	Content string
	Range   span.Range
	Cursor  token.Pos
}

A Selection represents the cursor position and surrounding identifier.

func (Selection) Prefix

func (p Selection) Prefix() string

type Session

type Session interface {
	// NewView creates a new View and returns it.
	NewView(name string, folder span.URI) View

	// Cache returns the cache that created this session.
	Cache() Cache

	// Returns the logger in use for this session.
	Logger() xlog.Logger

	// View returns a view with a mathing name, if the session has one.
	View(name string) View

	// ViewOf returns a view corresponding to the given URI.
	ViewOf(uri span.URI) View

	// Views returns the set of active views built by this session.
	Views() []View

	// Shutdown the session and all views it has created.
	Shutdown(ctx context.Context)

	// A FileSystem prefers the contents from overlays, and falls back to the
	// content from the underlying cache if no overlay is present.
	FileSystem

	// DidOpen is invoked each time a file is opened in the editor.
	DidOpen(uri span.URI)

	// DidSave is invoked each time an open file is saved in the editor.
	DidSave(uri span.URI)

	// DidClose is invoked each time an open file is closed in the editor.
	DidClose(uri span.URI)

	// IsOpen can be called to check if the editor has a file currently open.
	IsOpen(uri span.URI) bool

	// Called to set the effective contents of a file from this session.
	SetOverlay(uri span.URI, data []byte)
}

Session represents a single connection from a client. This is the level at which things like open files are maintained on behalf of the client. A session may have many active views at any given time.

type SignatureInformation

type SignatureInformation struct {
	Label           string
	Parameters      []ParameterInformation
	ActiveParameter int
}

func SignatureHelp

func SignatureHelp(ctx context.Context, f GoFile, pos token.Pos) (*SignatureInformation, error)

type SumFile

type SumFile interface {
	File
}

type Symbol

type Symbol struct {
	Name          string
	Detail        string
	Span          span.Span
	SelectionSpan span.Span
	Kind          SymbolKind
	Children      []Symbol
}

func DocumentSymbols

func DocumentSymbols(ctx context.Context, f GoFile) []Symbol

type SymbolKind

type SymbolKind int

const (
	PackageSymbol SymbolKind = iota
	StructSymbol
	VariableSymbol
	ConstantSymbol
	FunctionSymbol
	MethodSymbol
	InterfaceSymbol
	NumberSymbol
	StringSymbol
	BooleanSymbol
	FieldSymbol
)

func ParseSymbolKind

func ParseSymbolKind(s string) SymbolKind

func (SymbolKind) Format

func (e SymbolKind) Format(f fmt.State, c rune)

type TextEdit

type TextEdit struct {
	Span    span.Span
	NewText string
}

TextEdit represents a change to a section of a document. The text within the specified span should be replaced by the supplied new text.

func DiffToEdits

func DiffToEdits(uri span.URI, ops []*diff.Op) []TextEdit

DiffToEdits converts from a sequence of diff operations to a sequence of source.TextEdit

func Format

func Format(ctx context.Context, f GoFile, rng span.Range) ([]TextEdit, error)

Format formats a file with a given range.

func Imports

func Imports(ctx context.Context, f GoFile, rng span.Range) ([]TextEdit, error)

Imports formats a file using the goimports tool.

type View

type View interface {
	// Session returns the session that created this view.
	Session() Session

	// Name returns the name this view was constructed with.
	Name() string

	// Folder returns the root folder for this view.
	Folder() span.URI

	// BuiltinPackage returns the ast for the special "builtin" package.
	BuiltinPackage() *ast.Package

	// GetFile returns the file object for a given uri.
	GetFile(ctx context.Context, uri span.URI) (File, error)

	// Called to set the effective contents of a file from this view.
	SetContent(ctx context.Context, uri span.URI, content []byte) error

	// BackgroundContext returns a context used for all background processing
	// on behalf of this view.
	BackgroundContext() context.Context

	// Env returns the current set of environment overrides on this view.
	Env() []string

	// SetEnv is used to adjust the environment applied to the view.
	SetEnv([]string)

	// SetBuildFlags is used to adjust the build flags applied to the view.
	SetBuildFlags([]string)

	// Shutdown closes this view, and detaches it from it's session.
	Shutdown(ctx context.Context)

	// Ignore returns true if this file should be ignored by this view.
	Ignore(span.URI) bool
}

View represents a single workspace. This is the level at which we maintain configuration like working directory and build tags.