kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-19 18:55:14 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(lua): improvements for LSP and Diagnostic

Browse Source
This commit is contained in:
Lewis Russell 2024-03-05 12:06:15 +00:00 committed by Lewis Russell
parent 5b312cd5f6
commit a4290f462e
13 changed files with 568 additions and 507 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

454
runtime/doc/diagnostic.txt
View File

@ -367,79 +367,211 @@ Lua module: vim.diagnostic *diagnostic-api*
• {user_data}? (`any`) arbitrary data plugins can add • {user_data}? (`any`) arbitrary data plugins can add
• {namespace}? (`integer`) • {namespace}? (`integer`)
*vim.diagnostic.GetOpts*
A table with the following keys:
Fields: ~
• {namespace}? (`integer`) Limit diagnostics to the given namespace.
• {lnum}? (`integer`) Limit diagnostics to the given line number.
• {severity}? (`vim.diagnostic.SeverityFilter`) See
|diagnostic-severity|.
*vim.diagnostic.GotoOpts*
Extends: |vim.diagnostic.GetOpts|
Configuration table with the following keys:
Fields: ~
• {cursor_position}? (`{[1]:integer,[2]:integer}`, default: current cursor position)
Cursor position as a `(row, col)` tuple. See
|nvim_win_get_cursor()|.
• {wrap}? (`boolean`, default: `true`) Whether to loop
around file or not. Similar to 'wrapscan'.
• {severity} (`vim.diagnostic.Severity`) See
|diagnostic-severity|.
• {float}? (`boolean|vim.diagnostic.Opts.Float`, 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}? (`integer`, default: `0`) Window ID
*vim.diagnostic.NS* *vim.diagnostic.NS*
Fields: ~ Fields: ~
• {name} (`string`) • {name} (`string`)
• {opts} (`vim.diagnostic.Opts`) • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|.
• {user_data} (`table`) • {user_data} (`table`)
• {disabled}? (`boolean`) • {disabled}? (`boolean`)
*vim.diagnostic.Opts* *vim.diagnostic.Opts*
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.
Fields: ~ Fields: ~
• {float}? (`boolean|vim.diagnostic.Opts.Float`) • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`)
• {update_in_insert}? (`boolean`) Use underline for diagnostics.
• {underline}? (`boolean|vim.diagnostic.Opts.Underline`) • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `true`)
• {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText`) Use virtual text for diagnostics. If multiple
• {signs}? (`boolean|vim.diagnostic.Opts.Signs`) diagnostics are set for a namespace, one prefix
• {severity_sort}? (`boolean|{reverse?:boolean}`) per diagnostic + the last diagnostic message are
shown.
• {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`)
Use signs for diagnostics |diagnostic-signs|.
• {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`)
Options for floating windows. See
|vim.diagnostic.Opts.Float|.
• {update_in_insert}? (`boolean`, default: `false) Update diagnostics
in Insert mode (if `false`, diagnostics are
updated on |InsertLeave|)
• {severity_sort}? (`boolean|{reverse?:boolean}`, 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
*vim.diagnostic.Opts.Float* *vim.diagnostic.Opts.Float*
Fields: ~ Fields: ~
• {bufnr}? (`integer`) • {bufnr}? (`integer`, default: current buffer) Buffer number
• {namespace}? (`integer`) to show diagnostics from.
• {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`) • {namespace}? (`integer`) Limit diagnostics to the given namespace
• {pos}? (`integer|{[1]:integer,[2]:integer}`) • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default:
• {severity_sort}? (`boolean|{reverse?:boolean}`) `line`) Show diagnostics from the whole buffer
• {severity}? (`vim.diagnostic.SeverityFilter`) (`buffer"`, the current cursor line (`line`), or the
• {header}? (`string|{[1]:string,[2]:any}`) current cursor position (`cursor`). Shorthand
• {source}? (`boolean|string`) versions are also accepted (`c` for `cursor`, `l`
• {format}? (`fun(diagnostic:vim.Diagnostic): string`) for `line`, `b` for `buffer`).
• {prefix}? (`string|table`) • {pos}? (`integer|{[1]:integer,[2]:integer}`) If {scope} is
• {suffix}? (`string|table`) "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}? (`boolean|{reverse?:boolean}`, default: `false`)
Sort diagnostics by severity. Overrides the setting
from |vim.diagnostic.config()|.
• {severity}? (`vim.diagnostic.SeverityFilter`) See
|diagnostic-severity|. Overrides the setting from
|vim.diagnostic.config()|.
• {header}? (`string|{[1]:string,[2]:any}`) 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|'if_many'`) 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}? (`fun(diagnostic:vim.Diagnostic): string`) 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}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`)
Prefix each diagnostic in the floating window:
• If a `function`, {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 a `table`, it is interpreted as a `[text,
hl_group]` tuple as in |nvim_echo()|
• If a `string`, it is prepended to each diagnostic
in the window with no highlight. Overrides the
setting from |vim.diagnostic.config()|.
• {suffix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`)
Same as {prefix}, but appends the text to the
diagnostic instead of prepending it. Overrides the
setting from |vim.diagnostic.config()|.
• {focus_id}? (`string`) • {focus_id}? (`string`)
*vim.diagnostic.Opts.Signs* *vim.diagnostic.Opts.Signs*
Fields: ~ Fields: ~
• {severity}? (`vim.diagnostic.SeverityFilter`) • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual text
• {priority}? (`integer`) for diagnostics matching the given severity
• {text}? (`table<vim.diagnostic.Severity,string>`) |diagnostic-severity|
• {numhl}? (`table<vim.diagnostic.Severity,string>`) • {priority}? (`integer`, default: `10`) Base priority to use for
• {linehl}? (`table<vim.diagnostic.Severity,string>`) signs. When {severity_sort} is used, the priority of a
• {texthl}? (`table<vim.diagnostic.Severity,string>`) sign is adjusted based on its severity. Otherwise, all
signs use the same priority.
• {text}? (`table<vim.diagnostic.Severity,string>`) 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<vim.diagnostic.Severity,string>`) A table mapping
|diagnostic-severity| to the highlight group used for the
line number where the sign is placed.
• {linehl}? (`table<vim.diagnostic.Severity,string>`) A table mapping
|diagnostic-severity| to the highlight group used for the
whole line the sign is placed in.
*vim.diagnostic.Opts.Underline* *vim.diagnostic.Opts.Underline*
Fields: ~ Fields: ~
• {severity}? (`vim.diagnostic.SeverityFilter`) • {severity}? (`vim.diagnostic.SeverityFilter`) Only underline
diagnostics matching the given severity
|diagnostic-severity|.
*vim.diagnostic.Opts.VirtualText* *vim.diagnostic.Opts.VirtualText*
Fields: ~ Fields: ~
• {severity}? (`vim.diagnostic.SeverityFilter`) • {severity}? (`vim.diagnostic.SeverityFilter`) Only show
• {source}? (`boolean|string`) virtual text for diagnostics matching the given
• {prefix}? (`string|function`) severity |diagnostic-severity|
• {suffix}? (`string|function`) • {source}? (`boolean|"if_many"`) Include the diagnostic
• {spacing}? (`integer`) source in virtual text. Use `'if_many'` to only
• {format}? (`function`) show sources if there is more than one
• {hl_mode}? (`'replace'|'combine'|'blend'`) diagnostic source in the buffer. Otherwise, any
• {virt_text}? (`{[1]:string,[2]:any}[]`) truthy value means to always show the diagnostic
• {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) source.
• {virt_text_win_col}? (`integer`) • {spacing}? (`integer`) Amount of empty spaces inserted at
• {virt_text_hide}? (`boolean`) the beginning of the virtual text.
• {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`)
*vim.diagnostic.OptsResolved* Prepend diagnostic message with prefix. If a
`function`, {i} is the index of the diagnostic
Fields: ~ being evaluated, and {total} is the total number
• {float} (`vim.diagnostic.Opts.Float`) of diagnostics for the line. This can be used to
• {update_in_insert} (`boolean`) render diagnostic symbols or error codes.
• {underline} (`vim.diagnostic.Opts.Underline`) • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic):
• {virtual_text} (`vim.diagnostic.Opts.VirtualText`) string)`) Append diagnostic message with suffix.
• {signs} (`vim.diagnostic.Opts.Signs`) This can be used to render an LSP diagnostic
• {severity_sort} (`{reverse?:boolean}`) error code.
• {format}? (`fun(diagnostic:vim.Diagnostic): 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
<
• {hl_mode}? (`'replace'|'combine'|'blend'`) See
|nvim_buf_set_extmark()|.
• {virt_text}? (`{[1]:string,[2]:any}[]`) See
|nvim_buf_set_extmark()|.
• {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) See
|nvim_buf_set_extmark()|.
• {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|.
• {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|.
config({opts}, {namespace}) *vim.diagnostic.config()* config({opts}, {namespace}) *vim.diagnostic.config()*
@ -461,101 +593,16 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
then virtual text will not be enabled for those diagnostics. 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: ~ Parameters: ~
• {opts} (`table?`) When omitted or "nil", retrieve the current • {opts} (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve
configuration. Otherwise, a configuration table with the the current configuration. Otherwise, a configuration
following keys: table (see |vim.diagnostic.Opts|).
• 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. • {namespace} (`integer?`) Update the options for the given namespace.
When omitted, update the global diagnostic options. When omitted, update the global diagnostic options.
Return: ~ Return: ~
(`table?`) table of current diagnostic config if `opts` is omitted. (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is
omitted. See |vim.diagnostic.Opts|.
count({bufnr}, {opts}) *vim.diagnostic.count()* count({bufnr}, {opts}) *vim.diagnostic.count()*
Get current diagnostics count. Get current diagnostics count.
@ -563,14 +610,10 @@ count({bufnr}, {opts}) *vim.diagnostic.count()*
Parameters: ~ Parameters: ~
• {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for
current buffer or nil for all buffers. current buffer or nil for all buffers.
• {opts} (`table?`) A table with the following keys: • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|.
• namespace: (number) Limit diagnostics to the given
namespace.
• lnum: (number) Limit diagnostics to the given line number.
• severity: See |diagnostic-severity|.
Return: ~ Return: ~
(`table`) A table with actually present severity values as keys (see (`table`) Table with actually present severity values as keys (see
|diagnostic-severity|) and integer counts as values. |diagnostic-severity|) and integer counts as values.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()* disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
@ -599,8 +642,7 @@ fromqflist({list}) *vim.diagnostic.fromqflist()*
|getloclist()|. |getloclist()|.
Return: ~ Return: ~
(`vim.Diagnostic[]`) array of |diagnostic-structure|. See (`vim.Diagnostic[]`) See |vim.Diagnostic|.
|vim.Diagnostic|.
get({bufnr}, {opts}) *vim.diagnostic.get()* get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics. Get current diagnostics.
@ -611,15 +653,10 @@ get({bufnr}, {opts}) *vim.diagnostic.get()*
Parameters: ~ Parameters: ~
• {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for
current buffer or nil for all buffers. current buffer or nil for all buffers.
• {opts} (`table?`) A table with the following keys: • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|.
• namespace: (number) Limit diagnostics to the given
namespace.
• lnum: (number) Limit diagnostics to the given line number.
• severity: See |diagnostic-severity|.
Return: ~ Return: ~
(`vim.Diagnostic[]`) table A list of diagnostic items (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and
|diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and
`severity` are guaranteed to be present. See |vim.Diagnostic|. `severity` are guaranteed to be present. See |vim.Diagnostic|.
get_namespace({namespace}) *vim.diagnostic.get_namespace()* get_namespace({namespace}) *vim.diagnostic.get_namespace()*
@ -629,20 +666,20 @@ get_namespace({namespace}) *vim.diagnostic.get_namespace()*
• {namespace} (`integer`) Diagnostic namespace • {namespace} (`integer`) Diagnostic namespace
Return: ~ Return: ~
(`table`) Namespace metadata (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|.
get_namespaces() *vim.diagnostic.get_namespaces()* get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces. Get current diagnostic namespaces.
Return: ~ Return: ~
(`table<integer,vim.diagnostic.NS>`) A list of active diagnostic (`table<integer,vim.diagnostic.NS>`) List of active diagnostic
namespaces |vim.diagnostic|. namespaces |vim.diagnostic|.
get_next({opts}) *vim.diagnostic.get_next()* get_next({opts}) *vim.diagnostic.get_next()*
Get the next diagnostic closest to the cursor position. Get the next diagnostic closest to the cursor position.
Parameters: ~ Parameters: ~
• {opts} (`table?`) See |vim.diagnostic.goto_next()| • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
Return: ~ Return: ~
(`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|.
@ -651,17 +688,17 @@ get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current buffer. Return the position of the next diagnostic in the current buffer.
Parameters: ~ Parameters: ~
• {opts} (`table?`) See |vim.diagnostic.goto_next()| • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
Return: ~ Return: ~
(`table|false`) Next diagnostic position as a (row, col) tuple or (`table|false`) Next diagnostic position as a `(row, col)` tuple or
false if no next diagnostic. false if no next diagnostic.
get_prev({opts}) *vim.diagnostic.get_prev()* get_prev({opts}) *vim.diagnostic.get_prev()*
Get the previous diagnostic closest to the cursor position. Get the previous diagnostic closest to the cursor position.
Parameters: ~ Parameters: ~
• {opts} (`table?`) See |vim.diagnostic.goto_next()| • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
Return: ~ Return: ~
(`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|.
@ -670,39 +707,23 @@ get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current buffer. Return the position of the previous diagnostic in the current buffer.
Parameters: ~ Parameters: ~
• {opts} (`table?`) See |vim.diagnostic.goto_next()| • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
Return: ~ Return: ~
(`table|false`) Previous diagnostic position as a (row, col) tuple or (`table|false`) Previous diagnostic position as a `(row, col)` tuple
false if there is no prior diagnostic or `false` if there is no prior diagnostic.
goto_next({opts}) *vim.diagnostic.goto_next()* goto_next({opts}) *vim.diagnostic.goto_next()*
Move to the next diagnostic. Move to the next diagnostic.
Parameters: ~ Parameters: ~
• {opts} (`table?`) Configuration table with the following keys: • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
• {namespace} (`integer`) Only consider diagnostics from the
given namespace.
• {cursor_position}? (`{[1]:integer,[2]:integer}`) 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} (`vim.diagnostic.Severity`) See
|diagnostic-severity|.
• {float}? (`boolean|vim.diagnostic.Opts.Float`, 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}? (`integer`, default: `0`) Window ID
goto_prev({opts}) *vim.diagnostic.goto_prev()* goto_prev({opts}) *vim.diagnostic.goto_prev()*
Move to the previous diagnostic in the current buffer. Move to the previous diagnostic in the current buffer.
Parameters: ~ Parameters: ~
• {opts} (`table?`) See |vim.diagnostic.goto_next()| • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
hide({namespace}, {bufnr}) *vim.diagnostic.hide()* hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
Hide currently displayed diagnostics. Hide currently displayed diagnostics.
@ -740,7 +761,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
WARNING filename:27:3: Variable 'foo' does not exist WARNING filename:27:3: Variable 'foo' does not exist
< <
This can be parsed into a diagnostic |diagnostic-structure| with: >lua This can be parsed into |vim.Diagnostic| structure with: >lua
local s = "WARNING filename:27:3: Variable 'foo' does not exist" local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = { "severity", "lnum", "col", "message" } local groups = { "severity", "lnum", "col", "message" }
@ -750,9 +771,8 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
Parameters: ~ Parameters: ~
• {str} (`string`) String to parse diagnostics from. • {str} (`string`) String to parse diagnostics from.
• {pat} (`string`) Lua pattern with capture groups. • {pat} (`string`) Lua pattern with capture groups.
• {groups} (`string[]`) List of fields in a • {groups} (`string[]`) List of fields in a |vim.Diagnostic|
|diagnostic-structure| to associate with captures from structure to associate with captures from {pat}.
{pat}.
• {severity_map} (`table`) A table mapping the severity field from • {severity_map} (`table`) A table mapping the severity field from
{groups} with an item from |vim.diagnostic.severity|. {groups} with an item from |vim.diagnostic.severity|.
• {defaults} (`table?`) Table of default values for any fields not • {defaults} (`table?`) Table of default values for any fields not
@ -760,61 +780,15 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
default to 0 and "severity" defaults to ERROR. default to 0 and "severity" defaults to ERROR.
Return: ~ Return: ~
(`vim.Diagnostic?`) |diagnostic-structure| or `nil` if {pat} fails to (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails
match {str}. See |vim.Diagnostic|. to match {str}.
open_float({opts}) *vim.diagnostic.open_float()* open_float({opts}) *vim.diagnostic.open_float()*
Show diagnostics in a floating window. Show diagnostics in a floating window.
Parameters: ~ Parameters: ~
• {opts} (`table?`) Configuration table with the same keys as • {opts} (`vim.diagnostic.Opts.Float?`) See
|vim.lsp.util.open_floating_preview()| in addition to the |vim.diagnostic.Opts.Float|.
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 (multiple): ~ Return (multiple): ~
(`integer?`) float_bufnr (`integer?`) float_bufnr
@ -840,10 +814,9 @@ set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
Parameters: ~ Parameters: ~
• {namespace} (`integer`) The diagnostic namespace • {namespace} (`integer`) The diagnostic namespace
• {bufnr} (`integer`) Buffer number • {bufnr} (`integer`) Buffer number
• {diagnostics} (`vim.Diagnostic[]`) A list of diagnostic items • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|.
|diagnostic-structure|. See |vim.Diagnostic|. • {opts} (`vim.diagnostic.Opts?`) Display options to pass to
• {opts} (`table?`) Display options to pass to |vim.diagnostic.show()|. See |vim.diagnostic.Opts|.
|vim.diagnostic.show()|
setloclist({opts}) *vim.diagnostic.setloclist()* setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list. Add buffer diagnostics to the location list.
@ -890,19 +863,18 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
list of diagnostics without saving them or to display list of diagnostics without saving them or to display
only a subset of diagnostics. May not be used when only a subset of diagnostics. May not be used when
{namespace} or {bufnr} is nil. See |vim.Diagnostic|. {namespace} or {bufnr} is nil. See |vim.Diagnostic|.
• {opts} (`table?`) Display options. See • {opts} (`vim.diagnostic.Opts?`) Display options. See
|vim.diagnostic.config()|. |vim.diagnostic.Opts|.
toqflist({diagnostics}) *vim.diagnostic.toqflist()* toqflist({diagnostics}) *vim.diagnostic.toqflist()*
Convert a list of diagnostics to a list of quickfix items that can be Convert a list of diagnostics to a list of quickfix items that can be
passed to |setqflist()| or |setloclist()|. passed to |setqflist()| or |setloclist()|.
Parameters: ~ Parameters: ~
• {diagnostics} (`vim.Diagnostic[]`) List of diagnostics • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|.
|diagnostic-structure|. See |vim.Diagnostic|.
Return: ~ Return: ~
(`table[]`) of quickfix list items |setqflist-what| (`table[]`) Quickfix list items |setqflist-what|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

94
runtime/doc/lsp.txt
View File

@ -673,17 +673,18 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the
result. Parameters are the same as |vim.lsp.buf_request_all()| but the result. Parameters are the same as |vim.lsp.buf_request_all()| but the
result is different. Waits a maximum of {timeout_ms} (default 1000) ms. result is different. Waits a maximum of {timeout_ms}.
Parameters: ~ Parameters: ~
• {bufnr} (`integer`) Buffer handle, or 0 for current. • {bufnr} (`integer`) Buffer handle, or 0 for current.
• {method} (`string`) LSP method name • {method} (`string`) LSP method name
• {params} (`table?`) Parameters to send to the server • {params} (`table?`) Parameters to send to the server
• {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a • {timeout_ms} (`integer?`, default: `1000`) Maximum time in
result. Defaults to 1000 milliseconds to wait for a result.
Return (multiple): ~ Return (multiple): ~
(`table`) result Map of client_id:request_result. (`table<integer, {err: lsp.ResponseError, result: any}>?`) result Map
of client_id:request_result.
(`string?`) err On timeout, cancel, or error, `err` is a string (`string?`) err On timeout, cancel, or error, `err` is a string
describing the failure reason, and `result` is nil. describing the failure reason, and `result` is nil.
@ -946,13 +947,15 @@ Lua module: vim.lsp.client *lsp-client*
server. server.
• {config} (`vim.lsp.ClientConfig`) copy of the table • {config} (`vim.lsp.ClientConfig`) copy of the table
that was passed by the user to that was passed by the user to
|vim.lsp.start_client()|. |vim.lsp.start_client()|. See
|vim.lsp.ClientConfig|.
• {server_capabilities} (`lsp.ServerCapabilities?`) Response from the • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
server sent on initialize` describing the server sent on initialize` describing the
server's capabilities. server's capabilities.
• {progress} (`vim.lsp.Client.Progress`) A ring buffer • {progress} (`vim.lsp.Client.Progress`) A ring buffer
(|vim.ringbuf()|) containing progress messages (|vim.ringbuf()|) containing progress messages
sent by the server. sent by the server. See
|vim.lsp.Client.Progress|.
• {initialized} (`true?`) • {initialized} (`true?`)
• {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace • {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace
folders configured in the client when the folders configured in the client when the
@ -968,9 +971,28 @@ Lua module: vim.lsp.client *lsp-client*
action, code lenses, ...) triggers the action, code lenses, ...) triggers the
command. Client commands take precedence over command. Client commands take precedence over
the global command registry. the global command registry.
• {settings} (`table`) • {settings} (`table`) Map with language server specific
• {flags} (`table`) settings. These are returned to the language
• {get_language_id} (`fun(bufnr: integer, filetype: string): string`) server if requested via
`workspace/configuration`. Keys are
case-sensitive.
• {flags} (`table`) A table with flags for the client.
The current (experimental) flags are:
• {allow_incremental_sync}? (`boolean`) Allow
using incremental sync for buffer edits
(defailt: `true`)
• {debounce_text_changes} (`integer`, default:
`150`) Debounce `didChange` notifications to
the server by the given number in
milliseconds. No debounce occurs if `nil`.
• {exit_timeout} (`integer|false`, default:
`false`) Milliseconds to wait for server to
exit cleanly after sending the "shutdown"
request before sending kill -15. If set to
false, nvim exits immediately after sending
the "shutdown" request to the server.
• {get_language_id} (`fun(bufnr: integer, filetype: string):
string`)
• {capabilities} (`lsp.ClientCapabilities`) The capabilities • {capabilities} (`lsp.ClientCapabilities`) The capabilities
provided by the client (editor or tool) provided by the client (editor or tool)
• {dynamic_capabilities} (`lsp.DynamicCapabilities`) • {dynamic_capabilities} (`lsp.DynamicCapabilities`)
@ -1021,6 +1043,7 @@ Lua module: vim.lsp.client *lsp-client*
*vim.lsp.Client.Progress* *vim.lsp.Client.Progress*
Extends: |vim.Ringbuf| Extends: |vim.Ringbuf|
Fields: ~ Fields: ~
• {pending} (`table<lsp.ProgressToken,lsp.LSPAny>`) • {pending} (`table<lsp.ProgressToken,lsp.LSPAny>`)
@ -1070,10 +1093,8 @@ Lua module: vim.lsp.client *lsp-client*
• {handlers}? (`table<string,function>`) Map of language • {handlers}? (`table<string,function>`) Map of language
server method names to |lsp-handler| server method names to |lsp-handler|
• {settings}? (`table`) Map with language server specific • {settings}? (`table`) Map with language server specific
settings. These are returned to the language settings. See the {settings} in
server if requested via |vim.lsp.Client|.
`workspace/configuration`. Keys are
case-sensitive.
• {commands}? (`table<string,fun(command: lsp.Command, ctx: • {commands}? (`table<string,fun(command: lsp.Command, ctx:
table)>`) Table that maps string of clientside table)>`) Table that maps string of clientside
commands to user-defined functions. Commands commands to user-defined functions. Commands
@ -1101,13 +1122,14 @@ Lua module: vim.lsp.client *lsp-client*
possible errors. Use possible errors. Use
`vim.lsp.rpc.client_errors[code]` to get `vim.lsp.rpc.client_errors[code]` to get
human-friendly name. human-friendly name.
• {before_init}? (`vim.lsp.client.before_init_cb`) Callback • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
invoked before the LSP "initialize" phase, where Callback invoked before the LSP "initialize"
`params` contains the parameters being sent to phase, where `params` contains the parameters
the server and `config` is the config that was being sent to the server and `config` is the
passed to |vim.lsp.start_client()|. You can use config that was passed to
this to modify parameters before they are sent. |vim.lsp.start_client()|. You can use this to
• {on_init}? (`elem_or_list<vim.lsp.client.on_init_cb>`) modify parameters before they are sent.
• {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>`)
Callback invoked after LSP "initialize", where Callback invoked after LSP "initialize", where
`result` is a table of `capabilities` and `result` is a table of `capabilities` and
anything else the server may send. For example, anything else the server may send. For example,
@ -1115,13 +1137,13 @@ Lua module: vim.lsp.client *lsp-client*
if `capabilities.offsetEncoding` was sent to it. if `capabilities.offsetEncoding` was sent to it.
You can only modify the `client.offset_encoding` You can only modify the `client.offset_encoding`
here before any notifications are sent. here before any notifications are sent.
• {on_exit}? (`elem_or_list<vim.lsp.client.on_exit_cb>`) • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
Callback invoked on client exit. Callback invoked on client exit.
• code: exit code of the process • code: exit code of the process
• signal: number describing the signal used to • signal: number describing the signal used to
terminate (if any) terminate (if any)
• client_id: client handle • client_id: client handle
• {on_attach}? (`elem_or_list<vim.lsp.client.on_attach_cb>`) • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
Callback invoked when client attaches to a Callback invoked when client attaches to a
buffer. buffer.
• {trace}? (`'off'|'messages'|'verbose'`, default: "off") • {trace}? (`'off'|'messages'|'verbose'`, default: "off")
@ -1129,18 +1151,19 @@ Lua module: vim.lsp.client *lsp-client*
initialize request. Invalid/empty values will initialize request. Invalid/empty values will
• {flags}? (`table`) A table with flags for the client. The • {flags}? (`table`) A table with flags for the client. The
current (experimental) flags are: current (experimental) flags are:
• allow_incremental_sync (bool, default true): • {allow_incremental_sync}? (`boolean`) Allow
Allow using incremental sync for buffer edits using incremental sync for buffer edits
• debounce_text_changes (number, default 150): (defailt: `true`)
Debounce didChange notifications to the server • {debounce_text_changes} (`integer`, default:
by the given number in milliseconds. No `150`) Debounce `didChange` notifications to
debounce occurs if nil the server by the given number in
• exit_timeout (number|boolean, default false): milliseconds. No debounce occurs if `nil`.
Milliseconds to wait for server to exit • {exit_timeout} (`integer|false`, default:
cleanly after sending the "shutdown" request `false`) Milliseconds to wait for server to
before sending kill -15. If set to false, nvim exit cleanly after sending the "shutdown"
exits immediately after sending the "shutdown" request before sending kill -15. If set to
request to the server. false, nvim exits immediately after sending
the "shutdown" request to the server.
• {root_dir}? (`string`) Directory where the LSP server will • {root_dir}? (`string`) Directory where the LSP server will
base its workspaceFolders, rootUri, and rootPath base its workspaceFolders, rootUri, and rootPath
on initialization. on initialization.
@ -1176,6 +1199,7 @@ Lua module: vim.lsp.buf *lsp-buf*
*vim.lsp.LocationOpts* *vim.lsp.LocationOpts*
Extends: |vim.lsp.ListOpts| Extends: |vim.lsp.ListOpts|
Fields: ~ Fields: ~
• {reuse_win}? (`boolean`) Jump to existing window if buffer is already • {reuse_win}? (`boolean`) Jump to existing window if buffer is already
open. open.
@ -1443,7 +1467,7 @@ on_diagnostic({_}, {result}, {ctx}, {config})
Parameters: ~ Parameters: ~
• {result} (`lsp.DocumentDiagnosticReport`) • {result} (`lsp.DocumentDiagnosticReport`)
• {ctx} (`lsp.HandlerContext`) • {ctx} (`lsp.HandlerContext`)
• {config} (`table`) Configuration table (see • {config} (`vim.diagnostic.Opts`) Configuration table (see
|vim.diagnostic.config()|). |vim.diagnostic.config()|).
*vim.lsp.diagnostic.on_publish_diagnostics()* *vim.lsp.diagnostic.on_publish_diagnostics()*

37
runtime/doc/lua.txt
View File

@ -1831,15 +1831,15 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
• {col} (`integer?`) col to inspect, 0-based. Defaults to the col of • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
the current cursor the current cursor
• {filter} (`table?`) Table with key-value pairs to filter the items • {filter} (`table?`) Table with key-value pairs to filter the items
• {syntax} (`boolean`) Include syntax based highlight groups • {syntax} (`boolean`, default: `true`) Include syntax based
(defaults to true) highlight groups.
• {treesitter} (`boolean`) Include treesitter based • {treesitter} (`boolean`, default: `true`) Include
highlight groups (defaults to true) treesitter based highlight groups.
• {extmarks} (`boolean|"all"`, default: true) Include • {extmarks} (`boolean|"all"`, default: true) Include
extmarks. When `all`, then extmarks without a `hl_group` extmarks. When `all`, then extmarks without a `hl_group`
will also be included. will also be included.
• {semantic_tokens} (`boolean`) Include semantic token • {semantic_tokens} (`boolean`, default: true) Include
highlights (defaults to true) semantic token highlights.
Return: ~ Return: ~
(`table`) a table with the following key-value pairs. Items are in (`table`) a table with the following key-value pairs. Items are in
@ -1863,7 +1863,16 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()*
the current cursor the current cursor
• {col} (`integer?`) col to inspect, 0-based. Defaults to the col of • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
the current cursor the current cursor
• {filter} (`table?`) see |vim.inspect_pos()| • {filter} (`table?`) A table with the following fields:
• {syntax} (`boolean`, default: `true`) Include syntax based
highlight groups.
• {treesitter} (`boolean`, default: `true`) Include
treesitter based highlight groups.
• {extmarks} (`boolean|"all"`, default: true) Include
extmarks. When `all`, then extmarks without a `hl_group`
will also be included.
• {semantic_tokens} (`boolean`, default: true) Include
semantic token highlights.
@ -1989,7 +1998,7 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
end of the sequence. end of the sequence.
Return: ~ Return: ~
(`function`) Iterator over the split components (`fun():string?`) Iterator over the split components
See also: ~ See also: ~
• |string.gmatch()| • |string.gmatch()|
@ -2089,7 +2098,7 @@ vim.ringbuf({size}) *vim.ringbuf()*
• {size} (`integer`) • {size} (`integer`)
Return: ~ Return: ~
(`table`) (`vim.Ringbuf`) ringbuf See |vim.Ringbuf|.
vim.spairs({t}) *vim.spairs()* vim.spairs({t}) *vim.spairs()*
Enumerates key-value pairs of a table, ordered by key. Enumerates key-value pairs of a table, ordered by key.
@ -2097,8 +2106,10 @@ vim.spairs({t}) *vim.spairs()*
Parameters: ~ Parameters: ~
• {t} (`table`) Dict-like table • {t} (`table`) Dict-like table
Return: ~ Return (multiple): ~
(`function`) |for-in| iterator over sorted keys and their values (`fun(table: table<K, V>, index?: K):K, V`) |for-in| iterator over
sorted keys and their values
(`table`)
See also: ~ See also: ~
• Based on • Based on
@ -2334,8 +2345,8 @@ vim.tbl_map({func}, {t}) *vim.tbl_map()*
Apply a function to all values of a table. Apply a function to all values of a table.
Parameters: ~ Parameters: ~
• {func} (`function`) Function • {func} (`fun(value: T): any`) Function
• {t} (`table`) Table • {t} (`table<any, T>`) Table
Return: ~ Return: ~
(`table`) Table of transformed values (`table`) Table of transformed values

11
runtime/lua/vim/_inspector.lua
View File

@ -1,17 +1,20 @@
--- @class vim._inspector.Filter --- @class vim._inspector.Filter
--- @inlinedoc --- @inlinedoc
--- ---
--- Include syntax based highlight groups (defaults to true) --- Include syntax based highlight groups.
--- (default: `true`)
--- @field syntax boolean --- @field syntax boolean
--- ---
--- Include treesitter based highlight groups (defaults to true) --- Include treesitter based highlight groups.
--- (default: `true`)
--- @field treesitter boolean --- @field treesitter boolean
--- ---
--- Include extmarks. When `all`, then extmarks without a `hl_group` will also be included. --- Include extmarks. When `all`, then extmarks without a `hl_group` will also be included.
--- (default: true) --- (default: true)
--- @field extmarks boolean|"all" --- @field extmarks boolean|"all"
--- ---
--- Include semantic token highlights (defaults to true) --- Include semantic token highlights.
--- (default: true)
--- @field semantic_tokens boolean --- @field semantic_tokens boolean
local defaults = { local defaults = {
syntax = true, syntax = true,
@ -145,7 +148,7 @@ end
---@param bufnr? integer defaults to the current buffer ---@param bufnr? integer defaults to the current buffer
---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
---@param filter? vim._inspector.Filter (table) see |vim.inspect_pos()| ---@param filter? vim._inspector.Filter
function vim.show_pos(bufnr, row, col, filter) function vim.show_pos(bufnr, row, col, filter)
local items = vim.inspect_pos(bufnr, row, col, filter) local items = vim.inspect_pos(bufnr, row, col, filter)

371
runtime/lua/vim/diagnostic.lua
View File

@ -42,15 +42,44 @@ local M = {}
--- ---
--- @field namespace? integer --- @field namespace? integer
--- 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.
--- @class vim.diagnostic.Opts --- @class vim.diagnostic.Opts
--- @field float? boolean|vim.diagnostic.Opts.Float ---
--- Use underline for diagnostics.
--- (default: `true`)
--- @field underline? boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline
---
--- Use virtual text for diagnostics. If multiple diagnostics are set for a
--- namespace, one prefix per diagnostic + the last diagnostic message are
--- shown.
--- (default: `true`)
--- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText
---
--- Use signs for diagnostics |diagnostic-signs|.
--- (default: `true`)
--- @field signs? boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs
---
--- Options for floating windows. See |vim.diagnostic.Opts.Float|.
--- @field float? boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float
---
--- Update diagnostics in Insert mode
--- (if `false`, diagnostics are updated on |InsertLeave|)
--- (default: `false)
--- @field update_in_insert? boolean --- @field update_in_insert? boolean
--- @field underline? boolean|vim.diagnostic.Opts.Underline ---
--- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText --- Sort diagnostics by severity. This affects the order in which signs and
--- @field signs? boolean|vim.diagnostic.Opts.Signs --- 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
--- (default: `false)
--- @field severity_sort? boolean|{reverse?:boolean} --- @field severity_sort? boolean|{reverse?:boolean}
--- @class vim.diagnostic.OptsResolved --- @class (private) vim.diagnostic.OptsResolved
--- @field float vim.diagnostic.Opts.Float --- @field float vim.diagnostic.Opts.Float
--- @field update_in_insert boolean --- @field update_in_insert boolean
--- @field underline vim.diagnostic.Opts.Underline --- @field underline vim.diagnostic.Opts.Underline
@ -59,42 +88,156 @@ local M = {}
--- @field severity_sort {reverse?:boolean} --- @field severity_sort {reverse?:boolean}
--- @class vim.diagnostic.Opts.Float --- @class vim.diagnostic.Opts.Float
---
--- Buffer number to show diagnostics from.
--- (default: current buffer)
--- @field bufnr? integer --- @field bufnr? integer
---
--- Limit diagnostics to the given namespace
--- @field namespace? integer --- @field namespace? integer
---
--- 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`).
--- (default: `line`)
--- @field scope? 'line'|'buffer'|'cursor'|'c'|'l'|'b' --- @field scope? 'line'|'buffer'|'cursor'|'c'|'l'|'b'
---
--- 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.
--- @field pos? integer|{[1]:integer,[2]:integer} --- @field pos? integer|{[1]:integer,[2]:integer}
---
--- Sort diagnostics by severity.
--- Overrides the setting from |vim.diagnostic.config()|.
--- (default: `false`)
--- @field severity_sort? boolean|{reverse?:boolean} --- @field severity_sort? boolean|{reverse?:boolean}
---
--- See |diagnostic-severity|.
--- Overrides the setting from |vim.diagnostic.config()|.
--- @field severity? vim.diagnostic.SeverityFilter --- @field severity? vim.diagnostic.SeverityFilter
---
--- 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()|.
--- @field header? string|{[1]:string,[2]:any} --- @field header? string|{[1]:string,[2]:any}
--- @field source? boolean|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()|.
--- @field source? boolean|'if_many'
---
--- 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()|.
--- @field format? fun(diagnostic:vim.Diagnostic): string --- @field format? fun(diagnostic:vim.Diagnostic): string
---
--- Prefix each diagnostic in the floating window:
--- - If a `function`, {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 a `table`, it is interpreted as a `[text, hl_group]` tuple as
--- in |nvim_echo()|
--- - If a `string`, it is prepended to each diagnostic in the window with no
--- highlight.
--- Overrides the setting from |vim.diagnostic.config()|.
--- @field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string) --- @field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
---
--- Same as {prefix}, but appends the text to the diagnostic instead of
--- prepending it.
--- Overrides the setting from |vim.diagnostic.config()|.
--- @field suffix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string) --- @field suffix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
---
--- @field focus_id? string --- @field focus_id? string
--- @class vim.diagnostic.Opts.Underline --- @class vim.diagnostic.Opts.Underline
---
--- Only underline diagnostics matching the given
--- severity |diagnostic-severity|.
--- @field severity? vim.diagnostic.SeverityFilter --- @field severity? vim.diagnostic.SeverityFilter
--- @class vim.diagnostic.Opts.VirtualText --- @class vim.diagnostic.Opts.VirtualText
---
--- Only show virtual text for diagnostics matching the given
--- severity |diagnostic-severity|
--- @field severity? vim.diagnostic.SeverityFilter --- @field severity? vim.diagnostic.SeverityFilter
--- @field source? boolean|string ---
--- @field prefix? string|function --- Include the diagnostic source in virtual text. Use `'if_many'` to only
--- @field suffix? string|function --- show sources if there is more than one diagnostic source in the buffer.
--- Otherwise, any truthy value means to always show the diagnostic source.
--- @field source? boolean|"if_many"
---
--- Amount of empty spaces inserted at the beginning of the virtual text.
--- @field spacing? integer --- @field spacing? integer
--- @field format? function ---
--- Prepend diagnostic message with prefix. If a `function`, {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.
--- @field prefix? string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)
---
--- Append diagnostic message with suffix.
--- This can be used to render an LSP diagnostic error code.
--- @field suffix? string|(fun(diagnostic:vim.Diagnostic): 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
--- ```
--- @field format? fun(diagnostic:vim.Diagnostic): string
---
--- See |nvim_buf_set_extmark()|.
--- @field hl_mode? 'replace'|'combine'|'blend' --- @field hl_mode? 'replace'|'combine'|'blend'
---
--- See |nvim_buf_set_extmark()|.
--- @field virt_text? {[1]:string,[2]:any}[] --- @field virt_text? {[1]:string,[2]:any}[]
---
--- See |nvim_buf_set_extmark()|.
--- @field virt_text_pos? 'eol'|'overlay'|'right_align'|'inline' --- @field virt_text_pos? 'eol'|'overlay'|'right_align'|'inline'
---
--- See |nvim_buf_set_extmark()|.
--- @field virt_text_win_col? integer --- @field virt_text_win_col? integer
---
--- See |nvim_buf_set_extmark()|.
--- @field virt_text_hide? boolean --- @field virt_text_hide? boolean
--- @class vim.diagnostic.Opts.Signs --- @class vim.diagnostic.Opts.Signs
---
--- Only show virtual text for diagnostics matching the given
--- severity |diagnostic-severity|
--- @field severity? vim.diagnostic.SeverityFilter --- @field severity? vim.diagnostic.SeverityFilter
---
--- 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.
--- (default: `10`)
--- @field priority? integer --- @field priority? integer
---
--- 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', ... } }
--- })
--- ```
--- @field text? table<vim.diagnostic.Severity,string> --- @field text? table<vim.diagnostic.Severity,string>
---
--- A table mapping |diagnostic-severity| to the highlight group used for the
--- line number where the sign is placed.
--- @field numhl? table<vim.diagnostic.Severity,string> --- @field numhl? table<vim.diagnostic.Severity,string>
---
--- A table mapping |diagnostic-severity| to the highlight group used for the
--- whole line the sign is placed in.
--- @field linehl? table<vim.diagnostic.Severity,string> --- @field linehl? table<vim.diagnostic.Severity,string>
--- @field texthl? table<vim.diagnostic.Severity,string>
--- @nodoc --- @nodoc
--- @enum vim.diagnostic.Severity --- @enum vim.diagnostic.Severity
@ -752,83 +895,11 @@ end
--- ---
--- then virtual text will not be enabled for those diagnostics. --- then virtual text will not be enabled for those diagnostics.
--- ---
---@note Each of the configuration options below accepts one of the following: ---@param opts vim.diagnostic.Opts? When omitted or `nil`, retrieve the current
--- - `false`: Disable this feature --- configuration. Otherwise, a configuration table (see |vim.diagnostic.Opts|).
--- - `true`: Enable this feature, use default settings. ---@param namespace integer? Update the options for the given namespace.
--- - `table`: Enable this feature with overrides. Use an empty table to use default values. --- When omitted, update the global diagnostic options.
--- - `function`: Function with signature (namespace, bufnr) that returns any of the above. ---@return vim.diagnostic.Opts? : Current diagnostic config if {opts} is omitted.
---
---@param opts vim.diagnostic.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
---
---@param namespace integer? Update the options for the given namespace. When omitted, update the
--- global diagnostic options.
---
---@return vim.diagnostic.Opts? (table?) table of current diagnostic config if `opts` is omitted.
function M.config(opts, namespace) function M.config(opts, namespace)
vim.validate({ vim.validate({
opts = { opts, 't', true }, opts = { opts, 't', true },
@ -873,8 +944,8 @@ end
--- ---
---@param namespace integer The diagnostic namespace ---@param namespace integer The diagnostic namespace
---@param bufnr integer Buffer number ---@param bufnr integer Buffer number
---@param diagnostics vim.Diagnostic[] A list of diagnostic items |diagnostic-structure| ---@param diagnostics vim.Diagnostic[]
---@param opts? vim.diagnostic.Opts (table) Display options to pass to |vim.diagnostic.show()| ---@param opts? vim.diagnostic.Opts Display options to pass to |vim.diagnostic.show()|
function M.set(namespace, bufnr, diagnostics, opts) function M.set(namespace, bufnr, diagnostics, opts)
vim.validate({ vim.validate({
namespace = { namespace, 'n' }, namespace = { namespace, 'n' },
@ -908,7 +979,7 @@ end
--- Get namespace metadata. --- Get namespace metadata.
--- ---
---@param namespace integer Diagnostic namespace ---@param namespace integer Diagnostic namespace
---@return vim.diagnostic.NS (table) Namespace metadata ---@return vim.diagnostic.NS : Namespace metadata
function M.get_namespace(namespace) function M.get_namespace(namespace)
vim.validate({ namespace = { namespace, 'n' } }) vim.validate({ namespace = { namespace, 'n' } })
if not all_namespaces[namespace] then if not all_namespaces[namespace] then
@ -933,22 +1004,21 @@ end
--- Get current diagnostic namespaces. --- Get current diagnostic namespaces.
--- ---
---@return table<integer,vim.diagnostic.NS> A list of active diagnostic namespaces |vim.diagnostic|. ---@return table<integer,vim.diagnostic.NS> : List of active diagnostic namespaces |vim.diagnostic|.
function M.get_namespaces() function M.get_namespaces()
return vim.deepcopy(all_namespaces, true) return vim.deepcopy(all_namespaces, true)
end end
--- Get current diagnostics. --- Get current diagnostics.
--- ---
--- Modifying diagnostics in the returned table has no effect. To set diagnostics in a buffer, use |vim.diagnostic.set()|. --- Modifying diagnostics in the returned table has no effect.
--- To set diagnostics in a buffer, use |vim.diagnostic.set()|.
--- ---
---@param bufnr integer? Buffer number to get diagnostics from. Use 0 for ---@param bufnr integer? Buffer number to get diagnostics from. Use 0 for
--- current buffer or nil for all buffers. --- current buffer or nil for all buffers.
---@param opts? vim.diagnostic.GetOpts (table) A table with the following keys: ---@param opts? vim.diagnostic.GetOpts
--- - namespace: (number) Limit diagnostics to the given namespace. ---@return vim.Diagnostic[] : Fields `bufnr`, `end_lnum`, `end_col`, and `severity`
--- - lnum: (number) Limit diagnostics to the given line number. --- are guaranteed to be present.
--- - 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.
function M.get(bufnr, opts) function M.get(bufnr, opts)
vim.validate({ vim.validate({
bufnr = { bufnr, 'n', true }, bufnr = { bufnr, 'n', true },
@ -962,11 +1032,9 @@ end
--- ---
---@param bufnr? integer Buffer number to get diagnostics from. Use 0 for ---@param bufnr? integer Buffer number to get diagnostics from. Use 0 for
--- current buffer or nil for all buffers. --- current buffer or nil for all buffers.
---@param opts? table A table with the following keys: ---@param opts? vim.diagnostic.GetOpts
--- - namespace: (number) Limit diagnostics to the given namespace. ---@return table : Table with actually present severity values as keys
--- - lnum: (number) Limit diagnostics to the given line number. --- (see |diagnostic-severity|) and integer counts as values.
--- - severity: See |diagnostic-severity|.
---@return table A table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values.
function M.count(bufnr, opts) function M.count(bufnr, opts)
vim.validate({ vim.validate({
bufnr = { bufnr, 'n', true }, bufnr = { bufnr, 'n', true },
@ -984,8 +1052,8 @@ end
--- Get the previous diagnostic closest to the cursor position. --- Get the previous diagnostic closest to the cursor position.
--- ---
---@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ---@param opts? vim.diagnostic.GotoOpts
---@return vim.Diagnostic? Previous diagnostic ---@return vim.Diagnostic? : Previous diagnostic
function M.get_prev(opts) function M.get_prev(opts)
opts = opts or {} opts = opts or {}
@ -998,9 +1066,9 @@ end
--- Return the position of the previous diagnostic in the current buffer. --- Return the position of the previous diagnostic in the current buffer.
--- ---
---@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ---@param opts? vim.diagnostic.GotoOpts
---@return table|false: Previous diagnostic position as a (row, col) tuple or false if there is no ---@return table|false: Previous diagnostic position as a `(row, col)` tuple
--- prior diagnostic --- or `false` if there is no prior diagnostic.
function M.get_prev_pos(opts) function M.get_prev_pos(opts)
local prev = M.get_prev(opts) local prev = M.get_prev(opts)
if not prev then if not prev then
@ -1011,14 +1079,14 @@ function M.get_prev_pos(opts)
end end
--- Move to the previous diagnostic in the current buffer. --- Move to the previous diagnostic in the current buffer.
---@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ---@param opts? vim.diagnostic.GotoOpts
function M.goto_prev(opts) function M.goto_prev(opts)
return diagnostic_move_pos(opts, M.get_prev_pos(opts)) return diagnostic_move_pos(opts, M.get_prev_pos(opts))
end end
--- Get the next diagnostic closest to the cursor position. --- Get the next diagnostic closest to the cursor position.
--- ---
---@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ---@param opts? vim.diagnostic.GotoOpts
---@return vim.Diagnostic? : Next diagnostic ---@return vim.Diagnostic? : Next diagnostic
function M.get_next(opts) function M.get_next(opts)
opts = opts or {} opts = opts or {}
@ -1032,8 +1100,8 @@ end
--- Return the position of the next diagnostic in the current buffer. --- Return the position of the next diagnostic in the current buffer.
--- ---
---@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ---@param opts? vim.diagnostic.GotoOpts
---@return table|false : Next diagnostic position as a (row, col) tuple or false if no next ---@return table|false : Next diagnostic position as a `(row, col)` tuple or false if no next
--- diagnostic. --- diagnostic.
function M.get_next_pos(opts) function M.get_next_pos(opts)
local next = M.get_next(opts) local next = M.get_next(opts)
@ -1046,7 +1114,6 @@ end
--- A table with the following keys: --- A table with the following keys:
--- @class vim.diagnostic.GetOpts --- @class vim.diagnostic.GetOpts
--- @inlinedoc
--- ---
--- Limit diagnostics to the given namespace. --- Limit diagnostics to the given namespace.
--- @field namespace? integer --- @field namespace? integer
@ -1059,13 +1126,10 @@ end
--- Configuration table with the following keys: --- Configuration table with the following keys:
--- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts --- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts
--- @inlinedoc
--- ---
--- Only consider diagnostics from the given namespace. --- Cursor position as a `(row, col)` tuple.
--- @field namespace integer --- See |nvim_win_get_cursor()|.
--- --- (default: current cursor position)
--- Cursor position as a (row, col) tuple.
--- See |nvim_win_get_cursor()|. Defaults to the current cursor position.
--- @field cursor_position? {[1]:integer,[2]:integer} --- @field cursor_position? {[1]:integer,[2]:integer}
--- ---
--- Whether to loop around file or not. Similar to 'wrapscan'. --- Whether to loop around file or not. Similar to 'wrapscan'.
@ -1075,11 +1139,10 @@ end
--- See |diagnostic-severity|. --- See |diagnostic-severity|.
--- @field severity vim.diagnostic.Severity --- @field severity vim.diagnostic.Severity
--- ---
--- If "true", call |vim.diagnostic.open_float()| --- If `true`, call |vim.diagnostic.open_float()| after moving.
--- after moving. If a table, pass the table as the {opts} parameter --- If a table, pass the table as the {opts} parameter to |vim.diagnostic.open_float()|.
--- to |vim.diagnostic.open_float()|. Unless overridden, the float will show --- Unless overridden, the float will show diagnostics at the new cursor
--- diagnostics at the new cursor position (as if "cursor" were passed to --- position (as if "cursor" were passed to the "scope" option).
--- the "scope" option).
--- (default: `true`) --- (default: `true`)
--- @field float? boolean|vim.diagnostic.Opts.Float --- @field float? boolean|vim.diagnostic.Opts.Float
--- ---
@ -1141,7 +1204,7 @@ M.handlers.signs = {
-- Handle legacy diagnostic sign definitions -- Handle legacy diagnostic sign definitions
-- These were deprecated in 0.10 and will be removed in 0.12 -- These were deprecated in 0.10 and will be removed in 0.12
if opts.signs and not opts.signs.text and not opts.signs.numhl and not opts.signs.texthl then if opts.signs and not opts.signs.text and not opts.signs.numhl then
for _, v in ipairs({ 'Error', 'Warn', 'Info', 'Hint' }) do for _, v in ipairs({ 'Error', 'Warn', 'Info', 'Hint' }) do
local name = string.format('DiagnosticSign%s', v) local name = string.format('DiagnosticSign%s', v)
local sign = vim.fn.sign_getdefined(name)[1] local sign = vim.fn.sign_getdefined(name)[1]
@ -1476,7 +1539,7 @@ end
--- without saving them or to display only a subset of --- without saving them or to display only a subset of
--- diagnostics. May not be used when {namespace} --- diagnostics. May not be used when {namespace}
--- or {bufnr} is nil. --- or {bufnr} is nil.
---@param opts? vim.diagnostic.Opts (table) Display options. See |vim.diagnostic.config()|. ---@param opts? vim.diagnostic.Opts Display options.
function M.show(namespace, bufnr, diagnostics, opts) function M.show(namespace, bufnr, diagnostics, opts)
vim.validate({ vim.validate({
namespace = { namespace, 'n', true }, namespace = { namespace, 'n', true },
@ -1552,46 +1615,7 @@ end
--- Show diagnostics in a floating window. --- Show diagnostics in a floating window.
--- ---
---@param opts vim.diagnostic.Opts.Float? (table?) Configuration table with the same keys ---@param opts vim.diagnostic.Opts.Float?
--- 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? float_bufnr ---@return integer? float_bufnr
---@return integer? win_id ---@return integer? win_id
function M.open_float(opts, ...) function M.open_float(opts, ...)
@ -1963,8 +1987,7 @@ end
--- WARNING filename:27:3: Variable 'foo' does not exist --- WARNING filename:27:3: Variable 'foo' does not exist
--- ``` --- ```
--- ---
--- This can be parsed into a diagnostic |diagnostic-structure| --- This can be parsed into |vim.Diagnostic| structure with:
--- with:
--- ---
--- ```lua --- ```lua
--- local s = "WARNING filename:27:3: Variable 'foo' does not exist" --- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
@ -1975,14 +1998,14 @@ end
--- ---
---@param str string String to parse diagnostics from. ---@param str string String to parse diagnostics from.
---@param pat string Lua pattern with capture groups. ---@param pat string Lua pattern with capture groups.
---@param groups string[] List of fields in a |diagnostic-structure| to ---@param groups string[] List of fields in a |vim.Diagnostic| structure to
--- associate with captures from {pat}. --- associate with captures from {pat}.
---@param severity_map table A table mapping the severity field from {groups} ---@param severity_map table A table mapping the severity field from {groups}
--- with an item from |vim.diagnostic.severity|. --- with an item from |vim.diagnostic.severity|.
---@param defaults table? Table of default values for any fields not listed in {groups}. ---@param defaults table? Table of default values for any fields not listed in {groups}.
--- When omitted, numeric values default to 0 and "severity" defaults to --- When omitted, numeric values default to 0 and "severity" defaults to
--- ERROR. --- ERROR.
---@return vim.Diagnostic?: |diagnostic-structure| or `nil` if {pat} fails to match {str}. ---@return vim.Diagnostic?: |vim.Diagnostic| structure or `nil` if {pat} fails to match {str}.
function M.match(str, pat, groups, severity_map, defaults) function M.match(str, pat, groups, severity_map, defaults)
vim.validate({ vim.validate({
str = { str, 's' }, str = { str, 's' },
@ -2030,8 +2053,8 @@ local errlist_type_map = {
--- Convert a list of diagnostics to a list of quickfix items that can be --- Convert a list of diagnostics to a list of quickfix items that can be
--- passed to |setqflist()| or |setloclist()|. --- passed to |setqflist()| or |setloclist()|.
--- ---
---@param diagnostics vim.Diagnostic[] List of diagnostics |diagnostic-structure|. ---@param diagnostics vim.Diagnostic[]
---@return table[] of quickfix list items |setqflist-what| ---@return table[] : Quickfix list items |setqflist-what|
function M.toqflist(diagnostics) function M.toqflist(diagnostics)
vim.validate({ vim.validate({
diagnostics = { diagnostics = {
@ -2071,7 +2094,7 @@ end
--- Convert a list of quickfix items to a list of diagnostics. --- Convert a list of quickfix items to a list of diagnostics.
--- ---
---@param list table[] List of quickfix items from |getqflist()| or |getloclist()|. ---@param list table[] List of quickfix items from |getqflist()| or |getloclist()|.
---@return vim.Diagnostic[] array of |diagnostic-structure| ---@return vim.Diagnostic[]
function M.fromqflist(list) function M.fromqflist(list)
vim.validate({ vim.validate({
list = { list = {

17
runtime/lua/vim/lsp.lua
View File

@ -961,16 +961,15 @@ end
--- ---
--- Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result. --- Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result.
--- Parameters are the same as |vim.lsp.buf_request_all()| but the result is --- Parameters are the same as |vim.lsp.buf_request_all()| but the result is
--- different. Waits a maximum of {timeout_ms} (default 1000) ms. --- different. Waits a maximum of {timeout_ms}.
--- ---
---@param bufnr (integer) Buffer handle, or 0 for current. ---@param bufnr integer Buffer handle, or 0 for current.
---@param method (string) LSP method name ---@param method string LSP method name
---@param params (table|nil) Parameters to send to the server ---@param params table? Parameters to send to the server
---@param timeout_ms (integer|nil) Maximum time in milliseconds to wait for a ---@param timeout_ms integer? Maximum time in milliseconds to wait for a result.
--- result. Defaults to 1000 --- (default: `1000`)
--- ---@return table<integer, {err: lsp.ResponseError, result: any}>? result Map of client_id:request_result.
---@return table<integer, {err: lsp.ResponseError, result: any}>|nil (table) result Map of client_id:request_result. ---@return string? err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil.
---@return string|nil err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil.
function lsp.buf_request_sync(bufnr, method, params, timeout_ms) function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
local request_results local request_results

47
runtime/lua/vim/lsp/client.lua
View File

@ -11,6 +11,24 @@ local validate = vim.validate
--- @alias vim.lsp.client.on_exit_cb fun(code: integer, signal: integer, client_id: integer) --- @alias vim.lsp.client.on_exit_cb fun(code: integer, signal: integer, client_id: integer)
--- @alias vim.lsp.client.before_init_cb fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig) --- @alias vim.lsp.client.before_init_cb fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
--- @class vim.lsp.Client.Flags
--- @inlinedoc
---
--- Allow using incremental sync for buffer edits
--- (defailt: `true`)
--- @field allow_incremental_sync? boolean
---
--- Debounce `didChange` notifications to the server by the given number in milliseconds.
--- No debounce occurs if `nil`.
--- (default: `150`)
--- @field debounce_text_changes integer
---
--- Milliseconds to wait for server to exit cleanly after sending the
--- "shutdown" request before sending kill -15. If set to false, nvim exits
--- immediately after sending the "shutdown" request to the server.
--- (default: `false`)
--- @field exit_timeout integer|false
--- @class vim.lsp.ClientConfig --- @class vim.lsp.ClientConfig
--- command string[] that launches the language --- command string[] that launches the language
--- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like --- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
@ -55,8 +73,8 @@ local validate = vim.validate
--- Map of language server method names to |lsp-handler| --- Map of language server method names to |lsp-handler|
--- @field handlers? table<string,function> --- @field handlers? table<string,function>
--- ---
--- Map with language server specific settings. These are returned to the language server if --- Map with language server specific settings.
--- requested via `workspace/configuration`. Keys are case-sensitive. --- See the {settings} in |vim.lsp.Client|.
--- @field settings? table --- @field settings? table
--- ---
--- Table that maps string of clientside commands to user-defined functions. --- Table that maps string of clientside commands to user-defined functions.
@ -87,36 +105,29 @@ local validate = vim.validate
--- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters --- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
--- being sent to the server and `config` is the config that was passed to |vim.lsp.start_client()|. --- being sent to the server and `config` is the config that was passed to |vim.lsp.start_client()|.
--- You can use this to modify parameters before they are sent. --- You can use this to modify parameters before they are sent.
--- @field before_init? vim.lsp.client.before_init_cb --- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
--- ---
--- Callback invoked after LSP "initialize", where `result` is a table of `capabilities` --- Callback invoked after LSP "initialize", where `result` is a table of `capabilities`
--- and anything else the server may send. For example, clangd sends --- and anything else the server may send. For example, clangd sends
--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was sent to it. --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was sent to it.
--- You can only modify the `client.offset_encoding` here before any notifications are sent. --- You can only modify the `client.offset_encoding` here before any notifications are sent.
--- @field on_init? elem_or_list<vim.lsp.client.on_init_cb> --- @field on_init? elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>
--- ---
--- Callback invoked on client exit. --- Callback invoked on client exit.
--- - code: exit code of the process --- - code: exit code of the process
--- - signal: number describing the signal used to terminate (if any) --- - signal: number describing the signal used to terminate (if any)
--- - client_id: client handle --- - client_id: client handle
--- @field on_exit? elem_or_list<vim.lsp.client.on_exit_cb> --- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)>
--- ---
--- Callback invoked when client attaches to a buffer. --- Callback invoked when client attaches to a buffer.
--- @field on_attach? elem_or_list<vim.lsp.client.on_attach_cb> --- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>
--- ---
--- Passed directly to the language server in the initialize request. Invalid/empty values will --- Passed directly to the language server in the initialize request. Invalid/empty values will
--- (default: "off") --- (default: "off")
--- @field trace? 'off'|'messages'|'verbose' --- @field trace? 'off'|'messages'|'verbose'
--- ---
--- A table with flags for the client. The current (experimental) flags are: --- A table with flags for the client. The current (experimental) flags are:
--- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits --- @field flags? vim.lsp.Client.Flags
--- - debounce_text_changes (number, default 150): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce
--- occurs if nil
--- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to
--- exit cleanly after sending the "shutdown" request before sending kill -15.
--- If set to false, nvim exits immediately after sending the "shutdown" request to the server.
--- @field flags? table
--- ---
--- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization. --- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization.
--- @field root_dir? string --- @field root_dir? string
@ -189,8 +200,14 @@ local validate = vim.validate
--- Client commands take precedence over the global command registry. --- Client commands take precedence over the global command registry.
--- @field commands table<string,fun(command: lsp.Command, ctx: table)> --- @field commands table<string,fun(command: lsp.Command, ctx: table)>
--- ---
--- Map with language server specific settings. These are returned to the
--- language server if requested via `workspace/configuration`. Keys are
--- case-sensitive.
--- @field settings table --- @field settings table
--- @field flags table ---
--- A table with flags for the client. The current (experimental) flags are:
--- @field flags vim.lsp.Client.Flags
---
--- @field get_language_id fun(bufnr: integer, filetype: string): string --- @field get_language_id fun(bufnr: integer, filetype: string): string
--- ---
--- The capabilities provided by the client (editor or tool) --- The capabilities provided by the client (editor or tool)

2
runtime/lua/vim/lsp/diagnostic.lua
View File

@ -321,7 +321,7 @@ end
---@param _ lsp.ResponseError? ---@param _ lsp.ResponseError?
---@param result lsp.DocumentDiagnosticReport ---@param result lsp.DocumentDiagnosticReport
---@param ctx lsp.HandlerContext ---@param ctx lsp.HandlerContext
---@param config table Configuration table (see |vim.diagnostic.config()|). ---@param config vim.diagnostic.Opts Configuration table (see |vim.diagnostic.config()|).
function M.on_diagnostic(_, result, ctx, config) function M.on_diagnostic(_, result, ctx, config)
if result == nil or result.kind == 'unchanged' then if result == nil or result.kind == 'unchanged' then
return return

2
runtime/lua/vim/lsp/semantic_tokens.lua
View File

@ -572,7 +572,7 @@ local M = {}
--- ---
---@param bufnr integer ---@param bufnr integer
---@param client_id integer ---@param client_id integer
---@param opts (nil|table) Optional keyword arguments ---@param opts? table Optional keyword arguments
--- - debounce (integer, default: 200): Debounce token requests --- - debounce (integer, default: 200): Debounce token requests
--- to the server by the given number in milliseconds --- to the server by the given number in milliseconds
function M.start(bufnr, client_id, opts) function M.start(bufnr, client_id, opts)

14
runtime/lua/vim/shared.lua
View File

@ -102,7 +102,7 @@ end
--- @param s string String to split --- @param s string String to split
--- @param sep string Separator or pattern --- @param sep string Separator or pattern
--- @param opts? vim.gsplit.Opts Keyword arguments |kwargs|: --- @param opts? vim.gsplit.Opts Keyword arguments |kwargs|:
--- @return fun():string|nil (function) Iterator over the split components --- @return fun():string? : Iterator over the split components
function vim.gsplit(s, sep, opts) function vim.gsplit(s, sep, opts)
local plain --- @type boolean? local plain --- @type boolean?
local trimempty = false local trimempty = false
@ -245,8 +245,8 @@ end
--- Apply a function to all values of a table. --- Apply a function to all values of a table.
--- ---
---@generic T ---@generic T
---@param func fun(value: T): any (function) Function ---@param func fun(value: T): any Function
---@param t table<any, T> (table) Table ---@param t table<any, T> Table
---@return table : Table of transformed values ---@return table : Table of transformed values
function vim.tbl_map(func, t) function vim.tbl_map(func, t)
vim.validate({ func = { func, 'c' }, t = { t, 't' } }) vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@ -570,8 +570,10 @@ end
--- ---
---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
--- ---
---@param t table Dict-like table ---@generic T: table, K, V
---@return function # |for-in| iterator over sorted keys and their values ---@param t T Dict-like table
---@return fun(table: table<K, V>, index?: K):K, V # |for-in| iterator over sorted keys and their values
---@return T
function vim.spairs(t) function vim.spairs(t)
vim.validate({ t = { t, 't' } }) vim.validate({ t = { t, 't' } })
--- @cast t table<any,any> --- @cast t table<any,any>
@ -1018,7 +1020,7 @@ do
--- - |Ringbuf:clear()| --- - |Ringbuf:clear()|
--- ---
---@param size integer ---@param size integer
---@return vim.Ringbuf ringbuf (table) ---@return vim.Ringbuf ringbuf
function vim.ringbuf(size) function vim.ringbuf(size)
local ringbuf = { local ringbuf = {
_items = {}, _items = {},

15
scripts/gen_vimdoc.lua
View File

@ -536,7 +536,8 @@ local function render_fields_or_params(xs, generics, classes, exclude_types)
end end
--- @param class nvim.luacats.parser.class --- @param class nvim.luacats.parser.class
local function render_class(class) --- @param classes table<string,nvim.luacats.parser.class>
local function render_class(class, classes)
if class.access or class.nodoc or class.inlinedoc then if class.access or class.nodoc or class.inlinedoc then
return return
end end
@ -548,13 +549,14 @@ local function render_class(class)
if class.parent then if class.parent then
local txt = fmt('Extends: |%s|', class.parent) local txt = fmt('Extends: |%s|', class.parent)
table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH)) table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH))
table.insert(ret, '\n')
end end
if class.desc then if class.desc then
table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
end end
local fields_txt = render_fields_or_params(class.fields) local fields_txt = render_fields_or_params(class.fields, nil, classes)
if not fields_txt:match('^%s*$') then if not fields_txt:match('^%s*$') then
table.insert(ret, '\n Fields: ~\n') table.insert(ret, '\n Fields: ~\n')
table.insert(ret, fields_txt) table.insert(ret, fields_txt)
@ -564,13 +566,12 @@ local function render_class(class)
return table.concat(ret) return table.concat(ret)
end end
--- @param cls table<string,nvim.luacats.parser.class> --- @param classes table<string,nvim.luacats.parser.class>
local function render_classes(cls) local function render_classes(classes)
local ret = {} --- @type string[] local ret = {} --- @type string[]
--- @diagnostic disable-next-line:no-unknown for _, class in vim.spairs(classes) do
for _, class in vim.spairs(cls) do ret[#ret + 1] = render_class(class, classes)
ret[#ret + 1] = render_class(class)
end end
return table.concat(ret) return table.concat(ret)

2
scripts/luacats_grammar.lua
View File

@ -170,7 +170,7 @@ local grammar = P {
ltype = parenOpt(v.ty_union), ltype = parenOpt(v.ty_union),
ty_union = v.ty_opt * rep(Pf('|') * v.ty_opt), ty_union = v.ty_opt * rep(Pf('|') * v.ty_opt),
ty = v.ty_fun + ident + v.ty_table + literal, ty = v.ty_fun + ident + v.ty_table + literal + paren(v.ty),
ty_param = Pf('<') * comma1(v.ltype) * fill * P('>'), ty_param = Pf('<') * comma1(v.ltype) * fill * P('>'),
ty_opt = v.ty * opt(v.ty_param) * opt(P('[]')) * opt(P('?')), ty_opt = v.ty * opt(v.ty_param) * opt(P('[]')) * opt(P('?')),
ty_index = (Pf('[') * v.ltype * Pf(']')), ty_index = (Pf('[') * v.ltype * Pf(']')),

9
test/functional/script/luacats_grammar_spec.lua
View File

@ -130,4 +130,13 @@ describe('luacats grammar', function()
type = 'b', type = 'b',
desc = 'desc', desc = 'desc',
}) })
test(
'@field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)',
{
kind = 'field',
name = 'prefix?',
type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)',
}
)
end) end)