Commit | Line | Data |
d1edabcf |
1 | package open; |
ac27b0f5 |
2 | use Carp; |
16fe6d59 |
3 | $open::hint_bits = 0x20000; |
4 | |
7d3b96bb |
5 | # layers array and hash mainly manipulated by C code in perlio.c |
ac27b0f5 |
6 | use vars qw(%layers @layers); |
7 | |
8 | # Populate hash in non-PerlIO case |
9 | %layers = (crlf => 1, raw => 0) unless (@layers); |
10 | |
dfebf958 |
11 | # warn join(',',keys %layers); |
12 | |
b75c8c73 |
13 | our $VERSION = '1.00'; |
14 | |
16fe6d59 |
15 | sub import { |
dfebf958 |
16 | my ($class,@args) = @_; |
17 | croak("`use open' needs explicit list of disciplines") unless @args; |
16fe6d59 |
18 | $^H |= $open::hint_bits; |
ac27b0f5 |
19 | my ($in,$out) = split(/\0/,(${^OPEN} || '\0')); |
20 | my @in = split(/\s+/,$in); |
21 | my @out = split(/\s+/,$out); |
dfebf958 |
22 | while (@args) { |
23 | my $type = shift(@args); |
24 | my $discp = shift(@args); |
ac27b0f5 |
25 | my @val; |
dfebf958 |
26 | foreach my $layer (split(/\s+/,$discp)) { |
27 | $layer =~ s/^://; |
ac27b0f5 |
28 | unless(exists $layers{$layer}) { |
dfebf958 |
29 | carp("Unknown discipline layer '$layer'"); |
ac27b0f5 |
30 | } |
31 | push(@val,":$layer"); |
32 | if ($layer =~ /^(crlf|raw)$/) { |
33 | $^H{"open_$type"} = $layer; |
16fe6d59 |
34 | } |
ac27b0f5 |
35 | } |
36 | if ($type eq 'IN') { |
37 | $in = join(' ',@val); |
38 | } |
39 | elsif ($type eq 'OUT') { |
40 | $out = join(' ',@val); |
16fe6d59 |
41 | } |
42 | else { |
ac27b0f5 |
43 | croak "Unknown discipline class '$type'"; |
16fe6d59 |
44 | } |
45 | } |
ac27b0f5 |
46 | ${^OPEN} = join('\0',$in,$out); |
16fe6d59 |
47 | } |
48 | |
49 | 1; |
50 | __END__ |
d1edabcf |
51 | |
52 | =head1 NAME |
53 | |
54 | open - perl pragma to set default disciplines for input and output |
55 | |
56 | =head1 SYNOPSIS |
57 | |
16fe6d59 |
58 | use open IN => ":crlf", OUT => ":raw"; |
d1edabcf |
59 | |
60 | =head1 DESCRIPTION |
61 | |
d151aa0e |
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). |
16fe6d59 |
65 | |
7d3b96bb |
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 |
d151aa0e |
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. |
7d3b96bb |
73 | |
d151aa0e |
74 | When open() is given an explicit list of layers they are appended to |
75 | the list declared using this pragma. |
7d3b96bb |
76 | |
77 | Directory handles may also support disciplines in future. |
78 | |
79 | =head1 NONPERLIO FUNCTIONALITY |
80 | |
d151aa0e |
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. |
16fe6d59 |
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 |
d151aa0e |
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. |
7d3b96bb |
90 | |
91 | =head1 IMPLEMENTATION DETAILS |
d1edabcf |
92 | |
d151aa0e |
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: |
d1edabcf |
96 | |
7d3b96bb |
97 | print "Have ",join(',',keys %open::layers),"\n"; |
98 | print "Using ",join(',',@open::layers),"\n"; |
16fe6d59 |
99 | |
d151aa0e |
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 |
7d3b96bb |
112 | argument entries are currently restricted to being strings. |
d1edabcf |
113 | |
d151aa0e |
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": |
16fe6d59 |
117 | |
7d3b96bb |
118 | splice(@PerlIO::layers,-2,2); |
119 | push(@PerlIO::layers,$PerlIO::layers{'stdio'} => undef); |
16fe6d59 |
120 | |
d1edabcf |
121 | =head1 SEE ALSO |
122 | |
7d3b96bb |
123 | L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<PerlIO> |
d1edabcf |
124 | |
125 | =cut |