#🔍 regexp.mbt

⚠️ API STABILITY NOTICE This is a alpha release with a stabilizing API. While core functionality is complete and well-tested, API changes may occur in future versions as we refine the implementation.

#⚡ Quick Start

///|
test {
  // Compile once, use everywhere
  let regexp = @regexp.compile("a(bc|de)f")
  guard! regexp.match_("xxabcf") is Some(result)
  debug_inspect(
    result.results(),
    content=(
      #|[Some(<StringView: "abcf">), Some(<StringView: "bc">)]
    ),
  )

  // Write a simple split with regexp
  fn split(regexp : @regexp.Regexp, target : StringView) -> Array[StringView] {
    let result = []
    for target = target {
      match target {
        "" => break
        str => {
          let res = regexp.execute(str)
          result.push(res.before())
          continue res.after()
        }
      }
    }
    result
  }

  let re = @regexp.compile("_+")
  debug_inspect(
    split(re, "1_2__3__4__5_____6"),
    content=(
      #|[
      #|  <StringView: "1">,
      #|  <StringView: "2">,
      #|  <StringView: "3">,
      #|  <StringView: "4">,
      #|  <StringView: "5">,
      #|  <StringView: "6">,
      #|]
    ),
  )
}

#🎯 Core API

#Build & Execute

• compile(pattern) → Creates an Engine
• engine.execute(text) → Returns MatchResult

#Inspect Results

• result.matched() → Bool
• result.get(index) → Capture group content
• result.results() → Iterator over all matches

#Named Groups & Advanced

• engine.group_by_name(name) → Find group index by name
• engine.group_count() → Total capture groups
• result.groups() → Get named group content

#🎪 Syntax Playground

#🌍 Unicode Property Support

///|
test "unicode properties" {
  // Matching gc=L
  let regex = @regexp.compile("\\p{Letter}+")
  debug_inspect(
    regex.execute("Hello 世界").results(),
    content=(
      #|[Some(<StringView: "Hello">)]
    ),
  )

  // Matching gc=N
  let regex = @regexp.compile("\\p{Number}+")
  debug_inspect(
    regex.execute("123 and 456").results(),
    content=(
      #|[Some(<StringView: "123">)]
    ),
  )
}

• General Category

#🔄 Backreferences

⚠️ Performance Warning: Backreferences can cause exponential time complexity in worst cases!

///|
test "backreferences" {
  // Palindrome detection (simple)
  let palindrome = @regexp.compile("^(.)(.)\\2\\1")
  debug_inspect(
    palindrome.execute("abba").results(),
    content=(
      #|[
      #|  Some(<StringView: "abba">),
      #|  Some(<StringView: "a">),
      #|  Some(<StringView: "b">),
      #|]
    ),
  )

  // HTML tag matching
  let html_regex = @regexp.compile("<([a-zA-Z]+)[^>]*>(.*?)</\\1>")
  let result = html_regex.execute("<div class='test'>content</div>")
  debug_inspect(
    result.results(),
    content=(
      #|[
      #|  Some(<StringView: "<div class='test'>content</div>">),
      #|  Some(<StringView: "div">),
      #|  Some(<StringView: "content">),
      #|]
    ),
  )
}

#💡 Real Examples

///|
test "character classes" {
  // Email validation (simplified)
  let email = @regexp.compile(
    (
      #|[\w-]+@[\w-]+\.\w+
    ),
  )
  let email_result = email.execute("user@example.com").results()
  debug_inspect(
    email_result,
    content=(
      #|[Some(<StringView: "user@example.com">)]
    ),
  )
  // Extract numbers
  let numbers = @regexp.compile(
    (
      #|\d+\.\d{2}
    ),
  )
  let result = numbers.execute("Price: $42.99").results()
  debug_inspect(
    result,
    content=(
      #|[Some(<StringView: "42.99">)]
    ),
  )

  // Named captures for parsing
  let parser = @regexp.compile(
    (
      #|(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})
    ),
  )
  let date_result = parser.execute("2024-03-15")
  debug_inspect(
    date_result.groups(),
    content=(
      #|{
      #|  "year": <StringView: "2024">,
      #|  "month": <StringView: "03">,
      #|  "day": <StringView: "15">,
      #|}
    ),
  )
}

#🚨 Error Handling

///|
test {
  try {
    let _ = @regexp.compile("a(b")
    // Oops! Missing )
  } catch {
    RegexpError(err=MissingParenthesis, source_fragment=_) =>
      println("Fix your regex! 🔧")
    _ => ()
  }
}

#⚡ Performance Characteristics

• Predictable complexity — Designed to avoid catastrophic backtracking (except with backreferences)
• VM-based — Structured interpreter design
• Unicode support — Character set and property support

#🔍 Implementation Notes

#Behavior Differences from Other Engines

1. Empty Character Class Handling:
   • In JavaScript: [][] is parsed as two character classes with no characters
   • In Golang: [][] is parsed as one character class containing ] and [
   • In MoonBit: we follow the JavaScript interpretation

2. Empty Alternatives Behavior:
   • Expressions like (|a)* and (|a)+ have specific behavior that may differ from other implementations
   • See Golang issue #46123 for related discussion

3. Backreferences:
   • Backreferences are supported but may impact the complexity guarantees of the engine