3 our $VERSION = do { my @r = (q$Revision: 0.98 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
9 our @ISA = qw(Exporter DynaLoader);
11 # Public, encouraged API is exported by default
36 # Documentation moved after __END__ for speed - NI-S
40 our $ON_EBCDIC = (ord("A") == 193);
43 # Make a %Encoding package variable to allow a certain amount of cheating
48 viscii => 'Encode/Byte.pm',
49 'koi8-r' => 'Encode/Byte.pm',
50 cp1047 => 'Encode/EBCDIC.pm',
51 cp37 => 'Encode/EBCDIC.pm',
52 'posix-bc' => 'Encode/EBCDIC.pm',
53 symbol => 'Encode/Symbol.pm',
54 dingbats => 'Encode/Symbol.pm',
57 for my $k (2..11,13..16){
58 $ExtModule{"iso-8859-$k"} = 'Encode/Byte.pm';
61 for my $k (1250..1258){
62 $ExtModule{"cp$k"} = 'Encode/Byte.pm';
65 unless ($ON_EBCDIC) { # CJK added to autoload unless EBCDIC env
68 'euc-cn' => 'Encode/CN.pm',
69 gb2312 => 'Encode/CN.pm',
70 gb12345 => 'Encode/CN.pm',
71 gbk => 'Encode/CN.pm',
72 cp936 => 'Encode/CN.pm',
73 'iso-ir-165' => 'Encode/CN.pm',
74 'euc-jp' => 'Encode/JP.pm',
75 'iso-2022-jp' => 'Encode/JP.pm',
76 'iso-2022-jp-1' => 'Encode/JP.pm',
77 '7bit-jis' => 'Encode/JP.pm',
78 shiftjis => 'Encode/JP.pm',
79 macjapan => 'Encode/JP.pm',
80 cp932 => 'Encode/JP.pm',
81 'euc-kr' => 'Encode/KR.pm',
82 ksc5601 => 'Encode/KR.pm',
83 cp949 => 'Encode/KR.pm',
84 big5 => 'Encode/TW.pm',
85 'big5-hkscs' => 'Encode/TW.pm',
86 cp950 => 'Encode/TW.pm',
87 gb18030 => 'Encode/HanExtra.pm',
88 big5plus => 'Encode/HanExtra.pm',
89 'euc-tw' => 'Encode/HanExtra.pm',
93 for my $k (qw(centeuro croatian cyrillic dingbats greek
94 iceland roman rumanian sami
95 thai turkish ukraine))
97 $ExtModule{"mac$k"} = 'Encode/Byte.pm';
104 my @modules = (@_ and $_[0] eq ":all") ? values %ExtModule : @_;
107 $DEBUG and warn "about to require $m;";
108 eval { require $m; };
112 sort({$a->[1] cmp $b->[1]}
114 grep({ $_ ne 'Internal' } keys %Encoding))));
121 $Encoding{$name} = $obj;
123 define_alias($lc => $obj) unless $lc eq $name;
127 define_alias($alias,$obj);
134 my ($class,$name,$skip_external) = @_;
136 if (ref($name) && $name->can('new_sequence'))
141 if (exists $Encoding{$name})
143 return $Encoding{$name};
145 if (exists $Encoding{$lc})
147 return $Encoding{$lc};
150 my $oc = $class->find_alias($name);
151 return $oc if defined $oc;
153 $oc = $class->find_alias($lc) if $lc ne $name;
154 return $oc if defined $oc;
156 if (!$skip_external and exists $ExtModule{$lc})
158 eval{ require $ExtModule{$lc}; };
159 return $Encoding{$name} if exists $Encoding{$name};
167 my ($name,$skip_external) = @_;
168 return __PACKAGE__->getEncoding($name,$skip_external);
173 my ($name,$string,$check) = @_;
174 my $enc = find_encoding($name);
175 croak("Unknown encoding '$name'") unless defined $enc;
176 my $octets = $enc->encode($string,$check);
177 return undef if ($check && length($string));
183 my ($name,$octets,$check) = @_;
184 my $enc = find_encoding($name);
185 croak("Unknown encoding '$name'") unless defined $enc;
186 my $string = $enc->decode($octets,$check);
187 $_[1] = $octets if $check;
193 my ($string,$from,$to,$check) = @_;
194 my $f = find_encoding($from);
195 croak("Unknown encoding '$from'") unless defined $f;
196 my $t = find_encoding($to);
197 croak("Unknown encoding '$to'") unless defined $t;
198 my $uni = $f->decode($string,$check);
199 return undef if ($check && length($string));
200 $string = $t->encode($uni,$check);
201 return undef if ($check && length($uni));
202 return length($_[0] = $string);
215 return undef unless utf8::decode($str);
219 require Encode::Encoding;
221 require Encode::Internal;
222 require Encode::Unicode;
223 require Encode::utf8;
224 require Encode::iso10646_1;
225 require Encode::ucs2_le;
233 Encode - character encodings
241 The C<Encode> module provides the interfaces between Perl's strings
242 and the rest of the system. Perl strings are sequences of B<characters>.
244 To find more about character encodings, please consult
245 L<Encode::Details>. This document focuses on programming references.
247 =head1 PERL ENCODING API
249 =head2 Generic Encoding Interface
253 =item $bytes = encode(ENCODING, $string[, CHECK])
255 Encodes string from Perl's internal form into I<ENCODING> and returns
256 a sequence of octets. For CHECK see L</"Handling Malformed Data">.
258 For example to convert (internally UTF-8 encoded) Unicode data
261 $octets = encode("utf8", $unicode);
263 =item $string = decode(ENCODING, $bytes[, CHECK])
265 Decode sequence of octets assumed to be in I<ENCODING> into Perl's
266 internal form and returns the resulting string. For CHECK see
267 L</"Handling Malformed Data">.
269 For example to convert ISO-8859-1 data to UTF-8:
271 $utf8 = decode("latin1", $latin1);
273 =item from_to($string, FROM_ENCODING, TO_ENCODING[, CHECK])
275 Convert B<in-place> the data between two encodings. How did the data
276 in $string originally get to be in FROM_ENCODING? Either using
277 encode() or through PerlIO: See L</"Encoding and IO">. For CHECK
278 see L</"Handling Malformed Data">.
280 For example to convert ISO-8859-1 data to UTF-8:
282 from_to($data, "iso-8859-1", "utf-8");
284 and to convert it back:
286 from_to($data, "utf-8", "iso-8859-1");
288 Note that because the conversion happens in place, the data to be
289 converted cannot be a string constant, it must be a scalar variable.
293 =head2 Handling Malformed Data
295 If CHECK is not set, C<undef> is returned. If the data is supposed to
296 be UTF-8, an optional lexical warning (category utf8) is given. If
297 CHECK is true but not a code reference, dies.
299 It would desirable to have a way to indicate that transform should use
300 the encodings "replacement character" - no such mechanism is defined yet.
302 It is also planned to allow I<CHECK> to be a code reference.
304 This is not yet implemented as there are design issues with what its
305 arguments should be and how it returns its results.
311 Passed remaining fragment of string being processed.
312 Modifies it in place to remove bytes/characters it can understand
313 and returns a string used to represent them.
317 my $ch = substr($_[0],0,1,'');
318 return sprintf("\x{%02X}",ord($ch);
321 This scheme is close to how underlying C code for Encode works, but gives
322 the fixup routine very little context.
326 Passed original string, and an index into it of the problem area, and
327 output string so far. Appends what it will to output string and
328 returns new index into original string. For example:
331 # my ($s,$i,$d) = @_;
332 my $ch = substr($_[0],$_[1],1);
333 $_[2] .= sprintf("\x{%02X}",ord($ch);
337 This scheme gives maximal control to the fixup routine but is more
338 complicated to code, and may need internals of Encode to be tweaked to
339 keep original string intact.
345 Multiple return values rather than in-place modifications.
347 Index into the string could be C<pos($str)> allowing C<s/\G...//>.
353 The Unicode consortium defines the UTF-8 standard as a way of encoding
354 the entire Unicode repertoire as sequences of octets. This encoding is
355 expected to become very widespread. Perl can use this form internally
356 to represent strings, so conversions to and from this form are
357 particularly efficient (as octets in memory do not have to change,
358 just the meta-data that tells Perl how to treat them).
362 =item $bytes = encode_utf8($string);
364 The characters that comprise string are encoded in Perl's superset of UTF-8
365 and the resulting octets returned as a sequence of bytes. All possible
366 characters have a UTF-8 representation so this function cannot fail.
368 =item $string = decode_utf8($bytes [, CHECK]);
370 The sequence of octets represented by $bytes is decoded from UTF-8
371 into a sequence of logical characters. Not all sequences of octets
372 form valid UTF-8 encodings, so it is possible for this call to fail.
373 For CHECK see L</"Handling Malformed Data">.
377 =head2 Listing available encodings
380 @list = Encode->encodings();
382 Returns a list of the canonical names of the available encodings that
383 are loaded. To get a list of all available encodings including the
384 ones that are not loaded yet, say
386 @all_encodings = Encode->encodings(":all");
388 Or you can give the name of specific module.
390 @with_jp = Encode->encodings("Encode/JP.pm");
392 Note in this case you have to say C<"Encode/JP.pm"> instead of
395 To find which encodings are supported by this package in details,
396 see L<Encode::Supported>.
398 =head2 Defining Aliases
402 define_alias(newName => ENCODING);
404 Allows newName to be used as am alias for ENCODING. ENCODING may be
405 either the name of an encoding or and encoding object (as above).
407 See L<Encode::Alias> on details.
409 =head1 Defining Encodings
411 use Encode qw(define_alias);
412 define_encoding($object, 'canonicalName' [, alias...]);
414 Causes I<canonicalName> to be associated with I<$object>. The object
415 should provide the interface described in L<Encode::Encoding>
416 below. If more than two arguments are provided then additional
417 arguments are taken as aliases for I<$object> as for C<define_alias>.
419 =head1 Encoding and IO
421 It is very common to want to do encoding transformations when
422 reading or writing files, network connections, pipes etc.
423 If Perl is configured to use the new 'perlio' IO system then
424 C<Encode> provides a "layer" (See L<perliol>) which can transform
425 data as it is read or written.
427 Here is how the blind poet would modernise the encoding:
430 open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
431 open(my $utf8,'>:utf8','iliad.utf8');
437 In addition the new IO system can also be configured to read/write
438 UTF-8 encoded characters (as noted above this is efficient):
440 open(my $fh,'>:utf8','anything');
441 print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
443 Either of the above forms of "layer" specifications can be made the default
444 for a lexical scope with the C<use open ...> pragma. See L<open>.
446 Once a handle is open is layers can be altered using C<binmode>.
448 Without any such configuration, or if Perl itself is built using
449 system's own IO, then write operations assume that file handle accepts
450 only I<bytes> and will C<die> if a character larger than 255 is
451 written to the handle. When reading, each octet from the handle
452 becomes a byte-in-a-character. Note that this default is the same
453 behaviour as bytes-only languages (including Perl before v5.6) would
454 have, and is sufficient to handle native 8-bit encodings
455 e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling
456 other encodings and binary data.
458 In other cases it is the programs responsibility to transform
459 characters into bytes using the API above before doing writes, and to
460 transform the bytes read from a handle into characters before doing
461 "character operations" (e.g. C<lc>, C</\W+/>, ...).
463 You can also use PerlIO to convert larger amounts of data you don't
464 want to bring into memory. For example to convert between ISO-8859-1
465 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
467 open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
468 open(G, ">:utf8", "data.utf") or die $!;
469 while (<F>) { print G }
471 # Could also do "print G <F>" but that would pull
472 # the whole file into memory just to write it out again.
476 open(my $f, "<:encoding(cp1252)")
477 open(my $g, ">:encoding(iso-8859-2)")
478 open(my $h, ">:encoding(latin9)") # iso-8859-15
480 See L<PerlIO> for more information.
482 See also L<encoding> for how to change the default encoding of the
485 =head1 Messing with Perl's Internals
487 The following API uses parts of Perl's internals in the current
488 implementation. As such they are efficient, but may change.
492 =item is_utf8(STRING [, CHECK])
494 [INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
495 If CHECK is true, also checks the data in STRING for being well-formed
496 UTF-8. Returns true if successful, false otherwise.
498 =item _utf8_on(STRING)
500 [INTERNAL] Turn on the UTF-8 flag in STRING. The data in STRING is
501 B<not> checked for being well-formed UTF-8. Do not use unless you
502 B<know> that the STRING is well-formed UTF-8. Returns the previous
503 state of the UTF-8 flag (so please don't test the return value as
504 I<not> success or failure), or C<undef> if STRING is not a string.
506 =item _utf8_off(STRING)
508 [INTERNAL] Turn off the UTF-8 flag in STRING. Do not use frivolously.
509 Returns the previous state of the UTF-8 flag (so please don't test the
510 return value as I<not> success or failure), or C<undef> if STRING is
519 L<Encode::Supported>,
526 the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>