Vim-fork focused on extensibility and usability
Go to file
Justin M. Keyes 2e8103475e
Merge #15585 refactor: move vim.lsp.diagnostic to vim.diagnostic
## Overview

- Move vim.lsp.diagnostic to vim.diagnostic
- Refactor client ids to diagnostic namespaces
- Update tests
- Write/update documentation and function signatures

Currently, non-LSP diagnostics in Neovim must hook into the LSP subsystem. This
is what e.g. null-ls and nvim-lint do. This is necessary because none of the
diagnostic API is exposed separately from the LSP subsystem.

This commit addresses this by generalizing the diagnostic subsystem beyond the
scope of LSP. The `vim.lsp.diagnostic` module is now simply a specific
diagnostic producer and primarily maintains the interface between LSP clients
and the broader diagnostic API.

The current diagnostic API uses "client ids" which only makes sense in the
context of LSP. We replace "client ids" with standard API namespaces generated
from `nvim_create_namespace`.

This PR is *mostly* backward compatible (so long as plugins are only using the
publicly documented API): LSP diagnostics will continue to work as usual, as
will pseudo-LSP clients like null-ls and nvim-lint. However, the latter can now
use the new interface, which looks something like this:

```lua
-- The namespace *must* be given a name. Anonymous namespaces will not work with diagnostics
local ns = vim.api.nvim_create_namespace("foo")

-- Generate diagnostics
local diagnostics = generate_diagnostics()

-- Set diagnostics for the current buffer
vim.diagnostic.set(ns, diagnostics, bufnr)
```

Some public facing API utility methods were removed and internalized directly in `vim.diagnostic`:

* `vim.lsp.util.diagnostics_to_items`

## API Design

`vim.diagnostic` contains most of the same API as `vim.lsp.diagnostic` with
`client_id` simply replaced with `namespace`, with some differences:

* Generally speaking, functions that modify or add diagnostics require a namespace as their first argument, e.g.

  ```lua
  vim.diagnostic.set({namespace}, {bufnr}, {diagnostics}[, {opts}])
  ```

   while functions that read or query diagnostics do not (although in many cases one may be supplied optionally):

   ```lua
   vim.diagnostic.get({bufnr}[, {namespace}])
   ```

* We use our own severity levels to decouple `vim.diagnostic` from LSP. These
  are designed similarly to `vim.log.levels` and currently include:

  ```lua
  vim.diagnostic.severity.ERROR
  vim.diagnostic.severity.WARN
  vim.diagnostic.severity.INFO
  vim.diagnostic.severity.HINT
  ```

  In practice, these match the LSP diagnostic severity levels exactly, but we
  should treat this as an interface and not assume that they are the same. The
  "translation" between the two severity types is handled transparently in
  `vim.lsp.diagnostic`.

* The actual "diagnostic" data structure is: (**EDIT:** Updated 2021-09-09):

  ```lua
  {
    lnum = <number>,
    col = <number>,
    end_lnum = <number>,
    end_col = <number>,
    severity = <vim.diagnostic.severity>,
    message = <string>
  }
  ```

This differs from the LSP definition of a diagnostic, so we transform them in
the handler functions in vim.lsp.diagnostic.

## Configuration

The `vim.lsp.with` paradigm still works for configuring how LSP diagnostics are
displayed, but this is a specific use-case for the `publishDiagnostics` handler.
Configuration with `vim.diagnostic` is instead done with the
`vim.diagnostic.config` function:

```lua
vim.diagnostic.config({
    virtual_text = true,
    signs = false,
    underline = true,
    update_in_insert = true,
    severity_sort = false,
}[, namespace])
```

(or alternatively passed directly to `set()` or `show()`.)

When the `namespace` argument is `nil`, settings are set globally (i.e. for
*all* diagnostic namespaces). This is what user's will typically use for their
local configuration. Diagnostic producers can also set configuration options for
their specific namespace, although this is generally discouraged in order to
respect the user's global settings. All of the values in the table passed to
`vim.diagnostic.config()` are resolved in the same way that they are in
`on_publish_diagnostics`; that is, the value can be a boolean, a table, or
a function:

```lua
vim.diagnostic.config({
    virtual_text = function(namespace, bufnr)
        -- Only enable virtual text in buffer 3
        return bufnr == 3
    end,
})
```

## Misc Notes

* `vim.diagnostic` currently depends on `vim.lsp.util` for floating window
  previews. I think this is okay for now, although ideally we'd want to decouple
  these completely.
