Heterogeneous alternation

Introduce `oneOf` combinator, which takes a builder block and joins all elements into a regex alterantion. Fix the legacy VM to support alternation with captures.

-----

Example:

```swift
oneOf {
"a".capture()
"b".capture()
"c"
} => `.Match = (Substring, Substring?, Substring?)`
```

Author: rxwei

Sources/VariadicsGenerator/VariadicsGenerator.swift

@@ -160,6 +160,20 @@ struct VariadicsGenerator: ParsableCommand {
       print(to: &standardError)
     }
 
+    print("Generating alternation overloads...", to: &standardError)
+    for (leftArity, rightArity) in Permutations(totalArity: maxArity) {
+      print(
+        "  Left arity: \(leftArity)  Right arity: \(rightArity)",
+        to: &standardError)
+      emitAlternation(leftArity: leftArity, rightArity: rightArity)
+    }
+
+    print("Generating 'AlternationBuilder.buildBlock(_:)' overloads...", to: &standardError)
+    for arity in 1..<maxArity {
+      print("  Capture arity: \(arity)", to: &standardError)
+      emitUnaryAlternationBuildBlock(arity: arity)
+    }
+
     output("\n\n")
 
     output("// END AUTO-GENERATED CONTENT\n")
@@ -444,4 +458,90 @@ struct VariadicsGenerator: ParsableCommand {
 
       """)
   }
+
+  func emitAlternation(leftArity: Int, rightArity: Int) {
+    let typeName = "_Alternation_\(leftArity)_\(rightArity)"
+    let leftGenParams: String = {
+      if leftArity == 0 {
+        return "R0"
+      }
+      return "R0, W0, " + (0..<leftArity).map { "C\($0)" }.joined(separator: ", ")
+    }()
+    let rightGenParams: String = {
+      if rightArity == 0 {
+        return "R1"
+      }
+      return "R1, W1, " + (leftArity..<leftArity+rightArity).map { "C\($0)" }.joined(separator: ", ")
+    }()
+    let genericParams = leftGenParams + ", " + rightGenParams
+    let whereClause: String = {
+      var result = "where R0: \(regexProtocolName), R1: \(regexProtocolName)"
+      if leftArity > 0 {
+        result += ", R0.\(matchAssociatedTypeName) == (W0, \((0..<leftArity).map { "C\($0)" }.joined(separator: ", ")))"
+      }
+      if rightArity > 0 {
+        result += ", R1.\(matchAssociatedTypeName) == (W1, \((leftArity..<leftArity+rightArity).map { "C\($0)" }.joined(separator: ", ")))"
+      }
+      return result
+    }()
+    let resultCaptures: String = {
+      var result = (0..<leftArity).map { "C\($0)" }.joined(separator: ", ")
+      if leftArity > 0, rightArity > 0 {
+        result += ", "
+      }
+      result += (leftArity..<leftArity+rightArity).map { "C\($0)?" }.joined(separator: ", ")
+      return result
+    }()
+    let matchType: String = {
+      if leftArity == 0, rightArity == 0 {
+        return baseMatchTypeName
+      }
+      return "(\(baseMatchTypeName), \(resultCaptures))"
+    }()
+    output("""
+      public struct \(typeName)<\(genericParams)>: \(regexProtocolName) \(whereClause) {
+        public typealias Match = \(matchType)
+        public let regex: Regex<Match>
+
+        public init(_ left: R0, _ right: R1) {
+          self.regex = .init(node: left.regex.root.appendingAlternationCase(right.regex.root))
+        }
+      }
+
+      extension AlternationBuilder {
+        public static func buildBlock<\(genericParams)>(combining next: R1, into combined: R0) -> \(typeName)<\(genericParams)> {
+          .init(combined, next)
+        }
+      }
+
+      public func | <\(genericParams)>(lhs: R0, rhs: R1) -> \(typeName)<\(genericParams)> {
+        .init(lhs, rhs)
+      }
+
+      """)
+  }
+
+  func emitUnaryAlternationBuildBlock(arity: Int) {
+    assert(arity > 0)
+    let captures = (0..<arity).map { "C\($0)" }.joined(separator: ", ")
+    let genericParams: String = {
+      if arity == 0 {
+        return "R"
+      }
+      return "R, W, " + captures
+    }()
+    let whereClause: String = """
+      where R: \(regexProtocolName), \
+      R.\(matchAssociatedTypeName) == (W, \(captures))
+      """
+    let resultCaptures = (0..<arity).map { "C\($0)?" }.joined(separator: ", ")
+    output("""
+      extension AlternationBuilder {
+        public static func buildBlock<\(genericParams)>(_ regex: R) -> Regex<(W, \(resultCaptures))> \(whereClause) {
+          .init(node: .alternation([regex.regex.root]))
+        }
+      }
+      
+      """)
+  }
 }

Sources/_StringProcessing/ASTBuilder.swift

@@ -36,6 +36,13 @@ func alt(_ asts: AST.Node...) -> AST.Node {
   alt(asts)
 }
 
+func appendAlt(_ new: AST.Node, to combined: AST.Node) -> AST.Node {
+  if case .alternation(let alternation) = combined {
+    return alt(alternation.children + [new])
+  }
+  return alt(combined, new)
+}
+
 func concat(_ asts: [AST.Node]) -> AST.Node {
   .concatenation(.init(asts, .fake))
 }

Sources/_StringProcessing/Legacy/LegacyCompile.swift

@@ -240,22 +240,54 @@ func compile(
       //       E.g. `a` falls-through to the rest of the program and the
       //       other cases branch back.
       //
-      assert(!children.isEmpty)
-      guard children.count > 1 else {
-        return try compileNode(children[0])
+      
+      // For every capturing child after the child at the given index, emit a
+      // nil capture. This is used for skipping the remaining alternation
+      // cases after a succesful match.
+      func nullifyRest(after index: Int) {
+        for child in children.suffix(from: index + 1) where child.hasCapture {
+          instructions.append(contentsOf: [
+            .beginGroup,
+            .captureNil(childType: child.captureStructure.type),
+            .endGroup,
+          ])
+        }
       }
 
       let last = children.last!
       let middle = children.dropLast()
       let done = createLabel()
-      for child in middle {
+      for (childIndex, child) in middle.enumerated() {
         let nextLabel = createLabel()
+        if child.hasCapture {
+          instructions.append(.beginGroup)
+        }
         instructions.append(.split(disfavoring: nextLabel.label!))
         try compileNode(child)
-        instructions.append(.goto(label: done.label!))
-        instructions.append(nextLabel)
+        if child.hasCapture {
+          instructions.append(.captureSome)
+          instructions.append(.endGroup)
+        }
+        nullifyRest(after: childIndex)
+        instructions.append(contentsOf: [
+          .goto(label: done.label!),
+          nextLabel
+        ])
+        if child.hasCapture {
+          instructions.append(contentsOf: [
+            .captureNil(childType: child.captureStructure.type),
+            .endGroup
+          ])
+        }
+      }
+      if last.hasCapture {
+        instructions.append(.beginGroup)
       }
       try compileNode(last)
+      if last.hasCapture {
+        instructions.append(.captureSome)
+        instructions.append(.endGroup)
+      }
       instructions.append(done)
       return