summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Encode/Guess.pm
diff options
context:
space:
mode:
authorReinhard Kotucha <reinhard.kotucha@web.de>2008-01-05 21:23:03 +0000
committerReinhard Kotucha <reinhard.kotucha@web.de>2008-01-05 21:23:03 +0000
commit61700e8be90ff6f495c0b1a9835fe07e9848de8d (patch)
treeba85dbc1413d5f834a501a8828e3b67678ba8524 /Master/tlpkg/tlperl/lib/Encode/Guess.pm
parent270728c6f3efcac6728d2c335c79824c356f428d (diff)
tlperl: Perl for scripts provided by TeX Live.
git-svn-id: svn://tug.org/texlive/trunk@6046 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Encode/Guess.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Encode/Guess.pm351
1 files changed, 351 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Encode/Guess.pm b/Master/tlpkg/tlperl/lib/Encode/Guess.pm
new file mode 100644
index 00000000000..5692cee9a4a
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Encode/Guess.pm
@@ -0,0 +1,351 @@
+package Encode::Guess;
+use strict;
+
+use Encode qw(:fallbacks find_encoding);
+our $VERSION = do { my @r = (q$Revision: 2.0 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+
+my $Canon = 'Guess';
+sub DEBUG () { 0 }
+our %DEF_SUSPECTS = map { $_ => find_encoding($_) } qw(ascii utf8);
+$Encode::Encoding{$Canon} =
+ bless {
+ Name => $Canon,
+ Suspects => { %DEF_SUSPECTS },
+ } => __PACKAGE__;
+
+use base qw(Encode::Encoding);
+sub needs_lines { 1 }
+sub perlio_ok { 0 }
+
+our @EXPORT = qw(guess_encoding);
+our $NoUTFAutoGuess = 0;
+our $UTF8_BOM = pack("C3", 0xef, 0xbb, 0xbf);
+
+sub import { # Exporter not used so we do it on our own
+ my $callpkg = caller;
+ for my $item (@EXPORT){
+ no strict 'refs';
+ *{"$callpkg\::$item"} = \&{"$item"};
+ }
+ set_suspects(@_);
+}
+
+sub set_suspects{
+ my $class = shift;
+ my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
+ $self->{Suspects} = { %DEF_SUSPECTS };
+ $self->add_suspects(@_);
+}
+
+sub add_suspects{
+ my $class = shift;
+ my $self = ref($class) ? $class : $Encode::Encoding{$Canon};
+ for my $c (@_){
+ my $e = find_encoding($c) or die "Unknown encoding: $c";
+ $self->{Suspects}{$e->name} = $e;
+ DEBUG and warn "Added: ", $e->name;
+ }
+}
+
+sub decode($$;$){
+ my ($obj, $octet, $chk) = @_;
+ my $guessed = guess($obj, $octet);
+ unless (ref($guessed)){
+ require Carp;
+ Carp::croak($guessed);
+ }
+ my $utf8 = $guessed->decode($octet, $chk);
+ $_[1] = $octet if $chk;
+ return $utf8;
+}
+
+sub guess_encoding{
+ guess($Encode::Encoding{$Canon}, @_);
+}
+
+sub guess {
+ my $class = shift;
+ my $obj = ref($class) ? $class : $Encode::Encoding{$Canon};
+ my $octet = shift;
+
+ # sanity check
+ return unless defined $octet and length $octet;
+
+ # cheat 0: utf8 flag;
+ if ( Encode::is_utf8($octet) ) {
+ return find_encoding('utf8') unless $NoUTFAutoGuess;
+ Encode::_utf8_off($octet);
+ }
+ # cheat 1: BOM
+ use Encode::Unicode;
+ unless ($NoUTFAutoGuess) {
+ my $BOM = pack('C3', unpack("C3", $octet));
+ return find_encoding('utf8')
+ if (defined $BOM and $BOM eq $UTF8_BOM);
+ $BOM = unpack('N', $octet);
+ return find_encoding('UTF-32')
+ if (defined $BOM and ($BOM == 0xFeFF or $BOM == 0xFFFe0000));
+ $BOM = unpack('n', $octet);
+ return find_encoding('UTF-16')
+ if (defined $BOM and ($BOM == 0xFeFF or $BOM == 0xFFFe));
+ if ($octet =~ /\x00/o){ # if \x00 found, we assume UTF-(16|32)(BE|LE)
+ my $utf;
+ my ($be, $le) = (0, 0);
+ if ($octet =~ /\x00\x00/o){ # UTF-32(BE|LE) assumed
+ $utf = "UTF-32";
+ for my $char (unpack('N*', $octet)){
+ $char & 0x0000ffff and $be++;
+ $char & 0xffff0000 and $le++;
+ }
+ }else{ # UTF-16(BE|LE) assumed
+ $utf = "UTF-16";
+ for my $char (unpack('n*', $octet)){
+ $char & 0x00ff and $be++;
+ $char & 0xff00 and $le++;
+ }
+ }
+ DEBUG and warn "$utf, be == $be, le == $le";
+ $be == $le
+ and return
+ "Encodings ambiguous between $utf BE and LE ($be, $le)";
+ $utf .= ($be > $le) ? 'BE' : 'LE';
+ return find_encoding($utf);
+ }
+ }
+ my %try = %{$obj->{Suspects}};
+ for my $c (@_){
+ my $e = find_encoding($c) or die "Unknown encoding: $c";
+ $try{$e->name} = $e;
+ DEBUG and warn "Added: ", $e->name;
+ }
+ my $nline = 1;
+ for my $line (split /\r\n?|\n/, $octet){
+ # cheat 2 -- \e in the string
+ if ($line =~ /\e/o){
+ my @keys = keys %try;
+ delete @try{qw/utf8 ascii/};
+ for my $k (@keys){
+ ref($try{$k}) eq 'Encode::XS' and delete $try{$k};
+ }
+ }
+ my %ok = %try;
+ # warn join(",", keys %try);
+ for my $k (keys %try){
+ my $scratch = $line;
+ $try{$k}->decode($scratch, FB_QUIET);
+ if ($scratch eq ''){
+ DEBUG and warn sprintf("%4d:%-24s ok\n", $nline, $k);
+ }else{
+ use bytes ();
+ DEBUG and
+ warn sprintf("%4d:%-24s not ok; %d bytes left\n",
+ $nline, $k, bytes::length($scratch));
+ delete $ok{$k};
+ }
+ }
+ %ok or return "No appropriate encodings found!";
+ if (scalar(keys(%ok)) == 1){
+ my ($retval) = values(%ok);
+ return $retval;
+ }
+ %try = %ok; $nline++;
+ }
+ $try{ascii} or
+ return "Encodings too ambiguous: ", join(" or ", keys %try);
+ return $try{ascii};
+}
+
+
+
+1;
+__END__
+
+=head1 NAME
+
+Encode::Guess -- Guesses encoding from data
+
+=head1 SYNOPSIS
+
+ # if you are sure $data won't contain anything bogus
+
+ use Encode;
+ use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
+ my $utf8 = decode("Guess", $data);
+ my $data = encode("Guess", $utf8); # this doesn't work!
+
+ # more elaborate way
+ use Encode::Guess;
+ my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
+ ref($enc) or die "Can't guess: $enc"; # trap error this way
+ $utf8 = $enc->decode($data);
+ # or
+ $utf8 = decode($enc->name, $data)
+
+=head1 ABSTRACT
+
+Encode::Guess enables you to guess in what encoding a given data is
+encoded, or at least tries to.
+
+=head1 DESCRIPTION
+
+By default, it checks only ascii, utf8 and UTF-16/32 with BOM.
+
+ use Encode::Guess; # ascii/utf8/BOMed UTF
+
+To use it more practically, you have to give the names of encodings to
+check (I<suspects> as follows). The name of suspects can either be
+canonical names or aliases.
+
+CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED.
+
+ # tries all major Japanese Encodings as well
+ use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
+
+If the C<$Encode::Guess::NoUTFAutoGuess> variable is set to a true
+value, no heuristics will be applied to UTF8/16/32, and the result
+will be limited to the suspects and C<ascii>.
+
+=over 4
+
+=item Encode::Guess->set_suspects
+
+You can also change the internal suspects list via C<set_suspects>
+method.
+
+ use Encode::Guess;
+ Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);
+
+=item Encode::Guess->add_suspects
+
+Or you can use C<add_suspects> method. The difference is that
+C<set_suspects> flushes the current suspects list while
+C<add_suspects> adds.
+
+ use Encode::Guess;
+ Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
+ # now the suspects are euc-jp,shiftjis,7bit-jis, AND
+ # euc-kr,euc-cn, and big5-eten
+ Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);
+
+=item Encode::decode("Guess" ...)
+
+When you are content with suspects list, you can now
+
+ my $utf8 = Encode::decode("Guess", $data);
+
+=item Encode::Guess->guess($data)
+
+But it will croak if:
+
+=over
+
+=item *
+
+Two or more suspects remain
+
+=item *
+
+No suspects left
+
+=back
+
+So you should instead try this;
+
+ my $decoder = Encode::Guess->guess($data);
+
+On success, $decoder is an object that is documented in
+L<Encode::Encoding>. So you can now do this;
+
+ my $utf8 = $decoder->decode($data);
+
+On failure, $decoder now contains an error message so the whole thing
+would be as follows;
+
+ my $decoder = Encode::Guess->guess($data);
+ die $decoder unless ref($decoder);
+ my $utf8 = $decoder->decode($data);
+
+=item guess_encoding($data, [, I<list of suspects>])
+
+You can also try C<guess_encoding> function which is exported by
+default. It takes $data to check and it also takes the list of
+suspects by option. The optional suspect list is I<not reflected> to
+the internal suspects list.
+
+ my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
+ die $decoder unless ref($decoder);
+ my $utf8 = $decoder->decode($data);
+ # check only ascii and utf8
+ my $decoder = guess_encoding($data);
+
+=back
+
+=head1 CAVEATS
+
+=over 4
+
+=item *
+
+Because of the algorithm used, ISO-8859 series and other single-byte
+encodings do not work well unless either one of ISO-8859 is the only
+one suspect (besides ascii and utf8).
+
+ use Encode::Guess;
+ # perhaps ok
+ my $decoder = guess_encoding($data, 'latin1');
+ # definitely NOT ok
+ my $decoder = guess_encoding($data, qw/latin1 greek/);
+
+The reason is that Encode::Guess guesses encoding by trial and error.
+It first splits $data into lines and tries to decode the line for each
+suspect. It keeps it going until all but one encoding is eliminated
+out of suspects list. ISO-8859 series is just too successful for most
+cases (because it fills almost all code points in \x00-\xff).
+
+=item *
+
+Do not mix national standard encodings and the corresponding vendor
+encodings.
+
+ # a very bad idea
+ my $decoder
+ = guess_encoding($data, qw/shiftjis MacJapanese cp932/);
+
+The reason is that vendor encoding is usually a superset of national
+standard so it becomes too ambiguous for most cases.
+
+=item *
+
+On the other hand, mixing various national standard encodings
+automagically works unless $data is too short to allow for guessing.
+
+ # This is ok if $data is long enough
+ my $decoder =
+ guess_encoding($data, qw/euc-cn
+ euc-jp shiftjis 7bit-jis
+ euc-kr
+ big5-eten/);
+
+=item *
+
+DO NOT PUT TOO MANY SUSPECTS! Don't you try something like this!
+
+ my $decoder = guess_encoding($data,
+ Encode->encodings(":all"));
+
+=back
+
+It is, after all, just a guess. You should alway be explicit when it
+comes to encodings. But there are some, especially Japanese,
+environment that guess-coding is a must. Use this module with care.
+
+=head1 TO DO
+
+Encode::Guess does not work on EBCDIC platforms.
+
+=head1 SEE ALSO
+
+L<Encode>, L<Encode::Encoding>
+
+=cut
+