示例

构建完成后，程序可以像这样运行

echo '{"foo":"bar"}' | topiary fmt --language json

topiary 还可以通过 Cargo 或 Nix 构建 和运行，如果您已安装它们

echo '{"foo":"bar"}' | cargo run -- fmt --language json
echo '{"foo":"bar"}' | nix run . -- fmt --language json

它将输出以下格式化代码

{ "foo": "bar" }

配置

Topiary 使用 languages.toml 文件进行配置。Topiary 检查此类文件的上限有四个来源。

配置来源

在构建时，此存储库根目录中的 languages.toml 被嵌入到 Topiary 中。该文件在运行时被解析。此 languages.toml 文件的作用是为 Topiary 的用户提供合理的默认值（包括库和二进制文件）。

接下来两个在运行时被 Topiary 二进制读取，并允许用户根据需要配置 Topiary。第一个旨在用于特定用户，因此可以找到在 OS 的配置目录中

此文件不是由 Topiary 自动创建的。

下一个来源旨在作为 Topiary 的特定项目设置文件。当在某个目录中运行 Topiary 时，它会向上遍历文件树，直到找到 .topiary 目录。然后它会读取该目录中存在的任何 languages.toml 文件。

最后，可以使用 -C/--configuration 命令行参数（或 TOPIARY_CONFIG_FILE 环境变量）指定显式的配置文件。这旨在针对非常特定的使用情况来驱动 Topiary。

Topiary 二进制文件按以下顺序解析这些来源。对匹配项进行合并的操作取决于 合并模式。

1. 内置配置文件。
2. 在操作系统的配置目录中的用户配置文件。
3. 特定项目的 Topiary 配置。
4. 作为 CLI 参数指定的显式配置文件。

配置选项

配置文件包含一个语言列表，每个语言配置以 [[language]] 开头。例如，Nickel 的配置如下定义

[[language]]
name = "nickel"
extensions = ["ncl"]

name 字段被 Topiary 用于将语言条目与查询文件和 Tree-sitter 语法相关联。此值应小写。每个配置文件中的每个 [[language]] 块中的 name 字段都是必需的。

每个语言的扩展列表都是必需的，但不必在每个配置文件中都存在。对于每种语言，只要有一个配置文件定义了该语言的扩展列表，就足够了。

一个可选的最终字段，称为 indent，用于定义该语言的缩进方法。如果 Topiary 在任何配置文件中找不到特定语言的缩进字段，它将默认为两个空格 " "。

配置合并

当从多个来源解析配置时，Topiary 可以以各种方式合并匹配的配置项（按语言名称匹配）。合并模式由 --configuration-collation 命令行参数（或 TOPIARY_CONFIG_COLLATION 环境变量）设置。

不同的模式最好通过示例来解释。考虑以下两个配置，按优先级从低到高（为了说明目的添加了注释）

# Lowest priority configuration

[[language]]
name = "example"
extensions = ["eg"]

[[language]]
name = "demo"
extensions = ["demo"]

# Highest priority configuration

[[language]]
name = "example"
extensions = ["example"]
indent = "    "

合并模式（默认）

匹配的项目将从优先级较高的来源更新，集合合并为集合的并集。

# For the "example" language:
# * The collated extensions is the union of the source extensions
# * The indentation is taken from the highest priority source
[[language]]
name = "example"
extensions = ["eg", "example"]
indent = "    "

# The "demo" language is unchanged
[[language]]
name = "demo"
extensions = ["demo"]

修订模式

匹配的项目（包括集合）将替换为优先级较高的来源。

# The "example" language's values are taken from the highest priority source
[[language]]
name = "example"
extensions = ["example"]
indent = "    "

# The "demo" language is unchanged
[[language]]
name = "demo"
extensions = ["demo"]

覆盖模式

取最高优先级的来源。丢弃来自优先级较低来源的所有值。

# The "example" language's values are taken from the highest priority source
[[language]]
name = "example"
extensions = ["example"]
indent = "    "

# The "demo" language does not exist in the highest priority source, so is omitted

设计

只要为语言定义了 Tree-sitter 语法，Tree-sitter 就可以解析它并提供具体的语法树（CST）。Tree-sitter 还将允许我们对这个树运行查询。我们可以利用这一点来定义语言应该如何格式化。以下是一个查询示例

