perlopentut and PerlIO documentation

[p5sagit/p5-mst-13.2.git] / lib / PerlIO.pm

diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm
index 6bef21f..672efb2 100644 (file)
--- a/lib/PerlIO.pm
+++ b/lib/PerlIO.pm
@@ -33,8 +33,10 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
 
 =head1 SYNOPSIS
 
-  open($fh,">:crlf","my.txt")
-  open($fh,">:raw","his.jpg")
+  open($fh,"<:crlf", "my.txt"); # portably open a text file for reading
+
+  open($fh,"<","his.jpg");      # portably open a binary file for reading
+  binmode($fh);
 
   Shell:
     PERLIO=perlio perl ....
@@ -77,6 +79,8 @@ its operations.
 
 A layer which does CRLF to "\n" translation distinguishing "text" and
 "binary" files in the manner of MS-DOS and similar operating systems.
+(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
+as being an end-of-file marker.)
 
 =item utf8
 
@@ -108,25 +112,60 @@ to a such a stream.
 
 =item raw
 
-A pseudo-layer which performs two functions (which is messy, but
-necessary to maintain compatibility with non-PerlIO builds of Perl
-and their way things have been documented elsewhere).
+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.
+
+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.)
+
+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
+a known base on which to build e.g.
 
-Firstly it forces the file handle to be considered binary at that
-point in the layer stack, i.e. it turns off any CRLF translation.
+    open($fh,":raw:utf8",...)
 
-Secondly in prevents the IO system seaching back before it in the
-layer specification.  Thus:
+will construct a "binary" stream, but then enable UTF-8 translation.
 
-    open($fh,":raw:perlio",...)
+=item pop
 
-Forces the use of C<perlio> layer even if the platform default, or
-C<use open> default is something else (such as ":encoding(iso-8859-7)")
-(the C<:encoding> requires C<use Encode>) which would interfere with
-binary nature of the stream.
+A pseudo layer that removes the top-most layer. Gives perl code
+a way to manipulate the layer stack. Should be considered
+as experimental. Note that C<:pop> only works on real layers
+and will not undo the effects of pseudo layers like C<:utf8>.
+An example of a possible use might be:
+
+    open($fh,...)
+    ...
+    binmode($fh,":encoding(...)");  # next chunk is encoded
+    ...
+    binmode($fh,":pop");            # back to un-encocded
+
+A more elegant (and safer) interface is needed.
 
 =back
 
+=head2 Alternatives to raw
+
+To get a binary stream an alternate method is to use:
+
+    open($fh,"whatever")
+    binmode($fh);
+
+this has advantage of being backward compatible with how such things have
+had to be coded on some platforms for years.
+
+To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
+in the open call:
+
+    open($fh,"<:unix",$path)
+
 =head2 Defaults and how to override them
 
 If the platform is MS-DOS like and normally does CRLF to "\n"
@@ -164,7 +203,7 @@ 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