doc/lsp.txt

   1 *lsp.txt*       Language Server Protocol (LSP) Plugin for Vim9
   2
   3
   4 Author: Yegappan Lakshmanan  (yegappan AT yahoo DOT com)
   5 For Vim version 9.0 and above
   6 Last change: June 7, 2023
   7
   8 ==============================================================================
   9 CONTENTS                                                     *lsp-contents*
  10
  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|
  29
  30 ==============================================================================
  31 1. Overview                                     *lsp-overview*
  32
  33 The Language Server Protocol (LSP) plugin implements a LSP client for Vim9.
  34 Refer to the following pages for more information about LSP:
  35
  36     https://microsoft.github.io/language-server-protocol/
  37     https://langserver.org/
  38
  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
  42 languages.
  43
  44 The Github repository for this plugin is available at:
  45
  46       http://github.com/yegappan/lsp
  47
  48 ==============================================================================
  49 2. Installation                                 *lsp-installation*
  50
  51 You can install this plugin directly from github using the following steps:
  52
  53     $ mkdir -p $HOME/.vim/pack/downloads/opt
  54     $ cd $HOME/.vim/pack/downloads/opt
  55     $ git clone https://github.com/yegappan/lsp
  56
  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.
  59
  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.
  62
  63 To use this plugin, add the following line to your .vimrc file:
  64
  65     packadd lsp
  66
  67 ==============================================================================
  68 3. Usage                                        *lsp-usage*
  69
  70 The following commands are provided:
  71
  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 :LspDiagCurrent         Display the diagnostic message for the current line.
  77 :LspDiagFirst           Jump to the first diagnostic message for the current
  78                         buffer.
  79 :LspDiagHere            Jump to the next diagnostic message in the current
  80                         line.
  81 :LspDiagHighlightDisable
  82                         Disable highlighting lines with a diagnostic message
  83                         for the current Vim session.
  84 :LspDiagHighlightEnable Enable highlighting lines with a diagnostic message
  85                         for the current Vim session.
  86 :LspDiagLast            Jump to the last diagnostic message for the current
  87                         buffer.
  88 :LspDiagNext            Jump to the next diagnostic message for the current
  89                         buffer after the current cursor position.
  90 :LspDiagPrev            Jump to the previous diagnostic message for the
  91                         current buffer before the current current position.
  92 :LspDiagShow            Display the diagnostics messages from the language
  93                         server for the current buffer in a location list.
  94 :LspFold                Fold the current file
  95 :LspFormat              Format a range of lines in the current file using the
  96                         language server.  The default range is the entire
  97                         file.  See |lsp-format| for more information.
  98 :LspGotoDeclaration     Go to the declaration of the symbol under cursor
  99 :LspGotoDefinition      Go to the definition of the symbol under cursor
 100 :LspGotoImpl            Go to the implementation of the symbol under cursor
 101 :LspGotoTypeDef         Go to the type definition of the symbol under cursor
 102 :LspHighlight           Highlight all the matches for the keyword under cursor
 103 :LspHighlightClear      Clear all the matches highlighted by :LspHighlight
 104 :LspHover               Show the documentation for the symbol under the cursor
 105                         in a popup window.
 106 :LspIncomingCalls       Display the list of symbols calling the current symbol
 107                         in a window.
 108 :LspOutgoingCalls       Display the list of symbols called by the current
 109                         symbol in a window.
 110 :LspOutline             Show the list of symbols defined in the current file
 111                         in a separate window.
 112 :LspPeekDeclaration     Open the declaration of the symbol under cursor in a
 113                         popup window.
 114 :LspPeekDefinition      Open the definition of the symbol under cursor in a
 115                         popup window.
 116 :LspPeekImpl            Open the implementation of the symbol under cursor in
 117                         a popup window.
 118 :LspPeekReferences      Display the list of references to the symbol under
 119                         cursor in a popup window.
 120 :LspPeekTypeDef         Open the type definition of the symbol under cursor in
 121                         a popup window.
 122 :LspRename              Rename the current symbol
 123 :LspSelectionExpand     Expand the current symbol range visual selection
 124 :LspSelectionShrink     Shrink the current symbol range visual selection
 125 :LspServer              Command to display the status and messages from a
 126                         language server and to restart the language server.
 127 :LspShowAllServers      Display the status of all the registered language
 128                         servers.
 129 :LspShowReferences      Display the list of references to the keyword under
 130                         cursor in a new location list.
 131 :LspShowSignature       Display the signature of the symbol under cursor.
 132 :LspSubTypeHierarchy    Display the sub type hierarchy in a popup window.
 133 :LspSuperTypeHierarchy  Display the super type hierarchy in a popup window.
 134 :LspSwitchSourceHeader  Switch between a source and a header file.
 135 :LspSymbolSearch        Perform a workspace wide search for a symbol
 136 :LspWorkspaceAddFolder {folder}
 137                         Add a folder to the workspace
 138 :LspWorkspaceListFolders
 139                         Show the list of folders in the workspace
 140 :LspWorkspaceRemoveFolder {folder}
 141                         Remove a folder from the workspace
 142
 143 ==============================================================================
 144 4. Configuration                                *lsp-configuration*
 145                                         *LspAddServer()* *g:LspAddServer()*
 146
 147 To use the plugin features with a particular file type(s), you need to first
 148 register a language server for that file type(s).
 149
 150 To register one or more language servers, use the LspAddServer() function with
 151 a list of lanaguge server details in the .vimrc file.
 152
 153 To register a language server, add the following lines to your .vimrc file
 154 (use only the language servers that you need from the below list).
 155 If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the
 156 LSP plugin, the steps are described later in this section: >
 157
 158    vim9script
 159    var lspServers = [
 160                      {
 161                          name: 'typescriptls',
 162                          filetype: ['javascript', 'typescript'],
 163                          path: '/usr/local/bin/typescript-language-server',
 164                          args: ['--stdio']
 165                       },
 166                      {
 167                          name: 'pythonls',
 168                          filetype: 'python',
 169                          path: '/usr/local/bin/pyls',
 170                          args: ['--check-parent-process', '-v']
 171                       }
 172                    ]
 173    LspAddServer(lspServers)
 174 <
 175 Depending on the location of the typescript and python pyls language servers
 176 installed in your system, update the "path" in the above snippet
 177 appropriately.
 178
 179 Another example, for adding the language servers for the C, C++, Golang, Rust,
 180 Shell script, Vim script and PHP file types: >
 181
 182    vim9script
 183    var lspServers = [
 184                      {
 185                         name: 'clangd',
 186                         filetype: ['c', 'cpp'],
 187                         path: '/usr/local/bin/clangd',
 188                         args: ['--background-index']
 189                      },
 190                      {
 191                         name: 'golang',
 192                         filetype: ['go', 'gomod', 'gohtmltmpl', 'gotexttmpl'],
 193                         path: '/path/to/.go/bin/gopls',
 194                         args: [],
 195                         syncInit: true,
 196                       },
 197                      {
 198                         name: 'rustls',
 199                         filetype: ['rust'],
 200                         path: '/path/to/.cargo/bin/rust-analyzer',
 201                         args: [],
 202                         syncInit: true,
 203                       },
 204                      {
 205                         name: 'bashls',
 206                         filetype: 'sh',
 207                         path: '/usr/local/bin/bash-language-server',
 208                         args: ['start']
 209                      },
 210                      {
 211                         name: 'vimls',
 212                         filetype: ['vim'],
 213                         path: '/usr/local/bin/vim-language-server',
 214                         args: ['--stdio']
 215                      },
 216                      {
 217                         name: 'phpls',
 218                         filetype: ['php'],
 219                         path': '/usr/local/bin/intelephense',
 220                         args: ['--stdio'],
 221                         syncInit: true,
 222                         initializationOptions: {
 223                         licenceKey: 'xxxxxxxxxxxxxxx'
 224                         }
 225                       }
 226                    ]
 227    LspAddServer(lspServers)
 228 <
 229 To add a language server, the following information is needed:
 230
 231                                                 *lsp-cfg-name*
 232         name            (Optional) name of the language server.  Can by any
 233                         string.  Used in LSP messages and log files.
 234                                                 *lsp-cfg-path*
 235         path            complete path to the language server executable
 236                         (without any arguments).
 237                                                 *lsp-cfg-args*
 238         args            a |List| of command-line arguments passed to the
 239                         language server.  Each space separated language server
 240                         command-line argument is a separate List item.
 241                                                 *lsp-cfg-filetype*
 242         filetype        One or more file types supported by the language
 243                         server.  This can be a |String| or a |List|. To
 244                         specify multiple file types, use a List.
 245                                         *lsp-cfg-initializationOptions*
 246         initializationOptions
 247                         (Optional) for lsp servers (e.g. intelephense) some
 248                         additional initialization options may be required
 249                         or useful for initialization. Those can be provided in
 250                         this dictionary and if present will be transmitted to
 251                         the lsp server.
 252                                                 *lsp-cfg-workspaceConfig*
 253         workspaceConfig (Optional) a json encodable value that will be sent to
 254                         the language server after initialization as the
 255                         "settings" in a "workspace/didChangeConfiguration"
 256                         notification.  Refer to the language server
 257                         documentation for the values that will be accepted in
 258                         this notification.  This configuration is also used to
 259                         respond to the "workspace/configuration" request
 260                         message from the language server.
 261                                                 *lsp-cfg-rootSearch*
 262         rootSearch      (Optional) a List of file and directory names used to
 263                         locate the root path or uri of the workspace.  The
 264                         directory names in "rootSearch" must end in "/" or
 265                         "\".  Each file and directory name in "rootSearch" is
 266                         searched upwards in all the parent directories.  If
 267                         multiple directories are found, then the directory
 268                         closest to the directory of the current buffer is used
 269                         as the workspace root.
 270
 271                         If this parameter is not specified or the files are
 272                         not found, then the current working directory is used
 273                         as the workspace root for decendent files, for any
 274                         other files the parent directory of the file is used.
 275
 276                                                 *lsp-cfg-runIfSearch*
 277         runIfSearch     (Optional) a List of file and directory names used to
 278                         determinate if a server should run or not. The
 279                         directory names in "runIfSearch" must end in "/" or
 280                         "\".  Each file and directory name in "runIfSearch" is
 281                         searched upwards in all the parent directories.
 282                         Exactly like |lsp-cfg-rootSearch|.
 283
 284                         If a file or directory is found then the server will
 285                         be started, otherwise it will not.
 286
 287                         If this parameter is not specified or is an empty
 288                         list, then the server will be started unless
 289                         |lsp-cfg-runUnlessSearch| prevents it.
 290
 291                                                 *lsp-cfg-runUnlessSearch*
 292         runUnlessSearch (Optional) Opposite of |lsp-cfg-runIfSearch|.
 293
 294 Additionally the following configurations can be made:
 295
 296                                         *lsp-cfg-customNotificationHandlers*
 297         customNotificationHandlers
 298                         (Optional) some lsp servers (e.g.
 299                         typescript-language-server) will send additional
 300                         notifications which you might want to silence or
 301                         handle.  The provided notification handlers will be
 302                         called with a reference to the "lspserver" and the
 303                         "reply". >
 304
 305                 vim9script
 306                 g:LspAddServer([{
 307                         filetype: ['javascript', 'typescript'],
 308                         path: '/usr/local/bin/typescript-language-server',
 309                         args: ['--stdio'],
 310                         customNotificationHandlers: {
 311                                 '$/typescriptVersion': (lspserver, reply) => {
 312                                         echom printf("TypeScript Version = %s",
 313                                                 reply.params.version)
 314                                 }
 315                         }
 316                 }])
 317 <
 318                                         *lsp-cfg-customRequestHandlers*
 319         customRequestHandlers
 320                         (Optional) some lsp servers will send additional
 321                         request replies which you might want to silence or
 322                         handle.  The provided request handlers will be called
 323                         with a reference to the "lspserver" and the "request".
 324                                                 *lsp-cfg-features*
 325         features
 326                         (Optional) toggle which features should be enabled for
 327                         a given language server. See |lsp-multiple-servers|
 328                         and |lsp-features| for more information.
 329                                                 *lsp-cfg-omnicompl*
 330         omnicompl       (Optional) a boolean value that enables (true)
 331                         or disables (false) omni-completion for these file
 332                         types. By default this is set to "v:true".  This value
 333                         is applicable only if auto completion is disabled
 334                         (|lsp-opt-autoComplete|).
 335                                                 *lsp-cfg-processDiagHandler*
 336         processDiagHandler
 337                         (Optional) A |Funcref| or |lambda| that takes a list
 338                         of language server diagnostics and returns a new list
 339                         of filtered, or otherwise changed diagnostics.  Can be
 340                         used to remove unwanted diagnostics, prefix the
 341                         diagnostics text, etc.  The following example will
 342                         remove all but errors and warnings: >
 343
 344                 vim9script
 345                 g:LspAddServer([{
 346                         filetype: ['javascript', 'typescript'],
 347                         path: '/usr/local/bin/typescript-language-server',
 348                         args: ['--stdio'],
 349                         processDiagHandler: (diags: list<dict<any>>) => {
 350                                 # Only include errors and warnings
 351                                 return diags->filter((diag, ix) => {
 352                                         return diag.severity <= 2
 353                                 })
 354                         },
 355                 }])
 356 <
 357                         And this example will prefix the diagnostic message
 358                         with the string "TypeScript: ": >
 359
 360                 vim9script
 361                 g:LspAddServer([{
 362                         filetype: ['javascript', 'typescript'],
 363                         path: '/usr/local/bin/typescript-language-server',
 364                         args: ['--stdio'],
 365                         processDiagHandler: (diags: list<dict<any>>) => {
 366                                 return diags->map((diag, ix) => {
 367                                         diag.message = $'TypeScript: {diag.message}'
 368                                         return diag
 369                                 })
 370                         },
 371                 }])
 372 <
 373                                                 *lsp-cfg-syncInit*
 374         syncInit        (Optional) for language servers (e.g. rust analyzer,
 375                         gopls, etc.) that take time to initialize and reply to
 376                         a "initialize" request message this should be set to
 377                         "true". If this is set to true, then a synchronous
 378                         call is used to initialize the language server,
 379                         otherwise the server is initialized asynchronously.
 380                         By default this is set to "false".
 381                                                 *lsp-cfg-debug*
 382         debug           (Optional) log the messages printed by this language
 383                         server in stdout and stderr to a file.  Useful for
 384                         debugging a language server.  By default the
 385                         messages are not logged.  See |lsp-debug| for more
 386                         information.
 387                                                 *lsp-cfg-traceLevel*
 388         traceLevel      (Optional) set the debug trace level for this language
 389                         server.  Supported values are: "off", "debug" and
 390                         "verbose".  By default this is seto "off".
 391
 392 The language servers are added using the LspAddServer() function. This
 393 function accepts a list of language servers with the above information.
 394
 395 If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the
 396 LSP plugin, then you need to use the VimEnter autocmd to initialize the
 397 language server and to set the language server options.  For example: >
 398
 399     vim9script
 400     var lspServers = [
 401                      {
 402                         name: 'clangd',
 403                         filetype: ['c', 'cpp'],
 404                         path: '/usr/local/bin/clangd',
 405                         args: ['--background-index']
 406                       }
 407                    ]
 408     autocmd VimEnter * LspAddServer(lspServers)
 409
 410     var lspOpts = {'autoHighlightDiags': true}
 411     autocmd VimEnter * LspOptionsSet(lspOpts)
 412 <
 413                                                 *lsp-options* *LspOptionsSet*
 414                                                 *g:LspOptionsSet*
 415
 416 Some of the LSP plugin features can be enabled or disabled by using the
 417 LspOptionsSet() function. This function accepts a dictionary argument with the
 418 following optional items:
 419
 420                                                 *lsp-opt-aleSupport*
 421 aleSupport              |Boolean| option. If true, diagnostics will be sent to
 422                         Ale, instead of being displayed by this plugin.
 423                         This is useful to combine all LSP and linter
 424                         diagnostics. By default this is set to false.
 425                                                 *lsp-opt-autoComplete*
 426 autoComplete            |Boolean| option. In insert mode, automatically
 427                         complete the current symbol. Otherwise use
 428                         omni-completion. By default this is set to true.
 429                                                 *lsp-opt-autoHighlight*
 430 autoHighlight           |Boolean| option. In normal mode, automatically
 431                         highlight all the occurrences of the symbol under the
 432                         cursor. By default this is set to false.
 433                                                 *lsp-opt-autoHighlightDiags*
 434 autoHighlightDiags      |Boolean| option. Automatically place signs on the
 435                         lines with a diagnostic message from the language
 436                         server. By default this is set to true.
 437                                                 *lsp-opt-autoPopulateDiags*
 438 autoPopulateDiags       |Boolean| option. Automatically populate the location
 439                         list with diagnostics from the language server.
 440                         By default this is set to false.
 441                                                 *lsp-opt-completionMatcher*
 442 completionMatcher       |String| option.  Enable fuzzy or case insensitive
 443                         completion for language servers that replies with a
 444                         full list of completion items.  Some language servers
 445                         does completion filtering in the server, while other
 446                         relies on the client to do the filtering.
 447
 448                         This option only works for language servers that
 449                         expect the client to filter the completion items.
 450
 451                         This option accepts one of the following values:
 452                             case  - case sensitive matching (default).
 453                             fuzzy - fuzzy match completion items.
 454                             icase - ignore case when matching items.
 455                                                 *lsp-opt-completionTextEdit*
 456 completionTextEdit      |Boolean| option.  If true, apply the LSP server
 457                         supplied text edits after a completion.  If a snippet
 458                         plugin is going to apply the text edits, then set
 459                         this to false to avoid applying the text edits twice.
 460                         By default this is set to true.
 461                                                 *lsp-opt-completionKinds*
 462 completionKinds         |Dictionary| option. See |lsp-custom-kinds| for all
 463                         completion kind names.
 464                                         *lsp-opt-customCompletionKinds*
 465 customCompletionKinds   |Boolean| option.  If you set this to true, you can
 466                         set custom completion kinds using the option
 467                         completionKinds.
 468                                                 *lsp-opt-diagSignErrorText*
 469 diagSignErrorText       |String| option. Change diag sign text for errors
 470                         By default 'E>'
 471                                                 *lsp-opt-diagSignHintText*
 472 diagSignHintText        |String| option. Change diag sign text for hints
 473                         By default 'H>',
 474                                                 *lsp-opt-diagSignInfoText*
 475 diagSignInfoText        |String| option. Change diag sign text for info
 476                         By default 'I>',
 477                                                 *lsp-opt-diagSignWarningText*
 478 diagSignWarningText     |String| option. Change diag sign text for warnings
 479                         By default 'W>',
 480                                                 *lsp-opt-diagVirtualTextAlign*
 481 diagVirtualTextAlign    |String| option.   Alignment of diagnostics messages
 482                         if |lsp-opt-showDiagWithVirtualText| is set to true.
 483                         Allowed values are 'above', 'below' or 'after'
 484                         By default this is set to 'above',
 485                                                 *lsp-opt-echoSignature*
 486 echoSignature           |Boolean| option.  In insert mode, echo the current
 487                         symbol signature instead of showing it in a popup.
 488                         By default this is set to false.
 489                                         *lsp-opt-hideDisabledCodeActions*
 490 hideDisabledCodeActions |Boolean| option. Hide all the disabled code actions.
 491                         By default this is set to false.
 492                                                 *lsp-opt-highlightDiagInline*
 493 highlightDiagInline     |Boolean| option.  Highlight the diagnostics inline
 494                         By default this is set to false.
 495                                                 *lsp-opt-hoverInPreview*
 496 hoverInPreview          |Boolean| option. Show |:LspHover| in a preview window
 497                         instead of a popup.
 498                         By default this is set to false.
 499                                                 *lsp-opt-ignoreMissingServer*
 500 ignoreMissingServer     |Boolean| option.  Do not print a missing language
 501                         server executable.  By default this is set to false.
 502                                                 *lsp-opt-keepFocusInDiags*
 503 keepFocusInDiags        |Boolean| option.  Focus on the location list window
 504                         after LspDiagShow.
 505                         By default this is set to true.
 506                                         *lsp-opt-keepFocusInReferences*
 507 keepFocusInReferences   |Boolean| option.  Focus on the location list window
 508                         after LspShowReferences.
 509                         By default this is set to true.
 510                                                 *lsp-opt-noDiagHoverOnLine*
 511 noDiagHoverOnLine       |Boolean| option.  Suppress diagnostic hover from
 512                         appearing when the mouse is over the line instead of
 513                         the signature.
 514                         By default this is set to true.
 515                                         *lsp-opt-noNewlineInCompletion*
 516 noNewlineInCompletion   |Boolean| option.  Suppress adding a new line on
 517                         completion selection with <CR>.
 518                         By default this is set to false.
 519                                                 *lsp-opt-outlineOnRight*
 520 outlineOnRight          |Boolean| option.  Open the outline window on the
 521                         right side, by default this is false.
 522                                                 *lsp-opt-outlineWinSize*
 523 outlineWinSize          |Number| option.  The size of the symbol Outline
 524                         window.  By default this is set to 20.
 525                                                 *lsp-opt-showDiagInPopup*
 526 showDiagInPopup         |Boolean| option.  When using the |:LspDiagCurrent|
 527                         command to display the diagnostic message for the
 528                         current line, use a popup window to display the
 529                         message instead of echoing in the status area.
 530                         By default this is set to true.
 531                                                 *lsp-opt-showDiagOnStatusLine*
 532 showDiagOnStatusLine    |Boolean| option.  Show a diagnostic message on a
 533                         status line.  By default this is set to false.
 534                                         *lsp-opt-showDiagWithVirtualText*
 535 showDiagWithVirtualText |Boolean| option.  Show diagnostic message text from
 536                         the language server with virtual text.  By default
 537                         this is set to false.  The "autoHighlightDiags" option
 538                         should be set to true.
 539                         Needs Vim version 9.0.1157 or later.
 540                                                 *lsp-opt-showInlayHints*
 541 showInlayHints          |Boolean| option.  Show inlay hints from the language
 542                         server.  By default this is set to false.  The inlay
 543                         hint text is displayed as a virtual text.  Needs Vim
 544                         version 9.0.0178 or later.
 545                                                 *lsp-opt-showSignature*
 546 showSignature           |Boolean| option.  In insert mode, automatically show
 547                         the current symbol signature in a popup.
 548                         By default this is set to true.
 549                                                 *lsp-opt-snippetSupport*
 550 snippetSupport          |Boolean| option.  Enable snippet completion support.
 551                         Need a snippet completion plugin like vim-vsnip.
 552                         By default this is set to false.
 553                                                 *lsp-opt-ultisnipsSupport*
 554 ultisnipsSupport        |Boolean| option.  Enable SirVer/ultisnips support.
 555                         Need a snippet completion plugin SirVer/ultisnips.
 556                         By default this is set to false.
 557                                                 *lsp-opt-vssnipSupport*
 558 vsnipSupport            |Boolean| option.  Enable hrsh7th/vim-vsnip support.
 559                         Need snippet completion plugins hrsh7th/vim-vsnip
 560                         and hrsh7th/vim-vsnip-integ.  Make sure
 561                         ultisnipsSupport is set to false before enabling this.
 562                         By default this option is set to false.
 563                                                 *lsp-opt-usePopupInCodeAction*
 564 usePopupInCodeAction    |Boolean| option.  When using the |:LspCodeAction|
 565                         command to display the code action for the current
 566                         line, use a popup menu instead of echoing.
 567                         By default this is set to false.
 568                                         *lsp-opt-useQuickfixForLocations*
 569 useQuickfixForLocations |Boolean| option.  Show |:LspShowReferences| in a
 570                         quickfix list instead of a location list.
 571                         By default this is set to false.
 572                                                 *lsp-opt-useBufferCompletion*
 573 useBufferCompletion     |Boolean| option. If enabled, the words from the
 574                         current buffer are added to the auto completion list.
 575                         This may degrade Vim performance as the current buffer
 576                         contents are processed every time the completion menu
 577                         is displayed.
 578                         By default this is set to false.
 579
 580 For example, to disable the automatic placement of signs for the LSP
 581 diagnostic messages, you can add the following line to your .vimrc file: >
 582
 583         LspOptionsSet({'autoHighlightDiags': false})
 584 <
 585 The LspOptionsGet() function returns a |Dict| of all the LSP plugin options,
 586 To get a particular option value you can use the following: >
 587
 588         echo LspOptionsGet()['autoHighlightDiags']
 589 <
 590 ==============================================================================
 591 5. Commands                                     *lsp-commands*
 592
 593 A description of the various commands provided by this plugin is below.  You
 594 can map these commands to keys and make it easier to invoke them.
 595
 596                                                 *:LspCodeAction*
 597 :LspCodeAction [query]  Apply the code action supplied by the language server
 598                         to the diagnostic in the current line. This works only
 599                         if there is a diagnostic message for the current line.
 600                         You can use the |:LspDiagCurrent| command to display
 601                         the diagnostic for the current line.
 602
 603                         When [query] is given the code action starting with
 604                         [query] will be applied. [query] can be a regexp
 605                         pattern, or a digit corresponding to the index of the
 606                         code actions in the created prompt.
 607
 608                         When [query] is not given you will be prompted to
 609                         select one of the actions supplied by the language
 610                         server.
 611
 612                                                 *:LspCodeLens*
 613 :LspCodeLens            Display a list of code lens commands available for the
 614                         current buffer and apply the selected code lens
 615                         command.
 616
 617                                                 *:LspDiagCurrent*
 618 :LspDiagCurrent         Displays the diagnostic message (if any) for the
 619                         current line.  If the option 'showDiagInPopup' is set
 620                         to true (default), then the message is displayed in
 621                         a popup window.  Otherwise the message is displayed in
 622                         the status message area.
 623
 624 :LspDiagCurrent!        Only display a diagnostic message if it's directly
 625                         under the cursor.  Otherwise works exactly like
 626                         |:LspDiagCurrent|
 627
 628                         To show the current diagnotic under the cursor while
 629                         moving around the following autocmd can be used: >
 630
 631                             augroup LspCustom
 632                             au!
 633                             au CursorMoved * silent! LspDiagCurrent!
 634                             augroup END
 635 <
 636                                                 *:LspDiagFirst*
 637 :LspDiagFirst           Jumps to the location of the first diagnostic message
 638                         for the current file.
 639
 640                                                 *:LspDiagHere*
 641 :LspDiagHere            Jumps to the location of the diagnostic message in
 642                         the current line (start from current column).
 643
 644 :LspDiagHighlightDisable                        *:LspDiagHighlightDisable*
 645                         Disable highlighting lines with a diagnostic message
 646                         for the current Vim session.
 647                         To always disable the highlighting, set the
 648                         autoHighlightDiags option to false.
 649
 650                                                 *:LspDiagHighlightEnable*
 651 :LspDiagHighlightEnable Enable highlighting lines with a diagnostic message
 652                         for the current Vim session.  Note that highlighting
 653                         lines with a diagnostic message is enabled by default.
 654
 655                                                 *:LspDiagLast*
 656 :LspDiagLast            Jumps to the location of the first diagnostic message
 657                         for the current file.
 658
 659                                                 *:LspDiagNext*
 660 :[count]LspDiagNext     Go to the [count] diagnostic message after the current
 661                         cursor position.  If [count] is omitted, then 1 is
 662                         used.  If [count] exceeds the number of diagnostics
 663                         after the current position, then the last diagnostic
 664                         is selected.
 665
 666                                                 *:LspDiagPrev*
 667 :[count]LspDiagPrev     Go to the [count] diagnostic message before the
 668                         current cursor position.  If [count] is omitted, then
 669                         1 is used.  If [count] exceeds the number of
 670                         diagnostics before the current position, then first
 671                         last diagnostic is selected.
 672
 673                                                 *:LspDiagShow*
 674 :LspDiagShow            Creates a new location list with the diagnostics
 675                         messages (if any) from the language server for the
 676                         current file and opens the location list window. You
 677                         can use the Vim location list commands to browse the
 678                         list.
 679
 680                                                 *:LspFold*
 681 :LspFold                Create folds for the current buffer.
 682
 683                                                 *:LspFormat*
 684 :LspFormat              Format the current file using the language server. The
 685                         'shiftwidth' and 'expandtab' values set for the
 686                         current buffer are used when format is applied.
 687
 688 :{range}LspFormat       Format the specified range of lines in the current
 689                         file using the language server.
 690
 691                                                 *:LspGotoDeclaration*
 692 :[count]LspGotoDeclaration
 693                         Jumps to the declaration of the symbol under the
 694                         cursor. The behavior of this command is similar to the
 695                         |:LspGotoDefinition| command.
 696
 697                                                 *:LspGotoDefinition*
 698 :[count]LspGotoDefinition
 699                         Jumps to the [count] definition of the symbol under
 700                         the cursor.  If there are multiple matches and [count]
 701                         isn't specified, then a location list will be created
 702                         with the list of locations.
 703
 704                         If there is only one location, or [count] is provided
 705                         then the following will apply:
 706
 707                         If the file is already present in a window, then jumps
 708                         to that window.  Otherwise, opens the file in a new
 709                         window.  If the current buffer is modified and
 710                         'hidden' is not set or if the current buffer is a
 711                         special buffer, then a new window is opened.  If the
 712                         jump is successful, then the current cursor location
 713                         is pushed onto the tag stack.  The |CTRL-T| command
 714                         can be used to go back up the tag stack.  Also the
 715                         |``| mark is set to the position before the jump.
 716
 717                         This command supports |:command-modifiers|.  You can
 718                         use the modifiers to specify whether a new window or
 719                         a new tab page is used and where the window is opened.
 720                         Example(s): >
 721
 722                             # Open a horizontally split window
 723                             :topleft LspGotoDefinition
 724                             # Open a vertically split window
 725                             :vert LspGotoDefinition
 726                             # Open a new tab page
 727                             :tab LspGotoDefinition
 728 <
 729                         You may want to map a key to invoke this command: >
 730
 731             nnoremap <buffer> gd <Cmd>LspGotoDefinition<CR>
 732             nnoremap <buffer> <C-W>gd <Cmd>topleft LspGotoDefinition<CR>
 733 <
 734                         Or if you want to support [count]gd >
 735
 736             nnoremap <buffer> gd <Cmd>execute v:count .. 'LspGotoDefinition'<CR>
 737             nnoremap <buffer> <C-W>gd <Cmd>execute 'topleft ' .. v:count .. 'LspGotoDefinition'<CR>
 738 <
 739                                                 *:LspGotoImpl*
 740 :[count]LspGotoImpl     Jumps to the implementation of the symbol under the
 741                         cursor. The behavior of this command is similar to the
 742                         |:LspGotoDefinition| command. Note that not all the
 743                         language servers support this feature.
 744
 745                         You may want to map a key to invoke this command: >
 746
 747                             nnoremap <buffer> gi <Cmd>LspGotoImpl<CR>
 748 <
 749                                                 *:LspGotoTypeDef*
 750 :[count]LspGotoTypeDef  Jumps to the type definition of the symbol under the
 751                         cursor. The behavior of this command is similar to the
 752                         |:LspGotoDefinition| command. Note that not all the
 753                         language servers support this feature.
 754
 755                         You may want to map a key to invoke this command: >
 756
 757                             nnoremap <buffer> gt <Cmd>LspGotoTypeDef<CR>
 758 <
 759                                                 *:LspHighlight*
 760 :LspHighlight           Highlights all the matches for the symbol under
 761                         cursor. The text, read and write references to the
 762                         symbol are highlighted using Search, DiffChange and
 763                         DiffDelete highlight groups respectively.
 764
 765                                                 *:LspHighlightClear*
 766 :LspHighlightClear      Clears all the symbol matches highlighted by the
 767                         |:LspHighlight| command.
 768
 769                                                 *:LspHover*
 770 :LspHover               Show the documentation for the symbol under the cursor
 771                         in a popup window. If you want to show the symbol
 772                         documentation in the preview window instead of in a
 773                         popup set >
 774
 775                             LspOptionsSet({'hoverInPreview': true})
 776 <
 777                         You can use the |K| key in normal mode to display the
 778                         documentation for the keyword under the cursor by
 779                         setting the 'keywordprg' Vim option: >
 780
 781                             :set keywordprg=:LspHover
 782 <
 783                                                 *:LspIncomingCalls*
 784 :LspIncomingCalls       Display a hierarchy of symbols calling the symbol
 785                         under the cursor in a window.  See
 786                         |lsp-call-hierarchy| for more information.  Note that
 787                         not all the language servers support this feature.
 788
 789                                                 *:LspOutoingCalls*
 790 :LspOutoingCalls        Display a hierarchy of symbols called by the symbol
 791                         under the cursor in a window.  See
 792                         |lsp-call-hierarchy| for more information.  Note that
 793                         not all the language servers support this feature.
 794
 795                                                 *:LspOutline*
 796 :[count]LspOutline      Opens a vertically split window with the list of
 797                         symbols defined in the current file. The current
 798                         symbol is highlighted. The symbols are grouped by
 799                         their type. You can select a symbol and press <Enter>
 800                         to jump to the position of the symbol. As you move the
 801                         cursor in a file, the current symbol is automatically
 802                         highlighted in the outline window. If you open a new
 803                         file, the outline window is automatically updated with
 804                         the symbols in the new file.  Folds are created in the
 805                         outline window for the various group of symbols.
 806
 807                         You can use |lsp-opt-outlineOnRight| and
 808                         |lsp-opt-outlineWinSize| to customize the placement
 809                         and size of the window.
 810
 811                         This command also supports |:command-modifiers|.  You
 812                         can use the modifiers specify the position of the
 813                         window.  Note that the default is ":vert :topleft" or
 814                         ":vert :botright" depending on
 815                         |lsp-opt-outlineOnRight|
 816
 817                         This command also supports providing a [count] to
 818                         specify the size of the window.  Note that this
 819                         overrides the values defined in
 820                         |lsp-opt-outlineWinSize|.
 821                         Example: >
 822
 823                             # Open the outline window just above the current
 824                             # window
 825                             :aboveleft LspOutline
 826
 827                             # Open the outline window just next to the current
 828                             # window, this is different from the default, when
 829                             # you have multiple splits already
 830                             :vert aboveleft LspOutline
 831
 832                             # Same as above, but with a width of 50
 833                             :vert aboveleft 50LspOutline
 834 <
 835                                                 *:LspPeekDeclaration*
 836 :[count]LspPeekDeclaration
 837                         Displays the line where the symbol under the
 838                         cursor is declared in a popup window. The
 839                         behavior of this command is similar to the
 840                         |:LspPeekDefinition| command.
 841
 842                                                 *:LspPeekDefinition*
 843 :[count]LspPeekDefinition
 844                         Displays the line where the symbol under the cursor is
 845                         defined in a popup window. The symbol is highlighted
 846                         in the popup window. Moving the cursor or pressing
 847                         <Esc> will close the popup window.
 848                         When more than one symbol is found all of them will be
 849                         shown.  The corresponding file for the symbol is
 850                         displayed in another popup window.  As the selection
 851                         in the symbol popup menu changes, the file in the
 852                         popup is updated.
 853                         When [count] is provided only the [count] symbol will
 854                         be shown.
 855
 856                                                 *:LspPeekImpl*
 857 :[count]LspPeekImpl     Displays the implementation of the symbol under the
 858                         cursor in a popup window. The behavior of this
 859                         command is similar to the |:LspPeekDefinition|
 860                         command. Note that not all the language servers
 861                         support this feature.
 862
 863                                                 *:LspPeekReferences*
 864 :LspPeekReferences      Displays the list of references to the symbol under
 865                         cursor in a popup menu.  The corresponding file for
 866                         the reference is displayed in another popup window.
 867                         As the selection in the reference popup menu changes,
 868                         the file in the popup is updated.
 869
 870                                                 *:LspPeekTypeDef*
 871 :[count]LspPeekTypeDef  Displays the line where the type of the symbol under
 872                         the cursor is defined in a popup window. The
 873                         behavior of this command is similar to the
 874                         |:LspPeekDefinition| command. Note that not all the
 875                         language servers support this feature.
 876
 877                                                 *:LspRename*
 878 :LspRename [newName]    Rename the current symbol.
 879
 880                         When [newName] is not given, then you will be prompted
 881                         to enter the new name for the symbol. You can press
 882                         <Esc> or enter an empty string in the prompt to cancel
 883                         the operation.
 884
 885                                                 *:LspSelectionExpand*
 886 :LspSelectionExpand     Visually select the region of the symbol under the
 887                         cursor.  In visual mode, expands the current symbol
 888                         visual region selection to include the next level.
 889
 890                         For example, if the cursor is on a "for" statement,
 891                         this command selects the "for" statement and the body
 892                         of the "for" statement.
 893
 894                         It is useful to create a visual map to use this
 895                         command.  Example: >
 896
 897                         xnoremap <silent> <Leader>e <Cmd>LspSelectionExpand<CR>
 898 <
 899                         With the above map, you can press "\e" in visual mode
 900                         successively to expand the current symbol visual
 901                         region.
 902
 903                                                 *:LspSelectionShrink*
 904 :LspSelectionShrink     Shrink the current symbol range visual selection. It
 905                         is useful to create a visual map to use this command.
 906                         Example: >
 907
 908                         xnoremap <silent> <Leader>s <Cmd>LspSelectionShrink<CR>
 909 <
 910                         With the above map, you can press "\s" in visual mode
 911                         successively to shrink the current symbol visual
 912                         region.
 913
 914                                                 *:LspServer*
 915 :LspServer { debug | restart | show | trace }
 916                         Command to display and control the language server for
 917                         the current buffer.  Each argument has additional
 918                         sub-commands which are described below.
 919
 920                         debug { on | off | messages | errors }
 921                             Command to enable or disable the language server
 922                             debug messages and to display the debug messages
 923                             and error messages received from the language
 924                             server.  The following sub-commands are supported:
 925                                 errors  Open the log file containing the
 926                                         language server error messages.
 927                                 messages
 928                                         Open the log file containing the
 929                                         language server debug messages.
 930                                 off     Disable the logging of the language
 931                                         server messages.
 932                                 on      Enable the logging of the messages
 933                                         emitted by the language server in the
 934                                         standard output and standard error.
 935                             By default, the language server messages are not
 936                             logged.  On a Unix-like system, when enabled,
 937                             these messages are logged to the
 938                             /tmp/lsp-<server-name>.log and
 939                             /tmp/lsp-<server-name>.err file respectively.  On
 940                             MS-Windows, the %TEMP%/lsp-<server-name>.log and
 941                             %TEMP%/lsp-<server-name>.err% files are used. See
 942                             |lsp-debug| for more information.
 943
 944                         restart
 945                             Restart (stop and then start) the language server
 946                             for the current buffer. All the loaded buffers
 947                             with the same filetype as the current buffer are
 948                             added back to the server.
 949
 950                         show {capabilities | initializeRequest | messages
 951                                                                 | status}
 952                             The following sub-commands are supported:
 953                                 capabilities
 954                                         Display the list of language server
 955                                         capabilities for the current buffer.
 956                                         The server capabilities are described
 957                                         in the LSP protocol specification
 958                                         under the "ServerCapabilities"
 959                                         interface.
 960                                 initializeRequest
 961                                         Display the contents of the language
 962                                         server initialization request message
 963                                         (initialize).
 964                                 messages
 965                                         Display the log messages received from
 966                                         the language server.  This includes
 967                                         the messages received using the
 968                                         "window/logMessage" and "$/logTrace"
 969                                         LSP notifications.
 970                                 status
 971                                         Display the language server status for
 972                                         the current buffer.  The output shows
 973                                         the path to the language server
 974                                         executable and the server status.
 975
 976                         trace { off | messages | verbose }
 977                             Set the language server debug trace value using
 978                             the "$/setTrace" command.
 979
 980                                                 *:LspShowAllServers*
 981 :LspShowAllServers      Displays the list of registered language servers and
 982                         their status.  The language servers are registered
 983                         using the LspAddServer() function.  The output is
 984                         displayed in a scratch buffer.  The output shows the
 985                         Vim file type, the corresponding language server
 986                         status and the path to the language server executable.
 987                         The language server information for each buffer is
 988                         also shown.
 989
 990                                                 *:LspShowReferences*
 991 :LspShowReferences      Creates a new location list with the list of locations
 992                         where the symbol under the cursor is referenced and
 993                         opens the location window.  If you want to show the
 994                         references in a quickfix list instead of in a location
 995                         list set >
 996
 997                         LspOptionsSet({'useQuickfixForLocations': true})
 998 <
 999                                                 *:LspShowSignature*
