command

package
v0.15.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 12, 2024 License: BSD-3-Clause Imports: 5 Imported by: 0

Documentation

Overview

Package command defines the interface provided by gopls for the workspace/executeCommand LSP request.

This interface is fully specified by the Interface type, provided it conforms to the restrictions outlined in its doc string.

Bindings for server-side command dispatch and client-side serialization are also provided by this package, via code generation.

Index

Constants

This section is empty.

Variables

Functions

func Dispatch

func Dispatch(ctx context.Context, params *protocol.ExecuteCommandParams, s Interface) (interface{}, error)

func ID

func ID(name string) string

ID returns the command name for use in the LSP.

func MarshalArgs

func MarshalArgs(args ...interface{}) ([]json.RawMessage, error)

MarshalArgs encodes the given arguments to json.RawMessages. This function is used to construct arguments to a protocol.Command.

Example usage:

jsonArgs, err := MarshalArgs(1, "hello", true, StructuredArg{42, 12.6})

func NewAddDependencyCommand

func NewAddDependencyCommand(title string, a0 DependencyArgs) (protocol.Command, error)

func NewAddImportCommand

func NewAddImportCommand(title string, a0 AddImportArgs) (protocol.Command, error)

func NewAddTelemetryCountersCommand

func NewAddTelemetryCountersCommand(title string, a0 AddTelemetryCountersArgs) (protocol.Command, error)

func NewApplyFixCommand

func NewApplyFixCommand(title string, a0 ApplyFixArgs) (protocol.Command, error)

func NewChangeSignatureCommand

func NewChangeSignatureCommand(title string, a0 ChangeSignatureArgs) (protocol.Command, error)

func NewCheckUpgradesCommand

func NewCheckUpgradesCommand(title string, a0 CheckUpgradesArgs) (protocol.Command, error)

func NewDiagnoseFilesCommand

func NewDiagnoseFilesCommand(title string, a0 DiagnoseFilesArgs) (protocol.Command, error)

func NewEditGoDirectiveCommand

func NewEditGoDirectiveCommand(title string, a0 EditGoDirectiveArgs) (protocol.Command, error)

func NewFetchVulncheckResultCommand

func NewFetchVulncheckResultCommand(title string, a0 URIArg) (protocol.Command, error)

func NewGCDetailsCommand

func NewGCDetailsCommand(title string, a0 protocol.DocumentURI) (protocol.Command, error)

func NewGenerateCommand

func NewGenerateCommand(title string, a0 GenerateArgs) (protocol.Command, error)

func NewGoGetPackageCommand

func NewGoGetPackageCommand(title string, a0 GoGetPackageArgs) (protocol.Command, error)

func NewListImportsCommand

func NewListImportsCommand(title string, a0 URIArg) (protocol.Command, error)

func NewListKnownPackagesCommand

func NewListKnownPackagesCommand(title string, a0 URIArg) (protocol.Command, error)

func NewMaybePromptForTelemetryCommand

func NewMaybePromptForTelemetryCommand(title string) (protocol.Command, error)

func NewMemStatsCommand

func NewMemStatsCommand(title string) (protocol.Command, error)

func NewRegenerateCgoCommand

func NewRegenerateCgoCommand(title string, a0 URIArg) (protocol.Command, error)

func NewRemoveDependencyCommand

func NewRemoveDependencyCommand(title string, a0 RemoveDependencyArgs) (protocol.Command, error)

func NewResetGoModDiagnosticsCommand

func NewResetGoModDiagnosticsCommand(title string, a0 ResetGoModDiagnosticsArgs) (protocol.Command, error)

func NewRunGoWorkCommandCommand

func NewRunGoWorkCommandCommand(title string, a0 RunGoWorkArgs) (protocol.Command, error)

func NewRunGovulncheckCommand

func NewRunGovulncheckCommand(title string, a0 VulncheckArgs) (protocol.Command, error)

func NewRunTestsCommand

func NewRunTestsCommand(title string, a0 RunTestsArgs) (protocol.Command, error)

func NewStartDebuggingCommand

func NewStartDebuggingCommand(title string, a0 DebuggingArgs) (protocol.Command, error)

