Debian Codegraph @

upstream/fedora-44/man1/perlreapi.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLREAPI 1"
61 .TH PERLREAPI 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlreapi \- Perl regular expression plugin interface
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 As of Perl 5.9.5 there is a new interface for plugging and using
71 regular expression engines other than the default one.
72 .PP
73 Each engine is supposed to provide access to a constant structure of the
74 following format:
75 .PP
76 .Vb 10
77 \& typedef struct regexp_engine {
78 \& REGEXP* (*comp) (pTHX_
79 \& const SV * const pattern, const U32 flags);
80 \& I32 (*exec) (pTHX_
81 \& REGEXP * const rx,
82 \& char* stringarg,
83 \& char* strend, char* strbeg,
84 \& SSize_t minend, SV* sv,
85 \& void* data, U32 flags);
86 \& char* (*intuit) (pTHX_
87 \& REGEXP * const rx, SV *sv,
88 \& const char * const strbeg,
89 \& char *strpos, char *strend, U32 flags,
90 \& struct re_scream_pos_data_s *data);
91 \& SV* (*checkstr) (pTHX_ REGEXP * const rx);
92 \& void (*free) (pTHX_ REGEXP * const rx);
93 \& void (*numbered_buff_FETCH) (pTHX_
94 \& REGEXP * const rx,
95 \& const I32 paren,
96 \& SV * const sv);
97 \& void (*numbered_buff_STORE) (pTHX_
98 \& REGEXP * const rx,
99 \& const I32 paren,
100 \& SV const * const value);
101 \& I32 (*numbered_buff_LENGTH) (pTHX_
102 \& REGEXP * const rx,
103 \& const SV * const sv,
104 \& const I32 paren);
105 \& SV* (*named_buff) (pTHX_
106 \& REGEXP * const rx,
107 \& SV * const key,
108 \& SV * const value,
109 \& U32 flags);
110 \& SV* (*named_buff_iter) (pTHX_
111 \& REGEXP * const rx,
112 \& const SV * const lastkey,
113 \& const U32 flags);
114 \& SV* (*qr_package)(pTHX_ REGEXP * const rx);
115 \& #ifdef USE_ITHREADS
116 \& void* (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
117 \& #endif
118 \& REGEXP* (*op_comp) (...);
119 .Ve
120 .PP
121 When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at
122 the appropriate structure, so that when it needs to be used Perl can find
123 the right routines to do so.
124 .PP
125 In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set
126 to an integer which (when casted appropriately) resolves to one of these
127 structures. When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the
128 resulting \f(CW\*(C`regexp\*(C'\fR structure\*(Aqs engine field is expected to point back at
129 the same structure.
130 .PP
131 The pTHX_ symbol in the definition is a macro used by Perl under threading
132 to provide an extra argument to the routine holding a pointer back to
133 the interpreter that is executing the regexp. So under threading all
134 routines get an extra argument.
135 .SH Callbacks
136 .IX Header "Callbacks"
137 .SS comp
138 .IX Subsection "comp"
139 .Vb 1
140 \& REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);
141 .Ve
142 .PP
143 Compile the pattern stored in \f(CW\*(C`pattern\*(C'\fR using the given \f(CW\*(C`flags\*(C'\fR and
144 return a pointer to a prepared \f(CW\*(C`REGEXP\*(C'\fR structure that can perform
145 the match. See "The REGEXP structure" below for an explanation of
146 the individual fields in the REGEXP struct.
147 .PP
148 The \f(CW\*(C`pattern\*(C'\fR parameter is the scalar that was used as the
149 pattern. Previous versions of Perl would pass two \f(CW\*(C`char*\*(C'\fR indicating
150 the start and end of the stringified pattern; the following snippet can
151 be used to get the old parameters:
152 .PP
153 .Vb 3
154 \& STRLEN plen;
155 \& char* exp = SvPV(pattern, plen);
156 \& char* xend = exp + plen;
157 .Ve
158 .PP
159 Since any scalar can be passed as a pattern, it\*(Aqs possible to implement
160 an engine that does something with an array (\f(CW\*(C`"ook" =~ [ qw/ eek
161 hlagh / ]\*(C'\fR) or with the non\-stringified form of a compiled regular
162 expression (\f(CW\*(C`"ook" =~ qr/eek/\*(C'\fR). Perl\*(Aqs own engine will always
163 stringify everything using the snippet above, but that doesn\*(Aqt mean
164 other engines have to.
165 .PP
166 The \f(CW\*(C`flags\*(C'\fR parameter is a bitfield which indicates which of the
167 \&\f(CW\*(C`msixpn\*(C'\fR flags the regex was compiled with. It also contains
168 additional info, such as if \f(CW\*(C`use locale\*(C'\fR is in effect.
169 .PP
170 The \f(CW\*(C`eogc\*(C'\fR flags are stripped out before being passed to the comp
171 routine. The regex engine does not need to know if any of these
172 are set, as those flags should only affect what Perl does with the
173 pattern and its match variables, not how it gets compiled and
174 executed.
175 .PP
176 By the time the comp callback is called, some of these flags have
177 already had effect (noted below where applicable). However most of
178 their effect occurs after the comp callback has run, in routines that
179 read the \f(CW\*(C`rx\->extflags\*(C'\fR field which it populates.
180 .PP
181 In general the flags should be preserved in \f(CW\*(C`rx\->extflags\*(C'\fR after
182 compilation, although the regex engine might want to add or delete
183 some of them to invoke or disable some special behavior in Perl. The
184 flags along with any special behavior they cause are documented below:
185 .PP
186 The pattern modifiers:
187 .ie n .IP """/m"" \- RXf_PMf_MULTILINE" 4
188 .el .IP "\f(CW/m\fR \- RXf_PMf_MULTILINE" 4
189 .IX Item "/m - RXf_PMf_MULTILINE"
190 If this is in \f(CW\*(C`rx\->extflags\*(C'\fR it will be passed to
191 \&\f(CW\*(C`Perl_fbm_instr\*(C'\fR by \f(CW\*(C`pp_split\*(C'\fR which will treat the subject string
192 as a multi\-line string.
193 .ie n .IP """/s"" \- RXf_PMf_SINGLELINE" 4
194 .el .IP "\f(CW/s\fR \- RXf_PMf_SINGLELINE" 4
195 .IX Item "/s - RXf_PMf_SINGLELINE"
196 .PD 0
197 .ie n .IP """/i"" \- RXf_PMf_FOLD" 4
198 .el .IP "\f(CW/i\fR \- RXf_PMf_FOLD" 4
199 .IX Item "/i - RXf_PMf_FOLD"
200 .ie n .IP """/x"" \- RXf_PMf_EXTENDED" 4
201 .el .IP "\f(CW/x\fR \- RXf_PMf_EXTENDED" 4
202 .IX Item "/x - RXf_PMf_EXTENDED"
203 .PD
204 If present on a regex, \f(CW"#"\fR comments will be handled differently by the
205 tokenizer in some cases.
206 .Sp
207 TODO: Document those cases.
208 .ie n .IP """/p"" \- RXf_PMf_KEEPCOPY" 4
209 .el .IP "\f(CW/p\fR \- RXf_PMf_KEEPCOPY" 4
210 .IX Item "/p - RXf_PMf_KEEPCOPY"
211 TODO: Document this
212 .IP "Character set" 4
213 .IX Item "Character set"
214 The character set rules are determined by an enum that is contained
215 in this field. This is still experimental and subject to change, but
216 the current interface returns the rules by use of the in\-line function
217 \&\f(CW\*(C`get_regex_charset(const U32 flags)\*(C'\fR. The only currently documented
218 value returned from it is REGEX_LOCALE_CHARSET, which is set if
219 \&\f(CW\*(C`use locale\*(C'\fR is in effect. If present in \f(CW\*(C`rx\->extflags\*(C'\fR,
220 \&\f(CW\*(C`split\*(C'\fR will use the locale dependent definition of whitespace
221 when RXf_SKIPWHITE or RXf_WHITE is in effect. ASCII whitespace
222 is defined as per isSPACE, and by the internal
223 macros \f(CW\*(C`is_utf8_space\*(C'\fR under UTF\-8, and \f(CW\*(C`isSPACE_LC\*(C'\fR under \f(CW\*(C`use
224 locale\*(C'\fR.
225 .PP
226 Additional flags:
227 .IP RXf_SPLIT 4
228 .IX Item "RXf_SPLIT"
229 This flag was removed in perl 5.18.0. \f(CW\*(C`split \*(Aq \*(Aq\*(C'\fR is now special\-cased
230 solely in the parser. RXf_SPLIT is still #defined, so you can test for it.
231 This is how it used to work:
232 .Sp
233 If \f(CW\*(C`split\*(C'\fR is invoked as \f(CW\*(C`split \*(Aq \*(Aq\*(C'\fR or with no arguments (which
234 really means \f(CW\*(C`split(\*(Aq \*(Aq, $_)\*(C'\fR, see split), Perl will
235 set this flag. The regex engine can then check for it and set the
236 SKIPWHITE and WHITE extflags. To do this, the Perl engine does:
237 .Sp
238 .Vb 2
239 \& if (flags & RXf_SPLIT && r\->prelen == 1 && r\->precomp[0] == \*(Aq \*(Aq)
240 \& r\->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
241 .Ve
242 .PP
243 These flags can be set during compilation to enable optimizations in
244 the \f(CW\*(C`split\*(C'\fR operator.
245 .IP RXf_SKIPWHITE 4
246 .IX Item "RXf_SKIPWHITE"
247 This flag was removed in perl 5.18.0. It is still #defined, so you can
248 set it, but doing so will have no effect. This is how it used to work:
249 .Sp
250 If the flag is present in \f(CW\*(C`rx\->extflags\*(C'\fR \f(CW\*(C`split\*(C'\fR will delete
251 whitespace from the start of the subject string before it\*(Aqs operated
252 on. What is considered whitespace depends on if the subject is a
253 UTF\-8 string and if the \f(CW\*(C`RXf_PMf_LOCALE\*(C'\fR flag is set.
254 .Sp
255 If RXf_WHITE is set in addition to this flag, \f(CW\*(C`split\*(C'\fR will behave like
256 \&\f(CW\*(C`split " "\*(C'\fR under the Perl engine.
257 .IP RXf_START_ONLY 4
258 .IX Item "RXf_START_ONLY"
259 Tells the split operator to split the target string on newlines
260 (\f(CW\*(C`\en\*(C'\fR) without invoking the regex engine.
261 .Sp
262 Perl\*(Aqs engine sets this if the pattern is \f(CW\*(C`/^/\*(C'\fR (\f(CW\*(C`plen == 1 && *exp
263 == \*(Aq^\*(Aq\*(C'\fR), even under \f(CW\*(C`/^/s\*(C'\fR; see split. Of course a
264 different regex engine might want to use the same optimizations
265 with a different syntax.
266 .IP RXf_WHITE 4
267 .IX Item "RXf_WHITE"
268 Tells the split operator to split the target string on whitespace
269 without invoking the regex engine. The definition of whitespace varies
270 depending on if the target string is a UTF\-8 string and on
271 if RXf_PMf_LOCALE is set.
272 .Sp
273 Perl\*(Aqs engine sets this flag if the pattern is \f(CW\*(C`\es+\*(C'\fR.
274 .IP RXf_NULL 4
275 .IX Item "RXf_NULL"
276 Tells the split operator to split the target string on
277 characters. The definition of character varies depending on if
278 the target string is a UTF\-8 string.
279 .Sp
280 Perl\*(Aqs engine sets this flag on empty patterns, this optimization
281 makes \f(CW\*(C`split //\*(C'\fR much faster than it would otherwise be. It\*(Aqs even
282 faster than \f(CW\*(C`unpack\*(C'\fR.
283 .IP RXf_NO_INPLACE_SUBST 4
284 .IX Item "RXf_NO_INPLACE_SUBST"
285 Added in perl 5.18.0, this flag indicates that a regular expression might
286 perform an operation that would interfere with inplace substitution. For
287 instance it might contain lookbehind, or assign to non\-magical variables
288 (such as \f(CW$REGMARK\fR and \f(CW$REGERROR\fR) during matching. \f(CW\*(C`s///\*(C'\fR will skip
289 certain optimisations when this is set.
290 .SS exec
291 .IX Subsection "exec"
292 .Vb 4
293 \& I32 exec(pTHX_ REGEXP * const rx,
294 \& char *stringarg, char* strend, char* strbeg,
295 \& SSize_t minend, SV* sv,
296 \& void* data, U32 flags);
297 .Ve
298 .PP
299 Execute a regexp. The arguments are
300 .IP rx 4
301 .IX Item "rx"
302 The regular expression to execute.
303 .IP sv 4
304 .IX Item "sv"
305 This is the SV to be matched against. Note that the
306 actual char array to be matched against is supplied by the arguments
307 described below; the SV is just used to determine UTF8ness, \f(CWpos()\fR etc.
308 .IP strbeg 4
309 .IX Item "strbeg"
310 Pointer to the physical start of the string.
311 .IP strend 4
312 .IX Item "strend"
313 Pointer to the character following the physical end of the string (i.e.
314 the \f(CW\*(C`\e0\*(C'\fR, if any).
315 .IP stringarg 4
316 .IX Item "stringarg"
317 Pointer to the position in the string where matching should start; it might
318 not be equal to \f(CW\*(C`strbeg\*(C'\fR (for example in a later iteration of \f(CW\*(C`/.../g\*(C'\fR).
319 .IP minend 4
320 .IX Item "minend"
321 Minimum length of string (measured in bytes from \f(CW\*(C`stringarg\*(C'\fR) that must
322 match; if the engine reaches the end of the match but hasn\*(Aqt reached this
323 position in the string, it should fail.
324 .IP data 4
325 .IX Item "data"
326 Optimisation data; subject to change.
327 .IP flags 4
328 .IX Item "flags"
329 Optimisation flags; subject to change.
330 .SS intuit
331 .IX Subsection "intuit"
332 .Vb 8
333 \& char* intuit(pTHX_
334 \& REGEXP * const rx,
335 \& SV *sv,
336 \& const char * const strbeg,
337 \& char *strpos,
338 \& char *strend,
339 \& const U32 flags,
340 \& struct re_scream_pos_data_s *data);
341 .Ve
342 .PP
343 Find the start position where a regex match should be attempted,
344 or possibly if the regex engine should not be run because the
345 pattern can\*(Aqt match. This is called, as appropriate, by the core,
346 depending on the values of the \f(CW\*(C`extflags\*(C'\fR member of the \f(CW\*(C`regexp\*(C'\fR
347 structure.
348 .PP
349 Arguments:
350 .PP
351 .Vb 11
352 \& rx: the regex to match against
353 \& sv: the SV being matched: only used for utf8 flag; the string
354 \& itself is accessed via the pointers below. Note that on
355 \& something like an overloaded SV, SvPOK(sv) may be false
356 \& and the string pointers may point to something unrelated to
357 \& the SV itself.
358 \& strbeg: real beginning of string
359 \& strpos: the point in the string at which to begin matching
360 \& strend: pointer to the byte following the last char of the string
361 \& flags currently unused; set to 0
362 \& data: currently unused; set to NULL
363 .Ve
364 .SS checkstr
365 .IX Subsection "checkstr"
366 .Vb 1
367 \& SV* checkstr(pTHX_ REGEXP * const rx);
368 .Ve
369 .PP
370 Return a SV containing a string that must appear in the pattern. Used
371 by \f(CW\*(C`split\*(C'\fR for optimising matches.
372 .SS free
373 .IX Subsection "free"
374 .Vb 1
375 \& void free(pTHX_ REGEXP * const rx);
376 .Ve
377 .PP
378 Called by Perl when it is freeing a regexp pattern so that the engine
379 can release any resources pointed to by the \f(CW\*(C`pprivate\*(C'\fR member of the
380 \&\f(CW\*(C`regexp\*(C'\fR structure. This is only responsible for freeing private data;
381 Perl will handle releasing anything else contained in the \f(CW\*(C`regexp\*(C'\fR structure.
382 .SS "Numbered capture callbacks"
383 .IX Subsection "Numbered capture callbacks"
384 Called to get/set the value of \f(CW\*(C`$\`\*(C'\fR, \f(CW\*(C`$\*(Aq\*(C'\fR, \f(CW$&\fR and their named
385 equivalents, ${^PREMATCH}, ${^POSTMATCH} and ${^MATCH}, as well as the
386 numbered capture groups (\f(CW$1\fR, \f(CW$2\fR, ...).
387 .PP
388 The \f(CW\*(C`paren\*(C'\fR parameter will be \f(CW1\fR for \f(CW$1\fR, \f(CW2\fR for \f(CW$2\fR and so
389 forth, and have these symbolic values for the special variables:
390 .PP
391 .Vb 6
392 \& ${^PREMATCH} RX_BUFF_IDX_CARET_PREMATCH
393 \& ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
394 \& ${^MATCH} RX_BUFF_IDX_CARET_FULLMATCH
395 \& $\` RX_BUFF_IDX_PREMATCH
396 \& $\*(Aq RX_BUFF_IDX_POSTMATCH
397 \& $& RX_BUFF_IDX_FULLMATCH
398 .Ve
399 .PP
400 Note that in Perl 5.17.3 and earlier, the last three constants were also
401 used for the caret variants of the variables.
402 .PP
403 The names have been chosen by analogy with Tie::Scalar methods
404 names with an additional \fBLENGTH\fR callback for efficiency. However
405 named capture variables are currently not tied internally but
406 implemented via magic.
407 .PP
408 \fInumbered_buff_FETCH\fR
409 .IX Subsection "numbered_buff_FETCH"
410 .PP
411 .Vb 2
412 \& void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
413 \& SV * const sv);
414 .Ve
415 .PP
416 Fetch a specified numbered capture. \f(CW\*(C`sv\*(C'\fR should be set to the scalar
417 to return, the scalar is passed as an argument rather than being
418 returned from the function because when it\*(Aqs called Perl already has a
419 scalar to store the value, creating another one would be
420 redundant. The scalar can be set with \f(CW\*(C`sv_setsv\*(C'\fR, \f(CW\*(C`sv_setpvn\*(C'\fR and
421 friends, see perlapi.
422 .PP
423 This callback is where Perl untaints its own capture variables under
424 taint mode (see perlsec). See the \f(CW\*(C`Perl_reg_numbered_buff_fetch\*(C'\fR
425 function in \fIregcomp.c\fR for how to untaint capture variables if
426 that\*(Aqs something you\*(Aqd like your engine to do as well.
427 .PP
428 \fInumbered_buff_STORE\fR
429 .IX Subsection "numbered_buff_STORE"
430 .PP
431 .Vb 4
432 \& void (*numbered_buff_STORE) (pTHX_
433 \& REGEXP * const rx,
434 \& const I32 paren,
435 \& SV const * const value);
436 .Ve
437 .PP
438 Set the value of a numbered capture variable. \f(CW\*(C`value\*(C'\fR is the scalar
439 that is to be used as the new value. It\*(Aqs up to the engine to make
440 sure this is used as the new value (or reject it).
441 .PP
442 Example:
443 .PP
444 .Vb 4
445 \& if ("ook" =~ /(o*)/) {
446 \& # \*(Aqparen\*(Aq will be \*(Aq1\*(Aq and \*(Aqvalue\*(Aq will be \*(Aqee\*(Aq
447 \& $1 =~ tr/o/e/;
448 \& }
449 .Ve
450 .PP
451 Perl\*(Aqs own engine will croak on any attempt to modify the capture
452 variables, to do this in another engine use the following callback
453 (copied from \f(CW\*(C`Perl_reg_numbered_buff_store\*(C'\fR):
454 .PP
455 .Vb 9
456 \& void
457 \& Example_reg_numbered_buff_store(pTHX_
458 \& REGEXP * const rx,
459 \& const I32 paren,
460 \& SV const * const value)
461 \& {
462 \& PERL_UNUSED_ARG(rx);
463 \& PERL_UNUSED_ARG(paren);
464 \& PERL_UNUSED_ARG(value);
465 \&
466 \& if (!PL_localizing)
467 \& Perl_croak(aTHX_ PL_no_modify);
468 \& }
469 .Ve
470 .PP
471 Actually Perl will not \fIalways\fR croak in a statement that looks
472 like it would modify a numbered capture variable. This is because the
473 STORE callback will not be called if Perl can determine that it
474 doesn\*(Aqt have to modify the value. This is exactly how tied variables
475 behave in the same situation:
476 .PP
477 .Vb 2
478 \& package CaptureVar;
479 \& use parent \*(AqTie::Scalar\*(Aq;
480 \&
481 \& sub TIESCALAR { bless [] }
482 \& sub FETCH { undef }
483 \& sub STORE { die "This doesn\*(Aqt get called" }
484 \&
485 \& package main;
486 \&
487 \& tie my $sv => "CaptureVar";
488 \& $sv =~ y/a/b/;
489 .Ve
490 .PP
491 Because \f(CW$sv\fR is \f(CW\*(C`undef\*(C'\fR when the \f(CW\*(C`y///\*(C'\fR operator is applied to it,
492 the transliteration won\*(Aqt actually execute and the program won\*(Aqt
493 \&\f(CW\*(C`die\*(C'\fR. This is different to how 5.8 and earlier versions behaved
494 since the capture variables were READONLY variables then; now they\*(Aqll
495 just die when assigned to in the default engine.
496 .PP
497 \fInumbered_buff_LENGTH\fR
498 .IX Subsection "numbered_buff_LENGTH"
499 .PP
500 .Vb 4
501 \& I32 numbered_buff_LENGTH (pTHX_
502 \& REGEXP * const rx,
503 \& const SV * const sv,
504 \& const I32 paren);
505 .Ve
506 .PP
507 Get the \f(CW\*(C`length\*(C'\fR of a capture variable. There\*(Aqs a special callback
508 for this so that Perl doesn\*(Aqt have to do a FETCH and run \f(CW\*(C`length\*(C'\fR on
509 the result, since the length is (in Perl\*(Aqs case) known from an offset
510 stored in \f(CW\*(C`rx\->offs\*(C'\fR, this is much more efficient:
511 .PP
512 .Vb 3
513 \& I32 s1 = rx\->offs[paren].start;
514 \& I32 s2 = rx\->offs[paren].end;
515 \& I32 len = t1 \- s1;
516 .Ve
517 .PP
518 This is a little bit more complex in the case of UTF\-8, see what
519 \&\f(CW\*(C`Perl_reg_numbered_buff_length\*(C'\fR does with
520 is_utf8_string_loclen.
521 .SS "Named capture callbacks"
522 .IX Subsection "Named capture callbacks"
523 Called to get/set the value of \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR, as well as by some
524 utility functions in re.
525 .PP
526 There are two callbacks, \f(CW\*(C`named_buff\*(C'\fR is called in all the cases the
527 FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR Tie::Hash callbacks
528 would be on changes to \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR and \f(CW\*(C`named_buff_iter\*(C'\fR in the
529 same cases as FIRSTKEY and NEXTKEY.
530 .PP
531 The \f(CW\*(C`flags\*(C'\fR parameter can be used to determine which of these
532 operations the callbacks should respond to. The following flags are
533 currently defined:
534 .PP
535 Which Tie::Hash operation is being performed from the Perl level on
536 \&\f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%+\*(C'\fR, if any:
537 .PP
538 .Vb 8
539 \& RXapif_FETCH
540 \& RXapif_STORE
541 \& RXapif_DELETE
542 \& RXapif_CLEAR
543 \& RXapif_EXISTS
544 \& RXapif_SCALAR
545 \& RXapif_FIRSTKEY
546 \& RXapif_NEXTKEY
547 .Ve
548 .PP
549 If \f(CW\*(C`%+\*(C'\fR or \f(CW\*(C`%\-\*(C'\fR is being operated on, if any.
550 .PP
551 .Vb 2
552 \& RXapif_ONE /* %+ */
553 \& RXapif_ALL /* %\- */
554 .Ve
555 .PP
556 If this is being called as \f(CW\*(C`re::regname\*(C'\fR, \f(CW\*(C`re::regnames\*(C'\fR or
557 \&\f(CW\*(C`re::regnames_count\*(C'\fR, if any. The first two will be combined with
558 \&\f(CW\*(C`RXapif_ONE\*(C'\fR or \f(CW\*(C`RXapif_ALL\*(C'\fR.
559 .PP
560 .Vb 3
561 \& RXapif_REGNAME
562 \& RXapif_REGNAMES
563 \& RXapif_REGNAMES_COUNT
564 .Ve
565 .PP
566 Internally \f(CW\*(C`%+\*(C'\fR and \f(CW\*(C`%\-\*(C'\fR are implemented with a real tied interface
567 via Tie::Hash::NamedCapture. The methods in that package will call
568 back into these functions. However the usage of
569 Tie::Hash::NamedCapture for this purpose might change in future
570 releases. For instance this might be implemented by magic instead
571 (would need an extension to mgvtbl).
572 .PP
573 \fInamed_buff\fR
574 .IX Subsection "named_buff"
575 .PP
576 .Vb 2
577 \& SV* (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
578 \& SV * const value, U32 flags);
579 .Ve
580 .PP
581 \fInamed_buff_iter\fR
582 .IX Subsection "named_buff_iter"
583 .PP
584 .Vb 4
585 \& SV* (*named_buff_iter) (pTHX_
586 \& REGEXP * const rx,
587 \& const SV * const lastkey,
588 \& const U32 flags);
589 .Ve
590 .SS qr_package
591 .IX Subsection "qr_package"
592 .Vb 1
593 \& SV* qr_package(pTHX_ REGEXP * const rx);
594 .Ve
595 .PP
596 The package the qr// magic object is blessed into (as seen by \f(CW\*(C`ref
597 qr//\*(C'\fR). It is recommended that engines change this to their package
598 name for identification regardless of if they implement methods
599 on the object.
600 .PP
601 The package this method returns should also have the internal
602 \&\f(CW\*(C`Regexp\*(C'\fR package in its \f(CW@ISA\fR. \f(CW\*(C`qr//\->isa("Regexp")\*(C'\fR should always
603 be true regardless of what engine is being used.
604 .PP
605 Example implementation might be:
606 .PP
607 .Vb 6
608 \& SV*
609 \& Example_qr_package(pTHX_ REGEXP * const rx)
610 \& {
611 \& PERL_UNUSED_ARG(rx);
612 \& return newSVpvs("re::engine::Example");
613 \& }
614 .Ve
615 .PP
616 Any method calls on an object created with \f(CW\*(C`qr//\*(C'\fR will be dispatched to the
617 package as a normal object.
618 .PP
619 .Vb 3
620 \& use re::engine::Example;
621 \& my $re = qr//;
622 \& $re\->meth; # dispatched to re::engine::Example::meth()
623 .Ve
624 .PP
625 To retrieve the \f(CW\*(C`REGEXP\*(C'\fR object from the scalar in an XS function use
626 the \f(CW\*(C`SvRX\*(C'\fR macro, see "REGEXP Functions" in perlapi.
627 .PP
628 .Vb 3
629 \& void meth(SV * rv)
630 \& PPCODE:
631 \& REGEXP * re = SvRX(sv);
632 .Ve
633 .SS dupe
634 .IX Subsection "dupe"
635 .Vb 1
636 \& void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
637 .Ve
638 .PP
639 On threaded builds a regexp may need to be duplicated so that the pattern
640 can be used by multiple threads. This routine is expected to handle the
641 duplication of any private data pointed to by the \f(CW\*(C`pprivate\*(C'\fR member of
642 the \f(CW\*(C`regexp\*(C'\fR structure. It will be called with the preconstructed new
643 \&\f(CW\*(C`regexp\*(C'\fR structure as an argument, the \f(CW\*(C`pprivate\*(C'\fR member will point at
644 the \fBold\fR private structure, and it is this routine\*(Aqs responsibility to
645 construct a copy and return a pointer to it (which Perl will then use to
646 overwrite the field as passed to this routine.)
647 .PP
648 This allows the engine to dupe its private data but also if necessary
649 modify the final structure if it really must.
650 .PP
651 On unthreaded builds this field doesn\*(Aqt exist.
652 .SS op_comp
653 .IX Subsection "op_comp"
654 This is private to the Perl core and subject to change. Should be left
655 null.
656 .SH "The REGEXP structure"
657 .IX Header "The REGEXP structure"
658 The REGEXP struct is defined in \fIregexp.h\fR.
659 All regex engines must be able to
660 correctly build such a structure in their "comp" routine.
661 .PP
662 The REGEXP structure contains all the data that Perl needs to be aware of
663 to properly work with the regular expression. It includes data about
664 optimisations that Perl can use to determine if the regex engine should
665 really be used, and various other control info that is needed to properly
666 execute patterns in various contexts, such as if the pattern anchored in
667 some way, or what flags were used during the compile, or if the
668 program contains special constructs that Perl needs to be aware of.
669 .PP
670 In addition it contains two fields that are intended for the private
671 use of the regex engine that compiled the pattern. These are the
672 \&\f(CW\*(C`intflags\*(C'\fR and \f(CW\*(C`pprivate\*(C'\fR members. \f(CW\*(C`pprivate\*(C'\fR is a void pointer to
673 an arbitrary structure, whose use and management is the responsibility
674 of the compiling engine. Perl will never modify either of these
675 values.
676 .PP
677 .Vb 6
678 \& /* copied from: regexp.h */
679 \& typedef struct regexp {
680 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
681 \& * Fields required for compatibility with SV types
682 \& */
683 \& _XPV_HEAD;
684 \&
685 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
686 \& * Operational fields
687 \& */
688 \& const struct regexp_engine* engine; /* what engine created this regexp? */
689 \& REGEXP *mother_re; /* what re is this a lightweight copy of? */
690 \& HV *paren_names; /* Optional hash of paren names */
691 \&
692 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
693 \& * Information about the match that the perl core uses to manage things
694 \& */
695 \&
696 \& /* see comment in regcomp_internal.h about branch reset to understand
697 \& the distinction between physical and logical capture buffers */
698 \& U32 nparens; /* physical number of capture buffers */
699 \& U32 logical_nparens; /* logical_number of capture buffers */
700 \& I32 *logical_to_parno; /* map logical parno to first physical */
701 \& I32 *parno_to_logical; /* map every physical parno to logical */
702 \& I32 *parno_to_logical_next; /* map every physical parno to the next
703 \& physical with the same logical id */
704 \&
705 \& SSize_t maxlen; /* maximum possible number of chars in string to match */
706 \& SSize_t minlen; /* minimum possible number of chars in string to match */
707 \& SSize_t minlenret; /* minimum possible number of chars in $& */
708 \& STRLEN gofs; /* chars left of pos that we search from */
709 \& /* substring data about strings that must appear in
710 \& * the final match, used for optimisations */
711 \&
712 \& struct reg_substr_data *substrs;
713 \&
714 \& /* private engine specific data */
715 \&
716 \& void *pprivate; /* Data private to the regex engine which
717 \& * created this object. */
718 \& U32 extflags; /* Flags used both externally and internally */
719 \& U32 intflags; /* Engine Specific Internal flags */
720 \&
721 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
722 \& * Data about the last/current match. These are modified during matching
723 \& */
724 \&
725 \& U32 lastparen; /* highest close paren matched ($+) */
726 \& U32 lastcloseparen; /* last close paren matched ($^N) */
727 \& regexp_paren_pair *offs; /* Array of offsets for (@\-) and (@+) */
728 \& char **recurse_locinput; /* used to detect infinite recursion, XXX: move to internal */
729 \&
730 \&
731 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- */
732 \&
733 \& /* offset from wrapped to the start of precomp */
734 \& PERL_BITFIELD32 pre_prefix:4;
735 \&
736 \& /* original flags used to compile the pattern, may differ from
737 \& * extflags in various ways */
738 \& PERL_BITFIELD32 compflags:9;
739 \&
740 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- */
741 \&
742 \& char *subbeg; /* saved or original string so \edigit works forever. */
743 \& SV_SAVED_COPY /* If non\-NULL, SV which is COW from original */
744 \& SSize_t sublen; /* Length of string pointed by subbeg */
745 \& SSize_t suboffset; /* byte offset of subbeg from logical start of str */
746 \& SSize_t subcoffset; /* suboffset equiv, but in chars (for @\-/@+) */
747 \&
748 \& /*\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
749 \& * More Operational fields
750 \& */
751 \&
752 \& CV *qr_anoncv; /* the anon sub wrapped round qr/(?{..})/ */
753 \& } regexp;
754 .Ve
755 .PP
756 Most of the fields contained in this structure are accessed via macros
757 with a prefix of \f(CW\*(C`RX_\*(C'\fR or \f(CW\*(C`RXp_\*(C'\fR. The fields are discussed in more detail
758 below:
759 .ie n .SS """engine"""
760 .el .SS \f(CWengine\fP
761 .IX Subsection "engine"
762 This field points at a \f(CW\*(C`regexp_engine\*(C'\fR structure which contains pointers
763 to the subroutines that are to be used for performing a match. It
764 is the compiling routine\*(Aqs responsibility to populate this field before
765 returning the regexp object.
766 .PP
767 Internally this is set to \f(CW\*(C`NULL\*(C'\fR unless a custom engine is specified in
768 \&\f(CW$^H{regcomp}\fR, Perl\*(Aqs own set of callbacks can be accessed in the struct
769 pointed to by \f(CW\*(C`RE_ENGINE_PTR\*(C'\fR.
770 .ie n .SS """mother_re"""
771 .el .SS \f(CWmother_re\fP
772 .IX Subsection "mother_re"
773 This is a pointer to another struct regexp which this one was derived
774 from. \f(CW\*(C`qr//\*(C'\fR objects means that the same regexp pattern can be used in
775 different contexts at the same time, and as long as match status
776 information is stored in the structure (there are plans to change this
777 eventually) we need to support having multiple copies of the structure
778 in use at the same time. The fields related to the regexp program itself
779 are copied from the mother_re, and owned by the mother_re, whereas the
780 match state variables are owned by the struct itself.
781 .ie n .SS """extflags"""
782 .el .SS \f(CWextflags\fP
783 .IX Subsection "extflags"
784 This will be used by Perl to see what flags the regexp was compiled
785 with, this will normally be set to the value of the flags parameter by
786 the comp callback. See the comp documentation for
787 valid flags.
788 .ie n .SS """minlen"" ""minlenret"""
789 .el .SS "\f(CWminlen\fP \f(CWminlenret\fP"
790 .IX Subsection "minlen minlenret"
791 The minimum string length (in characters) required for the pattern to match.
792 This is used to
793 prune the search space by not bothering to match any closer to the end of a
794 string than would allow a match. For instance there is no point in even
795 starting the regex engine if the minlen is 10 but the string is only 5
796 characters long. There is no way that the pattern can match.
797 .PP
798 \&\f(CW\*(C`minlenret\*(C'\fR is the minimum length (in characters) of the string that would
799 be found in $& after a match.
800 .PP
801 The difference between \f(CW\*(C`minlen\*(C'\fR and \f(CW\*(C`minlenret\*(C'\fR can be seen in the
802 following pattern:
803 .PP
804 .Vb 1
805 \& /ns(?=\ed)/
806 .Ve
807 .PP
808 where the \f(CW\*(C`minlen\*(C'\fR would be 3 but \f(CW\*(C`minlenret\*(C'\fR would only be 2 as the \ed is
809 required to match but is not actually
810 included in the matched content. This
811 distinction is particularly important as the substitution logic uses the
812 \&\f(CW\*(C`minlenret\*(C'\fR to tell if it can do in\-place substitutions (these can
813 result in considerable speed\-up).
814 .ie n .SS """gofs"""
815 .el .SS \f(CWgofs\fP
816 .IX Subsection "gofs"
817 Left offset from \fBpos()\fR to start match at.
818 .ie n .SS """substrs"""
819 .el .SS \f(CWsubstrs\fP
820 .IX Subsection "substrs"
821 Substring data about strings that must appear in the final match. This
822 is currently only used internally by Perl\*(Aqs engine, but might be
823 used in the future for all engines for optimisations.
824 .ie n .SS """nparens"", ""logical_nparens"""
825 .el .SS "\f(CWnparens\fP, \f(CWlogical_nparens\fP"
826 .IX Subsection "nparens, logical_nparens"
827 These fields are used to keep track of the number of physical and logical
828 paren capture groups there are in the pattern, which may differ if the
829 pattern includes the use of the branch reset construct \f(CW\*(C`(?| ... | ... )\*(C'\fR.
830 For instance the pattern \f(CW\*(C`/(?|(foo)|(bar))/\*(C'\fR contains two physical capture
831 buffers, but only one logical capture buffer. Most internals logic in the
832 regex engine uses the physical capture buffer ids, but the user exposed
833 logic uses logical capture buffer ids. See the next section for data\-structures
834 that allow mapping from one to the other.
835 .ie n .SS """logical_to_parno"", ""parno_to_logical"", ""parno_to_logical_next"""
836 .el .SS "\f(CWlogical_to_parno\fP, \f(CWparno_to_logical\fP, \f(CWparno_to_logical_next\fP"
837 .IX Subsection "logical_to_parno, parno_to_logical, parno_to_logical_next"
838 These fields facilitate mapping between logical and physical capture
839 buffer numbers. \f(CW\*(C`logical_to_parno\*(C'\fR is an array whose Kth element
840 contains the lowest physical capture buffer id for the Kth logical
841 capture buffer. \f(CW\*(C`parno_to_logical\*(C'\fR is an array whose Kth element
842 contains the logical capture buffer associated with the Kth physical
843 capture buffer. \f(CW\*(C`parno_to_logical_next\*(C'\fR is an array whose Kth element
844 contains the next physical capture buffer with the same logical id, or 0
845 if there is none.
846 .PP
847 Note that all three of these arrays are ONLY populated when the pattern
848 includes the use of the branch reset concept. Patterns which do not use
849 branch\-reset effectively have a 1:1 to mapping between logical and
850 physical so there is no need for this meta\-data.
851 .PP
852 The following table gives an example of how this works.
853 .PP
854 .Vb 4
855 \& Pattern /(a) (?| (b) (c) (d) | (e) (f) | (g) ) (h)/
856 \& Logical: $1 $2 $3 $4 $2 $3 $2 $5
857 \& Physical: 1 2 3 4 5 6 7 8
858 \& Next: 0 5 6 0 7 0 0 0
859 .Ve
860 .PP
861 Also note that the 0th element of any of these arrays is not used as it
862 represents the "entire pattern".
863 .ie n .SS """lastparen"", and ""lastcloseparen"""
864 .el .SS "\f(CWlastparen\fP, and \f(CWlastcloseparen\fP"
865 .IX Subsection "lastparen, and lastcloseparen"
866 These fields are used to keep track of: which was the highest paren to
867 be closed (see "$+" in perlvar); and which was the most recent paren to be
868 closed (see "$^N" in perlvar).
869 .ie n .SS """intflags"""
870 .el .SS \f(CWintflags\fP
871 .IX Subsection "intflags"
872 The engine\*(Aqs private copy of the flags the pattern was compiled with. Usually
873 this is the same as \f(CW\*(C`extflags\*(C'\fR unless the engine chose to modify one of them.
874 .ie n .SS """pprivate"""
875 .el .SS \f(CWpprivate\fP
876 .IX Subsection "pprivate"
877 A void* pointing to an engine\-defined
878 data structure. The Perl engine uses the
879 \&\f(CW\*(C`regexp_internal\*(C'\fR structure (see "Base Structures" in perlreguts) but a custom
880 engine should use something else.
881 .ie n .SS """offs"""
882 .el .SS \f(CWoffs\fP
883 .IX Subsection "offs"
884 A \f(CW\*(C`regexp_paren_pair\*(C'\fR structure which defines offsets into the string being
885 matched which correspond to the \f(CW$&\fR and \f(CW$1\fR, \f(CW$2\fR etc. captures, the
886 \&\f(CW\*(C`regexp_paren_pair\*(C'\fR struct is defined as follows:
887 .PP
888 .Vb 4
889 \& typedef struct regexp_paren_pair {
890 \& I32 start;
891 \& I32 end;
892 \& } regexp_paren_pair;
893 .Ve
894 .PP
895 If \f(CW\*(C`\->offs[num].start\*(C'\fR or \f(CW\*(C`\->offs[num].end\*(C'\fR is \f(CW\-1\fR then that
896 capture group did not match.
897 \&\f(CW\*(C`\->offs[0].start/end\*(C'\fR represents \f(CW$&\fR (or
898 \&\f(CW\*(C`${^MATCH}\*(C'\fR under \f(CW\*(C`/p\*(C'\fR) and \f(CW\*(C`\->offs[paren].end\*(C'\fR matches \f(CW$$paren\fR where
899 \&\f(CW$paren \fR= 1>.
900 .ie n .SS """RX_PRECOMP"" ""RX_PRELEN"""
901 .el .SS "\f(CWRX_PRECOMP\fP \f(CWRX_PRELEN\fP"
902 .IX Subsection "RX_PRECOMP RX_PRELEN"
903 Used for optimisations. \f(CW\*(C`RX_PRECOMP\*(C'\fR holds a copy of the pattern that
904 was compiled and \f(CW\*(C`RX_PRELEN\*(C'\fR its length. When a new pattern is to be
905 compiled (such as inside a loop) the internal \f(CW\*(C`regcomp\*(C'\fR operator
906 checks if the last compiled \f(CW\*(C`REGEXP\*(C'\fR\*(Aqs \f(CW\*(C`RX_PRECOMP\*(C'\fR and \f(CW\*(C`RX_PRELEN\*(C'\fR
907 are equivalent to the new one, and if so uses the old pattern instead
908 of compiling a new one.
909 .PP
910 In older perls these two macros were actually fields in the structure
911 with the names \f(CW\*(C`precomp\*(C'\fR and \f(CW\*(C`prelen\*(C'\fR respectively.
912 .ie n .SS """paren_names"""
913 .el .SS \f(CWparen_names\fP
914 .IX Subsection "paren_names"
915 This is a hash used internally to track named capture groups and their
916 offsets. The keys are the names of the buffers the values are dualvars,
917 with the IV slot holding the number of buffers with the given name and the
918 pv being an embedded array of I32. The values may also be contained
919 independently in the data array in cases where named backreferences are
920 used.
921 .ie n .SS """substrs"""
922 .el .SS \f(CWsubstrs\fP
923 .IX Subsection "substrs"
924 Holds information on the longest string that must occur at a fixed
925 offset from the start of the pattern, and the longest string that must
926 occur at a floating offset from the start of the pattern. Used to do
927 Fast\-Boyer\-Moore searches on the string to find out if its worth using
928 the regex engine at all, and if so where in the string to search.
929 .ie n .SS """subbeg"" ""sublen"" ""saved_copy"" ""suboffset"" ""subcoffset"""
930 .el .SS "\f(CWsubbeg\fP \f(CWsublen\fP \f(CWsaved_copy\fP \f(CWsuboffset\fP \f(CWsubcoffset\fP"
931 .IX Subsection "subbeg sublen saved_copy suboffset subcoffset"
932 Used during the execution phase for managing search and replace patterns,
933 and for providing the text for \f(CW$&\fR, \f(CW$1\fR etc. \f(CW\*(C`subbeg\*(C'\fR points to a
934 buffer (either the original string, or a copy in the case of
935 \&\f(CWRX_MATCH_COPIED(rx_sv)\fR), and \f(CW\*(C`sublen\*(C'\fR is the length of the buffer. The
936 \&\f(CW\*(C`RX_OFFS_START(rx_sv,n)\*(C'\fR and \f(CW\*(C`RX_OFFS_END(rx_sv,n)\*(C'\fR macros index into this
937 buffer. as does the data structure returned by \f(CWRX_OFFSp(rx_sv)\fR but you
938 should not use that directly.
939 .PP
940 In the presence of the \f(CW\*(C`REXEC_COPY_STR\*(C'\fR flag, but with the addition of
941 the \f(CW\*(C`REXEC_COPY_SKIP_PRE\*(C'\fR or \f(CW\*(C`REXEC_COPY_SKIP_POST\*(C'\fR flags, an engine
942 can choose not to copy the full buffer (although it must still do so in
943 the presence of \f(CW\*(C`RXf_PMf_KEEPCOPY\*(C'\fR or the relevant bits being set in
944 \&\f(CW\*(C`PL_sawampersand\*(C'\fR). In this case, it may set \f(CW\*(C`suboffset\*(C'\fR to indicate the
945 number of bytes from the logical start of the buffer to the physical start
946 (i.e. \f(CW\*(C`subbeg\*(C'\fR). It should also set \f(CW\*(C`subcoffset\*(C'\fR, the number of
947 characters in the offset. The latter is needed to support \f(CW\*(C`@\-\*(C'\fR and \f(CW\*(C`@+\*(C'\fR
948 which work in characters, not bytes.
949 .ie n .SS """RX_WRAPPED"" ""RX_WRAPLEN"""
950 .el .SS "\f(CWRX_WRAPPED\fP \f(CWRX_WRAPLEN\fP"
951 .IX Subsection "RX_WRAPPED RX_WRAPLEN"
952 Macros which access the string the \f(CW\*(C`qr//\*(C'\fR stringifies to. The Perl
953 engine for example stores \f(CW\*(C`(?^:eek)\*(C'\fR in the case of \f(CW\*(C`qr/eek/\*(C'\fR.
954 .PP
955 When using a custom engine that doesn\*(Aqt support the \f(CW\*(C`(?:)\*(C'\fR construct
956 for inline modifiers, it\*(Aqs probably best to have \f(CW\*(C`qr//\*(C'\fR stringify to
957 the supplied pattern, note that this will create undesired patterns in
958 cases such as:
959 .PP
960 .Vb 3
961 \& my $x = qr/a|b/; # "a|b"
962 \& my $y = qr/c/i; # "c"
963 \& my $z = qr/$x$y/; # "a|bc"
964 .Ve
965 .PP
966 There\*(Aqs no solution for this problem other than making the custom
967 engine understand a construct like \f(CW\*(C`(?:)\*(C'\fR.
968 .ie n .SS RX_REFCNT()
969 .el .SS \f(CWRX_REFCNT()\fP
970 .IX Subsection "RX_REFCNT()"
971 The number of times the structure is referenced. When this falls to 0,
972 the regexp is automatically freed by a call to \f(CW\*(C`pregfree\*(C'\fR. This should
973 be set to 1 in each engine\*(Aqs "comp" routine. Note that in older perls
974 this was a member in the struct called \f(CW\*(C`refcnt\*(C'\fR but in more modern
975 perls where the regexp structure was unified with the SV structure this
976 is an alias to \fBSvREFCNT()\fR.
977 .SH HISTORY
978 .IX Header "HISTORY"
979 Originally part of perlreguts.
980 .SH AUTHORS
981 .IX Header "AUTHORS"
982 Originally written by Yves Orton, expanded by Ævar Arnfjörð
983 Bjarmason.
984 .SH LICENSE
985 .IX Header "LICENSE"
986 Copyright 2006 Yves Orton and 2007 Ævar Arnfjörð Bjarmason.
987 .PP
988 This program is free software; you can redistribute it and/or modify it under
989 the same terms as Perl itself.