local-lib5/man/man3/Class::MOP::Class.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 "Class::MOP::Class 3"
 132 .TH Class::MOP::Class 3 "2009-11-18" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Class::MOP::Class \- Class Meta Object
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  # assuming that class Foo
 139 \&  # has been defined, you can
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&  # use this for introspection ...
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  # add a method to Foo ...
 148 \&  Foo\->meta\->add_method( 'bar' => sub {...} )
 149 .Ve
 150 .PP
 151 .Vb 3
 152 \&  # get a list of all the classes searched
 153 \&  # the method dispatcher in the correct order
 154 \&  Foo\->meta\->class_precedence_list()
 155 .Ve
 156 .PP
 157 .Vb 2
 158 \&  # remove a method from Foo
 159 \&  Foo\->meta\->remove_method('bar');
 160 .Ve
 161 .PP
 162 .Vb 1
 163 \&  # or use this to actually create classes ...
 164 .Ve
 165 .PP
 166 .Vb 14
 167 \&  Class::MOP::Class\->create(
 168 \&      'Bar' => (
 169 \&          version      => '0.01',
 170 \&          superclasses => ['Foo'],
 171 \&          attributes   => [
 172 \&              Class::MOP::Attribute\->new('$bar'),
 173 \&              Class::MOP::Attribute\->new('$baz'),
 174 \&          ],
 175 \&          methods => {
 176 \&              calculate_bar => sub {...},
 177 \&              construct_baz => sub {...}
 178 \&          }
 179 \&      )
 180 \&  );
 181 .Ve
 182 .SH "DESCRIPTION"
 183 .IX Header "DESCRIPTION"
 184 The Class Protocol is the largest and most complex part of the
 185 Class::MOP meta-object protocol. It controls the introspection and
 186 manipulation of Perl 5 classes, and it can create them as well. The
 187 best way to understand what this module can do is to read the
 188 documentation for each of its methods.
 189 .SH "INHERITANCE"
 190 .IX Header "INHERITANCE"
 191 \&\f(CW\*(C`Class::MOP::Class\*(C'\fR is a subclass of Class::MOP::Module.
 192 .SH "METHODS"
 193 .IX Header "METHODS"
 194 .Sh "Class construction"
 195 .IX Subsection "Class construction"
 196 These methods all create new \f(CW\*(C`Class::MOP::Class\*(C'\fR objects. These
 197 objects can represent existing classes or they can be used to create
 198 new classes from scratch.
 199 .PP
 200 The metaclass object for a given class is a singleton. If you attempt
 201 to create a metaclass for the same class twice, you will just get the
 202 existing object.
 203 .ie n .IP "\fBClass::MOP::Class\->create($package_name, \fB%options\fB)\fR" 4
 204 .el .IP "\fBClass::MOP::Class\->create($package_name, \f(CB%options\fB)\fR" 4
 205 .IX Item "Class::MOP::Class->create($package_name, %options)"
 206 This method creates a new \f(CW\*(C`Class::MOP::Class\*(C'\fR object with the given
 207 package name. It accepts a number of options:
 208 .RS 4
 209 .IP "* version" 8
 210 .IX Item "version"
 211 An optional version number for the newly created package.
 212 .IP "* authority" 8
 213 .IX Item "authority"
 214 An optional authority for the newly created package.
 215 .IP "* superclasses" 8
 216 .IX Item "superclasses"
 217 An optional array reference of superclass names.
 218 .IP "* methods" 8
 219 .IX Item "methods"
 220 An optional hash reference of methods for the class. The keys of the
 221 hash reference are method names and values are subroutine references.
 222 .IP "* attributes" 8
 223 .IX Item "attributes"
 224 An optional array reference of Class::MOP::Attribute objects.
 225 .RE
 226 .RS 4
 227 .RE
 228 .IP "\fBClass::MOP::Class\->create_anon_class(%options)\fR" 4
 229 .IX Item "Class::MOP::Class->create_anon_class(%options)"
 230 This method works just like \f(CW\*(C`Class::MOP::Class\->create\*(C'\fR but it
 231 creates an \*(L"anonymous\*(R" class. In fact, the class does have a name, but
 232 that name is a unique name generated internally by this module.
 233 .Sp
 234 It accepts the same \f(CW\*(C`superclasses\*(C'\fR, \f(CW\*(C`methods\*(C'\fR, and \f(CW\*(C`attributes\*(C'\fR
 235 parameters that \f(CW\*(C`create\*(C'\fR accepts.
 236 .Sp
 237 Anonymous classes are destroyed once the metaclass they are attached
 238 to goes out of scope, and will be removed from Perl's internal symbol
 239 table.
 240 .Sp
 241 All instances of an anonymous class keep a special reference to the
 242 metaclass object, which prevents the metaclass from going out of scope
 243 while any instances exist.
 244 .Sp
 245 This only works if the instance is based on a hash reference, however.
 246 .ie n .IP "\fBClass::MOP::Class\->initialize($package_name, \fB%options\fB)\fR" 4
 247 .el .IP "\fBClass::MOP::Class\->initialize($package_name, \f(CB%options\fB)\fR" 4
 248 .IX Item "Class::MOP::Class->initialize($package_name, %options)"
 249 This method will initialize a \f(CW\*(C`Class::MOP::Class\*(C'\fR object for the
 250 named package. Unlike \f(CW\*(C`create\*(C'\fR, this method \fIwill not\fR create a new
 251 class.
 252 .Sp
 253 The purpose of this method is to retrieve a \f(CW\*(C`Class::MOP::Class\*(C'\fR
 254 object for introspecting an existing class.
 255 .Sp
 256 If an existing \f(CW\*(C`Class::MOP::Class\*(C'\fR object exists for the named
 257 package, it will be returned, and any options provided will be
 258 ignored!
 259 .Sp
 260 If the object does not yet exist, it will be created.
 261 .Sp
 262 The valid options that can be passed to this method are
 263 \&\f(CW\*(C`attribute_metaclass\*(C'\fR, \f(CW\*(C`method_metaclass\*(C'\fR,
 264 \&\f(CW\*(C`wrapped_method_metaclass\*(C'\fR, and \f(CW\*(C`instance_metaclass\*(C'\fR. These are all
 265 optional, and default to the appropriate class in the \f(CW\*(C`Class::MOP\*(C'\fR
 266 distribution.
 267 .Sh "Object instance construction and cloning"
 268 .IX Subsection "Object instance construction and cloning"
 269 These methods are all related to creating and/or cloning object
 270 instances.
 271 .ie n .IP "\fB$metaclass\->clone_object($instance, \fB%params\fB)\fR" 4
 272 .el .IP "\fB$metaclass\->clone_object($instance, \f(CB%params\fB)\fR" 4
 273 .IX Item "$metaclass->clone_object($instance, %params)"
 274 This method clones an existing object instance. Any parameters you
 275 provide are will override existing attribute values in the object.
 276 .Sp
 277 This is a convenience method for cloning an object instance, then
 278 blessing it into the appropriate package.
 279 .Sp
 280 You could implement a clone method in your class, using this method:
 281 .Sp
 282 .Vb 4
 283 \&  sub clone {
 284 \&      my ($self, %params) = @_;
 285 \&      $self\->meta\->clone_object($self, %params);
 286 \&  }
 287 .Ve
 288 .ie n .IP "\fB$metaclass\->rebless_instance($instance, \fB%params\fB)\fR" 4
 289 .el .IP "\fB$metaclass\->rebless_instance($instance, \f(CB%params\fB)\fR" 4
 290 .IX Item "$metaclass->rebless_instance($instance, %params)"
 291 This method changes the class of \f(CW$instance\fR to the metaclass's class.
 292 .Sp
 293 You can only rebless an instance into a subclass of its current
 294 class. If you pass any additional parameters, these will be treated
 295 like constructor parameters and used to initialize the object's
 296 attributes. Any existing attributes that are already set will be
 297 overwritten.
 298 .Sp
 299 Before reblessing the instance, this method will call
 300 \&\f(CW\*(C`rebless_instance_away\*(C'\fR on the instance's current metaclass. This method
 301 will be passed the instance, the new metaclass, and any parameters
 302 specified to \f(CW\*(C`rebless_instance\*(C'\fR. By default, \f(CW\*(C`rebless_instance_away\*(C'\fR
 303 does nothing; it is merely a hook.
 304 .IP "\fB$metaclass\->new_object(%params)\fR" 4
 305 .IX Item "$metaclass->new_object(%params)"
 306 This method is used to create a new object of the metaclass's
 307 class. Any parameters you provide are used to initialize the
 308 instance's attributes. A special \f(CW\*(C`_\|_INSTANCE_\|_\*(C'\fR key can be passed to
 309 provide an already generated instance, rather than having Class::MOP
 310 generate it for you. This is mostly useful for using Class::MOP with
 311 foreign classes which generate instances using their own constructors.
 312 .IP "\fB$metaclass\->instance_metaclass\fR" 4
 313 .IX Item "$metaclass->instance_metaclass"
 314 Returns the class name of the instance metaclass. See
 315 Class::MOP::Instance for more information on the instance
 316 metaclass.
 317 .IP "\fB$metaclass\->get_meta_instance\fR" 4
 318 .IX Item "$metaclass->get_meta_instance"
 319 Returns an instance of the \f(CW\*(C`instance_metaclass\*(C'\fR to be used in the
 320 construction of a new instance of the class.
 321 .Sh "Informational predicates"
 322 .IX Subsection "Informational predicates"
 323 These are a few predicate methods for asking information about the
 324 class itself.
 325 .IP "\fB$metaclass\->is_anon_class\fR" 4
 326 .IX Item "$metaclass->is_anon_class"
 327 This returns true if the class was created by calling \f(CW\*(C`Class::MOP::Class\->create_anon_class\*(C'\fR.
 328 .IP "\fB$metaclass\->is_mutable\fR" 4
 329 .IX Item "$metaclass->is_mutable"
 330 This returns true if the class is still mutable.
 331 .IP "\fB$metaclass\->is_immutable\fR" 4
 332 .IX Item "$metaclass->is_immutable"
 333 This returns true if the class has been made immutable.
 334 .IP "\fB$metaclass\->is_pristine\fR" 4
 335 .IX Item "$metaclass->is_pristine"
 336 A class is \fInot\fR pristine if it has non-inherited attributes or if it
 337 has any generated methods.
 338 .Sh "Inheritance Relationships"
 339 .IX Subsection "Inheritance Relationships"
 340 .IP "\fB$metaclass\->superclasses(@superclasses)\fR" 4
 341 .IX Item "$metaclass->superclasses(@superclasses)"
 342 This is a read-write accessor which represents the superclass
 343 relationships of the metaclass's class.
 344 .Sp
 345 This is basically sugar around getting and setting \f(CW@ISA\fR.
 346 .IP "\fB$metaclass\->class_precedence_list\fR" 4
 347 .IX Item "$metaclass->class_precedence_list"
 348 This returns a list of all of the class's ancestor classes. The
 349 classes are returned in method dispatch order.
 350 .IP "\fB$metaclass\->linearized_isa\fR" 4
 351 .IX Item "$metaclass->linearized_isa"
 352 This returns a list based on \f(CW\*(C`class_precedence_list\*(C'\fR but with all
 353 duplicates removed.
 354 .IP "\fB$metaclass\->subclasses\fR" 4
 355 .IX Item "$metaclass->subclasses"
 356 This returns a list of all subclasses for this class, even indirect
 357 subclasses.
 358 .IP "\fB$metaclass\->direct_subclasses\fR" 4
 359 .IX Item "$metaclass->direct_subclasses"
 360 This returns a list of immediate subclasses for this class, which does not
 361 include indirect subclasses.
 362 .Sh "Method introspection"
 363 .IX Subsection "Method introspection"
 364 See \*(L"Method introspection and creation\*(R" in Class::MOP::Package for
 365 methods that operate only on the current class.  Class::MOP::Class adds
 366 introspection capabilities that take inheritance into account.
 367 .IP "\fB$metaclass\->get_all_methods\fR" 4
 368 .IX Item "$metaclass->get_all_methods"
 369 This will traverse the inheritance hierarchy and return a list of all
 370 the Class::MOP::Method objects for this class and its parents.
 371 .IP "\fB$metaclass\->find_method_by_name($method_name)\fR" 4
 372 .IX Item "$metaclass->find_method_by_name($method_name)"
 373 This will return a Class::MOP::Method for the specified
 374 \&\f(CW$method_name\fR. If the class does not have the specified method, it
 375 returns \f(CW\*(C`undef\*(C'\fR
 376 .Sp
 377 Unlike \f(CW\*(C`get_method\*(C'\fR, this method \fIwill\fR look for the named method in
 378 superclasses.
 379 .IP "\fB$metaclass\->get_all_method_names\fR" 4
 380 .IX Item "$metaclass->get_all_method_names"
 381 This will return a list of method \fInames\fR for all of this class's
 382 methods, including inherited methods.
 383 .IP "\fB$metaclass\->find_all_methods_by_name($method_name)\fR" 4
 384 .IX Item "$metaclass->find_all_methods_by_name($method_name)"
 385 This method looks for the named method in the class and all of its
 386 parents. It returns every matching method it finds in the inheritance
 387 tree, so it returns a list of methods.
 388 .Sp
 389 Each method is returned as a hash reference with three keys. The keys
 390 are \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`class\*(C'\fR, and \f(CW\*(C`code\*(C'\fR. The \f(CW\*(C`code\*(C'\fR key has a
 391 Class::MOP::Method object as its value.
 392 .Sp
 393 The list of methods is distinct.
 394 .IP "\fB$metaclass\->find_next_method_by_name($method_name)\fR" 4
 395 .IX Item "$metaclass->find_next_method_by_name($method_name)"
 396 This method returns the first method in any superclass matching the
 397 given name. It is effectively the method that \f(CW\*(C`SUPER::$method_name\*(C'\fR
 398 would dispatch to.
 399 .Sh "Attribute introspection and creation"
 400 .IX Subsection "Attribute introspection and creation"
 401 Because Perl 5 does not have a core concept of attributes in classes,
 402 we can only return information about attributes which have been added
 403 via this class's methods. We cannot discover information about
 404 attributes which are defined in terms of \*(L"regular\*(R" Perl 5 methods.
 405 .IP "\fB$metaclass\->get_attribute($attribute_name)\fR" 4
 406 .IX Item "$metaclass->get_attribute($attribute_name)"
 407 This will return a Class::MOP::Attribute for the specified
 408 \&\f(CW$attribute_name\fR. If the class does not have the specified
 409 attribute, it returns \f(CW\*(C`undef\*(C'\fR.
 410 .Sp
 411 \&\s-1NOTE\s0 that get_attribute does not search superclasses, for that you
 412 need to use \f(CW\*(C`find_attribute_by_name\*(C'\fR.
 413 .IP "\fB$metaclass\->has_attribute($attribute_name)\fR" 4
 414 .IX Item "$metaclass->has_attribute($attribute_name)"
 415 Returns a boolean indicating whether or not the class defines the
 416 named attribute. It does not include attributes inherited from parent
 417 classes.
 418 .IP "\fB$metaclass\->get_attribute_list\fR" 4
 419 .IX Item "$metaclass->get_attribute_list"
 420 This will return a list of attributes \fInames\fR for all attributes
 421 defined in this class.
 422 .IP "\fB$metaclass\->get_all_attributes\fR" 4
 423 .IX Item "$metaclass->get_all_attributes"
 424 This will traverse the inheritance hierarchy and return a list of all
 425 the Class::MOP::Attribute objects for this class and its parents.
 426 .IP "\fB$metaclass\->find_attribute_by_name($attribute_name)\fR" 4
 427 .IX Item "$metaclass->find_attribute_by_name($attribute_name)"
 428 This will return a Class::MOP::Attribute for the specified
 429 \&\f(CW$attribute_name\fR. If the class does not have the specified
 430 attribute, it returns \f(CW\*(C`undef\*(C'\fR.
 431 .Sp
 432 Unlike \f(CW\*(C`get_attribute\*(C'\fR, this attribute \fIwill\fR look for the named
 433 attribute in superclasses.
 434 .IP "\fB$metaclass\->add_attribute(...)\fR" 4
 435 .IX Item "$metaclass->add_attribute(...)"
 436 This method accepts either an existing Class::MOP::Attribute
 437 object or parameters suitable for passing to that class's \f(CW\*(C`new\*(C'\fR
 438 method.
 439 .Sp
 440 The attribute provided will be added to the class.
 441 .Sp
 442 Any accessor methods defined by the attribute will be added to the
 443 class when the attribute is added.
 444 .Sp
 445 If an attribute of the same name already exists, the old attribute
 446 will be removed first.
 447 .IP "\fB$metaclass\->remove_attribute($attribute_name)\fR" 4
 448 .IX Item "$metaclass->remove_attribute($attribute_name)"
 449 This will remove the named attribute from the class, and
 450 Class::MOP::Attribute object.
 451 .Sp
 452 Removing an attribute also removes any accessor methods defined by the
 453 attribute.
 454 .Sp
 455 However, note that removing an attribute will only affect \fIfuture\fR
 456 object instances created for this class, not existing instances.
 457 .IP "\fB$metaclass\->attribute_metaclass\fR" 4
 458 .IX Item "$metaclass->attribute_metaclass"
 459 Returns the class name of the attribute metaclass for this class. By
 460 default, this is Class::MOP::Attribute.
 461 .Sh "Class Immutability"
 462 .IX Subsection "Class Immutability"
 463 Making a class immutable \*(L"freezes\*(R" the class definition. You can no
 464 longer call methods which alter the class, such as adding or removing
 465 methods or attributes.
 466 .PP
 467 Making a class immutable lets us optimize the class by inlining some
 468 methods, and also allows us to optimize some methods on the metaclass
 469 object itself.
 470 .PP
 471 After immutabilization, the metaclass object will cache most informational
 472 methods that returns information about methods or attributes. Methods which
 473 would alter the class, such as \f(CW\*(C`add_attribute\*(C'\fR and \f(CW\*(C`add_method\*(C'\fR, will
 474 throw an error on an immutable metaclass object.
 475 .PP
 476 The immutabilization system in Moose takes much greater advantage
 477 of the inlining features than Class::MOP itself does.
 478 .IP "\fB$metaclass\->make_immutable(%options)\fR" 4
 479 .IX Item "$metaclass->make_immutable(%options)"
 480 This method will create an immutable transformer and use it to make
 481 the class and its metaclass object immutable.
 482 .Sp
 483 This method accepts the following options:
 484 .RS 4
 485 .IP "* inline_accessors" 8
 486 .IX Item "inline_accessors"
 487 .PD 0
 488 .IP "* inline_constructor" 8
 489 .IX Item "inline_constructor"
 490 .IP "* inline_destructor" 8
 491 .IX Item "inline_destructor"
 492 .PD
 493 These are all booleans indicating whether the specified method(s)
 494 should be inlined.
 495 .Sp
 496 By default, accessors and the constructor are inlined, but not the
 497 destructor.
 498 .IP "* immutable_trait" 8
 499 .IX Item "immutable_trait"
 500 The name of a class which will be used as a parent class for the
 501 metaclass object being made immutable. This \*(L"trait\*(R" implements the
 502 post-immutability functionality of the metaclass (but not the
 503 transformation itself).
 504 .Sp
 505 This defaults to Class::MOP::Class::Immutable::Trait.
 506 .IP "* constructor_name" 8
 507 .IX Item "constructor_name"
 508 This is the constructor method name. This defaults to \*(L"new\*(R".
 509 .IP "* constructor_class" 8
 510 .IX Item "constructor_class"
 511 The name of the method metaclass for constructors. It will be used to
 512 generate the inlined constructor. This defaults to
 513 \&\*(L"Class::MOP::Method::Constructor\*(R".
 514 .IP "* replace_constructor" 8
 515 .IX Item "replace_constructor"
 516 This is a boolean indicating whether an existing constructor should be
 517 replaced when inlining a constructor. This defaults to false.
 518 .IP "* destructor_class" 8
 519 .IX Item "destructor_class"
 520 The name of the method metaclass for destructors. It will be used to
 521 generate the inlined destructor. This defaults to
 522 \&\*(L"Class::MOP::Method::Denstructor\*(R".
 523 .IP "* replace_destructor" 8
 524 .IX Item "replace_destructor"
 525 This is a boolean indicating whether an existing destructor should be
 526 replaced when inlining a destructor. This defaults to false.
 527 .RE
 528 .RS 4
 529 .RE
 530 .IP "\fB$metaclass\->immutable_options\fR" 4
 531 .IX Item "$metaclass->immutable_options"
 532 Returns a hash of the options used when making the class immutable, including
 533 both defaults and anything supplied by the user in the call to \f(CW\*(C`$metaclass\->make_immutable\*(C'\fR. This is useful if you need to temporarily make
 534 a class mutable and then restore immutability as it was before.
 535 .IP "\fB$metaclass\->make_mutable\fR" 4
 536 .IX Item "$metaclass->make_mutable"
 537 Calling this method reverse the immutabilization transformation.
 538 .Sh "Method Modifiers"
 539 .IX Subsection "Method Modifiers"
 540 Method modifiers are hooks which allow a method to be wrapped with
 541 \&\fIbefore\fR, \fIafter\fR and \fIaround\fR method modifiers. Every time a
 542 method is called, its modifiers are also called.
 543 .PP
 544 A class can modify its own methods, as well as methods defined in
 545 parent classes.
 546 .PP
 547 \fIHow method modifiers work?\fR
 548 .IX Subsection "How method modifiers work?"
 549 .PP
 550 Method modifiers work by wrapping the original method and then
 551 replacing it in the class's symbol table. The wrappers will handle
 552 calling all the modifiers in the appropriate order and preserving the
 553 calling context for the original method.
 554 .PP
 555 The return values of \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR modifiers are
 556 ignored. This is because their purpose is \fBnot\fR to filter the input
 557 and output of the primary method (this is done with an \fIaround\fR
 558 modifier).
 559 .PP
 560 This may seem like an odd restriction to some, but doing this allows
 561 for simple code to be added at the beginning or end of a method call
 562 without altering the function of the wrapped method or placing any
 563 extra responsibility on the code of the modifier.
 564 .PP
 565 Of course if you have more complex needs, you can use the \f(CW\*(C`around\*(C'\fR
 566 modifier which allows you to change both the parameters passed to the
 567 wrapped method, as well as its return value.
 568 .PP
 569 Before and around modifiers are called in last-defined-first-called
 570 order, while after modifiers are called in first-defined-first-called
 571 order. So the call tree might looks something like this:
 572 .PP
 573 .Vb 9
 574 \&  before 2
 575 \&   before 1
 576 \&    around 2
 577 \&     around 1
 578 \&      primary
 579 \&     around 1
 580 \&    around 2
 581 \&   after 1
 582 \&  after 2
 583 .Ve
 584 .PP
 585 \fIWhat is the performance impact?\fR
 586 .IX Subsection "What is the performance impact?"
 587 .PP
 588 Of course there is a performance cost associated with method
 589 modifiers, but we have made every effort to make that cost directly
 590 proportional to the number of modifier features you use.
 591 .PP
 592 The wrapping method does its best to \fBonly\fR do as much work as it
 593 absolutely needs to. In order to do this we have moved some of the
 594 performance costs to set-up time, where they are easier to amortize.
 595 .PP
 596 All this said, our benchmarks have indicated the following:
 597 .PP
 598 .Vb 5
 599 \&  simple wrapper with no modifiers             100% slower
 600 \&  simple wrapper with simple before modifier   400% slower
 601 \&  simple wrapper with simple after modifier    450% slower
 602 \&  simple wrapper with simple around modifier   500\-550% slower
 603 \&  simple wrapper with all 3 modifiers          1100% slower
 604 .Ve
 605 .PP
 606 These numbers may seem daunting, but you must remember, every feature
 607 comes with some cost. To put things in perspective, just doing a
 608 simple \f(CW\*(C`AUTOLOAD\*(C'\fR which does nothing but extract the name of the
 609 method called and return it costs about 400% over a normal method
 610 call.
 611 .ie n .IP "\fB$metaclass\->add_before_method_modifier($method_name, \fB$code\fB)\fR" 4
 612 .el .IP "\fB$metaclass\->add_before_method_modifier($method_name, \f(CB$code\fB)\fR" 4
 613 .IX Item "$metaclass->add_before_method_modifier($method_name, $code)"
 614 This wraps the specified method with the supplied subroutine
 615 reference. The modifier will be called as a method itself, and will
 616 receive the same arguments as are passed to the method.
 617 .Sp
 618 When the modifier exits, the wrapped method will be called.
 619 .Sp
 620 The return value of the modifier will be ignored.
 621 .ie n .IP "\fB$metaclass\->add_after_method_modifier($method_name, \fB$code\fB)\fR" 4
 622 .el .IP "\fB$metaclass\->add_after_method_modifier($method_name, \f(CB$code\fB)\fR" 4
 623 .IX Item "$metaclass->add_after_method_modifier($method_name, $code)"
 624 This wraps the specified method with the supplied subroutine
 625 reference. The modifier will be called as a method itself, and will
 626 receive the same arguments as are passed to the method.
 627 .Sp
 628 When the wrapped methods exits, the modifier will be called.
 629 .Sp
 630 The return value of the modifier will be ignored.
 631 .ie n .IP "\fB$metaclass\->add_around_method_modifier($method_name, \fB$code\fB)\fR" 4
 632 .el .IP "\fB$metaclass\->add_around_method_modifier($method_name, \f(CB$code\fB)\fR" 4
 633 .IX Item "$metaclass->add_around_method_modifier($method_name, $code)"
 634 This wraps the specified method with the supplied subroutine
 635 reference.
 636 .Sp
 637 The first argument passed to the modifier will be a subroutine
 638 reference to the wrapped method. The second argument is the object,
 639 and after that come any arguments passed when the method is called.
 640 .Sp
 641 The around modifier can choose to call the original method, as well as
 642 what arguments to pass if it does so.
 643 .Sp
 644 The return value of the modifier is what will be seen by the caller.
 645 .Sh "Introspection"
 646 .IX Subsection "Introspection"
 647 .IP "\fBClass::MOP::Class\->meta\fR" 4
 648 .IX Item "Class::MOP::Class->meta"
 649 This will return a Class::MOP::Class instance for this class.
 650 .Sp
 651 It should also be noted that Class::MOP will actually bootstrap
 652 this module by installing a number of attribute meta-objects into its
 653 metaclass.
 654 .SH "AUTHORS"
 655 .IX Header "AUTHORS"
 656 Stevan Little <stevan@iinteractive.com>
 657 .SH "COPYRIGHT AND LICENSE"
 658 .IX Header "COPYRIGHT AND LICENSE"
 659 Copyright 2006\-2009 by Infinity Interactive, Inc.
 660 .PP
 661 <http://www.iinteractive.com>
 662 .PP
 663 This library is free software; you can redistribute it and/or modify
 664 it under the same terms as Perl itself.