【推荐】Helix的编程语言配置

目录

• 编程语言
  • languages.toml
  • 语言配置
    • 探测文件类型
  • 编程语言服务
    • 为一个编程语言配置语言服务
  • Tree-sitter 语法配置
    • 选择语法

编程语言

编程语言设置以及语言服务器设置位于配置文件languages.toml 中。

languages.toml

languages.toml 有三个可能的位置:

1. 在Helix源代码中:Helix repository。
   
   其提供了语言设置的默认配置

2. 在你的配置目录下的languages.toml，这了会覆盖内置的语言配置设定。例如禁用rust语言自动格式化：

   
   [language-server.mylang-lsp]
   command = "mylang-lsp"
   
   [[language]]
   name = "rust"
   auto-format = false
   

3. 在你项目工程目录下的一个 .helix目录.在这里的语言配置会覆盖你本地的语言配置，以及内置的语言配置。

语言配置

每个编程语言可在 [[language]] 字段中进行配置，例如:

[[language]]
name = "mylang"
scope = "source.mylang"
injection-regex = "mylang"
file-types = ["mylang", "myl"]
comment-token = "#"
indent = { tab-width = 2, unit = "  " }
formatter = { command = "mylang-formatter" , args = ["--stdin"] }
language-servers = [ "mylang-lsp" ]

下列是可选的配置项

配置项	描述
name	编程语言名称
language-id	编程语言的标识,可以在TextDocumentItem查询
scope	编程语言的文件标识，类似source.js 。 当前我们争取匹配流行的元文本语法风格和语言库。 通常在标记语言中使用source.<name> 或text.<name>
injection-regex	使用正则表达式来测试一个语言名称是否匹配一个语言的潜在注入点,language injection
file-types	编程语言的文件类型,例如["yml", "yaml"]
shebangs	命令行的解析器，例如 ["sh", "bash"]
roots	一组标记文件，通常是作为工程目录的根,例如 Cargo.lock, yarn.lock
auto-format	是否要自动保存
diagnostic-severity	调试诊断信息显示的最小级别 (Error, Warning, Info, Hint)
comment-token	注释标记
indent	使用的缩进符号. 自配置包括unit (缩进时插入文档的文本,通常设置为几个空格或 tab符号："\t") 和tab-width ( 替换tab符号空格数量)
language-servers	编程语言的语言服务器.
grammar	tree-sitter 语法设置 (默认值是name)
formatter	编程语言的格式化工具, 它比LSP的设置优先级高. 格式化工具能从标准输入流中获得源文件，向标准输出流写出格式化的文件
soft-wrap	editor.softwrap
text-width	行的最大长度(默认值是editor.text-width),使用命令:reflow 刷新软换行，如果 soft-wrap.wrap-at-text-width 已经设置
workspace-lsp-roots	工程中的相对路径,被看作为LSP的根。应该只在.helix/config.toml中设置

探测文件类型

Helix 通过file-types来决定哪个编程语言配置被使用。file-types 是一列字符串或表格,例如：

file-types = ["Makefile", "toml", { suffix = ".git/config" }]

Helix决定编程语言配置的优先级顺序如下：

1. 精准匹配：如果文件名称能精确匹配 file-types 列表项。例如"Makefile"能匹配Makefile文件.
2. 扩展: 如果没能精确匹配，就匹配文件扩展名,例如"toml"能匹配Cargo.toml 或 languages.toml.
3. 后缀: 如果还未能匹配，那么检查suffix 表中的路径。例如: { suffix = ".git/config" } 会匹配任意在 .git中的config文件。
   
   注意: / 被用于分割目录，实际会根据具体系统环境来配置,例如在Windows中上述配置会匹配为.git\config

编程语言服务

编程语言服务在language-server 中配置

例如：

[language-server.mylang-lsp]
command = "mylang-lsp"
args = ["--stdio"]
config = { provideFormatter = true }
environment = { "ENV1" = "value1", "ENV2" = "value2" }

[language-server.efm-lsp-prettier]
command = "efm-langserver"

[language-server.efm-lsp-prettier.config]
documentFormatting = true
languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] }

These are the available options for a language server.

下列是对一个编程语言服务的可选配置项

配置项	描述
command	编程语言服务可执行文件名称或者路径. 可执行文件的名称需要在$PATH中配置
args	传递给编程语言服务的一系列参数
config	LSP 初始化选项
timeout	向编程语言服务请求的最大等待时间(s) 默认值是:20
environment	启动编程语言服务的环境变量值:{ "KEY1" = "Value1", "KEY2" = "Value2" }

在config 中的子表format 可以传递一些额外的格式化配置项

Document Formatting Requests.

例如，对于typescript:

[language-server.typescript-language-server]
# pass format options according to https://github.com/typescript-language-server/typescript-language-server#workspacedidchangeconfiguration omitting the "[language].format." prefix.
config = { format = { "semicolons" = "insert", "insertSpaceBeforeFunctionParenthesis" = true } }

为一个编程语言配置语言服务

language-servers 配置项设置了一个编程语言的语言服务，这个配置项在[language-server]下定义.

不同的编程语言可以使用相同的编程语言服务,例如 typescript-language-server 默认用于javascript, jsx, tsx 和typescript

通常在language-servers 中会指定多种编程语言服务,所以会经常针对特定语言配置其语言服务是否启动。

例如之前的例子中的efm-lsp-prettier 只会在格式化命令prettier中使用，所以typescript-language-server下应该做好这种配置。

语言服务的配置类似于：

[[language]]
name = "typescript"
language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ]

或者等价于:

[[language]]
name = "typescript"
language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ]

每个LSP特性的请求会按照 language-servers中的排序来处理优先级。

例如：第一个支持 goto-definition的语言服务会接管相关的LSP请求（命令goto_definition)

其他特性例如diagnostics, code-action, completion, document-symbols 和workspace-symbols 也遵循这个规则，当他们在多种语言服务中同时配置生效时。

如果没有配置except-features 或only-features ,那么会启动语言服务的所有特性。如果一个语言服务不支持某个特性，将会尝试下一个语言服务。

支持的特性列表：

• format
• goto-definition
• goto-declaration
• goto-type-definition
• goto-reference
• goto-implementation
• signature-help
• hover
• document-highlight
• completion
• code-action
• workspace-command
• document-symbols
• workspace-symbols
• diagnostics
• rename-symbol
• inlay-hints

Tree-sitter 语法配置

一个语言的tree-sitter语法是在[[grammar]]中配置的

例如：

[[grammar]]
name = "mylang"
source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }

语法配置包括这些配置项

配置项	描述
name	tree-sitter 语法的名称
source	获得语法的方式- 一组参数列表

source是一组参数列表，配置了git仓库的参数

配置项	描述
git	一个语法的git远程仓库URL
rev	需要获取的修订编号(commit hash 值或tag)
subpath	需要编译的语法目录路径.一些语法仓库包括多个语法子目录(如tree-sitter-typescript 和tree-sitter-ocaml),这个配置项用于hx --grammar build命令，如果不设置默认是仓库根目录

选择语法

使用一个顶级配置项use-grammars 来控制获取或编译那些语法.获取和编译命令:hx --grammar fetch 和hx --grammar build

# 注意：这配置项必须在 [[language]] 和 [[grammar]] 字段之前

use-grammars = { only = [ "rust", "c", "cpp" ] }
# or
use-grammars = { except = [ "yaml", "json" ] }

当配置项省略，所有的语法将会被获取并编译