x/tools/gopls: support advanced query syntax for Symbol

[myitcv]

What version of Go are you using (go version)?

$ go version
go version devel +b7689f5aa3 Fri Jan 31 06:02:00 2020 +0000 linux/amd64
$ go list -m golang.org/x/tools
golang.org/x/tools v0.0.0-20200214144324-88be01311a71
$ go list -m golang.org/x/tools/gopls
golang.org/x/tools/gopls v0.1.8-0.20200214144324-88be01311a71

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOENV="/home/myitcv/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/myitcv/gos"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/myitcv/gostuff/src/github.com/myitcv/govim/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build646330205=/tmp/go-build -gno-record-gcc-switches"

What did you do?

This is a request/proposal more than an issue.

We were discussing with @findleyr a means by which symbol search can be made more useful (in Vim). With #37236 fixed, the existing Symbol method will return matches from within the workspace (main module). But a fairly common query is to find symbols matching the query within the "current" package, where "current" is defined by the file within which the cursor is located. i.e. I want to jump to the definition of the method (*T).M.

Because the editor/client knows nothing about packages, I think this will require a query similar to the following. Imagine we are searching using the term hello, with the cursor in the file main.go

package:/path/to/main.go hello

gopls would then translate the file URI to a package and suitably constrain the results.

---

cc @stamblerre @findleyr

FYI @leitzler

[myitcv]

Per #37236 (comment), we should also add a module scope, again parameterised by file, to limit the search scope to the module containing the file.

[myitcv]

To make this request more formal I'd like to sketch out a potential query syntax. It is based on the popular fzf search syntax (FYI @junegunn).

In the text that follows, the term "item" refers to what we are matching against (noting that more information/context is returned in protocol.SymbolInformation in the form of location etc). At present an "item" is just the symbol name (variable, function, method etc), but in #38273 I have proposed making the fully qualified symbol the "item".

Search syntax

Unless otherwise specified via an option (see below), Symbol will search in extended-search mode, a mode that takes multiple space-separated search terms. The overall search query is the conjunction of these terms.

Token	Match type	Description
jsEnc	fuzzy-match	Items that match jsEnc
'json	exact-match (quoted)	Items that include json
^encoding	prefix-exact-match	Items that start with encoding
main$	suffix-exact-match	Items that end with main
!json	inverse-exact-match	Items that do not include json
!^encoding	inverse-prefix-exact-match	Items that do not start with encoding
!main$	inverse-suffix-exact-match	Items that do not end with main

To be explicit, / and . (which appear in some fully qualified symbol paths) also participate in the match if specified in a search term.

Options

Options are provided as special search terms in the form key::value.

• exact::true - enable exact matches (current behaviour)
• package::/path/to/file.go - constrain the search to the package that contains /path/to/file.go (filepath must be absolute)
• module::/path/to/file.go - constrain the search to the module that contains /path/to/file.go (filepath must be absolute)
• package::example.com/blah - constrain the search to the package example.com/blah
• module::example.com/blah - constrain the search to the module (that contains package) example.com/blah
• kind::X,Y,Z - constrain the search to the protocol.SymbolKind list provided (comma separated list of numbers corresponding to the SymbolKind enum

Examples

We assume for the following examples that:

• x/tools/gopls: fully qualify symbol names for Symbol #38273 is adopted
• the type of the symbol is not considered in the match
• the type of the symbol is returned to the client for display purposes

Example 1

A query of "jsEnc" would match encoding/json.Encoder and encoding/json.NewEncoder func(w io.Writer) *Encoder, and encoding/json.Encoder struct and encoding/json.NewEncoder func(w io.Writer) *Encoder respectively would be returned to the client

Example 2

A query of "package::/path/to/file.go 'main" would search within the package that contains /path/to/file.go for items that include the exact term main somewhere in their fully qualified path.

Outstanding questions

• Consider support for filepaths with spaces
• Support disjunctions?
• Further options

[gopherbot]

Change https://golang.org/cl/227677 mentions this issue: internal/lsp: first cut of advanced query syntax for WorkspaceSymbol