1Class::MOP::Class(3) User Contributed Perl Documentation Class::MOP::Class(3)
2
6 Class::MOP::Class - Class Meta Object
7
9 # assuming that class Foo
10 # has been defined, you can
11 # use this for introspection ...
13 # add a method to Foo ...
15 Foo->meta->add_method('bar' => sub { ... })
16 # get a list of all the classes searched
18 # the method dispatcher in the correct order
19 Foo->meta->class_precedence_list()
20 # remove a method from Foo
22 Foo->meta->remove_method('bar');
23 # or use this to actually create classes ...
25 Class::MOP::Class->create('Bar' => (
27 version => '0.01',
28 superclasses => [ 'Foo' ],
29 attributes => [
30 Class::MOP:::Attribute->new('$bar'),
31 Class::MOP:::Attribute->new('$baz'),
32 ],
33 methods => {
34 calculate_bar => sub { ... },
35 construct_baz => sub { ... }
36 }
37 ));
38
40 This is the largest and currently most complex part of the Perl 5 meta-
41 object protocol. It controls the introspection and manipulation of Perl
42 5 classes (and it can create them too). The best way to understand what
43 this module can do, is to read the documentation for each of it's meth‐
44 ods.
45
47 Self Introspection
48 meta
50 This will return a Class::MOP::Class instance which is related to
51 this class. Thereby allowing Class::MOP::Class to actually intro‐
52 spect itself.
53 As with Class::MOP::Attribute, Class::MOP will actually bootstrap
55 this module by installing a number of attribute meta-objects into
56 it's metaclass. This will allow this class to reap all the benifits
57 of the MOP when subclassing it.
58 Class construction
60 These methods will handle creating Class::MOP::Class objects, which can
62 be used to both create new classes, and analyze pre-existing classes.
63 This module will internally store references to all the instances you
65 create with these methods, so that they do not need to be created any
66 more than nessecary. Basically, they are singletons.
67 create ($package_name, version => ?$version, authority =>
69 ?$authority, superclasses => ?@superclasses, methods => ?%methods,
70 attributes => ?%attributes)
71 This returns a Class::MOP::Class object, bringing the specified
72 $package_name into existence and adding any of the $version,
73 $authority, @superclasses, %methods and %attributes to it.
74 create_anon_class (superclasses => ?@superclasses, methods =>
76 ?%methods, attributes => ?%attributes)
77 This will create an anonymous class, it works much like "create"
78 but it does not need a $package_name. Instead it will create a
79 suitably unique package name for you to stash things into.
80 On very important distinction is that anon classes are destroyed
82 once the metaclass they are attached to goes out of scope. In the
83 DESTROY method, the created package will be removed from the symbol
84 table.
85 It is also worth noting that any instances created with an anon-
87 class will keep a special reference to the anon-meta which will
88 prevent the anon-class from going out of scope until all instances
89 of it have also been destroyed. This however only works for HASH
90 based instance types, as we use a special reserved slot ("__MOP__")
91 to store this.
92 initialize ($package_name, %options)
94 This initializes and returns returns a Class::MOP::Class object for
95 a given a $package_name.
96 reinitialize ($package_name, %options)
98 This removes the old metaclass, and creates a new one in it's
99 place. Do not use this unless you really know what you are doing,
100 it could very easily make a very large mess of your program.
101 construct_class_instance (%options)
103 This will construct an instance of Class::MOP::Class, it is here so
104 that we can actually "tie the knot" for Class::MOP::Class to use
105 "construct_instance" once all the bootstrapping is done. This
106 method is used internally by "initialize" and should never be
107 called from outside of that method really.
108 check_metaclass_compatability
110 This method is called as the very last thing in the "con‐
111 struct_class_instance" method. This will check that the metaclass
112 you are creating is compatible with the metaclasses of all your
113 ancestors. For more inforamtion about metaclass compatibility see
114 the "About Metaclass compatibility" section in Class::MOP.
115 Object instance construction and cloning
117 These methods are entirely optional, it is up to you whether you want
119 to use them or not.
120 instance_metaclass
122 get_meta_instance
123 new_object (%params)
124 This is a convience method for creating a new object of the class,
125 and blessing it into the appropriate package as well. Ideally your
126 class would call a "new" this method like so:
127 sub MyClass::new {
129 my ($class, %param) = @_;
130 $class->meta->new_object(%params);
131 }
132 Of course the ideal place for this would actually be in "UNIVER‐
134 SAL::" but that is considered bad style, so we do not do that.
135 construct_instance (%params)
137 This method is used to construct an instace structure suitable for
138 "bless"-ing into your package of choice. It works in conjunction
139 with the Attribute protocol to collect all applicable attributes.
140 This will construct and instance using a HASH ref as storage (cur‐
142 rently only HASH references are supported). This will collect all
143 the applicable attributes and layout out the fields in the HASH
144 ref, it will then initialize them using either use the correspond‐
145 ing key in %params or any default value or initializer found in the
146 attribute meta-object.
147 clone_object ($instance, %params)
149 This is a convience method for cloning an object instance, then
150 blessing it into the appropriate package. This method will call
151 "clone_instance", which performs a shallow copy of the object, see
152 that methods documentation for more details. Ideally your class
153 would call a "clone" this method like so:
154 sub MyClass::clone {
156 my ($self, %param) = @_;
157 $self->meta->clone_object($self, %params);
158 }
159 Of course the ideal place for this would actually be in "UNIVER‐
161 SAL::" but that is considered bad style, so we do not do that.
162 clone_instance($instance, %params)
164 This method is a compliment of "construct_instance" (which means if
165 you override "construct_instance", you need to override this one
166 too), and clones the instance shallowly.
167 The cloned structure returned is (like with "construct_instance")
169 an un"bless"ed HASH reference, it is your responsibility to then
170 bless this cloned structure into the right class (which
171 "clone_object" will do for you).
172 As of 0.11, this method will clone the $instance structure shal‐
174 lowly, as opposed to the deep cloning implemented in prior ver‐
175 sions. After much thought, research and discussion, I have decided
176 that anything but basic shallow cloning is outside the scope of the
177 meta-object protocol. I think Yuval "nothingmuch" Kogman put it
178 best when he said that cloning is too context-specific to be part
179 of the MOP.
180 Informational
182 These are a few predicate methods for asking information about the
184 class.
185 is_anon_class
187 This returns true if the class is a "Class::MOP::Class" created
188 anon class.
189 is_mutable
191 This returns true if the class is still mutable.
192 is_immutable
194 This returns true if the class has been made immutable.
195 Inheritance Relationships
197 superclasses (?@superclasses)
199 This is a read-write attribute which represents the superclass
200 relationships of the class the Class::MOP::Class instance is asso‐
201 ciated with. Basically, it can get and set the @ISA for you.
202 NOTE: Perl will occasionally perform some @ISA and method caching,
204 if you decide to change your superclass relationship at runtime
205 (which is quite insane and very much not recommened), then you
206 should be aware of this and the fact that this module does not make
207 any attempt to address this issue.
208 class_precedence_list
210 This computes the a list of all the class's ancestors in the same
211 order in which method dispatch will be done. This is similair to
212 what Class::ISA::super_path does, but we don't remove duplicate
213 names.
214 linearized_isa
216 This returns a list based on "class_precedence_list" but with all
217 duplicates removed.
218 Methods
220 get_method_map
222 method_metaclass
223 add_method ($method_name, $method)
224 This will take a $method_name and CODE reference to that $method
225 and install it into the class's package.
226 NOTE: This does absolutely nothing special to $method other than
228 use Sub::Name to make sure it is tagged with the correct name, and
229 therefore show up correctly in stack traces and such.
230 alias_method ($method_name, $method)
232 This will take a $method_name and CODE reference to that $method
233 and alias the method into the class's package.
234 NOTE: Unlike "add_method", this will not try to name the $method
236 using Sub::Name, it only aliases the method in the class's package.
237 has_method ($method_name)
239 This just provides a simple way to check if the class implements a
240 specific $method_name. It will not however, attempt to check if the
241 class inherits the method (use "UNIVERSAL::can" for that).
242 This will correctly handle functions defined outside of the package
244 that use a fully qualified name ("sub Package::name { ... }").
245 This will correctly handle functions renamed with Sub::Name and
247 installed using the symbol tables. However, if you are naming the
248 subroutine outside of the package scope, you must use the fully
249 qualified name, including the package name, for "has_method" to
250 correctly identify it.
251 This will attempt to correctly ignore functions imported from other
253 packages using Exporter. It breaks down if the function imported is
254 an "__ANON__" sub (such as with "use constant"), which very well
255 may be a valid method being applied to the class.
256 In short, this method cannot always be trusted to determine if the
258 $method_name is actually a method. However, it will DWIM about 90%
259 of the time, so it's a small trade off I think.
260 get_method ($method_name)
262 This will return a Class::MOP::Method instance related to the spec‐
263 ified $method_name, or return undef if that method does not exist.
264 The Class::MOP::Method is codifiable, so you can use it like a nor‐
266 mal CODE reference, see Class::MOP::Method for more information.
267 find_method_by_name ($method_name
269 This will return a CODE reference of the specified $method_name, or
270 return undef if that method does not exist.
271 Unlike "get_method" this will also look in the superclasses.
273 remove_method ($method_name)
275 This will attempt to remove a given $method_name from the class.
276 It will return the CODE reference that it has removed, and will
277 attempt to use Sub::Name to clear the methods associated name.
278 get_method_list
280 This will return a list of method names for all locally defined
281 methods. It does not provide a list of all applicable methods,
282 including any inherited ones. If you want a list of all applicable
283 methods, use the "compute_all_applicable_methods" method.
284 compute_all_applicable_methods
286 This will return a list of all the methods names this class will
287 respond to, taking into account inheritance. The list will be a
288 list of HASH references, each one containing the following informa‐
289 tion; method name, the name of the class in which the method lives
290 and a CODE reference for the actual method.
291 find_all_methods_by_name ($method_name)
293 This will traverse the inheritence hierarchy and locate all methods
294 with a given $method_name. Similar to "compute_all_applicable_meth‐
295 ods" it returns a list of HASH references with the following infor‐
296 mation; method name (which will always be the same as
297 $method_name), the name of the class in which the method lives and
298 a CODE reference for the actual method.
299 The list of methods produced is a distinct list, meaning there are
301 no duplicates in it. This is especially useful for things like
302 object initialization and destruction where you only want the
303 method called once, and in the correct order.
304 find_next_method_by_name ($method_name)
306 This will return the first method to match a given $method_name in
307 the superclasses, this is basically equivalent to calling
308 "SUPER::$method_name", but it can be dispatched at runtime.
309 Method Modifiers
311 Method modifiers are a concept borrowed from CLOS, in which a method
313 can be wrapped with before, after and around method modifiers that will
314 be called everytime the method is called.
315 How method modifiers work?
317 Method modifiers work by wrapping the original method and then replac‐
319 ing it in the classes symbol table. The wrappers will handle calling
320 all the modifiers in the appropariate orders and preserving the calling
321 context for the original method.
322 Each method modifier serves a particular purpose, which may not be
324 obvious to users of other method wrapping modules. To start with, the
325 return values of before and after modifiers are ignored. This is
326 because thier purpose is not to filter the input and output of the pri‐
327 mary method (this is done with an around modifier). This may seem like
328 an odd restriction to some, but doing this allows for simple code to be
329 added at the begining or end of a method call without jeapordizing the
330 normal functioning of the primary method or placing any extra responsi‐
331 bility on the code of the modifier. Of course if you have more complex
332 needs, then use the around modifier, which uses a variation of continu‐
333 tation passing style to allow for a high degree of flexibility.
334 Before and around modifiers are called in last-defined-first-called
336 order, while after modifiers are called in first-defined-first-called
337 order. So the call tree might looks something like this:
338 before 2
340 before 1
341 around 2
342 around 1
343 primary
344 after 1
345 after 2
346 To see examples of using method modifiers, see the following examples
348 included in the distribution; InstanceCountingClass, Perl6Attribute,
349 AttributesWithHistory and C3MethodDispatchOrder. There is also a clas‐
350 sic CLOS usage example in the test 017_add_method_modifier.t.
351 What is the performance impact?
353 Of course there is a performance cost associated with method modifiers,
355 but we have made every effort to make that cost be directly propor‐
356 tional to the amount of modifier features you utilize.
357 The wrapping method does it's best to only do as much work as it abso‐
359 lutely needs to. In order to do this we have moved some of the perfor‐
360 mance costs to set-up time, where they are easier to amortize.
361 All this said, my benchmarks have indicated the following:
363 simple wrapper with no modifiers 100% slower
365 simple wrapper with simple before modifier 400% slower
366 simple wrapper with simple after modifier 450% slower
367 simple wrapper with simple around modifier 500-550% slower
368 simple wrapper with all 3 modifiers 1100% slower
369 These numbers may seem daunting, but you must remember, every feature
371 comes with some cost. To put things in perspective, just doing a simple
372 "AUTOLOAD" which does nothing but extract the name of the method called
373 and return it costs about 400% over a normal method call.
374 add_before_method_modifier ($method_name, $code)
376 This will wrap the method at $method_name and the supplied $code
377 will be passed the @_ arguments, and called before the original
378 method is called. As specified above, the return value of the
379 before method modifiers is ignored, and it's ability to modify @_
380 is fairly limited. If you need to do either of these things, use an
381 "around" method modifier.
382 add_after_method_modifier ($method_name, $code)
384 This will wrap the method at $method_name so that the original
385 method will be called, it's return values stashed, and then the
386 supplied $code will be passed the @_ arguments, and called. As
387 specified above, the return value of the after method modifiers is
388 ignored, and it cannot modify the return values of the original
389 method. If you need to do either of these things, use an "around"
390 method modifier.
391 add_around_method_modifier ($method_name, $code)
393 This will wrap the method at $method_name so that $code will be
394 called and passed the original method as an extra argument at the
395 begining of the @_ argument list. This is a variation of continua‐
396 tion passing style, where the function prepended to @_ can be con‐
397 sidered a continuation. It is up to $code if it calls the original
398 method or not, there is no restriction on what the $code can or
399 cannot do.
400 Attributes
402 It should be noted that since there is no one consistent way to define
404 the attributes of a class in Perl 5. These methods can only work with
405 the information given, and can not easily discover information on their
406 own. See Class::MOP::Attribute for more details.
407 attribute_metaclass
409 get_attribute_map
410 add_attribute ($attribute_meta_object ⎪ $attribute_name,
411 %attribute_spec)
412 This stores the $attribute_meta_object (or creates one from the
413 $attribute_name and %attribute_spec) in the Class::MOP::Class
414 instance associated with the given class. Unlike methods,
415 attributes within the MOP are stored as meta-information only. They
416 will be used later to construct instances from (see "con‐
417 struct_instance" above). More details about the attribute meta-
418 objects can be found in the Class::MOP::Attribute or the "The
419 Attribute protocol" in Class::MOP section.
420 It should be noted that any accessor, reader/writer or predicate
422 methods which the $attribute_meta_object has will be installed into
423 the class at this time.
424 NOTE If an attribute already exists for $attribute_name, the old
426 one will be removed (as well as removing all it's accessors), and
427 then the new one added.
428 has_attribute ($attribute_name)
430 Checks to see if this class has an attribute by the name of
431 $attribute_name and returns a boolean.
432 get_attribute ($attribute_name)
434 Returns the attribute meta-object associated with $attribute_name,
435 if none is found, it will return undef.
436 remove_attribute ($attribute_name)
438 This will remove the attribute meta-object stored at
439 $attribute_name, then return the removed attribute meta-object.
440 NOTE: Removing an attribute will only affect future instances of
442 the class, it will not make any attempt to remove the attribute
443 from any existing instances of the class.
444 It should be noted that any accessor, reader/writer or predicate
446 methods which the attribute meta-object stored at $attribute_name
447 has will be removed from the class at this time. This will make
448 these attributes somewhat inaccessable in previously created
449 instances. But if you are crazy enough to do this at runtime, then
450 you are crazy enough to deal with something like this :).
451 get_attribute_list
453 This returns a list of attribute names which are defined in the
454 local class. If you want a list of all applicable attributes for a
455 class, use the "compute_all_applicable_attributes" method.
456 compute_all_applicable_attributes
458 This will traverse the inheritance heirachy and return a list of
459 all the applicable attributes for this class. It does not construct
460 a HASH reference like "compute_all_applicable_methods" because all
461 that same information is discoverable through the attribute meta-
462 object itself.
463 find_attribute_by_name ($attr_name)
465 This method will traverse the inheritance heirachy and find the
466 first attribute whose name matches $attr_name, then return it. It
467 will return undef if nothing is found.
468 Class Immutability
470 make_immutable (%options)
472 This method will invoke a tranforamtion upon the class which will
473 make it immutable. Details of this transformation can be found in
474 the Class::MOP::Immutable documentation.
475 make_mutable
477 This method will reverse tranforamtion upon the class which made it
478 immutable.
479 create_immutable_transformer
481 Create a transformer suitable for making this class immutable
482
484 Stevan Little <stevan@iinteractive.com>
485
487 Copyright 2006, 2007 by Infinity Interactive, Inc.
488 <http://www.iinteractive.com>
490 This library is free software; you can redistribute it and/or modify it
492 under the same terms as Perl itself.
493perl v5.8.8 2007-11-07 Class::MOP::Class(3)