8a5a2148ceca442e3e05f456a34dc064468c0d12
[gitmo/Class-MOP.git] / lib / Class / MOP.pm
1
2 package Class::MOP;
3
4 use strict;
5 use warnings;
6
7 our $VERSION = '0.01';
8
9 1;
10
11 __END__
12
13 =pod
14
15 =head1 NAME 
16
17 Class::MOP - A Meta Object Protocol for Perl 5
18
19 =head1 SYNOPSIS
20
21   # ... coming soon
22
23 =head1 DESCRIPTON
24
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 it's manipulation and introspection.
29
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.
34
35 =head2 Who is this module for?
36
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 
42 of method dispatch. 
43
44 =head1 PROTOCOLS
45
46 The protocol is divided into 3 main sub-protocols:
47
48 =over 4
49
50 =item The Class protocol
51
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.
55
56 =item The Attribute protocol
57
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.
63
64 =item The Method protocol
65
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.
70
71 =back
72
73 What follows is a more detailed documentation on each specific sub 
74 protocol.
75
76 =head2 The Class protocol
77
78 =head3 Creation
79
80 These methods handle creating Class objects, which can be used to 
81 both create new classes, and analyze pre-existing ones. 
82
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. 
86
87 =over 4
88
89 =item B<create ($package_name, ?@superclasses, ?%methods, ?%attributes)>
90
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.
94
95 =item B<load ($package_name)>
96
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). 
100
101 B<NOTE>: This method makes every attempt to ignore subroutines
102 which have been exported by other packages into this one.
103
104 =item B<initialize ($package_name, @superclasses, %methods, %attributes)>
105
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 
109 C<create>.
110
111 This method also stores the Class object for you inside Class::MOP.
112
113 =back
114
115 =head3 Informational 
116
117 =over 4
118
119 =item C<name>
120
121 This is a read-only attribute which returns the package name that 
122 the Class is stored in.
123
124 =item C<version>
125
126 This is a read-only attribute which returns the C<$VERSION> of the 
127 package the Class is stored in.
128
129 =back
130
131 =head3 Inheritance Relationships
132
133 =over 4
134
135 =item C<superclasses (?@superclasses)>
136
137 This is a read-write attribute which represents the superclass 
138 relationships of this Class. Basically, it can get and set the 
139 C<@ISA> for you.
140
141 =item C<class_precendence_list>
142
143 This computes the a list of the Class's ancestors in the same order 
144 in which method dispatch will be done. 
145
146 =back
147
148 =head3 Methods
149
150 =over 4
151
152 =item C<add_method ($method_name, $method)>
153
154 This will take a C<$method_name> and CODE reference to that 
155 C<$method> and install it into the Class. 
156
157 B<NOTE> : This does absolutely nothing special to C<$method> 
158 other than use B<Sub::Name> to make sure it is tagged with the 
159 correct name, and therefore show up correctly in stack traces and 
160 such.
161
162 =item C<has_method ($method_name)>
163
164 This just provides a simple way to check if the Class implements 
165 a specific C<$method_name>. It will I<not> however, attempt to check 
166 if the class inherits the method.
167
168 =item C<get_method ($method_name)>
169
170 This will return a CODE reference of the specified C<$method_name>, 
171 or return undef if that method does not exist.
172
173 =item C<remove_method ($method_name)>
174
175 This will attempt to remove a given C<$method_name> from the Class. 
176 It will return the CODE reference that it has removed, and will 
177 attempt to use B<Sub::Name> to clear the methods associated name.
178
179 =item C<get_method_list>
180
181 This will return a list of method names for all I<locally> defined 
182 methods. It does B<not> provide a list of all applicable methods, 
183 including any inherited ones. If you want a list of all applicable 
184 methods, use the C<compute_all_applicable_methods> method.
185
186 =item C<compute_all_applicable_methods>
187
188 This will return a list of all the methods names this Class will 
189 support, taking into account inheritance. The list will be a list of 
190 HASH references, each one containing the following information; method 
191 name, the name of the class in which the method lives and a CODE reference 
192 for the actual method.
193
194 =item C<find_all_methods_by_name ($method_name)>
195
196 This will traverse the inheritence hierarchy and locate all methods 
197 with a given C<$method_name>. Similar to C<compute_all_applicable_methods>
198 it returns a list of HASH references with the following information; 
199 method name (which will always be the same as C<$method_name>), the name of 
200 the class in which the method lives and a CODE reference for the actual method.
201
202 =back
203
204 =head2 Attributes
205
206 It should be noted that since there is no one consistent way to define the 
207 attributes of a class in Perl 5. These methods can only work with the 
208 information given, and can not easily discover information on their own.
209
210 =over 4
211
212 =item C<>
213
214 =item C<>
215
216 =item C<>
217
218 =item C<>
219
220 =item C<>
221
222 =item C<>
223
224 =back
225
226 =head1 SEE ALSO
227
228 =over 4
229
230 =item "The Art of the Meta Object Protocol"
231
232 =item CLOS
233
234 =back
235
236 =head1 AUTHOR
237
238 Stevan Little E<gt>stevan@iinteractive.comE<lt>
239
240 =head1 COPYRIGHT AND LICENSE
241
242 Copyright 2006 by Infinity Interactive, Inc.
243
244 L<http://www.iinteractive.com>
245
246 This library is free software; you can redistribute it and/or modify
247 it under the same terms as Perl itself. 
248
249 =cut
250
251
252