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
382 the C<SvRX> macro, see L<"REGEXP Functions" in perlapi|perlapi/REGEXP
387 REGEXP * re = SvRX(sv);
391 void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
393 On threaded builds a regexp may need to be duplicated so that the pattern
394 can be used by mutiple threads. This routine is expected to handle the
395 duplication of any private data pointed to by the C<pprivate> member of
396 the regexp structure. It will be called with the preconstructed new
397 regexp structure as an argument, the C<pprivate> member will point at
398 the B<old> private structue, and it is this routine's responsibility to
399 construct a copy and return a pointer to it (which perl will then use to
400 overwrite the field as passed to this routine.)
402 This allows the engine to dupe its private data but also if necessary
403 modify the final structure if it really must.
405 On unthreaded builds this field doesn't exist.
407 =head1 The REGEXP structure
409 The REGEXP struct is defined in F<regexp.h>. All regex engines must be able to
410 correctly build such a structure in their L</comp> routine.
412 The REGEXP structure contains all the data that perl needs to be aware of
413 to properly work with the regular expression. It includes data about
414 optimisations that perl can use to determine if the regex engine should
415 really be used, and various other control info that is needed to properly
416 execute patterns in various contexts such as is the pattern anchored in
417 some way, or what flags were used during the compile, or whether the
418 program contains special constructs that perl needs to be aware of.
420 In addition it contains two fields that are intended for the private
421 use of the regex engine that compiled the pattern. These are the
422 C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
423 an arbitrary structure whose use and management is the responsibility
424 of the compiling engine. perl will never modify either of these
427 typedef struct regexp {
428 /* what engine created this regexp? */
429 const struct regexp_engine* engine;
431 /* what re is this a lightweight copy of? */
432 struct regexp* mother_re;
434 /* Information about the match that the perl core uses to manage things */
435 U32 extflags; /* Flags used both externally and internally */
436 I32 minlen; /* mininum possible length of string to match */
437 I32 minlenret; /* mininum possible length of $& */
438 U32 gofs; /* chars left of pos that we search from */
440 /* substring data about strings that must appear
441 in the final match, used for optimisations */
442 struct reg_substr_data *substrs;
444 U32 nparens; /* number of capture buffers */
446 /* private engine specific data */
447 U32 intflags; /* Engine Specific Internal flags */
448 void *pprivate; /* Data private to the regex engine which
449 created this object. */
451 /* Data about the last/current match. These are modified during matching*/
452 U32 lastparen; /* last open paren matched */
453 U32 lastcloseparen; /* last close paren matched */
454 regexp_paren_pair *swap; /* Swap copy of *offs */
455 regexp_paren_pair *offs; /* Array of offsets for (@-) and (@+) */
457 char *subbeg; /* saved or original string so \digit works forever. */
458 SV_SAVED_COPY /* If non-NULL, SV which is COW from original */
459 I32 sublen; /* Length of string pointed by subbeg */
461 /* Information about the match that isn't often used */
462 I32 prelen; /* length of precomp */
463 const char *precomp; /* pre-compilation regular expression */
465 /* wrapped can't be const char*, as it is returned by sv_2pv_flags */
466 char *wrapped; /* wrapped version of the pattern */
467 I32 wraplen; /* length of wrapped */
469 I32 seen_evals; /* number of eval groups in the pattern - for security checks */
470 HV *paren_names; /* Optional hash of paren names */
472 /* Refcount of this regexp */
473 I32 refcnt; /* Refcount of this regexp */
476 The fields are discussed in more detail below:
480 This field points at a regexp_engine structure which contains pointers
481 to the subroutines that are to be used for performing a match. It
482 is the compiling routine's responsibility to populate this field before
483 returning the regexp object.
485 Internally this is set to C<NULL> unless a custom engine is specified in
486 C<$^H{regcomp}>, perl's own set of callbacks can be accessed in the struct
487 pointed to by C<RE_ENGINE_PTR>.
491 TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>
495 This will be used by perl to see what flags the regexp was compiled
496 with, this will normally be set to the value of the flags parameter by
497 the L<comp|/comp> callback.
499 =head2 C<minlen> C<minlenret>
501 The minimum string length required for the pattern to match. This is used to
502 prune the search space by not bothering to match any closer to the end of a
503 string than would allow a match. For instance there is no point in even
504 starting the regex engine if the minlen is 10 but the string is only 5
505 characters long. There is no way that the pattern can match.
507 C<minlenret> is the minimum length of the string that would be found
510 The difference between C<minlen> and C<minlenret> can be seen in the
515 where the C<minlen> would be 3 but C<minlenret> would only be 2 as the \d is
516 required to match but is not actually included in the matched content. This
517 distinction is particularly important as the substitution logic uses the
518 C<minlenret> to tell whether it can do in-place substition which can result in
519 considerable speedup.
523 Left offset from pos() to start match at.
527 Substring data about strings that must appear in the final match. This
528 is currently only used internally by perl's engine for but might be
529 used in the future for all engines for optimisations like C<minlen>.
531 =head2 C<nparens>, C<lasparen>, and C<lastcloseparen>
533 These fields are used to keep track of how many paren groups could be matched
534 in the pattern, which was the last open paren to be entered, and which was
535 the last close paren to be entered.
539 The engine's private copy of the flags the pattern was compiled with. Usually
540 this is the same as C<extflags> unless the engine chose to modify one of them.
544 A void* pointing to an engine-defined data structure. The perl engine uses the
545 C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
546 engine should use something else.
554 A C<regexp_paren_pair> structure which defines offsets into the string being
555 matched which correspond to the C<$&> and C<$1>, C<$2> etc. captures, the
556 C<regexp_paren_pair> struct is defined as follows:
558 typedef struct regexp_paren_pair {
563 If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
564 capture buffer did not match. C<< ->offs[0].start/end >> represents C<$&> (or
565 C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
568 =head2 C<precomp> C<prelen>
570 Used for optimisations. C<precomp> holds a copy of the pattern that
571 was compiled and C<prelen> its length. When a new pattern is to be
572 compiled (such as inside a loop) the internal C<regcomp> operator
573 checks whether the last compiled C<REGEXP>'s C<precomp> and C<prelen>
574 are equivalent to the new one, and if so uses the old pattern instead
575 of compiling a new one.
577 The relevant snippet from C<Perl_pp_regcomp>:
579 if (!re || !re->precomp || re->prelen != (I32)len ||
580 memNE(re->precomp, t, len))
581 /* Compile a new pattern */
583 =head2 C<paren_names>
585 This is a hash used internally to track named capture buffers and their
586 offsets. The keys are the names of the buffers the values are dualvars,
587 with the IV slot holding the number of buffers with the given name and the
588 pv being an embedded array of I32. The values may also be contained
589 independently in the data array in cases where named backreferences are
592 =head2 C<reg_substr_data>
594 Holds information on the longest string that must occur at a fixed
595 offset from the start of the pattern, and the longest string that must
596 occur at a floating offset from the start of the pattern. Used to do
597 Fast-Boyer-Moore searches on the string to find out if its worth using
598 the regex engine at all, and if so where in the string to search.
600 =head2 C<subbeg> C<sublen> C<saved_copy>
602 #define SAVEPVN(p,n) ((p) ? savepvn(p,n) : NULL)
603 if (RX_MATCH_COPIED(ret))
604 ret->subbeg = SAVEPVN(ret->subbeg, ret->sublen);
608 C<PL_sawampersand || rx->extflags & RXf_PMf_KEEPCOPY>
610 These are used during execution phase for managing search and replace
613 =head2 C<wrapped> C<wraplen>
615 Stores the string C<qr//> stringifies to, for example C<(?-xism:eek)>
616 in the case of C<qr/eek/>.
618 When using a custom engine that doesn't support the C<(?:)> construct for
619 inline modifiers it's best to have C<qr//> stringify to the supplied pattern,
620 note that this will create invalid patterns in cases such as:
622 my $x = qr/a|b/; # "a|b"
623 my $y = qr/c/i; # "c"
624 my $z = qr/$x$y/; # "a|bc"
626 There's no solution for this problem other than making the custom
627 engine understand a construct like C<(?:)>.
629 The C<Perl_reg_stringify> in F<regcomp.c> does the stringification work.
633 This stores the number of eval groups in the pattern. This is used for security
634 purposes when embedding compiled regexes into larger patterns with C<qr//>.
638 The number of times the structure is referenced. When this falls to 0 the
639 regexp is automatically freed by a call to pregfree. This should be set to 1 in
640 each engine's L</comp> routine.
644 Originally part of L<perlreguts>.
648 Originally written by Yves Orton, expanded by E<AElig>var ArnfjE<ouml>rE<eth>
653 Copyright 2006 Yves Orton and 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
655 This program is free software; you can redistribute it and/or modify it under
656 the same terms as Perl itself.