Support for formatting a selection (given as an array of ranges) <#297>.

The basic idea here is to insert `enableFormatting` and `disableFormatting` tokens into the print stream when we enter or leave the selection. When formatting is enabled, we print out the tokens as usual. When formatting is disabled, we turn off any output until the next `enableFormatting` token. When that token is hit, we write the original source text from the location of the last `disableFormatting` to the current location.

Note that this means that all the APIs need the original source text to be passed in.

A `Selection` is represented as an enum with an `.infinite` case, and a `.ranges` case to indicate either selecting the entire file, or an array of start/end utf-8 offsets. The offset pairs are given with `Range<AbsolutePosition>`, matching the (now common) usage in swift-syntax.

For testing, allow marked text to use `⏩` and `⏪` to deliniate the start/end of a range of a selection.

The command line now takes an `--offsets` option of comma-separated "start:end" pairs to set the selection for formatting.

Author: DaveEwing

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(offsetPairs: [Range<Int>]) {
+    if offsetPairs.isEmpty {
+      self = .infinite
+    } else {
+      let ranges = offsetPairs.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 {
+  /// return 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
@@ -21,6 +21,9 @@ public final class SwiftFormatter {
   /// The configuration settings that control the formatter's behavior.
   public let configuration: Configuration
 
+  /// the ranges of text to format
+  public var selection: Selection = .infinite
+
   /// An optional callback that will be notified with any findings encountered during formatting.
   public let findingConsumer: ((Finding) -> Void)?
 
@@ -70,6 +73,7 @@ public final class SwiftFormatter {
     try format(
       source: String(contentsOf: url, encoding: .utf8),
       assumingFileURL: url,
+      selection: .infinite,
       to: &outputStream,
       parsingDiagnosticHandler: parsingDiagnosticHandler)
   }
@@ -86,6 +90,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 +99,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 +114,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 +128,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 +158,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/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 optional ranges 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.
+  /// location or not. Also makes sure the entire node is contained inside any selection.
   func isRuleEnabled<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/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,19 @@ 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
+  /// true if we're currently formatting
+  private var writingIsEnabled: Bool { disabledPosition == nil }
+
   private var outputBuffer: String = ""
 
   /// The number of spaces remaining on the current line.
@@ -172,11 +186,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
@@ -216,7 +233,9 @@ public class PrettyPrinter {
     }
 
     guard numberToPrint > 0 else { return }
-    writeRaw(String(repeating: "\n", count: numberToPrint))
+    if writingIsEnabled {
+      writeRaw(String(repeating: "\n", count: numberToPrint))
+    }
     lineNumber += numberToPrint
     isAtStartOfLine = true
     consecutiveNewlineCount += numberToPrint
@@ -238,13 +257,17 @@ public class PrettyPrinter {
   /// leading spaces that are required before the text itself.
   private func write(_ text: String) {
     if isAtStartOfLine {
-      writeRaw(currentIndentation.indentation())
+      if writingIsEnabled {
+        writeRaw(currentIndentation.indentation())
+      }
       spaceRemaining = maxLineLength - currentIndentation.length(in: configuration)
       isAtStartOfLine = false
-    } else if pendingSpaces > 0 {
+    } else if pendingSpaces > 0 && writingIsEnabled {
       writeRaw(String(repeating: " ", count: pendingSpaces))
     }
-    writeRaw(text)
+    if writingIsEnabled {
+      writeRaw(text)
+    }
     consecutiveNewlineCount = 0
     pendingSpaces = 0
   }
@@ -523,7 +546,9 @@ public class PrettyPrinter {
       }
 
     case .verbatim(let verbatim):
-      writeRaw(verbatim.print(indent: currentIndentation))
+      if writingIsEnabled {
+        writeRaw(verbatim.print(indent: currentIndentation))
+      }
       consecutiveNewlineCount = 0
       pendingSpaces = 0
       lastBreak = false
@@ -569,6 +594,40 @@ public class PrettyPrinter {
         write(",")
         spaceRemaining -= 1
       }
+
+    case .enableFormatting(let enabledPosition):
+      // if we're not disabled, we ignore the token
+      if let disabledPosition {
+        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])
+        }
+
+        writeRaw(text)
+        if text.hasSuffix("\n") {
+          isAtStartOfLine = true
+          consecutiveNewlineCount = 1
+        } else {
+          isAtStartOfLine = false
+          consecutiveNewlineCount = 0
+        }
+        self.disabledPosition = nil
+      }
+
+    case .disableFormatting(let newPosition):
+      // a second disable is ignored
+      if writingIsEnabled {
+        disabledPosition = newPosition
+      }
     }
   }
 
@@ -673,6 +732,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 +838,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)]")
     }
   }