README.md

   1 [![unit-tests](https://github.com/yegappan/lsp/workflows/unit-tests/badge.svg?branch=main)](https://github.com/yegappan/lsp/actions/workflows/unitests.yml?query=branch%3Amain)
   2
   3 Language Server Protocol (LSP) plugin for Vim. You need Vim version 9.0 or above to use this plugin.  This plugin is written using only the Vim9 script.
   4
   5 ## Installation
   6
   7 You can install this plugin directly from github using the following steps:
   8
   9 ```bash
  10 $ mkdir -p $HOME/.vim/pack/downloads/opt
  11 $ cd $HOME/.vim/pack/downloads/opt
  12 $ git clone https://github.com/yegappan/lsp
  13 ```
  14
  15 After installing the plugin using the above steps, add the following line to
  16 your $HOME/.vimrc file:
  17
  18 ```viml
  19 packadd lsp
  20 ```
  21
  22 You can also install and manage this plugin using any one of the Vim plugin managers (dein.vim, pathogen, vam, vim-plug, volt, Vundle, etc.).
  23
  24 You will also need to download and install one or more language servers corresponding to the programming languages that you are using. Refer to the https://langserver.org/ page for the list of available language servers.  This plugin doesn't install the language servers.
  25
  26 ## Features
  27
  28 The following language server protocol (LSP) features are supported:
  29
  30 * Code completion
  31 * Jump to definition, declaration, implementation, type definition
  32 * Peek definition, declaration, implementation, type definition and references
  33 * Display warning and error diagnostics
  34 * Find all symbol references
  35 * Document and Workspace symbol search
  36 * Display code outline
  37 * Rename symbol
  38 * Display type and documentation on hover
  39 * Signature help
  40 * Code action
  41 * Display Call hierarchy
  42 * Display Type hierarchy
  43 * Highlight current symbol references
  44 * Formatting code
  45 * Folding code
  46 * Inlay hints
  47 * Visually select symbol block/region
  48
  49 ## Configuration
  50
  51 To use the plugin features with a particular file type(s), you need to first register a LSP server for that file type(s).
  52
  53 The LSP servers are registered using the LspAddServer() function. This function accepts a list of LSP servers.
  54
  55 To register a LSP server, add the following lines to your .vimrc file (use only the LSP servers that you need from the below list).  If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the LSP plugin, the steps are described later in this section.
  56 ```viml
  57
  58 " Clangd language server
  59 call LspAddServer([#{
  60         \    name: 'clangd',
  61         \    filetype: ['c', 'cpp'],
  62         \    path: '/usr/local/bin/clangd',
  63         \    args: ['--background-index']
  64         \  }])
  65
  66 " Javascript/Typescript language server
  67 call LspAddServer([#{
  68         \    name: 'typescriptlang',
  69         \    filetype: ['javascript', 'typescript'],
  70         \    path: '/usr/local/bin/typescript-language-server',
  71         \    args: ['--stdio'],
  72         \  }])
  73
  74 " Go language server
  75 call LspAddServer([#{
  76         \    name: 'golang',
  77         \    filetype: ['go', 'gomod'],
  78         \    path: '/usr/local/bin/gopls',
  79         \    args: ['serve'],
  80         \    syncInit: v:true
  81         \  }])
  82
  83 " Rust language server
  84 call LspAddServer([#{
  85         \    name: 'rustlang',
  86         \    filetype: ['rust'],
  87         \    path: '/usr/local/bin/rust-analyzer',
  88         \    args: [],
  89         \    syncInit: v:true
  90         \  }])
  91 ```
  92
  93 The above lines register the language servers for C/C++, Javascript/Typescript, Go and Rust file types.  Refer to the [Wiki](https://github.com/yegappan/lsp/wiki) page for various language server specific configuration.
  94
  95 To register a LSP server, the following information is needed:
  96
  97 Field|Description
  98 -----|-----------
  99 filetype|One or more file types supported by the LSP server.  This can be a String or a List. To specify multiple multiple file types, use a List.
 100 path|complete path to the LSP server executable (without any arguments).
 101 args|a list of command-line arguments passed to the LSP server. Each argument is a separate List item.
 102 initializationOptions|User provided initialization options. May be of any type. For example the *intelephense* PHP language server accept several options here with the License Key among others.
 103 customNotificationHandlers|A dictionary of notifications and functions that can be specified to add support for custom language server notifications.
 104 customRequestHandlers|A dictionary of request handlers and functions that can be specified to add support for custom language server requests replies.
 105 features|A dictionary of booleans that can be specified to toggle what things a given LSP is providing (folding, goto definition, etc) This is useful when running multiple servers in one buffer.
 106
 107 The LspAddServer() function accepts a list of LSP servers with the above information.
 108
 109 Some of the LSP plugin features can be enabled or disabled by using the LspOptionsSet() function, detailed in `:help lsp-options`.
 110 Here is an example of configuration with default values:
 111 ```viml
 112 call LspOptionsSet(#{
 113         \   aleSupport: v:false,
 114         \   autoComplete: v:true,
 115         \   autoHighlight: v:false,
 116         \   autoHighlightDiags: v:true,
 117         \   autoPopulateDiags: v:false,
 118         \   completionMatcher: 'case',
 119         \   completionTextEdit: v:true,
 120         \   completionKinds: {},
 121         \   customCompletionKinds: v:false,
 122         \   diagSignErrorText: 'E>',
 123         \   diagSignInfoText: 'I>',
 124         \   diagSignHintText: 'H>',
 125         \   diagSignWarningText: 'W>',
 126         \   diagVirtualTextAlign: 'above',
 127         \   echoSignature: v:false,
 128         \   hideDisabledCodeActions: v:false,
 129         \   highlightDiagInline: v:true,
 130         \   hoverInPreview: v:false,
 131         \   ignoreMissingServer: v:false,
 132         \   keepFocusInReferences: v:false,
 133         \   noNewlineInCompletion: v:false,
 134         \   outlineOnRight: v:false,
 135         \   outlineWinSize: 20,
 136         \   showDiagInBalloon: v:true,
 137         \   showDiagInPopup: v:true,
 138         \   showDiagOnStatusLine: v:false,
 139         \   showDiagWithSign: v:true,
 140         \   showDiagWithVirtualText: v:false,
 141         \   showInlayHints: v:false,
 142         \   showSignature: v:true,
 143         \   snippetSupport: v:false,
 144         \   ultisnipsSupport: v:false,
 145         \   usePopupInCodeAction: v:false,
 146         \   useQuickfixForLocations: v:false,
 147         \   useBufferCompletion: v:false,
 148         \ })
 149 ```
 150
 151 If you used [vim-plug](https://github.com/junegunn/vim-plug) to install the LSP plugin, then you need to use the VimEnter autocmd to initialize the LSP server and to set the LSP server options.  For example:
 152 ```viml
 153 let lspServers = [#{
 154         \         name: 'clang',
 155         \         filetype: ['c', 'cpp'],
 156         \         path: '/usr/local/bin/clangd',
 157         \         args: ['--background-index']
 158         \ }]
 159 autocmd VimEnter * call LspAddServer(lspServers)
 160
 161 let lspOpts = #{autoHighlightDiags: v:true}
 162 autocmd VimEnter * call LspOptionsSet(lspOpts)
 163 ```
 164
 165 ## Supported Commands
 166
 167 The following commands are provided to use the LSP features.
 168
 169 Command|Description
 170 -------|-----------
 171 :LspCodeAction|Apply the code action supplied by the language server to the diagnostic in the current line.
 172 :LspCodeLens|Display a list of code lens commands and apply a selected code lens command to the current file.
 173 :LspDiag current|Display the diagnostic message for the current line.
 174 :LspDiag first|Jump to the first diagnostic message for the current buffer.
 175 :LspDiag here|Jump to the next diagnostic message in the current line.
 176 :LspDiag highlight disable|Disable diagnostic message highlights.
 177 :LspDiag highlight enable|Enable diagnostic message highlights.
 178 :LspDiag next|Jump to the next diagnostic message after the current position.
 179 :LspDiag prev|Jump to the previous diagnostic message before the current position.
 180 :LspDiag show|Display the diagnostics messages from the language server for the current buffer in a new location list.
 181 :LspDocumentSymbol|Display the symbols in the current file in a popup menu and jump to the selected symbol.
 182 :LspFold|Fold the current file.
 183 :LspFormat|Format a range of lines in the current file using the language server. The **shiftwidth** and **expandtab** values set for the current buffer are used when format is applied.  The default range is the entire file.
 184 :LspGotoDeclaration|Go to the declaration of the keyword under cursor.
 185 :LspGotoDefinition|Go to the definition of the keyword under cursor.
 186 :LspGotoImpl|Go to the implementation of the keyword under cursor.
 187 :LspGotoTypeDef|Go to the type definition of the keyword under cursor.
 188 :LspHighlight|Highlight all the matches for the keyword under cursor.
 189 :LspHighlightClear|Clear all the matches highlighted by :LspHighlight.
 190 :LspHover|Show the documentation for the symbol under the cursor in a popup window.
 191 :LspIncomingCalls|Display the list of symbols calling the current symbol.
 192 :LspOutgoingCalls|Display the list of symbols called by the current symbol.
 193 :LspOutline|Show the list of symbols defined in the current file in a separate window.
 194 :LspPeekDeclaration|Open the declaration of the symbol under cursor in the preview window.
 195 :LspPeekDefinition|Open the definition of the symbol under cursor in the preview window.
 196 :LspPeekImpl|Open the implementation of the symbol under cursor in the preview window.
 197 :LspPeekReferences|Display the list of references to the keyword under cursor in a location list associated with the preview window.
 198 :LspPeekTypeDef|Open the type definition of the symbol under cursor in the preview window.
 199 :LspRename|Rename the current symbol.
 200 :LspSelectionExpand|Expand the current symbol range visual selection.
 201 :LspSelectionShrink|Shrink the current symbol range visual selection.
 202 :LspShowAllServers|Display information about all the registered language servers.
 203 :LspServer|Display the capabilities or messages or status of the language server for the current buffer or restart the server.
 204 :LspShowReferences|Display the list of references to the keyword under cursor in a new location list.
 205 :LspShowSignature|Display the signature of the keyword under cursor.
 206 :LspSubTypeHierarchy|Display the sub type hierarchy in a popup window.
 207 :LspSuperTypeHierarchy|Display the super type hierarchy in a popup window.
 208 :LspSwitchSourceHeader|Switch between a source and a header file.
 209 :LspSymbolSearch|Perform a workspace wide search for a symbol.
 210 :LspWorkspaceAddFolder `{folder}`| Add a folder to the workspace.
 211 :LspWorkspaceListFolders|Show the list of folders in the workspace.
 212 :LspWorkspaceRemoveFolder `{folder}`|Remove a folder from the workspace.
 213
 214 ## Similar Vim LSP Plugins
 215
 216 1. [vim-lsp: Async Language Server Protocol](https://github.com/prabirshrestha/vim-lsp)
 217 1. [Coc: Conquer of Completion](https://github.com/neoclide/coc.nvim)
 218 1. [vim-lsc: Vim Language Server Client](https://github.com/natebosch/vim-lsc)
 219 1. [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
 220 1. [ALE: Asynchronous Lint Engine](https://github.com/dense-analysis/ale)
 221 1. [Neovim built-in LSP client](https://neovim.io/doc/user/lsp.html)
 222 2. [Omnisharp LSP client](https://github.com/OmniSharp/omnisharp-vim)