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