1Class::MOP::Class(3) User Contributed Perl Documentation Class::MOP::Class(3)
2
6 Class::MOP::Class - Class Meta Object
7
9 version 2.2014
10
12 # assuming that class Foo
13 # has been defined, you can
14 # use this for introspection ...
16 # add a method to Foo ...
18 Foo->meta->add_method( 'bar' => sub {...} )
19 # get a list of all the classes searched
21 # the method dispatcher in the correct order
22 Foo->meta->class_precedence_list()
23 # remove a method from Foo
25 Foo->meta->remove_method('bar');
26 # or use this to actually create classes ...
28 Class::MOP::Class->create(
30 'Bar' => (
31 version => '0.01',
32 superclasses => ['Foo'],
33 attributes => [
34 Class::MOP::Attribute->new('$bar'),
35 Class::MOP::Attribute->new('$baz'),
36 ],
37 methods => {
38 calculate_bar => sub {...},
39 construct_baz => sub {...}
40 }
41 )
42 );
43
45 The Class Protocol is the largest and most complex part of the
46 Class::MOP meta-object protocol. It controls the introspection and
47 manipulation of Perl 5 classes, and it can create them as well. The
48 best way to understand what this module can do is to read the
49 documentation for each of its methods.
50
52 "Class::MOP::Class" is a subclass of Class::MOP::Module.
53
55 Class construction
56 These methods all create new "Class::MOP::Class" objects. These objects
57 can represent existing classes or they can be used to create new
58 classes from scratch.
59 The metaclass object for a given class is a singleton. If you attempt
61 to create a metaclass for the same class twice, you will just get the
62 existing object.
63 Class::MOP::Class->create($package_name, %options)
65 This method creates a new "Class::MOP::Class" object with the given
66 package name. It accepts a number of options:
67 • version
69 An optional version number for the newly created package.
71 • authority
73 An optional authority for the newly created package. See
75 "authority" in Class::MOP::Module for more details.
76 • superclasses
78 An optional array reference of superclass names.
80 • methods
82 An optional hash reference of methods for the class. The
84 keys of the hash reference are method names and values are
85 subroutine references.
86 • attributes
88 An optional array reference of Class::MOP::Attribute
90 objects.
91 • meta_name
93 Specifies the name to install the "meta" method for this
95 class under. If it is not passed, "meta" is assumed, and
96 if "undef" is explicitly given, no meta method will be
97 installed.
98 • weaken
100 If true, the metaclass that is stored in the global cache
102 will be a weak reference.
103 Classes created in this way are destroyed once the
105 metaclass they are attached to goes out of scope, and will
106 be removed from Perl's internal symbol table.
107 All instances of a class with a weakened metaclass keep a
109 special reference to the metaclass object, which prevents
110 the metaclass from going out of scope while any instances
111 exist.
112 This only works if the instance is based on a hash
114 reference, however.
115 Class::MOP::Class->create_anon_class(%options)
117 This method works just like "Class::MOP::Class->create" but it
118 creates an "anonymous" class. In fact, the class does have a name,
119 but that name is a unique name generated internally by this module.
120 It accepts the same "superclasses", "methods", and "attributes"
122 parameters that "create" accepts.
123 It also accepts a "cache" option. If this is "true", then the
125 anonymous class will be cached based on its superclasses and roles.
126 If an existing anonymous class in the cache has the same
127 superclasses and roles, it will be reused.
128 Anonymous classes default to "weaken => 1" if cache is "false",
130 although this can be overridden.
131 Class::MOP::Class->initialize($package_name, %options)
133 This method will initialize a "Class::MOP::Class" object for the
134 named package. Unlike "create", this method will not create a new
135 class.
136 The purpose of this method is to retrieve a "Class::MOP::Class"
138 object for introspecting an existing class.
139 If an existing "Class::MOP::Class" object exists for the named
141 package, it will be returned, and any options provided will be
142 ignored!
143 If the object does not yet exist, it will be created.
145 The valid options that can be passed to this method are
147 "attribute_metaclass", "method_metaclass",
148 "wrapped_method_metaclass", and "instance_metaclass". These are all
149 optional, and default to the appropriate class in the "Class::MOP"
150 distribution.
151 Object instance construction and cloning
153 These methods are all related to creating and/or cloning object
154 instances.
155 $metaclass->clone_object($instance, %params)
157 This method clones an existing object instance. Any parameters you
158 provide are will override existing attribute values in the object.
159 This is a convenience method for cloning an object instance, then
161 blessing it into the appropriate package.
162 You could implement a clone method in your class, using this
164 method:
165 sub clone {
167 my ($self, %params) = @_;
168 $self->meta->clone_object($self, %params);
169 }
170 $metaclass->rebless_instance($instance, %params)
172 This method changes the class of $instance to the metaclass's
173 class.
174 You can only rebless an instance into a subclass of its current
176 class. If you pass any additional parameters, these will be treated
177 like constructor parameters and used to initialize the object's
178 attributes. Any existing attributes that are already set will be
179 overwritten.
180 Before reblessing the instance, this method will call
182 "rebless_instance_away" on the instance's current metaclass. This
183 method will be passed the instance, the new metaclass, and any
184 parameters specified to "rebless_instance". By default,
185 "rebless_instance_away" does nothing; it is merely a hook.
186 $metaclass->rebless_instance_back($instance)
188 Does the same thing as "rebless_instance", except that you can only
189 rebless an instance into one of its superclasses. Any attributes
190 that do not exist in the superclass will be deinitialized.
191 This is a much more dangerous operation than "rebless_instance",
193 especially when multiple inheritance is involved, so use this
194 carefully!
195 $metaclass->new_object(%params)
197 This method is used to create a new object of the metaclass's
198 class. Any parameters you provide are used to initialize the
199 instance's attributes. A special "__INSTANCE__" key can be passed
200 to provide an already generated instance, rather than having
201 Class::MOP generate it for you. This is mostly useful for using
202 Class::MOP with foreign classes which generate instances using
203 their own constructors.
204 $metaclass->instance_metaclass
206 Returns the class name of the instance metaclass. See
207 Class::MOP::Instance for more information on the instance
208 metaclass.
209 $metaclass->get_meta_instance
211 Returns an instance of the "instance_metaclass" to be used in the
212 construction of a new instance of the class.
213 Informational predicates
215 These are a few predicate methods for asking information about the
216 class itself.
217 $metaclass->is_anon_class
219 This returns true if the class was created by calling
220 "Class::MOP::Class->create_anon_class".
221 $metaclass->is_mutable
223 This returns true if the class is still mutable.
224 $metaclass->is_immutable
226 This returns true if the class has been made immutable.
227 $metaclass->is_pristine
229 A class is not pristine if it has non-inherited attributes or if it
230 has any generated methods.
231 Inheritance Relationships
233 $metaclass->superclasses(@superclasses)
234 This is a read-write accessor which represents the superclass
235 relationships of the metaclass's class.
236 This is basically sugar around getting and setting @ISA.
238 $metaclass->class_precedence_list
240 This returns a list of all of the class's ancestor classes. The
241 classes are returned in method dispatch order.
242 $metaclass->linearized_isa
244 This returns a list based on "class_precedence_list" but with all
245 duplicates removed.
246 $metaclass->subclasses
248 This returns a list of all subclasses for this class, even indirect
249 subclasses.
250 $metaclass->direct_subclasses
252 This returns a list of immediate subclasses for this class, which
253 does not include indirect subclasses.
254 Method introspection and creation
256 These methods allow you to introspect a class's methods, as well as
257 add, remove, or change methods.
258 Determining what is truly a method in a Perl 5 class requires some
260 heuristics (aka guessing).
261 Methods defined outside the package with a fully qualified name ("sub
263 Package::name { ... }") will be included. Similarly, methods named with
264 a fully qualified name using Sub::Name are also included.
265 However, we attempt to ignore imported functions.
267 Ultimately, we are using heuristics to determine what truly is a method
269 in a class, and these heuristics may get the wrong answer in some edge
270 cases. However, for most "normal" cases the heuristics work correctly.
271 $metaclass->get_method($method_name)
273 This will return a Class::MOP::Method for the specified
274 $method_name. If the class does not have the specified method, it
275 returns "undef"
276 $metaclass->has_method($method_name)
278 Returns a boolean indicating whether or not the class defines the
279 named method. It does not include methods inherited from parent
280 classes.
281 $metaclass->get_method_list
283 This will return a list of method names for all methods defined in
284 this class.
285 $metaclass->add_method($method_name, $method)
287 This method takes a method name and a subroutine reference, and
288 adds the method to the class.
289 The subroutine reference can be a Class::MOP::Method, and you are
291 strongly encouraged to pass a meta method object instead of a code
292 reference. If you do so, that object gets stored as part of the
293 class's method map directly. If not, the meta information will have
294 to be recreated later, and may be incorrect.
295 If you provide a method object, this method will clone that object
297 if the object's package name does not match the class name. This
298 lets us track the original source of any methods added from other
299 classes (notably Moose roles).
300 $metaclass->remove_method($method_name)
302 Remove the named method from the class. This method returns the
303 Class::MOP::Method object for the method.
304 $metaclass->method_metaclass
306 Returns the class name of the method metaclass, see
307 Class::MOP::Method for more information on the method metaclass.
308 $metaclass->wrapped_method_metaclass
310 Returns the class name of the wrapped method metaclass, see
311 Class::MOP::Method::Wrapped for more information on the wrapped
312 method metaclass.
313 $metaclass->get_all_methods
315 This will traverse the inheritance hierarchy and return a list of
316 all the Class::MOP::Method objects for this class and its parents.
317 $metaclass->find_method_by_name($method_name)
319 This will return a Class::MOP::Method for the specified
320 $method_name. If the class does not have the specified method, it
321 returns "undef"
322 Unlike "get_method", this method will look for the named method in
324 superclasses.
325 $metaclass->get_all_method_names
327 This will return a list of method names for all of this class's
328 methods, including inherited methods.
329 $metaclass->find_all_methods_by_name($method_name)
331 This method looks for the named method in the class and all of its
332 parents. It returns every matching method it finds in the
333 inheritance tree, so it returns a list of methods.
334 Each method is returned as a hash reference with three keys. The
336 keys are "name", "class", and "code". The "code" key has a
337 Class::MOP::Method object as its value.
338 The list of methods is distinct.
340 $metaclass->find_next_method_by_name($method_name)
342 This method returns the first method in any superclass matching the
343 given name. It is effectively the method that "SUPER::$method_name"
344 would dispatch to.
345 Attribute introspection and creation
347 Because Perl 5 does not have a core concept of attributes in classes,
348 we can only return information about attributes which have been added
349 via this class's methods. We cannot discover information about
350 attributes which are defined in terms of "regular" Perl 5 methods.
351 $metaclass->get_attribute($attribute_name)
353 This will return a Class::MOP::Attribute for the specified
354 $attribute_name. If the class does not have the specified
355 attribute, it returns "undef".
356 NOTE that get_attribute does not search superclasses, for that you
358 need to use "find_attribute_by_name".
359 $metaclass->has_attribute($attribute_name)
361 Returns a boolean indicating whether or not the class defines the
362 named attribute. It does not include attributes inherited from
363 parent classes.
364 $metaclass->get_attribute_list
366 This will return a list of attributes names for all attributes
367 defined in this class. Note that this operates on the current
368 class only, it does not traverse the inheritance hierarchy.
369 $metaclass->get_all_attributes
371 This will traverse the inheritance hierarchy and return a list of
372 all the Class::MOP::Attribute objects for this class and its
373 parents.
374 $metaclass->find_attribute_by_name($attribute_name)
376 This will return a Class::MOP::Attribute for the specified
377 $attribute_name. If the class does not have the specified
378 attribute, it returns "undef".
379 Unlike "get_attribute", this attribute will look for the named
381 attribute in superclasses.
382 $metaclass->add_attribute(...)
384 This method accepts either an existing Class::MOP::Attribute object
385 or parameters suitable for passing to that class's "new" method.
386 The attribute provided will be added to the class.
388 Any accessor methods defined by the attribute will be added to the
390 class when the attribute is added.
391 If an attribute of the same name already exists, the old attribute
393 will be removed first.
394 $metaclass->remove_attribute($attribute_name)
396 This will remove the named attribute from the class, and
397 Class::MOP::Attribute object.
398 Removing an attribute also removes any accessor methods defined by
400 the attribute.
401 However, note that removing an attribute will only affect future
403 object instances created for this class, not existing instances.
404 $metaclass->attribute_metaclass
406 Returns the class name of the attribute metaclass for this class.
407 By default, this is Class::MOP::Attribute.
408 Overload introspection and creation
410 These methods provide an API to the core overload functionality.
411 $metaclass->is_overloaded
413 Returns true if overloading is enabled for this class. Corresponds
414 to "is_overloaded" in Devel::OverloadInfo.
415 $metaclass->get_overloaded_operator($op)
417 Returns the Class::MOP::Overload object corresponding to the
418 operator named $op, if one exists for this class.
419 $metaclass->has_overloaded_operator($op)
421 Returns whether or not the operator $op is overloaded for this
422 class.
423 $metaclass->get_overload_list
425 Returns a list of operator names which have been overloaded (see
426 "Overloadable Operations" in overload for the list of valid
427 operator names).
428 $metaclass->get_all_overloaded_operators
430 Returns a list of Class::MOP::Overload objects corresponding to the
431 operators that have been overloaded.
432 $metaclass->add_overloaded_operator($op, $impl)
434 Overloads the operator $op for this class. The $impl can be a
435 coderef, a method name, or a Class::MOP::Overload object.
436 Corresponds to "use overload $op => $impl;"
437 $metaclass->remove_overloaded_operator($op)
439 Remove overloading for operator $op. Corresponds to "no overload
440 $op;"
441 $metaclass->get_overload_fallback_value
443 Returns the overload "fallback" setting for the package.
444 $metaclass->set_overload_fallback_value($fallback)
446 Sets the overload "fallback" setting for the package.
447 Class Immutability
449 Making a class immutable "freezes" the class definition. You can no
450 longer call methods which alter the class, such as adding or removing
451 methods or attributes.
452 Making a class immutable lets us optimize the class by inlining some
454 methods, and also allows us to optimize some methods on the metaclass
455 object itself.
456 After immutabilization, the metaclass object will cache most
458 informational methods that returns information about methods or
459 attributes. Methods which would alter the class, such as
460 "add_attribute" and "add_method", will throw an error on an immutable
461 metaclass object.
462 The immutabilization system in Moose takes much greater advantage of
464 the inlining features than Class::MOP itself does.
465 $metaclass->make_immutable(%options)
467 This method will create an immutable transformer and use it to make
468 the class and its metaclass object immutable, and returns true (you
469 should not rely on the details of this value apart from its truth).
470 This method accepts the following options:
472 • inline_accessors
474 • inline_constructor
476 • inline_destructor
478 These are all booleans indicating whether the specified
480 method(s) should be inlined.
481 By default, accessors and the constructor are inlined, but
483 not the destructor.
484 • immutable_trait
486 The name of a class which will be used as a parent class
488 for the metaclass object being made immutable. This "trait"
489 implements the post-immutability functionality of the
490 metaclass (but not the transformation itself).
491 This defaults to Class::MOP::Class::Immutable::Trait.
493 • constructor_name
495 This is the constructor method name. This defaults to
497 "new".
498 • constructor_class
500 The name of the method metaclass for constructors. It will
502 be used to generate the inlined constructor. This defaults
503 to "Class::MOP::Method::Constructor".
504 • replace_constructor
506 This is a boolean indicating whether an existing
508 constructor should be replaced when inlining a constructor.
509 This defaults to false.
510 • destructor_class
512 The name of the method metaclass for destructors. It will
514 be used to generate the inlined destructor. This defaults
515 to "Class::MOP::Method::Denstructor".
516 • replace_destructor
518 This is a boolean indicating whether an existing destructor
520 should be replaced when inlining a destructor. This
521 defaults to false.
522 $metaclass->immutable_options
524 Returns a hash of the options used when making the class immutable,
525 including both defaults and anything supplied by the user in the
526 call to "$metaclass->make_immutable". This is useful if you need to
527 temporarily make a class mutable and then restore immutability as
528 it was before.
529 $metaclass->make_mutable
531 Calling this method reverse the immutabilization transformation.
532 Method Modifiers
534 Method modifiers are hooks which allow a method to be wrapped with
535 before, after and around method modifiers. Every time a method is
536 called, its modifiers are also called.
537 A class can modify its own methods, as well as methods defined in
539 parent classes.
540 How method modifiers work?
542 Method modifiers work by wrapping the original method and then
544 replacing it in the class's symbol table. The wrappers will handle
545 calling all the modifiers in the appropriate order and preserving the
546 calling context for the original method.
547 The return values of "before" and "after" modifiers are ignored. This
549 is because their purpose is not to filter the input and output of the
550 primary method (this is done with an around modifier).
551 This may seem like an odd restriction to some, but doing this allows
553 for simple code to be added at the beginning or end of a method call
554 without altering the function of the wrapped method or placing any
555 extra responsibility on the code of the modifier.
556 Of course if you have more complex needs, you can use the "around"
558 modifier which allows you to change both the parameters passed to the
559 wrapped method, as well as its return value.
560 Before and around modifiers are called in last-defined-first-called
562 order, while after modifiers are called in first-defined-first-called
563 order. So the call tree might looks something like this:
564 before 2
566 before 1
567 around 2
568 around 1
569 primary
570 around 1
571 around 2
572 after 1
573 after 2
574 What is the performance impact?
576 Of course there is a performance cost associated with method modifiers,
578 but we have made every effort to make that cost directly proportional
579 to the number of modifier features you use.
580 The wrapping method does its best to only do as much work as it
582 absolutely needs to. In order to do this we have moved some of the
583 performance costs to set-up time, where they are easier to amortize.
584 All this said, our benchmarks have indicated the following:
586 simple wrapper with no modifiers 100% slower
588 simple wrapper with simple before modifier 400% slower
589 simple wrapper with simple after modifier 450% slower
590 simple wrapper with simple around modifier 500-550% slower
591 simple wrapper with all 3 modifiers 1100% slower
592 These numbers may seem daunting, but you must remember, every feature
594 comes with some cost. To put things in perspective, just doing a simple
595 "AUTOLOAD" which does nothing but extract the name of the method called
596 and return it costs about 400% over a normal method call.
597 $metaclass->add_before_method_modifier($method_name, $code)
599 This wraps the specified method with the supplied subroutine
600 reference. The modifier will be called as a method itself, and will
601 receive the same arguments as are passed to the method.
602 When the modifier exits, the wrapped method will be called.
604 The return value of the modifier will be ignored.
606 $metaclass->add_after_method_modifier($method_name, $code)
608 This wraps the specified method with the supplied subroutine
609 reference. The modifier will be called as a method itself, and will
610 receive the same arguments as are passed to the method.
611 When the wrapped methods exits, the modifier will be called.
613 The return value of the modifier will be ignored.
615 $metaclass->add_around_method_modifier($method_name, $code)
617 This wraps the specified method with the supplied subroutine
618 reference.
619 The first argument passed to the modifier will be a subroutine
621 reference to the wrapped method. The second argument is the object,
622 and after that come any arguments passed when the method is called.
623 The around modifier can choose to call the original method, as well
625 as what arguments to pass if it does so.
626 The return value of the modifier is what will be seen by the
628 caller.
629 Introspection
631 Class::MOP::Class->meta
632 This will return a Class::MOP::Class instance for this class.
633 It should also be noted that Class::MOP will actually bootstrap
635 this module by installing a number of attribute meta-objects into
636 its metaclass.
637
639 • Stevan Little <stevan@cpan.org>
640 • Dave Rolsky <autarch@urth.org>
642 • Jesse Luehrs <doy@cpan.org>
644 • Shawn M Moore <sartak@cpan.org>
646 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
648 • Karen Etheridge <ether@cpan.org>
650 • Florian Ragwitz <rafl@debian.org>
652 • Hans Dieter Pearcey <hdp@cpan.org>
654 • Chris Prather <chris@prather.org>
656 • Matt S Trout <mstrout@cpan.org>
658
660 This software is copyright (c) 2006 by Infinity Interactive, Inc.
661 This is free software; you can redistribute it and/or modify it under
663 the same terms as the Perl 5 programming language system itself.
664perl v5.32.1 2021-01-27 Class::MOP::Class(3)