Debian Codegraph @

upstream/fedora-44/man1/perlreref.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 "PERLREREF 1"
61 .TH PERLREREF 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 perlreref \- Perl Regular Expressions Reference
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This is a quick reference to Perl\*(Aqs regular expressions.
71 For full information see perlre and perlop, as well
72 as the "SEE ALSO" section in this document.
73 .SS OPERATORS
74 .IX Subsection "OPERATORS"
75 \&\f(CW\*(C`=~\*(C'\fR determines to which variable the regex is applied.
76 In its absence, \f(CW$_\fR is used.
77 .PP
78 .Vb 1
79 \& $var =~ /foo/;
80 .Ve
81 .PP
82 \&\f(CW\*(C`!~\*(C'\fR determines to which variable the regex is applied,
83 and negates the result of the match; it returns
84 false if the match succeeds, and true if it fails.
85 .PP
86 .Vb 1
87 \& $var !~ /foo/;
88 .Ve
89 .PP
90 \&\f(CW\*(C`m/pattern/msixpogcdualn\*(C'\fR searches a string for a pattern match,
91 applying the given options.
92 .PP
93 .Vb 10
94 \& m Multiline mode \- ^ and $ match internal lines
95 \& s match as a Single line \- . matches \en
96 \& i case\-Insensitive
97 \& x eXtended legibility \- free whitespace and comments
98 \& p Preserve a copy of the matched string \-
99 \& ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
100 \& o compile pattern Once
101 \& g Global \- all occurrences
102 \& c don\*(Aqt reset pos on failed matches when using /g
103 \& a restrict \ed, \es, \ew and [:posix:] to match ASCII only
104 \& aa (two a\*(Aqs) also /i matches exclude ASCII/non\-ASCII
105 \& l match according to current locale
106 \& u match according to Unicode rules
107 \& d match according to native rules unless something indicates
108 \& Unicode
109 \& n Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
110 .Ve
111 .PP
112 If \*(Aqpattern\*(Aq is an empty string, the last \fIsuccessfully\fR matched
113 regex is used. Delimiters other than \*(Aq/\*(Aq may be used for both this
114 operator and the following ones. The leading \f(CW\*(C`m\*(C'\fR can be omitted
115 if the delimiter is \*(Aq/\*(Aq.
116 .PP
117 \&\f(CW\*(C`qr/pattern/msixpodualn\*(C'\fR lets you store a regex in a variable,
118 or pass one around. Modifiers as for \f(CW\*(C`m//\*(C'\fR, and are stored
119 within the regex.
120 .PP
121 \&\f(CW\*(C`s/pattern/replacement/msixpogcedual\*(C'\fR substitutes matches of
122 \&\*(Aqpattern\*(Aq with \*(Aqreplacement\*(Aq. Modifiers as for \f(CW\*(C`m//\*(C'\fR,
123 with two additions:
124 .PP
125 .Vb 2
126 \& e Evaluate \*(Aqreplacement\*(Aq as an expression
127 \& r Return substitution and leave the original string untouched.
128 .Ve
129 .PP
130 \&\*(Aqe\*(Aq may be specified multiple times. \*(Aqreplacement\*(Aq is interpreted
131 as a double quoted string unless a single\-quote (\f(CW\*(C`\*(Aq\*(C'\fR) is the delimiter.
132 .PP
133 \&\f(CW\*(C`m?pattern?\*(C'\fR is like \f(CW\*(C`m/pattern/\*(C'\fR but matches only once. No alternate
134 delimiters can be used. Must be reset with \fBreset()\fR.
135 .SS SYNTAX
136 .IX Subsection "SYNTAX"
137 .Vb 10
138 \& \e Escapes the character immediately following it
139 \& . Matches any single character except a newline (unless /s is
140 \& used)
141 \& ^ Matches at the beginning of the string (or line, if /m is used)
142 \& $ Matches at the end of the string (or line, if /m is used)
143 \& * Matches the preceding element 0 or more times
144 \& + Matches the preceding element 1 or more times
145 \& ? Matches the preceding element 0 or 1 times
146 \& {...} Specifies a range of occurrences for the element preceding it
147 \& [...] Matches any one of the characters contained within the brackets
148 \& (...) Groups subexpressions for capturing to $1, $2...
149 \& (?:...) Groups subexpressions without capturing (cluster)
150 \& | Matches either the subexpression preceding or following it
151 \& \eg1 or \eg{1}, \eg2 ... Matches the text from the Nth group
152 \& \e1, \e2, \e3 ... Matches the text from the Nth group
153 \& \eg\-1 or \eg{\-1}, \eg\-2 ... Matches the text from the Nth previous group
154 \& \eg{name} Named backreference
155 \& \ek<name> Named backreference
156 \& \ek\*(Aqname\*(Aq Named backreference
157 \& (?P=name) Named backreference (python syntax)
158 .Ve
159 .SS "ESCAPE SEQUENCES"
160 .IX Subsection "ESCAPE SEQUENCES"
161 These work as in normal strings.
162 .PP
163 .Vb 10
164 \& \ea Alarm (beep)
165 \& \ee Escape
166 \& \ef Formfeed
167 \& \en Newline
168 \& \er Carriage return
169 \& \et Tab
170 \& \e037 Char whose ordinal is the 3 octal digits, max \e777
171 \& \eo{2307} Char whose ordinal is the octal number, unrestricted
172 \& \ex7f Char whose ordinal is the 2 hex digits, max \exFF
173 \& \ex{263a} Char whose ordinal is the hex number, unrestricted
174 \& \ecx Control\-x
175 \& \eN{name} A named Unicode character or character sequence
176 \& \eN{U+263D} A Unicode character by hex ordinal
177 \&
178 \& \el Lowercase next character
179 \& \eu Titlecase next character
180 \& \eL Lowercase until \eE
181 \& \eU Uppercase until \eE
182 \& \eF Foldcase until \eE
183 \& \eQ Disable pattern metacharacters until \eE
184 \& \eE End modification
185 .Ve
186 .PP
187 For Titlecase, see "Titlecase".
188 .PP
189 This one works differently from normal strings:
190 .PP
191 .Vb 1
192 \& \eb An assertion, not backspace, except in a character class
193 .Ve
194 .SS "CHARACTER CLASSES"
195 .IX Subsection "CHARACTER CLASSES"
196 .Vb 4
197 \& [amy] Match \*(Aqa\*(Aq, \*(Aqm\*(Aq or \*(Aqy\*(Aq
198 \& [f\-j] Dash specifies "range"
199 \& [f\-j\-] Dash escaped or at start or end means \*(Aqdash\*(Aq
200 \& [^f\-j] Caret indicates "match any character _except_ these"
201 .Ve
202 .PP
203 The following sequences (except \f(CW\*(C`\eN\*(C'\fR) work within or without a character class.
204 The first six are locale aware, all are Unicode aware. See perllocale
205 and perlunicode for details.
206 .PP
207 .Vb 10
208 \& \ed A digit
209 \& \eD A nondigit
210 \& \ew A word character
211 \& \eW A non\-word character
212 \& \es A whitespace character
213 \& \eS A non\-whitespace character
214 \& \eh A horizontal whitespace
215 \& \eH A non horizontal whitespace
216 \& \eN A non newline (when not followed by \*(Aq{NAME}\*(Aq;;
217 \& not valid in a character class; equivalent to [^\en]; it\*(Aqs
218 \& like \*(Aq.\*(Aq without /s modifier)
219 \& \ev A vertical whitespace
220 \& \eV A non vertical whitespace
221 \& \eR A generic newline (?>\ex0D\ex0A|\ev)
222 \&
223 \& \epP Match P\-named (Unicode) property
224 \& \ep{...} Match Unicode property with name longer than 1 character
225 \& \ePP Match non\-P
226 \& \eP{...} Match lack of Unicode property with name longer than 1 char
227 \& \eX Match Unicode extended grapheme cluster
228 .Ve
229 .PP
230 POSIX character classes and their Unicode and Perl equivalents:
231 .PP
232 .Vb 3
233 \& ASCII\- Full\-
234 \& POSIX range range backslash
235 \& [[:...:]] \ep{...} \ep{...} sequence Description
236 \&
237 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
238 \& alnum PosixAlnum XPosixAlnum \*(Aqalpha\*(Aq plus \*(Aqdigit\*(Aq
239 \& alpha PosixAlpha XPosixAlpha Alphabetic characters
240 \& ascii ASCII Any ASCII character
241 \& blank PosixBlank XPosixBlank \eh Horizontal whitespace;
242 \& full\-range also
243 \& written as
244 \& \ep{HorizSpace}
245 \& cntrl PosixCntrl XPosixCntrl Control characters
246 \& digit PosixDigit XPosixDigit \ed Decimal digits
247 \& graph PosixGraph XPosixGraph \*(Aqalnum\*(Aq plus \*(Aqpunct\*(Aq
248 \& lower PosixLower XPosixLower Lowercase characters
249 \& print PosixPrint XPosixPrint \*(Aqgraph\*(Aq plus \*(Aqspace\*(Aq,
250 \& but not any Controls
251 \& punct PosixPunct XPosixPunct Punctuation and Symbols
252 \& in ASCII\-range; just
253 \& punct outside it
254 \& space PosixSpace XPosixSpace \es Whitespace
255 \& upper PosixUpper XPosixUpper Uppercase characters
256 \& word PosixWord XPosixWord \ew \*(Aqalnum\*(Aq + Unicode marks
257 \& + connectors, like
258 \& \*(Aq_\*(Aq (Perl extension)
259 \& xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit,
260 \& ASCII\-range is
261 \& [0\-9A\-Fa\-f]
262 .Ve
263 .PP
264 Also, various synonyms like \f(CW\*(C`\ep{Alpha}\*(C'\fR for \f(CW\*(C`\ep{XPosixAlpha}\*(C'\fR; all listed
265 in "Properties accessible through \ep{} and \eP{}" in perluniprops
266 .PP
267 Within a character class:
268 .PP
269 .Vb 3
270 \& POSIX traditional Unicode
271 \& [:digit:] \ed \ep{Digit}
272 \& [:^digit:] \eD \eP{Digit}
273 .Ve
274 .SS ANCHORS
275 .IX Subsection "ANCHORS"
276 All are zero\-width assertions.
277 .PP
278 .Vb 11
279 \& ^ Match string start (or line, if /m is used)
280 \& $ Match string end (or line, if /m is used) or before newline
281 \& \eb{} Match boundary of type specified within the braces
282 \& \eB{} Match wherever \eb{} doesn\*(Aqt match
283 \& \eb Match word boundary (between \ew and \eW)
284 \& \eB Match except at word boundary (between \ew and \ew or \eW and \eW)
285 \& \eA Match string start (regardless of /m)
286 \& \eZ Match string end (before optional newline)
287 \& \ez Match absolute string end
288 \& \eG Match where previous m//g left off
289 \& \eK Keep the stuff left of the \eK, don\*(Aqt include it in $&
290 .Ve
291 .SS QUANTIFIERS
292 .IX Subsection "QUANTIFIERS"
293 Quantifiers are greedy by default and match the \fBlongest\fR leftmost.
294 .PP
295 .Vb 10
296 \& Maximal Minimal Possessive Allowed range
297 \& \-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-
298 \& {n,m} {n,m}? {n,m}+ Must occur at least n times
299 \& but no more than m times
300 \& {n,} {n,}? {n,}+ Must occur at least n times
301 \& {,n} {,n}? {,n}+ Must occur at most n times
302 \& {n} {n}? {n}+ Must occur exactly n times
303 \& * *? *+ 0 or more times (same as {0,})
304 \& + +? ++ 1 or more times (same as {1,})
305 \& ? ?? ?+ 0 or 1 time (same as {0,1})
306 .Ve
307 .PP
308 The possessive forms (new in Perl 5.10) prevent backtracking: what gets
309 matched by a pattern with a possessive quantifier will not be backtracked
310 into, even if that causes the whole match to fail.
311 .SS "EXTENDED CONSTRUCTS"
312 .IX Subsection "EXTENDED CONSTRUCTS"
313 .Vb 10
314 \& (?#text) A comment
315 \& (?:...) Groups subexpressions without capturing (cluster)
316 \& (?pimsx\-imsx:...) Enable/disable option (as per m// modifiers)
317 \& (?=...) Zero\-width positive lookahead assertion
318 \& (*pla:...) Same, starting in 5.32; experimentally in 5.28
319 \& (*positive_lookahead:...) Same, same versions as *pla
320 \& (?!...) Zero\-width negative lookahead assertion
321 \& (*nla:...) Same, starting in 5.32; experimentally in 5.28
322 \& (*negative_lookahead:...) Same, same versions as *nla
323 \& (?<=...) Zero\-width positive lookbehind assertion
324 \& (*plb:...) Same, starting in 5.32; experimentally in 5.28
325 \& (*positive_lookbehind:...) Same, same versions as *plb
326 \& (?<!...) Zero\-width negative lookbehind assertion
327 \& (*nlb:...) Same, starting in 5.32; experimentally in 5.28
328 \& (*negative_lookbehind:...) Same, same versions as *plb
329 \& (?>...) Grab what we can, prohibit backtracking
330 \& (*atomic:...) Same, starting in 5.32; experimentally in 5.28
331 \& (?|...) Branch reset
332 \& (?<name>...) Named capture
333 \& (?\*(Aqname\*(Aq...) Named capture
334 \& (?P<name>...) Named capture (python syntax)
335 \& (?[...]) Extended bracketed character class
336 \& (?{ code }) Embedded code, return value becomes $^R
337 \& (??{ code }) Dynamic regex, return value used as regex
338 \& (?N) Recurse into subpattern number N
339 \& (?\-N), (?+N) Recurse into Nth previous/next subpattern
340 \& (?R), (?0) Recurse at the beginning of the whole pattern
341 \& (?&name) Recurse into a named subpattern
342 \& (?P>name) Recurse into a named subpattern (python syntax)
343 \& (?(cond)yes|no)
344 \& (?(cond)yes) Conditional expression, where "(cond)" can be:
345 \& (?=pat) lookahead; also (*pla:pat)
346 \& (*positive_lookahead:pat)
347 \& (?!pat) negative lookahead; also (*nla:pat)
348 \& (*negative_lookahead:pat)
349 \& (?<=pat) lookbehind; also (*plb:pat)
350 \& (*lookbehind:pat)
351 \& (?<!pat) negative lookbehind; also (*nlb:pat)
352 \& (*negative_lookbehind:pat)
353 \& (N) subpattern N has matched something
354 \& (<name>) named subpattern has matched something
355 \& (\*(Aqname\*(Aq) named subpattern has matched something
356 \& (?{code}) code condition
357 \& (R) true if recursing
358 \& (RN) true if recursing into Nth subpattern
359 \& (R&name) true if recursing into named subpattern
360 \& (DEFINE) always false, no no\-pattern allowed
361 .Ve
362 .SS VARIABLES
363 .IX Subsection "VARIABLES"
364 .Vb 1
365 \& $_ Default variable for operators to use
366 \&
367 \& $\` Everything prior to matched string
368 \& $& Entire matched string
369 \& $\*(Aq Everything after to matched string
370 \&
371 \& ${^PREMATCH} Everything prior to matched string
372 \& ${^MATCH} Entire matched string
373 \& ${^POSTMATCH} Everything after to matched string
374 .Ve
375 .PP
376 Note to those still using Perl 5.18 or earlier:
377 The use of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR or \f(CW\*(C`$\*(Aq\*(C'\fR will slow down \fBall\fR regex use
378 within your program. Consult perlvar for \f(CW\*(C`@\-\*(C'\fR
379 to see equivalent expressions that won\*(Aqt cause slow down.
380 See also Devel::SawAmpersand. Starting with Perl 5.10, you
381 can also use the equivalent variables \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR
382 and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, but for them to be defined, you have to
383 specify the \f(CW\*(C`/p\*(C'\fR (preserve) modifier on your regular expression.
384 In Perl 5.20, the use of \f(CW\*(C`$\`\*(C'\fR, \f(CW$&\fR and \f(CW\*(C`$\*(Aq\*(C'\fR makes no speed difference.
385 .PP
386 .Vb 8
387 \& $1, $2 ... hold the Xth captured expr
388 \& $+ Last parenthesized pattern match
389 \& $^N Holds the most recently closed capture
390 \& $^R Holds the result of the last (?{...}) expr
391 \& @\- Offsets of starts of groups. $\-[0] holds start of whole match
392 \& @+ Offsets of ends of groups. $+[0] holds end of whole match
393 \& %+ Named capture groups
394 \& %\- Named capture groups, as array refs
395 .Ve
396 .PP
397 Captured groups are numbered according to their \fIopening\fR paren.
398 .SS FUNCTIONS
399 .IX Subsection "FUNCTIONS"
400 .Vb 5
401 \& lc Lowercase a string
402 \& lcfirst Lowercase first char of a string
403 \& uc Uppercase a string
404 \& ucfirst Titlecase first char of a string
405 \& fc Foldcase a string
406 \&
407 \& pos Return or set current match position
408 \& quotemeta Quote metacharacters (escape their normal meaning)
409 \& reset Reset m?pattern? status
410 \& study Analyze string for optimizing matching
411 \&
412 \& split Use a regex to split a string into parts
413 .Ve
414 .PP
415 The first five of these are like the escape sequences \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR,
416 \&\f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eF\*(C'\fR. For Titlecase, see "Titlecase"; For
417 Foldcase, see "Foldcase".
418 .SS TERMINOLOGY
419 .IX Subsection "TERMINOLOGY"
420 \fITitlecase\fR
421 .IX Subsection "Titlecase"
422 .PP
423 Unicode concept which most often is equal to uppercase, but for
424 certain characters like the German "sharp s" there is a difference.
425 .PP
426 \fIFoldcase\fR
427 .IX Subsection "Foldcase"
428 .PP
429 Unicode form that is useful when comparing strings regardless of case,
430 as certain characters have complex one\-to\-many case mappings. Primarily a
431 variant of lowercase.
432 .SH AUTHOR
433 .IX Header "AUTHOR"
434 Iain Truskett. Updated by the Perl 5 Porters.
435 .PP
436 This document may be distributed under the same terms as Perl itself.
437 .SH "SEE ALSO"
438 .IX Header "SEE ALSO"
439 .IP \(bu 4
440 perlretut for a tutorial on regular expressions.
441 .IP \(bu 4
442 perlrequick for a rapid tutorial.
443 .IP \(bu 4
444 perlre for more details.
445 .IP \(bu 4
446 perlvar for details on the variables.
447 .IP \(bu 4
448 perlop for details on the operators.
449 .IP \(bu 4
450 perlfunc for details on the functions.
451 .IP \(bu 4
452 perlfaq6 for FAQs on regular expressions.
453 .IP \(bu 4
454 perlrebackslash for a reference on backslash sequences.
455 .IP \(bu 4
456 perlrecharclass for a reference on character classes.
457 .IP \(bu 4
458 The re module to alter behaviour and aid
459 debugging.
460 .IP \(bu 4
461 "Debugging Regular Expressions" in perldebug
462 .IP \(bu 4
463 perluniintro, perlunicode, charnames and perllocale
464 for details on regexes and internationalisation.
465 .IP \(bu 4
466 \&\fIMastering Regular Expressions\fR by Jeffrey Friedl
467 (<https://www.oreilly.com/library/view/\-/0596528124/>) for a thorough grounding and
468 reference on the topic.
469 .SH THANKS
470 .IX Header "THANKS"
471 David P.C. Wollmann,
472 Richard Soderberg,
473 Sean M. Burke,
474 Tom Christiansen,
475 Jim Cromie,
476 and
477 Jeffrey Goff
478 for useful advice.