Pragmas (Learning Perl, 3rd Edition)

B.6. Pragmas

Pragmas are special modules that come with each release of Perl and tell Perl's internal compiler something about your code. You've already used the strict pragma. The pragmas available for your release of Perl should be listed in the perlmodlib manpage.

You use pragmas much like you'd use ordinary modules, with a use directive. Some pragmas are lexically scoped, like lexical ("my") variables are, and they therefore apply to the smallest enclosing block or file. Others may apply to the entire program or to the current package. (If you don't use any packages, the pragmas apply to your entire program.) Pragmas should generally appear near the top of your source code. The documentation for each pragma should tell you how it's scoped.

B.6.1. The constant Pragma

If you've used other languages, you've probably seen the ability to declare constants in one way or another. Constants are handy for making a setting just once, near the beginning of a program, but that can be easily updated if the need arises. Perl can do this with the package-scoped constant pragma, which tells the compiler that a given identifier has a constant value, which may thus be optimized wherever it appears. For example:

use constant DEBUGGING => 0;
use constant ONE_YEAR => 365.2425 * 24 * 60 * 60;

if (DEBUGGING) {
  # This code will be optimized away unless DEBUGGING is turned on
  ...
}

B.6.2. The diagnostics Pragma

Perl's diagnostic messages often seem somewhat cryptic, at least the first time you see them. But you can always look them up in the perldiag manpage to find out what they mean, and often a little about what's likely to be the problem and how to fix it. But you can save yourself the trouble of searching that manpage if you use the diagnostics pragma, which tells Perl to track down and print out the related information for any message. Unlike most pragmas, though, this one is not intended for everyday use, as it makes your program read the entire perldiag manpage just to get started. (This is potentially a significant amount of overhead, both in terms of time and memory.) Use this pragma only when you're debugging and expecting to get error message you don't yet understand. It affects your entire program. The syntax is:

use diagnostics;

B.6.3. The lib Pragma

It's nearly always best to install modules in the standard directories, so that they're available for everyone, but only the system administrator can do that. If you install your own modules, you'll have to store them in your own directories -- so, how will Perl know where to find them? That's what the lib pragma is all about. It tells Perl that the given directory is the first place to look for modules. (That means that it's also useful for trying out a new release of a given module.) It affects all modules loaded from this point on. The syntax is:

use lib '/home/rootbeer/experimental';

Be sure to use a nonrelative pathname as the argument, since there's no telling what will be the current working directory when your program is run. This is especially important for CGI programs (that is, programs run by a web server).

B.6.4. The strict Pragma

You've been using use strict for a while already without having to understand that it's a pragma. It's lexically scoped, and it enforces some good programming rules. See its documentation to learn what restrictions are available in your release of Perl.

B.6.5. The vars Pragma

In the rare case that you truly need a global variable while use strict is in effect, you may declare it with the vars pragma.[407] This package-scoped pragma tells Perl that you are intentionally using one or more global variables:

[407]If your program will never be used with a version of Perl prior to 5.6, you should use the our keyword instead of the vars pragma.

use strict;
use vars qw/ $fred $barney /;

$fred = "This is a global variable, but that's all right.\n";

B.6.6. The warnings Pragma

Starting in Perl version 5.6, you may choose to have lexically scoped warnings with the warnings pragma.[408] That is, rather than using the -w option crudely to turn warnings on or off for the entire program at once, you may specify that you want no warnings about undefined values in just one section of code, while other warnings should be available. This also serves as a signal to the maintenance programmer that says, "I know that this code would produce warnings, but I know what I'm doing anyway." See the documentation for this pragma to learn about the categories of warnings available in your release of Perl.

[408]If your program may be used with a version of Perl prior to 5.6, you should not use the warnings pragma.