Documentation

Overview

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

    Index

    Constants

    View Source
    const (
    	Go = FileKind(iota)
    	Mod
    	Sum
    )
    View Source
    const (
    	// ParseHeader specifies that the main package declaration and imports are needed.
    	// This is the mode used when attempting to examine the package graph structure.
    	ParseHeader = ParseMode(iota)
    
    	// ParseExported specifies that the public symbols are needed, but things like
    	// private symbols and function bodies are not.
    	// This mode is used for things where a package is being consumed only as a
    	// dependency.
    	ParseExported
    
    	// ParseFull specifies the full AST is needed.
    	// This is used for files of direct interest where the entire contents must
    	// be considered.
    	ParseFull
    )
    View Source
    const MaxDeepCompletions = 3

      Limit deep completion results because in most cases there are too many to be useful.

      Variables

      Functions

      func CandidateImports

      func CandidateImports(ctx context.Context, view View, filename string) (pkgs []imports.ImportFix, err error)

        AllImportsFixes formats f for each possible fix to the imports. In addition to returning the result of applying all edits, it returns a list of fixes that could be applied to the file, with the corresponding TextEdits that would be needed to apply that fix.

        func Completion

        func Completion(ctx context.Context, view View, f GoFile, pos protocol.Position, opts CompletionOptions) ([]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, view View, f GoFile, disabledAnalyses map[string]struct{}) (map[span.URI][]Diagnostic, error)

          func Format

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

            Format formats a file with a given range.

            func Highlight

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

            func Imports

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

              Imports formats a file using the goimports tool.

              func IsGenerated

              func IsGenerated(ctx context.Context, view View, uri span.URI) bool

              func ToProtocolEdits

              func ToProtocolEdits(m *protocol.ColumnMapper, edits []diff.TextEdit) ([]protocol.TextEdit, error)

              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(ctx context.Context) Session
                
                	// FileSet returns the shared fileset used by all files in the system.
                	FileSet() *token.FileSet
                
                	// TokenHandle returns a TokenHandle for the given file handle.
                	TokenHandle(fh FileHandle) TokenHandle
                
                	// ParseGoHandle returns a ParseGoHandle for the given file handle.
                	ParseGoHandle(fh FileHandle, mode ParseMode) ParseGoHandle
                }

                  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 CheckPackageHandle

                  type CheckPackageHandle interface {
                  	// ParseGoHandle returns a ParseGoHandle for which to get the package.
                  	Files() []ParseGoHandle
                  
                  	// Config is the *packages.Config that the package metadata was loaded with.
                  	Config() *packages.Config
                  
                  	// Check returns the type-checked Package for the CheckPackageHandle.
                  	Check(ctx context.Context) (Package, error)
                  
                  	// Cached returns the Package for the CheckPackageHandle if it has already been stored.
                  	Cached(ctx context.Context) (Package, error)
                  }

                    CheckPackageHandle represents a handle to a specific version of a package. It is uniquely defined by the file handles that make up the package.

                    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
                    
                    	// An optional array of additional TextEdits that are applied when
                    	// selecting this completion.
                    	//
                    	// Additional text edits should be used to change text unrelated to the current cursor position
                    	// (for example adding an import statement at the top of the file if the completion item will
                    	// insert an unqualified type).
                    	AdditionalTextEdits []protocol.TextEdit
                    
                    	// Depth is how many levels were searched to find this completion.
                    	// For example when completing "foo<>", "fooBar" is depth 0, and
                    	// "fooBar.Baz" is depth 1.
                    	Depth int
                    
                    	// Score is the internal relevance score.
                    	// A higher score indicates that this completion item is more relevant.
                    	Score float64
                    
                    	// Documentation is the documentation for the completion item.
                    	Documentation string
                    	// 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 CompletionOptions

                      type CompletionOptions struct {
                      	DeepComplete          bool
                      	WantDocumentaton      bool
                      	WantFullDocumentation bool
                      	WantUnimported        bool
                      }

                      type Diagnostic

                      type Diagnostic struct {
                      	URI      span.URI
                      	Range    protocol.Range
                      	Message  string
                      	Source   string
                      	Severity DiagnosticSeverity
                      
                      	SuggestedFixes []SuggestedFixes
                      }

                      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
                      	Handle(ctx context.Context) FileHandle
                      	FileSet() *token.FileSet
                      	GetToken(ctx context.Context) (*token.File, error)
                      }

                        File represents a source file of any type.

                        type FileHandle

                        type FileHandle interface {
                        	// FileSystem returns the file system this handle was acquired from.
                        	FileSystem() FileSystem
                        
                        	// Identity returns the FileIdentity for the file.
                        	Identity() FileIdentity
                        
                        	// Kind returns the FileKind for the file.
                        	Kind() FileKind
                        
                        	// Read reads the contents of a file and returns it along with its hash value.
                        	// If the file is not available, returns a nil slice and an error.
                        	Read(ctx context.Context) ([]byte, string, error)
                        }

                          FileHandle represents a handle to a specific version of a single file from a specific file system.

                          type FileIdentity

                          type FileIdentity struct {
                          	URI     span.URI
                          	Version string
                          }

                            FileIdentity uniquely identifies a file at a version from a FileSystem.

                            func (FileIdentity) String

                            func (identity FileIdentity) String() string

                            type FileKind

                            type FileKind int

                              FileKind describes the kind of the file in question. It can be one of Go, mod, or sum.

                              func DetectLanguage

                              func DetectLanguage(langID, filename string) FileKind

                              func (FileKind) String

                              func (k FileKind) String() string

                              type FileSystem

                              type FileSystem interface {
                              	// GetFile returns a handle for the specified file.
                              	GetFile(uri span.URI) FileHandle
                              }

                                FileSystem is the interface to something that provides file contents.

                                type GoFile

                                type GoFile interface {
                                	File
                                
                                	// GetAST returns the AST for the file, at or above the given mode.
                                	GetAST(ctx context.Context, mode ParseMode) (*ast.File, error)
                                
                                	// GetCachedPackage returns the cached package for the file, if any.
                                	GetCachedPackage(ctx context.Context) (Package, error)
                                
                                	// GetPackage returns the CheckPackageHandle for the package that this file belongs to.
                                	GetCheckPackageHandle(ctx context.Context) (CheckPackageHandle, error)
                                
                                	// GetPackages returns the CheckPackageHandles of the packages that this file belongs to.
                                	GetCheckPackageHandles(ctx context.Context) ([]CheckPackageHandle, error)
                                
                                	// GetPackage returns the CheckPackageHandle for the package that this file belongs to.
                                	GetPackage(ctx context.Context) (Package, error)
                                
                                	// GetPackages returns the CheckPackageHandles of the packages that this file belongs to.
                                	GetPackages(ctx context.Context) ([]Package, error)
                                
                                	// 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 HoverInformation

                                  type HoverInformation struct {
                                  	// Signature is the symbol's signature.
                                  	Signature string `json:"signature"`
                                  
                                  	// SingleLine is a single line describing the symbol.
                                  	// This is recommended only for use in clients that show a single line for hover.
                                  	SingleLine string `json:"singleLine"`
                                  
                                  	// Synopsis is a single sentence synopsis of the symbol's documentation.
                                  	Synopsis string `json:"synopsis"`
                                  
                                  	// FullDocumentation is the symbol's full documentation.
                                  	FullDocumentation string `json:"fullDocumentation"`
                                  	// contains filtered or unexported fields
                                  }

                                  type IdentifierInfo

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

                                    IdentifierInfo holds information about an identifier in Go source.

                                    func Identifier

                                    func Identifier(ctx context.Context, 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) DeclarationRange

                                      func (i *IdentifierInfo) DeclarationRange() span.Range

                                      func (*IdentifierInfo) Hover

                                      func (*IdentifierInfo) References

                                      func (i *IdentifierInfo) References(ctx context.Context) ([]*ReferenceInfo, error)

                                        References returns a list of references for a given identifier within the packages containing i.File. Declarations appear first in the result.

                                        func (*IdentifierInfo) Rename

                                        func (i *IdentifierInfo) Rename(ctx context.Context, newName string) (map[span.URI][]diff.TextEdit, error)

                                          Rename returns a map of TextEdits for each file modified when renaming a given identifier within a package.

                                          type ImportFix

                                          type ImportFix struct {
                                          	Fix   *imports.ImportFix
                                          	Edits []diff.TextEdit
                                          }

                                          func AllImportsFixes

                                          func AllImportsFixes(ctx context.Context, view View, f GoFile, rng span.Range) (edits []diff.TextEdit, editsPerFix []*ImportFix, err error)

                                            AllImportsFixes formats f for each possible fix to the imports. In addition to returning the result of applying all edits, it returns a list of fixes that could be applied to the file, with the corresponding TextEdits that would be needed to apply that fix.

                                            type ModFile

                                            type ModFile interface {
                                            	File
                                            }

                                            type Package

                                            type Package interface {
                                            	ID() string
                                            	PkgPath() string
                                            	GetHandles() []ParseGoHandle
                                            	GetSyntax(context.Context) []*ast.File
                                            	GetErrors() []packages.Error
                                            	GetTypes() *types.Package
                                            	GetTypesInfo() *types.Info
                                            	GetTypesSizes() types.Sizes
                                            	IsIllTyped() bool
                                            	GetDiagnostics() []Diagnostic
                                            	SetDiagnostics(diags []Diagnostic)
                                            
                                            	// GetImport returns the CheckPackageHandle for a package imported by this package.
                                            	GetImport(ctx context.Context, pkgPath string) (Package, error)
                                            
                                            	// GetActionGraph returns the action graph for the given package.
                                            	GetActionGraph(ctx context.Context, a *analysis.Analyzer) (*Action, error)
                                            }

                                              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 ParseGoHandle

                                              type ParseGoHandle interface {
                                              	// File returns a file handle for which to get the AST.
                                              	File() FileHandle
                                              
                                              	// Mode returns the parse mode of this handle.
                                              	Mode() ParseMode
                                              
                                              	// Parse returns the parsed AST for the file.
                                              	// If the file is not available, returns nil and an error.
                                              	Parse(ctx context.Context) (*ast.File, error)
                                              
                                              	// Cached returns the AST for this handle, if it has already been stored.
                                              	Cached(ctx context.Context) (*ast.File, error)
                                              }

                                                ParseGoHandle represents a handle to the AST for a file.

                                                type ParseMode

                                                type ParseMode int

                                                  ParseMode controls the content of the AST produced when parsing a source file.

                                                  type ReferenceInfo

                                                  type ReferenceInfo struct {
                                                  	Name  string
                                                  	Range span.Range
                                                  	// contains filtered or unexported fields
                                                  }

                                                    ReferenceInfo holds information about reference to an identifier in Go source.

                                                    type Selection

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

                                                      A Selection represents the cursor position and surrounding identifier.

                                                      func (Selection) Prefix

                                                      func (p Selection) Prefix() string

                                                      func (Selection) Range

                                                      func (s Selection) Range() (protocol.Range, error)

                                                      func (Selection) URI

                                                      func (s Selection) URI() span.URI

                                                      type Session

                                                      type Session interface {
                                                      	// NewView creates a new View and returns it.
                                                      	NewView(ctx context.Context, name string, folder span.URI) View
                                                      
                                                      	// Cache returns the cache that created this session.
                                                      	Cache() Cache
                                                      
                                                      	// 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(ctx context.Context, uri span.URI, kind FileKind, text []byte)
                                                      
                                                      	// 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) (wasFirstChange bool)
                                                      }

                                                        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, Documentation string
                                                        	Parameters           []ParameterInformation
                                                        	ActiveParameter      int
                                                        }

                                                        func SignatureHelp

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

                                                        type SuggestedFixes

                                                        type SuggestedFixes struct {
                                                        	Title string
                                                        	Edits []diff.TextEdit
                                                        }

                                                        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, error)

                                                        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 TokenHandle

                                                        type TokenHandle interface {
                                                        	// File returns a file handle for which to get the *token.File.
                                                        	File() FileHandle
                                                        
                                                        	// Token returns the *token.File for the file.
                                                        	Token(ctx context.Context) (*token.File, error)
                                                        }

                                                          TokenHandle represents a handle to the *token.File for a file.

                                                          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) (wasFirstChange bool, err 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
                                                          
                                                          	Config(ctx context.Context) *packages.Config
                                                          
                                                          	// RunProcessEnvFunc runs fn with the process env for this view inserted into opts.
                                                          	// Note: the process env contains cached module and filesystem state.
                                                          	RunProcessEnvFunc(ctx context.Context, fn func(*imports.Options) error, opts *imports.Options) error
                                                          }

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