From 522d56557b00246286d803425751a4334f3a94a5 Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Mon, 15 Jul 2024 20:05:47 +0100 Subject: Update lspconfig, add indent-blankline indent-blankline is probably old because I've actually been using it for ages, but I have a strict if-it-ain't-broke policy, so I'm not going to update it. lspconfig *was* broke though with nvim 0.10, so now it's fixed. --- start/lspconfig-0.1.3/doc/lspconfig.txt | 636 -------------------------------- 1 file changed, 636 deletions(-) delete mode 100644 start/lspconfig-0.1.3/doc/lspconfig.txt (limited to 'start/lspconfig-0.1.3/doc/lspconfig.txt') diff --git a/start/lspconfig-0.1.3/doc/lspconfig.txt b/start/lspconfig-0.1.3/doc/lspconfig.txt deleted file mode 100644 index d1d9103..0000000 --- a/start/lspconfig-0.1.3/doc/lspconfig.txt +++ /dev/null @@ -1,636 +0,0 @@ -*lspconfig.txt* For Nvim version 0.6.1+ Last change: 2021 Nov 7 -============================================================================== -TABLE OF CONTENTS *lspconfig-toc* - -1. Introduction (|lspconfig|) -2. LSP overview (|lspconfig-lsp|) -3. Quickstart (|lspconfig-quickstart|) -4. Setup {} (|lspconfig-setup|) -5. Global defaults (|lspconfig-global-defaults|) -6. Server configurations (|lspconfig-configurations|) - 6a. Adding servers (|lspconfig-adding-servers|) -7. Root directories (|lspconfig-root-detection|) - 7a. Advanced detection (|lspconfig-root-advanced|) - 7b. Single file support (|lspconfig-single-file-support|) -8. Commands (|lspconfig-commands|) -9. Keybindings (|lspconfig-keybindings|) -10. Completion (|lspconfig-completion|) -11. Debugging (|lspconfig-debugging|) -12. Logging (|lspconfig-logging|) -13. Scope (|lspconfig-scope|) - -============================================================================== -INTRODUCTION *lspconfig* - -`lspconfig` is a collection of community contributed configurations for the -built-in language server client in Neovim core. This plugin provides four -primary functionalities: - - - default launch commands, initialization options, and settings for each - server - - a root directory resolver which attempts to detect the root of your project - - an autocommand mapping that either launches a new language server or - attempts to attach a language server to each opened buffer if it falls - under a tracked project - - utility commands such as LspInfo, LspStart, LspStop, and LspRestart for - managing language server instances - -`lspconfig` is not required to use the built-in client, it is only one front-end -interface for when a language server specific plugin is not available. - -See |lspconfig-server-configurations| by typing `K` over it for the complete -list of language servers configurations. - -============================================================================== -LSP OVERVIEW *lspconfig-lsp* - -Nvim supports the Language Server Protocol (LSP) via the built-in language -server client. LSP facilitates many features, some of which include: - -- go-to-definition -- find-references -- hover -- completion -- rename -- format -- refactor - -These features are implemented in Neovim core, not `lspconfig`. See `:help lsp` -for more details. - -NOTE: Feature availability depends on the implementation details of the -server. A server may implement only a subset of these features. Always -consult the server documentation before filing a bug report on a missing -feature. - -============================================================================== -QUICKSTART *lspconfig-quickstart* - -- ensure the server is installed and executable from the command line - -- enable the server in your Neovim configuration (Lua example): -> - require'lspconfig'.clangd.setup{} -< -- create a new project, ensure that it contains a root marker which matches the - server requirements specified in |lspconfig-server-configurations|. - -- open a file within that project, such as `main.c`. - -- If you need more information about a server configuration, read the corresponding - entry in |lspconfig-server-configurations|. - -============================================================================== -THE SETUP METAMETHOD *lspconfig-setup* - -`lspconfig` consists of a collection of language server configurations. Each -configuration exposes a `setup {}` metamethod which makes it easy to directly -use the default configuration or selectively override the defaults. -`setup {}` is the primary interface by which users interact with `lspconfig`. - -Using the default configuration for a server is simple: -> - require'lspconfig'.clangd.setup{} -< -The available server names are listed in |lspconfig-server-configurations| and -match the server name in `config.SERVER_NAME` defined in each configuration's -source file. - -The purpose of `setup{}` is to wrap the call to Nvim's built-in -`vim.lsp.start_client()` with an autocommand that automatically launch a -language server. - -This autocommand calls `start_client()` or `vim.lsp.buf_attach_client()` -depending on whether the current file belongs to a project with a currently -running client. See |lspconfig-root-detection| for more details. - -The `setup{}` function takes a table which contains a superset of the keys -listed in `:help vim.lsp.start_client()` with the following unique entries: - -- {root_dir} - - `function(filename, bufnr)` - - Returns either a filepath (string) or nil. The language server will only - start if the function returns a filepath. - - If a root directory (string) is returned which is unique from any - previously returned root_dir, a new server will be spawned with that - root directory. See |lspconfig-root-detection| for more details - -- {name} - - `string` - - Defaults to the server's name (`clangd`, `pyright`, etc.). - -- {filetypes} - - `list[string] | nil` - - Set of filetypes for which to attempt to resolve {root_dir}. - - May be empty, or server may specify a default value. - -- {autostart} - - `bool` (default: true) - - Controls if the `FileType` autocommand that launches a language server is - created. If `false`, allows for deferring language servers until manually - launched with `:LspStart` (|lspconfig-commands|). - -- {single_file_support} - - `bool` (default: nil) - - Determines if a server is started without a matching root directory. - See |lspconfig-single-file-support|. - -- {on_new_config} - - `function(new_config, new_root_dir)` - - Function executed after a root directory is detected. This is used to - modify the server configuration (including `cmd` itself). Most commonly, - this is used to inject additional arguments into `cmd`. - - If overriding `on_new_config`, ensure that you read the - `on_new_config` defined in the source file of the default configuration - in `lspconfig`. The original `on_new_config` snippet for a given server - should likely be included in your new override. Some configurations - use `on_new_config` to dynamically set or modify `cmd`. - -Note: all entries passed to `setup {}` override the entry in the default -configuration. There is no composition. - -All `config` elements described in `:help vim.lsp.start_client()` can -additionally be overridden via the `setup {}` call. The most commonly -passed overrides to `setup {}` are: - -- {capabilities} `table ` - - a table which represents the neovim client capabilities. Useful for - broadcasting to the server additional functionality (snippets, off-protocol - features) provided by plugins. - -- {cmd} `list[string]` - - a list where each entry corresponds to the blankspace delimited part of - the command that launches the server. The first entry is the binary used - to run the language server. Additional entries are passed as arguments. - - The equivalent `cmd` for: -> - foo --bar baz -< - is: -> - {'foo', '--bar', 'baz} -< -- {handlers} `list[functions]` - - a list of handlers which override the function used to process a response - from a given language server. Applied only to the server referenced by - setup. See |lsp-handler|. - -- {init_options} `table ` - - a table passed during the initialization notification after launching - a language server. Equivalent to the `initializationOptions` field found - in `InitializeParams` in the LSP specification. - - See upstream server documentation for available initialization - options. - -- {on_attach} `function(client, bufnr)` - - Callback invoked by Nvim's built-in client when attaching a buffer to a - language server. Often used to set Nvim (buffer or global) options or to - override the Nvim client properties (`resolved_capabilities`) after a - language server attaches. Most commonly used for settings buffer - local keybindings. See |lspconfig-keybindings| for a usage example. - -- {settings} `table ` - - The `settings` table is sent in `on_init` via a - `workspace/didChangeConfiguration` notification from the Nvim client to - the language server. These settings allow a user to change optional runtime - settings of the language server. - - As an example, to set the following settings found in the pyright - documentation: - - `pyright.disableLanguageServices`: `boolean` - `pyright.disableOrganizeImports`: `boolean` - - Nested keys need to be translated into a nested table and passed to - the settings field in `setup {}` as follows: -> - require('lspconfig').pyright.setup{ - settings = { - pyright = { - disableLanguageServices = true, - disableOrganizeImports = true, - } - } - } -< -============================================================================== -OVERRIDING GLOBAL DEFAULTS *lspconfig-global-defaults* - -The global defaults for all servers can be overridden by extending the -`default_config` table. - -> - 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 {}` can additionally override these defaults in subsequent calls. - -============================================================================== -SERVER CONFIGURATIONS *lspconfig-configurations* - -See |lspconfig-server-configurations| by typing `K` over it for the complete -list of language servers configurations. - -While the `setup {}` function is the primary interface to `lspconfig`, for -servers for which there is not a configuration, it is necessary to define a -configuration directly. This can be useful if there is an outstanding PR that -is in review, or when developing a language server that is unavailable -publicly. This can be done through the `configs` module. - -The `configs` module is a singleton where configs are defined. The schema for -validating using `vim.validate` is: -> - configs.SERVER_NAME = { - default_config = {'t'}; - on_new_config = {'f', true}; - on_attach = {'f', true}; - commands = {'t', true}; - docs = {'t', true}; - } -< -where the structure of the docs table is as follows: -> - docs = { - description = {'s', true}; - default_config = {'t', true}; - } -< -`commands` is a map of `name:definition` key:value pairs, where `definition` -is a list whose first value is a function implementing the command, and the -rest are either array values which will be formed into flags for the command, -or special keys like `description`. Example: -> - commands = { - TexlabBuild = { - function() - buf_build(0) - end; - "-range"; - description = "Build the current buffer"; - }; - }; -< -The `configs.__newindex` metamethod consumes the config definition and returns -an object with a `setup()` method, to be invoked by users: -> - require'lspconfig'.SERVER_NAME.setup{} - -After you set `configs.SERVER_NAME` you can add arbitrary language-specific -functions to it if necessary. - -Example: - -> - configs.texlab.buf_build = buf_build -< -============================================================================== -ADDING NEW SERVERS *lspconfig-adding-servers* - -The three steps for adding and enabling a new server configuration are: - -- load the `lspconfig` module (note that this is a stylistic choice) -> - local lspconfig = require 'lspconfig' -< -- define the configuration - -> - local configs = require 'lspconfig.configs' - - -- Check if the config is already defined (useful when reloading this file) - if not configs.foo_lsp then - configs.foo_lsp = { - default_config = { - cmd = {'/home/neovim/lua-language-server/run.sh'}; - filetypes = {'lua'}; - root_dir = function(fname) - return lspconfig.util.find_git_ancestor(fname) - end; - settings = {}; - }; - } - end - -- call `setup()` to enable the FileType autocmd -> - lspconfig.foo_lsp.setup{} -< -============================================================================== -ROOT DETECTION *lspconfig-root-detection* - *lspconfig-root-dir* - -A project's `root_dir` is used by `lspconfig` to determine whether `lspconfig` -should start a new server, or attach a previous one, to the current file. - -`lspconfig` automatically launches language servers by defining a filetype -autocommand based on the `filetypes` specified in the default configuration of -each server, optionally overridable by the `filetypes` table passed to -`setup`. - -This autocommand triggers a search from the current file position in the -filesystem hierarchy up to the top level directory of your filesystem. The -`root_dir` entry of each configuration is a function that returns true if the -current directory in this traversal matches a given root pattern. - -The following utility functions are provided by `lspconfig`. Each function call -below returns a function that takes as its argument the current buffer path. - -- `util.root_pattern`: function which takes multiple arguments, each - corresponding to a different root pattern against which the contents of the - current directory are matched using |vim.fin.glob()| while traversing up the - filesystem. -> - root_dir = util.root_pattern('pyproject.toml', 'requirements.txt') -< -- `util.find_git_ancestor`: a function that locates the first parent directory - containing a `.git` directory. -> - root_dir = util.find_git_ancestor - -- `util.find_node_modules_ancestor`: a function that locates the first parent - directory containing a `node_modules` directory. -> - root_dir = util.find_node_modules_ancestor -< - -- `util.find_package_json_ancestor`: a function that locates the first parent - directory containing a `package.json`. -> - root_dir = util.find_json_ancestor -< -Note: On Windows, `lspconfig` always assumes forward slash normalized paths with -capitalized drive letters. - -============================================================================== -ADVANCED ROOT DIRECTORY DETECTION *lspconfig-root-advanced* - *lspconfig-root-composition* - -The `root_dir` key in `config` and `setup` can hold any function of the form -> - function custom_root_dir(filename, bufnr) - returns nil | string -> -This allows for rich composition of root directory patterns which is necessary -for some project structures. Example (for Kotlin): -> - local root_files = { - 'settings.gradle', -- Gradle (multi-project) - 'settings.gradle.kts', -- Gradle (multi-project) - 'build.xml', -- Ant - 'pom.xml', -- Maven - } - - local fallback_root_files = { - 'build.gradle', -- Gradle - 'build.gradle.kts', -- Gradle - } - root_dir = function(fname) - local primary = util.root_pattern(unpack(root_files))(fname) - local fallback = util.root_pattern(unpack(fallback_root_files))(fname) - return primary or fallback - end -< -Browsing the source of the default configurations is recommended. - -============================================================================== -SINGLE FILE SUPPORT *lspconfig-single-file-support* - -Language servers require each project to have a `root` in order to provide -features that require cross-file indexing. - -Some servers support not passing a root directory as a proxy for single file -mode under which cross-file features may be degraded. - -`lspconfig` offers limited support for an implicit single-file mode by: - -- first trying to resolve the root directory pattern -- then, if `single_file_support` is enabled for a given language server - configuration, starting the server without sending `rootDirectory` or - `workspaceFolders` during initialization. -- attaching subsequent files in the parent directory to the same server - instance, depending on filetype. - -Cross-file features (navigation, hover) may or may not work depending on the -language server. For a full feature-set, consider moving your files to a -directory with a project structure `lspconfig` can infer. - -Note that in the event that the LSP specification is extended to support a -standard for single-file mode, lspconfig will adopt that standard. - -============================================================================== -COMMANDS *lspconfig-commands* - -- `:LspInfo` shows the status of active and configured language servers. Note - that client id refers to the Nvim RPC instance connected to a given - language server. - -The following commands support tab-completion for all arguments. All commands -that require a client id can either leverage tab-completion or the info -contained in `:LspInfo`: - -- `:LspStart ` launches the requested (configured) client, but only - if it successfully resolves a root directory. Note: Defaults to all - configured servers matching the current buffer filetype. -- `:LspStop ` stops the server with the given client id. Defaults to - stopping all servers active on the current buffer. -- `:LspRestart ` restarts the client with the given client id, and - will attempt to reattach to all previously attached buffers. - -============================================================================== -EXAMPLE KEYBINDINGS *lspconfig-keybindings* - -`lspconfig`, and the core client, do not map any keybindings by default. The -following is an example Lua block which demonstrates how to leverage -`on-attach` to selectively apply keybindings after a language servers has -attached to a given buffer. -> -> - -- Mappings. - -- See `:help vim.diagnostic.*` for documentation on any of the below functions - local opts = { noremap=true, silent=true } - vim.api.nvim_set_keymap('n', 'e', 'lua vim.diagnostic.open_float()', opts) - vim.api.nvim_set_keymap('n', '[d', 'lua vim.diagnostic.goto_prev()', opts) - vim.api.nvim_set_keymap('n', ']d', 'lua vim.diagnostic.goto_next()', opts) - vim.api.nvim_set_keymap('n', 'q', 'lua vim.diagnostic.setloclist()', opts) - - -- Use an on_attach function to only map the following keys - -- after the language server attaches to the current buffer - local on_attach = function(client, bufnr) - -- Enable completion triggered by - vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc') - - -- Mappings. - -- See `:help vim.lsp.*` for documentation on any of the below functions - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gD', 'lua vim.lsp.buf.declaration()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gd', 'lua vim.lsp.buf.definition()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'K', 'lua vim.lsp.buf.hover()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gi', 'lua vim.lsp.buf.implementation()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', '', 'lua vim.lsp.buf.signature_help()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wa', 'lua vim.lsp.buf.add_workspace_folder()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wr', 'lua vim.lsp.buf.remove_workspace_folder()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wl', 'lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'D', 'lua vim.lsp.buf.type_definition()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'rn', 'lua vim.lsp.buf.rename()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'ca', 'lua vim.lsp.buf.code_action()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gr', 'lua vim.lsp.buf.references()', opts) - vim.api.nvim_buf_set_keymap(bufnr, 'n', 'f', 'lua vim.lsp.buf.formatting()', opts) - end - - -- Use a loop to conveniently call 'setup' on multiple servers and - -- map buffer local keybindings when the language server attaches - local servers = { 'pyright', 'rust_analyzer', 'tsserver' } - for _, lsp in pairs(servers) do - require('lspconfig')[lsp].setup { - on_attach = on_attach, - flags = { - -- This will be the default in neovim 0.7+ - debounce_text_changes = 150, - } - } - end -< -Note: these keymappings are meant for illustration and override some -infrequently used default mappings. - -============================================================================== -COMPLETION SUPPORT *lspconfig-completion* - -Manually triggered completion can be provided by Nvim's built-in omnifunc. -See `:help omnifunc` for more details. - -For autocompletion, Nvim does not offer built-in functionality at this time. -Consult the `lspconfig` wiki, which provides configuration examples for using a -completion plugin with the built-in client - -============================================================================== -DEBUGGING *lspconfig-debugging* - -While using language servers should be easy, debugging issues can be -challenging. First, it is important to identify the source of the issue, which -is typically (in rough order): - -- the language server itself -- a plugin -- overrides in a user configuration -- the built-in client in Nvim core -- `lspconfig` - -The first step in debugging is to test with a minimal configuration (such as -`../test/minimal_init.lua`). Historically, many users problems are due to -plugins or misconfiguration. - -Should that fail, identifying which component is the culprit is challenging. -The following are the only categories of bugs that pertain to `lspconfig`. - -- The root directory inferred for your project is wrong, or it should be - detected but is not due to a bug in the `lspconfig` path utilities. -- The server is launching, but you believe that the default settings, - initialization options, or command arguments are suboptimal and should be - replaced based on your understanding of the server documentation. - -All bugs Nvim's built-in client should be reported to the Nvim core issue -tracker. All bugs pertaining to plugins should be reported to the respective -plugin. All missing features in a language server should be reported to the -upstream language server issue tracker. - -For debugging `lspconfig` issues, the most common hurdles users face are: - - - The language server is not installed or is otherwise not executable. - `lspconfig` does not install language servers for you. Ensure the `cmd` - defined in `server_configurations.md` is executable from the command - line. If the absolute path to the binary is not supplied in `cmd`, ensure - it is on your PATH. - - No root detected. `lspconfig` is built around the concept of projects. See - |lspconfig-root-detection| for more details. Most of the time, - initializing a git repo will suffice. - - Misconfiguration. Often users will override `cmd`, `on_init`, or - `handlers`. Ensure that you debug by using a stock configuration to ensure - your customizations are not introducing issues. - -|LspInfo| provides an overview of your active and configured language servers -which can be useful for debugging. - -Note that it will not report any configuration changes applied in -`on_new_config`. - -============================================================================== -LOGGING *lspconfig-logging* - -When debugging language servers, it is helpful to enable additional logging in -the built-in client, specifically considering the RPC logs. Example: -> - vim.lsp.set_log_level 'trace' - if vim.fn.has 'nvim-0.5.1' == 1 then - require('vim.lsp.log').set_format_func(vim.inspect) - end -< -Attempt to run the language server, and open the log with: - -> - :lua vim.cmd('e'..vim.lsp.get_log_path()) -< -Note that `ERROR` messages containing `stderr` only indicate that the log was -sent to `stderr`. Many servers counter-intuitively send harmless messages -via stderr. - -============================================================================== -SCOPE *lspconfig-scope* - -`lspconfig` is a community effort to create default configurations that fit -within the scope of an official plugin for Nvim. All features that are not -strictly providing default configurations for language servers will be removed -from `lspconfig` in time. The power of the Neovim LSP ecosystem is in the -composability and flexibility of integrating multiple plugins which maximizes -user choice and freedom. - -`lspconfig` also opts to adhere strictly to the LSP specification, with some -small allowances when small modifications to a server configuration are -necessary to enable features critical to its usability. For more featureful -options, the `lspconfig` wiki lists community created plugins that build upon -the built-in client to provide functionality tailored to specific language -servers. - -============================================================================== - -vim:tw=78:ts=8:ft=help:norl: -- cgit v1.2.3