Better fix from Autrijus.
[p5sagit/p5-mst-13.2.git] / ext / Encode / Encode.pm
1 package Encode;
2 use strict;
3 our $VERSION = '0.40';
4
5 require DynaLoader;
6 require Exporter;
7
8 our @ISA = qw(Exporter DynaLoader);
9
10 # Public, encouraged API is exported by default
11 our @EXPORT = qw (
12   encode
13   decode
14   encode_utf8
15   decode_utf8
16   find_encoding
17   encodings
18 );
19
20 our @EXPORT_OK =
21     qw(
22        define_encoding
23        define_alias
24        from_to
25        is_utf8
26        is_8bit
27        is_16bit
28        utf8_upgrade
29        utf8_downgrade
30        _utf8_on
31        _utf8_off
32       );
33
34 bootstrap Encode ();
35
36 # Documentation moved after __END__ for speed - NI-S
37
38 use Carp;
39
40 # Make a %encoding package variable to allow a certain amount of cheating
41 our %encoding;
42 my @alias;  # ordered matching list
43 my %alias;  # cached known aliases
44
45                      # 0  1  2  3  4  5   6   7   8   9  10
46 our @latin2iso_num = ( 0, 1, 2, 3, 4, 9, 10, 13, 14, 15, 16 );
47
48 our %winlatin2cp   = (
49                       'Latin1'     => 1252,
50                       'Latin2'     => 1250,
51                       'Cyrillic'   => 1251,
52                       'Greek'      => 1253,
53                       'Turkish'    => 1254,
54                       'Hebrew'     => 1255,
55                       'Arabic'     => 1256,
56                       'Baltic'     => 1257,
57                       'Vietnamese' => 1258,
58                      );
59
60 our %external_tables = 
61     (
62         'euc-cn'        => 'Encode/CN.pm',
63         gb2312          => 'Encode/CN.pm',
64         gb12345         => 'Encode/CN.pm',
65         gbk             => 'Encode/CN.pm',
66         cp936           => 'Encode/CN.pm',
67         'iso-ir-165'    => 'Encode/CN.pm',
68         'euc-jp'        => 'Encode/JP.pm',
69         shiftjis        => 'Encode/JP.pm',
70         macjapan        => 'Encode/JP.pm',
71         cp932           => 'Encode/JP.pm',
72         'euc-kr'        => 'Encode/KR.pm',
73         ksc5601         => 'Encode/KR.pm',
74         cp949           => 'Encode/KR.pm',
75         big5            => 'Encode/TW.pm',
76         'big5-hkscs'    => 'Encode/TW.pm',
77         cp950           => 'Encode/TW.pm',
78         gb18030         => 'Encode/HanExtra.pm',
79         big5plus        => 'Encode/HanExtra.pm',
80         'euc-tw'        => 'Encode/HanExtra.pm',
81     );
82
83 sub encodings
84 {
85  my ($class) = @_;
86  return
87      map { $_->[0] }
88          sort { $a->[1] cmp $b->[1] }
89                map { [$_, lc $_] }
90                    grep { $_ ne 'Internal' }
91                         keys %encoding;
92 }
93
94 sub findAlias
95 {
96     my $class = shift;
97     local $_ = shift;
98     # print "# findAlias $_\n";
99     unless (exists $alias{$_})
100     {
101         for (my $i=0; $i < @alias; $i += 2)
102         {
103             my $alias = $alias[$i];
104             my $val   = $alias[$i+1];
105             my $new;
106             if (ref($alias) eq 'Regexp' && $_ =~ $alias)
107             {
108                 $new = eval $val;
109             }
110             elsif (ref($alias) eq 'CODE')
111             {
112                 $new = &{$alias}($val)
113                 }
114             elsif (lc($_) eq lc($alias))
115             {
116                 $new = $val;
117             }
118             if (defined($new))
119             {
120                 next if $new eq $_; # avoid (direct) recursion on bugs
121                 my $enc = (ref($new)) ? $new : find_encoding($new);
122                 if ($enc)
123                 {
124                     $alias{$_} = $enc;
125                     last;
126                 }
127             }
128         }
129     }
130     return $alias{$_};
131 }
132
133 sub define_alias
134 {
135     while (@_)
136     {
137         my ($alias,$name) = splice(@_,0,2);
138         push(@alias, $alias => $name);
139     }
140 }
141
142 # Allow variants of iso-8859-1 etc.
143 define_alias( qr/^iso[-_]?(\d+)[-_](\d+)$/i => '"iso-$1-$2"' );
144
145 # At least HP-UX has these.
146 define_alias( qr/^iso8859(\d+)$/i => '"iso-8859-$1"' );
147
148 # More HP stuff.
149 define_alias( qr/^(?:hp-)?(arabic|greek|hebrew|kana|roman|thai|turkish)8$/i => '"${1}8"' );
150
151 # The Official name of ASCII.
152 define_alias( qr/^ANSI[-_]?X3\.4[-_]?1968$/i => '"ascii"' );
153
154 # This is a font issue, not an encoding issue.
155 # (The currency symbol of the Latin 1 upper half
156 #  has been redefined as the euro symbol.)
157 define_alias( qr/^(.+)\@euro$/i => '"$1"' );
158
159 # Allow latin-1 style names as well
160 define_alias( qr/^(?:iso[-_]?)?latin[-_]?(\d+)$/i => '"iso-8859-$latin2iso_num[$1]"' );
161
162 # Allow winlatin1 style names as well
163 define_alias( qr/^win(latin[12]|cyrillic|baltic|greek|turkish|hebrew|arabic|baltic|vietnamese)$/i => '"cp$winlatin2cp{\u$1}"' );
164
165 # Common names for non-latin prefered MIME names
166 define_alias( 'ascii'    => 'US-ascii',
167               'cyrillic' => 'iso-8859-5',
168               'arabic'   => 'iso-8859-6',
169               'greek'    => 'iso-8859-7',
170               'hebrew'   => 'iso-8859-8',
171               'thai'     => 'iso-8859-11',
172               'tis620'   => 'iso-8859-11',
173             );
174
175 # At least AIX has IBM-NNN (surprisingly...) instead of cpNNN.
176 # And Microsoft has their own naming (again, surprisingly).
177 define_alias( qr/^(?:ibm|ms)[-_]?(\d\d\d\d?)$/i => '"cp$1"');
178
179 # Sometimes seen with a leading zero.
180 define_alias( qr/^cp037$/i => '"cp37"');
181
182 # Ououououou.
183 define_alias( qr/^macRomanian$/i => '"macRumanian"');
184
185 # Standardize on the dashed versions.
186 define_alias( qr/^utf8$/i  => 'utf-8' );
187 define_alias( qr/^koi8r$/i => 'koi8-r' );
188 define_alias( qr/^koi8u$/i => 'koi8-u' );
189
190 # Seen in some Linuxes.
191 define_alias( qr/^ujis$/i => 'euc-jp' );
192
193 # CP936 doesn't have vendor-addon for GBK, so they're identical.
194 define_alias( qr/^gbk$/i => '"cp936"');
195
196 # TODO: HP-UX '8' encodings arabic8 greek8 hebrew8 kana8 thai8 turkish8
197 # TODO: HP-UX '15' encodings japanese15 korean15 roi15
198 # TODO: Cyrillic encoding ISO-IR-111 (useful?)
199 # TODO: Armenian encoding ARMSCII-8
200 # TODO: Hebrew encoding ISO-8859-8-1
201 # TODO: Thai encoding TCVN
202 # TODO: Korean encoding Johab
203 # TODO: Vietnamese encodings VPS
204 # TODO: Japanese encoding JIS (not the same as SJIS)
205 # TODO: Mac Asian+African encodings: Arabic Armenian Bengali Burmese
206 #       ChineseSimp ChineseTrad Devanagari Ethiopic ExtArabic
207 #       Farsi Georgian Gujarati Gurmukhi Hebrew Japanese
208 #       Kannada Khmer Korean Laotian Malayalam Mongolian
209 #       Oriya Sinhalese Symbol Tamil Telugu Tibetan Vietnamese
210
211 # Map white space and _ to '-'
212 define_alias( qr/^(\S+)[\s_]+(.*)$/i => '"$1-$2"' );
213
214 sub define_encoding
215 {
216     my $obj  = shift;
217     my $name = shift;
218     $encoding{$name} = $obj;
219     my $lc = lc($name);
220     define_alias($lc => $obj) unless $lc eq $name;
221     while (@_)
222     {
223         my $alias = shift;
224         define_alias($alias,$obj);
225     }
226     return $obj;
227 }
228
229 sub getEncoding
230 {
231     my ($class,$name) = @_;
232     my $enc;
233     if (ref($name) && $name->can('new_sequence'))
234     {
235         return $name;
236     }
237     my $lc = lc $name;
238     if (exists $encoding{$name})
239     {
240         return $encoding{$name};
241     }
242     if (exists $encoding{$lc})
243     {
244         return $encoding{$lc};
245     }
246     if (exists $external_tables{$lc})
247     {
248         require $external_tables{$lc};
249         return $encoding{$name} if exists $encoding{$name};
250     }
251
252     my $oc = $class->findAlias($name);
253     return $oc if defined $oc;
254     return $class->findAlias($lc) if $lc ne $name;
255
256     return;
257 }
258
259 sub find_encoding
260 {
261     my ($name) = @_;
262     return __PACKAGE__->getEncoding($name);
263 }
264
265 sub encode
266 {
267     my ($name,$string,$check) = @_;
268     my $enc = find_encoding($name);
269     croak("Unknown encoding '$name'") unless defined $enc;
270     my $octets = $enc->encode($string,$check);
271     return undef if ($check && length($string));
272     return $octets;
273 }
274
275 sub decode
276 {
277     my ($name,$octets,$check) = @_;
278     my $enc = find_encoding($name);
279     croak("Unknown encoding '$name'") unless defined $enc;
280     my $string = $enc->decode($octets,$check);
281     $_[1] = $octets if $check;
282     return $string;
283 }
284
285 sub from_to
286 {
287     my ($string,$from,$to,$check) = @_;
288     my $f = find_encoding($from);
289     croak("Unknown encoding '$from'") unless defined $f;
290     my $t = find_encoding($to);
291     croak("Unknown encoding '$to'") unless defined $t;
292     my $uni = $f->decode($string,$check);
293     return undef if ($check && length($string));
294     $string = $t->encode($uni,$check);
295     return undef if ($check && length($uni));
296     return length($_[0] = $string);
297 }
298
299 sub encode_utf8
300 {
301     my ($str) = @_;
302   utf8::encode($str);
303     return $str;
304 }
305
306 sub decode_utf8
307 {
308     my ($str) = @_;
309     return undef unless utf8::decode($str);
310     return $str;
311 }
312
313 require Encode::Encoding;
314 require Encode::XS;
315 require Encode::Internal;
316 require Encode::Unicode;
317 require Encode::utf8;
318 require Encode::iso10646_1;
319 require Encode::ucs2_le;
320
321 1;
322
323 __END__
324
325 =head1 NAME
326
327 Encode - character encodings
328
329 =head1 SYNOPSIS
330
331     use Encode;
332
333 =head1 DESCRIPTION
334
335 The C<Encode> module provides the interfaces between Perl's strings
336 and the rest of the system.  Perl strings are sequences of B<characters>.
337
338 The repertoire of characters that Perl can represent is at least that
339 defined by the Unicode Consortium. On most platforms the ordinal
340 values of the characters (as returned by C<ord(ch)>) is the "Unicode
341 codepoint" for the character (the exceptions are those platforms where
342 the legacy encoding is some variant of EBCDIC rather than a super-set
343 of ASCII - see L<perlebcdic>).
344
345 Traditionaly computer data has been moved around in 8-bit chunks
346 often called "bytes". These chunks are also known as "octets" in
347 networking standards. Perl is widely used to manipulate data of
348 many types - not only strings of characters representing human or
349 computer languages but also "binary" data being the machines representation
350 of numbers, pixels in an image - or just about anything.
351
352 When Perl is processing "binary data" the programmer wants Perl to process
353 "sequences of bytes". This is not a problem for Perl - as a byte has 256
354 possible values it easily fits in Perl's much larger "logical character".
355
356 Due to size concerns, each of B<CJK> (Chinese, Japanese & Korean) modules
357 are not loaded in memory until the first time they're used. Although you
358 don't have to C<use> the corresponding B<Encode::>(B<TW>|B<CN>|B<JP>|B<KR>)
359 modules first, be aware that those encodings will not be in C<%encodings>
360 until their module is loaded (either implicitly through using encodings
361 contained in the same module, or via an explicit C<use>).
362
363 =head2 TERMINOLOGY
364
365 =over 4
366
367 =item *
368
369 I<character>: a character in the range 0..(2**32-1) (or more).
370 (What Perl's strings are made of.)
371
372 =item *
373
374 I<byte>: a character in the range 0..255
375 (A special case of a Perl character.)
376
377 =item *
378
379 I<octet>: 8 bits of data, with ordinal values 0..255
380 (Term for bytes passed to or from a non-Perl context, e.g. disk file.)
381
382 =back
383
384 The marker [INTERNAL] marks Internal Implementation Details, in
385 general meant only for those who think they know what they are doing,
386 and such details may change in future releases.
387
388 =head1 ENCODINGS
389
390 =head2 Characteristics of an Encoding
391
392 An encoding has a "repertoire" of characters that it can represent,
393 and for each representable character there is at least one sequence of
394 octets that represents it.
395
396 =head2 Types of Encodings
397
398 Encodings can be divided into the following types:
399
400 =over 4
401
402 =item * Fixed length 8-bit (or less) encodings.
403
404 Each character is a single octet so may have a repertoire of up to
405 256 characters. ASCII and iso-8859-* are typical examples.
406
407 =item * Fixed length 16-bit encodings
408
409 Each character is two octets so may have a repertoire of up to
410 65 536 characters.  Unicode's UCS-2 is an example.  Also used for
411 encodings for East Asian languages.
412
413 =item * Fixed length 32-bit encodings.
414
415 Not really very "encoded" encodings. The Unicode code points
416 are just represented as 4-octet integers. None the less because
417 different architectures use different representations of integers
418 (so called "endian") there at least two disctinct encodings.
419
420 =item * Multi-byte encodings
421
422 The number of octets needed to represent a character varies.
423 UTF-8 is a particularly complex but regular case of a multi-byte
424 encoding. Several East Asian countries use a multi-byte encoding
425 where 1-octet is used to cover western roman characters and Asian
426 characters get 2-octets.
427 (UTF-16 is strictly a multi-byte encoding taking either 2 or 4 octets
428 to represent a Unicode code point.)
429
430 =item * "Escape" encodings.
431
432 These encodings embed "escape sequences" into the octet sequence
433 which describe how the following octets are to be interpreted.
434 The iso-2022-* family is typical. Following the escape sequence
435 octets are encoded by an "embedded" encoding (which will be one
436 of the above types) until another escape sequence switches to
437 a different "embedded" encoding.
438
439 These schemes are very flexible and can handle mixed languages but are
440 very complex to process (and have state).  No escape encodings are
441 implemented for Perl yet.
442
443 =back
444
445 =head2 Specifying Encodings
446
447 Encodings can be specified to the API described below in two ways:
448
449 =over 4
450
451 =item 1. By name
452
453 Encoding names are strings with characters taken from a restricted
454 repertoire.  See L</"Encoding Names">.
455
456 =item 2. As an object
457
458 Encoding objects are returned by C<find_encoding($name)>.
459
460 =back
461
462 =head2 Encoding Names
463
464 Encoding names are case insensitive. White space in names is ignored.
465 In addition an encoding may have aliases. Each encoding has one
466 "canonical" name.  The "canonical" name is chosen from the names of
467 the encoding by picking the first in the following sequence:
468
469 =over 4
470
471 =item * The MIME name as defined in IETF RFCs.
472
473 =item * The name in the IANA registry.
474
475 =item * The name used by the organization that defined it.
476
477 =back
478
479 Because of all the alias issues, and because in the general case
480 encodings have state C<Encode> uses the encoding object internally
481 once an operation is in progress.
482
483 As of Perl 5.8.0, at least the following encodings are recognized
484 (the => marks aliases):
485
486   ASCII
487
488   US-ASCII => ASCII
489
490 The Unicode:
491
492   UTF-8
493   UTF-16
494   UCS-2
495
496   ISO 10646-1 => UCS-2
497
498 The ISO 8859 and KOI:
499
500   ISO 8859-1  ISO 8859-6   ISO 8859-11         KOI8-F
501   ISO 8859-2  ISO 8859-7   (12 doesn't exist)  KOI8-R
502   ISO 8859-3  ISO 8859-8   ISO 8859-13         KOI8-U
503   ISO 8859-4  ISO 8859-9   ISO 8859-14
504   ISO 8859-5  ISO 8859-10  ISO 8859-15
505                            ISO 8859-16
506
507   Latin1  => 8859-1  Latin6  => 8859-10
508   Latin2  => 8859-2  Latin7  => 8859-13
509   Latin3  => 8859-3  Latin8  => 8859-14
510   Latin4  => 8859-4  Latin9  => 8859-15
511   Latin5  => 8859-9  Latin10 => 8859-16
512
513   Cyrillic => 8859-5
514   Arabic   => 8859-6
515   Greek    => 8859-7
516   Hebrew   => 8859-8
517   Thai     => 8859-11
518   TIS620   => 8859-11
519
520 The CJKV: Chinese, Japanese, Korean, Vietnamese:
521
522   ISO 2022     ISO 2022 JP-1  JIS 0201  GB 1988   Big5       EUC-CN
523   ISO 2022 CN  ISO 2022 JP-2  JIS 0208  GB 2312   HZ         EUC-JP
524   ISO 2022 JP  ISO 2022 KR    JIS 0210  GB 12345  CNS 11643  EUC-JP-0212
525   Shift-JIS                             GBK       Big5-HKSCS EUC-KR
526   VISCII                                ISO-IR-165
527
528 (Due to size concerns, additional Chinese encodings including C<GB 18030>,
529 C<EUC-TW> and C<BIG5PLUS> are distributed separately on CPAN, under the name
530 L<Encode::HanExtra>.)
531
532 The PC codepages:
533
534   CP37   CP852  CP861  CP866  CP949   CP1251  CP1256
535   CP424  CP855  CP862  CP869  CP950   CP1252  CP1257
536   CP737  CP856  CP863  CP874  CP1006  CP1253  CP1258
537   CP775  CP857  CP864  CP932  CP1047  CP1254
538   CP850  CP860  CP865  CP936  CP1250  CP1255
539
540   WinLatin1     => CP1252
541   WinLatin2     => CP1250
542   WinCyrillic   => CP1251
543   WinGreek      => CP1253
544   WinTurkiskh   => CP1254
545   WinHebrew     => CP1255
546   WinArabic     => CP1256
547   WinBaltic     => CP1257
548   WinVietnamese => CP1258
549
550 (All the CPI<NNN...> are available also as IBMI<NNN...>.)
551
552 The Mac codepages:
553
554   MacCentralEuropean   MacJapanese
555   MacCroatian          MacRoman
556   MacCyrillic          MacRomanian
557   MacDingbats          MacSami
558   MacGreek             MacThai
559   MacIcelandic         MacTurkish
560                        MacUkraine
561
562 Miscellaneous:
563
564   7bit-greek  IR-197
565   7bit-kana   NeXTstep
566   7bit-latin1 POSIX-BC
567   DingBats    Roman8
568   GSM 0338    Symbol
569
570 =head1 PERL ENCODING API
571
572 =head2 Generic Encoding Interface
573
574 =over 4
575
576 =item *
577
578         $bytes  = encode(ENCODING, $string[, CHECK])
579
580 Encodes string from Perl's internal form into I<ENCODING> and returns
581 a sequence of octets.  For CHECK see L</"Handling Malformed Data">.
582
583 For example to convert (internally UTF-8 encoded) Unicode data
584 to octets:
585
586         $octets = encode("utf8", $unicode);
587
588 =item *
589
590         $string = decode(ENCODING, $bytes[, CHECK])
591
592 Decode sequence of octets assumed to be in I<ENCODING> into Perl's
593 internal form and returns the resulting string.  For CHECK see
594 L</"Handling Malformed Data">.
595
596 For example to convert ISO 8859-1 data to UTF-8:
597
598         $utf8 = decode("latin1", $latin1);
599
600 =item *
601
602         from_to($string, FROM_ENCODING, TO_ENCODING[, CHECK])
603
604 Convert B<in-place> the data between two encodings.  How did the data
605 in $string originally get to be in FROM_ENCODING?  Either using
606 encode() or through PerlIO: See L</"Encoding and IO">.  For CHECK
607 see L</"Handling Malformed Data">.
608
609 For example to convert ISO 8859-1 data to UTF-8:
610
611         from_to($data, "iso-8859-1", "utf-8");
612
613 and to convert it back:
614
615         from_to($data, "utf-8", "iso-8859-1");
616
617 Note that because the conversion happens in place, the data to be
618 converted cannot be a string constant, it must be a scalar variable.
619
620 =back
621
622 =head2 Handling Malformed Data
623
624 If CHECK is not set, C<undef> is returned.  If the data is supposed to
625 be UTF-8, an optional lexical warning (category utf8) is given.  If
626 CHECK is true but not a code reference, dies.
627
628 It would desirable to have a way to indicate that transform should use
629 the encodings "replacement character" - no such mechanism is defined yet.
630
631 It is also planned to allow I<CHECK> to be a code reference.
632
633 This is not yet implemented as there are design issues with what its
634 arguments should be and how it returns its results.
635
636 =over 4
637
638 =item Scheme 1
639
640 Passed remaining fragment of string being processed.
641 Modifies it in place to remove bytes/characters it can understand
642 and returns a string used to represent them.
643 e.g.
644
645  sub fixup {
646    my $ch = substr($_[0],0,1,'');
647    return sprintf("\x{%02X}",ord($ch);
648  }
649
650 This scheme is close to how underlying C code for Encode works, but gives
651 the fixup routine very little context.
652
653 =item Scheme 2
654
655 Passed original string, and an index into it of the problem area, and
656 output string so far.  Appends what it will to output string and
657 returns new index into original string.  For example:
658
659  sub fixup {
660    # my ($s,$i,$d) = @_;
661    my $ch = substr($_[0],$_[1],1);
662    $_[2] .= sprintf("\x{%02X}",ord($ch);
663    return $_[1]+1;
664  }
665
666 This scheme gives maximal control to the fixup routine but is more
667 complicated to code, and may need internals of Encode to be tweaked to
668 keep original string intact.
669
670 =item Other Schemes
671
672 Hybrids of above.
673
674 Multiple return values rather than in-place modifications.
675
676 Index into the string could be pos($str) allowing s/\G...//.
677
678 =back
679
680 =head2 UTF-8 / utf8
681
682 The Unicode consortium defines the UTF-8 standard as a way of encoding
683 the entire Unicode repertiore as sequences of octets.  This encoding is
684 expected to become very widespread. Perl can use this form internaly
685 to represent strings, so conversions to and from this form are
686 particularly efficient (as octets in memory do not have to change,
687 just the meta-data that tells Perl how to treat them).
688
689 =over 4
690
691 =item *
692
693         $bytes = encode_utf8($string);
694
695 The characters that comprise string are encoded in Perl's superset of UTF-8
696 and the resulting octets returned as a sequence of bytes. All possible
697 characters have a UTF-8 representation so this function cannot fail.
698
699 =item *
700
701         $string = decode_utf8($bytes [,CHECK]);
702
703 The sequence of octets represented by $bytes is decoded from UTF-8
704 into a sequence of logical characters. Not all sequences of octets
705 form valid UTF-8 encodings, so it is possible for this call to fail.
706 For CHECK see L</"Handling Malformed Data">.
707
708 =back
709
710 =head2 Other Encodings of Unicode
711
712 UTF-16 is similar to UCS-2, 16 bit or 2-byte chunks.  UCS-2 can only
713 represent 0..0xFFFF, while UTF-16 has a I<surrogate pair> scheme which
714 allows it to cover the whole Unicode range.
715
716 Surrogates are code points set aside to encode the 0x01000..0x10FFFF
717 range of Unicode code points in pairs of 16-bit units.  The I<high
718 surrogates> are the range 0xD800..0xDBFF, and the I<low surrogates>
719 are the range 0xDC00..0xDFFFF.  The surrogate encoding is
720
721         $hi = ($uni - 0x10000) / 0x400 + 0xD800;
722         $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
723
724 and the decoding is
725
726         $uni = 0x10000 + ($hi - 0xD8000) * 0x400 + ($lo - 0xDC00);
727
728 Encode implements big-endian UCS-2 aliased to "iso-10646-1" as that
729 happens to be the name used by that representation when used with X11
730 fonts.
731
732 UTF-32 or UCS-4 is 32-bit or 4-byte chunks.  Perl's logical characters
733 can be considered as being in this form without encoding. An encoding
734 to transfer strings in this form (e.g. to write them to a file) would
735 need to
736
737      pack('L*', unpack('U*', $string));  # native
738   or
739      pack('V*', unpack('U*', $string));  # little-endian
740   or
741      pack('N*', unpack('U*', $string));  # big-endian
742
743 depending on the endianness required.
744
745 No UTF-32 encodings are implemented yet.
746
747 Both UCS-2 and UCS-4 style encodings can have "byte order marks" by
748 representing the code point 0xFFFE as the very first thing in a file.
749
750 =head2 Listing available encodings
751
752   use Encode qw(encodings);
753   @list = encodings();
754
755 Returns a list of the canonical names of the available encodings.
756
757 =head2 Defining Aliases
758
759   use Encode qw(define_alias);
760   define_alias( newName => ENCODING);
761
762 Allows newName to be used as am alias for ENCODING. ENCODING may be
763 either the name of an encoding or and encoding object (as above).
764
765 Currently I<newName> can be specified in the following ways:
766
767 =over 4
768
769 =item As a simple string.
770
771 =item As a qr// compiled regular expression, e.g.:
772
773   define_alias( qr/^iso8859-(\d+)$/i => '"iso-8859-$1"' );
774
775 In this case if I<ENCODING> is not a reference it is C<eval>-ed to
776 allow C<$1> etc. to be subsituted.  The example is one way to names as
777 used in X11 font names to alias the MIME names for the iso-8859-*
778 family.
779
780 =item As a code reference, e.g.:
781
782   define_alias( sub { return /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } , '');
783
784 In this case C<$_> will be set to the name that is being looked up and
785 I<ENCODING> is passed to the sub as its first argument.  The example
786 is another way to names as used in X11 font names to alias the MIME
787 names for the iso-8859-* family.
788
789 =back
790
791 =head2 Defining Encodings
792
793     use Encode qw(define_alias);
794     define_encoding( $object, 'canonicalName' [,alias...]);
795
796 Causes I<canonicalName> to be associated with I<$object>.  The object
797 should provide the interface described in L</"IMPLEMENTATION CLASSES">
798 below.  If more than two arguments are provided then additional
799 arguments are taken as aliases for I<$object> as for C<define_alias>.
800
801 =head1 Encoding and IO
802
803 It is very common to want to do encoding transformations when
804 reading or writing files, network connections, pipes etc.
805 If Perl is configured to use the new 'perlio' IO system then
806 C<Encode> provides a "layer" (See L<perliol>) which can transform
807 data as it is read or written.
808
809 Here is how the blind poet would modernise the encoding:
810
811     use Encode;
812     open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
813     open(my $utf8,'>:utf8','iliad.utf8');
814     my @epic = <$iliad>;
815     print $utf8 @epic;
816     close($utf8);
817     close($illiad);
818
819 In addition the new IO system can also be configured to read/write
820 UTF-8 encoded characters (as noted above this is efficient):
821
822     open(my $fh,'>:utf8','anything');
823     print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
824
825 Either of the above forms of "layer" specifications can be made the default
826 for a lexical scope with the C<use open ...> pragma. See L<open>.
827
828 Once a handle is open is layers can be altered using C<binmode>.
829
830 Without any such configuration, or if Perl itself is built using
831 system's own IO, then write operations assume that file handle accepts
832 only I<bytes> and will C<die> if a character larger than 255 is
833 written to the handle. When reading, each octet from the handle
834 becomes a byte-in-a-character. Note that this default is the same
835 behaviour as bytes-only languages (including Perl before v5.6) would
836 have, and is sufficient to handle native 8-bit encodings
837 e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling
838 other encodings and binary data.
839
840 In other cases it is the programs responsibility to transform
841 characters into bytes using the API above before doing writes, and to
842 transform the bytes read from a handle into characters before doing
843 "character operations" (e.g. C<lc>, C</\W+/>, ...).
844
845 You can also use PerlIO to convert larger amounts of data you don't
846 want to bring into memory.  For example to convert between ISO 8859-1
847 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
848
849     open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
850     open(G, ">:utf8",                 "data.utf") or die $!;
851     while (<F>) { print G }
852
853     # Could also do "print G <F>" but that would pull
854     # the whole file into memory just to write it out again.
855
856 More examples:
857
858     open(my $f, "<:encoding(cp1252)")
859     open(my $g, ">:encoding(iso-8859-2)")
860     open(my $h, ">:encoding(latin9)")       # iso-8859-15
861
862 See L<PerlIO> for more information.
863
864 See also L<encoding> for how to change the default encoding of the
865 data in your script.
866
867 =head1 Encoding How to ...
868
869 To do:
870
871 =over 4
872
873 =item * IO with mixed content (faking iso-2020-*)
874
875 =item * MIME's Content-Length:
876
877 =item * UTF-8 strings in binary data.
878
879 =item * Perl/Encode wrappers on non-Unicode XS modules.
880
881 =back
882
883 =head1 Messing with Perl's Internals
884
885 The following API uses parts of Perl's internals in the current
886 implementation.  As such they are efficient, but may change.
887
888 =over 4
889
890 =item * is_utf8(STRING [, CHECK])
891
892 [INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
893 If CHECK is true, also checks the data in STRING for being well-formed
894 UTF-8.  Returns true if successful, false otherwise.
895
896 =item * valid_utf8(STRING)
897
898 [INTERNAL] Test whether STRING is in a consistent state.  Will return
899 true if string is held as bytes, or is well-formed UTF-8 and has the
900 UTF-8 flag on.  Main reason for this routine is to allow Perl's
901 testsuite to check that operations have left strings in a consistent
902 state.
903
904 =item *
905
906         _utf8_on(STRING)
907
908 [INTERNAL] Turn on the UTF-8 flag in STRING.  The data in STRING is
909 B<not> checked for being well-formed UTF-8.  Do not use unless you
910 B<know> that the STRING is well-formed UTF-8.  Returns the previous
911 state of the UTF-8 flag (so please don't test the return value as
912 I<not> success or failure), or C<undef> if STRING is not a string.
913
914 =item *
915
916         _utf8_off(STRING)
917
918 [INTERNAL] Turn off the UTF-8 flag in STRING.  Do not use frivolously.
919 Returns the previous state of the UTF-8 flag (so please don't test the
920 return value as I<not> success or failure), or C<undef> if STRING is
921 not a string.
922
923 =back
924
925 =head1 IMPLEMENTATION CLASSES
926
927 As mentioned above encodings are (in the current implementation at least)
928 defined by objects. The mapping of encoding name to object is via the
929 C<%encodings> hash.
930
931 The values of the hash can currently be either strings or objects.
932 The string form may go away in the future. The string form occurs
933 when C<encodings()> has scanned C<@INC> for loadable encodings but has
934 not actually loaded the encoding in question. This is because the
935 current "loading" process is all Perl and a bit slow.
936
937 Once an encoding is loaded then value of the hash is object which
938 implements the encoding. The object should provide the following
939 interface:
940
941 =over 4
942
943 =item -E<gt>name
944
945 Should return the string representing the canonical name of the encoding.
946
947 =item -E<gt>new_sequence
948
949 This is a placeholder for encodings with state. It should return an
950 object which implements this interface, all current implementations
951 return the original object.
952
953 =item -E<gt>encode($string,$check)
954
955 Should return the octet sequence representing I<$string>. If I<$check>
956 is true it should modify I<$string> in place to remove the converted
957 part (i.e.  the whole string unless there is an error).  If an error
958 occurs it should return the octet sequence for the fragment of string
959 that has been converted, and modify $string in-place to remove the
960 converted part leaving it starting with the problem fragment.
961
962 If check is is false then C<encode> should make a "best effort" to
963 convert the string - for example by using a replacement character.
964
965 =item -E<gt>decode($octets,$check)
966
967 Should return the string that I<$octets> represents. If I<$check> is
968 true it should modify I<$octets> in place to remove the converted part
969 (i.e.  the whole sequence unless there is an error).  If an error
970 occurs it should return the fragment of string that has been
971 converted, and modify $octets in-place to remove the converted part
972 leaving it starting with the problem fragment.
973
974 If check is is false then C<decode> should make a "best effort" to
975 convert the string - for example by using Unicode's "\x{FFFD}" as a
976 replacement character.
977
978 =back
979
980 It should be noted that the check behaviour is different from the
981 outer public API. The logic is that the "unchecked" case is useful
982 when encoding is part of a stream which may be reporting errors
983 (e.g. STDERR).  In such cases it is desirable to get everything
984 through somehow without causing additional errors which obscure the
985 original one. Also the encoding is best placed to know what the
986 correct replacement character is, so if that is the desired behaviour
987 then letting low level code do it is the most efficient.
988
989 In contrast if check is true, the scheme above allows the encoding to
990 do as much as it can and tell layer above how much that was. What is
991 lacking at present is a mechanism to report what went wrong. The most
992 likely interface will be an additional method call to the object, or
993 perhaps (to avoid forcing per-stream objects on otherwise stateless
994 encodings) and additional parameter.
995
996 It is also highly desirable that encoding classes inherit from
997 C<Encode::Encoding> as a base class. This allows that class to define
998 additional behaviour for all encoding objects. For example built in
999 Unicode, UCS-2 and UTF-8 classes use :
1000
1001   package Encode::MyEncoding;
1002   use base qw(Encode::Encoding);
1003
1004   __PACKAGE__->Define(qw(myCanonical myAlias));
1005
1006 To create an object with bless {Name => ...},$class, and call
1007 define_encoding.  They inherit their C<name> method from
1008 C<Encode::Encoding>.
1009
1010 =head2 Compiled Encodings
1011
1012 F<Encode.xs> provides a class C<Encode::XS> which provides the
1013 interface described above. It calls a generic octet-sequence to
1014 octet-sequence "engine" that is driven by tables (defined in
1015 F<encengine.c>). The same engine is used for both encode and
1016 decode. C<Encode:XS>'s C<encode> forces Perl's characters to their
1017 UTF-8 form and then treats them as just another multibyte
1018 encoding. C<Encode:XS>'s C<decode> transforms the sequence and then
1019 turns the UTF-8-ness flag as that is the form that the tables are
1020 defined to produce. For details of the engine see the comments in
1021 F<encengine.c>.
1022
1023 The tables are produced by the Perl script F<compile> (the name needs
1024 to change so we can eventually install it somewhere). F<compile> can
1025 currently read two formats:
1026
1027 =over 4
1028
1029 =item *.enc
1030
1031 This is a coined format used by Tcl. It is documented in
1032 Encode/EncodeFormat.pod.
1033
1034 =item *.ucm
1035
1036 This is the semi-standard format used by IBM's ICU package.
1037
1038 =back
1039
1040 F<compile> can write the following forms:
1041
1042 =over 4
1043
1044 =item *.ucm
1045
1046 See above - the F<Encode/*.ucm> files provided with the distribution have
1047 been created from the original Tcl .enc files using this approach.
1048
1049 =item *.c
1050
1051 Produces tables as C data structures - this is used to build in encodings
1052 into F<Encode.so>/F<Encode.dll>.
1053
1054 =item *.xs
1055
1056 In theory this allows encodings to be stand-alone loadable Perl
1057 extensions.  The process has not yet been tested. The plan is to use
1058 this approach for large East Asian encodings.
1059
1060 =back
1061
1062 The set of encodings built-in to F<Encode.so>/F<Encode.dll> is
1063 determined by F<Makefile.PL>.  The current set is as follows:
1064
1065 =over 4
1066
1067 =item ascii and iso-8859-*
1068
1069 That is all the common 8-bit "western" encodings.
1070
1071 =item IBM-1047 and two other variants of EBCDIC.
1072
1073 These are the same variants that are supported by EBCDIC Perl as
1074 "native" encodings.  They are included to prove "reversibility" of
1075 some constructs in EBCDIC Perl.
1076
1077 =item symbol and dingbats as used by Tk on X11.
1078
1079 (The reason Encode got started was to support Perl/Tk.)
1080
1081 =back
1082
1083 That set is rather ad hoc and has been driven by the needs of the
1084 tests rather than the needs of typical applications. It is likely
1085 to be rationalized.
1086
1087 =head1 SEE ALSO
1088
1089 L<perlunicode>, L<perlebcdic>, L<perlfunc/open>, L<PerlIO>, L<encoding>
1090
1091 =cut
1092