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