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