Make method body load lazily
[gitmo/Class-MOP.git] / lib / Class / MOP.pm
CommitLineData
94b19069 1
2package Class::MOP;
3
4use strict;
5use warnings;
6
5a2932cf 7use 5.008;
8
3cf322a0 9use MRO::Compat;
10
4c105333 11use Carp 'confess';
b1a46f91 12use Scalar::Util 'weaken', 'reftype', 'blessed';
fc4f8f91 13
0531f510 14use Class::MOP::Class;
15use Class::MOP::Attribute;
16use Class::MOP::Method;
17
b1f5f41d 18BEGIN {
c7e28c19 19 *IS_RUNNING_ON_5_10 = ($] < 5.009_005)
11b56828 20 ? sub () { 0 }
c7e28c19 21 : sub () { 1 };
46b23b44 22
3ecd1b25 23 # this is either part of core or set up appropriately by MRO::Compat
24 *check_package_cache_flag = \&mro::get_pkg_gen;
b1f5f41d 25}
e0e4674a 26
f6ca0704 27our $VERSION = '0.94';
8a7085c1 28our $XS_VERSION = $VERSION;
d519662a 29$VERSION = eval $VERSION;
c7e28c19 30our $AUTHORITY = 'cpan:STEVAN';
9d655b6d 31
4bfa5ddb 32require XSLoader;
33XSLoader::load( __PACKAGE__, $XS_VERSION );
d7bda114 34
35
be7677c7 36{
37 # Metaclasses are singletons, so we cache them here.
38 # there is no need to worry about destruction though
39 # because they should die only when the program dies.
40 # After all, do package definitions even get reaped?
247d5b3c 41 # Anonymous classes manage their own destruction.
1d68af04 42 my %METAS;
43
1d68af04 44 sub get_all_metaclasses { %METAS }
45 sub get_all_metaclass_instances { values %METAS }
46 sub get_all_metaclass_names { keys %METAS }
be7677c7 47 sub get_metaclass_by_name { $METAS{$_[0]} }
1d68af04 48 sub store_metaclass_by_name { $METAS{$_[0]} = $_[1] }
49 sub weaken_metaclass { weaken($METAS{$_[0]}) }
be7677c7 50 sub does_metaclass_exist { exists $METAS{$_[0]} && defined $METAS{$_[0]} }
efc98200 51 sub remove_metaclass_by_name { delete $METAS{$_[0]}; return }
1d68af04 52
86866fb5 53 # This handles instances as well as class names
54 sub class_of {
82999986 55 return unless defined $_[0];
86866fb5 56 my $class = blessed($_[0]) || $_[0];
57 return $METAS{$class};
58 }
59
be7677c7 60 # NOTE:
1d68af04 61 # We only cache metaclasses, meaning instances of
62 # Class::MOP::Class. We do not cache instance of
be7677c7 63 # Class::MOP::Package or Class::MOP::Module. Mostly
1d68af04 64 # because I don't yet see a good reason to do so.
be7677c7 65}
66
44da14be 67sub _class_to_pmfile {
68 my $class = shift;
69
70 my $file = $class . '.pm';
71 $file =~ s{::}{/}g;
72
73 return $file;
74}
75
063ad0c5 76sub load_first_existing_class {
f280f05c 77 my @classes = @_
78 or return;
5a24cf8a 79
80 foreach my $class (@classes) {
81 unless ( _is_valid_class_name($class) ) {
82 my $display = defined($class) ? $class : 'undef';
83 confess "Invalid class name ($display)";
84 }
ab5e2f48 85 }
86
063ad0c5 87 my $found;
5a24cf8a 88 my %exceptions;
063ad0c5 89 for my $class (@classes) {
90 my $e = _try_load_one_class($class);
91
5a24cf8a 92 if ($e) {
a3f2cdc0 93 my $pmfile = _class_to_pmfile($class);
063ad0c5 94 $exceptions{$class} = $e;
44da14be 95 last if $e !~ /^Can't locate \Q$pmfile\E in \@INC/;
5a24cf8a 96 }
97 else {
063ad0c5 98 $found = $class;
99 last;
5a24cf8a 100 }
063ad0c5 101 }
5a24cf8a 102
1d8153bd 103 return $found if $found;
07940968 104
063ad0c5 105 confess join(
106 "\n",
107 map {
108 sprintf(
fea44045 109 "Could not load class (%s) because : %s", $_,
063ad0c5 110 $exceptions{$_}
111 )
44da14be 112 }
113 grep {
114 exists $exceptions{$_}
063ad0c5 115 } @classes
f280f05c 116 );
5a24cf8a 117}
118
063ad0c5 119sub _try_load_one_class {
120 my $class = shift;
121
122 return if is_class_loaded($class);
2beec805 123
44da14be 124 my $file = _class_to_pmfile($class);
063ad0c5 125
126 return do {
127 local $@;
b3813a8c 128 local $SIG{__DIE__};
063ad0c5 129 eval { require($file) };
130 $@;
131 };
132}
133
5a24cf8a 134sub load_class {
7716a8f9 135 load_first_existing_class($_[0]);
136
674d9359 137 # This is done to avoid breaking code which checked the return value. Said
138 # code is dumb. The return value was _always_ true, since it dies on
139 # failure!
140 return 1;
448b6e55 141}
142
2c0fb064 143sub _is_valid_class_name {
144 my $class = shift;
145
146 return 0 if ref($class);
147 return 0 unless defined($class);
148 return 0 unless length($class);
149
150 return 1 if $class =~ /^\w+(?:::\w+)*$/;
151
152 return 0;
153}
154
aa448b16 155## ----------------------------------------------------------------------------
156## Setting up our environment ...
157## ----------------------------------------------------------------------------
1d68af04 158## Class::MOP needs to have a few things in the global perl environment so
aa448b16 159## that it can operate effectively. Those things are done here.
160## ----------------------------------------------------------------------------
161
3bf7644b 162# ... nothing yet actually ;)
8b978dd5 163
b51af7f9 164## ----------------------------------------------------------------------------
1d68af04 165## Bootstrapping
b51af7f9 166## ----------------------------------------------------------------------------
1d68af04 167## The code below here is to bootstrap our MOP with itself. This is also
b51af7f9 168## sometimes called "tying the knot". By doing this, we make it much easier
169## to extend the MOP through subclassing and such since now you can use the
1d68af04 170## MOP itself to extend itself.
171##
b51af7f9 172## Yes, I know, thats weird and insane, but it's a good thing, trust me :)
1d68af04 173## ----------------------------------------------------------------------------
727919c5 174
1d68af04 175# We need to add in the meta-attributes here so that
176# any subclass of Class::MOP::* will be able to
c2b256bc 177# inherit them using _construct_instance
727919c5 178
f0480c45 179## --------------------------------------------------------
6d5355c3 180## Class::MOP::Package
727919c5 181
6d5355c3 182Class::MOP::Package->meta->add_attribute(
8683db0e 183 Class::MOP::Attribute->new('package' => (
b880e0de 184 reader => {
1d68af04 185 # NOTE: we need to do this in order
186 # for the instance meta-object to
b880e0de 187 # not fall into meta-circular death
1d68af04 188 #
ce2ae40f 189 # we just alias the original method
1d68af04 190 # rather than re-produce it here
ce2ae40f 191 'name' => \&Class::MOP::Package::name
b880e0de 192 },
727919c5 193 ))
194);
195
a5e51f0b 196Class::MOP::Package->meta->add_attribute(
8683db0e 197 Class::MOP::Attribute->new('namespace' => (
a5e51f0b 198 reader => {
56dcfc1a 199 # NOTE:
ce2ae40f 200 # we just alias the original method
201 # rather than re-produce it here
202 'namespace' => \&Class::MOP::Package::namespace
a5e51f0b 203 },
2e877f58 204 init_arg => undef,
c4260b45 205 default => sub { \undef }
a5e51f0b 206 ))
207);
208
b1ff395f 209Class::MOP::Package->meta->add_attribute(
bcef1f7c 210 Class::MOP::Attribute->new('_methods' => (
211 reader => {
212 # NOTE:
213 # we just alias the original method
214 # rather than re-produce it here
215 '_full_method_map' => \&Class::MOP::Package::_full_method_map
216 },
217 default => sub { {} }
218 ))
219);
220
221Class::MOP::Package->meta->add_attribute(
b1ff395f 222 Class::MOP::Attribute->new('method_metaclass' => (
223 reader => {
224 # NOTE:
225 # we just alias the original method
226 # rather than re-produce it here
227 'method_metaclass' => \&Class::MOP::Package::method_metaclass
228 },
229 default => 'Class::MOP::Method',
230 ))
231);
232
233Class::MOP::Package->meta->add_attribute(
234 Class::MOP::Attribute->new('wrapped_method_metaclass' => (
235 reader => {
236 # NOTE:
237 # we just alias the original method
238 # rather than re-produce it here
239 'wrapped_method_metaclass' => \&Class::MOP::Package::wrapped_method_metaclass
240 },
241 default => 'Class::MOP::Method::Wrapped',
242 ))
243);
244
f0480c45 245## --------------------------------------------------------
246## Class::MOP::Module
247
248# NOTE:
1d68af04 249# yeah this is kind of stretching things a bit,
f0480c45 250# but truthfully the version should be an attribute
1d68af04 251# of the Module, the weirdness comes from having to
252# stick to Perl 5 convention and store it in the
253# $VERSION package variable. Basically if you just
254# squint at it, it will look how you want it to look.
f0480c45 255# Either as a package variable, or as a attribute of
256# the metaclass, isn't abstraction great :)
257
258Class::MOP::Module->meta->add_attribute(
8683db0e 259 Class::MOP::Attribute->new('version' => (
f0480c45 260 reader => {
ce2ae40f 261 # NOTE:
262 # we just alias the original method
1d68af04 263 # rather than re-produce it here
ce2ae40f 264 'version' => \&Class::MOP::Module::version
f0480c45 265 },
2e877f58 266 init_arg => undef,
c4260b45 267 default => sub { \undef }
f0480c45 268 ))
269);
270
271# NOTE:
1d68af04 272# By following the same conventions as version here,
273# we are opening up the possibility that people can
274# use the $AUTHORITY in non-Class::MOP modules as
275# well.
f0480c45 276
277Class::MOP::Module->meta->add_attribute(
8683db0e 278 Class::MOP::Attribute->new('authority' => (
f0480c45 279 reader => {
ce2ae40f 280 # NOTE:
281 # we just alias the original method
1d68af04 282 # rather than re-produce it here
ce2ae40f 283 'authority' => \&Class::MOP::Module::authority
1d68af04 284 },
2e877f58 285 init_arg => undef,
c4260b45 286 default => sub { \undef }
f0480c45 287 ))
288);
289
290## --------------------------------------------------------
6d5355c3 291## Class::MOP::Class
292
727919c5 293Class::MOP::Class->meta->add_attribute(
8683db0e 294 Class::MOP::Attribute->new('attributes' => (
f7259199 295 reader => {
1d68af04 296 # NOTE: we need to do this in order
297 # for the instance meta-object to
298 # not fall into meta-circular death
299 #
ce2ae40f 300 # we just alias the original method
1d68af04 301 # rather than re-produce it here
ce2ae40f 302 'get_attribute_map' => \&Class::MOP::Class::get_attribute_map
f7259199 303 },
727919c5 304 default => sub { {} }
305 ))
306);
307
351bd7d4 308Class::MOP::Class->meta->add_attribute(
8683db0e 309 Class::MOP::Attribute->new('superclasses' => (
c23184fc 310 accessor => {
311 # NOTE:
312 # we just alias the original method
1d68af04 313 # rather than re-produce it here
c23184fc 314 'superclasses' => \&Class::MOP::Class::superclasses
315 },
2e877f58 316 init_arg => undef,
c23184fc 317 default => sub { \undef }
318 ))
319);
320
321Class::MOP::Class->meta->add_attribute(
8683db0e 322 Class::MOP::Attribute->new('attribute_metaclass' => (
1d68af04 323 reader => {
6d2118a4 324 # NOTE:
325 # we just alias the original method
1d68af04 326 # rather than re-produce it here
6d2118a4 327 'attribute_metaclass' => \&Class::MOP::Class::attribute_metaclass
1d68af04 328 },
351bd7d4 329 default => 'Class::MOP::Attribute',
330 ))
331);
332
333Class::MOP::Class->meta->add_attribute(
8683db0e 334 Class::MOP::Attribute->new('instance_metaclass' => (
b880e0de 335 reader => {
1d68af04 336 # NOTE: we need to do this in order
337 # for the instance meta-object to
338 # not fall into meta-circular death
339 #
ce2ae40f 340 # we just alias the original method
1d68af04 341 # rather than re-produce it here
ce2ae40f 342 'instance_metaclass' => \&Class::MOP::Class::instance_metaclass
b880e0de 343 },
1d68af04 344 default => 'Class::MOP::Instance',
2bab2be6 345 ))
346);
347
44d6ea77 348Class::MOP::Class->meta->add_attribute(
f5d08022 349 Class::MOP::Attribute->new('immutable_trait' => (
350 reader => {
351 'immutable_trait' => \&Class::MOP::Class::immutable_trait
352 },
353 default => "Class::MOP::Class::Immutable::Trait",
354 ))
355);
356
357Class::MOP::Class->meta->add_attribute(
358 Class::MOP::Attribute->new('constructor_name' => (
44d6ea77 359 reader => {
f5d08022 360 'constructor_name' => \&Class::MOP::Class::constructor_name,
44d6ea77 361 },
f5d08022 362 default => "new",
363 ))
364);
365
366Class::MOP::Class->meta->add_attribute(
367 Class::MOP::Attribute->new('constructor_class' => (
44d6ea77 368 reader => {
f5d08022 369 'constructor_class' => \&Class::MOP::Class::constructor_class,
44d6ea77 370 },
f5d08022 371 default => "Class::MOP::Method::Constructor",
372 ))
373);
374
375
376Class::MOP::Class->meta->add_attribute(
377 Class::MOP::Attribute->new('destructor_class' => (
378 reader => {
379 'destructor_class' => \&Class::MOP::Class::destructor_class,
44d6ea77 380 },
381 ))
382);
383
9d6dce77 384# NOTE:
1d68af04 385# we don't actually need to tie the knot with
386# Class::MOP::Class here, it is actually handled
387# within Class::MOP::Class itself in the
c2b256bc 388# _construct_class_instance method.
9d6dce77 389
f0480c45 390## --------------------------------------------------------
727919c5 391## Class::MOP::Attribute
392
7b31baf4 393Class::MOP::Attribute->meta->add_attribute(
8683db0e 394 Class::MOP::Attribute->new('name' => (
c23184fc 395 reader => {
1d68af04 396 # NOTE: we need to do this in order
397 # for the instance meta-object to
398 # not fall into meta-circular death
399 #
ce2ae40f 400 # we just alias the original method
1d68af04 401 # rather than re-produce it here
ce2ae40f 402 'name' => \&Class::MOP::Attribute::name
b880e0de 403 }
7b31baf4 404 ))
405);
406
407Class::MOP::Attribute->meta->add_attribute(
8683db0e 408 Class::MOP::Attribute->new('associated_class' => (
c23184fc 409 reader => {
1d68af04 410 # NOTE: we need to do this in order
411 # for the instance meta-object to
412 # not fall into meta-circular death
413 #
ce2ae40f 414 # we just alias the original method
1d68af04 415 # rather than re-produce it here
ce2ae40f 416 'associated_class' => \&Class::MOP::Attribute::associated_class
b880e0de 417 }
7b31baf4 418 ))
419);
420
421Class::MOP::Attribute->meta->add_attribute(
8683db0e 422 Class::MOP::Attribute->new('accessor' => (
6d2118a4 423 reader => { 'accessor' => \&Class::MOP::Attribute::accessor },
424 predicate => { 'has_accessor' => \&Class::MOP::Attribute::has_accessor },
7b31baf4 425 ))
426);
427
428Class::MOP::Attribute->meta->add_attribute(
8683db0e 429 Class::MOP::Attribute->new('reader' => (
6d2118a4 430 reader => { 'reader' => \&Class::MOP::Attribute::reader },
431 predicate => { 'has_reader' => \&Class::MOP::Attribute::has_reader },
7b31baf4 432 ))
433);
434
435Class::MOP::Attribute->meta->add_attribute(
8683db0e 436 Class::MOP::Attribute->new('initializer' => (
8ee74136 437 reader => { 'initializer' => \&Class::MOP::Attribute::initializer },
438 predicate => { 'has_initializer' => \&Class::MOP::Attribute::has_initializer },
0ab65f99 439 ))
440);
441
442Class::MOP::Attribute->meta->add_attribute(
d9d99689 443 Class::MOP::Attribute->new('definition_context' => (
444 reader => { 'definition_context' => \&Class::MOP::Attribute::definition_context },
445 ))
446);
447
448Class::MOP::Attribute->meta->add_attribute(
8683db0e 449 Class::MOP::Attribute->new('writer' => (
6d2118a4 450 reader => { 'writer' => \&Class::MOP::Attribute::writer },
451 predicate => { 'has_writer' => \&Class::MOP::Attribute::has_writer },
7b31baf4 452 ))
453);
454
455Class::MOP::Attribute->meta->add_attribute(
8683db0e 456 Class::MOP::Attribute->new('predicate' => (
6d2118a4 457 reader => { 'predicate' => \&Class::MOP::Attribute::predicate },
458 predicate => { 'has_predicate' => \&Class::MOP::Attribute::has_predicate },
7b31baf4 459 ))
460);
461
462Class::MOP::Attribute->meta->add_attribute(
8683db0e 463 Class::MOP::Attribute->new('clearer' => (
6d2118a4 464 reader => { 'clearer' => \&Class::MOP::Attribute::clearer },
465 predicate => { 'has_clearer' => \&Class::MOP::Attribute::has_clearer },
7d28758b 466 ))
467);
468
469Class::MOP::Attribute->meta->add_attribute(
8683db0e 470 Class::MOP::Attribute->new('builder' => (
1d68af04 471 reader => { 'builder' => \&Class::MOP::Attribute::builder },
472 predicate => { 'has_builder' => \&Class::MOP::Attribute::has_builder },
473 ))
474);
475
476Class::MOP::Attribute->meta->add_attribute(
8683db0e 477 Class::MOP::Attribute->new('init_arg' => (
6d2118a4 478 reader => { 'init_arg' => \&Class::MOP::Attribute::init_arg },
479 predicate => { 'has_init_arg' => \&Class::MOP::Attribute::has_init_arg },
7b31baf4 480 ))
481);
482
483Class::MOP::Attribute->meta->add_attribute(
06a88dbb 484 Class::MOP::Attribute->new('lazy' => (
485 reader => { 'is_lazy' => \&Class::MOP::Attribute::is_lazy },
486 ))
487);
488
489Class::MOP::Attribute->meta->add_attribute(
8683db0e 490 Class::MOP::Attribute->new('default' => (
7b31baf4 491 # default has a custom 'reader' method ...
1d68af04 492 predicate => { 'has_default' => \&Class::MOP::Attribute::has_default },
7b31baf4 493 ))
494);
495
3545c727 496Class::MOP::Attribute->meta->add_attribute(
8683db0e 497 Class::MOP::Attribute->new('associated_methods' => (
c23184fc 498 reader => { 'associated_methods' => \&Class::MOP::Attribute::associated_methods },
1d68af04 499 default => sub { [] }
3545c727 500 ))
501);
727919c5 502
95b67145 503Class::MOP::Attribute->meta->add_attribute(
504 Class::MOP::Attribute->new('insertion_order' => (
505 reader => { 'insertion_order' => \&Class::MOP::Attribute::insertion_order },
943cbe2d 506 writer => { '_set_insertion_order' => \&Class::MOP::Attribute::_set_insertion_order },
95b67145 507 predicate => { 'has_insertion_order' => \&Class::MOP::Attribute::has_insertion_order },
508 ))
509);
510
5659d76e 511Class::MOP::Attribute->meta->add_method('clone' => sub {
a740253a 512 my $self = shift;
1d68af04 513 $self->meta->clone_object($self, @_);
727919c5 514});
515
f0480c45 516## --------------------------------------------------------
b6164407 517## Class::MOP::Method
b6164407 518Class::MOP::Method->meta->add_attribute(
8683db0e 519 Class::MOP::Attribute->new('body' => (
868853dc 520 lazy => 1,
521 default => \&Class::MOP::Method::body,
b6164407 522 ))
523);
524
4c105333 525Class::MOP::Method->meta->add_attribute(
5e607260 526 Class::MOP::Attribute->new('associated_metaclass' => (
5e607260 527 reader => { 'associated_metaclass' => \&Class::MOP::Method::associated_metaclass },
528 ))
529);
530
531Class::MOP::Method->meta->add_attribute(
8683db0e 532 Class::MOP::Attribute->new('package_name' => (
4c105333 533 reader => { 'package_name' => \&Class::MOP::Method::package_name },
534 ))
535);
536
537Class::MOP::Method->meta->add_attribute(
8683db0e 538 Class::MOP::Attribute->new('name' => (
4c105333 539 reader => { 'name' => \&Class::MOP::Method::name },
540 ))
541);
542
2226a8b0 543Class::MOP::Method->meta->add_attribute(
544 Class::MOP::Attribute->new('original_method' => (
545 reader => { 'original_method' => \&Class::MOP::Method::original_method },
546 writer => { '_set_original_method' => \&Class::MOP::Method::_set_original_method },
547 ))
548);
549
4c105333 550Class::MOP::Method->meta->add_method('clone' => sub {
551 my $self = shift;
2226a8b0 552 my $clone = $self->meta->clone_object($self, @_);
553 $clone->_set_original_method($self);
554 return $clone;
4c105333 555});
556
b6164407 557## --------------------------------------------------------
558## Class::MOP::Method::Wrapped
559
560# NOTE:
1d68af04 561# the way this item is initialized, this
562# really does not follow the standard
563# practices of attributes, but we put
b6164407 564# it here for completeness
565Class::MOP::Method::Wrapped->meta->add_attribute(
8683db0e 566 Class::MOP::Attribute->new('modifier_table')
b6164407 567);
568
569## --------------------------------------------------------
565f0cbb 570## Class::MOP::Method::Generated
571
572Class::MOP::Method::Generated->meta->add_attribute(
8683db0e 573 Class::MOP::Attribute->new('is_inline' => (
565f0cbb 574 reader => { 'is_inline' => \&Class::MOP::Method::Generated::is_inline },
4c105333 575 default => 0,
1d68af04 576 ))
565f0cbb 577);
578
d9d99689 579Class::MOP::Method::Generated->meta->add_attribute(
580 Class::MOP::Attribute->new('definition_context' => (
581 reader => { 'definition_context' => \&Class::MOP::Method::Generated::definition_context },
582 ))
583);
584
29d4e92a 585
586## --------------------------------------------------------
587## Class::MOP::Method::Inlined
588
589Class::MOP::Method::Inlined->meta->add_attribute(
590 Class::MOP::Attribute->new('_expected_method_class' => (
591 reader => { '_expected_method_class' => \&Class::MOP::Method::Inlined::_expected_method_class },
592 ))
593);
594
565f0cbb 595## --------------------------------------------------------
d90b42a6 596## Class::MOP::Method::Accessor
597
598Class::MOP::Method::Accessor->meta->add_attribute(
8683db0e 599 Class::MOP::Attribute->new('attribute' => (
1d68af04 600 reader => {
601 'associated_attribute' => \&Class::MOP::Method::Accessor::associated_attribute
d90b42a6 602 },
1d68af04 603 ))
d90b42a6 604);
605
606Class::MOP::Method::Accessor->meta->add_attribute(
8683db0e 607 Class::MOP::Attribute->new('accessor_type' => (
c23184fc 608 reader => { 'accessor_type' => \&Class::MOP::Method::Accessor::accessor_type },
1d68af04 609 ))
d90b42a6 610);
611
d90b42a6 612## --------------------------------------------------------
613## Class::MOP::Method::Constructor
614
615Class::MOP::Method::Constructor->meta->add_attribute(
8683db0e 616 Class::MOP::Attribute->new('options' => (
1d68af04 617 reader => {
618 'options' => \&Class::MOP::Method::Constructor::options
d90b42a6 619 },
4c105333 620 default => sub { +{} }
1d68af04 621 ))
d90b42a6 622);
623
624Class::MOP::Method::Constructor->meta->add_attribute(
8683db0e 625 Class::MOP::Attribute->new('associated_metaclass' => (
e8a38403 626 init_arg => "metaclass", # FIXME alias and rename
1d68af04 627 reader => {
628 'associated_metaclass' => \&Class::MOP::Method::Constructor::associated_metaclass
629 },
630 ))
d90b42a6 631);
632
633## --------------------------------------------------------
86482605 634## Class::MOP::Instance
635
636# NOTE:
1d68af04 637# these don't yet do much of anything, but are just
86482605 638# included for completeness
639
640Class::MOP::Instance->meta->add_attribute(
74890687 641 Class::MOP::Attribute->new('associated_metaclass',
642 reader => { associated_metaclass => \&Class::MOP::Instance::associated_metaclass },
643 ),
86482605 644);
645
646Class::MOP::Instance->meta->add_attribute(
74890687 647 Class::MOP::Attribute->new('_class_name',
648 init_arg => undef,
649 reader => { _class_name => \&Class::MOP::Instance::_class_name },
650 #lazy => 1, # not yet supported by Class::MOP but out our version does it anyway
651 #default => sub { $_[0]->associated_metaclass->name },
652 ),
653);
654
655Class::MOP::Instance->meta->add_attribute(
656 Class::MOP::Attribute->new('attributes',
0b5d46da 657 reader => { attributes => \&Class::MOP::Instance::get_all_attributes },
74890687 658 ),
32bfc810 659);
660
661Class::MOP::Instance->meta->add_attribute(
74890687 662 Class::MOP::Attribute->new('slots',
663 reader => { slots => \&Class::MOP::Instance::slots },
664 ),
86482605 665);
666
63d08a9e 667Class::MOP::Instance->meta->add_attribute(
74890687 668 Class::MOP::Attribute->new('slot_hash',
669 reader => { slot_hash => \&Class::MOP::Instance::slot_hash },
670 ),
63d08a9e 671);
672
30229767 673require Class::MOP::Deprecated unless our $no_deprecated;
63d08a9e 674
caa051fa 675# we need the meta instance of the meta instance to be created now, in order
676# for the constructor to be able to use it
677Class::MOP::Instance->meta->get_meta_instance;
678
caa051fa 679# pretend the add_method never happenned. it hasn't yet affected anything
680undef Class::MOP::Instance->meta->{_package_cache_flag};
681
86482605 682## --------------------------------------------------------
f0480c45 683## Now close all the Class::MOP::* classes
4d47b77f 684
1aa13cf4 685# NOTE: we don't need to inline the the accessors this only lengthens
686# the compile time of the MOP, and gives us no actual benefits.
0b9372a2 687
688$_->meta->make_immutable(
ec9e38e5 689 inline_constructor => 0,
6c2f6b5c 690 constructor_name => "_new",
45582002 691 inline_accessors => 0,
0b9372a2 692) for qw/
1d68af04 693 Class::MOP::Package
694 Class::MOP::Module
695 Class::MOP::Class
696
0b9372a2 697 Class::MOP::Attribute
1d68af04 698 Class::MOP::Method
699 Class::MOP::Instance
700
701 Class::MOP::Object
0b9372a2 702
565f0cbb 703 Class::MOP::Method::Generated
29d4e92a 704 Class::MOP::Method::Inlined
1d68af04 705
ba38bf08 706 Class::MOP::Method::Accessor
1d68af04 707 Class::MOP::Method::Constructor
708 Class::MOP::Method::Wrapped
0b9372a2 709/;
b6164407 710
94b19069 7111;
712
713__END__
714
715=pod
716
1d68af04 717=head1 NAME
94b19069 718
719Class::MOP - A Meta Object Protocol for Perl 5
720
5b60bf98 721=head1 DESCRIPTION
94b19069 722
127d39a7 723This module is a fully functioning meta object protocol for the
1d68af04 724Perl 5 object system. It makes no attempt to change the behavior or
725characteristics of the Perl 5 object system, only to create a
27e31eaf 726protocol for its manipulation and introspection.
94b19069 727
828ecf13 728That said, it does attempt to create the tools for building a rich set
729of extensions to the Perl 5 object system. Every attempt has been made
730to abide by the spirit of the Perl 5 object system that we all know
731and love.
94b19069 732
828ecf13 733This documentation is sparse on conceptual details. We suggest looking
734at the items listed in the L<SEE ALSO> section for more
735information. In particular the book "The Art of the Meta Object
736Protocol" was very influential in the development of this system.
40483095 737
bfe4d0fc 738=head2 What is a Meta Object Protocol?
739
1d68af04 740A meta object protocol is an API to an object system.
bfe4d0fc 741
828ecf13 742To be more specific, it abstracts the components of an object system
743(classes, object, methods, object attributes, etc.). These
744abstractions can then be used to inspect and manipulate the object
745system which they describe.
bfe4d0fc 746
1d68af04 747It can be said that there are two MOPs for any object system; the
828ecf13 748implicit MOP and the explicit MOP. The implicit MOP handles things
1d68af04 749like method dispatch or inheritance, which happen automatically as
750part of how the object system works. The explicit MOP typically
751handles the introspection/reflection features of the object system.
bfe4d0fc 752
828ecf13 753All object systems have implicit MOPs. Without one, they would not
5b60bf98 754work. Explicit MOPs are much less common, and depending on the
755language can vary from restrictive (Reflection in Java or C#) to wide
756open (CLOS is a perfect example).
e16da3e6 757
828ecf13 758=head2 Yet Another Class Builder! Why?
759
760This is B<not> a class builder so much as a I<class builder
761B<builder>>. The intent is that an end user will not use this module
762directly, but instead this module is used by module authors to build
763extensions and features onto the Perl 5 object system.
764
765This system is used by L<Moose>, which supplies a powerful class
766builder system built entirely on top of C<Class::MOP>.
e16da3e6 767
94b19069 768=head2 Who is this module for?
769
828ecf13 770This module is for anyone who has ever created or wanted to create a
771module for the Class:: namespace. The tools which this module provides
772make doing complex Perl 5 wizardry simpler, by removing such barriers
773as the need to hack symbol tables, or understand the fine details of
774method dispatch.
94b19069 775
bfe4d0fc 776=head2 What changes do I have to make to use this module?
777
828ecf13 778This module was designed to be as unintrusive as possible. Many of its
5b60bf98 779features are accessible without B<any> change to your existing
828ecf13 780code. It is meant to be a compliment to your existing code and not an
781intrusion on your code base. Unlike many other B<Class::> modules,
782this module B<does not> require you subclass it, or even that you
783C<use> it in within your module's package.
bfe4d0fc 784
1d68af04 785The only features which requires additions to your code are the
2eb717d5 786attribute handling and instance construction features, and these are
1d68af04 787both completely optional features. The only reason for this is because
788Perl 5's object system does not actually have these features built
2eb717d5 789in. More information about this feature can be found below.
bfe4d0fc 790
828ecf13 791=head2 About Performance
792
5b60bf98 793It is a common misconception that explicit MOPs are a performance hit.
828ecf13 794This is not a universal truth, it is a side-effect of some specific
795implementations. For instance, using Java reflection is slow because
796the JVM cannot take advantage of any compiler optimizations, and the
797JVM has to deal with much more runtime type information as well.
bfe4d0fc 798
828ecf13 799Reflection in C# is marginally better as it was designed into the
800language and runtime (the CLR). In contrast, CLOS (the Common Lisp
801Object System) was built to support an explicit MOP, and so
802performance is tuned for it.
1d68af04 803
828ecf13 804This library in particular does its absolute best to avoid putting
1d68af04 805B<any> drain at all upon your code's performance. In fact, by itself
828ecf13 806it does nothing to affect your existing code. So you only pay for what
807you actually use.
bfe4d0fc 808
550d56db 809=head2 About Metaclass compatibility
810
1d68af04 811This module makes sure that all metaclasses created are both upwards
812and downwards compatible. The topic of metaclass compatibility is
813highly esoteric and is something only encountered when doing deep and
814involved metaclass hacking. There are two basic kinds of metaclass
815incompatibility; upwards and downwards.
550d56db 816
1d68af04 817Upwards metaclass compatibility means that the metaclass of a
818given class is either the same as (or a subclass of) all of the
550d56db 819class's ancestors.
820
1d68af04 821Downward metaclass compatibility means that the metaclasses of a
828ecf13 822given class's ancestors are all either the same as (or a subclass
550d56db 823of) that metaclass.
824
1d68af04 825Here is a diagram showing a set of two classes (C<A> and C<B>) and
826two metaclasses (C<Meta::A> and C<Meta::B>) which have correct
550d56db 827metaclass compatibility both upwards and downwards.
828
829 +---------+ +---------+
830 | Meta::A |<----| Meta::B | <....... (instance of )
1d68af04 831 +---------+ +---------+ <------- (inherits from)
550d56db 832 ^ ^
833 : :
834 +---------+ +---------+
835 | A |<----| B |
836 +---------+ +---------+
837
1d68af04 838As I said this is a highly esoteric topic and one you will only run
828ecf13 839into if you do a lot of subclassing of L<Class::MOP::Class>. If you
840are interested in why this is an issue see the paper I<Uniform and
841safe metaclass composition> linked to in the L<SEE ALSO> section of
842this document.
550d56db 843
aa448b16 844=head2 Using custom metaclasses
845
828ecf13 846Always use the L<metaclass> pragma when using a custom metaclass, this
5b60bf98 847will ensure the proper initialization order and not accidentally
848create an incorrect type of metaclass for you. This is a very rare
849problem, and one which can only occur if you are doing deep metaclass
aa448b16 850programming. So in other words, don't worry about it.
851
828ecf13 852Note that if you're using L<Moose> we encourage you to I<not> use
853L<metaclass> pragma, and instead use L<Moose::Util::MetaRole> to apply
854roles to a class's metaclasses. This topic is covered at length in
855various L<Moose::Cookbook> recipes.
856
94b19069 857=head1 PROTOCOLS
858
828ecf13 859The meta-object protocol is divided into 4 main sub-protocols:
94b19069 860
828ecf13 861=head2 The Class protocol
94b19069 862
1d68af04 863This provides a means of manipulating and introspecting a Perl 5
828ecf13 864class. It handles symbol table hacking for you, and provides a rich
865set of methods that go beyond simple package introspection.
94b19069 866
552e3d24 867See L<Class::MOP::Class> for more details.
868
828ecf13 869=head2 The Attribute protocol
94b19069 870
828ecf13 871This provides a consistent representation for an attribute of a Perl 5
872class. Since there are so many ways to create and handle attributes in
873Perl 5 OO, the Attribute protocol provide as much of a unified
874approach as possible. Of course, you are always free to extend this
875protocol by subclassing the appropriate classes.
94b19069 876
552e3d24 877See L<Class::MOP::Attribute> for more details.
878
828ecf13 879=head2 The Method protocol
94b19069 880
828ecf13 881This provides a means of manipulating and introspecting methods in the
882Perl 5 object system. As with attributes, there are many ways to
1d68af04 883approach this topic, so we try to keep it pretty basic, while still
94b19069 884making it possible to extend the system in many ways.
885
552e3d24 886See L<Class::MOP::Method> for more details.
94b19069 887
828ecf13 888=head2 The Instance protocol
127d39a7 889
828ecf13 890This provides a layer of abstraction for creating object instances.
891Since the other layers use this protocol, it is relatively easy to
892change the type of your instances from the default hash reference to
893some other type of reference. Several examples are provided in the
894F<examples/> directory included in this distribution.
127d39a7 895
896See L<Class::MOP::Instance> for more details.
897
be7677c7 898=head1 FUNCTIONS
899
828ecf13 900Note that this module does not export any constants or functions.
901
c1d5345a 902=head2 Constants
903
904=over 4
905
828ecf13 906=item I<Class::MOP::IS_RUNNING_ON_5_10>
c1d5345a 907
828ecf13 908We set this constant depending on what version perl we are on, this
909allows us to take advantage of new 5.10 features and stay backwards
5b60bf98 910compatible.
c1d5345a 911
912=back
913
448b6e55 914=head2 Utility functions
915
bd07fbdb 916Note that these are all called as B<functions, not methods>.
081a927b 917
448b6e55 918=over 4
919
828ecf13 920=item B<Class::MOP::load_class($class_name)>
448b6e55 921
9d441c23 922This will load the specified C<$class_name>, if it is not already
923loaded (as reported by C<is_class_loaded>). This function can be used
828ecf13 924in place of tricks like C<eval "use $module"> or using C<require>
7716a8f9 925unconditionally.
448b6e55 926
674d9359 927If the module cannot be loaded, an exception is thrown.
928
929For historical reasons, this function returns explicitly returns a true value.
930
828ecf13 931=item B<Class::MOP::is_class_loaded($class_name)>
448b6e55 932
15ab5451 933Returns a boolean indicating whether or not C<$class_name> has been
934loaded.
448b6e55 935
828ecf13 936This does a basic check of the symbol table to try and determine as
937best it can if the C<$class_name> is loaded, it is probably correct
938about 99% of the time, but it can be fooled into reporting false
9d441c23 939positives. In particular, loading any of the core L<IO> modules will
940cause most of the rest of the core L<IO> modules to falsely report
941having been loaded, due to the way the base L<IO> module works.
448b6e55 942
cdac22cc 943=item B<Class::MOP::get_code_info($code)>
944
945This function returns two values, the name of the package the C<$code>
946is from and the name of the C<$code> itself. This is used by several
5b60bf98 947elements of the MOP to determine where a given C<$code> reference is
cdac22cc 948from.
949
44ba77a3 950=item B<Class::MOP::class_of($instance_or_class_name)>
951
3fa5b3f9 952This will return the metaclass of the given instance or class name. If the
953class lacks a metaclass, no metaclass will be initialized, and C<undef> will be
954returned.
44ba77a3 955
828ecf13 956=item B<Class::MOP::check_package_cache_flag($pkg)>
e0e4674a 957
bd07fbdb 958B<NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!>
959
828ecf13 960This will return an integer that is managed by L<Class::MOP::Class> to
961determine if a module's symbol table has been altered.
127d39a7 962
828ecf13 963In Perl 5.10 or greater, this flag is package specific. However in
964versions prior to 5.10, this will use the C<PL_sub_generation>
965variable which is not package specific.
127d39a7 966
828ecf13 967=item B<Class::MOP::load_first_existing_class(@class_names)>
063ad0c5 968
969B<NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!>
970
971Given a list of class names, this function will attempt to load each
972one in turn.
973
828ecf13 974If it finds a class it can load, it will return that class' name. If
975none of the classes can be loaded, it will throw an exception.
063ad0c5 976
448b6e55 977=back
978
979=head2 Metaclass cache functions
980
6c842677 981Class::MOP holds a cache of metaclasses. The following are functions
1d68af04 982(B<not methods>) which can be used to access that cache. It is not
6c842677 983recommended that you mess with these. Bad things could happen, but if
984you are brave and willing to risk it: go for it!
be7677c7 985
986=over 4
987
828ecf13 988=item B<Class::MOP::get_all_metaclasses>
be7677c7 989
6c842677 990This will return a hash of all the metaclass instances that have
828ecf13 991been cached by L<Class::MOP::Class>, keyed by the package name.
b9d9fc0b 992
828ecf13 993=item B<Class::MOP::get_all_metaclass_instances>
be7677c7 994
6c842677 995This will return a list of all the metaclass instances that have
828ecf13 996been cached by L<Class::MOP::Class>.
b9d9fc0b 997
828ecf13 998=item B<Class::MOP::get_all_metaclass_names>
be7677c7 999
6c842677 1000This will return a list of all the metaclass names that have
828ecf13 1001been cached by L<Class::MOP::Class>.
b9d9fc0b 1002
828ecf13 1003=item B<Class::MOP::get_metaclass_by_name($name)>
be7677c7 1004
828ecf13 1005This will return a cached L<Class::MOP::Class> instance, or nothing
6c842677 1006if no metaclass exists with that C<$name>.
127d39a7 1007
828ecf13 1008=item B<Class::MOP::store_metaclass_by_name($name, $meta)>
be7677c7 1009
127d39a7 1010This will store a metaclass in the cache at the supplied C<$key>.
1011
828ecf13 1012=item B<Class::MOP::weaken_metaclass($name)>
be7677c7 1013
6c842677 1014In rare cases (e.g. anonymous metaclasses) it is desirable to
1015store a weakened reference in the metaclass cache. This
1016function will weaken the reference to the metaclass stored
1017in C<$name>.
127d39a7 1018
828ecf13 1019=item B<Class::MOP::does_metaclass_exist($name)>
be7677c7 1020
828ecf13 1021This will return true of there exists a metaclass stored in the
6c842677 1022C<$name> key, and return false otherwise.
127d39a7 1023
828ecf13 1024=item B<Class::MOP::remove_metaclass_by_name($name)>
be7677c7 1025
6c842677 1026This will remove the metaclass stored in the C<$name> key.
127d39a7 1027
be7677c7 1028=back
1029
552e3d24 1030=head1 SEE ALSO
8b978dd5 1031
552e3d24 1032=head2 Books
8b978dd5 1033
1d68af04 1034There are very few books out on Meta Object Protocols and Metaclasses
1035because it is such an esoteric topic. The following books are really
1036the only ones I have found. If you know of any more, B<I<please>>
a2e85e6c 1037email me and let me know, I would love to hear about them.
1038
8b978dd5 1039=over 4
1040
15ab5451 1041=item I<The Art of the Meta Object Protocol>
8b978dd5 1042
15ab5451 1043=item I<Advances in Object-Oriented Metalevel Architecture and Reflection>
8b978dd5 1044
15ab5451 1045=item I<Putting MetaClasses to Work>
b51af7f9 1046
15ab5451 1047=item I<Smalltalk: The Language>
a2e85e6c 1048
94b19069 1049=back
1050
550d56db 1051=head2 Papers
1052
1053=over 4
1054
15ab5451 1055=item "Uniform and safe metaclass composition"
550d56db 1056
1d68af04 1057An excellent paper by the people who brought us the original Traits paper.
1058This paper is on how Traits can be used to do safe metaclass composition,
1059and offers an excellent introduction section which delves into the topic of
550d56db 1060metaclass compatibility.
1061
1062L<http://www.iam.unibe.ch/~scg/Archive/Papers/Duca05ySafeMetaclassTrait.pdf>
1063
15ab5451 1064=item "Safe Metaclass Programming"
550d56db 1065
1d68af04 1066This paper seems to precede the above paper, and propose a mix-in based
1067approach as opposed to the Traits based approach. Both papers have similar
1068information on the metaclass compatibility problem space.
550d56db 1069
1070L<http://citeseer.ist.psu.edu/37617.html>
1071
1072=back
1073
552e3d24 1074=head2 Prior Art
8b978dd5 1075
1076=over 4
1077
7184ca14 1078=item The Perl 6 MetaModel work in the Pugs project
8b978dd5 1079
1080=over 4
1081
02615ef0 1082=item L<http://svn.openfoundry.org/pugs/misc/Perl-MetaModel/>
8b978dd5 1083
552e3d24 1084=item L<http://svn.openfoundry.org/pugs/perl5/Perl6-ObjectSpace>
8b978dd5 1085
1086=back
1087
94b19069 1088=back
1089
1d68af04 1090=head2 Articles
f8dfcfb7 1091
1092=over 4
1093
1d68af04 1094=item CPAN Module Review of Class::MOP
f8dfcfb7 1095
1096L<http://www.oreillynet.com/onlamp/blog/2006/06/cpan_module_review_classmop.html>
1097
1098=back
1099
a2e85e6c 1100=head1 SIMILAR MODULES
1101
1d68af04 1102As I have said above, this module is a class-builder-builder, so it is
1103not the same thing as modules like L<Class::Accessor> and
1104L<Class::MethodMaker>. That being said there are very few modules on CPAN
1105with similar goals to this module. The one I have found which is most
1106like this module is L<Class::Meta>, although it's philosophy and the MOP it
1107creates are very different from this modules.
94b19069 1108
a2e85e6c 1109=head1 BUGS
1110
1d68af04 1111All complex software has bugs lurking in it, and this module is no
53702399 1112exception.
1113
1114Please report any bugs to C<bug-class-mop@rt.cpan.org>, or through the
1115web interface at L<http://rt.cpan.org>.
1116
1117You can also discuss feature requests or possible bugs on the Moose
1118mailing list (moose@perl.org) or on IRC at
1119L<irc://irc.perl.org/#moose>.
a2e85e6c 1120
1121=head1 ACKNOWLEDGEMENTS
1122
1123=over 4
1124
b9d9fc0b 1125=item Rob Kinyon
a2e85e6c 1126
1d68af04 1127Thanks to Rob for actually getting the development of this module kick-started.
a2e85e6c 1128
1129=back
1130
1a09d9cc 1131=head1 AUTHORS
94b19069 1132
a2e85e6c 1133Stevan Little E<lt>stevan@iinteractive.comE<gt>
552e3d24 1134
9c8cda90 1135B<with contributions from:>
1136
1137Brandon (blblack) Black
1138
4f116037 1139Florian (rafl) Ragwitz
1140
9c8cda90 1141Guillermo (groditi) Roditi
1142
53702399 1143Dave (autarch) Rolsky
1144
9195ddff 1145Matt (mst) Trout
1146
9c8cda90 1147Rob (robkinyon) Kinyon
1148
1149Yuval (nothingmuch) Kogman
1a09d9cc 1150
f430cfa4 1151Scott (konobi) McWhirter
1152
20f5ccef 1153Dylan Hardison
1154
94b19069 1155=head1 COPYRIGHT AND LICENSE
1156
070bb6c9 1157Copyright 2006-2009 by Infinity Interactive, Inc.
94b19069 1158
1159L<http://www.iinteractive.com>
1160
1161This library is free software; you can redistribute it and/or modify
1d68af04 1162it under the same terms as Perl itself.
94b19069 1163
1164=cut