This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Make "real" layers of ":utf8" and ":raw".
[perl5.git] / lib / open.pm
1 package open;
2 use Carp;
3 $open::hint_bits = 0x20000;
4
5 use vars qw(%layers @layers);
6
7 # Populate hash in non-PerlIO case
8 %layers = (crlf => 1, raw => 0) unless (@layers);
9
10 # warn join(',',keys %layers);
11
12 our $VERSION = '1.00';
13
14 sub import {
15     my ($class,@args) = @_;
16     croak("`use open' needs explicit list of disciplines") unless @args;
17     $^H |= $open::hint_bits;
18     my ($in,$out) = split(/\0/,(${^OPEN} || '\0'));
19     my @in  = split(/\s+/,$in);
20     my @out = split(/\s+/,$out);
21     while (@args) {
22         my $type = shift(@args);
23         my $discp = shift(@args);
24         my @val;
25         foreach my $layer (split(/\s+/,$discp)) {
26             $layer =~ s/^://;
27             unless(exists $layers{$layer}) {
28                 carp("Unknown discipline layer '$layer'");
29             }
30             push(@val,":$layer");
31             if ($layer =~ /^(crlf|raw)$/) {
32                 $^H{"open_$type"} = $layer;
33             }
34         }
35         if ($type eq 'IN') {
36             $in  = join(' ',@val);
37         }
38         elsif ($type eq 'OUT') {
39             $out = join(' ',@val);
40         }
41         else {
42             croak "Unknown discipline class '$type'";
43         }
44     }
45     ${^OPEN} = join('\0',$in,$out);
46 }
47
48 1;
49 __END__
50
51 =head1 NAME
52
53 open - perl pragma to set default disciplines for input and output
54
55 =head1 SYNOPSIS
56
57     use open IN => ":crlf", OUT => ":raw";
58
59 =head1 DESCRIPTION
60
61 The open pragma is used to declare one or more default disciplines for
62 I/O operations.  Any open() and readpipe() (aka qx//) operators found
63 within the lexical scope of this pragma will use the declared defaults.
64 Neither open() with an explicit set of disciplines, nor sysopen() are
65 influenced by this pragma.
66
67 Only the two pseudo-disciplines ":raw" and ":crlf" are currently
68 available.
69
70 The ":raw" discipline corresponds to "binary mode" and the ":crlf"
71 discipline corresponds to "text mode" on platforms that distinguish
72 between the two modes when opening files (which is many DOS-like
73 platforms, including Windows).  These two disciplines are currently
74 no-ops on platforms where binmode() is a no-op, but will be
75 supported everywhere in future.
76
77 =head1 UNIMPLEMENTED FUNCTIONALITY
78
79 Full-fledged support for I/O disciplines is currently unimplemented.
80 When they are eventually supported, this pragma will serve as one of
81 the interfaces to declare default disciplines for all I/O.
82
83 In future, any default disciplines declared by this pragma will be
84 available by the special discipline name ":DEFAULT", and could be used
85 within handle constructors that allow disciplines to be specified.
86 This would make it possible to stack new disciplines over the default
87 ones.
88
89     open FH, "<:para :DEFAULT", $file or die "can't open $file: $!";
90
91 Socket and directory handles will also support disciplines in
92 future.
93
94 Full support for I/O disciplines will enable all of the supported
95 disciplines to work on all platforms.
96
97 =head1 SEE ALSO
98
99 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>
100
101 =cut