func NewStartProfileCommand

func NewStartProfileCommand(title string, a0 StartProfileArgs) (protocol.Command, error)

func NewStopProfileCommand

func NewStopProfileCommand(title string, a0 StopProfileArgs) (protocol.Command, error)

func NewTestCommand

func NewTestCommand(title string, a0 protocol.DocumentURI, a1 []string, a2 []string) (protocol.Command, error)

func NewTidyCommand

func NewTidyCommand(title string, a0 URIArgs) (protocol.Command, error)

func NewToggleGCDetailsCommand

func NewToggleGCDetailsCommand(title string, a0 URIArg) (protocol.Command, error)

func NewUpdateGoSumCommand

func NewUpdateGoSumCommand(title string, a0 URIArgs) (protocol.Command, error)

func NewUpgradeDependencyCommand

func NewUpgradeDependencyCommand(title string, a0 DependencyArgs) (protocol.Command, error)

func NewVendorCommand

func NewVendorCommand(title string, a0 URIArg) (protocol.Command, error)

func NewViewsCommand

func NewViewsCommand(title string) (protocol.Command, error)

func NewWorkspaceStatsCommand

func NewWorkspaceStatsCommand(title string) (protocol.Command, error)

func UnmarshalArgs

func UnmarshalArgs(jsonArgs []json.RawMessage, args ...interface{}) error

UnmarshalArgs decodes the given json.RawMessages to the variables provided by args. Each element of args should be a pointer.

Example usage:

var (
    num int
    str string
    bul bool
    structured StructuredArg
)
err := UnmarshalArgs(args, &num, &str, &bul, &structured)

Types

type AddImportArgs

type AddImportArgs struct {
	// ImportPath is the target import path that should
	// be added to the URI file
	ImportPath string
	// URI is the file that the ImportPath should be
	// added to
	URI protocol.DocumentURI
}

type AddTelemetryCountersArgs

type AddTelemetryCountersArgs struct {
	// Names and Values must have the same length.
	Names  []string // Name of counters.
	Values []int64  // Values added to the corresponding counters. Must be non-negative.
}

AddTelemetryCountersArgs holds the arguments to the AddCounters command that updates the telemetry counters.

type ApplyFixArgs

type ApplyFixArgs struct {
	// The name of the fix to apply.
	//
	// For fixes suggested by analyzers, this is a string constant
	// advertised by the analyzer that matches the Category of
	// the analysis.Diagnostic with a SuggestedFix containing no edits.
	//
	// For fixes suggested by code actions, this is a string agreed
	// upon by the code action and golang.ApplyFix.
	Fix string

	// The file URI for the document to fix.
	URI protocol.DocumentURI
	// The document range to scan for fixes.
	Range protocol.Range
	// Whether to resolve and return the edits.
	ResolveEdits bool
}

type CallStack

type CallStack []StackEntry

CallStack models a trace of function calls starting with a client function or method and ending with a call to a vulnerable symbol.

type ChangeSignatureArgs

type ChangeSignatureArgs struct {
	RemoveParameter protocol.Location
	// Whether to resolve and return the edits.
	ResolveEdits bool
}

ChangeSignatureArgs specifies a "change signature" refactoring to perform.

type CheckUpgradesArgs

type CheckUpgradesArgs struct {
	// The go.mod file URI.
	URI protocol.DocumentURI
	// The modules to check.
	Modules []string
}

type Command

