lib/PerlIO.pm

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