typstyle

使用方法

作为 CLI 使用

安装

1. 从 发布页面 下载二进制文件
2. 使用您的包管理器安装： https://repology.org/project/typstyle/versions
3. 使用 cargo-binstall 安装： cargo binstall typstyle
4. 使用 cargo 安装： cargo install typstyle --locked

使用方法

Beautiful and reliable typst code formatter

Usage: typstyle.exe [OPTIONS] [INPUT]... [COMMAND]

Commands:
  format-all  Format all files in-place in the given directory
  help        Print this message or the help of the given subcommand(s)

Arguments:
  [INPUT]...  Path to the input files, if not provided, read from stdin. If multiple files are provided, they will be processed in order

Options:
  -c, --column <COLUMN>  The column width of the output [default: 80]
  -a, --ast              Print the AST of the input file
  -p, --pretty-doc       Print the pretty document
  -i, --inplace          Format the file in place
      --check            Run in 'check' mode. Exits with 0 if input is formatted correctly. Exits with 1 if formatting is required
  -h, --help             Print help
  -V, --version          Print version

典型使用方法

• 就地格式化文件

typstyle -i file.typ

• 格式化文件并将结果打印到 stdout

typstyle file.typ

• 就地格式化文件列表

typstyle -i file1.typ file2.typ file3.typ

• 格式化目录中的所有文件。如果没有提供，它将递归地格式化当前目录中的所有文件

typstyle format-all dir

• 从 stdin 读取并打印结果到 stdout

cat file.typ | typstyle > file-formatted.typ

在编辑器中使用

typstyle 已集成到 tinymist。您可以通过安装 tinymist 插件并将 tinymist.formatterMode 设置为 typstyle 在您的编辑器中使用它。

作为网络应用使用

在 https://enter-tainer.github.io/typstyle/ 上有一个格式化器的在线版本，您可以查看它是如何格式化您的代码的。

与pre-commit一起使用

将以下内容添加到您的.pre-commit-config.yaml

  - repo: https://github.com/Enter-tainer/typstyle
    rev: ''  # The the revision or tag you want to use
    hooks:
      - id: typstyle

逃生舱

如果您发现typstyle的表现不符合预期，您可以使用// @typstyle off或/* @typstyle off */来禁用下一个代码节点上的格式化器。

如果typstyle无法正确格式化代码，它也会放弃格式化代码的一部分。具体来说，如果

• 包含语法错误
• 包含格式化器不支持的语言

请通过在GitHub仓库创建问题来告知我们问题

设计目标

1. 有意见：我们希望所有代码库的风格保持一致。
2. 仅代码：我们只想格式化代码。内容应尽可能保持不变。
3. 收敛：运行格式化器两次不应更改代码。
4. 正确性：格式化器不应更改渲染输出的外观。

测试

cargo nextest run -E 'not test(~e2e)' --no-fail-fast
cargo insta review

我们已经设置了多个测试

1. 收敛测试：应用两次格式化后结果必须相同
2. 快照测试：格式化结果存储在snapshots目录中，并在运行测试时与当前结果进行比较
3. 正确性测试：我们比较格式化前后代码的渲染输出，并确保它们相同
4. 端到端正确性测试：我们收集了包括tablex、cetz、fletcher等在内的多个typst代码仓库，并将它们格式化以确保（a）格式化结果收敛和（b）渲染输出相同。

作为库使用

• npm：https://npmjs.net.cn/package/typstyle
• rust：https://crates.io/crates/typstyle

已知问题

告诉我们！格式化不良？输出不正确？请在GitHub仓库创建问题！

我们已经建立了全面的测试套件以确保格式化器的正确性。如果您发现任何问题，请告知我们！我们可以添加更多测试以防止问题再次发生。

为什么还需要另一个格式化器？

为什么还需要另一个格式化器？我们已经有了typstfmt、typstfmt、prettypst。为什么还需要另一个？

typstyle的起因是我有一堆关于如何改进typst源代码格式的想法，但始终发现typstfmt不是一个好的代码库来探索这些想法。

• 我想使用Wadler的漂亮打印机以任何宽度获得一致和美观的输出。（注意，这与prettier格式化器使用的相同技术）
• 我没有太多精力来维护一大堆配置选项组合。事实证明，使所有这些都正确是非常困难的。因此，我决定让它具有意见。
• 我想尝试更多的测试技术并确保格式化器是正确的。

因此，我决定从头开始编写。大约半年前我开始，并在业余时间继续工作。目前它缺少一些高级功能，但它已经可以用于大多数情况。希望您喜欢它！