RegexBuilder module

Move the regex builder DSL (except `RegexComponent`) to a new module named RegexBuilder. The DSL depends on `DSLTree` and a few other supporting types, so those types have been made `_spi(RegexBuilder) public`. The SPI establishes an ABI between `_StringProcessing` and `RegexBuilder`, but I don't think it's a concern because the two modules will co-evolve and both will be rebuilt for every release.

Author: rxwei

Package.swift

@@ -42,13 +42,22 @@ let package = Package(
         .target(
             name: "_StringProcessing",
             dependencies: ["_MatchingEngine", "_CUnicode"],
+            swiftSettings: [
+                .unsafeFlags(["-enable-library-evolution"]),
+            ]),
+        .target(
+            name: "RegexBuilder",
+            dependencies: ["_StringProcessing", "_MatchingEngine"],
             swiftSettings: [
                 .unsafeFlags(["-enable-library-evolution"]),
                 .unsafeFlags(["-Xfrontend", "-enable-experimental-pairwise-build-block"])
             ]),
         .testTarget(
             name: "RegexTests",
-            dependencies: ["_StringProcessing"],
+            dependencies: ["_StringProcessing"]),
+        .testTarget(
+            name: "RegexBuilderTests",
+            dependencies: ["_StringProcessing", "RegexBuilder"],
             swiftSettings: [
                 .unsafeFlags(["-Xfrontend", "-enable-experimental-pairwise-build-block"])
             ]),
@@ -73,7 +82,7 @@ let package = Package(
         // MARK: Exercises
         .target(
           name: "Exercises",
-          dependencies: ["_MatchingEngine", "Prototypes", "_StringProcessing"],
+          dependencies: ["_MatchingEngine", "Prototypes", "_StringProcessing", "RegexBuilder"],
           swiftSettings: [
               .unsafeFlags(["-Xfrontend", "-enable-experimental-pairwise-build-block"])
           ]),

Sources/Exercises/Participants/RegexParticipant.swift

@@ -10,6 +10,7 @@
 //===----------------------------------------------------------------------===//
 
 import _StringProcessing
+import RegexBuilder
 
 /*
 

Sources/_StringProcessing/RegexDSL/Anchor.swift renamed to Sources/RegexBuilder/Anchor.swift

@@ -10,6 +10,7 @@
 //===----------------------------------------------------------------------===//
 
 import _MatchingEngine
+@_spi(RegexBuilder) import _StringProcessing
 
 public struct Anchor {
   internal enum Kind {

Sources/_StringProcessing/RegexDSL/Builder.swift renamed to Sources/RegexBuilder/Builder.swift

@@ -9,6 +9,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+@_spi(RegexBuilder) import _StringProcessing
+
 @resultBuilder
 public enum RegexComponentBuilder {
   public static func buildBlock() -> Regex<Substring> {

Sources/_StringProcessing/RegexDSL/DSL.swift renamed to Sources/RegexBuilder/DSL.swift

@@ -10,6 +10,16 @@
 //===----------------------------------------------------------------------===//
 
 import _MatchingEngine
+@_spi(RegexBuilder) import _StringProcessing
+import _StringProcessing
+
+extension Regex {
+  public init<Content: RegexComponent>(
+    @RegexComponentBuilder _ content: () -> Content
+  ) where Content.Output == Output {
+    self.init(content())
+  }
+}
 
 // A convenience protocol for builtin regex components that are initialized with
 // a `DSLTree` node.
@@ -57,17 +67,6 @@ extension UnicodeScalar: RegexComponent {
   }
 }
 
-extension CharacterClass: RegexComponent {
-  public typealias Output = Substring
-
-  public var regex: Regex<Output> {
-    guard let ast = self.makeAST() else {
-      fatalError("FIXME: extended AST?")
-    }
-    return Regex(ast: ast)
-  }
-}
-
 // MARK: - Combinators
 
 // MARK: Concatenation
@@ -96,9 +95,9 @@ public struct QuantificationBehavior {
     case reluctantly
     case possessively
   }
-  
+
   var kind: Kind
-  
+
   internal var astKind: AST.Quantification.Kind {
     switch kind {
     case .eagerly: return .eager
@@ -108,19 +107,49 @@ public struct QuantificationBehavior {
   }
 }
 
+extension DSLTree.Node {
+  /// Generates a DSLTree node for a repeated range of the given DSLTree node.
+  /// Individual public API functions are in the generated Variadics.swift file.
+  static func repeating(
+    _ range: Range<Int>,
+    _ behavior: QuantificationBehavior,
+    _ node: DSLTree.Node
+  ) -> DSLTree.Node {
+    // TODO: Throw these as errors
+    assert(range.lowerBound >= 0, "Cannot specify a negative lower bound")
+    assert(!range.isEmpty, "Cannot specify an empty range")
+
+    switch (range.lowerBound, range.upperBound) {
+    case (0, Int.max): // 0...
+      return .quantification(.zeroOrMore, behavior.astKind, node)
+    case (1, Int.max): // 1...
+      return .quantification(.oneOrMore, behavior.astKind, node)
+    case _ where range.count == 1: // ..<1 or ...0 or any range with count == 1
+      // Note: `behavior` is ignored in this case
+      return .quantification(.exactly(.init(faking: range.lowerBound)), .eager, node)
+    case (0, _): // 0..<n or 0...n or ..<n or ...n
+      return .quantification(.upToN(.init(faking: range.upperBound)), behavior.astKind, node)
+    case (_, Int.max): // n...
+      return .quantification(.nOrMore(.init(faking: range.lowerBound)), behavior.astKind, node)
+    default: // any other range
+      return .quantification(.range(.init(faking: range.lowerBound), .init(faking: range.upperBound)), behavior.astKind, node)
+    }
+  }
+}
+
 extension QuantificationBehavior {
   /// Match as much of the input string as possible, backtracking when
   /// necessary.
   public static var eagerly: QuantificationBehavior {
     .init(kind: .eagerly)
   }
-  
+
   /// Match as little of the input string as possible, expanding the matched
   /// region as necessary to complete a match.
   public static var reluctantly: QuantificationBehavior {
     .init(kind: .reluctantly)
   }
-  
+
   /// Match as much of the input string as possible, performing no backtracking.
   public static var possessively: QuantificationBehavior {
     .init(kind: .possessively)
@@ -247,22 +276,18 @@ public struct TryCapture<Output>: _BuiltinRegexComponent {
 
 // MARK: - Backreference
 
-struct ReferenceID: Hashable, Equatable {
-  private static var counter: Int = 0
-  var base: Int
-
-  init() {
-    base = Self.counter
-    Self.counter += 1
-  }
-}
-
 public struct Reference<Capture>: RegexComponent {
   let id = ReferenceID()
-  
+
   public init(_ captureType: Capture.Type = Capture.self) {}
 
   public var regex: Regex<Capture> {
     .init(node: .atom(.symbolicReference(id)))
   }
 }
+
+extension Regex.Match {
+  public subscript<Capture>(_ reference: Reference<Capture>) -> Capture {
+    self[reference.id]
+  }
+}

Sources/RegexBuilder/Match.swift

@@ -0,0 +1,28 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2021-2022 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
+//
+//===----------------------------------------------------------------------===//
+
+import _StringProcessing
+
+extension String {
+  public func match<R: RegexComponent>(
+    @RegexComponentBuilder _ content: () -> R
+  ) -> Regex<R.Output>.Match? {
+    match(content())
+  }
+}
+
+extension Substring {
+  public func match<R: RegexComponent>(
+    @RegexComponentBuilder _ content: () -> R
+  ) -> Regex<R.Output>.Match? {
+    match(content())
+  }
+}

Sources/_StringProcessing/RegexDSL/Variadics.swift renamed to Sources/RegexBuilder/Variadics.swift

@@ -12,6 +12,7 @@
 // BEGIN AUTO-GENERATED CONTENT
 
 import _MatchingEngine
+@_spi(RegexBuilder) import _StringProcessing
 
 extension RegexComponentBuilder {
   public static func buildPartialBlock<W0, W1, C0, R0: RegexComponent, R1: RegexComponent>(

Sources/VariadicsGenerator/VariadicsGenerator.swift

@@ -9,7 +9,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-// swift run VariadicsGenerator --max-arity 10 > Sources/_StringProcessing/RegexDSL/Variadics.swift
+// swift run VariadicsGenerator --max-arity 10 > Sources/RegexBuilder/Variadics.swift
 
 import ArgumentParser
 #if os(macOS)
@@ -121,6 +121,7 @@ struct VariadicsGenerator: ParsableCommand {
       // BEGIN AUTO-GENERATED CONTENT
 
       import _MatchingEngine
+      @_spi(RegexBuilder) import _StringProcessing
 
 
       """)

Sources/_StringProcessing/CharacterClass.swift

@@ -178,6 +178,17 @@ public struct CharacterClass: Hashable {
   }
 }
 
+extension CharacterClass: RegexComponent {
+  public typealias Output = Substring
+
+  public var regex: Regex<Output> {
+    guard let ast = self.makeAST() else {
+      fatalError("FIXME: extended AST?")
+    }
+    return Regex(ast: ast)
+  }
+}
+
 extension RegexComponent where Self == CharacterClass {
   public static var any: CharacterClass {
     .init(cc: .any, matchLevel: .graphemeCluster)