Address code review feedback

Author: DougGregor

Sources/SwiftIfConfig/StaticBuildConfiguration.swift

@@ -29,7 +29,7 @@ public struct StaticBuildConfiguration: Codable {
  customConditions: Set<String> = [],
  features: Set<String> = [],
  attributes: Set<String> = [],
- targetOSNames: Set<String> = [],
+ targetOSs: Set<String> = [],
  targetArchitectures: Set<String> = [],
  targetEnvironments: Set<String> = [],
  targetRuntimes: Set<String> = [],
@@ -44,7 +44,7 @@ public struct StaticBuildConfiguration: Codable {
  self.customConditions = customConditions
  self.features = features
  self.attributes = attributes
- self.targetOSNames = targetOSNames
+ self.targetOSs = targetOSs
  self.targetArchitectures = targetArchitectures
  self.targetEnvironments = targetEnvironments
  self.targetRuntimes = targetRuntimes
@@ -53,7 +53,7 @@ public struct StaticBuildConfiguration: Codable {
  self.targetPointerBitWidth = targetPointerBitWidth
  self.targetAtomicBitWidths = targetAtomicBitWidths
  self.endianness = endianness
- self.languageVersion = languageVersion
+ self.languageMode = languageVersion
  self.compilerVersion = compilerVersion
  }
 
@@ -95,22 +95,76 @@ public struct StaticBuildConfiguration: Codable {
  /// ```
  public var attributes: Set<String> = []
 
- /// The active target OS names, e.g., "Windows", "iOS".
- public var targetOSNames: Set<String> = []
+ /// The active target OS, e.g., "Windows", "iOS".
+ ///
+ /// The target operating system can be queried with `os(<name>)`, e.g.,
+ ///
+ /// ```swift
+ /// #if os(Linux)
+ /// // Linux-specific implementation
+ /// #endif
+ /// ```
+ public var targetOSs: Set<String> = []
 
  /// The active target architectures, e.g., "x64_64".
+ ///
+ /// The target processor architecture can be queried with `arch(<name>)`, e.g.,
+ ///
+ /// ```swift
+ /// #if arch(x86_64)
+ /// // 64-bit x86 Intel-specific code
+ /// #endif
+ /// ```
  public var targetArchitectures: Set<String> = []
 
  /// The active target environments, e.g., "simulator".
+ ///
+ /// The target environment can be queried with `targetEnvironment(<name>)`,
+ /// e.g.,
+ ///
+ /// ```swift
+ /// #if targetEnvironment(simulator)
+ /// // Simulator-specific code
+ /// #endif
+ /// ```
  public var targetEnvironments: Set<String> = []
 
  /// The active target runtimes, e.g., _ObjC.
+ ///
+ /// The target runtime can only be queried by an experimental syntax
+ /// `_runtime(<name>)`, e.g.,
+ ///
+ /// ```swift
+ /// #if _runtime(_ObjC)
+ /// // Code that depends on Swift being built for use with the Objective-C
+ /// // runtime, e.g., on Apple platforms.
+ /// #endif
+ /// ```
  public var targetRuntimes: Set<String> = []
 
  /// The active target's pointer authentication schemes, e.g., "arm64e".
+ ///
+ /// The target pointer authentication scheme describes how pointers are
+ /// signed, as a security mitigation. This scheme can only be queried by
+ /// an experimental syntax `_ptrath(<name>)`, e.g.,
+ ///
+ /// ```swift
+ /// #if _ptrauth(arm64e)
+ /// // Special logic for arm64e pointer signing
+ /// #endif
+ /// ```
  public var targetPointerAuthenticationSchemes: Set<String> = []
 
  /// The active target's object file formats, e.g., "COFF"
+ ///
+ /// The target object file format can only be queried by an experimental
+ /// syntax `_objectFileFormat(<name>)`, e.g.,
+ ///
+ /// ```swift
+ /// #if _objectFileFormat(ELF)
+ /// // Special logic for ELF object file formats
+ /// #endif
+ /// ```
  public var targetObjectFileFormats: Set<String> = []
 
  /// The bit width of a data pointer for the target architecture.
@@ -151,17 +205,17 @@ public struct StaticBuildConfiguration: Codable {
  /// ```
  public var endianness: Endianness = .little
 
- /// The effective language version, which can be set by the user (e.g., 5.0).
+ /// The effective language mode, which can be set by the user (e.g., 5.0).
  ///
  /// The language version can be queried with the `swift` directive that checks
  /// how the supported language version compares, as described by
  /// [SE-0212](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0212-compiler-version-directive.md). For example:
  ///
  /// ```swift
- /// #if swift(>=5.5)
+ /// #if swift(>=6.0)
  /// // Hooray, we can use tasks!
  /// ```
- public var languageVersion: VersionTuple
+ public var languageMode: VersionTuple
 
  /// The version of the compiler (e.g., 5.9).
  ///
@@ -264,7 +318,7 @@ extension StaticBuildConfiguration: BuildConfiguration {
  /// - Returns: Whether the given operating system name is the target operating
  /// system, i.e., the operating system for which code is being generated.
  public func isActiveTargetOS(name: String) -> Bool {
- targetOSNames.contains(name)
+ targetOSs.contains(name)
  }
 
  /// Determine whether the given name is the active target architecture
@@ -363,6 +417,12 @@ extension StaticBuildConfiguration: BuildConfiguration {
  public func isActiveTargetObjectFileFormat(name: String) -> Bool {
  targetObjectFileFormats.contains(name)
  }
+
+ /// Equivalent to `languageMode`, but required for conformance to the
+ /// `BuildConfiguration` protocol.
+ public var languageVersion: VersionTuple {
+ languageMode
+ }
 }
 
 extension StaticBuildConfiguration {
@@ -376,11 +436,11 @@ extension StaticBuildConfiguration {
 extension StaticBuildConfiguration {
  /// The Swift version that can be set for the parser.
  public var parserSwiftVersion: Parser.SwiftVersion {
- if languageVersion < VersionTuple(5) {
+ if languageMode < VersionTuple(5) {
  return .v4
- } else if languageVersion < VersionTuple(6) {
+ } else if languageMode < VersionTuple(6) {
  return .v5
- } else if languageVersion < VersionTuple(7) {
+ } else if languageMode < VersionTuple(7) {
  return .v6
  } else {
  return Parser.defaultSwiftVersion

Sources/SwiftSyntaxMacros/MacroExpansionContext.swift

@@ -77,7 +77,9 @@ public protocol MacroExpansionContext: AnyObject {
  /// source code. Macro implementations can use this information to determine
  /// the context into which they are generating code.
  ///
- /// When the build configuration is not known, this returns nil.
+ /// When the build configuration is not known, for example because the
+ /// compiler has not provided this information to the macro implementation,
+ /// this returns nil.
  var buildConfiguration: (any BuildConfiguration)? { get }
 }
 

SwiftParserCLI/Sources/swift-parser-cli/Commands/Print.swift

@@ -23,12 +23,8 @@ struct Print: ParsableCommand, ParseCommand {
  @OptionGroup
  var arguments: ParseArguments
 
- @Flag(name: .long, help: "Include trivia in the output")
- var includeTrivia: Bool = false
-
  func run() throws {
- try withParsedSourceFile(wantDiagnostics: false) { (tree, _) in
- print(tree.description)
- }
+ let (tree, _) = try parsedSourceFile(wantDiagnostics: false)
+ print(tree.description)
  }
 }

SwiftParserCLI/Sources/swift-parser-cli/Commands/PrintDiags.swift

@@ -28,19 +28,18 @@ struct PrintDiags: ParsableCommand, ParseCommand {
  var colorize: Bool = false
 
  func run() throws {
- try withParsedSourceFile { (tree, diags) in
-  var group = GroupedDiagnostics()
-  group.addSourceFile(tree: tree, displayName: sourceFileName, diagnostics: diags)
-  let annotatedSource = DiagnosticsFormatter.annotateSources(
-  in: group,
-  colorize: colorize || TerminalHelper.isConnectedToTerminal
-  )
+ let (tree, diags) = try parsedSourceFile()
+ var group = GroupedDiagnostics()
+ group.addSourceFile(tree: tree, displayName: sourceFileName, diagnostics: diags)
+ let annotatedSource = DiagnosticsFormatter.annotateSources(
+ in: group,
+ colorize: colorize || TerminalHelper.isConnectedToTerminal
+ )
 
-  print(annotatedSource)
+ print(annotatedSource)
 
- if diags.isEmpty {
- print("No diagnostics produced")
- }
+ if diags.isEmpty {
+ print("No diagnostics produced")
  }
  }
 }

SwiftParserCLI/Sources/swift-parser-cli/Commands/PrintTree.swift

@@ -27,8 +27,7 @@ struct PrintTree: ParsableCommand, ParseCommand {
  var includeTrivia: Bool = false
 
  func run() throws {
- try withParsedSourceFile(wantDiagnostics: false) { (tree, _) in
- print(tree.debugDescription(includeTrivia: includeTrivia))
- }
+ let (tree, _) = try parsedSourceFile(wantDiagnostics: false)
+ print(tree.debugDescription(includeTrivia: includeTrivia))
  }
 }

SwiftParserCLI/Sources/swift-parser-cli/ParseCommand.swift

@@ -61,11 +61,10 @@ extension ParseCommand {
  var foldSequences: Bool { arguments.foldSequences }
 
  /// Parse the source file, applying any additional configuration options
- /// such as sequence folding, and provide it to the given closure.
- func withParsedSourceFile<R>(
- wantDiagnostics: Bool = true,
- body: (SourceFileSyntax, [Diagnostic]) throws -> R
- ) throws -> R {
+ /// such as sequence folding, and return it with diagnostics.
+ func parsedSourceFile(
+ wantDiagnostics: Bool = true
+ ) throws -> (SourceFileSyntax, [Diagnostic]) {
  return try sourceFileContents.withUnsafeBufferPointer { sourceBuffer in
  // Parse the sources
  var tree = Parser.parse(source: sourceBuffer)
@@ -104,7 +103,7 @@ extension ParseCommand {
  }
  }
 
- return try body(tree, diags)
+ return (tree, diags)
  }
  }
 }