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,">:bytes","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 B<Note that the explicit use of the C<raw> layer is deprecated.>
 112
 113 A pseudo-layer which performs two functions (which is messy, but
 114 necessary to maintain compatibility with non-PerlIO builds of Perl
 115 and their way things have been documented elsewhere).
 116
 117 Firstly it forces the file handle to be considered binary at that
 118 point in the layer stack, i.e. it turns off any CRLF translation.
 119
 120 Secondly in prevents the IO system seaching back before it in the
 121 layer specification.  Thus:
 122
 123     open($fh,":raw:perlio",...)
 124
 125 Forces the use of C<perlio> layer even if the platform default, or
 126 C<use open> default is something else (such as ":encoding(iso-8859-7)")
 127 (the C<:encoding> requires C<use Encode>) which would interfere with
 128 binary nature of the stream.
 129
 130 =back
 131
 132 =head2 Defaults and how to override them
 133
 134 If the platform is MS-DOS like and normally does CRLF to "\n"
 135 translation for text files then the default layers are :
 136
 137   unix crlf
 138
 139 (The low level "unix" layer may be replaced by a platform specific low
 140 level layer.)
 141
 142 Otherwise if C<Configure> found out how to do "fast" IO using system's
 143 stdio, then the default layers are :
 144
 145   unix stdio
 146
 147 Otherwise the default layers are
 148
 149   unix perlio
 150
 151 These defaults may change once perlio has been better tested and tuned.
 152
 153 The default can be overridden by setting the environment variable
 154 PERLIO to a space separated list of layers (unix or platform low level
 155 layer is always pushed first).
 156
 157 This can be used to see the effect of/bugs in the various layers e.g.
 158
 159   cd .../perl/t
 160   PERLIO=stdio  ./perl harness
 161   PERLIO=perlio ./perl harness
 162
 163 =head1 AUTHOR
 164
 165 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 166
 167 =head1 SEE ALSO
 168
 169 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>
 170
 171 =cut
 172