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