- publishing free software manuals
Perl Language Reference Manual
by Larry Wall and others
Paperback (6"x9"), 724 pages
ISBN 9781906966027
RRP £29.95 ($39.95)

Sales of this book support The Perl Foundation! Get a printed copy>>>


use Module VERSION

use Module LIST

use Module


Imports some semantics into the current package from the named module, generally by aliasing certain subroutine or variable names into your package. It is exactly equivalent to

BEGIN { require Module; Module->import( LIST ); }

except that Module must be a bareword.

In the peculiar use VERSION form, VERSION may be either a positive decimal fraction such as 5.006, which will be compared to $], or a v-string of the form v5.6.1, which will be compared to $^V (aka $PERL_VERSION). An exception is raised if VERSION is greater than the version of the current Perl interpreter; Perl will not attempt to parse the rest of the file. Compare with , which can do a similar check at run time. Symmetrically, no VERSION allows you to specify that you want a version of Perl older than the specified one.

Specifying VERSION as a literal of the form v5.6.1 should generally be avoided, because it leads to misleading error messages under earlier versions of Perl (that is, prior to 5.6.0) that do not support this syntax. The equivalent numeric version should be used instead.

use v5.6.1;     # compile time version check
use 5.6.1;      # ditto
use 5.006_001;  # ditto; preferred for backwards compatibility

This is often useful if you need to check the current Perl version before useing library modules that won't work with older versions of Perl. (We try not to do this more than we have to.)

Also, if the specified Perl version is greater than or equal to 5.9.5, use VERSION will also load the feature pragma and enable all features available in the requested version. See "Perl pragma to enable new features" (feature) in the Perl Library Reference Manual (Volume 1). Similarly, if the specified Perl version is greater than or equal to 5.11.0, strictures are enabled lexically as with use strict (except that the strict.pm file is not actually loaded).

The BEGIN forces the require and import to happen at compile time. The require makes sure the module is loaded into memory if it hasn't been yet. The import is not a builtin; it's just an ordinary static method call into the Module package to tell the module to import the list of features back into the current package. The module can implement its import method any way it likes, though most modules just choose to derive their import method via inheritance from the Exporter class that is defined in the Exporter module. See "Implements default import method for modules" (Exporter) in the Perl Library Reference Manual (Volume 2). If no import method can be found then the call is skipped, even if there is an AUTOLOAD method.

If you do not want to call the package's import method (for instance, to stop your namespace from being altered), explicitly supply the empty list:

use Module ();

That is exactly equivalent to

BEGIN { require Module }

If the VERSION argument is present between Module and LIST, then the use will call the VERSION method in class Module with the given version as an argument. The default VERSION method, inherited from the UNIVERSAL class, croaks if the given version is larger than the value of the variable $Module::VERSION.

Again, there is a distinction between omitting LIST (import called with no arguments) and an explicit empty LIST () (import not called). Note that there is no comma after VERSION!

Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are:

use constant;
use diagnostics;
use integer;
use sigtrap  qw(SEGV BUS);
use strict   qw(subs vars refs);
use subs     qw(afunc blurfl);
use warnings qw(all);
use sort     qw(stable _quicksort _mergesort);

Some of these pseudo-modules import semantics into the current block scope (like strict or integer, unlike ordinary modules, which import symbols into the current package (which are effective through the end of the file).

Because use takes effect at compile time, it doesn't respect the ordinary flow control of the code being compiled. In particular, putting a use inside the false branch of a conditional doesn't prevent it from being processed. If a module or pragma only needs to be loaded conditionally, this can be done using the "use a Perl module if a condition holds" (if) in the Perl Library Reference Manual (Volume 1) pragma:

use if $] < 5.008, "utf8";
use if WANT_WARNINGS, warnings => qw(all);

There's a corresponding no command that unimports meanings imported by use, i.e., it calls unimport Module LIST instead of import. It behaves just as import does with VERSION, an omitted or empty LIST, or no unimport method being found.

no integer;
no strict 'refs';
no warnings;

See "Writing new modules and finding existing ones" (perlmodlib) in the Perl Library Reference Manual (Volume 2) for a list of standard modules and pragmas. See 3 for the -M and -m command-line options to Perl that give use functionality from the command-line.

ISBN 9781906966027Perl Language Reference ManualSee the print edition