11. Packages and Modules

Created Saturday 26 April 2014

NAMESPACES AND PACKAGES

Most of the modules have effectively the same core:
package Module::Name;
use strict;
use warnings;
our $VERSION = 0.01; # or some other version number
# module code here
1; # in Perl a package must return a true value, otherwise the use fails at compile time

use vs require

use VERSION # must use a minimum version of Perl: use v5.8.1; use 5.8.1; use 5.008_001; see "Version Strings" in perldoc perldata
use Module VERSION LIST
use Module VERSION
use Module LIST
use Module

Using require:
sub debug { # Data::Dumper will never be loaded unless debug() is called
my @args = @_;
require Data::Dumper;
warn Data::Dumper::Dumper(\@args); # the import() ins't called, so must call Dumper() with its FQ sub name
}

Package Variables

WRONG:
package Universe::Roman;
use My::Number::Utilities;
$My::Number::Utilities::PI = 3;
RIGHT:
package Universe::Roman;
use My::Number::Utilities;
local $My::Number::Utilities::PI = 3;
package My::Number::Utilities;
use strict;
use warnings;
our $VERSION = 0.01;
sub pi {3.14159265359}
So now the value of PI is read-only:
package Universe::Roman;
use My::Number::Utilities;
my $PI = My::Number::Utilities::pi();

Version Numbers

SUBROUTINES IN OTHER PACKAGES

Exporting

use base 'Exporter';
our @EXPORT_OK = qw(pi is_prime);
our %EXPORT_TAGS = (

all => \@EXPORT_OK,
constants => [qw(ph e phi)],
);
Now, when someone wants to use your module, they can import those functions by specifying their names in the import list:
use My::Number::Utilities 'pi', 'is_prime';
Or ask for all:
use My::Number::Utilities ':all';

our @EXPORT_OK = qw(PI E PHI);
use constant PI => 3.14159265359;
use constant E => 2.71828182846
use constant => 1.61803398874;

Naming Conventions

package Really::Private;
use strict;
use warnings;
use Carp 'croak';
our $VERSION = '0.01';
my $is_arrayref_of_hashrefs = sub {
my $arg = shift;
# is it an array ref?
return unless 'ARRAY' eq ref $arg;
# return boolean indicating if all elements are hashrefs
return @$arg == grep {'HASH' eq ref $_} @$arg;
};
sub process_records {
my ($records) = @_;
unless ($is_arrayref_of_hashrefs->($records)) {
croak "process_records() needs an array ref of hashrefs";
}
# process records here
}
1;

BEGIN, UNITCHECK, CHECK, INIT, END

package Foo;
use strict;
use warnings;
BEGIN {
print "This is the 1st BEGIN block\n";
}
BEGIN {
print "This is the 2nd BEGIN block\n";
}

BEGIN blocks

END blocks

INIT, CHECK, and UNITCHECK blocks

PLAIN OLD DOCUMENTATION (POD)

sub reciprocal {return 1 / shift}
=pod
This is a paragraph in a POD section. When run through a formatter, the paragraph text will rewrap as necessary to fit the needs of your particular output format.

=cut

sub not_reciprocal {return shift}

Documentation Structure

=head1 NAME

Convert::Distance::Imperial - Convert imperial units to other units

=head1 VERSION

VERSION 0.001

=head1 SYNOPSIS

use Convert::Distance::Imperial 'miles_to_inches';
my $miles = miles_to_inches(453285);

Headings

Paragraphs

=pod

This is a POD paragraph.

This is a second POD paragraph.

=cut

Lists

=over 4

=item * This is a list item

=item * This is a second list item.

This is an optional paragraph explaining the second list item.

=back

Verbatim

=head1 SUBROUTINES

=head2 C<miles_to_yards>

use Convert::Distance::Imperial 'miles_to_yards';
my $yards = miles_to_yards($miles);
print "$miles miles is $yards yards\n";

The C<miles_to_yards()> subroutine takes a number, in miles, and returns a number, in yards

Miscellaneous

Formatting codes

Linking

Encoding

CREATING AND INSTALLING MODULES

Creating a Simple Module

Creating an installable version of the Convert::Distance::Imperial program:
module-starter --module=Convert::Distance::Imperial \
--author='Curtis "Ovid" Poe' \
**--email=ovid@cpan.org**
That creates a directory named Convert-Distance-Imperial:
$ tree.pl Convert-Distance-Imperial/
Convert-Distance-Imperial/
|--Changes
|--MANIFEST
|--Makefile.PL
|--README
|--ignore.txt
| lib/
| | Convert/
| | | Distance/
| | | |--Imperial.pm
| t/
| |--00-load.t
| |--boilerplate.t
| |--manifest.t
| |--pod-coverage.t
| |--pod.t



Backlinks: