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