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 perl is
  63 configured to use PerlIO as its IO system (which is now the default).
  64
  65 The C<open> pragma serves as one of the interfaces to declare default
  66 "layers" (aka disciplines) for all I/O.
  67
  68 The C<open> pragma is used to declare one or more default layers for
  69 I/O operations.  Any open(), readpipe() (aka qx//) and similar operators
  70 found within the lexical scope of this pragma will use the declared defaults.
  71
  72 When open() is given an explicit list of layers they are appended to the
  73 list declared using this pragma.
  74
  75 Directory handles may also support disciplines in future.
  76
  77 =head1 NONPERLIO FUNCTIONALITY
  78
  79 If perl is not built to use PerlIO as its IO system then only the two pseudo-disciplines
  80 ":raw" and ":crlf" are available.
  81
  82 The ":raw" discipline corresponds to "binary mode" and the ":crlf"
  83 discipline corresponds to "text mode" on platforms that distinguish
  84 between the two modes when opening files (which is many DOS-like
  85 platforms, including Windows).  These two disciplines are
  86 no-ops on platforms where binmode() is a no-op, but perform their
  87 functions everywhere if PerlIO is enabled.
  88
  89 =head1 IMPLEMENTATION DETAILS
  90
  91 There are two package variables C<%layers> and C<@layers> which
  92 are mainly manipulated by C code in F<perlio.c>, but are visible
  93 to the nosy:
  94
  95   print "Have ",join(',',keys %open::layers),"\n";
  96   print "Using ",join(',',@open::layers),"\n";
  97
  98 The C<%open::layers> hash is a record of the available "layers" that may be pushed
  99 onto a C<PerlIO> stream. The values of the hash are perl objects, of class C<PerlIO::Layer>
 100 which are created by the C code in F<perlio.c>. As yet there is nothing useful you
 101 can do with the objects at the perl level.
 102
 103 The C<@open::layers> array is the current set of layers and their arguments.
 104 The array consists of layer => argument pairs and I<must> always have even number of
 105 entries and the even entries I<must> be C<PerlIO::Layer> objects or perl will "die"
 106 when it attempts to open a filehandle. In most cases the odd entry will be C<undef>,
 107 but in the case of (say) ":encoding(iso-8859-1)" it will be 'iso-8859-1'. These
 108 argument entries are currently restricted to being strings.
 109
 110 When a new C<PerlIO> stream is opened, the C code looks at the
 111 array to determine the default layers to be pushed. So with care it is possible
 112 to manipulate the default layer "stack":
 113
 114     splice(@PerlIO::layers,-2,2);
 115     push(@PerlIO::layers,$PerlIO::layers{'stdio'} => undef);
 116
 117 =head1 SEE ALSO
 118
 119 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO>
 120
 121 =cut