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