The Perl You Need To Know - Part 3
by Stas Bekman
|
Pages: 1, 2, 3
Modules, Libraries and Program Files
Before we proceed, let's define what we mean by module, library and program file.
- Libraries These are files that contain Perl subroutines and other code.
When these are used to break up a large program into manageable chunks, they don't generally include a package declaration; when they are used as subroutine libraries, they often do have a package declaration.
Their last statement returns true, a simple 1; statement ensures
that.
They can be named in any way desired, but generally their extension is .pl.
Examples:
config.pl
----------
# No package so defaults to main::
$dir = "/home/httpd/cgi-bin";
$cgi = "/cgi-bin";
1;
mysubs.pl
----------
# No package so defaults to main::
sub print_header{
print "Content-type: text/plain\r\n\r\n";
}
1;
web.pl
------------
package web ;
# Call like this: web::print_with_class('loud',"Don't shout!");
sub print_with_class{
my( $class, $text ) = @_ ;
print qq{<span class="$class">$text</span>};
}
1;It generally declares a package name at the beginning.
Modules are generally used either as function libraries (which .pl files are still but less commonly used for), or as object libraries where a module is used to define a class and its methods.
Its last statement returns true.
The naming convention requires it to have a .pm extension.
Example:
MyModule.pm
-----------
package My::Module;
$My::Module::VERSION = 0.01;
sub new{ return bless {}, shift;}
END { print "Quitting\n"}
1;Many Perl programs exist as a single file. Under Linux and other
Unix-like operating systems, the file often has no suffix since the
operating system can determine that it is a Perl script from the first
line (shebang line) or if it's Apache that executes the code, there is
a variety of ways to tell how and when the file should be executed.
Under Windows, a suffix is normally used, for example .pl or
.plx.
The program file will normally require() any libraries and use()
any modules it requires for execution.
It will contain Perl code but won't usually have any package names.
Its last statement may return anything or nothing.
require()
|
Previously in the Series
The Perl You Need To Know - Part 2 |
require() reads a file containing Perl code and compiles it. Before
attempting to load the file, it looks up the argument in %INC to see
whether it has already been loaded. If it has, then require() just returns
without doing a thing. Otherwise, an attempt will be made to load and
compile the file.
require() has to find the file it has to load. If the argument is a
full path to the file, then it just tries to read it. For example:
require "/home/httpd/perl/mylibs.pl";If the path is relative, then require() will attempt to search for the file
in all the directories listed in @INC. For example:
require "mylibs.pl";If there is more than one occurrence of the file with the same name in
the directories listed in @INC, then the first occurrence will be used.
The file must return TRUE as the last statement to indicate
successful execution of any initialization code. Since you never know
what changes the file will go through in the future, you cannot be
sure that the last statement will always return TRUE. That's why
the suggestion is to put ``1;'' at the end of file.
Although you should use the real filename for most files, if the file is a module, then you may use the following convention instead:
require My::Module;This is equal to:
require "My/Module.pm";If require() fails to load the file, either because it couldn't find
the file in question or the code failed to compile, or it didn't
return TRUE, then the program would die(). To prevent this, the
require() statement can be enclosed into an eval() exception-handling
block, as in this example:
require.pl
----------
#!/usr/bin/perl -w
eval { require "/file/that/does/not/exists"};
if ($@) {
print "Failed to load, because : $@"
}
print "\nHello\n";When we execute the program:
% ./require.pl
Failed to load, because : Can't locate /file/that/does/not/exists in
@INC (@INC contains: /usr/lib/perl5/5.00503/i386-linux
/usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux
/usr/lib/perl5/site_perl/5.005 .) at require.pl line 3.
HelloWe see that the program didn't die(), because Hello was printed. This trick is useful when you want to check whether a user has some module installed. If she hasn't, then it's not critical, because the program can run with reduced functionality without this module.
If we remove the eval() part and try again:
require.pl
----------
#!/usr/bin/perl -w
require "/file/that/does/not/exists";
print "\nHello\n";
% ./require1.pl
Can't locate /file/that/does/not/exists in @INC (@INC contains:
/usr/lib/perl5/5.00503/i386-linux /usr/lib/perl5/5.00503
/usr/lib/perl5/site_perl/5.005/i386-linux
/usr/lib/perl5/site_perl/5.005 .) at require1.pl line 3.The program just die()s in the last example, which is what you want in most cases.
For more information, refer to the perlfunc manpage.
use()
use(), just like require(), loads and compiles files containing Perl
code, but it works with modules only. The only way to pass a module
to load is by its module name and not its filename. If the module is
located in MyCode.pm, then the correct way to use() it is:
use MyCodeand not:
use "MyCode.pm"use() translates the passed argument into a file name replacing ::
with the operating system's path separator (normally /) and
appending .pm at the end. So My::Module becomes My/Module.pm.
use() is equivalent to:
BEGIN { require Module; Module->import(LIST); }Internally it calls require() to do the loading and compilation
chores. When require() finishes its job, import() is called unless
() is the second argument. The following pairs are equivalent:
use MyModule;
BEGIN {require MyModule; MyModule->import; }
use MyModule qw(foo bar);
BEGIN {require MyModule; MyModule->import("foo","bar"); }
use MyModule ();
BEGIN {require MyModule; }The first pair exports the default tags. This happens if the module
sets @EXPORT to a list of tags to be exported by default. The
module's mainpage normally describes which tags are exported by
default.
The second pair exports only the tags passed as arguments.
The third pair describes the case where the caller does not want any symbols to be imported.
import() is not a built-in function, it's just an ordinary static
method call into the ``MyModule'' package to tell the module to
import the list of features back into the current package. See the
Exporter manpage for more information.
When you write your own modules, always remember that it's better to
use @EXPORT_OK instead of @EXPORT, since the former doesn't
export symbols unless it was asked to. Exports pollute the namespace
of the module user. Also avoid short or common symbol names to reduce
the risk of name clashes.
When functions and variables aren't exported you can still access them
using their full names, like $My::Module::bar or
$My::Module::foo(). By convention you can use a leading underscore
on names to informally indicate that they are internal and not for
public use.
There's a corresponding ``no'' command that un-imports symbols
imported by use, i.e., it calls Module->unimport(LIST)
instead of import().
do()
While do() behaves almost identically to require(), it reloads the
file unconditionally. It doesn't check %INC to see whether the file
was already loaded.
If do() cannot read the file, then it returns undef and sets $! to
report the error. If do() can read the file but cannot compile it, then it
returns undef and puts an error message in $@. If the file is
successfully compiled, then do() returns the value of the last expression
evaluated.
References
-
An article by Mark-Jason Dominus about how Perl handles variables and
namespaces, and the difference between
use vars()andmy()- http://www.plover.com/~mjd/perl/FAQs/Namespaces.html . -
For an in-depth explanation of Perl data types, see chapters 3 and 6
in the book ``Advanced Perl Programming'' by Sriram Srinivasan.
And, of course, the ``Programming Perl'' by L.Wall, T. Christiansen and J.Orwant (also known as the ``Camel'' book, named after the camel picture on the cover of the book). Look at chapters 10, 11 and 21.
- The Exporter, perlvar, perlmod and perlmodlib man pages.
