Login
Modify TODO.pod to reflect RequireCarping changes.
[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
c6e7b236 31=item * Report some statistics on the violations and the source code.
d1d6429f 32
c6e7b236
JRT
33e.g. Number of violations of each policy/severity. Total lines of code,
34number of subroutines, average number of statements/operators per sub.
d1d6429f 35
039ec6b9
ES
36=item * Allow policies to say that they've had enough and to not use them for the rest of the current document.
37
38Primarily for things like C<RequireUseStrict> and C<ProhibitMagicNumbers>.
2ad35e86 39Replace current workaround for C<RequireUseStrict>.
039ec6b9 40
d1d6429f
AL
41=back
42
daad783f
AL
43=head1 BUGS/LIMITATIONS
44
45=over 4
46
039ec6b9 47=item * Invalid policy names in F<.perlcriticrc> do not cause any warnings.
0ab066f7 48
039ec6b9
ES
49Fix for this should not cause T::P::C to fail, because "invalid" may simply
50mean that the policy isn't locally installed.
51
52=item * Invalid parameters in F<.perlcriticrc> do not cause any warnings.
daad783f 53
585ddee1
ES
54=item * Fix inappropriate uses of C<confess>.
55
56E.g. when no files to process have been found or multiple policies match
57the C<--singlepolicy> option.
58
daad783f
AL
59=item * Modules::RequireVersionVar
60
61Doesn't enforce three-part versions
62
63=item * NamingConventions::ProhibitAmbiguousNames
64
65Don't allow compound names with forbidden words, like "last_record".
66Allow forbidden words in RHS of variable declarations
67
68=item * Subroutines::ProtectPrivateSubs
69
70Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
71difference between that and C<< $self->_foo() >>
72
d1d6429f
AL
73=item * ErrorHandling::RequireCarping
74
63124782 75This should not complain about using C<warn> or C<die> if it's not in a
df88f751 76function, or if it's not in a non-main:: package.
d1d6429f 77
63124782 78Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 79
4c542233
AL
80=item * RegularExpressions::ProhibitCaptureWithoutTest
81
82Allow this construct:
83
84 for ( ... ) {
85 next unless /(....)/;
86 if ( $1 ) {
87 ....
88 }
89 }
90
91Right now, P::C thinks that the C<$1> isn't legal to use because it's
92"outside" of the match. The thing is, we can only get to the C<if>
93if the regex matched.
94 while ( $str =~ /(expression)/ )
95
039ec6b9
ES
96=item * Documentation::RequirePodSections
97
98Need to make this configurable to conform to either the book or
99his Module::Starter::PBP, since Damian's apparently changed his mind.
100
365e3d9d
AL
101=back
102
daad783f
AL
103=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
104
365e3d9d
AL
105=over 4
106
0ab066f7
JRT
107=item * ControlStructures::ProhibitComplexMappings (p113)
108
109Base this on RequireSimpleSortBlock. Make number of statements configurable
110
daad783f
AL
111=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements (p68)
112
113=item * ValuesAndExpressions::RequireListParens (p71)
114
115=item * ValuesAndExpressions::ProhibitScalarGrep (p71)
116
df88f751 117Look for C<grep> in a scalar context and recommend C<any()> instead.
71cb5eb8 118Perhaps we need to distinguish cases like:
7e9a4c52
AL
119
120 $count += grep {qr/foo/} @list;
daad783f 121
df88f751
AL
122OTOH, this assumes that the common use of scalar grep is to check
123for existence. I'm not sure that's the case.
124
daad783f
AL
125=item * Variables::RequireLocalizedPunctuationVars (p81)
126
daad783f
AL
127=item * Documentation::PodSpelling (p148)
128
129Base it on Pod::Spell or Test::Spelling. Add a "=for stopwords"
130section for words to skip, as per Pod::Spell.
131
daad783f
AL
132=item * Subroutines::RequireArgUnpacking (p178)
133
134Ensure that the first child of a sub is PPI::Statement::Variable
71cb5eb8 135(unless the sub has N or fewer statements, where N defaults to 1.
daad783f
AL
136
137=item * Subroutines::ProhibitManyArgs (p182)
138
71cb5eb8
CD
139If first L<PPI::Statement::Variable> is a list C<my>, and @_ is used,
140make sure it's fewer than N elements. Otherwise make sure there are
141less than N L<PPI::Statement::Variable>s in a row at begin which
142shift.
daad783f
AL
143
144=item * InputOutput::RequireErrorChecking (p208)
145
71cb5eb8 146Forbid open, print, close in void context, unless "use Fatal" is in
df88f751 147effect. Allow an exception for close and print.
daad783f
AL
148
149=item * InputOutput::RequireBriefOpen (p209)
150
151Make sure there's a close within N statements of an open, both with
152same lexical FH
153
154=item * InputOutput::ProhibitJoinedReadline (p213)
155
156=item * InputOutput::ProhibitExplicitStdin (p216)
157
df88f751
AL
158If you're reading from STDIN, chances are you're really wanting to
159read from the magic filehandle.
160
daad783f
AL
161=item * Miscellanea::ProhibitObnoxiousComments
162
163Forbid excessive hash marks e.g. "#### This is a loud comment ####".
164Make the obnoxious pattern configurable
165
166=item * RegularExpressions::RequireBracesForMultiline (p242)
167
168=item * RegularExpressions::ProhibitUnusualDelimiters (p246)
169
170=item * RegularExpressions::ProhibitEscapedMetacharacters (p247)
171
172=item * RegularExpressions::ProhibitEnumeratedClasses (p248)
173
df88f751 174This will be avoided for ASCII-only code.
daad783f
AL
175
176=item * RegularExpressions::ProhibitUnusedCapture (p252)
177
178Look for LHS of regexp or use of C<$1>, C<$2>, ... before next
df88f751 179regexp.
daad783f 180
daad783f
AL
181=item * RegularExpressions::ProhibitComplexRegexps (p261)
182
183If regexp is longer than N characters/lines, require it be split
184into C<qr//> pieces.
185
186=item * RegularExpressions::ProhibitSingleCharAlternation (p265)
187
188Not sure if this is easy or hard. Need to look at what PPI emits
1fd10f9b 189for regexps. Make an exception for qr/ [ ] /x.
daad783f
AL
190
191=item * RegularExpressions::ProhibitFixedStringMatches (p271)
192
193Can't be C<qr/\s*\\A\s*\((?:\?:)?(?:\s*\w+\s*\|)*\s*\w+\s*\)\s*\\z/>
194or C<qr/\s*\\A\s*\w+\s*\\z/>
195
daad783f
AL
196=back
197
198=head1 NON-PBP POLICIES WANTED
199
200=over 4
201
df88f751
AL
202=item * TBD::VariableNotUsed
203
204Detect a variable that has a value assigned to it, but never used.
205
206=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
207
208Anything that is a program should have a shebang line. This includes .t files.
209
daad783f
AL
210=item * BuiltInFunctions::RequireConstantSprintfFormat
211
212=item * BuiltInFunctions::RequireConstantUnpackFormat
213
214L<http://home.earthlink.net/~josh.jore/new-warnings/slides/slide1.html>
215
216=item * ControlStructures::ProhibitIncludeViaDo
217
218Forbid C<do "foo.pl">. Not sure about this policy name.
219
daad783f
AL
220=item * Variables::ProhibitUseVars
221
f707b14a
CD
222Disallow C<use vars qw(...)> and require C<our $foo> instead. This
223contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
224before applying this policy. Low severity.
daad783f
AL
225
226=item * VariablesAndExpressions::ProhibitQuotedHashKeys
227
228Forbid quotes around hash keys, unless they are really needed. This
229is against what Damian says. Suggested by Adam Kennedy. Low
230severity.
231
b589a229 232=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
233
234Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
235
236=item * VariablesAndExpressions::RequireConstantVersion (low severity)
237
f707b14a
CD
238=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
239
daad783f
AL
240L<http://rt.cpan.org/Ticket/Display.html?id=20439>
241
c6e7b236
JRT
242=item * Variables::ProhibitPerl4PackageNames
243
b589a229 244Forbid old-school package names like Foo'Bar'Baz. This should also
c6e7b236
JRT
245apply to any variables or subroutines that get declared/called.
246
79b72614
CD
247=item * Documentation::RequireSynopsis
248
249=item * Documentation::RequireLicense
250
251These are simplified versions of Documentation::RequirePodSections.
252
79b72614
CD
253=item * Miscellaneous::ProhibitBoilerplate
254
b589a229 255Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 256etc.
c6e7b236 257
ef919624
CD
258Here's a non-PPI implementation:
259L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
260
c38138ab
CD
261=item * CodeLayout::ProhibitTrailingSpaces
262
263Forbid [ \t] before \n. This is a subset of RequireTidyCode.
264
265L<http://rt.cpan.org/Ticket/Display.html?id=20714>
266
daad783f
AL
267=back
268
269=head1 REFACTORINGS and ENHANCEMENTS
270
271=over 4
272
501ee198
JRT
273=item * Enhance P::C::critique() to accept file names, directories, or code strings (as refs)
274
9b8f64cf 275Just like F<bin/perlcritic> does now.
daad783f 276
9b8f64cf
CD
277=item * Add C<-cache> flag to F<bin/perlcritic>
278
279If enabled, this turns on L<PPI::Cache>:
280
281 require PPI::Cache;
282 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
283 mkdir $cache_path, oct 700 if (! -d $cache_path);
284 PPI::Cache->import(path => $cache_path);
285
de8cacdb
CD
286This cachedir should perhaps include the PPI version number! At least
287until PPI incorporates it's own version number in the cache.
9b8f64cf 288
de8cacdb 289(see F<t/40_criticize.t> for a more robust implementation)
79b72614 290
c5bd966c
JRT
291=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
292
293In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
294a string is a member of a list. Instead, I suggest using a named
295subroutine that does a hash-lookup like this:
296
297 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
298 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
299
9b8f64cf
CD
300=back
301
302=head1 PPI BUGS
303
304We're waiting on the following bugs to get fixed in a CPAN release of PPI:
305
306=over 4
307
b589a229
CD
308=item literal()
309
310ValuesAndExpressions::RequireNumberSeparators uses a stringy eval to
311numify. Current PPI SVN has code for the
312PPI::Token::Number->literal() method which numifies from source. When
313we depend on a PPI version higher than 1.118, the _to_number()
314function in that policy can be removed in favor of literal().
315
c38138ab 316=item Newlines
b589a229
CD
317
318PPI does not preserve newlines. That makes
c38138ab
CD
319CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
320now, it's implemented by pulling the source out of the file and skipping PPI.
321
322It's unlikely that PPI will support mixde newlines anytime soon.
323
324=item Anonymous constructors in lists
325
326The following parses wrong in PPI v1.118. A PPI fix is in progress.
327
328 bless( {} );
329
330When this is fixed, uncomment a few tests in t/20_policies_classhierarchies.t
b589a229 331
d2d8975c
ES
332=item Hash constructors with a parenthesis directly to the left.
333
334The L<PPI::Statement> surrounding the L<PPI::Constructor> returns undef
335for C<location()> for the following:
336
337 ({})
338
339The same problem exists for
340
341 ({} )
342
343but not for
344
345 ( {})
346
347Logged as RT #23788.
348
349Remove trinary operator usage in RequireUseStrict, RequireUseWarnings, and
350RequireExplicitPackage once this is fixed.
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
daad783f 359=back
501ee198 360
85e38a07 361=cut