Integrate encoding::warnings from Autrijus Tang.

p4raw-id: //depot/perl@23980

5 files changed, 309 insertions, 0 deletions

diff --git a/MANIFEST b/MANIFEST
index c1e3eeb668..cf9c5ea5b1 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1271,6 +1271,10 @@ lib/Dumpvalue.pm		Screen dump of perl values
 lib/Dumpvalue.t			See if Dumpvalue works
 lib/dumpvar.pl			A variable dumper
 lib/dumpvar.t			A variable dumper tester
+lib/encoding/warnings.pm	warn on implicit encoding conversions
+lib/encoding/warnings/t/1-warning.t	tests for encoding::warnings
+lib/encoding/warnings/t/2-fatal.t	tests for encoding::warnings
+lib/encoding/warnings/t/3-normal.t	tests for encoding::warnings
 lib/English.pm			Readable aliases for short variables
 lib/English.t			See if English works
 lib/Env.pm			Map environment into ordinary variables
diff --git a/lib/encoding/warnings.pm b/lib/encoding/warnings.pm
new file mode 100644
index 0000000000..ba64b12f06
--- /dev/null
+++ b/lib/encoding/warnings.pm
@@ -0,0 +1,222 @@
+# $File: //member/autrijus/.vimrc $ $Author: autrijus $
+# $Revision: #14 $ $Change: 4137 $ $DateTime: 2003/02/08 11:41:59 $
+
+package encoding::warnings;
+$encoding::warnings::VERSION = '0.05';
+
+use strict;
+
+=head1 NAME
+
+encoding::warnings - Warn on implicit encoding conversions
+
+=head1 VERSION
+
+This document describes version 0.05 of encoding::warnings, released
+July 15, 2004.
+
+=head1 SYNOPSIS
+
+    use encoding::warnings; # or 'FATAL' to raise fatal exceptions
+
+    utf8::encode($a = chr(20000));  # a byte-string (raw bytes)
+    $b = chr(20000);		    # a unicode-string (wide characters)
+
+    # "Bytes implicitly upgraded into wide characters as iso-8859-1"
+    $c = $a . $b;
+
+=head1 DESCRIPTION
+
+=head2 Overview of the problem
+
+By default, there is a fundamental asymmetry in Perl's unicode model:
+implicit upgrading from byte-strings to unicode-strings assumes that
+they were encoded in I<ISO 8859-1 (Latin-1)>, but unicode-strings are
+downgraded with UTF-8 encoding.  This happens because the first 256
+codepoints in Unicode happens to agree with Latin-1.  
+
+However, this silent upgrading can easily cause problems, if you happen
+to mix unicode strings with non-Latin1 data -- i.e. byte-strings encoded
+in UTF-8 or other encodings.  The error will not manifest until the
+combined string is written to output, at which time it would be impossible
+to see where did the silent upgrading occur.
+
+=head2 Detecting the problem
+
+This module simplifies the process of diagnosing such problems.  Just put
+this line on top of your main program:
+
+    use encoding::warnings;
+
+Afterwards, implicit upgrading of high-bit bytes will raise a warning.
+Ex.: C<Bytes implicitly upgraded into wide characters as iso-8859-1 at
+- line 7>.
+
+However, strings composed purely of ASCII code points (C<0x00>..C<0x7F>)
+will I<not> trigger this warning.
+
+You can also make the warnings fatal by importing this module as:
+
+    use encoding::warnings 'FATAL';
+
+=head2 Solving the problem
+
+Most of the time, this warning occurs when a byte-string is concatenated
+with a unicode-string.  There are a number of ways to solve it:
+
+=over 4
+
+=item * Upgrade both sides to unicode-strings
+
+If your program does not need compatibility for Perl 5.6 and earlier,
+the recommended approach is to apply appropriate IO disciplines, so all
+data in your program become unicode-strings.  See L<encoding>, L<open> and
+L<perlfunc/binmode> for how.
+
+=item * Downgrade both sides to byte-strings
+
+The other way works too, especially if you are sure that all your data
+are under the same encoding, or if compatibility with older versions
+of Perl is desired.
+
+You may downgrade strings with C<Encode::encode> and C<utf8::encode>.
+See L<Encode> and L<utf8> for details.
+
+=item * Specify the encoding for implicit byte-string upgrading
+
+If you are confident that all byte-strings will be in a specific
+encoding like UTF-8, I<and> need not support older versions of Perl,
+use the C<encoding> pragma:
+
+    use encoding 'utf8';
+
+Similarly, this will silence warnings from this module, and preserve the
+default behaviour:
+
+    use encoding 'iso-8859-1';
+
+However, note that C<use encoding> actually had three distinct effects:
+
+=over 4
+
+=item * PerlIO layers for B<STDIN> and B<STDOUT>
+
+This is similar to what L<open> pragma does.
+
+=item * Literal conversions
+
+This turns I<all> literal string in your program into unicode-strings
+(equivalent to a C<use utf8>), by decoding them using the specified
+encoding.
+
+=item * Implicit upgrading for byte-strings
+
+This will silence warnings from this module, as shown above.
+
+=back
+
+Because literal conversions also work on empty strings, it may surprise
+some people:
+
+    use encoding 'big5';
+
+    my $byte_string = pack("C*", 0xA4, 0x40);
+    print length $a;	# 2 here.
+    $a .= "";		# concatenating with a unicode string...
+    print length $a;	# 1 here!
+
+In other words, do not C<use encoding> unless you are certain that the
+program will not deal with any raw, 8-bit binary data at all.
+
+However, the C<Filter =E<gt> 1> flavor of C<use encoding> will I<not>
+affect implicit upgrading for byte-strings, and is thus incapable of
+silencing warnings from this module.  See L<encoding> for more details.
+
+=back
+
+=head1 CAVEATS
+
+This module currently affects the whole script, instead of inside its
+lexical block.  This is expected to be addressed during Perl 5.9 development,
+where the B<encoding> module will also be made lexical.
+
+=cut
+
+# Constants.
+sub ASCII  () { 0 }
+sub LATIN1 () { 1 }
+sub FATAL  () { 2 }
+
+# Install a ${^ENCODING} handler if no other one are already in place.
+sub import {
+    my $class = shift;
+    my $fatal = shift || '';
+
+    local $@;
+    return if ${^ENCODING} and ref(${^ENCODING}) ne $class;
+    return unless eval { require Encode; 1 };
+
+    my $ascii  = Encode::find_encoding('us-ascii') or return;
+    my $latin1 = Encode::find_encoding('iso-8859-1') or return;
+
+    # Have to undef explicitly here
+    undef ${^ENCODING};
+
+    # Install a warning handler for decode()
+    ${^ENCODING} = bless(
+	[
+	    $ascii,
+	    $latin1,
+	    (($fatal eq 'FATAL') ? 'Carp::croak' : 'Carp::carp'),
+	], $class,
+    );
+}
+
+# Don't worry about source code literals.
+sub cat_decode {
+    my $self = shift;
+    return $self->[LATIN1]->cat_decode(@_);
+}
+
+# Warn if the data is not purely US-ASCII.
+sub decode {
+    my $self = shift;
+
+    local $@;
+    my $rv = eval { $self->[ASCII]->decode($_[0], Encode::FB_CROAK()) };
+    return $rv unless $@;
+
+    require Carp;
+    no strict 'refs';
+    $self->[FATAL]->(
+	"Bytes implicitly upgraded into wide characters as iso-8859-1"
+    );
+    return $self->[LATIN1]->decode(@_);
+}
+
+sub name { 'iso-8859-1' }
+
+1;
+
+__END__
+
+=head1 SEE ALSO
+
+L<perlunicode>, L<perluniintro>
+
+L<open>, L<utf8>, L<encoding>, L<Encode>
+
+=head1 AUTHORS
+
+Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>
+
+=head1 COPYRIGHT
+
+Copyright 2004 by Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>.
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+See L<http://www.perl.com/perl/misc/Artistic.html>
+
+=cut
diff --git a/lib/encoding/warnings/t/1-warning.t b/lib/encoding/warnings/t/1-warning.t
new file mode 100644
index 0000000000..d2b4af9191
--- /dev/null
+++ b/lib/encoding/warnings/t/1-warning.t
@@ -0,0 +1,29 @@
+#!/usr/bin/perl
+# $File: /member/local/autrijus/encoding-warnings//t/1-warning.t $ $Author: autrijus $
+# $Revision: #5 $ $Change: 6145 $ $DateTime: 2004-07-16T03:49:06.717424Z $
+
+use Test;
+BEGIN { plan tests => 2 }
+
+use strict;
+use encoding::warnings;
+ok(encoding::warnings->VERSION);
+
+if ($] < 5.008) {
+    ok(1);
+    exit;
+}
+
+my ($a, $b, $c, $ok);
+
+$SIG{__WARN__} = sub {
+    if ($_[0] =~ /upgraded/) { ok(1); exit }
+};
+
+utf8::encode($a = chr(20000));
+$b = chr(20000);
+$c = $a . $b;
+
+ok($ok);
+
+__END__
diff --git a/lib/encoding/warnings/t/2-fatal.t b/lib/encoding/warnings/t/2-fatal.t
new file mode 100644
index 0000000000..1047169a2f
--- /dev/null
+++ b/lib/encoding/warnings/t/2-fatal.t
@@ -0,0 +1,27 @@
+#!/usr/bin/perl
+# $File: /member/local/autrijus/encoding-warnings/t/2-fatal.t $ $Author: autrijus $
+# $Revision: #4 $ $Change: 1626 $ $DateTime: 2004-03-14T16:53:19.351256Z $
+
+use Test;
+BEGIN { plan tests => 2 }
+
+use strict;
+use encoding::warnings 'FATAL';
+ok(encoding::warnings->VERSION);
+
+if ($] < 5.008) {
+    ok(1);
+    exit;
+}
+
+my ($a, $b, $c, $ok);
+
+$SIG{__DIE__} = sub {
+    if ($_[0] =~ /upgraded/) { ok(1); exit }
+};
+
+utf8::encode($a = chr(20000));
+$b = chr(20000);
+$c = $a . $b;
+
+ok($ok);
diff --git a/lib/encoding/warnings/t/3-normal.t b/lib/encoding/warnings/t/3-normal.t
new file mode 100644
index 0000000000..f573a86673
--- /dev/null
+++ b/lib/encoding/warnings/t/3-normal.t
@@ -0,0 +1,27 @@
+#!/usr/bin/perl
+# $File: /member/local/autrijus/encoding-warnings/t/3-normal.t $ $Author: autrijus $
+# $Revision: #3 $ $Change: 1625 $ $DateTime: 2004-03-14T16:50:26.012462Z $
+
+use Test;
+BEGIN { plan tests => 2 }
+
+use strict;
+use encoding::warnings 'FATAL';
+ok(encoding::warnings->VERSION);
+
+if ($] < 5.008) {
+    ok(1);
+    exit;
+}
+
+my ($a, $b, $c, $ok);
+$ok = 1;
+
+$SIG{__DIE__} = sub { $ok = 0 };
+$SIG{__WARN__} = sub { $ok = 0 };
+
+$a = chr(20000);
+$b = chr(20000);
+$c = $a . $b;
+
+ok($ok);