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