Skip multideref for PL_check[OP_HELEM] tinkering
[perl.git] / lib / strict.pm
1 package strict;
2
3 $strict::VERSION = "1.09";
4
5 # Verify that we're called correctly so that strictures will work.
6 unless ( __FILE__ =~ /(^|[\/\\])\Q${\__PACKAGE__}\E\.pmc?$/ ) {
7     # Can't use Carp, since Carp uses us!
8     my (undef, $f, $l) = caller;
9     die("Incorrect use of pragma '${\__PACKAGE__}' at $f line $l.\n");
10 }
11
12 my ( %bitmask, %explicit_bitmask );
13
14 BEGIN {
15     %bitmask = (
16         refs => 0x00000002,
17         subs => 0x00000200,
18         vars => 0x00000400,
19     );
20
21     %explicit_bitmask = (
22         refs => 0x00000020,
23         subs => 0x00000040,
24         vars => 0x00000080,
25     );
26
27     my $bits = 0;
28     $bits |= $_ for values %bitmask;
29
30     my $inline_all_bits = $bits;
31     *all_bits = sub () { $inline_all_bits };
32
33     $bits = 0;
34     $bits |= $_ for values %explicit_bitmask;
35
36     my $inline_all_explicit_bits = $bits;
37     *all_explicit_bits = sub () { $inline_all_explicit_bits };
38 }
39
40 sub bits {
41     my $bits = 0;
42     my @wrong;
43     foreach my $s (@_) {
44         if (exists $bitmask{$s}) {
45             $^H |= $explicit_bitmask{$s};
46
47             $bits |= $bitmask{$s};
48         }
49         else {
50             push @wrong, $s;
51         }
52     }
53     if (@wrong) {
54         require Carp;
55         Carp::croak("Unknown 'strict' tag(s) '@wrong'");
56     }
57     $bits;
58 }
59
60 sub import {
61     shift;
62     $^H |= @_ ? &bits : all_bits | all_explicit_bits;
63 }
64
65 sub unimport {
66     shift;
67
68     if (@_) {
69         $^H &= ~&bits;
70     }
71     else {
72         $^H &= ~all_bits;
73         $^H |= all_explicit_bits;
74     }
75 }
76
77 1;
78 __END__
79
80 =head1 NAME
81
82 strict - Perl pragma to restrict unsafe constructs
83
84 =head1 SYNOPSIS
85
86     use strict;
87
88     use strict "vars";
89     use strict "refs";
90     use strict "subs";
91
92     use strict;
93     no strict "vars";
94
95 =head1 DESCRIPTION
96
97 If no import list is supplied, all possible restrictions are assumed.
98 (This is the safest mode to operate in, but is sometimes too strict for
99 casual programming.)  Currently, there are three possible things to be
100 strict about:  "subs", "vars", and "refs".
101
102 =over 6
103
104 =item C<strict refs>
105
106 This generates a runtime error if you 
107 use symbolic references (see L<perlref>).
108
109     use strict 'refs';
110     $ref = \$foo;
111     print $$ref;        # ok
112     $ref = "foo";
113     print $$ref;        # runtime error; normally ok
114     $file = "STDOUT";
115     print $file "Hi!";  # error; note: no comma after $file
116
117 There is one exception to this rule:
118
119     $bar = \&{'foo'};
120     &$bar;
121
122 is allowed so that C<goto &$AUTOLOAD> would not break under stricture.
123
124
125 =item C<strict vars>
126
127 This generates a compile-time error if you access a variable that was
128 neither explicitly declared (using any of C<my>, C<our>, C<state>, or C<use
129 vars>) nor fully qualified.  (Because this is to avoid variable suicide
130 problems and subtle dynamic scoping issues, a merely C<local> variable isn't
131 good enough.)  See L<perlfunc/my>, L<perlfunc/our>, L<perlfunc/state>,
132 L<perlfunc/local>, and L<vars>.
133
134     use strict 'vars';
135     $X::foo = 1;         # ok, fully qualified
136     my $foo = 10;        # ok, my() var
137     local $baz = 9;      # blows up, $baz not declared before
138
139     package Cinna;
140     our $bar;                   # Declares $bar in current package
141     $bar = 'HgS';               # ok, global declared via pragma
142
143 The local() generated a compile-time error because you just touched a global
144 name without fully qualifying it.
145
146 Because of their special use by sort(), the variables $a and $b are
147 exempted from this check.
148
149 =item C<strict subs>
150
151 This disables the poetry optimization, generating a compile-time error if
152 you try to use a bareword identifier that's not a subroutine, unless it
153 is a simple identifier (no colons) and that it appears in curly braces or
154 on the left hand side of the C<< => >> symbol.
155
156     use strict 'subs';
157     $SIG{PIPE} = Plumber;   # blows up
158     $SIG{PIPE} = "Plumber"; # fine: quoted string is always ok
159     $SIG{PIPE} = \&Plumber; # preferred form
160
161 =back
162
163 See L<perlmodlib/Pragmatic Modules>.
164
165 =head1 HISTORY
166
167 C<strict 'subs'>, with Perl 5.6.1, erroneously permitted to use an unquoted
168 compound identifier (e.g. C<Foo::Bar>) as a hash key (before C<< => >> or
169 inside curlies), but without forcing it always to a literal string.
170
171 Starting with Perl 5.8.1 strict is strict about its restrictions:
172 if unknown restrictions are used, the strict pragma will abort with
173
174     Unknown 'strict' tag(s) '...'
175
176 As of version 1.04 (Perl 5.10), strict verifies that it is used as
177 "strict" to avoid the dreaded Strict trap on case insensitive file
178 systems.
179
180 =cut