lib/Class/MOP.pm

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