mirror of
https://github.com/neovim/neovim.git
synced 2024-12-19 18:55:14 -07:00
827 lines
36 KiB
Plaintext
827 lines
36 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?`) 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?`) Update the options for the given namespace.
|
|
When omitted, update the global diagnostic options.
|
|
|
|
Return: ~
|
|
(`table?`) table of current diagnostic config if `opts` is omitted.
|
|
|
|
count({bufnr}, {opts}) *vim.diagnostic.count()*
|
|
Get current diagnostics count.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for
|
|
current buffer or nil for all buffers.
|
|
• {opts} (`table?`) 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 table with actually present severity values as keys (see
|
|
|diagnostic-severity|) and integer counts as values.
|
|
|
|
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
|
|
Disable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
|
|
omitted, disable diagnostics in all buffers.
|
|
• {namespace} (`integer?`) Only disable diagnostics for the given
|
|
namespace.
|
|
|
|
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
|
|
Enable diagnostics in the given buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
|
|
omitted, enable diagnostics in all buffers.
|
|
• {namespace} (`integer?`) 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: ~
|
|
(`vim.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?`) Buffer number to get diagnostics from. Use 0 for
|
|
current buffer or nil for all buffers.
|
|
• {opts} (`table?`) 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: ~
|
|
(`vim.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<integer,vim.diagnostic.NS>`) 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?`) See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
(`vim.Diagnostic?`) 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|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} (`table?`) See |vim.diagnostic.goto_next()|
|
|
|
|
Return: ~
|
|
(`vim.Diagnostic?`) 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|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?`) Configuration table with the following keys:
|
|
• namespace: (integer) 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?`) 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?`) Diagnostic namespace. When omitted, hide
|
|
diagnostics from all namespaces.
|
|
• {bufnr} (`integer?`) 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?`) Buffer number, or 0 for current buffer.
|
|
• {namespace} (`integer?`) 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} (`string[]`) 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?`) Table of default values for any fields not
|
|
listed in {groups}. When omitted, numeric values
|
|
default to 0 and "severity" defaults to ERROR.
|
|
|
|
Return: ~
|
|
(`vim.Diagnostic?`) |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?`) 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?, integer?`) ({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?`) Diagnostic namespace. When omitted, remove
|
|
diagnostics from all namespaces.
|
|
• {bufnr} (`integer?`) 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} (`vim.Diagnostic[]`) A list of diagnostic items
|
|
|diagnostic-structure|
|
|
• {opts} (`table?`) Display options to pass to
|
|
|vim.diagnostic.show()|
|
|
|
|
setloclist({opts}) *vim.diagnostic.setloclist()*
|
|
Add buffer diagnostics to the location list.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) 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?`) 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?`) Diagnostic namespace. When omitted, show
|
|
diagnostics from all namespaces.
|
|
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer.
|
|
When omitted, show diagnostics in all buffers.
|
|
• {diagnostics} (`vim.Diagnostic[]?`) 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?`) 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} (`vim.Diagnostic[]`) 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:
|