Class::MOP(3pm)

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

NAME

6       Class::MOP - A Meta Object Protocol for Perl 5
7

DESCRIPTION

9       This module is a fully functioning meta object protocol for the Perl 5
10       object system. It makes no attempt to change the behavior or
11       characteristics of the Perl 5 object system, only to create a protocol
12       for its manipulation and introspection.
13
14       That said, it does attempt to create the tools for building a rich set
15       of extensions to the Perl 5 object system. Every attempt has been made
16       to abide by the spirit of the Perl 5 object system that we all know and
17       love.
18
19       This documentation is sparse on conceptual details. We suggest looking
20       at the items listed in the "SEE ALSO" section for more information. In
21       particular the book "The Art of the Meta Object Protocol" was very
22       influential in the development of this system.
23
24   What is a Meta Object Protocol?
25       A meta object protocol is an API to an object system.
26
27       To be more specific, it abstracts the components of an object system
28       (classes, object, methods, object attributes, etc.). These abstractions
29       can then be used to inspect and manipulate the object system which they
30       describe.
31
32       It can be said that there are two MOPs for any object system; the
33       implicit MOP and the explicit MOP. The implicit MOP handles things like
34       method dispatch or inheritance, which happen automatically as part of
35       how the object system works. The explicit MOP typically handles the
36       introspection/reflection features of the object system.
37
38       All object systems have implicit MOPs. Without one, they would not
39       work. Explicit MOPs are much less common, and depending on the language
40       can vary from restrictive (Reflection in Java or C#) to wide open (CLOS
41       is a perfect example).
42
43   Yet Another Class Builder! Why?
44       This is not a class builder so much as a class builder builder. The
45       intent is that an end user will not use this module directly, but
46       instead this module is used by module authors to build extensions and
47       features onto the Perl 5 object system.
48
49       This system is used by Moose, which supplies a powerful class builder
50       system built entirely on top of "Class::MOP".
51
52   Who is this module for?
53       This module is for anyone who has ever created or wanted to create a
54       module for the Class:: namespace. The tools which this module provides
55       make doing complex Perl 5 wizardry simpler, by removing such barriers
56       as the need to hack symbol tables, or understand the fine details of
57       method dispatch.
58
59   What changes do I have to make to use this module?
60       This module was designed to be as unintrusive as possible. Many of its
61       features are accessible without any change to your existing code. It is
62       meant to be a compliment to your existing code and not an intrusion on
63       your code base. Unlike many other Class:: modules, this module does not
64       require you subclass it, or even that you "use" it in within your
65       module's package.
66
67       The only features which requires additions to your code are the
68       attribute handling and instance construction features, and these are
69       both completely optional features. The only reason for this is because
70       Perl 5's object system does not actually have these features built in.
71       More information about this feature can be found below.
72
73   About Performance
74       It is a common misconception that explicit MOPs are a performance hit.
75       This is not a universal truth, it is a side-effect of some specific
76       implementations. For instance, using Java reflection is slow because
77       the JVM cannot take advantage of any compiler optimizations, and the
78       JVM has to deal with much more runtime type information as well.
79
80       Reflection in C# is marginally better as it was designed into the
81       language and runtime (the CLR). In contrast, CLOS (the Common Lisp
82       Object System) was built to support an explicit MOP, and so performance
83       is tuned for it.
84
85       This library in particular does its absolute best to avoid putting any
86       drain at all upon your code's performance. In fact, by itself it does
87       nothing to affect your existing code. So you only pay for what you
88       actually use.
89
90   About Metaclass compatibility
91       This module makes sure that all metaclasses created are both upwards
92       and downwards compatible. The topic of metaclass compatibility is
93       highly esoteric and is something only encountered when doing deep and
94       involved metaclass hacking. There are two basic kinds of metaclass
95       incompatibility; upwards and downwards.
96
97       Upwards metaclass compatibility means that the metaclass of a given
98       class is either the same as (or a subclass of) all of the class's
99       ancestors.
100
101       Downward metaclass compatibility means that the metaclasses of a given
102       class's ancestors are all either the same as (or a subclass of) that
103       metaclass.
104
105       Here is a diagram showing a set of two classes ("A" and "B") and two
106       metaclasses ("Meta::A" and "Meta::B") which have correct metaclass
107       compatibility both upwards and downwards.
108
109           +---------+     +---------+
110           | Meta::A |<----| Meta::B |      <....... (instance of  )
111           +---------+     +---------+      <------- (inherits from)
112                ^               ^
113                :               :
114           +---------+     +---------+
115           |    A    |<----|    B    |
116           +---------+     +---------+
117
118       In actuality, all of a class's metaclasses must be compatible, not just
119       the class metaclass. That includes the instance, attribute, and method
120       metaclasses, as well as the constructor and destructor classes.
121
122       "Class::MOP" will attempt to fix some simple types of
123       incompatibilities. If all the metaclasses for the parent class are
124       subclasses of the child's metaclasses then we can simply replace the
125       child's metaclasses with the parent's. In addition, if the child is
126       missing a metaclass that the parent has, we can also just make the
127       child use the parent's metaclass.
128
129       As I said this is a highly esoteric topic and one you will only run
130       into if you do a lot of subclassing of Class::MOP::Class. If you are
131       interested in why this is an issue see the paper Uniform and safe
132       metaclass composition linked to in the "SEE ALSO" section of this
133       document.
134
135   Using custom metaclasses
136       Always use the metaclass pragma when using a custom metaclass, this
137       will ensure the proper initialization order and not accidentally create
138       an incorrect type of metaclass for you. This is a very rare problem,
139       and one which can only occur if you are doing deep metaclass
140       programming. So in other words, don't worry about it.
141
142       Note that if you're using Moose we encourage you to not use metaclass
143       pragma, and instead use Moose::Util::MetaRole to apply roles to a
144       class's metaclasses. This topic is covered at length in various
145       Moose::Cookbook recipes.
146

