diff options
Diffstat (limited to 'runtime/doc/diagnostic.txt')
| -rw-r--r-- | runtime/doc/diagnostic.txt | 609 |
1 files changed, 357 insertions, 252 deletions
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 7f5c809ac3..c9e783ca62 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -38,24 +38,6 @@ optionally supplied). A good rule of thumb is that if a method is meant to modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it requires a namespace. - *diagnostic-structure* -A diagnostic is a Lua table with the following keys. Required keys are -indicated with (+): - - bufnr: Buffer number - lnum(+): The starting line of the diagnostic - end_lnum: The final line of the diagnostic - col(+): The starting column of the diagnostic - end_col: The final column of the diagnostic - severity: The severity of the diagnostic |vim.diagnostic.severity| - message(+): The diagnostic text - source: The source of the diagnostic - code: The diagnostic code - user_data: Arbitrary data plugins or users can add - -Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based -rows and columns). |api-indexing| - *vim.diagnostic.severity* *diagnostic-severity* The "severity" key in a diagnostic is one of the values defined in `vim.diagnostic.severity`: @@ -317,12 +299,24 @@ SIGNS *diagnostic-signs* Signs are defined for each diagnostic severity. The default text for each sign is the first letter of the severity name (for example, "E" for ERROR). Signs -can be customized using the following: >vim +can be customized with |vim.diagnostic.config()|. Example: >lua - sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl= - sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl= - sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl= - sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl= + -- Highlight entire line for errors + -- Highlight the line number for warnings + vim.diagnostic.config({ + signs = { + text = { + [vim.diagnostic.severity.ERROR] = '', + [vim.diagnostic.severity.WARN] = '', + }, + linehl = { + [vim.diagnostic.severity.ERROR] = 'ErrorMsg', + }, + numhl = { + [vim.diagnostic.severity.WARN] = 'WarningMsg', + }, + }, + }) When the "severity_sort" option is set (see |vim.diagnostic.config()|) the priority of each sign depends on the severity of the associated diagnostic. @@ -349,6 +343,236 @@ Example: >lua ============================================================================== Lua module: vim.diagnostic *diagnostic-api* +*vim.Diagnostic* + *diagnostic-structure* + + Diagnostics use the same indexing as the rest of the Nvim API (i.e. + 0-based rows and columns). |api-indexing| + + Fields: ~ + • {bufnr}? (`integer`) Buffer number + • {lnum} (`integer`) The starting line of the diagnostic + (0-indexed) + • {end_lnum}? (`integer`) The final line of the diagnostic (0-indexed) + • {col} (`integer`) The starting column of the diagnostic + (0-indexed) + • {end_col}? (`integer`) The final column of the diagnostic + (0-indexed) + • {severity}? (`vim.diagnostic.Severity`) The severity of the + diagnostic |vim.diagnostic.severity| + • {message} (`string`) The diagnostic text + • {source}? (`string`) The source of the diagnostic + • {code}? (`string|integer`) The diagnostic code + • {_tags}? (`{ deprecated: boolean, unnecessary: boolean}`) + • {user_data}? (`any`) arbitrary data plugins can add + • {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* + + Fields: ~ + • {name} (`string`) + • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|. + • {user_data} (`table`) + • {disabled}? (`boolean`) + +*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: ~ + • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) + Use underline for diagnostics. + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, 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. + • {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* + + Fields: ~ + • {bufnr}? (`integer`, default: current buffer) Buffer number + to show diagnostics from. + • {namespace}? (`integer`) Limit diagnostics to the given namespace + • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, 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}? (`integer|{[1]:integer,[2]:integer}`) 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}? (`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`) + +*vim.diagnostic.Opts.Signs* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual text + for diagnostics matching the given severity + |diagnostic-severity| + • {priority}? (`integer`, 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<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* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only underline + diagnostics matching the given severity + |diagnostic-severity|. + +*vim.diagnostic.Opts.VirtualText* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show + virtual text for diagnostics matching the given + severity |diagnostic-severity| + • {source}? (`boolean|"if_many"`) 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}? (`integer`) Amount of empty spaces inserted at + the beginning of the virtual text. + • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) + 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. + • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) + Append diagnostic message with suffix. This can + be used to render an LSP diagnostic 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()* Configure diagnostic options globally or for a specific diagnostic namespace. @@ -368,115 +592,56 @@ config({opts}, {namespace}) *vim.diagnostic.config()* then virtual text will not be enabled for those diagnostics. - Note: ~ - • Each of the configuration options below accepts one of the following: - • `false`: Disable this feature - • `true`: Enable this feature, use default settings. - • `table`: Enable this feature with overrides. Use an empty table to - use default values. - • `function`: Function with signature (namespace, bufnr) that returns - any of the above. + Parameters: ~ + • {opts} (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve + the current configuration. Otherwise, a configuration + table (see |vim.diagnostic.Opts|). + • {namespace} (`integer?`) Update the options for the given namespace. + When omitted, update the global diagnostic options. + + Return: ~ + (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is + omitted. See |vim.diagnostic.Opts|. + +count({bufnr}, {opts}) *vim.diagnostic.count()* + Get current diagnostics count. Parameters: ~ - • {opts} (table|nil) 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 -< + • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for + current buffer or nil for all buffers. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. - • signs: (default true) Use signs for diagnostics. - Options: - • severity: Only show signs for diagnostics matching - the given severity |diagnostic-severity| - • priority: (number, default 10) Base priority to use - for signs. When {severity_sort} is used, the priority - of a sign is adjusted based on its severity. - Otherwise, all signs use the same priority. - - • 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|nil) Update the options for the given namespace. - When omitted, update the global diagnostic options. + Return: ~ + (`table`) Table with actually present severity values as keys (see + |diagnostic-severity|) and integer counts as values. disable({bufnr}, {namespace}) *vim.diagnostic.disable()* Disable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, disable diagnostics in all buffers. - • {namespace} (integer|nil) Only disable diagnostics for the given + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, disable diagnostics in all buffers. + • {namespace} (`integer?`) Only disable diagnostics for the given namespace. enable({bufnr}, {namespace}) *vim.diagnostic.enable()* Enable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, enable diagnostics in all buffers. - • {namespace} (integer|nil) Only enable diagnostics for the given + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, enable diagnostics in all buffers. + • {namespace} (`integer?`) Only enable diagnostics for the given namespace. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. Parameters: ~ - • {list} table[] List of quickfix items from |getqflist()| or + • {list} (`table[]`) List of quickfix items from |getqflist()| or |getloclist()|. Return: ~ - Diagnostic [] array of |diagnostic-structure| + (`vim.Diagnostic[]`) See |vim.Diagnostic|. get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. @@ -485,96 +650,79 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* diagnostics in a buffer, use |vim.diagnostic.set()|. Parameters: ~ - • {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0 - for current buffer or nil for all buffers. - • {opts} (table|nil) A table with the following keys: - • namespace: (number) Limit diagnostics to the given - namespace. - • lnum: (number) Limit diagnostics to the given line number. - • severity: See |diagnostic-severity|. + • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for + current buffer or nil for all buffers. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. Return: ~ - Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present. + (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and + `severity` are guaranteed to be present. See |vim.Diagnostic|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. Parameters: ~ - • {namespace} (integer) Diagnostic namespace + • {namespace} (`integer`) Diagnostic namespace Return: ~ - (table) Namespace metadata + (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|. get_namespaces() *vim.diagnostic.get_namespaces()* Get current diagnostic namespaces. Return: ~ - (table) A list of active diagnostic namespaces |vim.diagnostic|. + (`table<integer,vim.diagnostic.NS>`) List of active diagnostic + namespaces |vim.diagnostic|. get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - Diagnostic|nil Next diagnostic + (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. get_next_pos({opts}) *vim.diagnostic.get_next_pos()* Return the position of the next diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - table|false Next diagnostic position as a (row, col) tuple or false if - no next diagnostic. + (`table|false`) Next diagnostic position as a `(row, col)` tuple or + false if no next diagnostic. get_prev({opts}) *vim.diagnostic.get_prev()* Get the previous diagnostic closest to the cursor position. Parameters: ~ - • {opts} nil|table See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - Diagnostic|nil Previous diagnostic + (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return the position of the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - table|false Previous diagnostic position as a (row, col) tuple or - false if there is no prior diagnostic + (`table|false`) Previous diagnostic position as a `(row, col)` tuple + or `false` if there is no prior diagnostic. goto_next({opts}) *vim.diagnostic.goto_next()* Move to the next diagnostic. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only consider diagnostics from the given - namespace. - • cursor_position: (cursor position) Cursor position as a - (row, col) tuple. See |nvim_win_get_cursor()|. Defaults to - the current cursor position. - • wrap: (boolean, default true) Whether to loop around file or - not. Similar to 'wrapscan'. - • severity: See |diagnostic-severity|. - • float: (boolean or table, default true) If "true", call - |vim.diagnostic.open_float()| after moving. If a table, pass - the table as the {opts} parameter to - |vim.diagnostic.open_float()|. Unless overridden, the float - will show diagnostics at the new cursor position (as if - "cursor" were passed to the "scope" option). - • win_id: (number, default 0) Window ID + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. hide({namespace}, {bufnr}) *vim.diagnostic.hide()* Hide currently displayed diagnostics. @@ -587,22 +735,22 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* |vim.diagnostic.disable()|. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all - namespaces. - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, hide diagnostics in all buffers. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide + diagnostics from all namespaces. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, hide diagnostics in all buffers. is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()* Check whether diagnostics are disabled in a given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - • {namespace} (integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are - disabled in {bufnr}. Otherwise, only checks if - diagnostics from {namespace} are disabled. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, checks + if all diagnostics are disabled in {bufnr}. Otherwise, + only checks if diagnostics from {namespace} are disabled. Return: ~ - (boolean) + (`boolean`) *vim.diagnostic.match()* match({str}, {pat}, {groups}, {severity_map}, {defaults}) @@ -612,7 +760,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) WARNING filename:27:3: Variable 'foo' does not exist < - This can be parsed into a diagnostic |diagnostic-structure| with: >lua + This can be parsed into |vim.Diagnostic| structure with: >lua local s = "WARNING filename:27:3: Variable 'foo' does not exist" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local groups = { "severity", "lnum", "col", "message" } @@ -620,75 +768,30 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) < Parameters: ~ - • {str} (string) String to parse diagnostics from. - • {pat} (string) Lua pattern with capture groups. - • {groups} (table) List of fields in a |diagnostic-structure| to - associate with captures from {pat}. - • {severity_map} (table) A table mapping the severity field from + • {str} (`string`) String to parse diagnostics from. + • {pat} (`string`) Lua pattern with capture groups. + • {groups} (`string[]`) List of fields in a |vim.Diagnostic| + structure to associate with captures from {pat}. + • {severity_map} (`table`) A table mapping the severity field from {groups} with an item from |vim.diagnostic.severity|. - • {defaults} (table|nil) Table of default values for any fields not + • {defaults} (`table?`) Table of default values for any fields not listed in {groups}. When omitted, numeric values default to 0 and "severity" defaults to ERROR. Return: ~ - Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to - match {str}. + (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails + to match {str}. -open_float({opts}, {...}) *vim.diagnostic.open_float()* +open_float({opts}) *vim.diagnostic.open_float()* Show diagnostics in a floating window. Parameters: ~ - • {opts} (table|nil) Configuration table with the same keys as - |vim.lsp.util.open_floating_preview()| in addition to the - following: - • bufnr: (number) Buffer number to show diagnostics from. - Defaults to the current buffer. - • namespace: (number) Limit diagnostics to the given namespace - • scope: (string, default "line") Show diagnostics from the - whole buffer ("buffer"), the current cursor line ("line"), - or the current cursor position ("cursor"). Shorthand - versions are also accepted ("c" for "cursor", "l" for - "line", "b" for "buffer"). - • pos: (number or table) If {scope} is "line" or "cursor", use - this position rather than the cursor position. If a number, - interpreted as a line number; otherwise, a (row, col) tuple. - • severity_sort: (default false) Sort diagnostics by severity. - Overrides the setting from |vim.diagnostic.config()|. - • severity: See |diagnostic-severity|. Overrides the setting - from |vim.diagnostic.config()|. - • header: (string or table) String to use as the header for - the floating window. If a table, it is interpreted as a - [text, hl_group] tuple. Overrides the setting from - |vim.diagnostic.config()|. - • source: (boolean or string) Include the diagnostic source in - the message. Use "if_many" to only show sources if there is - more than one source of diagnostics in the buffer. - Otherwise, any truthy value means to always show the - diagnostic source. Overrides the setting from - |vim.diagnostic.config()|. - • format: (function) A function that takes a diagnostic as - input and returns a string. The return value is the text - used to display the diagnostic. Overrides the setting from - |vim.diagnostic.config()|. - • prefix: (function, string, or table) Prefix each diagnostic - in the floating window. If a function, it must have the - signature (diagnostic, i, total) -> (string, string), where - {i} is the index of the diagnostic being evaluated and - {total} is the total number of diagnostics displayed in the - window. The function should return a string which is - prepended to each diagnostic in the window as well as an - (optional) highlight group which will be used to highlight - the prefix. If {prefix} is a table, it is interpreted as a - [text, hl_group] tuple as in |nvim_echo()|; otherwise, if - {prefix} is a string, it is prepended to each diagnostic in - the window with no highlight. Overrides the setting from - |vim.diagnostic.config()|. - • suffix: Same as {prefix}, but appends the text to the - diagnostic instead of prepending it. Overrides the setting - from |vim.diagnostic.config()|. + • {opts} (`vim.diagnostic.Opts.Float?`) See + |vim.diagnostic.Opts.Float|. - Return: ~ - integer|nil, integer|nil: ({float_bufnr}, {win_id}) + Return (multiple): ~ + (`integer?`) float_bufnr + (`integer?`) win_id reset({namespace}, {bufnr}) *vim.diagnostic.reset()* Remove all diagnostics from the given namespace. @@ -699,76 +802,78 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()* re-displayed, use |vim.diagnostic.hide()|. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all - namespaces. - • {bufnr} (integer|nil) Remove diagnostics for the given buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, remove + diagnostics from all namespaces. + • {bufnr} (`integer?`) Remove diagnostics for the given buffer. When omitted, diagnostics are removed for all buffers. set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* Set diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (integer) The diagnostic namespace - • {bufnr} (integer) Buffer number - • {diagnostics} (table) A list of diagnostic items - |diagnostic-structure| - • {opts} (table|nil) Display options to pass to - |vim.diagnostic.show()| + • {namespace} (`integer`) The diagnostic namespace + • {bufnr} (`integer`) Buffer number + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. + • {opts} (`vim.diagnostic.Opts?`) Display options to pass to + |vim.diagnostic.show()|. See |vim.diagnostic.Opts|. setloclist({opts}) *vim.diagnostic.setloclist()* Add buffer diagnostics to the location list. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {opts} (`table?`) Configuration table with the following keys: + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • winnr: (number, default 0) Window number to set location - list for. - • open: (boolean, default true) Open the location list after - setting. - • title: (string) Title of the location list. Defaults to + • {winnr}? (`integer`, default: `0`) Window number to set + location list for. + • {open}? (`boolean`, default: `true`) Open the location list + after setting. + • {title}? (`string`) Title of the location list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. setqflist({opts}) *vim.diagnostic.setqflist()* Add all diagnostics to the quickfix list. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {opts} (`table?`) Configuration table with the following keys: + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • open: (boolean, default true) Open quickfix list after - setting. - • title: (string) Title of quickfix list. Defaults to + • {open}? (`boolean`, default: `true`) Open quickfix list + after setting. + • {title}? (`string`) Title of quickfix list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. *vim.diagnostic.show()* show({namespace}, {bufnr}, {diagnostics}, {opts}) Display diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, show diagnostics from all - namespaces. - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, show + diagnostics from all namespaces. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When omitted, show diagnostics in all buffers. - • {diagnostics} (table|nil) The diagnostics to display. When omitted, - use the saved diagnostics for the given namespace and - buffer. This can be used to display a list of - diagnostics without saving them or to display only a - subset of diagnostics. May not be used when {namespace} - or {bufnr} is nil. - • {opts} (table|nil) Display options. See - |vim.diagnostic.config()|. + • {diagnostics} (`vim.Diagnostic[]?`) The diagnostics to display. When + omitted, use the saved diagnostics for the given + namespace and buffer. This can be used to display a + list of diagnostics without saving them or to display + only a subset of diagnostics. May not be used when + {namespace} or {bufnr} is nil. See |vim.Diagnostic|. + • {opts} (`vim.diagnostic.Opts?`) Display options. See + |vim.diagnostic.Opts|. toqflist({diagnostics}) *vim.diagnostic.toqflist()* Convert a list of diagnostics to a list of quickfix items that can be passed to |setqflist()| or |setloclist()|. Parameters: ~ - • {diagnostics} (table) List of diagnostics |diagnostic-structure|. + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. 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: |