X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FPerlIO.pm;h=672efb2324356ddd641f509b975df976c52a28fb;hb=bc4938c65d770a20856c44a0d21026bcc6f41d7b;hp=a31141894cb80abe36e2e1418655ce45280ed74e;hpb=01e6739c7b8104181279fe94fb5488ec35b2ba1c;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index a311418..672efb2 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,60 @@ 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. +will construct a "binary" stream, but then enable UTF-8 translation. -Thus: +=item pop - open($fh,":raw:perlio",...) +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: -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. + 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 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" @@ -201,7 +203,7 @@ Nick Ing-Simmons Enick@ing-simmons.netE =head1 SEE ALSO -L, L, L, L +L, L, L, L, L =cut