lib/Class/MOP.pm

   1 package Class::MOP;
   2
   3 use strict;
   4 use warnings;
   5
   6 use 5.008;
   7
   8 use MRO::Compat;
   9
  10 use Carp          'confess';
  11 use Scalar::Util  'weaken', 'reftype', 'blessed';
  12 use Try::Tiny;
  13
  14 use Class::MOP::Mixin::AttributeCore;
  15 use Class::MOP::Mixin::HasAttributes;
  16 use Class::MOP::Mixin::HasMethods;
  17 use Class::MOP::Class;
  18 use Class::MOP::Attribute;
  19 use Class::MOP::Method;
  20
  21 BEGIN {
  22     *IS_RUNNING_ON_5_10 = ($] < 5.009_005)
  23         ? sub () { 0 }
  24         : sub () { 1 };
  25
  26     # this is either part of core or set up appropriately by MRO::Compat
  27     *check_package_cache_flag = \&mro::get_pkg_gen;
  28 }
  29
  30 our $VERSION   = '0.98';
  31 our $XS_VERSION = $VERSION;
  32 $VERSION = eval $VERSION;
  33 our $AUTHORITY = 'cpan:STEVAN';
  34
  35 require XSLoader;
  36 XSLoader::load( __PACKAGE__, $XS_VERSION );
  37
  38
  39 {
  40     # Metaclasses are singletons, so we cache them here.
  41     # there is no need to worry about destruction though
  42     # because they should die only when the program dies.
  43     # After all, do package definitions even get reaped?
  44     # Anonymous classes manage their own destruction.
  45     my %METAS;
  46
  47     sub get_all_metaclasses         {        %METAS         }
  48     sub get_all_metaclass_instances { values %METAS         }
  49     sub get_all_metaclass_names     { keys   %METAS         }
  50     sub get_metaclass_by_name       { $METAS{$_[0]}         }
  51     sub store_metaclass_by_name     { $METAS{$_[0]} = $_[1] }
  52     sub weaken_metaclass            { weaken($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 _class_to_pmfile {
  71     my $class = shift;
  72
  73     my $file = $class . '.pm';
  74     $file =~ s{::}{/}g;
  75
  76     return $file;
  77 }
  78
  79 sub load_first_existing_class {
  80     my @classes = @_
  81       or return;
  82
  83     foreach my $class (@classes) {
  84         unless ( _is_valid_class_name($class) ) {
  85             my $display = defined($class) ? $class : 'undef';
  86             confess "Invalid class name ($display)";
  87         }
  88     }
  89
  90     my $file_loaded;
  91     for my $class (@classes) {
  92
  93         return $class if is_class_loaded($class);;
  94
  95         my $file = _class_to_pmfile($class);
  96
  97         $file_loaded =
  98             try {
  99                 local $SIG{__DIE__};
 100                 require $file;
 101                 return [$class, $file];
 102             }
 103             catch {
 104                 unless (/^Can't locate \Q$file\E in \@INC/) {
 105                     confess "Couldn't load class ($class) because: $_";
 106                 }
 107                 return;
 108             };
 109
 110         return $class if $file_loaded && is_class_loaded($class);
 111     }
 112
 113     if( $file_loaded ) {
 114         confess "$file_loaded->[0] is empty or missing in file $file_loaded->[1]";
 115     }
 116     elsif ( @classes > 1 ) {
 117         confess "Can't locate any of @classes in \@INC (\@INC contains: @INC).";
 118     }
 119     else {
 120         confess "Can't locate " . _class_to_pmfile($classes[0]) . " in \@INC (\@INC contains: @INC).";
 121     }
 122 }
 123
 124 sub load_class {
 125     load_first_existing_class($_[0]);
 126
 127     # This is done to avoid breaking code which checked the return value. Said
 128     # code is dumb. The return value was _always_ true, since it dies on
 129     # failure!
 130     return 1;
 131 }
 132
 133 sub _is_valid_class_name {
 134     my $class = shift;
 135
 136     return 0 if ref($class);
 137     return 0 unless defined($class);
 138     return 0 unless length($class);
 139
 140     return 1 if $class =~ /^\w+(?:::\w+)*$/;
 141
 142     return 0;
 143 }
 144
 145 ## ----------------------------------------------------------------------------
 146 ## Setting up our environment ...
 147 ## ----------------------------------------------------------------------------
 148 ## Class::MOP needs to have a few things in the global perl environment so
 149 ## that it can operate effectively. Those things are done here.
 150 ## ----------------------------------------------------------------------------
 151
 152 # ... nothing yet actually ;)
 153
 154 ## ----------------------------------------------------------------------------
 155 ## Bootstrapping
 156 ## ----------------------------------------------------------------------------
 157 ## The code below here is to bootstrap our MOP with itself. This is also
 158 ## sometimes called "tying the knot". By doing this, we make it much easier
 159 ## to extend the MOP through subclassing and such since now you can use the
 160 ## MOP itself to extend itself.
 161 ##
 162 ## Yes, I know, thats weird and insane, but it's a good thing, trust me :)
 163 ## ----------------------------------------------------------------------------
 164
 165 # We need to add in the meta-attributes here so that
 166 # any subclass of Class::MOP::* will be able to
 167 # inherit them using _construct_instance
 168
 169 ## --------------------------------------------------------
 170 ## Class::MOP::Mixin::HasMethods
 171
 172 Class::MOP::Mixin::HasMethods->meta->add_attribute(
 173     Class::MOP::Attribute->new('_methods' => (
 174         reader   => {
 175             # NOTE:
 176             # we just alias the original method
 177             # rather than re-produce it here
 178             '_full_method_map' => \&Class::MOP::Mixin::HasMethods::_full_method_map
 179         },
 180         default => sub { {} }
 181     ))
 182 );
 183
 184 Class::MOP::Mixin::HasMethods->meta->add_attribute(
 185     Class::MOP::Attribute->new('method_metaclass' => (
 186         reader   => {
 187             # NOTE:
 188             # we just alias the original method
 189             # rather than re-produce it here
 190             'method_metaclass' => \&Class::MOP::Mixin::HasMethods::method_metaclass
 191         },
 192         default  => 'Class::MOP::Method',
 193     ))
 194 );
 195
 196 Class::MOP::Mixin::HasMethods->meta->add_attribute(
 197     Class::MOP::Attribute->new('wrapped_method_metaclass' => (
 198         reader   => {
 199             # NOTE:
 200             # we just alias the original method
 201             # rather than re-produce it here
 202             'wrapped_method_metaclass' => \&Class::MOP::Mixin::HasMethods::wrapped_method_metaclass
 203         },
 204         default  => 'Class::MOP::Method::Wrapped',
 205     ))
 206 );
 207
 208 ## --------------------------------------------------------
 209 ## Class::MOP::Mixin::HasMethods
 210
 211 Class::MOP::Mixin::HasAttributes->meta->add_attribute(
 212     Class::MOP::Attribute->new('attributes' => (
 213         reader   => {
 214             # NOTE: we need to do this in order
 215             # for the instance meta-object to
 216             # not fall into meta-circular death
 217             #
 218             # we just alias the original method
 219             # rather than re-produce it here
 220             '_attribute_map' => \&Class::MOP::Mixin::HasAttributes::_attribute_map
 221         },
 222         default  => sub { {} }
 223     ))
 224 );
 225
 226 Class::MOP::Mixin::HasAttributes->meta->add_attribute(
 227     Class::MOP::Attribute->new('attribute_metaclass' => (
 228         reader   => {
 229             # NOTE:
 230             # we just alias the original method
 231             # rather than re-produce it here
 232             'attribute_metaclass' => \&Class::MOP::Mixin::HasAttributes::attribute_metaclass
 233         },
 234         default  => 'Class::MOP::Attribute',
 235     ))
 236 );
 237
 238 ## --------------------------------------------------------
 239 ## Class::MOP::Package
 240
 241 Class::MOP::Package->meta->add_attribute(
 242     Class::MOP::Attribute->new('package' => (
 243         reader   => {
 244             # NOTE: we need to do this in order
 245             # for the instance meta-object to
 246             # not fall into meta-circular death
 247             #
 248             # we just alias the original method
 249             # rather than re-produce it here
 250             'name' => \&Class::MOP::Package::name
 251         },
 252     ))
 253 );
 254
 255 Class::MOP::Package->meta->add_attribute(
 256     Class::MOP::Attribute->new('namespace' => (
 257         reader => {
 258             # NOTE:
 259             # we just alias the original method
 260             # rather than re-produce it here
 261             'namespace' => \&Class::MOP::Package::namespace
 262         },
 263         init_arg => undef,
 264         default  => sub { \undef }
 265     ))
 266 );
 267
 268 ## --------------------------------------------------------
 269 ## Class::MOP::Module
 270
 271 # NOTE:
 272 # yeah this is kind of stretching things a bit,
 273 # but truthfully the version should be an attribute
 274 # of the Module, the weirdness comes from having to
 275 # stick to Perl 5 convention and store it in the
 276 # $VERSION package variable. Basically if you just
 277 # squint at it, it will look how you want it to look.
 278 # Either as a package variable, or as a attribute of
 279 # the metaclass, isn't abstraction great :)
 280
 281 Class::MOP::Module->meta->add_attribute(
 282     Class::MOP::Attribute->new('version' => (
 283         reader => {
 284             # NOTE:
 285             # we just alias the original method
 286             # rather than re-produce it here
 287             'version' => \&Class::MOP::Module::version
 288         },
 289         init_arg => undef,
 290         default  => sub { \undef }
 291     ))
 292 );
 293
 294 # NOTE:
 295 # By following the same conventions as version here,
 296 # we are opening up the possibility that people can
 297 # use the $AUTHORITY in non-Class::MOP modules as
 298 # well.
 299
 300 Class::MOP::Module->meta->add_attribute(
 301     Class::MOP::Attribute->new('authority' => (
 302         reader => {
 303             # NOTE:
 304             # we just alias the original method
 305             # rather than re-produce it here
 306             'authority' => \&Class::MOP::Module::authority
 307         },
 308         init_arg => undef,
 309         default  => sub { \undef }
 310     ))
 311 );
 312
 313 ## --------------------------------------------------------
 314 ## Class::MOP::Class
 315
 316 Class::MOP::Class->meta->add_attribute(
 317     Class::MOP::Attribute->new('superclasses' => (
 318         accessor => {
 319             # NOTE:
 320             # we just alias the original method
 321             # rather than re-produce it here
 322             'superclasses' => \&Class::MOP::Class::superclasses
 323         },
 324         init_arg => undef,
 325         default  => sub { \undef }
 326     ))
 327 );
 328
 329 Class::MOP::Class->meta->add_attribute(
 330     Class::MOP::Attribute->new('instance_metaclass' => (
 331         reader   => {
 332             # NOTE: we need to do this in order
 333             # for the instance meta-object to
 334             # not fall into meta-circular death
 335             #
 336             # we just alias the original method
 337             # rather than re-produce it here
 338             'instance_metaclass' => \&Class::MOP::Class::instance_metaclass
 339         },
 340         default  => 'Class::MOP::Instance',
 341     ))
 342 );
 343
 344 Class::MOP::Class->meta->add_attribute(
 345     Class::MOP::Attribute->new('immutable_trait' => (
 346         reader   => {
 347             'immutable_trait' => \&Class::MOP::Class::immutable_trait
 348         },
 349         default => "Class::MOP::Class::Immutable::Trait",
 350     ))
 351 );
 352
 353 Class::MOP::Class->meta->add_attribute(
 354     Class::MOP::Attribute->new('constructor_name' => (
 355         reader   => {
 356             'constructor_name' => \&Class::MOP::Class::constructor_name,
 357         },
 358         default => "new",
 359     ))
 360 );
 361
 362 Class::MOP::Class->meta->add_attribute(
 363     Class::MOP::Attribute->new('constructor_class' => (
 364         reader   => {
 365             'constructor_class' => \&Class::MOP::Class::constructor_class,
 366         },
 367         default => "Class::MOP::Method::Constructor",
 368     ))
 369 );
 370
 371
 372 Class::MOP::Class->meta->add_attribute(
 373     Class::MOP::Attribute->new('destructor_class' => (
 374         reader   => {
 375             'destructor_class' => \&Class::MOP::Class::destructor_class,
 376         },
 377     ))
 378 );
 379
 380 # NOTE:
 381 # we don't actually need to tie the knot with
 382 # Class::MOP::Class here, it is actually handled
 383 # within Class::MOP::Class itself in the
 384 # _construct_class_instance method.
 385
 386 ## --------------------------------------------------------
 387 ## Class::MOP::Mixin::AttributeCore
 388 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 389     Class::MOP::Attribute->new('name' => (
 390         reader   => {
 391             # NOTE: we need to do this in order
 392             # for the instance meta-object to
 393             # not fall into meta-circular death
 394             #
 395             # we just alias the original method
 396             # rather than re-produce it here
 397             'name' => \&Class::MOP::Mixin::AttributeCore::name
 398         }
 399     ))
 400 );
 401
 402 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 403     Class::MOP::Attribute->new('accessor' => (
 404         reader    => { 'accessor'     => \&Class::MOP::Mixin::AttributeCore::accessor     },
 405         predicate => { 'has_accessor' => \&Class::MOP::Mixin::AttributeCore::has_accessor },
 406     ))
 407 );
 408
 409 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 410     Class::MOP::Attribute->new('reader' => (
 411         reader    => { 'reader'     => \&Class::MOP::Mixin::AttributeCore::reader     },
 412         predicate => { 'has_reader' => \&Class::MOP::Mixin::AttributeCore::has_reader },
 413     ))
 414 );
 415
 416 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 417     Class::MOP::Attribute->new('initializer' => (
 418         reader    => { 'initializer'     => \&Class::MOP::Mixin::AttributeCore::initializer     },
 419         predicate => { 'has_initializer' => \&Class::MOP::Mixin::AttributeCore::has_initializer },
 420     ))
 421 );
 422
 423 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 424     Class::MOP::Attribute->new('definition_context' => (
 425         reader    => { 'definition_context'     => \&Class::MOP::Mixin::AttributeCore::definition_context     },
 426     ))
 427 );
 428
 429 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 430     Class::MOP::Attribute->new('writer' => (
 431         reader    => { 'writer'     => \&Class::MOP::Mixin::AttributeCore::writer     },
 432         predicate => { 'has_writer' => \&Class::MOP::Mixin::AttributeCore::has_writer },
 433     ))
 434 );
 435
 436 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 437     Class::MOP::Attribute->new('predicate' => (
 438         reader    => { 'predicate'     => \&Class::MOP::Mixin::AttributeCore::predicate     },
 439         predicate => { 'has_predicate' => \&Class::MOP::Mixin::AttributeCore::has_predicate },
 440     ))
 441 );
 442
 443 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 444     Class::MOP::Attribute->new('clearer' => (
 445         reader    => { 'clearer'     => \&Class::MOP::Mixin::AttributeCore::clearer     },
 446         predicate => { 'has_clearer' => \&Class::MOP::Mixin::AttributeCore::has_clearer },
 447     ))
 448 );
 449
 450 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 451     Class::MOP::Attribute->new('builder' => (
 452         reader    => { 'builder'     => \&Class::MOP::Mixin::AttributeCore::builder     },
 453         predicate => { 'has_builder' => \&Class::MOP::Mixin::AttributeCore::has_builder },
 454     ))
 455 );
 456
 457 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 458     Class::MOP::Attribute->new('init_arg' => (
 459         reader    => { 'init_arg'     => \&Class::MOP::Mixin::AttributeCore::init_arg     },
 460         predicate => { 'has_init_arg' => \&Class::MOP::Mixin::AttributeCore::has_init_arg },
 461     ))
 462 );
 463
 464 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 465     Class::MOP::Attribute->new('default' => (
 466         # default has a custom 'reader' method ...
 467         predicate => { 'has_default' => \&Class::MOP::Mixin::AttributeCore::has_default },
 468     ))
 469 );
 470
 471 Class::MOP::Mixin::AttributeCore->meta->add_attribute(
 472     Class::MOP::Attribute->new('insertion_order' => (
 473         reader      => { 'insertion_order' => \&Class::MOP::Mixin::AttributeCore::insertion_order },
 474         writer      => { '_set_insertion_order' => \&Class::MOP::Mixin::AttributeCore::_set_insertion_order },
 475         predicate   => { 'has_insertion_order' => \&Class::MOP::Mixin::AttributeCore::has_insertion_order },
 476     ))
 477 );
 478
 479 ## --------------------------------------------------------
 480 ## Class::MOP::Attribute
 481 Class::MOP::Attribute->meta->add_attribute(
 482     Class::MOP::Attribute->new('associated_class' => (
 483         reader   => {
 484             # NOTE: we need to do this in order
 485             # for the instance meta-object to
 486             # not fall into meta-circular death
 487             #
 488             # we just alias the original method
 489             # rather than re-produce it here
 490             'associated_class' => \&Class::MOP::Attribute::associated_class
 491         }
 492     ))
 493 );
 494
 495 Class::MOP::Attribute->meta->add_attribute(
 496     Class::MOP::Attribute->new('associated_methods' => (
 497         reader   => { 'associated_methods' => \&Class::MOP::Attribute::associated_methods },
 498         default  => sub { [] }
 499     ))
 500 );
 501
 502 Class::MOP::Attribute->meta->add_method('clone' => sub {
 503     my $self  = shift;
 504     $self->meta->clone_object($self, @_);
 505 });
 506
 507 ## --------------------------------------------------------
 508 ## Class::MOP::Method
 509 Class::MOP::Method->meta->add_attribute(
 510     Class::MOP::Attribute->new('body' => (
 511         reader   => { 'body' => \&Class::MOP::Method::body },
 512     ))
 513 );
 514
 515 Class::MOP::Method->meta->add_attribute(
 516     Class::MOP::Attribute->new('associated_metaclass' => (
 517         reader   => { 'associated_metaclass' => \&Class::MOP::Method::associated_metaclass },
 518     ))
 519 );
 520
 521 Class::MOP::Method->meta->add_attribute(
 522     Class::MOP::Attribute->new('package_name' => (
 523         reader   => { 'package_name' => \&Class::MOP::Method::package_name },
 524     ))
 525 );
 526
 527 Class::MOP::Method->meta->add_attribute(
 528     Class::MOP::Attribute->new('name' => (
 529         reader   => { 'name' => \&Class::MOP::Method::name },
 530     ))
 531 );
 532
 533 Class::MOP::Method->meta->add_attribute(
 534     Class::MOP::Attribute->new('original_method' => (
 535         reader   => { 'original_method'      => \&Class::MOP::Method::original_method },
 536         writer   => { '_set_original_method' => \&Class::MOP::Method::_set_original_method },
 537     ))
 538 );
 539
 540 Class::MOP::Method->meta->add_method('clone' => sub {
 541     my $self  = shift;
 542     my $clone = $self->meta->clone_object($self, @_);
 543     $clone->_set_original_method($self);
 544     return $clone;
 545 });
 546
 547 ## --------------------------------------------------------
 548 ## Class::MOP::Method::Wrapped
 549
 550 # NOTE:
 551 # the way this item is initialized, this
 552 # really does not follow the standard
 553 # practices of attributes, but we put
 554 # it here for completeness
 555 Class::MOP::Method::Wrapped->meta->add_attribute(
 556     Class::MOP::Attribute->new('modifier_table')
 557 );
 558
 559 ## --------------------------------------------------------
 560 ## Class::MOP::Method::Generated
 561
 562 Class::MOP::Method::Generated->meta->add_attribute(
 563     Class::MOP::Attribute->new('is_inline' => (
 564         reader   => { 'is_inline' => \&Class::MOP::Method::Generated::is_inline },
 565         default  => 0,
 566     ))
 567 );
 568
 569 Class::MOP::Method::Generated->meta->add_attribute(
 570     Class::MOP::Attribute->new('definition_context' => (
 571         reader   => { 'definition_context' => \&Class::MOP::Method::Generated::definition_context },
 572     ))
 573 );
 574
 575
 576 ## --------------------------------------------------------
 577 ## Class::MOP::Method::Inlined
 578
 579 Class::MOP::Method::Inlined->meta->add_attribute(
 580     Class::MOP::Attribute->new('_expected_method_class' => (
 581         reader   => { '_expected_method_class' => \&Class::MOP::Method::Inlined::_expected_method_class },
 582     ))
 583 );
 584
 585 ## --------------------------------------------------------
 586 ## Class::MOP::Method::Accessor
 587
 588 Class::MOP::Method::Accessor->meta->add_attribute(
 589     Class::MOP::Attribute->new('attribute' => (
 590         reader   => {
 591             'associated_attribute' => \&Class::MOP::Method::Accessor::associated_attribute
 592         },
 593     ))
 594 );
 595
 596 Class::MOP::Method::Accessor->meta->add_attribute(
 597     Class::MOP::Attribute->new('accessor_type' => (
 598         reader   => { 'accessor_type' => \&Class::MOP::Method::Accessor::accessor_type },
 599     ))
 600 );
 601
 602 ## --------------------------------------------------------
 603 ## Class::MOP::Method::Constructor
 604
 605 Class::MOP::Method::Constructor->meta->add_attribute(
 606     Class::MOP::Attribute->new('options' => (
 607         reader   => {
 608             'options' => \&Class::MOP::Method::Constructor::options
 609         },
 610         default  => sub { +{} }
 611     ))
 612 );
 613
 614 Class::MOP::Method::Constructor->meta->add_attribute(
 615     Class::MOP::Attribute->new('associated_metaclass' => (
 616         init_arg => "metaclass", # FIXME alias and rename
 617         reader   => {
 618             'associated_metaclass' => \&Class::MOP::Method::Constructor::associated_metaclass
 619         },
 620     ))
 621 );
 622
 623 ## --------------------------------------------------------
 624 ## Class::MOP::Instance
 625
 626 # NOTE:
 627 # these don't yet do much of anything, but are just
 628 # included for completeness
 629
 630 Class::MOP::Instance->meta->add_attribute(
 631     Class::MOP::Attribute->new('associated_metaclass',
 632         reader   => { associated_metaclass => \&Class::MOP::Instance::associated_metaclass },
 633     ),
 634 );
 635
 636 Class::MOP::Instance->meta->add_attribute(
 637     Class::MOP::Attribute->new('_class_name',
 638         init_arg => undef,
 639         reader   => { _class_name => \&Class::MOP::Instance::_class_name },
 640         #lazy     => 1, # not yet supported by Class::MOP but out our version does it anyway
 641         #default  => sub { $_[0]->associated_metaclass->name },
 642     ),
 643 );
 644
 645 Class::MOP::Instance->meta->add_attribute(
 646     Class::MOP::Attribute->new('attributes',
 647         reader   => { attributes => \&Class::MOP::Instance::get_all_attributes },
 648     ),
 649 );
 650
 651 Class::MOP::Instance->meta->add_attribute(
 652     Class::MOP::Attribute->new('slots',
 653         reader   => { slots => \&Class::MOP::Instance::slots },
 654     ),
 655 );
 656
 657 Class::MOP::Instance->meta->add_attribute(
 658     Class::MOP::Attribute->new('slot_hash',
 659         reader   => { slot_hash => \&Class::MOP::Instance::slot_hash },
 660     ),
 661 );
 662
 663 require Class::MOP::Deprecated unless our $no_deprecated;
 664
 665 # we need the meta instance of the meta instance to be created now, in order
 666 # for the constructor to be able to use it
 667 Class::MOP::Instance->meta->get_meta_instance;
 668
 669 # pretend the add_method never happenned. it hasn't yet affected anything
 670 undef Class::MOP::Instance->meta->{_package_cache_flag};
 671
 672 ## --------------------------------------------------------
 673 ## Now close all the Class::MOP::* classes
 674
 675 # NOTE: we don't need to inline the the accessors this only lengthens
 676 # the compile time of the MOP, and gives us no actual benefits.
 677
 678 $_->meta->make_immutable(
 679     inline_constructor  => 0,
 680     constructor_name    => "_new",
 681     inline_accessors => 0,
 682 ) for qw/
 683     Class::MOP::Package
 684     Class::MOP::Module
 685     Class::MOP::Class
 686
 687     Class::MOP::Attribute
 688     Class::MOP::Method
 689     Class::MOP::Instance
 690
 691     Class::MOP::Object
 692
 693     Class::MOP::Method::Generated
 694     Class::MOP::Method::Inlined
 695
 696     Class::MOP::Method::Accessor
 697     Class::MOP::Method::Constructor
 698     Class::MOP::Method::Wrapped
 699 /;
 700
 701 $_->meta->make_immutable(
 702     inline_constructor  => 0,
 703     constructor_name    => undef,
 704     inline_accessors => 0,
 705 ) for qw/
 706     Class::MOP::Mixin
 707     Class::MOP::Mixin::AttributeCore
 708     Class::MOP::Mixin::HasAttributes
 709     Class::MOP::Mixin::HasMethods
 710 /;
 711
 712 1;
 713
 714 __END__
 715
 716 =pod
 717
 718 =head1 NAME
 719
 720 Class::MOP - A Meta Object Protocol for Perl 5
 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 compliment 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 requires 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 either the same as (or a subclass
 824 of) that 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 As I said this is a highly esoteric topic and one you will only run
 840 into if you do a lot of subclassing of L<Class::MOP::Class>. If you
 841 are interested in why this is an issue see the paper I<Uniform and
 842 safe metaclass composition> linked to in the L<SEE ALSO> section of
 843 this document.
 844
 845 =head2 Using custom metaclasses
 846
 847 Always use the L<metaclass> pragma when using a custom metaclass, this
 848 will ensure the proper initialization order and not accidentally
 849 create an incorrect type of metaclass for you. This is a very rare
 850 problem, and one which can only occur if you are doing deep metaclass
 851 programming. So in other words, don't worry about it.
 852
 853 Note that if you're using L<Moose> we encourage you to I<not> use
 854 L<metaclass> pragma, and instead use L<Moose::Util::MetaRole> to apply
 855 roles to a class's metaclasses. This topic is covered at length in
 856 various L<Moose::Cookbook> recipes.
 857
 858 =head1 PROTOCOLS
 859
 860 The meta-object protocol is divided into 4 main sub-protocols:
 861
 862 =head2 The Class protocol
 863
 864 This provides a means of manipulating and introspecting a Perl 5
 865 class. It handles symbol table hacking for you, and provides a rich
 866 set of methods that go beyond simple package introspection.
 867
 868 See L<Class::MOP::Class> for more details.
 869
 870 =head2 The Attribute protocol
 871
 872 This provides a consistent representation for an attribute of a Perl 5
 873 class. Since there are so many ways to create and handle attributes in
 874 Perl 5 OO, the Attribute protocol provide as much of a unified
 875 approach as possible. Of course, you are always free to extend this
 876 protocol by subclassing the appropriate classes.
 877
 878 See L<Class::MOP::Attribute> for more details.
 879
 880 =head2 The Method protocol
 881
 882 This provides a means of manipulating and introspecting methods in the
 883 Perl 5 object system. As with attributes, there are many ways to
 884 approach this topic, so we try to keep it pretty basic, while still
 885 making it possible to extend the system in many ways.
 886
 887 See L<Class::MOP::Method> for more details.
 888
 889 =head2 The Instance protocol
 890
 891 This provides a layer of abstraction for creating object instances.
 892 Since the other layers use this protocol, it is relatively easy to
 893 change the type of your instances from the default hash reference to
 894 some other type of reference. Several examples are provided in the
 895 F<examples/> directory included in this distribution.
 896
 897 See L<Class::MOP::Instance> for more details.
 898
 899 =head1 FUNCTIONS
 900
 901 Note that this module does not export any constants or functions.
 902
 903 =head2 Constants
 904
 905 =over 4
 906
 907 =item I<Class::MOP::IS_RUNNING_ON_5_10>
 908
 909 We set this constant depending on what version perl we are on, this
 910 allows us to take advantage of new 5.10 features and stay backwards
 911 compatible.
 912
 913 =back
 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::load_class($class_name)>
 922
 923 This will load the specified C<$class_name>, if it is not already
 924 loaded (as reported by C<is_class_loaded>). This function can be used
 925 in place of tricks like C<eval "use $module"> or using C<require>
 926 unconditionally.
 927
 928 If the module cannot be loaded, an exception is thrown.
 929
 930 For historical reasons, this function explicitly returns a true value.
 931
 932 =item B<Class::MOP::is_class_loaded($class_name)>
 933
 934 Returns a boolean indicating whether or not C<$class_name> has been
 935 loaded.
 936
 937 This does a basic check of the symbol table to try and determine as
 938 best it can if the C<$class_name> is loaded, it is probably correct
 939 about 99% of the time, but it can be fooled into reporting false
 940 positives. In particular, loading any of the core L<IO> modules will
 941 cause most of the rest of the core L<IO> modules to falsely report
 942 having been loaded, due to the way the base L<IO> module works.
 943
 944 =item B<Class::MOP::get_code_info($code)>
 945
 946 This function returns two values, the name of the package the C<$code>
 947 is from and the name of the C<$code> itself. This is used by several
 948 elements of the MOP to determine where a given C<$code> reference is
 949 from.
 950
 951 =item B<Class::MOP::class_of($instance_or_class_name)>
 952
 953 This will return the metaclass of the given instance or class name.  If the
 954 class lacks a metaclass, no metaclass will be initialized, and C<undef> will be
 955 returned.
 956
 957 =item B<Class::MOP::check_package_cache_flag($pkg)>
 958
 959 B<NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!>
 960
 961 This will return an integer that is managed by L<Class::MOP::Class> to
 962 determine if a module's symbol table has been altered.
 963
 964 In Perl 5.10 or greater, this flag is package specific. However in
 965 versions prior to 5.10, this will use the C<PL_sub_generation>
 966 variable which is not package specific.
 967
 968 =item B<Class::MOP::load_first_existing_class(@class_names)>
 969
 970 B<NOTE: DO NOT USE THIS FUNCTION, IT IS FOR INTERNAL USE ONLY!>
 971
 972 Given a list of class names, this function will attempt to load each
 973 one in turn.
 974
 975 If it finds a class it can load, it will return that class' name.  If
 976 none of the classes can be loaded, it will throw an exception.
 977
 978 =back
 979
 980 =head2 Metaclass cache functions
 981
 982 Class::MOP holds a cache of metaclasses. The following are functions
 983 (B<not methods>) which can be used to access that cache. It is not
 984 recommended that you mess with these. Bad things could happen, but if
 985 you are brave and willing to risk it: go for it!
 986
 987 =over 4
 988
 989 =item B<Class::MOP::get_all_metaclasses>
 990
 991 This will return a hash of all the metaclass instances that have
 992 been cached by L<Class::MOP::Class>, keyed by the package name.
 993
 994 =item B<Class::MOP::get_all_metaclass_instances>
 995
 996 This will return a list of all the metaclass instances that have
 997 been cached by L<Class::MOP::Class>.
 998
 999 =item B<Class::MOP::get_all_metaclass_names>
