diff options
Diffstat (limited to 'runtime/doc/diagnostic.txt')
| -rw-r--r-- | runtime/doc/diagnostic.txt | 125 |
1 files changed, 84 insertions, 41 deletions
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 828093ddd4..7066a3739a 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -68,11 +68,11 @@ The "severity" key in a diagnostic is one of the values defined in 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: > +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): > +2. A table with a "min" or "max" key (or both): >lua vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } }) @@ -107,7 +107,7 @@ Nvim provides these handlers by default: "virtual_text", "signs", and *diagnostic-handlers-example* The example below creates a new handler that notifies the user of diagnostics -with |vim.notify()|: > +with |vim.notify()|: >lua -- It's good practice to namespace custom handlers to avoid collisions vim.diagnostic.handlers["my/notify"] = { @@ -135,7 +135,7 @@ 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: > +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 @@ -185,7 +185,7 @@ 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: > +highlights), use the |:highlight| command: >vim highlight DiagnosticError guifg="BrightRed" < @@ -209,6 +209,11 @@ 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. @@ -225,6 +230,10 @@ DiagnosticVirtualTextInfo DiagnosticVirtualTextHint Used for "Hint" diagnostic virtual text. + *hl-DiagnosticVirtualTextOk* +DiagnosticVirtualTextOk + Used for "Ok" diagnostic virtual text. + *hl-DiagnosticUnderlineError* DiagnosticUnderlineError Used to underline "Error" diagnostics. @@ -241,6 +250,10 @@ DiagnosticUnderlineInfo 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. @@ -258,6 +271,10 @@ DiagnosticFloatingInfo 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. @@ -274,12 +291,16 @@ DiagnosticSignInfo DiagnosticSignHint Used for "Hint" signs in sign column. + *hl-DiagnosticSignOk* +DiagnosticSignOk + Used for "Ok" 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: > +can be customized using the following: >vim sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl= sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl= @@ -299,7 +320,7 @@ DiagnosticChanged After diagnostics have changed. When used from Lua, the new diagnostics are passed to the autocmd callback in the "data" table. -Example: > +Example: >lua vim.api.nvim_create_autocmd('DiagnosticChanged', { callback = function(args) @@ -320,12 +341,12 @@ config({opts}, {namespace}) *vim.diagnostic.config()* |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 > + For example, if a user enables virtual text globally with >lua vim.diagnostic.config({ virtual_text = true }) < - and a diagnostic producer sets diagnostics with > + and a diagnostic producer sets diagnostics with >lua vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) < @@ -365,16 +386,21 @@ config({opts}, {namespace}) *vim.diagnostic.config()* the beginning of the virtual text. • prefix: (string) Prepend diagnostic message with prefix. + • 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: > + 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) + function(diagnostic) + if diagnostic.severity == vim.diagnostic.severity.ERROR then + return string.format("E: %s", diagnostic.message) + end + return diagnostic.message end - return diagnostic.message - end < • signs: (default true) Use signs for diagnostics. @@ -426,7 +452,7 @@ fromqflist({list}) *vim.diagnostic.fromqflist()* |getloclist()|. Return: ~ - array of diagnostics |diagnostic-structure| + Diagnostic [] array of |diagnostic-structure| get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. @@ -441,7 +467,7 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* • severity: See |diagnostic-severity|. Return: ~ - (table) A list of diagnostic items |diagnostic-structure|. + Diagnostic [] table A list of diagnostic items |diagnostic-structure|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. @@ -462,37 +488,39 @@ get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. Parameters: ~ - • {opts} (table) See |vim.diagnostic.goto_next()| + • {opts} (table|nil) See |vim.diagnostic.goto_next()| Return: ~ - (table) Next diagnostic + 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) See |vim.diagnostic.goto_next()| + • {opts} (table|nil) See |vim.diagnostic.goto_next()| Return: ~ - (table) Next diagnostic position as a (row, col) tuple. + 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()| + • {opts} nil|table See |vim.diagnostic.goto_next()| Return: ~ - (table) Previous diagnostic + 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) See |vim.diagnostic.goto_next()| + • {opts} (table|nil) See |vim.diagnostic.goto_next()| Return: ~ - (table) Previous diagnostic position as a (row, col) tuple. + 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. @@ -519,7 +547,7 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (table) See |vim.diagnostic.goto_next()| + • {opts} (table|nil) See |vim.diagnostic.goto_next()| hide({namespace}, {bufnr}) *vim.diagnostic.hide()* Hide currently displayed diagnostics. @@ -532,11 +560,23 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* |vim.diagnostic.disable()|. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, hide - diagnostics from all namespaces. + • {namespace} (number|nil) Diagnostic namespace. When omitted, hide diagnostics from all + namespaces. • {bufnr} (number|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} (number|nil) Buffer number, or 0 for current buffer. + • {namespace} (number|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. @@ -546,12 +586,12 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) WARNING filename:27:3: Variable 'foo' does not exist < - This can be parsed into a diagnostic |diagnostic-structure| with: > + 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 }) + 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: ~ @@ -566,8 +606,8 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) default to 0 and "severity" defaults to ERROR. Return: ~ - diagnostic |diagnostic-structure| or `nil` if {pat} fails to match - {str}. + 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. @@ -618,9 +658,12 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()* {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: ~ - tuple ({float_bufnr}, {win_id}) + number|nil, number|nil: ({float_bufnr}, {win_id}) reset({namespace}, {bufnr}) *vim.diagnostic.reset()* Remove all diagnostics from the given namespace. @@ -631,8 +674,8 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()* re-displayed, use |vim.diagnostic.hide()|. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, remove - diagnostics from all namespaces. + • {namespace} (number|nil) Diagnostic namespace. When omitted, remove diagnostics from all + namespaces. • {bufnr} (number|nil) Remove diagnostics for the given buffer. When omitted, diagnostics are removed for all buffers. @@ -680,8 +723,8 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) Display diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, show - diagnostics from all namespaces. + • {namespace} (number|nil) Diagnostic namespace. When omitted, show diagnostics from all + namespaces. • {bufnr} (number|nil) Buffer number, or 0 for current buffer. When omitted, show diagnostics in all buffers. • {diagnostics} (table|nil) The diagnostics to display. When omitted, @@ -701,6 +744,6 @@ toqflist({diagnostics}) *vim.diagnostic.toqflist()* • {diagnostics} (table) List of diagnostics |diagnostic-structure|. Return: ~ - array of quickfix list items |setqflist-what| + table[] of quickfix list items |setqflist-what| vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: |