Perl

CGI

Modules

CGI::Application

• builds upon CGI adding a structure for writing truly reusable Web-applications
• "run-mode" - single screen of an application
• "Mode Parameter" is used to store (and retrieve) the current run-mode of your application
• maps each run-mode to a specific Perl subroutine ("Run-Mode Method") that implements the behavior of a single run-mode
• an "abstract class", and is only used via inheritance

package Your::Web::Application;
use base 'CGI::Application';

• setup() method defines a map between run-modes and run-mode methods
• run-mode methods are responsible for setting up the HTTP and HTML output
• run-mode methods should never print() anything to STDOUT
• run() method is singularly responsible for actually sending all HTTP headers and HTML content to the Web browser
• your run-mode method is called by the run() method, and your code is expected to return a scalar containing all your HTML content
• header_type() and header_props() allow to change the default HTTP headers
• "Instance Script" manages a single "instance" of your "Application Module"
• widgetview.cgi - instance script

#!/usr/bin/perl -w
use WidgetView;
my $app = WidgetView->new();
$app->run();

• WidgetView.pm - application module, must be in Perl's search path (@INC)

   package WidgetView;
   use base 'CGI::Application';
   use strict;

   # Needed for our database connection
   use DBI;

   sub setup {
	my $self = shift;
	$self->start_mode('mode1');
	$self->run_modes(
		'mode1' => 'showform',
		'mode2' => 'showlist',
		'mode3' => 'showdetail'
	);

	# Connect to DBI database
	$self->param('mydbh' => DBI->connect());
   }

   sub teardown {
	my $self = shift;

	# Disconnect when we're done
	$self->param('mydbh')->disconnect();
   }

   sub showform {
	my $self = shift;

	# Get CGI query object
	my $q = $self->query();

	my $output = '';
	$output .= $q->start_html(-title => 'Widget Search Form');
	$output .= $q->start_form();
	$output .= $q->textfield(-name => 'widgetcode');
	$output .= $q->hidden(-name => 'rm', -value => 'mode2');
	$output .= $q->submit();
	$output .= $q->end_form();
	$output .= $q->end_html();

	return $output;
   }

   sub showlist {
	my $self = shift;

	# Get our database connection
	my $dbh = $self->param('mydbh');

	# Get CGI query object
	my $q = $self->query();
	my $widgetcode = $q->param("widgetcode");

	my $output = '';
	$output .= $q->start_html(-title => 'List of Matching Widgets');

	## Do a bunch of stuff to select "widgets" from a DBI-connected
	## database which match the user-supplied value of "widgetcode"
	## which has been supplied from the previous HTML form via a 
	## CGI.pm query object.
	##
	## Each row will contain a link to a "Widget Detail" which 
	## provides an anchor tag, as follows:
	##
	##   "widgetview.cgi?rm=mode3&widgetid=XXX"
	##
	##  ...Where "XXX" is a unique value referencing the ID of
	## the particular "widget" upon which the user has clicked.

	$output .= $q->end_html();

	return $output;
   }

   sub showdetail {
	my $self = shift;

	# Get our database connection
	my $dbh = $self->param('mydbh');

	# Get CGI query object
	my $q = $self->query();
	my $widgetid = $q->param("widgetid");

	my $output = '';
	$output .= $q->start_html(-title => 'Widget Detail');

	## Do a bunch of things to select all the properties of  
	## the particular "widget" upon which the user has
	## clicked.  The key id value of this widget is provided 
	## via the "widgetid" property, accessed via the CGI.pm
	## query object.

	$output .= $q->end_html();

	return $output;
   }

References

• Using CGI::Application
• CPAN
• Wiki

CGI::Builder

• CPAN

Packages

use Module();

is equivalent to

BEGIN { require "Module.pm"; }

and

require Module;

require "Cards/Poker.pm";           # runtime load
require Cards::Poker;               # ".pm" assumed; same as previous
use Cards::Poker;                   # compile-time load, implicit import of package

All programs are in package main until they use a package statement to change this.

package Alpha;
$name = "first";
package Omega;
$name = "last";
package main;
print "Alpha is $Alpha::name, Omega is $Omega::name.\n";

Output:

Alpha is first, Omega is last.

Module example

1    package Cards::Poker;
2    use Exporter;
3    @ISA = ("Exporter");
4    @EXPORT = qw(&shuffle @card_deck);
5    @card_deck = ( );                       # initialize globals
6    sub shuffle { }                        # fill-in definition later
7    1;    # last expression is the overall value of module - must be true

• Line 1

Typically, a module first switches to a particular package so that it has its own place for global variables and functions, one that won't conflict with that of another program. This package name must be written exactly as in the corresponding use statement when the module is loaded.

• Line 2 loads in the Exporter module, which manages your module's public interface
• Line 3 initializes the special, per-package array @ISA to contain the word "Exporter". When a user says use Cards::Poker, Perl implicitly calls a special method, Cards::Poker->import( ). You don't have an import method in your package, because the Exporter package does, and you're inheriting from it because of the assignment to @ISA (is a).
• Line 4 assigns the list ('&shuffle', '@card_deck') to the special, per-package array @EXPORT. When someone imports this module, variables and functions listed in that array are aliased into the caller's own package.
• Lines 5 and 6 set up the package global variables and functions to be exported.

Other kinds of library files

A library is a collection of loosely related functions designed to be used by other programs. It lacks the rigorous semantics of a Perl module. The file extension .pl indicates that it's a Perl library file.

Perl libraries—or in fact, any arbitrary file with Perl code in it—can be loaded in using do "file.pl" or with require "file.pl". The latter is preferred in most situations, because unlike do, require does implicit error checking.

Another advantage of require is that it keeps track of which files have already been loaded in the global hash %INC. It doesn't reload the file if %INC indicates that the file has already been read.

Finding modules and libraries

• @INC is an array that Perl uses to determine the directories to search for libraries and modules.
• %INC, which is a list of the actual modules Perl has loaded from the environment.

Example:

perl -e "print @INC";

and

foreach $key (sort keys(%INC)) {
   print "$key => $INC{$key}\n";
}

Modifying @INC

Easiest way:

use lib "C:\\MyModuleDirectory";
use MyModule;