lib/PerlIO.pm

   1 package PerlIO;
   2
   3 our $VERSION = '1.01';
   4
   5 # Map layer name to package that defines it
   6 our %alias;
   7
   8 sub import
   9 {
  10  my $class = shift;
  11  while (@_)
  12   {
  13    my $layer = shift;
  14    if (exists $alias{$layer})
  15     {
  16      $layer = $alias{$layer}
  17     }
  18    else
  19     {
  20      $layer = "${class}::$layer";
  21     }
  22    eval "require $layer";
  23    warn $@ if $@;
  24   }
  25 }
  26
  27 1;
  28 __END__
  29
  30 =head1 NAME
  31
  32 PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
  33
  34 =head1 SYNOPSIS
  35
  36   open($fh,">:crlf","my.txt")
  37   open($fh,">:raw","his.jpg")
  38
  39   Shell:
  40     PERLIO=perlio perl ....
  41
  42 =head1 DESCRIPTION
  43
  44 When an undefined layer 'foo' is encountered in an C<open> or
  45 C<binmode> layer specification then C code performs the equivalent of:
  46
  47   use PerlIO 'foo';
  48
  49 The perl code in PerlIO.pm then attempts to locate a layer by doing
  50
  51   require PerlIO::foo;
  52
  53 Otherwise the C<PerlIO> package is a place holder for additional
  54 PerlIO related functions.
  55
  56 The following layers are currently defined:
  57
  58 =over 4
  59
  60 =item unix
  61
  62 Low level layer which calls C<read>, C<write> and C<lseek> etc.
  63
  64 =item stdio
  65
  66 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.  Note
  67 that as this is "real" stdio it will ignore any layers beneath it and
  68 got straight to the operating system via the C library as usual.
  69
  70 =item perlio
  71
  72 This is a re-implementation of "stdio-like" buffering written as a
  73 PerlIO "layer".  As such it will call whatever layer is below it for
  74 its operations.
  75
  76 =item crlf
  77
  78 A layer which does CRLF to "\n" translation distinguishing "text" and
  79 "binary" files in the manner of MS-DOS and similar operating systems.
  80
  81 =item utf8
  82
  83 Declares that the stream accepts perl's internal encoding of
  84 characters.  (Which really is UTF-8 on ASCII machines, but is
  85 UTF-EBCDIC on EBCDIC machines.)  This allows any character perl can
  86 represent to be read from or written to the stream. The UTF-X encoding
  87 is chosen to render simple text parts (i.e.  non-accented letters,
  88 digits and common punctuation) human readable in the encoded file.
  89
  90 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
  91 and then read it back in.
  92
  93         open(F, ">:utf8", "data.utf");
  94         print F $out;
  95         close(F);
  96
  97         open(F, "<:utf8", "data.utf");
  98         $in = <F>;
  99         close(F);
 100
 101 =item bytes
 102
 103 This is the inverse of C<:utf8> layer. It turns off the flag
 104 on the layer below so that data read from it is considered to
 105 be "octets" i.e. characters in range 0..255 only. Likewise
 106 on output perl will warn if a "wide" character is written
 107 to a such a stream.
 108
 109 =item raw
 110
 111 A pseudo-layer which performs two functions (which is messy, but
 112 necessary to maintain compatibility with non-PerlIO builds of Perl
 113 and their way things have been documented elsewhere).
 114
 115 Firstly it forces the file handle to be considered binary at that
 116 point in the layer stack, i.e. it turns off any CRLF translation.
 117
 118 Secondly in prevents the IO system seaching back before it in the
 119 layer specification.  Thus:
 120
 121     open($fh,":raw:perlio",...)
 122
 123 Forces the use of C<perlio> layer even if the platform default, or
 124 C<use open> default is something else (such as ":encoding(iso-8859-7)")
 125 (the C<:encoding> requires C<use Encode>) which would interfere with
 126 binary nature of the stream.
 127
 128 =back
 129
 130 =head2 Defaults and how to override them
 131
 132 If the platform is MS-DOS like and normally does CRLF to "\n"
 133 translation for text files then the default layers are :
 134
 135   unix crlf
 136
 137 (The low level "unix" layer may be replaced by a platform specific low
 138 level layer.)
 139
 140 Otherwise if C<Configure> found out how to do "fast" IO using system's
 141 stdio, then the default layers are :
 142
 143   unix stdio
 144
 145 Otherwise the default layers are
 146
 147   unix perlio
 148
 149 These defaults may change once perlio has been better tested and tuned.
 150
 151 The default can be overridden by setting the environment variable
 152 PERLIO to a space separated list of layers (unix or platform low level
 153 layer is always pushed first).
 154
 155 This can be used to see the effect of/bugs in the various layers e.g.
 156
 157   cd .../perl/t
 158   PERLIO=stdio  ./perl harness
 159   PERLIO=perlio ./perl harness
 160
 161 =head1 AUTHOR
 162
 163 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 164
 165 =head1 SEE ALSO
 166
 167 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>
 168
 169 =cut
 170