local-lib5/man/man3/Mouse::Util::MetaRole.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Mouse::Util::MetaRole 3"
 127 .TH Mouse::Util::MetaRole 3 "2009-12-05" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Mouse::Util::MetaRole \- Apply roles to any metaclass, as well as the object base class
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  package MyApp::Mouse;
 138 \&
 139 \&  use Mouse ();
 140 \&  use Mouse::Exporter;
 141 \&  use Mouse::Util::MetaRole;
 142 \&
 143 \&  use MyApp::Role::Meta::Class;
 144 \&  use MyApp::Role::Meta::Method::Constructor;
 145 \&  use MyApp::Role::Object;
 146 \&
 147 \&  Mouse::Exporter\->setup_import_methods( also => \*(AqMouse\*(Aq );
 148 \&
 149 \&  sub init_meta {
 150 \&      shift;
 151 \&      my %options = @_;
 152 \&
 153 \&      Mouse\->init_meta(%options);
 154 \&
 155 \&      Mouse::Util::MetaRole::apply_metaclass_roles(
 156 \&          for_class               => $options{for_class},
 157 \&          metaclass_roles         => [\*(AqMyApp::Role::Meta::Class\*(Aq],
 158 \&          constructor_class_roles => [\*(AqMyApp::Role::Meta::Method::Constructor\*(Aq],
 159 \&      );
 160 \&
 161 \&      Mouse::Util::MetaRole::apply_base_class_roles(
 162 \&          for_class => $options{for_class},
 163 \&          roles     => [\*(AqMyApp::Role::Object\*(Aq],
 164 \&      );
 165 \&
 166 \&      return $options{for_class}\->meta();
 167 \&  }
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 This utility module is designed to help authors of Mouse extensions
 172 write extensions that are able to cooperate with other Mouse
 173 extensions. To do this, you must write your extensions as roles, which
 174 can then be dynamically applied to the caller's metaclasses.
 175 .PP
 176 This module makes sure to preserve any existing superclasses and roles
 177 already set for the meta objects, which means that any number of
 178 extensions can apply roles in any order.
 179 .SH "USAGE"
 180 .IX Header "USAGE"
 181 \&\fBIt is very important that you only call this module's functions when
 182 your module is imported by the caller\fR. The process of applying roles
 183 to the metaclass reinitializes the metaclass object, which wipes out
 184 any existing attributes already defined. However, as long as you do
 185 this when your module is imported, the caller should not have any
 186 attributes defined yet.
 187 .PP
 188 The easiest way to ensure that this happens is to use
 189 Mouse::Exporter, which can generate the appropriate \f(CW\*(C`init_meta\*(C'\fR
 190 method for you, and make sure it is called when imported.
 191 .SH "FUNCTIONS"
 192 .IX Header "FUNCTIONS"
 193 This module provides two functions.
 194 .SS "apply_metaclass_roles( ... )"
 195 .IX Subsection "apply_metaclass_roles( ... )"
 196 This function will apply roles to one or more metaclasses for the
 197 specified class. It accepts the following parameters:
 198 .IP "\(bu" 4
 199 for_class => \f(CW$name\fR
 200 .Sp
 201 This specifies the class for which to alter the meta classes.
 202 .IP "\(bu" 4
 203 metaclass_roles => \e@roles
 204 .IP "\(bu" 4
 205 attribute_metaclass_roles => \e@roles
 206 .IP "\(bu" 4
 207 method_metaclass_roles => \e@roles
 208 .IP "\(bu" 4
 209 constructor_class_roles => \e@roles
 210 .IP "\(bu" 4
 211 destructor_class_roles => \e@roles
 212 .Sp
 213 These parameter all specify one or more roles to be applied to the
 214 specified metaclass. You can pass any or all of these parameters at
 215 once.
 216 .ie n .SS "apply_base_class_roles( for_class => $class, roles => \e@roles )"
 217 .el .SS "apply_base_class_roles( for_class => \f(CW$class\fP, roles => \e@roles )"
 218 .IX Subsection "apply_base_class_roles( for_class => $class, roles => @roles )"
 219 This function will apply the specified roles to the object's base class.
 220 .SH "SEE ALSO"
 221 .IX Header "SEE ALSO"
 222 Moose::Util::MetaRole