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