1Role::Hooks(3) User Contributed Perl Documentation Role::Hooks(3)
2
6 Role::Hooks - role callbacks
7
9 package Local::Role {
10 use Moo::Role;
11 use Role::Hooks;
12 Role::Hooks->after_apply(__PACKAGE__, sub {
14 my ($role, $target) = @_;
15 print "$role has been applied to $target.\n";
16 });
17 }
18 package Local::Class {
20 use Moo;
21 with "Local::Role"; # prints above message
22 }
23
25 This module allows a role to run a callback when it is applied to a
26 class or to another role.
27 Compatibility
29 It should work with Role::Tiny, Moo::Role, Moose::Role, Mouse::Role,
30 Role::Basic, and Mite. Not all class builders work well with all role
31 builders (for example, a Moose class consuming a Mouse role). But when
32 they do work together, Role::Hooks should be able to run the callbacks.
33 (The only combination I've tested is Moo with Moose though.)
34 Some other role implementations (such as Moos::Role, exact::role, and
36 OX::Role) are just wrappers around one of the supported role builders,
37 so should mostly work.
38 With Role::Basic, the "after_apply" hook is called a little earlier
40 than would be ideal; after the role has been fully loaded and its
41 methods have been copied into the target package, but before handling
42 "requires", and before patching the "DOES" method in the target
43 package. If you are using Role::Basic, consider switching to
44 Role::Tiny.
45 With Mite, the "before_apply" hook is called fairly late; after the
47 role is fully loaded and attributes and methods have been copied into
48 the target package, after "DOES" has been patched, but before method
49 modifiers from the role have been applied to the target package.
50 Apart from Role::Tiny/Moo::Role, a hashref of additional arguments
52 (things like "-excludes" and "-alias") can be passed when consuming a
53 role. Although I discourage people from using these in general, if you
54 need access to these arguments in the callback, you can check
55 %Role::Hooks::ARGS.
56 Roles generated via Package::Variant should work; see
58 t/20packagevariant.t for a demonstration.
59 Methods
61 "before_apply"
62 Role::Hooks->before_apply($rolename, $callback);
63 Sets up a callback for a role that will be called before the role
65 is applied to a target package. The callback will be passed two
66 parameters: the role being applied and the target package.
67 The role being applied may not be the same role as the role the
69 callback was defined in!
70 package Local::Role1 {
72 use Moo::Role;
73 use Role::Hooks;
74 Role::Hooks->before_apply(__PACKAGE__, sub {
75 my ($role, $target) = @_;
76 print "$role has been applied to $target.\n";
77 });
78 }
79 package Local::Role2 {
81 use Moo::Role;
82 with "Local::Role1";
83 }
84 package Local::Class1 {
86 use Moo::Role;
87 with "Local::Role2";
88 }
89 This will print:
91 Local::Role1 has been applied to Local::Role2.
93 Local::Role2 has been applied to Local::Class1.
94 If you only care about direct applications of roles (i.e. the first
96 one):
97 Role::Hooks->before_apply(__PACKAGE__, sub {
99 my ($role, $target) = @_;
100 return if $role ne __PACKAGE__;
101 print "$role has been applied to $target.\n";
102 });
103 If you only care about roles being applied to classes (i.e. the
105 second one):
106 Role::Hooks->before_apply(__PACKAGE__, sub {
108 my ($role, $target) = @_;
109 return if Role::Hooks->is_role($target);
110 print "$role has been applied to $target.\n";
111 });
112 "after_apply"
114 Role::Hooks->after_apply($rolename, $callback);
115 The same as "before_apply", but called later in the role
117 application process.
118 Note that when the callback is called, even though it's after the
120 role has been applied to the target, it doesn't mean the target has
121 finished being built. For example, there might be "has" statements
122 after the "with" statement, and those will not have been evaluated
123 yet.
124 If you want to throw an error when someone applies your role to an
126 inappropriate target, it is probably better to do that in
127 "before_apply" if you can.
128 "after_inflate"
130 Role::Hooks->after_inflate($pkg_name, $callback);
131 Even though this is part of Role::Hooks, it works on classes too.
133 But it only works on classes and roles built using Moo. This runs
134 your callback if your Moo class or role gets "inflated" to a Moose
135 class or role.
136 If you set up a callback for a role, then the callback will also
138 get called if any packages that role was applied to get inflated.
139 "is_role"
141 Will return true if the given package seems to be a role, false
142 otherwise.
143 (In fact, returns a string representing which role builder the role
145 seems to be using -- "Role::Tiny", "Moose::Role", "Mouse::Role",
146 "Role::Basic", or "Mite::Role"; roles built using Moo::Role are
147 detected as "Role::Tiny".)
148
150 The environment variable "PERL_ROLE_HOOKS_DEBUG" may be set to true to
151 enable debugging messages.
152
154 Please report any bugs to
155 <http://rt.cpan.org/Dist/Display.html?Queue=Role-Hooks>.
156
158 Role::Tiny, Moose::Role.
159
161 Toby Inkster <tobyink@cpan.org>.
162
164 This software is copyright (c) 2020-2022 by Toby Inkster.
165 This is free software; you can redistribute it and/or modify it under
167 the same terms as the Perl 5 programming language system itself.
168
170 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
171 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
172 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
173perl v5.36.0 2023-01-20 Role::Hooks(3)