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