Perl Module Anatomy

h2xs -X -n Foo::Bar

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 is implemented as a package, it is convenient to set the default package to the module name.
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 5.6.1;	This line causes a compile-time error if the version of the Perl interpreter is less than 5.6.1. It's a good idea to require the version number of the interpreter on which you're developing the module; it might not run on earlier versions. This line isn't in the skeleton that h2xs creates; you have to add it yourself.
use vars qw($VERSION @ISA @EXPORT);	When use strict is in force, global variables become verbose and ungainly: $Foo::Bar::VERSION. The vars statement predeclares package names, so that they can be used in their unqualified form: $VERSION. use vars should be used only for things that actually need to be global variables, like the @ISA array. Ordinary program variables should almost alway be lexically scoped with my.
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: $c = 2 * $Math::PI * $r; $a = Math::area($len, $wid); 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.
require AutoLoader;	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.
@ISA = qw(Exporter AutoLoader);	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). If your module isn't an Autoloader, drop Autoloader from the @ISA array.
# Items to export into callers name # names by default without a very g # Do not simply export all your pub @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 unilaterally 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. If you're not exporting anything, you can delete the @EXPORT = qw() statement. Delete the explanatory comments, too.
$VERSION = '0.01';	This assigns a version number to the package. 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, a	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.

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.