-
-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathgopher.txt
638 lines (483 loc) · 27.9 KB
/
gopher.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
gopher.txt: plugin for the Go programming language
==============================================================================
INTRODUCTION *gopher*
Listen very carefully, I shall say this only once.
gopher.vim is a Vim plugin for the Go programming language. This is the
reference documentation; see the README for a quickstart tutorial.
Table of contents~
1. Motions |gopher-motions|
2. Text objects |gopher-text-objects|
3. Mappings |gopher-mappings|
4. Filetypes |gopher-filetypes|
5. Compilers |gopher-compilers|
6. Commands |gopher-commands|
7. Options |gopher-options|
==============================================================================
MOTIONS *gopher-motions*
*gopher-v_]]* *gopher-]]*
]] Go [count] top-level declarations forward. A top-level
declaration is a `func`, `type`, `var`, `const`, or `import`.
In |ft-gopresent| files it jumps [count] sections
forward
*gopher-v_[[* *gopher-[[*
[[ Go [count] top-level declarations backwards. In
|ft-gopresent| it jumps [count] sections backwards.
==============================================================================
TEXT OBJECTS *gopher-text-objects*
*gopher-v_af* *gopher-af*
af "a function": complete function body and any preceding
documentation comment.
*gopher-v_if* *gopher-if*
if "inner function": function contents without the
signature.
*gopher-v_ac* *gopher-ac*
ac "a comment": the entire comment block, including the
comment characters themselves.
*gopher-v_ic* *gopher-ic*
ic "inner comment": content of the function but exclude
the start and end markers.
==============================================================================
MAPPINGS *gopher-mappings*
*g:gopher_map* = `{}`
Control how keys are mapped. This is a dict where the following keys
have a special meaning (all starting with _):
Key name Default Description ~
_default 1 Use the defaults for any of the below;
otherwise changing one settings means
you'd have to copy all the defaults.
_popup 1 Use the popup menu; in Vim 8.1.1513 or
newer this uses the inline popup menus
(highly recommended!)
_nmap_prefix ; Prefix all normal mode mappings.
_imap_prefix <C-k> Prefix all insert mode mappings.
_imap_ctrl 1 Also map <C-> variants of insert
mappings, so <C-k>i and <C-k><C-i> both
work.
All other keys are a mapping name with the `gopher-` prefix and
parenthesis removed (e.g. `if`).
The value is used for both the normal and insert mode mappings if it's
is a string. Use a list to map different keys for normal and insert
mode. Use an empty string to not map a key.
Map Default value ~
|(gopher-install)| ;
|(gopher-test-current)| t
|(gopher-test)| T
|(gopher-lint)| l
|(gopher-error)| e
|(gopher-if)| i
|(gopher-implement)| m
|(gopher-return)| r
|(gopher-fillstruct)| f
Some examples:
Don't map anything; you can still use the (gopher-*) mappings
manually from your vimrc: >
let g:gopher_map = 0
<
Map all defaults except |(gopher-if)|, which is mapped to `;x`
(normal mode) and `<C-k>x` (insert mode): >
let g:gopher_map = {'_default': 1, 'if': 'x'}
<
The default for the `_default` key is `1`, so all the other keys
will be assigned their defaults. Set `_default` to `0` if you
don't want that, for example to just just |(gopher-if)|: >
let g:gopher_map = {'_default': 0, 'if': 'x'}
<
Use `<Leader>i` and `<C-g>i`; >
let g:gopher_map = {'_nmap_prefix': '<Leader>', '_imap_prefix': '<C-g>'}
<
A more complex example which 1) doesn't map any defaults, 2)
doesn't use a prefix for normal mode mappings, maps to `<F1>` and
`<F2>`, and 4) doesn't map anything in insert mode: >
let g:gopher_map = {
\ '_default': 0,
\ '_nmap_prefix': '',
\ 'if': ['<F1>', ''],
\ 'return' ['<F2>', ''],
\ }
*g:gopher_popup* = (undefined)
Dict to merge with the options passed to |popup_create|. See
|popup_create-arguments|.
Especially useful to override the position or appearance; for example
if you don't want any borders, padding, and a different colour you can
use something like: >
hi GopherMenu guibg=#cccccc guifg=#000000
let g:gopher_popup = {
\ 'border': [0, 0, 0, 0],
\ 'highlight': 'GopherMenu',
\ 'padding': [0, 0, 0, 0],
\ 'title': '',
\}
<
This can also be a function returning a dict, mainly so that you can
use |winwidth()| and |winheight()| for positioning. For example to
place it in the bottom-right of the current window: >
let g:Gopher_popup = {->{
\ 'pos': 'botright',
\ 'line': winheight(0) + 1,
\ 'col': winwidth(0),
\ }}
<
Note: You MUST spell this with a capital (Vim requirement, |E704|).
The uppercase variant will be merged with the lowercase variant if
both are defined.
The mappings that gopher.vim defines; the defaults are shown in the first
column with the default prefixes.
*(gopher-install)*
;; <C-k><C-k> Set compiler to `go` and |:make|.
*(gopher-test)*
;T <C-k><C-T> Set compiler to `gotest` and |:make|.
*(gopher-test-current)*
;t <C-k><C-t> Set compiler to `gotest` and |:make| with
`-run TestCurrentFunction` added if the cursor is
inside a test function.
*(gopher-lint)*
;l <C-k>l Set compiler to `golint` and |:make|.
*(gopher-if)*
;i <C-k>i Toggle between single-line and normal if checks. For
example these: >
err := e()
if err != nil {
, ok := aMap[key]
if ok && otherCond {
<
Become: >
if err := e(); err != nil {
if _, ok := aMap[key]; ok && otherCond {
<
This works in both directions.
*(gopher-implement)*
;m <C-k>m Implement an interface: generate all methods that
don't exist yet for a type.
Expects cursor to be on type definition; you'll be
asked which interface you want to implement.
*(gopher-return)*
;r <C-k>r Generate a return statement with the appropriate zero
values for the current function.
*(gopher-error)*
;e <C-k>e Generate a return statement with the appropriate zero
values for the current function, wrapped in an
`err != nil` check.
*(gopher-fillstruct)*
;f <C-k>f Fill a struct with all missing entries.
==============================================================================
FILETYPES *gopher-filetypes*
*ft-go*
go~
The go filetype sets the following settings:
'equalprg' `gofmt 2>/dev/null || cat /dev/stdin`
A simple/native way to format code with gofmt
while ignoring errors. Use ALE or Syntastic
for a more advanced experience.
Note: `goimports` is not used here as it can't
operate over a partial file (e.g a line or
function). See the snippet in the README on
how to format with goimports on write.
*g:gopher_highlight*
The `g:gopher_highlight` setting controls various options for the go
syntax highlighting. It's a list which can contain any combination of
the following items:
complex Highlight complex numbers; disabled by
default as it's fairly slow and not
frequently used.
string-fmt Highlight fmt formatting specifiers.
string-spell Enable spell checking in strings.
Options to control folding:
fold-block All `{` .. `}` blocks.
fold-comment Any comment except the package comment.
fold-import `import` block.
fold-pkg-comment The package comment.
fold-varconst `var` and `const` blocks.
The default is `['string-spell', 'string-fmt']`
Note: you will need to reload the syntax file with `:set syntax=go`
for changes to take effect when changing it at runtime.
*ft-gomod* *ft-gowork*
gomod gowork~
go.mod and go.work files; there are no options.
*ft-gopresent*
gopresent~
go present slide:
https://godoc.org/golang.org/x/tools/present
Only highlights the basics and adds |gopher-[[| and
|gopher-]]| motions.
*ft-gotext* *ft-gohtml*
gotext gohtml~
text/template and html/template. Automatically applied
to files ending with the `.gotext` and `.gohtml`.
gohtml loads the standard html syntax highlighting,
but they are otherwise identical.
==============================================================================
COMPILERS *gopher-compilers*
Several compilers are supported; you can select one with the
|:compiler| command.
go `go install`
gotest `go test`
golint `golangci-lint`
The compilers are compatible with vim-dispatch, but none of the
settings below will take effect (so you'll need to use
`:Dispatch go build ./cmd/pkg`; the package name won't be added
automatically).
*gopher-compiler-go*
go ~
gopher.vim tries to be a bit smart about what to set `makeprg` to:
go
gopher_build_command
gopher_build_flags
gopher_build_tags
gopher_build_package
if a `./cmd/<module-name>` package exists then it will compile that
instead of the current package, and build tags from the current file
are automatically added. There's a bunch of options to tweak the
behaviour: see `:help gopher-compilers` for detailed documentation.
*g:gopher_build_command*
*b:gopher_build_command*
Command to build Go code.
Default: `install`; set to `build` if you want to run `go build`
instead of `go install`
*g:gopher_build_package*
*b:gopher_build_package*
Can be set to a package name to install with |:make|; default is to set
the buffer-local setting to `[module]/cmd/[module-name]` if the
package exists.
You typically want to set this per-project with an |autocmd|:
>
autocmd BufReadPre /home/martin/code/proj/*.go
\ let b:gopher_build_package = 'example.com/proj/cmd/xxx'
<
This ensures that the `example.com/proj/cmd/xxx` package is installed
with |:make| regardless of the current directory or file you have
open. This is only used by the go |compiler|, not gotest or golint.
Set to `-1` to disable the automatic `cmd/[module-name]` detection.
Note: reset the compiler with `:compiler go` (or just run |:e|) to
reload after changing this during runtime.
*g:gopher_build_tags*
*b:gopher_build_tags*
List of build tags added to all commands that support it. The
buffer-local variable is automatically set to the build tags in the
file.
Note: the buffer-local variable overrides the global; it's not merged.
*g:gopher_build_flags*
*b:gopher_build_flags*
List of flags to add to all `go` commands.
Default: `['-tags'] + g:gopher_build_tags`
b: undefined
*gopher-compiler-gotest*
gotest~
TODO: document
*gopher-compiler-golint*
golint~
TODO: document
==============================================================================
COMMANDS *gopher-commands*
:GoSetup *:GoSetup*
Make sure all dependent tools are downloaded and compiled. Normally
this is done automatically after you start Vim so it's not required to
manually run it.
Add the `setup` flag to |g:gopher_debug| to show more information
about what it's doing.
You need to set the |filetype| to `go` to run this as a post-install
script, since it's only loaded for Go files; for example: >
vim +'set ft=go' +GoSetup +'q!'
<
*g:gopher_setup* = `[]`
A list of flags to control |:GoSetup| behaviour; allowed
values:
no-auto-install Don't automatically download or
install tools upon first use; it will
be an error if a tool doesn't exist.
This is useful if you run |:GoSetup|
manually after installing and are
_sure_ all the required tools exist
and want a minor performance boost.
no-vendor-gobin By default the tools are installed to
a "vendored" `$GOBIN` in the
gopher.vim directory to ensure 1) the
correct versions are used and 2) to
not interfere with anything else that
might be installed on the system. If
this is disabled it will run a
"normal" `go install` without setting
`$GOBIN`.
:GoDiag[!] {report, clear} *:GoDiag*
Print diagnostic information. Also see |g:gopher_debug|.
When the [!] is included the output will be copied to the clipboard
(|quote+| register).
When `report` is given the output will include your Vim's settings,
formatted for a GitHub issue, and copied to a clipboard (opening it in
the browser isn't foolproof due to URL length limits).
`clear` erases the command history.
:GoCoverage [flags] *:GoCoverage*
Run `go test -cover` and highlight lines reported as covered and
uncovered.
[flags] are passed to the `go test` command; there are two special
flags:
clear Clear all existing highlighting.
toggle Toggle display of highlighting.
*hl-goCoverageCovered* *hl-goCoverageUncover*
Note: it's impossible to highlight the background with a colour that
is guaranteed to work well with all colour schemes. The default is to
use something that works well with the default one and – hopefully –
most common ones.
Override the goCoverageCovered and/or goCoverageUncover highlight
groups if the defaults don't work well for you.
>
augroup my-gopher-coverage
au!
au Syntax go hi goCoverageCovered guibg=blue
au Syntax go hi goCoverageUncover guibg=brown
augroup end
<
:GoFrob [command] [parameters] *:GoFrob*
Various tools to frob with (modify) Go code. All these operations are
also mapped by default (see |gopher-mappings|); this is just an
alternative way to run it for people who prefer to not use the
mappings.
The [command] can be any of the `(gopher-*)`mappings, with the
`gopher-` prefix and parenthesis removed (e.g. `if`). You'll be asked
which operation to run if the [command] is omitted.
Some operations accept additional parameters:
implement One or more interface name.
:GoGuru [flags] {command} *:GoGuru*
Get information about Go code. {command} can be any of:
callees Show targets of function call.
This is useful especially if the function call is
an interface.
callers Show locations where the current function is
called from.
callstack Show path from callgraph root to the current
function.
definition Show declaration of identifier.
describe Show detailed description of selected syntax.
freevars Show free variables of selection, meaning
variables which are referenced but not defined
within the selection.
implements Show which interfaces a type of method implements.
peers Show locations where data is sent or read to/from
a channel.
pointsto Show variables the selected pointer may point to.
referrers Show all references to an identifier.
what Basic information about the selected syntax.
whicherrs Get possible values of an error variable.
See the guru manual for a full description and usage examples:
http://golang.org/s/using-guru
Note: `guru` is not fully modules-aware. Use a LSP client for gopls'
module-aware code insight features (not all of `guru`'s features are
supported in LSP though).
[flags] are passed to the `guru` command; commons ones are:
-reflect Analyse reflection soundly (slow).
-scope [pkg] Comma-separated list of packages the analysis
should be limited to; overrides
|g:gopher_guru_scope|.
*g:gopher_guru_scope* = `gopher#go#package()`
*b:gopher_guru_scope* = (undefined)
Limit the analysis to these package, comma-separated list.
Some guru commands are slow and expensive, so for reasons of
efficiency the analysis is limited to a limited set of
packages.
The default is to use the package the current buffer belongs
to; but this may not always be correct. For example for the
file example.com/pkg/a/a.go the scope will be set to
example.com/pkg/a, but you probably want example.com/pkg.
With this option a more extensive scope can be given. Some
examples:
golang.org/x/tools/cmd/guru A single package
golang.org/x/tools/... All packages under dir
... The entire workspace.
You can set it from an |:autocmd|: >
autocmd BufRead /code/example.com/*.go
let g:gopher_guru_scope = 'example.com/pkg'
<
:GoImport [flags] *:GoImport*
Add, modify, or remove imports.
Multiple imports can be added (`-add pkg`), removed (`-rm pkg`), or
replaced (`-replace pkg`). The `-add` flag is optional for the first
package. <cword> is assumed if [flags] is empty.
A package can be given as `pkg:import-alias`, for example use
`github.com/lib/pq:_` to add `import _ "github.com/lib/pq"`
Normally adding imports that already exist is an error, for example
`:GoImport html/template` while `text/template` is already imported.
With `-replace html/template` the existing `text/template` import is
replaced.
:GoRename [new-ident] *:GoRename*
Rename the identifier under the cursor.
if [new-ident] is omitted the new identifier is based on the following
rules:
- All caps identifiers are CamelCased (FOO_BAR -> FooBar).
- Exported are unexported (FooBar -> fooBar).
- Unexported are exported (fooBar -> FooBar).
Tab completion includes the exported and unexported version.
Note: this only works for packages in GOPATH. Use a LSP client for
gopls' module-aware rename feature.
*g:gopher_gorename_flags* = `[]`
List of flags to add to the `gorename` command.
:GoReplace [module] [path] *:GoReplace*
Add a `replace` directive in the project's go.mod. This currently only
works in the `go.mod` buffer.
[module] is a module name; if it's omitted the module on the current
line is used.
[path] is the replacement path; if it's omitted `../` is used.
:{range}GoTags [flags] *:GoTags*
Add, modify, or remove struct tags. Will only apply to the fields in
{range} if it's given, or applied to all fields in the struct if it's
omitted.
All tags in [flags] will be added. A tag can be followed by a `,`
(comma) and an option to add the option, or set to a specific name
with `tag:name`.
Tags can be removed by using `-rm tag`; options can be removed by
using `-rm tag,opt`
The value of |g:gopher_tag_default| is used if no [flags] is given.
Examples: >
:GoTags json Add tag "json"
:GoTags json,omitempty Add tag with omitempty, or add
omitempty for fields where it
already exists.
:GoTags json,omitempty db Add two tags
:GoTags -rm json Remove a tag
:GoTags -rm json,omitempty Remove the omitempty option
:GoTags -rm json -rm db Remove two tags
:GoTags -rm Remove all tags
:GoAddTags sometag:foo Set the tag sometag to the
string foo.
:GoTags json -rm yaml Combine add and rm
<
*g:gopher_tag_default* = `'json'`
Default tag for |:GoTags| when no parameters are given. Can be
any valid set of arguments for |:GoTags| (for example
`json,omitempty -rm yaml`).
*g:gopher_tag_complete* = `['db', 'json', 'json,omitempty', 'yaml']`
Values for tab-completion.
*g:gopher_tag_transform* = `'snakecase'`
Transform the struct field name when adding a tag. Supported
values:
snakecase FooBar -> foo_bar
camelcase FooBar -> fooBar
lispcase FooBar -> foo-bar
pascalcase fooBar -> FooBar
keep No transformation; FooBar -> FooBar
==============================================================================
OPTIONS *gopher-options*
Options documented elsewhere:
|g:gopher_popup| Control default mappings.
|g:gopher_map|
|g:gopher_highlight| Control syntax highlighting.
|g:gopher_build_flags| Flags to go install/test/build.
|g:gopher_build_tags|
|g:gopher_build_command|
|g:gopher_build_package|
|g:gopher_gorename_flags| Flags to various external tools.
|g:gopher_guru_scope|
|g:gopher_tag_complete|
|g:gopher_tag_default|
|g:gopher_tag_transform|
*g:gopher_debug* = `[]`
List of debugging options:
commands Records all shell commands; use |:GoDiag| or
`gopher#system#history()` to view. The last 5 commands are
always saved with limited output irregardless of this flag.
setup Be verbose about what |:GoSetup| does.
*g:gopher_override_vimgo* = (undefined)
Override vim-go; this removes all vim-go commands, autocommands,
unsets b:did_ftplugin and b:current_syntax, and removes vim-go from
'runtimepath'.
This is only recommended for testing/experimenting; and not guaranteed
to be 100% reliable.
vim:tw=78:ts=8:sts=8:sw=8:ft=help:norl:expandtab