Initial 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.
This initial commit doesn't really have the formatting working well - we need to tune where those tokens are inserted into the stream a bit better. But this does seem to show that the approach should work.

Author: DaveEwing

Sources/SwiftFormat/API/Selection.swift

@@ -0,0 +1,90 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 struct Selection {
+  // TODO: make this a typealias instead
+  public struct Range: Decodable {
+    public let offset: AbsolutePosition
+    public let length: Int
+    public var end: AbsolutePosition { offset.advanced(by: length) }
+
+    public init(from decoder: any Decoder) throws {
+      let container = try decoder.container(keyedBy: CodingKeys.self)
+      offset = AbsolutePosition(utf8Offset: try container.decode(Int.self, forKey: .offset))
+      length = try container.decode(Int.self, forKey: .length)
+    }
+
+    public init(start: AbsolutePosition, end: AbsolutePosition) {
+      offset = start
+      length = end.utf8Offset - start.utf8Offset
+    }
+
+    enum CodingKeys: CodingKey {
+      case offset
+      case length
+    }
+  }
+
+  public let ranges: [Range]
+
+  public init?(json: String) {
+    guard let data = json.data(using: .utf8),
+          let ranges = try? JSONDecoder().decode([Range].self, from: data) else {
+      return nil
+    }
+    self.ranges = ranges
+  }
+
+  public func contains(_ position: AbsolutePosition) -> Bool {
+    return ranges.contains { return $0.offset <= position && position < $0.end }
+  }
+
+  public func overlaps(_ range: Range) -> Bool {
+    return ranges.contains {
+      let maxStart = max($0.offset, range.offset)
+      let minEnd = (min($0.end, range.end))
+      return maxStart <= minEnd
+    }
+  }
+}
+
+
+public extension Syntax {
+
+  /// return true if the node touches any range in the selection (or if there's no selection)
+  func overlapsSelection(_ selection: Selection?) -> Bool {
+    // no selection means we should process everything
+    guard let selection else { return true }
+
+    return selection.ranges.contains { range in
+      let maxStart = max(range.offset, position)
+      let minEnd = (min(range.end, endPosition))
+      return maxStart <= minEnd
+    }
+  }
+
+  /// return true if the node is completely inside any range in the selection (or if there's
+  /// no selection)
+  func isInsideSelection(_ selection: Selection?) -> Bool {
+    // no selection means we should process everything
+    guard let selection else { return true }
+
+    return selection.ranges.contains { range in
+      return range.offset <= position && endPosition <= range.end
+    }
+  }
+
+}

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? = nil
+
   /// 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: nil,
       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? = nil,
     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

@@ -66,6 +66,8 @@ public class PrettyPrinter {
   private var configuration: Configuration { return context.configuration }
   private let maxLineLength: Int
   private var tokens: [Token]
+  private var source: String
+  private var disabledPosition: AbsolutePosition? = nil
   private var outputBuffer: String = ""
 
   /// The number of spaces remaining on the current line.
@@ -172,11 +174,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
@@ -237,6 +242,7 @@ public class PrettyPrinter {
   /// Before printing the text, this function will print any line-leading indentation or interior
   /// leading spaces that are required before the text itself.
   private func write(_ text: String) {
+    guard disabledPosition == nil else { return }
     if isAtStartOfLine {
       writeRaw(currentIndentation.indentation())
       spaceRemaining = maxLineLength - currentIndentation.length(in: configuration)
@@ -523,7 +529,9 @@ public class PrettyPrinter {
       }
 
     case .verbatim(let verbatim):
-      writeRaw(verbatim.print(indent: currentIndentation))
+      if disabledPosition == nil {
+        writeRaw(verbatim.print(indent: currentIndentation))
+      }
       consecutiveNewlineCount = 0
       pendingSpaces = 0
       lastBreak = false
@@ -569,6 +577,26 @@ 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 enabledPosition.utf8Offset != 0 {
+          end = source.utf8.index(source.utf8.startIndex, offsetBy: enabledPosition.utf8Offset)
+        } else {
+          end = source.endIndex
+        }
+        writeRaw(String(source[start..<end]))
+        self.disabledPosition = nil
+      }
+
+    case .disableFormatting(let newPosition):
+      // a second disable is ignored
+      if disabledPosition == nil {
+        disabledPosition = newPosition
+      }
     }
   }
 
@@ -673,6 +701,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 +807,14 @@ public class PrettyPrinter {
     case .contextualBreakingEnd:
       printDebugIndent()
       print("[END BREAKING CONTEXT Idx: \(idx)]")
+
+    case .enableFormatting(let pos):
+      printDebugIndent()
+      print("[ENABLE FORMATTTING utf8 offset: \(pos)]")
+
+    case .disableFormatting(let pos):
+      printDebugIndent()
+      print("[DISABLE FORMATTTING utf8 offset: \(pos)]")
     }
   }
 

Sources/SwiftFormat/PrettyPrint/Token.swift

@@ -10,6 +10,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+import SwiftSyntax
+
 enum GroupBreakStyle {
   /// A consistent break indicates that the break will always be finalized as a newline
   /// if wrapping occurs.
@@ -196,6 +198,13 @@ enum Token {
   /// Ends a scope where `contextual` breaks have consistent behavior.
   case contextualBreakingEnd
 
+  /// Turn formatting back on at the given position in the original file
+  /// nil is used to indicate the rest of the file should be output
+  case enableFormatting(AbsolutePosition)
+
+  /// Turn formatting off at the given position in the original file.
+  case disableFormatting(AbsolutePosition)
+
   // Convenience overloads for the enum types
   static let open = Token.open(.inconsistent, 0)