lib/Class/MOP.pm

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