Swiftpack.co - Package - apple/swift-format

swift-format

swift-format provides the formatting technology for SourceKit-LSP and the building blocks for doing code formatting transformations.

This package can be used as a command line tool or linked into other applications as a Swift Package Manager dependency and invoked via an API.

NOTE: No default Swift code style guidelines have yet been proposed. The style that is currently applied by swift-format is just one possibility, and the code is provided so that it can be tested on real-world code and experiments can be made by modifying it.

Matching swift-format to Your Swift Version

swift-format depends on SwiftSyntax and the standalone parsing library that is distributed as part of the Swift toolchain. The SwiftSyntax version in use must match the toolchain version, so you should check out and build swift-format from the branch that is compatible with the version of Swift you are using. This version dependency is also expressed in the SwiftSyntax dependency in Package.swift.

| Xcode Release | Swift Version | swift-format Branch | |:-------------:|:---------------------------------------:|:----------------------| | – | Swift at master | master | | Xcode 12.0 | Swift 5.3 | swift-5.3-branch | | Xcode 11.4 | Swift 5.2 | swift-5.2-branch | | Xcode 11.0 | Swift 5.1 | swift-5.1-branch |

For example, if you are using Xcode 12.0 (Swift 5.3), you can check out and build swift-format using the following commands:

git clone -b swift-5.3-branch https://github.com/apple/swift-format.git
cd swift-format
swift build

You can also add the --single-branch option if you only want to clone that specific branch.

The master branch is used for development and may depend on either a release version of Swift or on a developer snapshot. Changes committed to master that are compatible with the latest release branch will be cherry-picked into that branch.

To test that the formatter was built succesfully and is compatible with your Swift toolchain, you can run the following command:

swift test --parallel

We recommend using the --parallel flag to speed up the test run since there are a large number of tests.

Command Line Usage

swift-format [OPTIONS] FILE...

The swift-format tool can be invoked with one or more .swift source files, as well as the following command line options:

  • -v/--version: Prints the swift-format version and exits.

  • -m/--mode <format|lint|dump-configuration>: The mode in which to run swift-format. The format mode formats source files. The lint mode only prints diagnostics indicating style violations. The dump-configuration mode dumps the default swift-format configuration to standard output.

    If unspecified, the default mode is format.

  • --configuration <file>: The path to a JSON file that contains configurable settings for swift-format. If omitted, a default configuration is use (which can be seen by running --mode dump-configuration).

  • -i/--in-place: Overwrites the input files when formatting instead of printing the results to standard output.

  • -r/--recursive: If specified, then the tool will process .swift source files in any directories listed on the command line and their descendants. Without this flag, it is an error to list a directory on the command line.

Configuration

For any source file being checked or formatted, swift-format looks for a JSON-formatted file named .swift-format in the same directory. If one is found, then that file is loaded to determine the tool's configuration. If the file is not found, then it looks in the parent directory, and so on.

If no configuration file is found, a default configuration is used. The settings in the default configuration can be viewed by running swift-format --mode dump-configuration, which will dump it to standard output.

If the --configuration <file> option is passed to swift-format, then that configuration will be used unconditionally and the file system will not be searched.

See Documentation/Configuration.md for a description of the configuration file format and the settings that are available.

API Usage

swift-format can be easily integrated into other tools written in Swift. Instead of invoking the formatter by spawning a subprocess, users can depend on swift-format as a Swift Package Manager dependency and import the SwiftFormat module, which contains the entry points into the formatter's diagnostic and correction behavior.

Formatting behavior is provided by the SwiftFormatter class and linting behavior is provided by the SwiftLinter class. These APIs can be passed either a Swift source file URL or a Syntax node representing a SwiftSyntax syntax tree. The latter capability is particularly useful for writing code generators, since it significantly reduces the amount of trivia that the generator needs to be concerned about adding to the syntax nodes it creates. Instead, it can pass the in-memory syntax tree to the SwiftFormat API and receive perfectly formatted code as output.

Please see the documentation in the SwiftFormatter and SwiftLinter classes for more information about their usage.

Development

If you are interested in developing swift-format, there is additional documentation about that here.

Github

link
Stars: 1038

Used By

Total: 0

Releases

0.50300.0 - 2020-09-19 16:44:38

This release is compatible with Swift 5.3.

