1Class::MOP::Class(3)  User Contributed Perl Documentation Class::MOP::Class(3)
2
3
4

NAME

6       Class::MOP::Class - Class Meta Object
7

VERSION

9       version 2.2014
10

SYNOPSIS

12         # assuming that class Foo
13         # has been defined, you can
14
15         # use this for introspection ...
16
17         # add a method to Foo ...
18         Foo->meta->add_method( 'bar' => sub {...} )
19
20         # get a list of all the classes searched
21         # the method dispatcher in the correct order
22         Foo->meta->class_precedence_list()
23
24         # remove a method from Foo
25         Foo->meta->remove_method('bar');
26
27         # or use this to actually create classes ...
28
29         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

DESCRIPTION

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

INHERITANCE

52       "Class::MOP::Class" is a subclass of Class::MOP::Module.
53

METHODS

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
60       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
64       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
68           •       version
69
70                   An optional version number for the newly created package.
71
72           •       authority
73
74                   An optional authority for the newly created package.  See
75                   "authority" in Class::MOP::Module for more details.
76
77           •       superclasses
78
79                   An optional array reference of superclass names.
80
81           •       methods
82
83                   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
87           •       attributes
88
89                   An optional array reference of Class::MOP::Attribute
90                   objects.
91
92           •       meta_name
93
94                   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
99           •       weaken
100
101                   If true, the metaclass that is stored in the global cache
102                   will be a weak reference.
103
104                   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
108                   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
113                   This only works if the instance is based on a hash
114                   reference, however.
115
116       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
121           It accepts the same "superclasses", "methods", and "attributes"
122           parameters that "create" accepts.
123
124           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
129           Anonymous classes default to "weaken => 1" if cache is "false",
130           although this can be overridden.
131
132       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
137           The purpose of this method is to retrieve a "Class::MOP::Class"
138           object for introspecting an existing class.
139
140           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
144           If the object does not yet exist, it will be created.
145
146           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
152   Object instance construction and cloning
153       These methods are all related to creating and/or cloning object
154       instances.
155
156       $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
160           This is a convenience method for cloning an object instance, then
161           blessing it into the appropriate package.
162
163           You could implement a clone method in your class, using this
164           method:
165
166             sub clone {
167                 my ($self, %params) = @_;
168                 $self->meta->clone_object($self, %params);
169             }
170
171       $metaclass->rebless_instance($instance, %params)
172           This method changes the class of $instance to the metaclass's
173           class.
174
175           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
181           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
187       $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
192           This is a much more dangerous operation than "rebless_instance",
193           especially when multiple inheritance is involved, so use this
194           carefully!
195
196       $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
205       $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
210       $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
214   Informational predicates
215       These are a few predicate methods for asking information about the
216       class itself.
217
218       $metaclass->is_anon_class
219           This returns true if the class was created by calling
220           "Class::MOP::Class->create_anon_class".
221
222       $metaclass->is_mutable
223           This returns true if the class is still mutable.
224
225       $metaclass->is_immutable
226           This returns true if the class has been made immutable.
227
228       $metaclass->is_pristine
229           A class is not pristine if it has non-inherited attributes or if it
230           has any generated methods.
231
232   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
237           This is basically sugar around getting and setting @ISA.
238
239       $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
243       $metaclass->linearized_isa
244           This returns a list based on "class_precedence_list" but with all
245           duplicates removed.
246
247       $metaclass->subclasses
248           This returns a list of all subclasses for this class, even indirect
249           subclasses.
250
251       $metaclass->direct_subclasses
252           This returns a list of immediate subclasses for this class, which
253           does not include indirect subclasses.
254
255   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
259       Determining what is truly a method in a Perl 5 class requires some
260       heuristics (aka guessing).
261
262       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
266       However, we attempt to ignore imported functions.
267
268       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
272       $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
277       $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
282       $metaclass->get_method_list
283           This will return a list of method names for all methods defined in
284           this class.
285
286       $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
290           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
296           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
301       $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
305       $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
309       $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
314       $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
318       $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
323           Unlike "get_method", this method will look for the named method in
324           superclasses.
325
326       $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
330       $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
335           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
339           The list of methods is distinct.
340
341       $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
346   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
352       $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
357           NOTE that get_attribute does not search superclasses, for that you
358           need to use "find_attribute_by_name".
359
360       $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
365       $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
370       $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
375       $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
380           Unlike "get_attribute", this attribute will look for the named
381           attribute in superclasses.
382
383       $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
387           The attribute provided will be added to the class.
388
389           Any accessor methods defined by the attribute will be added to the
390           class when the attribute is added.
391
392           If an attribute of the same name already exists, the old attribute
393           will be removed first.
394
395       $metaclass->remove_attribute($attribute_name)
396           This will remove the named attribute from the class, and
397           Class::MOP::Attribute object.
398
399           Removing an attribute also removes any accessor methods defined by
400           the attribute.
401
402           However, note that removing an attribute will only affect future
403           object instances created for this class, not existing instances.
404
405       $metaclass->attribute_metaclass
406           Returns the class name of the attribute metaclass for this class.
407           By default, this is Class::MOP::Attribute.
408
409   Overload introspection and creation
410       These methods provide an API to the core overload functionality.
411
412       $metaclass->is_overloaded
413           Returns true if overloading is enabled for this class. Corresponds
414           to "is_overloaded" in Devel::OverloadInfo.
415
416       $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
420       $metaclass->has_overloaded_operator($op)
421           Returns whether or not the operator $op is overloaded for this
422           class.
423
424       $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
429       $metaclass->get_all_overloaded_operators
430           Returns a list of Class::MOP::Overload objects corresponding to the
431           operators that have been overloaded.
432
433       $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
438       $metaclass->remove_overloaded_operator($op)
439           Remove overloading for operator $op. Corresponds to "no overload
440           $op;"
441
442       $metaclass->get_overload_fallback_value
443           Returns the overload "fallback" setting for the package.
444
445       $metaclass->set_overload_fallback_value($fallback)
446           Sets the overload "fallback" setting for the package.
447
448   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
453       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
457       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
463       The immutabilization system in Moose takes much greater advantage of
464       the inlining features than Class::MOP itself does.
465
466       $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
471           This method accepts the following options:
472
473           •       inline_accessors
474
475           •       inline_constructor
476
477           •       inline_destructor
478
479                   These are all booleans indicating whether the specified
480                   method(s) should be inlined.
481
482                   By default, accessors and the constructor are inlined, but
483                   not the destructor.
484
485           •       immutable_trait
486
487                   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
492                   This defaults to Class::MOP::Class::Immutable::Trait.
493
494           •       constructor_name
495
496                   This is the constructor method name. This defaults to
497                   "new".
498
499           •       constructor_class
500
501                   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
505           •       replace_constructor
506
507                   This is a boolean indicating whether an existing
508                   constructor should be replaced when inlining a constructor.
509                   This defaults to false.
510
511           •       destructor_class
512
513                   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
517           •       replace_destructor
518
519                   This is a boolean indicating whether an existing destructor
520                   should be replaced when inlining a destructor. This
521                   defaults to false.
522
523       $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
530       $metaclass->make_mutable
531           Calling this method reverse the immutabilization transformation.
532
533   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
538       A class can modify its own methods, as well as methods defined in
539       parent classes.
540
541       How method modifiers work?
542
543       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
548       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
552       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
557       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
561       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
565         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
575       What is the performance impact?
576
577       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
581       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
585       All this said, our benchmarks have indicated the following:
586
587         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
593       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
598       $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
603           When the modifier exits, the wrapped method will be called.
604
605           The return value of the modifier will be ignored.
606
607       $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
612           When the wrapped methods exits, the modifier will be called.
613
614           The return value of the modifier will be ignored.
615
616       $metaclass->add_around_method_modifier($method_name, $code)
617           This wraps the specified method with the supplied subroutine
618           reference.
619
620           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
624           The around modifier can choose to call the original method, as well
625           as what arguments to pass if it does so.
626
627           The return value of the modifier is what will be seen by the
628           caller.
629
630   Introspection
631       Class::MOP::Class->meta
632           This will return a Class::MOP::Class instance for this class.
633
634           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

AUTHORS

639       •   Stevan Little <stevan@cpan.org>
640
641       •   Dave Rolsky <autarch@urth.org>
642
643       •   Jesse Luehrs <doy@cpan.org>
644
645       •   Shawn M Moore <sartak@cpan.org>
646
647       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
648
649       •   Karen Etheridge <ether@cpan.org>
650
651       •   Florian Ragwitz <rafl@debian.org>
652
653       •   Hans Dieter Pearcey <hdp@cpan.org>
654
655       •   Chris Prather <chris@prather.org>
656
657       •   Matt S Trout <mstrout@cpan.org>
658
660       This software is copyright (c) 2006 by Infinity Interactive, Inc.
661
662       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.
664
665
666
667perl v5.32.1                      2021-01-27              Class::MOP::Class(3)
Impressum