This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod: Suggest to use strict :encoding(UTF-8) PerlIO layer over not strict :encoding...
authorPali <pali@cpan.org>
Sun, 18 Sep 2016 15:19:59 +0000 (17:19 +0200)
committerKarl Williamson <khw@cpan.org>
Tue, 7 Feb 2017 03:09:22 +0000 (20:09 -0700)
For data exchange it is better to use strict UTF-8 encoding and not perl's utf8.

lib/PerlIO.pm
lib/open.pm
pod/perlfunc.pod
pod/perlrun.pod
pod/perlunicode.pod
pod/perluniintro.pod

index 2e27f98..7658ce4 100644 (file)
@@ -1,6 +1,6 @@
 package PerlIO;
 
-our $VERSION = '1.09';
+our $VERSION = '1.10';
 
 # Map layer name to package that defines it
 our %alias;
@@ -104,7 +104,7 @@ is chosen to render simple text parts (i.e.  non-accented letters,
 digits and common punctuation) human readable in the encoded file.
 
 (B<CAUTION>: This layer does not validate byte sequences.  For reading input,
-you should instead use C<:encoding(utf8)> instead of bare C<:utf8>.)
+you should instead use C<:encoding(UTF-8)> instead of bare C<:utf8>.)
 
 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
 and then read it back in.
index fd22e1b..ca3cf7b 100644 (file)
@@ -1,7 +1,7 @@
 package open;
 use warnings;
 
-our $VERSION = '1.10';
+our $VERSION = '1.11';
 
 require 5.008001; # for PerlIO::get_layers()
 
@@ -153,7 +153,7 @@ open - perl pragma to set default PerlIO layers for input and output
 
     use open IO  => ':locale';
 
-    use open ':encoding(utf8)';
+    use open ':encoding(UTF-8)';
     use open ':locale';
     use open ':encoding(iso-8859-7)';
 
@@ -195,8 +195,8 @@ For example:
 
 These are equivalent
 
-    use open ':encoding(utf8)';
-    use open IO => ':encoding(utf8)';
+    use open ':encoding(UTF-8)';
+    use open IO => ':encoding(UTF-8)';
 
 as are these
 
@@ -221,8 +221,8 @@ The C<:std> subpragma on its own has no effect, but if combined with
 the C<:utf8> or C<:encoding> subpragmas, it converts the standard
 filehandles (STDIN, STDOUT, STDERR) to comply with encoding selected
 for input/output handles.  For example, if both input and out are
-chosen to be C<:encoding(utf8)>, a C<:std> will mean that STDIN, STDOUT,
-and STDERR are also in C<:encoding(utf8)>.  On the other hand, if only
+chosen to be C<:encoding(UTF-8)>, a C<:std> will mean that STDIN, STDOUT,
+and STDERR are also in C<:encoding(UTF-8)>.  On the other hand, if only
 output is chosen to be in C<< :encoding(koi8r) >>, a C<:std> will cause
 only the STDOUT and STDERR to be in C<koi8r>.  The C<:locale> subpragma
 implicitly turns on C<:std>.
index 2b962aa..6f62f3f 100644 (file)
@@ -6090,7 +6090,7 @@ Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are received.  By default all sockets
 operate on bytes, but for example if the socket has been changed using
 L<C<binmode>|/binmode FILEHANDLE, LAYER> to operate with the
-C<:encoding(utf8)> I/O layer (see the L<open> pragma), the I/O will
+C<:encoding(UTF-8)> I/O layer (see the L<open> pragma), the I/O will
 operate on UTF8-encoded Unicode
 characters, not bytes.  Similarly for the C<:encoding> layer: in that
 case pretty much any characters can be read.
@@ -6650,7 +6650,7 @@ of the file) from the L<Fcntl> module.  Returns C<1> on success, false
 otherwise.
 
 Note the emphasis on bytes: even if the filehandle has been set to operate
-on characters (for example using the C<:encoding(utf8)> I/O layer), the
+on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
 L<C<tell>|/tell FILEHANDLE>, and
 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
