4 use Encode qw(:fallbacks find_encoding);
5 our $VERSION = do { my @r = ( q$Revision: 2.2 $ =~ /\d+/g ); sprintf "%d." . "%02d" x $#r, @r };
9 our %DEF_SUSPECTS = map { $_ => find_encoding($_) } qw(ascii utf8);
10 $Encode::Encoding{$Canon} = bless {
12 Suspects => {%DEF_SUSPECTS},
15 use base qw(Encode::Encoding);
19 our @EXPORT = qw(guess_encoding);
20 our $NoUTFAutoGuess = 0;
21 our $UTF8_BOM = pack( "C3", 0xef, 0xbb, 0xbf );
23 sub import { # Exporter not used so we do it on our own
25 for my $item (@EXPORT) {
27 *{"$callpkg\::$item"} = \&{"$item"};
34 my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
35 $self->{Suspects} = {%DEF_SUSPECTS};
36 $self->add_suspects(@_);
41 my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
43 my $e = find_encoding($c) or die "Unknown encoding: $c";
44 $self->{Suspects}{ $e->name } = $e;
45 DEBUG and warn "Added: ", $e->name;
50 my ( $obj, $octet, $chk ) = @_;
51 my $guessed = guess( $obj, $octet );
52 unless ( ref($guessed) ) {
54 Carp::croak($guessed);
56 my $utf8 = $guessed->decode( $octet, $chk );
57 $_[1] = $octet if $chk;
62 guess( $Encode::Encoding{$Canon}, @_ );
67 my $obj = ref($class) ? $class : $Encode::Encoding{$Canon};
71 return unless defined $octet and length $octet;
74 if ( Encode::is_utf8($octet) ) {
75 return find_encoding('utf8') unless $NoUTFAutoGuess;
76 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 )
92 { # if \x00 found, we assume UTF-(16|32)(BE|LE)
94 my ( $be, $le ) = ( 0, 0 );
95 if ( $octet =~ /\x00\x00/o ) { # UTF-32(BE|LE) assumed
97 for my $char ( unpack( 'N*', $octet ) ) {
98 $char & 0x0000ffff and $be++;
99 $char & 0xffff0000 and $le++;
102 else { # UTF-16(BE|LE) assumed
104 for my $char ( unpack( 'n*', $octet ) ) {
105 $char & 0x00ff and $be++;
106 $char & 0xff00 and $le++;
109 DEBUG and warn "$utf, be == $be, le == $le";
112 "Encodings ambiguous between $utf BE and LE ($be, $le)";
113 $utf .= ( $be > $le ) ? 'BE' : 'LE';
114 return find_encoding($utf);
117 my %try = %{ $obj->{Suspects} };
119 my $e = find_encoding($c) or die "Unknown encoding: $c";
120 $try{ $e->name } = $e;
121 DEBUG and warn "Added: ", $e->name;
124 for my $line ( split /\r\n?|\n/, $octet ) {
126 # cheat 2 -- \e in the string
127 if ( $line =~ /\e/o ) {
128 my @keys = keys %try;
129 delete @try{qw/utf8 ascii/};
131 ref( $try{$k} ) eq 'Encode::XS' and delete $try{$k};
136 # warn join(",", keys %try);
137 for my $k ( keys %try ) {
139 $try{$k}->decode( $scratch, FB_QUIET );
140 if ( $scratch eq '' ) {
141 DEBUG and warn sprintf( "%4d:%-24s ok\n", $nline, $k );
146 and warn sprintf( "%4d:%-24s not ok; %d bytes left\n",
147 $nline, $k, bytes::length($scratch) );
151 %ok or return "No appropriate encodings found!";
152 if ( scalar( keys(%ok) ) == 1 ) {
153 my ($retval) = values(%ok);
160 or return "Encodings too ambiguous: ", join( " or ", keys %try );
169 Encode::Guess -- Guesses encoding from data
173 # if you are sure $data won't contain anything bogus
176 use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
177 my $utf8 = decode("Guess", $data);
178 my $data = encode("Guess", $utf8); # this doesn't work!
182 my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
183 ref($enc) or die "Can't guess: $enc"; # trap error this way
184 $utf8 = $enc->decode($data);
186 $utf8 = decode($enc->name, $data)
190 Encode::Guess enables you to guess in what encoding a given data is
191 encoded, or at least tries to.
195 By default, it checks only ascii, utf8 and UTF-16/32 with BOM.
197 use Encode::Guess; # ascii/utf8/BOMed UTF
199 To use it more practically, you have to give the names of encodings to
200 check (I<suspects> as follows). The name of suspects can either be
201 canonical names or aliases.
203 CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED.
205 # tries all major Japanese Encodings as well
206 use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
208 If the C<$Encode::Guess::NoUTFAutoGuess> variable is set to a true
209 value, no heuristics will be applied to UTF8/16/32, and the result
210 will be limited to the suspects and C<ascii>.
214 =item Encode::Guess->set_suspects
216 You can also change the internal suspects list via C<set_suspects>
220 Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);
222 =item Encode::Guess->add_suspects
224 Or you can use C<add_suspects> method. The difference is that
225 C<set_suspects> flushes the current suspects list while
226 C<add_suspects> adds.
229 Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
230 # now the suspects are euc-jp,shiftjis,7bit-jis, AND
231 # euc-kr,euc-cn, and big5-eten
232 Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);
234 =item Encode::decode("Guess" ...)
236 When you are content with suspects list, you can now
238 my $utf8 = Encode::decode("Guess", $data);
240 =item Encode::Guess->guess($data)
242 But it will croak if:
248 Two or more suspects remain
256 So you should instead try this;
258 my $decoder = Encode::Guess->guess($data);
260 On success, $decoder is an object that is documented in
261 L<Encode::Encoding>. So you can now do this;
263 my $utf8 = $decoder->decode($data);
265 On failure, $decoder now contains an error message so the whole thing
268 my $decoder = Encode::Guess->guess($data);
269 die $decoder unless ref($decoder);
270 my $utf8 = $decoder->decode($data);
272 =item guess_encoding($data, [, I<list of suspects>])
274 You can also try C<guess_encoding> function which is exported by
275 default. It takes $data to check and it also takes the list of
276 suspects by option. The optional suspect list is I<not reflected> to
277 the internal suspects list.
279 my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
280 die $decoder unless ref($decoder);
281 my $utf8 = $decoder->decode($data);
282 # check only ascii and utf8
283 my $decoder = guess_encoding($data);
293 Because of the algorithm used, ISO-8859 series and other single-byte
294 encodings do not work well unless either one of ISO-8859 is the only
295 one suspect (besides ascii and utf8).
299 my $decoder = guess_encoding($data, 'latin1');
301 my $decoder = guess_encoding($data, qw/latin1 greek/);
303 The reason is that Encode::Guess guesses encoding by trial and error.
304 It first splits $data into lines and tries to decode the line for each
305 suspect. It keeps it going until all but one encoding is eliminated
306 out of suspects list. ISO-8859 series is just too successful for most
307 cases (because it fills almost all code points in \x00-\xff).
311 Do not mix national standard encodings and the corresponding vendor
316 = guess_encoding($data, qw/shiftjis MacJapanese cp932/);
318 The reason is that vendor encoding is usually a superset of national
319 standard so it becomes too ambiguous for most cases.
323 On the other hand, mixing various national standard encodings
324 automagically works unless $data is too short to allow for guessing.
326 # This is ok if $data is long enough
328 guess_encoding($data, qw/euc-cn
329 euc-jp shiftjis 7bit-jis
335 DO NOT PUT TOO MANY SUSPECTS! Don't you try something like this!
337 my $decoder = guess_encoding($data,
338 Encode->encodings(":all"));
342 It is, after all, just a guess. You should alway be explicit when it
343 comes to encodings. But there are some, especially Japanese,
344 environment that guess-coding is a must. Use this module with care.
348 Encode::Guess does not work on EBCDIC platforms.
352 L<Encode>, L<Encode::Encoding>