Merge pull request #708 from apple/dewing/FormatRanges

Support for formatting a selection

Author: allevato

Sources/SwiftFormat/API/Selection.swift

@@ -0,0 +1,63 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import SwiftSyntax
+
+/// The selection as given on the command line - an array of offets and lengths
+public enum Selection {
+  case infinite
+  case ranges([Range<AbsolutePosition>])
+
+  /// Create a selection from an array of utf8 ranges. An empty array means an infinite selection.
+  public init(offsetRanges: [Range<Int>]) {
+    if offsetRanges.isEmpty {
+      self = .infinite
+    } else {
+      let ranges = offsetRanges.map {
+        AbsolutePosition(utf8Offset: $0.lowerBound) ..< AbsolutePosition(utf8Offset: $0.upperBound)
+      }
+      self = .ranges(ranges)
+    }
+  }
+
+  public func contains(_ position: AbsolutePosition) -> Bool {
+    switch self {
+    case .infinite:
+      return true
+    case .ranges(let ranges):
+      return ranges.contains { $0.contains(position) }
+    }
+  }
+
+  public func overlapsOrTouches(_ range: Range<AbsolutePosition>) -> Bool {
+    switch self {
+    case .infinite:
+      return true
+    case .ranges(let ranges):
+      return ranges.contains { $0.overlapsOrTouches(range) }
+    }
+  }
+}
+
+
+public extension Syntax {
+  /// - Returns: `true` if the node is _completely_ inside any range in the selection
+  func isInsideSelection(_ selection: Selection) -> Bool {
+    switch selection {
+    case .infinite:
+      return true
+    case .ranges(let ranges):
+      return ranges.contains { return $0.lowerBound <= position && endPosition <= $0.upperBound }
+    }
+  }
+}

Sources/SwiftFormat/API/SwiftFormatter.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
+// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -70,6 +70,7 @@ public final class SwiftFormatter {
     try format(
       source: String(contentsOf: url, encoding: .utf8),
       assumingFileURL: url,
+      selection: .infinite,
       to: &outputStream,
       parsingDiagnosticHandler: parsingDiagnosticHandler)
   }
