Login
New policy InputOutput::RequireCheckedSyscalls
[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
223=item * ValuesAndExpressions::RequireInterpolatedStringyEval
224
225Ensure that the argument to a stringy eval is not a constant string. That's
226just wasteful. Real world examples include:
227
228 eval 'use Optional::Module';
229
230which is better written as
231
232 eval { require Optional::Module; Optional::Module->import };
233
234for performance gains and compile-time syntax checking.
235
76a987f3
CD
236=item * RegularExpressions::ProhibitUnnecessaryEscapes
237
238Complain if user puts a backslash escape in front of non-special characters. For example:
239
240 m/\!/;
241
242Make exceptions for C<\">, C<\'> and C<\`> since those are often inserted to
243workaround bugs in syntax highlighting.
244
245Note that this is different inside character classes, where only C<^>, C<]>
246and C<-> need to be escaped, I think. Caret only needs to be escaped at the
247beginning, and dash does NOT need to be escaped at the beginning and end. See
248L<perlreref>.
249
daad783f
AL
250=back
251
252=head1 REFACTORINGS and ENHANCEMENTS
253
254=over 4
255
628facda
ES
256=item * Create constants for the PPI location array elements.
257
992600be
JRT
258=item * MOVE THE LINE-DISABLING INTO P::C::Document
259
260All the code that deals with finding all the '##no critic' comments and noting
261which policies are disabled at each line seems like it would be better placed
262in Perl::Critic::Document. P::C::Document could then provide methods to
263indicate if a policy is disabled at a particular line. So the basic algorithm
264in Perl::Critic might look something like this:
265
266 foreach $element (@PPI_ELEMENTS) {
267 foreach $policy (@POLICIES) {
268 $line = $element->location->[0];
269 next if $doc->policy_is_disabled_at_line( $policy, $line );
270 push @violations, $policy->violates( $elem, $doc );
271 }
272 }
273
aae75e29
ES
274=item * Some means of detecting "runnaway" C<##no critic>
275
276Elliot was talking to a couple of users at ETech and one of their major
277concerns was that they were using C<##no critic> and forgetting to do a
278C<##use critic> after the problematic section. Perhaps an option to
279F<perlcritic> to scan for such things is in order.
280
dfe2eb3f
JRT
281=item * Change API to use named parameters
282
283Most of the methods on the public classes use named parameters for passing
284arguments. I'd like to extend that pattern to include all object-methods.
285Static methods can still use positional parameters.
286
287=item * Allow more flexible Policy parameter parsing
288
289Several policies use C<words_from_string()> to split their parameters into
290words. This function is currently limited to splitting on whitespace. It
291would be nice to allow some lattitude for users who might try and use commas
292or some other kind of delimiter.
293
294=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 295
9b8f64cf 296Just like F<bin/perlcritic> does now.
daad783f 297
9b8f64cf
CD
298=item * Add C<-cache> flag to F<bin/perlcritic>
299
300If enabled, this turns on L<PPI::Cache>:
301
302 require PPI::Cache;
303 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
304 mkdir $cache_path, oct 700 if (! -d $cache_path);
305 PPI::Cache->import(path => $cache_path);
306
de8cacdb 307This cachedir should perhaps include the PPI version number! At least
84e87307 308until PPI incorporates its own version number in the cache.
9b8f64cf 309
de8cacdb 310(see F<t/40_criticize.t> for a more robust implementation)
79b72614 311
c5bd966c
JRT
312=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
313
314In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
315a string is a member of a list. Instead, I suggest using a named
316subroutine that does a hash-lookup like this:
317
318 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
319 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
320
9b8f64cf
CD
321=back
322
323=head1 PPI BUGS
324
325We're waiting on the following bugs to get fixed in a CPAN release of PPI:
326
327=over 4
328
b589a229
CD
329=item literal()
330
331ValuesAndExpressions::RequireNumberSeparators uses a stringy eval to
332numify. Current PPI SVN has code for the
333PPI::Token::Number->literal() method which numifies from source. When
334we depend on a PPI version higher than 1.118, the _to_number()
335function in that policy can be removed in favor of literal().
336
c38138ab 337=item Newlines
b589a229
CD
338
339PPI does not preserve newlines. That makes
c38138ab
CD
340CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
341now, it's implemented by pulling the source out of the file and skipping PPI.
342
343It's unlikely that PPI will support mixde newlines anytime soon.
344
345=item Anonymous constructors in lists
346
347The following parses wrong in PPI v1.118. A PPI fix is in progress.
348
349 bless( {} );
350
351When this is fixed, uncomment a few tests in t/20_policies_classhierarchies.t
b589a229 352
d2d8975c
ES
353=item Hash constructors with a parenthesis directly to the left.
354
355The L<PPI::Statement> surrounding the L<PPI::Constructor> returns undef
356for C<location()> for the following:
357
358 ({})
359
360The same problem exists for
361
362 ({} )
363
364but not for
365
366 ( {})
367
368Logged as RT #23788.
369
370Remove trinary operator usage in RequireUseStrict, RequireUseWarnings, and
371RequireExplicitPackage once this is fixed.
372
c948abe5
ES
373=item L<PPI::Structure::Block>s being generated instead of L<PPI::Structure::Constructor>
374
375For complicated data structures, C<< { blah => blah } >> will result in a
376L<PPI::Structure::Block> being created, instead of a
377L<PPI::Structure::Constructor>.
378
379ValuesAndExpressions::ProhibitCommaSeparatedStatements and other policies have
380workarounds for this.
381
ef919624
CD
382=item Operators
383
384ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
385for PPI bugs with parsing operators. Many of these bugs have been
386fixed in PPI, so it would be good to check if those workarounds are
387still needed.
388
6a4d1045
CD
389=item Regexp methods
390
391Not strictly a bug -- the PPI Regexp classes have a dearth of accessor methods
392as of v1.118, meaning that we have to do messy digging into internals. I
393wrote Perl::Critic:Utils::PPIRegexp to encapsulate this messiness, but it
394would be nicer to have an official interface in PPI.
395
daad783f 396=back
501ee198 397
85e38a07 398=cut
dfe2eb3f
JRT
399
400##############################################################################
401# Local Variables:
402# mode: cperl
403# cperl-indent-level: 4
404# fill-column: 78
405# indent-tabs-mode: nil
406# c-indentation-style: bsd
407# End:
74dfa143 408# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab :