Commit | Line | Data |
94b19069 |
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 | |
6d681766 |
106 | This creates the actual Class object given a C<$package_name>, |
94b19069 |
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 | |
6d681766 |
194 | =item C<find_all_methods_by_name ($method_name)> |
94b19069 |
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; |
6d681766 |
199 | method name (which will always be the same as C<$method_name>), the name of |
94b19069 |
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 | |