[
  (infix_operator)
  "if"
  ":"
] @append_space

这将匹配语法已识别为 infix_operator 的任何节点，以及包含 if 或 : 的任何匿名节点。匹配将以 @append_space 的名称捕获。我们的格式化器会遍历所有匹配和捕获，并在处理任何名为 @append_space 的捕获时，在匹配的节点后添加一个空格。

格式化器遍历CST节点，检测所有跨越多行的节点。这被解释为程序员在输入中给出的指示，即相关节点应该格式化为多行。其他节点将格式化为单行。每当查询匹配插入了一个 软换行符，如果节点是多行的，它将被扩展为一个换行符；如果节点是单行的，则根据是否使用了 @append_spaced_softline 或 @append_empty_softline，它将被扩展为一个空格或无内容。

在渲染输出之前，格式化器将执行多项清理操作，例如将连续的空格和新行缩减为一个，修剪行尾的空格以及首尾的空白行，并一致地排序缩进和换行指令。

这意味着例如，你可以在 if 和 true 前后添加空格，我们仍然会输出 if true，单词之间只有一个空格。

支持的捕获指令

这假设你已经熟悉了 Tree-sitter查询语言。

请注意，捕获被放置在其相关节点之后。如果你想在一个节点前放置一个空格，你可以这样做

(infix_operator) @prepend_space

另一方面，这不会起作用

@append_space (infix_operator)

@allow_blank_line_before

如果输入中指定，匹配的节点将被允许在其前面有一个空白行。对于任何其他节点，空白行将被删除。

示例

; Allow comments and type definitions to have a blank line above them
[
  (comment)
  (type_definition)
] @allow_blank_line_before

@append_delimiter / @prepend_delimiter

匹配的节点将附加一个分隔符。分隔符必须使用谓词 #delimiter! 指定。

示例

