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 | |
8b978dd5 |
11 | my %METAS; |
12 | sub UNIVERSAL::meta { |
13 | my $class = blessed($_[0]) || $_[0]; |
14 | $METAS{$class} ||= Class::MOP::Class->initialize($class) |
15 | } |
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 | |
43 | =head2 Who is this module for? |
44 | |
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 |
50 | of method dispatch. |
51 | |
52 | =head1 PROTOCOLS |
53 | |
54 | The protocol is divided into 3 main sub-protocols: |
55 | |
56 | =over 4 |
57 | |
58 | =item The Class protocol |
59 | |
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. |
63 | |
64 | =item The Attribute protocol |
65 | |
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. |
71 | |
72 | =item The Method protocol |
73 | |
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. |
78 | |
79 | =back |
80 | |
81 | What follows is a more detailed documentation on each specific sub |
82 | protocol. |
83 | |
84 | =head2 The Class protocol |
85 | |
138f87a7 |
86 | =head3 Class construction |
94b19069 |
87 | |
88 | These methods handle creating Class objects, which can be used to |
89 | both create new classes, and analyze pre-existing ones. |
90 | |
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. |
94 | |
95 | =over 4 |
96 | |
8b978dd5 |
97 | =item B<create ($package_name, ?$package_version, |
98 | superclasses => ?@superclasses, |
99 | methods => ?%methods, |
100 | attributes => ?%attributes)> |
94b19069 |
101 | |
102 | This returns the basic Class object, bringing the specified |
103 | C<$package_name> into existence and adding any of the |
8b978dd5 |
104 | C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes> |
105 | to it. |
94b19069 |
106 | |
8b978dd5 |
107 | =item B<initialize ($package_name)> |
94b19069 |
108 | |
8b978dd5 |
109 | This initializes a Class object for a given a C<$package_name>. |
94b19069 |
110 | |
138f87a7 |
111 | =back |
112 | |
113 | =head3 Instance construction |
114 | |
115 | =over 4 |
116 | |
8b978dd5 |
117 | =item B<construct_instance ($canidate, %params)> |
138f87a7 |
118 | |
119 | This will construct and instance using the C<$canidate> as storage |
27e31eaf |
120 | (currently only HASH references are supported). This will collect all |
138f87a7 |
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. |
94b19069 |
125 | |
126 | =back |
127 | |
128 | =head3 Informational |
129 | |
130 | =over 4 |
131 | |
8b978dd5 |
132 | =item B<name> |
94b19069 |
133 | |
134 | This is a read-only attribute which returns the package name that |
135 | the Class is stored in. |
136 | |
8b978dd5 |
137 | =item B<version> |
94b19069 |
138 | |
139 | This is a read-only attribute which returns the C<$VERSION> of the |
140 | package the Class is stored in. |
141 | |
142 | =back |
143 | |
144 | =head3 Inheritance Relationships |
145 | |
146 | =over 4 |
147 | |
8b978dd5 |
148 | =item B<superclasses (?@superclasses)> |
94b19069 |
149 | |
150 | This is a read-write attribute which represents the superclass |
151 | relationships of this Class. Basically, it can get and set the |
152 | C<@ISA> for you. |
153 | |
8b978dd5 |
154 | =item B<class_precedence_list> |
94b19069 |
155 | |
156 | This computes the a list of the Class's ancestors in the same order |
157 | in which method dispatch will be done. |
158 | |
159 | =back |
160 | |
161 | =head3 Methods |
162 | |
8b978dd5 |
163 | B<NOTE>: These methods makes every attempt to ignore subroutines |
164 | which have been exported by other packages into this one. |
165 | |
94b19069 |
166 | =over 4 |
167 | |
8b978dd5 |
168 | =item B<add_method ($method_name, $method)> |
94b19069 |
169 | |
170 | This will take a C<$method_name> and CODE reference to that |
171 | C<$method> and install it into the Class. |
172 | |
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 |
176 | such. |
177 | |
8b978dd5 |
178 | =item B<has_method ($method_name)> |
94b19069 |
179 | |
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. |
183 | |
8b978dd5 |
184 | =item B<get_method ($method_name)> |
94b19069 |
185 | |
186 | This will return a CODE reference of the specified C<$method_name>, |
187 | or return undef if that method does not exist. |
188 | |
8b978dd5 |
189 | =item B<remove_method ($method_name)> |
94b19069 |
190 | |
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. |
194 | |
8b978dd5 |
195 | =item B<get_method_list> |
94b19069 |
196 | |
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. |
201 | |
8b978dd5 |
202 | =item B<compute_all_applicable_methods> |
94b19069 |
203 | |
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 |
ca843097 |
207 | name, the name of the class in which the method lives and a CODE |
208 | reference for the actual method. |
94b19069 |
209 | |
8b978dd5 |
210 | =item B<find_all_methods_by_name ($method_name)> |
94b19069 |
211 | |
212 | This will traverse the inheritence hierarchy and locate all methods |
ca843097 |
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. |
94b19069 |
218 | |
219 | =back |
220 | |
8b978dd5 |
221 | =head3 Attributes |
94b19069 |
222 | |
ca843097 |
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 |
226 | their own. |
94b19069 |
227 | |
228 | =over 4 |
229 | |
8b978dd5 |
230 | =item B<add_attribute ($attribute_name, $attribute_meta_object)> |
138f87a7 |
231 | |
ca843097 |
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 |
8b978dd5 |
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. |
138f87a7 |
238 | |
8b978dd5 |
239 | =item B<has_attribute ($attribute_name)> |
138f87a7 |
240 | |
ca843097 |
241 | Checks to see if this Class has an attribute by the name of |
242 | C<$attribute_name> and returns a boolean. |
138f87a7 |
243 | |
8b978dd5 |
244 | =item B<get_attribute ($attribute_name)> |
138f87a7 |
245 | |
ca843097 |
246 | Returns the attribute meta-object associated with C<$attribute_name>, |
247 | if none is found, it will return undef. |
138f87a7 |
248 | |
8b978dd5 |
249 | =item B<remove_attribute ($attribute_name)> |
138f87a7 |
250 | |
ca843097 |
251 | This will remove the attribute meta-object stored at |
252 | C<$attribute_name>, then return the removed attribute meta-object. |
94b19069 |
253 | |
ca843097 |
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. |
94b19069 |
257 | |
8b978dd5 |
258 | =item B<get_attribute_list> |
94b19069 |
259 | |
ca843097 |
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. |
94b19069 |
263 | |
8b978dd5 |
264 | =item B<compute_all_applicable_attributes> |
94b19069 |
265 | |
ca843097 |
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 |
94b19069 |
271 | |
8b978dd5 |
272 | =item B<create_all_accessors> |
273 | |
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). |
277 | |
278 | =back |
279 | |
280 | =head2 The Attribute Protocol |
281 | |
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. |
286 | |
287 | So, all that said, this module attempts to inject some order into this |
288 | chaos, by introducing a more consistent approach. |
289 | |
290 | =head3 Creation |
291 | |
292 | =over 4 |
293 | |
294 | =item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)> |
295 | |
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 |
300 | )); |
301 | |
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 |
307 | )); |
308 | |
309 | =back |
310 | |
311 | =head3 Informational |
312 | |
313 | =over 4 |
314 | |
315 | =item B<name> |
316 | |
317 | =item B<accessor> |
318 | |
319 | =item B<reader> |
320 | |
321 | =item B<writer> |
322 | |
323 | =item B<init_arg> |
324 | |
325 | =item B<default> |
326 | |
94b19069 |
327 | =back |
328 | |
8b978dd5 |
329 | =head3 Informational predicates |
330 | |
331 | =over 4 |
332 | |
333 | =item B<has_accessor> |
334 | |
335 | Returns true if this attribute uses a get/set accessor, and false |
336 | otherwise |
337 | |
338 | =item B<has_reader> |
339 | |
340 | Returns true if this attribute has a reader, and false otherwise |
341 | |
342 | =item B<has_writer> |
343 | |
344 | Returns true if this attribute has a writer, and false otherwise |
345 | |
346 | =item B<has_init_arg> |
347 | |
348 | Returns true if this attribute has a class intialization argument, and |
349 | false otherwise |
350 | |
351 | =item B<has_default> |
352 | |
353 | Returns true if this attribute has a default value, and false |
354 | otherwise. |
355 | |
356 | =back |
357 | |
358 | =head3 Attribute Accessor generation |
359 | |
360 | =over 4 |
361 | |
362 | =item B<generate_accessors> |
363 | |
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. |
367 | |
368 | =back |
369 | |
370 | =head2 The Method Protocol |
371 | |
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 |
375 | methods for it. |
376 | |
94b19069 |
377 | =head1 SEE ALSO |
378 | |
379 | =over 4 |
380 | |
381 | =item "The Art of the Meta Object Protocol" |
382 | |
138f87a7 |
383 | =item "Advances in Object-Oriented Metalevel Architecture and Reflection" |
94b19069 |
384 | |
385 | =back |
386 | |
387 | =head1 AUTHOR |
388 | |
389 | Stevan Little E<gt>stevan@iinteractive.comE<lt> |
390 | |
391 | =head1 COPYRIGHT AND LICENSE |
392 | |
393 | Copyright 2006 by Infinity Interactive, Inc. |
394 | |
395 | L<http://www.iinteractive.com> |
396 | |
397 | This library is free software; you can redistribute it and/or modify |
398 | it under the same terms as Perl itself. |
399 | |
400 | =cut |