rustfmt

一个用于根据风格指南格式化Rust代码的工具。

如果你想帮忙（你应该，这是一个有趣的项目！），请参阅Contributing.md和我们的行为准则。

你可以在Travis CI构建中使用rustfmt。我们提供了一个最小的Travis CI配置（见此处）。

快速开始

你可以使用Rust 1.24及更高版本运行rustfmt。

在稳定工具链上

安装

rustup component add rustfmt

在当前工作目录中的cargo项目中运行

cargo fmt

在Nightly工具链上

要使用最新和最好的rustfmt，则需要Nightly版本。

安装

rustup component add rustfmt --toolchain nightly

在当前工作目录中的cargo项目中运行

cargo +nightly fmt

限制

Rustfmt试图尽可能多地处理Rust代码。有时，代码甚至不需要编译！通常，我们希望限制不稳定区域的数量；特别是，从1.0版本开始，大多数代码的格式化在Rustfmt改进后不应改变。然而，有一些Rustfmt无法做到或做得不好的事情（因此格式化可能即使在1.0版本后也会发生显著变化）。我们希望随着时间的推移减少限制列表。

以下列表列出了Rustfmt无法工作或稳定性保证不适用的情况（我们不在这两者之间做区分，因为在将来，Rustfmt可能在目前无法工作的代码上工作）。

• 程序中任何部分无法解析（解析是编译的早期阶段，在Rust中包括宏展开）。
• 宏声明和使用（当前状态：一些宏声明和使用已被格式化）。
• 注释，包括任何带有“内部”注释的AST节点（Rustfmt目前不尝试格式化注释，但它格式化带有内部注释的代码，但这种格式化可能在将来发生变化）。
• 注释中的代码块中的Rust代码。
• 程序的任何片段（即，稳定性保证仅适用于整个程序，即使今天可以格式化程序片段）。
• 包含非ASCII Unicode字符的代码（我们相信Rustfmt在这里主要可以工作，但我们没有足够的测试覆盖率或经验来100%确信）。
• Rustfmt的错误（就像任何软件一样，Rustfmt也有错误，我们不认为错误修复会破坏我们的稳定性保证）。

运行

如果您已使用cargo install安装了Rustfmt，则只需输入rustfmt 文件名即可运行Rustfmt。这将运行rustfmt对指定的文件进行格式化，如果文件包含外部模块，则我们也会重新格式化这些模块。因此，要格式化整个模块或crate，只需在根文件（通常是mod.rs或lib.rs）上运行即可。Rustfmt还可以从stdin读取数据。或者，您可以使用cargo fmt来格式化您的crate的所有二进制和库目标。

您可以使用rustfmt -h来获取有关可用参数的信息。针对项目运行rustfmt的最简单方法是使用cargo fmt。cargo fmt适用于单个crate项目和cargo工作空间。请参阅cargo fmt --help以获取使用信息。

您可以通过设置环境变量RUSTFMT来指定cargo使用的自定义rustfmt二进制文件路径。该功能在v1.4.22版本中添加，因此您必须拥有此版本或更高版本才能利用此功能（cargo fmt --version）。

直接运行rustfmt

要格式化单个文件或从stdin读取的任意代码，应使用rustfmt二进制文件。以下是一些示例：

• rustfmt lib.rs main.rs将就地格式化"lib.rs"和"main.rs"。
• rustfmt将读取来自stdin的代码并将其格式化写入stdout。
  • echo "fn main() {}" | rustfmt将输出"fn main() {"。

有关更多信息，包括参数和输出选项，请参阅rustfmt -h。

验证代码格式化

当使用--check运行时，如果Rustfmt对输入没有进行任何格式化更改，它将以0退出，如果Rustfmt会进行更改，则以1退出。在其他模式下，如果在格式化过程中发生错误（例如解析或内部错误），Rustfmt将以1退出，如果没有错误完成格式化（无论是否进行了更改），则将以0退出。

在您的编辑器中运行Rustfmt

• Vim
• Emacs
• Sublime Text 3
• Atom
• Visual Studio Code
• IntelliJ或CLion

在CI服务器上检查样式

为了保持代码库格式的一致性，当拉取请求包含未格式化的代码时，使CI构建失败可能很有帮助。使用--check指令使rustfmt在输入格式不正确时以错误代码退出。它还会打印出找到的所有差异。（较旧版本的Rustfmt不支持--check，请使用--write-mode diff）。

一个最小的Travis设置可能如下所示（需要Rust 1.31.0或更高版本）

language: rust
before_script:
- rustup component add rustfmt
script:
- cargo build
- cargo test
- cargo fmt --all -- --check

有关更多信息，请参阅此博客文章。

如何构建和测试

使用cargo build来构建。

使用cargo test来运行所有测试。

之后要运行rustfmt，请使用cargo run --bin rustfmt -- filename。请参阅上述关于运行rustfmt的说明。

配置Rustfmt

Rustfmt设计得非常灵活。您可以创建一个名为rustfmt.toml或.rustfmt.toml的TOML文件，将其放置在项目或任何其他父目录中，它将应用该文件中的选项。有关可用选项的详细信息，请参阅rustfmt --help=config，或者如果您想查看视觉样式预览，请访问GitHub页面。

默认情况下，Rustfmt使用一种符合通过样式RFC流程形式化的Rust样式指南的样式。

配置选项要么是稳定的，要么是不稳定的。稳定选项始终可以使用，而不稳定的选项仅在夜间工具链上可用，并且需要选择。有关详细信息，请参阅GitHub页面。

Rust的版本

Rustfmt能够通过读取Cargo.toml文件来获取使用的版本，如果通过Cargo的格式化工具cargo fmt执行。否则，需要在rustfmt.toml中指定版本，例如使用edition = "2018"。

提示

• 对于您不希望rustfmt破坏的东西，请使用#[rustfmt::skip]

• 为了防止 rustfmt 格式化宏或属性，请使用以下代码：#[rustfmt::skip::macros(目标宏名称)] 或 #[rustfmt::skip::attributes(目标属性名称)]

  示例

  #![rustfmt::skip::attributes(custom_attribute)]
  
  #[custom_attribute(formatting , here , should , be , Skipped)]
  #[rustfmt::skip::macros(html)]
  fn main() {
      let macro_result1 = html! { <div>
  Hello</div>
      }.to_string();
  

• 当你运行 rustfmt 时，请将名为 rustfmt.toml 或 .rustfmt.toml 的文件放置在目标文件目录或其父目录中，以覆盖 rustfmt 的默认设置。你可以使用 rustfmt --print-config default rustfmt.toml 命令生成包含默认配置的文件，并根据需要自定义。

• 成功编译后，可以在目标目录中找到 rustfmt 可执行文件。

• 如果你在编译 Rustfmt 时遇到问题（或在尝试安装时出现编译错误），请确保你已安装最新版本的 Rust。

• 你可以使用 --emit 标志改变 rustfmt 输出更改的方式

  示例

  cargo fmt -- --emit files
  

  选项

  标志	描述	夜间仅用
  文件	覆盖输出到文件	否
  stdout	将输出写入 stdout	否
  覆盖率	显示输入文件处理了多少	是
  checkstyle	以 checkstyle 格式输出	是
  json	以 json 格式输出差异	是

许可证

Rustfmt 在 MIT 许可证和 Apache 许可证（版本 2.0）的条款下分发。

有关详细信息，请参阅 LICENSE-APACHE 和 LICENSE-MIT。