type Command string
const (
	AddDependency           Command = "add_dependency"
	AddImport               Command = "add_import"
	AddTelemetryCounters    Command = "add_telemetry_counters"
	ApplyFix                Command = "apply_fix"
	ChangeSignature         Command = "change_signature"
	CheckUpgrades           Command = "check_upgrades"
	DiagnoseFiles           Command = "diagnose_files"
	EditGoDirective         Command = "edit_go_directive"
	FetchVulncheckResult    Command = "fetch_vulncheck_result"
	GCDetails               Command = "gc_details"
	Generate                Command = "generate"
	GoGetPackage            Command = "go_get_package"
	ListImports             Command = "list_imports"
	ListKnownPackages       Command = "list_known_packages"
	MaybePromptForTelemetry Command = "maybe_prompt_for_telemetry"
	MemStats                Command = "mem_stats"
	RegenerateCgo           Command = "regenerate_cgo"
	RemoveDependency        Command = "remove_dependency"
	ResetGoModDiagnostics   Command = "reset_go_mod_diagnostics"
	RunGoWorkCommand        Command = "run_go_work_command"
	RunGovulncheck          Command = "run_govulncheck"
	RunTests                Command = "run_tests"
	StartDebugging          Command = "start_debugging"
	StartProfile            Command = "start_profile"
	StopProfile             Command = "stop_profile"
	Test                    Command = "test"
	Tidy                    Command = "tidy"
	ToggleGCDetails         Command = "toggle_gc_details"
	UpdateGoSum             Command = "update_go_sum"
	UpgradeDependency       Command = "upgrade_dependency"
	Vendor                  Command = "vendor"
	Views                   Command = "views"
	WorkspaceStats          Command = "workspace_stats"
)

Symbolic names for gopls commands, excluding "gopls." prefix. These commands may be requested by ExecuteCommand, CodeLens, CodeAction, and other LSP requests.

func (Command) ID

func (c Command) ID() string

ID returns the command identifier to use in the executeCommand request.

type DebuggingArgs

type DebuggingArgs struct {
	// Optional: the address (including port) for the debug server to listen on.
	// If not provided, the debug server will bind to "localhost:0", and the
	// full debug URL will be contained in the result.
	//
	// If there is more than one gopls instance along the serving path (i.e. you
	// are using a daemon), each gopls instance will attempt to start debugging.
	// If Addr specifies a port, only the daemon will be able to bind to that
	// port, and each intermediate gopls instance will fail to start debugging.
	// For this reason it is recommended not to specify a port (or equivalently,
	// to specify ":0").
	//
	// If the server was already debugging this field has no effect, and the
	// result will contain the previously configured debug URL(s).
	Addr string
}

type DebuggingResult

type DebuggingResult struct {
	// The URLs to use to access the debug servers, for all gopls instances in
	// the serving path. For the common case of a single gopls instance (i.e. no
	// daemon), this will be exactly one address.
	//
	// In the case of one or more gopls instances forwarding the LSP to a daemon,
	// URLs will contain debug addresses for each server in the serving path, in
	// serving order. The daemon debug address will be the last entry in the
	// slice. If any intermediate gopls instance fails to start debugging, no
	// error will be returned but the debug URL for that server in the URLs slice
	// will be empty.
	URLs []string
}

type DependencyArgs

type DependencyArgs struct {
	// The go.mod file URI.
	URI protocol.DocumentURI
	// Additional args to pass to the go command.
	GoCmdArgs []string
	// Whether to add a require directive.
	AddRequire bool
}

type DiagnoseFilesArgs

type DiagnoseFilesArgs struct {
	Files []protocol.DocumentURI
}

DiagnoseFilesArgs specifies a set of files for which diagnostics are wanted.

type EditGoDirectiveArgs

type EditGoDirectiveArgs struct {
	// Any document URI within the relevant module.
	URI protocol.DocumentURI
	// The version to pass to `go mod edit -go`.
	Version string
}

type FileImport

type FileImport struct {
	// Path is the import path of the import.
	Path string
	// Name is the name of the import, e.g. `foo` in `import foo "strings"`.
	Name string
}

type FileStats

type FileStats struct {
	Total   int // total number of files
	Largest int // number of bytes in the largest file
	Errs    int // number of files that could not be read
}

FileStats holds information about a set of files.

type GenerateArgs

type GenerateArgs struct {
	// URI for the directory to generate.
	Dir protocol.DocumentURI

	// Whether to generate recursively (go generate ./...)
	Recursive bool
}

type GoGetPackageArgs

type GoGetPackageArgs struct {
	// Any document URI within the relevant module.
	URI protocol.DocumentURI
	// The package to go get.
	Pkg        string
	AddRequire bool
}

type Interface

