neovim/runtime/doc/diagnostic.txt

*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
	source: The source of the diagnostic

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=
	sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl=
	sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl=
	sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl=

When the "severity_sort" option is set (see |vim.diagnostic.config()|) the
priority of each sign depends on the severity of the associated diagnostic.
Otherwise, all signs have the same priority (the value of the "priority"
option in the "signs" table of |vim.diagnostic.config()| or 10 if unset).

==============================================================================
EVENTS							*diagnostic-events*

							*DiagnosticsChanged*
DiagnosticsChanged	After diagnostics have changed.

Example: >
	autocmd User DiagnosticsChanged lua vim.diagnostic.setqflist({open = false })
<
==============================================================================
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
<
==============================================================================
Lua module: vim.diagnostic                                    *diagnostic-api*

config({opts}, {namespace})                          *vim.diagnostic.config()*
                Configure diagnostic options globally or for a specific
                diagnostic namespace.

                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.
                    • `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
                                   diagnostics. Options:
                                   • severity: Only underline diagnostics
                                     matching the given severity
                                     |diagnostic-severity|

                                 • virtual_text: (default true) Use virtual
                                   text for diagnostics. Options:
                                   • severity: Only show virtual text for
                                     diagnostics matching the given severity
                                     |diagnostic-severity|
                                   • source: (string) Include the diagnostic
                                     source in virtual text. 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. Example:>

                                       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. 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.

                                 • 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}  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.

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|

get({bufnr}, {opts})                                    *vim.diagnostic.get()*
                Get current diagnostics.

                Parameters: ~
                    {bufnr}  number|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: ~
                    table A list of diagnostic items |diagnostic-structure|.

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|.
                            • enable_popup: (boolean, default true) Call
                              |vim.diagnostic.show_line_diagnostics()| on
                              jump.
                            • popup_opts: (table) Table to pass as {opts}
                              parameter to
                              |vim.diagnostic.show_line_diagnostics()|
                            • 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.

                                                      *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: >

                 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}.

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()|.

                                      *vim.diagnostic.show_line_diagnostics()*
show_line_diagnostics({opts}, {bufnr}, {lnum})
                Open a floating window with the diagnostics from the given
                line.

                Parameters: ~
                    {opts}   table Configuration table. See
                             |vim.diagnostic.show_position_diagnostics()|.
                    {bufnr}  number|nil Buffer number. Defaults to the current
                             buffer.
                    {lnum}   number|nil Line number. Defaults to line number
                             of cursor.

                Return: ~
                    tuple ({popup_bufnr}, {win_id})

                                  *vim.diagnostic.show_position_diagnostics()*
show_position_diagnostics({opts}, {bufnr}, {position})
                Open a floating window with the diagnostics at the given
                position.

                Parameters: ~
                    {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
                                • 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.
                    {bufnr}     number|nil Buffer number. Defaults to the
                                current buffer.
                    {position}  table|nil The (0,0)-indexed position. Defaults
                                to the current cursor position.

                Return: ~
                    tuple ({popup_bufnr}, {win_id})

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|

 vim:tw=78:ts=8:ft=help:norl: