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 reading
  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 C<:raw> has been documented as both the opposite of C<:crlf> and
 116 as a way to make a stream "binary". With the new IO system those
 117 two are no longer equivalent. The name has also been read as meaning
 118 an unbuffered stream "as close to the operating system as possible".
 119 See below for better ways to do things.
 120
 121 The C<:raw> layer exists to maintain compatibility with non-PerlIO builds
 122 of Perl and to approximate the way it has been documented and how
 123 it was "faked" in perl5.6. It is a pseudo-layer which performs two
 124 functions (which is messy).
 125
 126 Firstly it forces the file handle to be considered binary at that
 127 point in the layer stack, i.e. it turns off any CRLF translation.
 128
 129 Secondly in prevents the IO system seaching back before it in the
 130 layer specification. This second effect is intended to disable other
 131 non-binary features of the stream.
 132
 133 Thus:
 134
 135     open($fh,":raw:perlio",...)
 136
 137 forces the use of C<perlio> layer even if the platform default, or
 138 C<use open> default is something else (such as ":encoding(iso-8859-7)")
 139 (the C<:encoding> requires C<use Encode>) which would interfere with
 140 binary nature of the stream.
 141
 142 =back
 143
 144 =head2 Alternatives to raw
 145
 146 To get a binary stream the prefered method is to use:
 147
 148     binmode($fh);
 149
 150 which is neatly backward compatible with how such things have
 151 had to be coded on some platforms for years.
 152 The current implementation comprehends the effects of C<:utf8> and
 153 C<:crlf> layers and will be extended to comprehend similar translations
 154 if they are defined in future releases of perl.
 155
 156 To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
 157 the open call:
 158
 159     open($fh,"<:unix",$path)
 160
 161 To get a non-CRLF translated stream on any platform start from
 162 the un-buffered stream and add the appropriate layer:
 163
 164     open($fh,"<:unix:perlio",$path)
 165
 166
 167 =head2 Defaults and how to override them
 168
 169 If the platform is MS-DOS like and normally does CRLF to "\n"
 170 translation for text files then the default layers are :
 171
 172   unix crlf
 173
 174 (The low level "unix" layer may be replaced by a platform specific low
 175 level layer.)
 176
 177 Otherwise if C<Configure> found out how to do "fast" IO using system's
 178 stdio, then the default layers are :
 179
 180   unix stdio
 181
 182 Otherwise the default layers are
 183
 184   unix perlio
 185
 186 These defaults may change once perlio has been better tested and tuned.
 187
 188 The default can be overridden by setting the environment variable
 189 PERLIO to a space separated list of layers (unix or platform low level
 190 layer is always pushed first).
 191
 192 This can be used to see the effect of/bugs in the various layers e.g.
 193
 194   cd .../perl/t
 195   PERLIO=stdio  ./perl harness
 196   PERLIO=perlio ./perl harness
 197
 198 =head1 AUTHOR
 199
 200 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 201
 202 =head1 SEE ALSO
 203
 204 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>
 205
 206 =cut
 207