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