1000 :LspShowSignature       Displays the signature of the symbol (e.g. a function
1001                         or method) before the cursor in a popup.
1002
1003                         The popup is also automatically displayed in insert
1004                         mode after entering a symbol name followed by a
1005                         separator (e.g. a opening parenthesis). To disable
1006                         this, you can set the showSignature option to false in
1007                         your .vimrc file: >
1008
1009                         LspOptionsSet({'showSignature': false})
1010 <
1011                         Default is true.
1012
1013                         You can get the function signature echoed in cmdline
1014                         rather than displayed in popup if you use >
1015
1016                         LspOptionsSet({'echoSignature': true})
1017 <
1018                         Default is false.
1019
1020                                                 *:LspSubTypeHierarchy*
1021 :LspSubTypeHierarchy    Show the sub type hierarchy for the symbol under the
1022                         cursor in a popup window.  The file containing the
1023                         type is shown in another popup window.  You can jump
1024                         to the location where a type is defined by browsing
1025                         the popup menu and selecting an entry.
1026
1027                                                 *:LspSuperTypeHierarchy*
1028 :LspSuperTypeHierarchy  Show the super type hierarchy for the symbol under the
1029                         cursor in a popup window.  The file containing the
1030                         type is shown in another popup window.  As the current
1031                         entry in the type hierarchy popup menu changes, the
1032                         file popup window is updated to show the location
1033                         where the type is defined.  You can jump to the
1034                         location where a type is defined by selecting the
1035                         entry in the popup menu.
1036
1037                         Note that the type hierarchy support is based on the
1038                         protocol supported by clangd.  This is different from
1039                         the one specified in the 3.17 of the LSP standard.
1040
1041                                                 *:LspSwitchSourceHeader*
1042 :LspSwitchSourceHeader  Switch between source and header files. This is a
1043                         Clangd specific extension and only works with C/C++
1044                         source files.
1045
1046                                                 *:LspSymbolSearch*
1047 :LspSymbolSearch <sym>  Perform a workspace wide search for the symbol <sym>.
1048                         If <sym> is not supplied, then you will be prompted to
1049                         enter the symbol name (the keyword under the cursor is
1050                         used as the default).  A popup window is opened with
1051                         the list of matching symbols.  You can enter a few
1052                         characters to narrow down the list of matches. The
1053                         displayed symbol name can be erased by pressing
1054                         <Backspace> or <C-U> and a new symbol search pattern
1055                         can be entered.  You can close the popup menu by
1056                         pressing the escape key or by pressing CTRL-C.
1057
1058                         In the popup menu, the following keys can be used:
1059
1060                                 CTRL-F     - Scroll one page forward
1061                                 <PageDown> - idem
1062                                 CTRL-B     - Scroll one page backward
1063                                 <PageUp>   - idem
1064                                 CTRL-Home  - Jump to the first entry
1065                                 CTRL-End   - Jump to the last entry
1066                                 <Up>       - Go up one entry
1067                                 <C-P>      - idem
1068                                 <Down>     - Go down one entry
1069                                 <C-N>      - idem
1070                                 <Enter>    - Open the selected file
1071                                 <Esc>      - Close the popup menu
1072                                 <CTRL-C>   - idem
1073                                 <BS>       - Erase one character from the
1074                                              filter text
1075                                 <C-H>      - idem
1076                                 <C-U>      - Erase the filter text
1077
1078                         Any other alphanumeric key will be used to narrow down
1079                         the list of names displayed in the popup menu. When
1080                         you type a filter string, then only the symbols fuzzy
1081                         matching the string are displayed in the popup menu.
1082                         You can enter a new search pattern to do a workspace
1083                         wide symbol search.
1084
1085                                                 *:LspWorkspaceAddFolder*
1086 :LspWorkspaceAddFolder {folder}
1087                         Add a folder to the workspace
1088
1089 :LspWorkspaceListFolders                        *:LspWorkspaceListFolders*
1090                         Show the list of folders in the workspace.
1091
1092                                                 *:LspWorkspaceRemoveFolder*
1093 :LspWorkspaceRemoveFolder {folder}
1094                         Remove a folder from the workspace
1095
1096 ==============================================================================
1097 6. Insert mode completion                   *lsp-ins-mode-completion*
1098
1099 By default, in insert mode, the LSP plugin automatically displays the matches
1100 for the symbol under the cursor in an insert-completion popup menu. You can
1101 use the keys described in |popupmenu-keys| with this menu.
1102
1103 To disable the auto-completion for all the files, you can set the
1104 'autoComplete' option to false in your .vimrc file: >
1105
1106         LspOptionsSet({'autoComplete': false})
1107 <
1108 If this variable is set, then the LSP plugin will not automatically start
1109 completion in insert mode and instead supports omni-completion (|compl-omni|).
1110 It sets the 'omnifunc' option for the buffers which have a registered language
1111 server. To complete a symbol in insert mode manually, you can press CTRL-X
1112 CTRL-O to invoke completion using the items suggested by the language server.
1113
1114 You can also enable or disable omni-completion for a specific language
1115 server by setting the 'omnicompl' item to 'false' when registering a lsp
1116 server for the filetype. If this item is not specified, then omni-completion
1117 is enabled by default. The following example disables omni-completion for
1118 python: >
1119
1120     vim9script
1121     var lspServers = [
1122                      {
1123                         filetype: 'python',
1124                         omnicompl: false,
1125                         path: '/usr/local/bin/pyls',
1126                         args: ['--check-parent-process', '-v']
1127                      }
1128                    ]
1129 <
1130 If you want to use omni completion, in addition to the automatic completion,
1131 then you can set the 'omnifunc' option to the "g:LspOmniFunc" function: >
1132
1133         set omnifunc=g:LspOmniFunc
1134 <
1135 To use omni completion, press CTRL-X CTRL-O in insert mode.  Refer to
1136 |compl-omni| for more information.
1137
1138 When doing insert-mode completion, the plugin sends a request message to the
1139 language server to return a list of possible completion matches for the
1140 current cursor position.  The plugin retrieves the keyword before the cursor
1141 (see 'iskeyword') and then filters the returned list of completion items
1142 against this keyword and displays the completion menu.  Some language servers
1143 does completion filtering in the server, while other relies on the client to
1144 do the filtering.  By default, case sensitive comparison is used to filter the
1145 returned items.  You can modify the 'completionMatcher' option to use either
1146 case insensitive or fuzzy comparison.
1147
1148 ==============================================================================
1149 7. Diagnostics                                          *lsp-diagnostics*
1150
1151 When a source file has syntax errors or warnings or static analysis warnings,
1152 the LSP plugin highlights them by placing |signs| in the |sign-column|.  You
1153 can use the |:LspDiagShow| command to display all the diagnostic messages for
1154 the current file in a |location-list-window|.  You can use the |:LspDiagFirst|
1155 command to jump to the line with the first diagnostic message, the
1156 |:LspDiagNext| command to jump to the next nearest line with the diagnostic
1157 message, the |:LspDiagPrev| command to jump to the previous nearest line with
1158 the diagnostic message, the |:LspDiagHere| command to jump to the diagnostic
1159 message in the current line.  You can use the |:LspDiagCurrent| command to
1160 display the entire diagnostic message from the language server for the current
1161 line.
1162
1163 By default, the lines with a diagnostic message have a sign placed on them and
1164 are highlighted.  You can temporarily disable them for the current Vim session
1165 using the |:LspDiagHighlightDisable| command and re-enable them using the
1166 |:LspDiagHighlightEnable| command.
1167
1168 To disable the automatic placement of signs on the lines with a diagnostic
1169 message, you can set the 'autoHighlightDiags' option to false: >
1170
1171         LspOptionsSet({'autoHighlightDiags': false})
1172 <
1173 By default the 'autoHighlightDiags' option is set to true.
1174
1175 The function lsp#lsp#ErrorCount() function can be used to get the count of the
1176 diagnostic messages in the current buffer by type.  This function returns a
1177 Dictionary with the following keys: Info, Hint, Warn and Error.  The value for
1178 these keys is the number of diagnostic messages of the corresponding type.
1179 This function can be used to display the number of diagnostics in the current
1180 buffer in a 'statusline'.
1181
1182 For some diagnostic errors/warnings, the language server may provide an
1183 automatic fix.  To apply this fix, you can use the |:LspCodeAction| command.
1184 This command applies the action provided by the language server (if any) for
1185 the current line.
1186
1187 The |:LspDiagShow| command creates a new location list with the current list
1188 of diagnostics for the current buffer.  To automatically add the diagnostics
1189 messages to the location list, you can set the 'autoPopulateDiags' option to
1190 true.  By default this option is set to false.  When new diagnostics are
1191 received for a buffer, if a location list with the diagnostics is already
1192 present, then it is refreshed with the new diagnostics.
1193
1194 When using GUI Vim or in a terminal Vim with 'ballooneval' option set, when
1195 the mouse is moved over the diagnostic sign displayed in the sign column, then
1196 the diagnostic message is displayed in a popup.  By default, the diagnostic
1197 message popup is not displayed when the mouse is moved over the text in the
1198 line. To display the diagnostic message when hovering the mouse over the text
1199 of the line, you can set the 'noDiagHoverOnLine' option to false.  By
1200 default, this option is set to true.
1201
1202 To display the diagnostic message for the current line in the status area, you
1203 can set the 'showDiagOnStatusLine' option to true.  By default, this option
1204 is set to false.
1205
1206 By default, the |:LspDiagCurrent| command displays the diagnostic message for
1207 the current line in a popup window.  To display the message in the status
1208 message area instead, you can set the 'showDiagInPopup' option to false.  By
1209 default this is set to true.
1210
1211 The lsp#diag#GetDiagsForBuf() function can be used to get all the LSP
1212 diagnostics in a buffer.  This function optionally accepts a buffer number.
1213 If the buffer number argument is not specified, then the current buffer is
1214 used.  This function returns a |List| of diagnostics sorted by their line and
1215 column number.  Each diagnostic is a |Dict| returned by the language server.
1216
1217 ==============================================================================
1218 8. Tag Function                                 *lsp-tagfunc*
1219
1220 The |:LspGotoDefinition| command can be used jump to the location where a
1221 symbol is defined.  To jump to the symbol definition using the Vim
1222 |tag-commands|, you can set the 'tagfunc' option to the 'lsp#lsp#TagFunc'
1223 function: >
1224
1225         setlocal tagfunc=lsp#lsp#TagFunc
1226 <
1227 After setting the above option, you can use |Ctrl-]| and other tag related
1228 commands to jump to the symbol definition.
1229
1230 Note that most of the language servers return only one symbol location even if
1231 the symbol is defined in multiple places in the code.
1232
1233 ==============================================================================
1234 9. Code Formatting                              *lsp-format*
1235
1236 The |:LspFormat| command can be used to format either the entire file or a
1237 selected range of lines using the language server.  The 'shiftwidth' and
1238 'expandtab' values set for the current buffer are used when format is applied.
1239
1240 To format code using the 'gq' command, you can set the 'formatexpr' option: >
1241
1242     setlocal formatexpr=lsp#lsp#FormatExpr()
1243 <
1244 ==============================================================================
1245 10. Call Hierarchy                              *lsp-call-hierarchy*
1246
1247 The |:LspIncomingCalls| and the |:LspOutoingCalls| commands can be used to
1248 display the call hierarchy of a symbol.  For example, the functions calling a
1249 function or the functions called by a function.  These two commands open a
1250 window containing the call hierarchy tree.  You can use the Vim motion
1251 commands to browse the call hierarchy.
1252
1253 In the call hierarchy tree window, the following keys are supported:
1254
1255 <Enter>                         Jump to the location of the symbol under the
1256                                 cursor.
1257 -                               Expand and show the symbols calling or called
1258                                 by the symbol under the cursor.
1259 +                               Close the call hierarchy for the symbol under
1260                                 the cursor.
1261
1262 You can display either the incoming call hierarchy or the outgoing call
1263 hierarchy in this window.  You cannot display both at the same time.
1264
1265 In the call hierarchy tree window, the following commands are supported:
1266
1267                                                 *:LspCallHierarchyRefresh*
1268 :LspCallHierarchyRefresh        Query the language server again for the top
1269                                 level symbol and refresh the call hierarchy
1270                                 tree.
1271                                                 *:LspCallHierarchyIncoming*
1272 :LspCallHierarchyIncoming       Display the incoming call hierarchy for the
1273                                 top level symbol.  If the window is currently
1274                                 displaying the outgoing calls, then it is
1275                                 refreshed to display the incoming calls.
1276                                                 *:LspCallHierarchyOutgoing*
1277 :LspCallHierarchyOutgoing       Display the outgoing call hierarchy for the
1278                                 top level symbol.  If the window is currently
1279                                 displaying the incoming calls, then it is
1280                                 refreshed to display the outgoing calls.
1281
1282 ==============================================================================
1283 11. Autocommands                                *lsp-autocmds*
1284
1285                                                 *LspAttached*
1286 LspAttached                     A |User| autocommand fired when the LSP client
1287                                 attaches to a buffer. Can be used to configure
1288                                 buffer-local mappings or options.
1289
1290                                                 *LspDiagsUpdated*
1291 LspDiagsUpdated                 A |User| autocommand invoked when new
1292                                 diagnostics are received from the language
1293                                 server.  This is invoked after the LSP client
1294                                 has processed the diagnostics.
1295
1296 ==============================================================================
1297 12. Highlight Groups                            *lsp-highlight-groups*
1298
1299 The following highlight groups are used by the LSP plugin.  You can define
1300 these highlight groups in your .vimrc file before sourcing this plugin to
1301 override them.
1302
1303 *LspDiagInlineError*            Used to highlight inline error diagnostics.
1304                                 By default, linked to the "SpellBad" highlight
1305                                 group.
1306 *LspDiagInlineHint*             Used to highlight inline hint diagnostics.
1307                                 By default, linked to the "SpellLocal"
1308                                 highlight group.
1309 *LspDiagInlineInfo*             Used to highlight inline info diagnostics.
1310                                 By default, linked to the "SpellRare"
1311                                 highlight group.
1312 *LspDiagInlineWarning*          Used to highlight inline warning diagnostics.
1313                                 By default, linked to the "SpellCap" highlight
1314                                 group.
1315 *LspDiagLine*                   Used to highlight a line with one or more
1316                                 diagnostics.  By default linked to the
1317                                 "DiffAdd" highlight group.  Use "NONE" to
1318                                 disable.
1319 *LspDiagSignErrorText*          Used to highlight the sign text for error
1320                                 diags.  By default linked to 'ErrorMsg'.
1321 *LspDiagSignHintText*           Used to highlight the sign text for hint
1322                                 diags.  By default linked to 'Question'.
1323 *LspDiagSignInfoText*           Used to highlight the sign text for info
1324                                 diags.  By default linked to 'Pmenu'.
1325 *LspDiagSignWarningText*        Used to highlight the sign text for warning
1326                                 diags.  By default linked to 'Search'.
1327 *LspDiagVirtualText*            Used to highlight diagnostic virtual text.
1328                                 By default, linked to the "LineNr" highlight
1329                                 group.
1330 *LspInlayHintsParam*            Used to highlight inlay hints of kind
1331                                 "parameter".  By default, linked to the
1332                                 "Label" highlight group.
1333 *LspInlayHintsType*             Used to highlight inlay hints of kind "type".
1334                                 By default, linked to the "Conceal" highlight
1335                                 group.
1336 *LspSigActiveParameter*         Used to highlight the active signature
1337                                 parameter.  By default, linked to the "LineNr"
1338                                 highlight group.
1339
1340 For example, to override the highlight used for diagnostics virtual text, you
1341 can use the following: >
1342
1343     highlight LspDiagVirtualText ctermfg=Cyan guifg=Blue
1344 <
1345 or >
1346
1347     highlight link LspDiagLine NONE
1348     highlight link LspDiagVirtualText WarningMsg
1349 <
1350 ==============================================================================
1351 13. Debugging                                   *lsp-debug*
1352
1353 To debug this plugin, you can log the language server protocol messages sent
1354 and received by the plugin from the language server.  The following command
1355 enables the logging of the messages from the language server for the current
1356 buffer: >
1357
1358     :LspServer debug on
1359 <
1360 This command also clears the log files.  The following command disables the
1361 logging of the messages from the language server for the current buffer: >
1362
1363     :LspServer debug off
1364 <
1365 By default, the messages are not logged.  Another method to enable the debug
1366 is to set the "debug" field to true when adding a language server
1367 using |LspAddServer()|.
1368
1369 The messages printed by the language server in the stdout are logged to the
1370 lsp-<server-name>.log file and the messages printed in the stderr are logged
1371 to the lsp-<server-name>.err file.  On a Unix-like system, these files are
1372 created in the /tmp directory.  On MS-Windows, these files are created in the
1373 %TEMP% directory.
1374
1375 The following command opens the file containing the messages printed by the
1376 language server in the stdout: >
1377
1378     :LspServer debug messages
1379 <
1380 The following command opens the file containing the messages printed by the
1381 language server in the stderr: >
1382
1383     :LspServer debug errors
1384 <
1385 To debug language server initialization problems, after enabling the above
1386 server debug, you can restart the server for the file type in the current
1387 buffer using the following command: >
1388
1389     :LspServer restart
1390 <
1391 The language servers typically support command line options to enable debug
1392 messages and to increase the verbosity of the messages.  You can refer to the
1393 language server documentation for information about this.  You can include
1394 these options when registering the language server with this plugin.
1395
1396 If a language server supports the "$/logTrace" LSP notification, then you can
1397 use the :LspServerTrace command to set the server trace value: >
1398
1399     :LspServer trace { off | messages | verbose }
1400 <
1401 ==============================================================================
1402 14. Custom Command Handlers                     *lsp-custom-commands*
1403
1404 When applying a code action, the language server may issue a non-standard
1405 command.  For example, the Java language server uses non-standard commands
1406 (e.g. java.apply.workspaceEdit).  To handle these commands, you can register a
1407 callback function for each command using the LspRegisterCmdHandler() function.
1408 For example: >
1409
1410     vim9script
1411     import autoload "lsp/textedit.vim"
1412
1413     def WorkspaceEdit(cmd: dict<any>)
1414       for editAct in cmd.arguments
1415           textedit.ApplyWorkspaceEdit(editAct)
1416       endfor
1417     enddef
1418     g:LspRegisterCmdHandler('java.apply.workspaceEdit', WorkspaceEdit)
1419 <
1420 Place the above code in a file named lsp_java/plugin/lsp_java.vim and load
1421 this plugin.
1422
1423 The callback function should accept a Dict argument.  The Dict argument
1424 contains the LSP Command interface fields.  Refer to the LSP specification for
1425 more information about the "Command" interface.
1426
1427 ==============================================================================
1428 15. Custom LSP Completion Kinds                 *lsp-custom-kinds*
1429
1430 When a completion popup is triggered, the LSP client will use a default kind
1431 list to show in the completion "kind" section, to customize it, you need to
1432 use the option |lsp-opt-customCompletionKinds| and set all custom kinds in the
1433 option |lsp-opt-completionKinds| . There is a table with all default LSP
1434 kinds:
1435
1436  Kind Name              | Value
1437 ------------------------|--------------------
1438  Text                   | t
1439  Method                 | m
1440  Function               | f
1441  Constructor            | C
1442  Field                  | F
1443  Variable               | v
1444  Class                  | c
1445  Interface              | i
1446  Module                 | M
1447  Property               | p
1448  Unit                   | u
1449  Value                  | V
1450  Enum                   | e
1451  Keyword                | k
1452  Snippet                | S
1453  Color                  | C
1454  File                   | f
1455  Reference              | r
1456  Folder                 | F
1457  EnumMember             | E
1458  Constant               | d
1459  Struct                 | s
1460  Event                  | E
1461  Operator               | o
1462  TypeParameter          | T
1463  Buffer                 | B
1464
1465 For example, if you want to change the "Method" kind to the kind "method()": >
1466
1467         vim9script
1468
1469         g:LspOptionsSet({
1470                 customCompletionKinds: true,
1471                 completionKinds: {
1472                         "Method": "method()"
1473                 }
1474         })
1475 <
1476 In the completion popup, will show something like this: >
1477
1478         var file = new File()
1479
1480         file.cre
1481                 | create                method() |
1482                 | createIfNotExists     method() |
1483                 | ...                            |
1484 <
1485 ==============================================================================
1486 16. Multiple Language Servers for a buffer      *lsp-multiple-servers*
1487
1488 It's possible to run multiple language servers for a given buffer.
1489
1490 By default the language server defined first will be used for as much as it
1491 supports, then the next and so on. With the exception that diagnostics from
1492 all running language servers will be combined.
1493
1494 This means that you can define a language server that only supports a subset
1495 of features at first and then define the general purpose language server after
1496 it:
1497 >
1498         vim9script
1499
1500         g:LspAddServer([
1501                 # This language server reports that it only supports
1502                 # textDocument/documentFormatting, so it will be used
1503                 # for :LspFormat but nothing else.
1504                 {
1505                         filetype: ['html'],
1506                         path: 'html-pretty-lsp',
1507                         args: ['--stdio']
1508                 },
1509                 # This language server also supports
1510                 # textDocument/documentFormatting, but since it's been
1511                 # defined later, the one above will be used instead.
1512                 # However this server also supports
1513                 # textDocument/definition, textDocument/declaration,
1514                 # etc, so it will be used for :LspGotoDefinition,
1515                 # :LspGotoDeclaration, etc
1516                 {
1517                         filetype: ['html'],
1518                         path: 'html-language-server',
1519                         args: ['--stdio']
1520                 }
1521         ])
1522 <
1523 As shown in the example above the order of when the language servers are being
1524 defined is taken into account for a given method.  However sometimes the
1525 language server that you want to use for formatting also reports that it
1526 supports other features. In such a case you can do one of two things:
1527
1528 1. change the order of language servers, and specify that a given language
1529 server should be used for a given method.
1530
1531 2. set the unwanted features to |false| in the features |Dictionary| >
1532
1533         features: { 'codeAction': false }
1534 <
1535 For example, if you want to use the efm-langserver for formatting, but the
1536 typescript-language-server for everything else: >
1537
1538         vim9script
1539
1540         g:LspAddServer([
1541                 # this language server will be used by default, as it's defined
1542                 # as the first LSP for 'javascript' and 'typescript'
1543                 {
1544                         filetype: ['javascript', 'typescript'],
1545                         path: '/usr/local/bin/typescript-language-server',
1546                         args: ['--stdio']
1547                 },
1548                 # this language server will be used for documentFormatting
1549                 {
1550                         filetype: ['efm-langserver'],
1551                         path: '/usr/local/bin/efm-langserver',
1552                         args: [],
1553                         features: {
1554                                 documentFormatting: true
1555                         }
1556                 }
1557         ])
1558 <
1559 Another way is to disable the unwanted features: for example if you don't want
1560 diagnostics from the typescript-language-server, but want to use it for
1561 everything else: >
1562
1563         vim9script
1564
1565         g:LspAddServer([
1566                 {
1567                         filetype: ['javascript', 'typescript'],
1568                         path: '/usr/local/bin/typescript-language-server',
1569                         args: ['--stdio'],
1570                         features: {
1571                                 diagnostics: false
1572                         }
1573                 },
1574         ])
1575 <
1576 ==============================================================================
1577 17. Language Server Features                    *lsp-features*
1578
1579 By providing the configuration |lsp-cfg-features| it's possible to specify
1580 which servers should be used for a given method.  The following feature flags
1581 are supported: See |lsp-multiple-servers| for examples.
1582
1583                                                 *lsp-features-codeAction*
1584 codeAction                      Used by |:LspCodeAction|
1585                                                 *lsp-features-codeLens*
1586 codeLens                        Used by |:LspCodeLens|
1587                                                 *lsp-features-completion*
1588 completion                      Used by 24/7 Completion and 'omnifunc'
1589                                                 *lsp-features-declaration*
1590 declaration                     Used by |:LspGotoDeclaration|, and
1591                                 |:LspPeekDeclaration|
1592                                                 *lsp-features-definition*
1593 definition                      Used by |:LspGotoDefinition|, and
1594                                 |:LspPeekDefinition|
1595                                                 *lsp-features-diagnostics*
1596 diagnostics                     Used to disable diagnostics for a single
1597                                 language server, by default diagnostics are
1598                                 combined from all running servers, by setting
1599                                 this to |false| you can ignore diagnostics
1600                                 from a specific server.
1601                                         *lsp-features-documentFormatting*
1602 documentFormatting              Used by |:LspFormat|, and 'formatexpr'
1603                                         *lsp-features-documentHighlight*
1604 documentHighlight               Used by the |:LspHighlight| and the
1605                                 |:LspHighlightClear| commands.
1606                                                 *lsp-features-foldingRange*
1607 foldingRange                    Used by |:LspFold|
1608                                                 *lsp-features-hover*
1609 hover                           Used by |:LspHover|
1610                                                 *lsp-features-implementation*
1611 implementation                  Used by |:LspGotoImpl|, and |:LspPeekImpl|
1612                                                 *lsp-features-references*
1613 references                      Used by |:LspShowReferences|
1614                                                 *lsp-features-rename*
1615 rename                          Used by |:LspRename|
1616                                                 *lsp-features-selectionRange*
1617 selectionRange                  Used by the |:LspSelectionExpand| and the
1618                                 |:LspSelectionShrink| commands.
1619                                                 *lsp-features-typeDefinition*
1620 typeDefinition                  Used by the |:LspGotoTypeDef| and the
1621                                 |:LspPeekTypeDef| commands.
1622
1623 ==============================================================================
1624                                                 *lsp-license*
1625 License: MIT License
1626 Copyright (c) 2020-2023 Yegappan Lakshmanan
1627
1628 Permission is hereby granted, free of charge, to any person obtaining a copy
1629 of this software and associated documentation files (the "Software"), to
1630 deal in the Software without restriction, including without limitation the
1631 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
1632 sell copies of the Software, and to permit persons to whom the Software is
1633 furnished to do so, subject to the following conditions:
1634
1635 The above copyright notice and this permission notice shall be included in
1636 all copies or substantial portions of the Software.
1637
1638 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1639 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1640 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1641 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1642 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
1643 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
1644 IN THE SOFTWARE.
1645
1646 ==============================================================================
1647
1648 vim:tw=78:ts=8:noet:ft=help:norl: