Merge pull request swiftlang#381 from hamishknight/5.7-merge-part-2

Author: hamishknight

.gitignore

@@ -1,5 +1,8 @@
 .DS_Store
 
+# The current toolchain is dumping files in the package root, rude
+*.emit-module.*
+
 # Xcode
 #
 # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore

Documentation/Evolution/ProposalOverview.md

@@ -3,6 +3,7 @@
 
 ## Regex Type and Overview
 
+- [Second review](https://forums.swift.org/t/se-0350-second-review-regex-type-and-overview/56886)
 - [Proposal](https://github.com/apple/swift-evolution/blob/main/proposals/0350-regex-type-overview.md), [Thread](https://forums.swift.org/t/se-0350-regex-type-and-overview/56530)
 - [Pitch thread](https://forums.swift.org/t/pitch-regex-type-and-overview/56029)
 

Sources/PatternConverter/PatternConverter.swift

@@ -30,9 +30,6 @@ struct PatternConverter: ParsableCommand {
   @Flag(help: "Whether to show canonical regex literal")
   var showCanonical: Bool = false
 
-  @Flag(help: "Whether to show capture structure")
-  var showCaptureStructure: Bool = false
-
   @Flag(help: "Whether to skip result builder DSL")
   var skipDSL: Bool = false
 
@@ -71,13 +68,6 @@ struct PatternConverter: ParsableCommand {
       print()
     }
 
-    if showCaptureStructure {
-      print("Capture structure:")
-      print()
-      print(ast.captureStructure)
-      print()
-    }
-
     print()
     if !skipDSL {
       let render = ast.renderAsBuilderDSL(

Sources/RegexBuilder/Anchor.swift

@@ -12,6 +12,12 @@
 @_implementationOnly import _RegexParser
 @_spi(RegexBuilder) import _StringProcessing
 
+/// A regex component that matches a specific condition at a particular position
+/// in an input string.
+///
+/// You can use anchors to guarantee that a match only occurs at certain points
+/// in an input string, such as at the beginning of the string or at the end of
+/// a line.
 @available(SwiftStdlib 5.7, *)
 public struct Anchor {
   internal enum Kind {
@@ -53,14 +59,24 @@ extension Anchor: RegexComponent {
 
 @available(SwiftStdlib 5.7, *)
 extension Anchor {
+  /// An anchor that matches at the start of the input string.
+  ///
+  /// This anchor is equivalent to `\A` in regex syntax.
   public static var startOfSubject: Anchor {
     Anchor(kind: .startOfSubject)
   }
-
+  
+  /// An anchor that matches at the end of the input string or at the end of
+  /// the line immediately before the the end of the string.
+  ///
+  /// This anchor is equivalent to `\Z` in regex syntax.
   public static var endOfSubjectBeforeNewline: Anchor {
     Anchor(kind: .endOfSubjectBeforeNewline)
   }
-
+  
+  /// An anchor that matches at the end of the input string.
+  ///
+  /// This anchor is equivalent to `\z` in regex syntax.
   public static var endOfSubject: Anchor {
     Anchor(kind: .endOfSubject)
   }
@@ -70,33 +86,67 @@ extension Anchor {
 //    Anchor(kind: resetStartOfMatch)
 //  }
 
+  /// An anchor that matches at the first position of a match in the input
+  /// string.
   public static var firstMatchingPositionInSubject: Anchor {
     Anchor(kind: .firstMatchingPositionInSubject)
   }
 
+  /// An anchor that matches at a grapheme cluster boundary.
+  ///
+  /// This anchor is equivalent to `\y` in regex syntax.
   public static var textSegmentBoundary: Anchor {
     Anchor(kind: .textSegmentBoundary)
   }
 
+  /// An anchor that matches at the start of a line, including the start of
+  /// the input string.
+  ///
+  /// This anchor is equivalent to `^` in regex syntax when the `m` option
+  /// has been enabled or `anchorsMatchLineEndings(true)` has been called.
   public static var startOfLine: Anchor {
     Anchor(kind: .startOfLine)
   }
 
+  /// An anchor that matches at the end of a line, including at the end of
+  /// the input string.
+  ///
+  /// This anchor is equivalent to `$` in regex syntax when the `m` option
+  /// has been enabled or `anchorsMatchLineEndings(true)` has been called.
   public static var endOfLine: Anchor {
     Anchor(kind: .endOfLine)
   }
 
+  /// An anchor that matches at a word boundary.
+  ///
+  /// Word boundaries are identified using the Unicode default word boundary
+  /// algorithm by default. To specify a different word boundary algorithm,
+  /// see the `RegexComponent.wordBoundaryKind(_:)` method.
+  ///
+  /// This anchor is equivalent to `\b` in regex syntax.
   public static var wordBoundary: Anchor {
     Anchor(kind: .wordBoundary)
   }
 
+  /// The inverse of this anchor, which matches at every position that this
+  /// anchor does not.
+  ///
+  /// For the `wordBoundary` and `textSegmentBoundary` anchors, the inverted
+  /// version corresponds to `\B` and `\Y`, respectively.
   public var inverted: Anchor {
     var result = self
     result.isInverted.toggle()
     return result
   }
 }
 
+/// A regex component that allows a match to continue only if its contents
+/// match at the given location.
+///
+/// A lookahead is a zero-length assertion that its included regex matches at
+/// a particular position. Lookaheads do not advance the overall matching
+/// position in the input string — once a lookahead succeeds, matching continues
+/// in the regex from the same position.
 @available(SwiftStdlib 5.7, *)
 public struct Lookahead<Output>: _BuiltinRegexComponent {
   public var regex: Regex<Output>
@@ -105,19 +155,48 @@ public struct Lookahead<Output>: _BuiltinRegexComponent {
     self.regex = regex
   }
 
+  /// Creates a lookahead from the given regex component.
   public init<R: RegexComponent>(
-    _ component: R,
-    negative: Bool = false
+    _ component: R
   ) where R.RegexOutput == Output {
-    self.init(node: .nonCapturingGroup(
-      negative ? .negativeLookahead : .lookahead, component.regex.root))
+    self.init(node: .nonCapturingGroup(.lookahead, component.regex.root))
   }
+  
+  /// Creates a lookahead from the regex generated by the given builder closure.
+  public init<R: RegexComponent>(
+    @RegexComponentBuilder _ component: () -> R
+  ) where R.RegexOutput == Output {
+    self.init(node: .nonCapturingGroup(.lookahead, component().regex.root))
+  }
+}
 
+/// A regex component that allows a match to continue only if its contents
+/// do not match at the given location.
+///
+/// A negative lookahead is a zero-length assertion that its included regex
+/// does not match at a particular position. Lookaheads do not advance the
+/// overall matching position in the input string — once a lookahead succeeds,
+/// matching continues in the regex from the same position.
+@available(SwiftStdlib 5.7, *)
+public struct NegativeLookahead<Output>: _BuiltinRegexComponent {
+  public var regex: Regex<Output>
+  
+  init(_ regex: Regex<Output>) {
+    self.regex = regex
+  }
+  
+  /// Creates a negative lookahead from the given regex component.
+  public init<R: RegexComponent>(
+    _ component: R
+  ) where R.RegexOutput == Output {
+    self.init(node: .nonCapturingGroup(.negativeLookahead, component.regex.root))
+  }
+  
+  /// Creates a negative lookahead from the regex generated by the given builder
+  /// closure.
   public init<R: RegexComponent>(
-    negative: Bool = false,
     @RegexComponentBuilder _ component: () -> R
   ) where R.RegexOutput == Output {
-    self.init(node: .nonCapturingGroup(
-      negative ? .negativeLookahead : .lookahead, component().regex.root))
+    self.init(node: .nonCapturingGroup(.negativeLookahead, component().regex.root))
   }
 }

Sources/_RegexParser/Regex/AST/AST.swift

@@ -25,12 +25,6 @@ public struct AST: Hashable {
 extension AST {
   /// Whether this AST tree contains at least one capture nested inside of it.
   public var hasCapture: Bool { root.hasCapture }
-
-  /// The capture structure of this AST tree.
-  public var captureStructure: CaptureStructure {
-    var constructor = CaptureStructure.Constructor(.flatten)
-    return root._captureStructure(&constructor)
-  }
 }
 
 extension AST {

Sources/_RegexParser/Regex/AST/MatchingOptions.swift

@@ -17,7 +17,7 @@ extension AST {
       case caseInsensitive          // i
       case allowDuplicateGroupNames // J
       case multiline                // m
-      case noAutoCapture            // n
+      case namedCapturesOnly        // n
       case singleLine               // s
       case reluctantByDefault       // U
       case extended                 // x

Sources/_RegexParser/Regex/Parse/CaptureList.swift

@@ -0,0 +1,154 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+public struct CaptureList {
+  public var captures: [Capture]
+
+  public init<S: Sequence>(_ s: S) where S.Element == Capture {
+    captures = Array(s)
+  }
+
+  public mutating func append(_ c: Capture) {
+    captures.append(c)
+  }
+}
+
+extension CaptureList {
+  public struct Capture {
+    public var name: String?
+    public var type: Any.Type?
+    public var optionalDepth: Int
+
+    public init(
+      name: String? = nil,
+      type: Any.Type? = nil,
+      optionalDepth: Int
+    ) {
+      self.name = name
+      self.type = type
+      self.optionalDepth = optionalDepth
+    }
+  }
+}
+
+// MARK: Generating from AST
+
+extension AST.Node {
+  public func _addCaptures(
+    to list: inout CaptureList,
+    optionalNesting nesting: Int
+  ) {
+    let addOptional = nesting+1
+    switch self {
+    case let .alternation(a):
+      for child in a.children {
+        child._addCaptures(to: &list, optionalNesting: addOptional)
+      }
+
+    case let .concatenation(c):
+      for child in c.children {
+        child._addCaptures(to: &list, optionalNesting: nesting)
+      }
+
+    case let .group(g):
+      switch g.kind.value {
+      case .capture:
+        list.append(.init(optionalDepth: nesting))
+
+      case .namedCapture(let name):
+        list.append(.init(name: name.value, optionalDepth: nesting))
+
+      case .balancedCapture(let b):
+        list.append(.init(name: b.name?.value, optionalDepth: nesting))
+
+      default: break
+      }
+      g.child._addCaptures(to: &list, optionalNesting: nesting)
+
+    case .conditional(let c):
+      switch c.condition.kind {
+      case .group(let g):
+        AST.Node.group(g)._addCaptures(to: &list, optionalNesting: nesting)
+      default:
+        break
+      }
+
+      c.trueBranch._addCaptures(to: &list, optionalNesting: addOptional)
+      c.falseBranch._addCaptures(to: &list, optionalNesting: addOptional)
+
+    case .quantification(let q):
+      var optNesting = nesting
+      if q.amount.value.bounds.atLeast == 0 {
+        optNesting += 1
+      }
+      q.child._addCaptures(to: &list, optionalNesting: optNesting)
+
+    case .absentFunction(let abs):
+      switch abs.kind {
+      case .expression(_, _, let child):
+        child._addCaptures(to: &list, optionalNesting: nesting)
+      case .clearer, .repeater, .stopper:
+        break
+      }
+
+    case .quote, .trivia, .atom, .customCharacterClass, .empty:
+      break
+    }
+  }
+
+  public var _captureList: CaptureList {
+    var caps = CaptureList()
+    self._addCaptures(to: &caps, optionalNesting: 0)
+    return caps
+  }
+}
+
+extension AST {
+  /// Get the capture list for this AST
+  public var captureList: CaptureList {
+    root._captureList
+  }
+}
+
+// MARK: Convenience for testing and inspection
+
+extension CaptureList.Capture: Equatable {
+  public static func == (lhs: Self, rhs: Self) -> Bool {
+    lhs.name == rhs.name &&
+    lhs.optionalDepth == rhs.optionalDepth &&
+    lhs.type == rhs.type
+  }
+}
+extension CaptureList: Equatable {}
+
+extension CaptureList.Capture: CustomStringConvertible {
+  public var description: String {
+    let typeStr: String
+    if let ty = type {
+      typeStr = "\(ty)"
+    } else {
+      typeStr = "Substring"
+    }
+    let suffix = String(repeating: "?", count: optionalDepth)
+    return typeStr + suffix
+  }
+}
+extension CaptureList: CustomStringConvertible {
+  public var description: String {
+    "(" + captures.map(\.description).joined(separator: ", ") + ")"
+  }
+}
+
+extension CaptureList: ExpressibleByArrayLiteral {
+  public init(arrayLiteral elements: Capture...) {
+    self.init(elements)
+  }
+}