Debian Codegraph @

upstream/mageia-cauldron/man1/perlunicode.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLUNICODE 1"
61 .TH PERLUNICODE 1 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlunicode \- Unicode support in Perl
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 If you haven\*(Aqt already, before reading this document, you should become
71 familiar with both perlunitut and perluniintro.
72 .PP
73 Unicode aims to \fBUNI\fR\-fy the en\-\fBCODE\fR\-ings of all the world\*(Aqs
74 character sets into a single Standard. For quite a few of the various
75 coding standards that existed when Unicode was first created, converting
76 from each to Unicode essentially meant adding a constant to each code
77 point in the original standard, and converting back meant just
78 subtracting that same constant. For ASCII and ISO\-8859\-1, the constant
79 is 0. For ISO\-8859\-5, (Cyrillic) the constant is 864; for Hebrew
80 (ISO\-8859\-8), it\*(Aqs 1488; Thai (ISO\-8859\-11), 3424; and so forth. This
81 made it easy to do the conversions, and facilitated the adoption of
82 Unicode.
83 .PP
84 And it worked; nowadays, those legacy standards are rarely used. Most
85 everyone uses Unicode.
86 .PP
87 Unicode is a comprehensive standard. It specifies many things outside
88 the scope of Perl, such as how to display sequences of characters. For
89 a full discussion of all aspects of Unicode, see
90 <https://www.unicode.org>.
91 .SS "Important Caveats"
92 .IX Subsection "Important Caveats"
93 Even though some of this section may not be understandable to you on
94 first reading, we think it\*(Aqs important enough to highlight some of the
95 gotchas before delving further, so here goes:
96 .PP
97 Unicode support is an extensive requirement. While Perl does not
98 implement the Unicode standard or the accompanying technical reports
99 from cover to cover, Perl does support many Unicode features.
100 .PP
101 Also, the use of Unicode may present security issues that aren\*(Aqt
102 obvious, see "Security Implications of Unicode" below.
103 .ie n .IP "Safest if you ""use feature \*(Aqunicode_strings\*(Aq""" 4
104 .el .IP "Safest if you \f(CWuse feature \*(Aqunicode_strings\*(Aq\fR" 4
105 .IX Item "Safest if you use feature 'unicode_strings'"
106 In order to preserve backward compatibility, Perl does not turn
107 on full internal Unicode support unless the pragma
108 \&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
109 is specified. (This is automatically
110 selected if you \f(CW\*(C`use\ v5.12\*(C'\fR or higher.) Failure to do this can
111 trigger unexpected surprises. See "The "Unicode Bug"" below.
112 .Sp
113 This pragma doesn\*(Aqt affect I/O. Nor does it change the internal
114 representation of strings, only their interpretation. There are still
115 several places where Unicode isn\*(Aqt fully supported, such as in
116 filenames.
117 .IP "Input and Output Layers" 4
118 .IX Item "Input and Output Layers"
119 Use the \f(CW:encoding(...)\fR layer to read from and write to
120 filehandles using the specified encoding. (See open.)
121 .IP "You must convert your non\-ASCII, non\-UTF\-8 Perl scripts to be UTF\-8." 4
122 .IX Item "You must convert your non-ASCII, non-UTF-8 Perl scripts to be UTF-8."
123 The encoding module has been deprecated since perl 5.18 and the
124 perl internals it requires have been removed with perl 5.26.
125 .ie n .IP """use utf8"" still needed to enable UTF\-8 in scripts" 4
126 .el .IP "\f(CWuse utf8\fR still needed to enable UTF\-8 in scripts" 4
127 .IX Item "use utf8 still needed to enable UTF-8 in scripts"
128 If your Perl script is itself encoded in UTF\-8,
129 the \f(CW\*(C`use\ utf8\*(C'\fR pragma must be explicitly included to enable
130 recognition of that (in string or regular expression literals, or in
131 identifier names). \fBThis is the only time when an explicit \fR\f(CB\*(C`use\ utf8\*(C'\fR\fB is needed.\fR (See utf8).
132 .Sp
133 If a Perl script begins with the bytes that form the UTF\-8 encoding of
134 the Unicode BYTE ORDER MARK (\f(CW\*(C`BOM\*(C'\fR, see "Unicode Encodings"), those
135 bytes are completely ignored.
136 .IP "UTF\-16 scripts autodetected" 4
137 .IX Item "UTF-16 scripts autodetected"
138 If a Perl script begins with the Unicode \f(CW\*(C`BOM\*(C'\fR (UTF\-16LE,
139 UTF16\-BE), or if the script looks like non\-\f(CW\*(C`BOM\*(C'\fR\-marked
140 UTF\-16 of either endianness, Perl will correctly read in the script as
141 the appropriate Unicode encoding.
142 .SS "Byte and Character Semantics"
143 .IX Subsection "Byte and Character Semantics"
144 Before Unicode, most encodings used 8 bits (a single byte) to encode
145 each character. Thus a character was a byte, and a byte was a
146 character, and there could be only 256 or fewer possible characters.
147 "Byte Semantics" in the title of this section refers to
148 this behavior. There was no need to distinguish between "Byte" and
149 "Character".
150 .PP
151 Then along comes Unicode which has room for over a million characters
152 (and Perl allows for even more). This means that a character may
153 require more than a single byte to represent it, and so the two terms
154 are no longer equivalent. What matter are the characters as whole
155 entities, and not usually the bytes that comprise them. That\*(Aqs what the
156 term "Character Semantics" in the title of this section refers to.
157 .PP
158 Perl had to change internally to decouple "bytes" from "characters".
159 It is important that you too change your ideas, if you haven\*(Aqt already,
160 so that "byte" and "character" no longer mean the same thing in your
161 mind.
162 .PP
163 The basic building block of Perl strings has always been a "character".
164 The changes basically come down to that the implementation no longer
165 thinks that a character is always just a single byte.
166 .PP
167 There are various things to note:
168 .IP \(bu 4
169 String handling functions, for the most part, continue to operate in
170 terms of characters. \f(CWlength()\fR, for example, returns the number of
171 characters in a string, just as before. But that number no longer is
172 necessarily the same as the number of bytes in the string (there may be
173 more bytes than characters). The other such functions include
174 \&\f(CWchop()\fR, \f(CWchomp()\fR, \f(CWsubstr()\fR, \f(CWpos()\fR, \f(CWindex()\fR, \f(CWrindex()\fR,
175 \&\f(CWsort()\fR, \f(CWsprintf()\fR, and \f(CWwrite()\fR.
176 .Sp
177 The exceptions are:
178 .RS 4
179 .IP \(bu 4
180 the bit\-oriented \f(CW\*(C`vec\*(C'\fR
181 .Sp
182 \
183 .IP \(bu 4
184 the byte\-oriented \f(CW\*(C`pack\*(C'\fR/\f(CW\*(C`unpack\*(C'\fR \f(CW"C"\fR format
185 .Sp
186 However, the \f(CW\*(C`W\*(C'\fR specifier does operate on whole characters, as does the
187 \&\f(CW\*(C`U\*(C'\fR specifier.
188 .IP \(bu 4
189 some operators that interact with the platform\*(Aqs operating system
190 .Sp
191 Operators dealing with filenames are examples.
192 .IP \(bu 4
193 when the functions are called from within the scope of the
194 \&\f(CW\*(C`use\ bytes\*(C'\fR pragma
195 .Sp
196 Likely, you should use this only for debugging anyway.
197 .RE
198 .RS 4
199 .RE
200 .IP \(bu 4
201 Strings\-\-including hash keys\-\-and regular expression patterns may
202 contain characters that have ordinal values larger than 255.
203 .Sp
204 If you use a Unicode editor to edit your program, Unicode characters may
205 occur directly within the literal strings in UTF\-8 encoding, or UTF\-16.
206 (The former requires a \f(CW\*(C`use utf8\*(C'\fR, the latter may require a \f(CW\*(C`BOM\*(C'\fR.)
207 .Sp
208 "Creating Unicode" in perluniintro gives other ways to place non\-ASCII
209 characters in your strings.
210 .IP \(bu 4
211 The \f(CWchr()\fR and \f(CWord()\fR functions work on whole characters.
212 .IP \(bu 4
213 Regular expressions match whole characters. For example, \f(CW"."\fR matches
214 a whole character instead of only a single byte.
215 .IP \(bu 4
216 The \f(CW\*(C`tr///\*(C'\fR operator translates whole characters. (Note that the
217 \&\f(CW\*(C`tr///CU\*(C'\fR functionality has been removed. For similar functionality to
218 that, see \f(CW\*(C`pack(\*(AqU0\*(Aq,\ ...)\*(C'\fR and \f(CW\*(C`pack(\*(AqC0\*(Aq,\ ...)\*(C'\fR).
219 .IP \(bu 4
220 \&\f(CW\*(C`scalar reverse()\*(C'\fR reverses by character rather than by byte.
221 .IP \(bu 4
222 The bit string operators, \f(CW\*(C`& | ^ ~\*(C'\fR and (starting in v5.22)
223 \&\f(CW\*(C`&. |. ^. ~.\*(C'\fR can operate on bit strings encoded in UTF\-8, but this
224 can give unexpected results if any of the strings contain code points
225 above 0xFF. Starting in v5.28, it is a fatal error to have such an
226 operand. Otherwise, the operation is performed on a non\-UTF\-8 copy of
227 the operand. If you\*(Aqre not sure about the encoding of a string,
228 downgrade it before using any of these operators; you can use
229 \&\f(CWutf8::utf8_downgrade()\fR.
230 .PP
231 The bottom line is that Perl has always practiced "Character Semantics",
232 but with the advent of Unicode, that is now different than "Byte
233 Semantics".
234 .SS "ASCII Rules versus Unicode Rules"
235 .IX Subsection "ASCII Rules versus Unicode Rules"
236 Before Unicode, when a character was a byte was a character,
237 Perl knew only about the 128 characters defined by ASCII, code points 0
238 through 127 (except for under \f(CW\*(C`use\ locale\*(C'\fR). That
239 left the code
240 points 128 to 255 as unassigned, and available for whatever use a
241 program might want. The only semantics they have is their ordinal
242 numbers, and that they are members of none of the non\-negative character
243 classes. None are considered to match \f(CW\*(C`\ew\*(C'\fR for example, but all match
244 \&\f(CW\*(C`\eW\*(C'\fR.
245 .PP
246 Unicode, of course, assigns each of those code points a particular
247 meaning (along with ones above 255). To preserve backward
248 compatibility, Perl only uses the Unicode meanings when there is some
249 indication that Unicode is what is intended; otherwise the non\-ASCII
250 code points remain treated as if they are unassigned.
251 .PP
252 Here are the ways that Perl knows that a string should be treated as
253 Unicode:
254 .IP \(bu 4
255 Within the scope of \f(CW\*(C`use\ utf8\*(C'\fR
256 .Sp
257 If the whole program is Unicode (signified by using 8\-bit \fBU\fRnicode
258 \&\fBT\fRransformation \fBF\fRormat), then all literal strings within it must be
259 Unicode.
260 .IP \(bu 4
261 Within the scope of
262 \&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
263 .Sp
264 This pragma was created so you can explicitly tell Perl that operations
265 executed within its scope are to use Unicode rules. More operations are
266 affected with newer perls. See "The "Unicode Bug"".
267 .IP \(bu 4
268 Within the scope of \f(CW\*(C`use\ v5.12\*(C'\fR or higher
269 .Sp
270 This implicitly turns on \f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR.
271 .IP \(bu 4
272 Within the scope of
273 \&\f(CW\*(C`use\ locale\ \*(Aqnot_characters\*(Aq\*(C'\fR,
274 or \f(CW\*(C`use\ locale\*(C'\fR and the current
275 locale is a UTF\-8 locale.
276 .Sp
277 The former is defined to imply Unicode handling; and the latter
278 indicates a Unicode locale, hence a Unicode interpretation of all
279 strings within it.
280 .IP \(bu 4
281 When the string contains a Unicode\-only code point
282 .Sp
283 Perl has never accepted code points above 255 without them being
284 Unicode, so their use implies Unicode for the whole string.
285 .IP \(bu 4
286 When the string contains a Unicode named code point \f(CW\*(C`\eN{...}\*(C'\fR
287 .Sp
288 The \f(CW\*(C`\eN{...}\*(C'\fR construct explicitly refers to a Unicode code point,
289 even if it is one that is also in ASCII. Therefore the string
290 containing it must be Unicode.
291 .IP \(bu 4
292 When the string has come from an external source marked as
293 Unicode
294 .Sp
295 The \f(CW\*(C`\-C\*(C'\fR command line option can
296 specify that certain inputs to the program are Unicode, and the values
297 of this can be read by your Perl code, see "${^UNICODE}" in perlvar.
298 .IP \(bu 4
299 When the string has been upgraded to UTF\-8
300 .Sp
301 The function \f(CWutf8::utf8_upgrade()\fR
302 can be explicitly used to permanently (unless a subsequent
303 \&\f(CWutf8::utf8_downgrade()\fR is called) cause a string to be treated as
304 Unicode.
305 .IP \(bu 4
306 There are additional methods for regular expression patterns
307 .Sp
308 A pattern that is compiled with the \f(CW\*(C`/u\*(C'\fR or \f(CW\*(C`/a\*(C'\fR modifiers is
309 treated as Unicode (though there are some restrictions with \f(CW\*(C`/a\*(C'\fR).
310 Under the \f(CW\*(C`/d\*(C'\fR and \f(CW\*(C`/l\*(C'\fR modifiers, there are several other
311 indications for Unicode; see "Character set modifiers" in perlre.
312 .PP
313 Note that all of the above are overridden within the scope of
314 \&\f(CW\*(C`use bytes\*(C'\fR; but you should be using this pragma only for
315 debugging.
316 .PP
317 Note also that some interactions with the platform\*(Aqs operating system
318 never use Unicode rules.
319 .PP
320 When Unicode rules are in effect:
321 .IP \(bu 4
322 Case translation operators use the Unicode case translation tables.
323 .Sp
324 Note that \f(CWuc()\fR, or \f(CW\*(C`\eU\*(C'\fR in interpolated strings, translates to
325 uppercase, while \f(CW\*(C`ucfirst\*(C'\fR, or \f(CW\*(C`\eu\*(C'\fR in interpolated strings,
326 translates to titlecase in languages that make the distinction (which is
327 equivalent to uppercase in languages without the distinction).
328 .Sp
329 There is a CPAN module, \f(CW\*(C`Unicode::Casing\*(C'\fR, which allows you to
330 define your own mappings to be used in \f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR,
331 \&\f(CWucfirst()\fR, and \f(CW\*(C`fc\*(C'\fR (or their double\-quoted string inlined versions
332 such as \f(CW\*(C`\eU\*(C'\fR). (Prior to Perl 5.16, this functionality was partially
333 provided in the Perl core, but suffered from a number of insurmountable
334 drawbacks, so the CPAN module was written instead.)
335 .IP \(bu 4
336 Character classes in regular expressions match based on the character
337 properties specified in the Unicode properties database.
338 .Sp
339 \&\f(CW\*(C`\ew\*(C'\fR can be used to match a Japanese ideograph, for instance; and
340 \&\f(CW\*(C`[[:digit:]]\*(C'\fR a Bengali number.
341 .IP \(bu 4
342 Named Unicode properties, scripts, and block ranges may be used (like
343 bracketed character classes) by using the \f(CW\*(C`\ep{}\*(C'\fR "matches property"
344 construct and the \f(CW\*(C`\eP{}\*(C'\fR negation, "doesn\*(Aqt match property".
345 .Sp
346 See "Unicode Character Properties" for more details.
347 .Sp
348 You can define your own character properties and use them
349 in the regular expression with the \f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR construct.
350 See "User\-Defined Character Properties" for more details.
351 .SS "Extended Grapheme Clusters (Logical characters)"
352 .IX Subsection "Extended Grapheme Clusters (Logical characters)"
353 Consider a character, say \f(CW\*(C`H\*(C'\fR. It could appear with various marks around it,
354 such as an acute accent, or a circumflex, or various hooks, circles, arrows,
355 \&\fIetc.\fR, above, below, to one side or the other, \fIetc\fR. There are many
356 possibilities among the world\*(Aqs languages. The number of combinations is
357 astronomical, and if there were a character for each combination, it would
358 soon exhaust Unicode\*(Aqs more than a million possible characters. So Unicode
359 took a different approach: there is a character for the base \f(CW\*(C`H\*(C'\fR, and a
360 character for each of the possible marks, and these can be variously combined
361 to get a final logical character. So a logical character\-\-what appears to be a
362 single character\-\-can be a sequence of more than one individual characters.
363 The Unicode standard calls these "extended grapheme clusters" (which
364 is an improved version of the no\-longer much used "grapheme cluster");
365 Perl furnishes the \f(CW\*(C`\eX\*(C'\fR regular expression construct to match such
366 sequences in their entirety.
367 .PP
368 But Unicode\*(Aqs intent is to unify the existing character set standards and
369 practices, and several pre\-existing standards have single characters that
370 mean the same thing as some of these combinations, like ISO\-8859\-1,
371 which has quite a few of them. For example, \f(CW"LATIN CAPITAL LETTER E
372 WITH ACUTE"\fR was already in this standard when Unicode came along.
373 Unicode therefore added it to its repertoire as that single character.
374 But this character is considered by Unicode to be equivalent to the
375 sequence consisting of the character \f(CW"LATIN CAPITAL LETTER E"\fR
376 followed by the character \f(CW"COMBINING ACUTE ACCENT"\fR.
377 .PP
378 \&\f(CW"LATIN CAPITAL LETTER E WITH ACUTE"\fR is called a "pre\-composed"
379 character, and its equivalence with the "E" and the "COMBINING ACCENT"
380 sequence is called canonical equivalence. All pre\-composed characters
381 are said to have a decomposition (into the equivalent sequence), and the
382 decomposition type is also called canonical. A string may consist
383 as much as possible of precomposed characters, or it may consist of
384 entirely decomposed characters. Unicode calls these respectively,
385 "Normalization Form Composed" (NFC) and "Normalization Form Decomposed".
386 The \f(CW\*(C`Unicode::Normalize\*(C'\fR module contains functions that convert
387 between the two. A string may also have both composed characters and
388 decomposed characters; this module can be used to make it all one or the
389 other.
390 .PP
391 You may be presented with strings in any of these equivalent forms.
392 There is currently nothing in Perl 5 that ignores the differences. So
393 you\*(Aqll have to specially handle it. The usual advice is to convert your
394 inputs to \f(CW\*(C`NFD\*(C'\fR before processing further.
395 .PP
396 For more detailed information, see <http://unicode.org/reports/tr15/>.
397 .SS "Unicode Character Properties"
398 .IX Subsection "Unicode Character Properties"
399 (The only time that Perl considers a sequence of individual code
400 points as a single logical character is in the \f(CW\*(C`\eX\*(C'\fR construct, already
401 mentioned above. Therefore "character" in this discussion means a single
402 Unicode code point.)
403 .PP
404 Very nearly all Unicode character properties are accessible through
405 regular expressions by using the \f(CW\*(C`\ep{}\*(C'\fR "matches property" construct
406 and the \f(CW\*(C`\eP{}\*(C'\fR "doesn\*(Aqt match property" for its negation.
407 .PP
408 For instance, \f(CW\*(C`\ep{Uppercase}\*(C'\fR matches any single character with the Unicode
409 \&\f(CW"Uppercase"\fR property, while \f(CW\*(C`\ep{L}\*(C'\fR matches any character with a
410 \&\f(CW\*(C`General_Category\*(C'\fR of \f(CW"L"\fR (letter) property (see
411 "General_Category" below). Brackets are not
412 required for single letter property names, so \f(CW\*(C`\ep{L}\*(C'\fR is equivalent to \f(CW\*(C`\epL\*(C'\fR.
413 .PP
414 More formally, \f(CW\*(C`\ep{Uppercase}\*(C'\fR matches any single character whose Unicode
415 \&\f(CW\*(C`Uppercase\*(C'\fR property value is \f(CW\*(C`True\*(C'\fR, and \f(CW\*(C`\eP{Uppercase}\*(C'\fR matches any character
416 whose \f(CW\*(C`Uppercase\*(C'\fR property value is \f(CW\*(C`False\*(C'\fR, and they could have been written as
417 \&\f(CW\*(C`\ep{Uppercase=True}\*(C'\fR and \f(CW\*(C`\ep{Uppercase=False}\*(C'\fR, respectively.
418 .PP
419 This formality is needed when properties are not binary; that is, if they can
420 take on more values than just \f(CW\*(C`True\*(C'\fR and \f(CW\*(C`False\*(C'\fR. For example, the
421 \&\f(CW\*(C`Bidi_Class\*(C'\fR property (see "Bidirectional Character Types" below),
422 can take on several different
423 values, such as \f(CW\*(C`Left\*(C'\fR, \f(CW\*(C`Right\*(C'\fR, \f(CW\*(C`Whitespace\*(C'\fR, and others. To match these, one needs
424 to specify both the property name (\f(CW\*(C`Bidi_Class\*(C'\fR), AND the value being
425 matched against
426 (\f(CW\*(C`Left\*(C'\fR, \f(CW\*(C`Right\*(C'\fR, \fIetc.\fR). This is done, as in the examples above, by having the
427 two components separated by an equal sign (or interchangeably, a colon), like
428 \&\f(CW\*(C`\ep{Bidi_Class: Left}\*(C'\fR.
429 .PP
430 All Unicode\-defined character properties may be written in these compound forms
431 of \f(CW\*(C`\ep{\fR\f(CIproperty\fR\f(CW=\fR\f(CIvalue\fR\f(CW}\*(C'\fR or \f(CW\*(C`\ep{\fR\f(CIproperty\fR\f(CW:\fR\f(CIvalue\fR\f(CW}\*(C'\fR, but Perl provides some
432 additional properties that are written only in the single form, as well as
433 single\-form short\-cuts for all binary properties and certain others described
434 below, in which you may omit the property name and the equals or colon
435 separator.
436 .PP
437 Most Unicode character properties have at least two synonyms (or aliases if you
438 prefer): a short one that is easier to type and a longer one that is more
439 descriptive and hence easier to understand. Thus the \f(CW"L"\fR and
440 \&\f(CW"Letter"\fR properties above are equivalent and can be used
441 interchangeably. Likewise, \f(CW"Upper"\fR is a synonym for \f(CW"Uppercase"\fR,
442 and we could have written \f(CW\*(C`\ep{Uppercase}\*(C'\fR equivalently as \f(CW\*(C`\ep{Upper}\*(C'\fR.
443 Also, there are typically various synonyms for the values the property
444 can be. For binary properties, \f(CW"True"\fR has 3 synonyms: \f(CW"T"\fR,
445 \&\f(CW"Yes"\fR, and \f(CW"Y"\fR; and \f(CW"False"\fR has correspondingly \f(CW"F"\fR,
446 \&\f(CW"No"\fR, and \f(CW"N"\fR. But be careful. A short form of a value for one
447 property may not mean the same thing as the short form spelled the same
448 for another.
449 Thus, for the \f(CW"General_Category"\fR property, \f(CW"L"\fR means
450 \&\f(CW"Letter"\fR, but for the \f(CW\*(C`Bidi_Class\*(C'\fR
451 property, \f(CW"L"\fR means \f(CW"Left"\fR. A complete list of properties and
452 synonyms is in perluniprops.
453 .PP
454 Upper/lower case differences in property names and values are irrelevant;
455 thus \f(CW\*(C`\ep{Upper}\*(C'\fR means the same thing as \f(CW\*(C`\ep{upper}\*(C'\fR or even \f(CW\*(C`\ep{UpPeR}\*(C'\fR.
456 Similarly, you can add or subtract underscores anywhere in the middle of a
457 word, so that these are also equivalent to \f(CW\*(C`\ep{U_p_p_e_r}\*(C'\fR. And white space
458 is generally irrelevant adjacent to non\-word characters, such as the
459 braces and the equals or colon separators, so \f(CW\*(C`\ep{ Upper }\*(C'\fR and
460 \&\f(CW\*(C`\ep{ Upper_case : Y }\*(C'\fR are equivalent to these as well. In fact, white
461 space and even hyphens can usually be added or deleted anywhere. So
462 even \f(CW\*(C`\ep{ Up\-per case = Yes}\*(C'\fR is equivalent. All this is called
463 "loose\-matching" by Unicode. The "name" property has some restrictions
464 on this due to a few outlier names. Full details are given in
465 <https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>.
466 .PP
467 The few places where stricter matching is
468 used is in the middle of numbers, the "name" property, and in the Perl
469 extension properties that begin or end with an underscore. Stricter
470 matching cares about white space (except adjacent to non\-word
471 characters), hyphens, and non\-interior underscores.
472 .PP
473 You can also use negation in both \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR by introducing a caret
474 (\f(CW\*(C`^\*(C'\fR) between the first brace and the property name: \f(CW\*(C`\ep{^Tamil}\*(C'\fR is
475 equal to \f(CW\*(C`\eP{Tamil}\*(C'\fR.
476 .PP
477 Almost all properties are immune to case\-insensitive matching. That is,
478 adding a \f(CW\*(C`/i\*(C'\fR regular expression modifier does not change what they
479 match. There are two sets that are affected.
480 The first set is
481 \&\f(CW\*(C`Uppercase_Letter\*(C'\fR,
482 \&\f(CW\*(C`Lowercase_Letter\*(C'\fR,
483 and \f(CW\*(C`Titlecase_Letter\*(C'\fR,
484 all of which match \f(CW\*(C`Cased_Letter\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
485 And the second set is
486 \&\f(CW\*(C`Uppercase\*(C'\fR,
487 \&\f(CW\*(C`Lowercase\*(C'\fR,
488 and \f(CW\*(C`Titlecase\*(C'\fR,
489 all of which match \f(CW\*(C`Cased\*(C'\fR under \f(CW\*(C`/i\*(C'\fR matching.
490 This set also includes its subsets \f(CW\*(C`PosixUpper\*(C'\fR and \f(CW\*(C`PosixLower\*(C'\fR both
491 of which under \f(CW\*(C`/i\*(C'\fR match \f(CW\*(C`PosixAlpha\*(C'\fR.
492 (The difference between these sets is that some things, such as Roman
493 numerals, come in both upper and lower case so they are \f(CW\*(C`Cased\*(C'\fR, but
494 aren\*(Aqt considered letters, so they aren\*(Aqt \f(CW\*(C`Cased_Letter\*(C'\fR\*(Aqs.)
495 .PP
496 See "Beyond Unicode code points" for special considerations when
497 matching Unicode properties against non\-Unicode code points.
498 .PP
499 \fR\f(BIGeneral_Category\fR\fI\fR
500 .IX Subsection "General_Category"
501 .PP
502 Every Unicode character is assigned a general category, which is the "most
503 usual categorization of a character" (from
504 <https://www.unicode.org/reports/tr44>).
505 .PP
506 The compound way of writing these is like \f(CW\*(C`\ep{General_Category=Number}\*(C'\fR
507 (short: \f(CW\*(C`\ep{gc:n}\*(C'\fR). But Perl furnishes shortcuts in which everything up
508 through the equal or colon separator is omitted. So you can instead just write
509 \&\f(CW\*(C`\epN\*(C'\fR.
510 .PP
511 Here are the short and long forms of the values the \f(CW\*(C`General Category\*(C'\fR property
512 can have:
513 .PP
514 .Vb 1
515 \& Short Long
516 \&
517 \& L Letter
518 \& LC, L& Cased_Letter (that is: [\ep{Ll}\ep{Lu}\ep{Lt}])
519 \& Lu Uppercase_Letter
520 \& Ll Lowercase_Letter
521 \& Lt Titlecase_Letter
522 \& Lm Modifier_Letter
523 \& Lo Other_Letter
524 \&
525 \& M Mark
526 \& Mn Nonspacing_Mark
527 \& Mc Spacing_Mark
528 \& Me Enclosing_Mark
529 \&
530 \& N Number
531 \& Nd Decimal_Number (also Digit)
532 \& Nl Letter_Number
533 \& No Other_Number
534 \&
535 \& P Punctuation (also Punct)
536 \& Pc Connector_Punctuation
537 \& Pd Dash_Punctuation
538 \& Ps Open_Punctuation
539 \& Pe Close_Punctuation
540 \& Pi Initial_Punctuation
541 \& (may behave like Ps or Pe depending on usage)
542 \& Pf Final_Punctuation
543 \& (may behave like Ps or Pe depending on usage)
544 \& Po Other_Punctuation
545 \&
546 \& S Symbol
547 \& Sm Math_Symbol
548 \& Sc Currency_Symbol
549 \& Sk Modifier_Symbol
550 \& So Other_Symbol
551 \&
552 \& Z Separator
553 \& Zs Space_Separator
554 \& Zl Line_Separator
555 \& Zp Paragraph_Separator
556 \&
557 \& C Other
558 \& Cc Control (also Cntrl)
559 \& Cf Format
560 \& Cs Surrogate
561 \& Co Private_Use
562 \& Cn Unassigned
563 .Ve
564 .PP
565 Single\-letter properties match all characters in any of the
566 two\-letter sub\-properties starting with the same letter.
567 \&\f(CW\*(C`LC\*(C'\fR and \f(CW\*(C`L&\*(C'\fR are special: both are aliases for the set consisting of everything matched by \f(CW\*(C`Ll\*(C'\fR, \f(CW\*(C`Lu\*(C'\fR, and \f(CW\*(C`Lt\*(C'\fR.
568 .PP
569 \fR\f(BIBidirectional Character Types\fR\fI\fR
570 .IX Subsection "Bidirectional Character Types"
571 .PP
572 Because scripts differ in their directionality (Hebrew and Arabic are
573 written right to left, for example) Unicode supplies a \f(CW\*(C`Bidi_Class\*(C'\fR property.
574 Some of the values this property can have are:
575 .PP
576 .Vb 1
577 \& Value Meaning
578 \&
579 \& L Left\-to\-Right
580 \& LRE Left\-to\-Right Embedding
581 \& LRO Left\-to\-Right Override
582 \& R Right\-to\-Left
583 \& AL Arabic Letter
584 \& RLE Right\-to\-Left Embedding
585 \& RLO Right\-to\-Left Override
586 \& PDF Pop Directional Format
587 \& EN European Number
588 \& ES European Separator
589 \& ET European Terminator
590 \& AN Arabic Number
591 \& CS Common Separator
592 \& NSM Non\-Spacing Mark
593 \& BN Boundary Neutral
594 \& B Paragraph Separator
595 \& S Segment Separator
596 \& WS Whitespace
597 \& ON Other Neutrals
598 .Ve
599 .PP
600 This property is always written in the compound form.
601 For example, \f(CW\*(C`\ep{Bidi_Class:R}\*(C'\fR matches characters that are normally
602 written right to left. Unlike the
603 \&\f(CW"General_Category"\fR property, this
604 property can have more values added in a future Unicode release. Those
605 listed above comprised the complete set for many Unicode releases, but
606 others were added in Unicode 6.3; you can always find what the
607 current ones are in perluniprops. And
608 <https://www.unicode.org/reports/tr9/> describes how to use them.
609 .PP
610 \fR\f(BIScripts\fR\fI\fR
611 .IX Subsection "Scripts"
612 .PP
613 The world\*(Aqs languages are written in many different scripts. This sentence
614 (unless you\*(Aqre reading it in translation) is written in Latin, while Russian is
615 written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
616 Hiragana or Katakana. There are many more.
617 .PP
618 The Unicode \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR properties give what
619 script a given character is in. The \f(CW\*(C`Script_Extensions\*(C'\fR property is an
620 improved version of \f(CW\*(C`Script\*(C'\fR, as demonstrated below. Either property
621 can be specified with the compound form like
622 \&\f(CW\*(C`\ep{Script=Hebrew}\*(C'\fR (short: \f(CW\*(C`\ep{sc=hebr}\*(C'\fR), or
623 \&\f(CW\*(C`\ep{Script_Extensions=Javanese}\*(C'\fR (short: \f(CW\*(C`\ep{scx=java}\*(C'\fR).
624 In addition, Perl furnishes shortcuts for all
625 \&\f(CW\*(C`Script_Extensions\*(C'\fR property names. You can omit everything up through
626 the equals (or colon), and simply write \f(CW\*(C`\ep{Latin}\*(C'\fR or \f(CW\*(C`\eP{Cyrillic}\*(C'\fR.
627 (This is not true for \f(CW\*(C`Script\*(C'\fR, which is required to be
628 written in the compound form. Prior to Perl v5.26, the single form
629 returned the plain old \f(CW\*(C`Script\*(C'\fR version, but was changed because
630 \&\f(CW\*(C`Script_Extensions\*(C'\fR gives better results.)
631 .PP
632 The difference between these two properties involves characters that are
633 used in multiple scripts. For example the digits \*(Aq0\*(Aq through \*(Aq9\*(Aq are
634 used in many parts of the world. These are placed in a script named
635 \&\f(CW\*(C`Common\*(C'\fR. Other characters are used in just a few scripts. For
636 example, the \f(CW"KATAKANA\-HIRAGANA DOUBLE HYPHEN"\fR is used in both Japanese
637 scripts, Katakana and Hiragana, but nowhere else. The \f(CW\*(C`Script\*(C'\fR
638 property places all characters that are used in multiple scripts in the
639 \&\f(CW\*(C`Common\*(C'\fR script, while the \f(CW\*(C`Script_Extensions\*(C'\fR property places those
640 that are used in only a few scripts into each of those scripts; while
641 still using \f(CW\*(C`Common\*(C'\fR for those used in many scripts. Thus both of these
642 match:
643 .PP
644 .Vb 2
645 \& "0" =~ /\ep{sc=Common}/ # Matches
646 \& "0" =~ /\ep{scx=Common}/ # Matches
647 .Ve
648 .PP
649 and only the first of these match:
650 .PP
651 .Vb 2
652 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Common} # Matches
653 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Common} # No match
654 .Ve
655 .PP
656 And only the last two of these match:
657 .PP
658 .Vb 4
659 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Hiragana} # No match
660 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{sc=Katakana} # No match
661 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Hiragana} # Matches
662 \& "\eN{KATAKANA\-HIRAGANA DOUBLE HYPHEN}" =~ /\ep{scx=Katakana} # Matches
663 .Ve
664 .PP
665 \&\f(CW\*(C`Script_Extensions\*(C'\fR is thus an improved \f(CW\*(C`Script\*(C'\fR, in which there are
666 fewer characters in the \f(CW\*(C`Common\*(C'\fR script, and correspondingly more in
667 other scripts. It is new in Unicode version 6.0, and its data are likely
668 to change significantly in later releases, as things get sorted out.
669 New code should probably be using \f(CW\*(C`Script_Extensions\*(C'\fR and not plain
670 \&\f(CW\*(C`Script\*(C'\fR. If you compile perl with a Unicode release that doesn\*(Aqt have
671 \&\f(CW\*(C`Script_Extensions\*(C'\fR, the single form Perl extensions will instead refer
672 to the plain \f(CW\*(C`Script\*(C'\fR property. If you compile with a version of
673 Unicode that doesn\*(Aqt have the \f(CW\*(C`Script\*(C'\fR property, these extensions will
674 not be defined at all.
675 .PP
676 (Actually, besides \f(CW\*(C`Common\*(C'\fR, the \f(CW\*(C`Inherited\*(C'\fR script, contains
677 characters that are used in multiple scripts. These are modifier
678 characters which inherit the script value
679 of the controlling character. Some of these are used in many scripts,
680 and so go into \f(CW\*(C`Inherited\*(C'\fR in both \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR.
681 Others are used in just a few scripts, so are in \f(CW\*(C`Inherited\*(C'\fR in
682 \&\f(CW\*(C`Script\*(C'\fR, but not in \f(CW\*(C`Script_Extensions\*(C'\fR.)
683 .PP
684 It is worth stressing that there are several different sets of digits in
685 Unicode that are equivalent to 0\-9 and are matchable by \f(CW\*(C`\ed\*(C'\fR in a
686 regular expression. If they are used in a single language only, they
687 are in that language\*(Aqs \f(CW\*(C`Script\*(C'\fR and \f(CW\*(C`Script_Extensions\*(C'\fR. If they are
688 used in more than one script, they will be in \f(CW\*(C`sc=Common\*(C'\fR, but only
689 if they are used in many scripts should they be in \f(CW\*(C`scx=Common\*(C'\fR.
690 .PP
691 The explanation above has omitted some detail; refer to UAX#24 "Unicode
692 Script Property": <https://www.unicode.org/reports/tr24>.
693 .PP
694 A complete list of scripts and their shortcuts is in perluniprops.
695 .PP
696 \fR\f(BIUse of the \fR\f(CB"Is"\fR\f(BI Prefix\fR\fI\fR
697 .IX Subsection "Use of the ""Is"" Prefix"
698 .PP
699 For backward compatibility (with ancient Perl 5.6), all properties writable
700 without using the compound form mentioned
701 so far may have \f(CW\*(C`Is\*(C'\fR or \f(CW\*(C`Is_\*(C'\fR prepended to their name, so \f(CW\*(C`\eP{Is_Lu}\*(C'\fR, for
702 example, is equal to \f(CW\*(C`\eP{Lu}\*(C'\fR, and \f(CW\*(C`\ep{IsScript:Arabic}\*(C'\fR is equal to
703 \&\f(CW\*(C`\ep{Arabic}\*(C'\fR.
704 .PP
705 \fR\f(BIBlocks\fR\fI\fR
706 .IX Subsection "Blocks"
707 .PP
708 In addition to \fBscripts\fR, Unicode also defines \fBblocks\fR of
709 characters. The difference between scripts and blocks is that the
710 concept of scripts is closer to natural languages, while the concept
711 of blocks is more of an artificial grouping based on groups of Unicode
712 characters with consecutive ordinal values. For example, the \f(CW"Basic Latin"\fR
713 block is all the characters whose ordinals are between 0 and 127, inclusive; in
714 other words, the ASCII characters. The \f(CW"Latin"\fR script contains some letters
715 from this as well as several other blocks, like \f(CW"Latin\-1 Supplement"\fR,
716 \&\f(CW"Latin Extended\-A"\fR, \fIetc.\fR, but it does not contain all the characters from
717 those blocks. It does not, for example, contain the digits 0\-9, because
718 those digits are shared across many scripts, and hence are in the
719 \&\f(CW\*(C`Common\*(C'\fR script.
720 .PP
721 For more about scripts versus blocks, see UAX#24 "Unicode Script Property":
722 <https://www.unicode.org/reports/tr24>
723 .PP
724 The \f(CW\*(C`Script_Extensions\*(C'\fR or \f(CW\*(C`Script\*(C'\fR properties are likely to be the
725 ones you want to use when processing
726 natural language; the \f(CW\*(C`Block\*(C'\fR property may occasionally be useful in working
727 with the nuts and bolts of Unicode.
728 .PP
729 Block names are matched in the compound form, like \f(CW\*(C`\ep{Block: Arrows}\*(C'\fR or
730 \&\f(CW\*(C`\ep{Blk=Hebrew}\*(C'\fR. Unlike most other properties, only a few block names have a
731 Unicode\-defined short name.
732 .PP
733 Perl also defines single form synonyms for the block property in cases
734 where these do not conflict with something else. But don\*(Aqt use any of
735 these, because they are unstable. Since these are Perl extensions, they
736 are subordinate to official Unicode property names; Unicode doesn\*(Aqt know
737 nor care about Perl\*(Aqs extensions. It may happen that a name that
738 currently means the Perl extension will later be changed without warning
739 to mean a different Unicode property in a future version of the perl
740 interpreter that uses a later Unicode release, and your code would no
741 longer work. The extensions are mentioned here for completeness: Take
742 the block name and prefix it with one of: \f(CW\*(C`In\*(C'\fR (for example
743 \&\f(CW\*(C`\ep{Blk=Arrows}\*(C'\fR can currently be written as \f(CW\*(C`\ep{In_Arrows}\*(C'\fR); or
744 sometimes \f(CW\*(C`Is\*(C'\fR (like \f(CW\*(C`\ep{Is_Arrows}\*(C'\fR); or sometimes no prefix at all
745 (\f(CW\*(C`\ep{Arrows}\*(C'\fR). As of this writing (Unicode 9.0) there are no
746 conflicts with using the \f(CW\*(C`In_\*(C'\fR prefix, but there are plenty with the
747 other two forms. For example, \f(CW\*(C`\ep{Is_Hebrew}\*(C'\fR and \f(CW\*(C`\ep{Hebrew}\*(C'\fR mean
748 \&\f(CW\*(C`\ep{Script_Extensions=Hebrew}\*(C'\fR which is NOT the same thing as
749 \&\f(CW\*(C`\ep{Blk=Hebrew}\*(C'\fR. Our
750 advice used to be to use the \f(CW\*(C`In_\*(C'\fR prefix as a single form way of
751 specifying a block. But Unicode 8.0 added properties whose names begin
752 with \f(CW\*(C`In\*(C'\fR, and it\*(Aqs now clear that it\*(Aqs only luck that\*(Aqs so far
753 prevented a conflict. Using \f(CW\*(C`In\*(C'\fR is only marginally less typing than
754 \&\f(CW\*(C`Blk:\*(C'\fR, and the latter\*(Aqs meaning is clearer anyway, and guaranteed to
755 never conflict. So don\*(Aqt take chances. Use \f(CW\*(C`\ep{Blk=foo}\*(C'\fR for new
756 code. And be sure that block is what you really really want to do. In
757 most cases scripts are what you want instead.
758 .PP
759 A complete list of blocks is in perluniprops.
760 .PP
761 \fR\f(BIOther Properties\fR\fI\fR
762 .IX Subsection "Other Properties"
763 .PP
764 There are many more properties than the very basic ones described here.
765 A complete list is in perluniprops.
766 .PP
767 Unicode defines all its properties in the compound form, so all single\-form
768 properties are Perl extensions. Most of these are just synonyms for the
769 Unicode ones, but some are genuine extensions, including several that are in
770 the compound form. And quite a few of these are actually recommended by Unicode
771 (in <https://www.unicode.org/reports/tr18>).
772 .PP
773 This section gives some details on all extensions that aren\*(Aqt just
774 synonyms for compound\-form Unicode properties
775 (for those properties, you\*(Aqll have to refer to the
776 Unicode Standard <https://www.unicode.org/reports/tr44>.
777 .ie n .IP "\fR\fB""\ep{All}""\fR\fB\fR" 4
778 .el .IP \fR\f(CB\ep{All}\fR\fB\fR 4
779 .IX Item "p{All}"
780 This matches every possible code point. It is equivalent to \f(CW\*(C`qr/./s\*(C'\fR.
781 Unlike all the other non\-user\-defined \f(CW\*(C`\ep{}\*(C'\fR property matches, no
782 warning is ever generated if this is property is matched against a
783 non\-Unicode code point (see "Beyond Unicode code points" below).
784 .ie n .IP "\fR\fB""\ep{Alnum}""\fR\fB\fR" 4
785 .el .IP \fR\f(CB\ep{Alnum}\fR\fB\fR 4
786 .IX Item "p{Alnum}"
787 This matches any \f(CW\*(C`\ep{Alphabetic}\*(C'\fR or \f(CW\*(C`\ep{Decimal_Number}\*(C'\fR character.
788 .ie n .IP "\fR\fB""\ep{Any}""\fR\fB\fR" 4
789 .el .IP \fR\f(CB\ep{Any}\fR\fB\fR 4
790 .IX Item "p{Any}"
791 This matches any of the 1_114_112 Unicode code points. It is a synonym
792 for \f(CW\*(C`\ep{Unicode}\*(C'\fR.
793 .ie n .IP "\fR\fB""\ep{ASCII}""\fR\fB\fR" 4
794 .el .IP \fR\f(CB\ep{ASCII}\fR\fB\fR 4
795 .IX Item "p{ASCII}"
796 This matches any of the 128 characters in the US\-ASCII character set,
797 which is a subset of Unicode.
798 .ie n .IP "\fR\fB""\ep{Assigned}""\fR\fB\fR" 4
799 .el .IP \fR\f(CB\ep{Assigned}\fR\fB\fR 4
800 .IX Item "p{Assigned}"
801 This matches any assigned code point; that is, any code point whose general
802 category is not \f(CW\*(C`Unassigned\*(C'\fR (or equivalently, not \f(CW\*(C`Cn\*(C'\fR).
803 .ie n .IP "\fR\fB""\ep{Blank}""\fR\fB\fR" 4
804 .el .IP \fR\f(CB\ep{Blank}\fR\fB\fR 4
805 .IX Item "p{Blank}"
806 This is the same as \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ep{HorizSpace}\*(C'\fR: A character that changes the
807 spacing horizontally.
808 .ie n .IP "\fR\fB""\ep{Decomposition_Type: Non_Canonical}""\fR\fB\fR (Short: ""\ep{Dt=NonCanon}"")" 4
809 .el .IP "\fR\f(CB\ep{Decomposition_Type: Non_Canonical}\fR\fB\fR (Short: \f(CW\ep{Dt=NonCanon}\fR)" 4
810 .IX Item "p{Decomposition_Type: Non_Canonical} (Short: p{Dt=NonCanon})"
811 Matches a character that has any of the non\-canonical decomposition
812 types. Canonical decompositions are introduced in the
813 "Extended Grapheme Clusters (Logical characters)" section above.
814 However, many more characters have a different type of decomposition,
815 generically called "compatible" decompositions, or "non\-canonical". The
816 sequences that form these decompositions are not considered canonically
817 equivalent to the pre\-composed character. An example is the
818 \&\f(CW"SUPERSCRIPT ONE"\fR. It is somewhat like a regular digit 1, but not
819 exactly; its decomposition into the digit 1 is called a "compatible"
820 decomposition, specifically a "super" (for "superscript") decomposition.
821 There are several such compatibility decompositions (see
822 <https://www.unicode.org/reports/tr44>). \f(CW\*(C`\ep{Dt:\ Non_Canon}\*(C'\fR is a
823 Perl extension that uses just one name to refer to the union of all of
824 them.
825 .Sp
826 Most Unicode characters don\*(Aqt have a decomposition, so their
827 decomposition type is \f(CW"None"\fR. Hence, \f(CW\*(C`Non_Canonical\*(C'\fR is equivalent
828 to
829 .Sp
830 .Vb 1
831 \& qr/(?[ \eP{DT=Canonical} \- \ep{DT=None} ])/
832 .Ve
833 .Sp
834 (Note that one of the non\-canonical decompositions is named "compat",
835 which could perhaps have been better named "miscellaneous". It includes
836 just the things that Unicode couldn\*(Aqt figure out a better generic name
837 for.)
838 .ie n .IP "\fR\fB""\ep{Graph}""\fR\fB\fR" 4
839 .el .IP \fR\f(CB\ep{Graph}\fR\fB\fR 4
840 .IX Item "p{Graph}"
841 Matches any character that is graphic. Theoretically, this means a character
842 that on a printer would cause ink to be used.
843 .ie n .IP "\fR\fB""\ep{HorizSpace}""\fR\fB\fR" 4
844 .el .IP \fR\f(CB\ep{HorizSpace}\fR\fB\fR 4
845 .IX Item "p{HorizSpace}"
846 This is the same as \f(CW\*(C`\eh\*(C'\fR and \f(CW\*(C`\ep{Blank}\*(C'\fR: a character that changes the
847 spacing horizontally.
848 .ie n .IP "\fR\fB""\ep{In=*}""\fR\fB\fR" 4
849 .el .IP \fR\f(CB\ep{In=*}\fR\fB\fR 4
850 .IX Item "p{In=*}"
851 This is a synonym for \f(CW\*(C`\ep{Present_In=*}\*(C'\fR
852 .ie n .IP "\fR\fB""\ep{PerlSpace}""\fR\fB\fR" 4
853 .el .IP \fR\f(CB\ep{PerlSpace}\fR\fB\fR 4
854 .IX Item "p{PerlSpace}"
855 This is the same as \f(CW\*(C`\es\*(C'\fR, restricted to ASCII, namely \f(CW\*(C`[\ \ef\en\er\et]\*(C'\fR
856 and starting in Perl v5.18, a vertical tab.
857 .Sp
858 Mnemonic: Perl\*(Aqs (original) space
859 .ie n .IP "\fR\fB""\ep{PerlWord}""\fR\fB\fR" 4
860 .el .IP \fR\f(CB\ep{PerlWord}\fR\fB\fR 4
861 .IX Item "p{PerlWord}"
862 This is the same as \f(CW\*(C`\ew\*(C'\fR, restricted to ASCII, namely \f(CW\*(C`[A\-Za\-z0\-9_]\*(C'\fR
863 .Sp
864 Mnemonic: Perl\*(Aqs (original) word.
865 .ie n .IP "\fR\fB""\ep{Posix...}""\fR\fB\fR" 4
866 .el .IP \fR\f(CB\ep{Posix...}\fR\fB\fR 4
867 .IX Item "p{Posix...}"
868 There are several of these, which are equivalents, using the \f(CW\*(C`\ep{}\*(C'\fR
869 notation, for Posix classes and are described in
870 "POSIX Character Classes" in perlrecharclass.
871 .ie n .IP "\fR\fB""\ep{Present_In: *}""\fR\fB\fR (Short: ""\ep{In=*}"")" 4
872 .el .IP "\fR\f(CB\ep{Present_In: *}\fR\fB\fR (Short: \f(CW\ep{In=*}\fR)" 4
873 .IX Item "p{Present_In: *} (Short: p{In=*})"
874 This property is used when you need to know in what Unicode version(s) a
875 character is.
876 .Sp
877 The "*" above stands for some Unicode version number, such as
878 \&\f(CW1.1\fR or \f(CW12.0\fR; or the "*" can also be \f(CW\*(C`Unassigned\*(C'\fR. This property will
879 match the code points whose final disposition has been settled as of the
880 Unicode release given by the version number; \f(CW\*(C`\ep{Present_In: Unassigned}\*(C'\fR
881 will match those code points whose meaning has yet to be assigned.
882 .Sp
883 For example, \f(CW\*(C`U+0041\*(C'\fR \f(CW"LATIN CAPITAL LETTER A"\fR was present in the very first
884 Unicode release available, which is \f(CW1.1\fR, so this property is true for all
885 valid "*" versions. On the other hand, \f(CW\*(C`U+1EFF\*(C'\fR was not assigned until version
886 5.1 when it became \f(CW"LATIN SMALL LETTER Y WITH LOOP"\fR, so the only "*" that
887 would match it are 5.1, 5.2, and later.
888 .Sp
889 Unicode furnishes the \f(CW\*(C`Age\*(C'\fR property from which this is derived. The problem
890 with Age is that a strict interpretation of it (which Perl takes) has it
891 matching the precise release a code point\*(Aqs meaning is introduced in. Thus
892 \&\f(CW\*(C`U+0041\*(C'\fR would match only 1.1; and \f(CW\*(C`U+1EFF\*(C'\fR only 5.1. This is not usually what
893 you want.
894 .Sp
895 Some non\-Perl implementations of the Age property may change its meaning to be
896 the same as the Perl \f(CW\*(C`Present_In\*(C'\fR property; just be aware of that.
897 .Sp
898 Another confusion with both these properties is that the definition is not
899 that the code point has been \fIassigned\fR, but that the meaning of the code point
900 has been \fIdetermined\fR. This is because 66 code points will always be
901 unassigned, and so the \f(CW\*(C`Age\*(C'\fR for them is the Unicode version in which the decision
902 to make them so was made. For example, \f(CW\*(C`U+FDD0\*(C'\fR is to be permanently
903 unassigned to a character, and the decision to do that was made in version 3.1,
904 so \f(CW\*(C`\ep{Age=3.1}\*(C'\fR matches this character, as also does \f(CW\*(C`\ep{Present_In: 3.1}\*(C'\fR and up.
905 .ie n .IP "\fR\fB""\ep{Print}""\fR\fB\fR" 4
906 .el .IP \fR\f(CB\ep{Print}\fR\fB\fR 4
907 .IX Item "p{Print}"
908 This matches any character that is graphical or blank, except controls.
909 .ie n .IP "\fR\fB""\ep{SpacePerl}""\fR\fB\fR" 4
910 .el .IP \fR\f(CB\ep{SpacePerl}\fR\fB\fR 4
911 .IX Item "p{SpacePerl}"
912 This is the same as \f(CW\*(C`\es\*(C'\fR, including beyond ASCII.
913 .Sp
914 Mnemonic: Space, as modified by Perl. (It doesn\*(Aqt include the vertical tab
915 until v5.18, which both the Posix standard and Unicode consider white space.)
916 .ie n .IP "\fR\fB""\ep{Title}""\fR\fB\fR and \fB\fR\fB""\ep{Titlecase}""\fR\fB\fR" 4
917 .el .IP "\fR\f(CB\ep{Title}\fR\fB\fR and \fB\fR\f(CB\ep{Titlecase}\fR\fB\fR" 4
918 .IX Item "p{Title} and p{Titlecase}"
919 Under case\-sensitive matching, these both match the same code points as
920 \&\f(CW\*(C`\ep{General Category=Titlecase_Letter}\*(C'\fR (\f(CW\*(C`\ep{gc=lt}\*(C'\fR). The difference
921 is that under \f(CW\*(C`/i\*(C'\fR caseless matching, these match the same as
922 \&\f(CW\*(C`\ep{Cased}\*(C'\fR, whereas \f(CW\*(C`\ep{gc=lt}\*(C'\fR matches \f(CW\*(C`\ep{Cased_Letter\*(C'\fR).
923 .ie n .IP "\fR\fB""\ep{Unicode}""\fR\fB\fR" 4
924 .el .IP \fR\f(CB\ep{Unicode}\fR\fB\fR 4
925 .IX Item "p{Unicode}"
926 This matches any of the 1_114_112 Unicode code points.
927 \&\f(CW\*(C`\ep{Any}\*(C'\fR.
928 .ie n .IP "\fR\fB""\ep{VertSpace}""\fR\fB\fR" 4
929 .el .IP \fR\f(CB\ep{VertSpace}\fR\fB\fR 4
930 .IX Item "p{VertSpace}"
931 This is the same as \f(CW\*(C`\ev\*(C'\fR: A character that changes the spacing vertically.
932 .ie n .IP "\fR\fB""\ep{Word}""\fR\fB\fR" 4
933 .el .IP \fR\f(CB\ep{Word}\fR\fB\fR 4
934 .IX Item "p{Word}"
935 This is the same as \f(CW\*(C`\ew\*(C'\fR, including over 100_000 characters beyond ASCII.
936 .ie n .IP "\fR\fB""\ep{XPosix...}""\fR\fB\fR" 4
937 .el .IP \fR\f(CB\ep{XPosix...}\fR\fB\fR 4
938 .IX Item "p{XPosix...}"
939 There are several of these, which are the standard Posix classes
940 extended to the full Unicode range. They are described in
941 "POSIX Character Classes" in perlrecharclass.
942 .ie n .SS "Comparison of ""\eN{...}"" and ""\ep{name=...}"""
943 .el .SS "Comparison of \f(CW\eN{...}\fP and \f(CW\ep{name=...}\fP"
944 .IX Subsection "Comparison of N{...} and p{name=...}"
945 Starting in Perl 5.32, you can specify a character by its name in
946 regular expression patterns using \f(CW\*(C`\ep{name=...}\*(C'\fR. This is in addition
947 to the longstanding method of using \f(CW\*(C`\eN{...}\*(C'\fR. The following
948 summarizes the differences between these two:
949 .PP
950 .Vb 6
951 \& \eN{...} \ep{Name=...}
952 \& can interpolate only with eval yes [1]
953 \& custom names yes no [2]
954 \& name aliases yes yes [3]
955 \& named sequences yes yes [4]
956 \& name value parsing exact Unicode loose [5]
957 .Ve
958 .IP [1] 4
959 .IX Item "[1]"
960 The ability to interpolate means you can do something like
961 .Sp
962 .Vb 1
963 \& qr/\ep{na=latin capital letter $which}/
964 .Ve
965 .Sp
966 and specify \f(CW$which\fR elsewhere.
967 .IP [2] 4
968 .IX Item "[2]"
969 You can create your own names for characters, and override official
970 ones when using \f(CW\*(C`\eN{...}\*(C'\fR. See "CUSTOM ALIASES" in charnames.
971 .IP [3] 4
972 .IX Item "[3]"
973 Some characters have multiple names (synonyms).
974 .IP [4] 4
975 .IX Item "[4]"
976 Some particular sequences of characters are given a single name, in
977 addition to their individual ones.
978 .IP [5] 4
979 .IX Item "[5]"
980 Exact name value matching means you have to specify case, hyphens,
981 underscores, and spaces precisely in the name you want. Loose matching
982 follows the Unicode rules
983 <https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>,
984 where these are mostly irrelevant. Except for a few outlier character
985 names, these are the same rules as are already used for any other
986 \&\f(CW\*(C`\ep{...}\*(C'\fR property.
987 .SS "Wildcards in Property Values"
988 .IX Subsection "Wildcards in Property Values"
989 Starting in Perl 5.30, it is possible to do something like this:
990 .PP
991 .Vb 1
992 \& qr!\ep{numeric_value=/\eA[0\-5]\ez/}!
993 .Ve
994 .PP
995 or, by abbreviating and adding \f(CW\*(C`/x\*(C'\fR,
996 .PP
997 .Vb 1
998 \& qr! \ep{nv= /(?x) \eA [0\-5] \ez / }!
999 .Ve
1000 .PP
1001 This matches all code points whose numeric value is one of 0, 1, 2, 3,
1002 4, or 5. This particular example could instead have been written as
1003 .PP
1004 .Vb 1
1005 \& qr! \eA [ \ep{nv=0}\ep{nv=1}\ep{nv=2}\ep{nv=3}\ep{nv=4}\ep{nv=5} ] \ez !xx
1006 .Ve
1007 .PP
1008 in earlier perls, so in this case this feature just makes things easier
1009 and shorter to write. If we hadn\*(Aqt included the \f(CW\*(C`\eA\*(C'\fR and \f(CW\*(C`\ez\*(C'\fR, these
1010 would have matched things like \f(CW\*(C`1/2\*(C'\fR because that contains a 1 (as
1011 well as a 2). As written, it matches things like subscripts that have
1012 these numeric values. If we only wanted the decimal digits with those
1013 numeric values, we could say,
1014 .PP
1015 .Vb 1
1016 \& qr! (?[ \ed & \ep{nv=/[0\-5]/ ]) }!x
1017 .Ve
1018 .PP
1019 The \f(CW\*(C`\ed\*(C'\fR gets rid of needing to anchor the pattern, since it forces the
1020 result to only match \f(CW\*(C`[0\-9]\*(C'\fR, and the \f(CW\*(C`[0\-5]\*(C'\fR further restricts it.
1021 .PP
1022 The text in the above examples enclosed between the \f(CW"/"\fR
1023 characters can be just about any regular expression. It is independent
1024 of the main pattern, so doesn\*(Aqt share any capturing groups, \fIetc\fR. The
1025 delimiters for it must be ASCII punctuation, but it may NOT be
1026 delimited by \f(CW"{"\fR, nor \f(CW"}"\fR nor contain a literal \f(CW"}"\fR, as that
1027 delimits the end of the enclosing \f(CW\*(C`\ep{}\*(C'\fR. Like any pattern, certain
1028 other delimiters are terminated by their mirror images. These are
1029 \&\f(CW"("\fR, \f(CW\*(C`"[\*(C'\fR", and \f(CW"<"\fR. If the delimiter is any of \f(CW"\-"\fR,
1030 \&\f(CW"_"\fR, \f(CW"+"\fR, or \f(CW"\e"\fR, or is the same delimiter as is used for the
1031 enclosing pattern, it must be preceded by a backslash escape, both
1032 fore and aft.
1033 .PP
1034 Beware of using \f(CW"$"\fR to indicate to match the end of the string. It
1035 can too easily be interpreted as being a punctuation variable, like
1036 \&\f(CW$/\fR.
1037 .PP
1038 No modifiers may follow the final delimiter. Instead, use
1039 "(?adlupimnsx\-imnsx)" in perlre and/or
1040 "(?adluimnsx\-imnsx:pattern)" in perlre to specify modifiers.
1041 However, certain modifiers are illegal in your wildcard subpattern.
1042 The only character set modifier specifiable is \f(CW\*(C`/aa\*(C'\fR;
1043 any other character set, and \f(CW\*(C`\-m\*(C'\fR, and \f(CW\*(C`p\*(C'\fR, and \f(CW\*(C`s\*(C'\fR are all illegal.
1044 Specifying modifiers like \f(CW\*(C`qr/.../gc\*(C'\fR that aren\*(Aqt legal in the
1045 \&\f(CW\*(C`(?...)\*(C'\fR notation normally raise a warning, but with wildcard
1046 subpatterns, their use is an error. The \f(CW\*(C`m\*(C'\fR modifier is ineffective;
1047 everything that matches will be a single line.
1048 .PP
1049 By default, your pattern is matched case\-insensitively, as if \f(CW\*(C`/i\*(C'\fR had
1050 been specified. You can change this by saying \f(CW\*(C`(?\-i)\*(C'\fR in your pattern.
1051 .PP
1052 There are also certain operations that are illegal. You can\*(Aqt nest
1053 \&\f(CW\*(C`\ep{...}\*(C'\fR and \f(CW\*(C`\eP{...}\*(C'\fR calls within a wildcard subpattern, and \f(CW\*(C`\eG\*(C'\fR
1054 doesn\*(Aqt make sense, so is also prohibited.
1055 .PP
1056 And the \f(CW\*(C`*\*(C'\fR quantifier (or its equivalent \f(CW\*(C`(0,}\*(C'\fR) is illegal.
1057 .PP
1058 This feature is not available when the left\-hand side is prefixed by
1059 \&\f(CW\*(C`Is_\*(C'\fR, nor for any form that is marked as "Discouraged" in
1060 "Discouraged" in perluniprops.
1061 .PP
1062 This experimental feature has been added to begin to implement
1063 <https://www.unicode.org/reports/tr18/#Wildcard_Properties>. Using it
1064 will raise a (default\-on) warning in the
1065 \&\f(CW\*(C`experimental::uniprop_wildcards\*(C'\fR category. We reserve the right to
1066 change its operation as we gain experience.
1067 .PP
1068 Your subpattern can be just about anything, but for it to have some
1069 utility, it should match when called with either or both of
1070 a) the full name of the property value with underscores (and/or spaces
1071 in the Block property) and some things uppercase; or b) the property
1072 value in all lowercase with spaces and underscores squeezed out. For
1073 example,
1074 .PP
1075 .Vb 2
1076 \& qr!\ep{Blk=/Old I.*/}!
1077 \& qr!\ep{Blk=/oldi.*/}!
1078 .Ve
1079 .PP
1080 would match the same things.
1081 .PP
1082 Another example that shows that within \f(CW\*(C`\ep{...}\*(C'\fR, \f(CW\*(C`/x\*(C'\fR isn\*(Aqt needed to
1083 have spaces:
1084 .PP
1085 .Vb 1
1086 \& qr!\ep{scx= /Hebrew|Greek/ }!
1087 .Ve
1088 .PP
1089 To be safe, we should have anchored the above example, to prevent
1090 matches for something like \f(CW\*(C`Hebrew_Braille\*(C'\fR, but there aren\*(Aqt
1091 any script names like that, so far.
1092 A warning is issued if none of the legal values for a property are
1093 matched by your pattern. It\*(Aqs likely that a future release will raise a
1094 warning if your pattern ends up causing every possible code point to
1095 match.
1096 .PP
1097 Starting in 5.32, the Name, Name Aliases, and Named Sequences properties
1098 are allowed to be matched. They are considered to be a single
1099 combination property, just as has long been the case for \f(CW\*(C`\eN{}\*(C'\fR. Loose
1100 matching doesn\*(Aqt work in exactly the same way for these as it does for
1101 the values of other properties. The rules are given in
1102 <https://www.unicode.org/reports/tr44/tr44\-24.html#UAX44\-LM2>. As a
1103 result, Perl doesn\*(Aqt try loose matching for you, like it does in other
1104 properties. All letters in names are uppercase, but you can add \f(CW\*(C`(?i)\*(C'\fR
1105 to your subpattern to ignore case. If you\*(Aqre uncertain where a blank
1106 is, you can use \f(CW\*(C` ?\*(C'\fR in your subpattern. No character name contains an
1107 underscore, so don\*(Aqt bother trying to match one. The use of hyphens is
1108 particularly problematic; refer to the above link. But note that, as of
1109 Unicode 13.0, the only script in modern usage which has weirdnesses with
1110 these is Tibetan; also the two Korean characters U+116C HANGUL JUNGSEONG
1111 OE and U+1180 HANGUL JUNGSEONG O\-E. Unicode makes no promises to not
1112 add hyphen\-problematic names in the future.
1113 .PP
1114 Using wildcards on these is resource intensive, given the hundreds of
1115 thousands of legal names that must be checked against.
1116 .PP
1117 An example of using Name property wildcards is
1118 .PP
1119 .Vb 1
1120 \& qr!\ep{name=/(SMILING|GRINNING) FACE/}!
1121 .Ve
1122 .PP
1123 Another is
1124 .PP
1125 .Vb 1
1126 \& qr/(?[ \ep{name=\e/CJK\e/} \- \ep{ideographic} ])/
1127 .Ve
1128 .PP
1129 which is the 200\-ish (as of Unicode 13.0) CJK characters that aren\*(Aqt
1130 ideographs.
1131 .PP
1132 There are certain properties that wildcard subpatterns don\*(Aqt currently
1133 work with. These are:
1134 .PP
1135 .Vb 9
1136 \& Bidi Mirroring Glyph
1137 \& Bidi Paired Bracket
1138 \& Case Folding
1139 \& Decomposition Mapping
1140 \& Equivalent Unified Ideograph
1141 \& Lowercase Mapping
1142 \& NFKC Case Fold
1143 \& Titlecase Mapping
1144 \& Uppercase Mapping
1145 .Ve
1146 .PP
1147 Nor is the \f(CW\*(C`@\fR\f(CIunicode_property\fR\f(CW@\*(C'\fR form implemented.
1148 .PP
1149 Here\*(Aqs a complete example of matching IPV4 internet protocol addresses
1150 in any (single) script
1151 .PP
1152 .Vb 1
1153 \& no warnings \*(Aqexperimental::uniprop_wildcards\*(Aq;
1154 \&
1155 \& # Can match a substring, so this intermediate regex needs to have
1156 \& # context or anchoring in its final use. Using nt=de yields decimal
1157 \& # digits. When specifying a subset of these, we must include \ed to
1158 \& # prevent things like U+00B2 SUPERSCRIPT TWO from matching
1159 \& my $zero_through_255 =
1160 \& qr/ \eb (*sr: # All from same script
1161 \& (?[ \ep{nv=0} & \ed ])* # Optional leading zeros
1162 \& ( # Then one of:
1163 \& \ed{1,2} # 0 \- 99
1164 \& | (?[ \ep{nv=1} & \ed ]) \ed{2} # 100 \- 199
1165 \& | (?[ \ep{nv=2} & \ed ])
1166 \& ( (?[ \ep{nv=:[0\-4]:} & \ed ]) \ed # 200 \- 249
1167 \& | (?[ \ep{nv=5} & \ed ])
1168 \& (?[ \ep{nv=:[0\-5]:} & \ed ]) # 250 \- 255
1169 \& )
1170 \& )
1171 \& )
1172 \& \eb
1173 \& /x;
1174 \&
1175 \& my $ipv4 = qr/ \eA (*sr: $zero_through_255
1176 \& (?: [.] $zero_through_255 ) {3}
1177 \& )
1178 \& \ez
1179 \& /x;
1180 .Ve
1181 .SS "User\-Defined Character Properties"
1182 .IX Subsection "User-Defined Character Properties"
1183 You can define your own binary character properties by defining subroutines
1184 whose names begin with \f(CW"In"\fR or \f(CW"Is"\fR. (The regex sets feature
1185 "(?[ ])" in perlre provides an alternative which allows more complex
1186 definitions.) The subroutines can be defined in any
1187 package. They override any Unicode properties expressed as the same
1188 names. The user\-defined properties can be used in the regular
1189 expression
1190 \&\f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR constructs; if you are using a user\-defined property from a
1191 package other than the one you are in, you must specify its package in the
1192 \&\f(CW\*(C`\ep{}\*(C'\fR or \f(CW\*(C`\eP{}\*(C'\fR construct.
1193 .PP
1194 .Vb 3
1195 \& # assuming property IsForeign defined in Lang::
1196 \& package main; # property package name required
1197 \& if ($txt =~ /\ep{Lang::IsForeign}+/) { ... }
1198 \&
1199 \& package Lang; # property package name not required
1200 \& if ($txt =~ /\ep{IsForeign}+/) { ... }
1201 .Ve
1202 .PP
1203 The subroutines are passed a single parameter, which is 0 if
1204 case\-sensitive matching is in effect and non\-zero if caseless matching
1205 is in effect. The subroutine may return different values depending on
1206 the value of the flag. But the subroutine is never called more than
1207 once for each flag value (zero vs non\-zero). The return value is saved
1208 and used instead of calling the sub ever again. If the sub is defined
1209 at the time the pattern is compiled, it will be called then; if not, it
1210 will be called the first time its value (for that flag) is needed during
1211 execution.
1212 .PP
1213 Note that if the regular expression is tainted, then Perl will die rather
1214 than calling the subroutine when the name of the subroutine is
1215 determined by the tainted data.
1216 .PP
1217 The subroutines must return a specially\-formatted string, with one
1218 or more newline\-separated lines. Each line must be one of the following:
1219 .IP \(bu 4
1220 A single hexadecimal number denoting a code point to include.
1221 .IP \(bu 4
1222 Two hexadecimal numbers separated by horizontal whitespace (space or
1223 tabular characters) denoting a range of code points to include. The
1224 second number must not be smaller than the first.
1225 .IP \(bu 4
1226 Something to include, prefixed by \f(CW"+"\fR: a built\-in character
1227 property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
1228 name) user\-defined character property,
1229 to represent all the characters in that property; two hexadecimal code
1230 points for a range; or a single hexadecimal code point.
1231 .IP \(bu 4
1232 Something to exclude, prefixed by \f(CW"\-"\fR: an existing character
1233 property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
1234 name) user\-defined character property,
1235 to represent all the characters in that property; two hexadecimal code
1236 points for a range; or a single hexadecimal code point.
1237 .IP \(bu 4
1238 Something to negate, prefixed \f(CW"!"\fR: an existing character
1239 property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
1240 name) user\-defined character property,
1241 to represent all the characters in that property; two hexadecimal code
1242 points for a range; or a single hexadecimal code point.
1243 .IP \(bu 4
1244 Something to intersect with, prefixed by \f(CW"&"\fR: an existing character
1245 property (prefixed by \f(CW"utf8::"\fR) or a fully qualified (including package
1246 name) user\-defined character property,
1247 for all the characters except the characters in the property; two
1248 hexadecimal code points for a range; or a single hexadecimal code point.
1249 .PP
1250 For example, to define a property that covers both the Japanese
1251 syllabaries (hiragana and katakana), you can define
1252 .PP
1253 .Vb 6
1254 \& sub InKana {
1255 \& return <<END;
1256 \& 3040\et309F
1257 \& 30A0\et30FF
1258 \& END
1259 \& }
1260 .Ve
1261 .PP
1262 Imagine that the here\-doc end marker is at the beginning of the line.
1263 Now you can use \f(CW\*(C`\ep{InKana}\*(C'\fR and \f(CW\*(C`\eP{InKana}\*(C'\fR.
1264 .PP
1265 You could also have used the existing block property names:
1266 .PP
1267 .Vb 6
1268 \& sub InKana {
1269 \& return <<\*(AqEND\*(Aq;
1270 \& +utf8::InHiragana
1271 \& +utf8::InKatakana
1272 \& END
1273 \& }
1274 .Ve
1275 .PP
1276 Suppose you wanted to match only the allocated characters,
1277 not the raw block ranges: in other words, you want to remove
1278 the unassigned characters:
1279 .PP
1280 .Vb 7
1281 \& sub InKana {
1282 \& return <<\*(AqEND\*(Aq;
1283 \& +utf8::InHiragana
1284 \& +utf8::InKatakana
1285 \& \-utf8::IsCn
1286 \& END
1287 \& }
1288 .Ve
1289 .PP
1290 The negation is useful for defining (surprise!) negated classes.
1291 .PP
1292 .Vb 7
1293 \& sub InNotKana {
1294 \& return <<\*(AqEND\*(Aq;
1295 \& !utf8::InHiragana
1296 \& \-utf8::InKatakana
1297 \& +utf8::IsCn
1298 \& END
1299 \& }
1300 .Ve
1301 .PP
1302 This will match all non\-Unicode code points, since every one of them is
1303 not in Kana. You can use intersection to exclude these, if desired, as
1304 this modified example shows:
1305 .PP
1306 .Vb 8
1307 \& sub InNotKana {
1308 \& return <<\*(AqEND\*(Aq;
1309 \& !utf8::InHiragana
1310 \& \-utf8::InKatakana
1311 \& +utf8::IsCn
1312 \& &utf8::Any
1313 \& END
1314 \& }
1315 .Ve
1316 .PP
1317 \&\f(CW&utf8::Any\fR must be the last line in the definition.
1318 .PP
1319 Intersection is used generally for getting the common characters matched
1320 by two (or more) classes. It\*(Aqs important to remember not to use \f(CW"&"\fR for
1321 the first set; that would be intersecting with nothing, resulting in an
1322 empty set. (Similarly using \f(CW"\-"\fR for the first set does nothing).
1323 .PP
1324 Unlike non\-user\-defined \f(CW\*(C`\ep{}\*(C'\fR property matches, no warning is ever
1325 generated if these properties are matched against a non\-Unicode code
1326 point (see "Beyond Unicode code points" below).
1327 .SS "User\-Defined Case Mappings (for serious hackers only)"
1328 .IX Subsection "User-Defined Case Mappings (for serious hackers only)"
1329 \&\fBThis feature has been removed as of Perl 5.16.\fR
1330 The CPAN module \f(CW\*(C`Unicode::Casing\*(C'\fR provides better functionality without
1331 the drawbacks that this feature had. If you are using a Perl earlier
1332 than 5.16, this feature was most fully documented in the 5.14 version of
1333 this pod:
1334 <http://perldoc.perl.org/5.14.0/perlunicode.html#User\-Defined\-Case\-Mappings\-%28for\-serious\-hackers\-only%29>
1335 .SS "Character Encodings for Input and Output"
1336 .IX Subsection "Character Encodings for Input and Output"
1337 See Encode.
1338 .SS "Unicode Regular Expression Support Level"
1339 .IX Subsection "Unicode Regular Expression Support Level"
1340 The following list of Unicode supported features for regular expressions describes
1341 all features currently directly supported by core Perl. The references
1342 to "Level \fIN\fR" and the section numbers refer to
1343 UTS#18 "Unicode Regular Expressions" <https://www.unicode.org/reports/tr18>,
1344 version 18, October 2016.
1345 .PP
1346 \fILevel 1 \- Basic Unicode Support\fR
1347 .IX Subsection "Level 1 - Basic Unicode Support"
1348 .PP
1349 .Vb 8
1350 \& RL1.1 Hex Notation \- Done [1]
1351 \& RL1.2 Properties \- Done [2]
1352 \& RL1.2a Compatibility Properties \- Done [3]
1353 \& RL1.3 Subtraction and Intersection \- Done [4]
1354 \& RL1.4 Simple Word Boundaries \- Done [5]
1355 \& RL1.5 Simple Loose Matches \- Done [6]
1356 \& RL1.6 Line Boundaries \- Partial [7]
1357 \& RL1.7 Supplementary Code Points \- Done [8]
1358 .Ve
1359 .ie n .IP "[1] ""\eN{U+...}"" and ""\ex{...}""" 4
1360 .el .IP "[1] \f(CW\eN{U+...}\fR and \f(CW\ex{...}\fR" 4
1361 .IX Item "[1] N{U+...} and x{...}"
1362 .PD 0
1363 .ie n .IP "[2] ""\ep{...}"" ""\eP{...}"". This requirement is for a minimal list of properties. Perl supports these. See R2.7 for other properties." 4
1364 .el .IP "[2] \f(CW\ep{...}\fR \f(CW\eP{...}\fR. This requirement is for a minimal list of properties. Perl supports these. See R2.7 for other properties." 4
1365 .IX Item "[2] p{...} P{...}. This requirement is for a minimal list of properties. Perl supports these. See R2.7 for other properties."
1366 .IP [3] 4
1367 .IX Item "[3]"
1368 .PD
1369 Perl has \f(CW\*(C`\ed\*(C'\fR \f(CW\*(C`\eD\*(C'\fR \f(CW\*(C`\es\*(C'\fR \f(CW\*(C`\eS\*(C'\fR \f(CW\*(C`\ew\*(C'\fR \f(CW\*(C`\eW\*(C'\fR \f(CW\*(C`\eX\*(C'\fR \f(CW\*(C`[:\fR\f(CIprop\fR\f(CW:]\*(C'\fR
1370 \&\f(CW\*(C`[:^\fR\f(CIprop\fR\f(CW:]\*(C'\fR, plus all the properties specified by
1371 <https://www.unicode.org/reports/tr18/#Compatibility_Properties>. These
1372 are described above in "Other Properties"
1373 .IP [4] 4
1374 .IX Item "[4]"
1375 The regex sets feature \f(CW"(?[...])"\fR starting in v5.18 accomplishes
1376 this. See "(?[ ])" in perlre.
1377 .ie n .IP "[5] ""\eb"" ""\eB"" meet most, but not all, the details of this requirement, but ""\eb{wb}"" and ""\eB{wb}"" do, as well as the stricter R2.3." 4
1378 .el .IP "[5] \f(CW\eb\fR \f(CW\eB\fR meet most, but not all, the details of this requirement, but \f(CW\eb{wb}\fR and \f(CW\eB{wb}\fR do, as well as the stricter R2.3." 4
1379 .IX Item "[5] b B meet most, but not all, the details of this requirement, but b{wb} and B{wb} do, as well as the stricter R2.3."
1380 .PD 0
1381 .IP [6] 4
1382 .IX Item "[6]"
1383 .PD
1384 Note that Perl does Full case\-folding in matching, not Simple:
1385 .Sp
1386 For example \f(CW\*(C`U+1F88\*(C'\fR is equivalent to \f(CW\*(C`U+1F00 U+03B9\*(C'\fR, instead of just
1387 \&\f(CW\*(C`U+1F80\*(C'\fR. This difference matters mainly for certain Greek capital
1388 letters with certain modifiers: the Full case\-folding decomposes the
1389 letter, while the Simple case\-folding would map it to a single
1390 character.
1391 .IP [7] 4
1392 .IX Item "[7]"
1393 The reason this is considered to be only partially implemented is that
1394 Perl has \f(CW\*(C`qr/\eb{lb}/\*(C'\fR and
1395 \&\f(CW\*(C`Unicode::LineBreak\*(C'\fR that are conformant with
1396 UAX#14 "Unicode Line Breaking Algorithm" <https://www.unicode.org/reports/tr14>.
1397 The regular expression construct provides default behavior, while the
1398 heavier\-weight module provides customizable line breaking.
1399 .Sp
1400 But Perl treats \f(CW\*(C`\en\*(C'\fR as the start\- and end\-line
1401 delimiter, whereas Unicode specifies more characters that should be
1402 so\-interpreted.
1403 .Sp
1404 These are:
1405 .Sp
1406 .Vb 6
1407 \& VT U+000B (\ev in C)
1408 \& FF U+000C (\ef)
1409 \& CR U+000D (\er)
1410 \& NEL U+0085
1411 \& LS U+2028
1412 \& PS U+2029
1413 .Ve
1414 .Sp
1415 \&\f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR in regular expression patterns are supposed to match all
1416 these, but don\*(Aqt.
1417 These characters also don\*(Aqt, but should, affect \f(CW\*(C`<>\*(C'\fR \f(CW$.\fR, and
1418 script line numbers.
1419 .Sp
1420 Also, lines should not be split within \f(CW\*(C`CRLF\*(C'\fR (i.e. there is no
1421 empty line between \f(CW\*(C`\er\*(C'\fR and \f(CW\*(C`\en\*(C'\fR). For \f(CW\*(C`CRLF\*(C'\fR, try the \f(CW\*(C`:crlf\*(C'\fR
1422 layer (see PerlIO).
1423 .ie n .IP "[8] UTF\-8/UTF\-EBDDIC used in Perl allows not only ""U+10000"" to ""U+10FFFF"" but also beyond ""U+10FFFF""" 4
1424 .el .IP "[8] UTF\-8/UTF\-EBDDIC used in Perl allows not only \f(CWU+10000\fR to \f(CWU+10FFFF\fR but also beyond \f(CWU+10FFFF\fR" 4
1425 .IX Item "[8] UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to U+10FFFF but also beyond U+10FFFF"
1426 .PP
1427 \fILevel 2 \- Extended Unicode Support\fR
1428 .IX Subsection "Level 2 - Extended Unicode Support"
1429 .PP
1430 .Vb 10
1431 \& RL2.1 Canonical Equivalents \- Retracted [9]
1432 \& by Unicode
1433 \& RL2.2 Extended Grapheme Clusters and \- Partial [10]
1434 \& Character Classes with Strings
1435 \& RL2.3 Default Word Boundaries \- Done [11]
1436 \& RL2.4 Default Case Conversion \- Done
1437 \& RL2.5 Name Properties \- Done
1438 \& RL2.6 Wildcards in Property Values \- Partial [12]
1439 \& RL2.7 Full Properties \- Partial [13]
1440 \& RL2.8 Optional Properties \- Partial [14]
1441 .Ve
1442 .IP "[9] Unicode has rewritten this portion of UTS#18 to say that getting canonical equivalence (see UAX#15 ""Unicode Normalization Forms"" <https://www.unicode.org/reports/tr15>) is basically to be done at the programmer level. Use NFD to write both your regular expressions and text to match them against (you can use Unicode::Normalize)." 4
1443 .IX Item "[9] Unicode has rewritten this portion of UTS#18 to say that getting canonical equivalence (see UAX#15 ""Unicode Normalization Forms"" <https://www.unicode.org/reports/tr15>) is basically to be done at the programmer level. Use NFD to write both your regular expressions and text to match them against (you can use Unicode::Normalize)."
1444 .PD 0
1445 .ie n .IP "[10] Perl has ""\eX"" and ""\eb{gcb}"". Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support." 4
1446 .el .IP "[10] Perl has \f(CW\eX\fR and \f(CW\eb{gcb}\fR. Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support." 4
1447 .IX Item "[10] Perl has X and b{gcb}. Unicode has retracted their ""Grapheme Cluster Mode"", and recently added string properties, which Perl does not yet support."
1448 .IP "[11] see UAX#29 ""Unicode Text Segmentation"" <https://www.unicode.org/reports/tr29>," 4
1449 .IX Item "[11] see UAX#29 ""Unicode Text Segmentation"" <https://www.unicode.org/reports/tr29>,"
1450 .IP "[12] see ""Wildcards in Property Values"" above." 4
1451 .IX Item "[12] see ""Wildcards in Property Values"" above."
1452 .IP "[13] Perl supports all the properties in the Unicode Character Database (UCD). It does not yet support the listed properties that come from other Unicode sources." 4
1453 .IX Item "[13] Perl supports all the properties in the Unicode Character Database (UCD). It does not yet support the listed properties that come from other Unicode sources."
1454 .IP "[14] The only optional property that Perl supports is Named Sequence. None of these properties are in the UCD." 4
1455 .IX Item "[14] The only optional property that Perl supports is Named Sequence. None of these properties are in the UCD."
1456 .PD
1457 .PP
1458 \fILevel 3 \- Tailored Support\fR
1459 .IX Subsection "Level 3 - Tailored Support"
1460 .PP
1461 This has been retracted by Unicode.
1462 .SS "Unicode Encodings"
1463 .IX Subsection "Unicode Encodings"
1464 Unicode characters are assigned to \fIcode points\fR, which are abstract
1465 numbers. To use these numbers, various encodings are needed.
1466 .IP \(bu 4
1467 UTF\-8
1468 .Sp
1469 UTF\-8 is a variable\-length (1 to 4 bytes), byte\-order independent
1470 encoding. In most of Perl\*(Aqs documentation, including elsewhere in this
1471 document, the term "UTF\-8" means also "UTF\-EBCDIC". But in this section,
1472 "UTF\-8" refers only to the encoding used on ASCII platforms. It is a
1473 superset of 7\-bit US\-ASCII, so anything encoded in ASCII has the
1474 identical representation when encoded in UTF\-8.
1475 .Sp
1476 The following table is from Unicode 3.2.
1477 .Sp
1478 .Vb 1
1479 \& Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
1480 \&
1481 \& U+0000..U+007F 00..7F
1482 \& U+0080..U+07FF * C2..DF 80..BF
1483 \& U+0800..U+0FFF E0 * A0..BF 80..BF
1484 \& U+1000..U+CFFF E1..EC 80..BF 80..BF
1485 \& U+D000..U+D7FF ED 80..9F 80..BF
1486 \& U+D800..U+DFFF +++++ utf16 surrogates, not legal utf8 +++++
1487 \& U+E000..U+FFFF EE..EF 80..BF 80..BF
1488 \& U+10000..U+3FFFF F0 * 90..BF 80..BF 80..BF
1489 \& U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF
1490 \& U+100000..U+10FFFF F4 80..8F 80..BF 80..BF
1491 .Ve
1492 .Sp
1493 Note the gaps marked by "*" before several of the byte entries above. These are
1494 caused by legal UTF\-8 avoiding non\-shortest encodings: it is technically
1495 possible to UTF\-8\-encode a single code point in different ways, but that is
1496 explicitly forbidden, and the shortest possible encoding should always be used
1497 (and that is what Perl does).
1498 .Sp
1499 Another way to look at it is via bits:
1500 .Sp
1501 .Vb 1
1502 \& Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
1503 \&
1504 \& 0aaaaaaa 0aaaaaaa
1505 \& 00000bbbbbaaaaaa 110bbbbb 10aaaaaa
1506 \& ccccbbbbbbaaaaaa 1110cccc 10bbbbbb 10aaaaaa
1507 \& 00000dddccccccbbbbbbaaaaaa 11110ddd 10cccccc 10bbbbbb 10aaaaaa
1508 .Ve
1509 .Sp
1510 As you can see, the continuation bytes all begin with \f(CW"10"\fR, and the
1511 leading bits of the start byte tell how many bytes there are in the
1512 encoded character.
1513 .Sp
1514 The original UTF\-8 specification allowed up to 6 bytes, to allow
1515 encoding of numbers up to \f(CW\*(C`0x7FFF_FFFF\*(C'\fR. Perl continues to allow those,
1516 and has extended that up to 13 bytes to encode code points up to what
1517 can fit in a 64\-bit word. However, Perl will warn if you output any of
1518 these as being non\-portable; and under strict UTF\-8 input protocols,
1519 they are forbidden. In addition, it is now illegal to use a code point
1520 larger than what a signed integer variable on your system can hold. On
1521 32\-bit ASCII systems, this means \f(CW\*(C`0x7FFF_FFFF\*(C'\fR is the legal maximum
1522 (much higher on 64\-bit systems).
1523 .IP \(bu 4
1524 UTF\-EBCDIC
1525 .Sp
1526 Like UTF\-8, but EBCDIC\-safe, in the way that UTF\-8 is ASCII\-safe.
1527 This means that all the basic characters (which includes all
1528 those that have ASCII equivalents (like \f(CW"A"\fR, \f(CW"0"\fR, \f(CW"%"\fR, \fIetc.\fR)
1529 are the same in both EBCDIC and UTF\-EBCDIC.)
1530 .Sp
1531 UTF\-EBCDIC is used on EBCDIC platforms. It generally requires more
1532 bytes to represent a given code point than UTF\-8 does; the largest
1533 Unicode code points take 5 bytes to represent (instead of 4 in UTF\-8),
1534 and, extended for 64\-bit words, it uses 14 bytes instead of 13 bytes in
1535 UTF\-8.
1536 .IP \(bu 4
1537 UTF\-16, UTF\-16BE, UTF\-16LE, Surrogates, and \f(CW\*(C`BOM\*(C'\fR\*(Aqs (Byte Order Marks)
1538 .Sp
1539 The following items are mostly for reference and general Unicode
1540 knowledge, Perl doesn\*(Aqt use these constructs internally.
1541 .Sp
1542 Like UTF\-8, UTF\-16 is a variable\-width encoding, but where
1543 UTF\-8 uses 8\-bit code units, UTF\-16 uses 16\-bit code units.
1544 All code points occupy either 2 or 4 bytes in UTF\-16: code points
1545 \&\f(CW\*(C`U+0000..U+FFFF\*(C'\fR are stored in a single 16\-bit unit, and code
1546 points \f(CW\*(C`U+10000..U+10FFFF\*(C'\fR in two 16\-bit units. The latter case is
1547 using \fIsurrogates\fR, the first 16\-bit unit being the \fIhigh
1548 surrogate\fR, and the second being the \fIlow surrogate\fR.
1549 .Sp
1550 Surrogates are code points set aside to encode the \f(CW\*(C`U+10000..U+10FFFF\*(C'\fR
1551 range of Unicode code points in pairs of 16\-bit units. The \fIhigh
1552 surrogates\fR are the range \f(CW\*(C`U+D800..U+DBFF\*(C'\fR and the \fIlow surrogates\fR
1553 are the range \f(CW\*(C`U+DC00..U+DFFF\*(C'\fR. The surrogate encoding is
1554 .Sp
1555 .Vb 2
1556 \& $hi = ($uni \- 0x10000) / 0x400 + 0xD800;
1557 \& $lo = ($uni \- 0x10000) % 0x400 + 0xDC00;
1558 .Ve
1559 .Sp
1560 and the decoding is
1561 .Sp
1562 .Vb 1
1563 \& $uni = 0x10000 + ($hi \- 0xD800) * 0x400 + ($lo \- 0xDC00);
1564 .Ve
1565 .Sp
1566 Because of the 16\-bitness, UTF\-16 is byte\-order dependent. UTF\-16
1567 itself can be used for in\-memory computations, but if storage or
1568 transfer is required either UTF\-16BE (big\-endian) or UTF\-16LE
1569 (little\-endian) encodings must be chosen.
1570 .Sp
1571 This introduces another problem: what if you just know that your data
1572 is UTF\-16, but you don\*(Aqt know which endianness? Byte Order Marks, or
1573 \&\f(CW\*(C`BOM\*(C'\fR\*(Aqs, are a solution to this. A special character has been reserved
1574 in Unicode to function as a byte order marker: the character with the
1575 code point \f(CW\*(C`U+FEFF\*(C'\fR is the \f(CW\*(C`BOM\*(C'\fR.
1576 .Sp
1577 The trick is that if you read a \f(CW\*(C`BOM\*(C'\fR, you will know the byte order,
1578 since if it was written on a big\-endian platform, you will read the
1579 bytes \f(CW\*(C`0xFE 0xFF\*(C'\fR, but if it was written on a little\-endian platform,
1580 you will read the bytes \f(CW\*(C`0xFF 0xFE\*(C'\fR. (And if the originating platform
1581 was writing in ASCII platform UTF\-8, you will read the bytes
1582 \&\f(CW\*(C`0xEF 0xBB 0xBF\*(C'\fR.)
1583 .Sp
1584 The way this trick works is that the character with the code point
1585 \&\f(CW\*(C`U+FFFE\*(C'\fR is not supposed to be in input streams, so the
1586 sequence of bytes \f(CW\*(C`0xFF 0xFE\*(C'\fR is unambiguously "\f(CW\*(C`BOM\*(C'\fR, represented in
1587 little\-endian format" and cannot be \f(CW\*(C`U+FFFE\*(C'\fR, represented in big\-endian
1588 format".
1589 .Sp
1590 Surrogates have no meaning in Unicode outside their use in pairs to
1591 represent other code points. However, Perl allows them to be
1592 represented individually internally, for example by saying
1593 \&\f(CWchr(0xD801)\fR, so that all code points, not just those valid for open
1594 interchange, are
1595 representable. Unicode does define semantics for them, such as their
1596 \&\f(CW"General_Category"\fR is \f(CW"Cs"\fR. But because their use is somewhat dangerous,
1597 Perl will warn (using the warning category \f(CW"surrogate"\fR, which is a
1598 sub\-category of \f(CW"utf8"\fR) if an attempt is made
1599 to do things like take the lower case of one, or match
1600 case\-insensitively, or to output them. (But don\*(Aqt try this on Perls
1601 before 5.14.)
1602 .IP \(bu 4
1603 UTF\-32, UTF\-32BE, UTF\-32LE
1604 .Sp
1605 The UTF\-32 family is pretty much like the UTF\-16 family, except that
1606 the units are 32\-bit, and therefore the surrogate scheme is not
1607 needed. UTF\-32 is a fixed\-width encoding. The \f(CW\*(C`BOM\*(C'\fR signatures are
1608 \&\f(CW\*(C`0x00 0x00 0xFE 0xFF\*(C'\fR for BE and \f(CW\*(C`0xFF 0xFE 0x00 0x00\*(C'\fR for LE.
1609 .IP \(bu 4
1610 UCS\-2, UCS\-4
1611 .Sp
1612 Legacy, fixed\-width encodings defined by the ISO 10646 standard. UCS\-2 is a 16\-bit
1613 encoding. Unlike UTF\-16, UCS\-2 is not extensible beyond \f(CW\*(C`U+FFFF\*(C'\fR,
1614 because it does not use surrogates. UCS\-4 is a 32\-bit encoding,
1615 functionally identical to UTF\-32 (the difference being that
1616 UCS\-4 forbids neither surrogates nor code points larger than \f(CW\*(C`0x10_FFFF\*(C'\fR).
1617 .IP \(bu 4
1618 UTF\-7
1619 .Sp
1620 A seven\-bit safe (non\-eight\-bit) encoding, which is useful if the
1621 transport or storage is not eight\-bit safe. Defined by RFC 2152.
1622 .SS "Noncharacter code points"
1623 .IX Subsection "Noncharacter code points"
1624 66 code points are set aside in Unicode as "noncharacter code points".
1625 These all have the \f(CW\*(C`Unassigned\*(C'\fR (\f(CW\*(C`Cn\*(C'\fR) \f(CW"General_Category"\fR, and
1626 no character will ever be assigned to any of them. They are the 32 code
1627 points between \f(CW\*(C`U+FDD0\*(C'\fR and \f(CW\*(C`U+FDEF\*(C'\fR inclusive, and the 34 code
1628 points:
1629 .PP
1630 .Vb 7
1631 \& U+FFFE U+FFFF
1632 \& U+1FFFE U+1FFFF
1633 \& U+2FFFE U+2FFFF
1634 \& ...
1635 \& U+EFFFE U+EFFFF
1636 \& U+FFFFE U+FFFFF
1637 \& U+10FFFE U+10FFFF
1638 .Ve
1639 .PP
1640 Until Unicode 7.0, the noncharacters were "\fBforbidden\fR for use in open
1641 interchange of Unicode text data", so that code that processed those
1642 streams could use these code points as sentinels that could be mixed in
1643 with character data, and would always be distinguishable from that data.
1644 (Emphasis above and in the next paragraph are added in this document.)
1645 .PP
1646 Unicode 7.0 changed the wording so that they are "\fBnot recommended\fR for
1647 use in open interchange of Unicode text data". The 7.0 Standard goes on
1648 to say:
1649 .Sp
1650 .RS 4
1651 "If a noncharacter is received in open interchange, an application is
1652 not required to interpret it in any way. It is good practice, however,
1653 to recognize it as a noncharacter and to take appropriate action, such
1654 as replacing it with \f(CW\*(C`U+FFFD\*(C'\fR replacement character, to indicate the
1655 problem in the text. It is not recommended to simply delete
1656 noncharacter code points from such text, because of the potential
1657 security issues caused by deleting uninterpreted characters. (See
1658 conformance clause C7 in Section 3.2, Conformance Requirements, and
1659 Unicode Technical Report #36, "Unicode Security
1660 Considerations" <https://www.unicode.org/reports/tr36/#Substituting_for_Ill_Formed_Subsequences>)."
1661 .RE
1662 .PP
1663 This change was made because it was found that various commercial tools
1664 like editors, or for things like source code control, had been written
1665 so that they would not handle program files that used these code points,
1666 effectively precluding their use almost entirely! And that was never
1667 the intent. They\*(Aqve always been meant to be usable within an
1668 application, or cooperating set of applications, at will.
1669 .PP
1670 If you\*(Aqre writing code, such as an editor, that is supposed to be able
1671 to handle any Unicode text data, then you shouldn\*(Aqt be using these code
1672 points yourself, and instead allow them in the input. If you need
1673 sentinels, they should instead be something that isn\*(Aqt legal Unicode.
1674 For UTF\-8 data, you can use the bytes 0xC0 and 0xC1 as sentinels, as
1675 they never appear in well\-formed UTF\-8. (There are equivalents for
1676 UTF\-EBCDIC). You can also store your Unicode code points in integer
1677 variables and use negative values as sentinels.
1678 .PP
1679 If you\*(Aqre not writing such a tool, then whether you accept noncharacters
1680 as input is up to you (though the Standard recommends that you not). If
1681 you do strict input stream checking with Perl, these code points
1682 continue to be forbidden. This is to maintain backward compatibility
1683 (otherwise potential security holes could open up, as an unsuspecting
1684 application that was written assuming the noncharacters would be
1685 filtered out before getting to it, could now, without warning, start
1686 getting them). To do strict checking, you can use the layer
1687 \&\f(CW:encoding(\*(AqUTF\-8\*(Aq)\fR.
1688 .PP
1689 Perl continues to warn (using the warning category \f(CW"nonchar"\fR, which
1690 is a sub\-category of \f(CW"utf8"\fR) if an attempt is made to output
1691 noncharacters.
1692 .SS "Beyond Unicode code points"
1693 .IX Subsection "Beyond Unicode code points"
1694 The maximum Unicode code point is \f(CW\*(C`U+10FFFF\*(C'\fR, and Unicode only defines
1695 operations on code points up through that. But Perl works on code
1696 points up to the maximum permissible signed number available on the
1697 platform. However, Perl will not accept these from input streams unless
1698 lax rules are being used, and will warn (using the warning category
1699 \&\f(CW"non_unicode"\fR, which is a sub\-category of \f(CW"utf8"\fR) if any are output.
1700 .PP
1701 Since Unicode rules are not defined on these code points, if a
1702 Unicode\-defined operation is done on them, Perl uses what we believe are
1703 sensible rules, while generally warning, using the \f(CW"non_unicode"\fR
1704 category. For example, \f(CWuc("\ex{11_0000}")\fR will generate such a
1705 warning, returning the input parameter as its result, since Perl defines
1706 the uppercase of every non\-Unicode code point to be the code point
1707 itself. (All the case changing operations, not just uppercasing, work
1708 this way.)
1709 .PP
1710 The situation with matching Unicode properties in regular expressions,
1711 the \f(CW\*(C`\ep{}\*(C'\fR and \f(CW\*(C`\eP{}\*(C'\fR constructs, against these code points is not as
1712 clear cut, and how these are handled has changed as we\*(Aqve gained
1713 experience.
1714 .PP
1715 One possibility is to treat any match against these code points as
1716 undefined. But since Perl doesn\*(Aqt have the concept of a match being
1717 undefined, it converts this to failing or \f(CW\*(C`FALSE\*(C'\fR. This is almost, but
1718 not quite, what Perl did from v5.14 (when use of these code points
1719 became generally reliable) through v5.18. The difference is that Perl
1720 treated all \f(CW\*(C`\ep{}\*(C'\fR matches as failing, but all \f(CW\*(C`\eP{}\*(C'\fR matches as
1721 succeeding.
1722 .PP
1723 One problem with this is that it leads to unexpected, and confusing
1724 results in some cases:
1725 .PP
1726 .Vb 2
1727 \& chr(0x110000) =~ \ep{ASCII_Hex_Digit=True} # Failed on <= v5.18
1728 \& chr(0x110000) =~ \ep{ASCII_Hex_Digit=False} # Failed! on <= v5.18
1729 .Ve
1730 .PP
1731 That is, it treated both matches as undefined, and converted that to
1732 false (raising a warning on each). The first case is the expected
1733 result, but the second is likely counterintuitive: "How could both be
1734 false when they are complements?" Another problem was that the
1735 implementation optimized many Unicode property matches down to already
1736 existing simpler, faster operations, which don\*(Aqt raise the warning. We
1737 chose to not forgo those optimizations, which help the vast majority of
1738 matches, just to generate a warning for the unlikely event that an
1739 above\-Unicode code point is being matched against.
1740 .PP
1741 As a result of these problems, starting in v5.20, what Perl does is
1742 to treat non\-Unicode code points as just typical unassigned Unicode
1743 characters, and matches accordingly. (Note: Unicode has atypical
1744 unassigned code points. For example, it has noncharacter code points,
1745 and ones that, when they do get assigned, are destined to be written
1746 Right\-to\-left, as Arabic and Hebrew are. Perl assumes that no
1747 non\-Unicode code point has any atypical properties.)
1748 .PP
1749 Perl, in most cases, will raise a warning when matching an above\-Unicode
1750 code point against a Unicode property when the result is \f(CW\*(C`TRUE\*(C'\fR for
1751 \&\f(CW\*(C`\ep{}\*(C'\fR, and \f(CW\*(C`FALSE\*(C'\fR for \f(CW\*(C`\eP{}\*(C'\fR. For example:
1752 .PP
1753 .Vb 2
1754 \& chr(0x110000) =~ \ep{ASCII_Hex_Digit=True} # Fails, no warning
1755 \& chr(0x110000) =~ \ep{ASCII_Hex_Digit=False} # Succeeds, with warning
1756 .Ve
1757 .PP
1758 In both these examples, the character being matched is non\-Unicode, so
1759 Unicode doesn\*(Aqt define how it should match. It clearly isn\*(Aqt an ASCII
1760 hex digit, so the first example clearly should fail, and so it does,
1761 with no warning. But it is arguable that the second example should have
1762 an undefined, hence \f(CW\*(C`FALSE\*(C'\fR, result. So a warning is raised for it.
1763 .PP
1764 Thus the warning is raised for many fewer cases than in earlier Perls,
1765 and only when what the result is could be arguable. It turns out that
1766 none of the optimizations made by Perl (or are ever likely to be made)
1767 cause the warning to be skipped, so it solves both problems of Perl\*(Aqs
1768 earlier approach. The most commonly used property that is affected by
1769 this change is \f(CW\*(C`\ep{Unassigned}\*(C'\fR which is a short form for
1770 \&\f(CW\*(C`\ep{General_Category=Unassigned}\*(C'\fR. Starting in v5.20, all non\-Unicode
1771 code points are considered \f(CW\*(C`Unassigned\*(C'\fR. In earlier releases the
1772 matches failed because the result was considered undefined.
1773 .PP
1774 The only place where the warning is not raised when it might ought to
1775 have been is if optimizations cause the whole pattern match to not even
1776 be attempted. For example, Perl may figure out that for a string to
1777 match a certain regular expression pattern, the string has to contain
1778 the substring \f(CW"foobar"\fR. Before attempting the match, Perl may look
1779 for that substring, and if not found, immediately fail the match without
1780 actually trying it; so no warning gets generated even if the string
1781 contains an above\-Unicode code point.
1782 .PP
1783 This behavior is more "Do what I mean" than in earlier Perls for most
1784 applications. But it catches fewer issues for code that needs to be
1785 strictly Unicode compliant. Therefore there is an additional mode of
1786 operation available to accommodate such code. This mode is enabled if a
1787 regular expression pattern is compiled within the lexical scope where
1788 the \f(CW"non_unicode"\fR warning class has been made fatal, say by:
1789 .PP
1790 .Vb 1
1791 \& use warnings FATAL => "non_unicode"
1792 .Ve
1793 .PP
1794 (see warnings). In this mode of operation, Perl will raise the
1795 warning for all matches against a non\-Unicode code point (not just the
1796 arguable ones), and it skips the optimizations that might cause the
1797 warning to not be output. (It currently still won\*(Aqt warn if the match
1798 isn\*(Aqt even attempted, like in the \f(CW"foobar"\fR example above.)
1799 .PP
1800 In summary, Perl now normally treats non\-Unicode code points as typical
1801 Unicode unassigned code points for regular expression matches, raising a
1802 warning only when it is arguable what the result should be. However, if
1803 this warning has been made fatal, it isn\*(Aqt skipped.
1804 .PP
1805 There is one exception to all this. \f(CW\*(C`\ep{All}\*(C'\fR looks like a Unicode
1806 property, but it is a Perl extension that is defined to be true for all
1807 possible code points, Unicode or not, so no warning is ever generated
1808 when matching this against a non\-Unicode code point. (Prior to v5.20,
1809 it was an exact synonym for \f(CW\*(C`\ep{Any}\*(C'\fR, matching code points \f(CW0\fR
1810 through \f(CW0x10FFFF\fR.)
1811 .SS "Security Implications of Unicode"
1812 .IX Subsection "Security Implications of Unicode"
1813 First, read
1814 Unicode Security Considerations <https://www.unicode.org/reports/tr36>.
1815 .PP
1816 Also, note the following:
1817 .IP \(bu 4
1818 Malformed UTF\-8
1819 .Sp
1820 UTF\-8 is very structured, so many combinations of bytes are invalid. In
1821 the past, Perl tried to soldier on and make some sense of invalid
1822 combinations, but this can lead to security holes, so now, if the Perl
1823 core needs to process an invalid combination, it will either raise a
1824 fatal error, or will replace those bytes by the sequence that forms the
1825 Unicode REPLACEMENT CHARACTER, for which purpose Unicode created it.
1826 .Sp
1827 Every code point can be represented by more than one possible
1828 syntactically valid UTF\-8 sequence. Early on, both Unicode and Perl
1829 considered any of these to be valid, but now, all sequences longer
1830 than the shortest possible one are considered to be malformed.
1831 .Sp
1832 Unicode considers many code points to be illegal, or to be avoided.
1833 Perl generally accepts them, once they have passed through any input
1834 filters that may try to exclude them. These have been discussed above
1835 (see "Surrogates" under UTF\-16 in "Unicode Encodings",
1836 "Noncharacter code points", and "Beyond Unicode code points").
1837 .IP \(bu 4
1838 Regular expression pattern matching may surprise you if you\*(Aqre not
1839 accustomed to Unicode. Starting in Perl 5.14, several pattern
1840 modifiers are available to control this, called the character set
1841 modifiers. Details are given in "Character set modifiers" in perlre.
1842 .PP
1843 As discussed elsewhere, Perl has one foot (two hooves?) planted in
1844 each of two worlds: the old world of ASCII and single\-byte locales, and
1845 the new world of Unicode, upgrading when necessary.
1846 If your legacy code does not explicitly use Unicode, no automatic
1847 switch\-over to Unicode should happen.
1848 .SS "Unicode in Perl on EBCDIC"
1849 .IX Subsection "Unicode in Perl on EBCDIC"
1850 Unicode is supported on EBCDIC platforms. See perlebcdic.
1851 .PP
1852 Unless ASCII vs. EBCDIC issues are specifically being discussed,
1853 references to UTF\-8 encoding in this document and elsewhere should be
1854 read as meaning UTF\-EBCDIC on EBCDIC platforms.
1855 See "Unicode and UTF" in perlebcdic.
1856 .PP
1857 Because UTF\-EBCDIC is so similar to UTF\-8, the differences are mostly
1858 hidden from you; \f(CW\*(C`use\ utf8\*(C'\fR (and NOT something like
1859 \&\f(CW\*(C`use\ utfebcdic\*(C'\fR) declares the script is in the platform\*(Aqs
1860 "native" 8\-bit encoding of Unicode. (Similarly for the \f(CW":utf8"\fR
1861 layer.)
1862 .SS Locales
1863 .IX Subsection "Locales"
1864 See "Unicode and UTF\-8" in perllocale
1865 .SS "When Unicode Does Not Happen"
1866 .IX Subsection "When Unicode Does Not Happen"
1867 There are still many places where Unicode (in some encoding or
1868 another) could be given as arguments or received as results, or both in
1869 Perl, but it is not, in spite of Perl having extensive ways to input and
1870 output in Unicode, and a few other "entry points" like the \f(CW@ARGV\fR
1871 array (which can sometimes be interpreted as UTF\-8).
1872 .PP
1873 The following are such interfaces. Also, see "The "Unicode Bug"".
1874 For all of these interfaces Perl
1875 currently (as of v5.16.0) simply assumes byte strings both as arguments
1876 and results, or UTF\-8 strings if the (deprecated) \f(CW\*(C`encoding\*(C'\fR pragma has been used.
1877 .PP
1878 One reason that Perl does not attempt to resolve the role of Unicode in
1879 these situations is that the answers are highly dependent on the operating
1880 system and the file system(s). For example, whether filenames can be
1881 in Unicode and in exactly what kind of encoding, is not exactly a
1882 portable concept. Similarly for \f(CW\*(C`qx\*(C'\fR and \f(CW\*(C`system\*(C'\fR: how well will the
1883 "command\-line interface" (and which of them?) handle Unicode?
1884 .IP \(bu 4
1885 \&\f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR,
1886 \&\f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`\-X\*(C'\fR
1887 .IP \(bu 4
1888 \&\f(CW%ENV\fR
1889 .IP \(bu 4
1890 \&\f(CW\*(C`glob\*(C'\fR (aka the \f(CW\*(C`<*>\*(C'\fR)
1891 .IP \(bu 4
1892 \&\f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR
1893 .IP \(bu 4
1894 \&\f(CW\*(C`qx\*(C'\fR (aka the backtick operator), \f(CW\*(C`system\*(C'\fR
1895 .IP \(bu 4
1896 \&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR
1897 .SS "The ""Unicode Bug"""
1898 .IX Subsection "The ""Unicode Bug"""
1899 The term, "Unicode bug" has been applied to an inconsistency with the
1900 code points in the \f(CW\*(C`Latin\-1 Supplement\*(C'\fR block, that is, between
1901 128 and 255. Without a locale specified, unlike all other characters or
1902 code points, these characters can have very different semantics
1903 depending on the rules in effect. (Characters whose code points are
1904 above 255 force Unicode rules; whereas the rules for ASCII characters
1905 are the same under both ASCII and Unicode rules.)
1906 .PP
1907 Under Unicode rules, these upper\-Latin1 characters are interpreted as
1908 Unicode code points, which means they have the same semantics as Latin\-1
1909 (ISO\-8859\-1) and C1 controls.
1910 .PP
1911 As explained in "ASCII Rules versus Unicode Rules", under ASCII rules,
1912 they are considered to be unassigned characters.
1913 .PP
1914 This can lead to unexpected results. For example, a string\*(Aqs
1915 semantics can suddenly change if a code point above 255 is appended to
1916 it, which changes the rules from ASCII to Unicode. As an
1917 example, consider the following program and its output:
1918 .PP
1919 .Vb 11
1920 \& $ perl \-le\*(Aq
1921 \& no feature "unicode_strings";
1922 \& $s1 = "\exC2";
1923 \& $s2 = "\ex{2660}";
1924 \& for ($s1, $s2, $s1.$s2) {
1925 \& print /\ew/ || 0;
1926 \& }
1927 \& \*(Aq
1928 \& 0
1929 \& 0
1930 \& 1
1931 .Ve
1932 .PP
1933 If there\*(Aqs no \f(CW\*(C`\ew\*(C'\fR in \f(CW\*(C`s1\*(C'\fR nor in \f(CW\*(C`s2\*(C'\fR, why does their concatenation
1934 have one?
1935 .PP
1936 This anomaly stems from Perl\*(Aqs attempt to not disturb older programs that
1937 didn\*(Aqt use Unicode, along with Perl\*(Aqs desire to add Unicode support
1938 seamlessly. But the result turned out to not be seamless. (By the way,
1939 you can choose to be warned when things like this happen. See
1940 \&\f(CW\*(C`encoding::warnings\*(C'\fR.)
1941 .PP
1942 \&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR
1943 was added, starting in Perl v5.12, to address this problem. It affects
1944 these things:
1945 .IP \(bu 4
1946 Changing the case of a scalar, that is, using \f(CWuc()\fR, \f(CWucfirst()\fR, \f(CWlc()\fR,
1947 and \f(CWlcfirst()\fR, or \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR and \f(CW\*(C`\el\*(C'\fR in double\-quotish
1948 contexts, such as regular expression substitutions.
1949 .Sp
1950 Under \f(CW\*(C`unicode_strings\*(C'\fR starting in Perl 5.12.0, Unicode rules are
1951 generally used. See "lc" in perlfunc for details on how this works
1952 in combination with various other pragmas.
1953 .IP \(bu 4
1954 Using caseless (\f(CW\*(C`/i\*(C'\fR) regular expression matching.
1955 .Sp
1956 Starting in Perl 5.14.0, regular expressions compiled within
1957 the scope of \f(CW\*(C`unicode_strings\*(C'\fR use Unicode rules
1958 even when executed or compiled into larger
1959 regular expressions outside the scope.
1960 .IP \(bu 4
1961 Matching any of several properties in regular expressions.
1962 .Sp
1963 These properties are \f(CW\*(C`\eb\*(C'\fR (without braces), \f(CW\*(C`\eB\*(C'\fR (without braces),
1964 \&\f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\eS\*(C'\fR, \f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`\eW\*(C'\fR, and all the Posix character classes
1965 \&\fIexcept\fR \f(CW\*(C`[[:ascii:]]\*(C'\fR.
1966 .Sp
1967 Starting in Perl 5.14.0, regular expressions compiled within
1968 the scope of \f(CW\*(C`unicode_strings\*(C'\fR use Unicode rules
1969 even when executed or compiled into larger
1970 regular expressions outside the scope.
1971 .IP \(bu 4
1972 In \f(CW\*(C`quotemeta\*(C'\fR or its inline equivalent \f(CW\*(C`\eQ\*(C'\fR.
1973 .Sp
1974 Starting in Perl 5.16.0, consistent quoting rules are used within the
1975 scope of \f(CW\*(C`unicode_strings\*(C'\fR, as described in "quotemeta" in perlfunc.
1976 Prior to that, or outside its scope, no code points above 127 are quoted
1977 in UTF\-8 encoded strings, but in byte encoded strings, code points
1978 between 128\-255 are always quoted.
1979 .IP \(bu 4
1980 In the \f(CW\*(C`..\*(C'\fR or range operator.
1981 .Sp
1982 Starting in Perl 5.26.0, the range operator on strings treats their lengths
1983 consistently within the scope of \f(CW\*(C`unicode_strings\*(C'\fR. Prior to that, or
1984 outside its scope, it could produce strings whose length in characters
1985 exceeded that of the right\-hand side, where the right\-hand side took up more
1986 bytes than the correct range endpoint.
1987 .IP \(bu 4
1988 In \f(CW\*(C`split\*(C'\fR\*(Aqs special\-case whitespace splitting.
1989 .Sp
1990 Starting in Perl 5.28.0, the \f(CW\*(C`split\*(C'\fR function with a pattern specified as
1991 a string containing a single space handles whitespace characters consistently
1992 within the scope of \f(CW\*(C`unicode_strings\*(C'\fR. Prior to that, or outside its scope,
1993 characters that are whitespace according to Unicode rules but not according to
1994 ASCII rules were treated as field contents rather than field separators when
1995 they appear in byte\-encoded strings.
1996 .PP
1997 You can see from the above that the effect of \f(CW\*(C`unicode_strings\*(C'\fR
1998 increased over several Perl releases. (And Perl\*(Aqs support for Unicode
1999 continues to improve; it\*(Aqs best to use the latest available release in
2000 order to get the most complete and accurate results possible.) Note that
2001 \&\f(CW\*(C`unicode_strings\*(C'\fR is automatically chosen if you \f(CW\*(C`use\ v5.12\*(C'\fR or
2002 higher.
2003 .PP
2004 For Perls earlier than those described above, or when a string is passed
2005 to a function outside the scope of \f(CW\*(C`unicode_strings\*(C'\fR, see the next section.
2006 .SS "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)"
2007 .IX Subsection "Forcing Unicode in Perl (Or Unforcing Unicode in Perl)"
2008 Sometimes (see "When Unicode Does Not Happen" or "The "Unicode Bug"")
2009 there are situations where you simply need to force a byte
2010 string into UTF\-8, or vice versa. The standard module Encode can be
2011 used for this, or the low\-level calls
2012 \&\f(CWutf8::upgrade($bytestring)\fR and
2013 \&\f(CW\*(C`utf8::downgrade($utf8string[, FAIL_OK])\*(C'\fR.
2014 .PP
2015 Note that \f(CWutf8::downgrade()\fR can fail if the string contains characters
2016 that don\*(Aqt fit into a byte.
2017 .PP
2018 Calling either function on a string that already is in the desired state is a
2019 no\-op.
2020 .PP
2021 "ASCII Rules versus Unicode Rules" gives all the ways that a string is
2022 made to use Unicode rules.
2023 .SS "Using Unicode in XS"
2024 .IX Subsection "Using Unicode in XS"
2025 See "Unicode Support" in perlguts for an introduction to Unicode at
2026 the XS level, and "Unicode Support" in perlapi for the API details.
2027 .SS "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)"
2028 .IX Subsection "Hacking Perl to work on earlier Unicode versions (for very serious hackers only)"
2029 Perl by default comes with the latest supported Unicode version built\-in, but
2030 the goal is to allow you to change to use any earlier one. In Perls
2031 v5.20 and v5.22, however, the earliest usable version is Unicode 5.1.
2032 Perl v5.18 and v5.24 are able to handle all earlier versions.
2033 .PP
2034 Download the files in the desired version of Unicode from the Unicode web
2035 site <https://www.unicode.org>). These should replace the existing files in
2036 \&\fIlib/unicore\fR in the Perl source tree. Follow the instructions in
2037 \&\fIREADME.perl\fR in that directory to change some of their names, and then build
2038 perl (see \fIINSTALL\fR).
2039 .SS "Porting code from perl\-5.6.X"
2040 .IX Subsection "Porting code from perl-5.6.X"
2041 Perls starting in 5.8 have a different Unicode model from 5.6. In 5.6 the
2042 programmer was required to use the \f(CW\*(C`utf8\*(C'\fR pragma to declare that a
2043 given scope expected to deal with Unicode data and had to make sure that
2044 only Unicode data were reaching that scope. If you have code that is
2045 working with 5.6, you will need some of the following adjustments to
2046 your code. The examples are written such that the code will continue to
2047 work under 5.6, so you should be safe to try them out.
2048 .IP \(bu 3
2049 A filehandle that should read or write UTF\-8
2050 .Sp
2051 .Vb 3
2052 \& if ($] > 5.008) {
2053 \& binmode $fh, ":encoding(UTF\-8)";
2054 \& }
2055 .Ve
2056 .IP \(bu 3
2057 A scalar that is going to be passed to some extension
2058 .Sp
2059 Be it \f(CW\*(C`Compress::Zlib\*(C'\fR, \f(CW\*(C`Apache::Request\*(C'\fR or any extension that has no
2060 mention of Unicode in the manpage, you need to make sure that the
2061 UTF8 flag is stripped off. Note that at the time of this writing
2062 (January 2012) the mentioned modules are not UTF\-8\-aware. Please
2063 check the documentation to verify if this is still true.
2064 .Sp
2065 .Vb 4
2066 \& if ($] > 5.008) {
2067 \& require Encode;
2068 \& $val = Encode::encode("UTF\-8", $val); # make octets
2069 \& }
2070 .Ve
2071 .IP \(bu 3
2072 A scalar we got back from an extension
2073 .Sp
2074 If you believe the scalar comes back as UTF\-8, you will most likely
2075 want the UTF8 flag restored:
2076 .Sp
2077 .Vb 4
2078 \& if ($] > 5.008) {
2079 \& require Encode;
2080 \& $val = Encode::decode("UTF\-8", $val);
2081 \& }
2082 .Ve
2083 .IP \(bu 3
2084 Same thing, if you are really sure it is UTF\-8
2085 .Sp
2086 .Vb 4
2087 \& if ($] > 5.008) {
2088 \& require Encode;
2089 \& Encode::_utf8_on($val);
2090 \& }
2091 .Ve
2092 .IP \(bu 3
2093 A wrapper for DBI \f(CW\*(C`fetchrow_array\*(C'\fR and \f(CW\*(C`fetchrow_hashref\*(C'\fR
2094 .Sp
2095 When the database contains only UTF\-8, a wrapper function or method is
2096 a convenient way to replace all your \f(CW\*(C`fetchrow_array\*(C'\fR and
2097 \&\f(CW\*(C`fetchrow_hashref\*(C'\fR calls. A wrapper function will also make it easier to
2098 adapt to future enhancements in your database driver. Note that at the
2099 time of this writing (January 2012), the DBI has no standardized way
2100 to deal with UTF\-8 data. Please check the DBI documentation to verify if
2101 that is still true.
2102 .Sp
2103 .Vb 10
2104 \& sub fetchrow {
2105 \& # $what is one of fetchrow_{array,hashref}
2106 \& my($self, $sth, $what) = @_;
2107 \& if ($] < 5.008) {
2108 \& return $sth\->$what;
2109 \& } else {
2110 \& require Encode;
2111 \& if (wantarray) {
2112 \& my @arr = $sth\->$what;
2113 \& for (@arr) {
2114 \& defined && /[^\e000\-\e177]/ && Encode::_utf8_on($_);
2115 \& }
2116 \& return @arr;
2117 \& } else {
2118 \& my $ret = $sth\->$what;
2119 \& if (ref $ret) {
2120 \& for my $k (keys %$ret) {
2121 \& defined
2122 \& && /[^\e000\-\e177]/
2123 \& && Encode::_utf8_on($_) for $ret\->{$k};
2124 \& }
2125 \& return $ret;
2126 \& } else {
2127 \& defined && /[^\e000\-\e177]/ && Encode::_utf8_on($_) for $ret;
2128 \& return $ret;
2129 \& }
2130 \& }
2131 \& }
2132 \& }
2133 .Ve
2134 .IP \(bu 3
2135 A large scalar that you know can only contain ASCII
2136 .Sp
2137 Scalars that contain only ASCII and are marked as UTF\-8 are sometimes
2138 a drag to your program. If you recognize such a situation, just remove
2139 the UTF8 flag:
2140 .Sp
2141 .Vb 1
2142 \& utf8::downgrade($val) if $] > 5.008;
2143 .Ve
2144 .SH BUGS
2145 .IX Header "BUGS"
2146 See also "The "Unicode Bug"" above.
2147 .SS "Interaction with Extensions"
2148 .IX Subsection "Interaction with Extensions"
2149 When Perl exchanges data with an extension, the extension should be
2150 able to understand the UTF8 flag and act accordingly. If the
2151 extension doesn\*(Aqt recognize that flag, it\*(Aqs likely that the extension
2152 will return incorrectly\-flagged data.
2153 .PP
2154 So if you\*(Aqre working with Unicode data, consult the documentation of
2155 every module you\*(Aqre using if there are any issues with Unicode data
2156 exchange. If the documentation does not talk about Unicode at all,
2157 suspect the worst and probably look at the source to learn how the
2158 module is implemented. Modules written completely in Perl shouldn\*(Aqt
2159 cause problems. Modules that directly or indirectly access code written
2160 in other programming languages are at risk.
2161 .PP
2162 For affected functions, the simple strategy to avoid data corruption is
2163 to always make the encoding of the exchanged data explicit. Choose an
2164 encoding that you know the extension can handle. Convert arguments passed
2165 to the extensions to that encoding and convert results back from that
2166 encoding. Write wrapper functions that do the conversions for you, so
2167 you can later change the functions when the extension catches up.
2168 .PP
2169 To provide an example, let\*(Aqs say the popular \f(CW\*(C`Foo::Bar::escape_html\*(C'\fR
2170 function doesn\*(Aqt deal with Unicode data yet. The wrapper function
2171 would convert the argument to raw UTF\-8 and convert the result back to
2172 Perl\*(Aqs internal representation like so:
2173 .PP
2174 .Vb 6
2175 \& sub my_escape_html ($) {
2176 \& my($what) = shift;
2177 \& return unless defined $what;
2178 \& Encode::decode("UTF\-8", Foo::Bar::escape_html(
2179 \& Encode::encode("UTF\-8", $what)));
2180 \& }
2181 .Ve
2182 .PP
2183 Sometimes, when the extension does not convert data but just stores
2184 and retrieves it, you will be able to use the otherwise
2185 dangerous \f(CWEncode::_utf8_on()\fR function. Let\*(Aqs say
2186 the popular \f(CW\*(C`Foo::Bar\*(C'\fR extension, written in C, provides a \f(CW\*(C`param\*(C'\fR
2187 method that lets you store and retrieve data according to these prototypes:
2188 .PP
2189 .Vb 2
2190 \& $self\->param($name, $value); # set a scalar
2191 \& $value = $self\->param($name); # retrieve a scalar
2192 .Ve
2193 .PP
2194 If it does not yet provide support for any encoding, one could write a
2195 derived class with such a \f(CW\*(C`param\*(C'\fR method:
2196 .PP
2197 .Vb 12
2198 \& sub param {
2199 \& my($self,$name,$value) = @_;
2200 \& utf8::upgrade($name); # make sure it is UTF\-8 encoded
2201 \& if (defined $value) {
2202 \& utf8::upgrade($value); # make sure it is UTF\-8 encoded
2203 \& return $self\->SUPER::param($name,$value);
2204 \& } else {
2205 \& my $ret = $self\->SUPER::param($name);
2206 \& Encode::_utf8_on($ret); # we know, it is UTF\-8 encoded
2207 \& return $ret;
2208 \& }
2209 \& }
2210 .Ve
2211 .PP
2212 Some extensions provide filters on data entry/exit points, such as
2213 \&\f(CW\*(C`DB_File::filter_store_key\*(C'\fR and family. Look out for such filters in
2214 the documentation of your extensions; they can make the transition to
2215 Unicode data much easier.
2216 .SS Speed
2217 .IX Subsection "Speed"
2218 Some functions are slower when working on UTF\-8 encoded strings than
2219 on byte encoded strings. All functions that need to hop over
2220 characters such as \f(CWlength()\fR, \f(CWsubstr()\fR or \f(CWindex()\fR, or matching
2221 regular expressions can work \fBmuch\fR faster when the underlying data are
2222 byte\-encoded.
2223 .PP
2224 In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
2225 a caching scheme was introduced which improved the situation. In general,
2226 operations with UTF\-8 encoded strings are still slower. As an example,
2227 the Unicode properties (character classes) like \f(CW\*(C`\ep{Nd}\*(C'\fR are known to
2228 be quite a bit slower (5\-20 times) than their simpler counterparts
2229 like \f(CW\*(C`[0\-9]\*(C'\fR (then again, there are hundreds of Unicode characters matching
2230 \&\f(CW\*(C`Nd\*(C'\fR compared with the 10 ASCII characters matching \f(CW\*(C`[0\-9]\*(C'\fR).
2231 .SH "SEE ALSO"
2232 .IX Header "SEE ALSO"
2233 perlunitut, perluniintro, perluniprops, Encode, open, utf8, bytes,
2234 perlretut, "${^UNICODE}" in perlvar,
2235 <https://www.unicode.org/reports/tr44>).