Chapter 31. Pragmatic Modules

A pragma is a special kind of module that affects the compilation phase of your program. Some pragmatic modules (or pragmata, for short (or pragmas, for shorter)) may also affect the execution phase of your program. Think of these as hints to the compiler. Because they need to be seen at compile time, they'll only work when invoked by a use or a no, because by the time a require or a do is run, compilation is long since over.

By convention, pragma names are written in all lowercase because lowercase module names are reserved for the Perl distribution itself. When writing your own modules, use at least one capital letter in the module name to avoid conflict with pragma names.

Unlike regular modules, most pragmas limit their effects to the rest of the innermost enclosing block from which they were invoked. In other words, they're lexically scoped, just like my variables. Ordinarily, the lexical scope of an outer block covers any inner block embedded within it, but an inner block may countermand a lexically scoped pragma from an outer block by using the no statement:

use strict;
use integer;
{
    no strict 'refs';       # allow symbolic references
    no integer;             # resume floating-point arithmetic
    # ....
}

More so than the other modules Perl ships with, the pragmas form an integral and essential part of the Perl compilation environment. It's hard to use the compiler well if you don't know how to pass hints to it, so we'll put some extra effort into describing pragmas.

Another thing to be aware of is that we often use pragmas to prototype features that later get encoded into "real" syntax. So in some programs you'll see deprecated pragmas like use attrs whose functionality is now supported directly by subroutine declaration syntax. Similarly, use vars is in the process of being replaced by our declarations. And use subs may someday be replaced by an override attribute on ordinary subroutine declarations. We're not in a terrible hurry to break the old ways of doing things, but we do think the new ways are prettier.

31.1. use attributes

sub afunc : method;
my $closure = sub : method { ... };

use attributes;           
@attrlist = attributes::get(\&afunc);

The attributes pragma has two purposes. The first is to provide an internal mechanism for declaring attribute lists, which are optional properties associated with subroutine declarations and (someday soon) variable declarations. (Since it's an internal mechanism, you don't generally use this pragma directly.) The second purpose is to provide a way to retrieve those attribute lists at run time using the attributes::get function call. In this capacity, attributes is just a standard module, not a pragma.

Only a few built-in attributes are currently handled by Perl. Package-specific attributes are allowed by an experimental extension mechanism described in the section "Package-specific Attribute Handling" of the attributes(3) manpage.

Attribute setting occurs at compile time; attempting to set an unrecognized attribute is a compilation error. (The error is trappable by eval, but it still stops the compilation within that eval block.)

Only three built-in attributes for subroutines are currently implemented: locked, method, and lvalue. See Chapter 6, "Subroutines", and Chapter 17, "Threads", for further discussion of these. There are currently no built-in attributes for variables as there are for subroutines, but we can think of several we might like, such as constant.

The attributes pragma provides two subroutines for general use. They may be imported if you ask for them.

get: This function returns a (possibly empty) list of attributes given a single input parameter that's a reference to a subroutine or variable. The function raises an exception by invoking Carp::croak if passed invalid arguments.
reftype: This function acts somewhat like the built-in ref function, but it always returns the underlying, built-in Perl data type of the referenced value, ignoring any package into which it might have been blessed.

Precise details of attribute handling remain in flux, so you'd best check out the online documentation included with your Perl release to see what state it's all in.

Chapter 31. Pragmatic Modules

Contents:

31.1. use attributes