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