Debian Codegraph @

upstream/debian-unstable/man1/perlreapi.1

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