Wrap multiline string literals to line length.

Change how PrettyPrinter emits StringSegmentSyntax's so that they can be broken up over multiple lines within multiline string literals. This does not change the behavior of single line string literals, which cannot contain newlines. This also does not change interpolations which are still emitted as verbatims and are never line broken by the pretty printer. Line breaking is done exclusively through escaped newlines. A literal containing escaped newlines will remove all escaped newlines and then reinsert them based on line length. Hard newlines are respected by the formatter and will not be moved, even if it causes short lines. Escaped newlines will be reformatted by the pretty printer so that lines ending in an escaped newline are at line length.

Wrapping is implemented by introducing a new newlinebreak behavior `.escaped`. `.escaped` acts very similarly to `.elective` but has slightly different length calculation logic and printing behavior. An escaped newline is printed including it's preceeding whitespace followed by "\\\n". So a break of `.break(_, 2, .escaped)` will print as "  \\\n". Because an escaped line break takes up characters when broken (unlike other breaks), length calculation must be handled differently for `.escaped` breaks.

Author: thunderseethe

Sources/SwiftFormat/API/Configuration+Default.swift

@@ -40,5 +40,6 @@ extension Configuration {
     self.spacesAroundRangeFormationOperators = false
     self.noAssignmentInExpressions = NoAssignmentInExpressionsConfiguration()
     self.multiElementCollectionTrailingCommas = true
+    self.reflowMultilineStringLiterals = .never
   }
 }

Sources/SwiftFormat/API/Configuration.swift

@@ -45,6 +45,7 @@ public struct Configuration: Codable, Equatable {
     case spacesAroundRangeFormationOperators
     case noAssignmentInExpressions
     case multiElementCollectionTrailingCommas
+    case reflowMultilineStringLiterals
   }
 
   /// A dictionary containing the default enabled/disabled states of rules, keyed by the rules'
