kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 03:05:11 -07:00
Code Issues Packages Projects Releases Wiki Activity
4472c56d54
neovim/runtime/doc/diagnostic.txt

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

646 lines
28 KiB
Plaintext
Raw Normal View History

refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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*
A diagnostic is a Lua table with the following keys:
lnum: The starting line of the diagnostic
end_lnum: The final line of the diagnostic
col: The starting column of the diagnostic
end_col: The final column of the diagnostic
severity: The severity of the diagnostic |vim.diagnostic.severity|
message: The diagnostic text
feat(diagnostic): add option to include diagnostic source Add an option to virtual text display and floating window previews to include diagnostic source in the diagnostic message.
2021-09-18 14:00:32 -07:00
source: The source of the diagnostic
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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:
1. A single |vim.diagnostic.severity| value: >
vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
2. A table with a "min" or "max" key (or both): >
vim.diagnostic.get(0, { severity = {min=vim.diagnostic.severity.WARN})
The latter form allows users to specify a range of severities.
==============================================================================
HIGHLIGHTS *diagnostic-highlights*
All highlights defined for diagnostics begin with `Diagnostic` followed by
the type of highlight (e.g., `Sign`, `Underline`, etc.) and the severity (e.g.
`Error`, `Warn`, etc.)
Sign, underline and virtual text highlights (by default) are linked to their
corresponding default highlight.
For example, the default highlighting for |hl-DiagnosticSignError| is linked
to |hl-DiagnosticError|. To change the default (and therefore the linked
highlights), use the |:highlight| command: >
highlight DiagnosticError guifg="BrightRed"
<
*hl-DiagnosticError*
DiagnosticError
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)
*hl-DiagnosticWarn*
DiagnosticWarn
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)
*hl-DiagnosticInfo*
DiagnosticInfo
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)
*hl-DiagnosticHint*
DiagnosticHint
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)
*hl-DiagnosticVirtualTextError*
DiagnosticVirtualTextError
Used for "Error" diagnostic virtual text.
*hl-DiagnosticVirtualTextWarn*
DiagnosticVirtualTextWarn
Used for "Warn" diagnostic virtual text.
*hl-DiagnosticVirtualTextInfo*
DiagnosticVirtualTextInfo
Used for "Info" diagnostic virtual text.
*hl-DiagnosticVirtualTextHint*
DiagnosticVirtualTextHint
Used for "Hint" diagnostic virtual text.
*hl-DiagnosticUnderlineError*
DiagnosticUnderlineError
Used to underline "Error" diagnostics.
*hl-DiagnosticUnderlineWarn*
DiagnosticUnderlineWarn
Used to underline "Warn" diagnostics.
*hl-DiagnosticUnderlineInfo*
DiagnosticUnderlineInfo
Used to underline "Info" diagnostics.
*hl-DiagnosticUnderlineHint*
DiagnosticUnderlineHint
Used to underline "Hint" diagnostics.
*hl-DiagnosticFloatingError*
DiagnosticFloatingError
Used to color "Error" diagnostic messages in diagnostics float.
See |vim.diagnostic.show_line_diagnostics()|
*hl-DiagnosticFloatingWarn*
DiagnosticFloatingWarn
Used to color "Warn" diagnostic messages in diagnostics float.
*hl-DiagnosticFloatingInfo*
DiagnosticFloatingInfo
Used to color "Info" diagnostic messages in diagnostics float.
*hl-DiagnosticFloatingHint*
DiagnosticFloatingHint
Used to color "Hint" diagnostic messages in diagnostics float.
*hl-DiagnosticSignError*
DiagnosticSignError
Used for "Error" signs in sign column.
*hl-DiagnosticSignWarn*
DiagnosticSignWarn
Used for "Warn" signs in sign column.
*hl-DiagnosticSignInfo*
DiagnosticSignInfo
Used for "Info" signs in sign column.
*hl-DiagnosticSignHint*
DiagnosticSignHint
Used for "Hint" signs in sign column.
==============================================================================
SIGNS *diagnostic-signs*
Signs are defined for each diagnostic severity. The default text for each sign
is the first letter of the severity name (for example, "E" for ERROR). Signs
can be customized using the following: >
sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl=
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
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=
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl=
refactor(diagnostic): use sign priority for severity_sort #15785 Rather than relying on the order in which signs are placed to dictate the order in which they are displayed, explicitly set the priority of the sign according to the severity of the diagnostic and the value of severity_sort. If severity_sort is false or unset then all signs use the same priority.
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).
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
==============================================================================
EVENTS *diagnostic-events*
*DiagnosticsChanged*
DiagnosticsChanged After diagnostics have changed.
Example: >
autocmd User DiagnosticsChanged lua vim.diagnostic.setqflist({open = false })
<
docs(diagnostic): add blurb on how to replace builtin handlers
2021-09-25 08:52:20 -07:00
==============================================================================
CUSTOMIZATION *diagnostic-config*
If you need more customization over the way diagnostics are displayed than the
built-in configuration options provide, you can override the display handler
explicitly. For example, use the following to only show a sign for the highest
severity diagnostic on a given line: >
-- Disable the default signs handler
vim.diagnostic.config({signs = false})
-- Create a namespace. This won't be used to add any diagnostics,
-- only to display them.
local ns = vim.api.nvim_create_namespace("my_namespace")
-- Create a reference to the original function
local orig_show = vim.diagnostic.show
local function set_signs(bufnr)
-- Get all diagnostics from the current buffer
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
-- Show the filtered diagnostics using the custom namespace. Use the
-- reference to the original function to avoid a loop.
local filtered_diagnostics = vim.tbl_values(max_severity_per_line)
orig_show(ns, bufnr, filtered_diagnostics, {
virtual_text=false,
underline=false,
signs=true
})
end
function vim.diagnostic.show(namespace, bufnr, ...)
orig_show(namespace, bufnr, ...)
set_signs(bufnr)
end
<
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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.
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
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.
For example, if a user enables virtual text globally with >
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
2021-10-19 10:45:51 -07:00
vim.diagnostic.config({virtual_text = true})
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
2021-10-17 07:18:35 -07:00
<
and a diagnostic producer sets diagnostics with >
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
2021-10-19 10:45:51 -07:00
vim.diagnostic.set(ns, 0, diagnostics, {virtual_text = false})
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
2021-10-17 07:18:35 -07:00
<
then virtual text will not be enabled for those diagnostics.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
Note:
Each of the configuration options below accepts one of the
following:
• `false` : Disable this feature
• `true` : Enable this feature, use default settings.
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
2021-10-17 07:18:35 -07:00
• `table` : Enable this feature with overrides. Use an
empty table to use default values.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
• `function` : Function with signature (namespace, bufnr)
that returns any of the above.
Parameters: ~
{opts} table Configuration table with the following
keys:
• underline: (default true) Use underline for
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
diagnostics. Options:
• severity: Only underline diagnostics
matching the given severity
|diagnostic-severity|
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
• virtual_text: (default true) Use virtual
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
text for diagnostics. Options:
• severity: Only show virtual text for
diagnostics matching the given severity
|diagnostic-severity|
feat(diagnostic): add option to include diagnostic source Add an option to virtual text display and floating window previews to include diagnostic source in the diagnostic message.
2021-09-18 14:00:32 -07:00
• source: (string) Include the diagnostic
source in virtual text. One of "always"
or "if_many".
feat(diagnostic): allow customized diagnostic messages (#15742) Provide a 'format' option for virtual text and floating window previews that allows the displayed text of a diagnostic to be customized.
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 the text used
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
2021-10-19 10:45:51 -07:00
to display the diagnostic. Example: >
feat(diagnostic): allow customized diagnostic messages (#15742) Provide a 'format' option for virtual text and floating window previews that allows the displayed text of a diagnostic to be customized.
2021-09-22 12:20:15 -07:00
function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
end
<
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
• signs: (default true) Use signs for
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
diagnostics. Options:
• severity: Only show signs for diagnostics
matching the given severity
|diagnostic-severity|
docs(diagnostics): add "priority" option to signs table (#15860) This feature was added in #15785, but the docs for vim.diagnostic.config() weren't updated.
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.
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
2021-10-19 10:45:51 -07:00
• float: Options for floating windows:
• severity: See |diagnostic-severity|.
• show_header: (boolean, default true) Show
"Diagnostics:" header
• source: (string) Include the diagnostic
source in the message. One of "always" or
"if_many".
• 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.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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 virtual text are
fix(diagnostic): change default severity_sort order When severity_sort is true, higher severities should be displayed before lower severities (e.g. ERROR is displayed over WARN). Also improved the test case for this.
2021-09-17 13:59:30 -07:00
displayed. When true, higher severities are
displayed before lower severities (e.g.
ERROR is displayed before WARN). Options:
fix(diagnostic): support severity_sort
2021-09-17 09:50:25 -07:00
• reverse: (boolean) Reverse sort order
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
{namespace} number|nil Update the options for the given
namespace. When omitted, update the global
diagnostic options.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
Disable diagnostics in the given buffer.
Parameters: ~
{bufnr} number|nil Buffer number. Defaults to the
current buffer.
{namespace} number|nil Only disable diagnostics for the
given namespace.
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
Enable diagnostics in the given buffer.
Parameters: ~
{bufnr} number|nil Buffer number. Defaults to the
current buffer.
{namespace} number|nil Only enable diagnostics for the
given namespace.
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
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: ~
{list} table A list of quickfix items from |getqflist()|
or |getloclist()|.
Return: ~
array of diagnostics |diagnostic-structure|
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics.
Parameters: ~
docs(diagnostics): fix typos
2021-09-17 07:57:51 -07:00
{bufnr} number|nil Buffer number to get diagnostics from.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
Use 0 for current buffer or nil for all buffers.
{opts} table|nil A table with the following keys:
• namespace: (number) Limit diagnostics to the
given namespace.
• lnum: (number) Limit diagnostics to the given
line number.
• severity: See |diagnostic-severity|.
Return: ~
table A list of diagnostic items |diagnostic-structure|.
docs: regenerate #15545
2021-10-05 10:48:48 -07:00
get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces.
Return: ~
table A list of active diagnostic namespaces
|vim.diagnostic|.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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: ~
{opts} table See |vim.diagnostic.goto_next()|
Return: ~
table Next diagnostic
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current
buffer.
Parameters: ~
{opts} table See |vim.diagnostic.goto_next()|
Return: ~
table Next diagnostic position as a (row, col) tuple.
get_prev({opts}) *vim.diagnostic.get_prev()*
Get the previous diagnostic closest to the cursor position.
Parameters: ~
{opts} table See |vim.diagnostic.goto_next()|
Return: ~
table Previous diagnostic
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current
buffer.
Parameters: ~
{opts} table See |vim.diagnostic.goto_next()|
Return: ~
table Previous diagnostic position as a (row, col) tuple.
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|.
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
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()|.
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
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: ~
{opts} table See |vim.diagnostic.goto_next()|
hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
Hide currently displayed diagnostics.
This only clears the decorations displayed in the buffer.
Diagnostics can be redisplayed with |vim.diagnostic.show()|.
To completely remove diagnostics, use
|vim.diagnostic.reset()|.
To hide diagnostics and prevent them from re-displaying, use
|vim.diagnostic.disable()|.
Parameters: ~
{namespace} number The diagnostic namespace
{bufnr} number|nil Buffer number. Defaults to the
current buffer.
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
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
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
2021-10-17 07:18:35 -07:00
<
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
2021-09-19 15:13:23 -07:00
fix(diagnostic): do not override existing config settings #16043 When using `true` as the value of a configuration option, the option is configured to use default values. For example, if a user configures virtual text to include the source globally (using vim.diagnostic.config) and a specific namespace or producer configures virtual text with `virt_text = true`, the user's global configuration is overriden. Instead, interpret a value of `true` to mean "use existing settings if defined, otherwise use defaults".
2021-10-17 07:18:35 -07:00
This can be parsed into a diagnostic |diagnostic-structure|
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
2021-09-19 15:13:23 -07:00
with: >
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = {"severity", "lnum", "col", "message"}
vim.diagnostic.match(s, pattern, groups, {WARNING = vim.diagnostic.WARN})
<
Parameters: ~
{str} string String to parse diagnostics from.
{pat} string Lua pattern with capture groups.
{groups} table List of fields in a
|diagnostic-structure| to associate with
captures from {pat}.
{severity_map} table A table mapping the severity field
from {groups} with an item from
|vim.diagnostic.severity|.
{defaults} table|nil Table of default values for any
fields not listed in {groups}. When
omitted, numeric values default to 0 and
"severity" defaults to ERROR.
Return: ~
diagnostic |diagnostic-structure| or `nil` if {pat} fails
to match {str}.
refactor(diagnostic)!: replace 'show_*' functions with 'open_float' (#16057) 'show_line_diagnostics()' and 'show_position_diagnostics()' are almost identical; they differ only in the fact that the latter also accepts a column to form a full position, rather than just a line. This is not enough to justify two separate interfaces for this common functionality. Renaming this to simply 'show_diagnostics()' is one step forward, but that is also not a good name as the '_diagnostics()' suffix is redundant. However, we cannot name it simply 'show()' since that function already exists with entirely different semantics. Instead, combine these two into a single 'open_float()' function that handles all of the cases of showing diagnostics in a floating window. Also add a "float" key to 'vim.diagnostic.config()' to provide global values of configuration options that can be overridden ephemerally. This makes the float API consistent with the rest of the diagnostic API. BREAKING CHANGE
2021-10-19 10:45:51 -07:00
open_float({bufnr}, {opts}) *vim.diagnostic.open_float()*
Show diagnostics in a floating window.
Parameters: ~
{bufnr} number|nil Buffer number. Defaults to the current
buffer.
{opts} table|nil Configuration table with the same keys
as |vim.lsp.util.open_floating_preview()| in
addition to the following:
• namespace: (number) Limit diagnostics to the
given namespace
• scope: (string, default "buffer") Show
diagnostics from the whole buffer ("buffer"),
the current cursor line ("line"), or the
current cursor position ("cursor").
• 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()|.
• show_header: (boolean, default true) Show
"Diagnostics:" header. Overrides the setting
from |vim.diagnostic.config()|.
• source: (string) Include the diagnostic source
in the message. One of "always" or "if_many".
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()|.
Return: ~
tuple ({float_bufnr}, {win_id})
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
Remove all diagnostics from the given namespace.
Unlike |vim.diagnostic.hide()|, this function removes all
saved diagnostics. They cannot be redisplayed using
|vim.diagnostic.show()|. To simply remove diagnostic
decorations in a way that they can be re-displayed, use
|vim.diagnostic.hide()|.
Parameters: ~
{namespace} number
{bufnr} number|nil Remove diagnostics for the given
buffer. When omitted, diagnostics are removed
for all buffers.
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
Set diagnostics for the given namespace and buffer.
Parameters: ~
{namespace} number The diagnostic namespace
{bufnr} number Buffer number
{diagnostics} table A list of diagnostic items
|diagnostic-structure|
{opts} table|nil Display options to pass to
|vim.diagnostic.show()|
setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list.
Parameters: ~
{opts} table|nil Configuration table with the following
keys:
• namespace: (number) Only add diagnostics from
the given namespace.
• winnr: (number, default 0) Window number to set
location list for.
• open: (boolean, default true) Open the location
list after setting.
• title: (string) Title of the location list.
Defaults to "Diagnostics".
• severity: See |diagnostic-severity|.
setqflist({opts}) *vim.diagnostic.setqflist()*
Add all diagnostics to the quickfix list.
Parameters: ~
{opts} table|nil Configuration table with the following
keys:
• namespace: (number) Only add diagnostics from
the given namespace.
• open: (boolean, default true) Open quickfix list
after setting.
• title: (string) Title of quickfix list. Defaults
to "Diagnostics".
• severity: See |diagnostic-severity|.
*vim.diagnostic.show()*
show({namespace}, {bufnr}, {diagnostics}, {opts})
Display diagnostics for the given namespace and buffer.
Parameters: ~
{namespace} number Diagnostic namespace
{bufnr} number|nil Buffer number. Defaults to the
current buffer.
{diagnostics} table|nil The diagnostics to display. When
omitted, use the saved diagnostics for the
given namespace and buffer. This can be
used to display a list of diagnostics
without saving them or to display only a
subset of diagnostics.
{opts} table|nil Display options. See
|vim.diagnostic.config()|.
feat(diagnostic): match(), tolist(), fromlist() #15704 * feat(diagnostic): add vim.diagnostic.match() Provide vim.diagnostic.match() to generate a diagnostic from a string and a Lua pattern. * feat(diagnostic): add tolist() and fromlist()
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: ~
{diagnostics} table List of diagnostics
|diagnostic-structure|.
Return: ~
array of quickfix list items |setqflist-what|
refactor: move vim.lsp.diagnostic to vim.diagnostic This generalizes diagnostic handling outside of just the scope of LSP. LSP clients are now a specific case of a diagnostic producer, but the diagnostic subsystem is decoupled from the LSP subsystem (or will be, eventually). More discussion at [1]. [1]: https://github.com/neovim/neovim/pull/15585
2021-09-06 19:21:18 -07:00
vim:tw=78:ts=8:ft=help:norl:
Reference in New Issue Copy Permalink