Sway 代码格式化工具（swayfmt）是一个根据预定义样式指南自动格式化 Sway 源代码的工具，类似于 Rust 的 rustfmt。它为 Sway 项目提供一致、标准化的格式，并且可以通过配置文件进行自定义。本文档概述了代码格式化工具的架构和功能、其配置选项以及它如何与 Sway 生态系统集成。
代码格式化工具的设计侧重于解析 Sway 源代码、根据样式规则对其进行转换以及保留注释和换行符。以下是格式化工具架构的高级概述：
图：代码格式化工具架构
来源
核心组件是 Formatter 结构体，它协调整个格式化过程。
图：关键格式化工具组件
来源
格式化工具遵循以下关键步骤来处理源代码：
Format trait 实现，根据样式规则格式化每个 AST 节点。格式化逻辑的核心是通过 Format trait 实现的。
图：Format Trait 实现
来源
格式化工具最复杂的方面之一是在重新格式化代码的同时保留注释和空白字符。
图：注释和空白字符处理
来源
格式化工具支持几种类型的注释：
| 注释类型 | 描述 | 示例 |
|---|---|---|
| 新行注释 | 前面带换行符的注释 | // This is a newlined comment |
| 行尾注释 | 行末注释 | let x = 5; // This is a trailing comment |
| 行内注释 | 位于标记之间的块注释 | fn foo(/* inlined comment */ x: u64) |
| 多行注释 | 跨越多行的块注释 | /* This is a\n multilined\n comment */ |
来源
格式化工具可以通过在 Sway 项目根目录放置 swayfmt.toml 配置文件进行自定义。
| 选项 | 描述 | 默认 |
|---|---|---|
max_width | 最大行宽 | 100 |
tab_spaces | 制表符空格数 | 4 |
newline_style | 换行符样式（Auto、Native、Unix、Windows） | 汽车 |
newline_threshold | 最大连续换行符数 | 2 |
| 选项 | 描述 | 默认 |
|---|---|---|
field_alignment | 结构体字段对齐 | 关闭 |
small_structures_single_line | 将小型结构体格式化为单行 | false |
field_alignment 选项可以设置为：
Off：无对齐AlignFields(threshold)：如果字段名长度低于阈值，则对齐字段冒号字段对齐示例
// Without alignment (Off)
struct Example {
short: u64,
very_long_field_name: bool,
}
// With alignment (AlignFields(20))
struct Example {
short : u64,
very_long_field_name: bool,
}
来源
函数会进行适当的间距和缩进格式化。
pub fn example_function(
param1: u64,
param2: bool,
) -> bool {
// Function body
true
}
当函数包含 where 子句时，它会在新行上格式化。
pub fn generic_function<T>(param: T) -> T
where
T: MyTrait,
{
// Function body
param
}
来源
if、match、while 和 for 等控制流构造会以一致的间距进行格式化。
if condition {
// Then block
} else if another_condition {
// Else-if block
} else {
// Else block
}
match value {
Pattern1 => expression1,
Pattern2 => {
// Block expression
expression2
},
}
来源
表达式根据其复杂性进行格式化。格式化工具使用启发式方法来确定何时使用多行格式化。
// Short expressions on one line
let result = a + b;
// Complex expressions broken into multiple lines
let complex_result = very_long_expression()
.method_call()
.another_method_call();
来源
格式化工具可以通过两种方式使用：
forc fmt：Fuel Orchestrator (forc) 提供了一个格式化命令。Formatter 结构体。用于编程使用
用于自定义配置
该格式化工具已与 Sway 语言服务器协议（LSP）实现集成，为支持 LSP 的 IDE 和编辑器提供格式化功能。
图：格式化工具与 LSP 集成
当语言服务器接收到格式化请求时，它会使用 swayfmt 格式化工具对文档进行格式化，并将格式化后的文本返回给 IDE/编辑器。
Sway 代码格式化工具提供了一种一致的、可配置的方法来格式化 Sway 代码。通过将格式化逻辑分离到不同的组件中，并为不同的 AST 节点实现 Format trait，它实现了模块化和可扩展的设计。凭借其保留注释和敏感处理空白字符的能力，它在强制执行一致风格的同时，保持了代码的语义意义和可读性。