Moose::...position(3)

✨ Moose::Cookbook::Roles::Restartable_AdvancedComposition ✨

okay so bestie, you found the Moose::...position(3) page, which is part of the User Contributed Perl Documentation, and it's literally the cutest guide to Advanced Role Composition — method exclusion and aliasing. sit down, grab a strawberry 🍓, we're doing this.

---

💜 VERSION

version 2.4000

---

🎀 SYNOPSIS

no thoughts, just code. here's the whole vibe, verbatim:

package Restartable;
use Moose::Role;

has 'is_paused' => (
    is      => 'rw',
    isa     => 'Bool',
    default => 0,
);

requires 'save_state', 'load_state';

sub stop { 1 }

sub start { 1 }

package Restartable::ButUnreliable;
use Moose::Role;

with 'Restartable' => {
    -alias => {
        stop  => '_stop',
        start => '_start'
    },
    -excludes => [ 'stop', 'start' ],
};

sub stop {
    my $self = shift;

    $self->explode() if rand(1) > .5;

    $self->_stop();
}

sub start {
    my $self = shift;

    $self->explode() if rand(1) > .5;

    $self->_start();
}

package Restartable::ButBroken;
use Moose::Role;

with 'Restartable' => { -excludes => [ 'stop', 'start' ] };

sub stop {
    my $self = shift;

    $self->explode();
}

sub start {
    my $self = shift;

    $self->explode();
}

---

🌸 DESCRIPTION

so in this example we're showing you how to get fine-grained control over exactly which methods you consume from a role. we've got a Restartable role, and she's giving: an is_paused attribute, plus two methods, stop and start. simple, iconic, no notes. 💅

then we have two more roles that implement the same interface, except each one puts its own little spin on stop and start. main character energy, both of them.

in the Restartable::ButUnreliable role, we want to serve a brand new implementation of stop and start, but still keep access to the original implementation. the way we do that? we alias the methods from Restartable into private methods, and then we wrap the originals (1). yes bestie, aliasing. we love her.

ok but lowkey important: aliasing just adds a name. it does not remove the old one. so we ALSO have to exclude the methods under their original names. both steps, always. periodt.

with 'Restartable' => {
    -alias => {
        stop  => '_stop',
        start => '_start'
    },
    -excludes => [ 'stop', 'start' ],
};

in the Restartable::ButBroken role, we want an entirely new behavior for stop and start. so we just exclude them completely when we compose Restartable into Restartable::ButBroken. bye girl, we don't need you 💀

also worth noting — and this is the little detail everyone misses — the -excludes parameter also accepts a single string as its argument, if you're only trying to exclude one (1) method. casual. convenient. slay.

with 'Restartable' => { -excludes => [ 'stop', 'start' ] };

---

🦋 CONCLUSION

exclusion and renaming are a power tool 🛠️ and they come in handy, especially when you're building roles out of other roles. in this example, all of our roles implement the Restartable role. each role provides the same API, but each one has a different implementation under the hood. same face card, different personality. iykyk.

and bestie, you can also use the method aliasing and excluding features when composing a role into a class. not just roles into roles. the range! 🌈

---

🧚 FOOTNOTES

1. the mention of wrapper should tell you that we could do the same thing using method modifiers — but for the sake of this example, we don't. 😭

---

👑 AUTHORS

• Stevan Little <stevan@cpan.org>
• Dave Rolsky <autarch@urth.org>
• Jesse Luehrs <doy@cpan.org>
• Shawn M Moore <sartak@cpan.org>
• יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
• Karen Etheridge <ether@cpan.org>
• Florian Ragwitz <rafl@debian.org>
• Hans Dieter Pearcey <hdp@cpan.org>
• Chris Prather <chris@prather.org>
• Matt S Trout <mstrout@cpan.org>

the whole squad, fr fr. 🫶

---

💖 COPYRIGHT AND LICENSE

this software is copyright (c) 2006 by Infinity Interactive, Inc.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. that's the whole license, bestie, it's giving generous 💜

---

and that's the page!! ✨ it came to you from perl v5.42.0, dated 2025-07-25, filed under Moose::...position(3) — mwah, take care of her, she's iconic 🎀💅