Login
Bugfix for Bleadperl, as reported by Steffan Mueller via cpantesters
[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
20=head1 NEW FEATURES
21
22=over 4
23
8b5892fc 24=item * Report Safari sections in addition to book page numbers.
9bc546d7 25
c6e7b236 26=item * Report some statistics on the violations and the source code.
d1d6429f 27
c6e7b236
JRT
28e.g. Number of violations of each policy/severity. Total lines of code,
29number of subroutines, average number of statements/operators per sub.
d1d6429f
AL
30
31=back
32
daad783f
AL
33=head1 BUGS/LIMITATIONS
34
35=over 4
36
0ab066f7
JRT
37=item * Invalid policy names in .perlcriticrc do not cause any warnings.
38
39=item * Invalid parameters in .perlcriticrc do not cause any warnings.
daad783f
AL
40
41=item * Modules::RequireVersionVar
42
43Doesn't enforce three-part versions
44
45=item * NamingConventions::ProhibitAmbiguousNames
46
47Don't allow compound names with forbidden words, like "last_record".
48Allow forbidden words in RHS of variable declarations
49
50=item * Subroutines::ProtectPrivateSubs
51
52Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
53difference between that and C<< $self->_foo() >>
54
d1d6429f
AL
55=item * ErrorHandling::RequireCarping
56
ef919624 57This should not complain about using warn or die if it's not in a
df88f751 58function, or if it's not in a non-main:: package.
d1d6429f 59
5c77583a
AL
60Also, if the error string ends with a "\n", then the line number
61and package information is not shown, so it doesn't matter if you
62use carp/confess or not. For example:
63
64 my $fh;
65 if ( !open( $fh, '<', $filename ) ) {
66 warn "ack: $filename: $!\n";
67 return;
68 }
69
70I just want to print a warning and move on. The location is irrelevant.
71
365e3d9d
AL
72=back
73
daad783f
AL
74=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
75
365e3d9d
AL
76=over 4
77
0ab066f7
JRT
78=item * ControlStructures::ProhibitComplexMappings (p113)
79
80Base this on RequireSimpleSortBlock. Make number of statements configurable
81
daad783f
AL
82=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements (p68)
83
84=item * ValuesAndExpressions::RequireListParens (p71)
85
86=item * ValuesAndExpressions::ProhibitScalarGrep (p71)
87
df88f751 88Look for C<grep> in a scalar context and recommend C<any()> instead.
71cb5eb8 89Perhaps we need to distinguish cases like:
7e9a4c52
AL
90
91 $count += grep {qr/foo/} @list;
daad783f 92
df88f751
AL
93OTOH, this assumes that the common use of scalar grep is to check
94for existence. I'm not sure that's the case.
95
daad783f
AL
96=item * Variables::RequireLocalizedPunctuationVars (p81)
97
daad783f
AL
98=item * Variables::ProhibitTopicChangeInListFunction (p114)
99
100=item * Documentation::PodSpelling (p148)
101
102Base it on Pod::Spell or Test::Spelling. Add a "=for stopwords"
103section for words to skip, as per Pod::Spell.
104
daad783f
AL
105=item * Subroutines::RequireArgUnpacking (p178)
106
107Ensure that the first child of a sub is PPI::Statement::Variable
71cb5eb8 108(unless the sub has N or fewer statements, where N defaults to 1.
daad783f
AL
109
110=item * Subroutines::ProhibitManyArgs (p182)
111
71cb5eb8
CD
112If first L<PPI::Statement::Variable> is a list C<my>, and @_ is used,
113make sure it's fewer than N elements. Otherwise make sure there are
114less than N L<PPI::Statement::Variable>s in a row at begin which
115shift.
daad783f
AL
116
117=item * InputOutput::RequireErrorChecking (p208)
118
71cb5eb8 119Forbid open, print, close in void context, unless "use Fatal" is in
df88f751 120effect. Allow an exception for close and print.
daad783f
AL
121
122=item * InputOutput::RequireBriefOpen (p209)
123
124Make sure there's a close within N statements of an open, both with
125same lexical FH
126
127=item * InputOutput::ProhibitJoinedReadline (p213)
128
129=item * InputOutput::ProhibitExplicitStdin (p216)
130
df88f751
AL
131If you're reading from STDIN, chances are you're really wanting to
132read from the magic filehandle.
133
daad783f
AL
134=item * Miscellanea::ProhibitObnoxiousComments
135
136Forbid excessive hash marks e.g. "#### This is a loud comment ####".
137Make the obnoxious pattern configurable
138
139=item * RegularExpressions::RequireBracesForMultiline (p242)
140
141=item * RegularExpressions::ProhibitUnusualDelimiters (p246)
142
143=item * RegularExpressions::ProhibitEscapedMetacharacters (p247)
144
145=item * RegularExpressions::ProhibitEnumeratedClasses (p248)
146
df88f751 147This will be avoided for ASCII-only code.
daad783f
AL
148
149=item * RegularExpressions::ProhibitUnusedCapture (p252)
150
151Look for LHS of regexp or use of C<$1>, C<$2>, ... before next
df88f751 152regexp.
daad783f 153
daad783f
AL
154=item * RegularExpressions::ProhibitComplexRegexps (p261)
155
156If regexp is longer than N characters/lines, require it be split
157into C<qr//> pieces.
158
159=item * RegularExpressions::ProhibitSingleCharAlternation (p265)
160
161Not sure if this is easy or hard. Need to look at what PPI emits
1fd10f9b 162for regexps. Make an exception for qr/ [ ] /x.
daad783f
AL
163
164=item * RegularExpressions::ProhibitFixedStringMatches (p271)
165
166Can't be C<qr/\s*\\A\s*\((?:\?:)?(?:\s*\w+\s*\|)*\s*\w+\s*\)\s*\\z/>
167or C<qr/\s*\\A\s*\w+\s*\\z/>
168
169=item * TestingAndDebugging::ProhibitProlongedStrictureOverride (p443)
170
71cb5eb8
CD
171This conflicts with TestingAndDebugging::ProhibitNoStrict
172
daad783f
AL
173=back
174
175=head1 NON-PBP POLICIES WANTED
176
177=over 4
178
df88f751
AL
179=item * TBD::VariableNotUsed
180
181Detect a variable that has a value assigned to it, but never used.
182
183=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
184
185Anything that is a program should have a shebang line. This includes .t files.
186
daad783f
AL
187=item * BuiltInFunctions::RequireConstantSprintfFormat
188
189=item * BuiltInFunctions::RequireConstantUnpackFormat
190
191L<http://home.earthlink.net/~josh.jore/new-warnings/slides/slide1.html>
192
193=item * ControlStructures::ProhibitIncludeViaDo
194
195Forbid C<do "foo.pl">. Not sure about this policy name.
196
b589a229 197=item * CodeLayout::ProhibitNonASCII
daad783f
AL
198
199Definitely low severity! Only looks at code, not comments or POD
200
b589a229 201=item * CodeLayout::RequireUTF8
79b72614
CD
202
203All characters must be valid UTF-8. Note that typical ASCII Perl code
204is a valid UTF8 subset.
205
daad783f
AL
206=item * Miscellanea::RequireMinimumPerlVersion
207
208Every module should have something like C<use 5.6.0>
209
210=item * Miscellanea::Prohibit5006isms
211
f707b14a 212Keep the code 5.005 compatible. Low severity
daad783f
AL
213
214=item * Variables::ProhibitUseVars
215
f707b14a
CD
216Disallow C<use vars qw(...)> and require C<our $foo> instead. This
217contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
218before applying this policy. Low severity.
daad783f
AL
219
220=item * VariablesAndExpressions::ProhibitQuotedHashKeys
221
222Forbid quotes around hash keys, unless they are really needed. This
223is against what Damian says. Suggested by Adam Kennedy. Low
224severity.
225
226=item * Miscellanea::B::Lint
227
228Create a compatibility layer for the L<B::Lint> code analyzer. Make
229it very clear that this runs code and thus is a security hole.
230
b589a229 231=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
232
233Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
234
235=item * VariablesAndExpressions::RequireConstantVersion (low severity)
236
f707b14a
CD
237=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
238
daad783f
AL
239L<http://rt.cpan.org/Ticket/Display.html?id=20439>
240
c6e7b236
JRT
241=item * Variables::ProhibitPerl4PackageNames
242
b589a229 243Forbid old-school package names like Foo'Bar'Baz. This should also
c6e7b236
JRT
244apply to any variables or subroutines that get declared/called.
245
b589a229 246=item * CodeLayout::RequireEditorSettings
79b72614
CD
247
248Files must have something like the following in them for Emacs and Vi:
249
250 # Local Variables:
251 # mode: cperl
252 # cperl-indent-level: 4
c38138ab 253 # fill-column: 78
79b72614
CD
254 # End:
255 # vim: expandtab shiftwidth=4:
256
b589a229
CD
257=over 4
258
3f5f950c 259=item Emacs file variables [IMPLEMENTED!]
b589a229
CD
260
261=item Vim modelines
262
263In vim, this is called "modelines" and should match the following
264pattern:
265
266 [text]{white}{vi:|vim:|ex:}[white]se[t] {options}:[text]
3f5f950c
CD
267 [text]{white}{vi:|vim:|ex:}[white]{options}
268
269Watch out for escaped colons!
b589a229
CD
270
271The vim modeline must be within N lines of the top or bottom of the
272file. That N is user-settable, but defaults to 5. To learn more type
273":help modelines" in vim.
274
275=item Kate modelines
276
277I also discovered that Kate supports per-file modelines:
278
279L<http://kate-editor.org/article/katepart_modelines>
280
281=back
282
79b72614
CD
283=item * Documentation::RequireSynopsis
284
285=item * Documentation::RequireLicense
286
287These are simplified versions of Documentation::RequirePodSections.
288
79b72614
CD
289=item * Miscellaneous::ProhibitBoilerplate
290
b589a229 291Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 292etc.
c6e7b236 293
ef919624
CD
294Here's a non-PPI implementation:
295L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
296
c38138ab
CD
297=item * ValuesAndExpressions::ProhibitHereDocs
298
299=item * ValuesAndExpressions::ProhibitLongStrings
300
301Low severity.
302
303Both of these attempt to address problems with code layout and appearance.
304Large blocks of inline text can disrupt the readability of code. Instead, the
305text should be external, in __DATA__, or simply declared in separate functions
306at the end of the module.
307
308Exceptions: if the only code in a sub is a return of a long string, allow it.
309If there is a C<use Inline::> at the top of the module, allow HereDocs.
310
311L<http://rt.cpan.org/Ticket/Display.html?id=20714>
312
313=item * CodeLayout::ProhibitTrailingSpaces
314
315Forbid [ \t] before \n. This is a subset of RequireTidyCode.
316
317L<http://rt.cpan.org/Ticket/Display.html?id=20714>
318
daad783f
AL
319=back
320
321=head1 REFACTORINGS and ENHANCEMENTS
322
323=over 4
324
daad783f
AL
325=item * Alias -verbose to -format option in Test::P::C.
326
327Give it same functionality as the -verbose option in `perlcritic`
328
501ee198
JRT
329=item * Enhance P::C::critique() to accept file names, directories, or code strings (as refs)
330
9b8f64cf 331Just like F<bin/perlcritic> does now.
daad783f 332
9b8f64cf
CD
333=item * Add C<-cache> flag to F<bin/perlcritic>
334
335If enabled, this turns on L<PPI::Cache>:
336
337 require PPI::Cache;
338 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
339 mkdir $cache_path, oct 700 if (! -d $cache_path);
340 PPI::Cache->import(path => $cache_path);
341
342(see F<t/40_criticize.t> for a more robust implementation)
343
79b72614
CD
344=item * File::RequirePortableName
345
346No spaces, punctuation, etc.
347
9b8f64cf
CD
348=back
349
350=head1 PPI BUGS
351
352We're waiting on the following bugs to get fixed in a CPAN release of PPI:
353
354=over 4
355
b589a229
CD
356=item literal()
357
358ValuesAndExpressions::RequireNumberSeparators uses a stringy eval to
359numify. Current PPI SVN has code for the
360PPI::Token::Number->literal() method which numifies from source. When
361we depend on a PPI version higher than 1.118, the _to_number()
362function in that policy can be removed in favor of literal().
363
c38138ab 364=item Newlines
b589a229
CD
365
366PPI does not preserve newlines. That makes
c38138ab
CD
367CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
368now, it's implemented by pulling the source out of the file and skipping PPI.
369
370It's unlikely that PPI will support mixde newlines anytime soon.
371
372=item Anonymous constructors in lists
373
374The following parses wrong in PPI v1.118. A PPI fix is in progress.
375
376 bless( {} );
377
378When this is fixed, uncomment a few tests in t/20_policies_classhierarchies.t
b589a229 379
ef919624
CD
380=item Operators
381
382ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
383for PPI bugs with parsing operators. Many of these bugs have been
384fixed in PPI, so it would be good to check if those workarounds are
385still needed.
386
daad783f 387=back
501ee198 388
85e38a07 389=cut