1Role::Hooks(3)        User Contributed Perl Documentation       Role::Hooks(3)
2
3
4

NAME

6       Role::Hooks - role callbacks
7

SYNOPSIS

9         package Local::Role {
10           use Moo::Role;
11           use Role::Hooks;
12
13           Role::Hooks->after_apply(__PACKAGE__, sub {
14             my ($role, $target) = @_;
15             print "$role has been applied to $target.\n";
16           });
17         }
18
19         package Local::Class {
20           use Moo;
21           with "Local::Role";   # prints above message
22         }
23

DESCRIPTION

25       This module allows a role to run a callback when it is applied to a
26       class or to another role.
27
28   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
35       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
39       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
46       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
51       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
57       Roles generated via Package::Variant should work; see
58       t/20packagevariant.t for a demonstration.
59
60   Methods
61       "before_apply"
62             Role::Hooks->before_apply($rolename, $callback);
63
64           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
68           The role being applied may not be the same role as the role the
69           callback was defined in!
70
71             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
80             package Local::Role2 {
81               use Moo::Role;
82               with "Local::Role1";
83             }
84
85             package Local::Class1 {
86               use Moo::Role;
87               with "Local::Role2";
88             }
89
90           This will print:
91
92             Local::Role1 has been applied to Local::Role2.
93             Local::Role2 has been applied to Local::Class1.
94
95           If you only care about direct applications of roles (i.e. the first
96           one):
97
98             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
104           If you only care about roles being applied to classes (i.e. the
105           second one):
106
107             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
113       "after_apply"
114             Role::Hooks->after_apply($rolename, $callback);
115
116           The same as "before_apply", but called later in the role
117           application process.
118
119           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
125           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
129       "after_inflate"
130             Role::Hooks->after_inflate($pkg_name, $callback);
131
132           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
137           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
140       "is_role"
141           Will return true if the given package seems to be a role, false
142           otherwise.
143
144           (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

ENVIRONMENT

150       The environment variable "PERL_ROLE_HOOKS_DEBUG" may be set to true to
151       enable debugging messages.
152

BUGS

154       Please report any bugs to
155       <http://rt.cpan.org/Dist/Display.html?Queue=Role-Hooks>.
156

SEE ALSO

158       Role::Tiny, Moose::Role.
159

AUTHOR

161       Toby Inkster <tobyink@cpan.org>.
162
164       This software is copyright (c) 2020-2022 by Toby Inkster.
165
166       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

DISCLAIMER OF WARRANTIES

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.
173
174
175
176perl v5.38.0                      2023-07-21                    Role::Hooks(3)
Impressum