From: Jarkko Hietaniemi Date: Mon, 17 Jun 2002 13:56:33 +0000 (+0000) Subject: Further discouraging of :raw. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d5563ed7fd46e9485baaa3b43c79a6a71c7b4740;p=p5sagit%2Fp5-mst-13.2.git Further discouraging of :raw. p4raw-id: //depot/perl@17271 --- diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 6bef21f..1ad295a 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -33,8 +33,8 @@ 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") + open($fh,">:bytes","his.jpg") Shell: PERLIO=perlio perl .... @@ -108,6 +108,8 @@ to a such a stream. =item raw +B layer is deprecated.> + 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). diff --git a/lib/open.pm b/lib/open.pm index aab99fb..872d8ea 100644 --- a/lib/open.pm +++ b/lib/open.pm @@ -146,7 +146,7 @@ open - perl pragma to set default disciplines for input and output =head1 SYNOPSIS - use open IN => ":crlf", OUT => ":raw"; + use open IN => ":crlf", OUT => ":bytes"; use open OUT => ':utf8'; use open IO => ":encoding(iso-8859-7)"; @@ -263,9 +263,9 @@ Directory handles may also support disciplines in future. =head1 NONPERLIO FUNCTIONALITY If Perl is not built to use PerlIO as its IO system then only the two -pseudo-disciplines ":raw" and ":crlf" are available. +pseudo-disciplines C<:bytes> and C<:crlf> are available. -The ":raw" discipline corresponds to "binary mode" and the ":crlf" +The C<:bytes> discipline corresponds to "binary mode" and the C<:crlf> discipline corresponds to "text mode" on platforms that distinguish between the two modes when opening files (which is many DOS-like platforms, including Windows). These two disciplines are no-ops on diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index f2ca525..858f23f 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -449,21 +449,25 @@ L. =item binmode FILEHANDLE -Arranges for FILEHANDLE to be read or written in "binary" or "text" mode -on systems where the run-time libraries distinguish between binary and -text files. If FILEHANDLE is an expression, the value is taken as the -name of the filehandle. - -DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for -"text" mode. If the DISCIPLINE is omitted, it defaults to C<:raw>. -Returns true on success, C on failure. To mark FILEHANDLE as -UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>. -For backward compatibility binmode(FILEHANDLE) also implicitly -marks the handle as bytes. - -The C<:raw> are C<:clrf>, and any other directives of the form -C<:...>, are called I/O I. The C pragma can be -used to establish default I/O disciplines. See L. +Arranges for FILEHANDLE to be read or written in "binary" or "text" +mode on systems where the run-time libraries distinguish between +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. + +DISCIPLINE can be either of C<:bytes> for "binary" mode or C<:crlf> +for "text" mode. If the DISCIPLINE is omitted, it defaults to +C<:bytes>. To mark FILEHANDLE as UTF-8, use C<:utf8>. For backward +compatibility C also implicitly marks the +filehandle as bytes. + +The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the +form C<:...>, are called I/O I. 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 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 flush any possibly @@ -473,12 +477,13 @@ the default character encoding of the handle, see L. The C<:encoding> discipline sometimes needs to be called in mid-stream, and it doesn't flush the stream. -On some systems binmode() is necessary when you're not working with a -text file. For the sake of portability it is a good idea to always use -it when appropriate, and to never use it when it isn't appropriate. +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 +of portability it is a good idea to always use it when appropriate, +and to never use it when it isn't appropriate. -In other words: Regardless of platform, use binmode() on binary -files, and do not use binmode() on text files. +In other words: regardless of platform, use binmode() on binary files +(like for example images), and do not use binmode() on text files. The operating system, device drivers, C libraries, and Perl run-time system all work together to let the programmer treat a single diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 60c7929..2531838 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -909,19 +909,21 @@ C<:perlio> will insert a C<:unix> layer below itself to do low level IO. =item :raw +B layer is deprecated.> + Arranges for all accesses go straight to the lowest level 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. +Not really useful in PERLIO environment variable, instead just use +C<:unix> layer explicitly. -In perl5.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 normaly does CRLF translation -the appropriate thing to do is to add C<:perlio> to PERLIO environment -variable. +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. =item :stdio