vim-diagnostic-使用

可查阅 :h vim.diagnostic.

Nvim 提供了一个 framework 来显示外部工具产生的 errors or warnings, 即 diagnostics. 其来源可以是 linters or LSP servers.

reports diagnostics 的步骤

1. 用 nvim_create_namespace() 创建一个具名 namespace
2. 用 vim.diagnostic.config() 给 diagnostic namespace 设置选项
3. 产生 diagnostics
4. 用 vim.diagnostics.set() 将 diagnostics 设置到一个 buffer
5. Repeat fron step 3

Report diagnostics 的被称为 “diagnostic producers”, 而阅读 diagnostics 的被称为 “diagnostic consumers”.

Severity

可用的 severity 定义在 vim.diagnostic.severity 这个 table 中:

vim.diagnostic.severity.ERROR
vim.diagnostic.severity.WARN
vim.diagnostic.severity.INFO
vim.diagnostic.severity.HINT

Handler

Diagnostics are shown to user with vim.diagnostic.show(). 而 display of diagnostics 是由 handlers 来处理.

一个 handler 是一个 table with a “show” and (optionally) a “hide” function, 其通过在 vim.diagnostic.handlers 这个 table 中添加一个键值来注册.

默认可用的 handler 有:

• vim.diagnostic.handlers.virtual_text
• vim.diagnostic.handlers.signs
• vim.diagnostic.handlers.underline

这些 handler 都可以被覆盖.

show function

show function 的函数签名为:

function(namespace, bufnr, diagnostics, opts)

其用于处理 the display of diagnostics.

hide function

hide function 的函数签名为:

function(namespace, bufnr)

其用于清理 any actions taken by the “show” function.

handler configuration

用 vim.diagnostic.confg() 来设置. 其实际设置的为传入 show function 的 opts 参数.

handler example

如:

-- It's good practice to namespace custom handlers to avoid collisions
vim.diagnostic.handlers["my/notify"] = {
  show = function(namespace, bufnr, diagnostics, opts)
    -- In our example, the opts table has a "log_level" option
    local level = opts["my/notify"].log_level

    local name = vim.diagnostic.get_namespace(namespace).name
    local msg = string.format("%d diagnostics in buffer %d from %s",
                              #diagnostics,
                              bufnr,
                              name)
    vim.notify(msg, level)
  end,
}

-- Users can configure the handler
vim.diagnostic.config({
  ["my/notify"] = {
    log_level = vim.log.levels.INFO
  }
})

Highlights

所有与 diagnostic 相关的 highlights 都定义以 Diagnostic 开头. 紧接着 the type of highlight (如 Sign, Underline) 和 the severity (如 Error, Warn).

Signs

Signs 定义给每一个 diagnostic severity 使用, 默认的 sign 是 severity name 的第一个字母 (如 “E” for ERROR).

可以通过 vim.diagnostic.config() 来自定义:

-- 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',
        },
    },
})

Events

用于触发 autocommand.

有 DiagnosticChanged, 即每一次 diagnostic 改变之后.

示例:

vim.api.nvim_create_autocmd('DiagnosticChanged', {
  callback = function(args)
    local diagnostics = args.data.diagnostics
    vim.print(diagnostics)
  end,
})

可用的 structure

这些 structure (都是 lua table), 并不是预定义有的, 只是定义了这些 table 需要满足的结构, 用于传入给一些 function 使用, 或者是作为 function 的返回值.

vim.Diagnostic

一个 lua table with the following keys. 必要的 key 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

这里指定的行和列都是 0-based.

vim.diagnostic 的使用

vim.diagnostic.config()

vim.diagnostic.config({opts}, {namespace})

可以全局设置或者对指定 namespace 设置.

使用配置的优先级为:

• Ephemeral configuration, 最高 (用 vim.diagnostic.set 或 vim.diagnostic.show 设置)
• Per-namespace
• Global configuration

vim.diagnostic.disable()

vim.diagnostic.disable({bufnr}, {namespace})

禁用一个 buffer 或者 namespace 的 diagnostic.

vim.diagnostic.enable()

vim.diagnostic.enable({bufnr}, {namespace})

启用一个 buffer 或者 namespace 的 diagnostic.

vim.diagnostic.fromqflist()

vim.diagnostic.fromqflist({list})

将 quickfix list 转换为 a list of diagnostics.

vim.diagnostic.get()

vim.diagnostic.get({bufnr}, {opts})

获取当前的 diagnostics.

vim.diagnostic.set()

vim.diagnostic.set({namespace}, {bufnr}, {diagnostics}, {opts})

设置指定 namespace 和 buffer 的 diagnostics.

vim.diagnostic.get_namespace()

vim.diagnostic.get_namespace({namespace})

获取指定 namespace 的 metadata 信息.

vim.diagnostic.get_namespaces()

vim.diagnostic.get_namespaces({namespace})

获取当前 namespace 的 metadata 信息.

vim.diagnostic.hide()

vim.diagnostic.hide({namespace}, {bufnr})

用于隐藏当前显示的 diagnostics. 若不指定 namespace 则隐藏所有 namespace 的 diagnostics, 若不指定 buffer, 则对所有 buffer 其作用.

可以用 vim.diagnostic.show() 再次显示 diagnostics.

如果要彻底移除 diagnostics, 用 vim.diagnostic.reset()

vim.diagnostic.is_disabled()

vim.diagnostic.is_disabled({bufnr}, {namespace})

判断一个 buffer 是否禁用了 diagnostics.

vim.diagnostic.match()

vim.diagnostic.open_float()

vim.diagnostic.open_float({opts})

在一个 floating window 中显示 diagnostics.

vim.diagnostic.reset()

vim.diagnostic.reset({namespace}, {bufnr})

移除指定 namespace 中的全部 diagnostics.

vim.diagnostic.setloclist()

vim.diagnostic.setloclist({opts})

将 buffer 中的 diagnostics 加入到 location list.

vim.diagnostic.setqflist()

vim.diagnostic.setqflist({opts})

将所有 diagnostics 加入到 quickfix list.

vim.diagnostic.show()

vim.diagnostic.show({namespace}, {bufnr}, {diagnostics}, {opts})

在指定 namespace 和 buffer 显示 diagnostics.

vim.diagnostic.toqflist()

vim.diagnostic.toqflist({diagnostics})

将 a list of diagnostics 转换为 a list of quickfix items.