Packages and Namespaces

Analogy categoryAnalogies

What a Package Actually Does

Every Perl variable and subroutine lives in a symbol table associated with a package, and the 'package' keyword simply changes which symbol table subsequent declarations attach to — it does not create a new file, scope block, or class by itself. By default every script starts in package 'main', so a bare subroutine 'sub hello {}' is really 'main::hello'; writing 'package Utils::Math;' before defining 'sub add {}' makes it accessible as 'Utils::Math::add()' from anywhere. This mechanism is what lets two different modules each define a function named 'new' or 'process' without colliding, because they live in fully distinct namespaces like 'Foo::Bar::new' versus 'Baz::Qux::new'.

🏏

Cricket analogy: Domestic cricket lets both Mumbai and Delhi field a player literally named 'Sharma' without confusion because each is scoped to their team roster, just as 'package' scopes a sub named 'process' separately under Foo::Bar:: versus Baz::Qux::.

perl

package Utils::Math;

sub add {
    my ($a, $b) = @_;
    return $a + $b;
}

package main;

print Utils::Math::add(2, 3), "\n";   # 5

# A package can also be scoped to a block
{
    package Local::Helper;
    sub greet { return "hi" }
}
print Local::Helper::greet(), "\n";   # hi
# Back in package main here

One File, Multiple Packages (and Vice Versa)

Perl does not enforce a one-package-per-file rule the way Java enforces one-class-per-file: a single .pm file can define several packages, which is common when a small helper class is tightly coupled to a larger one and doesn't warrant its own file. Conversely, a single logical package's implementation can be spread across multiple files that are all loaded via 'require' or 'use', though this is less common and mainly seen in very large frameworks. What matters for module loading is that Perl's '@INC' path-search mechanism maps a package name like 'Utils::Math' to a file path 'Utils/Math.pm' by convention when you write 'use Utils::Math;' — the mapping is purely a filesystem convention, not a language requirement.

🏏

Cricket analogy: A single training manual booklet can cover both the senior squad's drills and the reserve squad's drills in one document, just as one .pm file can define both a main class package and a small tightly-coupled helper package.

The Symbol Table and Fully Qualified Names

Perl exposes each package's symbol table as a hash named '%PackageName::', which is how introspection tools and some metaprogramming tricks work — you can technically inspect '%Utils::Math::' to see what's defined in that namespace. In practice, everyday code rarely touches the symbol table directly; instead you reference symbols with the '::' separator, as in '$Utils::Math::PI' for a package variable or 'Utils::Math::add(2,3)' for a fully-qualified subroutine call, which is useful when you deliberately want to bypass an imported shortcut and be explicit about where a symbol comes from. The double-colon separator is also legal in nested form, so 'MyApp::Model::User' is a perfectly valid single package name representing three levels of logical hierarchy, not three nested packages.

🏏

Cricket analogy: Referring to a player by their full registration ID 'IND-MUM-SharmaR-014' when a scorecard needs zero ambiguity is like writing the fully-qualified 'Utils::Math::add(2,3)' instead of relying on an imported shortcut.

The special variable '$Utils::Math::PI' and 'our $PI;' declared inside 'package Utils::Math;' refer to the exact same package variable — 'our' just gives you a lexically-scoped shorthand to write '$PI' instead of the fully-qualified name within that package's file.

Namespaces and Object-Oriented Perl

Packages are the foundation object-oriented Perl is built on: a 'class' in Perl is just a package whose subroutines are called as methods via the arrow operator, and 'bless'-ing a reference into a package name is what makes 'ref($obj)' report that package as the object's class. This is why inheritance in classic Perl OO is implemented through the '@ISA' array — 'our @ISA = ('Animal');' inside 'package Dog;' tells Perl's method resolution order to search the Animal package's symbol table when a method isn't found directly in Dog. Modern code typically uses a framework like Moose, Moo, or the built-in 'use feature "class"' (Perl 5.38+) to manage this, but underneath, every one of those still ultimately relies on packages and blessed references.

🏏

Cricket analogy: A player's central contract with the BCCI ('blessed' into the national team) is what officially makes them eligible to be listed as 'Team India' on a scorecard, just as bless() associates an object reference with a package to establish its class identity.

Multiple inheritance via '@ISA = ("A", "B");' resolves methods depth-first left-to-right by default in classic Perl, which can produce surprising results in diamond-shaped hierarchies; 'use mro "c3";' switches to the more predictable C3 linearization algorithm used by Python and modern OO frameworks.

'package' changes which symbol table subsequent declarations attach to; it does not create files or scopes by itself.
The default package is 'main'; every bare sub or variable belongs to main:: unless a package statement says otherwise.
A single .pm file may define multiple packages, and Perl's @INC file mapping is a filesystem convention, not a language rule.
'::' separates namespace levels; 'MyApp::Model::User' is one package name, not three nested ones.
Fully-qualified names like Utils::Math::add() let you bypass imports and be explicit about a symbol's origin.
Object-oriented Perl is built on packages: bless() ties an object reference to a package (its class).
Inheritance in classic Perl OO uses the @ISA array to control method resolution order across packages.