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