type Interface interface {
	// ApplyFix: Apply a fix
	//
	// Applies a fix to a region of source code.
	ApplyFix(context.Context, ApplyFixArgs) (*protocol.WorkspaceEdit, error)

	// Test: Run test(s) (legacy)
	//
	// Runs `go test` for a specific set of test or benchmark functions.
	Test(context.Context, protocol.DocumentURI, []string, []string) error

	// Test: Run test(s)
	//
	// Runs `go test` for a specific set of test or benchmark functions.
	RunTests(context.Context, RunTestsArgs) error

	// Generate: Run go generate
	//
	// Runs `go generate` for a given directory.
	Generate(context.Context, GenerateArgs) error

	// RegenerateCgo: Regenerate cgo
	//
	// Regenerates cgo definitions.
	RegenerateCgo(context.Context, URIArg) error

	// Tidy: Run go mod tidy
	//
	// Runs `go mod tidy` for a module.
	Tidy(context.Context, URIArgs) error

	// Vendor: Run go mod vendor
	//
	// Runs `go mod vendor` for a module.
	Vendor(context.Context, URIArg) error

	// EditGoDirective: Run go mod edit -go=version
	//
	// Runs `go mod edit -go=version` for a module.
	EditGoDirective(context.Context, EditGoDirectiveArgs) error

	// UpdateGoSum: Update go.sum
	//
	// Updates the go.sum file for a module.
	UpdateGoSum(context.Context, URIArgs) error

	// CheckUpgrades: Check for upgrades
	//
	// Checks for module upgrades.
	CheckUpgrades(context.Context, CheckUpgradesArgs) error

	// AddDependency: Add a dependency
	//
	// Adds a dependency to the go.mod file for a module.
	AddDependency(context.Context, DependencyArgs) error

	// UpgradeDependency: Upgrade a dependency
	//
	// Upgrades a dependency in the go.mod file for a module.
	UpgradeDependency(context.Context, DependencyArgs) error

	// RemoveDependency: Remove a dependency
	//
	// Removes a dependency from the go.mod file of a module.
	RemoveDependency(context.Context, RemoveDependencyArgs) error

	// ResetGoModDiagnostics: Reset go.mod diagnostics
	//
	// Reset diagnostics in the go.mod file of a module.
	ResetGoModDiagnostics(context.Context, ResetGoModDiagnosticsArgs) error

	// GoGetPackage: 'go get' a package
	//
	// Runs `go get` to fetch a package.
	GoGetPackage(context.Context, GoGetPackageArgs) error

	// GCDetails: Toggle gc_details
	//
	// Toggle the calculation of gc annotations.
	GCDetails(context.Context, protocol.DocumentURI) error

	// ToggleGCDetails: Toggle gc_details
	//
	// Toggle the calculation of gc annotations.
	ToggleGCDetails(context.Context, URIArg) error

	// ListKnownPackages: List known packages
	//
	// Retrieve a list of packages that are importable from the given URI.
	ListKnownPackages(context.Context, URIArg) (ListKnownPackagesResult, error)

	// ListImports: List imports of a file and its package
	//
	// Retrieve a list of imports in the given Go file, and the package it
	// belongs to.
	ListImports(context.Context, URIArg) (ListImportsResult, error)

	// AddImport: Add an import
	//
	// Ask the server to add an import path to a given Go file.  The method will
	// call applyEdit on the client so that clients don't have to apply the edit
	// themselves.
	AddImport(context.Context, AddImportArgs) error

	// StartDebugging: Start the gopls debug server
	//
	// Start the gopls debug server if it isn't running, and return the debug
	// address.
	StartDebugging(context.Context, DebuggingArgs) (DebuggingResult, error)

	// StartProfile: Start capturing a profile of gopls' execution
	//
	// Start a new pprof profile. Before using the resulting file, profiling must
	// be stopped with a corresponding call to StopProfile.
	//
	// This command is intended for internal use only, by the gopls benchmark
	// runner.
	StartProfile(context.Context, StartProfileArgs) (StartProfileResult, error)

	// StopProfile: Stop an ongoing profile
	//
	// This command is intended for internal use only, by the gopls benchmark
	// runner.
	StopProfile(context.Context, StopProfileArgs) (StopProfileResult, error)

	// RunGovulncheck: Run vulncheck
	//
	// Run vulnerability check (`govulncheck`).
	RunGovulncheck(context.Context, VulncheckArgs) (RunVulncheckResult, error)

	// FetchVulncheckResult: Get known vulncheck result
	//
	// Fetch the result of latest vulnerability check (`govulncheck`).
	FetchVulncheckResult(context.Context, URIArg) (map[protocol.DocumentURI]*vulncheck.Result, error)

	// MemStats: Fetch memory statistics
	//
	// Call runtime.GC multiple times and return memory statistics as reported by
	// runtime.MemStats.
	//
	// This command is used for benchmarking, and may change in the future.
	MemStats(context.Context) (MemStatsResult, error)

	// WorkspaceStats: Fetch workspace statistics
	//
	// Query statistics about workspace builds, modules, packages, and files.
	//
	// This command is intended for internal use only, by the gopls stats
	// command.
	WorkspaceStats(context.Context) (WorkspaceStatsResult, error)

	// RunGoWorkCommand: Run `go work [args...]`, and apply the resulting go.work
	// edits to the current go.work file
	RunGoWorkCommand(context.Context, RunGoWorkArgs) error

	// AddTelemetryCounters: Update the given telemetry counters
	//
	// Gopls will prepend "fwd/" to all the counters updated using this command
	// to avoid conflicts with other counters gopls collects.
	AddTelemetryCounters(context.Context, AddTelemetryCountersArgs) error

	// MaybePromptForTelemetry: Prompt user to enable telemetry
	//
	// Checks for the right conditions, and then prompts the user
	// to ask if they want to enable Go telemetry uploading. If
	// the user responds 'Yes', the telemetry mode is set to "on".
	MaybePromptForTelemetry(context.Context) error

	// ChangeSignature: Perform a "change signature" refactoring
	//
	// This command is experimental, currently only supporting parameter removal.
	// Its signature will certainly change in the future (pun intended).
	ChangeSignature(context.Context, ChangeSignatureArgs) (*protocol.WorkspaceEdit, error)

	// DiagnoseFiles: Cause server to publish diagnostics for the specified files.
	//
	// This command is needed by the 'gopls {check,fix}' CLI subcommands.
	DiagnoseFiles(context.Context, DiagnoseFilesArgs) error

	// Views: List current Views on the server.
	//
	// This command is intended for use by gopls tests only.
	Views(context.Context) ([]View, error)
}

