=over

=item require VERSION
X<require>

=item require EXPR

=item require

Demands a version of Perl specified by VERSION, or demands some semantics
specified by EXPR or by L<C<$_>|perlvar/$_> if EXPR is not supplied.

VERSION may be either a literal such as v5.24.1, which will be
compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in L<English>),
or a numeric argument of the form 5.024001, which will be compared to
L<C<$]>|perlvar/$]>. An exception is raised if VERSION is greater than
the version of the current Perl interpreter.  Compare with
L<C<use>|/use Module VERSION LIST>, which can do a similar check at
compile time.

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.

    require v5.24.1;    # run time version check
    require 5.24.1;     # ditto
    require 5.024_001;  # ditto; older syntax compatible
                          with perl 5.6

Otherwise, L<C<require>|/require VERSION> demands that a library file be
included if it hasn't already been included.  The file is included via
the do-FILE mechanism, which is essentially just a variety of
L<C<eval>|/eval EXPR> with the
caveat that lexical variables in the invoking script will be invisible
to the included code.  If it were implemented in pure Perl, it
would have semantics similar to the following:

    use Carp 'croak';
    use version;

    sub require {
        my ($filename) = @_;
        if ( my $version = eval { version->parse($filename) } ) {
            if ( $version > $^V ) {
               my $vn = $version->normal;
               croak "Perl $vn required--this is only $^V, stopped";
            }
            return 1;
        }

        if (exists $INC{$filename}) {
            return 1 if $INC{$filename};
            croak "Compilation failed in require";
        }

        local $INC;
        # this type of loop lets a hook overwrite $INC if they wish
        for($INC = 0; $INC < @INC; $INC++) {
            my $prefix = $INC[$INC];
            if (!defined $prefix) {
                next;
            }
            if (ref $prefix) {
                #... do other stuff - see text below ....
            }
            # (see text below about possible appending of .pmc
            # suffix to $filename)
            my $realfilename = "$prefix/$filename";
            next if ! -e $realfilename || -d _ || -b _;
            $INC{$filename} = $realfilename;
            my $result = do($realfilename);
                         # but run in caller's namespace

            if (!defined $result) {
                $INC{$filename} = undef;
                croak $@ ? "$@Compilation failed in require"
                         : "Can't locate $filename: $!\n";
            }
            if (!$result) {
                delete $INC{$filename};
                croak "$filename did not return true value";
            }
            $! = 0;
            return $result;
        }
        croak "Can't locate $filename in \@INC ...";
    }

Note that the file will not be included twice under the same specified
name.

Historically the file must return true as the last statement to indicate
successful execution of any initialization code, so it's customary to
end such a file with C<1;> unless you're sure it'll return true
otherwise.  But it's better just to put the C<1;>, in case you add more
statements. As of 5.37.6 this requirement may be avoided by enabling
the 'module_true' feature, which is enabled by default in modern
version bundles. Thus code with C<use v5.37;> no longer needs to concern
itself with this issue. See L<feature> for more details. Note that this
affects the compilation unit within which the feature is used, and using
it before requiring a module will not change the behavior of existing
modules that do not themselves also use it.

If EXPR is a bareword, L<C<require>|/require VERSION> assumes a F<.pm>
extension and replaces C<::> with C</> in the filename for you,
to make it easy to load standard modules.  This form of loading of
modules does not risk altering your namespace, however it will autovivify
the stash for the required module.

In other words, if you try this:

        require Foo::Bar;     # a splendid bareword

The require function will actually look for the F<Foo/Bar.pm> file in the
directories specified in the L<C<@INC>|perlvar/@INC> array, and it will
autovivify the C<Foo::Bar::> stash at compile time.

But if you try this:

        my $class = 'Foo::Bar';
        require $class;       # $class is not a bareword
    #or
        require "Foo::Bar";   # not a bareword because of the ""

The require function will look for the F<Foo::Bar> file in the
L<C<@INC>|perlvar/@INC>  array and
will complain about not finding F<Foo::Bar> there.  In this case you can do:

        eval "require $class";

or you could do

        require "Foo/Bar.pm";

Neither of these forms will autovivify any stashes at compile time and
only have run time effects.

Now that you understand how L<C<require>|/require VERSION> looks for
files with a bareword argument, there is a little extra functionality
going on behind the scenes.  Before L<C<require>|/require VERSION> looks
for a F<.pm> extension, it will first look for a similar filename with a
F<.pmc> extension.  If this file is found, it will be loaded in place of
any file ending in a F<.pm> extension. This applies to both the explicit
C<require "Foo/Bar.pm";> form and the C<require Foo::Bar;> form.

