Login
Fix false positive in ProhibitSingleCharAlternation
[gknop/Perl-Critic.git] / TODO.pod
CommitLineData
9b8f64cf
CD
1# best viewed via "perldoc TODO.pod"
2
501ee198
JRT
3=pod
4
a73f4a71 5=for stopwords LHS RHS REFACTORINGS FH SVN stopwords
501ee198 6
dae851e8
JRT
7=head1 NAME
8
369abea9 9Perl::Critic::TODO - Things for Perl::Critic developers to do
dae851e8 10
2b7b1533 11
dae851e8 12=head1 SOURCE
daad783f
AL
13
14 #######################################################################
15 # $URL$
16 # $Date$
17 # $Author$
18 # $Revision$
19 #######################################################################
20
2b7b1533 21
de8cacdb
CD
22=head1 SEE ALSO
23
24Perl-Critic-More is a separate distribution for less-widely-accepted
ab1cd5d7 25policies. It contains its own TODO.pod.
de8cacdb 26
2b7b1533 27
daad783f
AL
28=head1 NEW FEATURES
29
2b7b1533 30=over
daad783f 31
8b5892fc 32=item * Report Safari sections in addition to book page numbers.
9bc546d7 33
2b7b1533 34
515a4fff
ES
35=item * Add --files-with-violations/-l and --files-without-violations/-L options to F<perlcritic>.
36
37Just print out file names. I could have used this at work when combined with
38C<--single-policy>.
39
40 gvim `perlcritic --single-policy QuotedWordLists -l`
41
42
0fe898d5
ES
43=item * Add a file Behavior.
44
45
46=item * Allow values of (at least) string-list Parameters to be specified in a file.
47
48For the benefit of PodSpelling, etc.
49
50
51=item * Enhance string-list Behavior to allow specification of delimiters.
52
53For things like RequirePodSections.
54
55
afceaa1d
ES
56=item * Add queries to --list option to F<perlcritic>.
57
58List Policies based upon severity, theme, and (what I want this second)
59applies_to.
60
d0e776fc
ES
61=item * Add --prohibit-unrestricted-no-critic option to F<perlcritic>.
62
63Requires C<## no critic> to take an argument:
64
65 ## no critic (SomePolicyPattern) # ok
66 ## no critic # not ok
67
e95460bd 68Can't be done as a regular Policy because any line that violated it would disable it.
d0e776fc 69
2b7b1533 70
ad5f2c12
ES
71=item * Support for C<#line 123 "filename"> directives.
72
73For code generators and template languages that allow inline Perl code.
74
96fa2db5
ES
75Yes, somebody has an in-house templating system where they've written a custom
76test module that extracts the perl code from a template and critiques it.
77
1d077d29
ES
78Actually, this would be useful for programs: Module::Build "fixes" shebang
79lines so that there's the bit about invoking perl if the program is attempted
80to be run by a Bourne shell, which throws the line numbers off when using
81Test::P::C on the contents of a C<blib> directory.
82
2b7b1533 83
a889d362
ES
84=item * Enhance statistics.
85
86- Blank line count
87
88- POD line count
89
90- Comment line count
91
92- Data section count
93
a889d362 94
afb00bb2
ES
95=item * Detect 5.10 source and enable stuff for that.
96
97For example, treat C<say> as equivalent to C<print>.
98
99
1d077d29
ES
100=item * Support a means of failing if a Policy isn't installed.
101
102For example, the self compliance test now depends upon a Policy in the More
103distribution.
104
105Something like using a "+" sign in front of the Policy name in its
106configuration block, analogous to the "-" sign used for disabling a policy,
107e.g. "C<[+Example::Policy]>".
108
109
d1d6429f
AL
110=back
111
2b7b1533 112
daad783f
AL
113=head1 BUGS/LIMITATIONS
114
2b7b1533 115=over
daad783f 116
daad783f
AL
117=item * NamingConventions::ProhibitAmbiguousNames
118
119Don't allow compound names with forbidden words, like "last_record".
120Allow forbidden words in RHS of variable declarations
121
fd5bd7b5
JRT
122Also, we should make it easeir to add (or delete) words from the
123forbbiden list.
124
2b7b1533 125
daad783f
AL
126=item * Subroutines::ProtectPrivateSubs
127
128Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
129difference between that and C<< $self->_foo() >>
130
2b7b1533 131
d1d6429f
AL
132=item * ErrorHandling::RequireCarping
133
63124782 134This should not complain about using C<warn> or C<die> if it's not in a
dd813c73 135function, or if it's in main::.
d1d6429f 136
63124782 137Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 138
2b7b1533 139
4c542233
AL
140=item * RegularExpressions::ProhibitCaptureWithoutTest
141
142Allow this construct:
143
144 for ( ... ) {
145 next unless /(....)/;
146 if ( $1 ) {
147 ....
148 }
149 }
150
151Right now, P::C thinks that the C<$1> isn't legal to use because it's
152"outside" of the match. The thing is, we can only get to the C<if>
153if the regex matched.
dfe2eb3f 154 while ( $str =~ /(expression)/ )
4c542233 155
2b7b1533 156
d9abc689
JRT
157=item * CodeLayout::ProhibitParensWithBuiltins
158
159Some builtin functions (particularly those that take a variable number of
c296c678
ES
160scalar arguments) should probably get parentheses. This policy should be
161enhanced to allow the user to specify a list of builtins that are expempt
162from the policy.
d9abc689 163
2b7b1533 164
c59ac28c
ES
165=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements
166
167Needs to check for C<scalar( something, something )>.
168
169
326d1973
ES
170=item * Variables::ProhibitPunctuationVars
171
172Needs to look inside strings. RT #35970.
173
174
96280e8c
ES
175=item * TestingAndDebugging::RequireUseWarnings
176
177Check for -w on the shbang line.
178
2b7b1533 179
21bee11d
ES
180=item * Change formatting in Violation to eliminate double periods.
181
182
365e3d9d
AL
183=back
184
2b7b1533 185
daad783f
AL
186=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
187
5331273a
ES
188=over
189
190=item * Modules::RequireUseVersion [405-406]
191
192=item * Modules::RequireThreePartVersion [405-406]
193
3dabcef1
ES
194=item * RegularExpressions::RequireDotMatchAnything [240-241]
195
5331273a 196=back
daad783f 197
2b7b1533 198
daad783f
AL
199=head1 NON-PBP POLICIES WANTED
200
2b7b1533 201=over
daad783f 202
45136ef4
ES
203=item * Documentation::RequireModuleAbstract
204
205Require a C<=head1 NAME> POD section with content that matches
206C<\A \s* [\w:]+ \s+ - \s+ \S>. The single hyphen is the important bit. Also,
207must be a single line.
208
be48b0c6
ES
209=item * Expressions::RequireFatCommasInHashConstructors
210
f3bcb2ca
ES
211=item * ErrorHandling::RequireLocalizingEvalErrorInDESTROY
212
213Prevent C<$@> from being cleared unexpectedly by DESTROY methods.
214
215 package Foo;
216
217 sub DESTROY {
218 die "Died in Foo::DESTROY()";
219 }
220
221 package main;
222
223 eval {
224 my $foo = Foo->new();
225
226 die "Died in eval."
227 }
228 print $@; # "Died in Foo::DESTROY()", not "Died in eval.".
229
effbbbb3
ES
230See L<http://use.perl.org/~Ovid/journal/36767>.
231
77fa21bd
ES
232=item * Expressions::ProhibitDecimalWithBitwiseOperator
233
234=item * Expressions::ProhibitStringsWithBitwiseOperator
235
2b7b1533 236
3264a614
ES
237=item * InputOutput::ProhibitMagicDiamond
238
239Steal the idea from L<B::Lint>.
240
241
df88f751 242=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
243
244Anything that is a program should have a shebang line. This includes .t files.
245
2b7b1533 246
daad783f
AL
247=item * BuiltInFunctions::RequireConstantSprintfFormat
248
2b7b1533 249
daad783f
AL
250=item * BuiltInFunctions::RequireConstantUnpackFormat
251
1cc04072 252L<http://diotalevi.isa-geek.net/~josh/yapc-lint/slides/slide5.html>
daad783f 253
2b7b1533 254
dfe2eb3f
JRT
255=item * Miscellanea::ProhibitObnoxiousComments
256
257Forbid excessive hash marks e.g. "#### This is a loud comment ####".
258Make the obnoxious pattern configurable
259
2b7b1533 260
dfe2eb3f
JRT
261=item * ValuesAndExpressions::RequireNotOperator
262
263Require the use of "not" instead of "!", except when this would contradict
264ProhibitMixedBooleanOperators. This may be better suited for
265Perl::Critic::More.
266
2b7b1533 267
dfe2eb3f
JRT
268=item * Modules::RequireExplicitImporting
269
270Require every C<use> statement to have an explicit import list. You could
271still get around this by calling C<import> directly.
272
2b7b1533 273
dfe2eb3f
JRT
274=item * Modules::ForbidImporting
275
276Require every C<use> to have an explicitly empty import list. This is for
277folks who like to see fully-qualified function names. Should probably provide
278a list of exempt modules (like FindBin);
279
2b7b1533 280
daad783f
AL
281=item * ControlStructures::ProhibitIncludeViaDo
282
283Forbid C<do "foo.pl">. Not sure about this policy name.
284
2b7b1533 285
daad783f
AL
286=item * Variables::ProhibitUseVars
287
f707b14a
CD
288Disallow C<use vars qw(...)> and require C<our $foo> instead. This
289contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
290before applying this policy. Low severity.
daad783f 291
2b7b1533 292
daad783f
AL
293=item * VariablesAndExpressions::ProhibitQuotedHashKeys
294
295Forbid quotes around hash keys, unless they are really needed. This
296is against what Damian says. Suggested by Adam Kennedy. Low
297severity.
298
2b7b1533 299
b589a229 300=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
301
302Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
303
2b7b1533 304
7eec5b31
ES
305=item * RegularExpressions::ProhibitSWSWSW
306
307Require C<split> instead of C<m/\s*\w*\s*\w*\s*/>. From MJD's Red Flags.
308
309
daad783f
AL
310=item * VariablesAndExpressions::RequireConstantVersion (low severity)
311
2b7b1533 312
f707b14a
CD
313=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
314
daad783f
AL
315L<http://rt.cpan.org/Ticket/Display.html?id=20439>
316
2b7b1533 317
79b72614
CD
318=item * Documentation::RequireSynopsis
319
2b7b1533 320
79b72614
CD
321=item * Documentation::RequireLicense
322
323These are simplified versions of Documentation::RequirePodSections.
324
2b7b1533 325
6a4d1045
CD
326=item * Documentation::RequireValidSynopsis
327
328The Synopsis section must be all indented and must be syntactically valid Perl
329(as validated by PPI).
330
2b7b1533 331
90c0067c
CD
332=item * Documentation::ProhibitEmptySections
333
334Any C<=headN> and C<=over> sections must not be empty. This helps catch
335boilerplate (althought Test::Pod should catch empty C<=over> blocks).
336
337On the other hand, C<=item ...> sections can be empty, since the item label is
338content.
339
2b7b1533 340
79b72614
CD
341=item * Miscellaneous::ProhibitBoilerplate
342
b589a229 343Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 344etc.
c6e7b236 345
ef919624
CD
346Here's a non-PPI implementation:
347L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
348
2b7b1533 349
956825ec
CD
350=item * BuiltinFunctions::ProhibitExtraneousScalarCall
351
352Recommend that C<if (scalar @array)> be rewritten as C<if (@array)>.
353
2b7b1533 354
6a4d1045
CD
355=item * RegularExpressions::ProhibitMixedDelimiters
356
357Ban s{foo}(bar)
358
2b7b1533 359
c79c8b5b
CD
360=item * RegularExpressions::ProhibitScalarAsRegexp
361
362Ban naked srtings as regexps, like:
363
364 print 1 if $str =~ $regexp;
365
366Instead, it should be:
367
368 print 1 if $str =~ m/$regexp/;
369
370or
371
372 print 1 if $str =~ m/$regexp/xms;
373
374
6a4d1045
CD
375=item * ValuesAndExpressions::RequireInterpolatedStringyEval
376
377Ensure that the argument to a stringy eval is not a constant string. That's
378just wasteful. Real world examples include:
379
380 eval 'use Optional::Module';
381
382which is better written as
383
384 eval { require Optional::Module; Optional::Module->import };
385
386for performance gains and compile-time syntax checking.
387
2b7b1533 388
76a987f3
CD
389=item * RegularExpressions::ProhibitUnnecessaryEscapes
390
391Complain if user puts a backslash escape in front of non-special characters. For example:
392
393 m/\!/;
394
395Make exceptions for C<\">, C<\'> and C<\`> since those are often inserted to
396workaround bugs in syntax highlighting.
397
398Note that this is different inside character classes, where only C<^>, C<]>
399and C<-> need to be escaped, I think. Caret only needs to be escaped at the
400beginning, and dash does NOT need to be escaped at the beginning and end. See
401L<perlreref>.
402
2b7b1533 403
fef95802
ES
404=item * Steal ideas from L<Dunce::Files>.
405
18658b1a
CD
406Can someone expand this entry, please?
407
408=item * ControlStructures::ProhibitAssigmentInConditional
409
410=item * ValuesAndExpressions::RequireConstantBeforeEquals
411
412=item * ValuesAndExpressions::RequireConstantBeforeOperator
413
414L<http://use.perl.org/~stu42j/journal/36412>
415
416Just about everyone has been bitten by C<if ($x = 10) { ... }> when they meant
417to use C<==>. A safer style is C<10 == $x> because omitting the second C<=>
418yields a noisy compile-time failure instead of silent runtime error.
419
420ProhibitAssigmentInConditional complains if the condition of a while, until,
421if or unless is solely an assignment. If it's anything more complex (like
422C<if (($x=10)){}> or C<while ($x=$y=$z){}>), there is no warning.
423
424RequireConstantBeforeEquals complains if the left side of an C<==> is a
425variable while the right side is a constant.
426
427RequireConstantBeforeOperator complains if the left side of any comparison
428operator (C<==>, C<eq>, C<&lt;>, etc) is a variable while the right side is a
429constant.
fef95802 430
3f64b6c8
ES
431
432=item * InputOutput::ProhibitUTF8IOLayer
433
434http://www.perlfoundation.org/perl5/index.cgi?the_utf8_perlio_layer
435
b61a141c 436=item * BuiltinFunctions::ProhibitExit(?:InModules)?
f0a7988d
CD
437
438Forbid C<exit()> in files that lack a shebang. Inspired by
439L<http://use.perl.org/~Ovid/journal/36746> and an analgous checker in
440FindBugs.
3f64b6c8 441
daad783f
AL
442=back
443
2b7b1533 444
daad783f
AL
445=head1 REFACTORINGS and ENHANCEMENTS
446
2b7b1533 447=over
daad783f 448
628facda
ES
449=item * Create constants for the PPI location array elements.
450
2b7b1533 451
992600be
JRT
452=item * MOVE THE LINE-DISABLING INTO P::C::Document
453
454All the code that deals with finding all the '##no critic' comments and noting
455which policies are disabled at each line seems like it would be better placed
456in Perl::Critic::Document. P::C::Document could then provide methods to
457indicate if a policy is disabled at a particular line. So the basic algorithm
458in Perl::Critic might look something like this:
459
460 foreach $element (@PPI_ELEMENTS) {
461 foreach $policy (@POLICIES) {
462 $line = $element->location->[0];
463 next if $doc->policy_is_disabled_at_line( $policy, $line );
464 push @violations, $policy->violates( $elem, $doc );
465 }
466 }
467
2b7b1533 468
aae75e29
ES
469=item * Some means of detecting "runnaway" C<##no critic>
470
471Elliot was talking to a couple of users at ETech and one of their major
472concerns was that they were using C<##no critic> and forgetting to do a
473C<##use critic> after the problematic section. Perhaps an option to
474F<perlcritic> to scan for such things is in order.
475
2b7b1533 476
dfe2eb3f
JRT
477=item * Change API to use named parameters
478
479Most of the methods on the public classes use named parameters for passing
480arguments. I'd like to extend that pattern to include all object-methods.
481Static methods can still use positional parameters.
482
2b7b1533 483
dfe2eb3f 484=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 485
9b8f64cf 486Just like F<bin/perlcritic> does now.
daad783f 487
2b7b1533 488
9b8f64cf
CD
489=item * Add C<-cache> flag to F<bin/perlcritic>
490
491If enabled, this turns on L<PPI::Cache>:
492
493 require PPI::Cache;
494 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
495 mkdir $cache_path, oct 700 if (! -d $cache_path);
496 PPI::Cache->import(path => $cache_path);
497
de8cacdb 498This cachedir should perhaps include the PPI version number! At least
84e87307 499until PPI incorporates its own version number in the cache.
9b8f64cf 500
de8cacdb 501(see F<t/40_criticize.t> for a more robust implementation)
79b72614 502
2b7b1533 503
c5bd966c
JRT
504=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
505
506In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
507a string is a member of a list. Instead, I suggest using a named
508subroutine that does a hash-lookup like this:
509
510 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
511 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
512
f2b8ca3f
ES
513Why?
514
2b7b1533
ES
515
516=item * Allow color output to work through a pipe.
517
518http://rt.cpan.org/Ticket/Display.html?id=30140
519
233e8deb
ES
520F<ack> now supports this.
521
2b7b1533 522
9b8f64cf
CD
523=back
524
525=head1 PPI BUGS
526
527We're waiting on the following bugs to get fixed in a CPAN release of PPI:
528
2b7b1533
ES
529
530=over
9b8f64cf 531
dd813c73
ES
532=item PPI::Token::descendant_of()
533
534Exists in svn. Replace _descendant_of() in RequireCheckingReturnValueOfEval
535with that, once it is released, because it's faster and native.
536
c38138ab 537=item Newlines
b589a229
CD
538
539PPI does not preserve newlines. That makes
c38138ab
CD
540CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
541now, it's implemented by pulling the source out of the file and skipping PPI.
542
543It's unlikely that PPI will support mixde newlines anytime soon.
544
2b7b1533 545
ef919624
CD
546=item Operators
547
548ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
549for PPI bugs with parsing operators. Many of these bugs have been
550fixed in PPI, so it would be good to check if those workarounds are
551still needed.
552
2b7b1533 553
6a4d1045
CD
554=item Regexp methods
555
556Not strictly a bug -- the PPI Regexp classes have a dearth of accessor methods
557as of v1.118, meaning that we have to do messy digging into internals. I
558wrote Perl::Critic:Utils::PPIRegexp to encapsulate this messiness, but it
559would be nicer to have an official interface in PPI.
560
2b7b1533 561
daad783f 562=back
501ee198 563
85e38a07 564=cut
dfe2eb3f
JRT
565
566##############################################################################
567# Local Variables:
568# mode: cperl
569# cperl-indent-level: 4
570# fill-column: 78
571# indent-tabs-mode: nil
572# c-indentation-style: bsd
573# End:
96fed375 574# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab shiftround :