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 /;
 701
 702 $_->meta->make_immutable(
 703     inline_constructor  => 0,
 704     constructor_name    => undef,
 705     inline_accessors => 0,
 706 ) for qw/
 707     Class::MOP::Mixin
 708     Class::MOP::Mixin::AttributeCore
 709     Class::MOP::Mixin::HasAttributes
 710     Class::MOP::Mixin::HasMethods
 711 /;
 712
 713 1;
 714
 715 # ABSTRACT: A Meta Object Protocol for Perl 5
 716
 717 __END__
 718
 719 =pod
 720
 721 =head1 DESCRIPTION
 722
 723 This module is a fully functioning meta object protocol for the
 724 Perl 5 object system. It makes no attempt to change the behavior or
 725 characteristics of the Perl 5 object system, only to create a
 726 protocol for its manipulation and introspection.
 727
 728 That said, it does attempt to create the tools for building a rich set
 729 of extensions to the Perl 5 object system. Every attempt has been made
 730 to abide by the spirit of the Perl 5 object system that we all know
 731 and love.
 732
 733 This documentation is sparse on conceptual details. We suggest looking
 734 at the items listed in the L<SEE ALSO> section for more
 735 information. In particular the book "The Art of the Meta Object
 736 Protocol" was very influential in the development of this system.
 737
 738 =head2 What is a Meta Object Protocol?
 739
 740 A meta object protocol is an API to an object system.
 741
 742 To be more specific, it abstracts the components of an object system
 743 (classes, object, methods, object attributes, etc.). These
 744 abstractions can then be used to inspect and manipulate the object
 745 system which they describe.
 746
 747 It can be said that there are two MOPs for any object system; the
 748 implicit MOP and the explicit MOP. The implicit MOP handles things
 749 like method dispatch or inheritance, which happen automatically as
 750 part of how the object system works. The explicit MOP typically
 751 handles the introspection/reflection features of the object system.
 752
 753 All object systems have implicit MOPs. Without one, they would not
 754 work. Explicit MOPs are much less common, and depending on the
 755 language can vary from restrictive (Reflection in Java or C#) to wide
 756 open (CLOS is a perfect example).
 757
 758 =head2 Yet Another Class Builder! Why?
 759
 760 This is B<not> a class builder so much as a I<class builder
 761 B<builder>>. The intent is that an end user will not use this module
 762 directly, but instead this module is used by module authors to build
 763 extensions and features onto the Perl 5 object system.
 764
 765 This system is used by L<Moose>, which supplies a powerful class
 766 builder system built entirely on top of C<Class::MOP>.
 767
 768 =head2 Who is this module for?
 769
 770 This module is for anyone who has ever created or wanted to create a
 771 module for the Class:: namespace. The tools which this module provides
 772 make doing complex Perl 5 wizardry simpler, by removing such barriers
 773 as the need to hack symbol tables, or understand the fine details of
 774 method dispatch.
 775
 776 =head2 What changes do I have to make to use this module?
 777
 778 This module was designed to be as unintrusive as possible. Many of its
 779 features are accessible without B<any> change to your existing
 780 code. It is meant to be a complement to your existing code and not an
 781 intrusion on your code base. Unlike many other B<Class::> modules,
 782 this module B<does not> require you subclass it, or even that you
 783 C<use> it in within your module's package.
 784
 785 The only features which require additions to your code are the
 786 attribute handling and instance construction features, and these are
 787 both completely optional features. The only reason for this is because
 788 Perl 5's object system does not actually have these features built
 789 in. More information about this feature can be found below.
 790
 791 =head2 About Performance
 792
 793 It is a common misconception that explicit MOPs are a performance hit.
 794 This is not a universal truth, it is a side-effect of some specific
 795 implementations. For instance, using Java reflection is slow because
 796 the JVM cannot take advantage of any compiler optimizations, and the
 797 JVM has to deal with much more runtime type information as well.
 798
 799 Reflection in C# is marginally better as it was designed into the
 800 language and runtime (the CLR). In contrast, CLOS (the Common Lisp
 801 Object System) was built to support an explicit MOP, and so
 802 performance is tuned for it.
 803
 804 This library in particular does its absolute best to avoid putting
 805 B<any> drain at all upon your code's performance. In fact, by itself
 806 it does nothing to affect your existing code. So you only pay for what
 807 you actually use.
 808
 809 =head2 About Metaclass compatibility
 810
 811 This module makes sure that all metaclasses created are both upwards
 812 and downwards compatible. The topic of metaclass compatibility is
 813 highly esoteric and is something only encountered when doing deep and
 814 involved metaclass hacking. There are two basic kinds of metaclass
 815 incompatibility; upwards and downwards.
 816
 817 Upwards metaclass compatibility means that the metaclass of a
 818 given class is either the same as (or a subclass of) all of the
 819 class's ancestors.
 820
 821 Downward metaclass compatibility means that the metaclasses of a
 822 given class's ancestors are all the same as (or a subclass of) that
 823 metaclass.
 824
 825 Here is a diagram showing a set of two classes (C<A> and C<B>) and
 826 two metaclasses (C<Meta::A> and C<Meta::B>) which have correct
 827 metaclass compatibility both upwards and downwards.
 828
 829     +---------+     +---------+
 830     | Meta::A |<----| Meta::B |      <....... (instance of  )
 831     +---------+     +---------+      <------- (inherits from)
 832          ^               ^
 833          :               :
 834     +---------+     +---------+
 835     |    A    |<----|    B    |
 836     +---------+     +---------+
 837
 838 In actuality, I<all> of a class's metaclasses must be compatible,
 839 not just the class metaclass. That includes the instance, attribute,
 840 and method metaclasses, as well as the constructor and destructor
 841 classes.
 842
 843 C<Class::MOP> will attempt to fix some simple types of
 844 incompatibilities. If all the metaclasses for the parent class are
 845 I<subclasses> of the child's metaclasses then we can simply replace
 846 the child's metaclasses with the parent's. In addition, if the child
 847 is missing a metaclass that the parent has, we can also just make the
 848 child use the parent's metaclass.
 849
 850 As I said this is a highly esoteric topic and one you will only run
 851 into if you do a lot of subclassing of L<Class::MOP::Class>. If you
 852 are interested in why this is an issue see the paper I<Uniform and
 853 safe metaclass composition> linked to in the L<SEE ALSO> section of
 854 this document.
 855
 856 =head2 Using custom metaclasses
 857
 858 Always use the L<metaclass> pragma when using a custom metaclass, this
 859 will ensure the proper initialization order and not accidentally
 860 create an incorrect type of metaclass for you. This is a very rare
 861 problem, and one which can only occur if you are doing deep metaclass
 862 programming. So in other words, don't worry about it.
 863
 864 Note that if you're using L<Moose> we encourage you to I<not> use the
 865 L<metaclass> pragma, and instead use L<Moose::Util::MetaRole> to apply
 866 roles to a class's metaclasses. This topic is covered at length in
 867 various L<Moose::Cookbook> recipes.
 868
 869 =head1 PROTOCOLS
 870
 871 The meta-object protocol is divided into 4 main sub-protocols:
 872
 873 =head2 The Class protocol
 874
 875 This provides a means of manipulating and introspecting a Perl 5
 876 class. It handles symbol table hacking for you, and provides a rich
 877 set of methods that go beyond simple package introspection.
 878
 879 See L<Class::MOP::Class> for more details.
 880
 881 =head2 The Attribute protocol
 882
 883 This provides a consistent representation for an attribute of a Perl 5
 884 class. Since there are so many ways to create and handle attributes in
 885 Perl 5 OO, the Attribute protocol provide as much of a unified
 886 approach as possible. Of course, you are always free to extend this
 887 protocol by subclassing the appropriate classes.
 888
 889 See L<Class::MOP::Attribute> for more details.
 890
 891 =head2 The Method protocol
 892
 893 This provides a means of manipulating and introspecting methods in the
 894 Perl 5 object system. As with attributes, there are many ways to
 895 approach this topic, so we try to keep it pretty basic, while still
 896 making it possible to extend the system in many ways.
 897
 898 See L<Class::MOP::Method> for more details.
 899
 900 =head2 The Instance protocol
 901
 902 This provides a layer of abstraction for creating object instances.
 903 Since the other layers use this protocol, it is relatively easy to
 904 change the type of your instances from the default hash reference to
 905 some other type of reference. Several examples are provided in the
 906 F<examples/> directory included in this distribution.
 907
 908 See L<Class::MOP::Instance> for more details.
 909
 910 =head1 FUNCTIONS
 911
 912 Note that this module does not export any constants or functions.
 913
 914 =head2 Utility functions
 915
 916 Note that these are all called as B<functions, not methods>.
 917
 918 =over 4
 919
 920 =item B<Class::MOP::get_code_info($code)>
 921
 922 This function returns two values, the name of the package the C<$code>
 923 is from and the name of the C<$code> itself. This is used by several
 924 elements of the MOP to determine where a given C<$code> reference is
 925 from.
 926
 927 =item B<Class::MOP::class_of($instance_or_class_name)>
 928
 929 This will return the metaclass of the given instance or class name.  If the
 930 class lacks a metaclass, no metaclass will be initialized, and C<undef> will be
 931 returned.
 932
 933 =back
 934
 935 =head2 Metaclass cache functions
 936
 937 C<Class::MOP> holds a cache of metaclasses. The following are functions
 938 (B<not methods>) which can be used to access that cache. It is not
 939 recommended that you mess with these. Bad things could happen, but if
 940 you are brave and willing to risk it: go for it!
 941
 942 =over 4
 943
 944 =item B<Class::MOP::get_all_metaclasses>
 945
 946 This will return a hash of all the metaclass instances that have
 947 been cached by L<Class::MOP::Class>, keyed by the package name.
 948
 949 =item B<Class::MOP::get_all_metaclass_instances>
 950
 951 This will return a list of all the metaclass instances that have
 952 been cached by L<Class::MOP::Class>.
 953
 954 =item B<Class::MOP::get_all_metaclass_names>
 955
 956 This will return a list of all the metaclass names that have
 957 been cached by L<Class::MOP::Class>.
 958
 959 =item B<Class::MOP::get_metaclass_by_name($name)>
 960
 961 This will return a cached L<Class::MOP::Class> instance, or nothing
 962 if no metaclass exists with that C<$name>.
 963
 964 =item B<Class::MOP::store_metaclass_by_name($name, $meta)>
 965
 966 This will store a metaclass in the cache at the supplied C<$key>.
 967
 968 =item B<Class::MOP::weaken_metaclass($name)>
 969
 970 In rare cases (e.g. anonymous metaclasses) it is desirable to
 971 store a weakened reference in the metaclass cache. This
 972 function will weaken the reference to the metaclass stored
 973 in C<$name>.
 974
 975 =item B<Class::MOP::metaclass_is_weak($name)>
 976
 977 Returns true if the metaclass for C<$name> has been weakened
 978 (via C<weaken_metaclass>).
 979
 980 =item B<Class::MOP::does_metaclass_exist($name)>
 981
 982 This will return true of there exists a metaclass stored in the
 983 C<$name> key, and return false otherwise.
 984
 985 =item B<Class::MOP::remove_metaclass_by_name($name)>
 986
 987 This will remove the metaclass stored in the C<$name> key.
 988
 989 =back
 990
 991 Some utility functions (such as C<Class::MOP::load_class>) that were
 992 previously defined in C<Class::MOP> regarding loading of classes have been
 993 extracted to L<Class::Load>. Please see L<Class::Load> for documentation.
 994
 995 =head1 SEE ALSO
 996
 997 =head2 Books
 998
 999 There are very few books out on Meta Object Protocols and Metaclasses
1000 because it is such an esoteric topic. The following books are really
1001 the only ones I have found. If you know of any more, B<I<please>>
1002 email me and let me know, I would love to hear about them.
1003
1004 =over 4
1005
1006 =item I<The Art of the Meta Object Protocol>
1007
1008 =item I<Advances in Object-Oriented Metalevel Architecture and Reflection>
1009
1010 =item I<Putting MetaClasses to Work>
1011
1012 =item I<Smalltalk: The Language>
1013
1014 =back
1015
1016 =head2 Papers
1017
1018 =over 4
1019
1020 =item "Uniform and safe metaclass composition"
1021
1022 An excellent paper by the people who brought us the original Traits paper.
1023 This paper is on how Traits can be used to do safe metaclass composition,
1024 and offers an excellent introduction section which delves into the topic of
1025 metaclass compatibility.
1026
1027 L<http://scg.unibe.ch/archive/papers/Duca05ySafeMetaclassTrait.pdf>
1028
1029 =item "Safe Metaclass Programming"
1030
1031 This paper seems to precede the above paper, and propose a mix-in based
1032 approach as opposed to the Traits based approach. Both papers have similar
1033 information on the metaclass compatibility problem space.
1034
1035 L<http://citeseer.ist.psu.edu/37617.html>
1036
1037 =back
1038
1039 =head2 Prior Art
1040
1041 =over 4
1042
1043 =item The Perl 6 MetaModel work in the Pugs project
1044
1045 =over 4
1046
1047 =item L<http://svn.openfoundry.org/pugs/misc/Perl-MetaModel/>
1048
1049 =item L<http://github.com/perl6/p5-modules/tree/master/Perl6-ObjectSpace/>
1050
1051 =back
1052
1053 =back
1054
1055 =head2 Articles
1056
1057 =over 4
1058
1059 =item CPAN Module Review of Class::MOP
1060
1061 L<http://www.oreillynet.com/onlamp/blog/2006/06/cpan_module_review_classmop.html>
1062
1063 =back
1064
1065 =head1 SIMILAR MODULES
1066
1067 As I have said above, this module is a class-builder-builder, so it is
1068 not the same thing as modules like L<Class::Accessor> and
1069 L<Class::MethodMaker>. That being said there are very few modules on CPAN
1070 with similar goals to this module. The one I have found which is most
1071 like this module is L<Class::Meta>, although its philosophy and the MOP it
1072 creates are very different from this modules.
1073
1074 =head1 BUGS
1075
1076 All complex software has bugs lurking in it, and this module is no
1077 exception.
1078
1079 Please report any bugs to C<bug-class-mop@rt.cpan.org>, or through the
1080 web interface at L<http://rt.cpan.org>.
1081
1082 You can also discuss feature requests or possible bugs on the Moose
1083 mailing list (moose@perl.org) or on IRC at
1084 L<irc://irc.perl.org/#moose>.
1085
1086 =head1 ACKNOWLEDGEMENTS
1087
1088 =over 4
1089
1090 =item Rob Kinyon
1091
1092 Thanks to Rob for actually getting the development of this module kick-started.
1093
1094 =back
1095
1096 =cut