1PERLRECHARCLASS(1)     Perl Programmers Reference Guide     PERLRECHARCLASS(1)
2
3
4

NAME

6       perlrecharclass - Perl Regular Expression Character Classes
7

DESCRIPTION

9       The top level documentation about Perl regular expressions is found in
10       perlre.
11
12       This manual page discusses the syntax and use of character classes in
13       Perl regular expressions.
14
15       A character class is a way of denoting a set of characters in such a
16       way that one character of the set is matched.  It's important to
17       remember that: matching a character class consumes exactly one
18       character in the source string. (The source string is the string the
19       regular expression is matched against.)
20
21       There are three types of character classes in Perl regular expressions:
22       the dot, backslash sequences, and the form enclosed in square brackets.
23       Keep in mind, though, that often the term "character class" is used to
24       mean just the bracketed form.  Certainly, most Perl documentation does
25       that.
26
27   The dot
28       The dot (or period), "." is probably the most used, and certainly the
29       most well-known character class. By default, a dot matches any
30       character, except for the newline. That default can be changed to add
31       matching the newline by using the single line modifier: for the entire
32       regular expression with the "/s" modifier, or locally with "(?s)"  (and
33       even globally within the scope of "use re '/s'").  (The "\N" backslash
34       sequence, described below, matches any character except newline without
35       regard to the single line modifier.)
36
37       Here are some examples:
38
39        "a"  =~  /./       # Match
40        "."  =~  /./       # Match
41        ""   =~  /./       # No match (dot has to match a character)
42        "\n" =~  /./       # No match (dot does not match a newline)
43        "\n" =~  /./s      # Match (global 'single line' modifier)
44        "\n" =~  /(?s:.)/  # Match (local 'single line' modifier)
45        "ab" =~  /^.$/     # No match (dot matches one character)
46
47   Backslash sequences
48       A backslash sequence is a sequence of characters, the first one of
49       which is a backslash.  Perl ascribes special meaning to many such
50       sequences, and some of these are character classes.  That is, they
51       match a single character each, provided that the character belongs to
52       the specific set of characters defined by the sequence.
53
54       Here's a list of the backslash sequences that are character classes.
55       They are discussed in more detail below.  (For the backslash sequences
56       that aren't character classes, see perlrebackslash.)
57
58        \d             Match a decimal digit character.
59        \D             Match a non-decimal-digit character.
60        \w             Match a "word" character.
61        \W             Match a non-"word" character.
62        \s             Match a whitespace character.
63        \S             Match a non-whitespace character.
64        \h             Match a horizontal whitespace character.
65        \H             Match a character that isn't horizontal whitespace.
66        \v             Match a vertical whitespace character.
67        \V             Match a character that isn't vertical whitespace.
68        \N             Match a character that isn't a newline.
69        \pP, \p{Prop}  Match a character that has the given Unicode property.
70        \PP, \P{Prop}  Match a character that doesn't have the Unicode property
71
72       \N
73
74       "\N", available starting in v5.12, like the dot, matches any character
75       that is not a newline. The difference is that "\N" is not influenced by
76       the single line regular expression modifier (see "The dot" above).
77       Note that the form "\N{...}" may mean something completely different.
78       When the "{...}" is a quantifier, it means to match a non-newline
79       character that many times.  For example, "\N{3}" means to match 3 non-
80       newlines; "\N{5,}" means to match 5 or more non-newlines.  But if
81       "{...}" is not a legal quantifier, it is presumed to be a named
82       character.  See charnames for those.  For example, none of "\N{COLON}",
83       "\N{4F}", and "\N{F4}" contain legal quantifiers, so Perl will try to
84       find characters whose names are respectively "COLON", "4F", and "F4".
85
86       Digits
87
88       "\d" matches a single character considered to be a decimal digit.  If
89       the "/a" regular expression modifier is in effect, it matches [0-9].
90       Otherwise, it matches anything that is matched by "\p{Digit}", which
91       includes [0-9].  (An unlikely possible exception is that under locale
92       matching rules, the current locale might not have "[0-9]" matched by
93       "\d", and/or might match other characters whose code point is less than
94       256.  The only such locale definitions that are legal would be to match
95       "[0-9]" plus another set of 10 consecutive digit characters;  anything
96       else would be in violation of the C language standard, but Perl doesn't
97       currently assume anything in regard to this.)
98
99       What this means is that unless the "/a" modifier is in effect "\d" not
100       only matches the digits '0' - '9', but also Arabic, Devanagari, and
101       digits from other languages.  This may cause some confusion, and some
102       security issues.
103
104       Some digits that "\d" matches look like some of the [0-9] ones, but
105       have different values.  For example, BENGALI DIGIT FOUR (U+09EA) looks
106       very much like an ASCII DIGIT EIGHT (U+0038), and LEPCHA DIGIT SIX
107       (U+1C46) looks very much like an ASCII DIGIT FIVE (U+0035).  An
108       application that is expecting only the ASCII digits might be misled, or
109       if the match is "\d+", the matched string might contain a mixture of
110       digits from different writing systems that look like they signify a
111       number different than they actually do.  "num()" in Unicode::UCD can be
112       used to safely calculate the value, returning "undef" if the input
113       string contains such a mixture.  Otherwise, for example, a displayed
114       price might be deliberately different than it appears.
115
116       What "\p{Digit}" means (and hence "\d" except under the "/a" modifier)
117       is "\p{General_Category=Decimal_Number}", or synonymously,
118       "\p{General_Category=Digit}".  Starting with Unicode version 4.1, this
119       is the same set of characters matched by "\p{Numeric_Type=Decimal}".
120       But Unicode also has a different property with a similar name,
121       "\p{Numeric_Type=Digit}", which matches a completely different set of
122       characters.  These characters are things such as "CIRCLED DIGIT ONE" or
123       subscripts, or are from writing systems that lack all ten digits.
124
125       The design intent is for "\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       "\p{Numeric_Type=Digit}", and so "\d" doesn't match them.
131
132       The Tamil digits (U+0BE6 - U+0BEF) can also legally be used in old-
133       style Tamil numbers in which they would appear no more than one in a
134       row, separated by characters that mean "times 10", "times 100", etc.
135       (See <http://www.unicode.org/notes/tn21>.)
136
137       Any character not matched by "\d" is matched by "\D".
138
139       Word characters
140
141       A "\w" matches a single alphanumeric character (an alphabetic
142       character, or a decimal digit); or a connecting punctuation character,
143       such as an underscore ("_"); or a "mark" character (like some sort of
144       accent) that attaches to one of those.  It does not match a whole word.
145       To match a whole word, use "\w+".  This isn't the same thing as
146       matching an English word, but in the ASCII range it is the same as a
147       string of Perl-identifier characters.
148
149       If the "/a" modifier is in effect ...
150           "\w" matches the 63 characters [a-zA-Z0-9_].
151
152       otherwise ...
153           For code points above 255 ...
154               "\w" matches the same as "\p{Word}" matches in this range.
155               That is, it matches Thai letters, Greek letters, etc.  This
156               includes connector punctuation (like the underscore) which
157               connect two words together, or diacritics, such as a "COMBINING
158               TILDE" and the modifier letters, which are generally used to
159               add auxiliary markings to letters.
160
161           For code points below 256 ...
162               if locale rules are in effect ...
163                   "\w" matches the platform's native underscore character
164                   plus whatever the locale considers to be alphanumeric.
165
166               if, instead, Unicode rules are in effect ...
167                   "\w" matches exactly what "\p{Word}" matches.
168
169               otherwise ...
170                   "\w" matches [a-zA-Z0-9_].
171
172       Which rules apply are determined as described in "Which character set
173       modifier is in effect?" in perlre.
174
175       There are a number of security issues with the full Unicode list of
176       word characters.  See <http://unicode.org/reports/tr36>.
177
178       Also, for a somewhat finer-grained set of characters that are in
179       programming language identifiers beyond the ASCII range, you may wish
180       to instead use the more customized "Unicode Properties",
181       "\p{ID_Start}", "\p{ID_Continue}", "\p{XID_Start}", and
182       "\p{XID_Continue}".  See <http://unicode.org/reports/tr31>.
183
184       Any character not matched by "\w" is matched by "\W".
185
186       Whitespace
187
188       "\s" matches any single character considered whitespace.
189
190       If the "/a" modifier is in effect ...
191           In all Perl versions, "\s" matches the 5 characters [\t\n\f\r ];
192           that is, the horizontal tab, the newline, the form feed, the
193           carriage return, and the space.  Starting in Perl v5.18, it also
194           matches the vertical tab, "\cK".  See note "[1]" below for a
195           discussion of this.
196
197       otherwise ...
198           For code points above 255 ...
199               "\s" matches exactly the code points above 255 shown with an
200               "s" column in the table below.
201
202           For code points below 256 ...
203               if locale rules are in effect ...
204                   "\s" matches whatever the locale considers to be
205                   whitespace.
206
207               if, instead, Unicode rules are in effect ...
208                   "\s" matches exactly the characters shown with an "s"
209                   column in the table below.
210
211               otherwise ...
212                   "\s" matches [\t\n\f\r ] and, starting in Perl v5.18, the
213                   vertical tab, "\cK".  (See note "[1]" below for a
214                   discussion of this.)  Note that this list doesn't include
215                   the non-breaking space.
216
217       Which rules apply are determined as described in "Which character set
218       modifier is in effect?" in perlre.
219
220       Any character not matched by "\s" is matched by "\S".
221
222       "\h" matches any character considered horizontal whitespace; this
223       includes the platform's space and tab characters and several others
224       listed in the table below.  "\H" matches any character not considered
225       horizontal whitespace.  They use the platform's native character set,
226       and do not consider any locale that may otherwise be in use.
227
228       "\v" matches any character considered vertical whitespace; this
229       includes the platform's carriage return and line feed characters
230       (newline) plus several other characters, all listed in the table below.
231       "\V" matches any character not considered vertical whitespace.  They
232       use the platform's native character set, and do not consider any locale
233       that may otherwise be in use.
234
235       "\R" matches anything that can be considered a newline under Unicode
236       rules. It can match a multi-character sequence. It cannot be used
237       inside a bracketed character class; use "\v" instead (vertical
238       whitespace).  It uses the platform's native character set, and does not
239       consider any locale that may otherwise be in use.  Details are
240       discussed in perlrebackslash.
241
242       Note that unlike "\s" (and "\d" and "\w"), "\h" and "\v" always match
243       the same characters, without regard to other factors, such as the
244       active locale or whether the source string is in UTF-8 format.
245
246       One might think that "\s" is equivalent to "[\h\v]". This is indeed
247       true starting in Perl v5.18, but prior to that, the sole difference was
248       that the vertical tab ("\cK") was not matched by "\s".
249
250       The following table is a complete listing of characters matched by
251       "\s", "\h" and "\v" as of Unicode 6.3.
252
253       The first column gives the Unicode code point of the character (in hex
254       format), the second column gives the (Unicode) name. The third column
255       indicates by which class(es) the character is matched (assuming no
256       locale is in effect that changes the "\s" matching).
257
258        0x0009        CHARACTER TABULATION   h s
259        0x000a              LINE FEED (LF)    vs
260        0x000b             LINE TABULATION    vs  [1]
261        0x000c              FORM FEED (FF)    vs
262        0x000d        CARRIAGE RETURN (CR)    vs
263        0x0020                       SPACE   h s
264        0x0085             NEXT LINE (NEL)    vs  [2]
265        0x00a0              NO-BREAK SPACE   h s  [2]
266        0x1680            OGHAM SPACE MARK   h s
267        0x2000                     EN QUAD   h s
268        0x2001                     EM QUAD   h s
269        0x2002                    EN SPACE   h s
270        0x2003                    EM SPACE   h s
271        0x2004          THREE-PER-EM SPACE   h s
272        0x2005           FOUR-PER-EM SPACE   h s
273        0x2006            SIX-PER-EM SPACE   h s
274        0x2007                FIGURE SPACE   h s
275        0x2008           PUNCTUATION SPACE   h s
276        0x2009                  THIN SPACE   h s
277        0x200a                  HAIR SPACE   h s
278        0x2028              LINE SEPARATOR    vs
279        0x2029         PARAGRAPH SEPARATOR    vs
280        0x202f       NARROW NO-BREAK SPACE   h s
281        0x205f   MEDIUM MATHEMATICAL SPACE   h s
282        0x3000           IDEOGRAPHIC SPACE   h s
283
284       [1] Prior to Perl v5.18, "\s" did not match the vertical tab.
285           "[^\S\cK]" (obscurely) matches what "\s" traditionally did.
286
287       [2] NEXT LINE and NO-BREAK SPACE may or may not match "\s" depending on
288           the rules in effect.  See the beginning of this section.
289
290       Unicode Properties
291
292       "\pP" and "\p{Prop}" are character classes to match characters that fit
293       given Unicode properties.  One letter property names can be used in the
294       "\pP" form, with the property name following the "\p", otherwise,
295       braces are required.  When using braces, there is a single form, which
296       is just the property name enclosed in the braces, and a compound form
297       which looks like "\p{name=value}", which means to match if the property
298       "name" for the character has that particular "value".  For instance, a
299       match for a number can be written as "/\pN/" or as "/\p{Number}/", or
300       as "/\p{Number=True}/".  Lowercase letters are matched by the property
301       Lowercase_Letter which has the short form Ll. They need the braces, so
302       are written as "/\p{Ll}/" or "/\p{Lowercase_Letter}/", or
303       "/\p{General_Category=Lowercase_Letter}/" (the underscores are
304       optional).  "/\pLl/" is valid, but means something different.  It
305       matches a two character string: a letter (Unicode property "\pL"),
306       followed by a lowercase "l".
307
308       What a Unicode property matches is never subject to locale rules, and
309       if locale rules are not otherwise in effect, the use of a Unicode
310       property will force the regular expression into using Unicode rules, if
311       it isn't already.
312
313       Note that almost all properties are immune to case-insensitive
314       matching.  That is, adding a "/i" regular expression modifier does not
315       change what they match.  There are two sets that are affected.  The
316       first set is "Uppercase_Letter", "Lowercase_Letter", and
317       "Titlecase_Letter", all of which match "Cased_Letter" under "/i"
318       matching.  The second set is "Uppercase", "Lowercase", and "Titlecase",
319       all of which match "Cased" under "/i" matching.  (The difference
320       between these sets is that some things, such as Roman numerals, come in
321       both upper and lower case, so they are "Cased", but aren't considered
322       to be letters, so they aren't "Cased_Letter"s. They're actually
323       "Letter_Number"s.)  This set also includes its subsets "PosixUpper" and
324       "PosixLower", both of which under "/i" match "PosixAlpha".
325
326       For more details on Unicode properties, see "Unicode Character
327       Properties" in perlunicode; for a complete list of possible properties,
328       see "Properties accessible through \p{} and \P{}" in perluniprops,
329       which notes all forms that have "/i" differences.  It is also possible
330       to define your own properties. This is discussed in "User-Defined
331       Character Properties" in perlunicode.
332
333       Unicode properties are defined (surprise!) only on Unicode code points.
334       Starting in v5.20, when matching against "\p" and "\P", Perl treats
335       non-Unicode code points (those above the legal Unicode maximum of
336       0x10FFFF) as if they were typical unassigned Unicode code points.
337
338       Prior to v5.20, Perl raised a warning and made all matches fail on non-
339       Unicode code points.  This could be somewhat surprising:
340
341        chr(0x110000) =~ \p{ASCII_Hex_Digit=True}     # Fails on Perls < v5.20.
342        chr(0x110000) =~ \p{ASCII_Hex_Digit=False}    # Also fails on Perls
343                                                      # < v5.20
344
345       Even though these two matches might be thought of as complements, until
346       v5.20 they were so only on Unicode code points.
347
348       Starting in perl v5.30, wildcards are allowed in Unicode property
349       values.  See "Wildcards in Property Values" in perlunicode.
350
351       Examples
352
353        "a"  =~  /\w/      # Match, "a" is a 'word' character.
354        "7"  =~  /\w/      # Match, "7" is a 'word' character as well.
355        "a"  =~  /\d/      # No match, "a" isn't a digit.
356        "7"  =~  /\d/      # Match, "7" is a digit.
357        " "  =~  /\s/      # Match, a space is whitespace.
358        "a"  =~  /\D/      # Match, "a" is a non-digit.
359        "7"  =~  /\D/      # No match, "7" is not a non-digit.
360        " "  =~  /\S/      # No match, a space is not non-whitespace.
361
362        " "  =~  /\h/      # Match, space is horizontal whitespace.
363        " "  =~  /\v/      # No match, space is not vertical whitespace.
364        "\r" =~  /\v/      # Match, a return is vertical whitespace.
365
366        "a"  =~  /\pL/     # Match, "a" is a letter.
367        "a"  =~  /\p{Lu}/  # No match, /\p{Lu}/ matches upper case letters.
368
369        "\x{0e0b}" =~ /\p{Thai}/  # Match, \x{0e0b} is the character
370                                  # 'THAI CHARACTER SO SO', and that's in
371                                  # Thai Unicode class.
372        "a"  =~  /\P{Lao}/ # Match, as "a" is not a Laotian character.
373
374       It is worth emphasizing that "\d", "\w", etc, match single characters,
375       not complete numbers or words. To match a number (that consists of
376       digits), use "\d+"; to match a word, use "\w+".  But be aware of the
377       security considerations in doing so, as mentioned above.
378
379   Bracketed Character Classes
380       The third form of character class you can use in Perl regular
381       expressions is the bracketed character class.  In its simplest form, it
382       lists the characters that may be matched, surrounded by square
383       brackets, like this: "[aeiou]".  This matches one of "a", "e", "i", "o"
384       or "u".  Like the other character classes, exactly one character is
385       matched.* To match a longer string consisting of characters mentioned
386       in the character class, follow the character class with a quantifier.
387       For instance, "[aeiou]+" matches one or more lowercase English vowels.
388
389       Repeating a character in a character class has no effect; it's
390       considered to be in the set only once.
391
392       Examples:
393
394        "e"  =~  /[aeiou]/        # Match, as "e" is listed in the class.
395        "p"  =~  /[aeiou]/        # No match, "p" is not listed in the class.
396        "ae" =~  /^[aeiou]$/      # No match, a character class only matches
397                                  # a single character.
398        "ae" =~  /^[aeiou]+$/     # Match, due to the quantifier.
399
400        -------
401
402       * There are two exceptions to a bracketed character class matching a
403       single character only.  Each requires special handling by Perl to make
404       things work:
405
406       ·   When the class is to match caselessly under "/i" matching rules,
407           and a character that is explicitly mentioned inside the class
408           matches a multiple-character sequence caselessly under Unicode
409           rules, the class will also match that sequence.  For example,
410           Unicode says that the letter "LATIN SMALL LETTER SHARP S" should
411           match the sequence "ss" under "/i" rules.  Thus,
412
413            'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i             # Matches
414            'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i    # Matches
415
416           For this to happen, the class must not be inverted (see "Negation")
417           and the character must be explicitly specified, and not be part of
418           a multi-character range (not even as one of its endpoints).
419           ("Character Ranges" will be explained shortly.) Therefore,
420
421            'ss' =~ /\A[\0-\x{ff}]\z/ui       # Doesn't match
422            'ss' =~ /\A[\0-\N{LATIN SMALL LETTER SHARP S}]\z/ui   # No match
423            'ss' =~ /\A[\xDF-\xDF]\z/ui   # Matches on ASCII platforms, since
424                                          # \xDF is LATIN SMALL LETTER SHARP S,
425                                          # and the range is just a single
426                                          # element
427
428           Note that it isn't a good idea to specify these types of ranges
429           anyway.
430
431       ·   Some names known to "\N{...}" refer to a sequence of multiple
432           characters, instead of the usual single character.  When one of
433           these is included in the class, the entire sequence is matched.
434           For example,
435
436             "\N{TAMIL LETTER KA}\N{TAMIL VOWEL SIGN AU}"
437                                         =~ / ^ [\N{TAMIL SYLLABLE KAU}]  $ /x;
438
439           matches, because "\N{TAMIL SYLLABLE KAU}" is a named sequence
440           consisting of the two characters matched against.  Like the other
441           instance where a bracketed class can match multiple characters, and
442           for similar reasons, the class must not be inverted, and the named
443           sequence may not appear in a range, even one where it is both
444           endpoints.  If these happen, it is a fatal error if the character
445           class is within the scope of "use re 'strict", or within an
446           extended "(?[...])" class; otherwise only the first code point is
447           used (with a "regexp"-type warning raised).
448
449       Special Characters Inside a Bracketed Character Class
450
451       Most characters that are meta characters in regular expressions (that
452       is, characters that carry a special meaning like ".", "*", or "(") lose
453       their special meaning and can be used inside a character class without
454       the need to escape them. For instance, "[()]" matches either an opening
455       parenthesis, or a closing parenthesis, and the parens inside the
456       character class don't group or capture.  Be aware that, unless the
457       pattern is evaluated in single-quotish context, variable interpolation
458       will take place before the bracketed class is parsed:
459
460        $, = "\t| ";
461        $a =~ m'[$,]';        # single-quotish: matches '$' or ','
462        $a =~ q{[$,]}'        # same
463        $a =~ m/[$,]/;        # double-quotish: matches "\t", "|", or " "
464
465       Characters that may carry a special meaning inside a character class
466       are: "\", "^", "-", "[" and "]", and are discussed below. They can be
467       escaped with a backslash, although this is sometimes not needed, in
468       which case the backslash may be omitted.
469
470       The sequence "\b" is special inside a bracketed character class. While
471       outside the character class, "\b" is an assertion indicating a point
472       that does not have either two word characters or two non-word
473       characters on either side, inside a bracketed character class, "\b"
474       matches a backspace character.
475
476       The sequences "\a", "\c", "\e", "\f", "\n", "\N{NAME}", "\N{U+hex
477       char}", "\r", "\t", and "\x" are also special and have the same
478       meanings as they do outside a bracketed character class.
479
480       Also, a backslash followed by two or three octal digits is considered
481       an octal number.
482
483       A "[" is not special inside a character class, unless it's the start of
484       a POSIX character class (see "POSIX Character Classes" below). It
485       normally does not need escaping.
486
487       A "]" is normally either the end of a POSIX character class (see "POSIX
488       Character Classes" below), or it signals the end of the bracketed
489       character class.  If you want to include a "]" in the set of
490       characters, you must generally escape it.
491
492       However, if the "]" is the first (or the second if the first character
493       is a caret) character of a bracketed character class, it does not
494       denote the end of the class (as you cannot have an empty class) and is
495       considered part of the set of characters that can be matched without
496       escaping.
497
498       Examples:
499
500        "+"   =~ /[+?*]/     #  Match, "+" in a character class is not special.
501        "\cH" =~ /[\b]/      #  Match, \b inside in a character class
502                             #  is equivalent to a backspace.
503        "]"   =~ /[][]/      #  Match, as the character class contains
504                             #  both [ and ].
505        "[]"  =~ /[[]]/      #  Match, the pattern contains a character class
506                             #  containing just [, and the character class is
507                             #  followed by a ].
508
509       Bracketed Character Classes and the "/xx" pattern modifier
510
511       Normally SPACE and TAB characters have no special meaning inside a
512       bracketed character class; they are just added to the list of
513       characters matched by the class.  But if the "/xx" pattern modifier is
514       in effect, they are generally ignored and can be added to improve
515       readability.  They can't be added in the middle of a single construct:
516
517        / [ \x{10 FFFF} ] /xx  # WRONG!
518
519       The SPACE in the middle of the hex constant is illegal.
520
521       To specify a literal SPACE character, you can escape it with a
522       backslash, like:
523
524        /[ a e i o u \  ]/xx
525
526       This matches the English vowels plus the SPACE character.
527
528       For clarity, you should already have been using "\t" to specify a
529       literal tab, and "\t" is unaffected by "/xx".
530
531       Character Ranges
532
533       It is not uncommon to want to match a range of characters. Luckily,
534       instead of listing all characters in the range, one may use the hyphen
535       ("-").  If inside a bracketed character class you have two characters
536       separated by a hyphen, it's treated as if all characters between the
537       two were in the class. For instance, "[0-9]" matches any ASCII digit,
538       and "[a-m]" matches any lowercase letter from the first half of the
539       ASCII alphabet.
540
541       Note that the two characters on either side of the hyphen are not
542       necessarily both letters or both digits. Any character is possible,
543       although not advisable.  "['-?]" contains a range of characters, but
544       most people will not know which characters that means.  Furthermore,
545       such ranges may lead to portability problems if the code has to run on
546       a platform that uses a different character set, such as EBCDIC.
547
548       If a hyphen in a character class cannot syntactically be part of a
549       range, for instance because it is the first or the last character of
550       the character class, or if it immediately follows a range, the hyphen
551       isn't special, and so is considered a character to be matched
552       literally.  If you want a hyphen in your set of characters to be
553       matched and its position in the class is such that it could be
554       considered part of a range, you must escape that hyphen with a
555       backslash.
556
557       Examples:
558
559        [a-z]       #  Matches a character that is a lower case ASCII letter.
560        [a-fz]      #  Matches any letter between 'a' and 'f' (inclusive) or
561                    #  the letter 'z'.
562        [-z]        #  Matches either a hyphen ('-') or the letter 'z'.
563        [a-f-m]     #  Matches any letter between 'a' and 'f' (inclusive), the
564                    #  hyphen ('-'), or the letter 'm'.
565        ['-?]       #  Matches any of the characters  '()*+,-./0123456789:;<=>?
566                    #  (But not on an EBCDIC platform).
567        [\N{APOSTROPHE}-\N{QUESTION MARK}]
568                    #  Matches any of the characters  '()*+,-./0123456789:;<=>?
569                    #  even on an EBCDIC platform.
570        [\N{U+27}-\N{U+3F}] # Same. (U+27 is "'", and U+3F is "?")
571
572       As the final two examples above show, you can achieve portability to
573       non-ASCII platforms by using the "\N{...}" form for the range
574       endpoints.  These indicate that the specified range is to be
575       interpreted using Unicode values, so "[\N{U+27}-\N{U+3F}]" means to
576       match "\N{U+27}", "\N{U+28}", "\N{U+29}", ..., "\N{U+3D}", "\N{U+3E}",
577       and "\N{U+3F}", whatever the native code point versions for those are.
578       These are called "Unicode" ranges.  If either end is of the "\N{...}"
579       form, the range is considered Unicode.  A "regexp" warning is raised
580       under "use re 'strict'" if the other endpoint is specified non-
581       portably:
582
583        [\N{U+00}-\x09]    # Warning under re 'strict'; \x09 is non-portable
584        [\N{U+00}-\t]      # No warning;
585
586       Both of the above match the characters "\N{U+00}" "\N{U+01}", ...
587       "\N{U+08}", "\N{U+09}", but the "\x09" looks like it could be a mistake
588       so the warning is raised (under "re 'strict'") for it.
589
590       Perl also guarantees that the ranges "A-Z", "a-z", "0-9", and any
591       subranges of these match what an English-only speaker would expect them
592       to match on any platform.  That is, "[A-Z]" matches the 26 ASCII
593       uppercase letters; "[a-z]" matches the 26 lowercase letters; and
594       "[0-9]" matches the 10 digits.  Subranges, like "[h-k]", match
595       correspondingly, in this case just the four letters "h", "i", "j", and
596       "k".  This is the natural behavior on ASCII platforms where the code
597       points (ordinal values) for "h" through "k" are consecutive integers
598       (0x68 through 0x6B).  But special handling to achieve this may be
599       needed on platforms with a non-ASCII native character set.  For
600       example, on EBCDIC platforms, the code point for "h" is 0x88, "i" is
601       0x89, "j" is 0x91, and "k" is 0x92.   Perl specially treats "[h-k]" to
602       exclude the seven code points in the gap: 0x8A through 0x90.  This
603       special handling is only invoked when the range is a subrange of one of
604       the ASCII uppercase, lowercase, and digit ranges, AND each end of the
605       range is expressed either as a literal, like "A", or as a named
606       character ("\N{...}", including the "\N{U+..." form).
607
608       EBCDIC Examples:
609
610        [i-j]               #  Matches either "i" or "j"
611        [i-\N{LATIN SMALL LETTER J}]  # Same
612        [i-\N{U+6A}]        #  Same
613        [\N{U+69}-\N{U+6A}] #  Same
614        [\x{89}-\x{91}]     #  Matches 0x89 ("i"), 0x8A .. 0x90, 0x91 ("j")
615        [i-\x{91}]          #  Same
616        [\x{89}-j]          #  Same
617        [i-J]               #  Matches, 0x89 ("i") .. 0xC1 ("J"); special
618                            #  handling doesn't apply because range is mixed
619                            #  case
620
621       Negation
622
623       It is also possible to instead list the characters you do not want to
624       match. You can do so by using a caret ("^") as the first character in
625       the character class. For instance, "[^a-z]" matches any character that
626       is not a lowercase ASCII letter, which therefore includes more than a
627       million Unicode code points.  The class is said to be "negated" or
628       "inverted".
629
630       This syntax make the caret a special character inside a bracketed
631       character class, but only if it is the first character of the class. So
632       if you want the caret as one of the characters to match, either escape
633       the caret or else don't list it first.
634
635       In inverted bracketed character classes, Perl ignores the Unicode rules
636       that normally say that named sequence, and certain characters should
637       match a sequence of multiple characters use under caseless "/i"
638       matching.  Following those rules could lead to highly confusing
639       situations:
640
641        "ss" =~ /^[^\xDF]+$/ui;   # Matches!
642
643       This should match any sequences of characters that aren't "\xDF" nor
644       what "\xDF" matches under "/i".  "s" isn't "\xDF", but Unicode says
645       that "ss" is what "\xDF" matches under "/i".  So which one "wins"? Do
646       you fail the match because the string has "ss" or accept it because it
647       has an "s" followed by another "s"?  Perl has chosen the latter.  (See
648       note in "Bracketed Character Classes" above.)
649
650       Examples:
651
652        "e"  =~  /[^aeiou]/   #  No match, the 'e' is listed.
653        "x"  =~  /[^aeiou]/   #  Match, as 'x' isn't a lowercase vowel.
654        "^"  =~  /[^^]/       #  No match, matches anything that isn't a caret.
655        "^"  =~  /[x^]/       #  Match, caret is not special here.
656
657       Backslash Sequences
658
659       You can put any backslash sequence character class (with the exception
660       of "\N" and "\R") inside a bracketed character class, and it will act
661       just as if you had put all characters matched by the backslash sequence
662       inside the character class. For instance, "[a-f\d]" matches any decimal
663       digit, or any of the lowercase letters between 'a' and 'f' inclusive.
664
665       "\N" within a bracketed character class must be of the forms "\N{name}"
666       or "\N{U+hex char}", and NOT be the form that matches non-newlines, for
667       the same reason that a dot "." inside a bracketed character class loses
668       its special meaning: it matches nearly anything, which generally isn't
669       what you want to happen.
670
671       Examples:
672
673        /[\p{Thai}\d]/     # Matches a character that is either a Thai
674                           # character, or a digit.
675        /[^\p{Arabic}()]/  # Matches a character that is neither an Arabic
676                           # character, nor a parenthesis.
677
678       Backslash sequence character classes cannot form one of the endpoints
679       of a range.  Thus, you can't say:
680
681        /[\p{Thai}-\d]/     # Wrong!
682
683       POSIX Character Classes
684
685       POSIX character classes have the form "[:class:]", where class is the
686       name, and the "[:" and ":]" delimiters. POSIX character classes only
687       appear inside bracketed character classes, and are a convenient and
688       descriptive way of listing a group of characters.
689
690       Be careful about the syntax,
691
692        # Correct:
693        $string =~ /[[:alpha:]]/
694
695        # Incorrect (will warn):
696        $string =~ /[:alpha:]/
697
698       The latter pattern would be a character class consisting of a colon,
699       and the letters "a", "l", "p" and "h".
700
701       POSIX character classes can be part of a larger bracketed character
702       class.  For example,
703
704        [01[:alpha:]%]
705
706       is valid and matches '0', '1', any alphabetic character, and the
707       percent sign.
708
709       Perl recognizes the following POSIX character classes:
710
711        alpha  Any alphabetical character (e.g., [A-Za-z]).
712        alnum  Any alphanumeric character (e.g., [A-Za-z0-9]).
713        ascii  Any character in the ASCII character set.
714        blank  A GNU extension, equal to a space or a horizontal tab ("\t").
715        cntrl  Any control character.  See Note [2] below.
716        digit  Any decimal digit (e.g., [0-9]), equivalent to "\d".
717        graph  Any printable character, excluding a space.  See Note [3] below.
718        lower  Any lowercase character (e.g., [a-z]).
719        print  Any printable character, including a space.  See Note [4] below.
720        punct  Any graphical character excluding "word" characters.  Note [5].
721        space  Any whitespace character. "\s" including the vertical tab
722               ("\cK").
723        upper  Any uppercase character (e.g., [A-Z]).
724        word   A Perl extension (e.g., [A-Za-z0-9_]), equivalent to "\w".
725        xdigit Any hexadecimal digit (e.g., [0-9a-fA-F]).  Note [7].
726
727       Like the Unicode properties, most of the POSIX properties match the
728       same regardless of whether case-insensitive ("/i") matching is in
729       effect or not.  The two exceptions are "[:upper:]" and "[:lower:]".
730       Under "/i", they each match the union of "[:upper:]" and "[:lower:]".
731
732       Most POSIX character classes have two Unicode-style "\p" property
733       counterparts.  (They are not official Unicode properties, but Perl
734       extensions derived from official Unicode properties.)  The table below
735       shows the relation between POSIX character classes and these
736       counterparts.
737
738       One counterpart, in the column labelled "ASCII-range Unicode" in the
739       table, matches only characters in the ASCII character set.
740
741       The other counterpart, in the column labelled "Full-range Unicode",
742       matches any appropriate characters in the full Unicode character set.
743       For example, "\p{Alpha}" matches not just the ASCII alphabetic
744       characters, but any character in the entire Unicode character set
745       considered alphabetic.  An entry in the column labelled "backslash
746       sequence" is a (short) equivalent.
747
748        [[:...:]]      ASCII-range          Full-range  backslash  Note
749                        Unicode              Unicode     sequence
750        -----------------------------------------------------
751          alpha      \p{PosixAlpha}       \p{XPosixAlpha}
752          alnum      \p{PosixAlnum}       \p{XPosixAlnum}
753          ascii      \p{ASCII}
754          blank      \p{PosixBlank}       \p{XPosixBlank}  \h      [1]
755                                          or \p{HorizSpace}        [1]
756          cntrl      \p{PosixCntrl}       \p{XPosixCntrl}          [2]
757          digit      \p{PosixDigit}       \p{XPosixDigit}  \d
758          graph      \p{PosixGraph}       \p{XPosixGraph}          [3]
759          lower      \p{PosixLower}       \p{XPosixLower}
760          print      \p{PosixPrint}       \p{XPosixPrint}          [4]
761          punct      \p{PosixPunct}       \p{XPosixPunct}          [5]
762                     \p{PerlSpace}        \p{XPerlSpace}   \s      [6]
763          space      \p{PosixSpace}       \p{XPosixSpace}          [6]
764          upper      \p{PosixUpper}       \p{XPosixUpper}
765          word       \p{PosixWord}        \p{XPosixWord}   \w
766          xdigit     \p{PosixXDigit}      \p{XPosixXDigit}         [7]
767
768       [1] "\p{Blank}" and "\p{HorizSpace}" are synonyms.
769
770       [2] Control characters don't produce output as such, but instead
771           usually control the terminal somehow: for example, newline and
772           backspace are control characters.  On ASCII platforms, in the ASCII
773           range, characters whose code points are between 0 and 31 inclusive,
774           plus 127 ("DEL") are control characters; on EBCDIC platforms, their
775           counterparts are control characters.
776
777       [3] Any character that is graphical, that is, visible. This class
778           consists of all alphanumeric characters and all punctuation
779           characters.
780
781       [4] All printable characters, which is the set of all graphical
782           characters plus those whitespace characters which are not also
783           controls.
784
785       [5] "\p{PosixPunct}" and "[[:punct:]]" in the ASCII range match all
786           non-controls, non-alphanumeric, non-space characters:
787           "[-!"#$%&'()*+,./:;<=>?@[\\\]^_`{|}~]" (although if a locale is in
788           effect, it could alter the behavior of "[[:punct:]]").
789
790           The similarly named property, "\p{Punct}", matches a somewhat
791           different set in the ASCII range, namely
792           "[-!"#%&'()*,./:;?@[\\\]_{}]".  That is, it is missing the nine
793           characters "[$+<=>^`|~]".  This is because Unicode splits what
794           POSIX considers to be punctuation into two categories, Punctuation
795           and Symbols.
796
797           "\p{XPosixPunct}" and (under Unicode rules) "[[:punct:]]", match
798           what "\p{PosixPunct}" matches in the ASCII range, plus what
799           "\p{Punct}" matches.  This is different than strictly matching
800           according to "\p{Punct}".  Another way to say it is that if Unicode
801           rules are in effect, "[[:punct:]]" matches all characters that
802           Unicode considers punctuation, plus all ASCII-range characters that
803           Unicode considers symbols.
804
805       [6] "\p{XPerlSpace}" and "\p{Space}" match identically starting with
806           Perl v5.18.  In earlier versions, these differ only in that in non-
807           locale matching, "\p{XPerlSpace}" did not match the vertical tab,
808           "\cK".  Same for the two ASCII-only range forms.
809
810       [7] Unlike "[[:digit:]]" which matches digits in many writing systems,
811           such as Thai and Devanagari, there are currently only two sets of
812           hexadecimal digits, and it is unlikely that more will be added.
813           This is because you not only need the ten digits, but also the six
814           "[A-F]" (and "[a-f]") to correspond.  That means only the Latin
815           script is suitable for these, and Unicode has only two sets of
816           these, the familiar ASCII set, and the fullwidth forms starting at
817           U+FF10 (FULLWIDTH DIGIT ZERO).
818
819       There are various other synonyms that can be used besides the names
820       listed in the table.  For example, "\p{XPosixAlpha}" can be written as
821       "\p{Alpha}".  All are listed in "Properties accessible through \p{} and
822       \P{}" in perluniprops.
823
824       Both the "\p" counterparts always assume Unicode rules are in effect.
825       On ASCII platforms, this means they assume that the code points from
826       128 to 255 are Latin-1, and that means that using them under locale
827       rules is unwise unless the locale is guaranteed to be Latin-1 or UTF-8.
828       In contrast, the POSIX character classes are useful under locale rules.
829       They are affected by the actual rules in effect, as follows:
830
831       If the "/a" modifier, is in effect ...
832           Each of the POSIX classes matches exactly the same as their ASCII-
833           range counterparts.
834
835       otherwise ...
836           For code points above 255 ...
837               The POSIX class matches the same as its Full-range counterpart.
838
839           For code points below 256 ...
840               if locale rules are in effect ...
841                   The POSIX class matches according to the locale, except:
842
843                   "word"
844                       also includes the platform's native underscore
845                       character, no matter what the locale is.
846
847                   "ascii"
848                       on platforms that don't have the POSIX "ascii"
849                       extension, this matches just the platform's native
850                       ASCII-range characters.
851
852                   "blank"
853                       on platforms that don't have the POSIX "blank"
854                       extension, this matches just the platform's native tab
855                       and space characters.
856
857               if, instead, Unicode rules are in effect ...
858                   The POSIX class matches the same as the Full-range
859                   counterpart.
860
861               otherwise ...
862                   The POSIX class matches the same as the ASCII range
863                   counterpart.
864
865       Which rules apply are determined as described in "Which character set
866       modifier is in effect?" in perlre.
867
868       Negation of POSIX character classes
869
870       A Perl extension to the POSIX character class is the ability to negate
871       it. This is done by prefixing the class name with a caret ("^").  Some
872       examples:
873
874            POSIX         ASCII-range     Full-range  backslash
875                           Unicode         Unicode    sequence
876        -----------------------------------------------------
877        [[:^digit:]]   \P{PosixDigit}  \P{XPosixDigit}   \D
878        [[:^space:]]   \P{PosixSpace}  \P{XPosixSpace}
879                       \P{PerlSpace}   \P{XPerlSpace}    \S
880        [[:^word:]]    \P{PerlWord}    \P{XPosixWord}    \W
881
882       The backslash sequence can mean either ASCII- or Full-range Unicode,
883       depending on various factors as described in "Which character set
884       modifier is in effect?" in perlre.
885
886       [= =] and [. .]
887
888       Perl recognizes the POSIX character classes "[=class=]" and
889       "[.class.]", but does not (yet?) support them.  Any attempt to use
890       either construct raises an exception.
891
892       Examples
893
894        /[[:digit:]]/            # Matches a character that is a digit.
895        /[01[:lower:]]/          # Matches a character that is either a
896                                 # lowercase letter, or '0' or '1'.
897        /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
898                                 # except the letters 'a' to 'f' and 'A' to
899                                 # 'F'.  This is because the main character
900                                 # class is composed of two POSIX character
901                                 # classes that are ORed together, one that
902                                 # matches any digit, and the other that
903                                 # matches anything that isn't a hex digit.
904                                 # The OR adds the digits, leaving only the
905                                 # letters 'a' to 'f' and 'A' to 'F' excluded.
906
907       Extended Bracketed Character Classes
908
909       This is a fancy bracketed character class that can be used for more
910       readable and less error-prone classes, and to perform set operations,
911       such as intersection. An example is
912
913        /(?[ \p{Thai} & \p{Digit} ])/
914
915       This will match all the digit characters that are in the Thai script.
916
917       This is an experimental feature available starting in 5.18, and is
918       subject to change as we gain field experience with it.  Any attempt to
919       use it will raise a warning, unless disabled via
920
921        no warnings "experimental::regex_sets";
922
923       Comments on this feature are welcome; send email to
924       "perl5-porters@perl.org".
925
926       The rules used by "use re 'strict" apply to this construct.
927
928       We can extend the example above:
929
930        /(?[ ( \p{Thai} + \p{Lao} ) & \p{Digit} ])/
931
932       This matches digits that are in either the Thai or Laotian scripts.
933
934       Notice the white space in these examples.  This construct always has
935       the "/xx" modifier turned on within it.
936
937       The available binary operators are:
938
939        &    intersection
940        +    union
941        |    another name for '+', hence means union
942        -    subtraction (the result matches the set consisting of those
943             code points matched by the first operand, excluding any that
944             are also matched by the second operand)
945        ^    symmetric difference (the union minus the intersection).  This
946             is like an exclusive or, in that the result is the set of code
947             points that are matched by either, but not both, of the
948             operands.
949
950       There is one unary operator:
951
952        !    complement
953
954       All the binary operators left associate; "&" is higher precedence than
955       the others, which all have equal precedence.  The unary operator right
956       associates, and has highest precedence.  Thus this follows the normal
957       Perl precedence rules for logical operators.  Use parentheses to
958       override the default precedence and associativity.
959
960       The main restriction is that everything is a metacharacter.  Thus, you
961       cannot refer to single characters by doing something like this:
962
963        /(?[ a + b ])/ # Syntax error!
964
965       The easiest way to specify an individual typable character is to
966       enclose it in brackets:
967
968        /(?[ [a] + [b] ])/
969
970       (This is the same thing as "[ab]".)  You could also have said the
971       equivalent:
972
973        /(?[[ a b ]])/
974
975       (You can, of course, specify single characters by using, "\x{...}",
976       "\N{...}", etc.)
977
978       This last example shows the use of this construct to specify an
979       ordinary bracketed character class without additional set operations.
980       Note the white space within it.  This is allowed because "/xx" is
981       automatically turned on within this construct.
982
983       All the other escapes accepted by normal bracketed character classes
984       are accepted here as well.
985
986       Because this construct compiles under "use re 'strict",  unrecognized
987       escapes that generate warnings in normal classes are fatal errors here,
988       as well as all other warnings from these class elements, as well as
989       some practices that don't currently warn outside "re 'strict'".  For
990       example you cannot say
991
992        /(?[ [ \xF ] ])/     # Syntax error!
993
994       You have to have two hex digits after a braceless "\x" (use a leading
995       zero to make two).  These restrictions are to lower the incidence of
996       typos causing the class to not match what you thought it would.
997
998       If a regular bracketed character class contains a "\p{}" or "\P{}" and
999       is matched against a non-Unicode code point, a warning may be raised,
1000       as the result is not Unicode-defined.  No such warning will come when
1001       using this extended form.
1002
1003       The final difference between regular bracketed character classes and
1004       these, is that it is not possible to get these to match a multi-
1005       character fold.  Thus,
1006
1007        /(?[ [\xDF] ])/iu
1008
1009       does not match the string "ss".
1010
1011       You don't have to enclose POSIX class names inside double brackets,
1012       hence both of the following work:
1013
1014        /(?[ [:word:] - [:lower:] ])/
1015        /(?[ [[:word:]] - [[:lower:]] ])/
1016
1017       Any contained POSIX character classes, including things like "\w" and
1018       "\D" respect the "/a" (and "/aa") modifiers.
1019
1020       Note that "(?[ ])" is a regex-compile-time construct.  Any attempt to
1021       use something which isn't knowable at the time the containing regular
1022       expression is compiled is a fatal error.  In practice, this means just
1023       three limitations:
1024
1025       1.  When compiled within the scope of "use locale" (or the "/l" regex
1026           modifier), this construct assumes that the execution-time locale
1027           will be a UTF-8 one, and the generated pattern always uses Unicode
1028           rules.  What gets matched or not thus isn't dependent on the actual
1029           runtime locale, so tainting is not enabled.  But a "locale"
1030           category warning is raised if the runtime locale turns out to not
1031           be UTF-8.
1032
1033       2.  Any user-defined property used must be already defined by the time
1034           the regular expression is compiled (but note that this construct
1035           can be used instead of such properties).
1036
1037       3.  A regular expression that otherwise would compile using "/d" rules,
1038           and which uses this construct will instead use "/u".  Thus this
1039           construct tells Perl that you don't want "/d" rules for the entire
1040           regular expression containing it.
1041
1042       Note that skipping white space applies only to the interior of this
1043       construct.  There must not be any space between any of the characters
1044       that form the initial "(?[".  Nor may there be space between the
1045       closing "])" characters.
1046
1047       Just as in all regular expressions, the pattern can be built up by
1048       including variables that are interpolated at regex compilation time.
1049       But its best to compile each sub-component.
1050
1051        my $thai_or_lao = qr/(?[ \p{Thai} + \p{Lao} ])/;
1052        my $lower = qr/(?[ \p{Lower} + \p{Digit} ])/;
1053
1054       When these are embedded in another pattern, what they match does not
1055       change, regardless of parenthesization or what modifiers are in effect
1056       in that outer pattern.  If you fail to compile the subcomponents, you
1057       can get some nasty surprises.  For example:
1058
1059        my $thai_or_lao = '\p{Thai} + \p{Lao}';
1060        ...
1061        qr/(?[ \p{Digit} & $thai_or_lao ])/;
1062
1063       compiles to
1064
1065        qr/(?[ \p{Digit} & \p{Thai} + \p{Lao} ])/;
1066
1067       But this does not have the effect that someone reading the source code
1068       would likely expect, as the intersection applies just to "\p{Thai}",
1069       excluding the Laotian.  Its best to compile the subcomponents, but you
1070       could also parenthesize the component pieces:
1071
1072        my $thai_or_lao = '( \p{Thai} + \p{Lao} )';
1073
1074       But any modifiers will still apply to all the components:
1075
1076        my $lower = '\p{Lower} + \p{Digit}';
1077        qr/(?[ \p{Greek} & $lower ])/i;
1078
1079       matches upper case things.  So just, compile the subcomponents, as
1080       illustrated above.
1081
1082       Due to the way that Perl parses things, your parentheses and brackets
1083       may need to be balanced, even including comments.  If you run into any
1084       examples, please send them to "perlbug@perl.org", so that we can have a
1085       concrete example for this man page.
1086
1087       We may change it so that things that remain legal uses in normal
1088       bracketed character classes might become illegal within this
1089       experimental construct.  One proposal, for example, is to forbid
1090       adjacent uses of the same character, as in "(?[ [aa] ])".  The
1091       motivation for such a change is that this usage is likely a typo, as
1092       the second "a" adds nothing.
1093
1094
1095
1096perl v5.30.1                      2019-11-29                PERLRECHARCLASS(1)
Impressum