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