Class::MOP - closer
[gitmo/Class-MOP.git] / lib / Class / MOP.pm
1
2 package Class::MOP;
3
4 use strict;
5 use warnings;
6
7 use Scalar::Util 'blessed';
8
9 our $VERSION = '0.01';
10
11 # my %METAS;
12 # sub UNIVERSAL::meta { 
13 #     my $class = blessed($_[0]) || $_[0];
14 #     $METAS{$class} ||= Class::MOP::Class->initialize($class) 
15 # }
16
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 
36 protocol for its manipulation and introspection.
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
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
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
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
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
135 =head3 Class construction
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
146 =item B<create ($package_name, ?$package_version,
147                 superclasses => ?@superclasses, 
148                 methods      => ?%methods, 
149                 attributes   => ?%attributes)>
150
151 This returns the basic Class object, bringing the specified 
152 C<$package_name> into existence and adding any of the 
153 C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes> 
154 to it.
155
156 =item B<initialize ($package_name)>
157
158 This initializes a Class object for a given a C<$package_name>.
159
160 =back
161
162 =head3 Instance construction
163
164 =over 4
165
166 =item B<construct_instance ($canidate, %params)>
167
168 This will construct and instance using the C<$canidate> as storage 
169 (currently only HASH references are supported). This will collect all 
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.
174
175 =back
176
177 =head3 Informational 
178
179 =over 4
180
181 =item B<name>
182
183 This is a read-only attribute which returns the package name that 
184 the Class is stored in.
185
186 =item B<version>
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
197 =item B<superclasses (?@superclasses)>
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
203 =item B<class_precedence_list>
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
214 =item B<add_method ($method_name, $method)>
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
224 =item B<has_method ($method_name)>
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
230 This will correctly handle functions defined outside of the package 
231 that use a fully qualified name (C<sub Package::name { ... }>).
232
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. 
238
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. 
243
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.
247
248 =item B<get_method ($method_name)>
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
253 =item B<remove_method ($method_name)>
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
259 =item B<get_method_list>
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
266 =item B<compute_all_applicable_methods>
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 
271 name, the name of the class in which the method lives and a CODE 
272 reference for the actual method.
273
274 =item B<find_all_methods_by_name ($method_name)>
275
276 This will traverse the inheritence hierarchy and locate all methods 
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.
282
283 =back
284
285 =head3 Attributes
286
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.
291
292 =over 4
293
294 =item B<add_attribute ($attribute_name, $attribute_meta_object)>
295
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 
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.
302
303 =item B<has_attribute ($attribute_name)>
304
305 Checks to see if this Class has an attribute by the name of 
306 C<$attribute_name> and returns a boolean.
307
308 =item B<get_attribute ($attribute_name)>
309
310 Returns the attribute meta-object associated with C<$attribute_name>, 
311 if none is found, it will return undef. 
312
313 =item B<remove_attribute ($attribute_name)>
314
315 This will remove the attribute meta-object stored at 
316 C<$attribute_name>, then return the removed attribute meta-object. 
317
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.
321
322 =item B<get_attribute_list>
323
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.
327
328 =item B<compute_all_applicable_attributes>
329
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
335
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
391 =back
392
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
441 =head1 SEE ALSO
442
443 =over 4
444
445 =item "The Art of the Meta Object Protocol"
446
447 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
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