pod/perlreapi.pod

   1 =head1 NAME
   2
   3 perlreapi - Perl regular expression plugin interface
   4
   5 =head1 DESCRIPTION
   6
   7 As of Perl 5.9.5 there is a new interface for plugging and using
   8 regular expression engines other than the default one.
   9
  10 Each engine is supposed to provide access to a constant structure of the
  11 following format:
  12
  13     typedef struct regexp_engine {
  14         REGEXP* (*comp) (pTHX_
  15                          const SV * const pattern, const U32 flags);
  16         I32     (*exec) (pTHX_
  17                          REGEXP * const rx,
  18                          char* stringarg,
  19                          char* strend, char* strbeg,
  20                          I32 minend, SV* screamer,
  21                          void* data, U32 flags);
  22         char*   (*intuit) (pTHX_
  23                            REGEXP * const rx, SV *sv,
  24                            char *strpos, char *strend, U32 flags,
  25                            struct re_scream_pos_data_s *data);
  26         SV*     (*checkstr) (pTHX_ REGEXP * const rx);
  27         void    (*free) (pTHX_ REGEXP * const rx);
  28         void    (*numbered_buff_FETCH) (pTHX_
  29                                         REGEXP * const rx,
  30                                         const I32 paren,
  31                                         SV * const sv);
  32         void    (*numbered_buff_STORE) (pTHX_
  33                                         REGEXP * const rx,
  34                                         const I32 paren,
  35                                         SV const * const value);
  36         I32     (*numbered_buff_LENGTH) (pTHX_
  37                                          REGEXP * const rx,
  38                                          const SV * const sv,
  39                                          const I32 paren);
  40         SV*     (*named_buff) (pTHX_
  41                                REGEXP * const rx,
  42                                SV * const key,
  43                                SV * const value,
  44                                U32 flags);
  45         SV*     (*named_buff_iter) (pTHX_
  46                                     REGEXP * const rx,
  47                                     const SV * const lastkey,
  48                                     const U32 flags);
  49         SV*     (*qr_package)(pTHX_ REGEXP * const rx);
  50     #ifdef USE_ITHREADS
  51         void*   (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
  52     #endif
  53         REGEXP* (*op_comp) (...);
  54
  55
  56 When a regexp is compiled, its C<engine> field is then set to point at
  57 the appropriate structure, so that when it needs to be used Perl can find
  58 the right routines to do so.
  59
  60 In order to install a new regexp handler, C<$^H{regcomp}> is set
  61 to an integer which (when casted appropriately) resolves to one of these
  62 structures. When compiling, the C<comp> method is executed, and the
  63 resulting C<regexp> structure's engine field is expected to point back at
  64 the same structure.
  65
  66 The pTHX_ symbol in the definition is a macro used by Perl under threading
  67 to provide an extra argument to the routine holding a pointer back to
  68 the interpreter that is executing the regexp. So under threading all
  69 routines get an extra argument.
  70
  71 =head1 Callbacks
  72
  73 =head2 comp
  74
  75     REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);
  76
  77 Compile the pattern stored in C<pattern> using the given C<flags> and
  78 return a pointer to a prepared C<REGEXP> structure that can perform
  79 the match. See L</The REGEXP structure> below for an explanation of
  80 the individual fields in the REGEXP struct.
  81
  82 The C<pattern> parameter is the scalar that was used as the
  83 pattern.  Previous versions of Perl would pass two C<char*> indicating
  84 the start and end of the stringified pattern; the following snippet can
  85 be used to get the old parameters:
  86
  87     STRLEN plen;
  88     char*  exp = SvPV(pattern, plen);
  89     char* xend = exp + plen;
  90
  91 Since any scalar can be passed as a pattern, it's possible to implement
  92 an engine that does something with an array (C<< "ook" =~ [ qw/ eek
  93 hlagh / ] >>) or with the non-stringified form of a compiled regular
  94 expression (C<< "ook" =~ qr/eek/ >>).  Perl's own engine will always
  95 stringify everything using the snippet above, but that doesn't mean
  96 other engines have to.
  97
  98 The C<flags> parameter is a bitfield which indicates which of the
  99 C<msixp> flags the regex was compiled with. It also contains
 100 additional info, such as if C<use locale> is in effect.
 101
 102 The C<eogc> flags are stripped out before being passed to the comp
 103 routine. The regex engine does not need to know if any of these
 104 are set, as those flags should only affect what Perl does with the
 105 pattern and its match variables, not how it gets compiled and
 106 executed.
 107
 108 By the time the comp callback is called, some of these flags have
 109 already had effect (noted below where applicable). However most of
 110 their effect occurs after the comp callback has run, in routines that
 111 read the C<< rx->extflags >> field which it populates.
 112
 113 In general the flags should be preserved in C<< rx->extflags >> after
 114 compilation, although the regex engine might want to add or delete
 115 some of them to invoke or disable some special behavior in Perl. The
 116 flags along with any special behavior they cause are documented below:
 117
 118 The pattern modifiers:
 119
 120 =over 4
 121
 122 =item C</m> - RXf_PMf_MULTILINE
 123
 124 If this is in C<< rx->extflags >> it will be passed to
 125 C<Perl_fbm_instr> by C<pp_split> which will treat the subject string
 126 as a multi-line string.
 127
 128 =item C</s> - RXf_PMf_SINGLELINE
 129
 130 =item C</i> - RXf_PMf_FOLD
 131
 132 =item C</x> - RXf_PMf_EXTENDED
 133
 134 If present on a regex, C<"#"> comments will be handled differently by the
 135 tokenizer in some cases.
 136
 137 TODO: Document those cases.
 138
 139 =item C</p> - RXf_PMf_KEEPCOPY
 140
 141 TODO: Document this
 142
 143 =item Character set
 144
 145 The character set semantics are determined by an enum that is contained
 146 in this field.  This is still experimental and subject to change, but
 147 the current interface returns the rules by use of the in-line function
 148 C<get_regex_charset(const U32 flags)>.  The only currently documented
 149 value returned from it is REGEX_LOCALE_CHARSET, which is set if
 150 C<use locale> is in effect. If present in C<< rx->extflags >>,
 151 C<split> will use the locale dependent definition of whitespace
 152 when RXf_SKIPWHITE or RXf_WHITE is in effect. ASCII whitespace
 153 is defined as per L<isSPACE|perlapi/isSPACE>, and by the internal
 154 macros C<is_utf8_space> under UTF-8, and C<isSPACE_LC> under C<use
 155 locale>.
 156
 157 =back
 158
 159 Additional flags:
 160
 161 =over 4
 162
 163 =item RXf_SPLIT
 164
 165 If C<split> is invoked as C<split ' '> or with no arguments (which
 166 really means C<split(' ', $_)>, see L<split|perlfunc/split>), Perl will
 167 set this flag. The regex engine can then check for it and set the
 168 SKIPWHITE and WHITE extflags. To do this, the Perl engine does:
 169
 170     if (flags & RXf_SPLIT && r->prelen == 1 && r->precomp[0] == ' ')
 171         r->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
 172
 173 =back
 174
 175 These flags can be set during compilation to enable optimizations in
 176 the C<split> operator.
 177
 178 =over 4
 179
 180 =item RXf_SKIPWHITE
 181
 182 If the flag is present in C<< rx->extflags >> C<split> will delete
 183 whitespace from the start of the subject string before it's operated
 184 on. What is considered whitespace depends on if the subject is a
 185 UTF-8 string and if the C<RXf_PMf_LOCALE> flag is set.
 186
 187 If RXf_WHITE is set in addition to this flag, C<split> will behave like
 188 C<split " "> under the Perl engine.
 189
 190 =item RXf_START_ONLY
 191
 192 Tells the split operator to split the target string on newlines
 193 (C<\n>) without invoking the regex engine.
 194
 195 Perl's engine sets this if the pattern is C</^/> (C<plen == 1 && *exp
 196 == '^'>), even under C</^/s>; see L<split|perlfunc>. Of course a
 197 different regex engine might want to use the same optimizations
 198 with a different syntax.
 199
 200 =item RXf_WHITE
 201
 202 Tells the split operator to split the target string on whitespace
 203 without invoking the regex engine. The definition of whitespace varies
 204 depending on if the target string is a UTF-8 string and on
 205 if RXf_PMf_LOCALE is set.
 206
 207 Perl's engine sets this flag if the pattern is C<\s+>.
 208
 209 =item RXf_NULL
 210
 211 Tells the split operator to split the target string on
 212 characters. The definition of character varies depending on if
 213 the target string is a UTF-8 string.
 214
 215 Perl's engine sets this flag on empty patterns, this optimization
 216 makes C<split //> much faster than it would otherwise be. It's even
 217 faster than C<unpack>.
 218
 219 =back
 220
 221 =head2 exec
 222
 223     I32 exec(pTHX_ REGEXP * const rx,
 224              char *stringarg, char* strend, char* strbeg,
 225              I32 minend, SV* screamer,
 226              void* data, U32 flags);
 227
 228 Execute a regexp. The arguments are
 229
 230 =over 4
 231
 232 =item rx
 233
 234 The regular expression to execute.
 235
 236 =item screamer
 237
 238 This strangely-named arg is the SV to be matched against. Note that the
 239 actual char array to be matched against is supplied by the arguments
 240 described below; the SV is just used to determine UTF8ness, C<pos()> etc.
 241
 242 =item strbeg
 243
 244 Pointer to the physical start of the string.
 245
 246 =item strend
 247
 248 Pointer to the character following the physical end of the string (i.e.
 249 the C<\0>).
 250
 251 =item stringarg
 252
 253 Pointer to the position in the string where matching should start; it might
 254 not be equal to C<strbeg> (for example in a later iteration of C</.../g>).
 255
 256 =item minend
 257
 258 Minimum length of string (measured in bytes from C<stringarg>) that must
 259 match; if the engine reaches the end of the match but hasn't reached this
 260 position in the string, it should fail.
 261
 262 =item data
 263
 264 Optimisation data; subject to change.
 265
 266 =item flags
 267
 268 Optimisation flags; subject to change.
 269
 270 =back
 271
 272 =head2 intuit
 273
 274     char* intuit(pTHX_ REGEXP * const rx,
 275                   SV *sv, char *strpos, char *strend,
 276                   const U32 flags, struct re_scream_pos_data_s *data);
 277
 278 Find the start position where a regex match should be attempted,
 279 or possibly if the regex engine should not be run because the
 280 pattern can't match. This is called, as appropriate, by the core,
 281 depending on the values of the C<extflags> member of the C<regexp>
 282 structure.
 283
 284 =head2 checkstr
 285
 286     SV* checkstr(pTHX_ REGEXP * const rx);
 287
 288 Return a SV containing a string that must appear in the pattern. Used
 289 by C<split> for optimising matches.
 290
 291 =head2 free
 292
 293     void free(pTHX_ REGEXP * const rx);
 294
 295 Called by Perl when it is freeing a regexp pattern so that the engine
 296 can release any resources pointed to by the C<pprivate> member of the
 297 C<regexp> structure. This is only responsible for freeing private data;
 298 Perl will handle releasing anything else contained in the C<regexp> structure.
 299
 300 =head2 Numbered capture callbacks
 301
 302 Called to get/set the value of C<$`>, C<$'>, C<$&> and their named
 303 equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
 304 numbered capture groups (C<$1>, C<$2>, ...).
 305
 306 The C<paren> parameter will be C<1> for C<$1>, C<2> for C<$2> and so
 307 forth, and have these symbolic values for the special variables:
 308
 309     ${^PREMATCH}  RX_BUFF_IDX_CARET_PREMATCH
 310     ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
 311     ${^MATCH}     RX_BUFF_IDX_CARET_FULLMATCH
 312     $`            RX_BUFF_IDX_PREMATCH
 313     $'            RX_BUFF_IDX_POSTMATCH
 314     $&            RX_BUFF_IDX_FULLMATCH
 315
 316 Note that in Perl 5.17.3 and earlier, the last three constants were also
 317 used for the caret variants of the variables.
 318
 319
 320 The names have been chosen by analogy with L<Tie::Scalar> methods
 321 names with an additional B<LENGTH> callback for efficiency. However
 322 named capture variables are currently not tied internally but
 323 implemented via magic.
 324
 325 =head3 numbered_buff_FETCH
 326
 327     void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
 328                              SV * const sv);
 329
 330 Fetch a specified numbered capture. C<sv> should be set to the scalar
 331 to return, the scalar is passed as an argument rather than being
 332 returned from the function because when it's called Perl already has a
 333 scalar to store the value, creating another one would be
 334 redundant. The scalar can be set with C<sv_setsv>, C<sv_setpvn> and
 335 friends, see L<perlapi>.
 336
 337 This callback is where Perl untaints its own capture variables under
 338 taint mode (see L<perlsec>). See the C<Perl_reg_numbered_buff_fetch>
 339 function in F<regcomp.c> for how to untaint capture variables if
 340 that's something you'd like your engine to do as well.
 341
 342 =head3 numbered_buff_STORE
 343
 344     void    (*numbered_buff_STORE) (pTHX_
 345                                     REGEXP * const rx,
 346                                     const I32 paren,
 347                                     SV const * const value);
 348
 349 Set the value of a numbered capture variable. C<value> is the scalar
 350 that is to be used as the new value. It's up to the engine to make
 351 sure this is used as the new value (or reject it).
 352
 353 Example:
 354
 355     if ("ook" =~ /(o*)/) {
 356         # 'paren' will be '1' and 'value' will be 'ee'
 357         $1 =~ tr/o/e/;
 358     }
 359
 360 Perl's own engine will croak on any attempt to modify the capture
 361 variables, to do this in another engine use the following callback
 362 (copied from C<Perl_reg_numbered_buff_store>):
 363
 364     void
 365     Example_reg_numbered_buff_store(pTHX_
 366                                     REGEXP * const rx,
 367                                     const I32 paren,
 368                                     SV const * const value)
 369     {
 370         PERL_UNUSED_ARG(rx);
 371         PERL_UNUSED_ARG(paren);
 372         PERL_UNUSED_ARG(value);
 373
 374         if (!PL_localizing)
 375             Perl_croak(aTHX_ PL_no_modify);
 376     }
 377
 378 Actually Perl will not I<always> croak in a statement that looks
 379 like it would modify a numbered capture variable. This is because the
 380 STORE callback will not be called if Perl can determine that it
 381 doesn't have to modify the value. This is exactly how tied variables
 382 behave in the same situation:
 383
 384     package CaptureVar;
 385     use base 'Tie::Scalar';
 386
 387     sub TIESCALAR { bless [] }
 388     sub FETCH { undef }
 389     sub STORE { die "This doesn't get called" }
 390
 391     package main;
 392
 393     tie my $sv => "CaptureVar";
 394     $sv =~ y/a/b/;
 395
 396 Because C<$sv> is C<undef> when the C<y///> operator is applied to it,
 397 the transliteration won't actually execute and the program won't
 398 C<die>. This is different to how 5.8 and earlier versions behaved
 399 since the capture variables were READONLY variables then; now they'll
 400 just die when assigned to in the default engine.
 401
 402 =head3 numbered_buff_LENGTH
 403
 404     I32 numbered_buff_LENGTH (pTHX_
 405                               REGEXP * const rx,
 406                               const SV * const sv,
 407                               const I32 paren);
 408
 409 Get the C<length> of a capture variable. There's a special callback
 410 for this so that Perl doesn't have to do a FETCH and run C<length> on
 411 the result, since the length is (in Perl's case) known from an offset
 412 stored in C<< rx->offs >>, this is much more efficient:
 413
 414     I32 s1  = rx->offs[paren].start;
 415     I32 s2  = rx->offs[paren].end;
 416     I32 len = t1 - s1;
 417
 418 This is a little bit more complex in the case of UTF-8, see what
 419 C<Perl_reg_numbered_buff_length> does with
 420 L<is_utf8_string_loclen|perlapi/is_utf8_string_loclen>.
 421
 422 =head2 Named capture callbacks
 423
 424 Called to get/set the value of C<%+> and C<%->, as well as by some
 425 utility functions in L<re>.
 426
 427 There are two callbacks, C<named_buff> is called in all the cases the
 428 FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR L<Tie::Hash> callbacks
 429 would be on changes to C<%+> and C<%-> and C<named_buff_iter> in the
 430 same cases as FIRSTKEY and NEXTKEY.
 431
 432 The C<flags> parameter can be used to determine which of these
 433 operations the callbacks should respond to.  The following flags are
 434 currently defined:
 435
 436 Which L<Tie::Hash> operation is being performed from the Perl level on
 437 C<%+> or C<%+>, if any:
 438
 439     RXapif_FETCH
 440     RXapif_STORE
 441     RXapif_DELETE
 442     RXapif_CLEAR
 443     RXapif_EXISTS
 444     RXapif_SCALAR
 445     RXapif_FIRSTKEY
 446     RXapif_NEXTKEY
 447
 448 If C<%+> or C<%-> is being operated on, if any.
 449
 450     RXapif_ONE /* %+ */
 451     RXapif_ALL /* %- */
 452
 453 If this is being called as C<re::regname>, C<re::regnames> or
 454 C<re::regnames_count>, if any. The first two will be combined with
 455 C<RXapif_ONE> or C<RXapif_ALL>.
 456
 457     RXapif_REGNAME
 458     RXapif_REGNAMES
 459     RXapif_REGNAMES_COUNT
 460
 461 Internally C<%+> and C<%-> are implemented with a real tied interface
 462 via L<Tie::Hash::NamedCapture>. The methods in that package will call
 463 back into these functions. However the usage of
 464 L<Tie::Hash::NamedCapture> for this purpose might change in future
 465 releases. For instance this might be implemented by magic instead
 466 (would need an extension to mgvtbl).
 467
 468 =head3 named_buff
 469
 470     SV*     (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
 471                            SV * const value, U32 flags);
 472
 473 =head3 named_buff_iter
 474
 475     SV*     (*named_buff_iter) (pTHX_
 476                                 REGEXP * const rx,
 477                                 const SV * const lastkey,
 478                                 const U32 flags);
 479
 480 =head2 qr_package
 481
 482     SV* qr_package(pTHX_ REGEXP * const rx);
 483
 484 The package the qr// magic object is blessed into (as seen by C<ref
 485 qr//>). It is recommended that engines change this to their package
 486 name for identification regardless of if they implement methods
 487 on the object.
 488
 489 The package this method returns should also have the internal
 490 C<Regexp> package in its C<@ISA>. C<< qr//->isa("Regexp") >> should always
 491 be true regardless of what engine is being used.
 492
 493 Example implementation might be:
 494
 495     SV*
 496     Example_qr_package(pTHX_ REGEXP * const rx)
 497     {
 498         PERL_UNUSED_ARG(rx);
 499         return newSVpvs("re::engine::Example");
 500     }
 501
 502 Any method calls on an object created with C<qr//> will be dispatched to the
 503 package as a normal object.
 504
 505     use re::engine::Example;
 506     my $re = qr//;
 507     $re->meth; # dispatched to re::engine::Example::meth()
 508
 509 To retrieve the C<REGEXP> object from the scalar in an XS function use
 510 the C<SvRX> macro, see L<"REGEXP Functions" in perlapi|perlapi/REGEXP
 511 Functions>.
 512
 513     void meth(SV * rv)
 514     PPCODE:
 515         REGEXP * re = SvRX(sv);
 516
 517 =head2 dupe
 518
 519     void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
 520
 521 On threaded builds a regexp may need to be duplicated so that the pattern
 522 can be used by multiple threads. This routine is expected to handle the
 523 duplication of any private data pointed to by the C<pprivate> member of
 524 the C<regexp> structure.  It will be called with the preconstructed new
 525 C<regexp> structure as an argument, the C<pprivate> member will point at
 526 the B<old> private structure, and it is this routine's responsibility to
 527 construct a copy and return a pointer to it (which Perl will then use to
 528 overwrite the field as passed to this routine.)
 529
 530 This allows the engine to dupe its private data but also if necessary
 531 modify the final structure if it really must.
 532
 533 On unthreaded builds this field doesn't exist.
 534
 535 =head2 op_comp
 536
 537 This is private to the Perl core and subject to change. Should be left
 538 null.
 539
 540 =head1 The REGEXP structure
 541
 542 The REGEXP struct is defined in F<regexp.h>. All regex engines must be able to
 543 correctly build such a structure in their L</comp> routine.
 544
 545 The REGEXP structure contains all the data that Perl needs to be aware of
 546 to properly work with the regular expression. It includes data about
 547 optimisations that Perl can use to determine if the regex engine should
 548 really be used, and various other control info that is needed to properly
 549 execute patterns in various contexts, such as if the pattern anchored in
 550 some way, or what flags were used during the compile, or if the
 551 program contains special constructs that Perl needs to be aware of.
 552
 553 In addition it contains two fields that are intended for the private
 554 use of the regex engine that compiled the pattern. These are the
 555 C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
 556 an arbitrary structure, whose use and management is the responsibility
 557 of the compiling engine. Perl will never modify either of these
 558 values.
 559
 560     typedef struct regexp {
 561         /* what engine created this regexp? */
 562         const struct regexp_engine* engine;
 563
 564         /* what re is this a lightweight copy of? */
 565         struct regexp* mother_re;
 566
 567         /* Information about the match that the Perl core uses to manage
 568          * things */
 569         U32 extflags;   /* Flags used both externally and internally */
 570         I32 minlen;     /* mininum possible number of chars in */
 571                            string to match */
 572         I32 minlenret;  /* mininum possible number of chars in $& */
 573         U32 gofs;       /* chars left of pos that we search from */
 574
 575         /* substring data about strings that must appear
 576            in the final match, used for optimisations */
 577         struct reg_substr_data *substrs;
 578
 579         U32 nparens;  /* number of capture groups */
 580
 581         /* private engine specific data */
 582         U32 intflags;   /* Engine Specific Internal flags */
 583         void *pprivate; /* Data private to the regex engine which
 584                            created this object. */
 585
 586         /* Data about the last/current match. These are modified during
 587          * matching*/
 588         U32 lastparen;            /* highest close paren matched ($+) */
 589         U32 lastcloseparen;       /* last close paren matched ($^N) */
 590         regexp_paren_pair *swap;  /* Swap copy of *offs */
 591         regexp_paren_pair *offs;  /* Array of offsets for (@-) and
 592                                      (@+) */
 593
 594         char *subbeg;  /* saved or original string so \digit works
 595                           forever. */
 596         SV_SAVED_COPY  /* If non-NULL, SV which is COW from original */
 597         I32 sublen;    /* Length of string pointed by subbeg */
 598         I32 suboffset;  /* byte offset of subbeg from logical start of
 599                            str */
 600         I32 subcoffset; /* suboffset equiv, but in chars (for @-/@+) */
 601
 602         /* Information about the match that isn't often used */
 603         I32 prelen;           /* length of precomp */
 604         const char *precomp;  /* pre-compilation regular expression */
 605
 606         char *wrapped;  /* wrapped version of the pattern */
 607         I32 wraplen;    /* length of wrapped */
 608
 609         I32 seen_evals;   /* number of eval groups in the pattern - for
 610                              security checks */
 611         HV *paren_names;  /* Optional hash of paren names */
 612
 613         /* Refcount of this regexp */
 614         I32 refcnt;             /* Refcount of this regexp */
 615     } regexp;
 616
 617 The fields are discussed in more detail below:
 618
 619 =head2 C<engine>
 620
 621 This field points at a C<regexp_engine> structure which contains pointers
 622 to the subroutines that are to be used for performing a match. It
 623 is the compiling routine's responsibility to populate this field before
 624 returning the regexp object.
 625
 626 Internally this is set to C<NULL> unless a custom engine is specified in
 627 C<$^H{regcomp}>, Perl's own set of callbacks can be accessed in the struct
 628 pointed to by C<RE_ENGINE_PTR>.
 629
 630 =head2 C<mother_re>
 631
 632 TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>
 633
 634 =head2 C<extflags>
 635
 636 This will be used by Perl to see what flags the regexp was compiled
 637 with, this will normally be set to the value of the flags parameter by
 638 the L<comp|/comp> callback. See the L<comp|/comp> documentation for
 639 valid flags.
 640
 641 =head2 C<minlen> C<minlenret>
 642
 643 The minimum string length (in characters) required for the pattern to match.
 644 This is used to
 645 prune the search space by not bothering to match any closer to the end of a
 646 string than would allow a match. For instance there is no point in even
 647 starting the regex engine if the minlen is 10 but the string is only 5
 648 characters long. There is no way that the pattern can match.
 649
 650 C<minlenret> is the minimum length (in characters) of the string that would
 651 be found in $& after a match.
 652
 653 The difference between C<minlen> and C<minlenret> can be seen in the
 654 following pattern:
 655
 656     /ns(?=\d)/
 657
 658 where the C<minlen> would be 3 but C<minlenret> would only be 2 as the \d is
 659 required to match but is not actually included in the matched content. This
 660 distinction is particularly important as the substitution logic uses the
 661 C<minlenret> to tell if it can do in-place substitutions (these can
 662 result in considerable speed-up).
 663
 664 =head2 C<gofs>
 665
 666 Left offset from pos() to start match at.
 667
 668 =head2 C<substrs>
 669
 670 Substring data about strings that must appear in the final match. This
 671 is currently only used internally by Perl's engine, but might be
 672 used in the future for all engines for optimisations.
 673
 674 =head2 C<nparens>, C<lastparen>, and C<lastcloseparen>
 675
 676 These fields are used to keep track of how many paren groups could be matched
 677 in the pattern, which was the last open paren to be entered, and which was
 678 the last close paren to be entered.
 679
 680 =head2 C<intflags>
 681
 682 The engine's private copy of the flags the pattern was compiled with. Usually
 683 this is the same as C<extflags> unless the engine chose to modify one of them.
 684
 685 =head2 C<pprivate>
 686
 687 A void* pointing to an engine-defined data structure. The Perl engine uses the
 688 C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
 689 engine should use something else.
 690
 691 =head2 C<swap>
 692
 693 Unused. Left in for compatibility with Perl 5.10.0.
 694
 695 =head2 C<offs>
 696
 697 A C<regexp_paren_pair> structure which defines offsets into the string being
 698 matched which correspond to the C<$&> and C<$1>, C<$2> etc. captures, the
 699 C<regexp_paren_pair> struct is defined as follows:
 700
 701     typedef struct regexp_paren_pair {
 702         I32 start;
 703         I32 end;
 704     } regexp_paren_pair;
 705
 706 If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
 707 capture group did not match. C<< ->offs[0].start/end >> represents C<$&> (or
 708 C<${^MATCH}> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
 709 C<$paren >= 1>.
 710
 711 =head2 C<precomp> C<prelen>
 712
 713 Used for optimisations. C<precomp> holds a copy of the pattern that
 714 was compiled and C<prelen> its length. When a new pattern is to be
 715 compiled (such as inside a loop) the internal C<regcomp> operator
 716 checks if the last compiled C<REGEXP>'s C<precomp> and C<prelen>
 717 are equivalent to the new one, and if so uses the old pattern instead
 718 of compiling a new one.
 719
 720 The relevant snippet from C<Perl_pp_regcomp>:
 721
 722         if (!re || !re->precomp || re->prelen != (I32)len ||
 723             memNE(re->precomp, t, len))
 724         /* Compile a new pattern */
 725
 726 =head2 C<paren_names>
 727
 728 This is a hash used internally to track named capture groups and their
 729 offsets. The keys are the names of the buffers the values are dualvars,
 730 with the IV slot holding the number of buffers with the given name and the
 731 pv being an embedded array of I32.  The values may also be contained
 732 independently in the data array in cases where named backreferences are
 733 used.
 734
 735 =head2 C<substrs>
 736
 737 Holds information on the longest string that must occur at a fixed
 738 offset from the start of the pattern, and the longest string that must
 739 occur at a floating offset from the start of the pattern. Used to do
 740 Fast-Boyer-Moore searches on the string to find out if its worth using
 741 the regex engine at all, and if so where in the string to search.
 742
 743 =head2 C<subbeg> C<sublen> C<saved_copy> C<suboffset> C<subcoffset>
 744
 745 Used during the execution phase for managing search and replace patterns,
 746 and for providing the text for C<$&>, C<$1> etc. C<subbeg> points to a
 747 buffer (either the original string, or a copy in the case of
 748 C<RX_MATCH_COPIED(rx)>), and C<sublen> is the length of the buffer.  The
 749 C<RX_OFFS> start and end indices index into this buffer.
 750
 751 In the presence of the C<REXEC_COPY_STR> flag, but with the addition of
 752 the C<REXEC_COPY_SKIP_PRE> or C<REXEC_COPY_SKIP_POST> flags, an engine
 753 can choose not to copy the full buffer (although it must still do so in
 754 the presence of C<RXf_PMf_KEEPCOPY> or the relevant bits being set in
 755 C<PL_sawampersand>). In this case, it may set C<suboffset> to indicate the
 756 number of bytes from the logical start of the buffer to the physical start
 757 (i.e. C<subbeg>). It should also set C<subcoffset>, the number of
 758 characters in the offset. The latter is needed to support C<@-> and C<@+>
 759 which work in characters, not bytes.
 760
 761 =head2 C<wrapped> C<wraplen>
 762
 763 Stores the string C<qr//> stringifies to. The Perl engine for example
 764 stores C<(?^:eek)> in the case of C<qr/eek/>.
 765
 766 When using a custom engine that doesn't support the C<(?:)> construct
 767 for inline modifiers, it's probably best to have C<qr//> stringify to
 768 the supplied pattern, note that this will create undesired patterns in
 769 cases such as:
 770
 771     my $x = qr/a|b/;  # "a|b"
 772     my $y = qr/c/i;   # "c"
 773     my $z = qr/$x$y/; # "a|bc"
 774
 775 There's no solution for this problem other than making the custom
 776 engine understand a construct like C<(?:)>.
 777
 778 =head2 C<seen_evals>
 779
 780 This stores the number of eval groups in the pattern. This is used for security
 781 purposes when embedding compiled regexes into larger patterns with C<qr//>.
 782
 783 =head2 C<refcnt>
 784
 785 The number of times the structure is referenced. When this falls to 0, the
 786 regexp is automatically freed by a call to pregfree. This should be set to 1 in
 787 each engine's L</comp> routine.
 788
 789 =head1 HISTORY
 790
 791 Originally part of L<perlreguts>.
 792
 793 =head1 AUTHORS
 794
 795 Originally written by Yves Orton, expanded by E<AElig>var ArnfjE<ouml>rE<eth>
 796 Bjarmason.
 797
 798 =head1 LICENSE
 799
 800 Copyright 2006 Yves Orton and 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
 801
 802 This program is free software; you can redistribute it and/or modify it under
 803 the same terms as Perl itself.
 804
 805 =cut