pod/perlrecharclass.pod

   1 =head1 NAME
   2 X<character class>
   3
   4 perlrecharclass - Perl Regular Expression Character Classes
   5
   6 =head1 DESCRIPTION
   7
   8 The top level documentation about Perl regular expressions
   9 is found in L<perlre>.
  10
  11 This manual page discusses the syntax and use of character
  12 classes in Perl regular expressions.
  13
  14 A character class is a way of denoting a set of characters
  15 in such a way that one character of the set is matched.
  16 It's important to remember that: matching a character class
  17 consumes exactly one character in the source string. (The source
  18 string is the string the regular expression is matched against.)
  19
  20 There are three types of character classes in Perl regular
  21 expressions: the dot, backslash sequences, and the form enclosed in square
  22 brackets.  Keep in mind, though, that often the term "character class" is used
  23 to mean just the bracketed form.  Certainly, most Perl documentation does that.
  24
  25 =head2 The dot
  26
  27 The dot (or period), C<.> is probably the most used, and certainly
  28 the most well-known character class. By default, a dot matches any
  29 character, except for the newline. That default can be changed to
  30 add matching the newline by using the I<single line> modifier: either
  31 for the entire regular expression with the C</s> modifier, or
  32 locally with C<(?s)>.  (The experimental C<\N> backslash sequence, described
  33 below, matches any character except newline without regard to the
  34 I<single line> modifier.)
  35
  36 Here are some examples:
  37
  38  "a"  =~  /./       # Match
  39  "."  =~  /./       # Match
  40  ""   =~  /./       # No match (dot has to match a character)
  41  "\n" =~  /./       # No match (dot does not match a newline)
  42  "\n" =~  /./s      # Match (global 'single line' modifier)
  43  "\n" =~  /(?s:.)/  # Match (local 'single line' modifier)
  44  "ab" =~  /^.$/     # No match (dot matches one character)
  45
  46 =head2 Backslash sequences
  47 X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\p> X<\P>
  48 X<\N> X<\v> X<\V> X<\h> X<\H>
  49 X<word> X<whitespace>
  50
  51 A backslash sequence is a sequence of characters, the first one of which is a
  52 backslash.  Perl ascribes special meaning to many such sequences, and some of
  53 these are character classes.  That is, they match a single character each,
  54 provided that the character belongs to the specific set of characters defined
  55 by the sequence.
  56
  57 Here's a list of the backslash sequences that are character classes.  They
  58 are discussed in more detail below.  (For the backslash sequences that aren't
  59 character classes, see L<perlrebackslash>.)
  60
  61  \d             Match a decimal digit character.
  62  \D             Match a non-decimal-digit character.
  63  \w             Match a "word" character.
  64  \W             Match a non-"word" character.
  65  \s             Match a whitespace character.
  66  \S             Match a non-whitespace character.
  67  \h             Match a horizontal whitespace character.
  68  \H             Match a character that isn't horizontal whitespace.
  69  \v             Match a vertical whitespace character.
  70  \V             Match a character that isn't vertical whitespace.
  71  \N             Match a character that isn't a newline.  Experimental.
  72  \pP, \p{Prop}  Match a character that has the given Unicode property.
  73  \PP, \P{Prop}  Match a character that doesn't have the Unicode property
  74
  75 =head3 \N
  76
  77 C<\N> is new in 5.12, and is experimental.  It, like the dot, matches any
  78 character that is not a newline. The difference is that C<\N> is not influenced
  79 by the I<single line> regular expression modifier (see L</The dot> above).  Note
  80 that the form C<\N{...}> may mean something completely different.  When the
  81 C<{...}> is a L<quantifier|perlre/Quantifiers>, it means to match a non-newline
  82 character that many times.  For example, C<\N{3}> means to match 3
  83 non-newlines; C<\N{5,}> means to match 5 or more non-newlines.  But if C<{...}>
  84 is not a legal quantifier, it is presumed to be a named character.  See
  85 L<charnames> for those.  For example, none of C<\N{COLON}>, C<\N{4F}>, and
  86 C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose
  87 names are respectively C<COLON>, C<4F>, and C<F4>.
  88
  89 =head3 Digits
  90
  91 C<\d> matches a single character considered to be a decimal I<digit>.
  92 If the C</a> regular expression modifier is in effect, it matches [0-9].
  93 Otherwise, it
  94 matches anything that is matched by C<\p{Digit}>, which includes [0-9].
  95 (An unlikely possible exception is that under locale matching rules, the
  96 current locale might not have [0-9] matched by C<\d>, and/or might match
  97 other characters whose code point is less than 256.  Such a locale
  98 definition would be in violation of the C language standard, but Perl
  99 doesn't currently assume anything in regard to this.)
 100
 101 What this means is that unless the C</a> modifier is in effect C<\d> not
 102 only matches the digits '0' - '9', but also Arabic, Devanagari, and
 103 digits from other languages.  This may cause some confusion, and some
 104 security issues.
 105
 106 Some digits that C<\d> matches look like some of the [0-9] ones, but
 107 have different values.  For example, BENGALI DIGIT FOUR (U+09EA) looks
 108 very much like an ASCII DIGIT EIGHT (U+0038).  An application that
 109 is expecting only the ASCII digits might be misled, or if the match is
 110 C<\d+>, the matched string might contain a mixture of digits from
 111 different writing systems that look like they signify a number different
 112 than they actually do.  L<Unicode::UCD/num()> can
 113 be used to safely
 114 calculate the value, returning C<undef> if the input string contains
 115 such a mixture.
 116
 117 What C<\p{Digit}> means (and hence C<\d> except under the C</a>
 118 modifier) is C<\p{General_Category=Decimal_Number}>, or synonymously,
 119 C<\p{General_Category=Digit}>.  Starting with Unicode version 4.1, this
 120 is the same set of characters matched by C<\p{Numeric_Type=Decimal}>.
 121 But Unicode also has a different property with a similar name,
 122 C<\p{Numeric_Type=Digit}>, which matches a completely different set of
 123 characters.  These characters are things such as C<CIRCLED DIGIT ONE>
 124 or subscripts, or are from writing systems that lack all ten digits.
 125
 126 The design intent is for C<\d> to exactly match the set of characters
 127 that can safely be used with "normal" big-endian positional decimal
 128 syntax, where, for example 123 means one 'hundred', plus two 'tens',
 129 plus three 'ones'.  This positional notation does not necessarily apply
 130 to characters that match the other type of "digit",
 131 C<\p{Numeric_Type=Digit}>, and so C<\d> doesn't match them.
 132
 133 The Tamil digits (U+0BE6 - U+0BEF) can also legally be
 134 used in old-style Tamil numbers in which they would appear no more than
 135 one in a row, separated by characters that mean "times 10", "times 100",
 136 etc.  (See L<http://www.unicode.org/notes/tn21>.)
 137
 138 Any character not matched by C<\d> is matched by C<\D>.
 139
 140 =head3 Word characters
 141
 142 A C<\w> matches a single alphanumeric character (an alphabetic character, or a
 143 decimal digit); or a connecting punctuation character, such as an
 144 underscore ("_"); or a "mark" character (like some sort of accent) that
 145 attaches to one of those.  It does not match a whole word.  To match a
 146 whole word, use C<\w+>.  This isn't the same thing as matching an
 147 English word, but in the ASCII range it is the same as a string of
 148 Perl-identifier characters.
 149
 150 =over
 151
 152 =item If the C</a> modifier is in effect ...
 153
 154 C<\w> matches the 63 characters [a-zA-Z0-9_].
 155
 156 =item otherwise ...
 157
 158 =over
 159
 160 =item For code points above 255 ...
 161
 162 C<\w> matches the same as C<\p{Word}> matches in this range.  That is,
 163 it matches Thai letters, Greek letters, etc.  This includes connector
 164 punctuation (like the underscore) which connect two words together, or
 165 diacritics, such as a C<COMBINING TILDE> and the modifier letters, which
 166 are generally used to add auxiliary markings to letters.
 167
 168 =item For code points below 256 ...
 169
 170 =over
 171
 172 =item if locale rules are in effect ...
 173
 174 C<\w> matches the platform's native underscore character plus whatever
 175 the locale considers to be alphanumeric.
 176
 177 =item if Unicode rules are in effect or if on an EBCDIC platform ...
 178
 179 C<\w> matches exactly what C<\p{Word}> matches.
 180
 181 =item otherwise ...
 182
 183 C<\w> matches [a-zA-Z0-9_].
 184
 185 =back
 186
 187 =back
 188
 189 =back
 190
 191 Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
 192
 193 There are a number of security issues with the full Unicode list of word
 194 characters.  See L<http://unicode.org/reports/tr36>.
 195
 196 Also, for a somewhat finer-grained set of characters that are in programming
 197 language identifiers beyond the ASCII range, you may wish to instead use the
 198 more customized L</Unicode Properties>, C<\p{ID_Start}>,
 199 C<\p{ID_Continue}>, C<\p{XID_Start}>, and C<\p{XID_Continue}>.  See
 200 L<http://unicode.org/reports/tr31>.
 201
 202 Any character not matched by C<\w> is matched by C<\W>.
 203
 204 =head3 Whitespace
 205
 206 C<\s> matches any single character considered whitespace.
 207
 208 =over
 209
 210 =item If the C</a> modifier is in effect ...
 211
 212 C<\s> matches the 5 characters [\t\n\f\r ]; that is, the horizontal tab,
 213 the newline, the form feed, the carriage return, and the space.  (Note
 214 that it doesn't match the vertical tab, C<\cK> on ASCII platforms.)
 215
 216 =item otherwise ...
 217
 218 =over
 219
 220 =item For code points above 255 ...
 221
 222 C<\s> matches exactly the code points above 255 shown with an "s" column
 223 in the table below.
 224
 225 =item For code points below 256 ...
 226
 227 =over
 228
 229 =item if locale rules are in effect ...
 230
 231 C<\s> matches whatever the locale considers to be whitespace.  Note that
 232 this is likely to include the vertical space, unlike non-locale C<\s>
 233 matching.
 234
 235 =item if Unicode rules are in effect or if on an EBCDIC platform ...
 236
 237 C<\s> matches exactly the characters shown with an "s" column in the
 238 table below.
 239
 240 =item otherwise ...
 241
 242 C<\s> matches [\t\n\f\r ].
 243 Note that this list doesn't include the non-breaking space.
 244
 245 =back
 246
 247 =back
 248
 249 =back
 250
 251 Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
 252
 253 Any character not matched by C<\s> is matched by C<\S>.
 254
 255 C<\h> matches any character considered horizontal whitespace;
 256 this includes the platform's space and tab characters and several others
 257 listed in the table below.  C<\H> matches any character
 258 not considered horizontal whitespace.  They use the platform's native
 259 character set, and do not consider any locale that may otherwise be in
 260 use.
 261
 262 C<\v> matches any character considered vertical whitespace;
 263 this includes the platform's carriage return and line feed characters (newline)
 264 plus several other characters, all listed in the table below.
 265 C<\V> matches any character not considered vertical whitespace.
 266 They use the platform's native character set, and do not consider any
 267 locale that may otherwise be in use.
 268
 269 C<\R> matches anything that can be considered a newline under Unicode
 270 rules. It's not a character class, as it can match a multi-character
 271 sequence. Therefore, it cannot be used inside a bracketed character
 272 class; use C<\v> instead (vertical whitespace).  It uses the platform's
 273 native character set, and does not consider any locale that may
 274 otherwise be in use.
 275 Details are discussed in L<perlrebackslash>.
 276
 277 Note that unlike C<\s> (and C<\d> and C<\w>), C<\h> and C<\v> always match
 278 the same characters, without regard to other factors, such as the active
 279 locale or whether the source string is in UTF-8 format.
 280
 281 One might think that C<\s> is equivalent to C<[\h\v]>. This is not true.
 282 The difference is that the vertical tab (C<"\x0b">) is not matched by
 283 C<\s>; it is however considered vertical whitespace.
 284
 285 The following table is a complete listing of characters matched by
 286 C<\s>, C<\h> and C<\v> as of Unicode 6.0.
 287
 288 The first column gives the Unicode code point of the character (in hex format),
 289 the second column gives the (Unicode) name. The third column indicates
 290 by which class(es) the character is matched (assuming no locale or EBCDIC code
 291 page is in effect that changes the C<\s> matching).
 292
 293  0x0009        CHARACTER TABULATION   h s
 294  0x000a              LINE FEED (LF)    vs
 295  0x000b             LINE TABULATION    v
 296  0x000c              FORM FEED (FF)    vs
 297  0x000d        CARRIAGE RETURN (CR)    vs
 298  0x0020                       SPACE   h s
 299  0x0085             NEXT LINE (NEL)    vs  [1]
 300  0x00a0              NO-BREAK SPACE   h s  [1]
 301  0x1680            OGHAM SPACE MARK   h s
 302  0x180e   MONGOLIAN VOWEL SEPARATOR   h s
 303  0x2000                     EN QUAD   h s
 304  0x2001                     EM QUAD   h s
 305  0x2002                    EN SPACE   h s
 306  0x2003                    EM SPACE   h s
 307  0x2004          THREE-PER-EM SPACE   h s
 308  0x2005           FOUR-PER-EM SPACE   h s
 309  0x2006            SIX-PER-EM SPACE   h s
 310  0x2007                FIGURE SPACE   h s
 311  0x2008           PUNCTUATION SPACE   h s
 312  0x2009                  THIN SPACE   h s
 313  0x200a                  HAIR SPACE   h s
 314  0x2028              LINE SEPARATOR    vs
 315  0x2029         PARAGRAPH SEPARATOR    vs
 316  0x202f       NARROW NO-BREAK SPACE   h s
 317  0x205f   MEDIUM MATHEMATICAL SPACE   h s
 318  0x3000           IDEOGRAPHIC SPACE   h s
 319
 320 =over 4
 321
 322 =item [1]
 323
 324 NEXT LINE and NO-BREAK SPACE may or may not match C<\s> depending
 325 on the rules in effect.  See
 326 L<the beginning of this section|/Whitespace>.
 327
 328 =back
 329
 330 =head3 Unicode Properties
 331
 332 C<\pP> and C<\p{Prop}> are character classes to match characters that fit given
 333 Unicode properties.  One letter property names can be used in the C<\pP> form,
 334 with the property name following the C<\p>, otherwise, braces are required.
 335 When using braces, there is a single form, which is just the property name
 336 enclosed in the braces, and a compound form which looks like C<\p{name=value}>,
 337 which means to match if the property "name" for the character has that particular
 338 "value".
 339 For instance, a match for a number can be written as C</\pN/> or as
 340 C</\p{Number}/>, or as C</\p{Number=True}/>.
 341 Lowercase letters are matched by the property I<Lowercase_Letter> which
 342 has the short form I<Ll>. They need the braces, so are written as C</\p{Ll}/> or
 343 C</\p{Lowercase_Letter}/>, or C</\p{General_Category=Lowercase_Letter}/>
 344 (the underscores are optional).
 345 C</\pLl/> is valid, but means something different.
 346 It matches a two character string: a letter (Unicode property C<\pL>),
 347 followed by a lowercase C<l>.
 348
 349 If locale rules are not in effect, the use of
 350 a Unicode property will force the regular expression into using Unicode
 351 rules, if it isn't already.
 352
 353 Note that almost all properties are immune to case-insensitive matching.
 354 That is, adding a C</i> regular expression modifier does not change what
 355 they match.  There are two sets that are affected.  The first set is
 356 C<Uppercase_Letter>,
 357 C<Lowercase_Letter>,
 358 and C<Titlecase_Letter>,
 359 all of which match C<Cased_Letter> under C</i> matching.
 360 The second set is
 361 C<Uppercase>,
 362 C<Lowercase>,
 363 and C<Titlecase>,
 364 all of which match C<Cased> under C</i> matching.
 365 (The difference between these sets is that some things, such as Roman
 366 numerals, come in both upper and lower case, so they are C<Cased>, but
 367 aren't considered to be letters, so they aren't C<Cased_Letter>s. They're
 368 actually C<Letter_Number>s.)
 369 This set also includes its subsets C<PosixUpper> and C<PosixLower>, both
 370 of which under C</i> match C<PosixAlpha>.
 371
 372 For more details on Unicode properties, see L<perlunicode/Unicode
 373 Character Properties>; for a
 374 complete list of possible properties, see
 375 L<perluniprops/Properties accessible through \p{} and \P{}>,
 376 which notes all forms that have C</i> differences.
 377 It is also possible to define your own properties. This is discussed in
 378 L<perlunicode/User-Defined Character Properties>.
 379
 380 Unicode properties are defined (surprise!) only on Unicode code points.
 381 A warning is raised and all matches fail on non-Unicode code points
 382 (those above the legal Unicode maximum of 0x10FFFF).  This can be
 383 somewhat surprising,
 384
 385  chr(0x110000) =~ \p{ASCII_Hex_Digit=True}      # Fails.
 386  chr(0x110000) =~ \p{ASCII_Hex_Digit=False}     # Also fails!
 387
 388 Even though these two matches might be thought of as complements, they
 389 are so only on Unicode code points.
 390
 391 =head4 Examples
 392
 393  "a"  =~  /\w/      # Match, "a" is a 'word' character.
 394  "7"  =~  /\w/      # Match, "7" is a 'word' character as well.
 395  "a"  =~  /\d/      # No match, "a" isn't a digit.
 396  "7"  =~  /\d/      # Match, "7" is a digit.
 397  " "  =~  /\s/      # Match, a space is whitespace.
 398  "a"  =~  /\D/      # Match, "a" is a non-digit.
 399  "7"  =~  /\D/      # No match, "7" is not a non-digit.
 400  " "  =~  /\S/      # No match, a space is not non-whitespace.
 401
 402  " "  =~  /\h/      # Match, space is horizontal whitespace.
 403  " "  =~  /\v/      # No match, space is not vertical whitespace.
 404  "\r" =~  /\v/      # Match, a return is vertical whitespace.
 405
 406  "a"  =~  /\pL/     # Match, "a" is a letter.
 407  "a"  =~  /\p{Lu}/  # No match, /\p{Lu}/ matches upper case letters.
 408
 409  "\x{0e0b}" =~ /\p{Thai}/  # Match, \x{0e0b} is the character
 410                            # 'THAI CHARACTER SO SO', and that's in
 411                            # Thai Unicode class.
 412  "a"  =~  /\P{Lao}/ # Match, as "a" is not a Laotian character.
 413
 414 It is worth emphasizing that C<\d>, C<\w>, etc, match single characters, not
 415 complete numbers or words. To match a number (that consists of digits),
 416 use C<\d+>; to match a word, use C<\w+>.  But be aware of the security
 417 considerations in doing so, as mentioned above.
 418
 419 =head2 Bracketed Character Classes
 420
 421 The third form of character class you can use in Perl regular expressions
 422 is the bracketed character class.  In its simplest form, it lists the characters
 423 that may be matched, surrounded by square brackets, like this: C<[aeiou]>.
 424 This matches one of C<a>, C<e>, C<i>, C<o> or C<u>.  Like the other
 425 character classes, exactly one character is matched.* To match
 426 a longer string consisting of characters mentioned in the character
 427 class, follow the character class with a L<quantifier|perlre/Quantifiers>.  For
 428 instance, C<[aeiou]+> matches one or more lowercase English vowels.
 429
 430 Repeating a character in a character class has no
 431 effect; it's considered to be in the set only once.
 432
 433 Examples:
 434
 435  "e"  =~  /[aeiou]/        # Match, as "e" is listed in the class.
 436  "p"  =~  /[aeiou]/        # No match, "p" is not listed in the class.
 437  "ae" =~  /^[aeiou]$/      # No match, a character class only matches
 438                            # a single character.
 439  "ae" =~  /^[aeiou]+$/     # Match, due to the quantifier.
 440
 441  -------
 442
 443 * There is an exception to a bracketed character class matching a
 444 single character only.  When the class is to match caselessly under C</i>
 445 matching rules, and a character that is explicitly mentioned inside the
 446 class matches a
 447 multiple-character sequence caselessly under Unicode rules, the class
 448 (when not L<inverted|/Negation>) will also match that sequence.  For
 449 example, Unicode says that the letter C<LATIN SMALL LETTER SHARP S>
 450 should match the sequence C<ss> under C</i> rules.  Thus,
 451
 452  'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i             # Matches
 453  'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i    # Matches
 454
 455 For this to happen, the character must be explicitly specified, and not
 456 be part of a multi-character range (not even as one of its endpoints).
 457 (L</Character Ranges> will be explained shortly.)  Therefore,
 458
 459  'ss' =~ /\A[\0-\x{ff}]\z/i        # Doesn't match
 460  'ss' =~ /\A[\0-\N{LATIN SMALL LETTER SHARP S}]\z/i    # No match
 461  'ss' =~ /\A[\xDF-\xDF]\z/i    # Matches on ASCII platforms, since \XDF
 462                                # is LATIN SMALL LETTER SHARP S, and the
 463                                # range is just a single element
 464
 465 Note that it isn't a good idea to specify these types of ranges anyway.
 466
 467 =head3 Special Characters Inside a Bracketed Character Class
 468
 469 Most characters that are meta characters in regular expressions (that
 470 is, characters that carry a special meaning like C<.>, C<*>, or C<(>) lose
 471 their special meaning and can be used inside a character class without
 472 the need to escape them. For instance, C<[()]> matches either an opening
 473 parenthesis, or a closing parenthesis, and the parens inside the character
 474 class don't group or capture.
 475
 476 Characters that may carry a special meaning inside a character class are:
 477 C<\>, C<^>, C<->, C<[> and C<]>, and are discussed below. They can be
 478 escaped with a backslash, although this is sometimes not needed, in which
 479 case the backslash may be omitted.
 480
 481 The sequence C<\b> is special inside a bracketed character class. While
 482 outside the character class, C<\b> is an assertion indicating a point
 483 that does not have either two word characters or two non-word characters
 484 on either side, inside a bracketed character class, C<\b> matches a
 485 backspace character.
 486
 487 The sequences
 488 C<\a>,
 489 C<\c>,
 490 C<\e>,
 491 C<\f>,
 492 C<\n>,
 493 C<\N{I<NAME>}>,
 494 C<\N{U+I<hex char>}>,
 495 C<\r>,
 496 C<\t>,
 497 and
 498 C<\x>
 499 are also special and have the same meanings as they do outside a
 500 bracketed character class.  (However, inside a bracketed character
 501 class, if C<\N{I<NAME>}> expands to a sequence of characters, only the first
 502 one in the sequence is used, with a warning.)
 503
 504 Also, a backslash followed by two or three octal digits is considered an octal
 505 number.
 506
 507 A C<[> is not special inside a character class, unless it's the start of a
 508 POSIX character class (see L</POSIX Character Classes> below). It normally does
 509 not need escaping.
 510
 511 A C<]> is normally either the end of a POSIX character class (see
 512 L</POSIX Character Classes> below), or it signals the end of the bracketed
 513 character class.  If you want to include a C<]> in the set of characters, you
 514 must generally escape it.
 515
 516 However, if the C<]> is the I<first> (or the second if the first
 517 character is a caret) character of a bracketed character class, it
 518 does not denote the end of the class (as you cannot have an empty class)
 519 and is considered part of the set of characters that can be matched without
 520 escaping.
 521
 522 Examples:
 523
 524  "+"   =~ /[+?*]/     #  Match, "+" in a character class is not special.
 525  "\cH" =~ /[\b]/      #  Match, \b inside in a character class
 526                       #  is equivalent to a backspace.
 527  "]"   =~ /[][]/      #  Match, as the character class contains.
 528                       #  both [ and ].
 529  "[]"  =~ /[[]]/      #  Match, the pattern contains a character class
 530                       #  containing just ], and the character class is
 531                       #  followed by a ].
 532
 533 =head3 Character Ranges
 534
 535 It is not uncommon to want to match a range of characters. Luckily, instead
 536 of listing all characters in the range, one may use the hyphen (C<->).
 537 If inside a bracketed character class you have two characters separated
 538 by a hyphen, it's treated as if all characters between the two were in
 539 the class. For instance, C<[0-9]> matches any ASCII digit, and C<[a-m]>
 540 matches any lowercase letter from the first half of the ASCII alphabet.
 541
 542 Note that the two characters on either side of the hyphen are not
 543 necessarily both letters or both digits. Any character is possible,
 544 although not advisable.  C<['-?]> contains a range of characters, but
 545 most people will not know which characters that means.  Furthermore,
 546 such ranges may lead to portability problems if the code has to run on
 547 a platform that uses a different character set, such as EBCDIC.
 548
 549 If a hyphen in a character class cannot syntactically be part of a range, for
 550 instance because it is the first or the last character of the character class,
 551 or if it immediately follows a range, the hyphen isn't special, and so is
 552 considered a character to be matched literally.  If you want a hyphen in
 553 your set of characters to be matched and its position in the class is such
 554 that it could be considered part of a range, you must escape that hyphen
 555 with a backslash.
 556
 557 Examples:
 558
 559  [a-z]       #  Matches a character that is a lower case ASCII letter.
 560  [a-fz]      #  Matches any letter between 'a' and 'f' (inclusive) or
 561              #  the letter 'z'.
 562  [-z]        #  Matches either a hyphen ('-') or the letter 'z'.
 563  [a-f-m]     #  Matches any letter between 'a' and 'f' (inclusive), the
 564              #  hyphen ('-'), or the letter 'm'.
 565  ['-?]       #  Matches any of the characters  '()*+,-./0123456789:;<=>?
 566              #  (But not on an EBCDIC platform).
 567
 568
 569 =head3 Negation
 570
 571 It is also possible to instead list the characters you do not want to
 572 match. You can do so by using a caret (C<^>) as the first character in the
 573 character class. For instance, C<[^a-z]> matches any character that is not a
 574 lowercase ASCII letter, which therefore includes more than a million
 575 Unicode code points.  The class is said to be "negated" or "inverted".
 576
 577 This syntax make the caret a special character inside a bracketed character
 578 class, but only if it is the first character of the class. So if you want
 579 the caret as one of the characters to match, either escape the caret or
 580 else don't list it first.
 581
 582 In inverted bracketed character classes, Perl ignores the Unicode rules
 583 that normally say that certain characters should match a sequence of
 584 multiple characters under caseless C</i> matching.  Following those
 585 rules could lead to highly confusing situations:
 586
 587  "ss" =~ /^[^\xDF]+$/ui;   # Matches!
 588
 589 This should match any sequences of characters that aren't C<\xDF> nor
 590 what C<\xDF> matches under C</i>.  C<"s"> isn't C<\xDF>, but Unicode
 591 says that C<"ss"> is what C<\xDF> matches under C</i>.  So which one
 592 "wins"? Do you fail the match because the string has C<ss> or accept it
 593 because it has an C<s> followed by another C<s>?  Perl has chosen the
 594 latter.
 595
 596 Examples:
 597
 598  "e"  =~  /[^aeiou]/   #  No match, the 'e' is listed.
 599  "x"  =~  /[^aeiou]/   #  Match, as 'x' isn't a lowercase vowel.
 600  "^"  =~  /[^^]/       #  No match, matches anything that isn't a caret.
 601  "^"  =~  /[x^]/       #  Match, caret is not special here.
 602
 603 =head3 Backslash Sequences
 604
 605 You can put any backslash sequence character class (with the exception of
 606 C<\N> and C<\R>) inside a bracketed character class, and it will act just
 607 as if you had put all characters matched by the backslash sequence inside the
 608 character class. For instance, C<[a-f\d]> matches any decimal digit, or any
 609 of the lowercase letters between 'a' and 'f' inclusive.
 610
 611 C<\N> within a bracketed character class must be of the forms C<\N{I<name>}>
 612 or C<\N{U+I<hex char>}>, and NOT be the form that matches non-newlines,
 613 for the same reason that a dot C<.> inside a bracketed character class loses
 614 its special meaning: it matches nearly anything, which generally isn't what you
 615 want to happen.
 616
 617
 618 Examples:
 619
 620  /[\p{Thai}\d]/     # Matches a character that is either a Thai
 621                     # character, or a digit.
 622  /[^\p{Arabic}()]/  # Matches a character that is neither an Arabic
 623                     # character, nor a parenthesis.
 624
 625 Backslash sequence character classes cannot form one of the endpoints
 626 of a range.  Thus, you can't say:
 627
 628  /[\p{Thai}-\d]/     # Wrong!
 629
 630 =head3 POSIX Character Classes
 631 X<character class> X<\p> X<\p{}>
 632 X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph>
 633 X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit>
 634
 635 POSIX character classes have the form C<[:class:]>, where I<class> is
 636 name, and the C<[:> and C<:]> delimiters. POSIX character classes only appear
 637 I<inside> bracketed character classes, and are a convenient and descriptive
 638 way of listing a group of characters.
 639
 640 Be careful about the syntax,
 641
 642  # Correct:
 643  $string =~ /[[:alpha:]]/
 644
 645  # Incorrect (will warn):
 646  $string =~ /[:alpha:]/
 647
 648 The latter pattern would be a character class consisting of a colon,
 649 and the letters C<a>, C<l>, C<p> and C<h>.
 650 POSIX character classes can be part of a larger bracketed character class.
 651 For example,
 652
 653  [01[:alpha:]%]
 654
 655 is valid and matches '0', '1', any alphabetic character, and the percent sign.
 656
 657 Perl recognizes the following POSIX character classes:
 658
 659  alpha  Any alphabetical character ("[A-Za-z]").
 660  alnum  Any alphanumeric character. ("[A-Za-z0-9]")
 661  ascii  Any character in the ASCII character set.
 662  blank  A GNU extension, equal to a space or a horizontal tab ("\t").
 663  cntrl  Any control character.  See Note [2] below.
 664  digit  Any decimal digit ("[0-9]"), equivalent to "\d".
 665  graph  Any printable character, excluding a space.  See Note [3] below.
 666  lower  Any lowercase character ("[a-z]").
 667  print  Any printable character, including a space.  See Note [4] below.
 668  punct  Any graphical character excluding "word" characters.  Note [5].
 669  space  Any whitespace character. "\s" plus the vertical tab ("\cK").
 670  upper  Any uppercase character ("[A-Z]").
 671  word   A Perl extension ("[A-Za-z0-9_]"), equivalent to "\w".
 672  xdigit Any hexadecimal digit ("[0-9a-fA-F]").
 673
 674 Most POSIX character classes have two Unicode-style C<\p> property
 675 counterparts.  (They are not official Unicode properties, but Perl extensions
 676 derived from official Unicode properties.)  The table below shows the relation
 677 between POSIX character classes and these counterparts.
 678
 679 One counterpart, in the column labelled "ASCII-range Unicode" in
 680 the table, matches only characters in the ASCII character set.
 681
 682 The other counterpart, in the column labelled "Full-range Unicode", matches any
 683 appropriate characters in the full Unicode character set.  For example,
 684 C<\p{Alpha}> matches not just the ASCII alphabetic characters, but any
 685 character in the entire Unicode character set considered alphabetic.
 686 An entry in the column labelled "backslash sequence" is a (short)
 687 equivalent.
 688
 689  [[:...:]]      ASCII-range          Full-range  backslash  Note
 690                  Unicode              Unicode     sequence
 691  -----------------------------------------------------
 692    alpha      \p{PosixAlpha}       \p{XPosixAlpha}
 693    alnum      \p{PosixAlnum}       \p{XPosixAlnum}
 694    ascii      \p{ASCII}
 695    blank      \p{PosixBlank}       \p{XPosixBlank}  \h      [1]
 696                                    or \p{HorizSpace}        [1]
 697    cntrl      \p{PosixCntrl}       \p{XPosixCntrl}          [2]
 698    digit      \p{PosixDigit}       \p{XPosixDigit}  \d
 699    graph      \p{PosixGraph}       \p{XPosixGraph}          [3]
 700    lower      \p{PosixLower}       \p{XPosixLower}
 701    print      \p{PosixPrint}       \p{XPosixPrint}          [4]
 702    punct      \p{PosixPunct}       \p{XPosixPunct}          [5]
 703               \p{PerlSpace}        \p{XPerlSpace}   \s      [6]
 704    space      \p{PosixSpace}       \p{XPosixSpace}          [6]
 705    upper      \p{PosixUpper}       \p{XPosixUpper}
 706    word       \p{PosixWord}        \p{XPosixWord}   \w
 707    xdigit     \p{PosixXDigit}      \p{XPosixXDigit}
 708
 709 =over 4
 710
 711 =item [1]
 712
 713 C<\p{Blank}> and C<\p{HorizSpace}> are synonyms.
 714
 715 =item [2]
 716
 717 Control characters don't produce output as such, but instead usually control
 718 the terminal somehow: for example, newline and backspace are control characters.
 719 In the ASCII range, characters whose code points are between 0 and 31 inclusive,
 720 plus 127 (C<DEL>) are control characters.
 721
 722 On EBCDIC platforms, it is likely that the code page will define C<[[:cntrl:]]>
 723 to be the EBCDIC equivalents of the ASCII controls, plus the controls
 724 that in Unicode have code points from 128 through 159.
 725
 726 =item [3]
 727
 728 Any character that is I<graphical>, that is, visible. This class consists
 729 of all alphanumeric characters and all punctuation characters.
 730
 731 =item [4]
 732
 733 All printable characters, which is the set of all graphical characters
 734 plus those whitespace characters which are not also controls.
 735
 736 =item [5]
 737
 738 C<\p{PosixPunct}> and C<[[:punct:]]> in the ASCII range match all
 739 non-controls, non-alphanumeric, non-space characters:
 740 C<[-!"#$%&'()*+,./:;<=E<gt>?@[\\\]^_`{|}~]> (although if a locale is in effect,
 741 it could alter the behavior of C<[[:punct:]]>).
 742
 743 The similarly named property, C<\p{Punct}>, matches a somewhat different
 744 set in the ASCII range, namely
 745 C<[-!"#%&'()*,./:;?@[\\\]_{}]>.  That is, it is missing the nine
 746 characters C<[$+E<lt>=E<gt>^`|~]>.
 747 This is because Unicode splits what POSIX considers to be punctuation into two
 748 categories, Punctuation and Symbols.
 749
 750 C<\p{XPosixPunct}> and (under Unicode rules) C<[[:punct:]]>, match what
 751 C<\p{PosixPunct}> matches in the ASCII range, plus what C<\p{Punct}>
 752 matches.  This is different than strictly matching according to
 753 C<\p{Punct}>.  Another way to say it is that
 754 if Unicode rules are in effect, C<[[:punct:]]> matches all characters
 755 that Unicode considers punctuation, plus all ASCII-range characters that
 756 Unicode considers symbols.
 757
 758 =item [6]
 759
 760 C<\p{SpacePerl}> and C<\p{Space}> differ only in that in non-locale
 761 matching, C<\p{Space}> additionally
 762 matches the vertical tab, C<\cK>.   Same for the two ASCII-only range forms.
 763
 764 =back
 765
 766 There are various other synonyms that can be used besides the names
 767 listed in the table.  For example, C<\p{PosixAlpha}> can be written as
 768 C<\p{Alpha}>.  All are listed in
 769 L<perluniprops/Properties accessible through \p{} and \P{}>,
 770 plus all characters matched by each ASCII-range property.
 771
 772 Both the C<\p> counterparts always assume Unicode rules are in effect.
 773 On ASCII platforms, this means they assume that the code points from 128
 774 to 255 are Latin-1, and that means that using them under locale rules is
 775 unwise unless the locale is guaranteed to be Latin-1 or UTF-8.  In contrast, the
 776 POSIX character classes are useful under locale rules.  They are
 777 affected by the actual rules in effect, as follows:
 778
 779 =over
 780
 781 =item If the C</a> modifier, is in effect ...
 782
 783 Each of the POSIX classes matches exactly the same as their ASCII-range
 784 counterparts.
 785
 786 =item otherwise ...
 787
 788 =over
 789
 790 =item For code points above 255 ...
 791
 792 The POSIX class matches the same as its Full-range counterpart.
 793
 794 =item For code points below 256 ...
 795
 796 =over
 797
 798 =item if locale rules are in effect ...
 799
 800 The POSIX class matches according to the locale, except that
 801 C<word> uses the platform's native underscore character, no matter what
 802 the locale is.
 803
 804 =item if Unicode rules are in effect or if on an EBCDIC platform ...
 805
 806 The POSIX class matches the same as the Full-range counterpart.
 807
 808 =item otherwise ...
 809
 810 The POSIX class matches the same as the ASCII range counterpart.
 811
 812 =back
 813
 814 =back
 815
 816 =back
 817
 818 Which rules apply are determined as described in
 819 L<perlre/Which character set modifier is in effect?>.
 820
 821 It is proposed to change this behavior in a future release of Perl so that
 822 whether or not Unicode rules are in effect would not change the
 823 behavior:  Outside of locale or an EBCDIC code page, the POSIX classes
 824 would behave like their ASCII-range counterparts.  If you wish to
 825 comment on this proposal, send email to C<perl5-porters@perl.org>.
 826
 827 =head4 Negation of POSIX character classes
 828 X<character class, negation>
 829
 830 A Perl extension to the POSIX character class is the ability to
 831 negate it. This is done by prefixing the class name with a caret (C<^>).
 832 Some examples:
 833
 834      POSIX         ASCII-range     Full-range  backslash
 835                     Unicode         Unicode    sequence
 836  -----------------------------------------------------
 837  [[:^digit:]]   \P{PosixDigit}  \P{XPosixDigit}   \D
 838  [[:^space:]]   \P{PosixSpace}  \P{XPosixSpace}
 839                 \P{PerlSpace}   \P{XPerlSpace}    \S
 840  [[:^word:]]    \P{PerlWord}    \P{XPosixWord}    \W
 841
 842 The backslash sequence can mean either ASCII- or Full-range Unicode,
 843 depending on various factors as described in L<perlre/Which character set modifier is in effect?>.
 844
 845 =head4 [= =] and [. .]
 846
 847 Perl recognizes the POSIX character classes C<[=class=]> and
 848 C<[.class.]>, but does not (yet?) support them.  Any attempt to use
 849 either construct raises an exception.
 850
 851 =head4 Examples
 852
 853  /[[:digit:]]/            # Matches a character that is a digit.
 854  /[01[:lower:]]/          # Matches a character that is either a
 855                           # lowercase letter, or '0' or '1'.
 856  /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
 857                           # except the letters 'a' to 'f' and 'A' to
 858                           # 'F'.  This is because the main character
 859                           # class is composed of two POSIX character
 860                           # classes that are ORed together, one that
 861                           # matches any digit, and the other that
 862                           # matches anything that isn't a hex digit.
 863                           # The OR adds the digits, leaving only the
 864                           # letters 'a' to 'f' and 'A' to 'F' excluded.