3 perlreapi - perl regular expression plugin interface
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:
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,
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,
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,
31 SV* (*qr_package)(pTHX_ REGEXP * const rx);
33 void* (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
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.
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
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.
55 REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);
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.
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:
68 char* exp = SvPV(pattern, plen);
69 char* xend = exp + plen;
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.
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.
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.
96 C<split ' '> or C<split> with no arguments (which really means
97 C<split(' ', $_> see L<split|perlfunc>).
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>).
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.
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>.
118 =item RXf_PMf_MULTILINE
120 The C</m> flag, this ends up being passed to C<Perl_fbm_instr> by
121 C<pp_split> regardless of the engine.
123 =item RXf_PMf_SINGLELINE
125 The C</s> flag. Guaranteed not to be used outside the regex engine.
129 The C</i> flag. Guaranteed not to be used outside the regex engine.
131 =item RXf_PMf_EXTENDED
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.
137 =item RXf_PMf_KEEPCOPY
143 Set if the pattern is L<SvUTF8()|perlapi/SvUTF8>, set by Perl_pmruntime.
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 >>.
156 I32 exec(pTHX_ REGEXP * const rx,
157 char *stringarg, char* strend, char* strbeg,
158 I32 minend, SV* screamer,
159 void* data, U32 flags);
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);
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
177 SV* checkstr(pTHX_ REGEXP * const rx);
179 Return a SV containing a string that must appear in the pattern. Used
180 by C<split> for optimising matches.
184 void free(pTHX_ REGEXP * const rx);
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.
191 =head2 Numbered capture callbacks
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>, ...).
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.
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.
205 =head3 numbered_buff_FETCH
207 void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
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>.
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.
222 =head3 numbered_buff_STORE
224 void (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
225 SV const * const value);
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).
233 if ("ook" =~ /(o*)/) {
234 # `paren' will be `1' and `value' will be `ee'
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>):
243 Example_reg_numbered_buff_store(pTHX_ REGEXP * const rx, const I32 paren,
244 SV const * const value)
247 PERL_UNUSED_ARG(paren);
248 PERL_UNUSED_ARG(value);
251 Perl_croak(aTHX_ PL_no_modify);
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:
261 use base 'Tie::Scalar';
263 sub TIESCALAR { bless [] }
265 sub STORE { die "This doesn't get called" }
269 tie my $sv => "CatptureVar";
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.
278 =head3 numbered_buff_LENGTH
280 I32 numbered_buff_LENGTH (pTHX_ REGEXP * const rx, const SV * const sv,
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:
288 I32 s1 = rx->offs[paren].start;
289 I32 s2 = rx->offs[paren].end;
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>.
296 =head2 Named capture callbacks
298 Called to get/set the value of C<%+> and C<%-> as well as by some
299 utility functions in L<re>.
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.
306 The C<flags> parameter can be used to determine which of these
307 operations the callbacks should respond to, the following flags are
310 Which L<Tie::Hash> operation is being performed from the Perl level on
311 C<%+> or C<%+>, if any:
322 Whether C<%+> or C<%-> is being operated on, if any.
324 RXf_HASH_ONE /* %+ */
325 RXf_HASH_ALL /* %- */
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>.
333 RXf_HASH_REGNAMES_COUNT
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).
344 SV* (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
345 SV * const value, U32 flags);
347 =head3 named_buff_iter
349 SV* (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
354 SV* qr_package(pTHX_ REGEXP * const rx);
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
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.
365 Example implementation might be:
368 Example_qr_package(pTHX_ REGEXP * const rx)
371 return newSVpvs("re::engine::Example");
374 Any method calls on an object created with C<qr//> will be dispatched to the
375 package as a normal object.
377 use re::engine::Example;
379 $re->meth; # dispatched to re::engine::Example::meth()
381 To retrieve the C<REGEXP> object from the scalar in an XS function use the
392 (sv = (SV*)SvRV(sv)) && /* assignment deliberate */
393 SvTYPE(sv) == SVt_PVMG &&
394 (mg = mg_find(sv, PERL_MAGIC_qr))) /* assignment deliberate */
396 re = (REGEXP *)mg->mg_obj;
401 void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
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.)
412 This allows the engine to dupe its private data but also if necessary
413 modify the final structure if it really must.
415 On unthreaded builds this field doesn't exist.
417 =head1 The REGEXP structure
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.
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.
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
437 typedef struct regexp {
438 /* what engine created this regexp? */
439 const struct regexp_engine* engine;
441 /* what re is this a lightweight copy of? */
442 struct regexp* mother_re;
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 */
450 /* substring data about strings that must appear
451 in the final match, used for optimisations */
452 struct reg_substr_data *substrs;
454 U32 nparens; /* number of capture buffers */
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. */
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 (@+) */
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 */
471 /* Information about the match that isn't often used */
472 I32 prelen; /* length of precomp */
473 const char *precomp; /* pre-compilation regular expression */
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 */
479 I32 seen_evals; /* number of eval groups in the pattern - for security checks */
480 HV *paren_names; /* Optional hash of paren names */
482 /* Refcount of this regexp */
483 I32 refcnt; /* Refcount of this regexp */
486 The fields are discussed in more detail below:
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.
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>.
501 TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>
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.
509 =head2 C<minlen> C<minlenret>
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.
517 C<minlenret> is the minimum length of the string that would be found
520 The difference between C<minlen> and C<minlenret> can be seen in the
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.
533 Left offset from pos() to start match at.
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>.
541 =head2 C<nparens>, C<lasparen>, and C<lastcloseparen>
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.
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.
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.
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:
568 typedef struct regexp_paren_pair {
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
578 =head2 C<precomp> C<prelen>
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.
587 The relevant snippet from C<Perl_pp_regcomp>:
589 if (!re || !re->precomp || re->prelen != (I32)len ||
590 memNE(re->precomp, t, len))
591 /* Compile a new pattern */
593 =head2 C<paren_names>
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
602 =head2 C<reg_substr_data>
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.
610 =head2 C<subbeg> C<sublen> C<saved_copy>
612 #define SAVEPVN(p,n) ((p) ? savepvn(p,n) : NULL)
613 if (RX_MATCH_COPIED(ret))
614 ret->subbeg = SAVEPVN(ret->subbeg, ret->sublen);
618 C<PL_sawampersand || rx->extflags & RXf_PMf_KEEPCOPY>
620 These are used during execution phase for managing search and replace
623 =head2 C<wrapped> C<wraplen>
625 Stores the string C<qr//> stringifies to, for example C<(?-xism:eek)>
626 in the case of C<qr/eek/>.
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:
632 my $x = qr/a|b/; # "a|b"
633 my $y = qr/c/i; # "c"
634 my $z = qr/$x$y/; # "a|bc"
636 There's no solution for this problem other than making the custom
637 engine understand a construct like C<(?:)>.
639 The C<Perl_reg_stringify> in F<regcomp.c> does the stringification work.
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//>.
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.
654 Originally part of L<perlreguts>.
658 Originally written by Yves Orton, expanded by E<AElig>var ArnfjE<ouml>rE<eth>
663 Copyright 2006 Yves Orton and 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
665 This program is free software; you can redistribute it and/or modify it under
666 the same terms as Perl itself.