mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
3a4aa3fc58
Diagnostic signs should now be configured with vim.diagnostic.config(), but "legacy" sign definitions should go through the standard deprecation process to minimize the impact from breaking changes.
806 lines
35 KiB
Plaintext
806 lines
35 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. Required keys are
|
|
indicated with (+):
|
|
|
|
bufnr: Buffer number
|
|
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
|
|
source: The source of the diagnostic
|
|
code: The diagnostic code
|
|
user_data: Arbitrary data plugins or users can add
|
|
|
|
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 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).
|
|
|
|
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
|
|
with |vim.notify()|: >lua
|
|
|
|
-- 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
|
|
}
|
|
})
|
|
<
|
|
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
|
|
show a sign for the highest severity diagnostic on a given line: >lua
|
|
|
|
-- 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,
|
|
}
|
|
<
|
|
|
|
==============================================================================
|
|
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
|
|
highlights), use the |:highlight| command: >vim
|
|
|
|
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.
|
|
|
|
==============================================================================
|
|
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 with |vim.diagnostic.config()|. Example: >lua
|
|
|
|
-- Highlight entire line for errors
|
|
-- Highlight the line number for warnings
|
|
vim.diagnostic.config({
|
|
signs = {
|
|
text = {
|
|
[vim.diagnostic.severity.ERROR] = '',
|
|
[vim.diagnostic.severity.WARN] = '',
|
|
},
|
|
linehl = {
|
|
[vim.diagnostic.severity.ERROR] = 'ErrorMsg',
|
|
},
|
|
numhl = {
|
|
[vim.diagnostic.severity.WARN] = 'WarningMsg',
|
|
},
|
|
},
|
|
})
|
|
|
|
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).
|
|
|
|
==============================================================================
|
|
EVENTS *diagnostic-events*
|
|
|
|
*DiagnosticChanged*
|
|
DiagnosticChanged After diagnostics have changed. When used from Lua,
|
|
the new diagnostics are passed to the autocmd
|
|
callback in the "data" table.
|
|
|
|
Example: >lua
|
|
|
|
vim.api.nvim_create_autocmd('DiagnosticChanged', {
|
|
callback = function(args)
|
|
local diagnostics = args.data.diagnostics
|
|
vim.print(diagnostics)
|
|
end,
|
|
})
|
|
<
|
|
==============================================================================
|
|
Lua module: vim.diagnostic *diagnostic-api*
|
|
|
|
config({opts}, {namespace}) *vim.diagnostic.config()*
|
|
Configure diagnostic options globally or for a specific diagnostic
|
|
namespace.
|
|
|
|
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.
|
|
|
|
For example, if a user enables virtual text globally with >lua
|
|
vim.diagnostic.config({ virtual_text = true })
|
|
<
|
|
|
|
and a diagnostic producer sets diagnostics with >lua
|
|
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
|
|
<
|
|
|
|
then virtual text will not be enabled for those diagnostics.
|
|
|
|
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. Use an empty table to
|
|
use default values.
|
|
• `function`: Function with signature (namespace, bufnr) that returns
|
|
any of the above.
|
|
|
|
Parameters: ~
|
|
• {opts} (table|nil) When omitted or "nil", retrieve the current
|
|
configuration. Otherwise, a 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. If multiple diagnostics are set for a
|
|
namespace, one prefix per diagnostic + the last
|
|
diagnostic message are shown. In addition to the
|
|
options listed below, the "virt_text" options of
|
|
|nvim_buf_set_extmark()| may also be used here (e.g.
|
|
"virt_text_pos" and "hl_mode"). Options:
|
|
• severity: Only show virtual text for diagnostics
|
|
matching the given severity |diagnostic-severity|
|
|
• 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.
|
|
• spacing: (number) Amount of empty spaces inserted at
|
|
the beginning of the virtual text.
|
|
• prefix: (string or function) prepend diagnostic
|
|
message with prefix. If a function, it must have the
|
|
signature (diagnostic, i, total) -> string, where
|
|
{diagnostic} is of type |diagnostic-structure|, {i}
|
|
is the index of the diagnostic being evaluated, and
|
|
{total} is the total number of diagnostics for the
|
|
line. This can be used to render diagnostic symbols
|
|
or error codes.
|
|
• 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.
|
|
• 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. Example: >lua
|
|
|
|
function(diagnostic)
|
|
if diagnostic.severity == vim.diagnostic.severity.ERROR then
|
|
return string.format("E: %s", diagnostic.message)
|
|
end
|
|
return diagnostic.message
|
|
end
|
|
<
|
|
|
|
• signs: (default true) Use signs for diagnostics
|
|
|diagnostic-signs|. Options:
|
|
• severity: Only show signs for diagnostics matching
|
|
the given severity |diagnostic-severity|
|
|
• 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.
|
|
• text: (table) A table mapping |diagnostic-severity|
|
|
to the sign text to display in the sign column. The
|
|
default is to use "E", "W", "I", and "H" for errors,
|
|
warnings, information, and hints, respectively.
|
|
Example: >lua
|
|
|
|
vim.diagnostic.config({
|
|
signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
|
|
})
|
|
<
|
|
• numhl: (table) A table mapping |diagnostic-severity|
|
|
to the highlight group used for the line number where
|
|
the sign is placed.
|
|
• linehl: (table) A table mapping |diagnostic-severity|
|
|
to the highlight group used for the whole line the
|
|
sign is placed in.
|
|
|
|
• float: Options for floating windows. See
|
|
|vim.diagnostic.open_float()|.
|
|
• 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} (integer|nil) Update the options for the given namespace.
|
|
When omitted, update the global diagnostic options.
|
|
|
|
Return: ~
|
|
(table|nil) table of current diagnostic config if `opts` is omitted.
|
|
|
|
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
|
|
Disable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
• {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.
|
|
|
|
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
|
|
Enable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
• {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.
|
|
|
|
fromqflist({list}) *vim.diagnostic.fromqflist()*
|
|
Convert a list of quickfix items to a list of diagnostics.
|
|
|
|
Parameters: ~
|
|
• {list} table[] List of quickfix items from |getqflist()| or
|
|
|getloclist()|.
|
|
|
|
Return: ~
|
|
Diagnostic [] array of |diagnostic-structure|
|
|
|
|
get({bufnr}, {opts}) *vim.diagnostic.get()*
|
|
Get current diagnostics.
|
|
|
|
Modifying diagnostics in the returned table has no effect. To set
|
|
diagnostics in a buffer, use |vim.diagnostic.set()|.
|
|
|
|
Parameters: ~
|
|
• {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:
|
|
• namespace: (number) Limit diagnostics to the given
|
|
namespace.
|
|
• lnum: (number) Limit diagnostics to the given line number.
|
|
• severity: See |diagnostic-severity|.
|
|
|
|
Return: ~
|
|
Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present.
|
|
|
|
get_namespace({namespace}) *vim.diagnostic.get_namespace()*
|
|
Get namespace metadata.
|
|
|
|
Parameters: ~
|
|
• {namespace} (integer) Diagnostic namespace
|
|
|
|
Return: ~
|
|
(table) Namespace metadata
|
|
|
|
get_namespaces() *vim.diagnostic.get_namespaces()*
|
|
Get current diagnostic namespaces.
|
|
|
|
Return: ~
|
|
(table) A list of active diagnostic namespaces |vim.diagnostic|.
|
|
|
|
get_next({opts}) *vim.diagnostic.get_next()*
|
|
Get the next diagnostic closest to the cursor position.
|
|
|
|
Parameters: ~
|
|
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
Diagnostic|nil 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|nil) See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table|false Next diagnostic position as a (row, col) tuple or false if
|
|
no next diagnostic.
|
|
|
|
get_prev({opts}) *vim.diagnostic.get_prev()*
|
|
Get the previous diagnostic closest to the cursor position.
|
|
|
|
Parameters: ~
|
|
• {opts} nil|table See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
Diagnostic|nil 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|nil) See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
table|false Previous diagnostic position as a (row, col) tuple or
|
|
false if there is no prior diagnostic
|
|
|
|
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|.
|
|
• 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
|
|
will show diagnostics at the new cursor position (as if
|
|
"cursor" were passed to the "scope" option).
|
|
• 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|nil) 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} (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.
|
|
|
|
is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()*
|
|
Check whether diagnostics are disabled in a given buffer.
|
|
|
|
Parameters: ~
|
|
• {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.
|
|
|
|
Return: ~
|
|
(boolean)
|
|
|
|
*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: >lua
|
|
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|nil: |diagnostic-structure| or `nil` if {pat} fails to
|
|
match {str}.
|
|
|
|
open_float({opts}, {...}) *vim.diagnostic.open_float()*
|
|
Show diagnostics in a floating window.
|
|
|
|
Parameters: ~
|
|
• {opts} (table|nil) Configuration table with the same keys as
|
|
|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()|.
|
|
• 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
|
|
|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()|.
|
|
• suffix: Same as {prefix}, but appends the text to the
|
|
diagnostic instead of prepending it. Overrides the setting
|
|
from |vim.diagnostic.config()|.
|
|
|
|
Return: ~
|
|
integer|nil, integer|nil: ({float_bufnr}, {win_id})
|
|
|
|
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} (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.
|
|
|
|
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
|
|
Set diagnostics for the given namespace and buffer.
|
|
|
|
Parameters: ~
|
|
• {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()|
|
|
|
|
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} (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()|.
|
|
|
|
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: ~
|
|
table[] of quickfix list items |setqflist-what|
|
|
|
|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
|