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