2021-09-16 14:23:42 -07:00
.builds fix(ci): adjust DEPS_INSTALL_DIR on OpenBSD to avoid pkg-config bug (#14803) 2021-06-13 14:03:47 -04:00
.github docs: issue templates 2021-08-22 17:37:08 -07:00
ci fix(test): Detect more core filenames 2021-04-08 08:13:39 -04:00
cmake Merge branch 'master' into histfile 2021-09-10 07:05:11 -07:00
config vim-patch:8.1.2326: cannot parse a date/time string 2021-03-27 10:53:41 -04:00
contrib refactor: format files with uncrustify #15663 2021-09-14 09:13:34 -07:00
man vim-patch:partial 2346a6378483 (#15599) 2021-09-09 18:59:11 +02:00
runtime Merge #15585 refactor: move vim.lsp.diagnostic to vim.diagnostic 2021-09-16 14:23:42 -07:00
scripts Merge #15585 refactor: move vim.lsp.diagnostic to vim.diagnostic 2021-09-16 14:23:42 -07:00
snap cmake: install app icon in XDG hicolor icon theme (#14656) 2021-05-27 22:37:24 +02:00
src Merge #15585 refactor: move vim.lsp.diagnostic to vim.diagnostic 2021-09-16 14:23:42 -07:00
test Merge #15585 refactor: move vim.lsp.diagnostic to vim.diagnostic 2021-09-16 14:23:42 -07:00
third-party build(cmake): skip download if target file exists #14844) 2021-07-08 11:16:13 -07:00
unicode Update unicode files 2020-10-04 11:50:38 -04:00
.clang-format ci: increase clint line length limit to 100 characters (#15252) 2021-08-16 15:32:36 +02:00
.clangd Adding clangd language serever config file to point to build/ directory for compile_commands.json 2021-06-28 11:03:09 -04:00
.editorconfig editorconfig: set default tab width to 8 (#9467) 2019-01-07 02:15:19 +01:00
.flake8 ci: pylint target via flake8 2019-07-29 22:14:23 +02:00
.git-blame-ignore-revs docs: .git-blame-ignore-revs #15535 2021-09-11 07:12:03 -07:00
.gitattributes Exclude .github/ and CI files from exported archives 2021-05-05 08:59:12 -04:00
.gitignore chore: added ccls-cache in .gitignore (#15175) 2021-07-25 19:12:07 +02:00
.luacheckrc luacheck: Enforce compatibility with Lua5.1 2020-07-31 01:32:07 -04:00
.luacov Lua: vim.validate() 2019-11-10 22:50:24 -08:00
.travis.yml ci(travis): Remove jobs covered by GHA 2020-12-28 21:19:48 -05:00
BACKERS.md Update backer URL 2015-11-11 19:50:33 -08:00
BSDmakefile feat(lua)!: register_keystroke_callback => on_key 2021-09-09 06:09:33 -07:00
CMakeLists.txt version bump 2021-07-02 18:12:11 +02:00
codecov.yml bundle: move tree-sitter as a bundled dep 2020-11-03 10:39:35 +01:00
CONTRIBUTING.md docs: naming conventions 2021-09-09 06:28:11 -07:00
LICENSE docs: third-party licenses, TEST_COLORS, system() #15665 2021-09-14 10:20:33 -07:00
MAINTAIN.md docs: third-party licenses, TEST_COLORS, system() #15665 2021-09-14 10:20:33 -07:00
Makefile build: Inherit -n and -jN flags if Ninja #12219 2020-05-01 07:36:56 -07:00
README.md docs: .git-blame-ignore-revs #15510 2021-08-28 14:00:54 -07:00

Neovim

Documentation | Chat | Twitter

GitHub CI Codecov coverage Coverity Scan analysis Clang analysis PVS-Studio analysis

Packages Debian CI Downloads nvim

Neovim is a project that seeks to aggressively refactor Vim in order to:

See the Introduction wiki page and Roadmap for more information.

Features

See :help nvim-features for the full list!

Install from package

Pre-built packages for Windows, macOS, and Linux are found on the Releases page.

Managed packages are in Homebrew, Debian, Ubuntu, Fedora, Arch Linux, Void Linux, Gentoo, and more!

Install from source

See the Building Neovim wiki page for details.

The build is CMake-based, but a Makefile is provided as a convenience. After installing the dependencies, run the following command.

make CMAKE_BUILD_TYPE=RelWithDebInfo
sudo make install

To install to a non-default location:

make CMAKE_INSTALL_PREFIX=/full/path/
make install

CMake hints for inspecting the build:

  • cmake --build build --target help lists all build targets.
  • build/CMakeCache.txt (or cmake -LAH build/) contains the resolved values of all CMake variables.
  • build/compile_commands.json shows the full compiler invocations for each translation unit.

Transitioning from Vim

See :help nvim-from-vim for instructions.

Project layout

├─ ci/              build automation
├─ cmake/           build scripts
├─ runtime/         user plugins/docs
├─ src/nvim/        application source code (see src/nvim/README.md)
│  ├─ api/          API subsystem
│  ├─ eval/         VimL subsystem
│  ├─ event/        event-loop subsystem
│  ├─ generators/   code generation (pre-compilation)
│  ├─ lib/          generic data structures
│  ├─ lua/          Lua subsystem
│  ├─ msgpack_rpc/  RPC subsystem
│  ├─ os/           low-level platform code
│  └─ tui/          built-in UI
├─ third-party/     CMake subproject to build dependencies
└─ test/            tests (see test/README.md)

License

Neovim contributions since b17d96 are licensed under the Apache 2.0 license, except for contributions copied from Vim (identified by the vim-patch token). See LICENSE for details.

Vim is Charityware.  You can use and copy it as much as you like, but you are
encouraged to make a donation for needy children in Uganda.  Please see the
kcc section of the vim docs or visit the ICCF web site, available at these URLs:

        http://iccf-holland.org/
        http://www.vim.org/iccf/
        http://www.iccf.nl/

You can also sponsor the development of Vim.  Vim sponsors can vote for
features.  The money goes to Uganda anyway.