*diagnostic.txt*   Diagnostics


                            NVIM REFERENCE MANUAL


Diagnostic framework                                     *vim.diagnostic*

Nvim provides a framework for displaying errors or warnings from external
tools, otherwise known as "diagnostics". These diagnostics can come from a
variety of sources, such as linters or LSP servers. The diagnostic framework
is an extension to existing error handling functionality such as the
|quickfix| list.

                                      Type |gO| to see the table of contents.

==============================================================================
QUICKSTART                                              *diagnostic-quickstart*

Anything that reports diagnostics is referred to below as a "diagnostic
producer". Diagnostic producers need only follow a few simple steps to
report diagnostics:

1. Create a namespace |nvim_create_namespace()|. Note that the namespace must
   have a name. Anonymous namespaces WILL NOT WORK.
2. (Optional) Configure options for the diagnostic namespace
   |vim.diagnostic.config()|.
3. Generate diagnostics.
4. Set the diagnostics for the buffer |vim.diagnostic.set()|.
5. Repeat from step 3.

Generally speaking, the API is split between functions meant to be used by
diagnostic producers and those meant for diagnostic consumers (i.e. end users
who want to read and view the diagnostics for a buffer).  The APIs for
producers require a {namespace} as their first argument, while those for
consumers generally do not require a namespace (though often one may be
optionally supplied).  A good rule of thumb is that if a method is meant to
modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it
requires a namespace.

                                *vim.diagnostic.severity* *diagnostic-severity*
The "severity" key in a diagnostic is one of the values defined in
`vim.diagnostic.severity`:

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

Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) accept one of three forms:

1. A single |vim.diagnostic.severity| value: >lua

    vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })

2. A table with a "min" or "max" key (or both): >lua

    vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
<
    This form allows users to specify a range of severities.

3. A list-like table: >lua

    vim.diagnostic.get(0, { severity = {
        vim.diagnostic.severity.WARN,
        vim.diagnostic.severity.INFO,
    } })
<
    This form allows users to filter for specific severities

==============================================================================
HANDLERS                                                *diagnostic-handlers*

Diagnostics are shown to the user with |vim.diagnostic.show()|. The display of
diagnostics is managed through handlers. A handler is a table with a "show"
and (optionally) a "hide" function. The "show" function has the signature
>
    function(namespace, bufnr, diagnostics, opts)
<
and is responsible for displaying or otherwise handling the given
diagnostics. The "hide" function takes care of "cleaning up" any actions taken
by the "show" function and has the signature
>
    function(namespace, bufnr)
<
Handlers can be configured with |vim.diagnostic.config()| and added by
creating a new key in `vim.diagnostic.handlers` (see
|diagnostic-handlers-example|).

The {opts} table passed to a handler is the full set of configuration options
(that is, it is not limited to just the options for the handler itself). The
values in the table are already resolved (i.e. if a user specifies a
function for a config option, the function has already been evaluated).

If a diagnostic handler is configured with a "severity" key then the list of
diagnostics passed to that handler will be filtered using the value of that
key (see example