1 *lsp.txt* Language Server Protocol (LSP) Plugin for Vim9
4 Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com)
5 For Vim version 9.0 and above
6 Last change: July 26, 2023
8 ==============================================================================
9 CONTENTS *lsp-contents*
11 1. Overview ................................. |lsp-overview|
12 2. Requirements ............................. |lsp-installation|
13 3. Usage .................................... |lsp-usage|
14 4. Configuration............................. |lsp-configuration|
15 5. Commands ................................. |lsp-commands|
16 6. Insert Mode Completion ................... |lsp-ins-mode-completion|
17 7. Diagnostics .............................. |lsp-diagnostics|
18 8. Tag Function ............................. |lsp-tagfunc|
19 9. LSP Formatting ........................... |lsp-format|
20 10. Call Hierarchy ........................... |lsp-call-hierarchy|
21 11. Autocommands ............................. |lsp-autocmds|
22 12. Highlight Groups ......................... |lsp-highlight-groups|
23 13. Debugging ................................ |lsp-debug|
24 14. Custom Command Handlers .................. |lsp-custom-commands|
25 15. Custom LSP Completion Kinds .............. |lsp-custom-kinds|
26 16. Multiple Language Servers for a buffer ... |lsp-multiple-servers|
27 17. Language Servers Features ................ |lsp-features|
28 18. License .................................. |lsp-license|
30 ==============================================================================
31 1. Overview *lsp-overview*
33 The Language Server Protocol (LSP) plugin implements a LSP client for Vim9.
34 Refer to the following pages for more information about LSP:
36 https://microsoft.github.io/language-server-protocol/
37 https://langserver.org/
39 This plugin needs Vim version 9.0 and after. You will need a programming
40 language specific server in your system to use this plugin. Refer to the above
41 pages for a list of available language servers for the various programming
44 The Github repository for this plugin is available at:
46 http://github.com/yegappan/lsp
48 ==============================================================================
49 2. Installation *lsp-installation*
51 You can install this plugin directly from github using the following steps:
53 $ mkdir -p $HOME/.vim/pack/downloads/opt
54 $ cd $HOME/.vim/pack/downloads/opt
55 $ git clone https://github.com/yegappan/lsp
57 or you can use any one of the Vim plugin managers (dein.vim, pathogen, vam,
58 vim-plug, volt, Vundle, etc.) to install and manage this plugin.
60 To uninstall the LSP plugin, either use the uninstall command provided by the
61 plugin manager or manually remove the $HOME/.vim/pack/downloads/lsp directory.
63 To use this plugin, add the following line to your .vimrc file:
67 ==============================================================================
70 The following commands are provided:
72 :LspCodeAction Apply the code action supplied by the language server
73 to the diagnostic in the current line.
74 :LspCodeLens Display all the code lens commands available for the
75 current file and apply the selected command.
76 :LspDiag current Display the diagnostic message for the current line.
77 :LspDiag first Jump to the first diagnostic message for the current
79 :LspDiag here Jump to the next diagnostic message in the current
81 :LspDiag highlight disable
82 Disable highlighting lines with a diagnostic message
83 for the current Vim session.
84 :LspDiag highlight enable
85 Enable highlighting lines with a diagnostic message
86 for the current Vim session.
87 :LspDiag last Jump to the last diagnostic message for the current
89 :LspDiag next Jump to the next diagnostic message for the current
90 buffer after the current cursor position.
91 :LspDiag prev Jump to the previous diagnostic message for the
92 current buffer before the current current position.
93 :LspDiag show Display the diagnostics messages from the language
94 server for the current buffer in a location list.
95 :LspDocumentSymbol Display the symbols in the current file in a popup
96 menu and jump to the location of a selected symbol.
97 :LspFold Fold the current file
98 :LspFormat Format a range of lines in the current file using the
99 language server. The default range is the entire
100 file. See |lsp-format| for more information.
101 :LspGotoDeclaration Go to the declaration of the symbol under cursor
102 :LspGotoDefinition Go to the definition of the symbol under cursor
103 :LspGotoImpl Go to the implementation of the symbol under cursor
104 :LspGotoTypeDef Go to the type definition of the symbol under cursor
105 :LspHighlight Highlight all the matches for the keyword under cursor
106 :LspHighlightClear Clear all the matches highlighted by :LspHighlight
107 :LspHover Show the documentation for the symbol under the cursor
109 :LspIncomingCalls Display the list of symbols calling the current symbol
111 :LspInlayHints Enable or disable inlay hints.
112 :LspOutgoingCalls Display the list of symbols called by the current
114 :LspOutline Show the list of symbols defined in the current file
115 in a separate window.
116 :LspPeekDeclaration Open the declaration of the symbol under cursor in a
118 :LspPeekDefinition Open the definition of the symbol under cursor in a
120 :LspPeekImpl Open the implementation of the symbol under cursor in
122 :LspPeekReferences Display the list of references to the symbol under
123 cursor in a popup window.
124 :LspPeekTypeDef Open the type definition of the symbol under cursor in
126 :LspRename Rename the current symbol
127 :LspSelectionExpand Expand the current symbol range visual selection
128 :LspSelectionShrink Shrink the current symbol range visual selection
129 :LspServer Command to display the status and messages from a
130 language server and to restart the language server.
131 :LspShowAllServers Display the status of all the registered language
133 :LspShowReferences Display the list of references to the keyword under
134 cursor in a new location list.
135 :LspShowSignature Display the signature of the symbol under cursor.
136 :LspSubTypeHierarchy Display the sub type hierarchy in a popup window.
137 :LspSuperTypeHierarchy Display the super type hierarchy in a popup window.
138 :LspSwitchSourceHeader Switch between a source and a header file.
139 :LspSymbolSearch Perform a workspace wide search for a symbol
140 :LspWorkspaceAddFolder {folder}
141 Add a folder to the workspace
142 :LspWorkspaceListFolders
143 Show the list of folders in the workspace
144 :LspWorkspaceRemoveFolder {folder}
145 Remove a folder from the workspace
147 ==============================================================================
148 4. Configuration *lsp-configuration*
149 *LspAddServer()* *g:LspAddServer()*
151 To use the plugin features with a particular file type(s), you need to first
152 register a language server for that file type(s).
154 To register one or more language servers, use the LspAddServer() function with
155 a list of lanaguge server details in the .vimrc file.
157 To register a language server, add the following lines to your .vimrc file
158 (use only the language servers that you need from the below list).
159 If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the
160 LSP plugin, the steps are described later in this section: >
165 name: 'typescriptls',
166 filetype: ['javascript', 'typescript'],
167 path: '/usr/local/bin/typescript-language-server',
173 path: '/usr/local/bin/pyls',
174 args: ['--check-parent-process', '-v']
177 LspAddServer(lspServers)
179 Depending on the location of the typescript and python pyls language servers
180 installed in your system, update the "path" in the above snippet
183 Another example, for adding the language servers for the C, C++, Golang, Rust,
184 Shell script, Vim script and PHP file types: >
190 filetype: ['c', 'cpp'],
191 path: '/usr/local/bin/clangd',
192 args: ['--background-index']
196 filetype: ['go', 'gomod', 'gohtmltmpl', 'gotexttmpl'],
197 path: '/path/to/.go/bin/gopls',
204 path: '/path/to/.cargo/bin/rust-analyzer',
211 path: '/usr/local/bin/bash-language-server',
217 path: '/usr/local/bin/vim-language-server',
223 path': '/usr/local/bin/intelephense',
226 initializationOptions: {
227 licenceKey: 'xxxxxxxxxxxxxxx'
231 LspAddServer(lspServers)
233 To add a language server, the following information is needed:
236 name (Optional) name of the language server. Can by any
237 string. Used in LSP messages and log files.
239 path complete path to the language server executable
240 (without any arguments).
242 args a |List| of command-line arguments passed to the
243 language server. Each space separated language server
244 command-line argument is a separate List item.
246 filetype One or more file types supported by the language
247 server. This can be a |String| or a |List|. To
248 specify multiple file types, use a List.
249 *lsp-cfg-initializationOptions*
250 initializationOptions
251 (Optional) for lsp servers (e.g. intelephense) some
252 additional initialization options may be required
253 or useful for initialization. Those can be provided in
254 this dictionary and if present will be transmitted to
256 *lsp-cfg-workspaceConfig*
257 workspaceConfig (Optional) a json encodable value that will be sent to
258 the language server after initialization as the
259 "settings" in a "workspace/didChangeConfiguration"
260 notification. Refer to the language server
261 documentation for the values that will be accepted in
262 this notification. This configuration is also used to
263 respond to the "workspace/configuration" request
264 message from the language server.
266 rootSearch (Optional) a List of file and directory names used to
267 locate the root path or uri of the workspace. The
268 directory names in "rootSearch" must end in "/" or
269 "\". Each file and directory name in "rootSearch" is
270 searched upwards in all the parent directories. If
271 multiple directories are found, then the directory
272 closest to the directory of the current buffer is used
273 as the workspace root.
275 If this parameter is not specified or the files are
276 not found, then the current working directory is used
277 as the workspace root for decendent files, for any
278 other files the parent directory of the file is used.
280 *lsp-cfg-runIfSearch*
281 runIfSearch (Optional) a List of file and directory names used to
282 determinate if a server should run or not. The
283 directory names in "runIfSearch" must end in "/" or
284 "\". Each file and directory name in "runIfSearch" is
285 searched upwards in all the parent directories.
286 Exactly like |lsp-cfg-rootSearch|.
288 If a file or directory is found then the server will
289 be started, otherwise it will not.
291 If this parameter is not specified or is an empty
292 list, then the server will be started unless
293 |lsp-cfg-runUnlessSearch| prevents it.
295 *lsp-cfg-runUnlessSearch*
296 runUnlessSearch (Optional) Opposite of |lsp-cfg-runIfSearch|.
298 Additionally the following configurations can be made:
300 *lsp-cfg-customNotificationHandlers*
301 customNotificationHandlers
302 (Optional) some lsp servers (e.g.
303 typescript-language-server) will send additional
304 notifications which you might want to silence or
305 handle. The provided notification handlers will be
306 called with a reference to the "lspserver" and the
311 filetype: ['javascript', 'typescript'],
312 path: '/usr/local/bin/typescript-language-server',
314 customNotificationHandlers: {
315 '$/typescriptVersion': (lspserver, reply) => {
316 echom printf("TypeScript Version = %s",
317 reply.params.version)
322 *lsp-cfg-customRequestHandlers*
323 customRequestHandlers
324 (Optional) some lsp servers will send additional
325 request replies which you might want to silence or
326 handle. The provided request handlers will be called
327 with a reference to the "lspserver" and the "request".
329 features *lsp-cfg-features*
330 (Optional) toggle which features should be enabled for
331 a given language server. See |lsp-multiple-servers|
332 and |lsp-features| for more information.
334 forceOffsetEncoding *lsp-cfg-forceOffsetEncoding*
335 (Optional) a |String| value that forces the use of a
336 specific offset encoding in LSP messages. If this
337 option is not specified, then the UTF offset encoding
338 is negotiated with the server during initialization.
339 Supported values are 'utf-8' or 'utf-16' or 'utf-32'.
340 The Vim native offset encoding is 'utf-32'. For the
341 'utf-8' and 'utf-16' encodings, the offsets need to be
342 encoded and decoded in every LSP message and will
346 omnicompl (Optional) a boolean value that enables (true)
347 or disables (false) omni-completion for these file
348 types. By default this is set to "v:true". This value
349 is applicable only if auto completion is disabled
350 (|lsp-opt-autoComplete|).
352 *lsp-cfg-processDiagHandler*
354 (Optional) A |Funcref| or |lambda| that takes a list
355 of language server diagnostics and returns a new list
356 of filtered, or otherwise changed diagnostics. Can be
357 used to remove unwanted diagnostics, prefix the
358 diagnostics text, etc. The following example will
359 remove all but errors and warnings: >
363 filetype: ['javascript', 'typescript'],
364 path: '/usr/local/bin/typescript-language-server',
366 processDiagHandler: (diags: list<dict<any>>) => {
367 # Only include errors and warnings
368 return diags->filter((diag, ix) => {
369 return diag.severity <= 2
374 And this example will prefix the diagnostic message
375 with the string "TypeScript: ": >
379 filetype: ['javascript', 'typescript'],
380 path: '/usr/local/bin/typescript-language-server',
382 processDiagHandler: (diags: list<dict<any>>) => {
383 return diags->map((diag, ix) => {
384 diag.message = $'TypeScript: {diag.message}'
391 syncInit (Optional) for language servers (e.g. rust analyzer,
392 gopls, etc.) that take time to initialize and reply to
393 a "initialize" request message this should be set to
394 "true". If this is set to true, then a synchronous
395 call is used to initialize the language server,
396 otherwise the server is initialized asynchronously.
397 By default this is set to "false".
400 debug (Optional) log the messages printed by this language
401 server in stdout and stderr to a file. Useful for
402 debugging a language server. By default the
403 messages are not logged. See |lsp-debug| for more
407 traceLevel (Optional) set the debug trace level for this language
408 server. Supported values are: "off", "debug" and
409 "verbose". By default this is seto "off".
411 The language servers are added using the LspAddServer() function. This
412 function accepts a list of language servers with the above information.
414 If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the
415 LSP plugin, then you need to use the VimEnter autocmd to initialize the
416 language server and to set the language server options. For example: >
422 filetype: ['c', 'cpp'],
423 path: '/usr/local/bin/clangd',
424 args: ['--background-index']
427 autocmd VimEnter * LspAddServer(lspServers)
429 var lspOpts = {'autoHighlightDiags': true}
430 autocmd VimEnter * LspOptionsSet(lspOpts)
432 *lsp-options* *LspOptionsSet()*
435 Some of the LSP plugin features can be enabled or disabled by using the
436 LspOptionsSet() function. This function accepts a dictionary argument with the
437 following optional items:
440 aleSupport |Boolean| option. If true, diagnostics will be sent to
441 Ale, instead of being displayed by this plugin.
442 This is useful to combine all LSP and linter
443 diagnostics. By default this is set to false.
445 *lsp-opt-autoComplete*
446 autoComplete |Boolean| option. In insert mode, automatically
447 complete the current symbol. Otherwise use
448 omni-completion. By default this is set to true.
450 *lsp-opt-autoHighlight*
451 autoHighlight |Boolean| option. In normal mode, automatically
452 highlight all the occurrences of the symbol under the
453 cursor. By default this is set to false.
455 *lsp-opt-autoHighlightDiags*
456 autoHighlightDiags |Boolean| option. Automatically place signs on the
457 lines with a diagnostic message from the language
458 server. By default this is set to true.
460 *lsp-opt-autoPopulateDiags*
461 autoPopulateDiags |Boolean| option. Automatically populate the location
462 list with diagnostics from the language server.
463 By default this is set to false.
465 *lsp-opt-completionMatcher*
466 completionMatcher |String| option. Enable fuzzy or case insensitive
467 completion for language servers that replies with a
468 full list of completion items. Some language servers
469 does completion filtering in the server, while other
470 relies on the client to do the filtering.
472 This option only works for language servers that
473 expect the client to filter the completion items.
475 This option accepts one of the following values:
476 case - case sensitive matching (default).
477 fuzzy - fuzzy match completion items.
478 icase - ignore case when matching items.
480 *lsp-opt-completionTextEdit*
481 completionTextEdit |Boolean| option. If true, apply the LSP server
482 supplied text edits after a completion. If a snippet
483 plugin is going to apply the text edits, then set
484 this to false to avoid applying the text edits twice.
485 By default this is set to true.
487 *lsp-opt-completionKinds*
488 completionKinds |Dictionary| option. See |lsp-custom-kinds| for all
489 completion kind names.
491 *lsp-opt-customCompletionKinds*
492 customCompletionKinds |Boolean| option. If you set this to true, you can
493 set custom completion kinds using the option
496 *lsp-opt-diagSignErrorText*
497 diagSignErrorText |String| option. Change diag sign text for errors
500 *lsp-opt-diagSignHintText*
501 diagSignHintText |String| option. Change diag sign text for hints
504 *lsp-opt-diagSignInfoText*
505 diagSignInfoText |String| option. Change diag sign text for info
508 *lsp-opt-diagSignWarningText*
509 diagSignWarningText |String| option. Change diag sign text for warnings
512 *lsp-opt-diagVirtualTextAlign*
513 diagVirtualTextAlign |String| option. Alignment of diagnostics messages
514 if |lsp-opt-showDiagWithVirtualText| is set to true.
515 Allowed values are 'above', 'below' or 'after'
516 By default this is set to 'above',
518 *lsp-opt-echoSignature*
519 echoSignature |Boolean| option. In insert mode, echo the current
520 symbol signature instead of showing it in a popup.
521 By default this is set to false.
523 *lsp-opt-hideDisabledCodeActions*
524 hideDisabledCodeActions |Boolean| option. Hide all the disabled code actions.
525 By default this is set to false.
527 *lsp-opt-highlightDiagInline*
528 highlightDiagInline |Boolean| option. Highlight the diagnostics inline.
529 By default this is set to true.
531 *lsp-opt-hoverInPreview*
532 hoverInPreview |Boolean| option. Show |:LspHover| in a preview window
534 By default this is set to false.
536 *lsp-opt-ignoreMissingServer*
537 ignoreMissingServer |Boolean| option. Do not print a missing language
538 server executable. By default this is set to false.
540 *lsp-opt-keepFocusInDiags*
541 keepFocusInDiags |Boolean| option. Focus on the location list window
542 after ":LspDiag show".
543 By default this is set to true.
545 *lsp-opt-keepFocusInReferences*
546 keepFocusInReferences |Boolean| option. Focus on the location list window
547 after LspShowReferences.
548 By default this is set to true.
550 *lsp-opt-noNewlineInCompletion*
551 noNewlineInCompletion |Boolean| option. Suppress adding a new line on
552 completion selection with <CR>.
553 By default this is set to false.
555 *lsp-opt-omniComplete*
556 omniComplete |Boolean| option. Enables or disables omni-completion.
557 By default this is set to v:false. If "autoComplete"
558 is set to v:false, then omni-completion is enabled by
559 default. By setting "omniComplete" option to v:false,
560 omni-completion can also be disabled.
562 *lsp-opt-outlineOnRight*
563 outlineOnRight |Boolean| option. Open the outline window on the
564 right side, by default this is false.
566 *lsp-opt-outlineWinSize*
567 outlineWinSize |Number| option. The size of the symbol Outline
568 window. By default this is set to 20.
570 *lsp-opt-showDiagInBalloon*
571 showDiagInBalloon |Boolean| option. When the mouse is over a range of
572 text referenced by a diagnostic, display the
573 diagnostic text in a balloon. By default this is set
574 to true. In a GUI Vim, this needs the |+balloon_eval|
575 feature. In a terminal Vim, this needs the
576 |+balloon_eval_term| feature. In a terminal Vim,
577 'mouse' option should be set to enable mouse.
578 If this option is set to true, then the 'ballooneval'
579 and 'balloonevalterm' options are set.
581 *lsp-opt-showDiagInPopup*
582 showDiagInPopup |Boolean| option. When using the ":LspDiag current"
583 command to display the diagnostic message for the
584 current line, use a popup window to display the
585 message instead of echoing in the status area.
586 By default this is set to true.
588 *lsp-opt-showDiagOnStatusLine*
589 showDiagOnStatusLine |Boolean| option. Show a diagnostic message on a
590 status line. By default this is set to false.
592 *lsp-opt-showDiagWithSign*
593 showDiagWithSign |Boolean| option. Place a sign on lines with
594 diagnostics. By default this is set to true. The
595 "autoHighlightDiags" option should be set to true.
597 *lsp-opt-showDiagWithVirtualText*
598 showDiagWithVirtualText |Boolean| option. Show diagnostic message text from
599 the language server with virtual text. By default
600 this is set to false. The "autoHighlightDiags" option
601 should be set to true.
602 Needs Vim version 9.0.1157 or later.
604 *lsp-opt-showInlayHints*
605 showInlayHints |Boolean| option. Show inlay hints from the language
606 server. By default this is set to false. The inlay
607 hint text is displayed as a virtual text. Needs Vim
608 version 9.0.0178 or later.
610 *lsp-opt-showSignature*
611 showSignature |Boolean| option. In insert mode, automatically show
612 the current symbol signature in a popup.
613 By default this is set to true.
615 *lsp-opt-snippetSupport*
616 snippetSupport |Boolean| option. Enable snippet completion support.
617 Need a snippet completion plugin like vim-vsnip.
618 By default this is set to false.
620 *lsp-opt-ultisnipsSupport*
621 ultisnipsSupport |Boolean| option. Enable SirVer/ultisnips support.
622 Need a snippet completion plugin SirVer/ultisnips.
623 By default this is set to false.
625 *lsp-opt-vssnipSupport*
626 vsnipSupport |Boolean| option. Enable hrsh7th/vim-vsnip support.
627 Need snippet completion plugins hrsh7th/vim-vsnip
628 and hrsh7th/vim-vsnip-integ. Make sure
629 ultisnipsSupport is set to false before enabling this.
630 By default this option is set to false.
632 *lsp-opt-usePopupInCodeAction*
633 usePopupInCodeAction |Boolean| option. When using the |:LspCodeAction|
634 command to display the code action for the current
635 line, use a popup menu instead of echoing.
636 By default this is set to false.
638 *lsp-opt-useQuickfixForLocations*
639 useQuickfixForLocations |Boolean| option. Show |:LspShowReferences| in a
640 quickfix list instead of a location list.
641 By default this is set to false.
643 *lsp-opt-useBufferCompletion*
644 useBufferCompletion |Boolean| option. If enabled, the words from the
645 current buffer are added to the auto completion list.
646 By default this is set to false.
648 *lsp-opt-bufferCompletionTimeout*
649 bufferCompletionTimeout |Number| option. Specifies how long (in milliseconds)
650 to wait while processing current buffer for
651 autocompletion words. If set too high Vim performance
652 may degrade as the current buffer contents are
653 processed every time the completion menu is displayed.
654 If set to 0 the entire buffer is processed without
656 By default this is set to 100 ms.
658 For example, to disable the automatic placement of signs for the LSP
659 diagnostic messages, you can add the following line to your .vimrc file: >
661 call LspOptionsSet({'autoHighlightDiags': false})
664 The LspOptionsGet() function returns a |Dict| of all the LSP plugin options,
665 To get a particular option value you can use the following: >
667 echo LspOptionsGet()['autoHighlightDiags']
669 ==============================================================================
670 5. Commands *lsp-commands*
672 A description of the various commands provided by this plugin is below. You
673 can map these commands to keys and make it easier to invoke them.
676 :LspCodeAction [query] Apply the code action supplied by the language server
677 to the diagnostic in the current line. This works only
678 if there is a diagnostic message for the current line.
679 You can use the ":LspDiag current" command to display
680 the diagnostic for the current line.
682 When [query] is given the code action starting with
683 [query] will be applied. [query] can be a regexp
684 pattern, or a digit corresponding to the index of the
685 code actions in the created prompt.
687 When [query] is not given you will be prompted to
688 select one of the actions supplied by the language
692 :LspCodeLens Display a list of code lens commands available for the
693 current buffer and apply the selected code lens
697 :LspDiag current Displays the diagnostic message (if any) for the
698 current line. If the option 'showDiagInPopup' is set
699 to true (default), then the message is displayed in
700 a popup window. Otherwise the message is displayed in
701 the status message area.
703 :LspDiag! current Only display a diagnostic message if it's directly
704 under the cursor. Otherwise works exactly like
707 To show the current diagnotic under the cursor while
708 moving around the following autocmd can be used: >
712 au CursorMoved * silent! LspDiag! current
716 :LspDiag first Jumps to the location of the first diagnostic message
717 for the current file.
720 :LspDiag here Jumps to the location of the diagnostic message in
721 the current line (start from current column).
723 :LspDiag highlight disable *:LspDiag-highlight-disable*
724 Disable highlighting lines with a diagnostic message
725 for the current Vim session.
726 To always disable the highlighting, set the
727 autoHighlightDiags option to false.
729 :LspDiag highlight enable *:LspDiag-highlight-enable*
730 Enable highlighting lines with a diagnostic message
731 for the current Vim session. Note that highlighting
732 lines with a diagnostic message is enabled by default.
735 :LspDiag last Jumps to the location of the first diagnostic message
736 for the current file.
739 :[count]LspDiag next Go to the [count] diagnostic message after the current
740 cursor position. If [count] is omitted, then 1 is
741 used. If [count] exceeds the number of diagnostics
742 after the current position, then the last diagnostic
746 :[count]LspDiag prev Go to the [count] diagnostic message before the
747 current cursor position. If [count] is omitted, then
748 1 is used. If [count] exceeds the number of
749 diagnostics before the current position, then first
750 last diagnostic is selected.
753 :LspDiag show Creates a new location list with the diagnostics
754 messages (if any) from the language server for the
755 current file and opens the location list window. You
756 can use the Vim location list commands to browse the
760 :LspDocumentSymbol Display the symbols in the current file in a popup
761 menu. When a symbol is selected in the popup menu by
762 pressing <Enter> or <Space>, jump to the location of
765 The <Up>, <Down>, <C-F>, <C-B>, <PageUp>, <PageDown>,
766 <C-Home>, <C-End>, <C-N>, <C-P> keys can be used to
767 scroll the popup menu. The <Esc> or <Ctrl-C> keys can
768 be used to cancel the popup menu.
770 If one or more keyword characters are typed, then only
771 the symbols containing the keyword characters are
772 displayed in the popup menu. Fuzzy searching is used
773 to get the list of matching symbols. The <BS> key can
774 be used to erase the last typed character. The <C-U>
775 key can be used to erase all the characters.
777 When scrolling through the symbols in the popup menu,
778 the corresponding range of lines is highlighted.
781 :LspFold Create folds for the current buffer.
784 :LspFormat Format the current file using the language server. The
785 'shiftwidth' and 'expandtab' values set for the
786 current buffer are used when format is applied.
788 :{range}LspFormat Format the specified range of lines in the current
789 file using the language server.
791 *:LspGotoDeclaration*
792 :[count]LspGotoDeclaration
793 Jumps to the declaration of the symbol under the
794 cursor. The behavior of this command is similar to the
795 |:LspGotoDefinition| command.
798 :[count]LspGotoDefinition
799 Jumps to the [count] definition of the symbol under
800 the cursor. If there are multiple matches and [count]
801 isn't specified, then a location list will be created
802 with the list of locations.
804 If there is only one location, or [count] is provided
805 then the following will apply:
807 If the file is already present in a window, then jumps
808 to that window. Otherwise, opens the file in a new
809 window. If the current buffer is modified and
810 'hidden' is not set or if the current buffer is a
811 special buffer, then a new window is opened. If the
812 jump is successful, then the current cursor location
813 is pushed onto the tag stack. The |CTRL-T| command
814 can be used to go back up the tag stack. Also the
815 |``| mark is set to the position before the jump.
817 This command supports |:command-modifiers|. You can
818 use the modifiers to specify whether a new window or
819 a new tab page is used and where the window is opened.
822 # Open a horizontally split window
823 :topleft LspGotoDefinition
824 # Open a vertically split window
825 :vert LspGotoDefinition
826 # Open a new tab page
827 :tab LspGotoDefinition
829 You may want to map a key to invoke this command: >
831 nnoremap <buffer> gd <Cmd>LspGotoDefinition<CR>
832 nnoremap <buffer> <C-W>gd <Cmd>topleft LspGotoDefinition<CR>
834 Or if you want to support [count]gd >
836 nnoremap <buffer> gd <Cmd>execute v:count .. 'LspGotoDefinition'<CR>
837 nnoremap <buffer> <C-W>gd <Cmd>execute 'topleft ' .. v:count .. 'LspGotoDefinition'<CR>
840 :[count]LspGotoImpl Jumps to the implementation of the symbol under the
841 cursor. The behavior of this command is similar to the
842 |:LspGotoDefinition| command. Note that not all the
843 language servers support this feature.
845 You may want to map a key to invoke this command: >
847 nnoremap <buffer> gi <Cmd>LspGotoImpl<CR>
850 :[count]LspGotoTypeDef Jumps to the type definition of the symbol under the
851 cursor. The behavior of this command is similar to the
852 |:LspGotoDefinition| command. Note that not all the
853 language servers support this feature.
855 You may want to map a key to invoke this command: >
857 nnoremap <buffer> gt <Cmd>LspGotoTypeDef<CR>
860 :LspHighlight Highlights all the matches for the symbol under
861 cursor. The text, read and write references to the
862 symbol are highlighted using Search, DiffChange and
863 DiffDelete highlight groups respectively.
866 :LspHighlightClear Clears all the symbol matches highlighted by the
867 |:LspHighlight| command.
870 :LspHover Show the documentation for the symbol under the cursor
871 in a popup window. If you want to show the symbol
872 documentation in the |preview-window| instead of in a
875 LspOptionsSet({'hoverInPreview': true})
877 You can use the |:pclose| command to close the preview
880 You can use the |K| key in normal mode to display the
881 documentation for the keyword under the cursor by
882 setting the 'keywordprg' Vim option: >
884 :set keywordprg=:LspHover
887 :LspIncomingCalls Display a hierarchy of symbols calling the symbol
888 under the cursor in a window. See
889 |lsp-call-hierarchy| for more information. Note that
890 not all the language servers support this feature.
893 :LspInlayHints Enable or disable inlay hints. Supports the "enable"
894 and "disable" arguments. When "enable" is specified,
895 enables the inlay hints for all the buffers with a
896 language server that supports inlay hints. When
897 "disable" is specified, disables the inlay hints.
900 :LspOutoingCalls Display a hierarchy of symbols called by the symbol
901 under the cursor in a window. See
902 |lsp-call-hierarchy| for more information. Note that
903 not all the language servers support this feature.
906 :[count]LspOutline Opens a vertically split window with the list of
907 symbols defined in the current file. The current
908 symbol is highlighted. The symbols are grouped by
909 their type. You can select a symbol and press <Enter>
910 to jump to the position of the symbol. As you move the
911 cursor in a file, the current symbol is automatically
912 highlighted in the outline window. If you open a new
913 file, the outline window is automatically updated with
914 the symbols in the new file. Folds are created in the
915 outline window for the various group of symbols.
917 You can use |lsp-opt-outlineOnRight| and
918 |lsp-opt-outlineWinSize| to customize the placement
919 and size of the window.
921 This command also supports |:command-modifiers|. You
922 can use the modifiers specify the position of the
923 window. Note that the default is ":vert :topleft" or
924 ":vert :botright" depending on
925 |lsp-opt-outlineOnRight|
927 This command also supports providing a [count] to
928 specify the size of the window. Note that this
929 overrides the values defined in
930 |lsp-opt-outlineWinSize|.
933 # Open the outline window just above the current
935 :aboveleft LspOutline
937 # Open the outline window just next to the current
938 # window, this is different from the default, when
939 # you have multiple splits already
940 :vert aboveleft LspOutline
942 # Same as above, but with a width of 50
943 :vert aboveleft 50LspOutline
945 *:LspPeekDeclaration*
946 :[count]LspPeekDeclaration
947 Displays the line where the symbol under the
948 cursor is declared in a popup window. The
949 behavior of this command is similar to the
950 |:LspPeekDefinition| command.
953 :[count]LspPeekDefinition
954 Displays the line where the symbol under the cursor is
955 defined in a popup window. The symbol is highlighted
956 in the popup window. Moving the cursor or pressing
957 <Esc> will close the popup window.
958 When more than one symbol is found all of them will be
959 shown. The corresponding file for the symbol is
960 displayed in another popup window. As the selection
961 in the symbol popup menu changes, the file in the
963 When [count] is provided only the [count] symbol will
967 :[count]LspPeekImpl Displays the implementation of the symbol under the
968 cursor in a popup window. The behavior of this
969 command is similar to the |:LspPeekDefinition|
970 command. Note that not all the language servers
971 support this feature.
974 :LspPeekReferences Displays the list of references to the symbol under
975 cursor in a popup menu. The corresponding file for
976 the reference is displayed in another popup window.
977 As the selection in the reference popup menu changes,
978 the file in the popup is updated.
981 :[count]LspPeekTypeDef Displays the line where the type of the symbol under
982 the cursor is defined in a popup window. The
983 behavior of this command is similar to the
984 |:LspPeekDefinition| command. Note that not all the
985 language servers support this feature.
988 :LspRename [newName] Rename the current symbol.
990 When [newName] is not given, then you will be prompted
991 to enter the new name for the symbol. You can press
992 <Esc> or enter an empty string in the prompt to cancel
995 *:LspSelectionExpand*
996 :LspSelectionExpand Visually select the region of the symbol under the
997 cursor. In visual mode, expands the current symbol
998 visual region selection to include the next level.
1000 For example, if the cursor is on a "for" statement,
1001 this command selects the "for" statement and the body
1002 of the "for" statement.
1004 It is useful to create a visual map to use this
1007 xnoremap <silent> <Leader>e <Cmd>LspSelectionExpand<CR>
1009 With the above map, you can press "\e" in visual mode
1010 successively to expand the current symbol visual
1013 *:LspSelectionShrink*
1014 :LspSelectionShrink Shrink the current symbol range visual selection. It
1015 is useful to create a visual map to use this command.
1018 xnoremap <silent> <Leader>s <Cmd>LspSelectionShrink<CR>
1020 With the above map, you can press "\s" in visual mode
1021 successively to shrink the current symbol visual
1025 :LspServer { debug | restart | show | trace }
1026 Command to display and control the language server for
1027 the current buffer. Each argument has additional
1028 sub-commands which are described below.
1030 debug { on | off | messages | errors }
1031 Command to enable or disable the language server
1032 debug messages and to display the debug messages
1033 and error messages received from the language
1034 server. The following sub-commands are supported:
1035 errors Open the log file containing the
1036 language server error messages.
1038 Open the log file containing the
1039 language server debug messages.
1040 off Disable the logging of the language
1042 on Enable the logging of the messages
1043 emitted by the language server in the
1044 standard output and standard error.
1045 By default, the language server messages are not
1046 logged. On a Unix-like system, when enabled,
1047 these messages are logged to the
1048 /tmp/lsp-<server-name>.log and
1049 /tmp/lsp-<server-name>.err file respectively. On
1050 MS-Windows, the %TEMP%/lsp-<server-name>.log and
1051 %TEMP%/lsp-<server-name>.err% files are used. See
1052 |lsp-debug| for more information.
1055 Restart (stop and then start) the language server
1056 for the current buffer. All the loaded buffers
1057 with the same filetype as the current buffer are
1058 added back to the server.
1060 show {capabilities | initializeRequest | messages
1062 The following sub-commands are supported:
1064 Display the list of language server
1065 capabilities for the current buffer.
1066 The server capabilities are described
1067 in the LSP protocol specification
1068 under the "ServerCapabilities"
1071 Display the contents of the language
1072 server initialization request message
1075 Display the log messages received from
1076 the language server. This includes
1077 the messages received using the
1078 "window/logMessage" and "$/logTrace"
1081 Display the language server status for
1082 the current buffer. The output shows
1083 the path to the language server
1084 executable and the server status.
1086 trace { off | messages | verbose }
1087 Set the language server debug trace value using
1088 the "$/setTrace" command.
1090 *:LspShowAllServers*
1091 :LspShowAllServers Displays the list of registered language servers and
1092 their status. The language servers are registered
1093 using the LspAddServer() function. The output is
1094 displayed in a scratch buffer. The output shows the
1095 Vim file type, the corresponding language server
1096 status and the path to the language server executable.
1097 The language server information for each buffer is
1100 *:LspShowReferences*
1101 :LspShowReferences Creates a new location list with the list of locations
1102 where the symbol under the cursor is referenced and
1103 opens the location window. If you want to show the
1104 references in a quickfix list instead of in a location
1107 LspOptionsSet({'useQuickfixForLocations': true})
1110 :LspShowSignature Displays the signature of the symbol (e.g. a function
1111 or method) before the cursor in a popup.
1113 The popup is also automatically displayed in insert
1114 mode after entering a symbol name followed by a
1115 separator (e.g. a opening parenthesis). To disable
1116 this, you can set the showSignature option to false in
1119 LspOptionsSet({'showSignature': false})
1123 You can get the function signature echoed in cmdline
1124 rather than displayed in popup if you use >
1126 LspOptionsSet({'echoSignature': true})
1130 *:LspSubTypeHierarchy*
1131 :LspSubTypeHierarchy Show the sub type hierarchy for the symbol under the
1132 cursor in a popup window. The file containing the
1133 type is shown in another popup window. You can jump
1134 to the location where a type is defined by browsing
1135 the popup menu and selecting an entry.
1137 *:LspSuperTypeHierarchy*
1138 :LspSuperTypeHierarchy Show the super type hierarchy for the symbol under the
1139 cursor in a popup window. The file containing the
1140 type is shown in another popup window. As the current
1141 entry in the type hierarchy popup menu changes, the
1142 file popup window is updated to show the location
1143 where the type is defined. You can jump to the
1144 location where a type is defined by selecting the
1145 entry in the popup menu.
1147 Note that the type hierarchy support is based on the
1148 protocol supported by clangd. This is different from
1149 the one specified in the 3.17 of the LSP standard.
1151 *:LspSwitchSourceHeader*
1152 :LspSwitchSourceHeader Switch between source and header files. This is a
1153 Clangd specific extension and only works with C/C++
1157 :LspSymbolSearch <sym> Perform a workspace wide search for the symbol <sym>.
1158 If <sym> is not supplied, then you will be prompted to
1159 enter the symbol name (the keyword under the cursor is
1160 used as the default). If there is only one matching
1161 symbol, then the cursor will be positioned at the
1162 symbol location. Otherwise a popup window is opened
1163 with the list of matching symbols. You can enter a
1164 few characters to narrow down the list of matches. The
1165 displayed symbol name can be erased by pressing
1166 <Backspace> or <C-U> and a new symbol search pattern
1167 can be entered. You can close the popup menu by
1168 pressing the escape key or by pressing CTRL-C.
1170 In the popup menu, the following keys can be used:
1172 CTRL-F - Scroll one page forward
1174 CTRL-B - Scroll one page backward
1176 CTRL-Home - Jump to the first entry
1177 CTRL-End - Jump to the last entry
1178 <Up> - Go up one entry
1180 <Down> - Go down one entry
1182 <Enter> - Open the selected file
1183 <Esc> - Close the popup menu
1185 <BS> - Erase one character from the
1188 <C-U> - Erase the filter text
1190 Any other alphanumeric key will be used to narrow down
1191 the list of names displayed in the popup menu. When
1192 you type a filter string, then only the symbols fuzzy
1193 matching the string are displayed in the popup menu.
1194 You can enter a new search pattern to do a workspace
1197 This command accepts |:command-modifiers| which can be
1198 used to jump to a symbol in a horizontally or
1199 vertically split window or a new tab page: >
1201 :topleft LspSymbolSearch foo
1202 :vert LspSymbolSearch bar
1203 :tab LspSymbolSearch baz
1205 *:LspWorkspaceAddFolder*
1206 :LspWorkspaceAddFolder {folder}
1207 Add a folder to the workspace
1209 :LspWorkspaceListFolders *:LspWorkspaceListFolders*
1210 Show the list of folders in the workspace.
1212 *:LspWorkspaceRemoveFolder*
1213 :LspWorkspaceRemoveFolder {folder}
1214 Remove a folder from the workspace
1216 ==============================================================================
1217 6. Insert Mode Completion *lsp-ins-mode-completion*
1219 By default, when you are in insert mode, the LSP plugin will automatically
1220 display suggestions for the symbol under the cursor in an insert-completion
1221 popup menu. The keys specified in |popupmenu-keys| can be used to interact
1224 To disable this auto-completion feature for all files, you can set the
1225 "autoComplete" option to false in your .vimrc file using the |LspOptionsSet()|
1228 call LspOptionsSet({'autoComplete': false})
1230 By setting the "autoComplete" option to |v:false|, the LSP plugin will no
1231 longer automatically trigger completion suggestions in insert mode. Instead,
1232 it will use omni-completion (|compl-omni|) and set the 'omnifunc' option for
1233 buffers that have a registered language server. To manually trigger symbol
1234 completion in insert mode, you can press CTRL-X CTRL-O. This key combination
1235 will invoke completion using the suggestions provided by the language server.
1237 To enable omni-completion for all the buffers, set the "omniComplete" option
1238 to v:true. To explicitly disable omni-completion for all the buffers, set the
1239 "omniComplete" option to v:false (default).
1241 In addition to the general auto-completion behavior discussed above, you
1242 have the option to enable or disable omni-completion for a specific language
1243 server when registering it for a particular filetype.
1245 To do this, you can set the 'omnicompl' item to |v:false| in the configuration
1246 when registering the language server for the desired filetype. If the
1247 'omnicompl' item is not specified, omni-completion is enabled by default.
1249 Here's an example of how to disable omni-completion for Python: >
1256 path: '/usr/local/bin/pyls',
1257 args: ['--check-parent-process', '-v']
1261 In this example, the language server for Python is registered using the
1262 |LspAddServer()| function, and the 'omnicompl' item is explicitly set to
1263 |v:false|. As a result, omni-completion will be disabled for Python files
1264 associated with this language server.
1266 Please note that if 'omnicompl' is not included in the configuration
1267 when registering the language server, omni-completion will be enabled by
1270 In insert-mode completion, the plugin sends a completion request message to
1271 the language server and obtains a list of potential completion matches based
1272 on the current cursor position. To achieve this, the plugin retrieves the
1273 keyword immediately preceding the cursor (refer to 'iskeyword' setting) and
1274 then filters the list of completion items received from the language server
1275 based on this keyword. The resulting filtered list is displayed as the
1278 It's worth noting that different language servers handle completion filtering
1279 in distinct ways. Some servers perform the filtering directly on the
1280 server-side, while others delegate this task to the client-side, which is the
1281 plugin in this context.
1283 By default, the plugin uses a case-sensitive comparison method to filter the
1284 returned completion items. However, you have the flexibility to customize this
1285 behavior by modifying the "completionMatcher" option. This option allows you
1286 to switch between case-insensitive or fuzzy comparison methods as per your
1287 preference and requirements for completion matching.
1289 In addition to automatic completion and omni completion, there is a
1290 possibility to utilize external completion engines with the LSP client. This
1291 can be achieved by repurposing the |g:LspOmniFunc| function. The external
1292 completion engine adapter needs to invoke this function twice, following the
1293 approach outlined in the |complete-functions| documentation.
1295 The process works as follows:
1297 1. First Invocation: The external completion engine adapter calls
1298 |g:LspOmniFunc| to initiate a request to the LSP server for completion
1300 2. After the first invocation, a request is sent to the LSP server to find
1301 completion candidates.
1302 3. Second Invocation: The external completion engine adapter calls
1303 |g:LspOmniFunc| again to retrieve the matches returned by the LSP server.
1304 4. If the LSP server is not ready to reply immediately, |g:LspOmniFunc| waits
1305 for up to 2 seconds.
1306 5. However, this wait could block the caller from performing other tasks,
1307 which might be a concern for asynchronous completion engines.
1308 6. To address this issue, the adapter can use the |g:LspOmniCompletePending|
1309 function, which allows for a non-blocking check. It returns true
1310 immediately if the language server is not ready to respond yet.
1311 7. To proceed with the second invocation of g:LspOmniFunc, it is crucial to
1312 ensure that |g:LspOmniCompletePending| returns false, indicating that the
1313 language server is now ready to provide the completion matches.
1315 ==============================================================================
1316 7. Diagnostics *lsp-diagnostics*
1318 The LSP plugin offers a feature to highlight syntax errors, warnings, and
1319 static analysis warnings in a source file by placing signs in the sign column.
1320 These signs serve as visual indicators of the diagnostics reported by the
1323 To interact with these diagnostics, you can use various commands provided by
1326 1. ":LspDiag show": This command displays all the diagnostic messages for the
1327 current file in a location-list window. The location-list window allows
1328 you to view a list of all the diagnostic messages, along with their
1329 corresponding line numbers and descriptions.
1330 2. ":LspDiag first": Use this command to jump directly to the line containing
1331 the first diagnostic message. It helps you quickly navigate to the
1332 location of the initial issue detected by the language server.
1333 3. ":LspDiag next": With this command, you can navigate to the next nearest
1334 line with a diagnostic message. It helps you step through the list of
1335 diagnostics one by one.
1336 4. ":LspDiag prev": Conversely, this command allows you to jump to the
1337 previous nearest line with a diagnostic message. It is useful for
1338 reviewing diagnostics in reverse order.
1339 5. ":LspDiag here": If you want to focus solely on the diagnostic message for
1340 the current line, you can use this command to jump directly to it.
1341 6. ":LspDiag current": This command displays the entire diagnostic message
1342 from the language server for the current line. It provides detailed
1343 information about the specific issue and its description.
1345 By using these commands, you can efficiently navigate and inspect the
1346 diagnostics reported by the language server, making it easier to identify and
1347 address syntax errors, warnings, or static analysis issues in your code.
1349 By default, the LSP plugin marks lines with diagnostic messages by placing a
1350 sign on them and highlighting the range of text associated with the
1351 diagnostic. However, you have the option to customize this behavior by
1352 adjusting certain configuration settings:
1354 1. Disabling Automatic Sign Placement: If you wish to prevent the automatic
1355 placement of signs on lines with diagnostic messages, you can achieve this
1356 by setting the "showDiagWithSign" option to |v:false|. By default, this
1357 option is set to |v:true|, meaning that signs are automatically placed on
1358 lines with diagnostics.
1359 2. Disabling Diagnostic Text Highlighting: If you prefer not to have the
1360 diagnostic text highlighted, you can do so by setting the
1361 "highlightDiagInline" option to |v:false|. By default, this option is set
1362 to |v:true|, resulting in the highlighting of the text range associated
1363 with each diagnostic.
1364 3. Highlight Group for Line with Diagnostics: The LSP plugin uses the
1365 "LspDiagLine" highlight group to highlight lines containing diagnostics.
1366 By default, this highlight group is not set, allowing you to define your
1367 own highlighting style for lines with diagnostics if desired.
1369 In addition to the default display of the diagnostic messages with signs and
1370 text highlighting, the LSP plugin offers the option to present the diagnostic
1371 message as virtual text, located near the relevant location of the
1372 diagnostics. To enable this feature, you can set the
1373 "showDiagWithVirtualText" option to |v:true|. However, please note that this
1374 functionality requires Vim version 9.0.1157 or later. By default, this option
1375 is set to |v:false|, meaning that virtual text display is not activated.
1377 The position of the virtual text can be controlled using the
1378 "diagVirtualTextAlign" option, which determines its alignment relative to the
1379 affected line. By default, this option is set to 'above', which places the
1380 virtual text above the line with the diagnostic message. The other supported
1381 values for "diagVirtualTextAlign" are 'below', which positions the virtual
1382 text below the affected line, and 'after', which displays the virtual text
1383 immediately after the text on the affected line.
1385 The LSP plugin offers convenient ways to highlight diagnostic messages, making
1386 it easier to spot errors, warnings, hints, or informational notices within
1387 your code. By default, the plugin automatically highlights the range of text
1388 associated with each diagnostic message when the "highlightDiagInline" option
1391 The highlighting is done using different highlight groups based on the type of
1394 "LspDiagInlineError" for error messages.
1395 "LspDiagInlineHint" for hints.
1396 "LspDiagInlineInfo" for informational messages.
1397 "LspDiagInlineWarning" for warning messages.
1399 If you wish to temporarily disable the automatic diagnostic highlighting for
1400 the current Vim session, you can achieve this using the ":LspDiag highlight
1401 disable" command. When you want to re-enable the highlighting, you can use
1402 the ":LspDiag highlight enable" command.
1404 To permanently disable the automatic highlighting of diagnostics, you can set
1405 the "autoHighlightDiags" option to |v:false| in your .vimrc file. This
1406 configuration can be achieved using the |LspOptionsSet()| function: >
1408 call LspOptionsSet({'autoHighlightDiags': v:false})
1410 By default, the "autoHighlightDiags" option is set to |v:true|, ensuring that
1411 diagnostic messages are automatically highlighted during your coding sessions.
1413 The lsp#lsp#ErrorCount() function returns the count of diagnostic messages in
1414 the current buffer, categorized by their types. When called, this function
1415 returns a Dictionary containing four keys: "Info," "Hint," "Warn," and
1416 "Error." Each key corresponds to a specific diagnostic type, and its
1417 associated value is the number of diagnostic messages of that particular type
1418 found in the buffer. With the information gathered using this function, you
1419 can easily display the number of diagnostics in the current buffer in your
1422 For some diagnostic errors/warnings, the language server may provide an
1423 automatic fix. To apply this fix, you can use the |:LspCodeAction| command.
1424 This command applies the action provided by the language server (if any) for
1427 The ":LspDiag show" command creates a new location list with the current list
1428 of diagnostics for the current buffer. To automatically refresh the location
1429 list with the latest diagnostics received from the language server, you can
1430 set the "autoPopulateDiags" option to |v:true|. By default this option is set
1431 to |v:false|. When new diagnostics are received for a buffer, if a location
1432 list with the diagnostics is already present, then it is refreshed with the
1435 In GUI Vim or terminal Vim with the 'balloonevalterm' option enabled, a
1436 helpful feature allows you to view diagnostic messages in a popup balloon when
1437 you hover the mouse over the affected range of text. This provides a
1438 convenient way to quickly access diagnostic information without the need to
1439 execute additional commands or navigate through the location list.
1441 By default, the LSP plugin is configured to display diagnostic messages in the
1442 popup balloon, enhancing the user experience and providing visual feedback as
1443 you interact with your code. This default behavior is governed by the
1444 "showDiagInBalloon" option, which is set to |v:true| by default.
1446 However, if you prefer not to see the diagnostic messages in the popup
1447 balloons and prefer to rely solely on other methods, you have the flexibility
1448 to customize this behavior. By setting the "showDiagInBalloon" option to
1449 |v:false|, you can disable the display of diagnostic messages in the popup
1450 balloons. This can be useful if you find the balloons intrusive or if you
1451 prefer to view diagnostics through other means, such as the location list or
1454 To display the diagnostic message for the current line in the status area, you
1455 can set the "showDiagOnStatusLine" option to |v:true|. By default, this
1456 option is set to |v:false|.
1458 By default, the ":LspDiag current" command displays the diagnostic message for
1459 the current line in a popup window. To display the message in the status
1460 message area instead, you can set the 'showDiagInPopup' option to |v:false|.
1461 By default this is set to |v:true|.
1463 The lsp#diag#GetDiagsForBuf() function can be used to get all the LSP
1464 diagnostics in a buffer. This function optionally accepts a buffer number.
1465 If the buffer number argument is not specified, then the current buffer is
1466 used. This function returns a |List| of diagnostics sorted by their line and
1467 column number. Each diagnostic is a |Dict| returned by the language server.
1469 ==============================================================================
1470 8. Tag Function *lsp-tagfunc*
1472 The |:LspGotoDefinition| command can be used jump to the location where a
1473 symbol is defined. To jump to the symbol definition using the Vim
1474 |tag-commands|, you can set the 'tagfunc' option to the 'lsp#lsp#TagFunc'
1477 setlocal tagfunc=lsp#lsp#TagFunc
1479 After setting the above option, you can use |Ctrl-]| and other tag related
1480 commands to jump to the symbol definition.
1482 Note that most of the language servers return only one symbol location even if
1483 the symbol is defined in multiple places in the code.
1485 ==============================================================================
1486 9. Code Formatting *lsp-format*
1488 The |:LspFormat| command can be used to format either the entire file or a
1489 selected range of lines using the language server. The 'shiftwidth' and
1490 'expandtab' values set for the current buffer are used when format is applied.
1492 To format code using the 'gq' command, you can set the 'formatexpr' option: >
1494 setlocal formatexpr=lsp#lsp#FormatExpr()
1496 ==============================================================================
1497 10. Call Hierarchy *lsp-call-hierarchy*
1499 The |:LspIncomingCalls| and the |:LspOutoingCalls| commands can be used to
1500 display the call hierarchy of a symbol. For example, the functions calling a
1501 function or the functions called by a function. These two commands open a
1502 window containing the call hierarchy tree. You can use the Vim motion
1503 commands to browse the call hierarchy.
1505 In the call hierarchy tree window, the following keys are supported:
1507 <Enter> Jump to the location of the symbol under the
1509 - Expand and show the symbols calling or called
1510 by the symbol under the cursor.
1511 + Close the call hierarchy for the symbol under
1514 You can display either the incoming call hierarchy or the outgoing call
1515 hierarchy in this window. You cannot display both at the same time.
1517 In the call hierarchy tree window, the following commands are supported:
1519 *:LspCallHierarchyRefresh*
1520 :LspCallHierarchyRefresh Query the language server again for the top
1521 level symbol and refresh the call hierarchy
1523 *:LspCallHierarchyIncoming*
1524 :LspCallHierarchyIncoming Display the incoming call hierarchy for the
1525 top level symbol. If the window is currently
1526 displaying the outgoing calls, then it is
1527 refreshed to display the incoming calls.
1528 *:LspCallHierarchyOutgoing*
1529 :LspCallHierarchyOutgoing Display the outgoing call hierarchy for the
1530 top level symbol. If the window is currently
1531 displaying the incoming calls, then it is
1532 refreshed to display the outgoing calls.
1534 ==============================================================================
1535 11. Autocommands *lsp-autocmds*
1538 LspAttached A |User| autocommand fired when the LSP client
1539 attaches to a buffer. Can be used to configure
1540 buffer-local mappings or options.
1543 LspDiagsUpdated A |User| autocommand invoked when new
1544 diagnostics are received from the language
1545 server. This is invoked after the LSP client
1546 has processed the diagnostics. The function
1547 lsp#diag#GetDiagsForBuf() can be used to get
1548 all the diagnostics for a buffer.
1550 ==============================================================================
1551 12. Highlight Groups *lsp-highlight-groups*
1553 The following highlight groups are used by the LSP plugin. You can define
1554 these highlight groups in your .vimrc file before sourcing this plugin to
1557 *LspDiagInlineError* Used to highlight inline error diagnostics.
1558 By default, linked to the "SpellBad" highlight
1560 *LspDiagInlineHint* Used to highlight inline hint diagnostics.
1561 By default, linked to the "SpellLocal"
1563 *LspDiagInlineInfo* Used to highlight inline info diagnostics.
1564 By default, linked to the "SpellRare"
1566 *LspDiagInlineWarning* Used to highlight inline warning diagnostics.
1567 By default, linked to the "SpellCap" highlight
1569 *LspDiagLine* Used to highlight a line with one or more
1570 diagnostics. By default linked to "NONE"
1571 (cleared). You can link this to a highlight
1572 group to highlight the line.
1573 *LspDiagSignErrorText* Used to highlight the sign text for error
1574 diags. By default linked to 'ErrorMsg'.
1575 *LspDiagSignHintText* Used to highlight the sign text for hint
1576 diags. By default linked to 'Question'.
1577 *LspDiagSignInfoText* Used to highlight the sign text for info
1578 diags. By default linked to 'Pmenu'.
1579 *LspDiagSignWarningText* Used to highlight the sign text for warning
1580 diags. By default linked to 'Search'.
1581 *LspDiagVirtualText* Used to highlight diagnostic virtual text.
1582 By default, linked to the "LineNr" highlight
1584 *LspDiagVirtualTextError* Used to highlight virtual text for error diags.
1585 By default, linked to the "SpellBad" highlight
1587 *LspDiagVirtualTextHint* Used to highlight virtual text for hint
1588 diags. By default, linked to the "SpellLocal"
1590 *LspDiagVirtualTextInfo* Used to highlight virtual text for info
1591 diags. By default, linked to the "SpellRare"
1593 *LspDiagVirtualTextWarning* Used to highlight virtual text for warning
1594 diags. By default, linked to the "SpellCap"
1596 *LspInlayHintsParam* Used to highlight inlay hints of kind
1597 "parameter". By default, linked to the
1598 "Label" highlight group.
1599 *LspInlayHintsType* Used to highlight inlay hints of kind "type".
1600 By default, linked to the "Conceal" highlight
1602 *LspSigActiveParameter* Used to highlight the active signature
1603 parameter. By default, linked to the "LineNr"
1605 *LspSymbolName* Used to highlight the symbol name when using
1606 the |:LspDocumentSymbol| command. By default,
1607 linked to the "Search" highlight group.
1608 *LspSymbolRange* Used to highlight the range of lines
1609 containing a symbol when using the
1610 |:LspDocumentSymbol| command. By default,
1611 linked to the "Visual" highlight group.
1613 For example, to override the highlight used for diagnostics virtual text, you
1614 can use the following: >
1616 highlight LspDiagVirtualText ctermfg=Cyan guifg=Blue
1620 highlight link LspDiagLine DiffAdd
1621 highlight link LspDiagVirtualText WarningMsg
1623 ==============================================================================
1624 13. Debugging *lsp-debug*
1626 To debug this plugin, you can log the language server protocol messages sent
1627 and received by the plugin from the language server. The following command
1628 enables the logging of the messages from the language server for the current
1633 This command also clears the log files. The following command disables the
1634 logging of the messages from the language server for the current buffer: >
1636 :LspServer debug off
1638 By default, the messages are not logged. Another method to enable the debug
1639 is to set the "debug" field to true when adding a language server
1640 using |LspAddServer()|.
1642 The messages printed by the language server in the stdout are logged to the
1643 lsp-<server-name>.log file and the messages printed in the stderr are logged
1644 to the lsp-<server-name>.err file. On a Unix-like system, these files are
1645 created in the /tmp directory. On MS-Windows, these files are created in the
1648 The following command opens the file containing the messages printed by the
1649 language server in the stdout: >
1651 :LspServer debug messages
1653 The following command opens the file containing the messages printed by the
1654 language server in the stderr: >
1656 :LspServer debug errors
1658 To debug language server initialization problems, after enabling the above
1659 server debug, you can restart the server for the file type in the current
1660 buffer using the following command: >
1664 The language servers typically support command line options to enable debug
1665 messages and to increase the verbosity of the messages. You can refer to the
1666 language server documentation for information about this. You can include
1667 these options when registering the language server with this plugin.
1669 If a language server supports the "$/logTrace" LSP notification, then you can
1670 use the :LspServerTrace command to set the server trace value: >
1672 :LspServer trace { off | messages | verbose }
1674 ==============================================================================
1675 14. Custom Command Handlers *lsp-custom-commands*
1677 When applying a code action, the language server may issue a non-standard
1678 command. For example, the Java language server uses non-standard commands
1679 (e.g. java.apply.workspaceEdit). To handle these commands, you can register a
1680 callback function for each command using the LspRegisterCmdHandler() function.
1684 import autoload "lsp/textedit.vim"
1686 def WorkspaceEdit(cmd: dict<any>)
1687 for editAct in cmd.arguments
1688 textedit.ApplyWorkspaceEdit(editAct)
1691 g:LspRegisterCmdHandler('java.apply.workspaceEdit', WorkspaceEdit)
1693 Place the above code in a file named lsp_java/plugin/lsp_java.vim and load
1696 The callback function should accept a Dict argument. The Dict argument
1697 contains the LSP Command interface fields. Refer to the LSP specification for
1698 more information about the "Command" interface.
1700 ==============================================================================
1701 15. Custom LSP Completion Kinds *lsp-custom-kinds*
1703 When a completion popup is triggered, the LSP client will use a default kind
1704 list to show in the completion "kind" section, to customize it, you need to
1705 use the option |lsp-opt-customCompletionKinds| and set all custom kinds in the
1706 option |lsp-opt-completionKinds| . There is a table with all default LSP
1710 ------------------------|--------------------
1738 For example, if you want to change the "Method" kind to the kind "method()": >
1743 customCompletionKinds: true,
1745 "Method": "method()"
1749 In the completion popup, will show something like this: >
1751 var file = new File()
1755 | createIfNotExists method() |
1758 ==============================================================================
1759 16. Multiple Language Servers for a buffer *lsp-multiple-servers*
1761 It's possible to run multiple language servers for a given buffer.
1763 By default the language server defined first will be used for as much as it
1764 supports, then the next and so on. With the exception that diagnostics from
1765 all running language servers will be combined.
1767 This means that you can define a language server that only supports a subset
1768 of features at first and then define the general purpose language server after
1774 # This language server reports that it only supports
1775 # textDocument/documentFormatting, so it will be used
1776 # for :LspFormat but nothing else.
1779 path: 'html-pretty-lsp',
1782 # This language server also supports
1783 # textDocument/documentFormatting, but since it's been
1784 # defined later, the one above will be used instead.
1785 # However this server also supports
1786 # textDocument/definition, textDocument/declaration,
1787 # etc, so it will be used for :LspGotoDefinition,
1788 # :LspGotoDeclaration, etc
1791 path: 'html-language-server',
1796 As shown in the example above the order of when the language servers are being
1797 defined is taken into account for a given method. However sometimes the
1798 language server that you want to use for formatting also reports that it
1799 supports other features. In such a case you can do one of two things:
1801 1. change the order of language servers, and specify that a given language
1802 server should be used for a given method.
1804 2. set the unwanted features to |false| in the features |Dictionary| >
1806 features: { 'codeAction': false }
1808 For example, if you want to use the efm-langserver for formatting, but the
1809 typescript-language-server for everything else: >
1814 # this language server will be used by default, as it's defined
1815 # as the first LSP for 'javascript' and 'typescript'
1817 filetype: ['javascript', 'typescript'],
1818 path: '/usr/local/bin/typescript-language-server',
1821 # this language server will be used for documentFormatting
1823 filetype: ['efm-langserver'],
1824 path: '/usr/local/bin/efm-langserver',
1827 documentFormatting: true
1832 Another way is to disable the unwanted features: for example if you don't want
1833 diagnostics from the typescript-language-server, but want to use it for
1840 filetype: ['javascript', 'typescript'],
1841 path: '/usr/local/bin/typescript-language-server',
1849 ==============================================================================
1850 17. Language Server Features *lsp-features*
1852 When using multiple language servers for a given file type, by providing the
1853 configuration |lsp-cfg-features| it is possible to specify which language
1854 server should be used for a given method/functionality. The following feature
1855 flags are supported: See |lsp-multiple-servers| for examples.
1857 *lsp-features-callHierarchy*
1858 callHierarchy Used by the|:LspIncomingCalls| and the
1859 |:LspOutgoingCalls| commands.
1860 *lsp-features-codeAction*
1861 codeAction Used by the |:LspCodeAction| command.
1862 *lsp-features-codeLens*
1863 codeLens Used by the |:LspCodeLens| command.
1864 *lsp-features-completion*
1865 completion Used by 24/7 Completion and 'omnifunc'
1866 *lsp-features-declaration*
1867 declaration Used by the |:LspGotoDeclaration|, and
1868 the |:LspPeekDeclaration| commands.
1869 *lsp-features-definition*
1870 definition Used by the|:LspGotoDefinition|, and
1871 the |:LspPeekDefinition| commands.
1872 *lsp-features-diagnostics*
1873 diagnostics Used to disable diagnostics for a single
1874 language server, by default diagnostics are
1875 combined from all running servers, by setting
1876 this to |false| you can ignore diagnostics
1877 from a specific server.
1878 *lsp-features-documentFormatting*
1879 documentFormatting Used by the |:LspFormat| command, and
1881 *lsp-features-documentHighlight*
1882 documentHighlight Used by the |:LspHighlight| and the
1883 |:LspHighlightClear| commands.
1884 *lsp-features-documentSymbol*
1885 documentSymbol Used by the |:LspDocumentSymbol| and the
1886 |:LspOutline| commands.
1887 *lsp-features-foldingRange*
1888 foldingRange Used by the|:LspFold| command.
1889 *lsp-features-hover*
1890 hover Used by the |:LspHover| command.
1891 *lsp-features-implementation*
1892 implementation Used by the |:LspGotoImpl| and the
1893 |:LspPeekImpl| commands.
1894 *lsp-features-inlayHint*
1895 inlayHint Used to show the inlay hints for
1896 function/method arguments.
1897 *lsp-features-references*
1898 references Used by the |:LspShowReferences| command.
1899 *lsp-features-rename*
1900 rename Used by the |:LspRename| command.
1901 *lsp-features-selectionRange*
1902 selectionRange Used by the |:LspSelectionExpand| and the
1903 |:LspSelectionShrink| commands.
1904 *lsp-features-signatureHelp*
1905 signatureHelp Used by the |:LspShowSignature| command.
1906 *lsp-features-typeDefinition*
1907 typeDefinition Used by the |:LspGotoTypeDef| and the
1908 |:LspPeekTypeDef| commands.
1909 typeHierarchy Used by the |:LspSubTypeHierarchy| and the
1910 |:LspSuperTypeHiearchy| commands.
1911 workspaceSymbol Used by the |:LspSymbolSearch| command.
1913 ==============================================================================
1915 License: MIT License
1916 Copyright (c) 2020-2023 Yegappan Lakshmanan
1918 Permission is hereby granted, free of charge, to any person obtaining a copy
1919 of this software and associated documentation files (the "Software"), to
1920 deal in the Software without restriction, including without limitation the
1921 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
1922 sell copies of the Software, and to permit persons to whom the Software is
1923 furnished to do so, subject to the following conditions:
1925 The above copyright notice and this permission notice shall be included in
1926 all copies or substantial portions of the Software.
1928 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1929 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1930 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1931 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1932 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
1933 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
1936 ==============================================================================
1938 vim:tw=78:ts=8:noet:ft=help:norl: