Moose::Util(3)

💖 Moose::Util 💖

okay so bestie, welcome to Moose::Util, from the User Contributed Perl Documentation section of your friendly neighbourhood manpage collection. it's giving "utilities for working with Moose classes" and honestly? it ate. ✨

---

🌸 VERSION 🌸

version 2.4000 — yes that's the one, no cap.

---

🎀 SYNOPSIS 🎀

use Moose::Util qw/find_meta does_role search_class_by_role/;

my $meta = find_meta($object) || die "No metaclass found";

if (does_role($object, $role)) {
  print "The object can do $role!\n";
}

my $class = search_class_by_role($object, 'FooRole');
print "Nearest class with 'FooRole' is $class\n";

like, look at that. so clean. so demure. 💅

---

🦋 DESCRIPTION 🦋

so this module is literally just a little grab-bag of utility functions. a lot of them are lowkey meant for Moose itself or for MooseX modules to use internally, but some of them are genuinely useful in your own code too, so don't sleep on them. 🫶

---

✨ EXPORTED FUNCTIONS ✨

🌟 find_meta($class_or_obj)

you hand it a class name or an object, and it tries to find a metaclass for that class — if one already exists. and that's the tea: it will not create one for you if it doesn't exist yet. it's a finder, not a maker. periodt. 💀

🌟 is_role($package_or_obj)

returns true if the package name or object you passed in is a Moose::Role. that's it. that's the function. iconic. 👑

🌟 does_role($class_or_obj, $role_or_obj)

returns true if $class_or_obj does the given $role_or_obj. you can pass the role as either a name or an actual Moose::Meta::Role object, whichever vibe you're on.

⚠️ heads up bestie: the class must already have a metaclass for this to work. if it doesn't, this function just quietly returns false. no drama, no error, just false. 🍓

🌟 search_class_by_role($class_or_obj, $role_or_obj)

gives you the first class in the class's precedence list that does $role_or_obj, if there even is one. the role can be a name or a Moose::Meta::Role object.

⚠️ same rule as before: the class has to already have a metaclass for this to work. 💅

🌟 apply_all_roles($applicant, @roles)

applies one or more roles to the given $applicant. the applicant can be a role name, a class name, or an object — flexible queen. 🌈

⚠️ the $applicant must already have a metaclass object.

and the @roles list should be a list of names or Moose::Meta::Role objects, and each one of those can be followed by an optional hash reference of options: -excludes and -alias. yeah, they're right there in the list, cute little option hash just vibing after the role.

🌟 ensure_all_roles($applicant, @roles)

basically the same energy as apply_all_roles, except it's picky in a good way: it only applies the roles that $applicant doesn't already consume. no double-applying, we're not doing that today. 💖

🌟 with_traits($class_name, @role_names)

makes you a brand-new class out of $class_name, with every single one of @role_names applied to it. then it hands you back the name of the new class. slay. ✨

🌟 get_all_attribute_values($meta, $instance)

returns a hash reference with all of $instance's attributes in it. the keys are the attribute names. simple, useful, we love her. 🎀

🌟 get_all_init_args($meta, $instance)

returns a hash reference containing all of the "init_arg" values for the instance's attributes, and the values in there are the associated attribute values. if an attribute doesn't have a defined "init_arg", it just gets skipped. no notes.

ngl this one could come in handy if you're cloning an object. 👀

🌟 resolve_metaclass_alias($category, $name, %options)

🌟 resolve_metatrait_alias($category, $name, %options)

these two resolve a short name into a full class name. short names are what you see all the time when you're setting the "metaclass" or "traits" option on an attribute, like:

has foo => (
    metaclass => "Bar",
);

the whole name resolution mechanism is explained over in "Metaclass and Trait Name Resolution" in Moose. go read that if you want the full lore. 📚

🌟 meta_class_alias($to[, $from])

🌟 meta_attribute_alias($to[, $from])

these create an alias from the class $from — or from the current package, if you didn't specify $from — so that "Metaclass and Trait Name Resolution" in Moose actually works the way it's supposed to. iykyk. 🧚

🌟 english_list(@items)

give it a list of scalars and it turns them into a proper list in English — like "one and two", or "one, two, three, and four". it exists purely so our error messages can be nicer to look at. and honestly? we're obsessed. 💅

🌟 throw_exception( $class_name, %arguments_to_exception)

calls die with an object of Moose::Exception::$class_name, and passes %arguments_to_exception along as the arguments. dramatic exits only. 💀✨

---

🌈 TODO 🌈

here's a list of possible functions someone could write someday:

• discovering original method from modified method
• search for origin class of a method or attribute

manifesting these fr fr 🕯️

---

💀 BUGS 💀

for the details on how to report bugs, go check out "BUGS" in Moose. yes really, that's where the info lives.

---

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

look at this lineup. absolute legends, every single one. main character energy across the board. 🌟

---

🎀 COPYRIGHT AND LICENSE 🎀

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

it's free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

---

okay bestie that's the whole page, mwah 🫶 this was Moose::Util, version 2.4000, delivered to you by perl v5.42.0 on 2025-07-25. love that for us. go forth and find some metaclasses. ✨🌸💜