Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "Moose::Meta::Role 3" |
132 | .TH Moose::Meta::Role 3 "2009-11-19" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Moose::Meta::Role \- The Moose Role metaclass |
135 | .SH "DESCRIPTION" |
136 | .IX Header "DESCRIPTION" |
137 | This class is a subclass of Class::MOP::Module that provides |
138 | additional Moose-specific functionality. |
139 | .PP |
140 | It's \s-1API\s0 looks a lot like Moose::Meta::Class, but internally it |
141 | implements many things differently. This may change in the future. |
142 | .SH "INHERITANCE" |
143 | .IX Header "INHERITANCE" |
144 | \&\f(CW\*(C`Moose::Meta::Role\*(C'\fR is a subclass of Class::MOP::Module. |
145 | .SH "METHODS" |
146 | .IX Header "METHODS" |
147 | .Sh "Construction" |
148 | .IX Subsection "Construction" |
149 | .IP "\fBMoose::Meta::Role\->initialize($role_name)\fR" 4 |
150 | .IX Item "Moose::Meta::Role->initialize($role_name)" |
151 | This method creates a new role object with the provided name. |
152 | .ie n .IP "\fBMoose::Meta::Role\->combine( [ \fB$role\fB => { ... } ], [ \f(BI$role\fB ], ... )\fR" 4 |
153 | .el .IP "\fBMoose::Meta::Role\->combine( [ \f(CB$role\fB => { ... } ], [ \f(CB$role\fB ], ... )\fR" 4 |
154 | .IX Item "Moose::Meta::Role->combine( [ $role => { ... } ], [ $role ], ... )" |
155 | This method accepts a list of array references. Each array reference |
156 | should contain a role name as its first element. The second element is |
157 | an optional hash reference. The hash reference can contain \f(CW\*(C`\-excludes\*(C'\fR |
158 | and \f(CW\*(C`\-alias\*(C'\fR keys to control how methods are composed from the role. |
159 | .Sp |
160 | The return value is a new Moose::Meta::Role::Composite that |
161 | represents the combined roles. |
162 | .ie n .IP "\fBMoose::Meta::Role\->create($name, \fB%options\fB)\fR" 4 |
163 | .el .IP "\fBMoose::Meta::Role\->create($name, \f(CB%options\fB)\fR" 4 |
164 | .IX Item "Moose::Meta::Role->create($name, %options)" |
165 | This method is identical to the Moose::Meta::Class \f(CW\*(C`create\*(C'\fR |
166 | method. |
167 | .IP "\fBMoose::Meta::Role\->create_anon_role\fR" 4 |
168 | .IX Item "Moose::Meta::Role->create_anon_role" |
169 | This method is identical to the Moose::Meta::Class |
170 | \&\f(CW\*(C`create_anon_class\*(C'\fR method. |
171 | .IP "\fB$metarole\->is_anon_role\fR" 4 |
172 | .IX Item "$metarole->is_anon_role" |
173 | Returns true if the role is an anonymous role. |
174 | .Sh "Role application" |
175 | .IX Subsection "Role application" |
176 | .ie n .IP "\fB$metarole\->apply( \fB$thing\fB, \f(BI@options\fB )\fR" 4 |
177 | .el .IP "\fB$metarole\->apply( \f(CB$thing\fB, \f(CB@options\fB )\fR" 4 |
178 | .IX Item "$metarole->apply( $thing, @options )" |
179 | This method applies a role to the given \f(CW$thing\fR. That can be another |
180 | Moose::Meta::Role, object, a Moose::Meta::Class object, or a |
181 | (non\-meta) object instance. |
182 | .Sp |
183 | The options are passed directly to the constructor for the appropriate |
184 | Moose::Meta::Role::Application subclass. |
185 | .Sp |
186 | Note that this will apply the role even if the \f(CW$thing\fR in question already |
187 | \&\f(CW\*(C`does\*(C'\fR this role. \*(L"does_role\*(R" in Moose::Util is a convenient wrapper for |
188 | finding out if role application is necessary. |
189 | .Sh "Roles and other roles" |
190 | .IX Subsection "Roles and other roles" |
191 | .IP "\fB$metarole\->get_roles\fR" 4 |
192 | .IX Item "$metarole->get_roles" |
193 | This returns an array reference of roles which this role does. This |
194 | list may include duplicates. |
195 | .IP "\fB$metarole\->calculate_all_roles\fR" 4 |
196 | .IX Item "$metarole->calculate_all_roles" |
197 | This returns a \fIunique\fR list of all roles that this role does, and |
198 | all the roles that its roles do. |
199 | .IP "\fB$metarole\->does_role($role_name)\fR" 4 |
200 | .IX Item "$metarole->does_role($role_name)" |
201 | Given a role \fIname\fR, returns true if this role does the given |
202 | role. |
203 | .IP "\fB$metarole\->add_role($role)\fR" 4 |
204 | .IX Item "$metarole->add_role($role)" |
205 | Given a Moose::Meta::Role object, this adds the role to the list of |
206 | roles that the role does. |
207 | .IP "\fB$metarole\->get_excluded_roles_list\fR" 4 |
208 | .IX Item "$metarole->get_excluded_roles_list" |
209 | Returns a list of role names which this role excludes. |
210 | .IP "\fB$metarole\->excludes_role($role_name)\fR" 4 |
211 | .IX Item "$metarole->excludes_role($role_name)" |
212 | Given a role \fIname\fR, returns true if this role excludes the named |
213 | role. |
214 | .IP "\fB$metarole\->add_excluded_roles(@role_names)\fR" 4 |
215 | .IX Item "$metarole->add_excluded_roles(@role_names)" |
216 | Given one or more role names, adds those roles to the list of excluded |
217 | roles. |
218 | .Sh "Methods" |
219 | .IX Subsection "Methods" |
220 | The methods for dealing with a role's methods are all identical in \s-1API\s0 |
221 | and behavior to the same methods in Class::MOP::Class. |
222 | .IP "\fB$metarole\->method_metaclass\fR" 4 |
223 | .IX Item "$metarole->method_metaclass" |
224 | Returns the method metaclass name for the role. This defaults to |
225 | Moose::Meta::Role::Method. |
226 | .IP "\fB$metarole\->get_method($name)\fR" 4 |
227 | .IX Item "$metarole->get_method($name)" |
228 | .PD 0 |
229 | .IP "\fB$metarole\->has_method($name)\fR" 4 |
230 | .IX Item "$metarole->has_method($name)" |
231 | .ie n .IP "\fB$metarole\->add_method( \fB$name\fB, \f(BI$body\fB )\fR" 4 |
232 | .el .IP "\fB$metarole\->add_method( \f(CB$name\fB, \f(CB$body\fB )\fR" 4 |
233 | .IX Item "$metarole->add_method( $name, $body )" |
234 | .IP "\fB$metarole\->get_method_list\fR" 4 |
235 | .IX Item "$metarole->get_method_list" |
236 | .IP "\fB$metarole\->find_method_by_name($name)\fR" 4 |
237 | .IX Item "$metarole->find_method_by_name($name)" |
238 | .PD |
239 | These methods are all identical to the methods of the same name in |
240 | Class::MOP::Package |
241 | .Sh "Attributes" |
242 | .IX Subsection "Attributes" |
243 | As with methods, the methods for dealing with a role's attribute are |
244 | all identical in \s-1API\s0 and behavior to the same methods in |
245 | Class::MOP::Class. |
246 | .PP |
247 | However, attributes stored in this class are \fInot\fR stored as |
248 | objects. Rather, the attribute definition is stored as a hash |
249 | reference. When a role is composed into a class, this hash reference |
250 | is passed directly to the metaclass's \f(CW\*(C`add_attribute\*(C'\fR method. |
251 | .PP |
252 | This is quite likely to change in the future. |
253 | .IP "\fB$metarole\->get_attribute($attribute_name)\fR" 4 |
254 | .IX Item "$metarole->get_attribute($attribute_name)" |
255 | .PD 0 |
256 | .IP "\fB$metarole\->has_attribute($attribute_name)\fR" 4 |
257 | .IX Item "$metarole->has_attribute($attribute_name)" |
258 | .IP "\fB$metarole\->get_attribute_list\fR" 4 |
259 | .IX Item "$metarole->get_attribute_list" |
260 | .ie n .IP "\fB$metarole\->add_attribute($name, \fB%options\fB)\fR" 4 |
261 | .el .IP "\fB$metarole\->add_attribute($name, \f(CB%options\fB)\fR" 4 |
262 | .IX Item "$metarole->add_attribute($name, %options)" |
263 | .IP "\fB$metarole\->remove_attribute($attribute_name)\fR" 4 |
264 | .IX Item "$metarole->remove_attribute($attribute_name)" |
265 | .PD |
266 | .Sh "Required methods" |
267 | .IX Subsection "Required methods" |
268 | .IP "\fB$metarole\->get_required_method_list\fR" 4 |
269 | .IX Item "$metarole->get_required_method_list" |
270 | Returns the list of methods required by the role. |
271 | .IP "\fB$metarole\->requires_method($name)\fR" 4 |
272 | .IX Item "$metarole->requires_method($name)" |
273 | Returns true if the role requires the named method. |
274 | .IP "\fB$metarole\->add_required_methods(@names)\fR" 4 |
275 | .IX Item "$metarole->add_required_methods(@names)" |
276 | Adds the named methods to the role's list of required methods. |
277 | .IP "\fB$metarole\->remove_required_methods(@names)\fR" 4 |
278 | .IX Item "$metarole->remove_required_methods(@names)" |
279 | Removes the named methods from the role's list of required methods. |
280 | .IP "\fB$metarole\->add_conflicting_method(%params)\fR" 4 |
281 | .IX Item "$metarole->add_conflicting_method(%params)" |
282 | Instantiate the parameters as a Moose::Meta::Role::Method::Conflicting |
283 | object, then add it to the required method list. |
284 | .Sh "Method modifiers" |
285 | .IX Subsection "Method modifiers" |
286 | These methods act like their counterparts in Class::Mop::Class and |
287 | Moose::Meta::Class. |
288 | .PP |
289 | However, method modifiers are simply stored internally, and are not |
290 | applied until the role itself is applied to a class. |
291 | .ie n .IP "\fB$metarole\->add_after_method_modifier($method_name, \fB$method\fB)\fR" 4 |
292 | .el .IP "\fB$metarole\->add_after_method_modifier($method_name, \f(CB$method\fB)\fR" 4 |
293 | .IX Item "$metarole->add_after_method_modifier($method_name, $method)" |
294 | .PD 0 |
295 | .ie n .IP "\fB$metarole\->add_around_method_modifier($method_name, \fB$method\fB)\fR" 4 |
296 | .el .IP "\fB$metarole\->add_around_method_modifier($method_name, \f(CB$method\fB)\fR" 4 |
297 | .IX Item "$metarole->add_around_method_modifier($method_name, $method)" |
298 | .ie n .IP "\fB$metarole\->add_before_method_modifier($method_name, \fB$method\fB)\fR" 4 |
299 | .el .IP "\fB$metarole\->add_before_method_modifier($method_name, \f(CB$method\fB)\fR" 4 |
300 | .IX Item "$metarole->add_before_method_modifier($method_name, $method)" |
301 | .ie n .IP "\fB$metarole\->add_override_method_modifier($method_name, \fB$method\fB)\fR" 4 |
302 | .el .IP "\fB$metarole\->add_override_method_modifier($method_name, \f(CB$method\fB)\fR" 4 |
303 | .IX Item "$metarole->add_override_method_modifier($method_name, $method)" |
304 | .PD |
305 | These methods all add an appropriate modifier to the internal list of |
306 | modifiers. |
307 | .IP "\fB$metarole\->has_after_method_modifiers\fR" 4 |
308 | .IX Item "$metarole->has_after_method_modifiers" |
309 | .PD 0 |
310 | .IP "\fB$metarole\->has_around_method_modifiers\fR" 4 |
311 | .IX Item "$metarole->has_around_method_modifiers" |
312 | .IP "\fB$metarole\->has_before_method_modifiers\fR" 4 |
313 | .IX Item "$metarole->has_before_method_modifiers" |
314 | .IP "\fB$metarole\->has_override_method_modifier\fR" 4 |
315 | .IX Item "$metarole->has_override_method_modifier" |
316 | .PD |
317 | Return true if the role has any modifiers of the given type. |
318 | .IP "\fB$metarole\->get_after_method_modifiers($method_name)\fR" 4 |
319 | .IX Item "$metarole->get_after_method_modifiers($method_name)" |
320 | .PD 0 |
321 | .IP "\fB$metarole\->get_around_method_modifiers($method_name)\fR" 4 |
322 | .IX Item "$metarole->get_around_method_modifiers($method_name)" |
323 | .IP "\fB$metarole\->get_before_method_modifiers($method_name)\fR" 4 |
324 | .IX Item "$metarole->get_before_method_modifiers($method_name)" |
325 | .PD |
326 | Given a method name, returns a list of the appropriate modifiers for |
327 | that method. |
328 | .IP "\fB$metarole\->get_override_method_modifier($method_name)\fR" 4 |
329 | .IX Item "$metarole->get_override_method_modifier($method_name)" |
330 | Given a method name, returns the override method modifier for that |
331 | method, if it has one. |
332 | .Sh "Introspection" |
333 | .IX Subsection "Introspection" |
334 | .IP "\fBMoose::Meta::Role\->meta\fR" 4 |
335 | .IX Item "Moose::Meta::Role->meta" |
336 | This will return a Class::MOP::Class instance for this class. |
337 | .SH "BUGS" |
338 | .IX Header "BUGS" |
339 | All complex software has bugs lurking in it, and this module is no |
340 | exception. If you find a bug please either email me, or add the bug |
341 | to cpan\-RT. |
342 | .SH "AUTHOR" |
343 | .IX Header "AUTHOR" |
344 | Stevan Little <stevan@iinteractive.com> |
345 | .SH "COPYRIGHT AND LICENSE" |
346 | .IX Header "COPYRIGHT AND LICENSE" |
347 | Copyright 2006\-2009 by Infinity Interactive, Inc. |
348 | .PP |
349 | <http://www.iinteractive.com> |
350 | .PP |
351 | This library is free software; you can redistribute it and/or modify |
352 | it under the same terms as Perl itself. |