diagnostic.txt (48562B)
1 *diagnostic.txt* Diagnostics 2 3 4 NVIM REFERENCE MANUAL 5 6 7 Diagnostic framework *vim.diagnostic* 8 9 Nvim provides a framework for displaying errors or warnings from external 10 tools, otherwise known as "diagnostics". These diagnostics can come from a 11 variety of sources, such as linters or LSP servers. The diagnostic framework 12 is an extension to existing error handling functionality such as the 13 |quickfix| list. 14 15 Type |gO| to see the table of contents. 16 17 ============================================================================== 18 QUICKSTART *diagnostic-quickstart* 19 20 Anything that reports diagnostics is referred to below as a "diagnostic 21 producer". Diagnostic producers need only follow a few simple steps to 22 report diagnostics: 23 24 1. Create a namespace |nvim_create_namespace()|. Note that the namespace must 25 have a name. Anonymous namespaces WILL NOT WORK. 26 2. (Optional) Configure options for the diagnostic namespace 27 |vim.diagnostic.config()|. 28 3. Generate diagnostics. 29 4. Set the diagnostics for the buffer |vim.diagnostic.set()|. 30 5. Repeat from step 3. 31 32 Generally speaking, the API is split between functions meant to be used by 33 diagnostic producers and those meant for diagnostic consumers (i.e. end users 34 who want to read and view the diagnostics for a buffer). The APIs for 35 producers require a {namespace} as their first argument, while those for 36 consumers generally do not require a namespace (though often one may be 37 optionally supplied). A good rule of thumb is that if a method is meant to 38 modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it 39 requires a namespace. 40 41 *vim.diagnostic.severity* *diagnostic-severity* 42 The "severity" key in a diagnostic is one of the values defined in 43 `vim.diagnostic.severity`: > 44 45 vim.diagnostic.severity.ERROR 46 vim.diagnostic.severity.WARN 47 vim.diagnostic.severity.INFO 48 vim.diagnostic.severity.HINT 49 50 Functions that take a severity as an optional parameter (e.g. 51 |vim.diagnostic.get()|) accept one of three forms: 52 53 1. A single |vim.diagnostic.severity| value: >lua 54 55 vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN }) 56 57 2. A table with a "min" or "max" key (or both). This form allows users to 58 specify a range of severities: >lua 59 60 vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } }) 61 3. A list-like table. This form allows filtering for specific severities: >lua 62 63 vim.diagnostic.get(0, { severity = { 64 vim.diagnostic.severity.WARN, 65 vim.diagnostic.severity.INFO, 66 } }) 67 < 68 69 ============================================================================== 70 DEFAULTS *diagnostic-defaults* 71 72 These diagnostic keymaps are created unconditionally when Nvim starts: 73 - `]d` jumps to the next diagnostic in the buffer. |]d-default| 74 - `[d` jumps to the previous diagnostic in the buffer. |[d-default| 75 - `]D` jumps to the last diagnostic in the buffer. |]D-default| 76 - `[D` jumps to the first diagnostic in the buffer. |[D-default| 77 - `<C-w>d` shows diagnostic at cursor in a floating window. |CTRL-W_d-default| 78 79 ============================================================================== 80 HANDLERS *diagnostic-handlers* 81 82 Diagnostics are shown to the user with |vim.diagnostic.show()|. The display of 83 diagnostics is managed through handlers. A handler is a table with a "show" 84 and (optionally) a "hide" function. The "show" function has the signature 85 > 86 function(namespace, bufnr, diagnostics, opts) 87 < 88 and is responsible for displaying or otherwise handling the given 89 diagnostics. The "hide" function takes care of "cleaning up" any actions taken 90 by the "show" function and has the signature 91 > 92 function(namespace, bufnr) 93 < 94 Handlers can be configured with |vim.diagnostic.config()| and added by 95 creating a new key in `vim.diagnostic.handlers` (see 96 |diagnostic-handlers-example|). 97 98 The {opts} table passed to a handler is the full set of configuration options 99 (that is, it is not limited to just the options for the handler itself). The 100 values in the table are already resolved (i.e. if a user specifies a 101 function for a config option, the function has already been evaluated). 102 103 If a diagnostic handler is configured with a "severity" key then the list of 104 diagnostics passed to that handler will be filtered using the value of that 105 key (see example below). 106 107 Nvim provides these handlers by default: "virtual_text", "virtual_lines", 108 "signs", and "underline". 109 110 *diagnostic-handlers-example* 111 The example below creates a new handler that notifies the user of diagnostics 112 with |vim.notify()|: >lua 113 114 -- It's good practice to namespace custom handlers to avoid collisions 115 vim.diagnostic.handlers["my/notify"] = { 116 show = function(namespace, bufnr, diagnostics, opts) 117 -- In our example, the opts table has a "log_level" option 118 local level = opts["my/notify"].log_level 119 120 local name = vim.diagnostic.get_namespace(namespace).name 121 local msg = string.format("%d diagnostics in buffer %d from %s", 122 #diagnostics, 123 bufnr, 124 name) 125 vim.notify(msg, level) 126 end, 127 } 128 129 -- Users can configure the handler 130 vim.diagnostic.config({ 131 ["my/notify"] = { 132 log_level = vim.log.levels.INFO, 133 134 -- This handler will only receive "error" diagnostics. 135 severity = vim.diagnostic.severity.ERROR, 136 } 137 }) 138 < 139 In this example, there is nothing to do when diagnostics are hidden, so we 140 omit the "hide" function. 141 142 Existing handlers can be overridden. For example, use the following to only 143 show a sign for the highest severity diagnostic on a given line: >lua 144 145 -- Create a custom namespace. This will aggregate signs from all other 146 -- namespaces and only show the one with the highest severity on a 147 -- given line 148 local ns = vim.api.nvim_create_namespace("my_namespace") 149 150 -- Get a reference to the original signs handler 151 local orig_signs_handler = vim.diagnostic.handlers.signs 152 153 -- Override the built-in signs handler 154 vim.diagnostic.handlers.signs = { 155 show = function(_, bufnr, _, opts) 156 -- Get all diagnostics from the whole buffer rather than just the 157 -- diagnostics passed to the handler 158 local diagnostics = vim.diagnostic.get(bufnr) 159 160 -- Find the "worst" diagnostic per line 161 local max_severity_per_line = {} 162 for _, d in pairs(diagnostics) do 163 local m = max_severity_per_line[d.lnum] 164 if not m or d.severity < m.severity then 165 max_severity_per_line[d.lnum] = d 166 end 167 end 168 169 -- Pass the filtered diagnostics (with our custom namespace) to 170 -- the original handler 171 local filtered_diagnostics = vim.tbl_values(max_severity_per_line) 172 orig_signs_handler.show(ns, bufnr, filtered_diagnostics, opts) 173 end, 174 hide = function(_, bufnr) 175 orig_signs_handler.hide(ns, bufnr) 176 end, 177 } 178 < 179 180 *diagnostic-toggle-virtual-lines-example* 181 Diagnostic handlers can also be toggled. For example, you might want to toggle 182 the `virtual_lines` handler with the following keymap: >lua 183 184 vim.keymap.set('n', 'gK', function() 185 local new_config = not vim.diagnostic.config().virtual_lines 186 vim.diagnostic.config({ virtual_lines = new_config }) 187 end, { desc = 'Toggle diagnostic virtual_lines' }) 188 < 189 190 *diagnostic-on-jump-example* 191 You can use the `on_jump` option from |vim.diagnostic.jump()| to show the 192 diagnostic that was jumped to using a specific handler. For example, the 193 following uses the `virtual_lines` handler when jumping to a diagnostic: >lua 194 195 --- @param diagnostic? vim.Diagnostic 196 --- @param bufnr integer 197 local function on_jump(diagnostic, bufnr) 198 if not diagnostic then return end 199 200 vim.diagnostic.show( 201 diagnostic.namespace 202 bufnr, 203 { diagnostic }, 204 { virtual_lines = { current_line = true }, virtual_text = false } 205 ) 206 end 207 208 vim.diagnostic.config({ jump = { on_jump = on_jump } }) 209 < 210 *diagnostic-loclist-example* 211 Whenever the |location-list| is opened, the following `show` handler will show 212 the most recent diagnostics: >lua 213 214 vim.diagnostic.handlers.loclist = { 215 show = function(_, _, _, opts) 216 -- Generally don't want it to open on every update 217 opts.loclist.open = opts.loclist.open or false 218 local winid = vim.api.nvim_get_current_win() 219 vim.diagnostic.setloclist(opts.loclist) 220 vim.api.nvim_set_current_win(winid) 221 end 222 } 223 < 224 225 The handler accepts the same options as |vim.diagnostic.setloclist()| and can be 226 configured using |vim.diagnostic.config()|: >lua 227 228 -- Open the location list on every diagnostic change (warnings/errors only). 229 vim.diagnostic.config({ 230 loclist = { 231 open = true, 232 severity = { min = vim.diagnostic.severity.WARN }, 233 } 234 }) 235 < 236 237 ============================================================================== 238 HIGHLIGHTS *diagnostic-highlights* 239 240 All highlights defined for diagnostics begin with `Diagnostic` followed by 241 the type of highlight (e.g., `Sign`, `Underline`, etc.) and the severity (e.g. 242 `Error`, `Warn`, etc.) 243 244 By default, highlights for signs, floating windows, and virtual text are linked to the 245 corresponding default highlight. Underline highlights are not linked and use their 246 own default highlight groups. 247 248 For example, the default highlighting for |hl-DiagnosticSignError| is linked 249 to |hl-DiagnosticError|. To change the default (and therefore the linked 250 highlights), use the |:highlight| command: >vim 251 252 highlight DiagnosticError guifg="BrightRed" 253 < 254 *hl-DiagnosticError* 255 DiagnosticError 256 Used as the base highlight group. 257 Other Diagnostic highlights link to this by default (except Underline) 258 259 *hl-DiagnosticWarn* 260 DiagnosticWarn 261 Used as the base highlight group. 262 Other Diagnostic highlights link to this by default (except Underline) 263 264 *hl-DiagnosticInfo* 265 DiagnosticInfo 266 Used as the base highlight group. 267 Other Diagnostic highlights link to this by default (except Underline) 268 269 *hl-DiagnosticHint* 270 DiagnosticHint 271 Used as the base highlight group. 272 Other Diagnostic highlights link to this by default (except Underline) 273 274 *hl-DiagnosticOk* 275 DiagnosticOk 276 Used as the base highlight group. 277 Other Diagnostic highlights link to this by default (except Underline) 278 279 *hl-DiagnosticVirtualTextError* 280 DiagnosticVirtualTextError 281 Used for "Error" diagnostic virtual text. 282 283 *hl-DiagnosticVirtualTextWarn* 284 DiagnosticVirtualTextWarn 285 Used for "Warn" diagnostic virtual text. 286 287 *hl-DiagnosticVirtualTextInfo* 288 DiagnosticVirtualTextInfo 289 Used for "Info" diagnostic virtual text. 290 291 *hl-DiagnosticVirtualTextHint* 292 DiagnosticVirtualTextHint 293 Used for "Hint" diagnostic virtual text. 294 295 *hl-DiagnosticVirtualTextOk* 296 DiagnosticVirtualTextOk 297 Used for "Ok" diagnostic virtual text. 298 299 *hl-DiagnosticVirtualLinesError* 300 DiagnosticVirtualLinesError 301 Used for "Error" diagnostic virtual lines. 302 303 *hl-DiagnosticVirtualLinesWarn* 304 DiagnosticVirtualLinesWarn 305 Used for "Warn" diagnostic virtual lines. 306 307 *hl-DiagnosticVirtualLinesInfo* 308 DiagnosticVirtualLinesInfo 309 Used for "Info" diagnostic virtual lines. 310 311 *hl-DiagnosticVirtualLinesHint* 312 DiagnosticVirtualLinesHint 313 Used for "Hint" diagnostic virtual lines. 314 315 *hl-DiagnosticVirtualLinesOk* 316 DiagnosticVirtualLinesOk 317 Used for "Ok" diagnostic virtual lines. 318 319 *hl-DiagnosticUnderlineError* 320 DiagnosticUnderlineError 321 Used to underline "Error" diagnostics. 322 323 *hl-DiagnosticUnderlineWarn* 324 DiagnosticUnderlineWarn 325 Used to underline "Warn" diagnostics. 326 327 *hl-DiagnosticUnderlineInfo* 328 DiagnosticUnderlineInfo 329 Used to underline "Info" diagnostics. 330 331 *hl-DiagnosticUnderlineHint* 332 DiagnosticUnderlineHint 333 Used to underline "Hint" diagnostics. 334 335 *hl-DiagnosticUnderlineOk* 336 DiagnosticUnderlineOk 337 Used to underline "Ok" diagnostics. 338 339 *hl-DiagnosticFloatingError* 340 DiagnosticFloatingError 341 Used to color "Error" diagnostic messages in diagnostics float. 342 See |vim.diagnostic.open_float()| 343 344 *hl-DiagnosticFloatingWarn* 345 DiagnosticFloatingWarn 346 Used to color "Warn" diagnostic messages in diagnostics float. 347 348 *hl-DiagnosticFloatingInfo* 349 DiagnosticFloatingInfo 350 Used to color "Info" diagnostic messages in diagnostics float. 351 352 *hl-DiagnosticFloatingHint* 353 DiagnosticFloatingHint 354 Used to color "Hint" diagnostic messages in diagnostics float. 355 356 *hl-DiagnosticFloatingOk* 357 DiagnosticFloatingOk 358 Used to color "Ok" diagnostic messages in diagnostics float. 359 360 *hl-DiagnosticSignError* 361 DiagnosticSignError 362 Used for "Error" signs in sign column. 363 364 *hl-DiagnosticSignWarn* 365 DiagnosticSignWarn 366 Used for "Warn" signs in sign column. 367 368 *hl-DiagnosticSignInfo* 369 DiagnosticSignInfo 370 Used for "Info" signs in sign column. 371 372 *hl-DiagnosticSignHint* 373 DiagnosticSignHint 374 Used for "Hint" signs in sign column. 375 376 *hl-DiagnosticSignOk* 377 DiagnosticSignOk 378 Used for "Ok" signs in sign column. 379 380 *hl-DiagnosticDeprecated* 381 DiagnosticDeprecated 382 Used for deprecated or obsolete code. 383 384 *hl-DiagnosticUnnecessary* 385 DiagnosticUnnecessary 386 Used for unnecessary or unused code. 387 388 ============================================================================== 389 SIGNS *diagnostic-signs* 390 391 Signs are defined for each diagnostic severity. The default text for each sign 392 is the first letter of the severity name (for example, "E" for ERROR). Signs 393 can be customized with |vim.diagnostic.config()|. Example: >lua 394 395 -- Highlight entire line for errors 396 -- Highlight the line number for warnings 397 vim.diagnostic.config({ 398 signs = { 399 text = { 400 [vim.diagnostic.severity.ERROR] = '', 401 [vim.diagnostic.severity.WARN] = '', 402 }, 403 linehl = { 404 [vim.diagnostic.severity.ERROR] = 'ErrorMsg', 405 }, 406 numhl = { 407 [vim.diagnostic.severity.WARN] = 'WarningMsg', 408 }, 409 }, 410 }) 411 412 When the "severity_sort" option is set (see |vim.diagnostic.config()|) the 413 priority of each sign depends on the severity of the associated diagnostic. 414 Otherwise, all signs have the same priority (the value of the "priority" 415 option in the "signs" table of |vim.diagnostic.config()| or 10 if unset). 416 417 ============================================================================== 418 EVENTS *diagnostic-events* 419 420 *DiagnosticChanged* 421 DiagnosticChanged After diagnostics have changed. When used from Lua, 422 the new diagnostics are passed to the autocmd 423 callback in the "data" table. Triggered per buffer. 424 425 Example: >lua 426 427 vim.api.nvim_create_autocmd('DiagnosticChanged', { 428 callback = function(args) 429 local diagnostics = args.data.diagnostics 430 vim.print(diagnostics) 431 end, 432 }) 433 < 434 ============================================================================== 435 Lua module: vim.diagnostic *diagnostic-api* 436 437 *vim.Diagnostic* 438 Extends: |vim.Diagnostic.Set| 439 440 *diagnostic-structure* 441 442 Diagnostics use the same indexing as the rest of the Nvim API (i.e. 443 0-based rows and columns). |api-indexing| 444 445 Fields: ~ 446 • {bufnr} (`integer`) Buffer number 447 • {end_lnum} (`integer`) The final line of the diagnostic (0-indexed) 448 • {col} (`integer`) The starting column of the diagnostic 449 (0-indexed) 450 • {end_col} (`integer`) The final column of the diagnostic 451 (0-indexed) 452 • {severity} (`vim.diagnostic.Severity`) The severity of the 453 diagnostic |vim.diagnostic.severity| 454 • {namespace}? (`integer`) 455 456 *vim.Diagnostic.Set* 457 Diagnostics use the same indexing as the rest of the Nvim API (i.e. 458 0-based rows and columns). |api-indexing| 459 460 Fields: ~ 461 • {lnum} (`integer`) The starting line of the diagnostic 462 (0-indexed) 463 • {col}? (`integer`, default: `0`) The starting column of the 464 diagnostic (0-indexed) 465 • {end_lnum}? (`integer`, default: `lnum`) The final line of the 466 diagnostic (0-indexed) 467 • {end_col}? (`integer`, default: `col`) The final column of the 468 diagnostic (0-indexed) 469 • {severity}? (`vim.diagnostic.Severity`, default: `vim.diagnostic.severity.ERROR`) 470 The severity of the diagnostic |vim.diagnostic.severity| 471 • {message} (`string`) The diagnostic text 472 • {source}? (`string`) The source of the diagnostic 473 • {code}? (`string|integer`) The diagnostic code 474 • {user_data}? (`any`) arbitrary data plugins can add 475 476 *vim.diagnostic.GetOpts* 477 A table with the following keys: 478 479 Fields: ~ 480 • {namespace}? (`integer[]|integer`) Limit diagnostics to one or more 481 namespaces. 482 • {lnum}? (`integer`) Limit diagnostics to those spanning the 483 specified line number. 484 • {severity}? (`vim.diagnostic.SeverityFilter`) See 485 |diagnostic-severity|. 486 • {enabled}? (`boolean`, default: `nil`) Limit diagnostics to only 487 enabled or disabled. If nil, enablement is ignored. See 488 |vim.diagnostic.enable()| 489 490 *vim.diagnostic.JumpOpts* 491 Extends: |vim.diagnostic.GetOpts| 492 493 Configuration table with the keys listed below. Some parameters can have 494 their default values changed with |vim.diagnostic.config()|. 495 496 Fields: ~ 497 • {diagnostic}? (`vim.Diagnostic`) The diagnostic to jump to. Mutually 498 exclusive with {count}, {namespace}, and {severity}. 499 See |vim.Diagnostic|. 500 • {count}? (`integer`) The number of diagnostics to move by, 501 starting from {pos}. A positive integer moves forward 502 by {count} diagnostics, while a negative integer moves 503 backward by {count} diagnostics. Mutually exclusive 504 with {diagnostic}. 505 • {pos}? (`[integer,integer]`) Cursor position as a `(row, col)` 506 tuple. See |nvim_win_get_cursor()|. Used to find the 507 nearest diagnostic when {count} is used. Only used when 508 {count} is non-nil. Default is the current cursor 509 position. 510 • {wrap}? (`boolean`, default: `true`) Whether to loop around 511 file or not. Similar to 'wrapscan'. 512 • {severity}? (`vim.diagnostic.SeverityFilter`) See 513 |diagnostic-severity|. 514 • {on_jump}? (`fun(diagnostic:vim.Diagnostic?, bufnr:integer)`) 515 Optional callback invoked with the diagnostic that was 516 jumped to. 517 • {winid}? (`integer`, default: `0`) Window ID 518 519 *vim.diagnostic.NS* 520 521 Fields: ~ 522 • {name} (`string`) 523 • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|. 524 • {user_data} (`table`) 525 • {disabled}? (`boolean`) 526 527 *vim.diagnostic.Opts* 528 Many of the configuration options below accept one of the following: 529 • `false`: Disable this feature 530 • `true`: Enable this feature, use default settings. 531 • `table`: Enable this feature with overrides. Use an empty table to use 532 default values. 533 • `function`: Function with signature (namespace, bufnr) that returns any 534 of the above. 535 536 Fields: ~ 537 • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) 538 Use underline for diagnostics. 539 • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`) 540 Use virtual text for diagnostics. If multiple 541 diagnostics are set for a namespace, one prefix 542 per diagnostic + the last diagnostic message are 543 shown. 544 • {virtual_lines}? (`boolean|vim.diagnostic.Opts.VirtualLines|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualLines`, default: `false`) 545 Use virtual lines for diagnostics. 546 • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) 547 Use signs for diagnostics |diagnostic-signs|. 548 • {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`) 549 Options for floating windows. See 550 |vim.diagnostic.Opts.Float|. 551 • {status}? (`vim.diagnostic.Opts.Status`) Options for the 552 statusline component. See 553 |vim.diagnostic.Opts.Status|. 554 • {update_in_insert}? (`boolean`, default: `false`) Update diagnostics 555 in Insert mode (if `false`, diagnostics are 556 updated on |InsertLeave|) 557 • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) 558 Sort diagnostics by severity. This affects the 559 order in which signs, virtual text, and 560 highlights are displayed. When true, higher 561 severities are displayed before lower severities 562 (e.g. ERROR is displayed before WARN). Options: 563 • {reverse}? (boolean) Reverse sort order 564 • {jump}? (`vim.diagnostic.Opts.Jump`) Default values for 565 |vim.diagnostic.jump()|. See 566 |vim.diagnostic.Opts.Jump|. 567 568 *vim.diagnostic.Opts.Float* 569 Extends: |vim.lsp.util.open_floating_preview.Opts| 570 571 572 Fields: ~ 573 • {bufnr}? (`integer`, default: current buffer) Buffer number 574 to show diagnostics from. 575 • {namespace}? (`integer|integer[]`) Limit diagnostics to the given 576 namespace(s). 577 • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default: 578 `line`) Show diagnostics from the whole buffer 579 (`buffer`), the current cursor line (`line`), or the 580 current cursor position (`cursor`). Shorthand 581 versions are also accepted (`c` for `cursor`, `l` 582 for `line`, `b` for `buffer`). 583 • {pos}? (`integer|[integer,integer]`) If {scope} is "line" 584 or "cursor", use this position rather than the 585 cursor position. If a number, interpreted as a line 586 number; otherwise, a (row, col) tuple. 587 • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) 588 Sort diagnostics by severity. Overrides the setting 589 from |vim.diagnostic.config()|. 590 • {severity}? (`vim.diagnostic.SeverityFilter`) See 591 |diagnostic-severity|. Overrides the setting from 592 |vim.diagnostic.config()|. 593 • {header}? (`string|[string,any]`) String to use as the header 594 for the floating window. If a table, it is 595 interpreted as a `[text, hl_group]` tuple. Overrides 596 the setting from |vim.diagnostic.config()|. 597 • {source}? (`boolean|'if_many'`) Include the diagnostic source 598 in the message. Use "if_many" to only show sources 599 if there is more than one source of diagnostics in 600 the buffer. Otherwise, any truthy value means to 601 always show the diagnostic source. Overrides the 602 setting from |vim.diagnostic.config()|. 603 • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A 604 function that takes a diagnostic as input and 605 returns a string or nil. If the return value is nil, 606 the diagnostic is not displayed by the handler. Else 607 the output text is used to display the diagnostic. 608 Overrides the setting from 609 |vim.diagnostic.config()|. 610 • {prefix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) 611 Prefix each diagnostic in the floating window: 612 • If a `function`, {i} is the index of the 613 diagnostic being evaluated and {total} is the 614 total number of diagnostics displayed in the 615 window. The function should return a `string` 616 which is prepended to each diagnostic in the 617 window as well as an (optional) highlight group 618 which will be used to highlight the prefix. 619 • If a `table`, it is interpreted as a 620 `[text, hl_group]` tuple as in |nvim_echo()| 621 • If a `string`, it is prepended to each diagnostic 622 in the window with no highlight. Overrides the 623 setting from |vim.diagnostic.config()|. 624 • {suffix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) 625 Same as {prefix}, but appends the text to the 626 diagnostic instead of prepending it. Overrides the 627 setting from |vim.diagnostic.config()|. 628 629 *vim.diagnostic.Opts.Jump* 630 631 Fields: ~ 632 • {on_jump}? (`fun(diagnostic:vim.Diagnostic?, bufnr:integer)`) 633 Default value of the {on_jump} parameter of 634 |vim.diagnostic.jump()|. 635 • {wrap}? (`boolean`, default: true) Default value of the {wrap} 636 parameter of |vim.diagnostic.jump()|. 637 • {severity}? (`vim.diagnostic.SeverityFilter`) Default value of the 638 {severity} parameter of |vim.diagnostic.jump()|. 639 640 *vim.diagnostic.Opts.Signs* 641 642 Fields: ~ 643 • {severity}? (`vim.diagnostic.SeverityFilter`) Only show signs for 644 diagnostics matching the given severity 645 |diagnostic-severity| 646 • {priority}? (`integer`, default: `10`) Base priority to use for 647 signs. When {severity_sort} is used, the priority of a 648 sign is adjusted based on its severity. Otherwise, all 649 signs use the same priority. 650 • {text}? (`table<vim.diagnostic.Severity,string>`) A table mapping 651 |diagnostic-severity| to the sign text to display in the 652 sign column. The default is to use `"E"`, `"W"`, `"I"`, 653 and `"H"` for errors, warnings, information, and hints, 654 respectively. Example: >lua 655 vim.diagnostic.config({ 656 signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } } 657 }) 658 < 659 • {numhl}? (`table<vim.diagnostic.Severity,string>`) A table mapping 660 |diagnostic-severity| to the highlight group used for the 661 line number where the sign is placed. 662 • {linehl}? (`table<vim.diagnostic.Severity,string>`) A table mapping 663 |diagnostic-severity| to the highlight group used for the 664 whole line the sign is placed in. 665 666 *vim.diagnostic.Opts.Status* 667 668 Fields: ~ 669 • {text}? (`table<vim.diagnostic.Severity,string>`) A table mapping 670 |diagnostic-severity| to the text to use for each severity 671 section. 672 673 *vim.diagnostic.Opts.Underline* 674 675 Fields: ~ 676 • {severity}? (`vim.diagnostic.SeverityFilter`) Only underline 677 diagnostics matching the given severity 678 |diagnostic-severity|. 679 680 *vim.diagnostic.Opts.VirtualLines* 681 682 Fields: ~ 683 • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual 684 lines for diagnostics matching the given severity 685 |diagnostic-severity| 686 • {current_line}? (`boolean`, default: `false`) Only show diagnostics 687 for the current line. 688 • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A 689 function that takes a diagnostic as input and returns 690 a string or nil. If the return value is nil, the 691 diagnostic is not displayed by the handler. Else the 692 output text is used to display the diagnostic. 693 694 *vim.diagnostic.Opts.VirtualText* 695 696 Fields: ~ 697 • {severity}? (`vim.diagnostic.SeverityFilter`) Only show 698 virtual text for diagnostics matching the given 699 severity |diagnostic-severity| 700 • {current_line}? (`boolean`) Show or hide diagnostics based on 701 the current cursor line. If `true`, only 702 diagnostics on the current cursor line are 703 shown. If `false`, all diagnostics are shown 704 except on the current cursor line. If `nil`, all 705 diagnostics are shown. (default `nil`) 706 • {source}? (`boolean|"if_many"`) Include the diagnostic 707 source in virtual text. Use `'if_many'` to only 708 show sources if there is more than one 709 diagnostic source in the buffer. Otherwise, any 710 truthy value means to always show the diagnostic 711 source. 712 • {spacing}? (`integer`) Amount of empty spaces inserted at 713 the beginning of the virtual text. 714 • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) 715 Prepend diagnostic message with prefix. If a 716 `function`, {i} is the index of the diagnostic 717 being evaluated, and {total} is the total number 718 of diagnostics for the line. This can be used to 719 render diagnostic symbols or error codes. 720 • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) 721 Append diagnostic message with suffix. This can 722 be used to render an LSP diagnostic error code. 723 • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) If 724 not nil, the return value is the text used to 725 display the diagnostic. Example: >lua 726 function(diagnostic) 727 if diagnostic.severity == vim.diagnostic.severity.ERROR then 728 return string.format("E: %s", diagnostic.message) 729 end 730 return diagnostic.message 731 end 732 < 733 734 If the return value is nil, the diagnostic is 735 not displayed by the handler. 736 • {hl_mode}? (`'replace'|'combine'|'blend'`) See 737 |nvim_buf_set_extmark()|. 738 • {virt_text}? (`[string,any][]`) See |nvim_buf_set_extmark()|. 739 • {virt_text_pos}? (`'eol'|'eol_right_align'|'inline'|'overlay'|'right_align'`) 740 See |nvim_buf_set_extmark()|. 741 • {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|. 742 • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. 743 744 745 config({opts}, {namespace}) *vim.diagnostic.config()* 746 Configure diagnostic options globally or for a specific diagnostic 747 namespace. 748 749 Configuration can be specified globally, per-namespace, or ephemerally 750 (i.e. only for a single call to |vim.diagnostic.set()| or 751 |vim.diagnostic.show()|). Ephemeral configuration has highest priority, 752 followed by namespace configuration, and finally global configuration. 753 754 For example, if a user enables virtual text globally with >lua 755 vim.diagnostic.config({ virtual_text = true }) 756 < 757 758 and a diagnostic producer sets diagnostics with >lua 759 vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) 760 < 761 762 then virtual text will not be enabled for those diagnostics. 763 764 Parameters: ~ 765 • {opts} (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve 766 the current configuration. Otherwise, a configuration 767 table (see |vim.diagnostic.Opts|). 768 • {namespace} (`integer?`) Update the options for the given namespace. 769 When omitted, update the global diagnostic options. 770 771 Return: ~ 772 (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is 773 omitted. See |vim.diagnostic.Opts|. 774 775 count({bufnr}, {opts}) *vim.diagnostic.count()* 776 Get current diagnostics count. 777 778 Parameters: ~ 779 • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for 780 current buffer or nil for all buffers. 781 • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. 782 783 Return: ~ 784 (`table<integer, integer>`) Table with actually present severity 785 values as keys (see |diagnostic-severity|) and integer counts as 786 values. 787 788 enable({enable}, {filter}) *vim.diagnostic.enable()* 789 Enables or disables diagnostics. 790 791 To "toggle", pass the inverse of `is_enabled()`: >lua 792 vim.diagnostic.enable(not vim.diagnostic.is_enabled()) 793 < 794 795 Parameters: ~ 796 • {enable} (`boolean?`) true/nil to enable, false to disable 797 • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. 798 • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for 799 all. 800 • {bufnr}? (`integer`) Buffer number, or 0 for current 801 buffer, or `nil` for all buffers. 802 803 fromqflist({list}, {opts}) *vim.diagnostic.fromqflist()* 804 Convert a list of quickfix items to a list of diagnostics. 805 806 Parameters: ~ 807 • {list} (`vim.quickfix.entry[]`) List of quickfix items from 808 |getqflist()| or |getloclist()|. 809 • {opts} (`table?`) Configuration table with the following keys: 810 • {merge_lines}? (`boolean`) When true, items with valid=0 are 811 appended to the previous valid item's message with a 812 newline. (default: false) 813 814 Return: ~ 815 (`vim.Diagnostic[]`) See |vim.Diagnostic|. 816 817 get({bufnr}, {opts}) *vim.diagnostic.get()* 818 Get current diagnostics. 819 820 Modifying diagnostics in the returned table has no effect. To set 821 diagnostics in a buffer, use |vim.diagnostic.set()|. 822 823 Parameters: ~ 824 • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for 825 current buffer or nil for all buffers. 826 • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. 827 828 Return: ~ 829 (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and 830 `severity` are guaranteed to be present. See |vim.Diagnostic|. 831 832 get_namespace({namespace}) *vim.diagnostic.get_namespace()* 833 Get namespace metadata. 834 835 Parameters: ~ 836 • {namespace} (`integer`) Diagnostic namespace 837 838 Return: ~ 839 (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|. 840 841 get_namespaces() *vim.diagnostic.get_namespaces()* 842 Get current diagnostic namespaces. 843 844 Return: ~ 845 (`table<integer,vim.diagnostic.NS>`) List of active diagnostic 846 namespaces |vim.diagnostic|. 847 848 get_next({opts}) *vim.diagnostic.get_next()* 849 Get the next diagnostic closest to the cursor position. 850 851 Parameters: ~ 852 • {opts} (`vim.diagnostic.JumpOpts?`) See |vim.diagnostic.JumpOpts|. 853 854 Return: ~ 855 (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. 856 857 get_prev({opts}) *vim.diagnostic.get_prev()* 858 Get the previous diagnostic closest to the cursor position. 859 860 Parameters: ~ 861 • {opts} (`vim.diagnostic.JumpOpts?`) See |vim.diagnostic.JumpOpts|. 862 863 Return: ~ 864 (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. 865 866 hide({namespace}, {bufnr}) *vim.diagnostic.hide()* 867 Hide currently displayed diagnostics. 868 869 This only clears the decorations displayed in the buffer. Diagnostics can 870 be redisplayed with |vim.diagnostic.show()|. To completely remove 871 diagnostics, use |vim.diagnostic.reset()|. 872 873 To hide diagnostics and prevent them from re-displaying, use 874 |vim.diagnostic.enable()|. 875 876 Parameters: ~ 877 • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide 878 diagnostics from all namespaces. 879 • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When 880 omitted, hide diagnostics in all buffers. 881 882 is_enabled({filter}) *vim.diagnostic.is_enabled()* 883 Check whether diagnostics are enabled. 884 885 Attributes: ~ 886 Since: 0.10.0 887 888 Parameters: ~ 889 • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. 890 • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for 891 all. 892 • {bufnr}? (`integer`) Buffer number, or 0 for current 893 buffer, or `nil` for all buffers. 894 895 Return: ~ 896 (`boolean`) 897 898 jump({opts}) *vim.diagnostic.jump()* 899 Move to a diagnostic. 900 901 Parameters: ~ 902 • {opts} (`vim.diagnostic.JumpOpts`) See |vim.diagnostic.JumpOpts|. 903 904 Return: ~ 905 (`vim.Diagnostic?`) The diagnostic that was moved to. See 906 |vim.Diagnostic|. 907 908 *vim.diagnostic.match()* 909 match({str}, {pat}, {groups}, {severity_map}, {defaults}) 910 Parse a diagnostic from a string. 911 912 For example, consider a line of output from a linter: > 913 WARNING filename:27:3: Variable 'foo' does not exist 914 < 915 916 This can be parsed into |vim.Diagnostic| structure with: >lua 917 local s = "WARNING filename:27:3: Variable 'foo' does not exist" 918 local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" 919 local groups = { "severity", "lnum", "col", "message" } 920 vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) 921 < 922 923 Parameters: ~ 924 • {str} (`string`) String to parse diagnostics from. 925 • {pat} (`string`) Lua pattern with capture groups. 926 • {groups} (`string[]`) List of fields in a |vim.Diagnostic| 927 structure to associate with captures from {pat}. 928 • {severity_map} (`table`) A table mapping the severity field from 929 {groups} with an item from |vim.diagnostic.severity|. 930 • {defaults} (`table?`) Table of default values for any fields not 931 listed in {groups}. When omitted, numeric values 932 default to 0 and "severity" defaults to ERROR. 933 934 Return: ~ 935 (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails 936 to match {str}. 937 938 open_float({opts}) *vim.diagnostic.open_float()* 939 Show diagnostics in a floating window. 940 941 Parameters: ~ 942 • {opts} (`vim.diagnostic.Opts.Float?`) See 943 |vim.diagnostic.Opts.Float|. 944 945 Return (multiple): ~ 946 (`integer?`) float_bufnr 947 (`integer?`) winid 948 949 reset({namespace}, {bufnr}) *vim.diagnostic.reset()* 950 Remove all diagnostics from the given namespace. 951 952 Unlike |vim.diagnostic.hide()|, this function removes all saved 953 diagnostics. They cannot be redisplayed using |vim.diagnostic.show()|. To 954 simply remove diagnostic decorations in a way that they can be 955 re-displayed, use |vim.diagnostic.hide()|. 956 957 Parameters: ~ 958 • {namespace} (`integer?`) Diagnostic namespace. When omitted, remove 959 diagnostics from all namespaces. 960 • {bufnr} (`integer?`) Remove diagnostics for the given buffer. 961 When omitted, diagnostics are removed for all buffers. 962 963 set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* 964 Set diagnostics for the given namespace and buffer. 965 966 Parameters: ~ 967 • {namespace} (`integer`) The diagnostic namespace 968 • {bufnr} (`integer`) Buffer number 969 • {diagnostics} (`vim.Diagnostic.Set[]`) See |vim.Diagnostic.Set|. 970 • {opts} (`vim.diagnostic.Opts?`) Display options to pass to 971 |vim.diagnostic.show()|. See |vim.diagnostic.Opts|. 972 973 setloclist({opts}) *vim.diagnostic.setloclist()* 974 Add buffer diagnostics to the location list. 975 976 Parameters: ~ 977 • {opts} (`table?`) Configuration table with the following keys: 978 • {namespace}? (`integer[]|integer`) Only add diagnostics from 979 the given namespace(s). 980 • {winnr}? (`integer`, default: `0`) Window number to set 981 location list for. 982 • {open}? (`boolean`, default: `true`) Open the location list 983 after setting. 984 • {title}? (`string`) Title of the location list. Defaults to 985 "Diagnostics". 986 • {severity}? (`vim.diagnostic.SeverityFilter`) See 987 |diagnostic-severity|. 988 • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A 989 function that takes a diagnostic as input and returns a 990 string or nil. If the return value is nil, the diagnostic is 991 not displayed in the location list. Else the output text is 992 used to display the diagnostic. 993 994 setqflist({opts}) *vim.diagnostic.setqflist()* 995 Add all diagnostics to the quickfix list. 996 997 Parameters: ~ 998 • {opts} (`table?`) Configuration table with the following keys: 999 • {namespace}? (`integer[]|integer`) Only add diagnostics from 1000 the given namespace(s). 1001 • {open}? (`boolean`, default: `true`) Open quickfix list 1002 after setting. 1003 • {title}? (`string`) Title of quickfix list. Defaults to 1004 "Diagnostics". If there's already a quickfix list with this 1005 title, it's updated. If not, a new quickfix list is created. 1006 • {severity}? (`vim.diagnostic.SeverityFilter`) See 1007 |diagnostic-severity|. 1008 • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A 1009 function that takes a diagnostic as input and returns a 1010 string or nil. If the return value is nil, the diagnostic is 1011 not displayed in the quickfix list. Else the output text is 1012 used to display the diagnostic. 1013 1014 *vim.diagnostic.show()* 1015 show({namespace}, {bufnr}, {diagnostics}, {opts}) 1016 Display diagnostics for the given namespace and buffer. 1017 1018 Parameters: ~ 1019 • {namespace} (`integer?`) Diagnostic namespace. When omitted, show 1020 diagnostics from all namespaces. 1021 • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. 1022 When omitted, show diagnostics in all buffers. 1023 • {diagnostics} (`vim.Diagnostic[]?`) The diagnostics to display. When 1024 omitted, use the saved diagnostics for the given 1025 namespace and buffer. This can be used to display a 1026 list of diagnostics without saving them or to display 1027 only a subset of diagnostics. May not be used when 1028 {namespace} or {bufnr} is nil. See |vim.Diagnostic|. 1029 • {opts} (`vim.diagnostic.Opts?`) Display options. See 1030 |vim.diagnostic.Opts|. 1031 1032 status({bufnr}) *vim.diagnostic.status()* 1033 Returns formatted string with diagnostics for the current buffer. The 1034 severities with 0 diagnostics are left out. Example `E:2 W:3 I:4 H:5` 1035 1036 To customise appearance, set diagnostic text for each severity with >lua 1037 vim.diagnostic.config({ 1038 status = { text = { [vim.diagnostic.severity.ERROR] = 'e', ... } } 1039 }) 1040 < 1041 1042 Parameters: ~ 1043 • {bufnr} (`integer?`) Buffer number to get diagnostics from. Defaults 1044 to 0 for the current buffer 1045 1046 Return: ~ 1047 (`string`) 1048 1049 toqflist({diagnostics}) *vim.diagnostic.toqflist()* 1050 Convert a list of diagnostics to a list of quickfix items that can be 1051 passed to |setqflist()| or |setloclist()|. 1052 1053 Parameters: ~ 1054 • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. 1055 1056 Return: ~ 1057 (`table[]`) Quickfix list items |setqflist-what| 1058 1059 1060 vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: