1Class::MOP(3) User Contributed Perl Documentation Class::MOP(3)
2
6 Class::MOP - A Meta Object Protocol for Perl 5
7
9 version 2.2206
10
12 This module is a fully functioning meta object protocol for the Perl 5
13 object system. It makes no attempt to change the behavior or
14 characteristics of the Perl 5 object system, only to create a protocol
15 for its manipulation and introspection.
16 That said, it does attempt to create the tools for building a rich set
18 of extensions to the Perl 5 object system. Every attempt has been made
19 to abide by the spirit of the Perl 5 object system that we all know and
20 love.
21 This documentation is sparse on conceptual details. We suggest looking
23 at the items listed in the "SEE ALSO" section for more information. In
24 particular the book "The Art of the Meta Object Protocol" was very
25 influential in the development of this system.
26 What is a Meta Object Protocol?
28 A meta object protocol is an API to an object system.
29 To be more specific, it abstracts the components of an object system
31 (classes, object, methods, object attributes, etc.). These abstractions
32 can then be used to inspect and manipulate the object system which they
33 describe.
34 It can be said that there are two MOPs for any object system; the
36 implicit MOP and the explicit MOP. The implicit MOP handles things like
37 method dispatch or inheritance, which happen automatically as part of
38 how the object system works. The explicit MOP typically handles the
39 introspection/reflection features of the object system.
40 All object systems have implicit MOPs. Without one, they would not
42 work. Explicit MOPs are much less common, and depending on the language
43 can vary from restrictive (Reflection in Java or C#) to wide open (CLOS
44 is a perfect example).
45 Yet Another Class Builder! Why?
47 This is not a class builder so much as a class builder builder. The
48 intent is that an end user will not use this module directly, but
49 instead this module is used by module authors to build extensions and
50 features onto the Perl 5 object system.
51 This system is used by Moose, which supplies a powerful class builder
53 system built entirely on top of "Class::MOP".
54 Who is this module for?
56 This module is for anyone who has ever created or wanted to create a
57 module for the Class:: namespace. The tools which this module provides
58 make doing complex Perl 5 wizardry simpler, by removing such barriers
59 as the need to hack symbol tables, or understand the fine details of
60 method dispatch.
61 What changes do I have to make to use this module?
63 This module was designed to be as unobtrusive as possible. Many of its
64 features are accessible without any change to your existing code. It is
65 meant to be a complement to your existing code and not an intrusion on
66 your code base. Unlike many other Class:: modules, this module does not
67 require you subclass it, or even that you "use" it in within your
68 module's package.
69 The only features which require additions to your code are the
71 attribute handling and instance construction features, and these are
72 both completely optional features. The only reason for this is because
73 Perl 5's object system does not actually have these features built in.
74 More information about this feature can be found below.
75 About Performance
77 It is a common misconception that explicit MOPs are a performance hit.
78 This is not a universal truth, it is a side-effect of some specific
79 implementations. For instance, using Java reflection is slow because
80 the JVM cannot take advantage of any compiler optimizations, and the
81 JVM has to deal with much more runtime type information as well.
82 Reflection in C# is marginally better as it was designed into the
84 language and runtime (the CLR). In contrast, CLOS (the Common Lisp
85 Object System) was built to support an explicit MOP, and so performance
86 is tuned for it.
87 This library in particular does its absolute best to avoid putting any
89 drain at all upon your code's performance. In fact, by itself it does
90 nothing to affect your existing code. So you only pay for what you
91 actually use.
92 About Metaclass compatibility
94 This module makes sure that all metaclasses created are both upwards
95 and downwards compatible. The topic of metaclass compatibility is
96 highly esoteric and is something only encountered when doing deep and
97 involved metaclass hacking. There are two basic kinds of metaclass
98 incompatibility; upwards and downwards.
99 Upwards metaclass compatibility means that the metaclass of a given
101 class is either the same as (or a subclass of) all of the metaclasses
102 of the class's ancestors.
103 Downward metaclass compatibility means that the metaclasses of a given
105 class's ancestors are all the same as (or a subclass of) that class's
106 metaclass.
107 Here is a diagram showing a set of two classes ("A" and "B") and two
109 metaclasses ("Meta::A" and "Meta::B") which have correct metaclass
110 compatibility both upwards and downwards.
111 +---------+ +---------+
113 | Meta::A |<----| Meta::B | <....... (instance of )
114 +---------+ +---------+ <------- (inherits from)
115 ^ ^
116 : :
117 +---------+ +---------+
118 | A |<----| B |
119 +---------+ +---------+
120 In actuality, all of a class's metaclasses must be compatible, not just
122 the class metaclass. That includes the instance, attribute, and method
123 metaclasses, as well as the constructor and destructor classes.
124 "Class::MOP" will attempt to fix some simple types of
126 incompatibilities. If all the metaclasses for the parent class are
127 subclasses of the child's metaclasses then we can simply replace the
128 child's metaclasses with the parent's. In addition, if the child is
129 missing a metaclass that the parent has, we can also just make the
130 child use the parent's metaclass.
131 As I said this is a highly esoteric topic and one you will only run
133 into if you do a lot of subclassing of Class::MOP::Class. If you are
134 interested in why this is an issue see the paper Uniform and safe
135 metaclass composition linked to in the "SEE ALSO" section of this
136 document.
137 Using custom metaclasses
139 Always use the metaclass pragma when using a custom metaclass, this
140 will ensure the proper initialization order and not accidentally create
141 an incorrect type of metaclass for you. This is a very rare problem,
142 and one which can only occur if you are doing deep metaclass
143 programming. So in other words, don't worry about it.
144 Note that if you're using Moose we encourage you to not use the
146 metaclass pragma, and instead use Moose::Util::MetaRole to apply roles
147 to a class's metaclasses. This topic is covered at length in various
148 Moose::Cookbook recipes.
149
151 The meta-object protocol is divided into 4 main sub-protocols:
152 The Class protocol
154 This provides a means of manipulating and introspecting a Perl 5 class.
155 It handles symbol table hacking for you, and provides a rich set of
156 methods that go beyond simple package introspection.
157 See Class::MOP::Class for more details.
159 The Attribute protocol
161 This provides a consistent representation for an attribute of a Perl 5
162 class. Since there are so many ways to create and handle attributes in
163 Perl 5 OO, the Attribute protocol provide as much of a unified approach
164 as possible. Of course, you are always free to extend this protocol by
165 subclassing the appropriate classes.
166 See Class::MOP::Attribute for more details.
168 The Method protocol
170 This provides a means of manipulating and introspecting methods in the
171 Perl 5 object system. As with attributes, there are many ways to
172 approach this topic, so we try to keep it pretty basic, while still
173 making it possible to extend the system in many ways.
174 See Class::MOP::Method for more details.
176 The Instance protocol
178 This provides a layer of abstraction for creating object instances.
179 Since the other layers use this protocol, it is relatively easy to
180 change the type of your instances from the default hash reference to
181 some other type of reference. Several examples are provided in the
182 examples/ directory included in this distribution.
183 See Class::MOP::Instance for more details.
185
187 Note that this module does not export any constants or functions.
188 Utility functions
190 Note that these are all called as functions, not methods.
191 Class::MOP::get_code_info($code)
193 This function returns two values, the name of the package the $code is
195 from and the name of the $code itself. This is used by several elements
196 of the MOP to determine where a given $code reference is from.
197 Class::MOP::class_of($instance_or_class_name)
199 This will return the metaclass of the given instance or class name. If
201 the class lacks a metaclass, no metaclass will be initialized, and
202 "undef" will be returned.
203 You should almost certainly be using "Moose::Util::find_meta" instead.
205 Metaclass cache functions
207 "Class::MOP" holds a cache of metaclasses. The following are functions
208 (not methods) which can be used to access that cache. It is not
209 recommended that you mess with these. Bad things could happen, but if
210 you are brave and willing to risk it: go for it!
211 Class::MOP::get_all_metaclasses
213 This will return a hash of all the metaclass instances that have been
215 cached by Class::MOP::Class, keyed by the package name.
216 Class::MOP::get_all_metaclass_instances
218 This will return a list of all the metaclass instances that have been
220 cached by Class::MOP::Class.
221 Class::MOP::get_all_metaclass_names
223 This will return a list of all the metaclass names that have been
225 cached by Class::MOP::Class.
226 Class::MOP::get_metaclass_by_name($name)
228 This will return a cached Class::MOP::Class instance, or nothing if no
230 metaclass exists with that $name.
231 Class::MOP::store_metaclass_by_name($name, $meta)
233 This will store a metaclass in the cache at the supplied $key.
235 Class::MOP::weaken_metaclass($name)
237 In rare cases (e.g. anonymous metaclasses) it is desirable to store a
239 weakened reference in the metaclass cache. This function will weaken
240 the reference to the metaclass stored in $name.
241 Class::MOP::metaclass_is_weak($name)
243 Returns true if the metaclass for $name has been weakened (via
245 "weaken_metaclass").
246 Class::MOP::does_metaclass_exist($name)
248 This will return true of there exists a metaclass stored in the $name
250 key, and return false otherwise.
251 Class::MOP::remove_metaclass_by_name($name)
253 This will remove the metaclass stored in the $name key.
255 Some utility functions (such as "Class::MOP::load_class") that were
257 previously defined in "Class::MOP" regarding loading of classes have
258 been extracted to Class::Load. Please see Class::Load for
259 documentation.
260
262 Books
263 There are very few books out on Meta Object Protocols and Metaclasses
264 because it is such an esoteric topic. The following books are really
265 the only ones I have found. If you know of any more, please email me
266 and let me know, I would love to hear about them.
267 The Art of the Meta Object Protocol
269 Advances in Object-Oriented Metalevel Architecture and Reflection
270 Putting MetaClasses to Work
271 Smalltalk: The Language
272 Papers
274 "Uniform and safe metaclass composition"
275 An excellent paper by the people who brought us the original Traits
276 paper. This paper is on how Traits can be used to do safe
277 metaclass composition, and offers an excellent introduction section
278 which delves into the topic of metaclass compatibility.
279 <http://scg.unibe.ch/archive/papers/Duca05ySafeMetaclassTrait.pdf>
281 "Safe Metaclass Programming"
283 This paper seems to precede the above paper, and propose a mix-in
284 based approach as opposed to the Traits based approach. Both papers
285 have similar information on the metaclass compatibility problem
286 space.
287 <http://citeseer.ist.psu.edu/37617.html>
289 Prior Art
291 The Perl 6 MetaModel work in the Pugs project
292 <http://github.com/perl6/p5-modules/tree/master/Perl6-ObjectSpace/>
293 Articles
295 CPAN Module Review of Class::MOP
296 <http://www.oreillynet.com/onlamp/blog/2006/06/cpan_module_review_classmop.html>
297
299 As I have said above, this module is a class-builder-builder, so it is
300 not the same thing as modules like Class::Accessor and
301 Class::MethodMaker. That being said there are very few modules on CPAN
302 with similar goals to this module. The one I have found which is most
303 like this module is Class::Meta, although its philosophy and the MOP it
304 creates are very different from this modules.
305
307 All complex software has bugs lurking in it, and this module is no
308 exception.
309 Please report any bugs to "bug-class-mop@rt.cpan.org", or through the
311 web interface at <http://rt.cpan.org>.
312 You can also discuss feature requests or possible bugs on the Moose
314 mailing list (moose@perl.org) or on IRC at <irc://irc.perl.org/#moose>.
315
317 Rob Kinyon
318 Thanks to Rob for actually getting the development of this module
319 kick-started.
320
322 • Stevan Little <stevan@cpan.org>
323 • Dave Rolsky <autarch@urth.org>
325 • Jesse Luehrs <doy@cpan.org>
327 • Shawn M Moore <sartak@cpan.org>
329 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
331 • Karen Etheridge <ether@cpan.org>
333 • Florian Ragwitz <rafl@debian.org>
335 • Hans Dieter Pearcey <hdp@cpan.org>
337 • Chris Prather <chris@prather.org>
339 • Matt S Trout <mstrout@cpan.org>
341
343 This software is copyright (c) 2006 by Infinity Interactive, Inc.
344 This is free software; you can redistribute it and/or modify it under
346 the same terms as the Perl 5 programming language system itself.
347perl v5.38.0 2023-07-23 Class::MOP(3)