.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::Modules::RequireExplicitPackage 3pm"
.TH Perl::Critic::Policy::Modules::RequireExplicitPackage 3pm 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Perl::Critic::Policy::Modules::RequireExplicitPackage \- Always make the "package" explicit.
.SH AFFILIATION
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
In general, the first statement of any Perl module or library should
be a \f(CW\*(C`package\*(C'\fR statement.  Otherwise, all the code that comes before
the \f(CW\*(C`package\*(C'\fR statement is getting executed in the caller's package,
and you have no idea who that is.  Good encapsulation and common
decency require your module to keep its innards to itself.
.PP
There are some valid reasons for not having a \f(CW\*(C`package\*(C'\fR statement at
all.  But make sure you understand them before assuming that you
should do it too.
.PP
The maximum number of violations per document for this policy defaults
to 1.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
As for programs, most people understand that the default package is
\&\f(CW\*(C`main\*(C'\fR, so this Policy doesn't apply to files that begin with a perl
shebang.  If you want to require an explicit \f(CW\*(C`package\*(C'\fR declaration in
all files, including programs, then add the following to your
\&\fI.perlcriticrc\fR file
.PP
.Vb 2
\&    [Modules::RequireExplicitPackage]
\&    exempt_scripts = 0
.Ve
.PP
Some users may find it desirable to exempt the load of specific modules
from this policy. For example, Perl does not support Unicode module
names because of portability problems. Users who are not concerned about
this and intend to use \f(CW\*(C`UTF\-8\*(C'\fR module names will need to specify
\&\f(CW\*(C`use utf8;\*(C'\fR before the package declaration. To do this, add the
following to your \fI.perlcriticrc\fR file
.PP
.Vb 2
\&    [Modules::RequireExplicitPackage]
\&    allow_import_of = utf8
.Ve
.PP
The \f(CW\*(C`allow_import_of\*(C'\fR configuration option takes multiple module names,
separated by spaces.
.SH "IMPORTANT CHANGES"
.IX Header "IMPORTANT CHANGES"
This policy was formerly called \f(CW\*(C`ProhibitUnpackagedCode\*(C'\fR which
sounded a bit odd.  If you get lots of "Cannot load policy module"
errors, then you probably need to change \f(CW\*(C`ProhibitUnpackagedCode\*(C'\fR to
\&\f(CW\*(C`RequireExplicitPackage\*(C'\fR in your \fI.perlcriticrc\fR file.
.SH AUTHOR
.IX Header "AUTHOR"
Jeffrey Ryan Thalhammer <jeff@imaginative\-software.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2011 Imaginative Software Systems.  All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  The full text of this license
can be found in the LICENSE file included with this module.