You can also insert hooks into the import facility by putting Perl
coderefs or objects directly into the L<C<@INC>|perlvar/@INC> array.
There are two types of hooks, INC filters, and INCDIR hooks, and there
are three forms of representing a hook: subroutine references, array
references, and blessed objects.

Subroutine references are the simplest case.  When the inclusion system
walks through L<C<@INC>|perlvar/@INC> and encounters a subroutine, unless
this subroutine is blessed and supports an INCDIR hook this
subroutine will be assumed to be an INC hook will be called with two
parameters, the first a reference to itself, and the second the name of
the file to be included (e.g., F<Foo/Bar.pm>).  The subroutine should
return either nothing or else a list of up to four values in the
following order:

=over

=item 1

A reference to a scalar, containing any initial source code to prepend to
the file or generator output.

=item 2

A filehandle, from which the file will be read.

=item 3

A reference to a subroutine.  If there is no filehandle (previous item),
then this subroutine is expected to generate one line of source code per
call, writing the line into L<C<$_>|perlvar/$_> and returning 1, then
finally at end of file returning 0.  If there is a filehandle, then the
subroutine will be called to act as a simple source filter, with the
line as read in L<C<$_>|perlvar/$_>.
Again, return 1 for each valid line, and 0 after all lines have been
returned.
For historical reasons the subroutine will receive a meaningless argument
(in fact always the numeric value zero) as C<$_[0]>.

=item 4

Optional state for the subroutine.  The state is passed in as C<$_[1]>.

=back

C<AUTOLOAD> cannot be used to resolve the C<INCDIR> method, C<INC> is
checked first, and C<AUTOLOAD> would resolve that.

If an empty list, L<C<undef>|/undef EXPR>, or nothing that matches the
first 3 values above is returned, then L<C<require>|/require VERSION>
looks at the remaining elements of L<C<@INC>|perlvar/@INC>.
Note that this filehandle must be a real filehandle (strictly a typeglob
or reference to a typeglob, whether blessed or unblessed); tied filehandles
will be ignored and processing will stop there.

If the hook is an object, it should provide an C<INC> or C<INCDIR>
method that will be called as above, the first parameter being the
object itself. If it does not provide either method, and the object is
not CODE ref then an exception will be thrown, otherwise it will simply
be executed like an unblessed CODE ref would. Note that you must fully
qualify the method name when you declare an C<INC> sub (unlike the
C<INCDIR> sub), as the unqualified symbol C<INC> is always forced into
package C<main>.  Here is a typical code layout for an C<INC> hook:

    # In Foo.pm
    package Foo;
    sub new { ... }
    sub Foo::INC {
        my ($self, $filename) = @_;
        ...
    }

    # In the main program
    push @INC, Foo->new(...);

If the hook is an array reference, its first element must be a
subroutine reference or an object as described above. When the first
element is an object that supports an C<INC> or C<INCDIR> method then
the method will be called with the object as the first argument, the
filename requested as the second, and the hook array reference as the
the third. When the first element is a subroutine then it will be
called with the array as the first argument, and the filename as the
second, no third parameter will be passed in. In both forms you can
modify the contents of the array to provide state between calls, or
whatever you like.

In other words, you can write:

    push @INC, \&my_sub;
    sub my_sub {
        my ($coderef, $filename) = @_;  # $coderef is \&my_sub
        ...
    }

or:

    push @INC, [ \&my_sub, $x, $y, ... ];
    sub my_sub {
        my ($arrayref, $filename) = @_;
        # Retrieve $x, $y, ...
        my (undef, @parameters) = @$arrayref;
        ...
    }

or:

    push @INC, [ HookObj->new(), $x, $y, ... ];
    sub HookObj::INC {
        my ($self, $filename, $arrayref)= @_;
        my (undef, @parameters) = @$arrayref;
        ...
    }

These hooks are also permitted to set the L<C<%INC>|perlvar/%INC> entry
corresponding to the files they have loaded.  See L<perlvar/%INC>.
Should an C<INC> hook not do this then perl will set the C<%INC> entry
to be the hook reference itself.

A hook may also be used to rewrite the C<@INC> array. While this might
sound strange, there are situations where it can be very useful to do
this. Such hooks usually just return undef and do not mix filtering and
C<@INC> modifications. While in older versions of perl having a hook
modify C<@INC> was fraught with issues and could even result in
segfaults or assert failures, as of 5.37.7 the logic has been made much
more robust and the hook now has control over the loop iteration if it
wishes to do so.

