lib/PerlIO.pm

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