Interface defines the interface gopls exposes for the workspace/executeCommand request.

This interface is used to generate marshaling/unmarshaling code, dispatch, and documentation, and so has some additional restrictions:

  1. All method arguments must be JSON serializable.
  2. Methods must return either error or (T, error), where T is a JSON serializable type.
  3. The first line of the doc string is special. Everything after the colon is considered the command 'Title'. TODO(rFindley): reconsider this -- Title may be unnecessary.

The doc comment on each method is eventually published at https://github.com/golang/tools/blob/master/gopls/doc/commands.md, so please be consistent in using this form:

Command: Capitalized verb phrase with no period

Longer description here...

type ListImportsResult

type ListImportsResult struct {
	// Imports is a list of imports in the requested file.
	Imports []FileImport

	// PackageImports is a list of all imports in the requested file's package.
	PackageImports []PackageImport
}

type ListKnownPackagesResult

type ListKnownPackagesResult struct {
	// Packages is a list of packages relative
	// to the URIArg passed by the command request.
	// In other words, it omits paths that are already
	// imported or cannot be imported due to compiler
	// restrictions.
	Packages []string
}

type MemStatsResult

type MemStatsResult struct {
	HeapAlloc  uint64
	HeapInUse  uint64
	TotalAlloc uint64
}

MemStatsResult holds selected fields from runtime.MemStats.

type PackageImport

type PackageImport struct {
	// Path is the import path of the import.
	Path string
}

type PackageStats

type PackageStats struct {
	Packages        int // total number of packages
	LargestPackage  int // number of files in the largest package
	CompiledGoFiles int // total number of compiled Go files across all packages
	Modules         int // total number of unique modules
}

