--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Class::MOP::Class 3"
+.TH Class::MOP::Class 3 "2009-11-18" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Class::MOP::Class \- Class Meta Object
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\& # assuming that class Foo
+\& # has been defined, you can
+.Ve
+.PP
+.Vb 1
+\& # use this for introspection ...
+.Ve
+.PP
+.Vb 2
+\& # add a method to Foo ...
+\& Foo\->meta\->add_method( 'bar' => sub {...} )
+.Ve
+.PP
+.Vb 3
+\& # get a list of all the classes searched
+\& # the method dispatcher in the correct order
+\& Foo\->meta\->class_precedence_list()
+.Ve
+.PP
+.Vb 2
+\& # remove a method from Foo
+\& Foo\->meta\->remove_method('bar');
+.Ve
+.PP
+.Vb 1
+\& # or use this to actually create classes ...
+.Ve
+.PP
+.Vb 14
+\& Class::MOP::Class\->create(
+\& 'Bar' => (
+\& version => '0.01',
+\& superclasses => ['Foo'],
+\& attributes => [
+\& Class::MOP::Attribute\->new('$bar'),
+\& Class::MOP::Attribute\->new('$baz'),
+\& ],
+\& methods => {
+\& calculate_bar => sub {...},
+\& construct_baz => sub {...}
+\& }
+\& )
+\& );
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The Class Protocol is the largest and most complex part of the
+Class::MOP meta-object protocol. It controls the introspection and
+manipulation of Perl 5 classes, and it can create them as well. The
+best way to understand what this module can do is to read the
+documentation for each of its methods.
+.SH "INHERITANCE"
+.IX Header "INHERITANCE"
+\&\f(CW\*(C`Class::MOP::Class\*(C'\fR is a subclass of Class::MOP::Module.
+.SH "METHODS"
+.IX Header "METHODS"
+.Sh "Class construction"
+.IX Subsection "Class construction"
+These methods all create new \f(CW\*(C`Class::MOP::Class\*(C'\fR objects. These
+objects can represent existing classes or they can be used to create
+new classes from scratch.
+.PP
+The metaclass object for a given class is a singleton. If you attempt
+to create a metaclass for the same class twice, you will just get the
+existing object.
+.ie n .IP "\fBClass::MOP::Class\->create($package_name, \fB%options\fB)\fR" 4
+.el .IP "\fBClass::MOP::Class\->create($package_name, \f(CB%options\fB)\fR" 4
+.IX Item "Class::MOP::Class->create($package_name, %options)"
+This method creates a new \f(CW\*(C`Class::MOP::Class\*(C'\fR object with the given
+package name. It accepts a number of options:
+.RS 4
+.IP "* version" 8
+.IX Item "version"
+An optional version number for the newly created package.
+.IP "* authority" 8
+.IX Item "authority"
+An optional authority for the newly created package.
+.IP "* superclasses" 8
+.IX Item "superclasses"
+An optional array reference of superclass names.
+.IP "* methods" 8
+.IX Item "methods"
+An optional hash reference of methods for the class. The keys of the
+hash reference are method names and values are subroutine references.
+.IP "* attributes" 8
+.IX Item "attributes"
+An optional array reference of Class::MOP::Attribute objects.
+.RE
+.RS 4
+.RE
+.IP "\fBClass::MOP::Class\->create_anon_class(%options)\fR" 4
+.IX Item "Class::MOP::Class->create_anon_class(%options)"
+This method works just like \f(CW\*(C`Class::MOP::Class\->create\*(C'\fR but it
+creates an \*(L"anonymous\*(R" class. In fact, the class does have a name, but
+that name is a unique name generated internally by this module.
+.Sp
+It accepts the same \f(CW\*(C`superclasses\*(C'\fR, \f(CW\*(C`methods\*(C'\fR, and \f(CW\*(C`attributes\*(C'\fR
+parameters that \f(CW\*(C`create\*(C'\fR accepts.
+.Sp
+Anonymous classes are destroyed once the metaclass they are attached
+to goes out of scope, and will be removed from Perl's internal symbol
+table.
+.Sp
+All instances of an anonymous class keep a special reference to the
+metaclass object, which prevents the metaclass from going out of scope
+while any instances exist.
+.Sp
+This only works if the instance is based on a hash reference, however.
+.ie n .IP "\fBClass::MOP::Class\->initialize($package_name, \fB%options\fB)\fR" 4
+.el .IP "\fBClass::MOP::Class\->initialize($package_name, \f(CB%options\fB)\fR" 4
+.IX Item "Class::MOP::Class->initialize($package_name, %options)"
+This method will initialize a \f(CW\*(C`Class::MOP::Class\*(C'\fR object for the
+named package. Unlike \f(CW\*(C`create\*(C'\fR, this method \fIwill not\fR create a new
+class.
+.Sp
+The purpose of this method is to retrieve a \f(CW\*(C`Class::MOP::Class\*(C'\fR
+object for introspecting an existing class.
+.Sp
+If an existing \f(CW\*(C`Class::MOP::Class\*(C'\fR object exists for the named
+package, it will be returned, and any options provided will be
+ignored!
+.Sp
+If the object does not yet exist, it will be created.
+.Sp
+The valid options that can be passed to this method are
+\&\f(CW\*(C`attribute_metaclass\*(C'\fR, \f(CW\*(C`method_metaclass\*(C'\fR,
+\&\f(CW\*(C`wrapped_method_metaclass\*(C'\fR, and \f(CW\*(C`instance_metaclass\*(C'\fR. These are all
+optional, and default to the appropriate class in the \f(CW\*(C`Class::MOP\*(C'\fR
+distribution.
+.Sh "Object instance construction and cloning"
+.IX Subsection "Object instance construction and cloning"
+These methods are all related to creating and/or cloning object
+instances.
+.ie n .IP "\fB$metaclass\->clone_object($instance, \fB%params\fB)\fR" 4
+.el .IP "\fB$metaclass\->clone_object($instance, \f(CB%params\fB)\fR" 4
+.IX Item "$metaclass->clone_object($instance, %params)"
+This method clones an existing object instance. Any parameters you
+provide are will override existing attribute values in the object.
+.Sp
+This is a convenience method for cloning an object instance, then
+blessing it into the appropriate package.
+.Sp
+You could implement a clone method in your class, using this method:
+.Sp
+.Vb 4
+\& sub clone {
+\& my ($self, %params) = @_;
+\& $self\->meta\->clone_object($self, %params);
+\& }
+.Ve
+.ie n .IP "\fB$metaclass\->rebless_instance($instance, \fB%params\fB)\fR" 4
+.el .IP "\fB$metaclass\->rebless_instance($instance, \f(CB%params\fB)\fR" 4
+.IX Item "$metaclass->rebless_instance($instance, %params)"
+This method changes the class of \f(CW$instance\fR to the metaclass's class.
+.Sp
+You can only rebless an instance into a subclass of its current
+class. If you pass any additional parameters, these will be treated
+like constructor parameters and used to initialize the object's
+attributes. Any existing attributes that are already set will be
+overwritten.
+.Sp
+Before reblessing the instance, this method will call
+\&\f(CW\*(C`rebless_instance_away\*(C'\fR on the instance's current metaclass. This method
+will be passed the instance, the new metaclass, and any parameters
+specified to \f(CW\*(C`rebless_instance\*(C'\fR. By default, \f(CW\*(C`rebless_instance_away\*(C'\fR
+does nothing; it is merely a hook.
+.IP "\fB$metaclass\->new_object(%params)\fR" 4
+.IX Item "$metaclass->new_object(%params)"
+This method is used to create a new object of the metaclass's
+class. Any parameters you provide are used to initialize the
+instance's attributes. A special \f(CW\*(C`_\|_INSTANCE_\|_\*(C'\fR key can be passed to
+provide an already generated instance, rather than having Class::MOP
+generate it for you. This is mostly useful for using Class::MOP with
+foreign classes which generate instances using their own constructors.
+.IP "\fB$metaclass\->instance_metaclass\fR" 4
+.IX Item "$metaclass->instance_metaclass"
+Returns the class name of the instance metaclass. See
+Class::MOP::Instance for more information on the instance
+metaclass.
+.IP "\fB$metaclass\->get_meta_instance\fR" 4
+.IX Item "$metaclass->get_meta_instance"
+Returns an instance of the \f(CW\*(C`instance_metaclass\*(C'\fR to be used in the
+construction of a new instance of the class.
+.Sh "Informational predicates"
+.IX Subsection "Informational predicates"
+These are a few predicate methods for asking information about the
+class itself.
+.IP "\fB$metaclass\->is_anon_class\fR" 4
+.IX Item "$metaclass->is_anon_class"
+This returns true if the class was created by calling \f(CW\*(C`Class::MOP::Class\->create_anon_class\*(C'\fR.
+.IP "\fB$metaclass\->is_mutable\fR" 4
+.IX Item "$metaclass->is_mutable"
+This returns true if the class is still mutable.
+.IP "\fB$metaclass\->is_immutable\fR" 4
+.IX Item "$metaclass->is_immutable"
+This returns true if the class has been made immutable.
+.IP "\fB$metaclass\->is_pristine\fR" 4
+.IX Item "$metaclass->is_pristine"
+A class is \fInot\fR pristine if it has non-inherited attributes or if it
+has any generated methods.
+.Sh "Inheritance Relationships"
+.IX Subsection "Inheritance Relationships"
+.IP "\fB$metaclass\->superclasses(@superclasses)\fR" 4
+.IX Item "$metaclass->superclasses(@superclasses)"
+This is a read-write accessor which represents the superclass
+relationships of the metaclass's class.
+.Sp
+This is basically sugar around getting and setting \f(CW@ISA\fR.
+.IP "\fB$metaclass\->class_precedence_list\fR" 4
+.IX Item "$metaclass->class_precedence_list"
+This returns a list of all of the class's ancestor classes. The
+classes are returned in method dispatch order.
+.IP "\fB$metaclass\->linearized_isa\fR" 4
+.IX Item "$metaclass->linearized_isa"
+This returns a list based on \f(CW\*(C`class_precedence_list\*(C'\fR but with all
+duplicates removed.
+.IP "\fB$metaclass\->subclasses\fR" 4
+.IX Item "$metaclass->subclasses"
+This returns a list of all subclasses for this class, even indirect
+subclasses.
+.IP "\fB$metaclass\->direct_subclasses\fR" 4
+.IX Item "$metaclass->direct_subclasses"
+This returns a list of immediate subclasses for this class, which does not
+include indirect subclasses.
+.Sh "Method introspection"
+.IX Subsection "Method introspection"
+See \*(L"Method introspection and creation\*(R" in Class::MOP::Package for
+methods that operate only on the current class. Class::MOP::Class adds
+introspection capabilities that take inheritance into account.
+.IP "\fB$metaclass\->get_all_methods\fR" 4
+.IX Item "$metaclass->get_all_methods"
+This will traverse the inheritance hierarchy and return a list of all
+the Class::MOP::Method objects for this class and its parents.
+.IP "\fB$metaclass\->find_method_by_name($method_name)\fR" 4
+.IX Item "$metaclass->find_method_by_name($method_name)"
+This will return a Class::MOP::Method for the specified
+\&\f(CW$method_name\fR. If the class does not have the specified method, it
+returns \f(CW\*(C`undef\*(C'\fR
+.Sp
+Unlike \f(CW\*(C`get_method\*(C'\fR, this method \fIwill\fR look for the named method in
+superclasses.
+.IP "\fB$metaclass\->get_all_method_names\fR" 4
+.IX Item "$metaclass->get_all_method_names"
+This will return a list of method \fInames\fR for all of this class's
+methods, including inherited methods.
+.IP "\fB$metaclass\->find_all_methods_by_name($method_name)\fR" 4
+.IX Item "$metaclass->find_all_methods_by_name($method_name)"
+This method looks for the named method in the class and all of its
+parents. It returns every matching method it finds in the inheritance
+tree, so it returns a list of methods.
+.Sp
+Each method is returned as a hash reference with three keys. The keys
+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
+Class::MOP::Method object as its value.
+.Sp
+The list of methods is distinct.
+.IP "\fB$metaclass\->find_next_method_by_name($method_name)\fR" 4
+.IX Item "$metaclass->find_next_method_by_name($method_name)"
+This method returns the first method in any superclass matching the
+given name. It is effectively the method that \f(CW\*(C`SUPER::$method_name\*(C'\fR
+would dispatch to.
+.Sh "Attribute introspection and creation"
+.IX Subsection "Attribute introspection and creation"
+Because Perl 5 does not have a core concept of attributes in classes,
+we can only return information about attributes which have been added
+via this class's methods. We cannot discover information about
+attributes which are defined in terms of \*(L"regular\*(R" Perl 5 methods.
+.IP "\fB$metaclass\->get_attribute($attribute_name)\fR" 4
+.IX Item "$metaclass->get_attribute($attribute_name)"
+This will return a Class::MOP::Attribute for the specified
+\&\f(CW$attribute_name\fR. If the class does not have the specified
+attribute, it returns \f(CW\*(C`undef\*(C'\fR.
+.Sp
+\&\s-1NOTE\s0 that get_attribute does not search superclasses, for that you
+need to use \f(CW\*(C`find_attribute_by_name\*(C'\fR.
+.IP "\fB$metaclass\->has_attribute($attribute_name)\fR" 4
+.IX Item "$metaclass->has_attribute($attribute_name)"
+Returns a boolean indicating whether or not the class defines the
+named attribute. It does not include attributes inherited from parent
+classes.
+.IP "\fB$metaclass\->get_attribute_list\fR" 4
+.IX Item "$metaclass->get_attribute_list"
+This will return a list of attributes \fInames\fR for all attributes
+defined in this class.
+.IP "\fB$metaclass\->get_all_attributes\fR" 4
+.IX Item "$metaclass->get_all_attributes"
+This will traverse the inheritance hierarchy and return a list of all
+the Class::MOP::Attribute objects for this class and its parents.
+.IP "\fB$metaclass\->find_attribute_by_name($attribute_name)\fR" 4
+.IX Item "$metaclass->find_attribute_by_name($attribute_name)"
+This will return a Class::MOP::Attribute for the specified
+\&\f(CW$attribute_name\fR. If the class does not have the specified
+attribute, it returns \f(CW\*(C`undef\*(C'\fR.
+.Sp
+Unlike \f(CW\*(C`get_attribute\*(C'\fR, this attribute \fIwill\fR look for the named
+attribute in superclasses.
+.IP "\fB$metaclass\->add_attribute(...)\fR" 4
+.IX Item "$metaclass->add_attribute(...)"
+This method accepts either an existing Class::MOP::Attribute
+object or parameters suitable for passing to that class's \f(CW\*(C`new\*(C'\fR
+method.
+.Sp
+The attribute provided will be added to the class.
+.Sp
+Any accessor methods defined by the attribute will be added to the
+class when the attribute is added.
+.Sp
+If an attribute of the same name already exists, the old attribute
+will be removed first.
+.IP "\fB$metaclass\->remove_attribute($attribute_name)\fR" 4
+.IX Item "$metaclass->remove_attribute($attribute_name)"
+This will remove the named attribute from the class, and
+Class::MOP::Attribute object.
+.Sp
+Removing an attribute also removes any accessor methods defined by the
+attribute.
+.Sp
+However, note that removing an attribute will only affect \fIfuture\fR
+object instances created for this class, not existing instances.
+.IP "\fB$metaclass\->attribute_metaclass\fR" 4
+.IX Item "$metaclass->attribute_metaclass"
+Returns the class name of the attribute metaclass for this class. By
+default, this is Class::MOP::Attribute.
+.Sh "Class Immutability"
+.IX Subsection "Class Immutability"
+Making a class immutable \*(L"freezes\*(R" the class definition. You can no
+longer call methods which alter the class, such as adding or removing
+methods or attributes.
+.PP
+Making a class immutable lets us optimize the class by inlining some
+methods, and also allows us to optimize some methods on the metaclass
+object itself.
+.PP
+After immutabilization, the metaclass object will cache most informational
+methods that returns information about methods or attributes. Methods which
+would alter the class, such as \f(CW\*(C`add_attribute\*(C'\fR and \f(CW\*(C`add_method\*(C'\fR, will
+throw an error on an immutable metaclass object.
+.PP
+The immutabilization system in Moose takes much greater advantage
+of the inlining features than Class::MOP itself does.
+.IP "\fB$metaclass\->make_immutable(%options)\fR" 4
+.IX Item "$metaclass->make_immutable(%options)"
+This method will create an immutable transformer and use it to make
+the class and its metaclass object immutable.
+.Sp
+This method accepts the following options:
+.RS 4
+.IP "* inline_accessors" 8
+.IX Item "inline_accessors"
+.PD 0
+.IP "* inline_constructor" 8
+.IX Item "inline_constructor"
+.IP "* inline_destructor" 8
+.IX Item "inline_destructor"
+.PD
+These are all booleans indicating whether the specified method(s)
+should be inlined.
+.Sp
+By default, accessors and the constructor are inlined, but not the
+destructor.
+.IP "* immutable_trait" 8
+.IX Item "immutable_trait"
+The name of a class which will be used as a parent class for the
+metaclass object being made immutable. This \*(L"trait\*(R" implements the
+post-immutability functionality of the metaclass (but not the
+transformation itself).
+.Sp
+This defaults to Class::MOP::Class::Immutable::Trait.
+.IP "* constructor_name" 8
+.IX Item "constructor_name"
+This is the constructor method name. This defaults to \*(L"new\*(R".
+.IP "* constructor_class" 8
+.IX Item "constructor_class"
+The name of the method metaclass for constructors. It will be used to
+generate the inlined constructor. This defaults to
+\&\*(L"Class::MOP::Method::Constructor\*(R".
+.IP "* replace_constructor" 8
+.IX Item "replace_constructor"
+This is a boolean indicating whether an existing constructor should be
+replaced when inlining a constructor. This defaults to false.
+.IP "* destructor_class" 8
+.IX Item "destructor_class"
+The name of the method metaclass for destructors. It will be used to
+generate the inlined destructor. This defaults to
+\&\*(L"Class::MOP::Method::Denstructor\*(R".
+.IP "* replace_destructor" 8
+.IX Item "replace_destructor"
+This is a boolean indicating whether an existing destructor should be
+replaced when inlining a destructor. This defaults to false.
+.RE
+.RS 4
+.RE
+.IP "\fB$metaclass\->immutable_options\fR" 4
+.IX Item "$metaclass->immutable_options"
+Returns a hash of the options used when making the class immutable, including
+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
+a class mutable and then restore immutability as it was before.
+.IP "\fB$metaclass\->make_mutable\fR" 4
+.IX Item "$metaclass->make_mutable"
+Calling this method reverse the immutabilization transformation.
+.Sh "Method Modifiers"
+.IX Subsection "Method Modifiers"
+Method modifiers are hooks which allow a method to be wrapped with
+\&\fIbefore\fR, \fIafter\fR and \fIaround\fR method modifiers. Every time a
+method is called, its modifiers are also called.
+.PP
+A class can modify its own methods, as well as methods defined in
+parent classes.
+.PP
+\fIHow method modifiers work?\fR
+.IX Subsection "How method modifiers work?"
+.PP
+Method modifiers work by wrapping the original method and then
+replacing it in the class's symbol table. The wrappers will handle
+calling all the modifiers in the appropriate order and preserving the
+calling context for the original method.
+.PP
+The return values of \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR modifiers are
+ignored. This is because their purpose is \fBnot\fR to filter the input
+and output of the primary method (this is done with an \fIaround\fR
+modifier).
+.PP
+This may seem like an odd restriction to some, but doing this allows
+for simple code to be added at the beginning or end of a method call
+without altering the function of the wrapped method or placing any
+extra responsibility on the code of the modifier.
+.PP
+Of course if you have more complex needs, you can use the \f(CW\*(C`around\*(C'\fR
+modifier which allows you to change both the parameters passed to the
+wrapped method, as well as its return value.
+.PP
+Before and around modifiers are called in last-defined-first-called
+order, while after modifiers are called in first-defined-first-called
+order. So the call tree might looks something like this:
+.PP
+.Vb 9
+\& before 2
+\& before 1
+\& around 2
+\& around 1
+\& primary
+\& around 1
+\& around 2
+\& after 1
+\& after 2
+.Ve
+.PP
+\fIWhat is the performance impact?\fR
+.IX Subsection "What is the performance impact?"
+.PP
+Of course there is a performance cost associated with method
+modifiers, but we have made every effort to make that cost directly
+proportional to the number of modifier features you use.
+.PP
+The wrapping method does its best to \fBonly\fR do as much work as it
+absolutely needs to. In order to do this we have moved some of the
+performance costs to set-up time, where they are easier to amortize.
+.PP
+All this said, our benchmarks have indicated the following:
+.PP
+.Vb 5
+\& simple wrapper with no modifiers 100% slower
+\& simple wrapper with simple before modifier 400% slower
+\& simple wrapper with simple after modifier 450% slower
+\& simple wrapper with simple around modifier 500\-550% slower
+\& simple wrapper with all 3 modifiers 1100% slower
+.Ve
+.PP
+These numbers may seem daunting, but you must remember, every feature
+comes with some cost. To put things in perspective, just doing a
+simple \f(CW\*(C`AUTOLOAD\*(C'\fR which does nothing but extract the name of the
+method called and return it costs about 400% over a normal method
+call.
+.ie n .IP "\fB$metaclass\->add_before_method_modifier($method_name, \fB$code\fB)\fR" 4
+.el .IP "\fB$metaclass\->add_before_method_modifier($method_name, \f(CB$code\fB)\fR" 4
+.IX Item "$metaclass->add_before_method_modifier($method_name, $code)"
+This wraps the specified method with the supplied subroutine
+reference. The modifier will be called as a method itself, and will
+receive the same arguments as are passed to the method.
+.Sp
+When the modifier exits, the wrapped method will be called.
+.Sp
+The return value of the modifier will be ignored.
+.ie n .IP "\fB$metaclass\->add_after_method_modifier($method_name, \fB$code\fB)\fR" 4
+.el .IP "\fB$metaclass\->add_after_method_modifier($method_name, \f(CB$code\fB)\fR" 4
+.IX Item "$metaclass->add_after_method_modifier($method_name, $code)"
+This wraps the specified method with the supplied subroutine
+reference. The modifier will be called as a method itself, and will
+receive the same arguments as are passed to the method.
+.Sp
+When the wrapped methods exits, the modifier will be called.
+.Sp
+The return value of the modifier will be ignored.
+.ie n .IP "\fB$metaclass\->add_around_method_modifier($method_name, \fB$code\fB)\fR" 4
+.el .IP "\fB$metaclass\->add_around_method_modifier($method_name, \f(CB$code\fB)\fR" 4
+.IX Item "$metaclass->add_around_method_modifier($method_name, $code)"
+This wraps the specified method with the supplied subroutine
+reference.
+.Sp
+The first argument passed to the modifier will be a subroutine
+reference to the wrapped method. The second argument is the object,
+and after that come any arguments passed when the method is called.
+.Sp
+The around modifier can choose to call the original method, as well as
+what arguments to pass if it does so.
+.Sp
+The return value of the modifier is what will be seen by the caller.
+.Sh "Introspection"
+.IX Subsection "Introspection"
+.IP "\fBClass::MOP::Class\->meta\fR" 4
+.IX Item "Class::MOP::Class->meta"
+This will return a Class::MOP::Class instance for this class.
+.Sp
+It should also be noted that Class::MOP will actually bootstrap
+this module by installing a number of attribute meta-objects into its
+metaclass.
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+Stevan Little <stevan@iinteractive.com>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2006\-2009 by Infinity Interactive, Inc.
+.PP
+<http://www.iinteractive.com>
+.PP
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff