Merge pull request swiftlang#128 from dylansturg/contextual_breaking_tokens

Support conditional indentation for dot-chained expressions to align dots

Author: allevato

Documentation/Configuration.md

@@ -80,6 +80,13 @@ top-level keys and values:
     conditional compilation blocks are indented. If this setting is `false` the body
     of `#if`, `#elseif`, and `#else` is not indented. Defaults to `true`.
 
+*  `lineBreakAroundMultilineExpressionChainComponents` _(boolean)_:  Determines whether
+   line breaks should be forced before and after multiline components of dot-chained
+   expressions, such as function calls and subscripts chained together through member
+   access (i.e. "." expressions). When any component is multiline and this option is
+   true, a line break is forced before the "." of the component and after the component's
+   closing delimiter (i.e. right paren, right bracket, right brace, etc.).
+
 > TODO: Add support for enabling/disabling specific syntax transformations in
 > the pipeline.
 

Sources/SwiftFormatConfiguration/Configuration.swift

@@ -32,6 +32,7 @@ public struct Configuration: Codable, Equatable {
     case lineBreakBeforeEachGenericRequirement
     case prioritizeKeepingFunctionOutputTogether
     case indentConditionalCompilationBlocks
+    case lineBreakAroundMultilineExpressionChainComponents
     case rules
   }
 
@@ -111,6 +112,13 @@ public struct Configuration: Codable, Equatable {
   /// Determines the indentation behavior for `#if`, `#elseif`, and `#else`.
   public var indentConditionalCompilationBlocks = true
 
+  /// Determines whether line breaks should be forced before and after multiline components of
+  /// dot-chained expressions, such as function calls and subscripts chained together through member
+  /// access (i.e. "." expressions). When any component is multiline and this option is true, a line
+  /// break is forced before the "." of the component and after the component's closing delimiter
+  /// (i.e. right paren, right bracket, right brace, etc.).
+  public var lineBreakAroundMultilineExpressionChainComponents = false
+
   /// Constructs a Configuration with all default values.
   public init() {
     self.version = highestSupportedConfigurationVersion
@@ -157,6 +165,9 @@ public struct Configuration: Codable, Equatable {
       = try container.decodeIfPresent(Bool.self, forKey: .prioritizeKeepingFunctionOutputTogether) ?? false
     self.indentConditionalCompilationBlocks
       = try container.decodeIfPresent(Bool.self, forKey: .indentConditionalCompilationBlocks) ?? true
+    self.lineBreakAroundMultilineExpressionChainComponents =
+      try container.decodeIfPresent(
+        Bool.self, forKey: .lineBreakAroundMultilineExpressionChainComponents) ?? false
 
     // 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
@@ -181,6 +192,9 @@ public struct Configuration: Codable, Equatable {
     try container.encode(lineBreakBeforeEachGenericRequirement, forKey: .lineBreakBeforeEachGenericRequirement)
     try container.encode(prioritizeKeepingFunctionOutputTogether, forKey: .prioritizeKeepingFunctionOutputTogether)
     try container.encode(indentConditionalCompilationBlocks, forKey: .indentConditionalCompilationBlocks)
+    try container.encode(
+      lineBreakAroundMultilineExpressionChainComponents,
+      forKey: .lineBreakAroundMultilineExpressionChainComponents)
     try container.encode(rules, forKey: .rules)
   }
 }

Sources/SwiftFormatPrettyPrint/PrettyPrint.swift

@@ -44,6 +44,25 @@ public class PrettyPrinter {
     var contributesBlockIndent: Bool
   }
 
+  /// Records state of `contextualBreakingStart` tokens.
+  private struct ActiveBreakingContext {
+    /// The line number in the `outputBuffer` where a start token appeared.
+    let lineNumber: Int
+
+    enum BreakingBehavior {
+      /// The behavior hasn't been determined. This is treated as `continuation`.
+      case unset
+      /// The break is created as a `continuation` break, setting `currentLineIsContinuation` when
+      /// it fires.
+      case continuation
+      /// The break maintains the existing value of `currentLineIsContinuation` when it fires.
+      case maintain
+    }
+
+    /// The behavior to use when a `contextual` break fires inside of this break context.
+    var contextualBreakingBehavior = BreakingBehavior.unset
+  }
+
   private let context: Context
   private var configuration: Configuration { return context.configuration }
   private let maxLineLength: Int
@@ -75,6 +94,12 @@ public class PrettyPrinter {
   /// so far.
   private var activeOpenBreaks: [ActiveOpenBreak] = []
 
+  /// Stack of the active breaking contexts.
+  private var activeBreakingContexts: [ActiveBreakingContext] = []
+
+  /// The most recently ended breaking context, used to force certain following `contextual` breaks.
+  private var lastEndedBreakingContext: ActiveBreakingContext? = nil
+
   /// Keeps track of the current line number being printed.
   private var lineNumber: Int = 1
 
@@ -243,6 +268,24 @@ public class PrettyPrinter {
     assert(length >= 0, "Token lengths must be positive")
 
     switch token {
+    case .contextualBreakingStart:
+      activeBreakingContexts.append(ActiveBreakingContext(lineNumber: 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.
+      lastEndedBreakingContext = nil
+
+    case .contextualBreakingEnd:
+      guard let closedContext = activeBreakingContexts.popLast() else {
+        fatalError("Encountered unmatched contextualBreakingEnd token.")
+      }
+
+      // Break contexts create scopes, and a breaking context should never be carried between
+      // scopes. When there's no active break context, discard the popped one to prevent carrying it
+      // into a new scope.
+      lastEndedBreakingContext = activeBreakingContexts.isEmpty ? nil : closedContext
+
     // Check if we need to force breaks in this group, and calculate the indentation to be used in
     // the group.
     case .open(let breaktype):
@@ -384,6 +427,42 @@ public class PrettyPrinter {
 
       case .reset:
         mustBreak = currentLineIsContinuation
+
+      case .contextual:
+        // When the last context spanned multiple lines, move the next context (in the same parent
+        // break context scope) onto its own line. For example, this is used when the previous
+        // context includes a multiline trailing closure or multiline function argument list.
+        if let lastBreakingContext = lastEndedBreakingContext {
+          if configuration.lineBreakAroundMultilineExpressionChainComponents {
+            mustBreak = lastBreakingContext.lineNumber != lineNumber
+          }
+        }
+
+        // Wait for a contextual break to fire and then update the breaking behavior for the rest of
+        // the contextual breaks in this scope to match the behavior of the one that fired.
+        let willFire = (!isAtStartOfLine && length > spaceRemaining) || mustBreak
+        if willFire {
+          // Update the active breaking context according to the most recently finished breaking
+          // context so all following contextual breaks in this scope to have matching behavior.
+          if let closedContext = lastEndedBreakingContext,
+            let activeContext = activeBreakingContexts.last,
+            case .unset = activeContext.contextualBreakingBehavior
+          {
+            activeBreakingContexts[activeBreakingContexts.count - 1].contextualBreakingBehavior =
+              (closedContext.lineNumber == lineNumber) ? .continuation : .maintain
+          }
+        }
+
+        if let activeBreakingContext = activeBreakingContexts.last {
+          switch activeBreakingContext.contextualBreakingBehavior {
+          case .unset, .continuation:
+            isContinuationIfBreakFires = true
+          case .maintain:
+            isContinuationIfBreakFires = currentLineIsContinuation
+          }
+        }
+
+        lastEndedBreakingContext = nil
       }
 
       var overrideBreakingSuppressed = false
@@ -494,6 +573,12 @@ public class PrettyPrinter {
     // Calculate token lengths
     for (i, token) in tokens.enumerated() {
       switch token {
+      case .contextualBreakingStart:
+        lengths.append(0)
+
+      case .contextualBreakingEnd:
+        lengths.append(0)
+
       // Open tokens have lengths equal to the total of the contents of its group. The value is
       // calcualted when close tokens are encountered.
       case .open:
@@ -667,9 +752,17 @@ public class PrettyPrinter {
       printDebugIndent()
       print("[COMMA DELIMITED START Idx: \(idx)]")
 
-      case .commaDelimitedRegionEnd:
-        printDebugIndent()
-        print("[COMMA DELIMITED END Idx: \(idx)]")
+    case .commaDelimitedRegionEnd:
+      printDebugIndent()
+      print("[COMMA DELIMITED END Idx: \(idx)]")
+
+    case .contextualBreakingStart:
+      printDebugIndent()
+      print("[START BREAKING CONTEXT Idx: \(idx)]")
+
+    case .contextualBreakingEnd:
+      printDebugIndent()
+      print("[END BREAKING CONTEXT Idx: \(idx)]")
     }
   }
 

Sources/SwiftFormatPrettyPrint/Token.swift

@@ -111,6 +111,19 @@ enum BreakKind: Equatable {
   /// ```
   case reset
 
+  /// A `contextual` break acts as either a `continue` break or maintains the existing level of
+  /// indentation when it fires. The contextual breaking beahvior of a given contextual breaking
+  /// scope (i.e. inside a `contextualBreakingStart`/`contextualBreakingEnd` region) is set by the
+  /// first child `contextualBreakingStart`/`contextualBreakingEnd` pair. When the first child is
+  /// multiline the contextual breaks maintain indentation and they are continuations otherwise.
+  ///
+  /// These are used when multiple related breaks need to exhibit the same behavior based the
+  /// context in which they appear. For example, when breaks exist between expressions that are
+  /// chained together (e.g. member access) and indenting the line *after* a closing paren/brace
+  /// looks better indented when the previous expr was 1 line but not indented when the expr was
+  /// multiline.
+  case contextual
+
   /// A `close` break that defaults to forced breaking behavior.
   static let close = BreakKind.close(mustBreak: true)
 
@@ -179,6 +192,12 @@ enum Token {
   /// if and only if the collection spans multiple lines.
   case commaDelimitedRegionEnd(hasTrailingComma: Bool)
 
+  /// Starts a scope where `contextual` breaks have consistent behavior.
+  case contextualBreakingStart
+
+  /// Ends a scope where `contextual` breaks have consistent behavior.
+  case contextualBreakingEnd
+
   // Convenience overloads for the enum types
   static let open = Token.open(.inconsistent, 0)