2021-09-06 19:21:18 -07:00
*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*
2022-03-02 18:42:27 -07:00
A diagnostic is a Lua table with the following keys. Required keys are
2023-02-21 09:39:29 -07:00
indicated with (+):
2021-09-06 19:21:18 -07:00
2021-12-11 08:59:16 -07:00
bufnr: Buffer number
2023-02-21 09:39:29 -07:00
lnum(+): The starting line of the diagnostic
2021-09-06 19:21:18 -07:00
end_lnum: The final line of the diagnostic
2023-02-21 09:39:29 -07:00
col(+): The starting column of the diagnostic
2021-09-06 19:21:18 -07:00
end_col: The final column of the diagnostic
severity: The severity of the diagnostic |vim.diagnostic.severity|
2023-02-21 09:39:29 -07:00
message(+): The diagnostic text
2021-09-18 14:00:32 -07:00
source: The source of the diagnostic
2022-03-02 18:42:27 -07:00
code: The diagnostic code
2021-12-11 08:59:16 -07:00
user_data: Arbitrary data plugins or users can add
2021-09-06 19:21:18 -07:00
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:
2022-11-22 10:41:00 -07:00
1. A single |vim.diagnostic.severity| value: >lua
2021-09-06 19:21:18 -07:00
vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
2022-11-22 10:41:00 -07:00
2. A table with a "min" or "max" key (or both): >lua
2021-09-06 19:21:18 -07:00
2022-03-09 23:34:55 -07:00
vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
2021-09-06 19:21:18 -07:00
The latter form allows users to specify a range of severities.
2021-10-29 18:47:34 -07:00
==============================================================================
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).
Nvim provides these handlers by default: "virtual_text", "signs", and
"underline".
*diagnostic-handlers-example*
The example below creates a new handler that notifies the user of diagnostics
2022-11-22 10:41:00 -07:00
with |vim.notify()|: >lua
2021-10-29 18:47:34 -07:00
-- It's good practice to namespace custom handlers to avoid collisions
vim.diagnostic.handlers["my/notify"] = {
show = function(namespace, bufnr, diagnostics, opts)
-- In our example, the opts table has a "log_level" option
local level = opts["my/notify"].log_level
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
local name = vim.diagnostic.get_namespace(namespace).name
local msg = string.format("%d diagnostics in buffer %d from %s",
#diagnostics,
bufnr,
name)
vim.notify(msg, level)
end,
}
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
-- Users can configure the handler
vim.diagnostic.config({
["my/notify"] = {
log_level = vim.log.levels.INFO
}
})
<
In this example, there is nothing to do when diagnostics are hidden, so we
omit the "hide" function.
Existing handlers can be overridden. For example, use the following to only
2022-11-22 10:41:00 -07:00
show a sign for the highest severity diagnostic on a given line: >lua
2021-10-29 18:47:34 -07:00
-- Create a custom namespace. This will aggregate signs from all other
-- namespaces and only show the one with the highest severity on a
-- given line
local ns = vim.api.nvim_create_namespace("my_namespace")
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
-- Get a reference to the original signs handler
local orig_signs_handler = vim.diagnostic.handlers.signs
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
-- Override the built-in signs handler
vim.diagnostic.handlers.signs = {
show = function(_, bufnr, _, opts)
-- Get all diagnostics from the whole buffer rather than just the
-- diagnostics passed to the handler
local diagnostics = vim.diagnostic.get(bufnr)
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
-- Find the "worst" diagnostic per line
local max_severity_per_line = {}
for _, d in pairs(diagnostics) do
local m = max_severity_per_line[d.lnum]
if not m or d.severity < m.severity then
max_severity_per_line[d.lnum] = d
end
end
2022-08-11 05:25:48 -07:00
2021-10-29 18:47:34 -07:00
-- Pass the filtered diagnostics (with our custom namespace) to
-- the original handler
local filtered_diagnostics = vim.tbl_values(max_severity_per_line)
orig_signs_handler.show(ns, bufnr, filtered_diagnostics, opts)
end,
hide = function(_, bufnr)
orig_signs_handler.hide(ns, bufnr)
end,
}
<
2021-09-06 19:21:18 -07:00
==============================================================================
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.)
By default, highlights for signs, floating windows, and virtual text are linked to the
corresponding default highlight. Underline highlights are not linked and use their
own default highlight groups.
For example, the default highlighting for |hl-DiagnosticSignError| is linked
to |hl-DiagnosticError|. To change the default (and therefore the linked
2022-11-22 10:41:00 -07:00
highlights), use the |:highlight| command: >vim
2021-09-06 19:21:18 -07:00
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
2022-12-28 09:01:40 -07:00
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)
*hl-DiagnosticOk*
DiagnosticOk
2021-09-06 19:21:18 -07:00
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.
2022-12-28 09:01:40 -07:00
*hl-DiagnosticVirtualTextOk*
DiagnosticVirtualTextOk
Used for "Ok" diagnostic virtual text.
2021-09-06 19:21:18 -07:00
*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.
2022-12-28 09:01:40 -07:00
*hl-DiagnosticUnderlineOk*
DiagnosticUnderlineOk
Used to underline "Ok" diagnostics.
2021-09-06 19:21:18 -07:00
*hl-DiagnosticFloatingError*
DiagnosticFloatingError
Used to color "Error" diagnostic messages in diagnostics float.
2021-11-28 09:42:29 -07:00
See |vim.diagnostic.open_float()|
2021-09-06 19:21:18 -07:00
*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.
2022-12-28 09:01:40 -07:00
*hl-DiagnosticFloatingOk*
DiagnosticFloatingOk
Used to color "Ok" diagnostic messages in diagnostics float.
2021-09-06 19:21:18 -07:00
*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.
2022-12-28 09:01:40 -07:00
*hl-DiagnosticSignOk*
DiagnosticSignOk
Used for "Ok" signs in sign column.
2023-04-08 10:19:39 -07:00
*hl-DiagnosticDeprecated*
DiagnosticDeprecated
Used for deprecated or obsolete code.
*hl-DiagnosticUnnecessary*
DiagnosticUnnecessary
Used for unnecessary or unused code.
2021-09-06 19:21:18 -07:00
==============================================================================
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
2022-11-22 10:41:00 -07:00
can be customized using the following: >vim
2021-09-06 19:21:18 -07:00
sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl=
2021-09-19 15:13:23 -07:00
sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl=
sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl=
2021-09-06 19:21:18 -07:00
sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl=
2021-09-26 16:02:18 -07:00
When the "severity_sort" option is set (see |vim.diagnostic.config()|) the
priority of each sign depends on the severity of the associated diagnostic.
Otherwise, all signs have the same priority (the value of the "priority"
option in the "signs" table of |vim.diagnostic.config()| or 10 if unset).
2021-09-06 19:21:18 -07:00
==============================================================================
EVENTS *diagnostic-events*
2021-11-25 11:55:11 -07:00
*DiagnosticChanged*
2022-09-13 07:33:39 -07:00
DiagnosticChanged After diagnostics have changed. When used from Lua,
the new diagnostics are passed to the autocmd
callback in the "data" table.
2021-09-06 19:21:18 -07:00
2022-11-22 10:41:00 -07:00
Example: >lua
2022-09-13 07:33:39 -07:00
vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
local diagnostics = args.data.diagnostics
refactor!: rename vim.pretty_print => vim.print
Problem:
The function name `vim.pretty_print`:
1. is verbose, which partially defeats its purpose as sugar
2. does not draw from existing precedent or any sort of convention
(except external projects like penlight or python?), which reduces
discoverability, and degrades signaling about best practices.
Solution:
- Rename to `vim.print`.
- Change the behavior so that
1. strings are printed without quotes
2. each arg is printed on its own line
3. tables are indented with 2 instead of 4 spaces
- Example:
:lua ='a', 'b', 42, {a=3}
a
b
42
{
a = 3
}
Comparison of alternatives:
- `vim.print`:
- pro: consistent with Lua's `print()`
- pro: aligns with potential `nvim_print` API function which will
replace nvim_echo, nvim_notify, etc.
- con: behaves differently than Lua's `print()`, slightly misleading?
- `vim.echo`:
- pro: `:echo` has similar "pretty print" behavior.
- con: inconsistent with Lua idioms.
- `vim.p`:
- pro: very short, fits with `vim.o`, etc.
- con: not as discoverable as "echo"
- con: less opportunity for `local p = vim.p` because of potential shadowing.
2023-03-07 08:04:57 -07:00
vim.print(diagnostics)
2022-09-13 07:33:39 -07:00
end,
})
2021-09-06 19:21:18 -07:00
<
2021-09-25 08:52:20 -07:00
==============================================================================
2021-09-06 19:21:18 -07:00
Lua module: vim.diagnostic *diagnostic-api*
config({opts}, {namespace}) *vim.diagnostic.config()*
Configure diagnostic options globally or for a specific diagnostic
namespace.
2021-10-17 07:18:35 -07:00
Configuration can be specified globally, per-namespace, or ephemerally
(i.e. only for a single call to |vim.diagnostic.set()| or
|vim.diagnostic.show()|). Ephemeral configuration has highest priority,
followed by namespace configuration, and finally global configuration.
2022-11-23 04:31:49 -07:00
For example, if a user enables virtual text globally with >lua
2021-10-17 07:18:35 -07:00
2021-10-19 10:45:51 -07:00
vim.diagnostic.config({ virtual_text = true })
2021-10-17 07:18:35 -07:00
<
2022-11-23 04:31:49 -07:00
and a diagnostic producer sets diagnostics with >lua
2021-10-17 07:18:35 -07:00
2021-10-19 10:45:51 -07:00
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
2021-10-17 07:18:35 -07:00
<
then virtual text will not be enabled for those diagnostics.
2022-08-11 05:25:48 -07:00
2023-07-06 13:47:27 -07:00
Note: ~
• Each of the configuration options below accepts one of the following:
2022-03-13 05:48:14 -07:00
• `false`: Disable this feature
• `true`: Enable this feature, use default settings.
• `table`: Enable this feature with overrides. Use an empty table to
2021-10-17 07:18:35 -07:00
use default values.
2022-03-13 05:48:14 -07:00
• `function`: Function with signature (namespace, bufnr) that returns
2021-09-06 19:21:18 -07:00
any of the above.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) When omitted or "nil", retrieve the current
2022-05-12 07:02:46 -07:00
configuration. Otherwise, a configuration table with the
2022-01-11 16:44:31 -07:00
following keys:
2021-09-06 19:21:18 -07:00
• underline: (default true) Use underline for
2021-09-17 09:50:25 -07:00
diagnostics. Options:
• severity: Only underline diagnostics matching the
given severity |diagnostic-severity|
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
• virtual_text: (default true) Use virtual text for
2021-09-17 09:50:25 -07:00
diagnostics. If multiple diagnostics are set for a
2021-09-06 19:21:18 -07:00
namespace, one prefix per diagnostic + the last
2021-09-17 09:50:25 -07:00
diagnostic message are shown. Options:
• severity: Only show virtual text for diagnostics
matching the given severity |diagnostic-severity|
2021-12-17 19:38:33 -07:00
• source: (boolean or string) Include the diagnostic
source in virtual text. Use "if_many" to only show
sources if there is more than one diagnostic source
in the buffer. Otherwise, any truthy value means to
always show the diagnostic source.
2021-09-06 19:21:18 -07:00
• spacing: (number) Amount of empty spaces inserted at
2021-10-17 07:18:35 -07:00
the beginning of the virtual text.
2023-04-17 04:53:34 -07:00
• prefix: (string or function) prepend diagnostic
message with prefix. If a function, it must have the
signature (diagnostic) -> string, where {diagnostic}
is of type |diagnostic-structure|. This can be used
to render diagnostic symbols or error codes.
2022-11-20 16:57:36 -07:00
• suffix: (string or function) Append diagnostic
message with suffix. If a function, it must have the
signature (diagnostic) -> string, where {diagnostic}
is of type |diagnostic-structure|. This can be used
to render an LSP diagnostic error code.
2021-09-22 12:20:15 -07:00
• format: (function) A function that takes a diagnostic
as input and returns a string. The return value is
2022-11-23 04:31:49 -07:00
the text used to display the diagnostic. Example: >lua
2022-08-11 05:25:48 -07:00
2022-11-23 04:31:49 -07:00
function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
2021-09-22 12:20:15 -07:00
end
<
2021-09-17 09:50:25 -07:00
2021-09-06 19:21:18 -07:00
• signs: (default true) Use signs for diagnostics.
2021-09-17 09:50:25 -07:00
Options:
• severity: Only show signs for diagnostics matching
the given severity |diagnostic-severity|
2021-10-01 18:07:55 -07:00
• priority: (number, default 10) Base priority to use
for signs. When {severity_sort} is used, the priority
of a sign is adjusted based on its severity.
Otherwise, all signs use the same priority.
2022-08-11 05:25:48 -07:00
2021-10-19 10:45:51 -07:00
• float: Options for floating windows. See
2021-11-15 08:55:31 -07:00
|vim.diagnostic.open_float()|.
2021-09-06 19:21:18 -07:00
• 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
2021-09-17 13:59:30 -07:00
virtual text are displayed. When true, higher
severities are displayed before lower severities (e.g.
ERROR is displayed before WARN). Options:
2021-09-17 09:50:25 -07:00
• reverse: (boolean) Reverse sort order
2023-03-04 06:06:20 -07:00
• {namespace} (integer|nil) Update the options for the given namespace.
2021-09-06 19:21:18 -07:00
When omitted, update the global diagnostic options.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
Disable diagnostics in the given buffer.
Parameters: ~
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, disable diagnostics in all buffers.
• {namespace} (integer|nil) Only disable diagnostics for the given
2021-09-06 19:21:18 -07:00
namespace.
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
Enable diagnostics in the given buffer.
Parameters: ~
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, enable diagnostics in all buffers.
• {namespace} (integer|nil) Only enable diagnostics for the given
2021-09-06 19:21:18 -07:00
namespace.
2021-09-19 15:13:23 -07:00
fromqflist({list}) *vim.diagnostic.fromqflist()*
Convert a list of quickfix items to a list of diagnostics.
Parameters: ~
2023-08-09 02:06:13 -07:00
• {list} table[] List of quickfix items from |getqflist()| or
2022-05-12 07:02:46 -07:00
|getloclist()|.
2021-09-19 15:13:23 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
Diagnostic [] array of |diagnostic-structure|
2021-09-19 15:13:23 -07:00
2021-09-06 19:21:18 -07:00
get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0
for current buffer or nil for all buffers.
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) A table with the following keys:
2021-09-06 19:21:18 -07:00
• namespace: (number) Limit diagnostics to the given
namespace.
• lnum: (number) Limit diagnostics to the given line number.
• severity: See |diagnostic-severity|.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Return: ~
2023-06-27 08:14:17 -07:00
Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present.
2021-09-06 19:21:18 -07:00
2021-10-29 18:47:34 -07:00
get_namespace({namespace}) *vim.diagnostic.get_namespace()*
Get namespace metadata.
Parameters: ~
2023-03-04 06:06:20 -07:00
• {namespace} (integer) Diagnostic namespace
2021-10-29 18:47:34 -07:00
Return: ~
2022-05-12 07:02:46 -07:00
(table) Namespace metadata
2021-10-29 18:47:34 -07:00
2021-10-05 10:48:48 -07:00
get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces.
Return: ~
2022-05-12 07:02:46 -07:00
(table) A list of active diagnostic namespaces |vim.diagnostic|.
2021-10-05 10:48:48 -07:00
2021-09-06 19:21:18 -07:00
get_next({opts}) *vim.diagnostic.get_next()*
Get the next diagnostic closest to the cursor position.
Parameters: ~
2022-11-21 14:02:18 -07:00
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
2021-09-06 19:21:18 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
Diagnostic|nil Next diagnostic
2021-09-06 19:21:18 -07:00
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current buffer.
Parameters: ~
2022-11-21 14:02:18 -07:00
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
2021-09-06 19:21:18 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
table|false Next diagnostic position as a (row, col) tuple or false if
no next diagnostic.
2021-09-06 19:21:18 -07:00
get_prev({opts}) *vim.diagnostic.get_prev()*
Get the previous diagnostic closest to the cursor position.
Parameters: ~
2022-11-21 14:02:18 -07:00
• {opts} nil|table See |vim.diagnostic.goto_next()|
2021-09-06 19:21:18 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
Diagnostic|nil Previous diagnostic
2021-09-06 19:21:18 -07:00
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current buffer.
Parameters: ~
2022-11-21 14:02:18 -07:00
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
2021-09-06 19:21:18 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
table|false Previous diagnostic position as a (row, col) tuple or
false if there is no prior diagnostic
2021-09-06 19:21:18 -07:00
goto_next({opts}) *vim.diagnostic.goto_next()*
Move to the next diagnostic.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Configuration table with the following keys:
2021-09-06 19:21:18 -07:00
• 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|.
2021-10-19 10:45:51 -07:00
• float: (boolean or table, default true) If "true", call
|vim.diagnostic.open_float()| after moving. If a table, pass
the table as the {opts} parameter to
|vim.diagnostic.open_float()|. Unless overridden, the float
2021-11-27 09:26:49 -07:00
will show diagnostics at the new cursor position (as if
"cursor" were passed to the "scope" option).
2021-09-06 19:21:18 -07:00
• win_id: (number, default 0) Window ID
goto_prev({opts}) *vim.diagnostic.goto_prev()*
Move to the previous diagnostic in the current buffer.
Parameters: ~
2022-10-28 16:13:27 -07:00
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
2021-09-06 19:21:18 -07:00
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: ~
2023-03-04 06:06:20 -07:00
• {namespace} (integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all
2022-11-21 14:02:18 -07:00
namespaces.
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, hide diagnostics in all buffers.
2021-09-06 19:21:18 -07:00
2023-01-12 09:57:39 -07:00
is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()*
Check whether diagnostics are disabled in a given buffer.
Parameters: ~
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
• {namespace} (integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are
2023-01-12 09:57:39 -07:00
disabled in {bufnr}. Otherwise, only checks if
diagnostics from {namespace} are disabled.
Return: ~
(boolean)
2021-09-19 15:13:23 -07:00
*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
2021-10-17 07:18:35 -07:00
<
2021-09-19 15:13:23 -07:00
2022-11-23 04:31:49 -07:00
This can be parsed into a diagnostic |diagnostic-structure| with: >lua
2021-09-19 15:13:23 -07:00
2022-11-23 04:31:49 -07:00
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 })
2021-09-19 15:13:23 -07:00
<
Parameters: ~
2022-10-05 05:15:55 -07:00
• {str} (string) String to parse diagnostics from.
• {pat} (string) Lua pattern with capture groups.
• {groups} (table) List of fields in a |diagnostic-structure| to
2021-09-19 15:13:23 -07:00
associate with captures from {pat}.
2022-10-05 05:15:55 -07:00
• {severity_map} (table) A table mapping the severity field from
2021-09-19 15:13:23 -07:00
{groups} with an item from |vim.diagnostic.severity|.
2022-10-05 05:15:55 -07:00
• {defaults} (table|nil) Table of default values for any fields not
2022-05-12 07:02:46 -07:00
listed in {groups}. When omitted, numeric values
2021-09-19 15:13:23 -07:00
default to 0 and "severity" defaults to ERROR.
2022-08-11 05:25:48 -07:00
2021-09-19 15:13:23 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to
match {str}.
2021-09-19 15:13:23 -07:00
2021-12-08 18:44:31 -07:00
open_float({opts}, {...}) *vim.diagnostic.open_float()*
2021-10-19 10:45:51 -07:00
Show diagnostics in a floating window.
2022-08-11 05:25:48 -07:00
2021-10-19 10:45:51 -07:00
Parameters: ~
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Configuration table with the same keys as
2021-12-08 18:44:31 -07:00
|vim.lsp.util.open_floating_preview()| in addition to the
following:
• bufnr: (number) Buffer number to show diagnostics from.
Defaults to the current buffer.
• namespace: (number) Limit diagnostics to the given namespace
• scope: (string, default "line") Show diagnostics from the
whole buffer ("buffer"), the current cursor line ("line"),
or the current cursor position ("cursor"). Shorthand
versions are also accepted ("c" for "cursor", "l" for
"line", "b" for "buffer").
• pos: (number or table) If {scope} is "line" or "cursor", use
this position rather than the cursor position. If a number,
interpreted as a line number; otherwise, a (row, col) tuple.
• severity_sort: (default false) Sort diagnostics by severity.
Overrides the setting from |vim.diagnostic.config()|.
• severity: See |diagnostic-severity|. Overrides the setting
from |vim.diagnostic.config()|.
• header: (string or table) String to use as the header for
the floating window. If a table, it is interpreted as a
[text, hl_group] tuple. Overrides the setting from
|vim.diagnostic.config()|.
2021-12-17 19:38:33 -07:00
• source: (boolean or string) Include the diagnostic source in
the message. Use "if_many" to only show sources if there is
more than one source of diagnostics in the buffer.
Otherwise, any truthy value means to always show the
diagnostic source. Overrides the setting from
2021-12-08 18:44:31 -07:00
|vim.diagnostic.config()|.
• format: (function) A function that takes a diagnostic as
input and returns a string. The return value is the text
used to display the diagnostic. Overrides the setting from
|vim.diagnostic.config()|.
• prefix: (function, string, or table) Prefix each diagnostic
in the floating window. If a function, it must have the
signature (diagnostic, i, total) -> (string, string), where
{i} is the index of the diagnostic being evaluated and
{total} is the total number of diagnostics displayed in the
window. The function should return a string which is
prepended to each diagnostic in the window as well as an
(optional) highlight group which will be used to highlight
the prefix. If {prefix} is a table, it is interpreted as a
[text, hl_group] tuple as in |nvim_echo()|; otherwise, if
{prefix} is a string, it is prepended to each diagnostic in
the window with no highlight. Overrides the setting from
|vim.diagnostic.config()|.
2022-11-20 13:09:35 -07:00
• suffix: Same as {prefix}, but appends the text to the
diagnostic instead of prepending it. Overrides the setting
from |vim.diagnostic.config()|.
2022-08-11 05:25:48 -07:00
2021-10-19 10:45:51 -07:00
Return: ~
2023-03-04 06:06:20 -07:00
integer|nil, integer|nil: ({float_bufnr}, {win_id})
2021-10-19 10:45:51 -07:00
2021-09-06 19:21:18 -07:00
reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
Remove all diagnostics from the given namespace.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
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()|.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2023-03-04 06:06:20 -07:00
• {namespace} (integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all
2022-11-21 14:02:18 -07:00
namespaces.
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Remove diagnostics for the given buffer.
2021-09-06 19:21:18 -07:00
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: ~
2023-03-04 06:06:20 -07:00
• {namespace} (integer) The diagnostic namespace
• {bufnr} (integer) Buffer number
2022-10-05 05:15:55 -07:00
• {diagnostics} (table) A list of diagnostic items
2021-09-06 19:21:18 -07:00
|diagnostic-structure|
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Display options to pass to
2021-09-06 19:21:18 -07:00
|vim.diagnostic.show()|
setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Configuration table with the following keys:
2021-09-06 19:21:18 -07:00
• 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.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Configuration table with the following keys:
2021-09-06 19:21:18 -07:00
• 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.
2022-08-11 05:25:48 -07:00
2021-09-06 19:21:18 -07:00
Parameters: ~
2023-03-04 06:06:20 -07:00
• {namespace} (integer|nil) Diagnostic namespace. When omitted, show diagnostics from all
2022-11-21 14:02:18 -07:00
namespaces.
2023-03-04 06:06:20 -07:00
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
2022-05-12 07:02:46 -07:00
When omitted, show diagnostics in all buffers.
2022-10-05 05:15:55 -07:00
• {diagnostics} (table|nil) The diagnostics to display. When omitted,
2022-05-12 07:02:46 -07:00
use the saved diagnostics for the given namespace and
2021-09-06 19:21:18 -07:00
buffer. This can be used to display a list of
diagnostics without saving them or to display only a
2021-11-09 14:33:01 -07:00
subset of diagnostics. May not be used when {namespace}
2021-11-16 08:47:49 -07:00
or {bufnr} is nil.
2022-10-05 05:15:55 -07:00
• {opts} (table|nil) Display options. See
2021-09-06 19:21:18 -07:00
|vim.diagnostic.config()|.
2021-09-19 15:13:23 -07:00
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: ~
2022-10-05 05:15:55 -07:00
• {diagnostics} (table) List of diagnostics |diagnostic-structure|.
2021-09-19 15:13:23 -07:00
Return: ~
2022-11-21 14:02:18 -07:00
table[] of quickfix list items |setqflist-what|
2021-09-19 15:13:23 -07:00
2021-09-06 19:21:18 -07:00
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: