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 ¶
- Variables
- func Dispatch(ctx context.Context, params *protocol.ExecuteCommandParams, s Interface) (interface{}, error)
- func ID(name string) string
- func MarshalArgs(args ...interface{}) ([]json.RawMessage, error)
- func NewAddDependencyCommand(title string, a0 DependencyArgs) (protocol.Command, error)
- func NewAddImportCommand(title string, a0 AddImportArgs) (protocol.Command, error)
- func NewApplyFixCommand(title string, a0 ApplyFixArgs) (protocol.Command, error)
- func NewCheckUpgradesCommand(title string, a0 CheckUpgradesArgs) (protocol.Command, error)
- func NewEditGoDirectiveCommand(title string, a0 EditGoDirectiveArgs) (protocol.Command, error)
- func NewFetchVulncheckResultCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewGCDetailsCommand(title string, a0 protocol.DocumentURI) (protocol.Command, error)
- func NewGenerateCommand(title string, a0 GenerateArgs) (protocol.Command, error)
- func NewGenerateGoplsModCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewGoGetPackageCommand(title string, a0 GoGetPackageArgs) (protocol.Command, error)
- func NewListImportsCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewListKnownPackagesCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewRegenerateCgoCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewRemoveDependencyCommand(title string, a0 RemoveDependencyArgs) (protocol.Command, error)
- func NewResetGoModDiagnosticsCommand(title string, a0 ResetGoModDiagnosticsArgs) (protocol.Command, error)
- func NewRunGovulncheckCommand(title string, a0 VulncheckArgs) (protocol.Command, error)
- func NewRunTestsCommand(title string, a0 RunTestsArgs) (protocol.Command, error)
- func NewStartDebuggingCommand(title string, a0 DebuggingArgs) (protocol.Command, error)
- func NewTestCommand(title string, a0 protocol.DocumentURI, a1 []string, a2 []string) (protocol.Command, error)
- func NewTidyCommand(title string, a0 URIArgs) (protocol.Command, error)
- func NewToggleGCDetailsCommand(title string, a0 URIArg) (protocol.Command, error)
- func NewUpdateGoSumCommand(title string, a0 URIArgs) (protocol.Command, error)
- func NewUpgradeDependencyCommand(title string, a0 DependencyArgs) (protocol.Command, error)
- func NewVendorCommand(title string, a0 URIArg) (protocol.Command, error)
- func UnmarshalArgs(jsonArgs []json.RawMessage, args ...interface{}) error
- type AddImportArgs
- type ApplyFixArgs
- type CallStack
- type CheckUpgradesArgs
- type Command
- type DebuggingArgs
- type DebuggingResult
- type DependencyArgs
- type EditGoDirectiveArgs
- type FileImport
- type GenerateArgs
- type GoGetPackageArgs
- type Interface
- type ListImportsResult
- type ListKnownPackagesResult
- type PackageImport
- type RemoveDependencyArgs
- type ResetGoModDiagnosticsArgs
- type RunTestsArgs
- type RunVulncheckResult
- type StackEntry
- type URIArg
- type URIArgs
- type Vuln
- type VulncheckArgs
- type VulncheckResult
Constants ¶
This section is empty.
Variables ¶
var Commands = []Command{ AddDependency, AddImport, ApplyFix, CheckUpgrades, EditGoDirective, FetchVulncheckResult, GCDetails, Generate, GenerateGoplsMod, GoGetPackage, ListImports, ListKnownPackages, RegenerateCgo, RemoveDependency, ResetGoModDiagnostics, RunGovulncheck, RunTests, StartDebugging, Test, Tidy, ToggleGCDetails, UpdateGoSum, UpgradeDependency, Vendor, }
Functions ¶
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 NewApplyFixCommand ¶
func NewApplyFixCommand(title string, a0 ApplyFixArgs) (protocol.Command, error)
func NewCheckUpgradesCommand ¶
func NewCheckUpgradesCommand(title string, a0 CheckUpgradesArgs) (protocol.Command, error)
func NewEditGoDirectiveCommand ¶
func NewEditGoDirectiveCommand(title string, a0 EditGoDirectiveArgs) (protocol.Command, error)
func NewGCDetailsCommand ¶
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 NewRegenerateCgoCommand ¶
func NewRemoveDependencyCommand ¶
func NewRemoveDependencyCommand(title string, a0 RemoveDependencyArgs) (protocol.Command, error)
func NewResetGoModDiagnosticsCommand ¶
func NewResetGoModDiagnosticsCommand(title string, a0 ResetGoModDiagnosticsArgs) (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 NewTestCommand ¶
func NewUpdateGoSumCommand ¶
func NewUpgradeDependencyCommand ¶
func NewUpgradeDependencyCommand(title string, a0 DependencyArgs) (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 ApplyFixArgs ¶
type ApplyFixArgs struct { // The fix to apply. Fix string // The file URI for the document to fix. URI protocol.DocumentURI // The document range to scan for fixes. Range protocol.Range }
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 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" ApplyFix Command = "apply_fix" CheckUpgrades Command = "check_upgrades" EditGoDirective Command = "edit_go_directive" FetchVulncheckResult Command = "fetch_vulncheck_result" GCDetails Command = "gc_details" Generate Command = "generate" GenerateGoplsMod Command = "generate_gopls_mod" GoGetPackage Command = "go_get_package" ListImports Command = "list_imports" ListKnownPackages Command = "list_known_packages" RegenerateCgo Command = "regenerate_cgo" RemoveDependency Command = "remove_dependency" ResetGoModDiagnostics Command = "reset_go_mod_diagnostics" RunGovulncheck Command = "run_govulncheck" RunTests Command = "run_tests" StartDebugging Command = "start_debugging" Test Command = "test" Tidy Command = "tidy" ToggleGCDetails Command = "toggle_gc_details" UpdateGoSum Command = "update_go_sum" UpgradeDependency Command = "upgrade_dependency" Vendor Command = "vendor" )
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 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 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) 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 // GenerateGoplsMod: Generate gopls.mod // // (Re)generate the gopls.mod file for a workspace. GenerateGoplsMod(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) // RunGovulncheck: Run govulncheck. // // 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]*govulncheck.Result, 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:
- All method arguments must be JSON serializable.
- Methods must return either error or (T, error), where T is a JSON serializable type.
- 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.
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 PackageImport ¶
type PackageImport struct { // Path is the import path of the import. Path string }
type RemoveDependencyArgs ¶
type RemoveDependencyArgs struct { // The go.mod file URI. URI protocol.DocumentURI // The module path to remove. ModulePath string OnlyDiagnostic bool }
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 URIArg ¶
type URIArg struct { // The file URI. URI protocol.DocumentURI }
type URIArgs ¶
type URIArgs struct { // The file URIs. URIs []protocol.DocumentURI }
type Vuln ¶
type Vuln struct { // ID is the vulnerability ID (osv.Entry.ID). // https://ossf.github.io/osv-schema/#id-modified-fields ID string // Details is the description of the vulnerability (osv.Entry.Details). // https://ossf.github.io/osv-schema/#summary-details-fields Details string `json:",omitempty"` // Aliases are alternative IDs of the vulnerability. // https://ossf.github.io/osv-schema/#aliases-field Aliases []string `json:",omitempty"` // Symbol is the name of the detected vulnerable function or method. // Can be empty if the vulnerability exists in required modules, but no vulnerable symbols are used. Symbol string `json:",omitempty"` // PkgPath is the package path of the detected Symbol. // Can be empty if the vulnerability exists in required modules, but no vulnerable packages are used. PkgPath string `json:",omitempty"` // ModPath is the module path corresponding to PkgPath. // TODO: how do we specify standard library's vulnerability? ModPath string `json:",omitempty"` // URL is the URL for more info about the information. // Either the database specific URL or the one of the URLs // included in osv.Entry.References. URL string `json:",omitempty"` // Current is the current module version. CurrentVersion string `json:",omitempty"` // Fixed is the minimum module version that contains the fix. FixedVersion string `json:",omitempty"` // Example call stacks. CallStacks []CallStack `json:",omitempty"` // Short description of each call stack in CallStacks. CallStackSummaries []string `json:",omitempty"` }
Vuln models an osv.Entry and representative call stacks. TODO: deprecate
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 VulncheckResult ¶
type VulncheckResult struct {
Vuln []Vuln
}
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. |