Login
Whoops. In r1977, the PPI optimization in
[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
JRT
10
11=head1 SOURCE
daad783f
AL
12
13 #######################################################################
14 # $URL$
15 # $Date$
16 # $Author$
17 # $Revision$
18 #######################################################################
19
de8cacdb
CD
20=head1 SEE ALSO
21
22Perl-Critic-More is a separate distribution for less-widely-accepted
ab1cd5d7 23policies. It contains its own TODO.pod.
de8cacdb 24
daad783f
AL
25=head1 NEW FEATURES
26
27=over 4
28
8b5892fc 29=item * Report Safari sections in addition to book page numbers.
9bc546d7 30
039ec6b9
ES
31=item * Allow policies to say that they've had enough and to not use them for the rest of the current document.
32
33Primarily for things like C<RequireUseStrict> and C<ProhibitMagicNumbers>.
2ad35e86 34Replace current workaround for C<RequireUseStrict>.
039ec6b9 35
d0e776fc
ES
36=item * Add --prohibit-unrestricted-no-critic option to F<perlcritic>.
37
38Requires C<## no critic> to take an argument:
39
40 ## no critic (SomePolicyPattern) # ok
41 ## no critic # not ok
42
43Can't be done as a Policy because any line that violated it would disable it.
44
ad5f2c12
ES
45=item * Support for C<#line 123 "filename"> directives.
46
47For code generators and template languages that allow inline Perl code.
48
96fa2db5
ES
49Yes, somebody has an in-house templating system where they've written a custom
50test module that extracts the perl code from a template and critiques it.
51
d1d6429f
AL
52=back
53
daad783f
AL
54=head1 BUGS/LIMITATIONS
55
56=over 4
57
daad783f
AL
58=item * Modules::RequireVersionVar
59
60Doesn't enforce three-part versions
61
62=item * NamingConventions::ProhibitAmbiguousNames
63
64Don't allow compound names with forbidden words, like "last_record".
65Allow forbidden words in RHS of variable declarations
66
fd5bd7b5
JRT
67Also, we should make it easeir to add (or delete) words from the
68forbbiden list.
69
daad783f
AL
70=item * Subroutines::ProtectPrivateSubs
71
72Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
73difference between that and C<< $self->_foo() >>
74
d1d6429f
AL
75=item * ErrorHandling::RequireCarping
76
63124782 77This should not complain about using C<warn> or C<die> if it's not in a
df88f751 78function, or if it's not in a non-main:: package.
d1d6429f 79
63124782 80Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 81
4c542233
AL
82=item * RegularExpressions::ProhibitCaptureWithoutTest
83
84Allow this construct:
85
86 for ( ... ) {
87 next unless /(....)/;
88 if ( $1 ) {
89 ....
90 }
91 }
92
93Right now, P::C thinks that the C<$1> isn't legal to use because it's
94"outside" of the match. The thing is, we can only get to the C<if>
95if the regex matched.
dfe2eb3f 96 while ( $str =~ /(expression)/ )
4c542233 97
d9abc689
JRT
98=item * CodeLayout::ProhibitParensWithBuiltins
99
100Some builtin functions (particularly those that take a variable number of
101scalar arguments) should probably get parens. This policy should be enhanced
102to allow the user to specify a list of builtins that are expempt from the
103policy.
104
9fb2d1dc
AM
105=item * InputOutput::RequireCheckedOpen and RequireCheckedClose
106
107These policies should not report violations if 'use Fatal' is in effect.
108
96280e8c
ES
109=item * TestingAndDebugging::RequireUseWarnings
110
111Check for -w on the shbang line.
112
365e3d9d
AL
113=back
114
daad783f
AL
115=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
116
cbb58756
CD
117All the ones we formerly listed here are now done. Feel free to thumb through
118PBP and add more here.
daad783f
AL
119
120=head1 NON-PBP POLICIES WANTED
121
122=over 4
123
0b15f123
ES
124=item * ErrorHandling::RequireCheckOfEvalErrorAfterEval
125
df88f751
AL
126=item * TBD::VariableNotUsed
127
128Detect a variable that has a value assigned to it, but never used.
129
130=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
131
132Anything that is a program should have a shebang line. This includes .t files.
133
daad783f
AL
134=item * BuiltInFunctions::RequireConstantSprintfFormat
135
136=item * BuiltInFunctions::RequireConstantUnpackFormat
137
1cc04072 138L<http://diotalevi.isa-geek.net/~josh/yapc-lint/slides/slide5.html>
daad783f 139
dfe2eb3f
JRT
140=item * Miscellanea::ProhibitObnoxiousComments
141
142Forbid excessive hash marks e.g. "#### This is a loud comment ####".
143Make the obnoxious pattern configurable
144
145=item * ValuesAndExpressions::RequireNotOperator
146
147Require the use of "not" instead of "!", except when this would contradict
148ProhibitMixedBooleanOperators. This may be better suited for
149Perl::Critic::More.
150
151=item * Modules::RequireExplicitImporting
152
153Require every C<use> statement to have an explicit import list. You could
154still get around this by calling C<import> directly.
155
156=item * Modules::ForbidImporting
157
158Require every C<use> to have an explicitly empty import list. This is for
159folks who like to see fully-qualified function names. Should probably provide
160a list of exempt modules (like FindBin);
161
daad783f
AL
162=item * ControlStructures::ProhibitIncludeViaDo
163
164Forbid C<do "foo.pl">. Not sure about this policy name.
165
daad783f
AL
166=item * Variables::ProhibitUseVars
167
f707b14a
CD
168Disallow C<use vars qw(...)> and require C<our $foo> instead. This
169contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
170before applying this policy. Low severity.
daad783f
AL
171
172=item * VariablesAndExpressions::ProhibitQuotedHashKeys
173
174Forbid quotes around hash keys, unless they are really needed. This
175is against what Damian says. Suggested by Adam Kennedy. Low
176severity.
177
b589a229 178=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
179
180Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
181
182=item * VariablesAndExpressions::RequireConstantVersion (low severity)
183
f707b14a
CD
184=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
185
daad783f
AL
186L<http://rt.cpan.org/Ticket/Display.html?id=20439>
187
79b72614
CD
188=item * Documentation::RequireSynopsis
189
190=item * Documentation::RequireLicense
191
192These are simplified versions of Documentation::RequirePodSections.
193
6a4d1045
CD
194=item * Documentation::RequireValidSynopsis
195
196The Synopsis section must be all indented and must be syntactically valid Perl
197(as validated by PPI).
198
90c0067c
CD
199=item * Documentation::ProhibitEmptySections
200
201Any C<=headN> and C<=over> sections must not be empty. This helps catch
202boilerplate (althought Test::Pod should catch empty C<=over> blocks).
203
204On the other hand, C<=item ...> sections can be empty, since the item label is
205content.
206
79b72614
CD
207=item * Miscellaneous::ProhibitBoilerplate
208
b589a229 209Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 210etc.
c6e7b236 211
ef919624
CD
212Here's a non-PPI implementation:
213L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
214
956825ec
CD
215=item * BuiltinFunctions::ProhibitExtraneousScalarCall
216
217Recommend that C<if (scalar @array)> be rewritten as C<if (@array)>.
218
6a4d1045
CD
219=item * RegularExpressions::ProhibitMixedDelimiters
220
221Ban s{foo}(bar)
222
c79c8b5b
CD
223=item * RegularExpressions::ProhibitScalarAsRegexp
224
225Ban naked srtings as regexps, like:
226
227 print 1 if $str =~ $regexp;
228
229Instead, it should be:
230
231 print 1 if $str =~ m/$regexp/;
232
233or
234
235 print 1 if $str =~ m/$regexp/xms;
236
237
6a4d1045
CD
238=item * ValuesAndExpressions::RequireInterpolatedStringyEval
239
240Ensure that the argument to a stringy eval is not a constant string. That's
241just wasteful. Real world examples include:
242
243 eval 'use Optional::Module';
244
245which is better written as
246
247 eval { require Optional::Module; Optional::Module->import };
248
249for performance gains and compile-time syntax checking.
250
76a987f3
CD
251=item * RegularExpressions::ProhibitUnnecessaryEscapes
252
253Complain if user puts a backslash escape in front of non-special characters. For example:
254
255 m/\!/;
256
257Make exceptions for C<\">, C<\'> and C<\`> since those are often inserted to
258workaround bugs in syntax highlighting.
259
260Note that this is different inside character classes, where only C<^>, C<]>
261and C<-> need to be escaped, I think. Caret only needs to be escaped at the
262beginning, and dash does NOT need to be escaped at the beginning and end. See
263L<perlreref>.
264
daad783f
AL
265=back
266
267=head1 REFACTORINGS and ENHANCEMENTS
268
269=over 4
270
628facda
ES
271=item * Create constants for the PPI location array elements.
272
992600be
JRT
273=item * MOVE THE LINE-DISABLING INTO P::C::Document
274
275All the code that deals with finding all the '##no critic' comments and noting
276which policies are disabled at each line seems like it would be better placed
277in Perl::Critic::Document. P::C::Document could then provide methods to
278indicate if a policy is disabled at a particular line. So the basic algorithm
279in Perl::Critic might look something like this:
280
281 foreach $element (@PPI_ELEMENTS) {
282 foreach $policy (@POLICIES) {
283 $line = $element->location->[0];
284 next if $doc->policy_is_disabled_at_line( $policy, $line );
285 push @violations, $policy->violates( $elem, $doc );
286 }
287 }
288
aae75e29
ES
289=item * Some means of detecting "runnaway" C<##no critic>
290
291Elliot was talking to a couple of users at ETech and one of their major
292concerns was that they were using C<##no critic> and forgetting to do a
293C<##use critic> after the problematic section. Perhaps an option to
294F<perlcritic> to scan for such things is in order.
295
dfe2eb3f
JRT
296=item * Change API to use named parameters
297
298Most of the methods on the public classes use named parameters for passing
299arguments. I'd like to extend that pattern to include all object-methods.
300Static methods can still use positional parameters.
301
302=item * Allow more flexible Policy parameter parsing
303
304Several policies use C<words_from_string()> to split their parameters into
305words. This function is currently limited to splitting on whitespace. It
306would be nice to allow some lattitude for users who might try and use commas
307or some other kind of delimiter.
308
309=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 310
9b8f64cf 311Just like F<bin/perlcritic> does now.
daad783f 312
9b8f64cf
CD
313=item * Add C<-cache> flag to F<bin/perlcritic>
314
315If enabled, this turns on L<PPI::Cache>:
316
317 require PPI::Cache;
318 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
319 mkdir $cache_path, oct 700 if (! -d $cache_path);
320 PPI::Cache->import(path => $cache_path);
321
de8cacdb 322This cachedir should perhaps include the PPI version number! At least
84e87307 323until PPI incorporates its own version number in the cache.
9b8f64cf 324
de8cacdb 325(see F<t/40_criticize.t> for a more robust implementation)
79b72614 326
c5bd966c
JRT
327=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
328
329In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
330a string is a member of a list. Instead, I suggest using a named
331subroutine that does a hash-lookup like this:
332
333 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
334 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
335
9b8f64cf
CD
336=back
337
338=head1 PPI BUGS
339
340We're waiting on the following bugs to get fixed in a CPAN release of PPI:
341
342=over 4
343
c38138ab 344=item Newlines
b589a229
CD
345
346PPI does not preserve newlines. That makes
c38138ab
CD
347CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
348now, it's implemented by pulling the source out of the file and skipping PPI.
349
350It's unlikely that PPI will support mixde newlines anytime soon.
351
ef919624
CD
352=item Operators
353
354ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
355for PPI bugs with parsing operators. Many of these bugs have been
356fixed in PPI, so it would be good to check if those workarounds are
357still needed.
358
6a4d1045
CD
359=item Regexp methods
360
361Not strictly a bug -- the PPI Regexp classes have a dearth of accessor methods
362as of v1.118, meaning that we have to do messy digging into internals. I
363wrote Perl::Critic:Utils::PPIRegexp to encapsulate this messiness, but it
364would be nicer to have an official interface in PPI.
365
daad783f 366=back
501ee198 367
85e38a07 368=cut
dfe2eb3f
JRT
369
370##############################################################################
371# Local Variables:
372# mode: cperl
373# cperl-indent-level: 4
374# fill-column: 78
375# indent-tabs-mode: nil
376# c-indentation-style: bsd
377# End:
74dfa143 378# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab :