Unicode categories continue:
[p5sagit/p5-mst-13.2.git] / pod / perlunicode.pod
CommitLineData
393fec97 1=head1 NAME
2
3perlunicode - Unicode support in Perl
4
5=head1 DESCRIPTION
6
0a1f2d14 7=head2 Important Caveats
21bad921 8
776f8809 9WARNING: While the implementation of Unicode support in Perl is now
10fairly complete it is still evolving to some extent.
21bad921 11
75daf61c 12In particular the way Unicode is handled on EBCDIC platforms is still
13rather experimental. On such a platform references to UTF-8 encoding
14in this document and elsewhere should be read as meaning UTF-EBCDIC as
15specified in Unicode Technical Report 16 unless ASCII vs EBCDIC issues
16are specifically discussed. There is no C<utfebcdic> pragma or
17":utfebcdic" layer, rather "utf8" and ":utf8" are re-used to mean
18platform's "natural" 8-bit encoding of Unicode. See L<perlebcdic> for
19more discussion of the issues.
0a1f2d14 20
21The following areas are still under development.
21bad921 22
13a2d996 23=over 4
21bad921 24
25=item Input and Output Disciplines
26
75daf61c 27A filehandle can be marked as containing perl's internal Unicode
28encoding (UTF-8 or UTF-EBCDIC) by opening it with the ":utf8" layer.
0a1f2d14 29Other encodings can be converted to perl's encoding on input, or from
75daf61c 30perl's encoding on output by use of the ":encoding()" layer. There is
31not yet a clean way to mark the Perl source itself as being in an
32particular encoding.
21bad921 33
34=item Regular Expressions
35
e6739005 36The regular expression compiler does now attempt to produce
37polymorphic opcodes. That is the pattern should now adapt to the data
75daf61c 38and automatically switch to the Unicode character scheme when
39presented with Unicode data, or a traditional byte scheme when
40presented with byte data. The implementation is still new and
41(particularly on EBCDIC platforms) may need further work.
21bad921 42
ad0029c4 43=item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts
21bad921 44
75daf61c 45The C<utf8> pragma implements the tables used for Unicode support.
46These tables are automatically loaded on demand, so the C<utf8> pragma
47need not normally be used.
21bad921 48
75daf61c 49However, as a compatibility measure, this pragma must be explicitly
ad0029c4 50used to enable recognition of UTF-8 in the Perl scripts themselves on
51ASCII based machines or recognize UTF-EBCDIC on EBCDIC based machines.
7dedd01f 52B<NOTE: this should be the only place where an explicit C<use utf8> is
53needed>.
21bad921 54
55=back
56
57=head2 Byte and Character semantics
393fec97 58
59Beginning with version 5.6, Perl uses logically wide characters to
60represent strings internally. This internal representation of strings
b3419ed8 61uses either the UTF-8 or the UTF-EBCDIC encoding.
393fec97 62
75daf61c 63In future, Perl-level operations can be expected to work with
64characters rather than bytes, in general.
393fec97 65
75daf61c 66However, as strictly an interim compatibility measure, Perl aims to
67provide a safe migration path from byte semantics to character
68semantics for programs. For operations where Perl can unambiguously
69decide that the input data is characters, Perl now switches to
70character semantics. For operations where this determination cannot
71be made without additional information from the user, Perl decides in
72favor of compatibility, and chooses to use byte semantics.
8cbd9a7a 73
74This behavior preserves compatibility with earlier versions of Perl,
75which allowed byte semantics in Perl operations, but only as long as
76none of the program's inputs are marked as being as source of Unicode
77character data. Such data may come from filehandles, from calls to
78external programs, from information provided by the system (such as %ENV),
21bad921 79or from literals and constants in the source text.
8cbd9a7a 80
75daf61c 81If the C<-C> command line switch is used, (or the
82${^WIDE_SYSTEM_CALLS} global flag is set to C<1>), all system calls
83will use the corresponding wide character APIs. Note that this is
84currently only implemented on Windows since other platforms API
85standard on this area.
8cbd9a7a 86
75daf61c 87Regardless of the above, the C<bytes> pragma can always be used to
88force byte semantics in a particular lexical scope. See L<bytes>.
8cbd9a7a 89
90The C<utf8> pragma is primarily a compatibility device that enables
75daf61c 91recognition of UTF-(8|EBCDIC) in literals encountered by the parser.
7dedd01f 92Note that this pragma is only required until a future version of Perl
93in which character semantics will become the default. This pragma may
94then become a no-op. See L<utf8>.
8cbd9a7a 95
96Unless mentioned otherwise, Perl operators will use character semantics
97when they are dealing with Unicode data, and byte semantics otherwise.
98Thus, character semantics for these operations apply transparently; if
99the input data came from a Unicode source (for example, by adding a
100character encoding discipline to the filehandle whence it came, or a
101literal UTF-8 string constant in the program), character semantics
102apply; otherwise, byte semantics are in effect. To force byte semantics
8058d7ab 103on Unicode data, the C<bytes> pragma should be used.
393fec97 104
7dedd01f 105Notice that if you have a string with byte semantics and you then
106add character data into it, the bytes will be upgraded I<as if they
107were ISO 8859-1 (Latin-1)> (or if in EBCDIC, after a translation
108to ISO 8859-1).
109
393fec97 110Under character semantics, many operations that formerly operated on
75daf61c 111bytes change to operating on characters. For ASCII data this makes no
112difference, because UTF-8 stores ASCII in single bytes, but for any
113character greater than C<chr(127)>, the character B<may> be stored in
393fec97 114a sequence of two or more bytes, all of which have the high bit set.
2796c109 115
116For C1 controls or Latin 1 characters on an EBCDIC platform the
117character may be stored in a UTF-EBCDIC multi byte sequence. But by
118and large, the user need not worry about this, because Perl hides it
119from the user. A character in Perl is logically just a number ranging
120from 0 to 2**32 or so. Larger characters encode to longer sequences
121of bytes internally, but again, this is just an internal detail which
122is hidden at the Perl level.
393fec97 123
8cbd9a7a 124=head2 Effects of character semantics
393fec97 125
126Character semantics have the following effects:
127
128=over 4
129
130=item *
131
132Strings and patterns may contain characters that have an ordinal value
21bad921 133larger than 255.
393fec97 134
75daf61c 135Presuming you use a Unicode editor to edit your program, such
136characters will typically occur directly within the literal strings as
137UTF-8 (or UTF-EBCDIC on EBCDIC platforms) characters, but you can also
138specify a particular character with an extension of the C<\x>
139notation. UTF-X characters are specified by putting the hexadecimal
140code within curlies after the C<\x>. For instance, a Unicode smiley
141face is C<\x{263A}>.
393fec97 142
143=item *
144
145Identifiers within the Perl script may contain Unicode alphanumeric
146characters, including ideographs. (You are currently on your own when
75daf61c 147it comes to using the canonical forms of characters--Perl doesn't
148(yet) attempt to canonicalize variable names for you.)
393fec97 149
393fec97 150=item *
151
152Regular expressions match characters instead of bytes. For instance,
153"." matches a character instead of a byte. (However, the C<\C> pattern
75daf61c 154is provided to force a match a single byte ("C<char>" in C, hence C<\C>).)
393fec97 155
393fec97 156=item *
157
158Character classes in regular expressions match characters instead of
159bytes, and match against the character properties specified in the
75daf61c 160Unicode properties database. So C<\w> can be used to match an
161ideograph, for instance.
393fec97 162
393fec97 163=item *
164
165Named Unicode properties and block ranges make be used as character
166classes via the new C<\p{}> (matches property) and C<\P{}> (doesn't
167match property) constructs. For instance, C<\p{Lu}> matches any
168character with the Unicode uppercase property, while C<\p{M}> matches
9fdf68be 169any mark character. Single letter properties may omit the brackets,
170so that can be written C<\pM> also. Many predefined character classes
a1cc1cb1 171are available, such as C<\p{IsMirrored}> and C<\p{InTibetan}>.
4193bef7 172
173The C<\p{Is...}> test for "general properties" such as "letter",
174"digit", while the C<\p{In...}> test for Unicode scripts and blocks.
175
176The official Unicode script and block names have spaces and
177dashes and separators, but for convenience you can have
178dashes, spaces, and underbars at every word division, and
179you need not care about correct casing. It is recommended,
180however, that for consistency you use the following naming:
181the official Unicode script or block name (see below for
182the additional rules that apply to block names), with the whitespace
183and dashes removed, and the words "uppercase-first-lowercase-otherwise".
184That is, "Latin-1 Supplement" becomes "Latin1Supplement".
185
a1cc1cb1 186You can also negate both C<\p{}> and C<\P{}> by introducing a caret
187(^) between the first curly and the property name: C<\p{^InTamil}> is
4193bef7 188equal to C<\P{InTamil}>.
189
61247495 190The C<In> and C<Is> can be left out: C<\p{Greek}> is equal to
191C<\p{InGreek}>, C<\P{Pd}> is equal to C<\P{Pd}>.
393fec97 192
d73e5302 193 Short Long
194
195 L Letter
196 Lu Uppercase Letter
197 Ll Lowercase Letter
198 Lt Titlecase Letter
199 Lm Modifier Letter
200 Lo Other Letter
201
202 M Mark
203 Mn Non-Spacing Mark
204 Mc Spacing Combining Mark
205 Me Enclosing Mark
206
207 N Number
208 Nd Decimal Digit Number
209 Nl Letter Number
210 No Other Number
211
212 P Punctuation
213 Pc Connector Punctuation
214 Pd Dash Punctuation
215 Ps Open Punctuation
216 Pe Close Punctuation
217 Pi Initial Punctuation
218 (may behave like Ps or Pe depending on usage)
219 Pf Final Punctuation
220 (may behave like Ps or Pe depending on usage)
221 Po Other Punctuation
222
223 S Symbol
224 Sm Math Symbol
225 Sc Currency Symbol
226 Sk Modifier Symbol
227 So Other Symbol
228
229 Z Separator
230 Zs Space Separator
231 Zl Line Separator
232 Zp Paragraph Separator
233
234 C Other
235 Cc (Other) Control
236 Cf (Other) Format
237 Cs (Other) Surrogate
238 Co (Other) Private Use
239 Cn (Other) Not Assigned
1ac13f9a 240
241There's also C<L&> which is an alias for C<Ll>, C<Lu>, and C<Lt>.
32293815 242
d73e5302 243The following reserved ranges have C<In> tests:
244
245 CJK Ideograph Extension A
246 CJK Ideograph
247 Hangul Syllable
248 Non Private Use High Surrogate
249 Private Use High Surrogate
250 Low Surrogate
251 Private Surrogate
252 CJK Ideograph Extension B
a63942c2 253 Plane 15 Private Use
254 Plane 16 Private Use
d73e5302 255
256For example C<"\x{AC00}" =~ \p{HangulSyllable}> will test true.
257(Handling of surrogates is not implemented yet.)
258
32293815 259Additionally, because scripts differ in their directionality
260(for example Hebrew is written right to left), all characters
261have their directionality defined:
262
d73e5302 263 BidiL Left-to-Right
264 BidiLRE Left-to-Right Embedding
265 BidiLRO Left-to-Right Override
266 BidiR Right-to-Left
267 BidiAL Right-to-Left Arabic
268 BidiRLE Right-to-Left Embedding
269 BidiRLO Right-to-Left Override
270 BidiPDF Pop Directional Format
271 BidiEN European Number
272 BidiES European Number Separator
273 BidiET European Number Terminator
274 BidiAN Arabic Number
275 BidiCS Common Number Separator
276 BidiNSM Non-Spacing Mark
277 BidiBN Boundary Neutral
278 BidiB Paragraph Separator
279 BidiS Segment Separator
280 BidiWS Whitespace
281 BidiON Other Neutrals
32293815 282
2796c109 283=head2 Scripts
284
75daf61c 285The scripts available for C<\p{In...}> and C<\P{In...}>, for example
286\p{InCyrillic>, are as follows, for example C<\p{InLatin}> or C<\P{InHan}>:
2796c109 287
1ac13f9a 288 Latin
289 Greek
290 Cyrillic
291 Armenian
292 Hebrew
293 Arabic
294 Syriac
295 Thaana
296 Devanagari
297 Bengali
298 Gurmukhi
299 Gujarati
300 Oriya
301 Tamil
302 Telugu
303 Kannada
304 Malayalam
305 Sinhala
306 Thai
307 Lao
308 Tibetan
309 Myanmar
310 Georgian
311 Hangul
312 Ethiopic
313 Cherokee
71d929cb 314 Canadian Aboriginal
1ac13f9a 315 Ogham
316 Runic
317 Khmer
318 Mongolian
319 Hiragana
320 Katakana
321 Bopomofo
322 Han
323 Yi
71d929cb 324 Old Italic
1ac13f9a 325 Gothic
326 Deseret
327 Inherited
328
329There are also extended property classes that supplement the basic
330properties, defined by the F<PropList> Unicode database:
331
332 White_space
333 Bidi_Control
334 Join_Control
335 Dash
336 Hyphen
337 Quotation_Mark
338 Other_Math
339 Hex_Digit
340 ASCII_Hex_Digit
341 Other_Alphabetic
342 Ideographic
343 Diacritic
344 Extender
345 Other_Lowercase
346 Other_Uppercase
347 Noncharacter_Code_Point
348
349and further derived properties:
350
351 Alphabetic Lu + Ll + Lt + Lm + Lo + Other_Alphabetic
352 Lowercase Ll + Other_Lowercase
353 Uppercase Lu + Other_Uppercase
354 Math Sm + Other_Math
355
356 ID_Start Lu + Ll + Lt + Lm + Lo + Nl
357 ID_Continue ID_Start + Mn + Mc + Nd + Pc
358
359 Any Any character
360 Assigned Any non-Cn character
361 Common Any character (or unassigned code point)
362 not explicitly assigned to a script.
2796c109 363
364=head2 Blocks
365
366In addition to B<scripts>, Unicode also defines B<blocks> of
367characters. The difference between scripts and blocks is that the
368former concept is closer to natural languages, while the latter
369concept is more an artificial grouping based on groups of 256 Unicode
370characters. For example, the C<Latin> script contains letters from
371many blocks, but it does not contain all the characters from those
372blocks, it does not for example contain digits.
373
374For more about scripts see the UTR #24:
375http://www.unicode.org/unicode/reports/tr24/
376For more about blocks see
377http://www.unicode.org/Public/UNIDATA/Blocks.txt
378
379Because there are overlaps in naming (there are, for example, both
380a script called C<Katakana> and a block called C<Katakana>, the block
381version has C<Block> appended to its name, C<\p{InKatakanaBlock}>.
382
383Notice that this definition was introduced in Perl 5.8.0: in Perl
3845.6.0 only the blocks were used; in Perl 5.8.0 scripts became the
61247495 385preferential Unicode character class definition; this meant that
386the definitions of some character classes changed (the ones in the
2796c109 387below list that have the C<Block> appended).
388
71d929cb 389 Basic Latin
390 Latin 1 Supplement
391 Latin Extended-A
392 Latin Extended-B
393 IPA Extensions
394 Spacing Modifier Letters
395 Combining Diacritical Marks
396 Greek Block
397 Cyrillic Block
398 Armenian Block
399 Hebrew Block
400 Arabic Block
401 Syriac Block
402 Thaana Block
403 Devanagari Block
404 Bengali Block
405 Gurmukhi Block
406 Gujarati Block
407 Oriya Block
408 Tamil Block
409 Telugu Block
410 Kannada Block
411 Malayalam Block
412 Sinhala Block
413 Thai Block
414 Lao Block
415 Tibetan Block
416 Myanmar Block
417 Georgian Block
418 Hangul Jamo
419 Ethiopic Block
420 Cherokee Block
421 Unified Canadian Aboriginal Syllabics
422 Ogham Block
423 Runic Block
424 Khmer Block
425 Mongolian Block
426 Latin Extended Additional
427 Greek Extended
428 General Punctuation
429 Superscripts and Subscripts
430 Currency Symbols
431 Combining Marks for Symbols
432 Letterlike Symbols
433 Number Forms
2796c109 434 Arrows
71d929cb 435 Mathematical Operators
436 Miscellaneous Technical
437 Control Pictures
438 Optical Character Recognition
439 Enclosed Alphanumerics
440 Box Drawing
441 Block Elements
442 Geometric Shapes
443 Miscellaneous Symbols
2796c109 444 Dingbats
71d929cb 445 Braille Patterns
446 CJK Radicals Supplement
447 Kangxi Radicals
448 Ideographic Description Characters
449 CJK Symbols and Punctuation
450 Hiragana Block
451 Katakana Block
452 Bopomofo Block
453 Hangul Compatibility Jamo
2796c109 454 Kanbun
71d929cb 455 Bopomofo Extended
456 Enclosed CJK Letters and Months
457 CJK Compatibility
458 CJK Unified Ideographs Extension A
459 CJK Unified Ideographs
460 Yi Syllables
461 Yi Radicals
462 Hangul Syllables
463 High Surrogates
464 High Private Use Surrogates
465 Low Surrogates
466 Private Use
467 CJK Compatibility Ideographs
468 Alphabetic Presentation Forms
469 Arabic Presentation Forms-A
470 Combining Half Marks
471 CJK Compatibility Forms
472 Small Form Variants
473 Arabic Presentation Forms-B
2796c109 474 Specials
71d929cb 475 Halfwidth and Fullwidth Forms
476 Old Italic Block
477 Gothic Block
478 Deseret Block
479 Byzantine Musical Symbols
480 Musical Symbols
481 Mathematical Alphanumeric Symbols
482 CJK Unified Ideographs Extension B
483 CJK Compatibility Ideographs Supplement
2796c109 484 Tags
32293815 485
393fec97 486=item *
487
488The special pattern C<\X> match matches any extended Unicode sequence
489(a "combining character sequence" in Standardese), where the first
490character is a base character and subsequent characters are mark
491characters that apply to the base character. It is equivalent to
492C<(?:\PM\pM*)>.
493
393fec97 494=item *
495
383e7cdd 496The C<tr///> operator translates characters instead of bytes. Note
497that the C<tr///CU> functionality has been removed, as the interface
498was a mistake. For similar functionality see pack('U0', ...) and
499pack('C0', ...).
393fec97 500
393fec97 501=item *
502
503Case translation operators use the Unicode case translation tables
504when provided character input. Note that C<uc()> translates to
505uppercase, while C<ucfirst> translates to titlecase (for languages
506that make the distinction). Naturally the corresponding backslash
507sequences have the same semantics.
508
509=item *
510
511Most operators that deal with positions or lengths in the string will
75daf61c 512automatically switch to using character positions, including
513C<chop()>, C<substr()>, C<pos()>, C<index()>, C<rindex()>,
514C<sprintf()>, C<write()>, and C<length()>. Operators that
515specifically don't switch include C<vec()>, C<pack()>, and
516C<unpack()>. Operators that really don't care include C<chomp()>, as
517well as any other operator that treats a string as a bucket of bits,
518such as C<sort()>, and the operators dealing with filenames.
393fec97 519
520=item *
521
522The C<pack()>/C<unpack()> letters "C<c>" and "C<C>" do I<not> change,
523since they're often used for byte-oriented formats. (Again, think
524"C<char>" in the C language.) However, there is a new "C<U>" specifier
525that will convert between UTF-8 characters and integers. (It works
526outside of the utf8 pragma too.)
527
528=item *
529
530The C<chr()> and C<ord()> functions work on characters. This is like
531C<pack("U")> and C<unpack("U")>, not like C<pack("C")> and
532C<unpack("C")>. In fact, the latter are how you now emulate
35bcd338 533byte-oriented C<chr()> and C<ord()> for Unicode strings.
534(Note that this reveals the internal UTF-8 encoding of strings and
535you are not supposed to do that unless you know what you are doing.)
393fec97 536
537=item *
538
a1ca4561 539The bit string operators C<& | ^ ~> can operate on character data.
540However, for backward compatibility reasons (bit string operations
75daf61c 541when the characters all are less than 256 in ordinal value) one should
542not mix C<~> (the bit complement) and characters both less than 256 and
a1ca4561 543equal or greater than 256. Most importantly, the DeMorgan's laws
544(C<~($x|$y) eq ~$x&~$y>, C<~($x&$y) eq ~$x|~$y>) won't hold.
545Another way to look at this is that the complement cannot return
75daf61c 546B<both> the 8-bit (byte) wide bit complement B<and> the full character
a1ca4561 547wide bit complement.
548
549=item *
550
6f16a292 551lc(), uc(), lcfirst(), and ucfirst() work only for some of the
552simplest cases, where the mapping goes from a single Unicode character
03e60089 553to another single Unicode character, and where the mapping does not
554depend on surrounding characters, or on locales. More complex cases,
555where for example one character maps into several, are not yet
556implemented. See the Unicode Technical Report #21, Case Mappings,
557for more details. The Unicode::UCD module (part of Perl since 5.8.0)
558casespec() and casefold() interfaces supply information about the more
559complex cases.
ac1256e8 560
561=item *
562
393fec97 563And finally, C<scalar reverse()> reverses by character rather than by byte.
564
565=back
566
8cbd9a7a 567=head2 Character encodings for input and output
568
7221edc9 569See L<Encode>.
8cbd9a7a 570
393fec97 571=head1 CAVEATS
572
573As of yet, there is no method for automatically coercing input and
b3419ed8 574output to some encoding other than UTF-8 or UTF-EBCDIC. This is planned
575in the near future, however.
393fec97 576
8cbd9a7a 577Whether an arbitrary piece of data will be treated as "characters" or
578"bytes" by internal operations cannot be divined at the current time.
393fec97 579
580Use of locales with utf8 may lead to odd results. Currently there is
581some attempt to apply 8-bit locale info to characters in the range
5820..255, but this is demonstrably incorrect for locales that use
583characters above that range (when mapped into Unicode). It will also
584tend to run slower. Avoidance of locales is strongly encouraged.
585
776f8809 586=head1 UNICODE REGULAR EXPRESSION SUPPORT LEVEL
587
588The following list of Unicode regular expression support describes
589feature by feature the Unicode support implemented in Perl as of Perl
5905.8.0. The "Level N" and the section numbers refer to the Unicode
591Technical Report 18, "Unicode Regular Expression Guidelines".
592
593=over 4
594
595=item *
596
597Level 1 - Basic Unicode Support
598
599 2.1 Hex Notation - done [1]
600 Named Notation - done [2]
601 2.2 Categories - done [3][4]
602 2.3 Subtraction - MISSING [5][6]
603 2.4 Simple Word Boundaries - done [7]
604 2.5 Simple Loose Matches - MISSING [8]
605 2.6 End of Line - MISSING [9][10]
606
607 [ 1] \x{...}
608 [ 2] \N{...}
609 [ 3] . \p{Is...} \P{Is...}
610 [ 4] now scripts (see UTR#24 Script Names) in addition to blocks
611 [ 5] have negation
612 [ 6] can use look-ahead to emulate subtracion
613 [ 7] include Letters in word characters
614 [ 8] see UTR#21 Case Mappings
615 [ 9] see UTR#13 Unicode Newline Guidelines
616 [10] should do ^ and $ also on \x{2028} and \x{2029}
617
618=item *
619
620Level 2 - Extended Unicode Support
621
622 3.1 Surrogates - MISSING
623 3.2 Canonical Equivalents - MISSING [11][12]
624 3.3 Locale-Independent Graphemes - MISSING [13]
625 3.4 Locale-Independent Words - MISSING [14]
626 3.5 Locale-Independent Loose Matches - MISSING [15]
627
628 [11] see UTR#15 Unicode Normalization
629 [12] have Unicode::Normalize but not integrated to regexes
630 [13] have \X but at this level . should equal that
631 [14] need three classes, not just \w and \W
632 [15] see UTR#21 Case Mappings
633
634=item *
635
636Level 3 - Locale-Sensitive Support
637
638 4.1 Locale-Dependent Categories - MISSING
639 4.2 Locale-Dependent Graphemes - MISSING [16][17]
640 4.3 Locale-Dependent Words - MISSING
641 4.4 Locale-Dependent Loose Matches - MISSING
642 4.5 Locale-Dependent Ranges - MISSING
643
644 [16] see UTR#10 Unicode Collation Algorithms
645 [17] have Unicode::Collate but not integrated to regexes
646
647=back
648
393fec97 649=head1 SEE ALSO
650
32293815 651L<bytes>, L<utf8>, L<perlretut>, L<perlvar/"${^WIDE_SYSTEM_CALLS}">
393fec97 652
653=cut