mruby-regexp: document what a pattern still decides in the String overrides - #7067

The overrides in mrbgems/mruby-regexp/mrblib/string_regexp.rb take care not to let an
argument lie about its type: Regexp === pattern reads the real class, and
Regexp.__check_pattern makes the accept-or-reject decision in C so that no Ruby-side
helper can be swapped out under it. Having established what the object is, every override
then calls a method on it, and those methods are ordinary Ruby-visible methods on
Regexp.

r = Regexp.new("l+")
def r.match(*a); "PWNED"; end

"hello".sub(r) { |m| m.upcase }  # CRuby: "heLLo", mruby: NoMethodError (pre_match)
"hello"[r]                       # CRuby: "ll",    mruby: "P"
s = "hello"; s[r] = "X"; s       # CRuby: "heXo",  mruby: NoMethodError (begin)
"hello".slice!(r)                # CRuby: "ll",    mruby: NoMethodError (begin)

sub's block form reaches the pattern through md.pre_match, where md is whatever
pattern.match(self) returned; the redefined match's "PWNED" string has no
pre_match, so mruby raises NoMethodError instead of substituting garbage. sub! with
a block goes the same way, through sub.

String#[] answers "P" rather than raising: it hands the result of args[0].match(self)
to MatchData#[], and for a String receiver that is String#[] again with an index of 0,
so the answer is the first character of the string the redefined match returned.
String#slice is a second entry for the same method. []= and slice! fetch the match
the same way and then ask it for begin, which a String does not have, so those raise.

gsub and split do not consult match for their result, so a redefined match leaves
them alone. They reach the pattern through __byte_match instead, which is redefinable in
exactly the same way, and redefining that one gives them a NoMethodError on
__byte_begin. gsub! calls pattern.match(self) only for its truthiness, so a
redefined match returning any true value leaves it working; scan hands the whole job
to pattern.__scan, and the replacement-string forms of sub and gsub to
pattern.__sub_str and pattern.__gsub_str.

The surface is every method the overrides call on a pattern or on the MatchData that
pattern handed back:

• on the pattern: match (from match, sub, sub!, gsub!, [], []= and slice!),
  match? (from match?), =~ (from =~), __byte_match (from gsub and split),
  __sub_str, __gsub_str and __scan.
• on the MatchData: [], pre_match, post_match, begin, end, size, length,
  __byte_begin, __byte_end and __set_globals.

All of them are defined with mrb_define_method(); the __ prefix is a naming
convention, not a protection.

CRuby is open in one of these places and deliberately so: rb_str_match_m() dispatches
match to the pattern on purpose, which is why "hello".match(r) answers "PWNED" there
as well. Everywhere else it is closed. rb_str_sub_bang(), rb_str_subpat(),
rb_str_subpat_set() and rb_str_slice_bang() call rb_reg_search() directly, and
rb_str_match_m_p() and rb_str_match() search a real Regexp without asking it anything,
so String#match? and String#=~ are closed there while the overrides here dispatch. A
Regexp created with Regexp.new is not frozen in either implementation, so this needs no
unusual setup.

Why a comment rather than a fix

It takes deliberate sabotage to observe. Redefining Regexp#match on an instance you then
pass to String#sub or String#[] is not something a program does by accident, and
nothing here is reachable from ordinary input: an argument that is not a Regexp never
reaches these calls, because the type test in front of them cannot be steered. That
distinction is the point, and the existing comments do not draw it. They claim only that
the argument cannot pose as a Regexp, which is true, but placed in front of a search they
read as though accepting the argument settled everything the pattern can influence.

The alternative is to give the overrides a C entry point that takes a pattern and a string
and searches, without going through any Ruby-visible method on the pattern. That is a
larger change than it sounds: sub, gsub, split, scan, [], []= and slice!
would each need one, and the block forms have to stay in mrblib because they call back
into Ruby. It also buys nothing against any input the gem actually receives.

So this PR writes the position down instead:

• a note at the top of the file listing what an accepted pattern still decides, where
  CRuby stands on each, and why the gem accepts it;
• one added sentence in String#[], so its type-test comment stops reading as a claim
  about the search that follows it.

CodeRabbit raised the String#[] half of this on #7054 as a review comment, asking that
the regexp branch call the built-in Regexp#match directly. That is the C entry point
option applied to one method; it was left alone there on the grounds that the rest of the
file has the same shape and the question belongs to the whole gem. This is the answer to
that question.

Testing

Comment-only, so behaviour is unchanged. rake test passes (2008 tests, 0 failures, 0
crashes). Every result above was reproduced on this branch and against CRuby 4.0.6.

Summary by CodeRabbit

• Documentation
  • Clarified how String regexp methods validate patterns and dispatch operations.
  • Documented how rewritten Regexp instance and singleton methods can influence results after type validation.
  • Expanded String#[] documentation to distinguish implementation selection from subsequent pattern behavior.
  • Added notes describing behavior differences compared with CRuby and clarifying how pattern and match-data operations are dispatched.