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