This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Encode to CPAN version 2.54
[perl5.git] / cpan / Encode / Encode.pm
1 #
2 # $Id: Encode.pm,v 2.54 2013/08/29 16:47:39 dankogai Exp dankogai $
3 #
4 package Encode;
5 use strict;
6 use warnings;
7 our $VERSION = sprintf "%d.%02d", q$Revision: 2.54 $ =~ /(\d+)/g;
8 use constant DEBUG => !!$ENV{PERL_ENCODE_DEBUG};
9 use XSLoader ();
10 XSLoader::load( __PACKAGE__, $VERSION );
11
12 require Exporter;
13 use base qw/Exporter/;
14
15 # Public, encouraged API is exported by default
16
17 our @EXPORT = qw(
18   decode  decode_utf8  encode  encode_utf8 str2bytes bytes2str
19   encodings  find_encoding clone_encoding
20 );
21 our @FB_FLAGS = qw(
22   DIE_ON_ERR WARN_ON_ERR RETURN_ON_ERR LEAVE_SRC
23   PERLQQ HTMLCREF XMLCREF STOP_AT_PARTIAL
24 );
25 our @FB_CONSTS = qw(
26   FB_DEFAULT FB_CROAK FB_QUIET FB_WARN
27   FB_PERLQQ FB_HTMLCREF FB_XMLCREF
28 );
29 our @EXPORT_OK = (
30     qw(
31       _utf8_off _utf8_on define_encoding from_to is_16bit is_8bit
32       is_utf8 perlio_ok resolve_alias utf8_downgrade utf8_upgrade
33       ),
34     @FB_FLAGS, @FB_CONSTS,
35 );
36
37 our %EXPORT_TAGS = (
38     all          => [ @EXPORT,    @EXPORT_OK ],
39     default      => [ @EXPORT ],
40     fallbacks    => [ @FB_CONSTS ],
41     fallback_all => [ @FB_CONSTS, @FB_FLAGS ],
42 );
43
44 # Documentation moved after __END__ for speed - NI-S
45
46 our $ON_EBCDIC = ( ord("A") == 193 );
47
48 use Encode::Alias;
49
50 # Make a %Encoding package variable to allow a certain amount of cheating
51 our %Encoding;
52 our %ExtModule;
53 require Encode::Config;
54 #  See
55 #  https://bugzilla.redhat.com/show_bug.cgi?id=435505#c2
56 #  to find why sig handlers inside eval{} are disabled.
57 eval {
58     local $SIG{__DIE__};
59     local $SIG{__WARN__};
60     require Encode::ConfigLocal;
61 };
62
63 sub encodings {
64     my %enc;
65     my $arg  = $_[1] || '';
66     if ( $arg eq ":all" ) {
67         %enc = ( %Encoding, %ExtModule );
68     }
69     else {
70         %enc = %Encoding;
71         for my $mod ( map { m/::/ ? $_ : "Encode::$_" } @_ ) {
72             DEBUG and warn $mod;
73             for my $enc ( keys %ExtModule ) {
74                 $ExtModule{$enc} eq $mod and $enc{$enc} = $mod;
75             }
76         }
77     }
78     return sort { lc $a cmp lc $b }
79       grep      { !/^(?:Internal|Unicode|Guess)$/o } keys %enc;
80 }
81
82 sub perlio_ok {
83     my $obj = ref( $_[0] ) ? $_[0] : find_encoding( $_[0] );
84     $obj->can("perlio_ok") and return $obj->perlio_ok();
85     return 0;    # safety net
86 }
87
88 sub define_encoding {
89     my $obj  = shift;
90     my $name = shift;
91     $Encoding{$name} = $obj;
92     my $lc = lc($name);
93     define_alias( $lc => $obj ) unless $lc eq $name;
94     while (@_) {
95         my $alias = shift;
96         define_alias( $alias, $obj );
97     }
98     return $obj;
99 }
100
101 sub getEncoding {
102     my ( $class, $name, $skip_external ) = @_;
103
104     $name =~ s/\s+//g; # https://rt.cpan.org/Ticket/Display.html?id=65796
105
106     ref($name) && $name->can('renew') and return $name;
107     exists $Encoding{$name} and return $Encoding{$name};
108     my $lc = lc $name;
109     exists $Encoding{$lc} and return $Encoding{$lc};
110
111     my $oc = $class->find_alias($name);
112     defined($oc) and return $oc;
113     $lc ne $name and $oc = $class->find_alias($lc);
114     defined($oc) and return $oc;
115
116     unless ($skip_external) {
117         if ( my $mod = $ExtModule{$name} || $ExtModule{$lc} ) {
118             $mod =~ s,::,/,g;
119             $mod .= '.pm';
120             eval { require $mod; };
121             exists $Encoding{$name} and return $Encoding{$name};
122         }
123     }
124     return;
125 }
126
127 sub find_encoding($;$) {
128     my ( $name, $skip_external ) = @_;
129     return __PACKAGE__->getEncoding( $name, $skip_external );
130 }
131
132 sub resolve_alias($) {
133     my $obj = find_encoding(shift);
134     defined $obj and return $obj->name;
135     return;
136 }
137
138 sub clone_encoding($) {
139     my $obj = find_encoding(shift);
140     ref $obj or return;
141     eval { require Storable };
142     $@ and return;
143     return Storable::dclone($obj);
144 }
145
146 sub encode($$;$) {
147     my ( $name, $string, $check ) = @_;
148     return undef unless defined $string;
149     $string .= '';    # stringify;
150     $check ||= 0;
151     unless ( defined $name ) {
152         require Carp;
153         Carp::croak("Encoding name should not be undef");
154     }
155     my $enc = find_encoding($name);
156     unless ( defined $enc ) {
157         require Carp;
158         Carp::croak("Unknown encoding '$name'");
159     }
160     my $octets = $enc->encode( $string, $check );
161     $_[1] = $string if $check and !ref $check and !( $check & LEAVE_SRC() );
162     return $octets;
163 }
164 *str2bytes = \&encode;
165
166 sub decode($$;$) {
167     my ( $name, $octets, $check ) = @_;
168     return undef unless defined $octets;
169     $octets .= '';
170     $check ||= 0;
171     my $enc = find_encoding($name);
172     unless ( defined $enc ) {
173         require Carp;
174         Carp::croak("Unknown encoding '$name'");
175     }
176     my $string = $enc->decode( $octets, $check );
177     $_[1] = $octets if $check and !ref $check and !( $check & LEAVE_SRC() );
178     return $string;
179 }
180 *bytes2str = \&decode;
181
182 sub from_to($$$;$) {
183     my ( $string, $from, $to, $check ) = @_;
184     return undef unless defined $string;
185     $check ||= 0;
186     my $f = find_encoding($from);
187     unless ( defined $f ) {
188         require Carp;
189         Carp::croak("Unknown encoding '$from'");
190     }
191     my $t = find_encoding($to);
192     unless ( defined $t ) {
193         require Carp;
194         Carp::croak("Unknown encoding '$to'");
195     }
196     my $uni = $f->decode($string);
197     $_[0] = $string = $t->encode( $uni, $check );
198     return undef if ( $check && length($uni) );
199     return defined( $_[0] ) ? length($string) : undef;
200 }
201
202 sub encode_utf8($) {
203     my ($str) = @_;
204     utf8::encode($str);
205     return $str;
206 }
207
208 my $utf8enc;
209
210 sub decode_utf8($;$) {
211     my ( $octets, $check ) = @_;
212     return undef unless defined $octets;
213     $octets .= '' if ref $octets;
214     $check   ||= 0;
215     $utf8enc ||= find_encoding('utf8');
216     my $string = $utf8enc->decode( $octets, $check );
217     $_[0] = $octets if $check and !ref $check and !( $check & LEAVE_SRC() );
218     return $string;
219 }
220
221 # sub decode_utf8($;$) {
222 #     my ( $str, $check ) = @_;
223 #     return $str if is_utf8($str);
224 #     if ($check) {
225 #         return decode( "utf8", $str, $check );
226 #     }
227 #     else {
228 #         return decode( "utf8", $str );
229 #         return $str;
230 #     }
231 # }
232
233 predefine_encodings(1);
234
235 #
236 # This is to restore %Encoding if really needed;
237 #
238
239 sub predefine_encodings {
240     require Encode::Encoding;
241     no warnings 'redefine';
242     my $use_xs = shift;
243     if ($ON_EBCDIC) {
244
245         # was in Encode::UTF_EBCDIC
246         package Encode::UTF_EBCDIC;
247         push @Encode::UTF_EBCDIC::ISA, 'Encode::Encoding';
248         *decode = sub {
249             my ( undef, $str, $chk ) = @_;
250             my $res = '';
251             for ( my $i = 0 ; $i < length($str) ; $i++ ) {
252                 $res .=
253                   chr(
254                     utf8::unicode_to_native( ord( substr( $str, $i, 1 ) ) )
255                   );
256             }
257             $_[1] = '' if $chk;
258             return $res;
259         };
260         *encode = sub {
261             my ( undef, $str, $chk ) = @_;
262             my $res = '';
263             for ( my $i = 0 ; $i < length($str) ; $i++ ) {
264                 $res .=
265                   chr(
266                     utf8::native_to_unicode( ord( substr( $str, $i, 1 ) ) )
267                   );
268             }
269             $_[1] = '' if $chk;
270             return $res;
271         };
272         $Encode::Encoding{Unicode} =
273           bless { Name => "UTF_EBCDIC" } => "Encode::UTF_EBCDIC";
274     }
275     else {
276
277         package Encode::Internal;
278         push @Encode::Internal::ISA, 'Encode::Encoding';
279         *decode = sub {
280             my ( undef, $str, $chk ) = @_;
281             utf8::upgrade($str);
282             $_[1] = '' if $chk;
283             return $str;
284         };
285         *encode = \&decode;
286         $Encode::Encoding{Unicode} =
287           bless { Name => "Internal" } => "Encode::Internal";
288     }
289
290     {
291
292         # was in Encode::utf8
293         package Encode::utf8;
294         push @Encode::utf8::ISA, 'Encode::Encoding';
295
296         #
297         if ($use_xs) {
298             Encode::DEBUG and warn __PACKAGE__, " XS on";
299             *decode = \&decode_xs;
300             *encode = \&encode_xs;
301         }
302         else {
303             Encode::DEBUG and warn __PACKAGE__, " XS off";
304             *decode = sub {
305                 my ( undef, $octets, $chk ) = @_;
306                 my $str = Encode::decode_utf8($octets);
307                 if ( defined $str ) {
308                     $_[1] = '' if $chk;
309                     return $str;
310                 }
311                 return undef;
312             };
313             *encode = sub {
314                 my ( undef, $string, $chk ) = @_;
315                 my $octets = Encode::encode_utf8($string);
316                 $_[1] = '' if $chk;
317                 return $octets;
318             };
319         }
320         *cat_decode = sub {    # ($obj, $dst, $src, $pos, $trm, $chk)
321                                # currently ignores $chk
322             my ( undef, undef, undef, $pos, $trm ) = @_;
323             my ( $rdst, $rsrc, $rpos ) = \@_[ 1, 2, 3 ];
324             use bytes;
325             if ( ( my $npos = index( $$rsrc, $trm, $pos ) ) >= 0 ) {
326                 $$rdst .=
327                   substr( $$rsrc, $pos, $npos - $pos + length($trm) );
328                 $$rpos = $npos + length($trm);
329                 return 1;
330             }
331             $$rdst .= substr( $$rsrc, $pos );
332             $$rpos = length($$rsrc);
333             return '';
334         };
335         $Encode::Encoding{utf8} =
336           bless { Name => "utf8" } => "Encode::utf8";
337         $Encode::Encoding{"utf-8-strict"} =
338           bless { Name => "utf-8-strict", strict_utf8 => 1 } 
339             => "Encode::utf8";
340     }
341 }
342
343 1;
344
345 __END__
346
347 =head1 NAME
348
349 Encode - character encodings in Perl
350
351 =head1 SYNOPSIS
352
353     use Encode qw(decode encode);
354     $characters = decode('UTF-8', $octets,     Encode::FB_CROAK);
355     $octets     = encode('UTF-8', $characters, Encode::FB_CROAK);
356
357 =head2 Table of Contents
358
359 Encode consists of a collection of modules whose details are too extensive
360 to fit in one document.  This one itself explains the top-level APIs
361 and general topics at a glance.  For other topics and more details,
362 see the documentation for these modules:
363
364 =over 2
365
366 =item L<Encode::Alias> - Alias definitions to encodings
367
368 =item L<Encode::Encoding> - Encode Implementation Base Class
369
370 =item L<Encode::Supported> - List of Supported Encodings
371
372 =item L<Encode::CN> - Simplified Chinese Encodings
373
374 =item L<Encode::JP> - Japanese Encodings
375
376 =item L<Encode::KR> - Korean Encodings
377
378 =item L<Encode::TW> - Traditional Chinese Encodings
379
380 =back
381
382 =head1 DESCRIPTION
383
384 The C<Encode> module provides the interface between Perl strings
385 and the rest of the system.  Perl strings are sequences of
386 I<characters>.
387
388 The repertoire of characters that Perl can represent is a superset of those
389 defined by the Unicode Consortium. On most platforms the ordinal
390 values of a character as returned by C<ord(I<S>)> is the I<Unicode
391 codepoint> for that character. The exceptions are platforms where
392 the legacy encoding is some variant of EBCDIC rather than a superset
393 of ASCII; see L<perlebcdic>.
394
395 During recent history, data is moved around a computer in 8-bit chunks,
396 often called "bytes" but also known as "octets" in standards documents.
397 Perl is widely used to manipulate data of many types: not only strings of
398 characters representing human or computer languages, but also "binary"
399 data, being the machine's representation of numbers, pixels in an image, or
400 just about anything.
401
402 When Perl is processing "binary data", the programmer wants Perl to
403 process "sequences of bytes". This is not a problem for Perl: because a
404 byte has 256 possible values, it easily fits in Perl's much larger
405 "logical character".
406
407 This document mostly explains the I<how>. L<perlunitut> and L<perlunifaq>
408 explain the I<why>.
409
410 =head2 TERMINOLOGY
411
412 =head3 character
413
414 A character in the range 0 .. 2**32-1 (or more);
415 what Perl's strings are made of.
416
417 =head3 byte
418
419 A character in the range 0..255;
420 a special case of a Perl character.
421
422 =head3 octet
423
424 8 bits of data, with ordinal values 0..255;
425 term for bytes passed to or from a non-Perl context, such as a disk file,
426 standard I/O stream, database, command-line argument, environment variable,
427 socket etc.
428
429 =head1 THE PERL ENCODING API
430
431 =head2 Basic methods
432
433 =head3 encode
434
435   $octets  = encode(ENCODING, STRING[, CHECK])
436
437 Encodes the scalar value I<STRING> from Perl's internal form into
438 I<ENCODING> and returns a sequence of octets.  I<ENCODING> can be either a
439 canonical name or an alias.  For encoding names and aliases, see
440 L</"Defining Aliases">.  For CHECK, see L</"Handling Malformed Data">.
441
442 For example, to convert a string from Perl's internal format into
443 ISO-8859-1, also known as Latin1:
444
445   $octets = encode("iso-8859-1", $string);
446
447 B<CAVEAT>: When you run C<$octets = encode("utf8", $string)>, then
448 $octets I<might not be equal to> $string.  Though both contain the
449 same data, the UTF8 flag for $octets is I<always> off.  When you
450 encode anything, the UTF8 flag on the result is always off, even when it
451 contains a completely valid utf8 string. See L</"The UTF8 flag"> below.
452
453 If the $string is C<undef>, then C<undef> is returned.
454
455 =head3 decode
456
457   $string = decode(ENCODING, OCTETS[, CHECK])
458
459 This function returns the string that results from decoding the scalar
460 value I<OCTETS>, assumed to be a sequence of octets in I<ENCODING>, into
461 Perl's internal form.  The returns the resulting string.  As with encode(),
462 I<ENCODING> can be either a canonical name or an alias. For encoding names
463 and aliases, see L</"Defining Aliases">; for I<CHECK>, see L</"Handling
464 Malformed Data">.
465
466 For example, to convert ISO-8859-1 data into a string in Perl's
467 internal format:
468
469   $string = decode("iso-8859-1", $octets);
470
471 B<CAVEAT>: When you run C<$string = decode("utf8", $octets)>, then $string
472 I<might not be equal to> $octets.  Though both contain the same data, the
473 UTF8 flag for $string is on.  See L</"The UTF8 flag">
474 below.
475
476 If the $string is C<undef>, then C<undef> is returned.
477
478 =head3 find_encoding
479
480   [$obj =] find_encoding(ENCODING)
481
482 Returns the I<encoding object> corresponding to I<ENCODING>.  Returns
483 C<undef> if no matching I<ENCODING> is find.  The returned object is
484 what does the actual encoding or decoding.
485
486   $utf8 = decode($name, $bytes);
487
488 is in fact
489
490     $utf8 = do {
491         $obj = find_encoding($name);
492         croak qq(encoding "$name" not found) unless ref $obj;
493         $obj->decode($bytes);
494     };
495
496 with more error checking.
497
498 You can therefore save time by reusing this object as follows;
499
500     my $enc = find_encoding("iso-8859-1");
501     while(<>) {
502         my $utf8 = $enc->decode($_);
503         ... # now do something with $utf8;
504     }
505
506 Besides L</decode> and L</encode>, other methods are
507 available as well.  For instance, C<name()> returns the canonical
508 name of the encoding object.
509
510   find_encoding("latin1")->name; # iso-8859-1
511
512 See L<Encode::Encoding> for details.
513
514 =head3 from_to
515
516   [$length =] from_to($octets, FROM_ENC, TO_ENC [, CHECK])
517
518 Converts I<in-place> data between two encodings. The data in $octets
519 must be encoded as octets and I<not> as characters in Perl's internal
520 format. For example, to convert ISO-8859-1 data into Microsoft's CP1250
521 encoding:
522
523   from_to($octets, "iso-8859-1", "cp1250");
524
525 and to convert it back:
526
527   from_to($octets, "cp1250", "iso-8859-1");
528
529 Because the conversion happens in place, the data to be
530 converted cannot be a string constant: it must be a scalar variable.
531
532 C<from_to()> returns the length of the converted string in octets on success,
533 and C<undef> on error.
534
535 B<CAVEAT>: The following operations may look the same, but are not:
536
537   from_to($data, "iso-8859-1", "utf8"); #1
538   $data = decode("iso-8859-1", $data);  #2
539
540 Both #1 and #2 make $data consist of a completely valid UTF-8 string,
541 but only #2 turns the UTF8 flag on.  #1 is equivalent to:
542
543   $data = encode("utf8", decode("iso-8859-1", $data));
544
545 See L</"The UTF8 flag"> below.
546
547 Also note that:
548
549   from_to($octets, $from, $to, $check);
550
551 is equivalent t:o
552
553   $octets = encode($to, decode($from, $octets), $check);
554
555 Yes, it does I<not> respect the $check during decoding.  It is
556 deliberately done that way.  If you need minute control, use C<decode>
557 followed by C<encode> as follows:
558
559   $octets = encode($to, decode($from, $octets, $check_from), $check_to);
560
561 =head3 encode_utf8
562
563   $octets = encode_utf8($string);
564
565 Equivalent to C<$octets = encode("utf8", $string)>.  The characters in
566 $string are encoded in Perl's internal format, and the result is returned
567 as a sequence of octets.  Because all possible characters in Perl have a
568 (loose, not strict) UTF-8 representation, this function cannot fail.
569
570 =head3 decode_utf8
571
572   $string = decode_utf8($octets [, CHECK]);
573
574 Equivalent to C<$string = decode("utf8", $octets [, CHECK])>.
575 The sequence of octets represented by $octets is decoded
576 from UTF-8 into a sequence of logical characters.
577 Because not all sequences of octets are valid UTF-8,
578 it is quite possible for this function to fail.
579 For CHECK, see L</"Handling Malformed Data">.
580
581 =head2 Listing available encodings
582
583   use Encode;
584   @list = Encode->encodings();
585
586 Returns a list of canonical names of available encodings that have already
587 been loaded.  To get a list of all available encodings including those that
588 have not yet been loaded, say:
589
590   @all_encodings = Encode->encodings(":all");
591
592 Or you can give the name of a specific module:
593
594   @with_jp = Encode->encodings("Encode::JP");
595
596 When "C<::>" is not in the name, "C<Encode::>" is assumed.
597
598   @ebcdic = Encode->encodings("EBCDIC");
599
600 To find out in detail which encodings are supported by this package,
601 see L<Encode::Supported>.
602
603 =head2 Defining Aliases
604
605 To add a new alias to a given encoding, use:
606
607   use Encode;
608   use Encode::Alias;
609   define_alias(NEWNAME => ENCODING);
610
611 After that, I<NEWNAME> can be used as an alias for I<ENCODING>.
612 I<ENCODING> may be either the name of an encoding or an
613 I<encoding object>.
614
615 Before you do that, first make sure the alias is nonexistent using
616 C<resolve_alias()>, which returns the canonical name thereof.
617 For example:
618
619   Encode::resolve_alias("latin1") eq "iso-8859-1" # true
620   Encode::resolve_alias("iso-8859-12")   # false; nonexistent
621   Encode::resolve_alias($name) eq $name  # true if $name is canonical
622
623 C<resolve_alias()> does not need C<use Encode::Alias>; it can be
624 imported via C<use Encode qw(resolve_alias)>.
625
626 See L<Encode::Alias> for details.
627
628 =head2 Finding IANA Character Set Registry names
629
630 The canonical name of a given encoding does not necessarily agree with
631 IANA Character Set Registry, commonly seen as C<< Content-Type:
632 text/plain; charset=I<WHATEVER> >>.  For most cases, the canonical name
633 works, but sometimes it does not, most notably with "utf-8-strict".
634
635 As of C<Encode> version 2.21, a new method C<mime_name()> is therefore added.
636
637   use Encode;
638   my $enc = find_encoding("UTF-8");
639   warn $enc->name;      # utf-8-strict
640   warn $enc->mime_name; # UTF-8
641
642 See also:  L<Encode::Encoding>
643
644 =head1 Encoding via PerlIO
645
646 If your perl supports C<PerlIO> (which is the default), you can use a
647 C<PerlIO> layer to decode and encode directly via a filehandle.  The
648 following two examples are fully identical in functionality:
649
650   ### Version 1 via PerlIO
651     open(INPUT,  "< :encoding(shiftjis)", $infile)
652         || die "Can't open < $infile for reading: $!";
653     open(OUTPUT, "> :encoding(euc-jp)",  $outfile)
654         || die "Can't open > $output for writing: $!";
655     while (<INPUT>) {   # auto decodes $_
656         print OUTPUT;   # auto encodes $_
657     }
658     close(INPUT)   || die "can't close $infile: $!";
659     close(OUTPUT)  || die "can't close $outfile: $!";
660
661   ### Version 2 via from_to()
662     open(INPUT,  "< :raw", $infile)
663         || die "Can't open < $infile for reading: $!";
664     open(OUTPUT, "> :raw",  $outfile)
665         || die "Can't open > $output for writing: $!";
666
667     while (<INPUT>) {
668         from_to($_, "shiftjis", "euc-jp", 1);  # switch encoding
669         print OUTPUT;   # emit raw (but properly encoded) data
670     }
671     close(INPUT)   || die "can't close $infile: $!";
672     close(OUTPUT)  || die "can't close $outfile: $!";
673
674 In the first version above, you let the appropriate encoding layer
675 handle the conversion.  In the second, you explicitly translate
676 from one encoding to the other.
677
678 Unfortunately, it may be that encodings are C<PerlIO>-savvy.  You can check
679 to see whether your encoding is supported by C<PerlIO> by invoking the
680 C<perlio_ok> method on it:
681
682   Encode::perlio_ok("hz");             # false
683   find_encoding("euc-cn")->perlio_ok;  # true wherever PerlIO is available
684
685   use Encode qw(perlio_ok);            # imported upon request
686   perlio_ok("euc-jp")
687
688 Fortunately, all encodings that come with C<Encode> core are C<PerlIO>-savvy
689 except for C<hz> and C<ISO-2022-kr>.  For the gory details, see
690 L<Encode::Encoding> and L<Encode::PerlIO>.
691
692 =head1 Handling Malformed Data
693
694 The optional I<CHECK> argument tells C<Encode> what to do when
695 encountering malformed data.  Without I<CHECK>, C<Encode::FB_DEFAULT>
696 (== 0) is assumed.
697
698 As of version 2.12, C<Encode> supports coderef values for C<CHECK>;
699 see below.
700
701 B<NOTE:> Not all encodings support this feature.
702 Some encodings ignore the I<CHECK> argument.  For example,
703 L<Encode::Unicode> ignores I<CHECK> and it always croaks on error.
704
705 =head2 List of I<CHECK> values
706
707 =head3 FB_DEFAULT
708
709   I<CHECK> = Encode::FB_DEFAULT ( == 0)
710
711 If I<CHECK> is 0, encoding and decoding replace any malformed character
712 with a I<substitution character>.  When you encode, I<SUBCHAR> is used.
713 When you decode, the Unicode REPLACEMENT CHARACTER, code point U+FFFD, is
714 used.  If the data is supposed to be UTF-8, an optional lexical warning of
715 warning category C<"utf8"> is given.
716
717 =head3 FB_CROAK
718
719   I<CHECK> = Encode::FB_CROAK ( == 1)
720
721 If I<CHECK> is 1, methods immediately die with an error
722 message.  Therefore, when I<CHECK> is 1, you should trap
723 exceptions with C<eval{}>, unless you really want to let it C<die>.
724
725 =head3 FB_QUIET
726
727   I<CHECK> = Encode::FB_QUIET
728
729 If I<CHECK> is set to C<Encode::FB_QUIET>, encoding and decoding immediately
730 return the portion of the data that has been processed so far when an
731 error occurs. The data argument is overwritten with everything
732 after that point; that is, the unprocessed portion of the data.  This is
733 handy when you have to call C<decode> repeatedly in the case where your
734 source data may contain partial multi-byte character sequences,
735 (that is, you are reading with a fixed-width buffer). Here's some sample
736 code to do exactly that:
737
738     my($buffer, $string) = ("", "");
739     while (read($fh, $buffer, 256, length($buffer))) {
740         $string .= decode($encoding, $buffer, Encode::FB_QUIET);
741         # $buffer now contains the unprocessed partial character
742     }
743
744 =head3 FB_WARN
745
746   I<CHECK> = Encode::FB_WARN
747
748 This is the same as C<FB_QUIET> above, except that instead of being silent
749 on errors, it issues a warning.  This is handy for when you are debugging.
750
751 =head3 FB_PERLQQ FB_HTMLCREF FB_XMLCREF
752
753 =over 2
754
755 =item perlqq mode (I<CHECK> = Encode::FB_PERLQQ)
756
757 =item HTML charref mode (I<CHECK> = Encode::FB_HTMLCREF)
758
759 =item XML charref mode (I<CHECK> = Encode::FB_XMLCREF)
760
761 =back
762
763 For encodings that are implemented by the C<Encode::XS> module, C<CHECK> C<==>
764 C<Encode::FB_PERLQQ> puts C<encode> and C<decode> into C<perlqq> fallback mode.
765
766 When you decode, C<\xI<HH>> is inserted for a malformed character, where
767 I<HH> is the hex representation of the octet that could not be decoded to
768 utf8.  When you encode, C<\x{I<HHHH>}> will be inserted, where I<HHHH> is
769 the Unicode code point (in any number of hex digits) of the character that
770 cannot be found in the character repertoire of the encoding.
771
772 The HTML/XML character reference modes are about the same. In place of
773 C<\x{I<HHHH>}>, HTML uses C<&#I<NNN>;> where I<NNN> is a decimal number, and
774 XML uses C<&#xI<HHHH>;> where I<HHHH> is the hexadecimal number.
775
776 In C<Encode> 2.10 or later, C<LEAVE_SRC> is also implied.
777
778 =head3 The bitmask
779
780 These modes are all actually set via a bitmask.  Here is how the C<FB_I<XXX>>
781 constants are laid out.  You can import the C<FB_I<XXX>> constants via
782 C<use Encode qw(:fallbacks)>, and you can import the generic bitmask
783 constants via C<use Encode qw(:fallback_all)>.
784
785                      FB_DEFAULT FB_CROAK FB_QUIET FB_WARN  FB_PERLQQ
786  DIE_ON_ERR    0x0001             X
787  WARN_ON_ERR   0x0002                               X
788  RETURN_ON_ERR 0x0004                      X        X
789  LEAVE_SRC     0x0008                                        X
790  PERLQQ        0x0100                                        X
791  HTMLCREF      0x0200
792  XMLCREF       0x0400
793
794 =head3 LEAVE_SRC
795
796   Encode::LEAVE_SRC
797
798 If the C<Encode::LEAVE_SRC> bit is I<not> set but I<CHECK> is set, then the
799 source string to encode() or decode() will be overwritten in place.
800 If you're not interested in this, then bitwise-OR it with the bitmask.
801
802 =head2 coderef for CHECK
803
804 As of C<Encode> 2.12, C<CHECK> can also be a code reference which takes the
805 ordinal value of the unmapped character as an argument and returns a string
806 that represents the fallback character.  For instance:
807
808   $ascii = encode("ascii", $utf8, sub{ sprintf "<U+%04X>", shift });
809
810 Acts like C<FB_PERLQQ> but U+I<XXXX> is used instead of C<\x{I<XXXX>}>.
811
812 =head1 Defining Encodings
813
814 To define a new encoding, use:
815
816     use Encode qw(define_encoding);
817     define_encoding($object, CANONICAL_NAME [, alias...]);
818
819 I<CANONICAL_NAME> will be associated with I<$object>.  The object
820 should provide the interface described in L<Encode::Encoding>.
821 If more than two arguments are provided, additional
822 arguments are considered aliases for I<$object>.
823
824 See L<Encode::Encoding> for details.
825
826 =head1 The UTF8 flag
827
828 Before the introduction of Unicode support in Perl, The C<eq> operator
829 just compared the strings represented by two scalars. Beginning with
830 Perl 5.8, C<eq> compares two strings with simultaneous consideration of
831 I<the UTF8 flag>. To explain why we made it so, I quote from page 402 of
832 I<Programming Perl, 3rd ed.>
833
834 =over 2
835
836 =item Goal #1:
837
838 Old byte-oriented programs should not spontaneously break on the old
839 byte-oriented data they used to work on.
840
841 =item Goal #2:
842
843 Old byte-oriented programs should magically start working on the new
844 character-oriented data when appropriate.
845
846 =item Goal #3:
847
848 Programs should run just as fast in the new character-oriented mode
849 as in the old byte-oriented mode.
850
851 =item Goal #4:
852
853 Perl should remain one language, rather than forking into a
854 byte-oriented Perl and a character-oriented Perl.
855
856 =back
857
858 When I<Programming Perl, 3rd ed.> was written, not even Perl 5.6.0 had been
859 born yet, many features documented in the book remained unimplemented for a
860 long time.  Perl 5.8 corrected much of this, and the introduction of the
861 UTF8 flag is one of them.  You can think of there being two fundamentally
862 different kinds of strings and string-operations in Perl: one a
863 byte-oriented mode  for when the internal UTF8 flag is off, and the other a
864 character-oriented mode for when the internal UTF8 flag is on.
865
866 Here is how C<Encode> handles the UTF8 flag.
867
868 =over 2
869
870 =item *
871
872 When you I<encode>, the resulting UTF8 flag is always B<off>.
873
874 =item *
875
876 When you I<decode>, the resulting UTF8 flag is B<on>--I<unless> you can
877 unambiguously represent data.  Here is what we mean by "unambiguously".
878 After C<$utf8 = decode("foo", $octet)>,
879
880   When $octet is...   The UTF8 flag in $utf8 is
881   ---------------------------------------------
882   In ASCII only (or EBCDIC only)            OFF
883   In ISO-8859-1                              ON
884   In any other Encoding                      ON
885   ---------------------------------------------
886
887 As you see, there is one exception: in ASCII.  That way you can assume
888 Goal #1.  And with C<Encode>, Goal #2 is assumed but you still have to be
889 careful in the cases mentioned in the B<CAVEAT> paragraphs above.
890
891 This UTF8 flag is not visible in Perl scripts, exactly for the same reason
892 you cannot (or rather, you I<don't have to>) see whether a scalar contains
893 a string, an integer, or a floating-point number.   But you can still peek
894 and poke these if you will.  See the next section.
895
896 =back
897
898 =head2 Messing with Perl's Internals
899
900 The following API uses parts of Perl's internals in the current
901 implementation.  As such, they are efficient but may change in a future
902 release.
903
904 =head3 is_utf8
905
906   is_utf8(STRING [, CHECK])
907
908 [INTERNAL] Tests whether the UTF8 flag is turned on in the I<STRING>.
909 If I<CHECK> is true, also checks whether I<STRING> contains well-formed
910 UTF-8.  Returns true if successful, false otherwise.
911
912 As of Perl 5.8.1, L<utf8> also has the C<utf8::is_utf8> function.
913
914 =head3 _utf8_on
915
916   _utf8_on(STRING)
917
918 [INTERNAL] Turns the I<STRING>'s internal UTF8 flag B<on>.  The I<STRING>
919 is I<not> checked for containing only well-formed UTF-8.  Do not use this
920 unless you I<know with absolute certainty> that the STRING holds only
921 well-formed UTF-8.  Returns the previous state of the UTF8 flag (so please
922 don't treat the return value as indicating success or failure), or C<undef>
923 if I<STRING> is not a string.
924
925 B<NOTE>: For security reasons, this function does not work on tainted values.
926
927 =head3 _utf8_off
928
929   _utf8_off(STRING)
930
931 [INTERNAL] Turns the I<STRING>'s internal UTF8 flag B<off>.  Do not use
932 frivolously.  Returns the previous state of the UTF8 flag, or C<undef> if
933 I<STRING> is not a string.  Do not treat the return value as indicative of
934 success or failure, because that isn't what it means: it is only the
935 previous setting.
936
937 B<NOTE>: For security reasons, this function does not work on tainted values.
938
939 =head1 UTF-8 vs. utf8 vs. UTF8
940
941   ....We now view strings not as sequences of bytes, but as sequences
942   of numbers in the range 0 .. 2**32-1 (or in the case of 64-bit
943   computers, 0 .. 2**64-1) -- Programming Perl, 3rd ed.
944
945 That has historically been Perl's notion of UTF-8, as that is how UTF-8 was
946 first conceived by Ken Thompson when he invented it. However, thanks to
947 later revisions to the applicable standards, official UTF-8 is now rather
948 stricter than that. For example, its range is much narrower (0 .. 0x10_FFFF
949 to cover only 21 bits instead of 32 or 64 bits) and some sequences
950 are not allowed, like those used in surrogate pairs, the 31 non-character
951 code points 0xFDD0 .. 0xFDEF, the last two code points in I<any> plane
952 (0xI<XX>_FFFE and 0xI<XX>_FFFF), all non-shortest encodings, etc.
953
954 The former default in which Perl would always use a loose interpretation of
955 UTF-8 has now been overruled:
956
957   From: Larry Wall <larry@wall.org>
958   Date: December 04, 2004 11:51:58 JST
959   To: perl-unicode@perl.org
960   Subject: Re: Make Encode.pm support the real UTF-8
961   Message-Id: <20041204025158.GA28754@wall.org>
962
963   On Fri, Dec 03, 2004 at 10:12:12PM +0000, Tim Bunce wrote:
964   : I've no problem with 'utf8' being perl's unrestricted uft8 encoding,
965   : but "UTF-8" is the name of the standard and should give the
966   : corresponding behaviour.
967
968   For what it's worth, that's how I've always kept them straight in my
969   head.
970
971   Also for what it's worth, Perl 6 will mostly default to strict but
972   make it easy to switch back to lax.
973
974   Larry
975
976 Got that?  As of Perl 5.8.7, B<"UTF-8"> means UTF-8 in its current
977 sense, which is conservative and strict and security-conscious, whereas
978 B<"utf8"> means UTF-8 in its former sense, which was liberal and loose and
979 lax.  C<Encode> version 2.10 or later thus groks this subtle but critically
980 important distinction between C<"UTF-8"> and C<"utf8">.
981
982   encode("utf8",  "\x{FFFF_FFFF}", 1); # okay
983   encode("UTF-8", "\x{FFFF_FFFF}", 1); # croaks
984
985 In the C<Encode> module, C<"UTF-8"> is actually a canonical name for
986 C<"utf-8-strict">.  That hyphen between the C<"UTF"> and the C<"8"> is
987 critical; without it, C<Encode> goes "liberal" and (perhaps overly-)permissive:
988
989   find_encoding("UTF-8")->name # is 'utf-8-strict'
990   find_encoding("utf-8")->name # ditto. names are case insensitive
991   find_encoding("utf_8")->name # ditto. "_" are treated as "-"
992   find_encoding("UTF8")->name  # is 'utf8'.
993
994 Perl's internal UTF8 flag is called "UTF8", without a hyphen. It indicates
995 whether a string is internally encoded as "utf8", also without a hyphen.
996
997 =head1 SEE ALSO
998
999 L<Encode::Encoding>,
1000 L<Encode::Supported>,
1001 L<Encode::PerlIO>,
1002 L<encoding>,
1003 L<perlebcdic>,
1004 L<perlfunc/open>,
1005 L<perlunicode>, L<perluniintro>, L<perlunifaq>, L<perlunitut>
1006 L<utf8>,
1007 the Perl Unicode Mailing List L<http://lists.perl.org/list/perl-unicode.html>
1008
1009 =head1 MAINTAINER
1010
1011 This project was originated by the late Nick Ing-Simmons and later
1012 maintained by Dan Kogai I<< <dankogai@cpan.org> >>.  See AUTHORS
1013 for a full list of people involved.  For any questions, send mail to
1014 I<< <perl-unicode@perl.org> >> so that we can all share.
1015
1016 While Dan Kogai retains the copyright as a maintainer, credit
1017 should go to all those involved.  See AUTHORS for a list of those
1018 who submitted code to the project.
1019
1020 =head1 COPYRIGHT
1021
1022 Copyright 2002-2013 Dan Kogai I<< <dankogai@cpan.org> >>.
1023
1024 This library is free software; you can redistribute it and/or modify
1025 it under the same terms as Perl itself.
1026
1027 =cut