swift-format

swift-format 为 SourceKit-LSP 提供格式化技术，并为代码格式化转换提供构建模块。

此软件包可用作命令行工具，或作为 Swift Package Manager 依赖项链接到其他应用程序中，并通过 API 调用。

注意：目前尚未提出默认的 Swift 代码风格指南。 swift-format 当前应用的风格只是一种可能性，提供此代码是为了可以在真实的代码上进行测试，并且可以通过修改来进行实验。

从 Swift 5.8 开始，swift-format 依赖于 SwiftSyntax 的版本，其解析器已用 Swift 重写，不再依赖 Swift 工具链中的库。

此更改允许使用可以编译它的任何 Swift 版本来构建、开发和运行 swift-format，使其与支持特定语法的版本分离。但是，早期版本的 swift-format 仍然无法识别在更高版本的语言和解析器中添加的新语法。

另请注意，版本编号方案已更改为与 SwiftSyntax 匹配； swift-format 的 5.8 版本是 508.0.0，而不是 0.50800.0。

swift-format 0.50700.0 及更早版本依赖于 SwiftSyntax 的版本，这些版本使用作为 Swift 工具链一部分分发的独立解析库。 使用这些版本时，应检出并从与您使用的 Swift 版本兼容的发布标签或分支构建 swift-format。

swift-format 和 SwiftSyntax 的主版本和次版本组件必须相同——这在 Package.swift 中的 SwiftSyntax 依赖项中表达——并且这些版本组件必须与已安装并用于构建和运行格式化程序的 Swift 工具链匹配。

例如，如果您使用 Xcode 13.3 (Swift 5.6)，则需要 swift-format 0.50600.0。

如果您主要对使用 swift-format 感兴趣（而不是开发它），那么在确定所需的版本后，您可以检出源代码并使用以下命令进行构建

VERSION=508.0.0  # replace this with the version you need
git clone https://github.com/apple/swift-format.git
cd swift-format
git checkout "tags/$VERSION"
swift build -c release

请注意，上面的 git checkout 命令会将存储库置于“detached HEAD”状态。 如果构建和运行该工具是您要做的全部，这很好。

构建完成后，swift-format 可执行文件将位于 .build/release/swift-format。

要测试格式化程序是否已成功构建并且与您的 Swift 工具链兼容，您还可以运行以下命令

swift test --parallel

我们建议使用 --parallel 标志来加快测试运行速度，因为有大量测试。

swift-format 的一般调用语法如下

swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]

该工具支持许多子命令，每个子命令都有自己的选项，如下所述。 还可以通过运行 swift-format --help 来获得可用子命令的描述，并且可以通过在子命令名称后使用 --help 标志来获得特定子命令的描述； 例如，swift-format lint --help。

swift-format [format] [OPTIONS...] [FILES...]

format 子命令格式化一个或多个 Swift 源文件（如果命令行上未给出文件路径，则格式化来自标准输入的源代码）。 写出 format 子命令是可选的； 如果未给出其他子命令，则它是默认行为。

此子命令支持所有常见的 lint 和 format 选项，以及以下仅格式化选项

• -i/--in-place：格式化时覆盖输入文件，而不是将结果打印到标准输出。 覆盖之前不会备份原始文件。

swift-format lint [OPTIONS...] [FILES...]

lint 子命令检查一个或多个 Swift 源文件（如果命令行上未给出文件路径，则检查来自标准输入的源代码）是否存在样式违规，并将任何检测到的违规的诊断信息打印到标准错误。

此子命令支持所有常见的 lint 和 format 选项，以及以下仅 linting 选项

• -s/--strict：如果指定此选项，则 lint 警告将导致该工具以非零退出代码（失败）退出。 默认情况下，lint 警告不会阻止成功退出； 只有致命错误（例如，尝试 lint 一个不存在的文件）才会导致该工具退出失败。

format 和 lint 子命令都支持以下选项

• --assume-filename <path>：从标准输入进行 linting 或格式化时，应在诊断中使用的文件路径。 如果未提供此选项，则 <stdin> 将用作诊断中打印的文件名。

• --color-diagnostics/--no-color-diagnostics：默认情况下，如果标准错误连接到终端，swift-format 将以彩色打印诊断信息，否则不带颜色（例如，如果标准错误被重定向到文件）。 这些标志可用于分别强制打开或关闭颜色，而不管输出是否进入终端。

• --configuration <file>：包含 swift-format 的可配置设置的 JSON 文件的路径。 如果省略，则使用默认配置（可以通过运行 swift-format dump-configuration 查看）。

• --ignore-unparsable-files：如果指定此选项，并且源文件包含语法错误或 Swift 语法解析器无法成功解析，则该文件将被忽略（不会发出任何诊断信息，也不会被格式化）。 如果没有此选项，则会为任何无法解析的文件发出错误。

• -p/--parallel：并行处理文件，同时跨多个内核。

• -r/--recursive：如果指定，则该工具将处理命令行上列出的任何目录及其子目录中的 .swift 源文件。 如果没有此标志，则在命令行上列出目录会出错。

swift-format dump-configuration

dump-configuration 子命令将默认配置以 JSON 格式转储到标准输出。 这可以通过将其重定向到文件并进行编辑来简化生成自定义配置。

对于正在检查或格式化的任何源文件，swift-format 都会在同一目录中查找名为 .swift-format 的 JSON 格式文件。 如果找到，则加载该文件以确定该工具的配置。 如果找不到该文件，则它会在父目录中查找，依此类推。

如果未找到配置文件，则使用默认配置。 可以通过运行 swift-format --mode dump-configuration 来查看默认配置中的设置，该命令会将其转储到标准输出。

如果将 --configuration <file> 选项传递给 swift-format，则将无条件地使用该配置，并且不会搜索文件系统。

有关配置文件格式和可用设置的说明，请参阅 Documentation/Configuration.md。

运行 swift-format -v 或 swift-format --version 将打印有关 swift-format 版本的版本信息，然后退出。

swift-format 可以轻松集成到用 Swift 编写的其他工具中。 用户可以依赖 swift-format 作为 Swift Package Manager 依赖项并导入 SwiftFormat 模块，而不是通过生成子进程来调用格式化程序，该模块包含格式化程序的诊断和更正行为的入口点。

格式化行为由 SwiftFormatter 类提供，linting 行为由 SwiftLinter 类提供。 这些 API 可以传递 Swift 源文件 URL 或表示 SwiftSyntax 语法树的 Syntax 节点。 后一种能力对于编写代码生成器特别有用，因为它大大减少了生成器需要担心添加到它创建的语法节点中的琐事量。 相反，它可以将内存中的语法树传递给 SwiftFormat API，并接收完美格式化的代码作为输出。

有关其用法的更多信息，请参阅 SwiftFormatter 和 SwiftLinter 类中的文档。

main 分支用于开发。 应该创建拉取请求以合并到 main 分支中； 在合并到 main 后，可以将低风险且与最新发布分支兼容的更改选择性地添加到该分支中。

如果您对开发 swift-format 感兴趣，则可以在此处找到有关该主题的更多文档。