17 Class::MOP - A Meta Object Protocol for Perl 5
25 This module is an attempt to create a meta object protocol for the
26 Perl 5 object system. It makes no attempt to change the behavior or
27 characteristics of the Perl 5 object system, only to create a
28 protocol for its manipulation and introspection.
30 That said, it does attempt to create the tools for building a rich
31 set of extensions to the Perl 5 object system. Every attempt has been
32 made for these tools to keep to the spirit of the Perl 5 object
33 system that we all know and love.
35 =head2 Who is this module for?
37 This module is specifically for anyone who has ever created or
38 wanted to create a module for the Class:: namespace. The tools which
39 this module will provide will hopefully make it easier to do more
40 complex things with Perl 5 classes by removing such barriers as
41 the need to hack the symbol tables, or understand the fine details
46 The protocol is divided into 3 main sub-protocols:
50 =item The Class protocol
52 This provides a means of manipulating and introspecting a Perl 5
53 class. It handles all of symbol table hacking for you, and provides
54 a rich set of methods that go beyond simple package introspection.
56 =item The Attribute protocol
58 This provides a consistent represenation for an attribute of a
59 Perl 5 class. Since there are so many ways to create and handle
60 atttributes in Perl 5 OO, this attempts to provide as much of a
61 unified approach as possible, while giving the freedom and
62 flexibility to subclass for specialization.
64 =item The Method protocol
66 This provides a means of manipulating and introspecting methods in
67 the Perl 5 object system. As with attributes, there are many ways to
68 approach this topic, so we try to keep it pretty basic, while still
69 making it possible to extend the system in many ways.
73 What follows is a more detailed documentation on each specific sub
76 =head2 The Class protocol
78 =head3 Class construction
80 These methods handle creating Class objects, which can be used to
81 both create new classes, and analyze pre-existing ones.
83 Class::MOP will internally store weakened references to all the
84 instances you create with these methods, so that they do not need
85 to be created any more than nessecary.
89 =item B<create ($package_name, ?@superclasses, ?%methods, ?%attributes)>
91 This returns the basic Class object, bringing the specified
92 C<$package_name> into existence and adding any of the
93 C<@superclasses>, C<%methods> and C<%attributes> to it.
95 =item B<load ($package_name)>
97 This returns the basic Class object, after examining the given
98 C<$package_name> and attempting to discover it's components (the
99 methods, attributes and superclasses).
101 B<NOTE>: This method makes every attempt to ignore subroutines
102 which have been exported by other packages into this one.
104 =item B<initialize ($package_name, @superclasses, %methods, %attributes)>
106 This creates the actual Class object given a C<$package_name>,
107 an array of C<@superclasses>, a hash of C<%methods> and a hash
108 of C<%attributes>. This method is used by both C<load> and
113 =head3 Instance construction
117 =item <create_instance ($canidate, %params)>
119 This will construct and instance using the C<$canidate> as storage
120 (currently only HASH references are supported). This will collect all
121 the applicable attribute meta-objects and layout out the fields in the
122 C<$canidate>, it will then initialize them using either use the
123 corresponding key in C<%params> or any default value or initializer
124 found in the attribute meta-object.
134 This is a read-only attribute which returns the package name that
135 the Class is stored in.
139 This is a read-only attribute which returns the C<$VERSION> of the
140 package the Class is stored in.
144 =head3 Inheritance Relationships
148 =item C<superclasses (?@superclasses)>
150 This is a read-write attribute which represents the superclass
151 relationships of this Class. Basically, it can get and set the
154 =item C<class_precendence_list>
156 This computes the a list of the Class's ancestors in the same order
157 in which method dispatch will be done.
165 =item C<add_method ($method_name, $method)>
167 This will take a C<$method_name> and CODE reference to that
168 C<$method> and install it into the Class.
170 B<NOTE> : This does absolutely nothing special to C<$method>
171 other than use B<Sub::Name> to make sure it is tagged with the
172 correct name, and therefore show up correctly in stack traces and
175 =item C<has_method ($method_name)>
177 This just provides a simple way to check if the Class implements
178 a specific C<$method_name>. It will I<not> however, attempt to check
179 if the class inherits the method.
181 =item C<get_method ($method_name)>
183 This will return a CODE reference of the specified C<$method_name>,
184 or return undef if that method does not exist.
186 =item C<remove_method ($method_name)>
188 This will attempt to remove a given C<$method_name> from the Class.
189 It will return the CODE reference that it has removed, and will
190 attempt to use B<Sub::Name> to clear the methods associated name.
192 =item C<get_method_list>
194 This will return a list of method names for all I<locally> defined
195 methods. It does B<not> provide a list of all applicable methods,
196 including any inherited ones. If you want a list of all applicable
197 methods, use the C<compute_all_applicable_methods> method.
199 =item C<compute_all_applicable_methods>
201 This will return a list of all the methods names this Class will
202 support, taking into account inheritance. The list will be a list of
203 HASH references, each one containing the following information; method
204 name, the name of the class in which the method lives and a CODE
205 reference for the actual method.
207 =item C<find_all_methods_by_name ($method_name)>
209 This will traverse the inheritence hierarchy and locate all methods
210 with a given C<$method_name>. Similar to
211 C<compute_all_applicable_methods> it returns a list of HASH references
212 with the following information; method name (which will always be the
213 same as C<$method_name>), the name of the class in which the method
214 lives and a CODE reference for the actual method.
220 It should be noted that since there is no one consistent way to define
221 the attributes of a class in Perl 5. These methods can only work with
222 the information given, and can not easily discover information on
227 =item C<add_attribute ($attribute_name, $attribute_meta_object)>
229 This stores a C<$attribute_meta_object> in the Class object and
230 associates it with the C<$attribute_name>. Unlike methods, attributes
231 within the MOP are stored as meta-information only. They will be used
232 later to construct instances from (see C<create_instance> above). More
233 details about the attribute meta-objects can be found in the L<The
234 Attribute protocol> section of this document.
236 =item C<has_attribute ($attribute_name)>
238 Checks to see if this Class has an attribute by the name of
239 C<$attribute_name> and returns a boolean.
241 =item C<get_attribute ($attribute_name)>
243 Returns the attribute meta-object associated with C<$attribute_name>,
244 if none is found, it will return undef.
246 =item C<remove_attribute ($attribute_name)>
248 This will remove the attribute meta-object stored at
249 C<$attribute_name>, then return the removed attribute meta-object.
251 B<NOTE:> Removing an attribute will only affect future instances of
252 the class, it will not make any attempt to remove the attribute from
253 any existing instances of the class.
255 =item C<get_attribute_list>
257 This returns a list of attribute names which are defined in the local
258 class. If you want a list of all applicable attributes for a class,
259 use the C<compute_all_applicable_attributes> method.
261 =item C<compute_all_applicable_attributes>
263 This will traverse the inheritance heirachy and return a list of HASH
264 references for all the applicable attributes for this class. The HASH
265 references will contain the following information; the attribute name,
266 the class which the attribute is associated with and the actual
267 attribute meta-object
275 =item "The Art of the Meta Object Protocol"
277 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
283 Stevan Little E<gt>stevan@iinteractive.comE<lt>
285 =head1 COPYRIGHT AND LICENSE
287 Copyright 2006 by Infinity Interactive, Inc.
289 L<http://www.iinteractive.com>
291 This library is free software; you can redistribute it and/or modify
292 it under the same terms as Perl itself.