require

require VERSION

require EXPR

require

Demands a version of Perl specified by VERSION, or demands some semantics specified by EXPR or by $_ if EXPR is not supplied.

VERSION may be either a numeric argument such as 5.006, which will be compared to $], or a literal of the form v5.6.1, which will be compared to $^V (aka $PERL_VERSION). A fatal error is produced at run time if VERSION is greater than the version of the current Perl interpreter. Compare with /use, which can do a similar check at compile time.

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 which do not support this syntax. The equivalent numeric version should be used instead.

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

Otherwise, 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 eval. Has semantics similar to the following subroutine:

    sub require {
	my($filename) = @_;
	return 1 if $INC{$filename};
	my($realfilename,$result);
	ITER: {
	    foreach $prefix (@INC) {
		$realfilename = "$prefix/$filename";
		if (-f $realfilename) {
		    $INC{$filename} = $realfilename;
		    $result = do $realfilename;
		    last ITER;
		}
	    }
	    die "Can't find $filename in \@INC";
	}
	delete $INC{$filename} if $@ || !$result;
	die $@ if $@;
	die "$filename did not return true value" unless $result;
	return $result;
    }

Note that the file will not be included twice under the same specified name. 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 1; unless you're sure it'll return true otherwise. But it's better just to put the 1;, in case you add more statements.

If EXPR is a bareword, the require assumes a ".pm" extension and replaces "::" with "/" 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.

In other words, if you try this:

        require Foo::Bar;    # a splendid bareword

The require function will actually look for the "Foo/Bar.pm" file in the directories specified in the @INC array.

But if you try this:

        $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 "Foo::Bar" file in the @INC array and will complain about not finding "Foo::Bar" there. In this case you can do:

        eval "require $class";

Now that you understand how require looks for files in the case of a bareword argument, there is a little extra functionality going on behind the scenes. Before require looks for a ".pm" extension, it will first look for a filename with a ".pmc" extension. A file with this extension is assumed to be Perl bytecode generated by B::Bytecode. If this file is found, and it's modification time is newer than a coinciding ".pm" non-compiled file, it will be loaded in place of that non-compiled file ending in a ".pm" extension.

You can also insert hooks into the import facility, by putting directly Perl code into the @INC array. There are three forms of hooks: subroutine references, array references and blessed objects.

Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets called with two parameters, the first being a reference to itself, and the second the name of the file to be included (e.g. "Foo/Bar.pm"). The subroutine should return undef or a filehandle, from which the file to include will be read. If undef is returned, require will look at the remaining elements of @INC.

If the hook is an array reference, its first element must be a subroutine reference. This subroutine is called as above, but the first parameter is the array reference. This enables to pass indirectly some arguments to the subroutine.

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 @parameters = @$arrayref[1..$#$arrayref];
	...
    }

If the hook is an object, it must provide an INC method, that will be called as above, the first parameter being the object itself. (Note that you must fully qualify the sub's name, as it is always forced into package main.) Here is a typical code layout:

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

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

Note that these hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See perlvar/%INC.

For a yet-more-powerful import facility, see /use and perlmod.