mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 11:15:14 -07:00
e61ea7772e
* feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
555 lines
24 KiB
Plaintext
555 lines
24 KiB
Plaintext
*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.
|
|
|
|
*diagnostic-structure*
|
|
A diagnostic is a Lua table with the following keys:
|
|
|
|
lnum: The starting line of the diagnostic
|
|
end_lnum: The final line of the diagnostic
|
|
col: The starting column of the diagnostic
|
|
end_col: The final column of the diagnostic
|
|
severity: The severity of the diagnostic |vim.diagnostic.severity|
|
|
message: The diagnostic text
|
|
|
|
Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based
|
|
rows and columns). |api-indexing|
|
|
|
|
*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 two forms:
|
|
|
|
1. A single |vim.diagnostic.severity| value: >
|
|
|
|
vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
|
|
|
|
2. A table with a "min" or "max" key (or both): >
|
|
|
|
vim.diagnostic.get(0, { severity = {min=vim.diagnostic.severity.WARN})
|
|
|
|
The latter form allows users to specify a range of severities.
|
|
|
|
==============================================================================
|
|
HIGHLIGHTS *diagnostic-highlights*
|
|
|
|
All highlights defined for diagnostics begin with `Diagnostic` followed by
|
|
the type of highlight (e.g., `Sign`, `Underline`, etc.) and the severity (e.g.
|
|
`Error`, `Warn`, etc.)
|
|
|
|
Sign, underline and virtual text highlights (by default) are linked to their
|
|
corresponding default highlight.
|
|
|
|
For example, the default highlighting for |hl-DiagnosticSignError| is linked
|
|
to |hl-DiagnosticError|. To change the default (and therefore the linked
|
|
highlights), use the |:highlight| command: >
|
|
|
|
highlight DiagnosticError guifg="BrightRed"
|
|
<
|
|
*hl-DiagnosticError*
|
|
DiagnosticError
|
|
Used as the base highlight group.
|
|
Other Diagnostic highlights link to this by default (except Underline)
|
|
|
|
*hl-DiagnosticWarn*
|
|
DiagnosticWarn
|
|
Used as the base highlight group.
|
|
Other Diagnostic highlights link to this by default (except Underline)
|
|
|
|
*hl-DiagnosticInfo*
|
|
DiagnosticInfo
|
|
Used as the base highlight group.
|
|
Other Diagnostic highlights link to this by default (except Underline)
|
|
|
|
*hl-DiagnosticHint*
|
|
DiagnosticHint
|
|
Used as the base highlight group.
|
|
Other Diagnostic highlights link to this by default (except Underline)
|
|
|
|
*hl-DiagnosticVirtualTextError*
|
|
DiagnosticVirtualTextError
|
|
Used for "Error" diagnostic virtual text.
|
|
|
|
*hl-DiagnosticVirtualTextWarn*
|
|
DiagnosticVirtualTextWarn
|
|
Used for "Warn" diagnostic virtual text.
|
|
|
|
*hl-DiagnosticVirtualTextInfo*
|
|
DiagnosticVirtualTextInfo
|
|
Used for "Info" diagnostic virtual text.
|
|
|
|
*hl-DiagnosticVirtualTextHint*
|
|
DiagnosticVirtualTextHint
|
|
Used for "Hint" diagnostic virtual text.
|
|
|
|
*hl-DiagnosticUnderlineError*
|
|
DiagnosticUnderlineError
|
|
Used to underline "Error" diagnostics.
|
|
|
|
*hl-DiagnosticUnderlineWarn*
|
|
DiagnosticUnderlineWarn
|
|
Used to underline "Warn" diagnostics.
|
|
|
|
*hl-DiagnosticUnderlineInfo*
|
|
DiagnosticUnderlineInfo
|
|
Used to underline "Info" diagnostics.
|
|
|
|
*hl-DiagnosticUnderlineHint*
|
|
DiagnosticUnderlineHint
|
|
Used to underline "Hint" diagnostics.
|
|
|
|
*hl-DiagnosticFloatingError*
|
|
DiagnosticFloatingError
|
|
Used to color "Error" diagnostic messages in diagnostics float.
|
|
See |vim.diagnostic.show_line_diagnostics()|
|
|
|
|
*hl-DiagnosticFloatingWarn*
|
|
DiagnosticFloatingWarn
|
|
Used to color "Warn" diagnostic messages in diagnostics float.
|
|
|
|
*hl-DiagnosticFloatingInfo*
|
|
DiagnosticFloatingInfo
|
|
Used to color "Info" diagnostic messages in diagnostics float.
|
|
|
|
*hl-DiagnosticFloatingHint*
|
|
DiagnosticFloatingHint
|
|
Used to color "Hint" diagnostic messages in diagnostics float.
|
|
|
|
*hl-DiagnosticSignError*
|
|
DiagnosticSignError
|
|
Used for "Error" signs in sign column.
|
|
|
|
*hl-DiagnosticSignWarn*
|
|
DiagnosticSignWarn
|
|
Used for "Warn" signs in sign column.
|
|
|
|
*hl-DiagnosticSignInfo*
|
|
DiagnosticSignInfo
|
|
Used for "Info" signs in sign column.
|
|
|
|
*hl-DiagnosticSignHint*
|
|
DiagnosticSignHint
|
|
Used for "Hint" signs in sign column.
|
|
|
|
==============================================================================
|
|
SIGNS *diagnostic-signs*
|
|
|
|
Signs are defined for each diagnostic severity. The default text for each sign
|
|
is the first letter of the severity name (for example, "E" for ERROR). Signs
|
|
can be customized using the following: >
|
|
|
|
sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl=
|
|
sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl=
|
|
sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl=
|
|
sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl=
|
|
|
|
==============================================================================
|
|
EVENTS *diagnostic-events*
|
|
|
|
*DiagnosticsChanged*
|
|
DiagnosticsChanged After diagnostics have changed.
|
|
|
|
Example: >
|
|
autocmd User DiagnosticsChanged lua vim.diagnostic.setqflist({open = false })
|
|
<
|
|
|
|
==============================================================================
|
|
Lua module: vim.diagnostic *diagnostic-api*
|
|
|
|
config({opts}, {namespace}) *vim.diagnostic.config()*
|
|
Configure diagnostic options globally or for a specific
|
|
diagnostic namespace.
|
|
|
|
Note:
|
|
Each of the configuration options below accepts one of the
|
|
following:
|
|
• `false` : Disable this feature
|
|
• `true` : Enable this feature, use default settings.
|
|
• `table` : Enable this feature with overrides.
|
|
• `function` : Function with signature (namespace, bufnr)
|
|
that returns any of the above.
|
|
|
|
Parameters: ~
|
|
{opts} table Configuration table with the following
|
|
keys:
|
|
• underline: (default true) Use underline for
|
|
diagnostics. Options:
|
|
• severity: Only underline diagnostics
|
|
matching the given severity
|
|
|diagnostic-severity|
|
|
|
|
• virtual_text: (default true) Use virtual
|
|
text for diagnostics. Options:
|
|
• severity: Only show virtual text for
|
|
diagnostics matching the given severity
|
|
|diagnostic-severity|
|
|
|
|
• signs: (default true) Use signs for
|
|
diagnostics. Options:
|
|
• severity: Only show signs for diagnostics
|
|
matching the given severity
|
|
|diagnostic-severity|
|
|
|
|
• update_in_insert: (default false) Update
|
|
diagnostics in Insert mode (if false,
|
|
diagnostics are updated on InsertLeave)
|
|
• severity_sort: (default false) Sort
|
|
diagnostics by severity. This affects the
|
|
order in which signs and virtual text are
|
|
displayed. When true, higher severities are
|
|
displayed before lower severities (e.g.
|
|
ERROR is displayed before WARN). Options:
|
|
• reverse: (boolean) Reverse sort order
|
|
{namespace} number|nil Update the options for the given
|
|
namespace. When omitted, update the global
|
|
diagnostic options.
|
|
|
|
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
|
|
Disable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
{bufnr} number|nil Buffer number. Defaults to the
|
|
current buffer.
|
|
{namespace} number|nil Only disable diagnostics for the
|
|
given namespace.
|
|
|
|
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
|
|
Enable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
{bufnr} number|nil Buffer number. Defaults to the
|
|
current buffer.
|
|
{namespace} number|nil Only enable diagnostics for the
|
|
given namespace.
|
|
|
|
fromqflist({list}) *vim.diagnostic.fromqflist()*
|
|
Convert a list of quickfix items to a list of diagnostics.
|
|
|
|
Parameters: ~
|
|
{list} table A list of quickfix items from |getqflist()|
|
|
or |getloclist()|.
|
|
|
|
Return: ~
|
|
array of diagnostics |diagnostic-structure|
|
|
|
|
get({bufnr}, {opts}) *vim.diagnostic.get()*
|
|
Get current diagnostics.
|
|
|
|
Parameters: ~
|
|
{bufnr} number|nil Buffer number to get diagnostics from.
|
|
Use 0 for current buffer or nil for all buffers.
|
|
{opts} table|nil A table with the following keys:
|
|
• namespace: (number) Limit diagnostics to the
|
|
given namespace.
|
|
• lnum: (number) Limit diagnostics to the given
|
|
line number.
|
|
• severity: See |diagnostic-severity|.
|
|
|
|
Return: ~
|
|
table A list of diagnostic items |diagnostic-structure|.
|
|
|
|
get_next({opts}) *vim.diagnostic.get_next()*
|
|
Get the next diagnostic closest to the cursor position.
|
|
|
|
Parameters: ~
|
|
{opts} table See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table Next diagnostic
|
|
|
|
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
|
|
Return the position of the next diagnostic in the current
|
|
buffer.
|
|
|
|
Parameters: ~
|
|
{opts} table See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table Next diagnostic position as a (row, col) tuple.
|
|
|
|
get_prev({opts}) *vim.diagnostic.get_prev()*
|
|
Get the previous diagnostic closest to the cursor position.
|
|
|
|
Parameters: ~
|
|
{opts} table See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table Previous diagnostic
|
|
|
|
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
|
|
Return the position of the previous diagnostic in the current
|
|
buffer.
|
|
|
|
Parameters: ~
|
|
{opts} table See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table Previous diagnostic position as a (row, col) tuple.
|
|
|
|
*vim.diagnostic.get_virt_text_chunks()*
|
|
get_virt_text_chunks({line_diags}, {opts})
|
|
Get virtual text chunks to display using
|
|
|nvim_buf_set_extmark()|.
|
|
|
|
Parameters: ~
|
|
{line_diags} table The diagnostics associated with the
|
|
line.
|
|
{opts} table|nil Configuration table with the
|
|
following keys:
|
|
• prefix: (string) Prefix to display before
|
|
virtual text on line.
|
|
• spacing: (number) Number of spaces to
|
|
insert before virtual text.
|
|
|
|
Return: ~
|
|
array of ({text}, {hl_group}) tuples. This can be passed
|
|
directly to the {virt_text} option of
|
|
|nvim_buf_set_extmark()|.
|
|
|
|
goto_next({opts}) *vim.diagnostic.goto_next()*
|
|
Move to the next diagnostic.
|
|
|
|
Parameters: ~
|
|
{opts} table|nil Configuration table with the following
|
|
keys:
|
|
• namespace: (number) Only consider diagnostics
|
|
from the given namespace.
|
|
• cursor_position: (cursor position) Cursor
|
|
position as a (row, col) tuple. See
|
|
|nvim_win_get_cursor()|. Defaults to the current
|
|
cursor position.
|
|
• wrap: (boolean, default true) Whether to loop
|
|
around file or not. Similar to 'wrapscan'.
|
|
• severity: See |diagnostic-severity|.
|
|
• enable_popup: (boolean, default true) Call
|
|
|vim.diagnostic.show_line_diagnostics()| on
|
|
jump.
|
|
• popup_opts: (table) Table to pass as {opts}
|
|
parameter to
|
|
|vim.diagnostic.show_line_diagnostics()|
|
|
• win_id: (number, default 0) Window ID
|
|
|
|
goto_prev({opts}) *vim.diagnostic.goto_prev()*
|
|
Move to the previous diagnostic in the current buffer.
|
|
|
|
Parameters: ~
|
|
{opts} table See |vim.diagnostic.goto_next()|
|
|
|
|
hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
|
|
Hide currently displayed diagnostics.
|
|
|
|
This only clears the decorations displayed in the buffer.
|
|
Diagnostics can be redisplayed with |vim.diagnostic.show()|.
|
|
To completely remove diagnostics, use
|
|
|vim.diagnostic.reset()|.
|
|
|
|
To hide diagnostics and prevent them from re-displaying, use
|
|
|vim.diagnostic.disable()|.
|
|
|
|
Parameters: ~
|
|
{namespace} number The diagnostic namespace
|
|
{bufnr} number|nil Buffer number. Defaults to the
|
|
current buffer.
|
|
|
|
*vim.diagnostic.match()*
|
|
match({str}, {pat}, {groups}, {severity_map}, {defaults})
|
|
Parse a diagnostic from a string.
|
|
|
|
For example, consider a line of output from a linter: >
|
|
|
|
WARNING filename:27:3: Variable 'foo' does not exist
|
|
|
|
< This can be parsed into a diagnostic |diagnostic-structure|
|
|
with: >
|
|
|
|
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
|
|
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
|
|
local groups = {"severity", "lnum", "col", "message"}
|
|
vim.diagnostic.match(s, pattern, groups, {WARNING = vim.diagnostic.WARN})
|
|
<
|
|
|
|
Parameters: ~
|
|
{str} string String to parse diagnostics from.
|
|
{pat} string Lua pattern with capture groups.
|
|
{groups} table List of fields in a
|
|
|diagnostic-structure| to associate with
|
|
captures from {pat}.
|
|
{severity_map} table A table mapping the severity field
|
|
from {groups} with an item from
|
|
|vim.diagnostic.severity|.
|
|
{defaults} table|nil Table of default values for any
|
|
fields not listed in {groups}. When
|
|
omitted, numeric values default to 0 and
|
|
"severity" defaults to ERROR.
|
|
|
|
Return: ~
|
|
diagnostic |diagnostic-structure| or `nil` if {pat} fails
|
|
to match {str}.
|
|
|
|
reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
|
|
Remove all diagnostics from the given namespace.
|
|
|
|
Unlike |vim.diagnostic.hide()|, this function removes all
|
|
saved diagnostics. They cannot be redisplayed using
|
|
|vim.diagnostic.show()|. To simply remove diagnostic
|
|
decorations in a way that they can be re-displayed, use
|
|
|vim.diagnostic.hide()|.
|
|
|
|
Parameters: ~
|
|
{namespace} number
|
|
{bufnr} number|nil Remove diagnostics for the given
|
|
buffer. When omitted, diagnostics are removed
|
|
for all buffers.
|
|
|
|
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
|
|
Set diagnostics for the given namespace and buffer.
|
|
|
|
Parameters: ~
|
|
{namespace} number The diagnostic namespace
|
|
{bufnr} number Buffer number
|
|
{diagnostics} table A list of diagnostic items
|
|
|diagnostic-structure|
|
|
{opts} table|nil Display options to pass to
|
|
|vim.diagnostic.show()|
|
|
|
|
setloclist({opts}) *vim.diagnostic.setloclist()*
|
|
Add buffer diagnostics to the location list.
|
|
|
|
Parameters: ~
|
|
{opts} table|nil Configuration table with the following
|
|
keys:
|
|
• namespace: (number) Only add diagnostics from
|
|
the given namespace.
|
|
• winnr: (number, default 0) Window number to set
|
|
location list for.
|
|
• open: (boolean, default true) Open the location
|
|
list after setting.
|
|
• title: (string) Title of the location list.
|
|
Defaults to "Diagnostics".
|
|
• severity: See |diagnostic-severity|.
|
|
|
|
setqflist({opts}) *vim.diagnostic.setqflist()*
|
|
Add all diagnostics to the quickfix list.
|
|
|
|
Parameters: ~
|
|
{opts} table|nil Configuration table with the following
|
|
keys:
|
|
• namespace: (number) Only add diagnostics from
|
|
the given namespace.
|
|
• open: (boolean, default true) Open quickfix list
|
|
after setting.
|
|
• title: (string) Title of quickfix list. Defaults
|
|
to "Diagnostics".
|
|
• severity: See |diagnostic-severity|.
|
|
|
|
*vim.diagnostic.show()*
|
|
show({namespace}, {bufnr}, {diagnostics}, {opts})
|
|
Display diagnostics for the given namespace and buffer.
|
|
|
|
Parameters: ~
|
|
{namespace} number Diagnostic namespace
|
|
{bufnr} number|nil Buffer number. Defaults to the
|
|
current buffer.
|
|
{diagnostics} table|nil The diagnostics to display. When
|
|
omitted, use the saved diagnostics for the
|
|
given namespace and buffer. This can be
|
|
used to display a list of diagnostics
|
|
without saving them or to display only a
|
|
subset of diagnostics.
|
|
{opts} table|nil Display options. See
|
|
|vim.diagnostic.config()|.
|
|
|
|
*vim.diagnostic.show_line_diagnostics()*
|
|
show_line_diagnostics({opts}, {bufnr}, {lnum})
|
|
Open a floating window with the diagnostics from the given
|
|
line.
|
|
|
|
Parameters: ~
|
|
{opts} table Configuration table. See
|
|
|vim.diagnostic.show_position_diagnostics()|.
|
|
{bufnr} number|nil Buffer number. Defaults to the current
|
|
buffer.
|
|
{lnum} number|nil Line number. Defaults to line number
|
|
of cursor.
|
|
|
|
Return: ~
|
|
tuple ({popup_bufnr}, {win_id})
|
|
|
|
*vim.diagnostic.show_position_diagnostics()*
|
|
show_position_diagnostics({opts}, {bufnr}, {position})
|
|
Open a floating window with the diagnostics at the given
|
|
position.
|
|
|
|
Parameters: ~
|
|
{opts} table|nil Configuration table with the same
|
|
keys as |vim.lsp.util.open_floating_preview()|
|
|
in addition to the following:
|
|
• namespace: (number) Limit diagnostics to the
|
|
given namespace
|
|
• severity: See |diagnostic-severity|.
|
|
• show_header: (boolean, default true) Show
|
|
"Diagnostics:" header
|
|
{bufnr} number|nil Buffer number. Defaults to the
|
|
current buffer.
|
|
{position} table|nil The (0,0)-indexed position. Defaults
|
|
to the current cursor position.
|
|
|
|
Return: ~
|
|
tuple ({popup_bufnr}, {win_id})
|
|
|
|
toqflist({diagnostics}) *vim.diagnostic.toqflist()*
|
|
Convert a list of diagnostics to a list of quickfix items that
|
|
can be passed to |setqflist()| or |setloclist()|.
|
|
|
|
Parameters: ~
|
|
{diagnostics} table List of diagnostics
|
|
|diagnostic-structure|.
|
|
|
|
Return: ~
|
|
array of quickfix list items |setqflist-what|
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|