Scoping · Modules · Classes and OO

package

Declare the compile-time namespace for the declarations that follow.

package tells the compiler which symbol table to use when it resolves unqualified names in the code it is about to parse. It does not create a package in any run-time sense — packages spring into existence the first time something is stored in them. What a package statement really does is re-point the compiler: from here on, $foo means $NAMESPACE::foo, &bar means &NAMESPACE::bar, and so on, until the next package statement or the end of the enclosing scope.

Synopsis

package NAME;
package NAME VERSION;
package NAME     { ... }
package NAME VER { ... }

What you get back

package is a compile-time directive, not an expression. It has no useful runtime value — treat it as a statement. Its effect is on the parser: all subsequent unqualified identifiers resolve in NAME’s symbol table until scope ends.

The form with VERSION has one visible side effect: it sets $NAME::VERSION to a version object built from VERSION. This happens exactly once per package NAME VERSION statement, at compile time.

Global state it touches

• The current compile-time package. Every package statement replaces it for the rest of the scope. __PACKAGE__ returns the current value at any point in the source.

• $NAME::VERSION — set when the VERSION argument is provided. Set it only once per package.

• The target symbol table (stash) is created on first use. Nothing is populated by the package statement itself; subsequent declarations (sub, our, assignments to $NAME::foo, etc.) fill it.

The four forms

package NAMESPACE

Switches the compile-time package to NAMESPACE from this point to the end of the current scope (enclosing block, file, or eval). This is the classic “one package per file” form:

package My::Thing;

sub new { ... }         # defines &My::Thing::new
our $count = 0;         # defines $My::Thing::count

1;

package NAMESPACE VERSION

Same scoping as the bare form, plus it sets $NAMESPACE::VERSION to a version object. VERSION must be a strict version literal: either a positive decimal (1.23, 0.001) or a dotted-decimal v-string with a leading v and at least three components (v1.2.3). Exponent notation is not allowed.

package My::Thing 1.042;
package My::Thing v1.2.3;

Set $VERSION only once per package — a second package NAME VERSION statement in the same package overwrites the first, and use Module VERSION consumers see only the final value.

package NAMESPACE BLOCK

Lexically scopes the package switch to BLOCK. Inside the braces the compile-time package is NAMESPACE; outside the closing brace the previous package is restored. This is the only form that reverts automatically.

package Outer;
our $x = 1;             # $Outer::x

package Inner {
    our $y = 2;         # $Inner::y
}

our $z = 3;             # $Outer::z again

package NAMESPACE VERSION BLOCK

The block form with a version literal. Scope reverts at the closing brace; $NAMESPACE::VERSION stays set.

package My::Sub v0.9.1 {
    sub ping { "pong" }
}

What package does and does not scope

package affects dynamic (package) variables and unqualified name resolution. It does not affect lexicals:

• my, state — created in the lexical pad, invisible to package lookup. A package statement does nothing to them.

• local — dynamically scopes a package variable, which still belongs to whatever package its fully-qualified name names.

• our — declares a lexical alias to a package variable in the current compile-time package. This is the mechanism that lets our $count inside package My::Thing alias $My::Thing::count.

Switching packages after an our declaration does not retarget the alias: the alias was bound to the package in effect when our was compiled.

package Foo;
our $x;                 # aliases $Foo::x
package Bar;
$x = 1;                 # still writes $Foo::x

Interaction with use v5.36 and newer

use v5.36 (and any use v5.36 or later) enables strict and warnings implicitly. Once strict is on, unqualified package variables require an our declaration (or full qualification). Combined with a package statement, the idiomatic modern file skeleton is:

package My::Thing 1.00;

use v5.36;              # strict, warnings, say, signatures, ...

our @EXPORT_OK = qw(thingify);

sub thingify { ... }

1;

The package NAME VERSION form and use VERSION are independent: the first sets $My::Thing::VERSION; the second enables language features for the current file.

Special identifiers that always mean main::

A small set of identifiers are forced into the main:: package regardless of the current package:

• STDIN, STDOUT, STDERR, ARGV, ARGVOUT

• @ARGV, @INC, %ENV, %SIG, %INC

• All punctuation variables: $_, $!, $@, @_, etc.

Writing to $! inside package Foo still writes to $main::!. This is by design: these names would be useless if they moved with the package.

Examples

A minimal module file. The file name must match the package name (require translates :: to the directory separator):

# lib/My/Greeter.pm
package My::Greeter 1.00;
use v5.36;

sub new  { my ($cls, %a) = @_; bless { %a }, $cls }
sub greet { my $self = shift; "hello, $self->{name}\n" }

1;

Two packages in one file using the block form. Scope reverts automatically, so the 1; at the bottom belongs to no package in particular — it’s evaluated in whichever package was active at the top of the file (main for a script, the file’s own package for a module):

package My::Thing {
    sub do_stuff { ... }
}

package My::Thing::Helper {
    sub helper { ... }
}

Switching back and forth in the statement form — legal but rarely what you want:

package A;
sub one { 1 }           # &A::one

package B;
sub two { 2 }           # &B::two

package A;
sub three { 3 }         # &A::three

Setting a version and reading it back. Note that $VERSION is a version object, not a plain string; stringify or compare with version:

package Foo 1.23;

say $Foo::VERSION;      # 1.23
say ref $Foo::VERSION;  # version

our inside a package gives you a lexically-scoped alias to a package variable — the canonical way to declare module-level globals under strict:

package Counter;
use v5.36;

our $count = 0;         # aliases $Counter::count
sub bump { $count++ }

Edge cases

• package NAMESPACE VERSION accepts only strict version literals. Exponent notation (1e3), non-numeric strings, and two-component v-strings (v1.2) are compile errors.

• Setting $VERSION twice in the same package (whether by two package NAME VERSION statements or by explicit assignment after a package NAME VERSION) is legal but confusing — use Module VERSION checks the final value, and CPAN tooling reads whichever one it finds first. Declare the version once.

• The block form is a separate lexical scope. my and state variables declared inside a package NAME { ... } are not visible outside, just like any other block.

• package NAMESPACE without a trailing statement or block affects the rest of the file. A package at the top of a script permanently switches the script out of main, which means $main::ARGV[0] is still your argument list but freshly declared globals belong to the new package. This is almost never what a script wants.

• A file that contains only package Foo; and no other code still compiles cleanly and creates the Foo:: stash on first reference — but requireing it returns the value of the last statement, which is the package statement itself (false). Put 1; at the end of every module file.

• Nested block forms restore the immediately enclosing package, not main:

  package Outer;
  package Inner {
      package Innermost {
          # __PACKAGE__ is Innermost
      }
      # __PACKAGE__ is Inner again
  }
  # __PACKAGE__ is Outer again
  

• package inside eval. The package switch is scoped to the eval body. Symbols created during the eval persist in their stashes (stashes are global), but the compile-time package reverts when the eval ends.

• Apostrophe as package separator ($main'sail for $main::sail) is still parsed for compatibility with Perl 4 code but is deprecated. Do not write it; mention it only when reading ancient code.

Differences from upstream

Fully compatible with upstream Perl 5.42.

See also

• use — load a module at compile time and import symbols from its package; typically paired with a package declaration at the top of the loaded file

• require — load a module or file at runtime; the loaded file’s package statement determines which stash its declarations populate

• bless — associate a reference with a package so method calls dispatch to that package’s subs; the glue between package and OO

• my — declare a lexical variable that package does not affect; the counterpart to package globals

• our — declare a lexical alias to a package variable in the current compile-time package; the strict-safe way to use module-level globals

• local — dynamically scope a package variable’s value without changing which package it belongs to