perlre - Perl regular expressions
This page describes the syntax of regular expressions in Perl.
If you haven't used regular expressions before, a quick-start introduction is available in perlrequick, and a longer tutorial introduction is available in perlretut.
For reference on how regular expressions are used in matching operations, plus various examples of the same, see discussions of m//, s///, qr// and ?? in "Regexp Quote-Like Operators" in perlop.
New in v5.22, use re 'strict' applies stricter rules than otherwise when compiling regular expression patterns. It can find things that, while legal, may not be what you intended.
Matching operations can have various modifiers. Modifiers that relate to the interpretation of the regular expression inside are listed below. Modifiers that alter the way a regular expression is used by Perl are detailed in "Regexp Quote-Like Operators" in perlop and "Gory details of parsing quoted constructs" in perlop.
Treat string as multiple lines. That is, change "^" and "$" from matching the start of the string's first line and the end of its last line to matching the start and end of each line within the string.
Treat string as single line. That is, change "." to match any character whatsoever, even a newline, which normally it would not match.
Used together, as /ms, they let the "." match any character whatsoever, while still allowing "^" and "$" to match, respectively, just after and just before newlines within the string.
Do case-insensitive pattern matching.
If locale matching rules are in effect, the case map is taken from the current locale for code points less than 255, and from Unicode rules for larger code points. However, matches that would cross the Unicode rules/non-Unicode rules boundary (ords 255/256) will not succeed. See perllocale.
There are a number of Unicode characters that match multiple characters under /i. For example, LATIN SMALL LIGATURE FI should match the sequence fi. Perl is not currently able to do this when the multiple characters are in the pattern and are split between groupings, or when one or more are quantified. Thus
"\N{LATIN SMALL LIGATURE FI}" =~ /fi/i; # Matches
"\N{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i; # Doesn't match!
"\N{LATIN SMALL LIGATURE FI}" =~ /fi*/i; # Doesn't match!
# The below doesn't match, and it isn't clear what $1 and $2 would
# be even if it did!!
"\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match!Perl doesn't match multiple characters in a bracketed character class unless the character that maps to them is explicitly mentioned, and it doesn't match them at all if the character class is inverted, which otherwise could be highly confusing. See "Bracketed Character Classes" in perlrecharclass, and "Negation" in perlrecharclass.
Extend your pattern's legibility by permitting whitespace and comments. Details in "/x"
Preserve the string matched such that ${^PREMATCH}, ${^MATCH}, and ${^POSTMATCH} are available for use after matching.
In Perl 5.20 and higher this is ignored. Due to a new copy-on-write mechanism, ${^PREMATCH}, ${^MATCH}, and ${^POSTMATCH} will be available after the match regardless of the modifier.
These modifiers, all new in 5.14, affect which character-set rules (Unicode, etc.) are used, as described below in "Character set modifiers".
Prevent the grouping metacharacters () from capturing. This modifier, new in 5.22, will stop $1, $2, etc... from being filled in.
"hello" =~ /(hi|hello)/; # $1 is "hello"
"hello" =~ /(hi|hello)/n; # $1 is undefThis is equivalent to putting ?: at the beginning of every capturing group:
"hello" =~ /(?:hi|hello)/; # $1 is undef/n can be negated on a per-group basis. Alternatively, named captures may still be used.
"hello" =~ /(?-n:(hi|hello))/n; # $1 is "hello"
"hello" =~ /(?<greet>hi|hello)/n; # $1 is "hello", $+{greet} is
# "hello"There are a number of flags that can be found at the end of regular expression constructs that are not generic regular expression flags, but apply to the operation being performed, like matching or substitution (m// or s/// respectively).
Flags described further in "Using regular expressions in Perl" in perlretut are:
c - keep the current position during repeated matching
g - globally match the pattern repeatedly in the stringSubstitution-specific modifiers described in
"s/PATTERN/REPLACEMENT/msixpodualngcer" in perlop are:
e - evaluate the right-hand side as an expression
ee - evaluate the right side as a string then eval the result
o - pretend to optimize your code, but actually introduce bugs
r - perform non-destructive substitution and return the new valueRegular expression modifiers are usually written in documentation as e.g., "the /x modifier", even though the delimiter in question might not really be a slash. The modifiers /imnsxadlup may also be embedded within the regular expression itself using the (?...) construct, see "Extended Patterns" below.
Some of the modifiers require more explanation than given in the "Overview" above.
/x tells the regular expression parser to ignore most whitespace that is neither backslashed nor within a bracketed character class. You can use this to break up your regular expression into (slightly) more readable parts. Also, the # character is treated as a metacharacter introducing a comment that runs up to the pattern's closing delimiter, or to the end of the current line if the pattern extends onto the next line. Hence, this is very much like an ordinary Perl code comment. (You can include the closing delimiter within the comment only if you precede it with a backslash, so be careful!)
Use of /x means that if you want real whitespace or # characters in the pattern (outside a bracketed character class, which is unaffected by /x), then you'll either have to escape them (using backslashes or \Q...\E) or encode them using octal, hex, or \N{} escapes. It is ineffective to try to continue a comment onto the next line by escaping the \n with a backslash or \Q.
You can use "(?#text)" to create a comment that ends earlier than the end of the current line, but text also can't contain the closing delimiter unless escaped with a backslash.
Taken together, these features go a long way towards making Perl's regular expressions more readable. Here's an example:
# Delete (most) C comments.
$program =~ s {
/\* # Match the opening delimiter.
.*? # Match a minimal number of characters.
\*/ # Match the closing delimiter.
} []gsx;Note that anything inside a \Q...\E stays unaffected by /x. And note that /x doesn't affect space interpretation within a single multi-character construct. For example in \x{...}, regardless of the /x modifier, there can be no spaces. Same for a quantifier such as {3} or {5,}. Similarly, (?:...) can't have a space between the (, ?, and :. Within any delimiters for such a construct, allowed spaces are not affected by /x, and depend on the construct. For example, \x{...} can't have spaces because hexadecimal numbers don't have spaces in them. But, Unicode properties can have spaces, so in \p{...} there can be spaces that follow the Unicode rules, for which see "Properties accessible through \p{} and \P{}" in perluniprops.
The set of characters that are deemed whitespace are those that Unicode calls "Pattern White Space", namely:
U+0009 CHARACTER TABULATION
U+000A LINE FEED
U+000B LINE TABULATION
U+000C FORM FEED
U+000D CARRIAGE RETURN
U+0020 SPACE
U+0085 NEXT LINE
U+200E LEFT-TO-RIGHT MARK
U+200F RIGHT-TO-LEFT MARK
U+2028 LINE SEPARATOR
U+2029 PARAGRAPH SEPARATOR/d, /u, /a, and /l, available starting in 5.14, are called the character set modifiers; they affect the character set rules used for the regular expression.
The /d, /u, and /l modifiers are not likely to be of much use to you, and so you need not worry about them very much. They exist for Perl's internal use, so that complex regular expression data structures can be automatically serialized and later exactly reconstituted, including all their nuances. But, since Perl can't keep a secret, and there may be rare instances where they are useful, they are documented here.
The /a modifier, on the other hand, may be useful. Its purpose is to allow code that is to work mostly on ASCII data to not have to concern itself with Unicode.
Briefly, /l sets the character set to that of whatever Locale is in effect at the time of the execution of the pattern match.
/u sets the character set to Unicode.
/a also sets the character set to Unicode, BUT adds several restrictions for ASCII-safe matching.
/d is the old, problematic, pre-5.14 Default character set behavior. Its only use is to force that old behavior.
At any given time, exactly one of these modifiers is in effect. Their existence allows Perl to keep the originally compiled behavior of a regular expression, regardless of what rules are in effect when it is actually executed. And if it is interpolated into a larger regex, the original's rules continue to apply to it, and only it.
The /l and /u modifiers are automatically selected for regular expressions compiled within the scope of various pragmas, and we recommend that in general, you use those pragmas instead of specifying these modifiers explicitly. For one thing, the modifiers affect only pattern matching, and do not extend to even any replacement done, whereas using the pragmas give consistent results for all appropriate operations within their scopes. For example,
s/foo/\Ubar/ilwill match "foo" using the locale's rules for case-insensitive matching, but the /l does not affect how the \U operates. Most likely you want both of them to use locale rules. To do this, instead compile the regular expression within the scope of use locale. This both implicitly adds the /l, and applies locale rules to the \U. The lesson is to use locale, and not /l explicitly.
Similarly, it would be better to use use feature 'unicode_strings' instead of,
s/foo/\Lbar/iuto get Unicode rules, as the \L in the former (but not necessarily the latter) would also use Unicode rules.
More detail on each of the modifiers follows. Most likely you don't need to know this detail for /l, /u, and /d, and can skip ahead to /a.
means to use the current locale's rules (see perllocale) when pattern matching. For example, \w will match the "word" characters of that locale, and "/i" case-insensitive matching will match according to the locale's case folding rules. The locale used will be the one in effect at the time of execution of the pattern match. This may not be the same as the compilation-time locale, and can differ from one match to another if there is an intervening call of the setlocale() function.
The only non-single-byte locale Perl supports is (starting in v5.20) UTF-8. This means that code points above 255 are treated as Unicode no matter what locale is in effect (since UTF-8 implies Unicode).
Under Unicode rules, there are a few case-insensitive matches that cross the 255/256 boundary. Except for UTF-8 locales in Perls v5.20 and later, these are disallowed under /l. For example, 0xFF (on ASCII platforms) does not caselessly match the character at 0x178, LATIN CAPITAL LETTER Y WITH DIAERESIS, because 0xFF may not be LATIN SMALL LETTER Y WITH DIAERESIS in the current locale, and Perl has no way of knowing if that character even exists in the locale, much less what code point it is.
In a UTF-8 locale in v5.20 and later, the only visible difference between locale and non-locale in regular expressions should be tainting (see perlsec).
This modifier may be specified to be the default by use locale, but see "Which character set modifier is in effect?".
means to use Unicode rules when pattern matching. On ASCII platforms, this means that the code points between 128 and 255 take on their Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's). (Otherwise Perl considers their meanings to be undefined.) Thus, under this modifier, the ASCII platform effectively becomes a Unicode platform; and hence, for example, \w will match any of the more than 100_000 word characters in Unicode.
Unlike most locales, which are specific to a language and country pair, Unicode classifies all the characters that are letters somewhere in the world as \w. For example, your locale might not think that LATIN SMALL LETTER ETH is a letter (unless you happen to speak Icelandic), but Unicode does. Similarly, all the characters that are decimal digits somewhere in the world will match \d; this is hundreds, not 10, possible matches. And some of those digits look like some of the 10 ASCII digits, but mean a different number, so a human could easily think a number is a different quantity than it really is. For example, BENGALI DIGIT FOUR (U+09EA) looks very much like an ASCII DIGIT EIGHT (U+0038). And, \d+, may match strings of digits that are a mixture from different writing systems, creating a security issue. "num()" in Unicode::UCD can be used to sort this out. Or the /a modifier can be used to force \d to match just the ASCII 0 through 9.
Also, under this modifier, case-insensitive matching works on the full set of Unicode characters. The KELVIN SIGN, for example matches the letters "k" and "K"; and LATIN SMALL LIGATURE FF matches the sequence "ff", which, if you're not prepared, might make it look like a hexadecimal constant, presenting another potential security issue. See http://unicode.org/reports/tr36 for a detailed discussion of Unicode security issues.
This modifier may be specified to be the default by use feature 'unicode_strings, use locale ':not_characters', or use 5.012 (or higher), but see "Which character set modifier is in effect?".
This modifier means to use the "Default" native rules of the platform except when there is cause to use Unicode rules instead, as follows:
the target string is encoded in UTF-8; or
the pattern is encoded in UTF-8; or
the pattern explicitly mentions a code point that is above 255 (say by \x{100}); or
the pattern uses a Unicode name (\N{...}); or
the pattern uses a Unicode property (\p{...} or \P{...}); or
the pattern uses a Unicode break (\b{...} or \B{...}); or
the pattern uses "(?[ ])"
Another mnemonic for this modifier is "Depends", as the rules actually used depend on various things, and as a result you can get unexpected results. See "The "Unicode Bug"" in perlunicode. The Unicode Bug has become rather infamous, leading to yet another (printable) name for this modifier, "Dodgy".
Unless the pattern or string are encoded in UTF-8, only ASCII characters can match positively.
Here are some examples of how that works on an ASCII platform:
$str = "\xDF"; # $str is not in UTF-8 format.
$str =~ /^\w/; # No match, as $str isn't in UTF-8 format.
$str .= "\x{0e0b}"; # Now $str is in UTF-8 format.
$str =~ /^\w/; # Match! $str is now in UTF-8 format.
chop $str;
$str =~ /^\w/; # Still a match! $str remains in UTF-8 format.This modifier is automatically selected by default when none of the others are, so yet another name for it is "Default".
Because of the unexpected behaviors associated with this modifier, you probably should only use it to maintain weird backward compatibilities.
This modifier stands for ASCII-restrict (or ASCII-safe). This modifier, unlike the others, may be doubled-up to increase its effect.
When it appears singly, it causes the sequences \d, \s, \w, and the Posix character classes to match only in the ASCII range. They thus revert to their pre-5.6, pre-Unicode meanings. Under /a, \d always means precisely the digits "0" to "9"; \s means the five characters [ \f\n\r\t], and starting in Perl v5.18, the vertical tab; \w means the 63 characters [A-Za-z0-9_]; and likewise, all the Posix classes such as [[:print:]] match only the appropriate ASCII-range characters.
This modifier is useful for people who only incidentally use Unicode, and who do not wish to be burdened with its complexities and security concerns.
With /a, one can write \d with confidence that it will only match ASCII characters, and should the need arise to match beyond ASCII, you can instead use \p{Digit} (or \p{Word} for \w). There are similar \p{...} constructs that can match beyond ASCII both white space (see "Whitespace" in perlrecharclass), and Posix classes (see "POSIX Character Classes" in perlrecharclass). Thus, this modifier doesn't mean you can't use Unicode, it means that to get Unicode matching you must explicitly use a construct (\p{}, \P{}) that signals Unicode.
As you would expect, this modifier causes, for example, \D to mean the same thing as [^0-9]; in fact, all non-ASCII characters match \D, \S, and \W. \b still means to match at the boundary between \w and \W, using the /a definitions of them (similarly for \B).
Otherwise, /a behaves like the /u modifier, in that case-insensitive matching uses Unicode rules; for example, "k" will match the Unicode \N{KELVIN SIGN} under /i matching, and code points in the Latin1 range, above ASCII will have Unicode rules when it comes to case-insensitive matching.
To forbid ASCII/non-ASCII matches (like "k" with \N{KELVIN SIGN}), specify the "a" twice, for example /aai or /aia. (The first occurrence of "a" restricts the \d, etc., and the second occurrence adds the /i restrictions.) But, note that code points outside the ASCII range will use Unicode rules for /i matching, so the modifier doesn't really restrict things to just ASCII; it just forbids the intermixing of ASCII and non-ASCII.
To summarize, this modifier provides protection for applications that don't wish to be exposed to all of Unicode. Specifying it twice gives added protection.
This modifier may be specified to be the default by use re '/a' or use re '/aa'. If you do so, you may actually have occasion to use the /u modifier explicitly if there are a few regular expressions where you do want full Unicode rules (but even here, it's best if everything were under feature "unicode_strings", along with the use re '/aa'). Also see "Which character set modifier is in effect?".
Which of these modifiers is in effect at any given point in a regular expression depends on a fairly complex set of interactions. These have been designed so that in general you don't have to worry about it, but this section gives the gory details. As explained below in "Extended Patterns" it is possible to explicitly specify modifiers that apply only to portions of a regular expression. The innermost always has priority over any outer ones, and one applying to the whole expression has priority over any of the default settings that are described in the remainder of this section.
The use re '/foo' pragma can be used to set default modifiers (including these) for regular expressions compiled within its scope. This pragma has precedence over the other pragmas listed below that also change the defaults.
Otherwise, use locale sets the default modifier to /l; and use feature 'unicode_strings, or use 5.012 (or higher) set the default to /u when not in the same scope as either use locale or use bytes. (use locale ':not_characters' also sets the default to /u, overriding any plain use locale.) Unlike the mechanisms mentioned above, these affect operations besides regular expressions pattern matching, and so give more consistent results with other operators, including using \U, \l, etc. in substitution replacements.
If none of the above apply, for backwards compatibility reasons, the /d modifier is the one in effect by default. As this can lead to unexpected results, it is best to specify which other rule set should be used.
Prior to 5.14, there were no explicit modifiers, but /l was implied for regexes compiled within the scope of use locale, and /d was implied otherwise. However, interpolating a regex into a larger regex would ignore the original compilation in favor of whatever was in effect at the time of the second compilation. There were a number of inconsistencies (bugs) with the /d modifier, where Unicode rules would be used when inappropriate, and vice versa. \p{} did not imply Unicode rules, and neither did all occurrences of \N{}, until 5.12.
The patterns used in Perl pattern matching evolved from those supplied in the Version 8 regex routines. (The routines are derived (distantly) from Henry Spencer's freely redistributable reimplementation of the V8 routines.) See "Version 8 Regular Expressions" for details.
In particular the following metacharacters have their standard egrep-ish meanings:
\ Quote the next metacharacter
^ Match the beginning of the line
. Match any character (except newline)
$ Match the end of the string (or before newline at the end
of the string)
| Alternation
() Grouping
[] Bracketed Character classBy default, the "^" character is guaranteed to match only the beginning of the string, the "$" character only the end (or before the newline at the end), and Perl does certain optimizations with the assumption that the string contains only one line. Embedded newlines will not be matched by "^" or "$". You may, however, wish to treat a string as a multi-line buffer, such that the "^" will match after any newline within the string (except if the newline is the last character in the string), and "$" will match before any newline. At the cost of a little more overhead, you can do this by using the /m modifier on the pattern match operator. (Older programs did this by setting $*, but this option was removed in perl 5.10.)
To simplify multi-line substitutions, the "." character never matches a newline unless you use the /s modifier, which in effect tells Perl to pretend the string is a single line--even if it isn't.
The following standard quantifiers are recognized:
* Match 0 or more times
+ Match 1 or more times
? Match 1 or 0 times
{n} Match exactly n times
{n,} Match at least n times
{n,m} Match at least n but not more than m times(If a curly bracket occurs in any other context and does not form part of a backslashed sequence like \x{...}, it is treated as a regular character. However, a deprecation warning is raised for all such occurrences, and in Perl v5.26, literal uses of a curly bracket will be required to be escaped, say by preceding them with a backslash ("\{") or enclosing them within square brackets ("[{]"). This change will allow for future syntax extensions (like making the lower bound of a quantifier optional), and better error checking of quantifiers.)
The "*" quantifier is equivalent to {0,}, the "+" quantifier to {1,}, and the "?" quantifier to {0,1}. n and m are limited to non-negative integral values less than a preset limit defined when perl is built. This is usually 32766 on the most common platforms. The actual limit can be seen in the error message generated by code such as this:
$_ **= $_ , / {$_} / for 2 .. 42;By default, a quantified subpattern is "greedy", that is, it will match as many times as possible (given a particular starting location) while still allowing the rest of the pattern to match. If you want it to match the minimum number of times possible, follow the quantifier with a "?". Note that the meanings don't change, just the "greediness":
*? Match 0 or more times, not greedily
+? Match 1 or more times, not greedily
?? Match 0 or 1 time, not greedily
{n}? Match exactly n times, not greedily (redundant)
{n,}? Match at least n times, not greedily
{n,m}? Match at least n but not more than m times, not greedilyNormally when a quantified subpattern does not allow the rest of the overall pattern to match, Perl will backtrack. However, this behaviour is sometimes undesirable. Thus Perl provides the "possessive" quantifier form as well.
*+ Match 0 or more times and give nothing back
++ Match 1 or more times and give nothing back
?+ Match 0 or 1 time and give nothing back
{n}+ Match exactly n times and give nothing back (redundant)
{n,}+ Match at least n times and give nothing back
{n,m}+ Match at least n but not more than m times and give nothing backFor instance,
'aaaa' =~ /a++a/will never match, as the a++ will gobble up all the a's in the string and won't leave any for the remaining part of the pattern. This feature can be extremely useful to give perl hints about where it shouldn't backtrack. For instance, the typical "match a double-quoted string" problem can be most efficiently performed when written as:
/"(?:[^"\\]++|\\.)*+"/as we know that if the final quote does not match, backtracking will not help. See the independent subexpression "(?>pattern)" for more details; possessive quantifiers are just syntactic sugar for that construct. For instance the above example could also be written as follows:
/"(?>(?:(?>[^"\\]+)|\\.)*)"/Note that the possessive quantifier modifier can not be be combined with the non-greedy modifier. This is because it would make no sense. Consider the follow equivalency table:
Illegal Legal
------------ ------
X??+ X{0}
X+?+ X{1}
X{min,max}?+ X{min}Because patterns are processed as double-quoted strings, the following also work:
\t tab (HT, TAB)
\n newline (LF, NL)
\r return (CR)
\f form feed (FF)
\a alarm (bell) (BEL)
\e escape (think troff) (ESC)
\cK control char (example: VT)
\x{}, \x00 character whose ordinal is the given hexadecimal number
\N{name} named Unicode character or character sequence
\N{U+263D} Unicode character (example: FIRST QUARTER MOON)
\o{}, \000 character whose ordinal is the given octal number
\l lowercase next char (think vi)
\u uppercase next char (think vi)
\L lowercase until \E (think vi)
\U uppercase until \E (think vi)
\Q quote (disable) pattern metacharacters until \E
\E end either case modification or quoted section, think viDetails are in "Quote and Quote-like Operators" in perlop.
In addition, Perl defines the following:
Sequence Note Description
[...] [1] Match a character according to the rules of the
bracketed character class defined by the "...".
Example: [a-z] matches "a" or "b" or "c" ... or "z"
[[:...:]] [2] Match a character according to the rules of the POSIX
character class "..." within the outer bracketed
character class. Example: [[:upper:]] matches any
uppercase character.
(?[...]) [8] Extended bracketed character class
\w [3] Match a "word" character (alphanumeric plus "_", plus
other connector punctuation chars plus Unicode
marks)
\W [3] Match a non-"word" character
\s [3] Match a whitespace character
\S [3] Match a non-whitespace character
\d [3] Match a decimal digit character
\D [3] Match a non-digit character
\pP [3] Match P, named property. Use \p{Prop} for longer names
\PP [3] Match non-P
\X [4] Match Unicode "eXtended grapheme cluster"
\C Match a single C-language char (octet) even if that is
part of a larger UTF-8 character. Thus it breaks up
characters into their UTF-8 bytes, so you may end up
with malformed pieces of UTF-8. Unsupported in
lookbehind. (Deprecated.)
\1 [5] Backreference to a specific capture group or buffer.
'1' may actually be any positive integer.
\g1 [5] Backreference to a specific or previous group,
\g{-1} [5] The number may be negative indicating a relative
previous group and may optionally be wrapped in
curly brackets for safer parsing.
\g{name} [5] Named backreference
\k<name> [5] Named backreference
\K [6] Keep the stuff left of the \K, don't include it in $&
\N [7] Any character but \n. Not affected by /s modifier
\v [3] Vertical whitespace
\V [3] Not vertical whitespace
\h [3] Horizontal whitespace
\H [3] Not horizontal whitespace
\R [4] Linebreak