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