Moose::Role(3)

💖 Moose::Role(3) 💖

okay so bestie, welcome to Moose::Role — The Moose Role ✨ and yeah, this lives in the User Contributed Perl Documentation section of your man pages, section 3, the way it's always been. 🫶

🌸 VERSION 🌸

version 2.4000 — she's at 2.4000, no cap. 💅

---

✨ SYNOPSIS ✨

here's the whole vibe in code, bestie, verbatim:

  package Eq;
  use Moose::Role; # automatically turns on strict and warnings

  requires 'equal';

  sub no_equal {
      my ($self, $other) = @_;
      !$self->equal($other);
  }

  # ... then in your classes

  package Currency;
  use Moose; # automatically turns on strict and warnings

  with 'Eq';

  sub equal {
      my ($self, $other) = @_;
      $self->as_float == $other->as_float;
  }

  # ... and also

  package Comparator;
  use Moose;

  has compare_to => (
      is      => 'ro',
      does    => 'Eq',
      handles => 'Eq',
  );

  # ... which allows

  my $currency1 = Currency->new(...);
  my $currency2 = Currency->new(...);
  Comparator->new(compare_to => $currency1)->equal($currency2);

look at her go 😭 she's serving exactly what the docs serve. no edits, no notes. 💯

---

🌈 DESCRIPTION 🌈

okay so the concept of roles? that whole storyline is documented over in Moose::Manual::Roles — go read that for the lore 💖. THIS doc? this one is the API documentation. it's the reference sheet, the receipts, the technical tea. 🍓

---

🎀 EXPORTED FUNCTIONS 🎀

so rn Moose::Role supports literally all the functions that Moose exports ✨ — but it handles a couple of them slightly differently, so peek at "CAVEATS" down below for the details, bestie, don't skip it. 👀

and ALSO, Moose::Role offers two extra role-specific keyword exports, her little signature moves: 💅

🦋 requires (@method_names) 🦋

roles can require that certain methods get implemented by any class that "does" the role. it's giving "you can sit with us, but you gotta bring this." 👑

and ngl, heads up: attribute accessors also count as methods for the purposes of satisfying the requirements of a role. so don't come for her about accessors, they count. 🫶

🦋 excludes (@role_names) 🦋

roles can "exclude" other roles — which is basically her saying "I can never be combined with these @role_names". periodt. 🚫

this is a feature which should not be used lightly. like, she means it. use with caution, bestie, this is not a casual thing. 💀

🦋 no Moose::Role 🦋

and when you're done? she offers a way to remove all the keywords she exported, through the unimport method. you literally just say no Moose::Role at the bottom of your code and it works. clean exit, no messy goodbye. ✨

---

👑 METACLASS 👑

when you use Moose::Role, you can specify traits that get applied to your role metaclass, like this:

    use Moose::Role -traits => 'My::Trait';

this is very similar to the attribute traits feature, fr fr. when you do this, your class's meta object will have those specified traits applied to it. want more on that? see "Metaclass and Trait Name Resolution" in Moose for the full breakdown. 📚

also, important: all role metaclasses (note — not the role itself, bestie, the metaclass) extend Moose::Meta::Role. and if you ever need to test whether a package is a role or not, you use is_role in Moose::Util. vibe check complete. ✅

---

🌟 APPLYING ROLES 🌟

okay so besides getting applied to a class with the 'with' syntax (see Moose::Manual::Roles) and using the Moose::Util 'apply_all_roles' method — roles can ALSO be applied to an instance of a class, using Moose::Util 'apply_all_roles' or the role's metaclass, like:

   MyApp::Test::SomeRole->meta->apply( $instance );

doing this creates a new, mutable, anonymous subclass, applies the role to that, and reblesses. 😳 so in a debugger, for example, you'll see class names of the form Moose::Meta::Class::__ANON__::SERIAL::6, which means that doing a 'ref' on your instance may not return what you expect. she's mysterious like that. 🙈 see Moose::Object for 'DOES'.

and you can add additional params to the new instance by providing 'rebless_params'. see Moose::Meta::Role::Application::ToInstance for that whole situation. 🫶

---

💀 CAVEATS 💀

role support has only a few caveats, and honestly she's pretty chill about them:

• roles cannot use the extends keyword — it will throw an exception for now. 😭 the same is true of the augment and inner keywords (not sure those really make sense for roles anyway, ngl). but all other Moose keywords will be deferred so that they can be applied to the consuming class. so like, they wait their turn. patient icons. ⭐
• role composition does its best to not be order-sensitive when it comes to conflict resolution and requirements detection. however — and this is the plot twist 😳 — it IS order-sensitive when it comes to method modifiers. all before/around/after modifiers are included whenever a role is composed into a class, and then applied in the order in which the roles are used. this also means that there is no conflict for before/around/after modifiers. so no drama there, at least. 💅

in most cases this will be a non-issue; however, it is something to keep in mind when using method modifiers in a role.

you should never assume any ordering. never. ever. do not do it, bestie. 🚨

---

🐛 BUGS 🐛

see "BUGS" in Moose for all the details on reporting bugs, okay? if you found one, go tell them, they wanna know. 🫶

---

💜 AUTHORS 💜

the literal icons who made this happen, in order: 👑

• 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>

---

🌈 COPYRIGHT AND LICENSE 🌈

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

and it's free software, bestie — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. iconic behavior, honestly. 🎀

---

and that's the whole page!! 💖 written by the Perl docs girlies, delivered to you by perl v5.42.0 on 2025-07-25 🦋 mwah, go write some roles, you're gonna slay ✨💅