Debian Codegraph @

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