Perl Module Anatomy

When h2xs creates a new module directory, it writes a skeleton .pm file. For example,

h2xs -X -n Foo::Bar

will create Bar.pm like this

package Foo::Bar;

use 5.008008;
use strict;
use warnings;

require Exporter;
use AutoLoader qw(AUTOLOAD);

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration       use Foo::Bar ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(

) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(

);

our $VERSION = '0.01';


# Preloaded methods go here.

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__

This page describes the initial contents of the .pm file, and explains how to use it as a starting point for a module.

package Foo::Bar;
The package statement sets the default package for global names: variables, filehandles and subroutines. Since a module typically holds code for a package, it is convenient to set the default package name.

use 5.008008;
This line causes a compile-time error if the version of the Perl interpreter is less than 5.8.8.
Perl has evolved over the years. If you know that your module relies on features or bug fixes that are only available in a certain version of the interpreter, you can use a line like this to prevent it from running on any earlier version.
Short of that, you can write use 5;, which will at least cause the program to fail gracefully if someone somehow feeds your module to a Perl 4 interpreter.

use strict;
use strict enforces a restricted programming model on your code. It is strongly recommended.
The most obvious effect of use strict is that global variables must be referred to through fully qualified package names, e.g. $Foo::Bar::baz, rather than $baz. This has the practical consequence of flagging typos in lexically declared (my) variables.

use warnings;
use warnings turns on warnings for many questionable or potentially erroneous coding practices, such as use of uninitalized variables.
Conventional wisdom holds that all Perl programs should run with warnings enabled. However, I find use warnings to be too picky, and rarely use it.

require Exporter;
Packages allow a program to be partitioned into separate namespaces. However, this leads immediately to the problem of how one package may access the facilities of another. Conceptually, there are two possibilities:

reaching down
pushing up

Reaching down
Perl does not enforce access restrictions between packages. Any line of code, in any package, can access variables and subroutines in another package simply by naming them:
$circumference = 2 * $Math::PI * $radius; $area = Math::area($length, $width);
There are at least two problems with this:

it clutters the user's code with package names
it breaks encapsulation

Pushing up
Alternately, a package can place its own variables in the namespace of the caller's package:
package Math; $main::PI = 3.1415926; sub main::area { ... }
The problem with this is that it risks the very namespace collisions that packages were designed to prevent.
The Perl5 Fix
Perl5 provides support for both reaching down and pushing up. An object-oriented interface allows code to reach down into a package namespace without violating encapsulation
Conversely, the Exporter module allows a package to push (export) its names up into the caller's namespace in a controlled fashion.

use AutoLoader qw(AUTOLOAD);
One of the design objectives of Perl5 is to allow the language to scale. Current implementations compile a program each time it is run. This is acceptable for a 1000 line program, but could become a problem as programs scale up into the 10K-100K line range.
The Autoloader module implements a scheme that compiles subroutines at run time, on demand. This can reduce both the CPU and memory requirements of a program.
Autoloader is best used by modules that define a large number of infrequently used subroutines, such as POSIX.pm. If you don't use Autoloader, delete this statement from the module source.

our @ISA = qw(Exporter);
The @ISA array controls method inheritance in Perl modules. If a method isn't found in the current package, then Perl searches for it in the packages named in the @ISA array. (recursively, depth first).
@ISA is a global. The our declaration allows us to refer to it without a fully qualified package name, even though use strict is in force.

