1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
# nvim-lsp
Collection of common configurations for the [Nvim LSP client](https://neovim.io/doc/user/lsp.html).
It is hoped that these configurations serve as a "source of truth", but they
are strictly _best effort_. If something doesn't work, these configs are useful
as a starting point, which you can adjust to fit your environment.
This is work-in-progress and **requires [Nvim HEAD/nightly](https://github.com/neovim/neovim/releases/tag/nightly)**.
Update Nvim and nvim-lsp before reporting an issue.
## Contributions are welcome!
There are many language servers in the world, and not enough time.
Help us create configs for *all the LSPs!*
0. Read [CONTRIBUTING.md](CONTRIBUTING.md) for instructions.
Ask questions in [Neovim Gitter](https://gitter.im/neovim/neovim).
1. Choose a language from [the coc.nvim wiki](https://github.com/neoclide/coc.nvim/wiki/Language-servers) or
[the emacs-lsp project](https://github.com/emacs-lsp/lsp-mode#supported-languages).
2. Create a new file at `lua/nvim_lsp/SERVER_NAME.lua`. See
[existing configs](https://github.com/neovim/nvim-lsp/blob/master/lua/nvim_lsp/) for
examples (`lua/nvim_lsp/texlab.lua` is an extensive example).
## Install
- Requires [Nvim HEAD/nightly](https://github.com/neovim/neovim/releases/tag/nightly) (v0.5 prerelease).
- nvim-lsp is just a plugin. Install it like any other Vim plugin.
```
:Plug 'neovim/nvim-lsp'
```
## Usage
Each config provides a `setup()` function, to initialize the server with
reasonable defaults and some server-specific things like commands or different
diagnostics.
require'nvim_lsp'.<config>.setup{name=…, settings = {…}, …}
Find the [config](#configurations) for your language, then paste the example
given there to your `init.vim`. **All examples are given in Lua,** see `:help
:lua-heredoc` to use Lua from your init.vim.
Some configs may define additional server-specific functions, e.g. the `texlab`
config provides `nvim_lsp.texlab.buf_build({bufnr})`.
### Example: using the defaults
To use the defaults, just call `setup()` with an empty `config` parameter.
For the `gopls` config, that would be:
require'nvim_lsp'.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 nvim_lsp = require'nvim_lsp'
nvim_lsp.gopls.setup{
root_dir = nvim_lsp.util.root_pattern('.git');
}
```
The [documentation](#configurations) for each config lists default values and
additional optional properties.
```lua
local nvim_lsp = require'nvim_lsp'
nvim_lsp.texlab.setup{
name = 'texlab_fancy';
log_level = vim.lsp.protocol.MessageType.Log;
settings = {
latex = {
build = {
onSave = true;
}
}
}
}
```
### Example: custom config
To configure a custom/private server, just require `nvim_lsp/configs` and do
the same as we do if we were adding it to the repository itself.
1. Define the config: `configs.foo_lsp = { … }`
2. Call `setup()`: `require'nvim_lsp'.foo_lsp.setup{}`
```lua
local nvim_lsp = require'nvim_lsp'
local configs = require'nvim_lsp/configs'
-- Check if it's already defined for when I reload this file.
if not nvim_lsp.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 nvim_lsp.util.find_git_ancestor(fname) or vim.loop.os_homedir()
end;
log_level = vim.lsp.protocol.MessageType.Warning;
settings = {};
};
}
end
nvim_lsp.foo_lsp.setup{}
```
### Installing a language server
Configs may provide an `install()` function. Then you can use
`:LspInstall {name}` to install the required language server.
For example, to install the Elm language server:
:LspInstall elmls
Use `:LspInstallInfo` to see install info.
:LspInstallInfo
## setup() function
The `setup()` interface:
```
nvim_lsp.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 |nvim_lsp.util.search_ancestors()| and the functions which use it:
- |nvim_lsp.util.root_pattern(patterns...)| finds an ancestor which
- contains one of the files in `patterns...`. This is equivalent
to coc.nvim's "rootPatterns"
- Related utilities for common tools:
- |nvim_lsp.util.find_git_root()|
- |nvim_lsp.util.find_node_modules_root()|
- |nvim_lsp.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.
{log_level}
controls the level of logs to show from build processes and other
window/logMessage events. Defaults to
vim.lsp.protocol.MessageType.Warning instead of
vim.lsp.protocol.MessageType.Log.
{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)` executed with the current buffer as the one the {client}
is being attached-to. This is different from
|vim.lsp.start_client()|'s on_attach parameter, which passes the {bufnr} as
the second parameter instead. Useful for doing buffer-local setup.
{on_new_config}
`function(new_config)` 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()|.
```
# Configurations
The following LSP configs are included. Follow a link to find documentation for
that config.
{{implemented_servers_list}}
{{lsp_server_details}}
|
