Option APIs for RegexProtocol (#171)

This adds an API to any conforming type that lets the user control
whether a match uses case sensitive comparison from within a DSL
declaration. Adding successive modifiers is equivalent to nesting
an expression in a new Regex declaration.

For example, these two regex declarations are equivalent:

```
let regexDSL = Regex {
    oneOrMore {
        "a"
    }
    .caseSensitive(false)
    .caseSensitive(true)
}

let regexNested = Regex {
    Regex {
        oneOrMore {
            "a"
        }.caseSensitive(false)
    }.caseSensitive(true)
}
```

Author: natecook1000

Sources/_MatchingEngine/Regex/AST/MatchingOptions.swift

@@ -110,6 +110,16 @@ extension AST {
   }
 }
 
+extension AST.MatchingOptionSequence {
+  public init(adding: [AST.MatchingOption]) {
+    self.init(caretLoc: nil, adding: adding, minusLoc: nil, removing: [])
+  }
+
+  public init(removing: [AST.MatchingOption]) {
+    self.init(caretLoc: nil, adding: [], minusLoc: nil, removing: removing)
+  }
+}
+
 extension AST.MatchingOption: _ASTPrintable {
   public var _dumpBase: String { "\(kind)" }
 }

Sources/_StringProcessing/MatchingOptions.swift

@@ -189,6 +189,19 @@ extension MatchingOptions {
       contains(.init(kind))
     }
 
+    mutating func add(_ opt: Option) {
+      // If opt is in one of the mutually exclusive groups, clear out the
+      // group before inserting.
+      if Self.semanticMatchingLevels.contains(opt.representation) {
+        remove(.semanticMatchingLevels)
+      }
+      if Self.textSegmentOptions.contains(opt.representation) {
+        remove(.textSegmentOptions)
+      }
+
+      insert(opt.representation)
+    }
+    
     /// Applies the changes described by `sequence` to this set of options.
     mutating func apply(_ sequence: AST.MatchingOptionSequence) {
       // Replace entirely if the sequence includes a caret, e.g. `(?^is)`.
@@ -197,28 +210,17 @@ extension MatchingOptions {
       }
 
       for opt in sequence.adding {
-        guard let opt = Option(opt.kind)?.representation else {
+        guard let opt = Option(opt.kind) else {
           continue
         }
-        
-        // If opt is in one of the mutually exclusive groups, clear out the
-        // group before inserting.
-        if Self.semanticMatchingLevels.contains(opt) {
-          remove(.semanticMatchingLevels)
-        }
-        if Self.textSegmentOptions.contains(opt) {
-          remove(.textSegmentOptions)
-        }
-
-        insert(opt)
+        add(opt)
       }
 
       for opt in sequence.removing {
-        guard let opt = Option(opt.kind)?.representation else {
+        guard let opt = Option(opt.kind) else {
           continue
         }
-
-        remove(opt)
+        remove(opt.representation)
       }
     }
   }
@@ -229,6 +231,9 @@ extension MatchingOptions.Representation {
     self.rawValue = 1 << kind.rawValue
   }
 
+  // Case insensitivity
+  static var caseInsensitive: Self { .init(.caseInsensitive) }
+  
   // Text segmentation options
   static var textSegmentGraphemeMode: Self { .init(.textSegmentGraphemeMode) }
   static var textSegmentWordMode: Self { .init(.textSegmentWordMode) }

Sources/_StringProcessing/RegexDSL/Options.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 _MatchingEngine
+
+extension RegexProtocol {
+  public func caseSensitive(_ isCaseSensitive: Bool) -> Regex<Match> {
+    // The API is "case sensitive = true or false", so as to avoid the
+    // double negatives inherent in setting "case insensitive" to a Boolean
+    // value. The internal version of this option, on the other hand, is
+    // `.caseInsensitive`, derived from the `(?i)` regex literal option.
+    let sequence = isCaseSensitive
+      ? AST.MatchingOptionSequence(removing: [.init(.caseInsensitive, location: .fake)])
+      : AST.MatchingOptionSequence(adding: [.init(.caseInsensitive, location: .fake)])
+    return Regex(node: .group(.changeMatchingOptions(sequence, isIsolated: false), regex.root))
+  }
+}
+

Tests/RegexTests/RegexDSLTests.swift

@@ -152,6 +152,51 @@ class RegexDSLTests: XCTestCase {
     }
   }
 
+  func testOptions() throws {
+    try _testDSLCaptures(
+      ("abc", "abc"),
+      ("ABC", "ABC"),
+      ("abcabc", "abcabc"),
+      ("abcABCaBc", "abcABCaBc"),
+      captureType: Substring.self, ==) {
+        oneOrMore {
+          "abc"
+        }.caseSensitive(false)
+      }
+    
+    // Multiple options on one component wrap successively, but do not
+    // override - equivalent to each option attached to a wrapping `Regex`.
+    try _testDSLCaptures(
+      ("abc", "abc"),
+      ("ABC", "ABC"),
+      ("abcabc", "abcabc"),
+      ("abcABCaBc", "abcABCaBc"),
+      captureType: Substring.self, ==) {
+        oneOrMore {
+          "abc"
+        }
+        .caseSensitive(false)
+        .caseSensitive(true)
+      }
+
+    // An option on an outer component doesn't override an option set on an
+    // inner component.
+    try _testDSLCaptures(
+      ("abc", "abc"),
+      ("ABC", "ABC"),
+      ("ABCde", "ABCde"),
+      ("ABCDE", nil),
+      ("abcabc", "abcabc"),
+      ("abcdeABCdeaBcde", "abcdeABCdeaBcde"),
+      captureType: Substring.self, ==) {
+        oneOrMore {
+          "abc".caseSensitive(false)
+          optionally("de")
+        }
+        .caseSensitive(true)
+      }
+  }
+  
   func testQuantificationBehavior() throws {
     try _testDSLCaptures(
       ("abc1def2", ("abc1def2", "2")),
@@ -525,13 +570,6 @@ extension Unicode.Scalar {
 
 // MARK: Extra == functions
 
-// (Substring, [(Substring, Substring, [Substring])])
-typealias S_AS = (Substring, [(Substring, Substring, [Substring])])
-
-func ==(lhs: S_AS, rhs: S_AS) -> Bool {
-  lhs.0 == rhs.0 && lhs.1.elementsEqual(rhs.1, by: ==)
-}
-
 func == <T0: Equatable, T1: Equatable, T2: Equatable, T3: Equatable, T4: Equatable, T5: Equatable, T6: Equatable>(
   l: (T0, T1, T2, T3, T4, T5, T6), r: (T0, T1, T2, T3, T4, T5, T6)
 ) -> Bool {