Daftar Isi

• require VERSION

• require EXPR
• require

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

  VERSION may be either a numeric argument such as 5.006, which will becompared to $], or a literal of the form v5.6.1, which will be comparedto $^V (aka $PERL_VERSION). An exception is raised ifVERSION 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 beavoided, because it leads to misleading error messages under earlierversions of Perl that do not support this syntax. The equivalent numericversion 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, require demands that a library file be included if ithasn't already been included. The file is included via the do-FILEmechanism, which is essentially just a variety of eval with thecaveat that lexical variables in the invoking script will be invisibleto the included code. Has semantics similar to the following subroutine:

   sub require {
   
     my ($filename) = @_;
   
     if (exists $INC{$filename}) {
   
     return 1 if $INC{$filename};
   
     die "Compilation failed in require";
   
     }
   
     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";
   
     }
   
     if ($@) {
   
     $INC{$filename} = undef;
   
     die $@;
   
     } elsif (!$result) {
   
     delete $INC{$filename};
   
     die "$filename did not return true value";
   
     } else {
   
     return $result;
   
     }
   
   }
   

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

  The file must return true as the last statement to indicatesuccessful execution of any initialization code, so it's customary toend such a file with 1; unless you're sure it'll return trueotherwise. But it's better just to put the 1;, in case you add morestatements.

  If EXPR is a bareword, the require assumes a ".pm" extension andreplaces "::" with "/" in the filename for you,to make it easy to load standard modules. This form of loading ofmodules 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 thedirectories 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 andwill 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 with abareword argument, there is a little extra functionality going on behindthe scenes. Before require looks for a ".pm" extension, it willfirst look for a similar filename with a ".pmc" extension. If this fileis found, it will be loaded in place of any file ending in a ".pm"extension.

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

  Subroutine references are the simplest case. When the inclusion systemwalks through @INC and encounters a subroutine, this subroutine getscalled with two parameters, the first a reference to itself, and thesecond the name of the file to be included (e.g., "Foo/Bar.pm"). Thesubroutine should return either nothing or else a list of up to three values in the following order:

  1

  A filehandle, from which the file will be read.

  2

  A reference to a subroutine. If there is no filehandle (previous item),then this subroutine is expected to generate one line of source code percall, writing the line into $_ and returning 1, then finally at end offile returning 0. If there is a filehandle, then the subroutine will becalled to act as a simple source filter, with the line as read in $_.Again, return 1 for each valid line, and 0 after all lines have beenreturned.

  3

  Optional state for the subroutine. The state is passed in as $_[1]. Areference to the subroutine itself is passed in as $_[0].

  If an empty list, undef, or nothing that matches the first 3 values aboveis returned, then require looks at the remaining elements of @INC.Note that this filehandle must be a real filehandle (strictly a typeglobor reference to a typeglob, whether blessed or unblessed); tied filehandles will be ignored and processing will stop there.

  If the hook is an array reference, its first element must be a subroutinereference. This subroutine is called as above, but the first parameter isthe array reference. This lets you indirectly pass arguments tothe 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 becalled as above, the first parameter being the object itself. (Note thatyou must fully qualify the sub's name, as unqualified INC is always forcedinto 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, Foo->new(...);
   

  These hooks are also permitted to set the %INC entrycorresponding to the files they have loaded. See %INC in perlvar.

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