From: Nick Ing-Simmons Date: Wed, 19 Jun 2002 12:14:32 +0000 (+0000) Subject: Un-deprecate :raw after all - just define what it means X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0226bbdb9567884ccd3573b0b35272e596fbceba;p=p5sagit%2Fp5-mst-13.2.git Un-deprecate :raw after all - just define what it means more precisely. (Pending approval). p4raw-id: //depot/perlio@17295 --- diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 5df9797..1028c11 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 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 layer is deprecated:> +The C<:raw> layer is I as being identical to calling +C - 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 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 layer even if the platform default, or -C default is something else (such as ":encoding(iso-8859-7)") -(the C<:encoding> requires C) 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 1faa433..73515e8 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 -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, -C, C + C. +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 cf8eb02..42e0f23 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 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 the simply inverse of C<:crlf> +- other disciplines which would affect binary nature of the stream are +I disabled. See L, L 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. (There is typically a one-to-one correspondence between layers and disiplines.) The C pragma can be used to establish default I/O disciplines. See L. -The C<:raw> discipline is deprecated. (As opposed to what Camel III -said, it is not the inverse of C<:crlf>.) See L, L -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 2531838..2ebc671 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 layer is deprecated.> +Applying the <:raw> layer is equivalent to calling C. +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 behave like C.) - -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