/
lsp.txt
1962 lines (1563 loc) · 89.9 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 the nvim-lspconfig plugin. It provides common configuration for
various servers so you can get started quickly.
https://github.com/neovim/nvim-lspconfig
2. Install a language server. A list of language servers can be found here:
https://microsoft.github.io/language-server-protocol/implementors/servers/
See individual server documentation for installation instructions.
3. Add `lua require('lspconfig').xx.setup{…}` to your init.vim, where "xx" is
the name of the relevant config. See the nvim-lspconfig README for details.
NOTE: Make sure to restart nvim after installing and configuring.
4. Check that an LSP client has attached to the current buffer: >
:lua print(vim.inspect(vim.lsp.buf_get_clients()))
<
*lsp-config*
Inline diagnostics are enabled automatically, e.g. syntax errors will be
annotated in the buffer. But you probably also want to use other features
like go-to-definition, hover, etc.
While Nvim does not provide an "auto-completion" framework by default, it is
still possible to get completions from the LSP server. To incorporate these
completions, it is recommended to use |vim.lsp.omnifunc|, which is an 'omnifunc'
handler. When 'omnifunc' is set to `v:lua.vim.lsp.omnifunc`, |i_CTRL-X_CTRL-O|
will provide completions from the language server.
Example config (in init.vim): >
lua << EOF
local custom_lsp_attach = function(client)
-- See `:help nvim_buf_set_keymap()` for more information
vim.api.nvim_buf_set_keymap(0, 'n', 'K', '<cmd>lua vim.lsp.buf.hover()<CR>', {noremap = true})
vim.api.nvim_buf_set_keymap(0, 'n', '<c-]>', '<cmd>lua vim.lsp.buf.definition()<CR>', {noremap = true})
-- ... and other keymappings for LSP
-- Use LSP as the handler for omnifunc.
-- See `:help omnifunc` and `:help ins-completion` for more information.
vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.vim.lsp.omnifunc')
-- Use LSP as the handler for formatexpr.
-- See `:help formatexpr` for more information.
vim.api.nvim_buf_set_option(0, 'formatexpr', 'v:lua.vim.lsp.formatexpr()')
-- For plugins with an `on_attach` callback, call them here. For example:
-- require('completion').on_attach()
end
-- An example of configuring for `sumneko_lua`,
-- a language server for Lua.
-- set the path to the sumneko installation
local system_name = "Linux" -- (Linux, macOS, or Windows)
local sumneko_root_path = '/path/to/lua-language-server'
local sumneko_binary = sumneko_root_path.."/bin/"..system_name.."/lua-language-server"
require('lspconfig').sumneko_lua.setup({
cmd = {sumneko_binary, "-E", sumneko_root_path .. "/main.lua"};
-- An example of settings for an LSP server.
-- For more options, see nvim-lspconfig
settings = {
Lua = {
runtime = {
-- Tell the language server which version of Lua you're using (most likely LuaJIT in the case of Neovim)
version = 'LuaJIT',
-- Setup your lua path
path = vim.split(package.path, ';'),
},
diagnostics = {
-- Get the language server to recognize the `vim` global
globals = {'vim'},
},
workspace = {
-- Make the server aware of Neovim runtime files
library = {
[vim.fn.expand('$VIMRUNTIME/lua')] = true,
[vim.fn.expand('$VIMRUNTIME/lua/vim/lsp')] = true,
},
},
}
},
on_attach = custom_lsp_attach
})
EOF
<
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. >
:lua vim.lsp.stop_client(vim.lsp.get_active_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: Use the `_sync` variant of the function provided by |lsp-buf|, if it
exists.
E.g. code formatting: >
" Auto-format *.rs (rust) files prior to saving them
autocmd BufWritePre *.rs lua vim.lsp.buf.formatting_sync(nil, 1000)
<
*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|). The |vim.lsp.handlers| table defines default handlers used
when creating a new client. Keys are LSP method names: >
:lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
<
*lsp-method*
Methods are the names of requests and notifications as defined by the LSP
specification. These LSP requests/notifications are defined by default:
callHierarchy/incomingCalls
callHierarchy/outgoingCalls
textDocument/codeAction
textDocument/completion
textDocument/declaration*
textDocument/definition
textDocument/documentHighlight
textDocument/documentSymbol
textDocument/formatting
textDocument/hover
textDocument/implementation*
textDocument/publishDiagnostics
textDocument/rangeFormatting
textDocument/references
textDocument/rename
textDocument/signatureHelp
textDocument/typeDefinition*
window/logMessage
window/showMessage
window/showMessageRequest
workspace/applyEdit
workspace/symbol
* NOTE: These are sometimes not implemented by servers.
*lsp-handler*
lsp-handlers are functions with special signatures that are designed to handle
responses and notifications from LSP servers.
For |lsp-request|, each |lsp-handler| has this signature: >
function(err, result, ctx, config)
<
Parameters: ~
{err} (table|nil)
When the language server is unable to complete a
request, a table with information about the error
is sent. Otherwise, it is `nil`. See |lsp-response|.
{result} (Result | Params | nil)
When the language server is able to successfully
complete a request, this contains the `result` key
of the response. See |lsp-response|.
{ctx} (table)
Context describes additional calling state
associated with the handler. It consists of the
following key, value pairs:
{method} (string)
The |lsp-method| name.
{client_id} (number)
The ID of the |vim.lsp.client|.
{bufnr} (Buffer)
Buffer handle, or 0 for current.
{params} (table|nil)
The parameters used in the original request
which resulted in this handler
call.
{config} (table)
Configuration for the handler.
Each handler can define its own configuration
table that allows users to customize the behavior
of a particular handler.
To configure a particular |lsp-handler|, see:
|lsp-handler-configuration|
Returns: ~
The |lsp-handler| can respond by returning two values: `result, err`
Where `err` must be shaped like an RPC error:
`{ code, message, data? }`
You can use |vim.lsp.rpc_response_error()| to create this object.
For |lsp-notification|, each |lsp-handler| has this signature: >
function(err, result, ctx, config)
<
Parameters: ~
{err} (nil)
This is always `nil`.
See |lsp-notification|
{result} (Result)
This contains the `params` key of the notification.
See |lsp-notification|
{ctx} (table)
Context describes additional calling state
associated with the handler. It consists of the
following key, value pairs:
{method} (string)
The |lsp-method| name.
{client_id} (number)
The ID of the |vim.lsp.client|.
{config} (table)
Configuration for the handler.
Each handler can define its own configuration
table that allows users to customize the behavior
of a particular handler.
For an example, see:
|vim.lsp.diagnostic.on_publish_diagnostics()|
To configure a particular |lsp-handler|, see:
|lsp-handler-configuration|
Returns: ~
The |lsp-handler|'s return value will be ignored.
*lsp-handler-configuration*
To configure the behavior of a builtin |lsp-handler|, the convenient method
|vim.lsp.with()| is provided for users.
To configure the behavior of |vim.lsp.diagnostic.on_publish_diagnostics()|,
consider the following example, where a new |lsp-handler| is created using
|vim.lsp.with()| that no longer generates signs for the diagnostics: >
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Disable signs
signs = false,
}
)
<
To enable signs, use |vim.lsp.with()| again to create and assign a new
|lsp-handler| to |vim.lsp.handlers| for the associated method: >
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Enable signs
signs = true,
}
)
<
To configure a handler on a per-server basis, you can use the {handlers} key
for |vim.lsp.start_client()| >
vim.lsp.start_client {
..., -- Other configuration omitted.
handlers = {
["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Disable virtual_text
virtual_text = false,
}
},
}
<
or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`: >
require('lspconfig').rust_analyzer.setup {
handlers = {
["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Disable virtual_text
virtual_text = false
}
),
}
}
<
Some handlers do not have an explicitly named handler function (such as
|on_publish_diagnostics()|). To override these, first create a reference
to the existing handler: >
local on_references = vim.lsp.handlers["textDocument/references"]
vim.lsp.handlers["textDocument/references"] = vim.lsp.with(
on_references, {
-- Use location list instead of quickfix list
loclist = true,
}
)
<
*lsp-handler-resolution*
Handlers can be set by:
- 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|.
To override the handler for the `"textDocument/definition"` method: >
vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
<
- The {handlers} parameter for |vim.lsp.start_client|.
This will set the |lsp-handler| as the default handler for this server.
For example: >
vim.lsp.start_client {
..., -- Other configuration omitted.
handlers = {
["textDocument/definition"] = my_custom_server_definition
},
}
- The {handler} parameter for |vim.lsp.buf_request()|.
This will set the |lsp-handler| ONLY for the current request.
For example: >
vim.lsp.buf_request(
0,
"textDocument/definition",
definition_params,
my_request_custom_definition
)
<
In summary, the |lsp-handler| will be chosen based on the current |lsp-method|
in the following order:
1. Handler passed to |vim.lsp.buf_request()|, if any.
2. Handler defined in |vim.lsp.start_client()|, if any.
3. Handler defined in |vim.lsp.handlers|, if any.
*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: >
vim.lsp.protocol.TextDocumentSyncKind.Full == 1
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
<
*lsp-response*
For the format of the response message, see:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
*lsp-notification*
For the format of the notification message, see:
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
*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 lens.
*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()|.
==============================================================================
EVENTS *lsp-events*
LspProgressUpdate *LspProgressUpdate*
Upon receipt of a progress notification from the server. See
|vim.lsp.util.get_progress_messages()|.
LspRequest *LspRequest*
After a change to the active set of pending LSP requests. See {requests}
in |vim.lsp.client|.
Example: >
autocmd User LspProgressUpdate redrawstatus
autocmd User LspRequest redrawstatus
<
==============================================================================
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} (number) Buffer handle, or 0 for current
{client_id} (number) Client id
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} number Buffer handle, or 0 for current
{client_id} number Client id
buf_get_clients({bufnr}) *vim.lsp.buf_get_clients()*
Gets a map of client_id:client pairs for the given buffer,
where each value is a |vim.lsp.client| object.
Parameters: ~
{bufnr} (optional, number): Buffer handle, or 0 for
current
buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()*
Checks if a buffer is attached for a particular client.
Parameters: ~
{bufnr} (number) Buffer handle, or 0 for current
{client_id} (number) the client id
buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()*
Send a notification to a server
Parameters: ~
{bufnr} [number] (optional): The number of the buffer
{method} [string]: Name of the request method
{params} [string]: Arguments to send to the server
Return: ~
true if any client returns true; false otherwise
*vim.lsp.buf_request()*
buf_request({bufnr}, {method}, {params}, {handler})
Sends an async request for all active clients attached to the
buffer.
Parameters: ~
{bufnr} (number) Buffer handle, or 0 for current.
{method} (string) LSP method name
{params} (optional, table) Parameters to send to the
server
{handler} (optional, function) See |lsp-handler| If nil,
follows resolution strategy defined in
|lsp-handler-configuration|
Return: ~
2-tuple:
• Map of client-id:request-id pairs for all successful
requests.
• Function which can be used to cancel all the requests.
You could instead iterate all clients and call their
`cancel_request()` methods.
*vim.lsp.buf_request_all()*
buf_request_all({bufnr}, {method}, {params}, {callback})
Sends an async request for all active clients attached to the
buffer. Executes the callback on the combined result.
Parameters are the same as |vim.lsp.buf_request()| but the
return result and callback are different.
Parameters: ~
{bufnr} (number) Buffer handle, or 0 for current.
{method} (string) LSP method name
{params} (optional, table) Parameters to send to the
server
{callback} (function) The callback to call when all
requests are finished.
Return: ~
(function) A function that will cancel all requests which
is the same as the one returned from `buf_request` .
*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()| but the return result is different.
Wait maximum of {timeout_ms} (default 1000) ms.
Parameters: ~
{bufnr} (number) Buffer handle, or 0 for current.
{method} (string) LSP method name
{params} (optional, table) Parameters to send to the
server
{timeout_ms} (optional, number, default=1000) Maximum
time in milliseconds to wait for a result.
Return: ~
Map of client_id:request_result. On timeout, cancel or
error, returns `(nil, err)` where `err` is a string
describing the failure reason.
client() *vim.lsp.client*
LSP client object. You can get an active client object via
|vim.lsp.get_client_by_id()| or
|vim.lsp.get_active_clients()|.
• Methods:
• request(method, params, [handler], bufnr) Sends a request
to the server. This is a thin wrapper around
{client.rpc.request} with some additional checking. If
{handler} is not specified, If one is not found there,
then an error will occur. Returns: {status},
{[client_id]}. {status} is a boolean indicating if the
notification was successful. If it is `false` , then it
will always be `false` (the client has shutdown). If
{status} is `true` , the function returns {request_id} as
the second result. You can use this with
`client.cancel_request(request_id)` to cancel the request.
• request_sync(method, params, timeout_ms, bufnr) Sends a
request to the server and synchronously waits for the
response. This is a wrapper around {client.request}
Returns: { err=err, result=result }, a dictionary, where
`err` and `result` come from the |lsp-handler|. On
timeout, cancel or error, returns `(nil, err)` where `err`
is a string describing the failure reason. If the request
was unsuccessful returns `nil` .
• notify(method, params) Sends a notification to an LSP
server. Returns: a boolean to indicate if the notification
was successful. If it is false, then it will always be
false (the client has shutdown).
• cancel_request(id) Cancels a request with a given request
id. Returns: same as `notify()` .
• stop([force]) Stops a client, optionally with force. By
default, it will just ask the server to shutdown without
force. If you request to stop a client which has
previously been requested to shutdown, it will
automatically escalate and force shutdown.
• is_stopped() Checks whether a client is stopped. Returns:
true if the client is fully stopped.
• on_attach(client, bufnr) Runs the on_attach function from
the client's config if it was defined. Useful for
buffer-local setup.
• Members
• {id} (number): 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} (table): RPC client object, for low level
interaction with the client. See |vim.lsp.rpc.start()|.
• {offset_encoding} (string): 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): The handlers used by the client as
described in |lsp-handler|.
• {requests} (table): 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.
• {config} (table): copy of the table that was passed by the
user to |vim.lsp.start_client()|.
• {server_capabilities} (table): Response from the server
sent on `initialize` describing the server's capabilities.
• {resolved_capabilities} (table): Normalized table of
capabilities that we have detected based on the initialize
response from the server in `server_capabilities` .
client_is_stopped({client_id}) *vim.lsp.client_is_stopped()*
Checks whether a client is stopped.
Parameters: ~
{client_id} (Number)
Return: ~
true if client is stopped, false otherwise.
*vim.lsp.for_each_buffer_client()*
for_each_buffer_client({bufnr}, {fn})
Invokes a function for each LSP client attached to a buffer.
Parameters: ~
{bufnr} number Buffer number
{fn} function Function to run on each client attached
to buffer {bufnr}. The function takes the client,
client ID, and buffer number as arguments.
Example: >
vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
print(vim.inspect(client))
end)
<
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()` but will typically or in `on_attach` via vim.api.nvim_buf_set_option(bufnr, 'formatexpr , 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`.
Parameters: ~
{opts} table options for customizing the formatting
expression which takes the following optional
keys:
• timeout_ms (default 500ms). The timeout period
for the formatting request.
get_active_clients() *vim.lsp.get_active_clients()*
Gets all active clients.
Return: ~
Table of |vim.lsp.client| objects
*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} number client id
Return: ~
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} number client id
Return: ~
|vim.lsp.client| object, or nil
get_log_path() *vim.lsp.get_log_path()*
Gets the path of the logfile used by the LSP client.
Return: ~
(String) Path to logfile.
omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
Implements 'omnifunc' compatible LSP completion.
Parameters: ~
{findstart} 0 or 1, decides behavior
{base} If findstart=0, text to match against
Return: ~
(number) 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"
Level numbers begin with "trace" at 0
Use `lsp.log_levels` for reverse lookup.
Parameters: ~
{level} [number|string] the case insensitive level name
or number
See also: ~
|vim.lsp.log_levels|
start_client({config}) *vim.lsp.start_client()*
Starts and initializes a client with the given configuration.
Parameter `cmd` is required.
The following parameters describe fields in the {config}
table.
Parameters: ~
{cmd} (required, string or list treated
like |jobstart()|) Base command that
initiates the LSP client.
{cmd_cwd} (string, default=|getcwd()|)
Directory to launch the `cmd`
process. Not related to `root_dir` .
{cmd_env} (table) Environment flags to pass to
the LSP on spawn. Can be specified
using keys like a map or as a list
with `k=v` pairs or both. Non-string values are
coerced to string. Example: >
{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
<
{workspace_folders} (table) List of workspace folders
passed to the language server. For
backwards compatibility rootUri and
rootPath will be derived from the
first workspace folder in this list.
See `workspaceFolders` in the LSP
spec.
{capabilities} Map overriding the default
capabilities defined by
|vim.lsp.protocol.make_client_capabilities()|,
passed to the language server on
initialization. Hint: use
make_client_capabilities() and modify
its result.
• Note: To send an empty dictionary
use
`{[vim.type_idx]=vim.types.dictionary}`
, else it will be encoded as an
array.
{handlers} Map of language server method names
to |lsp-handler|
{settings} Map with language server specific
settings. These are returned to the
language server if requested via
`workspace/configuration` . Keys are
case-sensitive.
{commands} table Table that maps string of
clientside commands to user-defined
functions. Commands passed to
start_client take precedence over the
global command registry. Each key
must be a unique command name, and
the value is a function which is
called if any LSP action (code
action, code lenses, ...) triggers
the command.
{init_options} Values to pass in the initialization
request as `initializationOptions` .
See `initialize` in the LSP spec.
{name} (string, default=client-id) Name in
log messages.
{get_language_id} function(bufnr, filetype) -> language
ID as string. Defaults to the
filetype.
{offset_encoding} (default="utf-16") One of "utf-8",
"utf-16", or "utf-32" which is the
encoding that the LSP server expects.
Client does not verify this is
correct.
{on_error} Callback with parameters (code, ...),
invoked when the client operation
throws an error. `code` is a number
describing the error. Other arguments
may be passed depending on the error
kind. See |vim.lsp.rpc.client_errors|
for possible errors. Use
`vim.lsp.rpc.client_errors[code]` to
get human-friendly name.
{before_init} Callback with parameters
(initialize_params, config) invoked
before the LSP "initialize" phase,
where `params` contains the
parameters being sent to the server
and `config` is the config that was
passed to |vim.lsp.start_client()|.
You can use this to modify parameters
before they are sent.
{on_init} Callback (client, initialize_result)
invoked after LSP "initialize", where
`result` is a table of `capabilities`
and anything else the server may
send. For example, clangd sends
`initialize_result.offsetEncoding` if
`capabilities.offsetEncoding` was
sent to it. You can only modify the
`client.offset_encoding` here before
any notifications are sent. Most
language servers expect to be sent
client specified settings after
initialization. Neovim does not make
this assumption. A
`workspace/didChangeConfiguration`
notification should be sent to the
server during on_init.
{on_exit} Callback (code, signal, client_id)
invoked on client exit.
• code: exit code of the process
• signal: number describing the
signal used to terminate (if any)
• client_id: client handle
{on_attach} Callback (client, bufnr) invoked when
client attaches to a buffer.
{trace} "off" | "messages" | "verbose" | nil
passed directly to the language
server in the initialize request.
Invalid/empty values will default to
"off"
{flags} A table with flags for the client.
The current (experimental) flags are:
• allow_incremental_sync (bool,
default true): Allow using
incremental sync for buffer edits
• debounce_text_changes (number,
default 150): Debounce didChange
notifications to the server by the
given number in milliseconds. No
debounce occurs if set to 0.
• exit_timeout (number, default 500):
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 the
'shutdown' request to the server.
{root_dir} string Directory where the LSP server
will base its workspaceFolders,
rootUri, and rootPath on
initialization.
Return: ~
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.
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:
>
vim.lsp.stop_client(vim.lsp.get_active_clients())
<
By default asks the server to shutdown, unless stop was
requested already for this client, then force-shutdown is
attempted.
Parameters: ~
{client_id} client id or |vim.lsp.client| object, or list
thereof
{force} boolean (optional) shutdown forcefully
tagfunc({...}) *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} Pattern used to find a workspace symbol
{flags} See |tag-function|
Return: ~
A list of matching tags
with({handler}, {override_config}) *vim.lsp.with()*
Function to manage overriding defaults for LSP handlers.
Parameters: ~
{handler} (function) See |lsp-handler|
{override_config} (table) Table containing the keys to
override behavior of the {handler}
==============================================================================
Lua module: vim.lsp.buf *lsp-buf*
*vim.lsp.buf.add_workspace_folder()*
add_workspace_folder({workspace_folder})
Add the folder at path to the workspace folders. If {path} is
not provided, the user will be prompted for a path using
|input()|.
clear_references() *vim.lsp.buf.clear_references()*
Removes document highlights from current buffer.
code_action({context}) *vim.lsp.buf.code_action()*
Selects a code action available at the current cursor
position.
Parameters: ~
{context} table|nil `CodeActionContext` of the LSP specification:
• diagnostics: (table|nil) LSP`Diagnostic[]` . Inferred from the current position if not
provided.
• only: (string|nil) LSP `CodeActionKind` used
to filter the code actions. Most language
servers support values like `refactor` or
`quickfix` .
See also: ~
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
completion({context}) *vim.lsp.buf.completion()*
Retrieves the completion items at the current cursor position.
Can only be called in Insert mode.
Parameters: ~
{context} (context support not yet implemented)
Additional information about the context in
which a completion was triggered (how it was
triggered, and by which trigger character, if
applicable)
See also: ~
|vim.lsp.protocol.constants.CompletionTriggerKind|
declaration() *vim.lsp.buf.declaration()*
Jumps to the declaration of the symbol under the cursor.
Note: