Un-deprecate :raw after all - just define what it means

more precisely. (Pending approval).

p4raw-id: //depot/perlio@17295

4 files changed, 50 insertions, 60 deletions

diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm
index 5df9797cf4..1028c11013 100644
--- a/lib/PerlIO.pm
+++ b/lib/PerlIO.pm
@@ -79,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
 
@@ -110,60 +112,44 @@ to a such a stream.
 
 =item raw
 
-B<Note that the explicit use of the C<raw> layer is deprecated:>
+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<:raw> has been documented as both the opposite of C<:crlf> and
-as a way to make a stream "binary". With the new IO system those
-two are no longer equivalent. The name has also been read as meaning
-an unbuffered stream "as close to the operating system as possible".
-See below for better ways to do things.
+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.)
 
-The C<:raw> layer exists to maintain compatibility with non-PerlIO builds
-of Perl and to approximate the way it has been documented and how
-it was "faked" in perl5.6. It is a pseudo-layer which performs two
-functions (which is messy).
+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. This second effect is intended to disable other
-non-binary features of the stream.
-
-Thus:
-
-    open($fh,":raw:perlio",...)
-
-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.
+will construct a "binary" stream, but then enable UTF-8 translation.
 
 =back
 
 =head2 Alternatives to raw
 
-To get a binary stream the prefered method is to use:
+To get a binary stream an alternate method is to use:
 
+    open($fh,"whatever")
     binmode($fh);
 
-which is neatly backward compatible with how such things have
+this has advantage of being backward compatible with how such things have
 had to be coded on some platforms for years.
-The current implementation comprehends the effects of C<:utf8> and
-C<:crlf> layers and will be extended to comprehend similar translations
-if they are defined in future releases of perl.
 
 To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
-the open call:
+in the open call:
 
     open($fh,"<:unix",$path)
 
-To get a non-CRLF translated stream on any platform start from
-the un-buffered stream and add the appropriate layer:
-
-    open($fh,"<:unix:perlio",$path)
-
-
 =head2 Defaults and how to override them
 
 If the platform is MS-DOS like and normally does CRLF to "\n"
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 1faa4331c7..73515e8968 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -237,12 +237,15 @@ source code level, this shouldn't be that drastic a change.
 
 =item *
 
-The PerlIO C<:raw> discipline (as described in Camel III) is deprecated
-because its definition (as either the discipline version of C<binmode(FH)>
-or as the opposite of C<:crlf>) didn't really work: most importantly
-because turning off "clrfness" is not enough to make a stream truly
-binary.  Instead of C<:raw> use one of the following: C<open(..., ':bytes')>,
-C<binmode(FH)>, C<sysopen()> + C<sysread()>.
+Previous versions of perl and some readings of some sections of Camel III
+implied that C<:raw> "discipline" was the inverse of  C<:crlf>.
+Turning off "clrfness" is no longer enough to make a stream truly
+binary. So the PerlIO C<:raw> discipline is now formally defined as being
+equivalent to binmode(FH) - which is in turn defined as doing whatever
+is necessary to pass each byte as-is without any translation.
+In particular binmode(FH) - and hence C<:raw> - will now turn off both CRLF
+and UTF-8  translation and remove other "layers" (e.g. :encoding()) which
+would modify byte stream.
 
 =item *
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index cf8eb025c9..42e0f236f2 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -455,9 +455,14 @@ binary and text files.  If FILEHANDLE is an expression, the value is
 taken as the name of the filehandle.  Returns true on success,
 C<undef> on failure.
 
-If DISCIPLINE is omitted the filehandle is made suitable for passing
-binary data. This includes turning off possible CRLF translation and
-marking it as bytes (as opposed to Unicode characters).
+If DISCIPLINE is omitted or specified as C<:raw> the filehandle is made
+suitable for passing binary data. This includes turning off possible CRLF
+translation and marking it as bytes (as opposed to Unicode characters).
+Note that as desipite what may be implied in I<"Programming Perl">
+(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+- other disciplines which would affect binary nature of the stream are
+I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
+PERLIO environment variable.
 
 On some systems (in general, DOS and Windows-based systems) binmode()
 is necessary when you're not working with a text file.  For the sake
@@ -481,10 +486,6 @@ L<PerlIO>. (There is typically a one-to-one correspondence between
 layers and disiplines.) The C<open> pragma can be used to establish
 default I/O disciplines.  See L<open>.
 
-The C<:raw> discipline is deprecated.  (As opposed to what Camel III
-said, it is not the inverse of C<:crlf>.)  See L<PerlIO>, L<perlrun>
-and the discussion about the PERLIO environment variable.
-
 In general, binmode() should be called after open() but before any I/O
 is done on the filehandle.  Calling binmode() will normally flush any
 pending buffered output data (and perhaps pending input data) on the
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 2531838995..2ebc671031 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -909,21 +909,21 @@ C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
 
 =item :raw
 
-B<Note that the explicit use of the C<:raw> layer is deprecated.>
+Applying the <:raw> layer is equivalent to calling C<binmode($fh)>.
+It makes the stream pass each byte as-is without any translation.
+In particular CRLF translation, and/or :utf8 inuited from locale
+are disabled.
 
-Arranges for all accesses go straight to the lowest level layer provided
+Arranges for all accesses go straight to the lowest buffered layer provided
 by the configration. That is it strips off any layers above that layer.
-(The intent - unless layers are then pushed on top again -
-is to make perl's C<read> behave like C<sysread>.)
-
-Not really useful in PERLIO environment variable, instead just use
-C<:unix> layer explicitly.
 
 In Perl 5.6 and some books the C<:raw> layer (also called a discipline)
-is documented as the inverse of the C<:crlf> layer. That is not really
-the case.  If you want UNIX line endings on a platform that normally
-does CRLF translation the appropriate thing to do is to add C<:perlio>
-to PERLIO environment variable.
+is documented as the inverse of the C<:crlf> layer. That is no longer
+the case - other layers which would alter binary nature of the
+stream are also disabled.  If you want UNIX line endings on a platform
+that normally does CRLF translation, but still want UTF-8 or encoding
+defaults the appropriate thing to do is to add C<:perlio> to PERLIO
+environment variable.
 
 =item :stdio