PROTOCOLS

148       The meta-object protocol is divided into 4 main sub-protocols:
149
150   The Class protocol
151       This provides a means of manipulating and introspecting a Perl 5 class.
152       It handles symbol table hacking for you, and provides a rich set of
153       methods that go beyond simple package introspection.
154
155       See Class::MOP::Class for more details.
156
157   The Attribute protocol
158       This provides a consistent representation for an attribute of a Perl 5
159       class. Since there are so many ways to create and handle attributes in
160       Perl 5 OO, the Attribute protocol provide as much of a unified approach
161       as possible. Of course, you are always free to extend this protocol by
162       subclassing the appropriate classes.
163
164       See Class::MOP::Attribute for more details.
165
166   The Method protocol
167       This provides a means of manipulating and introspecting methods in the
168       Perl 5 object system. As with attributes, there are many ways to
169       approach this topic, so we try to keep it pretty basic, while still
170       making it possible to extend the system in many ways.
171
172       See Class::MOP::Method for more details.
173
174   The Instance protocol
175       This provides a layer of abstraction for creating object instances.
176       Since the other layers use this protocol, it is relatively easy to
177       change the type of your instances from the default hash reference to
178       some other type of reference. Several examples are provided in the
179       examples/ directory included in this distribution.
180
181       See Class::MOP::Instance for more details.
182

FUNCTIONS

184       Note that this module does not export any constants or functions.
185
186   Constants
187       Class::MOP::IS_RUNNING_ON_5_10
188           We set this constant depending on what version perl we are on, this
189           allows us to take advantage of new 5.10 features and stay backwards
190           compatible.
191
192   Utility functions
193       Note that these are all called as functions, not methods.
194
195       Class::MOP::load_class($class_name, \%options?)
196           This will load the specified $class_name, if it is not already
197           loaded (as reported by "is_class_loaded"). This function can be
198           used in place of tricks like "eval "use $module"" or using
199           "require" unconditionally.
200
201           If the module cannot be loaded, an exception is thrown.
202
203           You can pass a hash reference with options as second argument. The
204           only option currently recognised is "-version", which will ensure
205           that the loaded class has at least the required version.
206
207           See also "Class Loading Options".
208
209           For historical reasons, this function explicitly returns a true
210           value.
211
212       Class::MOP::is_class_loaded($class_name, \%options?)
213           Returns a boolean indicating whether or not $class_name has been
214           loaded.
215
216           This does a basic check of the symbol table to try and determine as
217           best it can if the $class_name is loaded, it is probably correct
218           about 99% of the time, but it can be fooled into reporting false
219           positives. In particular, loading any of the core IO modules will
220           cause most of the rest of the core IO modules to falsely report
221           having been loaded, due to the way the base IO module works.
222
223           You can pass a hash reference with options as second argument. The
224           only option currently recognised is "-version", which will ensure
225           that the loaded class has at least the required version.
226
227           See also "Class Loading Options".
228
229       Class::MOP::get_code_info($code)
230           This function returns two values, the name of the package the $code
231           is from and the name of the $code itself. This is used by several
232           elements of the MOP to determine where a given $code reference is
233           from.
234
235       Class::MOP::class_of($instance_or_class_name)
236           This will return the metaclass of the given instance or class name.
237           If the class lacks a metaclass, no metaclass will be initialized,
238           and "undef" will be returned.
239
240       Class::MOP::check_package_cache_flag($pkg)
241           NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!
242
243           This will return an integer that is managed by Class::MOP::Class to
244           determine if a module's symbol table has been altered.
245
246           In Perl 5.10 or greater, this flag is package specific. However in
247           versions prior to 5.10, this will use the "PL_sub_generation"
248           variable which is not package specific.
249
250       Class::MOP::load_first_existing_class(@class_names)
251       Class::MOP::load_first_existing_class($classA, \%optionsA?, $classB,
252       ...)
253           NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!
254
255           Given a list of class names, this function will attempt to load
256           each one in turn.
257
258           If it finds a class it can load, it will return that class' name.
259           If none of the classes can be loaded, it will throw an exception.
260
261           Additionally, you can pass a hash reference with options after each
262           class name. Currently, only "-version" is recognised and will
263           ensure that the loaded class has at least the required version. If
264           the class version is not sufficient, an exception will be raised.
265
266           See also "Class Loading Options".
267
268   Metaclass cache functions
269       Class::MOP holds a cache of metaclasses. The following are functions
270       (not methods) which can be used to access that cache. It is not
271       recommended that you mess with these. Bad things could happen, but if
272       you are brave and willing to risk it: go for it!
273
274       Class::MOP::get_all_metaclasses
275           This will return a hash of all the metaclass instances that have
276           been cached by Class::MOP::Class, keyed by the package name.
277
278       Class::MOP::get_all_metaclass_instances
279           This will return a list of all the metaclass instances that have
280           been cached by Class::MOP::Class.
281
282       Class::MOP::get_all_metaclass_names
283           This will return a list of all the metaclass names that have been
284           cached by Class::MOP::Class.
285
286       Class::MOP::get_metaclass_by_name($name)
287           This will return a cached Class::MOP::Class instance, or nothing if
288           no metaclass exists with that $name.
289
290       Class::MOP::store_metaclass_by_name($name, $meta)
291           This will store a metaclass in the cache at the supplied $key.
292
293       Class::MOP::weaken_metaclass($name)
294           In rare cases (e.g. anonymous metaclasses) it is desirable to store
295           a weakened reference in the metaclass cache. This function will
296           weaken the reference to the metaclass stored in $name.
297
298       Class::MOP::does_metaclass_exist($name)
299           This will return true of there exists a metaclass stored in the
300           $name key, and return false otherwise.
301
302       Class::MOP::remove_metaclass_by_name($name)
303           This will remove the metaclass stored in the $name key.
304
305   Class Loading Options
306       -version
307           Can be used to pass a minimum required version that will be checked
308           against the class version after it was loaded.
309

SIMILAR MODULES

351       As I have said above, this module is a class-builder-builder, so it is
352       not the same thing as modules like Class::Accessor and
353       Class::MethodMaker. That being said there are very few modules on CPAN
354       with similar goals to this module. The one I have found which is most
355       like this module is Class::Meta, although it's philosophy and the MOP
356       it creates are very different from this modules.
357

BUGS

359       All complex software has bugs lurking in it, and this module is no
360       exception.
361
362       Please report any bugs to "bug-class-mop@rt.cpan.org", or through the
363       web interface at <http://rt.cpan.org>.
364
365       You can also discuss feature requests or possible bugs on the Moose
366       mailing list (moose@perl.org) or on IRC at <irc://irc.perl.org/#moose>.
367

ACKNOWLEDGEMENTS

369       Rob Kinyon
370           Thanks to Rob for actually getting the development of this module
371           kick-started.
372

AUTHORS

374       Stevan Little <stevan@iinteractive.com>
375
376       with contributions from:
377
378       Brandon (blblack) Black
379
380       Florian (rafl) Ragwitz
381
382       Guillermo (groditi) Roditi
383
384       Dave (autarch) Rolsky
385
386       Matt (mst) Trout
387
388       Rob (robkinyon) Kinyon
389
390       Yuval (nothingmuch) Kogman
391
392       Scott (konobi) McWhirter
393
394       Dylan Hardison
395

COPYRIGHT AND LICENSE

397       Copyright 2006-2010 by Infinity Interactive, Inc.
398
399       <http://www.iinteractive.com>
400
401       This library is free software; you can redistribute it and/or modify it
402       under the same terms as Perl itself.
403
404
405
406perl v5.12.2                      2010-09-13                     Class::MOP(3)