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