# Items to export into callers namespace by de # names by default without a very good reason. # Do not simply export all your public functio # This allows declaration use Foo::Bar ' # If you do not need this, moving things direc # will save memory. our %EXPORT_TAGS = ( 'all' => [ qw( ) ] ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); our @EXPORT = qw( );
The usual way to include a module in your program is with a use statement:
use Foo::Bar LIST
The Perl manual documents this statement as being exactly equivalent to
BEGIN { require Foo::Bar; import Foo::Bar LIST }
The require statement causes the file Foo/Bar.pm to be located, read and compiled.
The import statement is an ordinary method call on the Foo::Bar class. Foo::Bar may implement an import method, and this method may do anything: in particular, it may take the opportunity to export names into the caller's namespace. However, this runs the risk of namespace collisions. The preferred approach is to inherit your import method from Exporter.
The Exporter module has an import method that exports names in a controlled fashion: names listed in the @EXPORT array are unconditionally exported to the caller's namespace; names listed in the @EXPORT_OK array are exported only if the caller explicitly asks for them by listing them in the use statement.
The @EXPORT array should only be used for things like pragmas, where some change to the user's environment is intrinsic to the concept of the package. Ordinary application modules should not @EXPORT anything. Instead, any names to be exported to the caller's namespace should be placed in @EXPORT_OK, so that the caller can decide whether or not to import them.
The %EXPORT_TAGS hash is a convenience feature. It allows the user to import groups of related names by putting the associated tag in LIST.
If you're not exporting anything, you can delete these three statements. Delete the explanatory comments, too.

our $VERSION = '0.01';
This assigns a version number to the module. If a user writes
use Foo::Bar 1.01
then the program will die if $VERSION is lower than the value specified in the use statement.
It's a good idea to bump the version number of a module each time you change it.

# Preloaded methods go here.
This is where you put methods, subroutines, variables, and whatever else the module needs. Preloaded means that they will be compiled in the usual fashion: at compile time.
Go ahead and delete the comment.

# Autoload methods go after =cut, and are proc
Methods that are to be compiled at run time via the Autoload module are placed after the logical end of program text. I've never had occasion to do this.
Delete this comment, too.

1;
A use statement evals the contents of a file. The last expression in the file must evaluate to true, or the eval dies.
It is conventional to end .pm and .pl files with a 1 to provide this value. Of course, if your module has initialization code that could fail at compile time, then it should return the results of the initialization.
I like to drop the semicolon after the 1. This puts people on notice that if they put any code after the 1, then they are responsible for establishing the return value.

__END__
__END__ is the logical end of program text. You can put anything you want after this token; it will be ignored by the compiler.
It is common practice to put documentation after this token, in POD format. See Program PODs for details.

Notes

ordinary: It's not completely ordinary. Normally, calling a method that doesn't exist causes a fatal error. However, you can use a module that neither has nor inherits an import method, and the interpreter will quietly ignore the problem.

Steven W. McDougall / resume / swmcd@theworld.com / 2007 March 14

