vscode插件快餐教程(3) - Diagnostic

上一节我们介绍了语言扩展的大致情况，这一节我们开始深入一些细节。

诊断信息

语言扩展中一个重要的功能是代码扫描的诊断信息。这个诊断信息是以vscode.Diagnostic为载体呈现的。
我们来看一下vscode.Diagnostic类的成员和与相关类的关系：

以小到大，这些类为：

• Position: 定位到一行上的一个字符的坐标
• Range: 由起点和终点两个Position决定
• Location: 一个Range配上一个URI
• DiagnosticRelatedInformation: 一个Location配一个message
• Diagnostic: 主体是一个message字符串，一个Range和一个DiagnosticRelatedInformation.

构造一个诊断信息

下面我们来构造一个诊断信息。
我们随便造一个BASIC语言的例子吧，保存为test.bas:

dim i as integer

for i = 1 to 10 step 1
    for i = 1 to 10 step 1
        print "*";
    next i
next i

这个例子中，循环控制变量在外循环和内循环中被重用，导致外循环失效。
出现问题的Range是第4行的第9字符到第10字符。位置是以0开始的，所以我们构造(3,8)到(3,9)这样两个Position为首尾的Range.

        new vscode.Range(
            new vscode.Position(3, 8), new vscode.Position(3, 9),
        )

有了Range，加上问题描述字符串，和问题的严重程序三项，就可以构造一个Diagnostic来。

    let diag1: vscode.Diagnostic = new vscode.Diagnostic(
        new vscode.Range(
            new vscode.Position(3, 8), new vscode.Position(3, 9),
        ),
        '循环变量重复赋值',
        vscode.DiagnosticSeverity.Hint,
    )

诊断相关信息

上一节提到，有Range，有message，有严重程度这三项，就可以构造一个Diagnostic信息出来。

除此之外，还可以设置一些高级信息。
第一个是来源，比如来自eslint某版本，使用了某某规则之类的。这个可以写到Diagnostic的source属性中。

diag1.source = 'basic-lint';

第二个是错误码，有助于分类和查询。这个是code属性来表示的，既可以是一个数字，也可以是一个字符串。

diag1.code = 102;

第三个是相关信息。以上节例子来说，我们说i已经被赋值过了，那么可以进一步告诉开发者是在哪里被赋值过了。所以要有一个uri，能找到代码的地址。还要有一个Range，告诉在uri中的具体位置。前面介绍过了，这是一个vscode.Location结构。

    diag1.relatedInformation = [new vscode.DiagnosticRelatedInformation(
        new vscode.Location(document.uri,
            new vscode.Range(new vscode.Position(2, 4), new vscode.Position(2, 5))),
        '第一次赋值')];

下面我们把它们集合起来，针对上面的test.bas进行错误提示。主要就是将上面的提示信息写到传参进来的DiagnosticCollection中。

import * as vscode from 'vscode';
import * as path from 'path';

export function updateDiags(document: vscode.TextDocument,
    collection: vscode.DiagnosticCollection): void {
    let diag1: vscode.Diagnostic = new vscode.Diagnostic(
        new vscode.Range(
            new vscode.Position(3, 8), new vscode.Position(3, 9),
        ),
        '循环变量重复赋值',
        vscode.DiagnosticSeverity.Hint,
    );
    diag1.source = 'basic-lint';
    diag1.relatedInformation = [new vscode.DiagnosticRelatedInformation(
        new vscode.Location(document.uri,
            new vscode.Range(new vscode.Position(2, 4), new vscode.Position(2, 5))),
        '第一次赋值')];
    diag1.code = 102;

    if (document && path.basename(document.uri.fsPath) === 'test.bas') {
        collection.set(document.uri, [diag1]);
    } else {
        collection.clear();
    }
}

触发诊断信息的事件

下面我们在plugin的activate函数中增加到于刚才写的updateDiags函数的调用。

    const diag_coll = vscode.languages.createDiagnosticCollection('basic-lint-1');

    if (vscode.window.activeTextEditor) {
        diag.updateDiags(vscode.window.activeTextEditor.document, diag_coll);
    }

    context.subscriptions.push(vscode.window.onDidChangeActiveTextEditor(
        (e: vscode.TextEditor | undefined) => {
            if (e !== undefined) {
                diag.updateDiags(e.document, diag_coll);
            }
        }));

运行一下，在新启动的vscode中打开test.bas，然后在最后任意编辑一下代码，激活事情就可以触发。运行界面如下：

从中可以看到，第4行的i变量下面有一个提示，错误码102，source是basic-lint。第二行是DiagnosticRelatedInformation的信息。