@@ -6889,7 +6889,7 @@ Note the I<characters>: depending on the status of the socket, either
 (8-bit) bytes or characters are sent.  By default all sockets operate
 on bytes, but for example if the socket has been changed using
 L<C<binmode>|/binmode FILEHANDLE, LAYER> to operate with the
-C<:encoding(utf8)> I/O layer (see L<C<open>|/open FILEHANDLE,EXPR>, or
+C<:encoding(UTF-8)> I/O layer (see L<C<open>|/open FILEHANDLE,EXPR>, or
 the L<open> pragma), the I/O will operate on UTF-8
 encoded Unicode characters, not bytes.  Similarly for the C<:encoding>
 layer: in that case pretty much any characters can be sent.
@@ -8535,7 +8535,7 @@ to the current position plus POSITION; and C<2> to set it to EOF plus
 POSITION, typically negative.
 
 Note the emphasis on bytes: even if the filehandle has been set to operate
-on characters (for example using the C<:encoding(utf8)> I/O layer), the
+on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
 L<C<tell>|/tell FILEHANDLE>, and
 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
@@ -8702,7 +8702,7 @@ the actual filehandle.  If FILEHANDLE is omitted, assumes the file
 last read.
 
 Note the emphasis on bytes: even if the filehandle has been set to operate
-on characters (for example using the C<:encoding(utf8)> I/O layer), the
+on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
 L<C<tell>|/tell FILEHANDLE>, and
 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
index 9d59a6a..b4bb5a3 100644 (file)
@@ -1121,7 +1121,7 @@ A pseudolayer that enables a flag in the layer below to tell Perl
 that output should be in utf8 and that input should be regarded as
 already in valid utf8 form. B<WARNING: It does not check for validity and as such
 should be handled with extreme caution for input, because security violations
-can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(utf8)> is
+can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(UTF-8)> is
 the best option when reading UTF-8 encoded data.
 
 =item :win32
index ba5e312..23818a1 100644 (file)
@@ -1889,7 +1889,7 @@ work under 5.6, so you should be safe to try them out.
 A filehandle that should read or write UTF-8
 
   if ($] > 5.008) {
-    binmode $fh, ":encoding(utf8)";
+    binmode $fh, ":encoding(UTF-8)";
   }
 
 =item *
index 5a865c9..308113d 100644 (file)
@@ -406,7 +406,7 @@ Unicode or legacy encodings does not magically turn the data into
 Unicode in Perl's eyes.  To do that, specify the appropriate
 layer when opening files
 
-    open(my $fh,'<:encoding(utf8)', 'anything');
+    open(my $fh,'<:encoding(UTF-8)', 'anything');
     my $line_of_unicode = <$fh>;
 
     open(my $fh,'<:encoding(Big5)', 'anything');
@@ -415,8 +415,8 @@ layer when opening files
 The I/O layers can also be specified more flexibly with
 the C<open> pragma.  See L<open>, or look at the following example.
 
-    use open ':encoding(utf8)'; # input/output default encoding will be
-                                # UTF-8
+    use open ':encoding(UTF-8)'; # input/output default encoding will be
+                                 # UTF-8
     open X, ">file";
     print X chr(0x100), "\n";
     close X;
@@ -485,12 +485,12 @@ by repeatedly encoding the data:
     local $/; ## read in the whole file of 8-bit characters
     $t = <F>;
     close F;
-    open F, ">:encoding(utf8)", "file";
+    open F, ">:encoding(UTF-8)", "file";
     print F $t; ## convert to UTF-8 on output
     close F;
 
 If you run this code twice, the contents of the F<file> will be twice
-UTF-8 encoded.  A C<use open ':encoding(utf8)'> would have avoided the
+UTF-8 encoded.  A C<use open ':encoding(UTF-8)'> would have avoided the
 bug, or explicitly opening also the F<file> for input as UTF-8.
 
 B<NOTE>: the C<:utf8> and C<:encoding> features work only if your