Significant changes since the last release:

  • Support is added for rules to be opt-in rather than on-by-default. (40bab4e8b99d52dc561e62aa14e39d0d6cda7c17)
  • The following rules have been made opt-in, because they are either too strict for many real-world use cases or are not yet correct enough to enable universally. Existing configuration files will not be affected, but when using the default configuration, these rules will be off by default: (1c2a5a2d244b89ef10195799bbe9ca86ecc15bf3, 642c2d17e50936aa517f08c72eed9826bc163e4d)
    • AllPublicDeclarationsHaveDocumentation
    • NeverForceUnwrap
    • NeverUseForceTry
    • NeverUseImplicitlyUnwrappedOptionals
    • NoLeadingUnderscores
    • ValidateDocumentationComments
  • Improvements to AlwaysUseLowerCamelCase:
    • It is now applied to closure arguments and variables bound in if/guard let patterns. (7867cda76f800f6031cafa83793dd136f17b1c38)
    • Diagnostics are now clearer about the kind of declaration affected. (97628a8b0068fd0977ce50915c36f3dee8c5426a)
    • Functions that look like test case methods are excluded; for example, to support common naming schemes like testSomeObject_inSomeState_actsSomeWay. (90807621e2a52ca3432c56c3bb855bc89146b360)
  • Improvements to ValidateDocumentationComments:
    • A Returns section is no longer required for functions that return Never. (674b34df5114291df26f0f9edba8b94b76c28f80)
    • Presence of absence of the Throws section is now validated against the function signature. (57a5cb66a72bd04c9a07635b8a980573033dcc96)
  • Multiple trailing closures are formatted. (e286081a1342944236bde8653f5ca763ba61cfc3)
  • Fix a crash when linting a collection literal with single element and a trailing comma. (483580f1d3047272292aa516e06a02adc8b365aa)
  • Fixed invalid locations in some diagnostics. (ea02880b86bee22da9fbbfe37e43e17d75b673dd)
  • Keep try keyword next to the expression following it whenever possible, only breaking between them when necessary. (35fdb4fff0aeb9a506fccdfad98fab16d907c173)
  • Recursively apply NoParensAroundCondition to pick up nested occurrences. (ed45527f1c1891f90bb98c642275f43d164d56a1)
  • Do not remove semicolons between a do block and a while block. (cb4e6210c637b4ce3fd3ae81d0241c2c02895bfb)
  • Fix some situations where OneVariableDeclarationPerLine would incorrectly break declarations. (2b4364b7676964b430e66449e2981029e99ddd20)
  • Add a indentSwitchCaseLabels configuration option to control whether case statements inside a switch are indented. (2107603c7a0cb549a2e3fc7c35e5740dd4bee90e)
  • Speed and memory usage improvements when formatting and linting.

0.50200.1 - 2020-04-30 23:23:59

Significant changes in this release:

  • Format property wrappers correctly. (e829789)
  • Move open group token past ifstmt's if token to avoid extra newlines. (5df9eb4)
  • Handle @derivative attribute without a wrt: clause. (2c29da1)
  • Disallow discretionary newlines before trailing closures. (a4100c3)
  • Disallow line breaks inside completely empty array and dictionary expressions. (66cac37)
  • Force all branches of an if/else if/else sequence to break inside the {...} if the sequence requires more than one line, even for branches that contain a single statement. (c52e0d2)
  • Fix indentation of wrapped conditions in while statements. (8fbc3f1)
  • Fix formatting of @differentiable containing only wrt: and where clauses. (0da09d0)
  • Fix counting of consecutive newlines. (513a2c7)
  • Apply NoEmptyTrailingClosureParentheses rule recursively. (5cca489)
  • Fix some cases where class declarations would overflow line length. (20162cd)
  • Prevent trailing commas from overflowing the maximum line length. (ed5f980)
  • Detect () cases previously missed by ReturnVoidInsteadOfEmptyTuple. (ff7ac9a)
  • Allow right parenthesis of an enum case to be on the same line as the last parameter. (a50d4fe)
  • Add spaces after labels for all statement types. (c7db906)
  • Fix @differentiable attribute formatting when the where clause is the first thing in the attribute, or when the wrt: clause is a tuple. (428b33c)
  • Remove calls to FileHandle.synchronizeFile() that were crashing on Linux. (744ca11)
  • Restrict doc-block to doc-line transform to first doc comment on a declaration. (58ccbf3)
  • Discard newlines when sorting imports. (47b5015)

0.50200.0 - 2020-04-01 22:25:32

This release is compatible with Swift 5.2.