package Foo::Bar;	The `package` statement sets the default package for global names: variables, filehandles and subroutines. Since a module typically holds code for a package, it is convenient to set the default package name.
use 5.008008;	This line causes a compile-time error if the version of the Perl interpreter is less than 5.8.8. Perl has evolved over the years. If you know that your module relies on features or bug fixes that are only available in a certain version of the interpreter, you can use a line like this to prevent it from running on any earlier version. Short of that, you can write `use 5;`, which will at least cause the program to fail gracefully if someone somehow feeds your module to a Perl 4 interpreter.
use strict;	`use strict` enforces a restricted programming model on your code. It is strongly recommended. The most obvious effect of `use strict` is that global variables must be referred to through fully qualified package names, e.g. `$Foo::Bar::baz`, rather than `$baz`. This has the practical consequence of flagging typos in lexically declared (`my`) variables.
use warnings;	`use warnings` turns on warnings for many questionable or potentially erroneous coding practices, such as use of uninitalized variables. Conventional wisdom holds that all Perl programs should run with warnings enabled. However, I find `use warnings` to be too picky, and rarely use it.
require Exporter;	Packages allow a program to be partitioned into separate namespaces. However, this leads immediately to the problem of how one package may access the facilities of another. Conceptually, there are two possibilities: reaching down pushing up Reaching down Perl does not enforce access restrictions between packages. Any line of code, in any package, can access variables and subroutines in another package simply by naming them: $circumference = 2 * $Math::PI * $radius; $area = Math::area($length, $width); There are at least two problems with this: it clutters the user's code with package names it breaks encapsulation Pushing up Alternately, a package can place its own variables in the namespace of the caller's package: package Math; $main::PI = 3.1415926; sub main::area { ... } The problem with this is that it risks the very namespace collisions that packages were designed to prevent. The Perl5 Fix Perl5 provides support for both reaching down and pushing up. An object-oriented interface allows code to reach down into a package namespace without violating encapsulation Conversely, the `Exporter` module allows a package to push (export) its names up into the caller's namespace in a controlled fashion.
use AutoLoader qw(AUTOLOAD);	One of the design objectives of Perl5 is to allow the language to scale. Current implementations compile a program each time it is run. This is acceptable for a 1000 line program, but could become a problem as programs scale up into the 10K-100K line range. The `Autoloader` module implements a scheme that compiles subroutines at run time, on demand. This can reduce both the CPU and memory requirements of a program. `Autoloader` is best used by modules that define a large number of infrequently used subroutines, such as `POSIX.pm`. If you don't use `Autoloader`, delete this statement from the module source.
our @ISA = qw(Exporter);	The `@ISA` array controls method inheritance in Perl modules. If a method isn't found in the current package, then Perl searches for it in the packages named in the `@ISA` array. (recursively, depth first). `@ISA` is a global. The `our` declaration allows us to refer to it without a fully qualified package name, even though `use strict` is in force.
# Items to export into callers namespace by de # names by default without a very good reason. # Do not simply export all your public functio # This allows declaration use Foo::Bar ' # If you do not need this, moving things direc # will save memory. our %EXPORT_TAGS = ( 'all' => [ qw( ) ] ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); our @EXPORT = qw( );	The usual way to include a module in your program is with a `use` statement: use Foo::Bar LIST The Perl manual documents this statement as being exactly equivalent to BEGIN { require Foo::Bar; import Foo::Bar LIST } The `require` statement causes the file `Foo/Bar.pm` to be located, read and compiled. The `import` statement is an ordinary method call on the `Foo::Bar` class. `Foo::Bar` may implement an `import` method, and this method may do anything: in particular, it may take the opportunity to export names into the caller's namespace. However, this runs the risk of namespace collisions. The preferred approach is to inherit your `import` method from `Exporter`. The `Exporter` module has an `import` method that exports names in a controlled fashion: names listed in the `@EXPORT` array are unconditionally exported to the caller's namespace; names listed in the `@EXPORT_OK` array are exported only if the caller explicitly asks for them by listing them in the `use` statement. The `@EXPORT` array should only be used for things like pragmas, where some change to the user's environment is intrinsic to the concept of the package. Ordinary application modules should not `@EXPORT` anything. Instead, any names to be exported to the caller's namespace should be placed in `@EXPORT_OK`, so that the caller can decide whether or not to import them. The `%EXPORT_TAGS` hash is a convenience feature. It allows the user to import groups of related names by putting the associated tag in `LIST`. If you're not exporting anything, you can delete these three statements. Delete the explanatory comments, too.
our $VERSION = '0.01';	This assigns a version number to the module. If a user writes use Foo::Bar 1.01 then the program will `die` if `$VERSION` is lower than the value specified in the `use` statement. It's a good idea to bump the version number of a module each time you change it.
# Preloaded methods go here.	This is where you put methods, subroutines, variables, and whatever else the module needs. Preloaded means that they will be compiled in the usual fashion: at compile time. Go ahead and delete the comment.
# Autoload methods go after =cut, and are proc	Methods that are to be compiled at run time via the `Autoload` module are placed after the logical end of program text. I've never had occasion to do this. Delete this comment, too.
1;	A `use` statement `eval`s the contents of a file. The last expression in the file must evaluate to true, or the `eval` `die`s. It is conventional to end `.pm` and `.pl` files with a `1` to provide this value. Of course, if your module has initialization code that could fail at compile time, then it should return the results of the initialization. I like to drop the semicolon after the `1`. This puts people on notice that if they put any code after the `1`, then they are responsible for establishing the return value.
__END__	`__END__` is the logical end of program text. You can put anything you want after this token; it will be ignored by the compiler. It is common practice to put documentation after this token, in POD format. See Program PODs for details.