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