1000
1001 This will return a list of all the metaclass names that have
1002 been cached by L<Class::MOP::Class>.
1003
1004 =item B<Class::MOP::get_metaclass_by_name($name)>
1005
1006 This will return a cached L<Class::MOP::Class> instance, or nothing
1007 if no metaclass exists with that C<$name>.
1008
1009 =item B<Class::MOP::store_metaclass_by_name($name, $meta)>
1010
1011 This will store a metaclass in the cache at the supplied C<$key>.
1012
1013 =item B<Class::MOP::weaken_metaclass($name)>
1014
1015 In rare cases (e.g. anonymous metaclasses) it is desirable to
1016 store a weakened reference in the metaclass cache. This
1017 function will weaken the reference to the metaclass stored
1018 in C<$name>.
1019
1020 =item B<Class::MOP::does_metaclass_exist($name)>
1021
1022 This will return true of there exists a metaclass stored in the
1023 C<$name> key, and return false otherwise.
1024
1025 =item B<Class::MOP::remove_metaclass_by_name($name)>
1026
1027 This will remove the metaclass stored in the C<$name> key.
1028
1029 =back
1030
1031 =head1 SEE ALSO
1032
1033 =head2 Books
1034
1035 There are very few books out on Meta Object Protocols and Metaclasses
1036 because it is such an esoteric topic. The following books are really
1037 the only ones I have found. If you know of any more, B<I<please>>
1038 email me and let me know, I would love to hear about them.
1039
1040 =over 4
1041
1042 =item I<The Art of the Meta Object Protocol>
1043
1044 =item I<Advances in Object-Oriented Metalevel Architecture and Reflection>
1045
1046 =item I<Putting MetaClasses to Work>
1047
1048 =item I<Smalltalk: The Language>
1049
1050 =back
1051
1052 =head2 Papers
1053
1054 =over 4
1055
1056 =item "Uniform and safe metaclass composition"
1057
1058 An excellent paper by the people who brought us the original Traits paper.
1059 This paper is on how Traits can be used to do safe metaclass composition,
1060 and offers an excellent introduction section which delves into the topic of
1061 metaclass compatibility.
1062
1063 L<http://www.iam.unibe.ch/~scg/Archive/Papers/Duca05ySafeMetaclassTrait.pdf>
1064
1065 =item "Safe Metaclass Programming"
1066
1067 This paper seems to precede the above paper, and propose a mix-in based
1068 approach as opposed to the Traits based approach. Both papers have similar
1069 information on the metaclass compatibility problem space.
1070
1071 L<http://citeseer.ist.psu.edu/37617.html>
1072
1073 =back
1074
1075 =head2 Prior Art
1076
1077 =over 4
1078
1079 =item The Perl 6 MetaModel work in the Pugs project
1080
1081 =over 4
1082
1083 =item L<http://svn.openfoundry.org/pugs/misc/Perl-MetaModel/>
1084
1085 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-ObjectSpace>
1086
1087 =back
1088
1089 =back
1090
1091 =head2 Articles
1092
1093 =over 4
1094
1095 =item CPAN Module Review of Class::MOP
1096
1097 L<http://www.oreillynet.com/onlamp/blog/2006/06/cpan_module_review_classmop.html>
1098
1099 =back
1100
1101 =head1 SIMILAR MODULES
1102
1103 As I have said above, this module is a class-builder-builder, so it is
1104 not the same thing as modules like L<Class::Accessor> and
1105 L<Class::MethodMaker>. That being said there are very few modules on CPAN
1106 with similar goals to this module. The one I have found which is most
1107 like this module is L<Class::Meta>, although it's philosophy and the MOP it
1108 creates are very different from this modules.
1109
1110 =head1 BUGS
1111
1112 All complex software has bugs lurking in it, and this module is no
1113 exception.
1114
1115 Please report any bugs to C<bug-class-mop@rt.cpan.org>, or through the
1116 web interface at L<http://rt.cpan.org>.
1117
1118 You can also discuss feature requests or possible bugs on the Moose
1119 mailing list (moose@perl.org) or on IRC at
1120 L<irc://irc.perl.org/#moose>.
1121
1122 =head1 ACKNOWLEDGEMENTS
1123
1124 =over 4
1125
1126 =item Rob Kinyon
1127
1128 Thanks to Rob for actually getting the development of this module kick-started.
1129
1130 =back
1131
1132 =head1 AUTHORS
1133
1134 Stevan Little E<lt>stevan@iinteractive.comE<gt>
1135
1136 B<with contributions from:>
1137
1138 Brandon (blblack) Black
1139
1140 Florian (rafl) Ragwitz
1141
1142 Guillermo (groditi) Roditi
1143
1144 Dave (autarch) Rolsky
1145
1146 Matt (mst) Trout
1147
1148 Rob (robkinyon) Kinyon
1149
1150 Yuval (nothingmuch) Kogman
1151
1152 Scott (konobi) McWhirter
1153
1154 Dylan Hardison
1155
1156 =head1 COPYRIGHT AND LICENSE
1157
1158 Copyright 2006-2010 by Infinity Interactive, Inc.
1159
1160 L<http://www.iinteractive.com>
1161
1162 This library is free software; you can redistribute it and/or modify
1163 it under the same terms as Perl itself.
1164
1165 =cut