4 use Encode qw(:fallbacks find_encoding);
5 our $VERSION = do { my @r = (q$Revision: 2.0 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
9 our %DEF_SUSPECTS = map { $_ => find_encoding($_) } qw(ascii utf8);
10 $Encode::Encoding{$Canon} =
13 Suspects => { %DEF_SUSPECTS },
16 use base qw(Encode::Encoding);
20 our @EXPORT = qw(guess_encoding);
21 our $NoUTFAutoGuess = 0;
22 our $UTF8_BOM = pack("C3", 0xef, 0xbb, 0xbf);
24 sub import { # Exporter not used so we do it on our own
26 for my $item (@EXPORT){
28 *{"$callpkg\::$item"} = \&{"$item"};
35 my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
36 $self->{Suspects} = { %DEF_SUSPECTS };
37 $self->add_suspects(@_);
42 my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
44 my $e = find_encoding($c) or die "Unknown encoding: $c";
45 $self->{Suspects}{$e->name} = $e;
46 DEBUG and warn "Added: ", $e->name;
51 my ($obj, $octet, $chk) = @_;
52 my $guessed = guess($obj, $octet);
53 unless (ref($guessed)){
55 Carp::croak($guessed);
57 my $utf8 = $guessed->decode($octet, $chk);
58 $_[1] = $octet if $chk;
63 guess($Encode::Encoding{$Canon}, @_);
68 my $obj = ref($class) ? $class : $Encode::Encoding{$Canon};
72 return unless defined $octet and length $octet;
75 if ( Encode::is_utf8($octet) ) {
76 return find_encoding('utf8') unless $NoUTFAutoGuess;
77 Encode::_utf8_off($octet);
81 unless ($NoUTFAutoGuess) {
82 my $BOM = pack('C3', unpack("C3", $octet));
83 return find_encoding('utf8')
84 if (defined $BOM and $BOM eq $UTF8_BOM);
85 $BOM = unpack('N', $octet);
86 return find_encoding('UTF-32')
87 if (defined $BOM and ($BOM == 0xFeFF or $BOM == 0xFFFe0000));
88 $BOM = unpack('n', $octet);
89 return find_encoding('UTF-16')
90 if (defined $BOM and ($BOM == 0xFeFF or $BOM == 0xFFFe));
91 if ($octet =~ /\x00/o){ # if \x00 found, we assume UTF-(16|32)(BE|LE)
93 my ($be, $le) = (0, 0);
94 if ($octet =~ /\x00\x00/o){ # UTF-32(BE|LE) assumed
96 for my $char (unpack('N*', $octet)){
97 $char & 0x0000ffff and $be++;
98 $char & 0xffff0000 and $le++;
100 }else{ # UTF-16(BE|LE) assumed
102 for my $char (unpack('n*', $octet)){
103 $char & 0x00ff and $be++;
104 $char & 0xff00 and $le++;
107 DEBUG and warn "$utf, be == $be, le == $le";
110 "Encodings ambiguous between $utf BE and LE ($be, $le)";
111 $utf .= ($be > $le) ? 'BE' : 'LE';
112 return find_encoding($utf);
115 my %try = %{$obj->{Suspects}};
117 my $e = find_encoding($c) or die "Unknown encoding: $c";
119 DEBUG and warn "Added: ", $e->name;
122 for my $line (split /\r\n?|\n/, $octet){
123 # cheat 2 -- \e in the string
125 my @keys = keys %try;
126 delete @try{qw/utf8 ascii/};
128 ref($try{$k}) eq 'Encode::XS' and delete $try{$k};
132 # warn join(",", keys %try);
133 for my $k (keys %try){
135 $try{$k}->decode($scratch, FB_QUIET);
137 DEBUG and warn sprintf("%4d:%-24s ok\n", $nline, $k);
141 warn sprintf("%4d:%-24s not ok; %d bytes left\n",
142 $nline, $k, bytes::length($scratch));
146 %ok or return "No appropriate encodings found!";
147 if (scalar(keys(%ok)) == 1){
148 my ($retval) = values(%ok);
151 %try = %ok; $nline++;
154 return "Encodings too ambiguous: ", join(" or ", keys %try);
165 Encode::Guess -- Guesses encoding from data
169 # if you are sure $data won't contain anything bogus
172 use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
173 my $utf8 = decode("Guess", $data);
174 my $data = encode("Guess", $utf8); # this doesn't work!
178 my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
179 ref($enc) or die "Can't guess: $enc"; # trap error this way
180 $utf8 = $enc->decode($data);
182 $utf8 = decode($enc->name, $data)
186 Encode::Guess enables you to guess in what encoding a given data is
187 encoded, or at least tries to.
191 By default, it checks only ascii, utf8 and UTF-16/32 with BOM.
193 use Encode::Guess; # ascii/utf8/BOMed UTF
195 To use it more practically, you have to give the names of encodings to
196 check (I<suspects> as follows). The name of suspects can either be
197 canonical names or aliases.
199 CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED.
201 # tries all major Japanese Encodings as well
202 use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
204 If the C<$Encode::Guess::NoUTFAutoGuess> variable is set to a true
205 value, no heuristics will be applied to UTF8/16/32, and the result
206 will be limited to the suspects and C<ascii>.
210 =item Encode::Guess->set_suspects
212 You can also change the internal suspects list via C<set_suspects>
216 Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);
218 =item Encode::Guess->add_suspects
220 Or you can use C<add_suspects> method. The difference is that
221 C<set_suspects> flushes the current suspects list while
222 C<add_suspects> adds.
225 Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
226 # now the suspects are euc-jp,shiftjis,7bit-jis, AND
227 # euc-kr,euc-cn, and big5-eten
228 Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);
230 =item Encode::decode("Guess" ...)
232 When you are content with suspects list, you can now
234 my $utf8 = Encode::decode("Guess", $data);
236 =item Encode::Guess->guess($data)
238 But it will croak if:
244 Two or more suspects remain
252 So you should instead try this;
254 my $decoder = Encode::Guess->guess($data);
256 On success, $decoder is an object that is documented in
257 L<Encode::Encoding>. So you can now do this;
259 my $utf8 = $decoder->decode($data);
261 On failure, $decoder now contains an error message so the whole thing
264 my $decoder = Encode::Guess->guess($data);
265 die $decoder unless ref($decoder);
266 my $utf8 = $decoder->decode($data);
268 =item guess_encoding($data, [, I<list of suspects>])
270 You can also try C<guess_encoding> function which is exported by
271 default. It takes $data to check and it also takes the list of
272 suspects by option. The optional suspect list is I<not reflected> to
273 the internal suspects list.
275 my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
276 die $decoder unless ref($decoder);
277 my $utf8 = $decoder->decode($data);
278 # check only ascii and utf8
279 my $decoder = guess_encoding($data);
289 Because of the algorithm used, ISO-8859 series and other single-byte
290 encodings do not work well unless either one of ISO-8859 is the only
291 one suspect (besides ascii and utf8).
295 my $decoder = guess_encoding($data, 'latin1');
297 my $decoder = guess_encoding($data, qw/latin1 greek/);
299 The reason is that Encode::Guess guesses encoding by trial and error.
300 It first splits $data into lines and tries to decode the line for each
301 suspect. It keeps it going until all but one encoding is eliminated
302 out of suspects list. ISO-8859 series is just too successful for most
303 cases (because it fills almost all code points in \x00-\xff).
307 Do not mix national standard encodings and the corresponding vendor
312 = guess_encoding($data, qw/shiftjis MacJapanese cp932/);
314 The reason is that vendor encoding is usually a superset of national
315 standard so it becomes too ambiguous for most cases.
319 On the other hand, mixing various national standard encodings
320 automagically works unless $data is too short to allow for guessing.
322 # This is ok if $data is long enough
324 guess_encoding($data, qw/euc-cn
325 euc-jp shiftjis 7bit-jis
331 DO NOT PUT TOO MANY SUSPECTS! Don't you try something like this!
333 my $decoder = guess_encoding($data,
334 Encode->encodings(":all"));
338 It is, after all, just a guess. You should alway be explicit when it
339 comes to encodings. But there are some, especially Japanese,
340 environment that guess-coding is a must. Use this module with care.
344 Encode::Guess does not work on EBCDIC platforms.
348 L<Encode>, L<Encode::Encoding>