vis-config
lua scripts to configure vis editor
git clone https://9o.is/git/vis-config.git
README.md
(10043B)
1 # `vis-lspc`
2
3 A language server protocol client for the [`vis` editor](https://github.com/martanne/vis).
4
5 ## What's working
6
7 `vis-lspc` currently supports:
8 * `textDocument/completion`
9 * `textDocument/declaration`
10 * `textDocument/definition`
11 * `textDocument/references`
12 * `textDocument/typeDefinition`
13 * `textDocument/implementation`
14 * `textDocument/hover`
15 * `textDocument/rename`
16 * `textDocument/formatting`
17 * `Diagnostics`
18
19 ## What's not working
20
21 Everything else.
22
23 To my knowledge there is currently no good way to detect file changes via the Lua API.
24 But this is essential to support [Text Synchronization](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textSynchronization) which is required by the
25 LSP protocol.
26
27 A dirty workaround we currently use is to send the whole file content in a `textDocument/didChange`
28 method call before calling any other method.
29 If someone can come up with an idea how to solve this I would appreciate contributions.
30
31 Communicating with language-servers via other channels than stdin/stdout.
32
33 Currently, only a handful of language servers are configured by default.
34 Their configuration can be found in [`supported_servers.lua`](https://gitlab.com/muhq/vis-lspc/-/blob/main/supported-servers.lua).
35
36 ## Requirements
37
38 * `vis` must offer the `communicate` Lua API
39 * The API included in `vis` >= 0.9 is supported on the main branch
40 * For legacy support using the [first API draft patches](https://github.com/martanne/vis/pull/675) use the v0.2.x branch
41 * The language server you want to use. [Microsoft's list of implementations](https://microsoft.github.io/language-server-protocol/implementors/servers/)
42 * Optional: the JSON implementation of your choice
43 * must provide `encode` and `decode` methods
44 * `vis-lspc` tries to find a suitable JSON implementation using those candidates:
45 * `json`
46 * `cjson`
47 * `dkjson`
48 * bundled fallback (no utf8 support)
49
50 ## Installation
51
52 1. Clone this repository into your `vis` plugins directory
53 2. Load the plugin in your `visrc.lua` with `require('plugins/vis-lspc')`
54
55 Alternatively, a plugin manager like [vis-plug](https://github.com/erf/vis-plug) can be used to install `vis-lspc`.
56
57 ## Usage
58
59 `vis-lspc` provides some default key bindings:
60
61 ### Default Bindings
62
63 Normal mode:
64 <F2> - start a language server for win.syntax
65 <F3> - open win.file with a running language server
66 <C-]> | <gd> - jump to the definition of the symbol under the main cursor
67 <gD> - jump to declaration
68 <gd> - jump to definition
69 <gi> - jump to implementation
70 <gr> - show references
71 < D> - jump to type definition
72 <C-t> - go back in the jump history
73 < e> - show diagnostics of current line
74 <K> - hover over current position
75 Normal and Insert mode:
76 <C- > - get completions
77
78
79 ### Available commands
80
81 # language-server management:
82 lspc-start-server [syntax] - start a language server for syntax or win.syntax
83 lspc-stop-server [syntax] - stop the language server for syntax or win.syntax
84
85 # file registration:
86 lspc-open - register the file in the current window
87 lspc-close - unregister the file in the current window
88
89 # navigation commands (they all operate on the symbol under the main cursor):
90 lspc-completion - syntax completion
91 lspc-references [e | vsplit | hsplit] - select and open a reference
92 lspc-declaration [e | vsplit | hsplit] - select and open a declaration
93 lspc-definition [e | vsplit | hsplit] - open the definition
94 lspc-typeDeclaration [e | vsplit | hsplit] - select and open a type declaration
95 lspc-implementation [e | vsplit | hsplit] - I actually have no idea what this does
96
97 lspc-back - navigate back in the goto history
98
99 # workspace edits
100 lspc-rename <new name> - rename the identifier under the cursor to <new name>
101 lspc-format - format the file in the current window
102
103 # development support
104 lspc-hover - hover over the current line
105 lspc-show-diagnostics - show the available diagnostics of the current line
106 lspc-next-diagnostic - jump to the next available diagnostic
107 lspc-prev-diagnostic - jump to the previous available diagnostic
108
109 ### Available configuration options
110
111 The module table returned by `require('plugins/vis-lspc')` can be used to configure
112 some aspects of `vis-lspc`.
113
114 Available options are:
115
116 * `name = 'vis-lspc'` - the name `vis-lspc` introduces itself to a language server
117 * `logging = false` - enable logging only useful for debugging `vis-lspc`
118 * `log_file = nil` - nil, filename or function returning a filename
119 * If `log_file` is `nil` `vis-lspc` will create a new file in `$XDG_DATA_HOME/vis-lspc`
120 * `autostart = true` - try to start a language server in WIN_OPEN
121 * `menu_cmd = 'fzf' or 'vis-menu'` - program to prompt for user choices
122 * `confirm_cmd = 'vis-menu'` - program to prompt for user confirmation
123 * `ls_map` - a table mapping `vis` syntax names to language server configurations
124 * `highlight_diagnostics = 'line'` - highlight the `range` or `line`number of available diagnostics
125 * `diagnostic_style_id = nil` - vis style id used to highlight diagnostics, win.STYLE_LEXER_MAX is used by default
126 * `diagnostic_styles = { error = 'back:red', warning = 'back:yellow', information = 'back:yellow', hint = 'back:yellow', }` - styles used to highlight different diagnostics
127 * `workspace_edit_remember_cursor = true` - restore the primary cursor position after a workspaceEdit
128 * `message_level = 3` - the level of shown messages retrieved via `window/showMessage` notifications
129 * `show_message = 'message'` - how to present information. `'message'`: use `vis:message`; `'open'`: use a new window supporting syntax highlighting.
130 * `universal_root_globs = {}` - Globs to consider as workspace root for any language server (e.g. `*.git` or `*.hg`).
131 * `fallback_dirname_as_root = false` - If set to true a file's directory is used as workspace root if no explicit root was found.
132
133 #### Configure your own Language Server
134
135 If `vis-lspc` has no language server configuration for your desired language or server
136 you have to create a language server configuration and insert it into the `ls_map`
137 table.
138 Please have a look at #2 and share your configuration with everyone else.
139
140 A language server configuration is a Lua table containing at least a `name` field
141 which is used to manage the language server and a `cmd` field which is used to
142 start the language server.
143
144 **Note:** the language server must communicate with `vis-lspc` via stdio.
145 Your language server probably supports stdio but maybe requires a [special
146 command line flag](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#implementationConsiderations).
147
148 Additional fields are:
149
150 * `settings` - a table of arbitrary possibly nested data. It is sent in a `workspace/didChangeConfiguration` to the language server after initialization. It is also used to lookup configuration for the `workspace/configuratio` method call.
151 * `init_options` - table of arbitrary possibly nested data. It will be sent to the server as `initializationOptions` in the parameters of the `initialize` method call.
152 * `formatting_options` - table of configuration data as found in [the LSP specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting). `tabSize` and `insertSpaces` are required.
153
154 **Example:** The language server configuration entry in the `ls_map` for `lua-language-server`
155
156 ```lua
157 ls_map.lua = {
158 name = 'lua-language-server',
159 cmd = 'lua-language-server',
160 settings = {
161 Lua = {diagnostics = {globals = {'vis'}}, telemetry = {enable = false}},
162 },
163 formatting_options = {tabSize = 2, insertSpaces = true},
164 },
165 ```
166
167 Language servers configured in `vis-lspc` can be found in `supported_servers.lua`.
168
169 ### Workspace Detection
170
171 During server initialization an URI to the root of the workspace (a folder opened by the editor) can be passed to the server.
172 Workspaces are used to implement certain project wide [features](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_symbol).
173
174 Since vis has no sense of folders and I think it is the job of each individual language server to detect the root of language idiomatic projects, workspace root detection is only activated for certain language servers by default.
175
176 If you want to use some universal criteria to detect project roots, like always using a file's directory or considering all source-control repositories as projects you can use the configuration options `universal_root_globs` and `fallback_dirname_as_root`.
177
178 Additionally, you can configure globs to detect a project's root for each language server using the `roots` member in its `ls_map` table entry.
179
180 For example `roots = {'compile_commands.json', '.clangd'}` is used to detect the project root for clangd.
181
182 ### Events
183
184 vis-lspc extends vis' event system with its own set of events:
185
186 * `lspc.event.LS_INITIALIZED` - emitted after sending the `initialized` notification
187 * `lspc.event.LS_DID_OPEN` - emitted after sending the `textDocument/didOpen` notification
188
189 All events receive the language server as first argument.
190
191 ### Extensibility
192
193 The returned module table also includes functions you can use in your own `vis`
194 configuration.
195
196 #### `lspc.lspc_open`
197
198 Navigate between or in files, while remembering the current position in a runtime history.
199
200 ```lua
201 lspc_open(win, path, line, col, cmd)
202 ```
203
204 - `win` - a window in which to open the file
205 - `path` - the path to the file to open
206 - `line` - the line to open. (`nil` for no position within the file).
207 - `col` - same as `line`, but for the column.
208 - `cmd` - `vis` command to open the file. (`e` or `o`, see `vis` commands)
209
210 ## License
211
212 All code except otherwise noted is licensed under the term of GPL-3.
213 See the LICENSE file for more details.
214 Our fallback JSON implementation in `json.lua` is NOT licensed under GPL-3.
215 It is taken from [here](https://gist.github.com/tylerneylon/59f4bcf316be525b30ab)
216 and is put into public domain by [Tyler Neylon](https://github.com/tylerneylon).