Packages and __PACKAGE__

The default name space in Perl is called main. Unless Perl is
directed otherwise, all subroutines and variables are added to the
main name space.

To create a new name space in Perl (also called a package) we use the
package keyword. Using different name spaces allows us to separate
our code into logical parts where we can have identically named
subroutines and variables if required. For example we may have a
Client package which includes subroutines for name, address,
and phone_number as well as a PTA package (for Perl Training
Australia) with the same subroutines.

__PACKAGE__

Sometimes you may find yourself writing the package name out multiple
times inside your package. For example, when using Class::DBI we
might write:

package Music::Artist;
# Inherit from the Music::DBI class (defined elsewhere)
use base 'Music::DBI';
# These records are pulled from this database table
Music::Artist->table('artist');
# We care about these columns
Music::Artist->columns(All => qw/artistid name/);
# Each artist may have many CDs
Music::Artist->has_many(cds => 'Music::CD');

As with any code repetition this can lead to errors should we later
decide to change our package name, or if someone should cut and paste
our code. To avoid these errors Perl gives us the __PACKAGE__
constant which contains the name of the current package.

This allows us to rewrite the above as follows:

package Music::Artist;
# Inherit from the Music::DBI class (defined elsewhere)
use base 'Music::DBI';
# These records are pulled from this database table
__PACKAGE__->table('artist');
# We care about these columns
__PACKAGE__->columns(All => qw/artistid name/);
# Each artist may have many CDs
__PACKAGE__->has_many(cds => 'Music::CD');

__PACKAGE__ and hashes

If you attempt to use the value from __PACKAGE__ as a hash key you
may find that things don't turn out exactly as you expect. Writing:

# Doesn't work as intended
$hash{__PACKAGE__} = 1;

will create the key __PACKAGE__ inside your hash rather than the
name of your package. This is because whenever a hash gets a bareword
as its key it immediately treats that as a string. Thus the following
two statements are the same.

Accidently creating a __PACKAGE__ key rather than one from the name
of your package is a very common mistaken which can lead to very
subtle and hard-to-track down bugs. If you are uncertain, remember
to use Data::Dumper on your hash to ensure that you're getting the
keys you want.