Skip to Content

Files and packages in Perl Syndicate content

Dave Sherohman's picture

In the last couple weeks, I've seen Perl questions on at least two separate forums which revolved around the connection between .pm files and Perl packages. Really, though, this connection is quite easy to understand if you just remember one thing:

It doesn't exist.

Well, OK, that may be overstating things a bit. There is a connection born of convention, but the language itself makes no rules about this. You can have five packages in a single file, a single package split across five files, a file containing a package with a different name, or any combination of the above. perl doesn't care how chaotic your naming may get.

This is the case because the two types of names have different significance:

  • The name of the .pm file is what you use or require when you want to pull that file's code into the current program. This process is essentially equivalent to putting the content of the used/required file into the file that uses/requires it. There is nothing magical about the name, it just needs to correspond to an existing file.
  • The package name determines how the contents of that package are referenced and, in object-oriented code, it identifies the class to which the code is attached. All Perl code is part of one package or another; if no package is specified, the code will be placed into package main.

Of course, code needs to be readable by programmers, not just by the language interpreter, so putting package Foo into Bar.pm is strongly discouraged, as that would lead to use Foo; being followed by Bar::some_sub or Bar->new without any indication of where Bar came from. Even though you can do this, you almost certainly should not. The standard convention is to give the same name to the .pm file and the package it contains and this convention should be followed in the large majority of cases.

There are, however, two situations in which I have found it useful and reasonable to make use of the ability to decouple package names from file names:

The first is when one (usually abstract) class has one or more (concrete) subclasses which are invariably used along with it. In this case, it can declutter things a bit to put all of Foo, Foo::Bar, and Foo::Baz into Foo.pm, giving access to all three with a single use Foo;. As the subclasses still fall within the Foo namespace, I do not feel that this compromises the clarity of the code.

The other is when writing small, self-contained utility scripts for which it would be useful to make use of simple object-oriented classes, but which do not warrant the overhead of needing an external module installed to provide those class definitions. In this case, it is possible to put the package providing the class definition directly into the main body of the program without using a .pm file at all, like so:

#!/usr/bin/perl

use strict;
use warnings;

my $foo = Inline::Foo->new('Hello, world!');
$foo->display;

### Inline::Foo ###
package Inline::Foo;

sub new {
  my $class = shift;
  return bless { text => shift }, $class;
}

sub display {
  my $self = shift;
  print $text = $self->{text}, "\n";
}

Note that there is no need to use Inline::Foo, as there is no external file that has to be read to provide the class definition.

Hopefully, this has helped to clarify the use of Perl packages and their relationship to the files which contain them.