1strictures(3)         User Contributed Perl Documentation        strictures(3)
2
3
4

NAME

6       strictures - Turn on strict and make most warnings fatal
7

SYNOPSIS

9         use strictures 2;
10
11       is equivalent to
12
13         use strict;
14         use warnings FATAL => 'all';
15         use warnings NONFATAL => qw(
16           exec
17           recursion
18           internal
19           malloc
20           newline
21           experimental
22           deprecated
23           portable
24         );
25         no warnings 'once';
26
27       except when called from a file which matches:
28
29         (caller)[1] =~ /^(?:t|xt|lib|blib)[\\\/]/
30
31       and when either ".git", ".svn", ".hg", or ".bzr" is present in the
32       current directory (with the intention of only forcing extra tests on
33       the author side) -- or when ".git", ".svn", ".hg", or ".bzr" is present
34       two directories up along with "dist.ini" (which would indicate we are
35       in a "dzil test" operation, via Dist::Zilla) -- or when the
36       "PERL_STRICTURES_EXTRA" environment variable is set, in which case it
37       also does the equivalent of
38
39         no indirect 'fatal';
40         no multidimensional;
41         no bareword::filehandles;
42
43       Note that "PERL_STRICTURES_EXTRA" may at some point add even more
44       tests, with only a minor version increase, but any changes to the
45       effect of "use strictures" in normal mode will involve a major version
46       bump.
47
48       If any of the extra testing modules are not present, strictures will
49       complain loudly, once, via warn(), and then shut up. But you really
50       should consider installing them, they're all great anti-footgun tools.
51

DESCRIPTION

53       I've been writing the equivalent of this module at the top of my code
54       for about a year now. I figured it was time to make it shorter.
55
56       Things like the importer in "use Moose" don't help me because they turn
57       warnings on but don't make them fatal -- which from my point of view is
58       useless because I want an exception to tell me my code isn't warnings-
59       clean.
60
61       Any time I see a warning from my code, that indicates a mistake.
62
63       Any time my code encounters a mistake, I want a crash -- not spew to
64       STDERR and then unknown (and probably undesired) subsequent behaviour.
65
66       I also want to ensure that obvious coding mistakes, like indirect
67       object syntax (and not so obvious mistakes that cause things to
68       accidentally compile as such) get caught, but not at the cost of an XS
69       dependency and not at the cost of blowing things up on another machine.
70
71       Therefore, strictures turns on additional checking, but only when it
72       thinks it's running in a test file in a VCS checkout -- although if
73       this causes undesired behaviour this can be overridden by setting the
74       "PERL_STRICTURES_EXTRA" environment variable.
75
76       If additional useful author side checks come to mind, I'll add them to
77       the "PERL_STRICTURES_EXTRA" code path only -- this will result in a
78       minor version increase (e.g. 1.000000 to 1.001000 (1.1.0) or similar).
79       Any fixes only to the mechanism of this code will result in a sub-
80       version increase (e.g. 1.000000 to 1.000001 (1.0.1)).
81

CATEGORY SELECTIONS

83       strictures does not enable fatal warnings for all categories.
84
85       exec
86           Includes a warning that can cause your program to continue running
87           unintentionally after an internal fork.  Not safe to fatalize.
88
89       recursion
90           Infinite recursion will end up overflowing the stack eventually
91           anyway.
92
93       internal
94           Triggers deep within perl, in places that are not safe to trap.
95
96       malloc
97           Triggers deep within perl, in places that are not safe to trap.
98
99       newline
100           Includes a warning for using stat on a valid but suspect filename,
101           ending in a newline.
102
103       experimental
104           Experimental features are used intentionally.
105
106       deprecated
107           Deprecations will inherently be added to in the future in
108           unexpected ways, so making them fatal won't be reliable.
109
110       portable
111           Doesn't indicate an actual problem with the program, only that it
112           may not behave properly if run on a different machine.
113
114       once
115           Can't be fatalized.  Also triggers very inconsistently, so we just
116           disable it.
117

VERSIONS

