Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
{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. Required keys are
indicated with (+):vim.diagnostic.severity
diagnostic-severity
The "severity" key in a diagnostic is one of the values defined in
vim.diagnostic.severity
: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 } })
vim.diagnostic.get(0, { severity = {
vim.diagnostic.severity.WARN,
vim.diagnostic.severity.INFO,
} })
function(namespace, bufnr, diagnostics, opts)
function(namespace, bufnr)
vim.diagnostic.handlers
(see
diagnostic-handlers-example).{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).diagnostic-handlers-example
The example below creates a new handler that notifies the user of diagnostics
with vim.notify():-- 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
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,
}
-- Users can configure the handler
vim.diagnostic.config({
["my/notify"] = {
log_level = vim.log.levels.INFO
}
})
-- 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")
-- Get a reference to the original signs handler
local orig_signs_handler = vim.diagnostic.handlers.signs
-- 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)
-- 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
-- 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,
}
Diagnostic
followed by
the type of highlight (e.g., Sign
, Underline
, etc.) and the severity (e.g.
Error
, Warn
, etc.)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-DiagnosticOk
DiagnosticOk
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-DiagnosticVirtualTextOk
DiagnosticVirtualTextOk
Used for "Ok" 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-DiagnosticUnderlineOk
DiagnosticUnderlineOk
Used to underline "Ok" diagnostics.hl-DiagnosticFloatingError
DiagnosticFloatingError
Used to color "Error" diagnostic messages in diagnostics float.
See vim.diagnostic.open_float()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-DiagnosticFloatingOk
DiagnosticFloatingOk
Used to color "Ok" 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.hl-DiagnosticSignOk
DiagnosticSignOk
Used for "Ok" signs in sign column.hl-DiagnosticDeprecated
DiagnosticDeprecated
Used for deprecated or obsolete code.hl-DiagnosticUnnecessary
DiagnosticUnnecessary
Used for unnecessary or unused code.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=
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).DiagnosticChanged
DiagnosticChanged After diagnostics have changed. When used from Lua,
the new diagnostics are passed to the autocmd
callback in the "data" table.vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
local diagnostics = args.data.diagnostics
vim.print(diagnostics)
end,
})
{opts}
, {namespace}
) vim.diagnostic.config()
Configure diagnostic options globally or for a specific diagnostic
namespace.vim.diagnostic.config({ virtual_text = true })
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
false
: Disable this feature
true
: Enable this feature, use default settings.
table
: Enable this feature with overrides. Use an empty table to
use default values.
function
: Function with signature (namespace, bufnr) that returns
any of the above.
{opts}
(table|nil) When omitted or "nil", retrieve the current
configuration. Otherwise, a configuration table with the
following keys:
{diagnostic}
is of type diagnostic-structure. This can be used
to render diagnostic symbols or error codes.
{diagnostic}
is of type diagnostic-structure. This can be used
to render an LSP diagnostic error code.
function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
end
{severity_sort}
is used, the priority
of a sign is adjusted based on its severity.
Otherwise, all signs use the same priority.
{namespace}
(integer|nil) Update the options for the given namespace.
When omitted, update the global diagnostic options.
{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
namespace.
{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
namespace.
{list}
) vim.diagnostic.fromqflist()
Convert a list of quickfix items to a list of diagnostics.{bufnr}
(integer|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:
bufnr
, end_lnum
, end_col
, and severity
are guaranteed to be present.{namespace}
) vim.diagnostic.get_namespace()
Get namespace metadata.{namespace}
(integer) Diagnostic namespace
vim.diagnostic.get_namespaces()
Get current diagnostic namespaces.{opts}
) vim.diagnostic.get_next()
Get the next diagnostic closest to the cursor position.{opts}
(table|nil) See vim.diagnostic.goto_next()
{opts}
) vim.diagnostic.get_next_pos()
Return the position of the next diagnostic in the current buffer.{opts}
(table|nil) See vim.diagnostic.goto_next()
{opts}
) vim.diagnostic.get_prev()
Get the previous diagnostic closest to the cursor position.{opts}
nil|table See vim.diagnostic.goto_next()
{opts}
) vim.diagnostic.get_prev_pos()
Return the position of the previous diagnostic in the current buffer.{opts}
(table|nil) See vim.diagnostic.goto_next()
{opts}
) vim.diagnostic.goto_next()
Move to the next diagnostic.{opts}
(table|nil) Configuration table with the following keys:
{opts}
parameter to
vim.diagnostic.open_float(). Unless overridden, the float
will show diagnostics at the new cursor position (as if
"cursor" were passed to the "scope" option).
{opts}
) vim.diagnostic.goto_prev()
Move to the previous diagnostic in the current buffer.{opts}
(table|nil) See vim.diagnostic.goto_next()
{namespace}
(integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all
namespaces.
{bufnr}
(integer|nil) Buffer number, or 0 for current buffer.
When omitted, hide diagnostics in all buffers.
{bufnr}
, {namespace}
) vim.diagnostic.is_disabled()
Check whether diagnostics are disabled in a given buffer.{bufnr}
(integer|nil) Buffer number, or 0 for current buffer.
{namespace}
(integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are
disabled in {bufnr}
. Otherwise, only checks if
diagnostics from {namespace}
are disabled.
vim.diagnostic.match()
match({str}
, {pat}
, {groups}
, {severity_map}
, {defaults}
)
Parse a diagnostic from a string.WARNING filename:27:3: Variable 'foo' does not exist
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 })
{str}
(string) String to parse diagnostics from.
{pat}
(string) Lua pattern with capture groups.
{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.
{opts}
(table|nil) Configuration table with the same keys as
vim.lsp.util.open_floating_preview() in addition to the
following:
{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.
{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().
{prefix}
, but appends the text to the
diagnostic instead of prepending it. Overrides the setting
from vim.diagnostic.config().
{float_bufnr}
, {win_id}
){namespace}
(integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all
namespaces.
{bufnr}
(integer|nil) Remove diagnostics for the given buffer.
When omitted, diagnostics are removed for all buffers.
{namespace}
, {bufnr}
, {diagnostics}
, {opts}
) vim.diagnostic.set()
Set diagnostics for the given namespace and buffer.{namespace}
(integer) The diagnostic namespace
{bufnr}
(integer) Buffer number
{diagnostics}
(table) A list of diagnostic items
diagnostic-structure
{opts}
(table|nil) Display options to pass to
vim.diagnostic.show()
{opts}
) vim.diagnostic.setloclist()
Add buffer diagnostics to the location list.{opts}
(table|nil) Configuration table with the following keys:
{opts}
) vim.diagnostic.setqflist()
Add all diagnostics to the quickfix list.{opts}
(table|nil) Configuration table with the following keys:
vim.diagnostic.show()
show({namespace}
, {bufnr}
, {diagnostics}
, {opts}
)
Display diagnostics for the given namespace and buffer.{namespace}
(integer|nil) Diagnostic namespace. When omitted, show diagnostics from all
namespaces.
{bufnr}
(integer|nil) Buffer number, or 0 for current buffer.
When omitted, show diagnostics in all buffers.
{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. May not be used when {namespace}
or {bufnr}
is nil.
{opts}
(table|nil) Display options. See
vim.diagnostic.config().
{diagnostics}
) vim.diagnostic.toqflist()
Convert a list of diagnostics to a list of quickfix items that can be
passed to setqflist() or setloclist().{diagnostics}
(table) List of diagnostics diagnostic-structure.