Login
Bump PPI version requirement to 1.203.
[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
517c4d69
ES
117=item * Don't kill entire run if PPI::Document cannot be instantiated.
118
119Just say that the individual file is bad and skip to the next one.
120
121
daad783f
AL
122=item * Modules::RequireVersionVar
123
124Doesn't enforce three-part versions
125
2b7b1533 126
daad783f
AL
127=item * NamingConventions::ProhibitAmbiguousNames
128
129Don't allow compound names with forbidden words, like "last_record".
130Allow forbidden words in RHS of variable declarations
131
fd5bd7b5
JRT
132Also, we should make it easeir to add (or delete) words from the
133forbbiden list.
134
2b7b1533 135
daad783f
AL
136=item * Subroutines::ProtectPrivateSubs
137
138Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
139difference between that and C<< $self->_foo() >>
140
2b7b1533 141
d1d6429f
AL
142=item * ErrorHandling::RequireCarping
143
63124782 144This should not complain about using C<warn> or C<die> if it's not in a
df88f751 145function, or if it's not in a non-main:: package.
d1d6429f 146
63124782 147Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 148
2b7b1533 149
4c542233
AL
150=item * RegularExpressions::ProhibitCaptureWithoutTest
151
152Allow this construct:
153
154 for ( ... ) {
155 next unless /(....)/;
156 if ( $1 ) {
157 ....
158 }
159 }
160
161Right now, P::C thinks that the C<$1> isn't legal to use because it's
162"outside" of the match. The thing is, we can only get to the C<if>
163if the regex matched.
dfe2eb3f 164 while ( $str =~ /(expression)/ )
4c542233 165
2b7b1533 166
d9abc689
JRT
167=item * CodeLayout::ProhibitParensWithBuiltins
168
169Some builtin functions (particularly those that take a variable number of
c296c678
ES
170scalar arguments) should probably get parentheses. This policy should be
171enhanced to allow the user to specify a list of builtins that are expempt
172from the policy.
d9abc689 173
2b7b1533 174
9fb2d1dc
AM
175=item * InputOutput::RequireCheckedOpen and RequireCheckedClose
176
177These policies should not report violations if 'use Fatal' is in effect.
178
2b7b1533 179
c59ac28c
ES
180=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements
181
182Needs to check for C<scalar( something, something )>.
183
184
d6dc5ff8
ES
185=item * ValuesAndExpressions::ProhibitMagicNumbers
186
187The C<allowed_values> option needs to handle ranges.
188
189Needs to be tested against a wider range of $VERSION declarations.
190
191
96280e8c
ES
192=item * TestingAndDebugging::RequireUseWarnings
193
194Check for -w on the shbang line.
195
2b7b1533 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
be48b0c6
ES
215=item * Expressions::RequireFatCommasInHashConstructors
216
0b15f123
ES
217=item * ErrorHandling::RequireCheckOfEvalErrorAfterEval
218
77fa21bd
ES
219=item * Expressions::ProhibitDecimalWithBitwiseOperator
220
221=item * Expressions::ProhibitStringsWithBitwiseOperator
222
2b7b1533 223
3264a614
ES
224=item * InputOutput::ProhibitMagicDiamond
225
226Steal the idea from L<B::Lint>.
227
228
df88f751
AL
229=item * TBD::VariableNotUsed
230
d19608d1 231Detect a variable that is declared, but never used.
df88f751 232
2b7b1533 233
df88f751 234=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
235
236Anything that is a program should have a shebang line. This includes .t files.
237
2b7b1533 238
daad783f
AL
239=item * BuiltInFunctions::RequireConstantSprintfFormat
240
2b7b1533 241
daad783f
AL
242=item * BuiltInFunctions::RequireConstantUnpackFormat
243
1cc04072 244L<http://diotalevi.isa-geek.net/~josh/yapc-lint/slides/slide5.html>
daad783f 245
2b7b1533 246
dfe2eb3f
JRT
247=item * Miscellanea::ProhibitObnoxiousComments
248
249Forbid excessive hash marks e.g. "#### This is a loud comment ####".
250Make the obnoxious pattern configurable
251
2b7b1533 252
dfe2eb3f
JRT
253=item * ValuesAndExpressions::RequireNotOperator
254
255Require the use of "not" instead of "!", except when this would contradict
256ProhibitMixedBooleanOperators. This may be better suited for
257Perl::Critic::More.
258
2b7b1533 259
dfe2eb3f
JRT
260=item * Modules::RequireExplicitImporting
261
262Require every C<use> statement to have an explicit import list. You could
263still get around this by calling C<import> directly.
264
2b7b1533 265
dfe2eb3f
JRT
266=item * Modules::ForbidImporting
267
268Require every C<use> to have an explicitly empty import list. This is for
269folks who like to see fully-qualified function names. Should probably provide
270a list of exempt modules (like FindBin);
271
2b7b1533 272
daad783f
AL
273=item * ControlStructures::ProhibitIncludeViaDo
274
275Forbid C<do "foo.pl">. Not sure about this policy name.
276
2b7b1533 277
daad783f
AL
278=item * Variables::ProhibitUseVars
279
f707b14a
CD
280Disallow C<use vars qw(...)> and require C<our $foo> instead. This
281contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
282before applying this policy. Low severity.
daad783f 283
2b7b1533 284
daad783f
AL
285=item * VariablesAndExpressions::ProhibitQuotedHashKeys
286
287Forbid quotes around hash keys, unless they are really needed. This
288is against what Damian says. Suggested by Adam Kennedy. Low
289severity.
290
2b7b1533 291
b589a229 292=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
293
294Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
295
2b7b1533 296
7eec5b31
ES
297=item * RegularExpressions::ProhibitSWSWSW
298
299Require C<split> instead of C<m/\s*\w*\s*\w*\s*/>. From MJD's Red Flags.
300
301
daad783f
AL
302=item * VariablesAndExpressions::RequireConstantVersion (low severity)
303
2b7b1533 304
f707b14a
CD
305=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
306
daad783f
AL
307L<http://rt.cpan.org/Ticket/Display.html?id=20439>
308
2b7b1533 309
79b72614
CD
310=item * Documentation::RequireSynopsis
311
2b7b1533 312
79b72614
CD
313=item * Documentation::RequireLicense
314
315These are simplified versions of Documentation::RequirePodSections.
316
2b7b1533 317
6a4d1045
CD
318=item * Documentation::RequireValidSynopsis
319
320The Synopsis section must be all indented and must be syntactically valid Perl
321(as validated by PPI).
322
2b7b1533 323
90c0067c
CD
324=item * Documentation::ProhibitEmptySections
325
326Any C<=headN> and C<=over> sections must not be empty. This helps catch
327boilerplate (althought Test::Pod should catch empty C<=over> blocks).
328
329On the other hand, C<=item ...> sections can be empty, since the item label is
330content.
331
2b7b1533 332
79b72614
CD
333=item * Miscellaneous::ProhibitBoilerplate
334
b589a229 335Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 336etc.
c6e7b236 337
ef919624
CD
338Here's a non-PPI implementation:
339L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
340
2b7b1533 341
956825ec
CD
342=item * BuiltinFunctions::ProhibitExtraneousScalarCall
343
344Recommend that C<if (scalar @array)> be rewritten as C<if (@array)>.
345
2b7b1533 346
6a4d1045
CD
347=item * RegularExpressions::ProhibitMixedDelimiters
348
349Ban s{foo}(bar)
350
2b7b1533 351
c79c8b5b
CD
352=item * RegularExpressions::ProhibitScalarAsRegexp
353
354Ban naked srtings as regexps, like:
355
356 print 1 if $str =~ $regexp;
357
358Instead, it should be:
359
360 print 1 if $str =~ m/$regexp/;
361
362or
363
364 print 1 if $str =~ m/$regexp/xms;
365
366
6a4d1045
CD
367=item * ValuesAndExpressions::RequireInterpolatedStringyEval
368
369Ensure that the argument to a stringy eval is not a constant string. That's
370just wasteful. Real world examples include:
371
372 eval 'use Optional::Module';
373
374which is better written as
375
376 eval { require Optional::Module; Optional::Module->import };
377
378for performance gains and compile-time syntax checking.
379
2b7b1533 380
76a987f3
CD
381=item * RegularExpressions::ProhibitUnnecessaryEscapes
382
383Complain if user puts a backslash escape in front of non-special characters. For example:
384
385 m/\!/;
386
387Make exceptions for C<\">, C<\'> and C<\`> since those are often inserted to
388workaround bugs in syntax highlighting.
389
390Note that this is different inside character classes, where only C<^>, C<]>
391and C<-> need to be escaped, I think. Caret only needs to be escaped at the
392beginning, and dash does NOT need to be escaped at the beginning and end. See
393L<perlreref>.
394
2b7b1533 395
fef95802
ES
396=item * Steal ideas from L<Dunce::Files>.
397
398
daad783f
AL
399=back
400
2b7b1533 401
daad783f
AL
402=head1 REFACTORINGS and ENHANCEMENTS
403
2b7b1533 404=over
daad783f 405
628facda
ES
406=item * Create constants for the PPI location array elements.
407
2b7b1533 408
992600be
JRT
409=item * MOVE THE LINE-DISABLING INTO P::C::Document
410
411All the code that deals with finding all the '##no critic' comments and noting
412which policies are disabled at each line seems like it would be better placed
413in Perl::Critic::Document. P::C::Document could then provide methods to
414indicate if a policy is disabled at a particular line. So the basic algorithm
415in Perl::Critic might look something like this:
416
417 foreach $element (@PPI_ELEMENTS) {
418 foreach $policy (@POLICIES) {
419 $line = $element->location->[0];
420 next if $doc->policy_is_disabled_at_line( $policy, $line );
421 push @violations, $policy->violates( $elem, $doc );
422 }
423 }
424
2b7b1533 425
aae75e29
ES
426=item * Some means of detecting "runnaway" C<##no critic>
427
428Elliot was talking to a couple of users at ETech and one of their major
429concerns was that they were using C<##no critic> and forgetting to do a
430C<##use critic> after the problematic section. Perhaps an option to
431F<perlcritic> to scan for such things is in order.
432
2b7b1533 433
dfe2eb3f
JRT
434=item * Change API to use named parameters
435
436Most of the methods on the public classes use named parameters for passing
437arguments. I'd like to extend that pattern to include all object-methods.
438Static methods can still use positional parameters.
439
2b7b1533 440
dfe2eb3f
JRT
441=item * Allow more flexible Policy parameter parsing
442
443Several policies use C<words_from_string()> to split their parameters into
444words. This function is currently limited to splitting on whitespace. It
445would be nice to allow some lattitude for users who might try and use commas
446or some other kind of delimiter.
447
2b7b1533 448
dfe2eb3f 449=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 450
9b8f64cf 451Just like F<bin/perlcritic> does now.
daad783f 452
2b7b1533 453
9b8f64cf
CD
454=item * Add C<-cache> flag to F<bin/perlcritic>
455
456If enabled, this turns on L<PPI::Cache>:
457
458 require PPI::Cache;
459 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
460 mkdir $cache_path, oct 700 if (! -d $cache_path);
461 PPI::Cache->import(path => $cache_path);
462
de8cacdb 463This cachedir should perhaps include the PPI version number! At least
84e87307 464until PPI incorporates its own version number in the cache.
9b8f64cf 465
de8cacdb 466(see F<t/40_criticize.t> for a more robust implementation)
79b72614 467
2b7b1533 468
c5bd966c
JRT
469=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
470
471In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
472a string is a member of a list. Instead, I suggest using a named
473subroutine that does a hash-lookup like this:
474
475 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
476 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
477
2b7b1533
ES
478
479=item * Allow color output to work through a pipe.
480
481http://rt.cpan.org/Ticket/Display.html?id=30140
482
233e8deb
ES
483F<ack> now supports this.
484
2b7b1533 485
9b8f64cf
CD
486=back
487
488=head1 PPI BUGS
489
490We're waiting on the following bugs to get fixed in a CPAN release of PPI:
491
2b7b1533
ES
492
493=over
9b8f64cf 494
c38138ab 495=item Newlines
b589a229
CD
496
497PPI does not preserve newlines. That makes
c38138ab
CD
498CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
499now, it's implemented by pulling the source out of the file and skipping PPI.
500
501It's unlikely that PPI will support mixde newlines anytime soon.
502
2b7b1533 503
ef919624
CD
504=item Operators
505
506ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
507for PPI bugs with parsing operators. Many of these bugs have been
508fixed in PPI, so it would be good to check if those workarounds are
509still needed.
510
2b7b1533 511
6a4d1045
CD
512=item Regexp methods
513
514Not strictly a bug -- the PPI Regexp classes have a dearth of accessor methods
515as of v1.118, meaning that we have to do messy digging into internals. I
516wrote Perl::Critic:Utils::PPIRegexp to encapsulate this messiness, but it
517would be nicer to have an official interface in PPI.
518
2b7b1533 519
d6dc5ff8
ES
520=item Hash constructors being parsed as blocks
521
522ValuesAndExpressions::ProhibitMagicNumbers has a performance optimization that
523can't be done because it can't tell whether a block is really a block or not.
524
525When fixed, uncomment the lines in
526_element_is_in_an_include_or_readonly_statement().
527
528
92e27ee0
ES
529=item Labels
530
531PPI doesn't treat labels with whitepace between them and the following colon
532as labels. Remove TODO from
533F<t/ControlStructures/ProhibitLabelsWithSpecialBlockNames.run> once the fix is
534released.
535
d6dc5ff8 536
d6dc5ff8
ES
537
538
daad783f 539=back
501ee198 540
85e38a07 541=cut
dfe2eb3f
JRT
542
543##############################################################################
544# Local Variables:
545# mode: cperl
546# cperl-indent-level: 4
547# fill-column: 78
548# indent-tabs-mode: nil
549# c-indentation-style: bsd
550# End:
96fed375 551# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab shiftround :