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