lib/open.pm

   1 package open;
   2 use Carp;
   3 $open::hint_bits = 0x20000;
   4
   5 # layers array and hash mainly manipulated by C code in perlio.c
   6 use vars qw(%layers @layers);
   7
   8 # Populate hash in non-PerlIO case
   9 %layers = (crlf => 1, raw => 0) unless (@layers);
  10
  11 # warn join(',',keys %layers);
  12
  13 our $VERSION = '1.00';
  14
  15 sub import {
  16     my ($class,@args) = @_;
  17     croak("`use open' needs explicit list of disciplines") unless @args;
  18     $^H |= $open::hint_bits;
  19     my ($in,$out) = split(/\0/,(${^OPEN} || '\0'));
  20     my @in  = split(/\s+/,$in);
  21     my @out = split(/\s+/,$out);
  22     while (@args) {
  23         my $type = shift(@args);
  24         my $discp = shift(@args);
  25         my @val;
  26         foreach my $layer (split(/\s+/,$discp)) {
  27             $layer =~ s/^://;
  28             unless(exists $layers{$layer}) {
  29                 carp("Unknown discipline layer '$layer'");
  30             }
  31             push(@val,":$layer");
  32             if ($layer =~ /^(crlf|raw)$/) {
  33                 $^H{"open_$type"} = $layer;
  34             }
  35         }
  36         if ($type eq 'IN') {
  37             $in  = join(' ',@val);
  38         }
  39         elsif ($type eq 'OUT') {
  40             $out = join(' ',@val);
  41         }
  42         else {
  43             croak "Unknown discipline class '$type'";
  44         }
  45     }
  46     ${^OPEN} = join('\0',$in,$out);
  47 }
  48
  49 1;
  50 __END__
  51
  52 =head1 NAME
  53
  54 open - perl pragma to set default disciplines for input and output
  55
  56 =head1 SYNOPSIS
  57
  58     use open IN => ":crlf", OUT => ":raw";
  59
  60 =head1 DESCRIPTION
  61
  62 Full-fledged support for I/O disciplines is now implemented provided
  63 Perl is configured to use PerlIO as its IO system (which is now the
  64 default).
  65
  66 The C<open> pragma serves as one of the interfaces to declare default
  67 "layers" (aka disciplines) for all I/O.
  68
  69 The C<open> pragma is used to declare one or more default layers for
  70 I/O operations.  Any open(), readpipe() (aka qx//) and similar
  71 operators found within the lexical scope of this pragma will use the
  72 declared defaults.
  73
  74 When open() is given an explicit list of layers they are appended to
  75 the list declared using this pragma.
  76
  77 Directory handles may also support disciplines in future.
  78
  79 =head1 NONPERLIO FUNCTIONALITY
  80
  81 If Perl is not built to use PerlIO as its IO system then only the two
  82 pseudo-disciplines ":raw" and ":crlf" are available.
  83
  84 The ":raw" discipline corresponds to "binary mode" and the ":crlf"
  85 discipline corresponds to "text mode" on platforms that distinguish
  86 between the two modes when opening files (which is many DOS-like
  87 platforms, including Windows).  These two disciplines are no-ops on
  88 platforms where binmode() is a no-op, but perform their functions
  89 everywhere if PerlIO is enabled.
  90
  91 =head1 IMPLEMENTATION DETAILS
  92
  93 There are two package variables C<%layers> and C<@layers> which are
  94 mainly manipulated by C code in F<perlio.c>, but are visible to the
  95 nosy:
  96
  97   print "Have ",join(',',keys %open::layers),"\n";
  98   print "Using ",join(',',@open::layers),"\n";
  99
 100 The C<%open::layers> hash is a record of the available "layers" that
 101 may be pushed onto a C<PerlIO> stream. The values of the hash are Perl
 102 objects, of class C<PerlIO::Layer> which are created by the C code in
 103 F<perlio.c>.  As yet there is nothing useful you can do with the
 104 objects at the perl level.
 105
 106 The C<@open::layers> array is the current set of layers and their
 107 arguments.  The array consists of layer => argument pairs and I<must>
 108 always have even number of entries and the even entries I<must> be
 109 C<PerlIO::Layer> objects or Perl will "die" when it attempts to open a
 110 filehandle. In most cases the odd entry will be C<undef>, but in the
 111 case of (say) ":encoding(iso-8859-1)" it will be 'iso-8859-1'. These
 112 argument entries are currently restricted to being strings.
 113
 114 When a new C<PerlIO> stream is opened, the C code looks at the array
 115 to determine the default layers to be pushed. So with care it is
 116 possible to manipulate the default layer "stack":
 117
 118     splice(@PerlIO::layers,-2,2);
 119     push(@PerlIO::layers,$PerlIO::layers{'stdio'} => undef);
 120
 121 =head1 SEE ALSO
 122
 123 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO>
 124
 125 =cut