View source for TPM Talk: An Introduction Perl Modules

{{talk_header}}

'''''An Introduction to Perl Modules'''''

'''Writing, Documenting and Testing Object-Oriented Perl Modules'''

Author:

''Madison Kelly, mkelly@alteeve.ca''

Date:

''October 29, 2009''

''Note'': This paper can be downloaded as a [[PDF]] or [[ODT]] and the sample files can be downloaded as a tarball in the [[TPM_Talk:_An_Introduction_Perl_Modules#References|references]] section at the bottom of this page.

= Welcome! =

This talk is essentially a condensed, hopefully more approachable version of '<span class="code">perlmod</span>', '<span class="code">perlobj</span>' and '<span class="code">perltoot</span>'. 

For years, Perl Modules seemed like a mysterious, inaccessible realm best left to perl gurus. This kept me from even considering writing them. It wasn't until I was had to read through the source of a set of modules that I realize how, well, accessible they are.

I want to present this talk to help other perl developers see how powerful perl modules are, and how easy it is to write them.

For reference, the modules I will introduce here are Object Oriented. Modules do not need to be so, however.

= So Then, What is a Perl Module, Anyway? =

A perl module is, at it's most basic, a collection of methods stored in a file that can be loaded by a program to provide a certain set of functions. It is very similar to how we would load a library of functions. There is a little magic in perl modules, but nothing crazy.

== That's Nice, So Why not just use a library? ==

Perl modules are designed to be very portable blocks of code. In truth, a well written library is not really different from a module, but modules are generally designed to stand alone from the programs that use them.

== So What is the Difference? ==

Three main things:

* Modules have their scope defined via the '<span class="code">package NAME</span>' command. Any variables and subroutines following the '<span class="code">package</span>' operator are considered to be in the package's name space. The scope refers to code in the same block, same file or same eval, same as how the '<span class="code">my</span>' operator defines a variable's scope.
* Modules generally have a "constructor method", usually a special subroutine called '<span class="code">new</span>'. This sets up the module for use by a program and returns a handle to the module, through which its methods are accessed. 
* Module constructor methods receive, as their first argument, the name of the package. This is also the package's "name space". Secondly, they usually '<span class="code">bless</span>' a variable, which simply marks that reference as being inside the name space of the package.

If this seems overwhelming just now, please don't worry. It will make more sense once the examples start flowing.

= Let's Get Started =

Let's start with a simple module that does simple math. 

== Name Space ==

First up, I need a name for my modules. I don't want to risk stepping on any existing module names, so I  hopped over to '<span class="code">[http://cpan.org CPAN]</span>' and did a search for names that interest me. In my case, I like the acronym '<span class="code">AN</span>' for my personal projects, so I would like to name my first module '<span class="code">AN::Tut::Sample1</span>'. I don't see anything using the '<span class="code">AN::</span>' root, so I will use it.

There are no special rules for naming your modules. Use whatever appeals to you and fits your project. However, if you want your module to eventually be hosted on CPAN, you may need to think twice about your module name. Specifically, the "top level". CPAN is reluctant to give out new top-level name space and would rather you use an existing top-level name space like '<span class="code">App::*</span>', '<span class="code">Net::*</span>' or similar. My choice of '<span class="code">AN::*</span>' is, admittedly, a little risky and could well bite me one day.

This is a good time to mention the double-colon you see in module names. This is nothing more than a directory deliminator. It's meant to be more portable between differing operating systems. So, to use my '<span class="code">AN::Tut::Sample1</span>' module name as an example, this would translate to:

<span class="code">AN/Tut/Sample1.pm</span>

On *nix systems or:

<span class="code">AN\Tut\Sample1.pm</span>

On Microsoft systems.

When you use your module, you do not need to specify the '<span class="code">.pm</span>' at the end of the actual module name. This is because perl knows to look for module files with this extension in its '<span class="code">@INC</span>' variable.

== Directory and Files ==

Before we begin, we need to decide where to store our files. Perl maintains an internal variable called '<span class="code">@INC</span>' which contains an array of directories. When you use the '<span class="code">use ...</span>' command to load a module, perl steps through this array looking for the module or library you are asking for. We will use:

<span class="code">/usr/share/perl5/</span>

Any new directories will be under this one. So our first example will be in the directory:

<span class="code">/usr/share/perl5/AN/Tut/Sample1.pm</span>

If you want to store your module in a directory not in '<span class="code">@INC</span>', you can do so. Simply have your calling script push the directory containing your module into the '<span class="code">@INC</span>' array in a '<span class="code">BEGIN {}</span>' block so that it can be found before the interpreter goes looking for it.

== Some Lingo ==

There are a few terms that are worth covering now.

* '''Reference''':
** A reference is simply a pointer, stored in a string variable, to another string variable, an array, a hash or a code block. See '<span class="code">perldoc perlref</span>'.
* '''Function''':
** A function is another name for a sub routine, generally used for perl's various built-in functions. I often use the term function for my own subroutines out of (bad?) habit. See '<span class="code">perldoc perlref</span>'.
* '''Library''':
** This is simply a standard file with a collection of sub routines. Generally their extension is '<span class="code">.lib</span>' and must end with '<span class="code">1;</span>'.
* '''Module''':
** A module is a special type of library. Exactly how it is special will be explained below. See '<span class="code">perldoc perlmod</span>'.
* '''Package''':
** A package is, essentially, a block of code with a specified name space. The scope of a package's name space is the same as the scope used by '<span class="code">my ...</span>'. See '<span class="code">perldoc -f package</span>'.
* '''Method''':
** A method is simply a sub routine in a module. The only difference is that a method expects an object reference or a package name as it's first argument. Which it gets depends on how it was called. See the first part of '<span class="code">perldoc perlobj</span>'.
* '''Class''':
** A class is simply a package with a set of methods in it's scope.
* '''Object''':
** An object is simply a reference with the class it belongs to prefixed onto the front of the reference. See '<span class="code">perldoc perlobj</span>'.
* '''bless''':
** This is actually a function whose sole purpose is to associate a reference with the package it is in. What it actually does is take the package name and prefixes it to the reference. See '<span class="code">perldoc -f bless</span>'.

If this seems a little vague just now, don't worry. Each item will be shown below, one step at a time.

= Our First Module; AN::Tut::Sample1 =

Let's start off with a very simple module that provides two methods: 

* A constructor method.
* A method that takes two numbers, adds them and returns the result.

== Our First Script; sample1.pl ==

We need a simple script to load and call our method. Let me show you a completed script and the completed module, then we will step through them to show how they work.

It would probably help to copy these into two files on your own system so that you can play along.

This is the normal perl script that we will use to call our module.

<source lang="bash">/usr/share/perl5/AN/Tut/sample1.pl</source>
<source lang="perl">
#!/usr/bin/perl

# This just sets perl to be strict about how it runs.
use strict;
use warnings;

# Load my module.
use AN::Tut::Sample1;

# Call my constructor method and show the user what is happening.
print "Here is what happens when I call the 'new' constructor method.\n";
my $an=AN::Tut::Sample1->new();
print "Now, this is what my 'an' object looks like: [$an]\n";

# Call the method 'add' using my 'an' object.
my $added_1=$an->add(2, 2);
print "2 + 2 = [$added_1]\n";

# Call the method 'add' directly via the module.
my $added_2=AN::Tut::Sample1->add(2, 2);
print "2 + 2 = [$added_2]\n";

exit 0;
</source>

== Our First Module; Sample1.pm ==

This is the actual module. It contains only two methods; the '<span class="code">new</span>' constructor method and the '<span class="code">add</span>' method.

<source lang="bash">/usr/share/perl5/AN/Tut/Sample1.pm</source>
<source lang="perl">
package AN::Tut::Sample1;

# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;
use Carp;

# My constructor method
sub new
{
	# gets the Package name.
	my $class=shift;
	print "The first argument passed into my constructor method is the 'class': [$class]\n";
	
	# Create an anonymous hash reference for later use.
	my $self={};
	print "This is what the simple hash reference 'self' looks like at first: [$self]\n";
	
	bless ($self, $class);	# Associate 'self' as an object in 'class'.
	print "This is what the hash ref. 'self' looks like after being 'bless'ed into this class: [$self]\n";
	
	return ($self);
}

# My addition method
sub add
{
	# I expect this to be called via the object returned by the constructor
	# method.
	my $self=shift;
	print "The first argument passed into my 'add' method: [$self]\n";
	
	# Pick up my two numbers.
	my $num_a=shift;
	my $num_b=shift;
	
	# Just a little sanity check.
	if (($num_a !~ /(^-?)\d+(\.\d+)?/) || ($num_b !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample1->add' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num_a + $num_b;
	
	# Return the results.
	return ($result);
}

1;
</source>

== Step Through the Module; 'AN::Tut::Sample1' ==

Let's start by stepping through the '<span class="code">AN::Tut::Sample1</span>' file and talk about each section.

=== Function: package ===

The first line is the '<span class="code">package</span>' function.

<source lang="perl">
package AN::Tut::Sample1;
</source>

This function sets the scope of the '<span class="code">AN::Tut::Sample1</span>' package. It is traditionally at the top of the module file, but doesn't strictly need to be. Anything within the scope of the '<span class="code">package</span>' call will be loaded by the calling script. For example, let's say I had something like this:

<source lang="perl">
sub blah
{
	print "Interesting things!\n";
}

package AN::Tut::Sample1;
...
</source>

The subroutine '<span class="code">blah</span>' would not be a method available in the '<span class="code">AN::Tut::Sample1</span>' package as it is outside the package scope.

=== The 'BEGIN' Block ===

At this time, this isn't really needed, but I like to be in the habit of setting versions in my modules. This will be useful later if you want to ensure that a script is using a particular version of a module (or higher) later.

<source lang="perl">
# This sets the version of this file. It will be useful later.
BEGIN
{
	our $VERSION="0.1.001";
}
</source>

Setting up the Environment

The only thing of note here is the '<span class="code">use Carp</span>' module. This allows me to have the module '<span class="code">die</span>' (croak) or '<span class="code">warn</span>' (carp) in a way friendlier for the calling program. Please see '<span class="code">perldoc Carp</span>' for details.

<source lang="perl">
# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;
use Carp;
</source>

=== The Constructor Method ===

The constructor method is useful for storing values, setting options and so on within a given invocation of the module. I'll go into this more in the next example. We will see in the next example how we could use the constructor to record how many times a method is called and store the last arguments sent to a method. For now though, let's keep it simple.

Modules do not need this, per-se, as we will see when we call the '<span class="code">add</span>' method later.

<source lang="perl">
# My constructor method
sub new
{
	# gets the Package name.
	my $class=shift;
	print "The first argument passed into my constructor method is the 'class': [$class]\n";
	
	# Create an anonymous hash reference for later use.
	my $self={};
	print "This is what the simple hash reference 'self' looks like at first: [$self]\n";
	
	bless ($self, $class);	# Associate 'self' as an object in 'class'.
	print "This is what the hash reference 'self' looks like after being 'bless'ed into this class: [$self]\n";
	
	return ($self);
}
</source>

Let's look at a few things now:

==== sub new ====

The name '<span class="code">new</span>' itself is nothing special. I could just as easily have called this method '<span class="code">constructor</span>', '<span class="code">glarb</span>' or '<span class="code">wow</span>'... Perl doesn't care. The only thing to be said for the word '<span class="code">new</span>' is that it is probably the most often used name for constructor methods, so it might make the most sense to users of your module.

==== my $class=shift; ====

When a method is called directly, the first argument passed into it is the name of the package. In our case, this is '<span class="code">AN::Tut::Sample1</span>'. This is the module's "class", or name space. This will be used in a moment by '<span class="code">bless</span>'.

==== my $self={}; ====

This is a string variable that stores a pointer to an anonymous hash. In the real world, and as we will see in the next example, this would be where we'd store module-wide data. For now though, to keep things simple, we'll leave it empty and focus on what it looks like from invocation and through '<span class="code">bless'ing.

If the syntax seems a bit off, I could have written:

<source lang="perl">
my %self;
my $self=\%self;
</source>

This is exactly the same as above. If this still doesn't seem clear, please look at '<span class="code">perldoc perlref</span>'.

==== The 'add' Method ====

The biggest thing to note here is the the first argument passed into the function. I've called the variable that will pick up this argument '<span class="code">self</span>' because I anticipate that this method will be called using the object returned by my '<span class="code">new</span>' constructor method described above. This would look like:

<source lang="perl">
# Call 'add' using the object returned by my constructor method.
my $an=AN::Tut::Sample1->new();
$an->add(2, 2);
</source>

In this case, the first argument passed in is the '<span class="code">bless</span>'ed hash reference.

However:

If the user calls this method directly, the first argument passed in will be the module's class, it's name space. Specifically, the name following the '<span class="code">package</span>' function. If the user does this, nothing stored in the '<span class="code">bless</span>'ed '<span class="code">$self</span>' hash reference will be available. In this case, that is fine as the constructor does nothing yet. As we'll see shortly, the '<span class="code">new</span>' method will work just fine in either case.

<source lang="perl">
# My addition method
sub add
{
	# I expect this to be called via the object returned by the constructor
	# method.
	my $self=shift;		
	print "The first argument passed into my 'add' method: [$self]\n";
	
	# Pick up my two numbers.
	my $num_a=shift;
	my $num_b=shift;
	
	# Just a little sanity check.
	if (($num_a !~ /(^-?)\d+(\.\d+)?/) || ($num_b !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample1->add' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num_a + $num_b;
	
	# Return the results.
	return ($result);
}
</source>

Other than the first passed argument, the rest of this method works like any old subroutine.

==== Closing the Module ====

If you are familiar with writing libraries then this will be familiar.

When the module is loaded, it must end with '<span class="code">1;</span>' so that the '<span class="code">use AN::Tut::Sample1</span>' returns a success.

<source lang="perl">
1;
</source>

== The 'sample1.pl' script ==

Before we step through the '<span class="code">sample1.pl</span>' script itself, lets take a look at the output printed when we run it. This way, as we step through it, we can talk about the relevant output at the same time.

=== Output From Running 'sample1.pl' ===

This shows the output printed to the shell when the '<span class="code">sample1.pl</span>' script is called. Notice the difference of what it passed to the '<span class="code">add</span>' method when it's called via the '<span class="code">new</span>' constructor versus being called directly? At this point, it makes no difference at all, but very shortly it will.

<pre>
/usr/share/perl5/AN/Tut/sample1.pl
Here is what happens when I call the 'new' constructor method. 
The first argument passed into my constructor method is the 'class': [AN::Tut::Sample1] 
This is what the simple hash reference 'self' looks like at first: [HASH(0x945d880)] 
This is what the hash reference 'self' looks like after being 'bless'ed into this class: [AN::Tut::Sample1=HASH(0x945d880)] 
Now, this is what my 'an' object looks like: [AN::Tut::Sample1=HASH(0x945d880)] 
The first argument passed into my 'add' method: [AN::Tut::Sample1=HASH(0x945d880)] 
2 + 2 = [4] 
The first argument passed into my 'add' method: [AN::Tut::Sample1] 
2 + 2 = [4] 
</pre>

In brief; we call the '<span class="code">new</span>' constructor method which in turn shows what happens in that method. Then I call the '<span class="code">add</span>' method using the object returned by '<span class="code">new</span>' and print the results. Secondly, I call '<span class="code">add</span>' again with the same arguments to compare what happens differently in the '<span class="code">add</span>' method when called directly.

=== Loading Modules ===

The first two modules are the usual, built-in modules that tell perl to be picky about what it fails on. 

<source lang="perl">
#!/usr/bin/perl

# This just sets perl to be strict about how it runs.
use strict;
use warnings;
</source>

Then we load our module.

<source lang="perl">
# Load my module.
use AN::Tut::Sample1;
</source>

What we've done here is tell perl to look for the module '<span class="code">AN::Tut::Sample1</span>' and load anything in it's name space, specifically, anything in the scope of the '<span class="code">package</span>' function. 

You probably noticed that the '<span class="code">AN</span>' sub directory was not added to the '<span class="code">@INC</span>' array, but the module can still be found. You will remember that perl looks at the module name and converts the double-colons '<span class="code">::</span>' into directory delimiters. Therefore, perl actually looks for '<span class="code">AN/Sample1.pm</span>' within the directories in '<span class="code">@INC</span>', not simply '<span class="code">Sample1.pm</span>'.

In our module, we set a version in the '<span class="code">BEGIN</span>' block.  You likely also noticed that the variable was in all capital letters. This is a special variable that we can use to ensure in our calling script that the module is of a certain version or newer. We don't actually do this here, to keep things simple, but you can modify the '<span class="code">use</span>' line above to specify a certain version. To do so, change the line to:

<source lang="perl">
# Load my module.
use AN::Tut::Sample1 0.1.001;
</source>

In this case, perl will fail at compile time if the module version it finds is too old. For example, if you instead changed the version to, say, '<span class="code">0.1.002</span>' and tried to run the script, you would see the error:

<source lang="perl">
AN::Tut::Sample1 version v0.1.2 required--this is only version v0.1.1 at ./sample1.pl line 14. 
BEGIN failed--compilation aborted at ./sample1.pl line 14. 
</source>

We won't explore this further in this paper, but it was worth mentioning that we could see how this works.

=== Creating an Object to Access our Module's Methods ===

We want to show what happens when we call the '<span class="code">add</span>' method using the object returned by our constructor method versus calling the method directly. To do this, we must first call the constructor and store the returned object in a string variable. Once we have this, we will print the contents of the object.

<source lang="perl">
# Call my constructor method and show the user what is happening.
print "Here is what happens when I call the 'new' constructor method.\n";
my $an=AN::Tut::Sample1->new();
print "Now, this is what my 'an' object looks like: [$an]\n";
</source>

You will notice once we run this script that the contents of '<span class="code">$an</span>' will match the '<span class="code">bless</span>'ed version of the module's internal '<span class="code">$self</span>' hash reference. The code above generates this output:

Here is what happens when I call the '<span class="code">new</span>' constructor method. 

<pre>
The first argument passed into my constructor method is the 'class': [AN::Tut::Sample1] 
This is what the simple hash reference 'self' looks like at first: [HASH(0x9271880)] 
This is what the hash reference 'self' looks like after being 'bless'ed into this class: [AN::Tut::Sample1=HASH(0x9271880)] 
Now, this is what my 'an' object looks like: [AN::Tut::Sample1=HASH(0x9271880)]
</pre>

We can see that the first and last lines come from the '<span class="code">sample1.pl</span>' script and the rest of the lines are printed by '<span class="code">AN::Tut::Sample1's '<span class="code">new</span>' constructor. Pay attention to how the module's class is the argument passed in, what the '<span class="code">$self</span>' hash reference looks like at first and how the module's class get prefixed to this hash reference by the '<span class="code">bless</span>' function. This is how the object returned to the caller is constructed and will become the instance of this module.

=== Call the 'add' Method Via the Module's Object ===

First I will call the '<span class="code">add</span>' method using the object, then, we will call it again directly. Thanks to the '<span class="code">print</span>' statement in the '<span class="code">add</span>' method, you will see that the first argument passed into the method differs in either case. When called using '<span class="code">$an</span>', the first argument it receives is the module's object, which again is the '<span class="code">bless</span>'ed '<span class="code">$self</span>' hash reference. When called directly, you will see that the first  argument is the module's class, which is the name set by the '<span class="code">package</span>' function.

==== Calling 'add' Via the Module's Object ====

Watch when this portion of '<span class="code">sample1.pl</span>' runs.

<source lang="perl">
# Call the method 'add' using my 'an' object.
my $added_1=$an->add(2, 2);
print "2 + 2 = [$added_1]\n";
</source>

You will see a combination of the '<span class="code">print</span>' from the '<span class="code">add</span>' method followed by the simple '<span class="code">print</span>' above.

<pre>
The first argument passed into my 'add' method: [AN::Tut::Sample1=HASH(0x9271880)] 
2 + 2 = [4] 
</pre>

Take notice of how the argument passed into the method is the object used to call it.

==== Calling 'add' Directly ====

This time we call the '<span class="code">add</span>' method directly. 

<source lang="perl">
# Call the method 'add' directly via the module.
my $added_2=AN::Tut::Sample1->add(2, 2);
print "2 + 2 = [$added_2]\n";
</source>

This time, the '<span class="code">add</span>' method prints a line showing that the first argument passed in is the module's class.

<pre>
The first argument passed into my 'add' method: [AN::Tut::Sample1] 
2 + 2 = [4] 
</pre>

= Our Second Module; AN::Tut::Sample2 =

This module is simply an expansion of our first module. The difference is that now we will make use of the module's object. We add five methods to this module. Two are meant to be used by the user and three are "private methods".  

== The New Module; Sample2.pm ==

This is the new module, '<span class="code">AN::Tut::Sample2</span>', with the five new methods and an expanded constructor.

<source lang="bash">/usr/share/perl5/AN/Tut/Sample2.pm</source>
<source lang="perl">
package AN::Tut::Sample2;

# This sets the version of this file. It will be useful later.
BEGIN
{
	our $VERSION="0.1.001";
}

# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;
use Carp;

# My constructor method
sub new
{
	# gets the Package name.
	my $class=shift;
	
	# Now this hash reference will be used to store a counter of how many
	# times the module is called and how many times each method is called.
	my $self={
		CALL_COUNT	=>	0,
		CALLED		=>	{
			ADD		=>	0,
			SUBTRACT	=>	0,
		},
	};
	
	bless ($self, $class);	# Associate 'self' as an object in 'class'.
	
	return ($self);
}

# My addition method
sub add
{
	# I expect this to be called via the object returned by the constructor
	# method. The next two arguments are the two numbers to sum up.
	my $self=shift;
	my $num_a=shift;
	my $num_b=shift;
	
	# Make sure that this method is called via the module's object.
	croak "The method 'add' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# Count this call.
	$self->_count_module;
	$self->_count_method_add;
	
	# Just a little sanity check.
	if (($num_a !~ /(^-?)\d+(\.\d+)?/) || ($num_b !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample2->add' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num_a + $num_b;
	
	# Return the results.
	return ($result);
}

# My subtraction method
sub subtract
{
	# I expect this to be called via the object returned by the constructor
	# method. Then I expect a number followed by the number to subtract
	# from it.
	my $self=shift;
	my $num_a=shift;
	my $num_b=shift;
	
	# Make sure that this method is called via the module's object.
	croak "The method 'subtract' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# Count this call.
	$self->_count_module;
	$self->_count_method_subtract;
	
	# Just a little sanity check.
	if (($num_a !~ /(^-?)\d+(\.\d+)?/) || ($num_b !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample2->subtract' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num_a - $num_b;
	
	# Return the results.
	return ($result);
}

# This simply returns how many times things have been called.
sub get_counts
{
	my $self=shift;
	croak "The method 'get_counts' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# I don't actually do anything here, I just return value. The one thing
	# to note though is how I call the internal method '_count_module',
	# which will increment the overall module call to account for this
	# call, and then return the values from the 'self' hash directly so
	# that they don't increment.
	return ($self->_count_module, $self->{CALLED}{ADD}, $self->{CALLED}{SUBTRACT});
}

# My internal method to count calls to this module. Returns the current count.
sub _count_module
{
	my $self=shift;
	
	# Increment by one.
	$self->{CALL_COUNT}++;
	
	return ($self->{CALL_COUNT});
}

# My internal method to count calls to the 'add' method.
sub _count_method_add
{
	my $self=shift;
	
	# Increment by one.
	$self->{CALLED}{ADD}++;
	
	return ($self->{CALLED}{ADD});
}

# My internal method to count calls to the 'add' method.
sub _count_method_subtract
{
	my $self=shift;
	
	# Increment by one.
	$self->{CALLED}{SUBTRACT}++;
	
	return ($self->{CALLED}{SUBTRACT});
}

1;
</source>

== Public Versus Private Methods ==

<blockquote>
"Perl doesn't have an infatuation with enforced privacy. It would prefer that you 
stayed out of its living room because you weren't invited, not because it has a 
shotgun"
</blockquote>
<blockquote>
- Larry Wall
</blockquote>

In truth, there is no difference between "public" and "private" methods. This is entirely a "by convention" concept. If you wish, you can call a private method, though you do so at your own risk. 

=== Public Methods ===

Public methods are the "normal" methods in that they are well documented. Good module programmers do all that they can to not change the arguments or returned values of a method so that programs that use them won't break as the method changes over time.

In this module, there are four public methods.

* '<span class="code">new</span>'
** The constructor method.
* '<span class="code">add</span>'
** The addition method that takes two numbers and returns the sum of those numbers.
* '<span class="code">subtract</span>'
** The subtraction method that takes two numbers and returns the subtracted value.
* '<span class="code">get_counts</span>'
** The method that takes no arguments and returns how many times the module has been called and how many times the '<span class="code">add</span>' and '<span class="code">subtract</span>' methods where called.

=== Private Methods ===

Private methods are intended to be used internally within the module itself. By convention, private methods begin with an underscore, though this is not a requirement. There is rarely public documentation and little effort is made towards backwards compatibility.

In this module, there are three private methods.

* '<span class="code">_count_module</span>'
** This method counts each time the module is called.
* '<span class="code">_count_method_add</span>'
** This counts each time the '<span class="code">add</span>' method is called.
* '<span class="code">_count_method_subtract</span>'
** This counts each time the '<span class="code">subtract</span>' method is called.

=== The 'bless'ed '$self' Hash Reference, redux ===

Throughout this document, we will use '<span class="code">$self</span>' as our object and it will be a hash reference. Note though that you could use any reference; An array reference, a simple string reference, etc. Likewise, you can use a name other than '<span class="code">$self</span>'. All that really matters is that it is '<span class="code">bless</span>'ed into your package.

When the object is used to by the user to call a method, the object itself becomes the first argument passed into the called method. In this module, we are creating a somewhat artificial use for the object's hash reference; We use it to store integer values representing how many times different methods are called.

You will notice that in any method called using the object, the '<span class="code">$self</span>' hash keys in the constructor can be directly accessed. Doing so is considered bad form though. So right off the bat we will create private methods to manipulate the contents of this hash. The reasoning for this extra overhead is protection of the data contained within the hash and to create a single point of manipulation for any given key. This becomes particularly important in complex methods where the values stored in the hash are used to control how things work.

== Stepping Through the New Module and Script ==

There isn't much changed from the user's point of view, so we will just look at the important bits.

In the real world, this would be the next version of the same module. For this reason, we will be careful to not change what arguments are accepted or what values are returned. That is exactly the goal of modules. Portable, backwards compatible code!

=== The Constructor Method ===

The first real difference with the new module is the '<span class="code">$self</span>' hash reference. Now there are keys and values where the first module's '<span class="code">$self</span>' hash reference was empty.

<source lang="perl">
	my $self={
		CALL_COUNT	=>	0,
		CALLED		=>	{
			ADD		=>	0,
			SUBTRACT	=>	0,
		},
	};
</source>

You might have noticed that these keys are in all capital letters. There is no requirement for this, but it is recommended to make it easier to see at a glance that you are accessing keys in the '<span class="code">bless</span>'ed hash.

These keys will be used to keep a running count of how many times the module is called. Every call to any method will be recorded in '<span class="code">$self->{CALL_COUNT}</span>', how many times the '<span class="code">add</span>' and '<span class="code">subtract</span>' methods are called will be stored in '<span class="code">$self->{CALLED}{ADD}</span>' and '<span class="code">$self->{CALLED}{SUBTRACT}</span>' respectively.

=== The Updated 'add' Method ===

From a functional point of view, '<span class="code">add</span>' still does exactly the same thing it did before. This way, if our user upgrades to the new version of this module, their old calls to this method will still work.

There are three key internal differences:

* In the first module, we recommended that users access our method using the module's object returned by the constructor. Now we require it and will return an error if it is called directly.
* We call the '<span class="code">_count_module</span>' private method which will record the call to the module.
* We call the '<span class="code">_count_method_add</span>' private method which will record the call to the '<span class="code">add</span>' method.

==== Requiring Calls be Via the Module's Object ====

We want to make sure that every call to our module and the '<span class="code">add</span>' method are counted. This can only occur if the module is called using the module's '<span class="code">$an</span>' object as this is how we get access to our '<span class="code">bless</span>'ed hash reference.

<source lang="perl">
	# Make sure that this method is called via the module's object.
	croak "The method 'add' must be called via the object returned by 'new'.\n" if not ref($self);
</source>

If the user tries to directly access this method, they will see this error:

<pre>
The method 'add' must be called via the object returned by the 'new' constructor method. 
 at ./sample2.pl line 36
</pre>

This works because the '<span class="code">ref()</span>' function will return the module's class if '<span class="code">$self</span>' is indeed our hash reference. Otherwise '<span class="code">$self</span>' contains the module's class name directly so '<span class="code">ref()</span>' returns nothing, triggering the '<span class="code">croak</span>'.

==== Automatically Counting the Method and Module Call ====

Before we get to work on the numbers, we count the call to the module and this method by making two calls to the relevant private methods. 

<source lang="perl">
	# Count this call.
	$self->_count_module;
	$self->_count_method_add;
</source>

The rest of this method is the same as before.

=== The New 'subtract' Public Method ===

This nearly identical to the '<span class="code">add</span>' method. The only difference is that is subtracts the second number from the first.

=== The New '_count_module' Private Method ===

This private method is called automatically by all three public methods. This way we can keep a count of how many times the module was called in any way.

<source lang="perl">
sub _count_module
{
	my $self=shift;
	
	# Increment by one.
	$self->{CALL_COUNT}++;
	
	return ($self->{CALL_COUNT});
}
</source>

It simply increments the object's '<span class="code">CALL_COUNT</span>' hash key and the returns the same.

=== The New '_count_method_add' Private Method ===

This private method is called automatically when the '<span class="code">add</span>' method is called. 

<source lang="perl">
sub _count_method_add
{
	my $self=shift;
	
	# Increment by one.
	$self->{CALLED}{ADD}++;
	
	return ($self->{CALLED}{ADD});
}
</source>

Like in the '<span class="code">_count_module</span>' above, this simply increments the object's '<span class="code">{CALLED}{ADD}</span>' hash key and then returns it.

=== The New '_count_method_subtract' Private Method ===

This private method is almost identical the '<span class="code">_count_method_add</span>' except that it is called by the '<span class="code">subtract</span>' public method. It increments and returns the  object's '<span class="code">{CALLED}{SUBTRACT}</span>' hash key

=== The New 'get_counts' Public Method ===

This method returns three values; 

* How many times the module has been called, including the current call. It does this by calling '<span class="code">_count_module</span>' in the '<span class="code">return ()</span>'.
* How many times the '<span class="code">add</span>' method was called. In this case, we directly call and return the object's hash key because calling '<span class="code">_count_method_add</span>' would increment the value improperly.
* How many times the '<span class="code">add</span>' method was called in the same way as above.

== The New Script; Sample2.pl ==

This is the updated script that will demonstrate the new methods in this module.

<source lang="bash">/usr/share/perl5/AN/Tut/sample2.pl</source>
<source lang="perl">
#!/usr/bin/perl

# This just sets perl to be strict about how it runs.
use strict;
use warnings;

# Load my module.
use AN::Tut::Sample2;

# Call my constructor method and show the user what is happening.
print "Starting 'sample2.pl'\n";
my $an=AN::Tut::Sample2->new();

# Call the method 'add' using my 'an' object.
my $added_1=$an->add(2, 2);
print "2 + 2 = [$added_1]\n";

# Call the method 'add' using my 'an' object.
my $subtract_1=$an->subtract(9, 4);
print "9 - 4 = [$subtract_1]\n";

# Now show the counts.
my ($module_count, $add_count, $subtract_count)=$an->get_counts();
print "Method call counts; All: [$module_count], add: [$add_count], subtract: [$subtract_count]\n";

# Change this to '1' to see how calling this method directly will trigger an
# error.
if (0)
{
	my $added_2=AN::Tut::Sample2->add(2, 2);
	print "2 + 2 = [$added_2]\n";
}

exit 0;
</source>

This is pretty similar to '<span class="code">sample1.pl</span>'. We see that the '<span class="code">add</span>' method is still called the same way and we've got a call to the new '<span class="code">subtract</span>' method. 

The first real difference is the call to the '<span class="code">get_counts</span>' method to show how many times we called the module and it's public methods. The second is the disabled, illegal call to '<span class="code">add</span>'. If you change '<span class="code">if (0)</span>' to '<span class="code">if (1)</span>' and try running the script you will see how the '<span class="code">add</span>' method will '<span class="code">croak</span>' not having been called via the module's object.

== Running 'sample2.pl' ==

This is what we see when we run '<span class="code">sample2.pl</span>'.

<source lang="bash">/usr/share/perl5/AN/Tut/sample2.pl</source>
<source lang="perl">
Starting 'sample2.pl' 
The first argument passed into my 'add' method: [AN::Tut::Sample2=HASH(0x92e3f20)] 
2 + 2 = [4] 
9 - 4 = [5] 
Method call counts; All: [3], add: [1], subtract: [1] 
</source>

It's a lot cleaner than '<span class="code">sample1.pl</span>' and closer to what your user might actually expect to see.

= Using Sibling Modules =

At some point you may decide that you have too many methods, or you will have methods that are too dissimilar to keep them in the same module. At this point you will want to break up your methods into a suite of modules in a common name space. These modules are then referred to as "sibling" modules.

This begs the question; How do you put methods in different modules while still allowing those methods to call one another? There are many ways to split up your modules, and no one way is particularly better than another. We will see here one method that is some what object oriented.

== Overview ==

This section will use almost all new methods and a new file layout. Before we jump into it, I would like to give a brief overview of how the script and modules will work to help you follow along easier.

Access to all modules and their methods will be done via a single "parent" module. This is in fact just another sibling module, and is being called a "parent" only to help you visualize it's role. 

When the user calls the parent's constructor method, it automatically calls the constructor methods of all the sibling modules and then stores the returned objects as internal variables. Then the constructor calls the method '<span class="code">_parent</span>' in each sibling, passing into the child module the handle to itself. Finally, the parent returns it's own blessed reference, it's object, to the user.

The parent module offers a method for each sibling module with a matching name whose sole purpose is to return to the user it's handle on the child module's object. It is through these methods that the user will access the methods in each siblings modules. This is also how each child module will access it's sibling's methods.

This will all make more sense once we step through the new script and modules.

=== The New Suite ===

This example suite uses many files. They are:

* <span class="code">sample3.pl</span>
** This is the new sample script that will use the new module suite.
* <span class="code">AN::Tut::Tools</span>
** This is the "parent" method. Access to all child modules will be through this module.
* <span class="code">AN::Tut::Tools::Math</span>
** This is a module that provides mathematical methods. It provides the same methods as before plus one new method.
* <span class="code">AN::Tut::Tools::Say</span>
** This is a module that provides a localization method.
* <span class="code">Tools.pod</span>
** This is the POD documentation for the <span class="code">AN::Tut::Tools</span> module. We will cover documentation in the next section.
* <span class="code">Math.pod</span>
** This is the POD documentation for <span class="code">AN::Tut::Tools::Math</span> module.
* <span class="code">Say.pod</span>
** This is the POD documentation for <span class="code">AN::Tut::Tools::Say</span> module.
* <span class="code">test.pl</span>
** This is a script used for testing our modules. We will cover tests more in the last section.
* <span class="code">t/Math.t</span>
** This is the test script for testing the <span class="code">AN::Tut::Tools::Math</span> methods.
* <span class="code">t/Say.t</span>
** This is the test script for testing the <span class="code">AN::Tut::Tools::Say</span> methods.

=== The Parent Module; AN::Tut::Tools ===

Let's start by looking at the full "parent" module:

<source lang="bash">/usr/share/perl5/AN/Tut/Tools.pm</source>
<source lang="perl">
package AN::Tut::Tools;

# This sets the version of this file. It will be useful later.
BEGIN
{
	our $VERSION="0.1.001";
}

# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;

use AN::Tut::Tools::Math;
use AN::Tut::Tools::Say;

# My constructor method
sub new
{
	# gets the Package name.
	my $class=shift;
	
	# Now this hash reference will be used to store a counter of how many
	# times the module is called and how many times each method is called.
	my $self={
		HANDLE	=>	{
			MATH	=>	"",
			SAY	=>	"",
		},
	};
	
	# Associate 'self' as an object in 'class'.
	bless ($self, $class);
	
	# Get a handle on the other two modules.
	$self->Math(AN::Tut::Tools::Math->new());
	$self->Say(AN::Tut::Tools::Say->new());
	
	# Pass along my handle to the sibling modules so that they can talk to
	# this module and their other sibling.
	$self->Math->_parent($self);
	$self->Say->_parent($self);
	
	return ($self);
}

# This is a the public access method to the internal 'AN::Tut::Tools::Math'
# object.
sub Math
{
	my $self=shift;
	
	$self->{HANDLE}{MATH}=shift if defined $_[0];
	
	return ($self->{HANDLE}{MATH});
}

# This is a the public access method to the internal 'AN::Tut::Tools::Say'
# object.
sub Say
{
	my $self=shift;
	
	$self->{HANDLE}{SAY}=shift if defined $_[0];
	
	return ($self->{HANDLE}{SAY});
}

1;
</source>

This is the "main" module that your users will load to get access to all the modules and method in your new suite. It provides only three methods, '<span class="code">new</span>', the usual constructor, '<span class="code">Math</span>', which sets and/or returns a handle to '<span class="code">AN::Tut::Tools::Math</span>' and '<span class="code">Say</span>', which sets and/or returns a handle to '<span class="code">AN::Tut::Tools::Say</span>'.

==== Loading the Siblings ====

The first real difference in this module is that it loads the sibling modules itself.

<source lang="perl">
use AN::Tut::Tools::Math;
use AN::Tut::Tools::Say;
</source>

By doing this, the user will not need to load all of the modules in our suite themselves. By loading just '<span class="code">AN::Tut::Tools</span>', they will have access to all the methods in all our modules.

==== Getting a Handle on our Siblings ====

Simply loading our siblings isn't enough because we are building object oriented style methods. We will need to call each sibling module's constructor method and store the returned object.

In this case, we will store these objects in the hash keys below:

<source lang="perl">
	my $self={
		HANDLE	=>	{
			MATH	=>	"",
			SAY	=>	"",
		},
	};
</source>

The name of the keys is not important. The only thing that matters is that the objects are stored in the '<span class="code">bless</span>'ed hash reference. For this reason, we call their constructors after we bless '<span class="code">$self</span>'.

<source lang="perl">
	# Get a handle on the other two modules.
	$self->Math(AN::Tut::Tools::Math->new());
	$self->Say(AN::Tut::Tools::Say->new());
</source>

Notice that the call to each sibling's constructor is contained withing the argument list for the '<span class="code">Math</span>' and '<span class="code">Say</span>' methods? This is just a lazy way to get the module's object and to pass it to the relevant method in one go.

==== Passing on our 'bless'ed Reference to our Siblings ====

The last thing our constructor method does is call a special, internal methods called '<span class="code">_parent</span>' for each of our sibling modules.

<source lang="perl">
	# Pass along my handle to the sibling modules so that they can talk to
	# this module and their other sibling.
	$self->Math->_parent($self);
	$self->Say->_parent($self);
</source>

As we will see later, each sibling will store the parent's object and us it to call the parent and it's siblings</span>' methods.

==== Getting a Handle on AN::Tut::Tools::Math ====

The '<span class="code">Math</span>' method does only two things; It returns whatever is stored in '<span class="code">$self->{HANDLE}{MATH}</span>' and, if something was passed into it, it saved that argument. 

<source lang="perl">
sub Math
{
	my $self=shift;
	
	$self->{HANDLE}{MATH}=shift if defined $_[0];
	
	return ($self->{HANDLE}{MATH});
}
</source>

When our constructor method called '<span class="code">AN::Tut::Tools::Math</span>'s '<span class="code">new</span>' constructor within the call to '<span class="code">Math</span>', the returned object got passed to this method and stored in '<span class="code">$self->{HANDLE}{MATH}</span>'. Now, whenever '<span class="code">Math</span>' gets called, the object referencing '<span class="code">AN::Tut::Tools::Math</span>' gets returned. 

We do it this way for the same reasons we discussed in the section; "[[TPM Talk: An Introduction Perl Modules#The 'bless'ed '$self' Hash Reference, redux|The 'bless'ed '$self' Hash Reference, redux]]". That is, we never want to directly access or alter the values stored in '<span class="code">$self</span>'. It is always better in the long run to have a single method to do this manipulation so that any future changes, tweaks or edits can be done in one place only.

==== Getting a Handle on AN::Tut::Tools::Say ====

This works exactly the same as the '<span class="code">Math</span>' call above.

<source lang="perl">
sub Say
{
	my $self=shift;
	
	$self->{HANDLE}{SAY}=shift if defined $_[0];
	
	return ($self->{HANDLE}{SAY});
}
</source>

=== The 'Say' Sibling; AN::Tut::Tools::Say ===

This new module provides a method that can return a language-specific string suitable for display to the end user. We will use this to create English or French strings, depending on the user's preference, describing the results of a calls to '<span class="code">AN::Tut::Tools::Math</span>'.

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Say.pm</source>
<source lang="perl">
package AN::Tut::Tools::Say;

# This sets the version of this file. It will be useful later.
BEGIN
{
	our $VERSION="0.1.001";
}

# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;
use Carp;


# The constructor method.
sub new
{
	my $class=shift;
	
	my $self={
		HANDLE_TUT_TOOLS	=>	""
	};
	
	bless ($self, $class);
	
	return ($self);
}

# Get a handle on the AN::Tut::Tools object. I know that technically that is a
# sibling module, but it makes more sense in this case to think of it as a
# parent.
sub _parent
{
	my $self=shift;
	my $parent=shift;
	
	$self->{HANDLE_TUT_TOOLS}=$parent if $parent;
	
	return ($self->{HANDLE_TUT_TOOLS});
}

# This method takes the values given to one of the Math methods, the result and
# the method called plus a language code to create a string to show the user.
sub math
{
	my $self=shift;
	my $param=shift;
	
	# I support two ways to pick up variables, so first I create the
	# empty or default variables here.
	my $task;
	my $num1;
	my $num2;
	my $result;
	my $lang="en";
	
	# Pick out the passed in parameters or switch to reading by array.
	if (ref($param) eq "HASH")
	{
		# Read in variables from the 'param' hash reference.
		$task=$param->{task};
		$num1=$param->{num1};
		$num2=$param->{num2};
		$result=$param->{result};
		$lang=$param->{lang} if exists $param->{lang};
	}
	else
	{
		# 'param' is not a hash reference, so switch to array-mode.
		$task=$param;
		$num1=shift;
		$num2=shift;
		$result=shift;
		$lang=shift if defined $_[0];
	}
	
	# Create the 'say' variable.
	my $say="";
	
	# Now choose the task 
	if ($task eq "add")
	{
		# Adding, now choose the language.
		if ($lang eq "en")
		{
			# English
			$say="I added: [$num1] and: [$num2] and got: [$result].";
		}
		elsif ($lang eq "fr")
		{
			# French
			$say="J'ai additionné: [$num1] et: [$num2] et la somme est: [$result].";
		}
	}
	elsif ($task eq "sub")
	{
		# Subtracting, now choose the language.
		if ($lang eq "en")
		{
			# English
			$say="I subtracted: [$num1] from [$num2] and got: [$result].";
		}
		elsif ($lang eq "fr")
		{
			# French (thanks to Sonja Elen Kisa for correcting my French!)
			$say="J'ai soustrait: [$num1] de: [$num2] et la différence est: [$result].";
		}
	}
	else
	{
		croak "Invalid task: [$task] passed to '\$an->Say->math'. Valid task arguments are 'add' and 'sub'.\n";
	}
	
	return ($say);
}

1;
</source>

==== Getting a Handle on our Parent; The '_parent' Method ====

In this module, we will use the hash key '<span class="code">HANDLE_TUT_TOOLS</span>' in our blessed reference to store the handle to the "parent" '<span class="code">AN::Tut::Tools</span>' module. The difference this time is that this module can't go out and get the handle. If it tried to, it would get a new object that wouldn't 
match the handle the user got. This is why '<span class="code">AN::Tut::Tools</span>' called this module's '<span class="code">_parent</span>' method and passed in it's own blessed hash reference. The '<span class="code">_parent</span>' module takes that reference and stores it. Thus, any further call to '<span class="code">_parent</span>' will return the '<span class="code">AN::Tut::Tools</span>' object.

=== The 'math' Method ===

This method is pretty straight forward from a module point of view. There is a little trick at the start that lets this method pick up arguments via an array or a hash. This trick exists so that the testing done in the last section will be more interesting. It checks to see if the first argument passed in my the user is a hash reference. If it is, it begins looking for variables by name. If it isn't, it switches to array-type reading of arguments and copies '<span class="code">$param</span>' to '<span class="code">$task</span>'.

=== The 'Math' Sibling; AN::Tut::Tools::Math ===

Let's take a look at the whole module before looking at the new parts:

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Math.pm</source>
<source lang="perl">
package AN::Tut::Tools::Math;

# This sets the version of this file. It will be useful later.
BEGIN
{
	our $VERSION="0.1.001";
}

# This just sets perl to be strict about how it runs and to die in a way
# more compatible with the caller.
use strict;
use warnings;
use Carp;

# The constructor method.
sub new
{
	my $class=shift;
	
	my $self={
		HANDLE_TUT_TOOLS	=>	""
	};
	
	bless ($self, $class);
	
	return ($self);
}

# Get a handle on the AN::Tut::Tools object. I know that technically that is a
# sibling module, but it makes more sense in this case to think of it as a
# parent.
sub _parent
{
	my $self=shift;
	my $parent=shift;
	
	$self->{HANDLE_TUT_TOOLS}=$parent if $parent;
	
	return ($self->{HANDLE_TUT_TOOLS});
}

# My addition method
sub add
{
	# I expect this to be called via the object returned by the constructor
	# method. The next two arguments are the two numbers to sum up.
	my $self=shift;
	my $num1=shift;
	my $num2=shift;
	
	# Make sure that this method is called via the module's object.
	croak "The method 'add' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# Just a little sanity check.
	if (($num1 !~ /(^-?)\d+(\.\d+)?/) || ($num2 !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample2->add' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num1 + $num2;
	
	# Return the results.
	return ($result);
}

# My subtraction method
sub subtract
{
	# I expect this to be called via the object returned by the constructor
	# method. Then I expect a number followed by the number to subtract
	# from it.
	my $self=shift;
	my $num1=shift;
	my $num2=shift;
	
	# Make sure that this method is called via the module's object.
	croak "The method 'subtract' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# Just a little sanity check.
	if (($num1 !~ /(^-?)\d+(\.\d+)?/) || ($num2 !~ /(^-?)\d+(\.\d+)?/))
	{
		croak "The method 'AN::Tut::Sample2->subtract' needs to be passed two numbers.\n";
	}
	
	# Do the math.
	my $result=$num1 - $num2;
	
	# Return the results.
	return ($result);
}

# My addition method that calls say on it's own.
sub add_and_say
{
	# I expect this to be called via the object returned by the constructor
	# method. The next two arguments are the two numbers to sum up.
	my $self=shift;
	my $num1=shift;
	my $num2=shift;
	my $lang=defined $_[0] ? shift : "en";
	
	# Make sure that this method is called via the module's object.
	croak "The method 'add' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# I use this object to get access to my sibling module's methods.
	my $an=$self->_parent;
	
	# Call a method in this module, but use the object from 'parent'
	# instead of 'self'. 
	my $result=$an->Math->add($num1, $num2);
	
	# Call $an->Say to print the result.
	my $say_result=$an->Say->math({
		lang	=>	"$lang",
		task	=>	"add",
		num1	=>	$num1,
		num2	=>	$num2,
		result	=>	$result
	});
	
	# Return the results.
	return ($say_result);
}

1;
</source>

This module is fairly similar to what we saw earlier in '<span class="code">Sample1.pm</span>' and the '<span class="code">Sample2.pm</span>' modules. The main difference is that the counting methods are gone and a new '<span class="code">add_and_say</span>' method has been added. 

==== Using the Parent Handle in 'add_and_say' ====

The new '<span class="code">add_and_say</span>' method is actually a wrapper for two methods; The '<span class="code">add</span>' method in this module and the '<span class="code">math</span>' module in the AN::Tut::Tools::Say sibling module.

<source lang="perl">
sub add_and_say
{
	# I expect this to be called via the object returned by the constructor
	# method. The next two arguments are the two numbers to sum up.
	my $self=shift;
	my $num1=shift;
	my $num2=shift;
	my $lang=defined $_[0] ? shift : "en";
	
	# Make sure that this method is called via the module's object.
	croak "The method 'add' must be called via the object returned by 'new'.\n" if not ref($self);
	
	# I use this object to get access to my sibling module's methods.
	my $an=$self->_parent;
	
	# Call a method in this module, but use the object from 'parent'
	# instead of 'self'. 
	my $result=$an->Math->add($num1, $num2);
	
	# Call $an->Say to print the result.
	my $say_result=$an->Say->math({
		lang	=>	"$lang",
		task	=>	"add",
		num1	=>	$num1,
		num2	=>	$num2,
		result	=>	$result
	});
	
	# Return the results.
	return ($say_result);
}
</source>

The first interesting bit is:

<source lang="perl">
	my $an=$self->_parent;
</source>

This calls the private method '<span class="code">_parent</span>' and stores the returned object in '<span class="code">$an</span>'. By doing this, we now have the object to '<span class="code">AN::Tut::Tools</span>' that matches the object returned to the user. This is particularly important in more complex programs that make use of shared variable. This object is how we will access methods in the '<span class="code">AN::Tut::Tools::Math</span>' module in the next two steps.

<source lang="perl">
	my $result=$an->Math->add($num1, $num2);
</source>

We could have used '<span class="code">my $result=$self->add</span>' just effectively. The only reason I don't is that using the '<span class="code">$an</span>' object allows me to move a method from one module to another module without changing any code; It makes this method more portable.

Now the magic!

<source lang="perl">
	my $say_result=$an->Say->math({
		lang	=>	"$lang",
		task	=>	"add",
		num1	=>	$num1,
		num2	=>	$num2,
		result	=>	$result
	});
</source>

By using the '<span class="code">Say</span>' method in the parent module '<span class="code">AN::Tut::Tools</span>' via the '<span class="code">$an</span>' object, I can call the '<span class="code">math</span>' method in '<span class="code">AN::Tut::Tools::Say</span>' from this module! This is how we can create a method that interacts with it's siblings, allowing the user to make a single method call the provides functions spanning multiple modules and methods!

== Putting it All Together; sample3.pl ==

<source lang="bash">/usr/share/perl5/AN/Tut/sample3.pl</source>
<source lang="perl">
#!/usr/bin/perl

# This just sets perl to be strict about how it runs.
use strict;
use warnings;

# Load my module.
use AN::Tut::Tools 0.0.001;

# Call my constructor method.
my $an=AN::Tut::Tools->new();

# Call the 'add' method via the 'Math' method.
my $num1=10;
my $num2=12;
my $result=$an->Math->add($num1, $num2);

### Here are the different ways this method can be called.
# Using the default language 'en', English.
print $an->Say->math("add", $num1, $num2, $result), "\n";
# Specifying the language 'fr', French
print $an->Say->math("add", $num1, $num2, $result, "fr"), "\n";
# Array-type; allows for better self-documenting code and flexible argument
# order.
print $an->Say->math({
	task	=>	"add",
	num1	=>	$num1,
	num2	=>	$num2,
	result	=>	$result,
	lang	=>	"fr"
}), "\n";

# This time I do the print and math at the same time. Ya, it's ugly. :)
$num1=40;
$num2=12;
print $an->Say->math({
	task	=>	"sub",
	num1	=>	$num1,
	num2	=>	$num2,
	result	=>	$an->Math->subtract($num1, $num2),
	lang	=>	"fr"
}), "\n";

# Finally, let's call 'add_and_say' to show how one module's method can call a
# sibling module's method.
print $an->Math->add_and_say(15, 20), "\n";
# Again, but specifying a language.
print $an->Math->add_and_say(2, 18, "fr"), "\n";

exit 0;
</source>

We accessed both the '<span class="code">Math</span>' and '<span class="code">Say</span>' modules via the '<span class="code">$an</span>' object. We only needed to load the parent module '<span class="code">AN::Tut::Tools</span>' and then use it's pointer methods. This lets us expand our module in future releases, adding entirely new modules to our suite and the user never has to worry about it. They can simply start using the new module's methods via new pointer methods we would add.

The rest of this sample script shows examples of different ways the methods can be called. These are needlessly complex, but will show different ways of writing tests in the last section of this paper.

Here's what it looks like when we run it.

<pre>
/usr/share/perl5/AN/Tut/sample3.pl
I added: [10] and: [12] and got: [22]. 
J'ai additionné: [10] et: [12] et la somme est: [22]. 
J'ai additionné: [10] et: [12] et la somme est: [22]. 
J'ai soustrait: [40] de: [12] et la différence est: [28]. 
I added: [15] and: [20] and got: [35]. 
J'ai additionné: [2] et: [18] et la somme est: [20]. 
</pre>

Pretty neat, eh?

= Documentation: PODs (Plain-Old Document) =

Documenting your modules can be done in a few ways. As good programmers, we already liberally sprinkle our code with comments in the program itself. We also use clear variable names to make the code as self-documenting as possible. 

What about our users though? If we're writing a module, we can't expect a user to ever look at our module's source code, so we need another mechanism to make our documentation available to them. Perl has this ability through '<span class="code">POD's; Plain Old Documentation.

POD documentation can exist in-line in our module or exist in a dedicated '<span class="code">Module.pod</span>' file sitting beside our '<span class="code">Module.pm</span>' module file. In either case, the user can then read our file by using a tool like the Linux command line '<span class="code">perldoc Your::Module</span>'.

The syntax for PODs is a simple markup language.

== In-line POD Documentation ==

Before we get into the actual syntax of POD, I wanted to point out the difference between in-line POD and a dedicated POD file.

When writing your POD in-line, you simply wrap the docs in '<span class="code">=pod</span>' and '<span class="code">=cut</span>'. Anything between these will be ignored by the perl interpreter at run time. All POD command syntax must start at the beginning of a newline with a blank line above and below it to be parsed properly.

Generally, when doing in-line documentation, a POD section will precede the method or function it relates to. This is by convention only however.

You do not need to wrap the text inside PODs unless you specifically want a certain indentation. Instead, just write each paragraph on a single line and the POD interpreted will handle line wrapping for you.

== POD Markup Syntax ==

It is a simple markup syntax that POD compatible readers can interpret and format for display to the user. The most common interpreter is '<span class="code">perldoc</span>', though many other POD interpreters exist to translate POD documentation into web pages and other formats.

POD syntax is pretty straight-forward. Here is a quick overview of how the syntax would be ordered, with the actual documentation still missing. This is pretty much copypasta of the '<span class="code">perldoc perlpod</span>' documentation.

<pre>
=pod 
=encoding type 
=head1 Heading Text 
=head2 Heading Text 
=head3 Heading Text 
=head4 Heading Text 
=over #
=item stuff 
=back 
=begin format 
=end format 
=for format text... 
=cut 
</pre>

All command syntax requires a blank line preceding it and for the command to be at the start of the new line.

=== =pod ===

This starts the POD documentation. If you are using a dedicated '<span class="code">something.pod</span>' file, this will be the first line, or at least the start of what you want the user to read. When using in-line documentation, this will end the compilation of your code until the first '<span class="code">=cut</span>' is seen.

=== =cut ===

This ends a block of POD documentation. When in-line with a program, normal compilation of the script will resume after this line.

=== =head# (1 - 4) ===

This precedes the heading text. Any text following a '<span class="code">=head#</span>' will be given a prominent font style to bring attention to the user. There are four heading levels supported, with 3 and 4 being recent additions not supported by older versions of perldoc.

Under all four heading styles, text following the heading is indented eight spaces.

==== =head1 ====

Heading 1 bolds the text and does not indent the string following it. An example:

<pre>
=head1 METHODS
</pre>

This module provides methods that do foo...

==== =head2 ====

Heading 2 bolds the text and indents the following text four spaces. For example:

<pre>
=head 2 method_name
</pre>

This method provides bar...

==== =head3 ====

Heading 3 underlines the text and indents the following text eight spaces.

==== =head4 ====

Heading 4 does not format the following text and indents it eight space.

=== =over #, =item, =back ===

The '<span class="code">=over</span>' command starts a list of '<span class="code">=item's, ending with the closing '<span class="code">=back</span>' command. This is useful for creating a list, for example, of parameters a method takes.

The '<span class="code">#</span>' following the '<span class="code">=over</span>' is an optional number of '<span class="code">ems</span>' (elements) to indent the paragraph(s) describing each item in the list. The default is 4 ems when no number is given. At the command line, this translates to the description text being incremented four spaces. By contrast, '<span class="code">=over 2</span>' will increment the description text by 2 elements, or spaces when interpreted by perldoc.

An example:

<pre>
=over

=item

foo

Foo is the first argument that 'some_method' takes and can be ...

=item 

bar

Bar is the second argument that 'some_method' takes and is used to...

=item 

baz

Baz is the last argument taken and is optional. It controls...

=back
</pre>

==== Some notes on '=item' ====

If you put one bare word following '<span class="code">=item</span>', the description text will start in-line after item's text. If you put a space in front of the first line of description text though, the description text will start on an indented new line with the first line of the paragraph being indented one extra space. 

Alternatively, you can put a star '<span class="code">*</span>' between the item command and it's text to create a bullet list (=item * foo). Likewise, if the first line in the description is a single bare word, perldoc will create a bulleted entry. Last, you can put a number followed by a period after the item and before it's text to create a numbered list (=item 1. foo). A bare word followed by '<span class="code">()</span>' (=item foo()) will be underlined and the description text will start on a new line. Whichever you use, just be sure to be consistent.

Lastly, you can not use '<span class="code">=head#</span>' inside an '<span class="code">=over</span>' - '<span class="code">=back</span>' block.

=== Code Blocks ===

To prevent a line from being parsed in any way, simply put a space or tab at the beginning of the line. This is an effective way to show code.

=== Other Syntax ===

This covers just the basics of documenting your perl module. There are many other commands and formatting options well worth reviewing in '<span class="code">perldoc perlpod'! There are ways to specify the encoding used in your POD, a method for embedding other bits of data for compatible interpreters like HTML, manual formatting and embedding links.

== Dedicated POD File Examples ==

Lets see some real-world POD files created for the our most recent suite of modules.

=== AN::Tut::Tools.pod ===

<source lang="bash">/usr/share/perl5/AN/Tut/Tools.pod</source>
<source lang="perl">
=pod

=encoding utf8

=head1 NAME

AN::Tools::Tut

This module provides access to the the other C<AN::Tut::Tools> module's methods.

=head1 SYNOPSIS

  use AN::Tut::Tools;

  # Get a common object handle on all AN::Tut::Tools::* modules.
  my $an=AN::Tut::Tools->new();

=head1 DESCRIPTION

This module provides access to C<AN::Tut::Tools::Math> and C<AN::Tut::Tools::Say>. It provides no usable methods other than an object to access these other modules.

=head1 NOTES

All AN::Tut::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

=head1 METHODS

Below are the detailed usage instructions for the methods provided by this module.

=head2 Math

=head3 Example

  # Call 'add' in 'AN::Tut::Tools::Math'.
  my $num1=10;
  my $num2=12;
  my $result=$an->Math->add($num1, $num2);

=head3 Details

This method simply provides access to the methods provided by AN::Tut::Tools::Math. Please see that module's POD for mode information.

=head2 Say

=head3 Example

  # Call 'math' in 'AN::Tut::Tools::Say' using the data from the 'Math' call
  # above.
  print $an->Say->math("add", $num1, $num2, $result), "\n";

=head3 Details

This method simply provides access to the methods provided by AN::Tut::Tools::Say. Please see that module's POD for mode information.

=head1 SEE ALSO

Other modules in the AN::Tools suite:

=over

=item AN::Tut::Tools::Math

=item AN::Tut::Tools::Say

=back

=head1 LICENSE

 Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

=cut
</source>

=== AN::Tut::Tools::Say.pod ===

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Say.pod</source>
<source lang="perl">
=pod

=encoding utf8

=head1 NAME

AN::Tut::Tools::Say

This module provides access to the translation methods.

=head1 SYNOPSIS

  use AN::Tut::Tools;

  # Get a common object handle on all AN::Tut::Tools::* modules.
  my $an=AN::Tut::Tools->new();

=head1 DESCRIPTION

This module provides methods that take arguments and variables from other module's methods and generates a string in a given language suitable for reading by the user.

=head1 NOTES

All AN::Tut::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

=head1 METHODS

Below are the detailed usage instructions for the methods provided by this module.

=head2 math

=head3 Example

  # Do a simple addition using '$an->Math->add()' so that there is something to
  # talk about.
  my $num1=10;
  my $num2=12;
  my $result=$an->Math->add($num1, $num2);
  
  # Now generate and print a string to show the user using the default
  # language.
  print $an->Say->math("add", $num1, $num2, $result), "\n";
  
  # This time, generate a French string.
  print $an->Say->math("add", $num1, $num2, $result, "fr"), "\n";
  
  # Now, generate a French string using a hash to pass in arguments.
  print $an->Say->math({
  	task	=>	"add",
  	num1	=>	$num1, 
  	num2	=>	$num2, 
  	result	=>	$result, 
  	lang	=>	"fr"
  }), "\n";

=head3 Details

This method takes arguments passed into and the resulting output from calls to C<AN::Tut::Tools::Math>'s C<add> and C<subtract> methods. It then produces a string suitable for reading by the user in either English (default) or French.

=head3 Arguments

This method can either take arguments as an array or via a hash reference. The former being shorter and easier to type, the latter allowing for a more self-documenting format.

When call as an array, arguments must be passed in the order: C<task>, C<num1>, C<num2>, C<result> and, optionally, C<lang>. When C<lang> is not specified, C<en> (English) is used.

When call using a hash reference the arguments need not be in any particular order. The arguments below are to be used:

=head4 C<task>

This is either C<add> or C<sub> with no default being set. This is used as a key to tell this method what string type to generate; "Addition" or "Subtraction".

=head4 C<num1>

This is the first number used in the equation being discussed.

=head4 C<num2>

This is the second number used in the equation being discussed.

=head4 C<result>

This is the resulting number generated by the equation.

=head4 C<lang>

Default: C<en>

This is the language code used to tell this method what language string to create. Valid arguments are:

=over

=item C<en>

English

=item C<fr>

French

=back

=head1 SEE ALSO

Other modules in the AN::Tut::Tools suite:

=over

=item AN::Tut::Tools

=item AN::Tut::Tools::Math

=back

=head1 LICENSE

 Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

=cut
</source>

=== AN::Tut::Tools::Math.pod ===

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Math.pod</source>
<source lang="perl">
=pod

=encoding utf8

=head1 NAME

AN::Tools::Tut::Math

This module provides access to the mathematical methods.

=head1 SYNOPSIS

  use AN::Tut::Tools;

  # Get a common object handle on all AN::Tut::Tools::* modules.
  my $an=AN::Tut::Tools->new();

=head1 DESCRIPTION

This module provides methods for performing basic math.

=head1 NOTES

All AN::Tut::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

=head1 METHODS

Below are the detailed usage instructions for the methods provided by this module.

=head2 add

=head3 Example

  # Do a simple addition.
  my $num1=10;
  my $num2=12;
  my $result=$an->Math->add($num1, $num2);
  # $result is '22'.

=head3 Details

This method takes two numbers and returns the resulting addition of those two numbers. The numbers may be signed whole integers or floating points (real) numbers.

=head2 subtract

=head3 Example

  # Do a simple subtraction.
  # talk about.
  my $num1=10;
  my $num2=12;
  my $result=$an->Math->subtract($num1, $num2);
  # $result is '-2'.

=head3 Details

This method takes two numbers and returns the result of subtracting the second number from the first. The numbers may be signed whole integers or floating points (real) numbers.

=head2 add_and_say

=head3 Example

  # Do a simple addition, but get back the processed string in French.
  $an->Math->add_and_say(2, 18, "fr");
  # $result is 'J'ai additionné: [2] et: [18] et la somme est: [20].'.

=head3 Details

This method takes two numbers and returns a string in the specified language with the answer (English, if not specified).

=head1 SEE ALSO

Other modules in the AN::Tools suite:

=over

=item AN::Tut::Tools

=item AN::Tut::Tools::Say

=back

=head1 LICENSE

 Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

=cut
</source>

= The Importance of Testing =

<blockquote>
"Just as there's no such thing as a bug-free program there's no program that can't be debugged. Am l wrong?"
</blockquote>
<blockquote>
- Ghost in the Shell
</blockquote>

All module's and their methods need to be tested. This should be done after every change to the program. This can be extremely tedious without some testing program. Thankfully, several tools already exist to help you write a test script for your modules. 

To start, read the PODs for '<span class="code">Test::Tutorial</span>', then the '<span class="code">Test::Simple</span>' and lastly '<span class="code">Test::More</span>'. This section of the talk is an overview of those modules</span>' documentation. The main difference being that I assume you understand why testing is important so I will leave the sarcasm and brow-beating behind.

== Reasoning ==

The main reason for creating a comprehensive testing module is to help catch unanticipated consequences of changes to your modules. Ideally, your module will be used by many different people and/or in many different ways. Further, a proper test suite is required to get your modules onto CPAN.

A well designed test program calls your various module's and methods in all the possible ways you can think of. As you can guess, this means you have to write your test program to be very thorough. If you decide to leave the testing program until after you have finished your modules, you will be faced with a daunting task that you may simply never do. Like documentation, it is best to write your test suite along side of writing your modules themselves.

== The Test::More module ==

It is generally recommended to start your first test script using the '<span class="code">Test::Simple</span>' module. However, I disagree as '<span class="code">Test::More</span>' is a drop-in replacement for '<span class="code">Test::Simple</span>' that offers a wider range of tests. You may wish to start with '<span class="code">Test::Simple</span>' and then switch when you run into it's limitations. 

The two main reasons I prefer starting with '<span class="code">Test::More</span>' are;

* It supports a string describing each test.
* It has methods that go well beyond the simple '<span class="code">does A match B</span>' test. It allows for regular expression tests, '<span class="code">unlike</span>' tests and so forth.

== Overview ==

Each test is ultimately the same; Does '<span class="code">A</span>' [equal|not equal|match|not match] '<span class="code">B</span>'. If so, the test passes. If not, the test fails. If one or more tests fail, the entire test suite fails. Later, if your build a Makefile for your modules, a failed test will prevent your module suite from installing on a user's machine.

The core of the '<span class="code">Test::*</span>' suite is the '<span class="code">Test::Harness</span>' module. All other '<span class="code">Test::*</span>' modules print output in a format that '<span class="code">Test::Harness</span>' can parse. In turn, '<span class="code">Test::Harness</span>' ensures that all planned tests are run and it handles how the test results and errors are displayed to the user. 

== Example; test.pl ==

Let's take a look at a test suite for our most recent modules.

We'll start with a normal perl script that will load '<span class="code">Test::More</span>', test against the parent module and then call test files for each of the sibling modules.

<source lang="bash">/usr/share/perl5/AN/Tut/test.pl</source>
<source lang="perl">
#!/usr/bin/perl -Tw

use strict;
use warnings;
use POSIX;

# Be nice and set a version number.
our $VERSION="0.0.001";

# Call in the test module
use Test::More tests => 28;
# use Test::More 'no_plan';

# Load my module via 'use_ok' test.
BEGIN
{
	print "Will now test AN::Tut::Tools on $^O.\n";
	use_ok('AN::Tut::Tools', 0.0.001);
}

# Get a handle on the main module and test it.
my $an=AN::Tut::Tools->new();
like($an, qr/^AN::Tut::Tools=HASH\(0x\w+\)$/, "AN::Tut::Tools object appears valid.");

# Build an array of methods that 'AN::Tut::Tools' should provide.
my @methods=("Math", "Say");
can_ok("AN::Tut::Tools", @methods);

### test AN::Tut::Tools::Math
print "Testing AN::Tut::Tools::Math\n";
require_ok("AN/Tut/t/Math.t");

### test AN::Tut::Tools::Math
print "Testing AN::Tut::Tools::Say\n";
require_ok("AN/Tut/t/Say.t");

exit;
</source>

=== Breaking it Down ===

Let's take a closer look at the '<span class="code">test.pl</span>' script.

==== Loading Test::More ====

The first interesting part is:

<source lang="perl">
# Call in the test module
use Test::More tests => 28;
# use Test::More 'no_plan';
</source>

When you load '<span class="code">Test::More</span>' you can invoke it in one of two ways. Both are shown here, with the second one being commented out.

In the first case, I tell '<span class="code">Test::More</span>', which in turn tells '<span class="code">Test::Harness</span>', that I plan to run 28 tests. This is important because a given test could fail so badly that the test script could exit without the bad test itself returning a fail. Without a predetermined number of tests, '<span class="code">Test::Harness</span>' will see all run tests as having passed and declare the tests a success. Conversely, by declaring that we will run 28 tests, and 12 run successfully before the 13th kills the script, '<span class="code">Test::Harness</span>' will know that something went wrong and print an overall failure.

In the second commented out case, I tell '<span class="code">Test::More</span>' that I don't have a plan. This is useful while you write your test suite. It would be very annoying to have to go back and edit that line every time you add or remove a test. Be sure to always switch back to the planned number of tests when you finish working on your test suite.

==== The 'use_ok()' Method ====

The first step in our test is to load our '<span class="code">AN::Tools</span>' module.

<source lang="perl">
BEGIN
{
	print "Will now test AN::Tut::Tools on $^O.\n";
	use_ok('AN::Tut::Tools', 0.0.001);
}
</source>

This is done in a '<span class="code">BEGIN</span>' block, as recommended by '<span class="code">Test::More</span>', so that functions are exported at compile time and that prototypes are properly honoured.

The '<span class="code">use_ok</span>' test takes one or two arguments; The first being the module to load and the second, optional argument being the minimum version of the module needed. If anything were to fail when a user ran '<span class="code">use AN::Tut::Tools 0.0.001</span>', the '<span class="code">use_ok()</span>' test would catch it.

==== The 'like()' and 'unlike()' Tests ====

These tests do a regular expression test of the first argument against the second argument. 

<source lang="perl">
my $an=AN::Tut::Tools->new();
like($an, qr/^AN::Tut::Tools=HASH\(0x\w+\)$/, "AN::Tut::Tools object appears valid.");
</source>

In this example, I use a regular expression to make sure that the object returned by calling the constructor method is '<span class="code">bless</span>'ed into my module's class. The '<span class="code">unlike</span>' test is simply the reverse and would fail is '<span class="code">$an</span>' matched '<span class="code">/^AN::Tut::Tools=HASH\(0x\w+\)$/</span>'.

==== The 'can_ok()' Test ====

This test takes an array of method names as it's sole argument and fails in any of the method names in the array do not exist.

<source lang="perl">
my @methods=("Math", "Say");
can_ok("AN::Tut::Tools", @methods);
</source>

In this case, I am making sure that both the '<span class="code">Math</span>' and '<span class="code">Say</span>' methods exist. 

==== Loading Other Test Scripts ====

It is customary, and expected by perl Makefiles, that test scripts exist in a '<span class="code">/t</span>' subdirectory. Specifically, a '<span class="code">Module.t</span>' script is expected for each '<span class="code">Module.pm</span>' module.

<source lang="perl">
### test AN::Tut::Tools::Math
print "Testing AN::Tut::Tools::Math\n";
require_ok("AN/Tut/t/Math.t");

### test AN::Tut::Tools::Math
print "Testing AN::Tut::Tools::Say\n";
require_ok("AN/Tut/t/Say.t");
</source>

The rest of the '<span class="code">test.pl</span>' script loads these test files, one for each sibling module. 

=== The 'AN::Tut::Tools::Math' Module's 'Math.t' Test Script ===

The first test script to be run by '<span class="code">test.pl</span>' is '<span class="code">Math.t':

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Math.t</source>
<source lang="perl">
#!/usr/bin/perl -Tw

use AN::Tut::Tools 0.0.001;
my $an=AN::Tut::Tools->new();

# Make sure that $parent matches $an.
my $parent=$an->Math->_parent();
is($an, $parent, "Internal 'parent' method returns same blessed reference as is in \$an.");

# Make sure that all methods are available.
my @methods=("_parent", "add", "subtract", "add_and_say");
can_ok("AN::Tut::Tools::Math", @methods);

# Test adding a few numbers. Start with ints, then try signed and unsigned ints
# and floats.
#  Got					Expect	Message
is($an->Math->add(4, 8), 		12, 	"add(); Simple integer addition test.");
is($an->Math->add(4, 8.5), 		12.5, 	"add(); Integer plus float addition test.");
is($an->Math->add(5.25, 8.5), 	13.75, 	"add(); Float addition test.");
is($an->Math->add(15, -3), 		12, 	"add(); Signed integer addition test.");
is($an->Math->add(3, -15), 		-12, 	"add(); Signed integer addition with negative result test.");
is($an->Math->add(-15, -3), 		-18, 	"add(); Double-negative integer addition with negative result test.");
is($an->Math->add(+15, -3), 		12, 	"add(); Signed integer addition including '+' test.");

# Now test subtracting a few numbers. Same style of tests as above.
#  Got					Expect	Message
is($an->Math->subtract(15, 3), 	12, 	"subtract(); Simple integer subtraction test.");
is($an->Math->subtract(15, 2.5), 	12.5, 	"subtract(); Integer minus float subtraction test.");
is($an->Math->subtract(15.45, 2.5), 	12.95, 	"subtract(); Float subtraction test.");
is($an->Math->subtract(15, -3), 	18, 	"subtract(); Signed integer subtraction test.");
is($an->Math->subtract(3, -15), 	18, 	"subtract(); Signed integer subtraction with positive result test.");
is($an->Math->subtract(-15, -3), 	-12, 	"subtract(); Double-negative integer subtraction with negative result test.");
is($an->Math->subtract(+15, -3), 	18, 	"subtract(); Signed integer subtraction including '+' test.");

# Now test the 'add_and_say' method.
is(
	"I added: [15] and: [20] and got: [35].", 
	$an->Math->add_and_say(15, 20), 
	"add_and_say(); Test default language processing of a simple integer addition."
);
is(
	"J'ai additionné: [2] et: [18] et la somme est: [20].", 
	$an->Math->add_and_say(2, 18, "fr"), 
	"add_and_say(); Test specified language processing of a simple integer addition."
);
</source>

The first part of this test script is pretty normal.

==== The 'is()' and 'isnt()' Tests ====

The first new test we see is;

<source lang="perl">
# Make sure that $parent matches $an.
my $parent=$an->Math->_parent();
is($an, $parent, "Internal 'parent' method returns same blessed reference as is in \$an.");
</source>

This looks at the '<span class="code">$an</span>' object and compares it with the object returned by the private method '<span class="code">_parent</span>'. If they are the same, the test passes. The '<span class="code">isnt()</span>' test is simply the opposite test and would fail is the two objects matched. This is an example of how '<span class="code">is()</span>' and '<span class="code">isnt()</span>' can match normal strings. There is no separate test between numeric and string matching.

We see this test through the rest of this test files. In all cases, the first argument is what '<span class="code">Test::More</span>' expects, the second argument is what we're testing and the last argument is a description of the test.

=== The 'AN::Tut::Tools::Say' Module's 'Say.t' Test Script ===

The second test script to be run by '<span class="code">test.pl</span>' is '<span class="code">Say.t</span>'.

<source lang="bash">/usr/share/perl5/AN/Tut/Tools/Say.t</source>
<source lang="perl">
#!/usr/bin/perl -Tw

use AN::Tut::Tools 0.0.001;
my $an=AN::Tut::Tools->new();

# Make sure that $parent matches $an.
my $parent=$an->Say->_parent();
is($an, $parent, "Internal 'parent' method returns same blessed reference as is in \$an.");

# Make sure that all methods are available.
my @methods=("_parent", "math");
can_ok("AN::Tut::Tools::Say", @methods);

# First, I need something to talk about, so I will use this:
my $num1=10;
my $num2=12;
my $result=$an->Math->add($num1, $num2);

# Now, this module has only one method that takes arguments, but it can receive
# those arguments is several ways. This tests them.
is(
	$an->Say->math("add", $num1, $num2, $result), 						# Got
	"I added: [$num1] and: [$num2] and got: [$result].", 					# Expect
	"math(); Test default language processing using the default language, array-type call."	# Message
);
is(
	$an->Say->math("add", $num1, $num2, $result, "fr"), 					# Got
	"J'ai additionné: [$num1] et: [$num2] et la somme est: [$result].", 			# Expect
	"math(); Test processing, specifying French, array-type call."				# Message
);
is(
	$an->Say->math({task=>"add", num1=>$num1, num2=>$num2, result=>$result, lang=>"fr"}), 	# Got
	"J'ai additionné: [$num1] et: [$num2] et la somme est: [$result].", 			# Expect
	"math(); Test processing, specifying French, hash-type call."				# Message
);
</source>

This test introduces nothing new. It simply uses '<span class="code">is()</span>' and '<span class="code">can_ok()</span>' to do all the testing it needs.

=== The Majority of  the 'Math.t' and 'Say.t' Tests ===

The majority of the test scripts are a large number of '<span class="code">is()</span>' tests. 

Generally, we start with the simplest tests for each method, then add new tests of growing complexity to test all of the different ways a method can be called. The limit to testing is the limit of your imagination. 

This is another good reason to start your test scripts early. When you run into weird problems, often ones found by creative users, you can add tests for those conditions right away. This way, your test scripts grow in effectiveness right along with your modules growing in features.

== Running 'test.pl' ==

With the test scripts in place, we should see something like this:

<source lang="bash">/usr/share/perl5/AN/Tut/test.pl</source>
<pre>
1..28 
Will now test AN::Tut::Tools on linux. 
ok 1 - use AN::Tut::Tools; 
ok 2 - AN::Tut::Tools object appears valid. 
ok 3 - AN::Tut::Tools->can(...) 
Testing AN::Tut::Tools::Math 
ok 4 - Internal 'parent' method returns same blessed reference as is in $an. 
ok 5 - AN::Tut::Tools::Math->can(...) 
ok 6 - add(); Simple integer addition test. 
ok 7 - add(); Integer plus float addition test. 
ok 8 - add(); Float addition test. 
ok 9 - add(); Signed integer addition test. 
ok 10 - add(); Signed integer addition with negative result test. 
ok 11 - add(); Double-negative integer addition with negative result test. 
ok 12 - add(); Signed integer addition including '+' test. 
ok 13 - subtract(); Simple integer subtraction test. 
ok 14 - subtract(); Integer minus float subtraction test. 
ok 15 - subtract(); Float subtraction test. 
ok 16 - subtract(); Signed integer subtraction test. 
ok 17 - subtract(); Signed integer subtraction with positive result test. 
ok 18 - subtract(); Double-negative integer subtraction with negative result test. 
ok 19 - subtract(); Signed integer subtraction including '+' test. 
ok 20 - add_and_say(); Test default language processing of a simple integer addition. 
ok 21 - add_and_say(); Test specified language processing of a simple integer addition. 
ok 22 - require 'AN/Tut/t/Math.t'; 
Testing AN::Tut::Tools::Say 
ok 23 - Internal 'parent' method returns same blessed reference as is in $an. 
ok 24 - AN::Tut::Tools::Say->can(...) 
ok 25 - math(); Test default language processing using the default language, array-type call. 
ok 26 - math(); Test processing, specifying French, array-type call. 
ok 27 - math(); Test processing, specifying French, hash-type call. 
ok 28 - require 'AN/Tut/t/Say.t'; 
</pre>

The first line shows that there are 28 planned tests. The rest of the output simply shows that the test was "ok", what the test number was and finally the descriptive text we passed in as the third argument of each test.

Done!

That's it! You now have a documented, testable suite of object oriented perl modules that can talk to each other.

= References =

You can download a copy of this talk as a:
* [https://alteeve.ca/local/talks/whitepaper_TPM_Modules.pdf PDF] (289 KiB)
* [https://alteeve.ca/local/talks/whitepaper_TPM_Modules.odt ODT] (87 KiB)
You can download a copy of all the files in this talk:
* [https://alteeve.ca/local/talks/Module_Tutorial/AN_Tut_Tools_v0.0.001.tar.gz AN_Tut_Tools_v0.0.001.tar.gz] (7.4 KiB)
** '''Note'''! The above tarball is meant to be extracted in <span class="code">/usr/share/perl5/</span>. It will create a directory called '<span class="code">AN/</span>' in the directory it is extracted in.

{{footer}}