X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FPerlIO.pm;h=5777679bfaaeff3e13b3729fa479f34cd53c7820;hb=ce4f4a1cb8714c6c6c3c7b002c9830a7cafc6780;hp=9a4da3a2a343a9e8598139b3ebd076df20c5b7ce;hpb=a6445d6f86f35d439d396b8deb840ae3cb7a429e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 9a4da3a..5777679 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -1,6 +1,6 @@ package PerlIO; -our $VERSION = '1.01'; +our $VERSION = '1.02'; # Map layer name to package that defines it our %alias; @@ -24,6 +24,8 @@ sub import } } +sub F_UTF8 () { 0x8000 } + 1; __END__ @@ -33,7 +35,7 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space =head1 SYNOPSIS - open($fh,">:crlf", "my.txt"); # portably open a text file for writing + 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); @@ -79,6 +81,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,27 +114,85 @@ 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 in the 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. + +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 popping 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. -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). + open($fh,":raw:utf8",...) -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. +will construct a "binary" stream, but then enable UTF-8 translation. -Secondly in prevents the IO system seaching back before it in the -layer specification. 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 Custom Layers + +It is possible to write custom layers in addition to the above builtin +ones, both in C/XS and Perl. Two such layers (and one example written +in Perl using the latter) come with the Perl distribution. + +=over 4 + +=item :encoding + +Use C<:encoding(ENCODING)> either in open() or binmode() to install +a layer that does transparently character set and encoding transformations, +for example from Shift-JIS to Unicode. Note that under C +an C<:encoding> also enables C<:utf8>. See L +for more information. + +=item :via + +Use C<:via(MODULE)> either in open() or binmode() to install a layer +that does whatever transformation (for example compression / +decompression, encryption / decryption) to the filehandle. +See L for more information. + +=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" @@ -142,7 +204,7 @@ translation for text files then the default layers are : level layer.) Otherwise if C found out how to do "fast" IO using system's -stdio, then the default layers are : +stdio, then the default layers are: unix stdio @@ -153,8 +215,8 @@ Otherwise the default layers are These defaults may change once perlio has been better tested and tuned. The default can be overridden by setting the environment variable -PERLIO to a space separated list of layers (unix or platform low level -layer is always pushed first). +PERLIO to a space separated list of layers (C or platform low +level layer is always pushed first). This can be used to see the effect of/bugs in the various layers e.g. @@ -162,13 +224,70 @@ This can be used to see the effect of/bugs in the various layers e.g. PERLIO=stdio ./perl harness PERLIO=perlio ./perl harness +For the various value of PERLIO see L. + +=head2 Querying the layers of filehandle + +The following returns the B of the PerlIO layers on a filehandle. + + my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH". + +The layers are returned in the order an open() or binmode() call would +use them. Note that the "default stack" depends on the operating +system and on the perl version. + +The following table summarizes the default layers on UNIX-like and +DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>: + + PERLIO UNIX-like DOS-like + + unset / "" unix perlio / stdio [1] unix crlf + stdio unix perlio / stdio [1] stdio + perlio unix perlio unix perlio + mmap unix mmap unix mmap + + # [1] "stdio" if Configure found out how to do "fast stdio" (depends + # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio" + +By default the layers from the input side of the filehandle is +returned, to get the output side use the optional C argument: + + my @layers = PerlIO::get_layers($fh, output => 1); + +(Usually the layers are identical on either side of a filehandle but +for example with sockets there may be differences, or if you have +been using the C pragma.) + +There is no set_layers(), nor does get_layers() return a tied array +mirroring the stack, or anything fancy like that. This is not +accidental or unintentional. The PerlIO layer stack is a bit more +complicated than just a stack (see for example the behaviour of C<:raw>). +You are supposed to use open() and binmode() to manipulate the stack. + +B + +The arguments to layers are by default returned in parenthesis after +the name of the layer, and certain layers (like C) are not real +layers but instead flags on real layers: to get all of these returned +separately use the optional C argument: + + my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1); + +The result will be up to be three times the number of layers: +the first element will be a name, the second element the arguments +(unspecified arguments will be C), the third element the flags, +the fourth element a name again, and so forth. + +B + =head1 AUTHOR Nick Ing-Simmons Enick@ing-simmons.netE =head1 SEE ALSO -L, L, L, L +L, L, L, L, +L =cut