Create perldelta for 5.14.3
[perl.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 Digits
76
77 C<\d> matches a single character considered to be a decimal I<digit>.
78 If the C</a> modifier in effect, it matches [0-9].  Otherwise, it
79 matches anything that is matched by C<\p{Digit}>, which includes [0-9].
80 (An unlikely possible exception is that under locale matching rules, the
81 current locale might not have [0-9] matched by C<\d>, and/or might match
82 other characters whose code point is less than 256.  Such a locale
83 definition would be in violation of the C language standard, but Perl
84 doesn't currently assume anything in regard to this.)
85
86 What this means is that unless the C</a> modifier is in effect C<\d> not
87 only matches the digits '0' - '9', but also Arabic, Devanagari, and
88 digits from other languages.  This may cause some confusion, and some
89 security issues.
90
91 Some digits that C<\d> matches look like some of the [0-9] ones, but
92 have different values.  For example, BENGALI DIGIT FOUR (U+09EA) looks
93 very much like an ASCII DIGIT EIGHT (U+0038).  An application that
94 is expecting only the ASCII digits might be misled, or if the match is
95 C<\d+>, the matched string might contain a mixture of digits from
96 different writing systems that look like they signify a number different
97 than they actually do. L<Unicode::UCD/num()> can be used to safely
98 calculate the value, returning C<undef> if the input string contains
99 such a mixture.
100
101 What C<\p{Digit}> means (and hence C<\d> except under the C</a>
102 modifier) is C<\p{General_Category=Decimal_Number}>, or synonymously,
103 C<\p{General_Category=Digit}>.  Starting with Unicode version 4.1, this
104 is the same set of characters matched by C<\p{Numeric_Type=Decimal}>.
105 But Unicode also has a different property with a similar name,
106 C<\p{Numeric_Type=Digit}>, which matches a completely different set of
107 characters.  These characters are things such as C<CIRCLED DIGIT ONE>
108 or subscripts, or are from writing systems that lack all ten digits.
109
110 The design intent is for C<\d> to exactly match the set of characters
111 that can safely be used with "normal" big-endian positional decimal
112 syntax, where, for example 123 means one 'hundred', plus two 'tens',
113 plus three 'ones'.  This positional notation does not necessarily apply
114 to characters that match the other type of "digit",
115 C<\p{Numeric_Type=Digit}>, and so C<\d> doesn't match them.
116
117 In Unicode 5.2, the Tamil digits (U+0BE6 - U+0BEF) can also legally be
118 used in old-style Tamil numbers in which they would appear no more than
119 one in a row, separated by characters that mean "times 10", "times 100",
120 etc.  (See L<http://www.unicode.org/notes/tn21>.)
121
122 Any character not matched by C<\d> is matched by C<\D>.
123
124 =head3 Word characters
125
126 A C<\w> matches a single alphanumeric character (an alphabetic character, or a
127 decimal digit) or a connecting punctuation character, such as an
128 underscore ("_").  It does not match a whole word.  To match a whole
129 word, use C<\w+>.  This isn't the same thing as matching an English word, but
130 in the ASCII range it is the same as a string of Perl-identifier
131 characters.
132
133 =over
134
135 =item If the C</a> modifier is in effect ...
136
137 C<\w> matches the 63 characters [a-zA-Z0-9_].
138
139 =item otherwise ...
140
141 =over
142
143 =item For code points above 255 ...
144
145 C<\w> matches the same as C<\p{Word}> matches in this range.  That is,
146 it matches Thai letters, Greek letters, etc.  This includes connector
147 punctuation (like the underscore) which connect two words together, or
148 diacritics, such as a C<COMBINING TILDE> and the modifier letters, which
149 are generally used to add auxiliary markings to letters.
150
151 =item For code points below 256 ...
152
153 =over
154
155 =item if locale rules are in effect ...
156
157 C<\w> matches the platform's native underscore character plus whatever
158 the locale considers to be alphanumeric.
159
160 =item if Unicode rules are in effect or if on an EBCDIC platform ...
161
162 C<\w> matches exactly what C<\p{Word}> matches.
163
164 =item otherwise ...
165
166 C<\w> matches [a-zA-Z0-9_].
167
168 =back
169
170 =back
171
172 =back
173
174 Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
175
176 There are a number of security issues with the full Unicode list of word
177 characters.  See L<http://unicode.org/reports/tr36>.
178
179 Also, for a somewhat finer-grained set of characters that are in programming
180 language identifiers beyond the ASCII range, you may wish to instead use the
181 more customized Unicode properties, "ID_Start", ID_Continue", "XID_Start", and
182 "XID_Continue".  See L<http://unicode.org/reports/tr31>.
183
184 Any character not matched by C<\w> is matched by C<\W>.
185
186 =head3 Whitespace
187
188 C<\s> matches any single character considered whitespace.
189
190 =over
191
192 =item If the C</a> modifier is in effect ...
193
194 C<\s> matches the 5 characters [\t\n\f\r ]; that is, the horizontal tab,
195 the newline, the form feed, the carriage return, and the space.  (Note
196 that it doesn't match the vertical tab, C<\cK> on ASCII platforms.)
197
198 =item otherwise ...
199
200 =over
201
202 =item For code points above 255 ...
203
204 C<\s> matches exactly the code points above 255 shown with an "s" column
205 in the table below.
206
207 =item For code points below 256 ...
208
209 =over
210
211 =item if locale rules are in effect ...
212
213 C<\s> matches whatever the locale considers to be whitespace.  Note that
214 this is likely to include the vertical space, unlike non-locale C<\s>
215 matching.
216
217 =item if Unicode rules are in effect or if on an EBCDIC platform ...
218
219 C<\s> matches exactly the characters shown with an "s" column in the
220 table below.
221
222 =item otherwise ...
223
224 C<\s> matches [\t\n\f\r ].
225 Note that this list doesn't include the non-breaking space.
226
227 =back
228
229 =back
230
231 =back
232
233 Which rules apply are determined as described in L<perlre/Which character set modifier is in effect?>.
234
235 Any character not matched by C<\s> is matched by C<\S>.
236
237 C<\h> matches any character considered horizontal whitespace;
238 this includes the space and tab characters and several others
239 listed in the table below.  C<\H> matches any character
240 not considered horizontal whitespace.
241
242 C<\v> matches any character considered vertical whitespace;
243 this includes the carriage return and line feed characters (newline)
244 plus several other characters, all listed in the table below.
245 C<\V> matches any character not considered vertical whitespace.
246
247 C<\R> matches anything that can be considered a newline under Unicode
248 rules. It's not a character class, as it can match a multi-character
249 sequence. Therefore, it cannot be used inside a bracketed character
250 class; use C<\v> instead (vertical whitespace).
251 Details are discussed in L<perlrebackslash>.
252
253 Note that unlike C<\s> (and C<\d> and C<\w>), C<\h> and C<\v> always match
254 the same characters, without regard to other factors, such as whether the
255 source string is in UTF-8 format.
256
257 One might think that C<\s> is equivalent to C<[\h\v]>. This is not true.
258 For example, the vertical tab (C<"\x0b">) is not matched by C<\s>, it is
259 however considered vertical whitespace.
260
261 The following table is a complete listing of characters matched by
262 C<\s>, C<\h> and C<\v> as of Unicode 6.0.
263
264 The first column gives the code point of the character (in hex format),
265 the second column gives the (Unicode) name. The third column indicates
266 by which class(es) the character is matched (assuming no locale or EBCDIC code
267 page is in effect that changes the C<\s> matching).
268
269  0x00009        CHARACTER TABULATION   h s
270  0x0000a              LINE FEED (LF)    vs
271  0x0000b             LINE TABULATION    v
272  0x0000c              FORM FEED (FF)    vs
273  0x0000d        CARRIAGE RETURN (CR)    vs
274  0x00020                       SPACE   h s
275  0x00085             NEXT LINE (NEL)    vs  [1]
276  0x000a0              NO-BREAK SPACE   h s  [1]
277  0x01680            OGHAM SPACE MARK   h s
278  0x0180e   MONGOLIAN VOWEL SEPARATOR   h s
279  0x02000                     EN QUAD   h s
280  0x02001                     EM QUAD   h s
281  0x02002                    EN SPACE   h s
282  0x02003                    EM SPACE   h s
283  0x02004          THREE-PER-EM SPACE   h s
284  0x02005           FOUR-PER-EM SPACE   h s
285  0x02006            SIX-PER-EM SPACE   h s
286  0x02007                FIGURE SPACE   h s
287  0x02008           PUNCTUATION SPACE   h s
288  0x02009                  THIN SPACE   h s
289  0x0200a                  HAIR SPACE   h s
290  0x02028              LINE SEPARATOR    vs
291  0x02029         PARAGRAPH SEPARATOR    vs
292  0x0202f       NARROW NO-BREAK SPACE   h s
293  0x0205f   MEDIUM MATHEMATICAL SPACE   h s
294  0x03000           IDEOGRAPHIC SPACE   h s
295
296 =over 4
297
298 =item [1]
299
300 NEXT LINE and NO-BREAK SPACE may or may not match C<\s> depending
301 on the rules in effect.  See
302 L<the beginning of this section|/Whitespace>.
303
304 =back
305
306 =head3 \N
307
308 C<\N> is new in 5.12, and is experimental.  It, like the dot, matches any
309 character that is not a newline. The difference is that C<\N> is not influenced
310 by the I<single line> regular expression modifier (see L</The dot> above).  Note
311 that the form C<\N{...}> may mean something completely different.  When the
312 C<{...}> is a L<quantifier|perlre/Quantifiers>, it means to match a non-newline
313 character that many times.  For example, C<\N{3}> means to match 3
314 non-newlines; C<\N{5,}> means to match 5 or more non-newlines.  But if C<{...}>
315 is not a legal quantifier, it is presumed to be a named character.  See
316 L<charnames> for those.  For example, none of C<\N{COLON}>, C<\N{4F}>, and
317 C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose
318 names are respectively C<COLON>, C<4F>, and C<F4>.
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 (Each of the counterparts has various synonyms as well.
655 L<perluniprops/Properties accessible through \p{} and \P{}> lists all
656 synonyms, plus all characters matched by each ASCII-range property.
657 For example, C<\p{AHex}> is a synonym for C<\p{ASCII_Hex_Digit}>,
658 and any C<\p> property name can be prefixed with "Is" such as C<\p{IsAlpha}>.)
659
660 Both the C<\p> counterparts always assume Unicode rules are in effect.
661 On ASCII platforms, this means they assume that the code points from 128
662 to 255 are Latin-1, and that means that using them under locale rules is
663 unwise unless the locale is guaranteed to be Latin-1 or UTF-8.  In contrast, the
664 POSIX character classes are useful under locale rules.  They are
665 affected by the actual rules in effect, as follows:
666
667 =over
668
669 =item If the C</a> modifier, is in effect ...
670
671 Each of the POSIX classes matches exactly the same as their ASCII-range
672 counterparts.
673
674 =item otherwise ...
675
676 =over
677
678 =item For code points above 255 ...
679
680 The POSIX class matches the same as its Full-range counterpart.
681
682 =item For code points below 256 ...
683
684 =over
685
686 =item if locale rules are in effect ...
687
688 The POSIX class matches according to the locale.
689
690 =item if Unicode rules are in effect or if on an EBCDIC platform ...
691
692 The POSIX class matches the same as the Full-range counterpart.
693
694 =item otherwise ...
695
696 The POSIX class matches the same as the ASCII range counterpart.
697
698 =back
699
700 =back
701
702 =back
703
704 Which rules apply are determined as described in
705 L<perlre/Which character set modifier is in effect?>.
706
707 It is proposed to change this behavior in a future release of Perl so that
708 whether or not Unicode rules are in effect would not change the
709 behavior:  Outside of locale or an EBCDIC code page, the POSIX classes
710 would behave like their ASCII-range counterparts.  If you wish to
711 comment on this proposal, send email to C<perl5-porters@perl.org>.
712
713  [[:...:]]      ASCII-range          Full-range  backslash  Note
714                  Unicode              Unicode     sequence
715  -----------------------------------------------------
716    alpha      \p{PosixAlpha}       \p{XPosixAlpha}
717    alnum      \p{PosixAlnum}       \p{XPosixAlnum}
718    ascii      \p{ASCII}
719    blank      \p{PosixBlank}       \p{XPosixBlank}  \h      [1]
720                                    or \p{HorizSpace}        [1]
721    cntrl      \p{PosixCntrl}       \p{XPosixCntrl}          [2]
722    digit      \p{PosixDigit}       \p{XPosixDigit}  \d
723    graph      \p{PosixGraph}       \p{XPosixGraph}          [3]
724    lower      \p{PosixLower}       \p{XPosixLower}
725    print      \p{PosixPrint}       \p{XPosixPrint}          [4]
726    punct      \p{PosixPunct}       \p{XPosixPunct}          [5]
727               \p{PerlSpace}        \p{XPerlSpace}   \s      [6]
728    space      \p{PosixSpace}       \p{XPosixSpace}          [6]
729    upper      \p{PosixUpper}       \p{XPosixUpper}
730    word       \p{PosixWord}        \p{XPosixWord}   \w
731    xdigit     \p{PosixXDigit}      \p{XPosixXDigit}
732
733 =over 4
734
735 =item [1]
736
737 C<\p{Blank}> and C<\p{HorizSpace}> are synonyms.
738
739 =item [2]
740
741 Control characters don't produce output as such, but instead usually control
742 the terminal somehow: for example, newline and backspace are control characters.
743 In the ASCII range, characters whose code points are between 0 and 31 inclusive,
744 plus 127 (C<DEL>) are control characters.
745
746 On EBCDIC platforms, it is likely that the code page will define C<[[:cntrl:]]>
747 to be the EBCDIC equivalents of the ASCII controls, plus the controls
748 that in Unicode have code pointss from 128 through 159.
749
750 =item [3]
751
752 Any character that is I<graphical>, that is, visible. This class consists
753 of all alphanumeric characters and all punctuation characters.
754
755 =item [4]
756
757 All printable characters, which is the set of all graphical characters
758 plus those whitespace characters which are not also controls.
759
760 =item [5]
761
762 C<\p{PosixPunct}> and C<[[:punct:]]> in the ASCII range match all
763 non-controls, non-alphanumeric, non-space characters:
764 C<[-!"#$%&'()*+,./:;<=E<gt>?@[\\\]^_`{|}~]> (although if a locale is in effect,
765 it could alter the behavior of C<[[:punct:]]>).
766
767 The similarly named property, C<\p{Punct}>, matches a somewhat different
768 set in the ASCII range, namely
769 C<[-!"#%&'()*,./:;?@[\\\]_{}]>.  That is, it is missing C<[$+E<lt>=E<gt>^`|~]>.
770 This is because Unicode splits what POSIX considers to be punctuation into two
771 categories, Punctuation and Symbols.
772
773 C<\p{XPosixPunct}> and (in Unicode mode) C<[[:punct:]]>, match what
774 C<\p{PosixPunct}> matches in the ASCII range, plus what C<\p{Punct}>
775 matches.  This is different than strictly matching according to
776 C<\p{Punct}>.  Another way to say it is that
777 if Unicode rules are in effect, C<[[:punct:]]> matches all characters
778 that Unicode considers punctuation, plus all ASCII-range characters that
779 Unicode considers symbols.
780
781 =item [6]
782
783 C<\p{SpacePerl}> and C<\p{Space}> differ only in that in non-locale
784 matching, C<\p{Space}> additionally
785 matches the vertical tab, C<\cK>.   Same for the two ASCII-only range forms.
786
787 =back
788
789 There are various other synonyms that can be used for these besides
790 C<\p{HorizSpace}> and \C<\p{XPosixBlank}>.  For example,
791 C<\p{PosixAlpha}> can be written as C<\p{Alpha}>.  All are listed
792 in L<perluniprops/Properties accessible through \p{} and \P{}>.
793
794 =head4 Negation of POSIX character classes
795 X<character class, negation>
796
797 A Perl extension to the POSIX character class is the ability to
798 negate it. This is done by prefixing the class name with a caret (C<^>).
799 Some examples:
800
801      POSIX         ASCII-range     Full-range  backslash
802                     Unicode         Unicode    sequence
803  -----------------------------------------------------
804  [[:^digit:]]   \P{PosixDigit}  \P{XPosixDigit}   \D
805  [[:^space:]]   \P{PosixSpace}  \P{XPosixSpace}
806                 \P{PerlSpace}   \P{XPerlSpace}    \S
807  [[:^word:]]    \P{PerlWord}    \P{XPosixWord}    \W
808
809 The backslash sequence can mean either ASCII- or Full-range Unicode,
810 depending on various factors as described in L<perlre/Which character set modifier is in effect?>.
811
812 =head4 [= =] and [. .]
813
814 Perl recognizes the POSIX character classes C<[=class=]> and
815 C<[.class.]>, but does not (yet?) support them.  Any attempt to use
816 either construct raises an exception.
817
818 =head4 Examples
819
820  /[[:digit:]]/            # Matches a character that is a digit.
821  /[01[:lower:]]/          # Matches a character that is either a
822                           # lowercase letter, or '0' or '1'.
823  /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
824                           # except the letters 'a' to 'f'.  This is
825                           # because the main character class is composed
826                           # of two POSIX character classes that are ORed
827                           # together, one that matches any digit, and
828                           # the other that matches anything that isn't a
829                           # hex digit.  The result matches all
830                           # characters except the letters 'a' to 'f' and
831                           # 'A' to 'F'.