Commit | Line | Data |
94b19069 |
1 | |
2 | package Class::MOP; |
3 | |
4 | use strict; |
5 | use warnings; |
6 | |
8b978dd5 |
7 | use Scalar::Util 'blessed'; |
8 | |
94b19069 |
9 | our $VERSION = '0.01'; |
10 | |
bfe4d0fc |
11 | # my %METAS; |
12 | # sub UNIVERSAL::meta { |
13 | # my $class = blessed($_[0]) || $_[0]; |
14 | # $METAS{$class} ||= Class::MOP::Class->initialize($class) |
15 | # } |
8b978dd5 |
16 | |
94b19069 |
17 | 1; |
18 | |
19 | __END__ |
20 | |
21 | =pod |
22 | |
23 | =head1 NAME |
24 | |
25 | Class::MOP - A Meta Object Protocol for Perl 5 |
26 | |
27 | =head1 SYNOPSIS |
28 | |
29 | # ... coming soon |
30 | |
31 | =head1 DESCRIPTON |
32 | |
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 |
27e31eaf |
36 | protocol for its manipulation and introspection. |
94b19069 |
37 | |
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. |
42 | |
bfe4d0fc |
43 | =head2 What is a Meta Object Protocol? |
44 | |
45 | A meta object protocol is an API to an object system. |
46 | |
47 | To be more specific, it is a set of abstractions of the components of |
48 | an object system (typically things like; classes, object, methods, |
49 | object attributes, etc.). These abstractions can then be used to both |
50 | inspect and manipulate the object system which they describe. |
51 | |
52 | It can be said that there are two MOPs for any object system; the |
53 | implicit MOP, and the explicit MOP. The implicit MOP handles things |
54 | like method dispatch or inheritance, which happen automatically as |
55 | part of how the object system works. The explicit MOP typically |
56 | handles the introspection/reflection features of the object system. |
57 | All object systems have implicit MOPs, without one, they would not |
58 | work. Explict MOPs however as less common, and depending on the |
59 | language can vary from restrictive (Reflection in Java or C#) to |
60 | wide open (CLOS is a perfect example). |
61 | |
94b19069 |
62 | =head2 Who is this module for? |
63 | |
64 | This module is specifically for anyone who has ever created or |
65 | wanted to create a module for the Class:: namespace. The tools which |
66 | this module will provide will hopefully make it easier to do more |
67 | complex things with Perl 5 classes by removing such barriers as |
68 | the need to hack the symbol tables, or understand the fine details |
69 | of method dispatch. |
70 | |
bfe4d0fc |
71 | =head2 What changes do I have to make to use this module? |
72 | |
73 | This module was designed to be as unintrusive as possible. So many of |
74 | it's features are accessible without B<any> change to your existsing |
75 | code at all. It is meant to be a compliment to your existing code and |
76 | not an intrusion on your code base. |
77 | |
78 | The only feature which requires additions to your code are the |
79 | attribute handling and instance construction features. The only reason |
80 | for this is because Perl 5's object system does not actually have |
81 | these features built in. More information about this feature can be |
82 | found below. |
83 | |
84 | =head2 A Note about Performance? |
85 | |
86 | It is a common misconception that explict MOPs are performance drains. |
87 | But this is not a universal truth at all, it is an side-effect of |
88 | specific implementations. For instance, using Java reflection is much |
89 | slower because the JVM cannot take advantage of any compiler |
90 | optimizations, and the JVM has to deal with much more runtime type |
91 | information as well. Reflection in C# is marginally better as it was |
92 | designed into the language and runtime (the CLR). In contrast, CLOS |
93 | (the Common Lisp Object System) was built to support an explicit MOP, |
94 | and so performance is tuned for it. |
95 | |
96 | This library in particular does it's absolute best to avoid putting |
97 | B<any> drain at all upon your code's performance, while still trying |
98 | to make sure it is fast as well (although only as a secondary |
99 | concern). |
100 | |
94b19069 |
101 | =head1 PROTOCOLS |
102 | |
103 | The protocol is divided into 3 main sub-protocols: |
104 | |
105 | =over 4 |
106 | |
107 | =item The Class protocol |
108 | |
109 | This provides a means of manipulating and introspecting a Perl 5 |
110 | class. It handles all of symbol table hacking for you, and provides |
111 | a rich set of methods that go beyond simple package introspection. |
112 | |
113 | =item The Attribute protocol |
114 | |
115 | This provides a consistent represenation for an attribute of a |
116 | Perl 5 class. Since there are so many ways to create and handle |
117 | atttributes in Perl 5 OO, this attempts to provide as much of a |
118 | unified approach as possible, while giving the freedom and |
119 | flexibility to subclass for specialization. |
120 | |
121 | =item The Method protocol |
122 | |
123 | This provides a means of manipulating and introspecting methods in |
124 | the Perl 5 object system. As with attributes, there are many ways to |
125 | approach this topic, so we try to keep it pretty basic, while still |
126 | making it possible to extend the system in many ways. |
127 | |
128 | =back |
129 | |
130 | What follows is a more detailed documentation on each specific sub |
131 | protocol. |
132 | |
133 | =head2 The Class protocol |
134 | |
138f87a7 |
135 | =head3 Class construction |
94b19069 |
136 | |
137 | These methods handle creating Class objects, which can be used to |
138 | both create new classes, and analyze pre-existing ones. |
139 | |
140 | Class::MOP will internally store weakened references to all the |
141 | instances you create with these methods, so that they do not need |
142 | to be created any more than nessecary. |
143 | |
144 | =over 4 |
145 | |
8b978dd5 |
146 | =item B<create ($package_name, ?$package_version, |
147 | superclasses => ?@superclasses, |
148 | methods => ?%methods, |
149 | attributes => ?%attributes)> |
94b19069 |
150 | |
151 | This returns the basic Class object, bringing the specified |
152 | C<$package_name> into existence and adding any of the |
8b978dd5 |
153 | C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes> |
154 | to it. |
94b19069 |
155 | |
8b978dd5 |
156 | =item B<initialize ($package_name)> |
94b19069 |
157 | |
8b978dd5 |
158 | This initializes a Class object for a given a C<$package_name>. |
94b19069 |
159 | |
138f87a7 |
160 | =back |
161 | |
162 | =head3 Instance construction |
163 | |
164 | =over 4 |
165 | |
8b978dd5 |
166 | =item B<construct_instance ($canidate, %params)> |
138f87a7 |
167 | |
168 | This will construct and instance using the C<$canidate> as storage |
27e31eaf |
169 | (currently only HASH references are supported). This will collect all |
138f87a7 |
170 | the applicable attribute meta-objects and layout out the fields in the |
171 | C<$canidate>, it will then initialize them using either use the |
172 | corresponding key in C<%params> or any default value or initializer |
173 | found in the attribute meta-object. |
94b19069 |
174 | |
175 | =back |
176 | |
177 | =head3 Informational |
178 | |
179 | =over 4 |
180 | |
8b978dd5 |
181 | =item B<name> |
94b19069 |
182 | |
183 | This is a read-only attribute which returns the package name that |
184 | the Class is stored in. |
185 | |
8b978dd5 |
186 | =item B<version> |
94b19069 |
187 | |
188 | This is a read-only attribute which returns the C<$VERSION> of the |
189 | package the Class is stored in. |
190 | |
191 | =back |
192 | |
193 | =head3 Inheritance Relationships |
194 | |
195 | =over 4 |
196 | |
8b978dd5 |
197 | =item B<superclasses (?@superclasses)> |
94b19069 |
198 | |
199 | This is a read-write attribute which represents the superclass |
200 | relationships of this Class. Basically, it can get and set the |
201 | C<@ISA> for you. |
202 | |
8b978dd5 |
203 | =item B<class_precedence_list> |
94b19069 |
204 | |
205 | This computes the a list of the Class's ancestors in the same order |
206 | in which method dispatch will be done. |
207 | |
208 | =back |
209 | |
210 | =head3 Methods |
211 | |
212 | =over 4 |
213 | |
8b978dd5 |
214 | =item B<add_method ($method_name, $method)> |
94b19069 |
215 | |
216 | This will take a C<$method_name> and CODE reference to that |
217 | C<$method> and install it into the Class. |
218 | |
219 | B<NOTE> : This does absolutely nothing special to C<$method> |
220 | other than use B<Sub::Name> to make sure it is tagged with the |
221 | correct name, and therefore show up correctly in stack traces and |
222 | such. |
223 | |
8b978dd5 |
224 | =item B<has_method ($method_name)> |
94b19069 |
225 | |
226 | This just provides a simple way to check if the Class implements |
227 | a specific C<$method_name>. It will I<not> however, attempt to check |
228 | if the class inherits the method. |
229 | |
bfe4d0fc |
230 | This will correctly handle functions defined outside of the package |
231 | that use a fully qualified name (C<sub Package::name { ... }>). |
60d90bbc |
232 | |
bfe4d0fc |
233 | This will correctly handle functions renamed with B<Sub::Name> and |
234 | installed using the symbol tables. However, if you are naming the |
235 | subroutine outside of the package scope, you must use the fully |
236 | qualified name, including the package name, for C<has_method> to |
237 | correctly identify it. |
60d90bbc |
238 | |
bfe4d0fc |
239 | This will attempt to correctly ignore functions imported from other |
240 | packages using B<Exporter>. It breaks down if the function imported |
241 | is an C<__ANON__> sub (such as with C<use constant>), which very well |
242 | may be a valid method being applied to the class. |
60d90bbc |
243 | |
bfe4d0fc |
244 | In short, this method cannot always be trusted to determine if the |
245 | C<$method_name> is actually a method. However, it will DWIM about |
246 | 90% of the time, so it's a small trade off IMO. |
60d90bbc |
247 | |
8b978dd5 |
248 | =item B<get_method ($method_name)> |
94b19069 |
249 | |
250 | This will return a CODE reference of the specified C<$method_name>, |
251 | or return undef if that method does not exist. |
252 | |
8b978dd5 |
253 | =item B<remove_method ($method_name)> |
94b19069 |
254 | |
255 | This will attempt to remove a given C<$method_name> from the Class. |
256 | It will return the CODE reference that it has removed, and will |
257 | attempt to use B<Sub::Name> to clear the methods associated name. |
258 | |
8b978dd5 |
259 | =item B<get_method_list> |
94b19069 |
260 | |
261 | This will return a list of method names for all I<locally> defined |
262 | methods. It does B<not> provide a list of all applicable methods, |
263 | including any inherited ones. If you want a list of all applicable |
264 | methods, use the C<compute_all_applicable_methods> method. |
265 | |
8b978dd5 |
266 | =item B<compute_all_applicable_methods> |
94b19069 |
267 | |
268 | This will return a list of all the methods names this Class will |
269 | support, taking into account inheritance. The list will be a list of |
270 | HASH references, each one containing the following information; method |
ca843097 |
271 | name, the name of the class in which the method lives and a CODE |
272 | reference for the actual method. |
94b19069 |
273 | |
8b978dd5 |
274 | =item B<find_all_methods_by_name ($method_name)> |
94b19069 |
275 | |
276 | This will traverse the inheritence hierarchy and locate all methods |
ca843097 |
277 | with a given C<$method_name>. Similar to |
278 | C<compute_all_applicable_methods> it returns a list of HASH references |
279 | with the following information; method name (which will always be the |
280 | same as C<$method_name>), the name of the class in which the method |
281 | lives and a CODE reference for the actual method. |
94b19069 |
282 | |
283 | =back |
284 | |
8b978dd5 |
285 | =head3 Attributes |
94b19069 |
286 | |
ca843097 |
287 | It should be noted that since there is no one consistent way to define |
288 | the attributes of a class in Perl 5. These methods can only work with |
289 | the information given, and can not easily discover information on |
290 | their own. |
94b19069 |
291 | |
292 | =over 4 |
293 | |
8b978dd5 |
294 | =item B<add_attribute ($attribute_name, $attribute_meta_object)> |
138f87a7 |
295 | |
ca843097 |
296 | This stores a C<$attribute_meta_object> in the Class object and |
297 | associates it with the C<$attribute_name>. Unlike methods, attributes |
298 | within the MOP are stored as meta-information only. They will be used |
8b978dd5 |
299 | later to construct instances from (see C<construct_instance> above). |
300 | More details about the attribute meta-objects can be found in the |
301 | L<The Attribute protocol> section of this document. |
138f87a7 |
302 | |
8b978dd5 |
303 | =item B<has_attribute ($attribute_name)> |
138f87a7 |
304 | |
ca843097 |
305 | Checks to see if this Class has an attribute by the name of |
306 | C<$attribute_name> and returns a boolean. |
138f87a7 |
307 | |
8b978dd5 |
308 | =item B<get_attribute ($attribute_name)> |
138f87a7 |
309 | |
ca843097 |
310 | Returns the attribute meta-object associated with C<$attribute_name>, |
311 | if none is found, it will return undef. |
138f87a7 |
312 | |
8b978dd5 |
313 | =item B<remove_attribute ($attribute_name)> |
138f87a7 |
314 | |
ca843097 |
315 | This will remove the attribute meta-object stored at |
316 | C<$attribute_name>, then return the removed attribute meta-object. |
94b19069 |
317 | |
ca843097 |
318 | B<NOTE:> Removing an attribute will only affect future instances of |
319 | the class, it will not make any attempt to remove the attribute from |
320 | any existing instances of the class. |
94b19069 |
321 | |
8b978dd5 |
322 | =item B<get_attribute_list> |
94b19069 |
323 | |
ca843097 |
324 | This returns a list of attribute names which are defined in the local |
325 | class. If you want a list of all applicable attributes for a class, |
326 | use the C<compute_all_applicable_attributes> method. |
94b19069 |
327 | |
8b978dd5 |
328 | =item B<compute_all_applicable_attributes> |
94b19069 |
329 | |
ca843097 |
330 | This will traverse the inheritance heirachy and return a list of HASH |
331 | references for all the applicable attributes for this class. The HASH |
332 | references will contain the following information; the attribute name, |
333 | the class which the attribute is associated with and the actual |
334 | attribute meta-object |
94b19069 |
335 | |
8b978dd5 |
336 | =item B<create_all_accessors> |
337 | |
338 | This will communicate with all of the classes attributes to create |
339 | and install the appropriate accessors. (see L<The Attribute Protocol> |
340 | below for more details). |
341 | |
342 | =back |
343 | |
344 | =head2 The Attribute Protocol |
345 | |
346 | This protocol is almost entirely an invention of this module. This is |
347 | because Perl 5 does not have consistent notion of what is an attribute |
348 | of a class. There are so many ways in which this is done, and very few |
349 | (if any) are discoverable by this module. |
350 | |
351 | So, all that said, this module attempts to inject some order into this |
352 | chaos, by introducing a more consistent approach. |
353 | |
354 | =head3 Creation |
355 | |
356 | =over 4 |
357 | |
358 | =item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)> |
359 | |
360 | Class::MOP::Attribute->new('$foo' => ( |
361 | accessor => 'foo', # dual purpose get/set accessor |
362 | init_arg => '-foo', # class->new will look for a -foo key |
363 | default => 'BAR IS BAZ!' # if no -foo key is provided, use this |
364 | )); |
365 | |
366 | Class::MOP::Attribute->new('$.bar' => ( |
367 | reader => 'bar', # getter |
368 | writer => 'set_bar', # setter |
369 | init_arg => '-bar', # class->new will look for a -bar key |
370 | # no default value means it is undef |
371 | )); |
372 | |
373 | =back |
374 | |
375 | =head3 Informational |
376 | |
377 | =over 4 |
378 | |
379 | =item B<name> |
380 | |
381 | =item B<accessor> |
382 | |
383 | =item B<reader> |
384 | |
385 | =item B<writer> |
386 | |
387 | =item B<init_arg> |
388 | |
389 | =item B<default> |
390 | |
94b19069 |
391 | =back |
392 | |
8b978dd5 |
393 | =head3 Informational predicates |
394 | |
395 | =over 4 |
396 | |
397 | =item B<has_accessor> |
398 | |
399 | Returns true if this attribute uses a get/set accessor, and false |
400 | otherwise |
401 | |
402 | =item B<has_reader> |
403 | |
404 | Returns true if this attribute has a reader, and false otherwise |
405 | |
406 | =item B<has_writer> |
407 | |
408 | Returns true if this attribute has a writer, and false otherwise |
409 | |
410 | =item B<has_init_arg> |
411 | |
412 | Returns true if this attribute has a class intialization argument, and |
413 | false otherwise |
414 | |
415 | =item B<has_default> |
416 | |
417 | Returns true if this attribute has a default value, and false |
418 | otherwise. |
419 | |
420 | =back |
421 | |
422 | =head3 Attribute Accessor generation |
423 | |
424 | =over 4 |
425 | |
426 | =item B<generate_accessors> |
427 | |
428 | This allows the attribute to generate code for it's own accessor |
429 | methods. This is mostly part of an internal protocol between the class |
430 | and it's own attributes, see the C<create_all_accessors> method above. |
431 | |
432 | =back |
433 | |
434 | =head2 The Method Protocol |
435 | |
436 | This protocol is very small, since methods in Perl 5 are just |
437 | subroutines within the particular package. Basically all we do is to |
438 | bless the subroutine and provide some very simple introspection |
439 | methods for it. |
440 | |
94b19069 |
441 | =head1 SEE ALSO |
442 | |
443 | =over 4 |
444 | |
445 | =item "The Art of the Meta Object Protocol" |
446 | |
138f87a7 |
447 | =item "Advances in Object-Oriented Metalevel Architecture and Reflection" |
94b19069 |
448 | |
449 | =back |
450 | |
451 | =head1 AUTHOR |
452 | |
453 | Stevan Little E<gt>stevan@iinteractive.comE<lt> |
454 | |
455 | =head1 COPYRIGHT AND LICENSE |
456 | |
457 | Copyright 2006 by Infinity Interactive, Inc. |
458 | |
459 | L<http://www.iinteractive.com> |
460 | |
461 | This library is free software; you can redistribute it and/or modify |
462 | it under the same terms as Perl itself. |
463 | |
464 | =cut |