@@ -194,6 +195,71 @@ public struct Configuration: Codable, Equatable {
   /// ```
   public var multiElementCollectionTrailingCommas: Bool
 
+  /// Determines how multiline string literals should reflow when formatted.
+  public enum MultilineStringReflowBehavior: Codable {
+    /// Never reflow multiline string literals.
+    case never
+    /// Reflow lines in string literal that exceed the maximum line length. For example with a line length of 10:
+    /// ```swift
+    /// """
+    /// an escape\
+    ///  line break
+    /// a hard line break
+    /// """
+    /// ```
+    /// will be formatted as:
+    /// ```swift
+    /// """
+    /// an esacpe\
+    ///  line break
+    /// a hard \
+    /// line break
+    /// """
+    /// ```
+    /// The existing `\` is left in place, but the line over line length is broken.
+    case onlyLinesOverLength
+    /// Always reflow multiline string literals, this will ignore existing escaped newlines in the literal and reflow each line. Hard linebreaks are still respected.
+    /// For example, with a line length of 10:
+    /// ```swift
+    /// """
+    /// one \
+    /// word \
+    /// a line.
+    /// this is too long.
+    /// """
+    /// ```
+    /// will be formatted as:
+    /// ```swift
+    /// """
+    /// one word \
+    /// a line.
+    /// this is \
+    /// too long.
+    /// """
+    /// ```
+    case always
+
+    var isNever: Bool {
+      switch self {
+      case .never:
+        return true
+      default:
+        return false
+      }
+    }
+
+    var isAlways: Bool {
+      switch self {
+      case .always:
+        return true
+      default:
+        return false
+      }
+    }
+  }
+
+  public var reflowMultilineStringLiterals: MultilineStringReflowBehavior
+
   /// Creates a new `Configuration` by loading it from a configuration file.
   public init(contentsOf url: URL) throws {
     let data = try Data(contentsOf: url)
@@ -287,6 +353,10 @@ public struct Configuration: Codable, Equatable {
         Bool.self, forKey: .multiElementCollectionTrailingCommas)
     ?? defaults.multiElementCollectionTrailingCommas
 
+    self.reflowMultilineStringLiterals =
+      try container.decodeIfPresent(MultilineStringReflowBehavior.self, forKey: .reflowMultilineStringLiterals)
+      ?? defaults.reflowMultilineStringLiterals
+
     // If the `rules` key is not present at all, default it to the built-in set
     // so that the behavior is the same as if the configuration had been
     // default-initialized. To get an empty rules dictionary, one can explicitly
@@ -321,6 +391,7 @@ public struct Configuration: Codable, Equatable {
     try container.encode(indentSwitchCaseLabels, forKey: .indentSwitchCaseLabels)
     try container.encode(noAssignmentInExpressions, forKey: .noAssignmentInExpressions)
     try container.encode(multiElementCollectionTrailingCommas, forKey: .multiElementCollectionTrailingCommas)
+    try container.encode(reflowMultilineStringLiterals, forKey: .reflowMultilineStringLiterals)
     try container.encode(rules, forKey: .rules)
   }
 

Sources/SwiftFormat/PrettyPrint/PrettyPrint.swift

@@ -214,7 +214,6 @@ public class PrettyPrinter {
     switch token {
     case .contextualBreakingStart:
       activeBreakingContexts.append(ActiveBreakingContext(lineNumber: outputBuffer.lineNumber))
-
       // Discard the last finished breaking context to keep it from effecting breaks inside of the
       // new context. The discarded context has already either had an impact on the contextual break
       // after it or there was no relevant contextual break, so it's safe to discard.
@@ -414,7 +413,7 @@ public class PrettyPrinter {
 
       var overrideBreakingSuppressed = false
       switch newline {
-      case .elective: break
+      case .elective, .escaped: break
       case .soft(_, let discretionary):
         // A discretionary newline (i.e. from the source) should create a line break even if the
         // rules for breaking are disabled.
@@ -429,6 +428,10 @@ public class PrettyPrinter {
       let suppressBreaking = isBreakingSuppressed && !overrideBreakingSuppressed
       if !suppressBreaking && (!canFit(length) || mustBreak) {
         currentLineIsContinuation = isContinuationIfBreakFires
+        if case .escaped = newline {
+          outputBuffer.enqueueSpaces(size)
+          outputBuffer.write("\\")
+        }
         outputBuffer.writeNewlines(newline)
         lastBreak = true
       } else {
@@ -594,19 +597,51 @@ public class PrettyPrinter {
       // Break lengths are equal to its size plus the token or group following it. Calculate the
       // length of any prior break tokens.
       case .break(_, let size, let newline):
-        if let index = delimIndexStack.last, case .break = tokens[index] {
-          lengths[index] += total
+        if let index = delimIndexStack.last, case .break(_, _, let lastNewline) = tokens[index] {
+          /// If the last break and this break are both `.escaped` we add an extra 1 to the total for the last `.escaped` break.
+          /// This is to handle situations where adding the `\` for an escaped line break would put us over the line length.
+          /// For example, consider the token sequence:
+          /// `[.syntax("this fits"), .break(.escaped), .syntax("this fits in line length"), .break(.escaped)]`
+          /// The naive layout of these tokens will incorrectly print as:
+          ///  """
+          ///  this fits this fits in line length \
+          ///  """
+          ///  which will be too long because of the '\' character. Instead we have to print it as:
+          ///  """
+          ///  this fits \
+          ///  this fits in line length
+          ///  """
+          ///
+          /// While not prematurely inserting a line in situations where a hard line break is occurring, such as:
+          ///
+          /// `[.syntax("some text"), .break(.escaped), .syntax("this is exactly the right length"), .break(.hard)]`
+          ///
+          /// We want this to print as:
+          /// """
+          /// some text this is exactly the right length
+          /// """
+          /// and not:
+          /// """
+          /// some text \
+          /// this is exactly the right length
+          /// """
+          if case .escaped = newline, case .escaped = lastNewline {
+            lengths[index] += total + 1
+          } else {
+            lengths[index] += total
+          }
           delimIndexStack.removeLast()
         }
         lengths.append(-total)
         delimIndexStack.append(i)
 
-        if case .elective = newline {
-          total += size
-        } else {
-          // `size` is never used in this case, because the break always fires. Use `maxLineLength`
-          // to ensure enclosing groups are large enough to force preceding breaks to fire.
-          total += maxLineLength
+        switch newline {
+        case .elective, .escaped:
+            total += size
+        default:
+            // `size` is never used in this case, because the break always fires. Use `maxLineLength`
+            // to ensure enclosing groups are large enough to force preceding breaks to fire.
+            total += maxLineLength
         }
 
       // Space tokens have a length equal to its size.

Sources/SwiftFormat/PrettyPrint/PrettyPrintBuffer.swift

@@ -81,6 +81,8 @@ struct PrettyPrintBuffer {
       numberToPrint = min(count, maximumBlankLines + 1) - consecutiveNewlineCount
     case .hard(let count):
       numberToPrint = count
+    case .escaped:
+      numberToPrint = 1
     }
 
     guard numberToPrint > 0 else { return }

Sources/SwiftFormat/PrettyPrint/Token.swift

@@ -147,6 +147,10 @@ enum NewlineBehavior {
   /// newlines and the configured maximum number of blank lines.
   case hard(count: Int)
 
+  /// Break onto a new line is allowed if neccessary. If a line break is emitted, it will be escaped with a '\', and this breaks whitespace will be printed prior to the
+  /// escaped line break. This is useful in multiline strings where we don't want newlines printed in syntax to appear in the literal.
+  case escaped
+
   /// An elective newline that respects discretionary newlines from the user-entered text.
   static let elective = NewlineBehavior.elective(ignoresDiscretionary: false)