; Put a semicolon delimiter after field declarations, unless they already have
; one, in which case we do nothing.
(
  (field_declaration) @append_delimiter
  .
  ";"* @do_nothing
  (#delimiter! ";")
)

如果已经存在分号，则将激活 @do_nothing 指令，并防止查询中的其他指令（这里的 @append_delimiter）应用。否则，";"* 捕获不到任何内容，在这种情况下，相关的指令（@do_nothing）不会激活。

请注意，当分隔符设置为 " "（即，一个空格）时，@append_delimiter 与 @append_space 相同。

@append_multiline_delimiter / @prepend_multiline_delimiter

匹配的节点将附加一个仅适用于多行的分隔符。它将仅在多行节点中打印，在单行节点中省略。分隔符必须使用谓词 #delimiter! 指定。

示例

; Add a semicolon at the end of lists only if they are multi-line, to avoid [1; 2; 3;].
(list_expression
  (#delimiter! ";")
  (_) @append_multiline_delimiter
  .
  ";"? @do_nothing
  .
  "]"
  .
)

如果已经存在分号，则将激活 @do_nothing 指令，并阻止查询（此处为 @append_multiline_delimiter）中的其他指令应用。同样，如果节点是单行，则也不会添加分隔符。

@append_empty_softline / @prepend_empty_softline

匹配的节点将添加或前置一个空软行。对于多行节点，这将展开为换行符，对于单行节点则不会。

示例

; Put an empty softline before dots, so that in multi-line constructs we start
; new lines for each dot.
(_
  "." @prepend_empty_softline
)

@append_hardline / @prepend_hardline

匹配的节点将添加或前置一个换行符。

示例

; Consecutive definitions must be separated by line breaks
(
  (value_definition) @append_hardline
  .
  (value_definition)
)

@append_indent_start / @prepend_indent_start

匹配的节点将在其前后触发缩进。这仅适用于后续行，直到接收到缩进结束信号。如果在同一行开始和结束缩进，则不会发生任何操作。这很有用，因为无论节点是单行还是多行格式，我们都能得到正确的行为。所有缩进开始和结束都必须平衡。

示例

; Start an indented block after these
[
  "begin"
  "else"
  "then"
  "{"
] @append_indent_start

@append_indent_end / @prepend_indent_end

匹配的节点将触发在它们前后结束缩进。

示例

; End the indented block before these
[
  "end"
  "}"
] @prepend_indent_end

; End the indented block after these
[
  (else_clause)
  (then_clause)
] @append_indent_end

@append_input_softline / @prepend_input_softline

匹配的节点将添加或前置一个输入软行。输入软行是如果节点在输入文档的前面有换行符，则为换行符，否则为空格。

示例

; Input softlines before and after all comments. This means that the input
; decides if a comment should have line breaks before or after. But don't put a
; softline directly in front of commas or semicolons.

(comment) @prepend_input_softline

(
  (comment) @append_input_softline
  .
  [ "," ";" ]* @do_nothing
)

@append_space / @prepend_space

匹配的节点将添加或前置一个空格。注意，这与 @append_delimiter / @prepend_delimiter 相同，但分隔符为空格。

示例

[
  (infix_operator)
  "if"
  ":"
] @append_space

@append_antispace / @prepend_antispace

通常情况下，标记需要与空格相邻，除了在少数孤立的情况下。而不是编写复杂规则来列举每个异常，可以使用 @append_antispace / @prepend_antispace 插入“反空格”，这将销毁该节点上的任何空格（不包括换行符），包括由其他格式化规则添加的。

示例

[
  ","
  ";"
  ":"
  "."
] @prepend_antispace

@append_spaced_softline / @prepend_spaced_softline

匹配的节点将添加或前置一个带空格的软行。对于多行节点，这将展开为换行符，对于单行节点则为空格。

示例

; Append spaced softlines, unless there is a comment following.
(
  [
    "begin"
    "else"
    "then"
    "->"
    "{"
    ";"
  ] @append_spaced_softline
  .
  (comment)* @do_nothing
)

@删除

从输出中删除匹配的节点。

示例

; Move semicolon after comments.
(
  ";" @delete
  .
  (comment)+ @append_delimiter
  (#delimiter! ";")
)

@do_nothing

如果查询中任何捕获匹配 @do_nothing，则匹配将被忽略。

示例

; Put a semicolon delimiter after field declarations, unless they already have
; one, in which case we do nothing.
(
  (field_declaration) @append_delimiter
  .
  ";"* @do_nothing
  (#delimiter! ";")
)

@multi_line_indent_all

用于注释或其他叶节点，表示我们应该缩进其所有行，而不仅仅是第一行。

示例

(#language! ocaml)
(comment) @multi_line_indent_all

@single_line_no_indent

匹配的节点将以单行打印，没有缩进。

示例

(#language! ocaml)
; line number directives must be alone on their line, and can't be indented
(line_number_directive) @single_line_no_indent

理解不同的换行符捕获

"输入软行"在目标节点后跟换行符时将被渲染为新行。否则，它们将被渲染为空格。

示例

考虑以下JSON，它已经被手动格式化为展示不同换行捕获名称在哪些上下文中运行

{
  "single-line": [1, 2, 3, 4],
  "multi-line": [
    1, 2,
    3
    , 4
  ]
}

我们将应用一组简化的JSON格式查询，

1. 为对象打开（并关闭）缩进的块；
2. 每个键值对都占一行，值被分割到第二行；
3. 在数组分隔符上应用不同的换行捕获名称。

也就是说，遍历每个 @NEWLINE 类型，我们应用以下

(#language! json)

(object . "{" @append_hardline @append_indent_start)
(object "}" @prepend_hardline @prepend_indent_end .)
(object (pair) @prepend_hardline)
(pair . _ ":" @append_hardline)

(array "," @NEWLINE)

前两条格式化规则只是为了清晰起见。最后一条规则才是重要的；其结果如下所示

@append_hardline

{
  "single-line":
  [1,
  2,
  3,
  4],
  "multi-line":
  [1,
  2,
  3,
  4]
}

@prepend_hardline

{
  "single-line":
  [1
  ,2
  ,3
  ,4],
  "multi-line":
  [1
  ,2
  ,3
  ,4]
}

@append_empty_softline

{
  "single-line":
  [1,2,3,4],
  "multi-line":
  [1,
  2,
  3,
  4]
}

@prepend_empty_softline

{
  "single-line":
  [1,2,3,4],
  "multi-line":
  [1
  ,2
  ,3
  ,4]
}

@append_spaced_softline

{
  "single-line":
  [1, 2, 3, 4],
  "multi-line":
  [1,
  2,
  3,
  4]
}

@prepend_spaced_softline

{
  "single-line":
  [1 ,2 ,3 ,4],
  "multi-line":
  [1
  ,2
  ,3
  ,4]
}

@append_input_softline

{
  "single-line":
  [1, 2, 3, 4],
  "multi-line":
  [1, 2,
  3, 4]
}

@prepend_input_softline

{
  "single-line":
  [1 ,2 ,3 ,4],
  "multi-line":
  [1 ,2 ,3
  ,4]
}

自定义作用域和软行

到目前为止，我们已经根据与它们关联的CST节点是多行还是单行，将软行扩展为换行符。有时，CST节点定义的作用域太大或太小，不符合我们的需求。例如，考虑以下OCaml代码片段

(1,2,
3)

其CST如下

{Node parenthesized_expression (0, 0) - (1, 2)} - Named: true
  {Node ( (0, 0) - (0, 1)} - Named: false
  {Node product_expression (0, 1) - (1, 1)} - Named: true
    {Node product_expression (0, 1) - (0, 4)} - Named: true
      {Node number (0, 1) - (0, 2)} - Named: true
      {Node , (0, 2) - (0, 3)} - Named: false
      {Node number (0, 3) - (0, 4)} - Named: true
    {Node , (0, 4) - (0, 5)} - Named: false
    {Node number (1, 0) - (1, 1)} - Named: true
  {Node ) (1, 1) - (1, 2)} - Named: false

我们希望在第一个逗号后添加换行符，但由于CST结构是嵌套的，包含此逗号的节点（product_expression (0, 1) - (0, 4)）不是多行的。只有顶级节点 product_expression (0, 1) - (1, 1)是多行的。

为了解决这个问题，我们引入用户定义的作用域和软行。

@prepend_begin_scope / @append_begin_scope / @prepend_end_scope / @append_end_scope

这些标签用于定义自定义作用域。与 #scope_id! 谓词结合使用，它们定义可以跨越多个CST节点或仅跨越一个部分的作用域。例如，此作用域匹配 parenthesized_expression 中括号内的任何内容

(parenthesized_expression
  "(" @append_begin_scope
  ")" @prepend_end_scope
  (#scope_id! "tuple")
)

作用域内的软行

我们定义了四个谓词，它们与 #scope_id! 谓词结合，在自定义作用域中插入软行

• @prepend_empty_scoped_softline
• @prepend_spaced_scoped_softline
• @append_empty_scoped_softline
• @append_spaced_scoped_softline

当使用这些作用域内的软行之一时，它们的行为取决于最内层的对应 scope_id 的作用域。如果该作用域是多行的，则软行扩展为换行符。在其他方面，它们的行为与它们的非 scoped 对应物相同。

示例

此Tree-sitter查询

(#language! ocaml)

(parenthesized_expression
  "(" @begin_scope @append_empty_softline @append_indent_start
  ")" @end_scope @prepend_empty_softline @prepend_indent_end
  (#scope_id! "tuple")
)

(product_expression
  "," @append_spaced_scoped_softline
  (#scope_id! "tuple")
)

...格式化此代码片段

(1,2,
3)

...如下

(
  1,
  2,
  3
)

...而单行的 (1, 2, 3) 保持不变。

; Allow (and enforce) the optional "|" before the first match case
; in OCaml if and only if the context is multi-line
(
  "with"
  .
  "|" @delete
  .
  (match_case)
  (#single_line_only!)
)

(
  "with"
  .
  "|"? @do_nothing
  .
  (match_case) @prepend_delimiter
  (#delimiter! "| ")
  (#multi_line_only!)
)

; Allow (and enforce) the optional "|" before the first match case
; in function expressions in OCaml if and only if the scope is multi-line
(function_expression
  (match_case)? @do_nothing
  .
  "|" @delete
  .
  (match_case)
  (#single_line_scope_only! "function_definition")
)
(function_expression
  "|"? @do_nothing
  .
  (match_case) @prepend_delimiter
  (#multi_line_scope_only! "function_definition")
  (#delimiter! "| ") ; sic
)

Usage: ${PROGNAME} LANGUAGE [QUERY_FILE] [INPUT_SOURCE]

LANGUAGE can be one of the supported languages (e.g., "ocaml", "rust",
etc.). The packaged formatting queries for this language can be
overridden by specifying a QUERY_FILE.

The INPUT_SOURCE is optional. If not specified, it defaults to trying
to find the bundled integration test input file for the given language.