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 * Display warning and error diagnostics
  33 * Find all symbol references
  34 * Workspace symbol search
  35 * Display code outline
  36 * Rename symbol
  37 * Display type and documentation on hover
  38 * Signature help
  39 * Code action
  40 * Display Call hierarchy
  41 * Display Type hierarchy
  42 * Formatting code
  43 * Folding code
  44 * Inlay hints
  45 * Visually select symbol block/region
  46
  47 ## Configuration
  48
  49 To use the plugin features with a particular file type(s), you need to first register a LSP server for that file type(s).
  50
  51 The LSP servers are registered using the LspAddServer() function. This function accepts a list of LSP servers.
  52
  53 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.
  54 ```viml
  55
  56 " Clangd language server
  57 call LspAddServer([#{
  58         \    name: 'clangd',
  59         \    filetype: ['c', 'cpp'],
  60         \    path: '/usr/local/bin/clangd',
  61         \    args: ['--background-index']
  62         \  }])
  63
  64 " Javascript/Typescript language server
  65 call LspAddServer([#{
  66         \    name: 'typescriptlang',
  67         \    filetype: ['javascript', 'typescript'],
  68         \    path: '/usr/local/bin/typescript-language-server',
  69         \    args: ['--stdio'],
  70         \  }])
  71
  72 " Go language server
  73 call LspAddServer([#{
  74         \    name: 'golang',
  75         \    filetype: ['go', 'gomod'],
  76         \    path: '/usr/local/bin/gopls',
  77         \    args: ['serve'],
  78         \    syncInit: v:true
  79         \  }])
  80
  81 " Rust language server
  82 call LspAddServer([#{
  83         \    name: 'rustlang',
  84         \    filetype: ['rust'],
  85         \    path: '/usr/local/bin/rust-analyzer',
  86         \    args: [],
  87         \    syncInit: v:true
  88         \  }])
  89 ```
  90
  91 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.
  92
  93 To register a LSP server, the following information is needed:
  94
  95 Field|Description
  96 -----|-----------
  97 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.
  98 path|complete path to the LSP server executable (without any arguments).
  99 args|a list of command-line arguments passed to the LSP server. Each argument is a separate List item.
 100 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.
 101 customNotificationHandlers|A dictionary of notifications and functions that can be specified to add support for custom language server notifications.
 102 customRequestHandlers|A dictionary of request handlers and functions that can be specified to add support for custom language server requests replies.
 103 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.
 104
 105 The LspAddServer() function accepts a list of LSP servers with the above information.
 106
 107 Some of the LSP plugin features can be enabled or disabled by using the LspOptionsSet() function, detailed in `:help lsp-options`.
 108 Here is an example of configuration with default values:
 109 ```viml
 110 call LspOptionsSet(#{
 111         \   aleSupport: v:false,
 112         \   autoComplete: v:true,
 113         \   autoHighlight: v:false,
 114         \   autoHighlightDiags: v:true,
 115         \   autoPopulateDiags: v:false,
 116         \   completionMatcher: 'case',
 117         \   completionTextEdit: v:true,
 118         \   completionKinds: {},
 119         \   customCompletionKinds: v:false,
 120         \   diagSignErrorText: 'E>',
 121         \   diagSignInfoText: 'I>',
 122         \   diagSignHintText: 'H>',
 123         \   diagSignWarningText: 'W>',
 124         \   diagVirtualTextAlign: 'above',
 125         \   echoSignature: v:false,
 126         \   hideDisabledCodeActions: v:false,
 127         \   highlightDiagInline: v:true,
 128         \   hoverInPreview: v:false,
 129         \   ignoreMissingServer: v:false,
 130         \   keepFocusInReferences: v:false,
 131         \   noNewlineInCompletion: v:false,
 132         \   outlineOnRight: v:false,
 133         \   outlineWinSize: 20,
 134         \   showDiagInBalloon: v:true,
 135         \   showDiagInPopup: v:true,
 136         \   showDiagOnStatusLine: v:false,
 137         \   showDiagWithSign: v:true,
 138         \   showDiagWithVirtualText: v:false,
 139         \   showInlayHints: v:false,
 140         \   showSignature: v:true,
 141         \   snippetSupport: v:false,
 142         \   ultisnipsSupport: v:false,
 143         \   usePopupInCodeAction: v:false,
 144         \   useQuickfixForLocations: v:false,
 145         \   useBufferCompletion: v:false,
 146         \ })
 147 ```
 148
 149 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:
 150 ```viml
 151 let lspServers = [#{
 152         \         name: 'clang',
 153         \         filetype: ['c', 'cpp'],
 154         \         path: '/usr/local/bin/clangd',
 155         \         args: ['--background-index']
 156         \ }]
 157 autocmd VimEnter * call LspAddServer(lspServers)
 158
 159 let lspOpts = #{autoHighlightDiags: v:true}
 160 autocmd VimEnter * call LspOptionsSet(lspOpts)
 161 ```
 162
 163 ## Supported Commands
 164
 165 The following commands are provided to use the LSP features.
 166
 167 Command|Description
 168 -------|-----------
 169 :LspCodeAction|Apply the code action supplied by the language server to the diagnostic in the current line.
 170 :LspCodeLens|Display a list of code lens commands and apply a selected code lens command to the current file.
 171 :LspDiag current|Display the diagnostic message for the current line.
 172 :LspDiag first|Jump to the first diagnostic message for the current buffer.
 173 :LspDiag here|Jump to the next diagnostic message in the current line.
 174 :LspDiag highlight disable|Disable diagnostic message highlights.
 175 :LspDiag highlight enable|Enable diagnostic message highlights.
 176 :LspDiag next|Jump to the next diagnostic message after the current position.
 177 :LspDiag prev|Jump to the previous diagnostic message before the current position.
 178 :LspDiag show|Display the diagnostics messages from the language server for the current buffer in a new location list.
 179 :LspDocumentSymbol|Display the symbols in the current file in a popup menu and jump to the selected symbol.
 180 :LspFold|Fold the current file.
 181 :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.
 182 :LspGotoDeclaration|Go to the declaration of the keyword under cursor.
 183 :LspGotoDefinition|Go to the definition of the keyword under cursor.
 184 :LspGotoImpl|Go to the implementation of the keyword under cursor.
 185 :LspGotoTypeDef|Go to the type definition of the keyword under cursor.
 186 :LspHighlight|Highlight all the matches for the keyword under cursor.
 187 :LspHighlightClear|Clear all the matches highlighted by :LspHighlight.
 188 :LspHover|Show the documentation for the symbol under the cursor in a popup window.
 189 :LspIncomingCalls|Display the list of symbols calling the current symbol.
 190 :LspOutgoingCalls|Display the list of symbols called by the current symbol.
 191 :LspOutline|Show the list of symbols defined in the current file in a separate window.
 192 :LspPeekDeclaration|Open the declaration of the symbol under cursor in the preview window.
 193 :LspPeekDefinition|Open the definition of the symbol under cursor in the preview window.
 194 :LspPeekImpl|Open the implementation of the symbol under cursor in the preview window.
 195 :LspPeekReferences|Display the list of references to the keyword under cursor in a location list associated with the preview window.
 196 :LspPeekTypeDef|Open the type definition of the symbol under cursor in the preview window.
 197 :LspRename|Rename the current symbol.
 198 :LspSelectionExpand|Expand the current symbol range visual selection.
 199 :LspSelectionShrink|Shrink the current symbol range visual selection.
 200 :LspShowAllServers|Display information about all the registered language servers.
 201 :LspServer|Display the capabilities or messages or status of the language server for the current buffer or restart the server.
 202 :LspShowReferences|Display the list of references to the keyword under cursor in a new location list.
 203 :LspShowSignature|Display the signature of the keyword under cursor.
 204 :LspSubTypeHierarchy|Display the sub type hierarchy in a popup window.
 205 :LspSuperTypeHierarchy|Display the super type hierarchy in a popup window.
 206 :LspSwitchSourceHeader|Switch between a source and a header file.
 207 :LspSymbolSearch|Perform a workspace wide search for a symbol.
 208 :LspWorkspaceAddFolder `{folder}`| Add a folder to the workspace.
 209 :LspWorkspaceListFolders|Show the list of folders in the workspace.
 210 :LspWorkspaceRemoveFolder `{folder}`|Remove a folder from the workspace.
 211
 212 ## Similar Vim LSP Plugins
 213
 214 1. [vim-lsp: Async Language Server Protocol](https://github.com/prabirshrestha/vim-lsp)
 215 1. [Coc: Conquer of Completion](https://github.com/neoclide/coc.nvim)
 216 1. [vim-lsc: Vim Language Server Client](https://github.com/natebosch/vim-lsc)
 217 1. [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
 218 1. [ALE: Asynchronous Lint Engine](https://github.com/dense-analysis/ale)
 219 1. [Neovim built-in LSP client](https://neovim.io/doc/user/lsp.html)
 220 2. [Omnisharp LSP client](https://github.com/OmniSharp/omnisharp-vim)