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