lib/Class/MOP.pm

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