lib/PerlIO.pm

   1 package PerlIO;
   2
   3 our $VERSION = '1.06';
   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 sub F_UTF8 () { 0x8000 }
  28
  29 1;
  30 __END__
  31
  32 =head1 NAME
  33
  34 PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
  35
  36 =head1 SYNOPSIS
  37
  38   open($fh,"<:crlf", "my.txt"); # support platform-native and CRLF text files
  39
  40   open($fh,"<","his.jpg");      # portably open a binary file for reading
  41   binmode($fh);
  42
  43   Shell:
  44     PERLIO=perlio perl ....
  45
  46 =head1 DESCRIPTION
  47
  48 When an undefined layer 'foo' is encountered in an C<open> or
  49 C<binmode> layer specification then C code performs the equivalent of:
  50
  51   use PerlIO 'foo';
  52
  53 The perl code in PerlIO.pm then attempts to locate a layer by doing
  54
  55   require PerlIO::foo;
  56
  57 Otherwise the C<PerlIO> package is a place holder for additional
  58 PerlIO related functions.
  59
  60 The following layers are currently defined:
  61
  62 =over 4
  63
  64 =item :unix
  65
  66 Lowest level layer which provides basic PerlIO operations in terms of
  67 UNIX/POSIX numeric file descriptor calls
  68 (open(), read(), write(), lseek(), close()).
  69
  70 =item :stdio
  71
  72 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.  Note
  73 that as this is "real" stdio it will ignore any layers beneath it and
  74 go straight to the operating system via the C library as usual.
  75
  76 =item :perlio
  77
  78 A from scratch implementation of buffering for PerlIO. Provides fast
  79 access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
  80 and in general attempts to minimize data copying.
  81
  82 C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
  83
  84 =item :crlf
  85
  86 A layer that implements DOS/Windows like CRLF line endings.  On read
  87 converts pairs of CR,LF to a single "\n" newline character.  On write
  88 converts each "\n" to a CR,LF pair.  Note that this layer likes to be
  89 one of its kind: it silently ignores attempts to be pushed into the
  90 layer stack more than once.
  91
  92 It currently does I<not> mimic MS-DOS as far as treating of Control-Z
  93 as being an end-of-file marker.
  94
  95 (Gory details follow) To be more exact what happens is this: after
  96 pushing itself to the stack, the C<:crlf> layer checks all the layers
  97 below itself to find the first layer that is capable of being a CRLF
  98 layer but is not yet enabled to be a CRLF layer.  If it finds such a
  99 layer, it enables the CRLFness of that other deeper layer, and then
 100 pops itself off the stack.  If not, fine, use the one we just pushed.
 101
 102 The end result is that a C<:crlf> means "please enable the first CRLF
 103 layer you can find, and if you can't find one, here would be a good
 104 spot to place a new one."
 105
 106 Based on the C<:perlio> layer.
 107
 108 =item :mmap
 109
 110 A layer which implements "reading" of files by using C<mmap()> to
 111 make a (whole) file appear in the process's address space, and then
 112 using that as PerlIO's "buffer". This I<may> be faster in certain
 113 circumstances for large files, and may result in less physical memory
 114 use when multiple processes are reading the same file.
 115
 116 Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
 117 layer. Writes also behave like the C<:perlio> layer, as C<mmap()> for write
 118 needs extra house-keeping (to extend the file) which negates any advantage.
 119
 120 The C<:mmap> layer will not exist if the platform does not support C<mmap()>.
 121
 122 =item :utf8
 123
 124 Declares that the stream accepts perl's I<internal> encoding of
 125 characters.  (Which really is UTF-8 on ASCII machines, but is
 126 UTF-EBCDIC on EBCDIC machines.)  This allows any character perl can
 127 represent to be read from or written to the stream. The UTF-X encoding
 128 is chosen to render simple text parts (i.e.  non-accented letters,
 129 digits and common punctuation) human readable in the encoded file.
 130
 131 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
 132 and then read it back in.
 133
 134         open(F, ">:utf8", "data.utf");
 135         print F $out;
 136         close(F);
 137
 138         open(F, "<:utf8", "data.utf");
 139         $in = <F>;
 140         close(F);
 141
 142 Note that this layer does not validate byte sequences. For reading
 143 input, using C<:encoding(utf8)> instead of bare C<:utf8> is strongly
 144 recommended.
 145
 146 =item :bytes
 147
 148 This is the inverse of the C<:utf8> layer. It turns off the flag
 149 on the layer below so that data read from it is considered to
 150 be "octets" i.e. characters in the range 0..255 only. Likewise
 151 on output perl will warn if a "wide" character is written
 152 to a such a stream.
 153
 154 =item :raw
 155
 156 The C<:raw> layer is I<defined> as being identical to calling
 157 C<binmode($fh)> - the stream is made suitable for passing binary data,
 158 i.e. each byte is passed as-is. The stream will still be
 159 buffered.
 160
 161 In Perl 5.6 and some books the C<:raw> layer (previously sometimes also
 162 referred to as a "discipline") is documented as the inverse of the
 163 C<:crlf> layer. That is no longer the case - other layers which would
 164 alter the binary nature of the stream are also disabled.  If you want UNIX
 165 line endings on a platform that normally does CRLF translation, but still
 166 want UTF-8 or encoding defaults, the appropriate thing to do is to add
 167 C<:perlio> to the PERLIO environment variable.
 168
 169 The implementation of C<:raw> is as a pseudo-layer which when "pushed"
 170 pops itself and then any layers which do not declare themselves as suitable
 171 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
 172 flags rather than popping layers but that is an implementation detail.)
 173
 174 As a consequence of the fact that C<:raw> normally pops layers,
 175 it usually only makes sense to have it as the only or first element in
 176 a layer specification.  When used as the first element it provides
 177 a known base on which to build e.g.
 178
 179     open($fh,":raw:utf8",...)
 180
 181 will construct a "binary" stream, but then enable UTF-8 translation.
 182
 183 =item :pop
 184
 185 A pseudo layer that removes the top-most layer. Gives perl code
 186 a way to manipulate the layer stack. Should be considered
 187 as experimental. Note that C<:pop> only works on real layers
 188 and will not undo the effects of pseudo layers like C<:utf8>.
 189 An example of a possible use might be:
 190
 191     open($fh,...)
 192     ...
 193     binmode($fh,":encoding(...)");  # next chunk is encoded
 194     ...
 195     binmode($fh,":pop");            # back to un-encoded
 196
 197 A more elegant (and safer) interface is needed.
 198
 199 =item :win32
 200
 201 On Win32 platforms this I<experimental> layer uses the native "handle" IO
 202 rather than the unix-like numeric file descriptor layer. Known to be
 203 buggy as of perl 5.8.2.
 204
 205 =back
 206
 207 =head2 Custom Layers
 208
 209 It is possible to write custom layers in addition to the above builtin
 210 ones, both in C/XS and Perl.  Two such layers (and one example written
 211 in Perl using the latter) come with the Perl distribution.
 212
 213 =over 4
 214
 215 =item :encoding
 216
 217 Use C<:encoding(ENCODING)> either in open() or binmode() to install
 218 a layer that transparently does character set and encoding transformations,
 219 for example from Shift-JIS to Unicode.  Note that under C<stdio>
 220 an C<:encoding> also enables C<:utf8>.  See L<PerlIO::encoding>
 221 for more information.
 222
 223 =item :via
 224
 225 Use C<:via(MODULE)> either in open() or binmode() to install a layer
 226 that does whatever transformation (for example compression /
 227 decompression, encryption / decryption) to the filehandle.
 228 See L<PerlIO::via> for more information.
 229
 230 =back
 231
 232 =head2 Alternatives to raw
 233
 234 To get a binary stream an alternate method is to use:
 235
 236     open($fh,"whatever")
 237     binmode($fh);
 238
 239 this has the advantage of being backward compatible with how such things have
 240 had to be coded on some platforms for years.
 241
 242 To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>)
 243 in the open call:
 244
 245     open($fh,"<:unix",$path)
 246
 247 =head2 Defaults and how to override them
 248
 249 If the platform is MS-DOS like and normally does CRLF to "\n"
 250 translation for text files then the default layers are :
 251
 252   unix crlf
 253
 254 (The low level "unix" layer may be replaced by a platform specific low
 255 level layer.)
 256
 257 Otherwise if C<Configure> found out how to do "fast" IO using the system's
 258 stdio, then the default layers are:
 259
 260   unix stdio
 261
 262 Otherwise the default layers are
 263
 264   unix perlio
 265
 266 These defaults may change once perlio has been better tested and tuned.
 267
 268 The default can be overridden by setting the environment variable
 269 PERLIO to a space separated list of layers (C<unix> or platform low
 270 level layer is always pushed first).
 271
 272 This can be used to see the effect of/bugs in the various layers e.g.
 273
 274   cd .../perl/t
 275   PERLIO=stdio  ./perl harness
 276   PERLIO=perlio ./perl harness
 277
 278 For the various values of PERLIO see L<perlrun/PERLIO>.
 279
 280 =head2 Querying the layers of filehandles
 281
 282 The following returns the B<names> of the PerlIO layers on a filehandle.
 283
 284    my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
 285
 286 The layers are returned in the order an open() or binmode() call would
 287 use them.  Note that the "default stack" depends on the operating
 288 system and on the Perl version, and both the compile-time and
 289 runtime configurations of Perl.
 290
 291 The following table summarizes the default layers on UNIX-like and
 292 DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>:
 293
 294  PERLIO     UNIX-like                   DOS-like
 295  ------     ---------                   --------
 296  unset / "" unix perlio / stdio [1]     unix crlf
 297  stdio      unix perlio / stdio [1]     stdio
 298  perlio     unix perlio                 unix perlio
 299  mmap       unix mmap                   unix mmap
 300
 301  # [1] "stdio" if Configure found out how to do "fast stdio" (depends
 302  # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
 303
 304 By default the layers from the input side of the filehandle are
 305 returned; to get the output side, use the optional C<output> argument:
 306
 307    my @layers = PerlIO::get_layers($fh, output => 1);
 308
 309 (Usually the layers are identical on either side of a filehandle but
 310 for example with sockets there may be differences, or if you have
 311 been using the C<open> pragma.)
 312
 313 There is no set_layers(), nor does get_layers() return a tied array
 314 mirroring the stack, or anything fancy like that.  This is not
 315 accidental or unintentional.  The PerlIO layer stack is a bit more
 316 complicated than just a stack (see for example the behaviour of C<:raw>).
 317 You are supposed to use open() and binmode() to manipulate the stack.
 318
 319 B<Implementation details follow, please close your eyes.>
 320
 321 The arguments to layers are by default returned in parentheses after
 322 the name of the layer, and certain layers (like C<utf8>) are not real
 323 layers but instead flags on real layers; to get all of these returned
 324 separately, use the optional C<details> argument:
 325
 326    my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
 327
 328 The result will be up to be three times the number of layers:
 329 the first element will be a name, the second element the arguments
 330 (unspecified arguments will be C<undef>), the third element the flags,
 331 the fourth element a name again, and so forth.
 332
 333 B<You may open your eyes now.>
 334
 335 =head1 AUTHOR
 336
 337 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
 338
 339 =head1 SEE ALSO
 340
 341 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>,
 342 L<Encode>
 343
 344 =cut