1 files changed, 98 insertions, 13 deletions
diff --git a/gnu/usr.bin/perl/lib/PerlIO.pm b/gnu/usr.bin/perl/lib/PerlIO.pm
index 1ee5b888154..c7b9f1312b5 100644
--- a/gnu/usr.bin/perl/lib/PerlIO.pm
+++ b/gnu/usr.bin/perl/lib/PerlIO.pm
@@ -1,6 +1,6 @@
 package PerlIO;
 
-our $VERSION = '1.01';
+our $VERSION = '1.02';
 
 # Map layer name to package that defines it
 our %alias;
@@ -24,6 +24,8 @@ sub import
   }
 }
 
+sub F_UTF8 () { 0x8000 }
+
 1;
 __END__
 
@@ -113,20 +115,20 @@ to a such a stream.
 =item raw
 
 The C<:raw> layer is I<defined> as being identical to calling
-C<binmode($fh)> - the stream is made suitable for passing binary
-data i.e. each byte is passed as-is. The stream will still be
-buffered. Unlike earlier versions of perl C<:raw> is I<not> just the
-inverse of C<:crlf> - other layers which would affect the binary nature of
-the stream are also removed or disabled.
+C<binmode($fh)> - the stream is made suitable for passing binary data
+i.e. each byte is passed as-is. The stream will still be
+buffered. Unlike in the earlier versions of Perl C<:raw> is I<not>
+just the inverse of C<:crlf> - other layers which would affect the
+binary nature of the stream are also removed or disabled.
 
 The implementation of C<:raw> is as a pseudo-layer which when "pushed"
 pops itself and then any layers which do not declare themselves as suitable
 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
-flags rather than poping layers but that is an implementation detail.)
+flags rather than popping layers but that is an implementation detail.)
 
 As a consequence of the fact that C<:raw> normally pops layers
-it usually only makes sense to have it as the only or first element in a
-layer specification.  When used as the first element it provides
+it usually only makes sense to have it as the only or first element in
+a layer specification.  When used as the first element it provides
 a known base on which to build e.g.
 
     open($fh,":raw:utf8",...)
@@ -151,6 +153,31 @@ A more elegant (and safer) interface is needed.
 
 =back
 
+=head2 Custom Layers
+
+It is possible to write custom layers in addition to the above builtin
+ones, both in C/XS and Perl.  Two such layers (and one example written
+in Perl using the latter) come with the Perl distribution.
+
+=over 4
+
+=item :encoding
+
+Use C<:encoding(ENCODING)> either in open() or binmode() to install
+a layer that does transparently character set and encoding transformations,
+for example from Shift-JIS to Unicode.  Note that under C<stdio>
+an C<:encoding> also enables C<:utf8>.  See L<PerlIO::encoding>
+for more information.
+
+=item :via
+
+Use C<:via(MODULE)> either in open() or binmode() to install a layer
+that does whatever transformation (for example compression /
+decompression, encryption / decryption) to the filehandle.
+See L<PerlIO::via> for more information.
+
+=back
+
 =head2 Alternatives to raw
 
 To get a binary stream an alternate method is to use:
@@ -177,7 +204,7 @@ translation for text files then the default layers are :
 level layer.)
 
 Otherwise if C<Configure> found out how to do "fast" IO using system's
-stdio, then the default layers are :
+stdio, then the default layers are:
 
   unix stdio
 
@@ -188,8 +215,8 @@ Otherwise the default layers are
 These defaults may change once perlio has been better tested and tuned.
 
 The default can be overridden by setting the environment variable
-PERLIO to a space separated list of layers (unix or platform low level
-layer is always pushed first).
+PERLIO to a space separated list of layers (C<unix> or platform low
+level layer is always pushed first).
 
 This can be used to see the effect of/bugs in the various layers e.g.
 
@@ -197,13 +224,71 @@ This can be used to see the effect of/bugs in the various layers e.g.
   PERLIO=stdio  ./perl harness
   PERLIO=perlio ./perl harness
 
+For the various value of PERLIO see L<perlrun/PERLIO>.
+
+=head2 Querying the layers of filehandles
+
+The following returns the B<names> of the PerlIO layers on a filehandle.
+
+   my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
+
+The layers are returned in the order an open() or binmode() call would
+use them.  Note that the "default stack" depends on the operating
+system and on the Perl version, and both the compile-time and
+runtime configurations of Perl.
+
+The following table summarizes the default layers on UNIX-like and
+DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>:
+
+ PERLIO     UNIX-like                   DOS-like
+ 
+ unset / "" unix perlio / stdio [1]     unix crlf
+ stdio      unix perlio / stdio [1]     stdio
+ perlio     unix perlio                 unix perlio
+ mmap       unix mmap                   unix mmap
+
+ # [1] "stdio" if Configure found out how to do "fast stdio" (depends
+ # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
+
+By default the layers from the input side of the filehandle is
+returned, to get the output side use the optional C<output> argument:
+
+   my @layers = PerlIO::get_layers($fh, output => 1);
+
+(Usually the layers are identical on either side of a filehandle but
+for example with sockets there may be differences, or if you have
+been using the C<open> pragma.)
+
+There is no set_layers(), nor does get_layers() return a tied array
+mirroring the stack, or anything fancy like that.  This is not
+accidental or unintentional.  The PerlIO layer stack is a bit more
+complicated than just a stack (see for example the behaviour of C<:raw>).
+You are supposed to use open() and binmode() to manipulate the stack.
+
+B<Implementation details follow, please close your eyes.>
+
+The arguments to layers are by default returned in parenthesis after
+the name of the layer, and certain layers (like C<utf8>) are not real
+layers but instead flags on real layers: to get all of these returned
+separately use the optional C<separate> argument:
+
+   my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
+
+The result will be up to be three times the number of layers:
+the first element will be a name, the second element the arguments
+(unspecified arguments will be C<undef>), the third element the flags,
+the fourth element a name again, and so forth.
+
+B<You may open your eyes now.>
+
 =head1 AUTHOR
 
 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 
 =head1 SEE ALSO
 
-L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>
+L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>,
+L<Encode>
 
 =cut