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 Modulemust be a bareword. The importation can be made conditional by using theif module.
TheBEGIN forces therequire andimport to happen at compile time. Therequire makes sure the module is loaded into memory if it hasn't been yet. Theimport is not a builtin; it's just an ordinary static method call into theModule package to tell the module to import the list of features back into the current package. The module can implement itsimport method any way it likes, though most modules just choose to derive theirimport method via inheritance from theExporter class that is defined in theExporter module. SeeExporter. If noimport 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'simport 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 theuse will call theVERSION method in class Module with the given version as an argument:
use Module 12.34;is equivalent to:
BEGIN { require Module; Module->VERSION(12.34) }ThedefaultVERSION method, inherited from theUNIVERSAL class, croaks if the given version is larger than the value of the variable$Module::VERSION.
The VERSION argument cannot be an arbitrary expression. It only counts as a VERSION argument if it is a version number literal, starting with either a digit orv followed by a digit. Anything that doesn't look like a version literal will be parsed as the start of the LIST. Nevertheless, many attempts to use an arbitrary expression as a VERSION argument will appear to work, becauseExporter'simport method handles numeric arguments specially, performing version checks rather than treating them as things to export.
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. Some of the currently implemented pragmas are:
use constant;use diagnostics;use integer;use feature qw(say signatures bitwise);use sigtrap qw(SEGV BUS);use strict qw(subs vars refs);use subs qw(afunc blurfl);use warnings qw(all);Some of these pseudo-modules import semantics into the current block scope (likestrict orinteger, unlike ordinary modules, which import symbols into the current package (which are effective through the end of the file).
Becauseuse takes effect at compile time, it doesn't respect the ordinary flow control of the code being compiled. In particular, putting ause 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 theif pragma:
use if $] < 5.008, "utf8";use if WANT_WARNINGS, warnings => qw(all);There's a correspondingno declaration that unimports meanings imported byuse, i.e., it callsModule->unimport(LIST) instead ofimport. It behaves just asimport does with VERSION, an omitted or empty LIST, or no unimport method being found.
no integer;no strict 'refs';no warnings;Seeperlmodlib for a list of standard modules and pragmas. Seeperlrun for the-M and-m command-line options to Perl that giveuse functionality from the command-line.
Lexically enables all features available in the requested version as defined by thefeature pragma, disabling any features not in the requested version's feature bundle. Seefeature.
VERSION may be either a v-string such as v5.24.1, which will be compared to$^V (aka $PERL_VERSION), or a numeric argument of the form 5.024001, which will be compared to$]. 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 withrequire, which can do a similar check at run time.
If the specified Perl version is 5.12 or higher, strictures are enabled lexically as withuse strict.
If the specified Perl version is 5.35.0 or higher,warnings are enabled.
If the specified Perl version is 5.39.0 or higher, builtin functions are imported lexically as withuse builtin with a corresponding version bundle.
Use ofuse VERSION while another is in effect is not allowed with ause v5.39; or greater version. For lower versions,use VERSION will override most behavior of a previoususe VERSION, possibly removingwarnings andfeature effects added by it. This behavior is deprecated, and a future release of perl will disallow changing the version once one has been declared. Additionally, ause VERSION with a version less than 5.11 is not allowed after ause VERSION with a version greater than 5.11.
use VERSION does not load thefeature.pm,strict.pm,warnings.pm orbuiltin.pm files, but instead implements the equivalent functionality directly.
In the current implementation, any explicit use ofno strict overridesuse VERSION, even if it comes before it. However, this may be subject to change in a future release of Perl, so new code should not rely on this fact. It is recommended that ause VERSION declaration be the first significant statement within a file (possibly after apackage statement or any amount of whitespace or comment), so that its effects happen first, and other pragmata are applied after it.
Specifying VERSION as a numeric argument of the form 5.024001 should generally be avoided as older less readable syntax compared to v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric form was the only supported syntax, which is why you might see it in older code.
use v5.24.1; # compile time version checkuse 5.24.1; # dittouse 5.024_001; # ditto; older syntax compatible with perl 5.6This is often useful if you need to check the current Perl version beforeuseing library modules that won't work with older versions of Perl. (We try not to do this more than we have to.)
Symmetrically,no VERSION allows you to specify that you want a version of Perl older than the specified one. Historically this was added during early designs of the Raku language (formerly "Perl 6"), so that a Perl 5 program could begin
no 6;to declare that it is not a Perl 6 program. As the two languages have different implementations, file naming conventions, and other infrastructure, this feature is now little used in practice and should be avoided in newly-written code.
Care should be taken when using theno VERSION form, as it isonly meant to be used to assert that the running Perl is of a earlier version than its argument andnot to undo the feature-enabling side effects ofuse VERSION.
Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.
The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.