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 (the C<:encoding> requires C<use Encode>) which would interfere with
 116 binary nature of the stream.
 117
 118 =back
 119
 120 =head2 Defaults and how to override them
 121
 122 If the platform is MS-DOS like and normally does CRLF to "\n"
 123 translation for text files then the default layers are :
 124
 125   unix crlf
 126
 127 (The low level "unix" layer may be replaced by a platform specific low
 128 level layer.)
 129
 130 Otherwise if C<Configure> found out how to do "fast" IO using system's
 131 stdio, then the default layers are :
 132
 133   unix stdio
 134
 135 Otherwise the default layers are
 136
 137   unix perlio
 138
 139 These defaults may change once perlio has been better tested and tuned.
 140
 141 The default can be overridden by setting the environment variable
 142 PERLIO to a space separated list of layers (unix or platform low level
 143 layer is always pushed first).
 144
 145 This can be used to see the effect of/bugs in the various layers e.g.
 146
 147   cd .../perl/t
 148   PERLIO=stdio  ./perl harness
 149   PERLIO=perlio ./perl harness
 150
 151 =head1 AUTHOR
 152
 153 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 154
 155 =head1 SEE ALSO
 156
 157 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>
 158
 159 =cut
 160