Perl Program Anatomy

This is a skeleton for a typical Perl program.

#!/usr/bin/perl

use 5.8.8;
use strict;
use Getopt::Std;
use Pod::Usage;

my %Opts;
getopt('', \%Opts);

$Opts{H} and pod2usage(VERBOSE=>1);
$Opts{M} and pod2usage(VERBOSE=>2);

my($Param1, $Param2) = @ARGV;
$Param2 or 
    pod2usage(VERBOSE=>0);

Foo();
Bar();

for ($Param1)
{
    /flip/ and Flop();
    /flop/ and Flip();
}

Baz();

sub ParseArgs
{
}

sub Foo
{
}

sub Bar
{
}

sub Baz
{
}

__END__

#!/usr/bin/perl	This is the sharp-bang, or shebang. It tells your shell where to find the perl interpreter. N.B. The shebang doesn't usually work under Windows. The shebang may be followed by command-line switches, such as `-w`; these will be passed to the perl interpreter.
use 5.8.8;	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 program 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. If not, you can omit the line.
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 Getopt::Std;	`Getopt::Std` is a module that processes command-line switches. Using `Getopt::Std` will save you typing and debugging, and will lend a consistent interface to your programs. There are other `Getopt::` modules that support different styles of command-line switches. See Parsing the Command Line with `Getopt::*` for a survey.
use Pod::Usage;	`Pod::Usage` is a module that reads a POD from the program source and prints it in various formats. `Pod::Usage` allows programs to be self-documenting.
my %Opts; getopt('', \%Opts);	Many programs take command line switches. I like to store these in a hash at file scope. `getopt()` is a routine in `Getopt::Std` that parses command-line switches. For each switch that it finds, it sets a key in a hash. For example, if the user specifies `-H` on the command line, then `getopt('', \%Opts)` will set `$Opts{H}`.
$Opts{H} and pod2usage(VERBOSE=>1); $Opts{M} and pod2usage(VERBOSE=>2);	`pod2usage` is a routine in `Pod::Usage`. It locates the program source, parses the POD from it, prints it to the screen, and exits. With `VERBOSE=>0`, it just prints the synopsis. `VERBOSE=>1` adds the options, and `VERBOSE=>2` prints the entire man page.
my($Param1, $Param2) = @ARGV; $Param2 or pod2usage(VERBOSE=>0);	Many programs take command line parameters. I like to store these in `my` variables at file scope. In an actual program, I give the parameters mnemonic names. This line picks up the positional parameters from the command line. I design my interfaces so that there is always at least one positional parameter. If the user doesn't provide the required number, the program prints a usage line and exits.
Foo(); Bar(); for ($Param1) { /flip/ and Flop(); /flop/ and Flip(); } Baz();	This is where the program runs. The code here should give a view of the program from 50,000 feet. If this section runs more than 20 or 30 lines, consider breaking it up into smaller subroutines. On the other hand, if this section is nothing more than a call to a single subroutine, named (what else?) `Main()`, then get rid of `Main()` and hoist its contents up to here.
sub Foo { } sub Bar { } sub Baz { }	This is where subroutines go.
__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.

Steven W. McDougall / resume / swmcd@theworld.com / 2009 Aug 21