Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "Class::MOP::Class 3" |
132 | .TH Class::MOP::Class 3 "2009-11-18" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Class::MOP::Class \- Class Meta Object |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 2 |
138 | \& # assuming that class Foo |
139 | \& # has been defined, you can |
140 | .Ve |
141 | .PP |
142 | .Vb 1 |
143 | \& # use this for introspection ... |
144 | .Ve |
145 | .PP |
146 | .Vb 2 |
147 | \& # add a method to Foo ... |
148 | \& Foo\->meta\->add_method( 'bar' => sub {...} ) |
149 | .Ve |
150 | .PP |
151 | .Vb 3 |
152 | \& # get a list of all the classes searched |
153 | \& # the method dispatcher in the correct order |
154 | \& Foo\->meta\->class_precedence_list() |
155 | .Ve |
156 | .PP |
157 | .Vb 2 |
158 | \& # remove a method from Foo |
159 | \& Foo\->meta\->remove_method('bar'); |
160 | .Ve |
161 | .PP |
162 | .Vb 1 |
163 | \& # or use this to actually create classes ... |
164 | .Ve |
165 | .PP |
166 | .Vb 14 |
167 | \& Class::MOP::Class\->create( |
168 | \& 'Bar' => ( |
169 | \& version => '0.01', |
170 | \& superclasses => ['Foo'], |
171 | \& attributes => [ |
172 | \& Class::MOP::Attribute\->new('$bar'), |
173 | \& Class::MOP::Attribute\->new('$baz'), |
174 | \& ], |
175 | \& methods => { |
176 | \& calculate_bar => sub {...}, |
177 | \& construct_baz => sub {...} |
178 | \& } |
179 | \& ) |
180 | \& ); |
181 | .Ve |
182 | .SH "DESCRIPTION" |
183 | .IX Header "DESCRIPTION" |
184 | The Class Protocol is the largest and most complex part of the |
185 | Class::MOP meta-object protocol. It controls the introspection and |
186 | manipulation of Perl 5 classes, and it can create them as well. The |
187 | best way to understand what this module can do is to read the |
188 | documentation for each of its methods. |
189 | .SH "INHERITANCE" |
190 | .IX Header "INHERITANCE" |
191 | \&\f(CW\*(C`Class::MOP::Class\*(C'\fR is a subclass of Class::MOP::Module. |
192 | .SH "METHODS" |
193 | .IX Header "METHODS" |
194 | .Sh "Class construction" |
195 | .IX Subsection "Class construction" |
196 | These methods all create new \f(CW\*(C`Class::MOP::Class\*(C'\fR objects. These |
197 | objects can represent existing classes or they can be used to create |
198 | new classes from scratch. |
199 | .PP |
200 | The metaclass object for a given class is a singleton. If you attempt |
201 | to create a metaclass for the same class twice, you will just get the |
202 | existing object. |
203 | .ie n .IP "\fBClass::MOP::Class\->create($package_name, \fB%options\fB)\fR" 4 |
204 | .el .IP "\fBClass::MOP::Class\->create($package_name, \f(CB%options\fB)\fR" 4 |
205 | .IX Item "Class::MOP::Class->create($package_name, %options)" |
206 | This method creates a new \f(CW\*(C`Class::MOP::Class\*(C'\fR object with the given |
207 | package name. It accepts a number of options: |
208 | .RS 4 |
209 | .IP "* version" 8 |
210 | .IX Item "version" |
211 | An optional version number for the newly created package. |
212 | .IP "* authority" 8 |
213 | .IX Item "authority" |
214 | An optional authority for the newly created package. |
215 | .IP "* superclasses" 8 |
216 | .IX Item "superclasses" |
217 | An optional array reference of superclass names. |
218 | .IP "* methods" 8 |
219 | .IX Item "methods" |
220 | An optional hash reference of methods for the class. The keys of the |
221 | hash reference are method names and values are subroutine references. |
222 | .IP "* attributes" 8 |
223 | .IX Item "attributes" |
224 | An optional array reference of Class::MOP::Attribute objects. |
225 | .RE |
226 | .RS 4 |
227 | .RE |
228 | .IP "\fBClass::MOP::Class\->create_anon_class(%options)\fR" 4 |
229 | .IX Item "Class::MOP::Class->create_anon_class(%options)" |
230 | This method works just like \f(CW\*(C`Class::MOP::Class\->create\*(C'\fR but it |
231 | creates an \*(L"anonymous\*(R" class. In fact, the class does have a name, but |
232 | that name is a unique name generated internally by this module. |
233 | .Sp |
234 | It accepts the same \f(CW\*(C`superclasses\*(C'\fR, \f(CW\*(C`methods\*(C'\fR, and \f(CW\*(C`attributes\*(C'\fR |
235 | parameters that \f(CW\*(C`create\*(C'\fR accepts. |
236 | .Sp |
237 | Anonymous classes are destroyed once the metaclass they are attached |
238 | to goes out of scope, and will be removed from Perl's internal symbol |
239 | table. |
240 | .Sp |
241 | All instances of an anonymous class keep a special reference to the |
242 | metaclass object, which prevents the metaclass from going out of scope |
243 | while any instances exist. |
244 | .Sp |
245 | This only works if the instance is based on a hash reference, however. |
246 | .ie n .IP "\fBClass::MOP::Class\->initialize($package_name, \fB%options\fB)\fR" 4 |
247 | .el .IP "\fBClass::MOP::Class\->initialize($package_name, \f(CB%options\fB)\fR" 4 |
248 | .IX Item "Class::MOP::Class->initialize($package_name, %options)" |
249 | This method will initialize a \f(CW\*(C`Class::MOP::Class\*(C'\fR object for the |
250 | named package. Unlike \f(CW\*(C`create\*(C'\fR, this method \fIwill not\fR create a new |
251 | class. |
252 | .Sp |
253 | The purpose of this method is to retrieve a \f(CW\*(C`Class::MOP::Class\*(C'\fR |
254 | object for introspecting an existing class. |
255 | .Sp |
256 | If an existing \f(CW\*(C`Class::MOP::Class\*(C'\fR object exists for the named |
257 | package, it will be returned, and any options provided will be |
258 | ignored! |
259 | .Sp |
260 | If the object does not yet exist, it will be created. |
261 | .Sp |
262 | The valid options that can be passed to this method are |
263 | \&\f(CW\*(C`attribute_metaclass\*(C'\fR, \f(CW\*(C`method_metaclass\*(C'\fR, |
264 | \&\f(CW\*(C`wrapped_method_metaclass\*(C'\fR, and \f(CW\*(C`instance_metaclass\*(C'\fR. These are all |
265 | optional, and default to the appropriate class in the \f(CW\*(C`Class::MOP\*(C'\fR |
266 | distribution. |
267 | .Sh "Object instance construction and cloning" |
268 | .IX Subsection "Object instance construction and cloning" |
269 | These methods are all related to creating and/or cloning object |
270 | instances. |
271 | .ie n .IP "\fB$metaclass\->clone_object($instance, \fB%params\fB)\fR" 4 |
272 | .el .IP "\fB$metaclass\->clone_object($instance, \f(CB%params\fB)\fR" 4 |
273 | .IX Item "$metaclass->clone_object($instance, %params)" |
274 | This method clones an existing object instance. Any parameters you |
275 | provide are will override existing attribute values in the object. |
276 | .Sp |
277 | This is a convenience method for cloning an object instance, then |
278 | blessing it into the appropriate package. |
279 | .Sp |
280 | You could implement a clone method in your class, using this method: |
281 | .Sp |
282 | .Vb 4 |
283 | \& sub clone { |
284 | \& my ($self, %params) = @_; |
285 | \& $self\->meta\->clone_object($self, %params); |
286 | \& } |
287 | .Ve |
288 | .ie n .IP "\fB$metaclass\->rebless_instance($instance, \fB%params\fB)\fR" 4 |
289 | .el .IP "\fB$metaclass\->rebless_instance($instance, \f(CB%params\fB)\fR" 4 |
290 | .IX Item "$metaclass->rebless_instance($instance, %params)" |
291 | This method changes the class of \f(CW$instance\fR to the metaclass's class. |
292 | .Sp |
293 | You can only rebless an instance into a subclass of its current |
294 | class. If you pass any additional parameters, these will be treated |
295 | like constructor parameters and used to initialize the object's |
296 | attributes. Any existing attributes that are already set will be |
297 | overwritten. |
298 | .Sp |
299 | Before reblessing the instance, this method will call |
300 | \&\f(CW\*(C`rebless_instance_away\*(C'\fR on the instance's current metaclass. This method |
301 | will be passed the instance, the new metaclass, and any parameters |
302 | specified to \f(CW\*(C`rebless_instance\*(C'\fR. By default, \f(CW\*(C`rebless_instance_away\*(C'\fR |
303 | does nothing; it is merely a hook. |
304 | .IP "\fB$metaclass\->new_object(%params)\fR" 4 |
305 | .IX Item "$metaclass->new_object(%params)" |
306 | This method is used to create a new object of the metaclass's |
307 | class. Any parameters you provide are used to initialize the |
308 | instance's attributes. A special \f(CW\*(C`_\|_INSTANCE_\|_\*(C'\fR key can be passed to |
309 | provide an already generated instance, rather than having Class::MOP |
310 | generate it for you. This is mostly useful for using Class::MOP with |
311 | foreign classes which generate instances using their own constructors. |
312 | .IP "\fB$metaclass\->instance_metaclass\fR" 4 |
313 | .IX Item "$metaclass->instance_metaclass" |
314 | Returns the class name of the instance metaclass. See |
315 | Class::MOP::Instance for more information on the instance |
316 | metaclass. |
317 | .IP "\fB$metaclass\->get_meta_instance\fR" 4 |
318 | .IX Item "$metaclass->get_meta_instance" |
319 | Returns an instance of the \f(CW\*(C`instance_metaclass\*(C'\fR to be used in the |
320 | construction of a new instance of the class. |
321 | .Sh "Informational predicates" |
322 | .IX Subsection "Informational predicates" |
323 | These are a few predicate methods for asking information about the |
324 | class itself. |
325 | .IP "\fB$metaclass\->is_anon_class\fR" 4 |
326 | .IX Item "$metaclass->is_anon_class" |
327 | This returns true if the class was created by calling \f(CW\*(C`Class::MOP::Class\->create_anon_class\*(C'\fR. |
328 | .IP "\fB$metaclass\->is_mutable\fR" 4 |
329 | .IX Item "$metaclass->is_mutable" |
330 | This returns true if the class is still mutable. |
331 | .IP "\fB$metaclass\->is_immutable\fR" 4 |
332 | .IX Item "$metaclass->is_immutable" |
333 | This returns true if the class has been made immutable. |
334 | .IP "\fB$metaclass\->is_pristine\fR" 4 |
335 | .IX Item "$metaclass->is_pristine" |
336 | A class is \fInot\fR pristine if it has non-inherited attributes or if it |
337 | has any generated methods. |
338 | .Sh "Inheritance Relationships" |
339 | .IX Subsection "Inheritance Relationships" |
340 | .IP "\fB$metaclass\->superclasses(@superclasses)\fR" 4 |
341 | .IX Item "$metaclass->superclasses(@superclasses)" |
342 | This is a read-write accessor which represents the superclass |
343 | relationships of the metaclass's class. |
344 | .Sp |
345 | This is basically sugar around getting and setting \f(CW@ISA\fR. |
346 | .IP "\fB$metaclass\->class_precedence_list\fR" 4 |
347 | .IX Item "$metaclass->class_precedence_list" |
348 | This returns a list of all of the class's ancestor classes. The |
349 | classes are returned in method dispatch order. |
350 | .IP "\fB$metaclass\->linearized_isa\fR" 4 |
351 | .IX Item "$metaclass->linearized_isa" |
352 | This returns a list based on \f(CW\*(C`class_precedence_list\*(C'\fR but with all |
353 | duplicates removed. |
354 | .IP "\fB$metaclass\->subclasses\fR" 4 |
355 | .IX Item "$metaclass->subclasses" |
356 | This returns a list of all subclasses for this class, even indirect |
357 | subclasses. |
358 | .IP "\fB$metaclass\->direct_subclasses\fR" 4 |
359 | .IX Item "$metaclass->direct_subclasses" |
360 | This returns a list of immediate subclasses for this class, which does not |
361 | include indirect subclasses. |
362 | .Sh "Method introspection" |
363 | .IX Subsection "Method introspection" |
364 | See \*(L"Method introspection and creation\*(R" in Class::MOP::Package for |
365 | methods that operate only on the current class. Class::MOP::Class adds |
366 | introspection capabilities that take inheritance into account. |
367 | .IP "\fB$metaclass\->get_all_methods\fR" 4 |
368 | .IX Item "$metaclass->get_all_methods" |
369 | This will traverse the inheritance hierarchy and return a list of all |
370 | the Class::MOP::Method objects for this class and its parents. |
371 | .IP "\fB$metaclass\->find_method_by_name($method_name)\fR" 4 |
372 | .IX Item "$metaclass->find_method_by_name($method_name)" |
373 | This will return a Class::MOP::Method for the specified |
374 | \&\f(CW$method_name\fR. If the class does not have the specified method, it |
375 | returns \f(CW\*(C`undef\*(C'\fR |
376 | .Sp |
377 | Unlike \f(CW\*(C`get_method\*(C'\fR, this method \fIwill\fR look for the named method in |
378 | superclasses. |
379 | .IP "\fB$metaclass\->get_all_method_names\fR" 4 |
380 | .IX Item "$metaclass->get_all_method_names" |
381 | This will return a list of method \fInames\fR for all of this class's |
382 | methods, including inherited methods. |
383 | .IP "\fB$metaclass\->find_all_methods_by_name($method_name)\fR" 4 |
384 | .IX Item "$metaclass->find_all_methods_by_name($method_name)" |
385 | This method looks for the named method in the class and all of its |
386 | parents. It returns every matching method it finds in the inheritance |
387 | tree, so it returns a list of methods. |
388 | .Sp |
389 | Each method is returned as a hash reference with three keys. The keys |
390 | are \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`class\*(C'\fR, and \f(CW\*(C`code\*(C'\fR. The \f(CW\*(C`code\*(C'\fR key has a |
391 | Class::MOP::Method object as its value. |
392 | .Sp |
393 | The list of methods is distinct. |
394 | .IP "\fB$metaclass\->find_next_method_by_name($method_name)\fR" 4 |
395 | .IX Item "$metaclass->find_next_method_by_name($method_name)" |
396 | This method returns the first method in any superclass matching the |
397 | given name. It is effectively the method that \f(CW\*(C`SUPER::$method_name\*(C'\fR |
398 | would dispatch to. |
399 | .Sh "Attribute introspection and creation" |
400 | .IX Subsection "Attribute introspection and creation" |
401 | Because Perl 5 does not have a core concept of attributes in classes, |
402 | we can only return information about attributes which have been added |
403 | via this class's methods. We cannot discover information about |
404 | attributes which are defined in terms of \*(L"regular\*(R" Perl 5 methods. |
405 | .IP "\fB$metaclass\->get_attribute($attribute_name)\fR" 4 |
406 | .IX Item "$metaclass->get_attribute($attribute_name)" |
407 | This will return a Class::MOP::Attribute for the specified |
408 | \&\f(CW$attribute_name\fR. If the class does not have the specified |
409 | attribute, it returns \f(CW\*(C`undef\*(C'\fR. |
410 | .Sp |
411 | \&\s-1NOTE\s0 that get_attribute does not search superclasses, for that you |
412 | need to use \f(CW\*(C`find_attribute_by_name\*(C'\fR. |
413 | .IP "\fB$metaclass\->has_attribute($attribute_name)\fR" 4 |
414 | .IX Item "$metaclass->has_attribute($attribute_name)" |
415 | Returns a boolean indicating whether or not the class defines the |
416 | named attribute. It does not include attributes inherited from parent |
417 | classes. |
418 | .IP "\fB$metaclass\->get_attribute_list\fR" 4 |
419 | .IX Item "$metaclass->get_attribute_list" |
420 | This will return a list of attributes \fInames\fR for all attributes |
421 | defined in this class. |
422 | .IP "\fB$metaclass\->get_all_attributes\fR" 4 |
423 | .IX Item "$metaclass->get_all_attributes" |
424 | This will traverse the inheritance hierarchy and return a list of all |
425 | the Class::MOP::Attribute objects for this class and its parents. |
426 | .IP "\fB$metaclass\->find_attribute_by_name($attribute_name)\fR" 4 |
427 | .IX Item "$metaclass->find_attribute_by_name($attribute_name)" |
428 | This will return a Class::MOP::Attribute for the specified |
429 | \&\f(CW$attribute_name\fR. If the class does not have the specified |
430 | attribute, it returns \f(CW\*(C`undef\*(C'\fR. |
431 | .Sp |
432 | Unlike \f(CW\*(C`get_attribute\*(C'\fR, this attribute \fIwill\fR look for the named |
433 | attribute in superclasses. |
434 | .IP "\fB$metaclass\->add_attribute(...)\fR" 4 |
435 | .IX Item "$metaclass->add_attribute(...)" |
436 | This method accepts either an existing Class::MOP::Attribute |
437 | object or parameters suitable for passing to that class's \f(CW\*(C`new\*(C'\fR |
438 | method. |
439 | .Sp |
440 | The attribute provided will be added to the class. |
441 | .Sp |
442 | Any accessor methods defined by the attribute will be added to the |
443 | class when the attribute is added. |
444 | .Sp |
445 | If an attribute of the same name already exists, the old attribute |
446 | will be removed first. |
447 | .IP "\fB$metaclass\->remove_attribute($attribute_name)\fR" 4 |
448 | .IX Item "$metaclass->remove_attribute($attribute_name)" |
449 | This will remove the named attribute from the class, and |
450 | Class::MOP::Attribute object. |
451 | .Sp |
452 | Removing an attribute also removes any accessor methods defined by the |
453 | attribute. |
454 | .Sp |
455 | However, note that removing an attribute will only affect \fIfuture\fR |
456 | object instances created for this class, not existing instances. |
457 | .IP "\fB$metaclass\->attribute_metaclass\fR" 4 |
458 | .IX Item "$metaclass->attribute_metaclass" |
459 | Returns the class name of the attribute metaclass for this class. By |
460 | default, this is Class::MOP::Attribute. |
461 | .Sh "Class Immutability" |
462 | .IX Subsection "Class Immutability" |
463 | Making a class immutable \*(L"freezes\*(R" the class definition. You can no |
464 | longer call methods which alter the class, such as adding or removing |
465 | methods or attributes. |
466 | .PP |
467 | Making a class immutable lets us optimize the class by inlining some |
468 | methods, and also allows us to optimize some methods on the metaclass |
469 | object itself. |
470 | .PP |
471 | After immutabilization, the metaclass object will cache most informational |
472 | methods that returns information about methods or attributes. Methods which |
473 | would alter the class, such as \f(CW\*(C`add_attribute\*(C'\fR and \f(CW\*(C`add_method\*(C'\fR, will |
474 | throw an error on an immutable metaclass object. |
475 | .PP |
476 | The immutabilization system in Moose takes much greater advantage |
477 | of the inlining features than Class::MOP itself does. |
478 | .IP "\fB$metaclass\->make_immutable(%options)\fR" 4 |
479 | .IX Item "$metaclass->make_immutable(%options)" |
480 | This method will create an immutable transformer and use it to make |
481 | the class and its metaclass object immutable. |
482 | .Sp |
483 | This method accepts the following options: |
484 | .RS 4 |
485 | .IP "* inline_accessors" 8 |
486 | .IX Item "inline_accessors" |
487 | .PD 0 |
488 | .IP "* inline_constructor" 8 |
489 | .IX Item "inline_constructor" |
490 | .IP "* inline_destructor" 8 |
491 | .IX Item "inline_destructor" |
492 | .PD |
493 | These are all booleans indicating whether the specified method(s) |
494 | should be inlined. |
495 | .Sp |
496 | By default, accessors and the constructor are inlined, but not the |
497 | destructor. |
498 | .IP "* immutable_trait" 8 |
499 | .IX Item "immutable_trait" |
500 | The name of a class which will be used as a parent class for the |
501 | metaclass object being made immutable. This \*(L"trait\*(R" implements the |
502 | post-immutability functionality of the metaclass (but not the |
503 | transformation itself). |
504 | .Sp |
505 | This defaults to Class::MOP::Class::Immutable::Trait. |
506 | .IP "* constructor_name" 8 |
507 | .IX Item "constructor_name" |
508 | This is the constructor method name. This defaults to \*(L"new\*(R". |
509 | .IP "* constructor_class" 8 |
510 | .IX Item "constructor_class" |
511 | The name of the method metaclass for constructors. It will be used to |
512 | generate the inlined constructor. This defaults to |
513 | \&\*(L"Class::MOP::Method::Constructor\*(R". |
514 | .IP "* replace_constructor" 8 |
515 | .IX Item "replace_constructor" |
516 | This is a boolean indicating whether an existing constructor should be |
517 | replaced when inlining a constructor. This defaults to false. |
518 | .IP "* destructor_class" 8 |
519 | .IX Item "destructor_class" |
520 | The name of the method metaclass for destructors. It will be used to |
521 | generate the inlined destructor. This defaults to |
522 | \&\*(L"Class::MOP::Method::Denstructor\*(R". |
523 | .IP "* replace_destructor" 8 |
524 | .IX Item "replace_destructor" |
525 | This is a boolean indicating whether an existing destructor should be |
526 | replaced when inlining a destructor. This defaults to false. |
527 | .RE |
528 | .RS 4 |
529 | .RE |
530 | .IP "\fB$metaclass\->immutable_options\fR" 4 |
531 | .IX Item "$metaclass->immutable_options" |
532 | Returns a hash of the options used when making the class immutable, including |
533 | both defaults and anything supplied by the user in the call to \f(CW\*(C`$metaclass\->make_immutable\*(C'\fR. This is useful if you need to temporarily make |
534 | a class mutable and then restore immutability as it was before. |
535 | .IP "\fB$metaclass\->make_mutable\fR" 4 |
536 | .IX Item "$metaclass->make_mutable" |
537 | Calling this method reverse the immutabilization transformation. |
538 | .Sh "Method Modifiers" |
539 | .IX Subsection "Method Modifiers" |
540 | Method modifiers are hooks which allow a method to be wrapped with |
541 | \&\fIbefore\fR, \fIafter\fR and \fIaround\fR method modifiers. Every time a |
542 | method is called, its modifiers are also called. |
543 | .PP |
544 | A class can modify its own methods, as well as methods defined in |
545 | parent classes. |
546 | .PP |
547 | \fIHow method modifiers work?\fR |
548 | .IX Subsection "How method modifiers work?" |
549 | .PP |
550 | Method modifiers work by wrapping the original method and then |
551 | replacing it in the class's symbol table. The wrappers will handle |
552 | calling all the modifiers in the appropriate order and preserving the |
553 | calling context for the original method. |
554 | .PP |
555 | The return values of \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR modifiers are |
556 | ignored. This is because their purpose is \fBnot\fR to filter the input |
557 | and output of the primary method (this is done with an \fIaround\fR |
558 | modifier). |
559 | .PP |
560 | This may seem like an odd restriction to some, but doing this allows |
561 | for simple code to be added at the beginning or end of a method call |
562 | without altering the function of the wrapped method or placing any |
563 | extra responsibility on the code of the modifier. |
564 | .PP |
565 | Of course if you have more complex needs, you can use the \f(CW\*(C`around\*(C'\fR |
566 | modifier which allows you to change both the parameters passed to the |
567 | wrapped method, as well as its return value. |
568 | .PP |
569 | Before and around modifiers are called in last-defined-first-called |
570 | order, while after modifiers are called in first-defined-first-called |
571 | order. So the call tree might looks something like this: |
572 | .PP |
573 | .Vb 9 |
574 | \& before 2 |
575 | \& before 1 |
576 | \& around 2 |
577 | \& around 1 |
578 | \& primary |
579 | \& around 1 |
580 | \& around 2 |
581 | \& after 1 |
582 | \& after 2 |
583 | .Ve |
584 | .PP |
585 | \fIWhat is the performance impact?\fR |
586 | .IX Subsection "What is the performance impact?" |
587 | .PP |
588 | Of course there is a performance cost associated with method |
589 | modifiers, but we have made every effort to make that cost directly |
590 | proportional to the number of modifier features you use. |
591 | .PP |
592 | The wrapping method does its best to \fBonly\fR do as much work as it |
593 | absolutely needs to. In order to do this we have moved some of the |
594 | performance costs to set-up time, where they are easier to amortize. |
595 | .PP |
596 | All this said, our benchmarks have indicated the following: |
597 | .PP |
598 | .Vb 5 |
599 | \& simple wrapper with no modifiers 100% slower |
600 | \& simple wrapper with simple before modifier 400% slower |
601 | \& simple wrapper with simple after modifier 450% slower |
602 | \& simple wrapper with simple around modifier 500\-550% slower |
603 | \& simple wrapper with all 3 modifiers 1100% slower |
604 | .Ve |
605 | .PP |
606 | These numbers may seem daunting, but you must remember, every feature |
607 | comes with some cost. To put things in perspective, just doing a |
608 | simple \f(CW\*(C`AUTOLOAD\*(C'\fR which does nothing but extract the name of the |
609 | method called and return it costs about 400% over a normal method |
610 | call. |
611 | .ie n .IP "\fB$metaclass\->add_before_method_modifier($method_name, \fB$code\fB)\fR" 4 |
612 | .el .IP "\fB$metaclass\->add_before_method_modifier($method_name, \f(CB$code\fB)\fR" 4 |
613 | .IX Item "$metaclass->add_before_method_modifier($method_name, $code)" |
614 | This wraps the specified method with the supplied subroutine |
615 | reference. The modifier will be called as a method itself, and will |
616 | receive the same arguments as are passed to the method. |
617 | .Sp |
618 | When the modifier exits, the wrapped method will be called. |
619 | .Sp |
620 | The return value of the modifier will be ignored. |
621 | .ie n .IP "\fB$metaclass\->add_after_method_modifier($method_name, \fB$code\fB)\fR" 4 |
622 | .el .IP "\fB$metaclass\->add_after_method_modifier($method_name, \f(CB$code\fB)\fR" 4 |
623 | .IX Item "$metaclass->add_after_method_modifier($method_name, $code)" |
624 | This wraps the specified method with the supplied subroutine |
625 | reference. The modifier will be called as a method itself, and will |
626 | receive the same arguments as are passed to the method. |
627 | .Sp |
628 | When the wrapped methods exits, the modifier will be called. |
629 | .Sp |
630 | The return value of the modifier will be ignored. |
631 | .ie n .IP "\fB$metaclass\->add_around_method_modifier($method_name, \fB$code\fB)\fR" 4 |
632 | .el .IP "\fB$metaclass\->add_around_method_modifier($method_name, \f(CB$code\fB)\fR" 4 |
633 | .IX Item "$metaclass->add_around_method_modifier($method_name, $code)" |
634 | This wraps the specified method with the supplied subroutine |
635 | reference. |
636 | .Sp |
637 | The first argument passed to the modifier will be a subroutine |
638 | reference to the wrapped method. The second argument is the object, |
639 | and after that come any arguments passed when the method is called. |
640 | .Sp |
641 | The around modifier can choose to call the original method, as well as |
642 | what arguments to pass if it does so. |
643 | .Sp |
644 | The return value of the modifier is what will be seen by the caller. |
645 | .Sh "Introspection" |
646 | .IX Subsection "Introspection" |
647 | .IP "\fBClass::MOP::Class\->meta\fR" 4 |
648 | .IX Item "Class::MOP::Class->meta" |
649 | This will return a Class::MOP::Class instance for this class. |
650 | .Sp |
651 | It should also be noted that Class::MOP will actually bootstrap |
652 | this module by installing a number of attribute meta-objects into its |
653 | metaclass. |
654 | .SH "AUTHORS" |
655 | .IX Header "AUTHORS" |
656 | Stevan Little <stevan@iinteractive.com> |
657 | .SH "COPYRIGHT AND LICENSE" |
658 | .IX Header "COPYRIGHT AND LICENSE" |
659 | Copyright 2006\-2009 by Infinity Interactive, Inc. |
660 | .PP |
661 | <http://www.iinteractive.com> |
662 | .PP |
663 | This library is free software; you can redistribute it and/or modify |
664 | it under the same terms as Perl itself. |