bless#

Mark the thing a reference points at as an object in a package.

bless associates the referent of REF with the package named by CLASSNAME, so that method calls through REF dispatch against that package’s subroutines (and its @ISA ancestors). The reference itself does not change; what changes is the referent’s class tag. bless returns REF, which is why it is almost always the last statement in a constructor.

Synopsis#

bless REF, CLASSNAME
bless REF

What you get back#

The same reference that was passed in as the first argument, now carrying the class tag of CLASSNAME. Returning the reference lets you tail-call bless from a constructor:

sub new {
    my ($class, %args) = @_;
    return bless { %args }, $class;
}

From that point on, ref on the returned reference yields the class name rather than the raw reference type (HASH, ARRAY, CODE, …).

Forms#

Two calling forms, one strongly preferred:

Two-argument — always use this.
```
bless $ref, $class;
```
The referent becomes an object in the package named by $class. Using the first argument of the constructor ($_[0], conventionally $class) keeps the constructor inheritable: a subclass calling Parent::new('Child', ...) gets back an object blessed into Child, not into Parent.
Two-argument with empty string — bless into main.
```
bless $ref, "";
```
An empty CLASSNAME is treated as the main package. Rarely useful outside of deliberate tricks.
One-argument — discouraged.
```
bless $ref;
```
The referent is blessed into the current package (the package the bless call is compiled in). This breaks inheritance: a subclass that inherits a one-argument bless constructor still ends up with objects in the parent’s package, not the caller’s. Use the two-argument form unless you have a concrete reason not to, and document the reason.

Examples#

A minimal hash-based class:

package Point;

sub new {
    my ($class, $x, $y) = @_;
    return bless { x => $x, y => $y }, $class;
}

sub x { $_[0]->{x} }
sub y { $_[0]->{y} }

package main;

my $p = Point->new(3, 4);
print ref $p, "\n";       # Point
print $p->x, ",", $p->y;  # 3,4

Inheritable constructor — the same new works for a subclass without modification:

package Shape;
sub new {
    my ($class, %args) = @_;
    return bless { %args }, $class;
}

package Circle;
our @ISA = ('Shape');
sub area {
    my $self = shift;
    return 3.14159 * $self->{radius} ** 2;
}

package main;
my $c = Circle->new(radius => 5);
print ref $c, "\n";       # Circle
print $c->area, "\n";     # 78.53975

Array-based objects work the same way — any reference type can be blessed:

package Pair;
sub new {
    my ($class, $a, $b) = @_;
    return bless [$a, $b], $class;
}
sub first  { $_[0]->[0] }
sub second { $_[0]->[1] }

my $p = Pair->new("left", "right");
print $p->first, "/", $p->second;   # left/right

Re-blessing an existing object changes its class tag in place:

my $obj = bless {}, 'OldClass';
bless $obj, 'NewClass';
print ref $obj;            # NewClass

bless returns the reference, which is why chaining into method calls on the same line works:

Logger->new(file => $path)->info("started");
#                              ^ called on the blessed ref

Edge cases#

The reference is what gets tagged, not the variable. Copies of the reference share the class tag because they all point to the same referent:
```
my $a = bless {}, 'Foo';
my $b = $a;
print ref $b;            # Foo
```
Re-blessing is permitted and immediate. A reference can be blessed as many times as you like; each call overwrites the previous class tag. There is no “unbless” built-in — rebless into a neutral package if you need to strip objecthood from a referent you still hold references to.
CLASSNAME of "" means main. Explicit and rarely wanted; usually a sign that a computed class name came out empty by accident.
Avoid bless $ref, "0". The class name "0" is a false value, so code that checks if (ref $obj) { ... } will misread the object as “not a reference”. Pick any non-false class name.
Class-name casing convention. Use mixed-case (My::Package). ALL-CAPS names are reserved for Perl built-in types (SCALAR, ARRAY, HASH, CODE, …) and all-lowercase names are reserved for pragmas (strict, warnings, utf8). Blessing into either namespace invites confusion with language-level machinery.
Non-reference first argument is a fatal error. bless 42, 'Foo' dies with Can't bless non-reference value. The first argument must be a reference.
One-argument bless picks the compile-time package. It uses the package the bless call is lexically inside — not the caller’s package, not the package of $class. That is exactly why it breaks inheritance and why the two-argument form exists.
Weak references and blessing interact as expected. Scalar::Util::weaken on a blessed reference does not unbless it; the weakened slot still sees the class tag, and ref works until the referent is destroyed.
DESTROY fires on the blessed referent. When the last reference to a blessed referent goes away, Perl calls DESTROY in the reference’s class (following @ISA). Changing the class with a late bless changes which DESTROY runs.

Differences from upstream#

Fully compatible with upstream Perl 5.42.