local-lib5/man/man3/Moose::Meta::Role.3pm

   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.