| Current File : //usr/local/apps/perl/man/man1/perlreref.1 |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PERLREREF 1"
.TH PERLREREF 1 "2019-05-11" "perl v5.30.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
perlreref \- Perl Regular Expressions Reference
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a quick reference to Perl's regular expressions.
For full information see perlre and perlop, as well
as the \*(L"\s-1SEE ALSO\*(R"\s0 section in this document.
.SS "\s-1OPERATORS\s0"
.IX Subsection "OPERATORS"
\&\f(CW\*(C`=~\*(C'\fR determines to which variable the regex is applied.
In its absence, \f(CW$_\fR is used.
.PP
.Vb 1
\& $var =~ /foo/;
.Ve
.PP
\&\f(CW\*(C`!~\*(C'\fR determines to which variable the regex is applied,
and negates the result of the match; it returns
false if the match succeeds, and true if it fails.
.PP
.Vb 1
\& $var !~ /foo/;
.Ve
.PP
\&\f(CW\*(C`m/pattern/msixpogcdualn\*(C'\fR searches a string for a pattern match,
applying the given options.
.PP
.Vb 10
\& m Multiline mode \- ^ and $ match internal lines
\& s match as a Single line \- . matches \en
\& i case\-Insensitive
\& x eXtended legibility \- free whitespace and comments
\& p Preserve a copy of the matched string \-
\& ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
\& o compile pattern Once
\& g Global \- all occurrences
\& c don\*(Aqt reset pos on failed matches when using /g
\& a restrict \ed, \es, \ew and [:posix:] to match ASCII only
\& aa (two a\*(Aqs) also /i matches exclude ASCII/non\-ASCII
\& l match according to current locale
\& u match according to Unicode rules
\& d match according to native rules unless something indicates
\& Unicode
\& n Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
.Ve
.PP
If 'pattern' is an empty string, the last \fIsuccessfully\fR matched
regex is used. Delimiters other than '/' may be used for both this
operator and the following ones. The leading \f(CW\*(C`m\*(C'\fR can be omitted
if the delimiter is '/'.
.PP
\&\f(CW\*(C`qr/pattern/msixpodualn\*(C'\fR lets you store a regex in a variable,
or pass one around. Modifiers as for \f(CW\*(C`m//\*(C'\fR, and are stored
within the regex.
.PP
\&\f(CW\*(C`s/pattern/replacement/msixpogcedual\*(C'\fR substitutes matches of
\&'pattern' with 'replacement'. Modifiers as for \f(CW\*(C`m//\*(C'\fR,
with two additions:
.PP
.Vb 2
\& e Evaluate \*(Aqreplacement\*(Aq as an expression
\& r Return substitution and leave the original string untouched.
.Ve
.PP
\&'e' may be specified multiple times. 'replacement' is interpreted
as a double quoted string unless a single-quote (\f(CW\*(C`\*(Aq\*(C'\fR) is the delimiter.
.PP
\&\f(CW\*(C`m?pattern?\*(C'\fR is like \f(CW\*(C`m/pattern/\*(C'\fR but matches only once. No alternate
delimiters can be used. Must be reset with \fBreset()\fR.
.SS "\s-1SYNTAX\s0"
.IX Subsection "SYNTAX"
.Vb 10
\& \e Escapes the character immediately following it
\& . Matches any single character except a newline (unless /s is
\& used)
\& ^ Matches at the beginning of the string (or line, if /m is used)
\& $ Matches at the end of the string (or line, if /m is used)
\& * Matches the preceding element 0 or more times
\& + Matches the preceding element 1 or more times
\& ? Matches the preceding element 0 or 1 times
\& {...} Specifies a range of occurrences for the element preceding it
\& [...] Matches any one of the characters contained within the brackets
\& (...) Groups subexpressions for capturing to $1, $2...
\& (?:...) Groups subexpressions without capturing (cluster)
\& | Matches either the subexpression preceding or following it
\& \eg1 or \eg{1}, \eg2 ... Matches the text from the Nth group
\& \e1, \e2, \e3 ... Matches the text from the Nth group
\& \eg\-1 or \eg{\-1}, \eg\-2 ... Matches the text from the Nth previous group
\& \eg{name} Named backreference
\& \ek<name> Named backreference
\& \ek\*(Aqname\*(Aq Named backreference
\& (?P=name) Named backreference (python syntax)
.Ve
.SS "\s-1ESCAPE SEQUENCES\s0"
.IX Subsection "ESCAPE SEQUENCES"
These work as in normal strings.
.PP
.Vb 10
\& \ea Alarm (beep)
\& \ee Escape
\& \ef Formfeed
\& \en Newline
\& \er Carriage return
\& \et Tab
\& \e037 Char whose ordinal is the 3 octal digits, max \e777
\& \eo{2307} Char whose ordinal is the octal number, unrestricted
\& \ex7f Char whose ordinal is the 2 hex digits, max \exFF
\& \ex{263a} Char whose ordinal is the hex number, unrestricted
\& \ecx Control\-x
\& \eN{name} A named Unicode character or character sequence
\& \eN{U+263D} A Unicode character by hex ordinal
\&
\& \el Lowercase next character
\& \eu Titlecase next character
\& \eL Lowercase until \eE
\& \eU Uppercase until \eE
\& \eF Foldcase until \eE
\& \eQ Disable pattern metacharacters until \eE
\& \eE End modification
.Ve
.PP
For Titlecase, see \*(L"Titlecase\*(R".
.PP
This one works differently from normal strings:
.PP
.Vb 1
\& \eb An assertion, not backspace, except in a character class
.Ve
.SS "\s-1CHARACTER CLASSES\s0"
.IX Subsection "CHARACTER CLASSES"
.Vb 4
\& [amy] Match \*(Aqa\*(Aq, \*(Aqm\*(Aq or \*(Aqy\*(Aq
\& [f\-j] Dash specifies "range"
\& [f\-j\-] Dash escaped or at start or end means \*(Aqdash\*(Aq
\& [^f\-j] Caret indicates "match any character _except_ these"
.Ve
.PP
The following sequences (except \f(CW\*(C`\eN\*(C'\fR) work within or without a character class.
The first six are locale aware, all are Unicode aware. See perllocale
and perlunicode for details.
.PP
.Vb 10
\& \ed A digit
\& \eD A nondigit
\& \ew A word character
\& \eW A non\-word character
\& \es A whitespace character
\& \eS A non\-whitespace character
\& \eh A horizontal whitespace
\& \eH A non horizontal whitespace
\& \eN A non newline (when not followed by \*(Aq{NAME}\*(Aq;;
\& not valid in a character class; equivalent to [^\en]; it\*(Aqs
\& like \*(Aq.\*(Aq without /s modifier)
\& \ev A vertical whitespace
\& \eV A non vertical whitespace
\& \eR A generic newline (?>\ev|\ex0D\ex0A)
\&
\& \epP Match P\-named (Unicode) property
\& \ep{...} Match Unicode property with name longer than 1 character
\& \ePP Match non\-P
\& \eP{...} Match lack of Unicode property with name longer than 1 char
\& \eX Match Unicode extended grapheme cluster
.Ve
.PP
\&\s-1POSIX\s0 character classes and their Unicode and Perl equivalents:
.PP
.Vb 3
\& ASCII\- Full\-
\& POSIX range range backslash
\& [[:...:]] \ep{...} \ep{...} sequence Description
\&
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& alnum PosixAlnum XPosixAlnum \*(Aqalpha\*(Aq plus \*(Aqdigit\*(Aq
\& alpha PosixAlpha XPosixAlpha Alphabetic characters
\& ascii ASCII Any ASCII character
\& blank PosixBlank XPosixBlank \eh Horizontal whitespace;
\& full\-range also
\& written as
\& \ep{HorizSpace} (GNU
\& extension)
\& cntrl PosixCntrl XPosixCntrl Control characters
\& digit PosixDigit XPosixDigit \ed Decimal digits
\& graph PosixGraph XPosixGraph \*(Aqalnum\*(Aq plus \*(Aqpunct\*(Aq
\& lower PosixLower XPosixLower Lowercase characters
\& print PosixPrint XPosixPrint \*(Aqgraph\*(Aq plus \*(Aqspace\*(Aq,
\& but not any Controls
\& punct PosixPunct XPosixPunct Punctuation and Symbols
\& in ASCII\-range; just
\& punct outside it
\& space PosixSpace XPosixSpace \es Whitespace
\& upper PosixUpper XPosixUpper Uppercase characters
\& word PosixWord XPosixWord \ew \*(Aqalnum\*(Aq + Unicode marks
\& + connectors, like
\& \*(Aq_\*(Aq (Perl extension)
\& xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit,
\& ASCII\-range is
\& [0\-9A\-Fa\-f]
.Ve
.PP
Also, various synonyms like \f(CW\*(C`\ep{Alpha}\*(C'\fR for \f(CW\*(C`\ep{XPosixAlpha}\*(C'\fR; all listed
in \*(L"Properties accessible through \ep{} and \eP{}\*(R" in perluniprops
.PP
Within a character class:
.PP
.Vb 3
\& POSIX traditional Unicode
\& [:digit:] \ed \ep{Digit}
\& [:^digit:] \eD \eP{Digit}
.Ve
.SS "\s-1ANCHORS\s0"
.IX Subsection "ANCHORS"
All are zero-width assertions.
.PP
.Vb 11
\& ^ Match string start (or line, if /m is used)
\& $ Match string end (or line, if /m is used) or before newline
\& \eb{} Match boundary of type specified within the braces
\& \eB{} Match wherever \eb{} doesn\*(Aqt match
\& \eb Match word boundary (between \ew and \eW)
\& \eB Match except at word boundary (between \ew and \ew or \eW and \eW)
\& \eA Match string start (regardless of /m)
\& \eZ Match string end (before optional newline)
\& \ez Match absolute string end
\& \eG Match where previous m//g left off
\& \eK Keep the stuff left of the \eK, don\*(Aqt include it in $&
.Ve
.SS "\s-1QUANTIFIERS\s0"
.IX Subsection "QUANTIFIERS"
Quantifiers are greedy by default and match the \fBlongest\fR leftmost.
.PP
.Vb 9
\& Maximal Minimal Possessive Allowed range
\& \-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-
\& {n,m} {n,m}? {n,m}+ Must occur at least n times
\& but no more than m times
\& {n,} {n,}? {n,}+ Must occur at least n times
\& {n} {n}? {n}+ Must occur exactly n times
\& * *? *+ 0 or more times (same as {0,})
\& + +? ++ 1 or more times (same as {1,})
\& ? ?? ?+ 0 or 1 time (same as {0,1})
.Ve
.PP
The possessive forms (new in Perl 5.10) prevent backtracking: what gets
matched by a pattern with a possessive quantifier will not be backtracked
into, even if that causes the whole match to fail.
.PP
There is no quantifier \f(CW\*(C`{,n}\*(C'\fR. That's interpreted as a literal string.
.SS "\s-1EXTENDED CONSTRUCTS\s0"
.IX Subsection "EXTENDED CONSTRUCTS"
.Vb 10
\& (?#text) A comment
\& (?:...) Groups subexpressions without capturing (cluster)
\& (?pimsx\-imsx:...) Enable/disable option (as per m// modifiers)
\& (?=...) Zero\-width positive lookahead assertion
\& (?*pla:...) Same; avail experimentally starting in 5.28
\& (?!...) Zero\-width negative lookahead assertion
\& (?*nla:...) Same; avail experimentally starting in 5.28
\& (?<=...) Zero\-width positive lookbehind assertion
\& (?*plb:...) Same; avail experimentally starting in 5.28
\& (?<!...) Zero\-width negative lookbehind assertion
\& (?*nlb:...) Same; avail experimentally starting in 5.28
\& (?>...) Grab what we can, prohibit backtracking
\& (?*atomic:...) Same; avail experimentally starting in 5.28
\& (?|...) Branch reset
\& (?<name>...) Named capture
\& (?\*(Aqname\*(Aq...) Named capture
\& (?P<name>...) Named capture (python syntax)
\& (?[...]) Extended bracketed character class
\& (?{ code }) Embedded code, return value becomes $^R
\& (??{ code }) Dynamic regex, return value used as regex
\& (?N) Recurse into subpattern number N
\& (?\-N), (?+N) Recurse into Nth previous/next subpattern
\& (?R), (?0) Recurse at the beginning of the whole pattern
\& (?&name) Recurse into a named subpattern
\& (?P>name) Recurse into a named subpattern (python syntax)
\& (?(cond)yes|no)
\& (?(cond)yes) Conditional expression, where "(cond)" can be:
\& (?=pat) lookahead
\& (?!pat) negative lookahead
\& (?<=pat) lookbehind
\& (?<!pat) negative lookbehind
\& (N) subpattern N has matched something
\& (<name>) named subpattern has matched something
\& (\*(Aqname\*(Aq) named subpattern has matched something
\& (?{code}) code condition
\& (R) true if recursing
\& (RN) true if recursing into Nth subpattern
\& (R&name) true if recursing into named subpattern
\& (DEFINE) always false, no no\-pattern allowed
.Ve
.SS "\s-1VARIABLES\s0"
.IX Subsection "VARIABLES"
.Vb 1
\& $_ Default variable for operators to use
\&
\& $\` Everything prior to matched string
\& $& Entire matched string
\& $\*(Aq Everything after to matched string
\&
\& ${^PREMATCH} Everything prior to matched string
\& ${^MATCH} Entire matched string
\& ${^POSTMATCH} Everything after to matched string
.Ve
.PP
Note to those still using Perl 5.18 or earlier:
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
within your program. Consult perlvar for \f(CW\*(C`@\-\*(C'\fR
to see equivalent expressions that won't cause slow down.
See also Devel::SawAmpersand. Starting with Perl 5.10, you
can also use the equivalent variables \f(CW\*(C`${^PREMATCH}\*(C'\fR, \f(CW\*(C`${^MATCH}\*(C'\fR
and \f(CW\*(C`${^POSTMATCH}\*(C'\fR, but for them to be defined, you have to
specify the \f(CW\*(C`/p\*(C'\fR (preserve) modifier on your regular expression.
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.
.PP
.Vb 8
\& $1, $2 ... hold the Xth captured expr
\& $+ Last parenthesized pattern match
\& $^N Holds the most recently closed capture
\& $^R Holds the result of the last (?{...}) expr
\& @\- Offsets of starts of groups. $\-[0] holds start of whole match
\& @+ Offsets of ends of groups. $+[0] holds end of whole match
\& %+ Named capture groups
\& %\- Named capture groups, as array refs
.Ve
.PP
Captured groups are numbered according to their \fIopening\fR paren.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
.Vb 5
\& lc Lowercase a string
\& lcfirst Lowercase first char of a string
\& uc Uppercase a string
\& ucfirst Titlecase first char of a string
\& fc Foldcase a string
\&
\& pos Return or set current match position
\& quotemeta Quote metacharacters
\& reset Reset m?pattern? status
\& study Analyze string for optimizing matching
\&
\& split Use a regex to split a string into parts
.Ve
.PP
The first five of these are like the escape sequences \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR,
\&\f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eF\*(C'\fR. For Titlecase, see \*(L"Titlecase\*(R"; For
Foldcase, see \*(L"Foldcase\*(R".
.SS "\s-1TERMINOLOGY\s0"
.IX Subsection "TERMINOLOGY"
\fITitlecase\fR
.IX Subsection "Titlecase"
.PP
Unicode concept which most often is equal to uppercase, but for
certain characters like the German \*(L"sharp s\*(R" there is a difference.
.PP
\fIFoldcase\fR
.IX Subsection "Foldcase"
.PP
Unicode form that is useful when comparing strings regardless of case,
as certain characters have complex one-to-many case mappings. Primarily a
variant of lowercase.
.SH "AUTHOR"
.IX Header "AUTHOR"
Iain Truskett. Updated by the Perl 5 Porters.
.PP
This document may be distributed under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
perlretut for a tutorial on regular expressions.
.IP "\(bu" 4
perlrequick for a rapid tutorial.
.IP "\(bu" 4
perlre for more details.
.IP "\(bu" 4
perlvar for details on the variables.
.IP "\(bu" 4
perlop for details on the operators.
.IP "\(bu" 4
perlfunc for details on the functions.
.IP "\(bu" 4
perlfaq6 for FAQs on regular expressions.
.IP "\(bu" 4
perlrebackslash for a reference on backslash sequences.
.IP "\(bu" 4
perlrecharclass for a reference on character classes.
.IP "\(bu" 4
The re module to alter behaviour and aid
debugging.
.IP "\(bu" 4
\&\*(L"Debugging Regular Expressions\*(R" in perldebug
.IP "\(bu" 4
perluniintro, perlunicode, charnames and perllocale
for details on regexes and internationalisation.
.IP "\(bu" 4
\&\fIMastering Regular Expressions\fR by Jeffrey Friedl
(<http://oreilly.com/catalog/9780596528126/>) for a thorough grounding and
reference on the topic.
.SH "THANKS"
.IX Header "THANKS"
David P.C. Wollmann,
Richard Soderberg,
Sean M. Burke,
Tom Christiansen,
Jim Cromie,
and
Jeffrey Goff
for useful advice.