There is a now a facility to control the iterator for the C<@INC> array
traversal that is performed during require. The C<$INC> variable will be
initialized with the index of the currently executing hook. Once the
hook returns the next slot in C<@INC> that will be checked will be the
integer successor of value in C<$INC> (or -1 if it is undef). For example
the following code

    push @INC, sub {
        splice @INC, $INC, 1; # remove this hook from @INC
        unshift @INC, sub { warn "A" };
        undef $INC; # reset the $INC iterator so we
                    # execute the newly installed sub
                    # immediately.
    };

would install a sub into C<@INC> that when executed as a hook (by for
instance a require of a file that does not exist), the hook will splice
itself out of C<@INC>, and add a new sub to the front that will warn
whenever someone does a require operation that requires an C<@INC>
search, and then immediately execute that hook.

Prior to 5.37.7, there was no way to cause perl to use the newly
installed hook immediately, or to inspect any changed items in C<@INC> to
the left of the iterator, and so the warning would only be generated on
the second call to require. In more recent perl the presence of the last
statement which undefines C<$INC> will cause perl to restart the
traversal of the C<@INC> array at the beginning and execute the newly
installed sub immediately.

Whatever value C<$INC> held, if any, will be restored at the end of the
require. Any changes made to C<$INC> during the lifetime of the hook
will be unrolled after the hook exits, and its value only has meaning
immediately after execution of the hook, thus setting C<$INC> to some
value prior to executing a C<require> will have no effect on how the
require executes at all.

As of 5.37.7 C<@INC> values of undef will be silently ignored.

The function C<require()> is difficult to wrap properly. Many modules
consult the stack to find information about their caller, and injecting
a new stack frame by wrapping C<require()> often breaks things.
Nevertheless it can be very helpful to have the ability to perform
actions before and after a C<require>, for instance for trace utilities
like C<Devel::TraceUse> or to measure time to load and the memory
consumption of the require graph. Because of the difficulties in safely
creating a C<require()> wrapper in 5.37.10 we introduced a new mechanism.

As of 5.37.10, prior to any other actions it performs, C<require> will
check if C<${^HOOK}{require__before}> contains a coderef, and if it does
it will be called with the filename form of the item being loaded. The hook
may modify C<$_[0]> to load a different filename, or it may throw a fatal
exception to cause the require to fail, which will be treated as though the
required code itself had thrown an exception.

The C<${^HOOK}{require__before}> hook may return a code reference, in
which case the code reference will be executed (in an eval with the
filname as a parameter) after the require completes. It will be executed
regardless of how the compilation completed, and even if the require
throws a fatal exception.  The function may consult C<%INC> to determine
if the require failed or not.  For instance the following code will print
some diagnostics before and after every C<require> statement.  The
example also includes logic to chain the signal, so that multiple
signals can cooperate. Well behaved C<${^HOOK}{require__before}>
handlers should always take this into account.

    {
        use Scalar::Util qw(reftype);
        my $old_hook = ${^HOOK}{require__before};
        local ${^HOOK}{require__before} = sub {
            my ($name) = @_;
            my $old_hook_ret;
            $old_hook_ret = $old_hook->($name) if $old_hook;
            warn "Requiring: $name\n";
            return sub {
                $old_hook_ret->() if ref($old_hook_ret)
                                  && reftype($old_hook_ret) eq "CODE";
                warn sprintf "Finished requiring %s: %s\n",
                        $name, $INC{$name} ? "loaded" :"failed";
            };
        };
        require Whatever;
    }

This hook executes for ALL C<require> statements, unlike C<INC> and
C<INCDIR> hooks, which are only executed for relative file names, and it
executes first before any other special behaviour inside of require.
Note that the initial hook in C<${^HOOK}{require__before}> is *not*
executed inside of an eval, and throwing an exception will stop further
processing, but the after hook it may return is executed inside of an
eval, and any exceptions it throws will be silently ignored.  This is
because it executes inside of the scope cleanup logic that is triggered
after the require completes, and an exception at this time would not
stop the module from being loaded, etc.

There is a similar hook that fires after require completes,
C<${^HOOK}{require__after}>, which will be called after each require statement
completes, either via an exception or successfully. It will be called with
the filename of the most recently executed require statement. It is executed
in an eval, and will not in any way affect execution.

For a yet-more-powerful import facility built around C<require>, see
L<C<use>|/use Module VERSION LIST> and L<perlmod>.

=back