X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FPerlIO.pm;h=bb678a6a07b70108c9918c3801512cb4666d113d;hb=e7ec2331900cd22a50f48dd01fa18bd3026f6253;hp=04cd4cfcc4a73ee76d68aa146ebb89d4835d0a13;hpb=7d3b96bbd83d17f17b26b4c05ef623881c8477be;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 04cd4cf..bb678a6 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -1,5 +1,7 @@ package PerlIO; +our $VERSION = '1.00'; + # Map layer name to package that defines it my %alias = (encoding => 'Encode'); @@ -39,8 +41,8 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space =head1 DESCRIPTION -When an undefined layer 'foo' is encountered in an C or C layer -specification then C code performs the equivalent of: +When an undefined layer 'foo' is encountered in an C or +C layer specification then C code performs the equivalent of: use PerlIO 'foo'; @@ -48,8 +50,8 @@ The perl code in PerlIO.pm then attempts to locate a layer by doing require PerlIO::foo; -Otherwise the C package is a place holder for additional PerLIO related -functions. +Otherwise the C package is a place holder for additional +PerlIO related functions. The following layers are currently defined: @@ -61,60 +63,74 @@ Low level layer which calls C, C and C etc. =item stdio -Layer which calls C, C and C/C etc. -Note that as this is "real" stdio it will ignore any layers beneath it and +Layer which calls C, C and C/C etc. Note +that as this is "real" stdio it will ignore any layers beneath it and got straight to the operating system via the C library as usual. =item perlio -This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer". -As such it will call whatever layer is below it for its operations. +This is a re-implementation of "stdio-like" buffering written as a +PerlIO "layer". As such it will call whatever layer is below it for +its operations. =item crlf -A layer which does CRLF to "\n" translation distinguishing "text" and "binary" -files in the manner of MS-DOS and similar operating systems. +A layer which does CRLF to "\n" translation distinguishing "text" and +"binary" files in the manner of MS-DOS and similar operating systems. =item utf8 -Declares that the stream accepts perl's internal encoding of characters. -(Which really is UTF-8 on ASCII machines, but is UTF-EBCDIC on EBCDIC machines.) -This allows any character perl can represent to be read from or written to the -stream. The UTF-X encoding is chosen to render simple text parts (i.e. -non-accented letters, digits and common punctuation) human readable in the -encoded file. +Declares that the stream accepts perl's internal encoding of +characters. (Which really is UTF-8 on ASCII machines, but is +UTF-EBCDIC on EBCDIC machines.) This allows any character perl can +represent to be read from or written to the stream. The UTF-X encoding +is chosen to render simple text parts (i.e. non-accented letters, +digits and common punctuation) human readable in the encoded file. + +Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) +and then read it back in. + + open(F, ">:utf8", "data.utf"); + print F $out; + close(F); + + open(F, "<:utf8", "data.utf"); + $in = ; + close(F); =item raw -A pseudo-layer which performs two functions (which is messy, but necessary to -maintain compatibility with non-PerLIO builds of perl and they way things -have been documented elsewhere). +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). -Firstly it forces the file handle to be considered binary at that point -in the layer stack, +Firstly it forces the file handle to be considered binary at that +point in the layer stack, -Secondly in prevents the IO system seaching back before it in the layer specification. -Thus: +Secondly in prevents the IO system seaching back before it in the +layer specification. Thus: - open($fh,":raw:perlio"),...) + 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)" ) which would interfere with +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. =back =head2 Defaults and how to override them -If the platform is MS-DOS like and normally does CRLF to "\n" translation -for text files then the default layers are : +If the platform is MS-DOS like and normally does CRLF to "\n" +translation for text files then the default layers are : unix crlf -(The low level "unix" layer may be replaced by a platform specific low level layer.) +(The low level "unix" layer may be replaced by a platform specific low +level layer.) -Otherwise if C found out how to do "fast" IO using system's stdio, then -the default layers are : +Otherwise if C found out how to do "fast" IO using system's +stdio, then the default layers are : unix stdio @@ -124,9 +140,10 @@ 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). +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). + This can be used to see the effect of/bugs in the various layers e.g. cd .../perl/t @@ -139,7 +156,7 @@ Nick Ing-Simmons Enick@ing-simmons.netE =head1 SEE ALSO -L, L, L, L +L, L, L, L =cut