15

I have made a custom language extension and I would like to enable the "Go To Symbol" feature. I have tried to follow the guidelines here, but I'm still kind of lost.

I think all I need to do is implement a DocumentSymbolProvider, but I'm not really sure how to go about it.

UPDATE

The example language server docs point to a repo that is deprecated. It is replaced with this one, which is much more complex. I think the simplest example I can find there is the lsp-sample, but it doesn't use a DocumentSymbolProvider.

I've found other repos that do use symbol providers, but they are a bit overwhelming. I can't figure out what needs to go where (for example, do I need both a client and a server? Some packages only seem to use an extension.ts without both client and server folders).

All I really want to do in my language is detect lines that start with @ and show them in the Go to Symbol pane. I'd love to see a simple tutorial of this.

Gama11
  • 31,714
  • 9
  • 78
  • 100
nachocab
  • 13,328
  • 21
  • 91
  • 149
  • Related: ["How can I implement my own code outline layout in vscode?"](https://stackoverflow.com/questions/48306520/how-can-i-implement-my-own-code-outline-layout-in-vscode) – pianoJames Apr 20 '21 at 23:48

1 Answers1

24

Do I need both a client and a server?

Not necessarily. As the language support docs you linked show, there's usually two options: a "direct implementation" and one using the Language Server Protocol. For the former, you don't need a client / server architecture. Language Servers have the advantage of being editor-agnostic, you can theoretically use them in any editor that implements the protocol. A direct implementation is limited to usage in VSCode.

All I really want to do in my language is detect lines that start with @ and show them in the Go to Symbol pane.

Here's the extension.ts for a very simple example of a "direct implementation" for this:

'use strict';
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(vscode.languages.registerDocumentSymbolProvider(
        {language: "foo"}, new FooDocumentSymbolProvider()
    ));
}

class FooDocumentSymbolProvider implements vscode.DocumentSymbolProvider {
    public provideDocumentSymbols(document: vscode.TextDocument,
            token: vscode.CancellationToken): Thenable<vscode.SymbolInformation[]> {
        return new Promise((resolve, reject) => {
            var symbols = [];

            for (var i = 0; i < document.lineCount; i++) {
                var line = document.lineAt(i);
                if (line.text.startsWith("@")) {
                    symbols.push({
                        name: line.text.substr(1),
                        kind: vscode.SymbolKind.Field,
                        location: new vscode.Location(document.uri, line.range)
                    })
                }
            }

            resolve(symbols);
        });
    }
}

You will also need to add this to the package.json generated by the VSCode extension template. It registers the foo language and activates the extension when a file with the .foo extension is opened:

"activationEvents": [
    "onLanguage:foo"
],
"contributes": {
    "languages": [{
        "id": "foo",
        "extensions": [".foo"]
    }]
}

Here it is in action:

Gama11
  • 31,714
  • 9
  • 78
  • 100
  • Thanks a lot!!! You totally saved me . Just for my edification, why is it okay to not provide the containerName in the [SymbolInformation](https://code.visualstudio.com/docs/extensionAPI/vscode-api#_a-namesymbolinformationaspan-classcodeitem-id597symbolinformationspan) object? – nachocab Sep 05 '17 at 16:37
  • If you check the constructors, you'll find it's optional in one of them. In fact, it's probably better practice to call the constructor instead of constructing the object like this - I'm more used to the langauge server API. :) – Gama11 Sep 05 '17 at 16:54
  • @Gama11 how to append more symbols to my js or less file? I wrote the code you gave, and got my symbols replaced. All the js symbols were gone. Thanks. – Jack Hu Feb 17 '23 at 08:20