vcs.maemo.org Git - dh-make-perl/blob - dev/i386/libperl-critic-perl/libperl-critic-perl-1.088/lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm

   1 ##############################################################################
   2 #      $URL: http://perlcritic.tigris.org/svn/perlcritic/trunk/Perl-Critic/lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm $
   3 #     $Date: 2008-07-03 10:19:10 -0500 (Thu, 03 Jul 2008) $
   4 #   $Author: clonezone $
   5 # $Revision: 2489 $
   6 ##############################################################################
   7
   8 package Perl::Critic::Policy::Modules::RequireExplicitPackage;
   9
  10 use 5.006001;
  11 use strict;
  12 use warnings;
  13 use Readonly;
  14
  15 use Perl::Critic::Utils qw{ :severities :classification };
  16 use base 'Perl::Critic::Policy';
  17
  18 our $VERSION = '1.088';
  19
  20 #-----------------------------------------------------------------------------
  21
  22 Readonly::Scalar my $EXPL => q{Violates encapsulation};
  23 Readonly::Scalar my $DESC => q{Code not contained in explicit package};
  24
  25 #-----------------------------------------------------------------------------
  26
  27 sub supported_parameters {
  28     return (
  29         {
  30             name           => 'exempt_scripts',
  31             description    => q{Don't require programs to contain a package statement.},
  32             default_string => '1',
  33             behavior       => 'boolean',
  34         },
  35     );
  36 }
  37
  38 sub default_severity { return $SEVERITY_HIGH  }
  39 sub default_themes   { return qw( core bugs ) }
  40 sub applies_to       { return 'PPI::Document' }
  41
  42 sub default_maximum_violations_per_document { return 1; }
  43
  44 #-----------------------------------------------------------------------------
  45
  46
  47 sub violates {
  48     my ( $self, $elem, $doc ) = @_;
  49
  50     # You can configure this policy to exclude scripts
  51     return if $self->{_exempt_scripts} && is_script($doc);
  52
  53     # Find the first 'package' statement
  54     my $package_stmnt = $doc->find_first( 'PPI::Statement::Package' );
  55     my $package_line = $package_stmnt ? $package_stmnt->location()->[0] : undef;
  56
  57     # Find all statements that aren't 'package' statements
  58     my $stmnts_ref = $doc->find( 'PPI::Statement' );
  59     return if !$stmnts_ref;
  60     my @non_packages = grep { !$_->isa('PPI::Statement::Package') } @{$stmnts_ref};
  61     return if !@non_packages;
  62
  63     # If the 'package' statement is not defined, or the other
  64     # statements appear before the 'package', then it violates.
  65
  66     my @viols = ();
  67     for my $stmnt ( @non_packages ) {
  68         my $stmnt_line = $stmnt->location()->[0];
  69         if ( (! defined $package_line) || ($stmnt_line < $package_line) ) {
  70             push @viols, $self->violation( $DESC, $EXPL, $stmnt );
  71         }
  72     }
  73
  74     return @viols;
  75 }
  76
  77 1;
  78
  79 __END__
  80
  81 #-----------------------------------------------------------------------------
  82
  83 =pod
  84
  85 =head1 NAME
  86
  87 Perl::Critic::Policy::Modules::RequireExplicitPackage - Always make the C<package> explicit.
  88
  89
  90 =head1 AFFILIATION
  91
  92 This Policy is part of the core L<Perl::Critic> distribution.
  93
  94
  95 =head1 DESCRIPTION
  96
  97 In general, the first statement of any Perl module or
  98 library should be a C<package> statement.  Otherwise, all the code
  99 that comes before the C<package> statement is getting executed in the
 100 caller's package, and you have no idea who that is.  Good
 101 encapsulation and common decency require your module to keep its
 102 innards to itself.
 103
 104 There are some valid reasons for not having a C<package> statement at
 105 all.  But make sure you understand them before assuming that you
 106 should do it too.
 107
 108 The maximum number of violations per document for this policy defaults to 1.
 109
 110
 111
 112 =head1 CONFIGURATION
 113
 114 As for programs, most people understand that the default package is C<main>, so
 115 this Policy doesn't apply to files that begin with a perl shebang.  If you want
 116 to require an explicit C<package> declaration in all files, including programs,
 117 then add the following to your F<.perlcriticrc> file
 118
 119   [Modules::RequireExplicitPackage]
 120   exempt_scripts = 0
 121
 122
 123 =head1 IMPORTANT CHANGES
 124
 125 This policy was formerly called C<ProhibitUnpackagedCode> which sounded
 126 a bit odd.  If you get lots of "Cannot load policy module" errors,
 127 then you probably need to change C<ProhibitUnpackagedCode> to
 128 C<RequireExplicitPackage> in your F<.perlcriticrc> file.
 129
 130
 131 =head1 AUTHOR
 132
 133 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 134
 135
 136 =head1 COPYRIGHT
 137
 138 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 139
 140 This program is free software; you can redistribute it and/or modify
 141 it under the same terms as Perl itself.  The full text of this license
 142 can be found in the LICENSE file included with this module.
 143
 144 =cut
 145
 146 # Local Variables:
 147 #   mode: cperl
 148 #   cperl-indent-level: 4
 149 #   fill-column: 78
 150 #   indent-tabs-mode: nil
 151 #   c-indentation-style: bsd
 152 # End:
 153 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :