7 use Scalar::Util 'blessed';
13 my $class = blessed($_[0]) || $_[0];
14 $METAS{$class} ||= Class::MOP::Class->initialize($class)
25 Class::MOP - A Meta Object Protocol for Perl 5
33 This module is an attempt to create a meta object protocol for the
34 Perl 5 object system. It makes no attempt to change the behavior or
35 characteristics of the Perl 5 object system, only to create a
36 protocol for its manipulation and introspection.
38 That said, it does attempt to create the tools for building a rich
39 set of extensions to the Perl 5 object system. Every attempt has been
40 made for these tools to keep to the spirit of the Perl 5 object
41 system that we all know and love.
43 =head2 Who is this module for?
45 This module is specifically for anyone who has ever created or
46 wanted to create a module for the Class:: namespace. The tools which
47 this module will provide will hopefully make it easier to do more
48 complex things with Perl 5 classes by removing such barriers as
49 the need to hack the symbol tables, or understand the fine details
54 The protocol is divided into 3 main sub-protocols:
58 =item The Class protocol
60 This provides a means of manipulating and introspecting a Perl 5
61 class. It handles all of symbol table hacking for you, and provides
62 a rich set of methods that go beyond simple package introspection.
64 =item The Attribute protocol
66 This provides a consistent represenation for an attribute of a
67 Perl 5 class. Since there are so many ways to create and handle
68 atttributes in Perl 5 OO, this attempts to provide as much of a
69 unified approach as possible, while giving the freedom and
70 flexibility to subclass for specialization.
72 =item The Method protocol
74 This provides a means of manipulating and introspecting methods in
75 the Perl 5 object system. As with attributes, there are many ways to
76 approach this topic, so we try to keep it pretty basic, while still
77 making it possible to extend the system in many ways.
81 What follows is a more detailed documentation on each specific sub
84 =head2 The Class protocol
86 =head3 Class construction
88 These methods handle creating Class objects, which can be used to
89 both create new classes, and analyze pre-existing ones.
91 Class::MOP will internally store weakened references to all the
92 instances you create with these methods, so that they do not need
93 to be created any more than nessecary.
97 =item B<create ($package_name, ?$package_version,
98 superclasses => ?@superclasses,
100 attributes => ?%attributes)>
102 This returns the basic Class object, bringing the specified
103 C<$package_name> into existence and adding any of the
104 C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes>
107 =item B<initialize ($package_name)>
109 This initializes a Class object for a given a C<$package_name>.
113 =head3 Instance construction
117 =item B<construct_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 B<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 B<class_precedence_list>
156 This computes the a list of the Class's ancestors in the same order
157 in which method dispatch will be done.
163 B<NOTE>: These methods makes every attempt to ignore subroutines
164 which have been exported by other packages into this one.
168 =item B<add_method ($method_name, $method)>
170 This will take a C<$method_name> and CODE reference to that
171 C<$method> and install it into the Class.
173 B<NOTE> : This does absolutely nothing special to C<$method>
174 other than use B<Sub::Name> to make sure it is tagged with the
175 correct name, and therefore show up correctly in stack traces and
178 =item B<has_method ($method_name)>
180 This just provides a simple way to check if the Class implements
181 a specific C<$method_name>. It will I<not> however, attempt to check
182 if the class inherits the method.
184 =item B<get_method ($method_name)>
186 This will return a CODE reference of the specified C<$method_name>,
187 or return undef if that method does not exist.
189 =item B<remove_method ($method_name)>
191 This will attempt to remove a given C<$method_name> from the Class.
192 It will return the CODE reference that it has removed, and will
193 attempt to use B<Sub::Name> to clear the methods associated name.
195 =item B<get_method_list>
197 This will return a list of method names for all I<locally> defined
198 methods. It does B<not> provide a list of all applicable methods,
199 including any inherited ones. If you want a list of all applicable
200 methods, use the C<compute_all_applicable_methods> method.
202 =item B<compute_all_applicable_methods>
204 This will return a list of all the methods names this Class will
205 support, taking into account inheritance. The list will be a list of
206 HASH references, each one containing the following information; method
207 name, the name of the class in which the method lives and a CODE
208 reference for the actual method.
210 =item B<find_all_methods_by_name ($method_name)>
212 This will traverse the inheritence hierarchy and locate all methods
213 with a given C<$method_name>. Similar to
214 C<compute_all_applicable_methods> it returns a list of HASH references
215 with the following information; method name (which will always be the
216 same as C<$method_name>), the name of the class in which the method
217 lives and a CODE reference for the actual method.
223 It should be noted that since there is no one consistent way to define
224 the attributes of a class in Perl 5. These methods can only work with
225 the information given, and can not easily discover information on
230 =item B<add_attribute ($attribute_name, $attribute_meta_object)>
232 This stores a C<$attribute_meta_object> in the Class object and
233 associates it with the C<$attribute_name>. Unlike methods, attributes
234 within the MOP are stored as meta-information only. They will be used
235 later to construct instances from (see C<construct_instance> above).
236 More details about the attribute meta-objects can be found in the
237 L<The Attribute protocol> section of this document.
239 =item B<has_attribute ($attribute_name)>
241 Checks to see if this Class has an attribute by the name of
242 C<$attribute_name> and returns a boolean.
244 =item B<get_attribute ($attribute_name)>
246 Returns the attribute meta-object associated with C<$attribute_name>,
247 if none is found, it will return undef.
249 =item B<remove_attribute ($attribute_name)>
251 This will remove the attribute meta-object stored at
252 C<$attribute_name>, then return the removed attribute meta-object.
254 B<NOTE:> Removing an attribute will only affect future instances of
255 the class, it will not make any attempt to remove the attribute from
256 any existing instances of the class.
258 =item B<get_attribute_list>
260 This returns a list of attribute names which are defined in the local
261 class. If you want a list of all applicable attributes for a class,
262 use the C<compute_all_applicable_attributes> method.
264 =item B<compute_all_applicable_attributes>
266 This will traverse the inheritance heirachy and return a list of HASH
267 references for all the applicable attributes for this class. The HASH
268 references will contain the following information; the attribute name,
269 the class which the attribute is associated with and the actual
270 attribute meta-object
272 =item B<create_all_accessors>
274 This will communicate with all of the classes attributes to create
275 and install the appropriate accessors. (see L<The Attribute Protocol>
276 below for more details).
280 =head2 The Attribute Protocol
282 This protocol is almost entirely an invention of this module. This is
283 because Perl 5 does not have consistent notion of what is an attribute
284 of a class. There are so many ways in which this is done, and very few
285 (if any) are discoverable by this module.
287 So, all that said, this module attempts to inject some order into this
288 chaos, by introducing a more consistent approach.
294 =item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)>
296 Class::MOP::Attribute->new('$foo' => (
297 accessor => 'foo', # dual purpose get/set accessor
298 init_arg => '-foo', # class->new will look for a -foo key
299 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
302 Class::MOP::Attribute->new('$.bar' => (
303 reader => 'bar', # getter
304 writer => 'set_bar', # setter
305 init_arg => '-bar', # class->new will look for a -bar key
306 # no default value means it is undef
329 =head3 Informational predicates
333 =item B<has_accessor>
335 Returns true if this attribute uses a get/set accessor, and false
340 Returns true if this attribute has a reader, and false otherwise
344 Returns true if this attribute has a writer, and false otherwise
346 =item B<has_init_arg>
348 Returns true if this attribute has a class intialization argument, and
353 Returns true if this attribute has a default value, and false
358 =head3 Attribute Accessor generation
362 =item B<generate_accessors>
364 This allows the attribute to generate code for it's own accessor
365 methods. This is mostly part of an internal protocol between the class
366 and it's own attributes, see the C<create_all_accessors> method above.
370 =head2 The Method Protocol
372 This protocol is very small, since methods in Perl 5 are just
373 subroutines within the particular package. Basically all we do is to
374 bless the subroutine and provide some very simple introspection
381 =item "The Art of the Meta Object Protocol"
383 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
389 Stevan Little E<gt>stevan@iinteractive.comE<lt>
391 =head1 COPYRIGHT AND LICENSE
393 Copyright 2006 by Infinity Interactive, Inc.
395 L<http://www.iinteractive.com>
397 This library is free software; you can redistribute it and/or modify
398 it under the same terms as Perl itself.