Wrap multiline string literals to line length.

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)