# best viewed via "perldoc TODO.pod"

=pod

=for stopwords LHS RHS REFACTORINGS FH SVN stopwords

=head1 NAME

TODO - Things for Perl::Critic::More developers to do

=head1 SOURCE

    #######################################################################
    #      $URL: http://perlcritic.tigris.org/svn/perlcritic/trunk/Perl-Critic-More/TODO.pod $
    #     $Date: 2008-05-04 14:51:19 -0500 (Sun, 04 May 2008) $
    #   $Author: clonezone $
    # $Revision: 2308 $
    #######################################################################

=head1 FIXES AND FEATURES NEEDED

=over 4

=item Emacs file variables

This should eventually take a perlcriticrc option to specify the exact
set of variables.

=back

=head1 POLICIES WANTED

=over 4

=item * CodeLayout::RequireUTF8

All characters must be valid UTF-8.  Note that typical ASCII Perl code
is a valid UTF-8 subset.

=item * Miscellanea::B::Lint

Create a compatibility layer for the L<B::Lint> code analyzer.  Make
it very clear that this runs code and thus is a security hole.

=item * Editor::RequireViModelines

Files must have something like the following in them for Emacs and Vi:

  # vim: expandtab shiftwidth=4:

In vim, this is called "modelines" and should match the following
pattern (taken from Vim docs):

  [text]{white}{vi:|vim:|ex:}[white]se[t] {options}:[text]
  [text]{white}{vi:|vim:|ex:}[white]{options}

Roughly translated to regexp:

  ($options) = m/^ (?:\N*\S)? [ \t]+ (?:vi|vim|ex): [ \t]+ set? [ \t]+ (\N+): \N* $/xms;
  ($options) = m/^ (?:\N*\S)? [ \t]+ (?:vi|vim|ex): [ \t]+ (\N+) $/xms;

Watch out for escaped colons!!

The vim modeline must be within N lines of the top or bottom of the
file.  That N is user-settable, but defaults to 5.  To learn more type
":help modelines" in vim.

=over 4

=item jEdit buffer-local properties

Colon-delimited, equals-sign-separated name-value pairs within the
first or last 10 lines of a file.  For example, this:

  :indentSize=4:noTabs=true:maxLineLen=78:mode=perl:

will result in settings similar to the current values being specified
for Emacs and vi.

L<http://jedit.org/users-guide/buffer-local.html>

=item Kate modelines

I also discovered that Kate supports per-file modelines:

L<http://kate-editor.org/article/katepart_modelines>

=item Others

Eclipse

=back

=item * Documentation::RequireSynopsis

=item * Documentation::RequireLicense

These are simplified versions of Documentation::RequirePodSections.

=item * Miscellaneous::ProhibitBoilerplate

Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
etc.

Here's a non-PPI implementation, derived from Module::Starter itself:
L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>

=item * ValuesAndExpressions::RestrictHereDocs

=item * ValuesAndExpressions::RestrictLongStrings

Low severity.

Both of these attempt to address problems with code layout and appearance.
Large blocks of inline text can disrupt the readability of code.  Instead, the
text should be external, in __DATA__, or simply declared in separate functions
at the end of the module.

Exceptions: if the only code in a sub is a return of a long string, allow it.
If there is a C<use Inline::> at the top of the module, allow HereDocs.

L<http://rt.cpan.org/Ticket/Display.html?id=20714>

=item * File::RequirePortableName

No spaces, punctuation, etc.  See L<Test::Portability::Files>.

=item * Modules::ProhibitSuperfluousIncludes

Warn about modules that are loaded, but don't seem to be used.  You
would have to compare sub calls, imports, and package symbols used in
the current file with those declared in the included files.  This is
likely to generate false positives.  Would have to provide a way to
configure exempt modules and symbols.

=item * Modules::RequireIncInBeginBlock

L<http://rt.cpan.org/Ticket/Display.html?id=28803>

The implementation would probably be:

 * look for @INC
   - else return
 * check if it's the lhs of an assignment
   - else return
 * recurse up to see if it's inside a PPI::Statement::Scheduled
   - if we hit the top of the tree, emit violation
 * check that statement is a BEGIN
   - else return
 * emit violation.

=back

=head1 PPI BUGS

We're waiting on the following bugs to get fixed in a CPAN release of PPI:

=over 4

=back

=cut

# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab shiftround :
