.\" -*- 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::Variables::ProhibitPackageVars 3pm"
.TH Perl::Critic::Policy::Variables::ProhibitPackageVars 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::Variables::ProhibitPackageVars \- Eliminate globals declared with "our" or "use vars".
.SH AFFILIATION
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Conway suggests avoiding package variables completely, because they
expose your internals to other packages.  Never use a package variable
when a lexical variable will suffice.  If your package needs to keep
some dynamic state, consider using an object or closures to keep the
state private.
.PP
This policy assumes that you're using \f(CW\*(C`strict vars\*(C'\fR so that naked
variable declarations are not package variables by default.  Thus, it
complains you declare a variable with \f(CW\*(C`our\*(C'\fR or \f(CW\*(C`use vars\*(C'\fR, or if you
make reference to variable with a fully-qualified package name.
.PP
.Vb 7
\&    $Some::Package::foo = 1;    # not ok
\&    our $foo            = 1;    # not ok
\&    use vars \*(Aq$foo\*(Aq;            # not ok
\&    $foo = 1;                   # not allowed by \*(Aqstrict\*(Aq
\&    local $foo = 1;             # bad taste, but technically ok.
\&    use vars \*(Aq$FOO\*(Aq;            # ok, because it\*(Aqs ALL CAPS
\&    my $foo = 1;                # ok
.Ve
.PP
In practice though, its not really practical to prohibit all package
variables.  Common variables like \f(CW$VERSION\fR and \f(CW@EXPORT\fR need to
be global, as do any variables that you want to Export.  To work
around this, the Policy overlooks any variables that are in ALL_CAPS.
This forces you to put all your exported variables in ALL_CAPS too,
which seems to be the usual practice anyway.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
There is room for exceptions.  Some modules, like the core File::Find
module, use package variables as their only interface, and others like
Data::Dumper use package variables as their most common interface.
These module can be specified from your \fI.perlcriticrc\fR file, and the
policy will ignore them.
.PP
.Vb 2
\&    [Variables::ProhibitPackageVars]
\&    packages = Data::Dumper File::Find FindBin Log::Log4perl
.Ve
.PP
This is the default setting.  Using \f(CW\*(C`packages =\*(C'\fR  will override these
defaults.
.PP
You can also add packages to the defaults like so:
.PP
.Vb 2
\&    [Variables::ProhibitPackageVars]
\&    add_packages = My::Package
.Ve
.PP
You can add package \f(CW\*(C`main\*(C'\fR to the list of packages, but that will
only OK variables explicitly in the \f(CW\*(C`main\*(C'\fR package.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Perl::Critic::Policy::Variables::ProhibitPunctuationVars
.PP
Perl::Critic::Policy::Variables::ProhibitLocalVars
.SH AUTHOR
.IX Header "AUTHOR"
Jeffrey Ryan Thalhammer <jeff@imaginative\-software.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2021 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.