pod/perlre.pod

   1 =head1 NAME
   2
   3 perlre - Perl regular expressions
   4
   5 =head1 DESCRIPTION
   6
   7 For a description of how to use regular expressions in matching
   8 operations, see C<m//> and C<s///> in L<perlop>.  The matching operations can
   9 have various modifiers, some of which relate to the interpretation of
  10 the regular expression inside.  These are:
  11
  12     i   Do case-insensitive pattern matching.
  13     m   Treat string as multiple lines.
  14     s   Treat string as single line.
  15     x   Use extended regular expressions.
  16
  17 These are usually written as "the C</x> modifier", even though the delimiter
  18 in question might not actually be a slash.  In fact, any of these
  19 modifiers may also be embedded within the regular expression itself using
  20 the new C<(?...)> construct.  See below.
  21
  22 The C</x> modifier itself needs a little more explanation.  It tells the
  23 regular expression parser to ignore whitespace that is not backslashed
  24 or within a character class.  You can use this to break up your regular
  25 expression into (slightly) more readable parts.  Together with the
  26 capability of embedding comments described later, this goes a long
  27 way towards making Perl 5 a readable language.  See the C comment
  28 deletion code in L<perlop>.
  29
  30 =head2 Regular Expressions
  31
  32 The patterns used in pattern matching are regular expressions such as
  33 those supplied in the Version 8 regexp routines.  (In fact, the
  34 routines are derived (distantly) from Henry Spencer's freely
  35 redistributable reimplementation of the V8 routines.)
  36 See L<Version 8 Regular Expressions> for details.
  37
  38 In particular the following metacharacters have their standard I<egrep>-ish
  39 meanings:
  40
  41     \   Quote the next metacharacter
  42     ^   Match the beginning of the line
  43     .   Match any character (except newline)
  44     $   Match the end of the line
  45     |   Alternation
  46     ()  Grouping
  47     []  Character class
  48
  49 By default, the "^" character is guaranteed to match only at the
  50 beginning of the string, the "$" character only at the end (or before the
  51 newline at the end) and Perl does certain optimizations with the
  52 assumption that the string contains only one line.  Embedded newlines
  53 will not be matched by "^" or "$".  You may, however, wish to treat a
  54 string as a multi-line buffer, such that the "^" will match after any
  55 newline within the string, and "$" will match before any newline.  At the
  56 cost of a little more overhead, you can do this by using the /m modifier
  57 on the pattern match operator.  (Older programs did this by setting C<$*>,
  58 but this practice is deprecated in Perl 5.)
  59
  60 To facilitate multi-line substitutions, the "." character never matches a
  61 newline unless you use the C</s> modifier, which tells Perl to pretend
  62 the string is a single line--even if it isn't.  The C</s> modifier also
  63 overrides the setting of C<$*>, in case you have some (badly behaved) older
  64 code that sets it in another module.
  65
  66 The following standard quantifiers are recognized:
  67
  68     *      Match 0 or more times
  69     +      Match 1 or more times
  70     ?      Match 1 or 0 times
  71     {n}    Match exactly n times
  72     {n,}   Match at least n times
  73     {n,m}  Match at least n but not more than m times
  74
  75 (If a curly bracket occurs in any other context, it is treated
  76 as a regular character.)  The "*" modifier is equivalent to C<{0,}>, the "+"
  77 modifier to C<{1,}>, and the "?" modifier to C<{0,1}>.  There is no limit to the
  78 size of n or m, but large numbers will chew up more memory.
  79
  80 By default, a quantified subpattern is "greedy", that is, it will match as
  81 many times as possible without causing the rest pattern not to match.  The
  82 standard quantifiers are all "greedy", in that they match as many
  83 occurrences as possible (given a particular starting location) without
  84 causing the pattern to fail.  If you want it to match the minimum number
  85 of times possible, follow the quantifier with a "?" after any of them.
  86 Note that the meanings don't change, just the "gravity":
  87
  88     *?     Match 0 or more times
  89     +?     Match 1 or more times
  90     ??     Match 0 or 1 time
  91     {n}?   Match exactly n times
  92     {n,}?  Match at least n times
  93     {n,m}? Match at least n but not more than m times
  94
  95 Since patterns are processed as double quoted strings, the following
  96 also work:
  97
  98     \t          tab
  99     \n          newline
 100     \r          return
 101     \f          form feed
 102     \v          vertical tab, whatever that is
 103     \a          alarm (bell)
 104     \e          escape
 105     \033        octal char
 106     \x1b        hex char
 107     \c[         control char
 108     \l          lowercase next char
 109     \u          uppercase next char
 110     \L          lowercase till \E
 111     \U          uppercase till \E
 112     \E          end case modification
 113     \Q          quote regexp metacharacters till \E
 114
 115 In addition, Perl defines the following:
 116
 117     \w  Match a "word" character (alphanumeric plus "_")
 118     \W  Match a non-word character
 119     \s  Match a whitespace character
 120     \S  Match a non-whitespace character
 121     \d  Match a digit character
 122     \D  Match a non-digit character
 123
 124 Note that C<\w> matches a single alphanumeric character, not a whole
 125 word.  To match a word you'd need to say C<\w+>.  You may use C<\w>, C<\W>, C<\s>,
 126 C<\S>, C<\d> and C<\D> within character classes (though not as either end of a
 127 range).
 128
 129 Perl defines the following zero-width assertions:
 130
 131     \b  Match a word boundary
 132     \B  Match a non-(word boundary)
 133     \A  Match only at beginning of string
 134     \Z  Match only at end of string
 135     \G  Match only where previous m//g left off
 136
 137 A word boundary (C<\b>) is defined as a spot between two characters that
 138 has a C<\w> on one side of it and and a C<\W> on the other side of it (in
 139 either order), counting the imaginary characters off the beginning and
 140 end of the string as matching a C<\W>.  (Within character classes C<\b>
 141 represents backspace rather than a word boundary.)  The C<\A> and C<\Z> are
 142 just like "^" and "$" except that they won't match multiple times when the
 143 C</m> modifier is used, while "^" and "$" will match at every internal line
 144 boundary.
 145
 146 When the bracketing construct C<( ... )> is used, \<digit> matches the
 147 digit'th substring.  (Outside of the pattern, always use "$" instead of
 148 "\" in front of the digit.  The scope of $<digit> (and C<$`>, C<$&>, and C<$')>
 149 extends to the end of the enclosing BLOCK or eval string, or to the
 150 next pattern match with subexpressions.
 151 If you want to
 152 use parentheses to delimit subpattern (e.g. a set of alternatives) without
 153 saving it as a subpattern, follow the ( with a ?.
 154 The \<digit> notation
 155 sometimes works outside the current pattern, but should not be relied
 156 upon.)  You may have as many parentheses as you wish.  If you have more
 157 than 9 substrings, the variables $10, $11, ... refer to the
 158 corresponding substring.  Within the pattern, \10, \11, etc. refer back
 159 to substrings if there have been at least that many left parens before
 160 the backreference.  Otherwise (for backward compatibilty) \10 is the
 161 same as \010, a backspace, and \11 the same as \011, a tab.  And so
 162 on.  (\1 through \9 are always backreferences.)
 163
 164 C<$+> returns whatever the last bracket match matched.  C<$&> returns the
 165 entire matched string.  ($0 used to return the same thing, but not any
 166 more.)  C<$`> returns everything before the matched string.  C<$'> returns
 167 everything after the matched string.  Examples:
 168
 169     s/^([^ ]*) *([^ ]*)/$2 $1/;     # swap first two words
 170
 171     if (/Time: (..):(..):(..)/) {
 172         $hours = $1;
 173         $minutes = $2;
 174         $seconds = $3;
 175     }
 176
 177 You will note that all backslashed metacharacters in Perl are
 178 alphanumeric, such as C<\b>, C<\w>, C<\n>.  Unlike some other regular expression
 179 languages, there are no backslashed symbols that aren't alphanumeric.
 180 So anything that looks like \\, \(, \), \<, \>, \{, or \} is always
 181 interpreted as a literal character, not a metacharacter.  This makes it
 182 simple to quote a string that you want to use for a pattern but that
 183 you are afraid might contain metacharacters.  Simply quote all the
 184 non-alphanumeric characters:
 185
 186     $pattern =~ s/(\W)/\\$1/g;
 187
 188 You can also use the built-in quotemeta() function to do this.
 189 An even easier way to quote metacharacters right in the match operator
 190 is to say
 191
 192     /$unquoted\Q$quoted\E$unquoted/
 193
 194 Perl 5 defines a consistent extension syntax for regular expressions.
 195 The syntax is a pair of parens with a question mark as the first thing
 196 within the parens (this was a syntax error in Perl 4).  The character
 197 after the question mark gives the function of the extension.  Several
 198 extensions are already supported:
 199
 200 =over 10
 201
 202 =item (?#text)
 203
 204 A comment.  The text is ignored.
 205
 206 =item (?:regexp)
 207
 208 This groups things like "()" but doesn't make backrefences like "()" does.  So
 209
 210     split(/\b(?:a|b|c)\b/)
 211
 212 is like
 213
 214     split(/\b(a|b|c)\b/)
 215
 216 but doesn't spit out extra fields.
 217
 218 =item (?=regexp)
 219
 220 A zero-width positive lookahead assertion.  For example, C</\w+(?=\t)/>
 221 matches a word followed by a tab, without including the tab in C<$&>.
 222
 223 =item (?!regexp)
 224
 225 A zero-width negative lookahead assertion.  For example C</foo(?!bar)/>
 226 matches any occurrence of "foo" that isn't followed by "bar".  Note
 227 however that lookahead and lookbehind are NOT the same thing.  You cannot
 228 use this for lookbehind: C</(?!foo)bar/> will not find an occurrence of
 229 "bar" that is preceded by something which is not "foo".  That's because
 230 the C<(?!foo)> is just saying that the next thing cannot be "foo"--and
 231 it's not, it's a "bar", so "foobar" will match.  You would have to do
 232 something like C</(?foo)...bar/> for that.   We say "like" because there's
 233 the case of your "bar" not having three characters before it.  You could
 234 cover that this way: C</(?:(?!foo)...|^..?)bar/>.  Sometimes it's still
 235 easier just to say:
 236
 237     if (/foo/ && $` =~ /bar$/)
 238
 239
 240 =item (?imsx)
 241
 242 One or more embedded pattern-match modifiers.  This is particularly
 243 useful for patterns that are specified in a table somewhere, some of
 244 which want to be case sensitive, and some of which don't.  The case
 245 insensitive ones merely need to include C<(?i)> at the front of the
 246 pattern.  For example:
 247
 248     $pattern = "foobar";
 249     if ( /$pattern/i )
 250
 251     # more flexible:
 252
 253     $pattern = "(?i)foobar";
 254     if ( /$pattern/ )
 255
 256 =back
 257
 258 The specific choice of question mark for this and the new minimal
 259 matching construct was because 1) question mark is pretty rare in older
 260 regular expressions, and 2) whenever you see one, you should stop
 261 and "question" exactly what is going on.  That's psychology...
 262
 263 =head2 Version 8 Regular Expressions
 264
 265 In case you're not familiar with the "regular" Version 8 regexp
 266 routines, here are the pattern-matching rules not described above.
 267
 268 Any single character matches itself, unless it is a I<metacharacter>
 269 with a special meaning described here or above.  You can cause
 270 characters which normally function as metacharacters to be interpreted
 271 literally by prefixing them with a "\" (e.g. "\." matches a ".", not any
 272 character; "\\" matches a "\").  A series of characters matches that
 273 series of characters in the target string, so the pattern C<blurfl>
 274 would match "blurfl" in the target string.
 275
 276 You can specify a character class, by enclosing a list of characters
 277 in C<[]>, which will match any one of the characters in the list.  If the
 278 first character after the "[" is "^", the class matches any character not
 279 in the list.  Within a list, the "-" character is used to specify a
 280 range, so that C<a-z> represents all the characters between "a" and "z",
 281 inclusive.
 282
 283 Characters may be specified using a metacharacter syntax much like that
 284 used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
 285 "\f" a form feed, etc.  More generally, \I<nnn>, where I<nnn> is a string
 286 of octal digits, matches the character whose ASCII value is I<nnn>.
 287 Similarly, \xI<nn>, where I<nn> are hexidecimal digits, matches the
 288 character whose ASCII value is I<nn>. The expression \cI<x> matches the
 289 ASCII character control-I<x>.  Finally, the "." metacharacter matches any
 290 character except "\n" (unless you use C</s>).
 291
 292 You can specify a series of alternatives for a pattern using "|" to
 293 separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
 294 or "foe" in the target string (as would C<f(e|i|o)e>).  Note that the
 295 first alternative includes everything from the last pattern delimiter
 296 ("(", "[", or the beginning of the pattern) up to the first "|", and
 297 the last alternative contains everything from the last "|" to the next
 298 pattern delimiter.  For this reason, it's common practice to include
 299 alternatives in parentheses, to minimize confusion about where they
 300 start and end.  Note however that "|" is interpreted as a literal with
 301 square brackets, so if you write C<[fee|fie|foe]> you're really only
 302 matching C<[feio|]>.
 303
 304 Within a pattern, you may designate subpatterns for later reference by
 305 enclosing them in parentheses, and you may refer back to the I<n>th
 306 subpattern later in the pattern using the metacharacter \I<n>.
 307 Subpatterns are numbered based on the left to right order of their
 308 opening parenthesis.  Note that a backreference matches whatever
 309 actually matched the subpattern in the string being examined, not the
 310 rules for that subpattern.  Therefore, C<(0|0x)\d*\s\1\d*> will
 311 match "0x1234 0x4321",but not "0x1234 01234", since subpattern 1
 312 actually matched "0x", even though the rule C<0|0x> could
 313 potentially match the leading 0 in the second number.