visual-studio-code - 使 VS Code 解析并显示一种新语言的结构到 VSC 的轮廓区域

Question

我试图通过将语言定义添加到 VSC 来使 VSC 显示包含 DSL(域特定语言)的文档的结构。该结构应出现在 VSC“大纲 View ”中，其中显示已安装语言的所有文档结构(如 json、markdown、html 等)

DSL 非常简单，只有一些大写字母的元素应该出现在大纲中并保持层次结构:

WORD xxx
GRAMMAR xxx
STRUCTURE xxx xxx
     xxx xxx xxx xxx
MEANING xxx xxx xxx 
    SUB_MEANING xxx xxx xxx xxx
        SUB_SUB_MEANING xxx xxx xxx

我遵循了关于 stackoverflow 的所有提示，这些提示都导致了 VSC 和/或语言服务器协议(protocol) (LSP) 的官方文档。但是，没有任何帮助，根本没有-.-
是的，我可以使用 CodeMap 扩展，但我不想依赖它，因为 VSC 实际上能够理解新语言。对于众所周知的语言，不需要创建专用的 TreeView 元素或其他东西，因此必须有一种方法让 VSC 解析语言结构。

VSC 中的“大纲 View ”仍然为空。
我发现如果删除 VSC 扩展文件夹中的文件夹“xxx-language-features”(xxx 代表语言)，则安装的(例如)markdown 或 json 的语言支持也不会为“大纲”生成任何内容.所以看来我也需要一个语言功能扩展。

我经历了 https://code.visualstudio.com/api/language-extensions/language-configuration-guide和 https://microsoft.github.io/language-server-protocol/和许多其他的东西，包括来自 VSC 的 Github-Repo 的 LSP 示例，但对此没有任何帮助。我还尝试借助“哟代码”创建一种新语言。没有。
Microsoft 提供的 LSP 示例是针对纯文本文件的……为纯文本创建语言服务器有多大用处？!我想举一个关于语言的例子。查看扩展中的已编译文件无济于事，因为它们已被缩小。

在该问题上没有完整的“如何做” - 因此，感谢任何帮助!
如何告诉 VSC 将文档结构解析为“大纲 View ”？

Answer 1

你有几种方法可以解决这个问题，你可以:

创建一个 IDE 独有的扩展来完成所有工作(解析文件、理解所有标记的含义并提供符号列表等)

使用实现 language server protocol 的语言服务器创建语言服务器客户端扩展由 Microsoft 指定。在这种情况下，您的 VSCode 扩展本质上将是一个启动语言服务器并与之通信的“shell”扩展。 vscode-languageclient 已经开箱即用地实现了如何处理服务器返回的信息。包的LanguageClient类(class)。

选项 2. 有一个巨大的优势:它修复了 N*M 问题:所有支持语言服务器协议(protocol)的编辑器都可以与您的语言服务器通信，因此可以轻松地为多个编辑器(VSCode、Visual Studio、Atom、Vim)提供语言支持, emacs 等, IntelliJ 以有限的方式使用 3rd 方插件) 以最小的努力。
在您的问题中，我不清楚您是否打算编写一个可以完成所有工作的扩展，或者您是否打算开发一个语言服务器和一个语言客户端扩展来配合它。
答案实际上取决于您的语言(或 DSL)的复杂性。如果它的语法有点复杂，并且您已经有一个编译器，那么制作语言服务器是有意义的，因为大多数解析和逻辑已经在编译器中实现。如果您的语言真的像您给出的示例一样简单并且没有语法，那么它可能是矫枉过正。
如果你走“语言服务器”路线，那么有不同语言的库可以简化服务器的实现，它们负责 LSP 的 JSON-RPC 部分，你只需要覆盖语言服务器定义的方法协议(protocol)(例如 LSP4J 用于任何 JVM 语言，或 vscode-languageserver 用于 NodeJS(尽管它的名称，该包并不特定于 VSCode))。
在这种情况下，让 VSCode 的大纲 View 填充符号的层次结构只需要您实现 textDocument/documentSymbol请求在您的语言服务器中，而在扩展中没有其他内容，它由 vscode-languageclient 处理包的 LanguageClient类(class)!

如果您的语言客户端支持分层文档符号:在语言服务器中 initialize方法，您将收到带有 textDocument.documentSymbol.hierarchicalDocumentSymbolSupport == true 的 InitializeParams (VSCode 确实支持这个)然后你返回 DocumentSymbol[] (它具有 children 属性，从而为您的客户提供符号树)。

如果您的语言服务器客户端不支持分层文档符号(例如 Visual Studio)，则返回 SymbolInformation[] ，这是一个简单的符号列表。

一件重要的事情要照顾 : VSCode 采用 range DocumentSymbol 的属性在显示符号树时考虑(在大纲 View 中)。你的 child 符号' range必须包含在其 parent 的 range 中或 VSCode 将不会在大纲 View 中显示任何符号，即使您的符号树结构和 selectionRange s 是正确的。 range是定义范围(符号的整个定义，例如对于 typescript 类，它以关键字 class 开始，以结束 } 结束)和 selectionRange通常只是符号的标记范围(但根据规范，它还可以包括文档注释 block 和可见性修饰符，这是实现者的选择)。
例如

class MyClass {
  /**
   * Some method documentation
   */
  private function myFunction(param1) {
    console.log(param1);
  }
}

在这种情况下，范围将是

rangeOfClass = {
  "start": { "line": 0, "character": 0 },
  "end": { "line": 7, "character": 1 }
};
rangeOfMethod = {
  "start": { "line": 4, "character": 2 },
  "end": { "line": 6, "character": 3 }
};

并且 selectionRange 可能只是符号的名称

selectionRangeOfClass = {
  "start": { "line": 0, "character": 6 },
  "end": { "line": 0, "character": 13 }
};
selectionRangeOfMethod = {
  "start": { "line": 4, "character": 19 },
  "end": { "line": 4, "character": 29 }
};

或者它可以包括从文档、关键字和修饰符到符号的末尾

selectionRangeOfClass = {
  "start": { "line": 0, "character": 0 },
  "end": { "line": 0, "character": 13 }
};
selectionRangeOfMethod = {
  "start": { "line": 1, "character": 2 },
  "end": { "line": 4, "character": 29 }
};

有了这个，你会得到一个很好的大纲: