mruby-regexp: stop capturing plain groups once a pattern has a named group - #7057

In CRuby, a single named group turns every plain (...) in the same pattern into a
non-capturing group and makes a numbered backreference a compile error. mruby-regexp
captures both kinds side by side, so a pattern that mixes them has a different number of
groups in the two implementations, and every numbered accessor disagrees.

md = /(?<a>a)(b)/.match("ab")
md.size          # CRuby: 2,            mruby: 3
md.to_a          # CRuby: ["ab", "a"],  mruby: ["ab", "a", "b"]
md.captures      # CRuby: ["a"],        mruby: ["a", "b"]
md[2]            # CRuby: nil,          mruby: "b"
md.begin(2)      # CRuby: IndexError (index 2 out of matches),  mruby: 1

"ab" =~ /(?<a>a)(b)/
$2               # CRuby: nil,  mruby: "b"
$+               # CRuby: "a",  mruby: "b"

"ab".sub(/(?<a>a)(b)/, '[\2]')   # CRuby: "[]",  mruby: "[b]"

Regexp.new("(a)(?<b>b)\\1")
# CRuby: RegexpError (numbered backref/call is not allowed. (use name))
# mruby: compiles, and \1 refers to (a)

Named access agrees in every case already: md[:a], md["a"], Regexp#named_captures,
Regexp#names and MatchData#names all report the same thing. Only the numbered side
differs.

The rule is Onigmo's ONIG_OPTION_DONT_CAPTURE_GROUP, which CRuby enables for a pattern
that declares at least one named group. It is not a corner case: (...) used purely for
grouping or alternation is common, and code carried over from CRuby silently sees its
capture numbers shift by however many plain groups the pattern has.

What this changes

Whether a plain group captures depends on a named group that may appear later in the
pattern, so mrb_re_compile() pre-scans for (?< before it starts allocating group
numbers. The scan reads the same bytes the parser will read, after the /x strip, so
free-spacing and comments are already gone. Three details it has to get right, each
checked against the parser and pinned by a test:

• It skips escape pairs and character-class bodies, so /\(?/ and /[(?<]/ are not false
  positives. That skipping is shared with strip_extended() for the [:name:] case,
  which the first commit lifts into skip_posix_bracket().
• It excludes (?<= and (?<!, which open a lookbehind rather than define a group.
  \k<name> is a reference, not a definition. (?'name'...) is not a spelling this gem
  accepts at all, so (?< is the only form to look for.
• A truncated (?< still raises from the parser, as Regexp.new("(?<") asserts. The
  pre-scan counts those bytes as a named group, which is harmless, but it is not the
  thing that decides the error.

compile_atom() then demotes a plain group to non-capturing, and rejects a numbered
backreference in both its \1 and its \k<1> / \k<-1> spellings. The \k branch
matters as much as the \1 one: once plain groups stop consuming numbers, its absolute
bound and its relative num_captures - n would resolve to a different group instead of
erroring.

The only representation that changes is pat->num_captures, which shrinks for an
affected pattern. Every numbered accessor already derives from it, so regexp.c and
re_exec.c need no edit, and that is what makes the $2, $+, sub and md.begin(2)
rows above agree, down to the IndexError message.

The gem README gains a Named Captures section stating the rule, and the
\k<name> row its Pattern Syntax list was missing.

Alternative considered

Documenting the difference instead. mruby's behaviour was a superset: every pattern CRuby
accepts still matched the same text, and the only patterns that behaved differently were
the ones CRuby refuses to compile or whose numbered groups it discards. Keeping it costs
nothing at compile time. There is a precedent for pinning a deliberate gap as a test
rather than closing it (599856d, for the to_str pattern of String#match). What
argues the other way here is that this difference is silent and changes results rather
than raising, so I went with following CRuby. Happy to turn it into a documented
difference instead if you prefer.

Out of scope

Two adjacent gaps on the same patterns are left alone, since neither follows from the
capture-numbering rule:

• CRuby also blanks a numbered \1 in a replacement string when the pattern has named
  captures, even though md[1] still answers. After this change "ab".sub(/(?<a>a)b/, '[\1]')
  is "[a]" here against "[]" in CRuby.
• \k<name> in a replacement string is not supported by this gem; it stays literal.

Testing

rake test passes. No existing test mixed a named group with a plain capturing group, so
nothing in the suite had to change. New coverage in mrbgems/mruby-regexp/test/regexp.rb
takes the table above row by row, plus the lookbehind, escaped, character-class,
[:alpha:], /x and truncated (?< cases, and the three rejected backreference
spellings with their messages.

Summary by CodeRabbit

• Bug Fixes

  • Improved regular expression handling for patterns containing named groups.
  • Unnamed groups are now treated as non-capturing when named groups are present.
  • Numeric backreferences are correctly rejected in these patterns.
  • Improved safety when parsing incomplete POSIX character classes in extended mode.

• Documentation

  • Added guidance and examples for named captures and named backreferences, including numbering rules and error behavior.

• Tests

  • Added regression coverage for named-group semantics, backreferences, capture behavior, and truncated syntax.