Introduce tryCapture(_:).

`tryCapture(_:)` works like `capture(_:)` but accepts an optional or throwing capture transform instead. When the transform fails (returns `nil` or throws), it will cause matching to fail. This works well with failable conversion initializers such as `Int.init?(_:)`, `Unicode.Scalar.init?(_:)`, etc.

----

Example:

With `tryCapture`, the following example avoids unnecessary levels of optionals and double optionals.

```swift
line.match {
  OneOrMore(.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
  Optionally {
    ".."
    OneOrMore(.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
  }
  OneOrMore(.whitespace)
  ";"
  OneOrMore(.whitespace)
  OneOrMore(.word).tryCapture(Unicode.GraphemeBreakProperty.init)
  Repeat(.any)
} // Regex<(Substring, Unicode.Scalar, Unicode.Scalar?, Unicode.GraphemeBreakProperty)>
```

Author: rxwei

Sources/Exercises/Participants/RegexParticipant.swift

@@ -43,6 +43,8 @@ struct RegexLiteralParticipant: Participant {
   }
 }
 
+// MARK: - Regex literal
+
 private func extractFromCaptures(
   _ match: Tuple4<Substring, Substring, Substring?, Substring>
 ) -> GraphemeBreakEntry? {
@@ -63,28 +65,33 @@ private func graphemeBreakPropertyData<RP: RegexProtocol>(
   line.match(regex).map(\.match).flatMap(extractFromCaptures)
 }
 
+private func graphemeBreakPropertyDataLiteral(
+  forLine line: String
+) -> GraphemeBreakEntry? {
+  return graphemeBreakPropertyData(
+    forLine: line,
+    using: r(#"([0-9A-F]+)(?:\.\.([0-9A-F]+))?\s+;\s+(\w+).*"#,
+             matching: Tuple4<Substring, Substring, Substring?, Substring>.self))
+}
+
+// MARK: - Builder DSL
+
 private func graphemeBreakPropertyData(
   forLine line: String
 ) -> GraphemeBreakEntry? {
-  graphemeBreakPropertyData(forLine: line, using: Regex {
-    OneOrMore(.hexDigit).capture()
+  line.match {
+    OneOrMore(.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
     Optionally {
       ".."
-      OneOrMore(.hexDigit).capture()
+      OneOrMore(.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
     }
     OneOrMore(.whitespace)
     ";"
     OneOrMore(.whitespace)
-    OneOrMore(.word).capture()
+    OneOrMore(.word).tryCapture(Unicode.GraphemeBreakProperty.init)
     Repeat(.any)
-  })
-}
-
-private func graphemeBreakPropertyDataLiteral(
-  forLine line: String
-) -> GraphemeBreakEntry? {
-  return graphemeBreakPropertyData(
-    forLine: line,
-    using: r(#"([0-9A-F]+)(?:\.\.([0-9A-F]+))?\s+;\s+(\w+).*"#,
-             matching: Tuple4<Substring, Substring, Substring?, Substring>.self))
+  }.map {
+    let (_, lower, upper, property) = $0.match.tuple
+    return GraphemeBreakEntry(lower...(upper ?? lower), property)
+  }
 }

Sources/_MatchingEngine/Regex/AST/AST.swift

@@ -210,18 +210,61 @@ extension AST {
 
 // FIXME: Get this out of here
 public struct CaptureTransform: Equatable, Hashable, CustomStringConvertible {
+  public enum Closure {
+    case nonfailable((Substring) -> Any)
+    case failable((Substring) -> Any?)
+    case throwing((Substring) throws -> Any)
+  }
   public let resultType: Any.Type
-  public let closure: (Substring) -> Any
+  public let closure: Closure
 
-  public init(resultType: Any.Type, _ closure: @escaping (Substring) -> Any) {
+  public init(resultType: Any.Type, closure: Closure) {
     self.resultType = resultType
     self.closure = closure
   }
 
-  public func callAsFunction(_ input: Substring) -> Any {
-    let result = closure(input)
-    assert(type(of: result) == resultType)
-    return result
+  public init(
+    resultType: Any.Type,
+    _ closure: @escaping (Substring) -> Any
+  ) {
+    self.init(resultType: resultType, closure: .nonfailable(closure))
+  }
+
+  public init(
+    resultType: Any.Type,
+    _ closure: @escaping (Substring) -> Any?
+  ) {
+    self.init(resultType: resultType, closure: .failable(closure))
+  }
+
+  public init(
+    resultType: Any.Type,
+    _ closure: @escaping (Substring) throws -> Any
+  ) {
+    self.init(resultType: resultType, closure: .throwing(closure))
+  }
+
+  public func callAsFunction(_ input: Substring) -> Any? {
+    switch closure {
+    case .nonfailable(let closure):
+      let result = closure(input)
+      assert(type(of: result) == resultType)
+      return result
+    case .failable(let closure):
+      guard let result = closure(input) else {
+        return nil
+      }
+      assert(type(of: result) == resultType)
+      return result
+    case .throwing(let closure):
+      do {
+        let result = try closure(input)
+        assert(type(of: result) == resultType)
+        return result
+      } catch {
+        return nil
+      }
+    }
   }
 
   public static func == (lhs: CaptureTransform, rhs: CaptureTransform) -> Bool {

Sources/_StringProcessing/Legacy/HareVM.swift

@@ -188,7 +188,9 @@ struct HareVM: VirtualMachine {
         bunny.hop()
 
       case let .endCapture(transform):
-        bunny.core.endCapture(bunny.sp, transform: transform)
+        guard bunny.core.endCapture(bunny.sp, transform: transform) else {
+          return nil
+        }
         bunny.hop()
 
       case .beginGroup:

Sources/_StringProcessing/Legacy/TortoiseVM.swift

@@ -108,8 +108,11 @@ extension TortoiseVM {
           hatchling.core.beginCapture(sp)
           hatchling.plod()
         case .endCapture(let transform):
-          hatchling.core.endCapture(sp, transform: transform)
-          hatchling.plod()
+          if hatchling.core.endCapture(sp, transform: transform) {
+            hatchling.plod()
+          } else {
+            hatchling.plod(to: code.endIndex)
+          }
         case .beginGroup:
           hatchling.core.beginGroup()
           hatchling.plod()

Sources/_StringProcessing/Legacy/VirtualMachine.swift

@@ -117,11 +117,25 @@ extension RECode {
       captureState.start(at: index)
     }
 
-    mutating func endCapture(_ endIndex: String.Index, transform: CaptureTransform?) {
+    /// Ends the current capture at the given index and applies the given
+    /// transform if available. Returns true on success. Returns false if the
+    /// trasnform failed.
+    mutating func endCapture(
+      _ endIndex: String.Index, transform: CaptureTransform?
+    ) -> Bool {
       let range = captureState.end(at: endIndex)
       let substring = input[range]
-      let value = transform?(substring) ?? substring
+      let value: Any
+      if let transform = transform {
+        guard let transformed = transform(substring) else {
+          return false
+        }
+        value = transformed
+      } else {
+        value = substring
+      }
       topLevelCaptures.append(.atom(value))
+      return true
     }
 
     mutating func beginGroup() {

Sources/_StringProcessing/RegexDSL/DSL.swift

@@ -172,15 +172,46 @@ public struct CapturingGroup<Match: MatchProtocol>: RegexProtocol {
     )
   }
 
+  init<Component: RegexProtocol>(
+    _ component: Component,
+    transform: CaptureTransform
+  ) {
+    self.regex = .init(
+      ast: .groupTransform(
+        .init(.init(faking: .capture), component.regex.ast, .fake),
+        transform: transform))
+  }
+
   init<NewCapture, Component: RegexProtocol>(
     _ component: Component,
     transform: @escaping (Substring) -> NewCapture
   ) {
-    self.regex = .init(ast:
-      .groupTransform(
-        .init(.init(faking: .capture), component.regex.ast, .fake),
-        transform: CaptureTransform(resultType: NewCapture.self) {
-          transform($0) as Any
-        }))
+    self.init(
+      component,
+      transform: CaptureTransform(resultType: NewCapture.self) {
+        transform($0) as Any
+      })
+  }
+
+  init<NewCapture, Component: RegexProtocol>(
+    _ component: Component,
+    transform: @escaping (Substring) throws -> NewCapture
+  ) {
+    self.init(
+      component,
+      transform: CaptureTransform(resultType: NewCapture.self) {
+        try transform($0) as Any
+      })
+  }
+
+  init<NewCapture, Component: RegexProtocol>(
+    _ component: Component,
+    transform: @escaping (Substring) -> NewCapture?
+  ) {
+    self.init(
+      component,
+      transform: CaptureTransform(resultType: NewCapture.self) {
+        transform($0) as Any?
+      })
   }
 }

Sources/_StringProcessing/RegexDSL/DSLCapture.swift

@@ -20,6 +20,18 @@ extension RegexProtocol {
     .init(self, transform: transform)
   }
 
+  public func tryCapture<NewCapture>(
+    _ transform: @escaping (Substring) throws -> NewCapture
+  ) -> CapturingGroup<Tuple2<Substring, NewCapture>> where Match.Capture: EmptyCaptureProtocol {
+    .init(self, transform: transform)
+  }
+
+  public func tryCapture<NewCapture>(
+    _ transform: @escaping (Substring) -> NewCapture?
+  ) -> CapturingGroup<Tuple2<Substring, NewCapture>> where Match.Capture: EmptyCaptureProtocol {
+    .init(self, transform: transform)
+  }
+
   public func capture<C0>() -> CapturingGroup<Tuple3<Substring, Substring, C0>>
   where Match.Capture == C0 {
     .init(self)
@@ -31,6 +43,18 @@ extension RegexProtocol {
     .init(self, transform: transform)
   }
 
+  public func tryCapture<NewCapture, C0>(
+    _ transform: @escaping (Substring) throws -> NewCapture
+  ) -> CapturingGroup<Tuple3<Substring, NewCapture, C0>> where Match.Capture == C0 {
+    .init(self, transform: transform)
+  }
+
+  public func tryCapture<NewCapture, C0>(
+    _ transform: @escaping (Substring) -> NewCapture?
+  ) -> CapturingGroup<Tuple3<Substring, NewCapture, C0>> where Match.Capture == C0 {
+    .init(self, transform: transform)
+  }
+
   public func capture<C0, C1>() -> CapturingGroup<Tuple4<Substring, Substring, C0, C1>> where Match.Capture == Tuple2<C0, C1> {
     .init(self)
   }
@@ -41,6 +65,18 @@ extension RegexProtocol {
     .init(self, transform: transform)
   }
 
+  public func tryCapture<NewCapture, C0, C1>(
+    _ transform: @escaping (Substring) throws -> NewCapture
+  ) -> CapturingGroup<Tuple4<Substring, NewCapture, C0, C1>> where Match.Capture == Tuple2<C0, C1> {
+    .init(self, transform: transform)
+  }
+
+  public func tryCapture<NewCapture, C0, C1>(
+    _ transform: @escaping (Substring) -> NewCapture?
+  ) -> CapturingGroup<Tuple4<Substring, NewCapture, C0, C1>> where Match.Capture == Tuple2<C0, C1> {
+    .init(self, transform: transform)
+  }
+
   public func capture<C0, C1, C2>() -> CapturingGroup<Tuple5<Substring, Substring, C0, C1, C2>>
   where Match.Capture == Tuple3<C0, C1, C2> {
     .init(self)
@@ -51,6 +87,18 @@ extension RegexProtocol {
   ) -> CapturingGroup<Tuple5<Substring, NewCapture, C0, C1, C2>> where Match.Capture == Tuple3<C0, C1, C2> {
     .init(self, transform: transform)
   }
+
+  public func tryCapture<NewCapture, C0, C1, C2>(
+    _ transform: @escaping (Substring) throws -> NewCapture
+  ) -> CapturingGroup<Tuple5<Substring, NewCapture, C0, C1, C2>> where Match.Capture == Tuple3<C0, C1, C2> {
+    .init(self, transform: transform)
+  }
+
+  public func tryCapture<NewCapture, C0, C1, C2>(
+    _ transform: @escaping (Substring) -> NewCapture?
+  ) -> CapturingGroup<Tuple5<Substring, NewCapture, C0, C1, C2>> where Match.Capture == Tuple3<C0, C1, C2> {
+    .init(self, transform: transform)
+  }
 }
 
 /* Or using parameterized extensions and variadic generics.

Tests/ExercisesTests/ExercisesTests.swift

@@ -39,7 +39,12 @@ class ExercisesTests: XCTestCase {
         let result = f(line)
         guard ref == result else {
           pass = false
-          XCTFail("Participant \(participant.name) failed")
+          XCTFail("""
+            Participant \(participant.name) failed
+            - Input: \(line)
+            - Expected: \(String(describing: ref))
+            - Result: \(String(describing: result))
+            """)
           break
         }
       }

Tests/RegexTests/RegexDSLTests.swift

@@ -17,7 +17,7 @@ class RegexDSLTests: XCTestCase {
     let regex = Regex {
       "a"
       Character("b").capture() // Character
-      "1".capture { Int($0)! } // Int
+      "1".tryCapture { Int($0) } // Int
     }
     // Assert the inferred capture type.
     let _: Tuple3<Substring, Substring, Int>.Type = type(of: regex).Match.self
@@ -150,7 +150,7 @@ class RegexDSLTests: XCTestCase {
     let regex2 = Regex {
       "a".+
       Regex {
-        "b".capture { Int($0)! }.*
+        "b".tryCapture { Int($0) }.*
         "e".?
       }.capture()
     }
@@ -159,8 +159,8 @@ class RegexDSLTests: XCTestCase {
     let regex3 = Regex {
       "a".+
       Regex {
-        "b".capture { Int($0)! }
-        "c".capture { Double($0)! }.*
+        "b".tryCapture { Int($0) }
+        "c".tryCapture { Double($0) }.*
         "e".?
       }.capture()
     }
@@ -256,6 +256,33 @@ class RegexDSLTests: XCTestCase {
       XCTAssertEqual(propertyString, "Extend")
     }
 
+    let regexWithTryCapture = Regex {
+      OneOrMore(CharacterClass.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
+      Optionally {
+        ".."
+        OneOrMore(CharacterClass.hexDigit).tryCapture(Unicode.Scalar.init(hex:))
+      }
+      OneOrMore(CharacterClass.whitespace)
+      ";"
+      OneOrMore(CharacterClass.whitespace)
+      OneOrMore(CharacterClass.word).capture()
+      Repeat(CharacterClass.any)
+    } // Regex<(Substring, Unicode.Scalar, Unicode.Scalar?, Substring)>
+    do {
+      // Assert the inferred capture type.
+      typealias ExpectedMatch = Tuple4<
+        Substring, Unicode.Scalar, Unicode.Scalar?, Substring
+      >
+      let _: ExpectedMatch.Type = type(of: regexWithTryCapture).Match.self
+      let maybeMatchResult = line.match(regexWithTryCapture)
+      let matchResult = try XCTUnwrap(maybeMatchResult)
+      let (wholeMatch, lower, upper, propertyString) = matchResult.match.tuple
+      XCTAssertEqual(wholeMatch, Substring(line))
+      XCTAssertEqual(lower, Unicode.Scalar(0xA6F0))
+      XCTAssertEqual(upper, Unicode.Scalar(0xA6F1))
+      XCTAssertEqual(propertyString, "Extend")
+    }
+
     do {
       let regexLiteral = try MockRegexLiteral(
         #"([0-9A-F]+)(?:\.\.([0-9A-F]+))?\s+;\s+(\w+).*"#,
@@ -297,7 +324,7 @@ class RegexDSLTests: XCTestCase {
 
 extension Unicode.Scalar {
   // Convert a hexadecimal string to a scalar
-  public init?<S: StringProtocol>(hex: S) {
+  init?<S: StringProtocol>(hex: S) {
     guard let val = UInt32(hex, radix: 16), let scalar = Self(val) else {
       return nil
     }