119       Depending on the version of strictures requested, different warnings
120       will be enabled.  If no specific version is requested, the current
121       version's behavior will be used.  Versions can be requested using
122       perl's standard mechanism:
123
124         use strictures 2;
125
126       Or, by passing in a "version" option:
127
128         use strictures version => 2;
129
130   VERSION 2
131       Equivalent to:
132
133         use strict;
134         use warnings FATAL => 'all';
135         use warnings NONFATAL => qw(
136           exec
137           recursion
138           internal
139           malloc
140           newline
141           experimental
142           deprecated
143           portable
144         );
145         no warnings 'once';
146
147         # and if in dev mode:
148         no indirect 'fatal';
149         no multidimensional;
150         no bareword::filehandles;
151
152       Additionally, any warnings created by modules using warnings::register
153       or warnings::register_categories() will not be fatalized.
154
155   VERSION 1
156       Equivalent to:
157
158         use strict;
159         use warnings FATAL => 'all';
160         # and if in dev mode:
161         no indirect 'fatal';
162         no multidimensional;
163         no bareword::filehandles;
164

METHODS

166   import
167       This method does the setup work described above in "DESCRIPTION".
168       Optionally accepts a "version" option to request a specific version's
169       behavior.
170
171   VERSION
172       This method traps the "strictures->VERSION(1)" call produced by a use
173       line with a version number on it and does the version check.
174

EXTRA TESTING RATIONALE

176       Every so often, somebody complains that they're deploying via "git
177       pull" and that they don't want strictures to enable itself in this case
178       -- and that setting "PERL_STRICTURES_EXTRA" to 0 isn't acceptable
179       (additional ways to disable extra testing would be welcome but the
180       discussion never seems to get that far).
181
182       In order to allow us to skip a couple of stages and get straight to a
183       productive conversation, here's my current rationale for turning the
184       extra testing on via a heuristic:
185
186       The extra testing is all stuff that only ever blows up at compile time;
187       this is intentional. So the oft-raised concern that it's different code
188       being tested is only sort of the case -- none of the modules involved
189       affect the final optree to my knowledge, so the author gets some
190       additional compile time crashes which he/she then fixes, and the rest
191       of the testing is completely valid for all environments.
192
193       The point of the extra testing -- especially "no indirect" -- is to
194       catch mistakes that newbie users won't even realise are mistakes
195       without help. For example,
196
197         foo { ... };
198
199       where foo is an & prototyped sub that you forgot to import -- this is
200       pernicious to track down since all seems fine until it gets called and
201       you get a crash. Worse still, you can fail to have imported it due to a
202       circular require, at which point you have a load order dependent bug
203       which I've seen before now only show up in production due to tiny
204       differences between the production and the development environment. I
205       wrote <http://shadow.cat/blog/matt-s-trout/indirect-but-still-fatal/>
206       to explain this particular problem before strictures itself existed.
207
208       As such, in my experience so far strictures' extra testing has avoided
209       production versus development differences, not caused them.
210
211       Additionally, strictures' policy is very much "try and provide as much
212       protection as possible for newbies -- who won't think about whether
213       there's an option to turn on or not" -- so having only the environment
214       variable is not sufficient to achieve that (I get to explain that you
215       need to add "use strict" at least once a week on freenode #perl --
216       newbies sometimes completely skip steps because they don't understand
217       that that step is important).
218
219       I make no claims that the heuristic is perfect -- it's already been
220       evolved significantly over time, especially for 1.004 where we changed
221       things to ensure it only fires on files in your checkout (rather than
222       strictures-using modules you happened to have installed, which was just
223       silly). However, I hope the above clarifies why a heuristic approach is
224       not only necessary but desirable from a point of view of providing new
225       users with as much safety as possible, and will allow any future
226       discussion on the subject to focus on "how do we minimise annoyance to
227       people deploying from checkouts intentionally".
228

SEE ALSO

230       •   indirect
231
232       •   multidimensional
233
234       •   bareword::filehandles
235

COMMUNITY AND SUPPORT

237   IRC channel
238       irc.perl.org #toolchain
239
240       (or bug 'mst' in query on there or freenode)
241
242   Git repository
243       Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
244
245         git clone git://git.shadowcat.co.uk/p5sagit/strictures.git
246
247       The web interface to the repository is at:
248
249         http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/strictures.git
250

AUTHOR

252       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
253

CONTRIBUTORS

255       Karen Etheridge (cpan:ETHER) <ether@cpan.org>
256
257       Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com>
258
259       haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
260
262       Copyright (c) 2010 the strictures "AUTHOR" and "CONTRIBUTORS" as listed
263       above.
264

LICENSE

266       This library is free software and may be distributed under the same
267       terms as perl itself.
268
269
270
271perl v5.38.0                      2023-07-21                     strictures(3)
Impressum