Parse Oniguruma callouts

Parse named and 'of-contents' Oniguruma callouts.
This requires generalizing the group name handling
to be for arbitrary identifiers, which may have a
specific kind for diagnostics.

Author: hamishknight

Sources/_MatchingEngine/Regex/AST/Atom.swift

@@ -476,14 +476,117 @@ extension AST.Atom {
 }
 
 extension AST.Atom {
-  public struct Callout: Hashable {
-    public enum Argument: Hashable {
-      case number(Int)
-      case string(String)
+  public enum Callout: Hashable {
+    /// A PCRE callout written `(?C...)`
+    public struct PCRE: Hashable {
+      public enum Argument: Hashable {
+        case number(Int)
+        case string(String)
+      }
+      public var arg: AST.Located<Argument>
+
+      public init(_ arg: AST.Located<Argument>) {
+        self.arg = arg
+      }
+
+      /// Whether the argument isn't written explicitly in the source, e.g
+      /// `(?C)` which is implicitly `(?C0)`.
+      public var isImplicit: Bool { arg.location.isEmpty }
     }
-    public var arg: AST.Located<Argument>
-    public init(_ arg: AST.Located<Argument>) {
-      self.arg = arg
+
+    /// A named Oniguruma callout written `(*name[tag]{args, ...})`
+    public struct OnigurumaNamed: Hashable {
+      public struct ArgList: Hashable {
+        public var leftBrace: SourceLocation
+        public var args: [AST.Located<String>]
+        public var rightBrace: SourceLocation
+
+        public init(
+          _ leftBrace: SourceLocation,
+          _ args: [AST.Located<String>],
+          _ rightBrace: SourceLocation
+        ) {
+          self.leftBrace = leftBrace
+          self.args = args
+          self.rightBrace = rightBrace
+        }
+      }
+
+      public var name: AST.Located<String>
+      public var tag: OnigurumaTag?
+      public var args: ArgList?
+
+      public init(
+        _ name: AST.Located<String>, tag: OnigurumaTag?, args: ArgList?
+      ) {
+        self.name = name
+        self.tag = tag
+        self.args = args
+      }
+    }
+
+    /// An Oniguruma callout 'of contents', written `(?{...}[tag]D)`
+    public struct OnigurumaOfContents: Hashable {
+      public enum Direction: Hashable {
+        case inProgress   // > (the default)
+        case inRetraction // <
+        case both         // X
+      }
+      public var openBraces: SourceLocation
+      public var contents: AST.Located<String>
+      public var closeBraces: SourceLocation
+      public var tag: OnigurumaTag?
+      public var direction: AST.Located<Direction>
+
+      public init(
+        _ openBraces: SourceLocation, _ contents: AST.Located<String>,
+        _ closeBraces: SourceLocation, tag: OnigurumaTag?,
+        direction: AST.Located<Direction>
+      ) {
+        self.openBraces = openBraces
+        self.contents = contents
+        self.closeBraces = closeBraces
+        self.tag = tag
+        self.direction = direction
+      }
+
+      /// Whether the direction flag isn't written explicitly in the
+      /// source, e.g `(?{x})` which is implicitly `(?{x}>)`.
+      public var isDirectionImplicit: Bool { direction.location.isEmpty }
+    }
+    case pcre(PCRE)
+    case onigurumaNamed(OnigurumaNamed)
+    case onigurumaOfContents(OnigurumaOfContents)
+
+    private var _associatedValue: Any {
+      switch self {
+      case .pcre(let v):                return v
+      case .onigurumaNamed(let v):      return v
+      case .onigurumaOfContents(let v): return v
+      }
+    }
+
+    func `as`<T>(_ t: T.Type = T.self) -> T? {
+      _associatedValue as? T
+    }
+  }
+}
+
+extension AST.Atom.Callout {
+  /// A tag specifier `[...]` which may appear in an Oniguruma callout.
+  public struct OnigurumaTag: Hashable {
+    public var leftBracket: SourceLocation
+    public var name: AST.Located<String>
+    public var rightBracket: SourceLocation
+
+    public init(
+      _ leftBracket: SourceLocation,
+      _ name: AST.Located<String>,
+      _ rightBracket: SourceLocation
+    ) {
+      self.leftBracket = leftBracket
+      self.name = name
+      self.rightBracket = rightBracket
     }
   }
 }

Sources/_MatchingEngine/Regex/Parse/Diagnostics.swift

@@ -56,11 +56,24 @@ enum ParseError: Error, Hashable {
 
   case expectedGroupSpecifier
   case unbalancedEndOfGroup
-  case expectedGroupName
-  case groupNameMustBeAlphaNumeric
-  case groupNameCannotStartWithNumber
+
+  // Identifier diagnostics.
+  case expectedIdentifier(IdentifierKind)
+  case identifierMustBeAlphaNumeric(IdentifierKind)
+  case identifierCannotStartWithNumber(IdentifierKind)
 
   case cannotRemoveTextSegmentOptions
+  case expectedCalloutArgument
+}
+
+extension IdentifierKind {
+  fileprivate var diagDescription: String {
+    switch self {
+    case .groupName:            return "group name"
+    case .onigurumaCalloutName: return "callout name"
+    case .onigurumaCalloutTag:  return "callout tag"
+    }
+  }
 }
 
 extension ParseError: CustomStringConvertible {
@@ -120,14 +133,16 @@ extension ParseError: CustomStringConvertible {
       return "expected group specifier"
     case .unbalancedEndOfGroup:
       return "closing ')' does not balance any groups openings"
-    case .expectedGroupName:
-      return "expected group name"
-    case .groupNameMustBeAlphaNumeric:
-      return "group name must only contain alphanumeric characters"
-    case .groupNameCannotStartWithNumber:
-      return "group name must not start with number"
+    case .expectedIdentifier(let i):
+      return "expected \(i.diagDescription)"
+    case .identifierMustBeAlphaNumeric(let i):
+      return "\(i.diagDescription) must only contain alphanumeric characters"
+    case .identifierCannotStartWithNumber(let i):
+      return "\(i.diagDescription) must not start with number"
     case .cannotRemoveTextSegmentOptions:
       return "text segment mode cannot be unset, only changed"
+    case .expectedCalloutArgument:
+      return "expected argument to callout"
     }
   }
 }