swift-syntax

510.0.1

A set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.
apple/swift-syntax

What's New

510.0.1

2024-03-09T00:15:33Z

Compared to 510.0.0 this fixes a possible misaligned memory access.

It also contains the following changes from 510.0.0.

New APIs

  • SyntaxStringInterpolation.appendInterpolation(_: (some SyntaxProtocol)?)

    • Description: Allows optional syntax nodes to be used inside string interpolation of syntax nodes. If the node is nil, nothing will get added to the string interpolation.
    • Pull Request: #2085
  • SyntaxCollection.index(at:)

    • Description: Returns the index of the n-th element in a SyntaxCollection. This computation is in O(n) and SyntaxCollection is not subscriptable by an integer.
    • Pull Request: #2014
  • Convenience initializer ClosureCaptureSyntax.init()

    • Description: Provides a convenience initializer for ClosureCaptureSyntax that takes a concrete name argument and automatically adds equal = TokenSyntax.equalToken() to it.
    • Issue: #1984
    • Pull Request: #2127
  • Convenience initializer EnumCaseParameterSyntax.init()

    • Description: Provides a convenience initializer for EnumCaseParameterSyntax that takes a concrete firstName value and adds colon = TokenSyntax.colonToken() automatically to it.
    • Issue: #1984
    • Pull Request: #2112
  • DiagnosticSeverity and PluginMessage.Diagnostic.Severity now have new case named remark

    • Description: Remarks are used by the Swift compiler and other tools to describe some aspect of translation that doesn't reflect correctness, but may be useful for the user. Remarks have been added to the diagnostic severity enums to align with the Swift compiler.
    • Pull Request: #2143

Deprecations

  • Leaf Node Casts

    • Description: Syntax nodes that do not act as base nodes for other syntax types have the casting methods marked as deprecated. This prevents unsafe type-casting by issuing deprecation warnings for methods that will always result in failed casts.
    • Issue: #2092
    • Pull Request: #2108
  • Same-Type Casts

    • Description: is, as, and cast overloads on SyntaxProtocol with same-type conversions are marked as deprecated. The deprecated methods emit a warning indicating the cast will always succeed.
    • Issue: #2092
    • Pull Request: #2108
  • Base Node Casts

    • Description: is, as, and cast methods on base node protocols with base-type conversions are marked as deprecated. The deprecated methods emit a warning that informs the developer that the cast will always succeed and should be done using the base node's initializer.
    • Issue: #2092
    • Pull Request: #2108
  • WildcardPatternSyntax.typeAnnotation

    • Description: typeAnnotation on WildcardPatternSyntax was a mistake. Use typeAnnotation properties on the outer constructs instead. E.g. PatternBindingListSyntax.typeAnnotation
    • Pull Request: #2393

API-Incompatible Changes

  • NoteMessage.fixItID renamed to noteID

    • Description: This was an error that it was named fixItID and should have been named noteID instead. Accesses to fixItID are deprecated and forward to noteID. Any types that conform NoteMessage it will need to be updated to provide a noteID instead of a fixItID.
    • Issue: #2261
    • Pull Request: #2264
  • DiagnosticSpec.highlight replaced by highlights

    • Description: The use of a single string highlight prevented users from asserting that a macro highlighted exactly the expected set of syntax nodes. Use of DiagnosticSpec.init(...highlight:...) is deprecated and forwards to DiagnosticSpec.init(...highlights:...). Migrating from highlight to highlights is straightforward; any uses of DiagnosticSpec.init which do not specify a highlight do not need to change, otherwise:
      • If the diagnostic highlights a single node, the highlight string should be replaced with a single element array containing the same string without any trailing trivia, e.g., highlight: "let " -> highlights: ["let"].
      • If the diagnostic highlights multiple nodes, the highlight string should be replaced with an array containing an element for each highlighted node, e.g., highlight: "struct {}" -> highlights: ["struct", "{}"].
    • Pull Request: #2213

SwiftSyntax

SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.

Documentation

You can read SwiftSyntax’s documentation on swiftpackageindex.com.

A great way to interactively explore the SwiftSyntax tree of a source file is https://swift-ast-explorer.com, developed by @kishikawakatsumi.

Adding SwiftSyntax as a Dependency

Trunk Development (main)

The mainline branch of SwiftSyntax tracks the latest developments. It is not an official release, and is subject to rapid changes in APIs and behaviors. To use it, add this repository to the Package.swift manifest of your project:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
  name: "MyTool",
  dependencies: [
    .package(url: "https://github.com/apple/swift-syntax.git", branch: "main"),
  ],
  targets: [
    .target(name: "MyTool", dependencies: [
      .product(name: "SwiftSyntax", package: "swift-syntax"),
    ]),
  ]
)

Mainline SwiftSyntax also includes

  • SwiftParser for natively parsing source code
  • SwiftOperators for folding SwiftSyntax trees containing operators
  • SwiftSyntaxBuilder for generating Swift code with a result builder-style interface
  • SwiftSyntaxMacros for providing syntactic macro support

Releases

Releases of SwiftSyntax are aligned with corresponding language and tooling releases and are stable. To use them, add this repository to the Package.swift manifest of your project:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
  name: "MyTool",
  dependencies: [
    .package(url: "https://github.com/apple/swift-syntax.git", exact: "<#Specify Release tag#>"),
  ],
  targets: [
    .target(name: "MyTool", dependencies: [
      .product(name: "SwiftSyntax", package: "swift-syntax"),
    ]),
  ]
)

Replace <#Specify Release tag#> by the version of SwiftSyntax that you want to use (see the following table for mapping details).

Xcode Release Swift Release Tag SwiftSyntax Release Tag
Xcode 14.3 swift-5.8-RELEASE 508.0.0
Xcode 14.0 swift-5.7-RELEASE 0.50700.1
Xcode 13.3 swift-5.6-RELEASE 0.50600.1
Xcode 13.0 swift-5.5-RELEASE 0.50500.0
Xcode 12.5 swift-5.4-RELEASE 0.50400.0
Xcode 12.0 swift-5.3-RELEASE 0.50300.0
Xcode 11.4 swift-5.2-RELEASE 0.50200.0

Documentation

SwiftSyntax uses DocC bundles for its documentation. To view rendered documentation in Xcode, open the SwiftSyntax package and select

Product > Build Documentation

Associated articles are written in markdown, and can be viewed in a browser, text editor, or IDE.

Contributing

Start contributing to SwiftSyntax see this guide for more information.

Reporting Issues

If you should hit any issues while using SwiftSyntax, we appreciate bug reports on GitHub Issue.

Bazel

SwiftSyntax provides an experimental Bazel build configuration, maintained by Keith Smiley. To use it you can pull the source archive from the relevant release tag into your WORKSPACE and depend on the libraries you need from the BUILD.bazel file. Each library also has an associated Library_opt target (such as SwiftSyntax_opt) which forces SwiftSyntax to always build with optimizations enabled. This may help local runtime performance at the cost of debuggability, and initial build time. Please tag any issues related to the Bazel configuration with the label "Bazel".

License

Please see LICENSE for more information.

Description

  • Swift Tools 5.7.0
View More Packages from this Author

Dependencies

  • None
Last updated: Thu Mar 28 2024 20:37:25 GMT-0900 (Hawaii-Aleutian Daylight Time)