Login
Added workaround for RT #27065. There might be an alternative
[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
f7231315 9TODO - 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
d1d6429f
AL
36=back
37
daad783f
AL
38=head1 BUGS/LIMITATIONS
39
40=over 4
41
daad783f
AL
42=item * Modules::RequireVersionVar
43
44Doesn't enforce three-part versions
45
46=item * NamingConventions::ProhibitAmbiguousNames
47
48Don't allow compound names with forbidden words, like "last_record".
49Allow forbidden words in RHS of variable declarations
50
fd5bd7b5
JRT
51Also, we should make it easeir to add (or delete) words from the
52forbbiden list.
53
daad783f
AL
54=item * Subroutines::ProtectPrivateSubs
55
56Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
57difference between that and C<< $self->_foo() >>
58
d1d6429f
AL
59=item * ErrorHandling::RequireCarping
60
63124782 61This should not complain about using C<warn> or C<die> if it's not in a
df88f751 62function, or if it's not in a non-main:: package.
d1d6429f 63
63124782 64Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 65
4c542233
AL
66=item * RegularExpressions::ProhibitCaptureWithoutTest
67
68Allow this construct:
69
70 for ( ... ) {
71 next unless /(....)/;
72 if ( $1 ) {
73 ....
74 }
75 }
76
77Right now, P::C thinks that the C<$1> isn't legal to use because it's
78"outside" of the match. The thing is, we can only get to the C<if>
79if the regex matched.
dfe2eb3f 80 while ( $str =~ /(expression)/ )
4c542233 81
d9abc689
JRT
82=item * CodeLayout::ProhibitParensWithBuiltins
83
84Some builtin functions (particularly those that take a variable number of
85scalar arguments) should probably get parens. This policy should be enhanced
86to allow the user to specify a list of builtins that are expempt from the
87policy.
88
9fb2d1dc
AM
89=item * InputOutput::RequireCheckedOpen and RequireCheckedClose
90
91These policies should not report violations if 'use Fatal' is in effect.
92
365e3d9d
AL
93=back
94
daad783f
AL
95=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
96
365e3d9d
AL
97=over 4
98
0ab066f7
JRT
99=item * ControlStructures::ProhibitComplexMappings (p113)
100
101Base this on RequireSimpleSortBlock. Make number of statements configurable
102
daad783f
AL
103=item * ValuesAndExpressions::RequireListParens (p71)
104
105=item * ValuesAndExpressions::ProhibitScalarGrep (p71)
106
df88f751 107Look for C<grep> in a scalar context and recommend C<any()> instead.
71cb5eb8 108Perhaps we need to distinguish cases like:
7e9a4c52
AL
109
110 $count += grep {qr/foo/} @list;
daad783f 111
df88f751
AL
112OTOH, this assumes that the common use of scalar grep is to check
113for existence. I'm not sure that's the case.
114
8fb63e09
JRT
115=item * ValuesAndExpressions::ProhibitImplicitNewlines (p60-61)
116
117Forbid multi-line strings with implicit newlines. Use concatenation or
118heredoc instead.
119
daad783f
AL
120=item * Variables::RequireLocalizedPunctuationVars (p81)
121
daad783f
AL
122=item * Documentation::PodSpelling (p148)
123
124Base it on Pod::Spell or Test::Spelling. Add a "=for stopwords"
125section for words to skip, as per Pod::Spell.
126
daad783f
AL
127=item * Subroutines::RequireArgUnpacking (p178)
128
129Ensure that the first child of a sub is PPI::Statement::Variable
71cb5eb8 130(unless the sub has N or fewer statements, where N defaults to 1.
daad783f
AL
131
132=item * Subroutines::ProhibitManyArgs (p182)
133
71cb5eb8
CD
134If first L<PPI::Statement::Variable> is a list C<my>, and @_ is used,
135make sure it's fewer than N elements. Otherwise make sure there are
136less than N L<PPI::Statement::Variable>s in a row at begin which
137shift.
daad783f 138
9fb2d1dc 139=item * InputOutput::RequireChecked* for system calls (p208)
daad783f 140
9fb2d1dc
AM
141Add policies to ensure checking the return values of system calls. See
142InputOutputRequireCheckedOpen.
daad783f
AL
143
144=item * InputOutput::RequireBriefOpen (p209)
145
146Make sure there's a close within N statements of an open, both with
147same lexical FH
148
149=item * InputOutput::ProhibitJoinedReadline (p213)
150
151=item * InputOutput::ProhibitExplicitStdin (p216)
152
df88f751
AL
153If you're reading from STDIN, chances are you're really wanting to
154read from the magic filehandle.
155
daad783f
AL
156=item * RegularExpressions::RequireBracesForMultiline (p242)
157
158=item * RegularExpressions::ProhibitUnusualDelimiters (p246)
159
160=item * RegularExpressions::ProhibitEscapedMetacharacters (p247)
161
162=item * RegularExpressions::ProhibitEnumeratedClasses (p248)
163
df88f751 164This will be avoided for ASCII-only code.
daad783f
AL
165
166=item * RegularExpressions::ProhibitUnusedCapture (p252)
167
168Look for LHS of regexp or use of C<$1>, C<$2>, ... before next
df88f751 169regexp.
daad783f 170
daad783f
AL
171=item * RegularExpressions::ProhibitComplexRegexps (p261)
172
173If regexp is longer than N characters/lines, require it be split
174into C<qr//> pieces.
175
176=item * RegularExpressions::ProhibitSingleCharAlternation (p265)
177
178Not sure if this is easy or hard. Need to look at what PPI emits
1fd10f9b 179for regexps. Make an exception for qr/ [ ] /x.
daad783f
AL
180
181=item * RegularExpressions::ProhibitFixedStringMatches (p271)
182
183Can't be C<qr/\s*\\A\s*\((?:\?:)?(?:\s*\w+\s*\|)*\s*\w+\s*\)\s*\\z/>
184or C<qr/\s*\\A\s*\w+\s*\\z/>
185
daad783f
AL
186=back
187
188=head1 NON-PBP POLICIES WANTED
189
190=over 4
191
df88f751
AL
192=item * TBD::VariableNotUsed
193
194Detect a variable that has a value assigned to it, but never used.
195
196=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
197
198Anything that is a program should have a shebang line. This includes .t files.
199
daad783f
AL
200=item * BuiltInFunctions::RequireConstantSprintfFormat
201
202=item * BuiltInFunctions::RequireConstantUnpackFormat
203
1cc04072 204L<http://diotalevi.isa-geek.net/~josh/yapc-lint/slides/slide5.html>
daad783f 205
dfe2eb3f
JRT
206=item * Miscellanea::ProhibitObnoxiousComments
207
208Forbid excessive hash marks e.g. "#### This is a loud comment ####".
209Make the obnoxious pattern configurable
210
211=item * ValuesAndExpressions::RequireNotOperator
212
213Require the use of "not" instead of "!", except when this would contradict
214ProhibitMixedBooleanOperators. This may be better suited for
215Perl::Critic::More.
216
217=item * Modules::RequireExplicitImporting
218
219Require every C<use> statement to have an explicit import list. You could
220still get around this by calling C<import> directly.
221
222=item * Modules::ForbidImporting
223
224Require every C<use> to have an explicitly empty import list. This is for
225folks who like to see fully-qualified function names. Should probably provide
226a list of exempt modules (like FindBin);
227
daad783f
AL
228=item * ControlStructures::ProhibitIncludeViaDo
229
230Forbid C<do "foo.pl">. Not sure about this policy name.
231
daad783f
AL
232=item * Variables::ProhibitUseVars
233
f707b14a
CD
234Disallow C<use vars qw(...)> and require C<our $foo> instead. This
235contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
236before applying this policy. Low severity.
daad783f
AL
237
238=item * VariablesAndExpressions::ProhibitQuotedHashKeys
239
240Forbid quotes around hash keys, unless they are really needed. This
241is against what Damian says. Suggested by Adam Kennedy. Low
242severity.
243
b589a229 244=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
245
246Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
247
248=item * VariablesAndExpressions::RequireConstantVersion (low severity)
249
f707b14a
CD
250=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
251
daad783f
AL
252L<http://rt.cpan.org/Ticket/Display.html?id=20439>
253
79b72614
CD
254=item * Documentation::RequireSynopsis
255
256=item * Documentation::RequireLicense
257
258These are simplified versions of Documentation::RequirePodSections.
259
79b72614
CD
260=item * Miscellaneous::ProhibitBoilerplate
261
b589a229 262Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 263etc.
c6e7b236 264
ef919624
CD
265Here's a non-PPI implementation:
266L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
267
956825ec
CD
268=item * BuiltinFunctions::ProhibitExtraneousScalarCall
269
270Recommend that C<if (scalar @array)> be rewritten as C<if (@array)>.
271
daad783f
AL
272=back
273
274=head1 REFACTORINGS and ENHANCEMENTS
275
276=over 4
277
992600be
JRT
278=item * MOVE THE LINE-DISABLING INTO P::C::Document
279
280All the code that deals with finding all the '##no critic' comments and noting
281which policies are disabled at each line seems like it would be better placed
282in Perl::Critic::Document. P::C::Document could then provide methods to
283indicate if a policy is disabled at a particular line. So the basic algorithm
284in Perl::Critic might look something like this:
285
286 foreach $element (@PPI_ELEMENTS) {
287 foreach $policy (@POLICIES) {
288 $line = $element->location->[0];
289 next if $doc->policy_is_disabled_at_line( $policy, $line );
290 push @violations, $policy->violates( $elem, $doc );
291 }
292 }
293
aae75e29
ES
294=item * Some means of detecting "runnaway" C<##no critic>
295
296Elliot was talking to a couple of users at ETech and one of their major
297concerns was that they were using C<##no critic> and forgetting to do a
298C<##use critic> after the problematic section. Perhaps an option to
299F<perlcritic> to scan for such things is in order.
300
dfe2eb3f
JRT
301=item * Change API to use named parameters
302
303Most of the methods on the public classes use named parameters for passing
304arguments. I'd like to extend that pattern to include all object-methods.
305Static methods can still use positional parameters.
306
307=item * Allow more flexible Policy parameter parsing
308
309Several policies use C<words_from_string()> to split their parameters into
310words. This function is currently limited to splitting on whitespace. It
311would be nice to allow some lattitude for users who might try and use commas
312or some other kind of delimiter.
313
314=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 315
9b8f64cf 316Just like F<bin/perlcritic> does now.
daad783f 317
9b8f64cf
CD
318=item * Add C<-cache> flag to F<bin/perlcritic>
319
320If enabled, this turns on L<PPI::Cache>:
321
322 require PPI::Cache;
323 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
324 mkdir $cache_path, oct 700 if (! -d $cache_path);
325 PPI::Cache->import(path => $cache_path);
326
de8cacdb
CD
327This cachedir should perhaps include the PPI version number! At least
328until PPI incorporates it's own version number in the cache.
9b8f64cf 329
de8cacdb 330(see F<t/40_criticize.t> for a more robust implementation)
79b72614 331
c5bd966c
JRT
332=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
333
334In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
335a string is a member of a list. Instead, I suggest using a named
336subroutine that does a hash-lookup like this:
337
338 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
339 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
340
9b8f64cf
CD
341=back
342
343=head1 PPI BUGS
344
345We're waiting on the following bugs to get fixed in a CPAN release of PPI:
346
347=over 4
348
b589a229
CD
349=item literal()
350
351ValuesAndExpressions::RequireNumberSeparators uses a stringy eval to
352numify. Current PPI SVN has code for the
353PPI::Token::Number->literal() method which numifies from source. When
354we depend on a PPI version higher than 1.118, the _to_number()
355function in that policy can be removed in favor of literal().
356
c38138ab 357=item Newlines
b589a229
CD
358
359PPI does not preserve newlines. That makes
c38138ab
CD
360CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
361now, it's implemented by pulling the source out of the file and skipping PPI.
362
363It's unlikely that PPI will support mixde newlines anytime soon.
364
365=item Anonymous constructors in lists
366
367The following parses wrong in PPI v1.118. A PPI fix is in progress.
368
369 bless( {} );
370
371When this is fixed, uncomment a few tests in t/20_policies_classhierarchies.t
b589a229 372
d2d8975c
ES
373=item Hash constructors with a parenthesis directly to the left.
374
375The L<PPI::Statement> surrounding the L<PPI::Constructor> returns undef
376for C<location()> for the following:
377
378 ({})
379
380The same problem exists for
381
382 ({} )
383
384but not for
385
386 ( {})
387
388Logged as RT #23788.
389
390Remove trinary operator usage in RequireUseStrict, RequireUseWarnings, and
391RequireExplicitPackage once this is fixed.
392
c948abe5
ES
393=item L<PPI::Structure::Block>s being generated instead of L<PPI::Structure::Constructor>
394
395For complicated data structures, C<< { blah => blah } >> will result in a
396L<PPI::Structure::Block> being created, instead of a
397L<PPI::Structure::Constructor>.
398
399ValuesAndExpressions::ProhibitCommaSeparatedStatements and other policies have
400workarounds for this.
401
ef919624
CD
402=item Operators
403
404ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
405for PPI bugs with parsing operators. Many of these bugs have been
406fixed in PPI, so it would be good to check if those workarounds are
407still needed.
408
daad783f 409=back
501ee198 410
85e38a07 411=cut
dfe2eb3f
JRT
412
413##############################################################################
414# Local Variables:
415# mode: cperl
416# cperl-indent-level: 4
417# fill-column: 78
418# indent-tabs-mode: nil
419# c-indentation-style: bsd
420# End:
74dfa143 421# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab :