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