prep for 1.004002
[p5sagit/strictures.git] / lib / strictures.pm
CommitLineData
394c3a46 1package strictures;
2
3use strict;
4use warnings FATAL => 'all';
5
084caaf3 6use constant _PERL_LT_5_8_4 => ($] < 5.008004) ? 1 : 0;
7
7b5a233d 8our $VERSION = '1.004002'; # 1.4.2
394c3a46 9
10sub VERSION {
11 for ($_[1]) {
12 last unless defined && !ref && int != 1;
13 die "Major version specified as $_ - this is strictures version 1";
14 }
0925b84b 15 # disable this since Foo->VERSION(undef) correctly returns the version
16 # and that can happen either if our caller passes undef explicitly or
17 # because the for above autovivified $_[1] - I could make it stop but
18 # it's pointless since we don't want to blow up if the caller does
19 # something valid either.
20 no warnings 'uninitialized';
394c3a46 21 shift->SUPER::VERSION(@_);
22}
23
ffedb166 24my $extras_load_warned;
25
d7e82ccb 26our $Smells_Like_VCS = (-e '.git' || -e '.svn'
27 || (-e '../../dist.ini' && (-e '../../.git' || -e '../../.svn')));
12b8f19b 28
394c3a46 29sub import {
30 strict->import;
31 warnings->import(FATAL => 'all');
084caaf3 32
653f4377 33 my $extra_tests = do {
394c3a46 34 if (exists $ENV{PERL_STRICTURES_EXTRA}) {
084caaf3 35 if (_PERL_LT_5_8_4 and $ENV{PERL_STRICTURES_EXTRA}) {
0f96deac 36 die 'PERL_STRICTURES_EXTRA checks are not available on perls older than 5.8.4: '
084caaf3 37 . "please unset \$ENV{PERL_STRICTURES_EXTRA}\n";
38 }
39 $ENV{PERL_STRICTURES_EXTRA};
40 } elsif (! _PERL_LT_5_8_4) {
5ab06a4d 41 !!((caller)[1] =~ /^(?:t|xt|lib|blib)/
12b8f19b 42 and $Smells_Like_VCS)
394c3a46 43 }
44 };
653f4377 45 if ($extra_tests) {
ffedb166 46 my @failed;
47 if (eval { require indirect; 1 }) {
eae006ee 48 indirect->unimport(':fatal');
ffedb166 49 } else {
50 push @failed, 'indirect';
51 }
52 if (eval { require multidimensional; 1 }) {
653f4377 53 multidimensional->unimport;
ffedb166 54 } else {
55 push @failed, 'multidimensional';
56 }
57 if (eval { require bareword::filehandles; 1 }) {
653f4377 58 bareword::filehandles->unimport;
394c3a46 59 } else {
ffedb166 60 push @failed, 'bareword::filehandles';
61 }
62 if (@failed and not $extras_load_warned++) {
63 my $failed = join ' ', @failed;
64 warn <<EOE;
65strictures.pm extra testing active but couldn't load all modules. Missing were:
66
67 $failed
68
0925b84b 69Extra testing is auto-enabled in checkouts only, so if you're the author
653f4377 70of a strictures using module you need to run:
71
72 cpan indirect multidimensional bareword::filehandles
73
74but these modules are not required by your users.
084caaf3 75EOE
394c3a46 76 }
77 }
78}
79
801;
81
82__END__
83=head1 NAME
84
85strictures - turn on strict and make all warnings fatal
86
87=head1 SYNOPSIS
88
89 use strictures 1;
90
91is equivalent to
92
93 use strict;
94 use warnings FATAL => 'all';
95
5ab06a4d 96except when called from a file which matches:
394c3a46 97
5ab06a4d 98 (caller)[1] =~ /^(?:t|xt|lib|blib)/
394c3a46 99
25877bf2 100and when either C<.git> or C<.svn> is present in the current directory (with
d8c1c6b2 101the intention of only forcing extra tests on the author side) -- or when C<.git>
25877bf2 102or C<.svn> is present two directories up along with C<dist.ini> (which would
d8c1c6b2 103indicate we are in a C<dzil test> operation, via L<Dist::Zilla>) --
25877bf2 104or when the C<PERL_STRICTURES_EXTRA> environment variable is set, in which case
394c3a46 105
106 use strictures 1;
107
108is equivalent to
109
110 use strict;
111 use warnings FATAL => 'all';
112 no indirect 'fatal';
653f4377 113 no multidimensional;
114 no bareword::filehandles;
394c3a46 115
25877bf2 116Note that C<PERL_STRICTURES_EXTRA> may at some point add even more tests, with only a minor
117version increase, but any changes to the effect of C<use strictures> in
394c3a46 118normal mode will involve a major version bump.
119
0eb0d037 120If any of the extra testing modules are not present, L<strictures> will
25877bf2 121complain loudly, once, via C<warn()>, and then shut up. But you really
ffedb166 122should consider installing them, they're all great anti-footgun tools.
17b03f2e 123
394c3a46 124=head1 DESCRIPTION
125
126I've been writing the equivalent of this module at the top of my code for
127about a year now. I figured it was time to make it shorter.
128
25877bf2 129Things like the importer in C<use Moose> don't help me because they turn
d8c1c6b2 130warnings on but don't make them fatal -- which from my point of view is
2288278f 131useless because I want an exception to tell me my code isn't warnings-clean.
394c3a46 132
133Any time I see a warning from my code, that indicates a mistake.
134
d8c1c6b2 135Any time my code encounters a mistake, I want a crash -- not spew to STDERR
394c3a46 136and then unknown (and probably undesired) subsequent behaviour.
137
138I also want to ensure that obvious coding mistakes, like indirect object
139syntax (and not so obvious mistakes that cause things to accidentally compile
140as such) get caught, but not at the cost of an XS dependency and not at the
141cost of blowing things up on another machine.
142
0eb0d037 143Therefore, L<strictures> turns on additional checking, but only when it thinks
2288278f 144it's running in a test file in a VCS checkout -- although if this causes
93ae637e 145undesired behaviour this can be overridden by setting the
25877bf2 146C<PERL_STRICTURES_EXTRA> environment variable.
394c3a46 147
148If additional useful author side checks come to mind, I'll add them to the
2288278f 149C<PERL_STRICTURES_EXTRA> code path only -- this will result in a minor version increase (e.g.
394c3a46 1501.000000 to 1.001000 (1.1.0) or similar). Any fixes only to the mechanism of
2288278f 151this code will result in a sub-version increase (e.g. 1.000000 to 1.000001
394c3a46 152(1.0.1)).
153
25877bf2 154If the behaviour of C<use strictures> in normal mode changes in any way, that
d8c1c6b2 155will constitute a major version increase -- and the code already checks
394c3a46 156when its version is tested to ensure that
157
158 use strictures 1;
159
160will continue to only introduce the current set of strictures even if 2.0 is
161installed.
eae006ee 162
163=head1 METHODS
164
165=head2 import
166
167This method does the setup work described above in L</DESCRIPTION>
168
169=head2 VERSION
170
25877bf2 171This method traps the C<< strictures->VERSION(1) >> call produced by a use line
eae006ee 172with a version number on it and does the version check.
173
f9df7e2e 174=head1 EXTRA TESTING RATIONALE
175
25877bf2 176Every so often, somebody complains that they're deploying via C<git pull>
d8c1c6b2 177and that they don't want L<strictures> to enable itself in this case -- and that
f9df7e2e 178setting C<PERL_STRICTURES_EXTRA> to 0 isn't acceptable (additional ways to
179disable extra testing would be welcome but the discussion never seems to get
180that far).
181
182In order to allow us to skip a couple of stages and get straight to a
183productive conversation, here's my current rationale for turning the
184extra testing on via a heuristic:
185
186The extra testing is all stuff that only ever blows up at compile time;
2288278f 187this is intentional. So the oft-raised concern that it's different code being
d8c1c6b2 188tested is only sort of the case -- none of the modules involved affect the
f9df7e2e 189final optree to my knowledge, so the author gets some additional compile
190time crashes which he/she then fixes, and the rest of the testing is
191completely valid for all environments.
192
d8c1c6b2 193The point of the extra testing -- especially C<no indirect> -- is to catch
f9df7e2e 194mistakes that newbie users won't even realise are mistakes without
195help. For example,
196
197 foo { ... };
198
d8c1c6b2 199where foo is an & prototyped sub that you forgot to import -- this is
9a363fed 200pernicious to track down since all I<seems> fine until it gets called
f9df7e2e 201and you get a crash. Worse still, you can fail to have imported it due
202to a circular require, at which point you have a load order dependent
9a363fed 203bug which I've seen before now I<only> show up in production due to tiny
f9df7e2e 204differences between the production and the development environment. I wrote
205L<http://shadow.cat/blog/matt-s-trout/indirect-but-still-fatal/> to explain
206this particular problem before L<strictures> itself existed.
207
2288278f 208As such, in my experience so far L<strictures>' extra testing has
9a363fed 209I<avoided> production versus development differences, not caused them.
f9df7e2e 210
0eb0d037 211Additionally, L<strictures>' policy is very much "try and provide as much
d8c1c6b2 212protection as possible for newbies -- who won't think about whether there's
213an option to turn on or not" -- so having only the environment variable
f9df7e2e 214is not sufficient to achieve that (I get to explain that you need to add
d8c1c6b2 215C<use strict> at least once a week on freenode #perl -- newbies sometimes
f9df7e2e 216completely skip steps because they don't understand that that step
217is important).
218
d8c1c6b2 219I make no claims that the heuristic is perfect -- it's already been evolved
f9df7e2e 220significantly over time, especially for 1.004 where we changed things to
0eb0d037 221ensure it only fires on files in your checkout (rather than L<strictures>-using
f9df7e2e 222modules you happened to have installed, which was just silly). However, I
223hope the above clarifies why a heuristic approach is not only necessary but
2288278f 224desirable from a point of view of providing new users with as much safety as possible,
f9df7e2e 225and will allow any future discussion on the subject to focus on "how do we
226minimise annoyance to people deploying from checkouts intentionally".
227
eae006ee 228=head1 COMMUNITY AND SUPPORT
229
230=head2 IRC channel
231
232irc.perl.org #toolchain
233
234(or bug 'mst' in query on there or freenode)
235
236=head2 Git repository
237
238Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is:
239
240 git clone git://git.shadowcat.co.uk/p5sagit/strictures.git
241
91be28bc 242The web interface to the repository is at:
243
244 http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/strictures.git
245
eae006ee 246=head1 AUTHOR
247
d81f898d 248mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
eae006ee 249
250=head1 CONTRIBUTORS
251
252None required yet. Maybe this module is perfect (hahahahaha ...).
253
254=head1 COPYRIGHT
255
256Copyright (c) 2010 the strictures L</AUTHOR> and L</CONTRIBUTORS>
257as listed above.
258
259=head1 LICENSE
260
261This library is free software and may be distributed under the same terms
262as perl itself.
263
264=cut