diff options
| -rw-r--r-- | ADVANCED_README.md | 177 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 15 | ||||
| -rw-r--r-- | README.md | 24 |
3 files changed, 197 insertions, 19 deletions
diff --git a/ADVANCED_README.md b/ADVANCED_README.md new file mode 100644 index 00000000..d1c1e26a --- /dev/null +++ b/ADVANCED_README.md @@ -0,0 +1,177 @@ +## Advanced usage + +**All provided examples are in Lua,** see `:help :lua-heredoc` to use Lua from your init.vim, +or the quickstart above for an example of a lua heredoc. + +Each config provides a `setup()` function to initialize the server with reasonable default +initialization options and settings, as well as some server-specific commands. This is +invoked in the following form, where `<server>` corresponds to the language server name +in [CONFIG.md](CONFIG.md). + +`setup()` takes optional arguments <config>, each of which overrides the respective +part of the default configuration. The allowed arguments are detailed [below](#setup-function). +```lua +require'lspconfig'.<server>.setup{<config>} +``` + +### Example: using the defaults + +To use the defaults, just call `setup()` with an empty `config` parameter. +For the `gopls` config, that would be: + +```lua +require'lspconfig'.gopls.setup{} +``` + +### Example: override some defaults + +To set some config properties at `setup()`, specify their keys. For example to +change how the "project root" is found, set the `root_dir` key: + +```lua +local lspconfig = require'lspconfig' +lspconfig.gopls.setup{ + root_dir = lspconfig.util.root_pattern('.git'); +} +``` + +The [documentation](CONFIG.md) for each config lists default values and +additional optional properties. For a more complicated example overriding +the `name`, `log_level`, `message_level`, and `settings` of texlab: + +```lua +local lspconfig = require'lspconfig' +lspconfig.texlab.setup{ + name = 'texlab_fancy'; + settings = { + latex = { + build = { + onSave = true; + } + } + } +} +``` + +### Example: custom config + +To configure a custom/private server, just + +1. load the lspconfig module: `local lspconfig = require('lspconfig')`, +2. Define the config: `lspconfig.configs.foo_lsp = { … }` +3. Call `setup()`: `lspconfig.foo_lsp.setup{}` + +```lua +local lspconfig = require'lspconfig' +local configs = require'lspconfig/configs' +-- Check if it's already defined for when reloading this file. +if not lspconfig.foo_lsp then + configs.foo_lsp = { + default_config = { + cmd = {'/home/ashkan/works/3rd/lua-language-server/run.sh'}; + filetypes = {'lua'}; + root_dir = function(fname) + return lspconfig.util.find_git_ancestor(fname) or vim.loop.os_homedir() + end; + settings = {}; + }; + } +end +lspconfig.foo_lsp.setup{} +``` + +### Example: override default config for all servers + +If you want to change default configs for all servers, you can override default_config like this. In this example, we additionally add a check for log_level and message_level which can be passed to the server to control the verbosity of "window/logMessage". + +```lua +local lspconfig = require'lspconfig' +lspconfig.util.default_config = vim.tbl_extend( + "force", + lspconfig.util.default_config, + { + autostart = false, + handlers = { + ["window/logMessage"] = function(err, method, params, client_id) + if params and params.type <= vim.lsp.protocol.MessageType.Log then + vim.lsp.handlers["window/logMessage"](err, method, params, client_id) + end + end; + ["window/showMessage"] = function(err, method, params, client_id) + if params and params.type <= vim.lsp.protocol.MessageType.Warning.Error then + vim.lsp.handlers["window/showMessage"](err, method, params, client_id) + end + end; + } + } +) +``` + +## setup() function + +Only the following arguments can be passed to the setup function: + +``` +lspconfig.SERVER.setup{config} + + The `config` parameter has the same shape as that of + |vim.lsp.start_client()|, with these additions and changes: + + {root_dir} + Required for some servers, optional for others. + Function of the form `function(filename, bufnr)`. + Called on new candidate buffers being attached-to. + Returns either a root_dir or nil. + + If a root_dir is returned, then this file will also be attached. You + can optionally use {filetype} to help pre-filter by filetype. + + If a root_dir is returned which is unique from any previously returned + root_dir, a new server will be spawned with that root_dir. + + If nil is returned, the buffer is skipped. + + See |lspconfig.util.search_ancestors()| and the functions which use it: + - |lspconfig.util.root_pattern(pattern1, pattern2...)| is a variadic function which + takes string patterns as arguments, and finds an ancestor + which contains one of the files matching the pattern. + Each pattern can be a specific filename, such as ".git", or a glob. + See `:help glob` for allowed patterns. This is equivalent to + coc.nvim's "rootPatterns" + - Related utilities for common tools: + - |lspconfig.util.find_git_root()| + - |lspconfig.util.find_node_modules_root()| + - |lspconfig.util.find_package_json_root()| + + {name} + Defaults to the server's name. + + {filetypes} + Set of filetypes to filter for consideration by {root_dir}. + May be empty. + Server may specify a default value. + + {autostart} + Whether to automatically start a language server when a matching filetype is detected. + Defaults to true. + + {settings} + Map with case-sensitive keys corresponding to `workspace/configuration` + event responses. + We also notify the server *once* on `initialize` with + `workspace/didChangeConfiguration`. + If you change the settings later on, you must emit the notification + with `client.workspace_did_change_configuration({settings})` + Example: `settings = { keyName = { subKey = 1 } }` + + {on_attach} + `function(client, bufnr)` Runs the on_attach function from the client's + config if it was defined. Useful for doing buffer-local setup. + + {on_new_config} + `function(new_config, new_root_dir)` will be executed after a new configuration has been + created as a result of {root_dir} returning a unique value. You can use this + as an opportunity to further modify the new_config or use it before it is + sent to |vim.lsp.start_client()|. If you set a custom `on_new_config`, ensure that + `new_config.cmd = cmd` is present within the function body. +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5904893f..be58012b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,3 @@ -# Contributing to nvim-lspconfig - -Thank you! - ## Requirements - [Neovim](https://neovim.io/) :P @@ -74,14 +70,3 @@ functions to it if necessary. Example: configs.texlab.buf_build = buf_build - -## Auto-install - -Note **we have removed auto installers from the nvim-lspconfig repo** -([#334](https://github.com/neovim/nvim-lspconfig/issues/334)). Instead, each -config _documents_ key installation details: - -- URL to download the server -- URL to documentation explaining how to install the server -- Brief instructions that user can copy/paste into their shell to install via - common package managers such as apt-get/homebrew. @@ -1,8 +1,24 @@ # nvim-lspconfig - A collection of common configurations for Neovim's built-in [language server client](https://neovim.io/doc/user/lsp.html). + This repo handles automatically launching and initializing language servers that are installed on your system. +# LSP overview + +Neovim supports the Language Server Protocol (LSP), which means it acts as a client to language servers and includes a Lua framework `vim.lsp` for building enhanced LSP tools. LSP facilitates features like: + +- go-to-definition +- find-references +- hover +- completion +- rename +- format +- refactor + +Neovim provides an interface for all of these features, and the language server client is designed to be highly extensible to allow plugins to integrate language server features which are not yet present in Neovim core such as [**auto**-completion](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) (as opposed to manual completion with omnifunc) and [snippet integration](https://github.com/neovim/nvim-lspconfig/wiki/Snippets). + +These features are not implemented in this repo, but in Neovim core. See `:help lsp` for more details. + ## Install * Requires [Neovim HEAD/nightly](https://github.com/neovim/neovim/releases/tag/nightly) (v0.5 prerelease). Update Neovim and nvim-lspconfig before reporting an issue. @@ -19,7 +35,7 @@ npm i -g pyright ``` 2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [CONFIG.md](CONFIG.md) ```vim -lua << eof +lua << EOF require'lspconfig'.pyright.setup{} eof ``` @@ -42,14 +58,14 @@ Language servers require each project to have a `root` in order to provide compl ## Enabling additional language servers -Enabling most language servers is as easy as installing the language on your PATH, and adding the following to your config: +Enabling most language servers is as easy as installing the language server, ensuring it is on your PATH, and adding the following to your config: ```vim lua << EOF require'lspconfig'.rust_analyzer.setup{} EOF ``` -For a full list of servers, see [CONFIG.md](CONFIG.md). This document contains installation instructions and additional, optional customization suggestions for each language server. For some servers that are not on your system path (jdtls, elixirls) you will be required to manually add `cmd` as an entry in the table passed to setup. +For a full list of servers, see [CONFIG.md](CONFIG.md). This document contains installation instructions and additional, optional customization suggestions for each language server. For some servers that are not on your system path (jdtls, elixirls) you will be required to manually add `cmd` as an entry in the table passed to setup. Most language servers can be installed in less than a minute. ## Keybindings and completion |