local-lib5/man/man3/Moose::Util::MetaRole.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::Util::MetaRole 3"
 132 .TH Moose::Util::MetaRole 3 "2009-11-19" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Util::MetaRole \- Apply roles to any metaclass, as well as the object base class
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  package MyApp::Moose;
 139 .Ve
 140 .PP
 141 .Vb 3
 142 \&  use Moose ();
 143 \&  use Moose::Exporter;
 144 \&  use Moose::Util::MetaRole;
 145 .Ve
 146 .PP
 147 .Vb 3
 148 \&  use MyApp::Role::Meta::Class;
 149 \&  use MyApp::Role::Meta::Method::Constructor;
 150 \&  use MyApp::Role::Object;
 151 .Ve
 152 .PP
 153 .Vb 1
 154 \&  Moose::Exporter\->setup_import_methods( also => 'Moose' );
 155 .Ve
 156 .PP
 157 .Vb 3
 158 \&  sub init_meta {
 159 \&      shift;
 160 \&      my %options = @_;
 161 .Ve
 162 .PP
 163 .Vb 1
 164 \&      Moose\->init_meta(%options);
 165 .Ve
 166 .PP
 167 .Vb 5
 168 \&      Moose::Util::MetaRole::apply_metaclass_roles(
 169 \&          for_class               => $options{for_class},
 170 \&          metaclass_roles         => ['MyApp::Role::Meta::Class'],
 171 \&          constructor_class_roles => ['MyApp::Role::Meta::Method::Constructor'],
 172 \&      );
 173 .Ve
 174 .PP
 175 .Vb 4
 176 \&      Moose::Util::MetaRole::apply_base_class_roles(
 177 \&          for_class => $options{for_class},
 178 \&          roles     => ['MyApp::Role::Object'],
 179 \&      );
 180 .Ve
 181 .PP
 182 .Vb 2
 183 \&      return $options{for_class}\->meta();
 184 \&  }
 185 .Ve
 186 .SH "DESCRIPTION"
 187 .IX Header "DESCRIPTION"
 188 This utility module is designed to help authors of Moose extensions
 189 write extensions that are able to cooperate with other Moose
 190 extensions. To do this, you must write your extensions as roles, which
 191 can then be dynamically applied to the caller's metaclasses.
 192 .PP
 193 This module makes sure to preserve any existing superclasses and roles
 194 already set for the meta objects, which means that any number of
 195 extensions can apply roles in any order.
 196 .SH "USAGE"
 197 .IX Header "USAGE"
 198 \&\fBIt is very important that you only call this module's functions when
 199 your module is imported by the caller\fR. The process of applying roles
 200 to the metaclass reinitializes the metaclass object, which wipes out
 201 any existing attributes already defined. However, as long as you do
 202 this when your module is imported, the caller should not have any
 203 attributes defined yet.
 204 .PP
 205 The easiest way to ensure that this happens is to use
 206 Moose::Exporter, which can generate the appropriate \f(CW\*(C`init_meta\*(C'\fR
 207 method for you, and make sure it is called when imported.
 208 .SH "FUNCTIONS"
 209 .IX Header "FUNCTIONS"
 210 This module provides two functions.
 211 .Sh "apply_metaclass_roles( ... )"
 212 .IX Subsection "apply_metaclass_roles( ... )"
 213 This function will apply roles to one or more metaclasses for the
 214 specified class. It accepts the following parameters:
 215 .ie n .IP "* for_class => $name" 4
 216 .el .IP "* for_class => \f(CW$name\fR" 4
 217 .IX Item "for_class => $name"
 218 This specifies the class for which to alter the meta classes.
 219 .IP "* metaclass_roles => \e@roles" 4
 220 .IX Item "metaclass_roles => @roles"
 221 .PD 0
 222 .IP "* attribute_metaclass_roles => \e@roles" 4
 223 .IX Item "attribute_metaclass_roles => @roles"
 224 .IP "* method_metaclass_roles => \e@roles" 4
 225 .IX Item "method_metaclass_roles => @roles"
 226 .IP "* wrapped_method_metaclass_roles => \e@roles" 4
 227 .IX Item "wrapped_method_metaclass_roles => @roles"
 228 .IP "* instance_metaclass_roles => \e@roles" 4
 229 .IX Item "instance_metaclass_roles => @roles"
 230 .IP "* constructor_class_roles => \e@roles" 4
 231 .IX Item "constructor_class_roles => @roles"
 232 .IP "* destructor_class_roles => \e@roles" 4
 233 .IX Item "destructor_class_roles => @roles"
 234 .IP "* application_to_class_class_roles => \e@roles" 4
 235 .IX Item "application_to_class_class_roles => @roles"
 236 .IP "* application_to_role_class_roles => \e@roles" 4
 237 .IX Item "application_to_role_class_roles => @roles"
 238 .IP "* application_to_instance_class_roles => \e@roles" 4
 239 .IX Item "application_to_instance_class_roles => @roles"
 240 .PD
 241 These parameter all specify one or more roles to be applied to the
 242 specified metaclass. You can pass any or all of these parameters at
 243 once.
 244 .ie n .Sh "apply_base_class_roles( for_class => $class, roles => \e@roles )"
 245 .el .Sh "apply_base_class_roles( for_class => \f(CW$class\fP, roles => \e@roles )"
 246 .IX Subsection "apply_base_class_roles( for_class => $class, roles => @roles )"
 247 This function will apply the specified roles to the object's base class.
 248 .SH "AUTHOR"
 249 .IX Header "AUTHOR"
 250 Dave Rolsky <autarch@urth.org>
 251 .SH "COPYRIGHT AND LICENSE"
 252 .IX Header "COPYRIGHT AND LICENSE"
 253 Copyright 2009 by Infinity Interactive, Inc.
 254 .PP
 255 <http://www.iinteractive.com>
 256 .PP
 257 This library is free software; you can redistribute it and/or modify
 258 it under the same terms as Perl itself.