PackageStats holds information about a collection of packages.

type RemoveDependencyArgs

type RemoveDependencyArgs struct {
	// The go.mod file URI.
	URI protocol.DocumentURI
	// The module path to remove.
	ModulePath string
	// If the module is tidied apart from the one unused diagnostic, we can
	// run `go get module@none`, and then run `go mod tidy`. Otherwise, we
	// must make textual edits.
	OnlyDiagnostic bool
}

type ResetGoModDiagnosticsArgs

type ResetGoModDiagnosticsArgs struct {
	URIArg

	// Optional: source of the diagnostics to reset.
	// If not set, all resettable go.mod diagnostics will be cleared.
	DiagnosticSource string
}

type RunGoWorkArgs

type RunGoWorkArgs struct {
	ViewID    string   // ID of the view to run the command from
	InitFirst bool     // Whether to run `go work init` first
	Args      []string // Args to pass to `go work`
}

type RunTestsArgs

type RunTestsArgs struct {
	// The test file containing the tests to run.
	URI protocol.DocumentURI

	// Specific test names to run, e.g. TestFoo.
	Tests []string

	// Specific benchmarks to run, e.g. BenchmarkFoo.
	Benchmarks []string
}

type RunVulncheckResult

type RunVulncheckResult struct {
	// Token holds the progress token for LSP workDone reporting of the vulncheck
	// invocation.
	Token protocol.ProgressToken
}

RunVulncheckResult holds the result of asynchronously starting the vulncheck command.

type StackEntry

type StackEntry struct {

	// User-friendly representation of function/method names.
	// e.g. package.funcName, package.(recvType).methodName, ...
	Name string
	URI  protocol.DocumentURI
	Pos  protocol.Position // Start position. (0-based. Column is always 0)
}

StackEntry models an element of a call stack.

type StartProfileArgs

type StartProfileArgs struct {
}

StartProfileArgs holds the arguments to the StartProfile command.

It is a placeholder for future compatibility.

type StartProfileResult

type StartProfileResult struct {
}

StartProfileResult holds the result of the StartProfile command.

It is a placeholder for future compatibility.

type StopProfileArgs

type StopProfileArgs struct {
}

StopProfileArgs holds the arguments to the StopProfile command.

It is a placeholder for future compatibility.

type StopProfileResult

type StopProfileResult struct {
	// File is the profile file name.
	File string
}

StopProfileResult holds the result to the StopProfile command.

type URIArg

type URIArg struct {
	// The file URI.
	URI protocol.DocumentURI
}

type URIArgs

type URIArgs struct {
	// The file URIs.
	URIs []protocol.DocumentURI
}

type View

type View struct {
	ID         string               // view ID (the index of this view among all views created)
	Type       string               // view type (via cache.ViewType.String)
	Root       protocol.DocumentURI // root dir of the view (e.g. containing go.mod or go.work)
	Folder     protocol.DocumentURI // workspace folder associated with the view
	EnvOverlay []string             // environment variable overrides
}

A View holds summary information about a cache.View.

type ViewStats

type ViewStats struct {
	GoCommandVersion  string       // version of the Go command resolved for this view
	AllPackages       PackageStats // package info for all packages (incl. dependencies)
	WorkspacePackages PackageStats // package info for workspace packages
	Diagnostics       int          // total number of diagnostics in the workspace
}

ViewStats holds information about a single View in the session.

type VulncheckArgs

type VulncheckArgs struct {
	// Any document in the directory from which govulncheck will run.
	URI protocol.DocumentURI

	// Package pattern. E.g. "", ".", "./...".
	Pattern string
}

type WorkspaceStatsResult

type WorkspaceStatsResult struct {
	Files FileStats   // file stats for the cache
	Views []ViewStats // stats for each view in the session
}

WorkspaceStatsResult returns information about the size and shape of the workspace.

Directories

Path Synopsis
Package commandmeta provides metadata about LSP commands, by analyzing the command.Interface type.
Package commandmeta provides metadata about LSP commands, by analyzing the command.Interface type.
Package gen is used to generate command bindings from the gopls command interface.
Package gen is used to generate command bindings from the gopls command interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL