-
-
Notifications
You must be signed in to change notification settings - Fork 5.7k
/
lsp.txt
2414 lines (1926 loc) · 106 KB
/
lsp.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
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*lsp.txt* LSP
NVIM REFERENCE MANUAL
LSP client/framework *lsp* *LSP*
Nvim supports the Language Server Protocol (LSP), which means it acts as
a client to LSP servers and includes a Lua framework `vim.lsp` for building
enhanced LSP tools.
https://microsoft.github.io/language-server-protocol/
LSP facilitates features like go-to-definition, find references, hover,
completion, rename, format, refactor, etc., using semantic whole-project
analysis (unlike |ctags|).
Type |gO| to see the table of contents.
==============================================================================
QUICKSTART *lsp-quickstart*
Nvim provides an LSP client, but the servers are provided by third parties.
Follow these steps to get LSP features:
1. Install language servers using your package manager or by following the
upstream installation instructions. You can find language servers here:
https://microsoft.github.io/language-server-protocol/implementors/servers/
2. Use |vim.lsp.start()| to start the LSP server (or attach to an existing
one) when a file is opened. Example: >lua
-- Create an event handler for the FileType autocommand
vim.api.nvim_create_autocmd('FileType', {
-- This handler will fire when the buffer's 'filetype' is "python"
pattern = 'python',
callback = function(args)
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable', '--option', 'arg1', 'arg2'},
-- Set the "root directory" to the parent directory of the file in the
-- current buffer (`args.buf`) that contains either a "setup.py" or a
-- "pyproject.toml" file. Files that share a root directory will reuse
-- the connection to the same LSP server.
root_dir = vim.fs.root(args.buf, {'setup.py', 'pyproject.toml'}),
})
end,
})
<
3. Check that the buffer is attached to the server: >vim
:checkhealth lsp
4. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-config|
*lsp-defaults*
When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
|vim.diagnostic.config()| to customize). It also sets various default options,
listed below, if (1) the language server supports the functionality and (2)
the options are empty or were set by the builtin runtime (ftplugin) files. The
options are not restored when the LSP client is stopped or detached.
- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
completion.
- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|,
|CTRL-W_}| to utilize the language server.
- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
|gq| if the language server supports it.
- To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|.
- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
a custom keymap for `K` exists.
*grr* *gra* *grn* *gri* *i_CTRL-S*
Some keymaps are created unconditionally when Nvim starts:
- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()|
- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|
If not wanted, these keymaps can be removed at any time using
|vim.keymap.del()| or |:unmap| (see also |gr-default|).
*lsp-defaults-disable*
To override or delete any of the above defaults, set or unset the options on
|LspAttach|: >lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
-- Unset 'formatexpr'
vim.bo[args.buf].formatexpr = nil
-- Unset 'omnifunc'
vim.bo[args.buf].omnifunc = nil
-- Unmap K
vim.keymap.del('n', 'K', { buffer = args.buf })
end,
})
<
*lsp-config*
To use other LSP features, set keymaps and other buffer options on
|LspAttach|. Not all language servers provide the same capabilities. Use
capability checks to ensure you only use features supported by the language
server. Example: >lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
if client.supports_method('textDocument/implementation') then
-- Create a keymap for vim.lsp.buf.implementation
end
if client.supports_method('textDocument/completion') then
-- Enable auto-completion
vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
end
if client.supports_method('textDocument/formatting') then
-- Format the current buffer on save
vim.api.nvim_create_autocmd('BufWritePre', {
buffer = args.buf,
callback = function()
vim.lsp.buf.format({bufnr = args.buf, id = client.id})
end,
})
end
end,
})
<
To learn what capabilities are available you can run the following command in
a buffer with a started LSP client: >vim
:lua =vim.lsp.get_clients()[1].server_capabilities
Full list of features provided by default can be found in |lsp-buf|.
================================================================================
FAQ *lsp-faq*
- Q: How to force-reload LSP?
- A: Stop all clients, then reload the buffer. >vim
:lua vim.lsp.stop_client(vim.lsp.get_clients())
:edit
- Q: Why isn't completion working?
- A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
"v:lua.vim.lsp.omnifunc": `:verbose set omnifunc?`
- Some other plugin may be overriding the option. To avoid that you could
set the option in an |after-directory| ftplugin, e.g.
"after/ftplugin/python.vim".
- Q: How do I run a request synchronously (e.g. for formatting on file save)?
- A: Check if the function has an `async` parameter and set the value to
false. E.g. code formatting: >vim
" Auto-format *.rs (rust) files prior to saving them
" (async = false is the default for format)
autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
<
*lsp-vs-treesitter*
- Q: How do LSP and Treesitter compare?
- A: LSP requires a client and language server. The language server uses
semantic analysis to understand code at a project level. This provides
language servers with the ability to rename across files, find
definitions in external libraries and more.
Treesitter is a language parsing library that provides excellent tools
for incrementally parsing text and handling errors. This makes it a great
fit for editors to understand the contents of the current file for things
like syntax highlighting, simple goto-definitions, scope analysis and
more.
LSP and Treesitter are both great tools for editing and inspecting code.
================================================================================
LSP API *lsp-api*
LSP core API is described at |lsp-core|. Those are the core functions for
creating and managing clients.
The `vim.lsp.buf_…` functions perform operations for all LSP clients attached
to the given buffer. |lsp-buf|
LSP request/response handlers are implemented as Lua functions (see
|lsp-handler|).
*lsp-method*
Requests and notifications defined by the LSP specification are referred to as
"LSP methods". The Nvim LSP client provides default handlers in the global
|vim.lsp.handlers| table, you can list them with this command: >vim
:lua vim.print(vim.tbl_keys(vim.lsp.handlers))
<
They are also listed below. Note that handlers depend on server support: they
won't run if your server doesn't support them.
- `'callHierarchy/incomingCalls'`
- `'callHierarchy/outgoingCalls'`
- `'textDocument/codeAction'`
- `'textDocument/completion'`
- `'textDocument/declaration'`
- `'textDocument/definition'`
- `'textDocument/diagnostic'`
- `'textDocument/documentHighlight'`
- `'textDocument/documentSymbol'`
- `'textDocument/foldingRange'`
- `'textDocument/formatting'`
- `'textDocument/hover'`
- `'textDocument/implementation'`
- `'textDocument/inlayHint'`
- `'textDocument/prepareTypeHierarchy'`
- `'textDocument/publishDiagnostics'`
- `'textDocument/rangeFormatting'`
- `'textDocument/rangesFormatting'`
- `'textDocument/references'`
- `'textDocument/rename'`
- `'textDocument/semanticTokens/full'`
- `'textDocument/semanticTokens/full/delta'`
- `'textDocument/signatureHelp'`
- `'textDocument/typeDefinition*'`
- `'typeHierarchy/subtypes'`
- `'typeHierarchy/supertypes'`
- `'window/logMessage'`
- `'window/showMessage'`
- `'window/showDocument'`
- `'window/showMessageRequest'`
- `'workspace/applyEdit'`
- `'workspace/configuration'`
- `'workspace/executeCommand'`
- `'workspace/inlayHint/refresh'`
- `'workspace/symbol'`
- `'workspace/workspaceFolders'`
*lsp-handler*
LSP handlers are functions that handle |lsp-response|s to requests made by Nvim
to the server. (Notifications, as opposed to requests, are fire-and-forget:
there is no response, so they can't be handled. |lsp-notification|)
Each response handler has this signature: >
function(err, result, ctx)
<
Parameters: ~
• {err} (`table|nil`) Error info dict, or `nil` if the request
completed.
• {result} (`Result|Params|nil`) `result` key of the |lsp-response| or
`nil` if the request failed.
• {ctx} (`table`) Table of calling state associated with the
handler, with these keys:
• {method} (`string`) |lsp-method| name.
• {client_id} (`number`) |vim.lsp.Client| identifier.
• {bufnr} (`Buffer`) Buffer handle.
• {params} (`table|nil`) Request parameters table.
• {version} (`number`) Document version at time of
request. Handlers can compare this to the
current document version to check if the
response is "stale". See also |b:changedtick|.
Returns: ~
Two values `result, err` where `err` is shaped like an RPC error: >
{ code, message, data? }
< You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
*lsp-handler-resolution*
Handlers can be set by (in increasing priority):
- Setting a field in vim.lsp.handlers. *vim.lsp.handlers*
`vim.lsp.handlers` is a global table that contains the default mapping of
|lsp-method| names to lsp-handlers.
Example: >lua
vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler
<
Note: this only applies for requests/notifications made by the
server to the client.
- The {handlers} parameter of |vim.lsp.start()|. This sets the default
|lsp-handler| for a specific server.
Example: >lua
vim.lsp.start {
..., -- Other configuration omitted.
handlers = {
['textDocument/publishDiagnostics'] = my_custom_server_definition
},
}
<
Note: this only applies for requests/notifications made by the
server to the client.
- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
the |lsp-handler| ONLY for the given request(s).
Example: >lua
vim.lsp.buf_request_all(
0,
'textDocument/publishDiagnostics',
my_request_params,
my_handler
)
<
*vim.lsp.log_levels*
Log levels are defined in |vim.log.levels|
VIM.LSP.PROTOCOL *vim.lsp.protocol*
Module `vim.lsp.protocol` defines constants dictated by the LSP specification,
and helper functions for creating protocol-related objects.
https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
name: >lua
vim.lsp.protocol.TextDocumentSyncKind.Full == 1
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
<
*lsp-response*
LSP response shape:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
*lsp-notification*
LSP notification shape:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
================================================================================
LSP HIGHLIGHT *lsp-highlight*
Reference Highlights:
Highlight groups that are meant to be used by |vim.lsp.buf.document_highlight()|.
You can see more about the differences in types here:
https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight
*hl-LspReferenceText*
LspReferenceText used for highlighting "text" references
*hl-LspReferenceRead*
LspReferenceRead used for highlighting "read" references
*hl-LspReferenceWrite*
LspReferenceWrite used for highlighting "write" references
*hl-LspReferenceTarget*
LspReferenceTarget used for highlighting reference targets (e.g. in a
hover range)
*hl-LspInlayHint*
LspInlayHint used for highlighting inlay hints
*lsp-highlight-codelens*
Highlight groups related to |lsp-codelens| functionality.
*hl-LspCodeLens*
LspCodeLens
Used to color the virtual text of the codelens. See
|nvim_buf_set_extmark()|.
LspCodeLensSeparator *hl-LspCodeLensSeparator*
Used to color the separator between two or more code lenses.
*lsp-highlight-signature*
Highlight groups related to |vim.lsp.handlers.signature_help()|.
*hl-LspSignatureActiveParameter*
LspSignatureActiveParameter
Used to highlight the active parameter in the signature help. See
|vim.lsp.handlers.signature_help()|.
------------------------------------------------------------------------------
LSP SEMANTIC HIGHLIGHTS *lsp-semantic-highlight*
When available, the LSP client highlights code using |lsp-semantic_tokens|,
which are another way that LSP servers can provide information about source
code. Note that this is in addition to treesitter syntax highlighting;
semantic highlighting does not replace syntax highlighting.
The server will typically provide one token per identifier in the source code.
The token will have a `type` such as "function" or "variable", and 0 or more
`modifier`s such as "readonly" or "deprecated." The standard types and
modifiers are described here:
https://microsoft.github.io/language-server-protocol/specification/#textDocument_semanticTokens
LSP servers may also use off-spec types and modifiers.
The LSP client adds one or more highlights for each token. The highlight
groups are derived from the token's type and modifiers:
• `@lsp.type.<type>.<ft>` for the type
• `@lsp.mod.<mod>.<ft>` for each modifier
• `@lsp.typemod.<type>.<mod>.<ft>` for each modifier
Use |:Inspect| to view the highlights for a specific token. Use |:hi| or
|nvim_set_hl()| to change the appearance of semantic highlights: >vim
hi @lsp.type.function guifg=Yellow " function names are yellow
hi @lsp.type.variable.lua guifg=Green " variables in lua are green
hi @lsp.mod.deprecated gui=strikethrough " deprecated is crossed out
hi @lsp.typemod.function.async guifg=Blue " async functions are blue
<
The value |vim.hl.priorities|`.semantic_tokens` is the priority of the
`@lsp.type.*` highlights. The `@lsp.mod.*` and `@lsp.typemod.*` highlights
have priorities one and two higher, respectively.
You can disable semantic highlights by clearing the highlight groups: >lua
-- Hide semantic highlights for functions
vim.api.nvim_set_hl(0, '@lsp.type.function', {})
-- Hide all semantic highlights
for _, group in ipairs(vim.fn.getcompletion("@lsp", "highlight")) do
vim.api.nvim_set_hl(0, group, {})
end
<
You probably want these inside a |ColorScheme| autocommand.
Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more
complex highlighting.
The following is a list of standard captures used in queries for Nvim,
highlighted according to the current colorscheme (use |:Inspect| on one to see
the exact definition):
@lsp.type.class Identifiers that declare or reference a class type
@lsp.type.comment Tokens that represent a comment
@lsp.type.decorator Identifiers that declare or reference decorators and annotations
@lsp.type.enum Identifiers that declare or reference an enumeration type
@lsp.type.enumMember Identifiers that declare or reference an enumeration property, constant, or member
@lsp.type.event Identifiers that declare an event property
@lsp.type.function Identifiers that declare a function
@lsp.type.interface Identifiers that declare or reference an interface type
@lsp.type.keyword Tokens that represent a language keyword
@lsp.type.macro Identifiers that declare a macro
@lsp.type.method Identifiers that declare a member function or method
@lsp.type.modifier Tokens that represent a modifier
@lsp.type.namespace Identifiers that declare or reference a namespace, module, or package
@lsp.type.number Tokens that represent a number literal
@lsp.type.operator Tokens that represent an operator
@lsp.type.parameter Identifiers that declare or reference a function or method parameters
@lsp.type.property Identifiers that declare or reference a member property, member field, or member variable
@lsp.type.regexp Tokens that represent a regular expression literal
@lsp.type.string Tokens that represent a string literal
@lsp.type.struct Identifiers that declare or reference a struct type
@lsp.type.type Identifiers that declare or reference a type that is not covered above
@lsp.type.typeParameter Identifiers that declare or reference a type parameter
@lsp.type.variable Identifiers that declare or reference a local or global variable
@lsp.mod.abstract Types and member functions that are abstract
@lsp.mod.async Functions that are marked async
@lsp.mod.declaration Declarations of symbols
@lsp.mod.defaultLibrary Symbols that are part of the standard library
@lsp.mod.definition Definitions of symbols, for example, in header files
@lsp.mod.deprecated Symbols that should no longer be used
@lsp.mod.documentation Occurrences of symbols in documentation
@lsp.mod.modification Variable references where the variable is assigned to
@lsp.mod.readonly Readonly variables and member fields (constants)
@lsp.mod.static Class members (static members)
==============================================================================
EVENTS *lsp-events*
LspAttach *LspAttach*
After an LSP client attaches to a buffer. The |autocmd-pattern| is the
name of the buffer. When used from Lua, the client ID is passed to the
callback in the "data" table. See |lsp-config| for an example.
LspDetach *LspDetach*
Just before an LSP client detaches from a buffer. The |autocmd-pattern|
is the name of the buffer. When used from Lua, the client ID is passed
to the callback in the "data" table. Example: >lua
vim.api.nvim_create_autocmd('LspDetach', {
callback = function(args)
-- Get the detaching client
local client = vim.lsp.get_client_by_id(args.data.client_id)
-- Remove the autocommand to format the buffer on save, if it exists
if client.supports_method('textDocument/formatting') then
vim.api.nvim_clear_autocmds({
event = 'BufWritePre',
buffer = args.buf,
})
end
end,
})
<
LspNotify *LspNotify*
This event is triggered after each successful notification sent to an
LSP server.
When used from Lua, the client_id, LSP method, and parameters are sent
in the "data" table. Example: >lua
vim.api.nvim_create_autocmd('LspNotify', {
callback = function(args)
local bufnr = args.buf
local client_id = args.data.client_id
local method = args.data.method
local params = args.data.params
-- do something with the notification
if method == 'textDocument/...' then
update_buffer(bufnr)
end
end,
})
<
LspProgress *LspProgress*
Upon receipt of a progress notification from the server. Notifications can
be polled from a `progress` ring buffer of a |vim.lsp.Client| or use
|vim.lsp.status()| to get an aggregate message.
If the server sends a "work done progress", the `pattern` is set to `kind`
(one of `begin`, `report` or `end`).
When used from Lua, the event contains a `data` table with `client_id` and
`params` properties. `params` will contain the request params sent by the
server (see `lsp.ProgressParams`).
Example: >vim
autocmd LspProgress * redrawstatus
<
LspRequest *LspRequest*
For each request sent to an LSP server, this event is triggered for
every change to the request's status. The status can be one of
`pending`, `complete`, or `cancel` and is sent as the {type} on the
"data" table passed to the callback function.
It triggers when the initial request is sent ({type} == `pending`) and
when the LSP server responds ({type} == `complete`). If a cancellation
is requested using `client.cancel_request(request_id)`, then this event
will trigger with {type} == `cancel`.
When used from Lua, the client ID, request ID, and request are sent in
the "data" table. See {requests} in |vim.lsp.Client| for details on the
{request} value. If the request type is `complete`, the request will be
deleted from the client's pending requests table immediately after
calling the event's callbacks. Example: >lua
vim.api.nvim_create_autocmd('LspRequest', {
callback = function(args)
local bufnr = args.buf
local client_id = args.data.client_id
local request_id = args.data.request_id
local request = args.data.request
if request.type == 'pending' then
-- do something with pending requests
track_pending(client_id, bufnr, request_id, request)
elseif request.type == 'cancel' then
-- do something with pending cancel requests
track_canceling(client_id, bufnr, request_id, request)
elseif request.type == 'complete' then
-- do something with finished requests. this pending
-- request entry is about to be removed since it is complete
track_finish(client_id, bufnr, request_id, request)
end
end,
})
<
LspTokenUpdate *LspTokenUpdate*
When a visible semantic token is sent or updated by the LSP server, or
when an existing token becomes visible for the first time. The
|autocmd-pattern| is the name of the buffer. When used from Lua, the
token and client ID are passed to the callback in the "data" table. The
token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|.
Example:
>lua
vim.api.nvim_create_autocmd('LspTokenUpdate', {
callback = function(args)
local token = args.data.token
if token.type == 'variable' and not token.modifiers.readonly then
vim.lsp.semantic_tokens.highlight_token(
token, args.buf, args.data.client_id, 'MyMutableVariableHighlight'
)
end
end,
})
<
Note: doing anything other than calling
|vim.lsp.semantic_tokens.highlight_token()| is considered experimental.
==============================================================================
Lua module: vim.lsp *lsp-core*
buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()*
Implements the `textDocument/did…` notifications required to track a
buffer for any language server.
Without calling this, the server won't be notified of changes to a buffer.
Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current
• {client_id} (`integer`) Client id
Return: ~
(`boolean`) success `true` if client was attached successfully;
`false` otherwise
buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()*
Detaches client from the specified buffer. Note: While the server is
notified that the text document (buffer) was closed, it is still able to
send notifications should it ignore this notification.
Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current
• {client_id} (`integer`) Client id
buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()*
Checks if a buffer is attached for a particular client.
Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current
• {client_id} (`integer`) the client id
buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()*
Send a notification to a server
Parameters: ~
• {bufnr} (`integer?`) The number of the buffer
• {method} (`string`) Name of the request method
• {params} (`any`) Arguments to send to the server
Return: ~
(`boolean`) success true if any client returns true; false otherwise
*vim.lsp.buf_request_all()*
buf_request_all({bufnr}, {method}, {params}, {handler})
Sends an async request for all active clients attached to the buffer and
executes the `handler` callback with the combined result.
Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current.
• {method} (`string`) LSP method name
• {params} (`table|(fun(client: vim.lsp.Client, bufnr: integer): table?)?`)
Parameters to send to the server. Can also be passed as a
function that returns the params table for cases where
parameters are specific to the client.
• {handler} (`function`) Handler called after all requests are
completed. Server results are passed as a
`client_id:result` map.
Return: ~
(`function`) cancel Function that cancels all requests.
*vim.lsp.buf_request_sync()*
buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
Sends a request to all server and waits for the response of all of them.
Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the
result. Parameters are the same as |vim.lsp.buf_request_all()| but the
result is different. Waits a maximum of {timeout_ms}.
Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current.
• {method} (`string`) LSP method name
• {params} (`table?`) Parameters to send to the server
• {timeout_ms} (`integer?`, default: `1000`) Maximum time in
milliseconds to wait for a result.
Return (multiple): ~
(`table<integer, {error: lsp.ResponseError?, result: any}>?`) result
Map of client_id:request_result.
(`string?`) err On timeout, cancel, or error, `err` is a string
describing the failure reason, and `result` is nil.
client_is_stopped({client_id}) *vim.lsp.client_is_stopped()*
Checks whether a client is stopped.
Parameters: ~
• {client_id} (`integer`)
Return: ~
(`boolean`) stopped true if client is stopped, false otherwise.
commands *vim.lsp.commands*
Registry for client side commands. This is an extension point for plugins
to handle custom commands which are not part of the core language server
protocol specification.
The registry is a table where the key is a unique command name, and the
value is a function which is called if any LSP action (code action, code
lenses, ...) triggers the command.
If a LSP response contains a command for which no matching entry is
available in this registry, the command will be executed via the LSP
server using `workspace/executeCommand`.
The first argument to the function will be the `Command`: Command title:
String command: String arguments?: any[]
The second argument is the `ctx` of |lsp-handler|
foldclose({kind}, {winid}) *vim.lsp.foldclose()*
Close all {kind} of folds in the the window with {winid}.
To automatically fold imports when opening a file, you can use an autocmd: >lua
vim.api.nvim_create_autocmd('LspNotify', {
callback = function(args)
if args.data.method == 'textDocument/didOpen' then
vim.lsp.foldclose('imports', vim.fn.bufwinid(args.buf))
end
end,
})
<
Parameters: ~
• {kind} (`lsp.FoldingRangeKind`) Kind to close, one of "comment",
"imports" or "region".
• {winid} (`integer?`) Defaults to the current window.
foldexpr({lnum}) *vim.lsp.foldexpr()*
Provides an interface between the built-in client and a `foldexpr`
function.
Parameters: ~
• {lnum} (`integer`) line number
foldtext() *vim.lsp.foldtext()*
Provides a `foldtext` function that shows the `collapsedText` retrieved,
defaults to the first folded line if `collapsedText` is not provided.
formatexpr({opts}) *vim.lsp.formatexpr()*
Provides an interface between the built-in client and a `formatexpr`
function.
Currently only supports a single client. This can be set via
`setlocal formatexpr=v:lua.vim.lsp.formatexpr()` or (more typically) in
`on_attach` via
`vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
Parameters: ~
• {opts} (`table?`) A table with the following fields:
• {timeout_ms} (`integer`, default: 500ms) The timeout period
for the formatting request..
*vim.lsp.get_buffers_by_client_id()*
get_buffers_by_client_id({client_id})
Returns list of buffers attached to client_id.
Parameters: ~
• {client_id} (`integer`) client id
Return: ~
(`integer[]`) buffers list of buffer ids
get_client_by_id({client_id}) *vim.lsp.get_client_by_id()*
Gets a client by id, or nil if the id is invalid. The returned client may
not yet be fully initialized.
Parameters: ~
• {client_id} (`integer`) client id
Return: ~
(`vim.lsp.Client?`) client rpc object
get_clients({filter}) *vim.lsp.get_clients()*
Get active clients.
Parameters: ~
• {filter} (`table?`) Key-value pairs used to filter the returned
clients.
• {id}? (`integer`) Only return clients with the given id
• {bufnr}? (`integer`) Only return clients attached to this
buffer
• {name}? (`string`) Only return clients with the given name
• {method}? (`string`) Only return clients supporting the
given method
Return: ~
(`vim.lsp.Client[]`) List of |vim.lsp.Client| objects
get_log_path() *vim.lsp.get_log_path()*
Gets the path of the logfile used by the LSP client.
Return: ~
(`string`) path to log file
omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
Implements 'omnifunc' compatible LSP completion.
Parameters: ~
• {findstart} (`integer`) 0 or 1, decides behavior
• {base} (`integer`) findstart=0, text to match against
Return: ~
(`integer|table`) Decided by {findstart}:
• findstart=0: column where the completion starts, or -2 or -3
• findstart=1: list of matches (actually just calls |complete()|)
See also: ~
• |complete-functions|
• |complete-items|
• |CompleteDone|
set_log_level({level}) *vim.lsp.set_log_level()*
Sets the global log level for LSP logging.
Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
Level numbers begin with "TRACE" at 0
Use `lsp.log_levels` for reverse lookup.
Parameters: ~
• {level} (`integer|string`) the case insensitive level name or number
See also: ~
• |vim.lsp.log_levels|
start({config}, {opts}) *vim.lsp.start()*
Create a new LSP client and start a language server or reuses an already
running client if one is found matching `name` and `root_dir`. Attaches
the current buffer to the client.
Example: >lua
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
root_dir = vim.fs.root(0, {'pyproject.toml', 'setup.py'}),
})
<
See |vim.lsp.start_client()| for all available options. The most important
are:
• `name` arbitrary name for the LSP client. Should be unique per language
server.
• `cmd` command string[] or function, described at
|vim.lsp.start_client()|.
• `root_dir` path to the project root. By default this is used to decide
if an existing client should be re-used. The example above uses
|vim.fs.root()| to detect the root by traversing the file system upwards
starting from the current directory until either a `pyproject.toml` or
`setup.py` file is found.
• `workspace_folders` list of `{ uri:string, name: string }` tables
specifying the project root folders used by the language server. If
`nil` the property is derived from `root_dir` for convenience.
Language servers use this information to discover metadata like the
dependencies of your project and they tend to index the contents within
the project folder.
To ensure a language server is only started for languages it can handle,
make sure to call |vim.lsp.start()| within a |FileType| autocmd. Either
use |:au|, |nvim_create_autocmd()| or put the call in a
`ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
Parameters: ~
• {config} (`vim.lsp.ClientConfig`) Configuration for the server. See
|vim.lsp.ClientConfig|.
• {opts} (`table?`) Optional keyword arguments
• {reuse_client}?
(`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`)
Predicate used to decide if a client should be re-used.
Used on all running clients. The default implementation
re-uses a client if name and root_dir matches.
• {bufnr}? (`integer`) Buffer handle to attach to if
starting or re-using a client (0 for current).
• {silent}? (`boolean`) Suppress error reporting if the LSP
server fails to start (default false).
Return: ~
(`integer?`) client_id
start_client({config}) *vim.lsp.start_client()*
Starts and initializes a client with the given configuration.
Parameters: ~
• {config} (`vim.lsp.ClientConfig`) Configuration for the server. See
|vim.lsp.ClientConfig|.
Return (multiple): ~
(`integer?`) client_id |vim.lsp.get_client_by_id()| Note: client may
not be fully initialized. Use `on_init` to do any actions once the
client has been initialized.
(`string?`) Error message, if any
status() *vim.lsp.status()*
Consumes the latest progress messages from all clients and formats them as
a string. Empty if there are no clients or if no new messages
Return: ~
(`string`)
stop_client({client_id}, {force}) *vim.lsp.stop_client()*
Stops a client(s).
You can also use the `stop()` function on a |vim.lsp.Client| object. To
stop all clients: >lua
vim.lsp.stop_client(vim.lsp.get_clients())
<
By default asks the server to shutdown, unless stop was requested already
for this client, then force-shutdown is attempted.
Parameters: ~
• {client_id} (`integer|integer[]|vim.lsp.Client[]`) id, list of id's,
or list of |vim.lsp.Client| objects
• {force} (`boolean?`) shutdown forcefully
tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()*
Provides an interface between the built-in client and 'tagfunc'.
When used with normal mode commands (e.g. |CTRL-]|) this will invoke the
"textDocument/definition" LSP method to find the tag under the cursor.
Otherwise, uses "workspace/symbol". If no results are returned from any
LSP servers, falls back to using built-in tags.
Parameters: ~
• {pattern} (`string`) Pattern used to find a workspace symbol
• {flags} (`string`) See |tag-function|
Return: ~
(`table[]`) tags A list of matching tags
==============================================================================
Lua module: vim.lsp.client *lsp-client*
*vim.lsp.Client*
Fields: ~
• {id} (`integer`) The id allocated to the client.
• {name} (`string`) If a name is specified on creation,
that will be used. Otherwise it is just the
client id. This is used for logs and messages.
• {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
object, for low level interaction with the
client. See |vim.lsp.rpc.start()|.
• {offset_encoding} (`string`) Called "position encoding" in LSP
spec, the encoding used for communicating with
the server. You can modify this in the
`config`'s `on_init` method before text is
sent to the server.
• {handlers} (`table<string,lsp.Handler>`) The handlers
used by the client as described in
|lsp-handler|.
• {requests} (`table<integer,{ type: string, bufnr: integer, method: string}>`)
The current pending requests in flight to the
server. Entries are key-value pairs with the
key being the request id while the value is a
table with `type`, `bufnr`, and `method`
key-value pairs. `type` is either "pending"
for an active request, or "cancel" for a
cancel request. It will be "complete"
ephemerally while executing |LspRequest|
autocmds when replies are received from the
server.
• {config} (`vim.lsp.ClientConfig`) copy of the table
that was passed by the user to
|vim.lsp.start_client()|. See
|vim.lsp.ClientConfig|.
• {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
server sent on `initialize` describing the
server's capabilities.
• {progress} (`vim.lsp.Client.Progress`) A ring buffer
(|vim.ringbuf()|) containing progress messages
sent by the server. See
|vim.lsp.Client.Progress|.
• {initialized} (`true?`)
• {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace
folders configured in the client when the
server starts. This property is only available
if the client supports workspace folders. It
can be `null` if the client supports workspace
folders but none are configured.
• {root_dir} (`string?`)
• {attached_buffers} (`table<integer,true>`)
• {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`)
Table of command name to function which is
called if any LSP action (code action, code
lenses, ...) triggers the command. Client
commands take precedence over the global
command registry.
• {settings} (`table`) Map with language server specific
settings. These are returned to the language
server if requested via
`workspace/configuration`. Keys are
case-sensitive.
• {flags} (`table`) A table with flags for the client.
The current (experimental) flags are:
• {allow_incremental_sync}? (`boolean`,
default: `true`) Allow using incremental
sync for buffer edits
• {debounce_text_changes} (`integer`, default:
`150`) Debounce `didChange` notifications to
the server by the given number in
milliseconds. No debounce occurs if `nil`.
• {exit_timeout} (`integer|false`, default:
`false`) Milliseconds to wait for server to
exit cleanly after sending the "shutdown"
request before sending kill -15. If set to
false, nvim exits immediately after sending