@@ -86,6 +87,7 @@ public final class SwiftFormatter {
   ///   - url: A file URL denoting the filename/path that should be assumed for this syntax tree,
   ///     which is associated with any diagnostics emitted during formatting. If this is nil, a
   ///     dummy value will be used.
+  ///   - selection: The ranges to format
   ///   - outputStream: A value conforming to `TextOutputStream` to which the formatted output will
   ///     be written.
   ///   - parsingDiagnosticHandler: An optional callback that will be notified if there are any
@@ -94,6 +96,7 @@ public final class SwiftFormatter {
   public func format<Output: TextOutputStream>(
     source: String,
     assumingFileURL url: URL?,
+    selection: Selection,
     to outputStream: inout Output,
     parsingDiagnosticHandler: ((Diagnostic, SourceLocation) -> Void)? = nil
   ) throws {
@@ -108,8 +111,8 @@ public final class SwiftFormatter {
       assumingFileURL: url,
       parsingDiagnosticHandler: parsingDiagnosticHandler)
     try format(
-      syntax: sourceFile, operatorTable: .standardOperators, assumingFileURL: url, source: source,
-      to: &outputStream)
+      syntax: sourceFile, source: source, operatorTable: .standardOperators, assumingFileURL: url,
+      selection: selection, to: &outputStream)
   }
 
   /// Formats the given Swift syntax tree and writes the result to an output stream.
@@ -122,32 +125,26 @@ public final class SwiftFormatter {
   ///
   /// - Parameters:
   ///   - syntax: The Swift syntax tree to be converted to source code and formatted.
+  ///   - source: The original Swift source code used to build the syntax tree.
   ///   - operatorTable: The table that defines the operators and their precedence relationships.
   ///     This must be the same operator table that was used to fold the expressions in the `syntax`
   ///     argument.
   ///   - url: A file URL denoting the filename/path that should be assumed for this syntax tree,
   ///     which is associated with any diagnostics emitted during formatting. If this is nil, a
   ///     dummy value will be used.
+  ///   - selection: The ranges to format
   ///   - outputStream: A value conforming to `TextOutputStream` to which the formatted output will
   ///     be written.
   /// - Throws: If an unrecoverable error occurs when formatting the code.
   public func format<Output: TextOutputStream>(
-    syntax: SourceFileSyntax, operatorTable: OperatorTable, assumingFileURL url: URL?,
-    to outputStream: inout Output
-  ) throws {
-    try format(
-      syntax: syntax, operatorTable: operatorTable, assumingFileURL: url, source: nil,
-      to: &outputStream)
-  }
-
-  private func format<Output: TextOutputStream>(
-    syntax: SourceFileSyntax, operatorTable: OperatorTable,
-    assumingFileURL url: URL?, source: String?, to outputStream: inout Output
+    syntax: SourceFileSyntax, source: String, operatorTable: OperatorTable,
+    assumingFileURL url: URL?, selection: Selection, to outputStream: inout Output
   ) throws {
     let assumedURL = url ?? URL(fileURLWithPath: "source")
     let context = Context(
       configuration: configuration, operatorTable: operatorTable, findingConsumer: findingConsumer,
-      fileURL: assumedURL, sourceFileSyntax: syntax, source: source, ruleNameCache: ruleNameCache)
+      fileURL: assumedURL, selection: selection, sourceFileSyntax: syntax, source: source,
+      ruleNameCache: ruleNameCache)
     let pipeline = FormatPipeline(context: context)
     let transformedSyntax = pipeline.rewrite(Syntax(syntax))
 
@@ -158,6 +155,7 @@ public final class SwiftFormatter {
 
     let printer = PrettyPrinter(
       context: context,
+      source: source,
       node: transformedSyntax,
       printTokenStream: debugOptions.contains(.dumpTokenStream),
       whitespaceOnly: false)

Sources/SwiftFormat/API/SwiftLinter.swift

@@ -119,17 +119,18 @@ public final class SwiftLinter {
   /// - Throws: If an unrecoverable error occurs when formatting the code.
   public func lint(
     syntax: SourceFileSyntax,
+    source: String,
     operatorTable: OperatorTable,
     assumingFileURL url: URL
   ) throws {
-    try lint(syntax: syntax, operatorTable: operatorTable, assumingFileURL: url, source: nil)
+    try lint(syntax: syntax, operatorTable: operatorTable, assumingFileURL: url, source: source)
   }
 
   private func lint(
     syntax: SourceFileSyntax,
     operatorTable: OperatorTable,
     assumingFileURL url: URL,
-    source: String?
+    source: String
   ) throws {
     let context = Context(
       configuration: configuration, operatorTable: operatorTable, findingConsumer: findingConsumer,
@@ -145,6 +146,7 @@ public final class SwiftLinter {
     // pretty-printer.
     let printer = PrettyPrinter(
       context: context,
+      source: source,
       node: Syntax(syntax),
       printTokenStream: debugOptions.contains(.dumpTokenStream),
       whitespaceOnly: true)

Sources/SwiftFormat/CMakeLists.txt

@@ -14,6 +14,7 @@ add_library(SwiftFormat
   API/Finding.swift
   API/FindingCategorizing.swift
   API/Indent.swift
+  API/Selection.swift
   API/SwiftFormatError.swift
   API/SwiftFormatter.swift
   API/SwiftLinter.swift

Sources/SwiftFormat/Core/Context.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
+// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -39,6 +39,9 @@ public final class Context {
   /// The configuration for this run of the pipeline, provided by a configuration JSON file.
   let configuration: Configuration
 
+  /// The selection to process
+  let selection: Selection
+
   /// Defines the operators and their precedence relationships that were used during parsing.
   let operatorTable: OperatorTable
 
@@ -66,6 +69,7 @@ public final class Context {
     operatorTable: OperatorTable,
     findingConsumer: ((Finding) -> Void)?,
     fileURL: URL,
+    selection: Selection = .infinite,
     sourceFileSyntax: SourceFileSyntax,
     source: String? = nil,
     ruleNameCache: [ObjectIdentifier: String]
@@ -74,6 +78,7 @@ public final class Context {
     self.operatorTable = operatorTable
     self.findingEmitter = FindingEmitter(consumer: findingConsumer)
     self.fileURL = fileURL
+    self.selection = selection
     self.importsXCTest = .notDetermined
     let tree = source.map { Parser.parse(source: $0) } ?? sourceFileSyntax
     self.sourceLocationConverter =
@@ -86,8 +91,10 @@ public final class Context {
   }
 
   /// Given a rule's name and the node it is examining, determine if the rule is disabled at this
-  /// location or not.
-  func isRuleEnabled<R: Rule>(_ rule: R.Type, node: Syntax) -> Bool {
+  /// location or not. Also makes sure the entire node is contained inside any selection.
+  func shouldFormat<R: Rule>(_ rule: R.Type, node: Syntax) -> Bool {
+    guard node.isInsideSelection(selection) else { return false }
+
     let loc = node.startLocation(converter: self.sourceLocationConverter)
 
     assert(

Sources/SwiftFormat/Core/LintPipeline.swift

@@ -28,7 +28,7 @@ extension LintPipeline {
   func visitIfEnabled<Rule: SyntaxLintRule, Node: SyntaxProtocol>(
     _ visitor: (Rule) -> (Node) -> SyntaxVisitorContinueKind, for node: Node
   ) {
-    guard context.isRuleEnabled(Rule.self, node: Syntax(node)) else { return }
+    guard context.shouldFormat(Rule.self, node: Syntax(node)) else { return }
     let ruleId = ObjectIdentifier(Rule.self)
     guard self.shouldSkipChildren[ruleId] == nil else { return }
     let rule = self.rule(Rule.self)
@@ -54,7 +54,7 @@ extension LintPipeline {
     // more importantly because the `visit` methods return protocol refinements of `Syntax` that
     // cannot currently be expressed as constraints without duplicating this function for each of
     // them individually.
-    guard context.isRuleEnabled(Rule.self, node: Syntax(node)) else { return }
+    guard context.shouldFormat(Rule.self, node: Syntax(node)) else { return }
     guard self.shouldSkipChildren[ObjectIdentifier(Rule.self)] == nil else { return }
     let rule = self.rule(Rule.self)
     _ = visitor(rule)(node)

Sources/SwiftFormat/Core/SyntaxFormatRule.swift

@@ -32,7 +32,7 @@ public class SyntaxFormatRule: SyntaxRewriter, Rule {
   public override func visitAny(_ node: Syntax) -> Syntax? {
     // If the rule is not enabled, then return the node unmodified; otherwise, returning nil tells
     // SwiftSyntax to continue with the standard dispatch.
-    guard context.isRuleEnabled(type(of: self), node: node) else { return node }
+    guard context.shouldFormat(type(of: self), node: node) else { return node }
     return nil
   }
 }

Sources/SwiftFormat/PrettyPrint/PrettyPrint.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 import SwiftSyntax
+import Foundation
 
 /// PrettyPrinter takes a Syntax node and outputs a well-formatted, re-indented reproduction of the
 /// code as a String.
@@ -66,6 +67,17 @@ public class PrettyPrinter {
   private var configuration: Configuration { return context.configuration }
   private let maxLineLength: Int
   private var tokens: [Token]
+  private var source: String
+
+  /// Keep track of where formatting was disabled in the original source
+  ///
+  /// To format a selection, we insert `enableFormatting`/`disableFormatting` tokens into the
+  /// stream when entering/exiting a selection range. Those tokens include utf8 offsets into the
+  /// original source. When enabling formatting, we copy the text between `disabledPosition` and the
+  /// current position to `outputBuffer`. From then on, we continue to format until the next
+  /// `disableFormatting` token.
+  private var disabledPosition: AbsolutePosition? = nil
+
   private var outputBuffer: String = ""
 
   /// The number of spaces remaining on the current line.
@@ -172,11 +184,14 @@ public class PrettyPrinter {
   ///   - printTokenStream: Indicates whether debug information about the token stream should be
   ///     printed to standard output.
   ///   - whitespaceOnly: Whether only whitespace changes should be made.
-  public init(context: Context, node: Syntax, printTokenStream: Bool, whitespaceOnly: Bool) {
+  public init(context: Context, source: String, node: Syntax, printTokenStream: Bool, whitespaceOnly: Bool) {
     self.context = context
+    self.source = source
     let configuration = context.configuration
     self.tokens = node.makeTokenStream(
-      configuration: configuration, operatorTable: context.operatorTable)
+      configuration: configuration,
+      selection: context.selection,
+      operatorTable: context.operatorTable)
     self.maxLineLength = configuration.lineLength
     self.spaceRemaining = self.maxLineLength
     self.printTokenStream = printTokenStream
@@ -187,7 +202,9 @@ public class PrettyPrinter {
   ///
   /// No further processing is performed on the string.
   private func writeRaw<S: StringProtocol>(_ str: S) {
-    outputBuffer.append(String(str))
+    if disabledPosition == nil {
+      outputBuffer.append(String(str))
+    }
   }
 
   /// Writes newlines into the output stream, taking into account any preexisting consecutive
@@ -241,7 +258,7 @@ public class PrettyPrinter {
       writeRaw(currentIndentation.indentation())
       spaceRemaining = maxLineLength - currentIndentation.length(in: configuration)
       isAtStartOfLine = false
-    } else if pendingSpaces > 0 {
+    } else if pendingSpaces > 0  {
       writeRaw(String(repeating: " ", count: pendingSpaces))
     }
     writeRaw(text)
@@ -569,6 +586,39 @@ public class PrettyPrinter {
         write(",")
         spaceRemaining -= 1
       }
+
+    case .enableFormatting(let enabledPosition):
+      guard let disabledPosition else {
+        // if we're not disabled, we ignore the token
+        break
+      }
+      let start = source.utf8.index(source.utf8.startIndex, offsetBy: disabledPosition.utf8Offset)
+      let end: String.Index
+      if let enabledPosition {
+        end = source.utf8.index(source.utf8.startIndex, offsetBy: enabledPosition.utf8Offset)
+      } else {
+        end = source.endIndex
+      }
+      var text = String(source[start..<end])
+      // strip trailing whitespace so that the next formatting can add the right amount
+      if let nonWhitespace = text.rangeOfCharacter(
+        from: CharacterSet.whitespaces.inverted, options: .backwards) {
+        text = String(text[..<nonWhitespace.upperBound])
+      }
+
+      self.disabledPosition = nil
+      writeRaw(text)
+      if text.hasSuffix("\n") {
+        isAtStartOfLine = true
+        consecutiveNewlineCount = 1
+      } else {
+        isAtStartOfLine = false
+        consecutiveNewlineCount = 0
+      }
+
+    case .disableFormatting(let newPosition):
+      assert(disabledPosition == nil)
+      disabledPosition = newPosition
     }
   }
 
@@ -673,6 +723,10 @@ public class PrettyPrinter {
         let length = isSingleElement ? 0 : 1
         total += length
         lengths.append(length)
+
+      case .enableFormatting, .disableFormatting:
+        // no effect on length calculations
+        lengths.append(0)
       }
     }
 
@@ -775,6 +829,14 @@ public class PrettyPrinter {
     case .contextualBreakingEnd:
       printDebugIndent()
       print("[END BREAKING CONTEXT Idx: \(idx)]")
+
+    case .enableFormatting(let pos):
+      printDebugIndent()
+      print("[ENABLE FORMATTING utf8 offset: \(String(describing: pos))]")
+
+    case .disableFormatting(let pos):
+      printDebugIndent()
+      print("[DISABLE FORMATTING utf8 offset: \(pos)]")
     }
   }