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