Documentation

Overview

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

    Index

    Constants

    View Source
    const (
    	NoDocumentation = HoverKind(iota)
    	SynopsisDocumentation
    	FullDocumentation
    )
    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
    )

    Variables

    Functions

    func Completion

    func Completion(ctx context.Context, view View, f GoFile, pos token.Pos, 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 EditsToDiff

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

      func Highlight

      func Highlight(ctx context.Context, f GoFile, pos token.Pos) ([]span.Span, 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
        
        	// Token returns a TokenHandle for the given file handle.
        	TokenHandle(FileHandle) TokenHandle
        
        	// ParseGo returns a ParseGoHandle for the given file handle.
        	ParseGoHandle(FileHandle, 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 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
          
          	// 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
            }

            type Diagnostic

            type Diagnostic struct {
            	span.Span
            	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.

                  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 full AST for the file.
                      	GetAST(ctx context.Context, mode ParseMode) (*ast.File, error)
                      
                      	// GetPackage returns the package that this file belongs to.
                      	GetPackage(ctx context.Context) Package
                      
                      	// GetPackages returns all of the packages that this file belongs to.
                      	GetPackages(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 HoverKind

                        type HoverKind int

                        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, view 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) DeclarationRange

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

                            func (*IdentifierInfo) Documentation

                            func (i *IdentifierInfo) Documentation(ctx context.Context, hoverKind HoverKind) (string, error)

                            func (*IdentifierInfo) Hover

                            func (i *IdentifierInfo) Hover(ctx context.Context, markdownSupported bool, hoverKind HoverKind) (string, error)

                            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][]TextEdit, error)

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

                                type ModFile

                                type ModFile interface {
                                	File
                                }

                                type Package

                                type Package interface {
                                	ID() string
                                	PkgPath() string
                                	GetFilenames() []string
                                	GetSyntax(context.Context) []*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
                                	GetDiagnostics() []Diagnostic
                                	SetDiagnostics(diags []Diagnostic)
                                }

                                  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)
                                  }

                                    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 {
                                        	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(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)
                                          }

                                            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 []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 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, view View, f GoFile, rng span.Range) ([]TextEdit, error)

                                                    Imports formats a file using the goimports tool.

                                                    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) 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
                                                      
                                                      	// Process returns the process for this view.
                                                      	// Note: this contains cached module and filesystem state, which must
                                                      	// be invalidated after a 'go.mod' change.
                                                      	//
                                                      	// TODO(suzmue): the state cached in the process env is specific to each view,
                                                      	// however, there is state that can be shared between views that is not currently
                                                      	// cached, like the module cache.
                                                      	ProcessEnv(ctx context.Context) *imports.ProcessEnv
                                                      }

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