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 ();
   9
  10 use Class::MOP::Class;
  11 use Class::MOP::Attribute;
  12 use Class::MOP::Method;
  13
  14 our $VERSION = '0.07';
  15
  16 ## ----------------------------------------------------------------------------
  17 ## Setting up our environment ...
  18 ## ----------------------------------------------------------------------------
  19 ## Class::MOP needs to have a few things in the global perl environment so
  20 ## that it can operate effectively. Those things are done here.
  21 ## ----------------------------------------------------------------------------
  22
  23 # so that mixins can have runtime
  24 # dispatched SUPER calls
  25 use SUPER ();
  26
  27 ## ----------------------------------------------------------------------------
  28 ## Bootstrapping
  29 ## ----------------------------------------------------------------------------
  30 ## The code below here is to bootstrap our MOP with itself. This is also
  31 ## sometimes called "tying the knot". By doing this, we make it much easier
  32 ## to extend the MOP through subclassing and such since now you can use the
  33 ## MOP itself to extend itself.
  34 ##
  35 ## Yes, I know, thats weird and insane, but it's a good thing, trust me :)
  36 ## ----------------------------------------------------------------------------
  37
  38 # We need to add in the meta-attributes here so that
  39 # any subclass of Class::MOP::* will be able to
  40 # inherit them using &construct_instance
  41
  42 ## Class::MOP::Class
  43
  44 Class::MOP::Class->meta->add_attribute(
  45     Class::MOP::Attribute->new('$:package' => (
  46         reader   => 'name',
  47         init_arg => ':package',
  48     ))
  49 );
  50
  51 Class::MOP::Class->meta->add_attribute(
  52     Class::MOP::Attribute->new('%:attributes' => (
  53         reader   => 'get_attribute_map',
  54         init_arg => ':attributes',
  55         default  => sub { {} }
  56     ))
  57 );
  58
  59 Class::MOP::Class->meta->add_attribute(
  60     Class::MOP::Attribute->new('$:attribute_metaclass' => (
  61         reader   => 'attribute_metaclass',
  62         init_arg => ':attribute_metaclass',
  63         default  => 'Class::MOP::Attribute',
  64     ))
  65 );
  66
  67 Class::MOP::Class->meta->add_attribute(
  68     Class::MOP::Attribute->new('$:method_metaclass' => (
  69         reader   => 'method_metaclass',
  70         init_arg => ':method_metaclass',
  71         default  => 'Class::MOP::Method',
  72     ))
  73 );
  74
  75 ## Class::MOP::Attribute
  76
  77 Class::MOP::Attribute->meta->add_attribute(
  78     Class::MOP::Attribute->new('name' => (
  79         reader => 'name'
  80     ))
  81 );
  82
  83 Class::MOP::Attribute->meta->add_attribute(
  84     Class::MOP::Attribute->new('associated_class' => (
  85         reader => 'associated_class'
  86     ))
  87 );
  88
  89 Class::MOP::Attribute->meta->add_attribute(
  90     Class::MOP::Attribute->new('accessor' => (
  91         reader    => 'accessor',
  92         predicate => 'has_accessor',
  93     ))
  94 );
  95
  96 Class::MOP::Attribute->meta->add_attribute(
  97     Class::MOP::Attribute->new('reader' => (
  98         reader    => 'reader',
  99         predicate => 'has_reader',
 100     ))
 101 );
 102
 103 Class::MOP::Attribute->meta->add_attribute(
 104     Class::MOP::Attribute->new('writer' => (
 105         reader    => 'writer',
 106         predicate => 'has_writer',
 107     ))
 108 );
 109
 110 Class::MOP::Attribute->meta->add_attribute(
 111     Class::MOP::Attribute->new('predicate' => (
 112         reader    => 'predicate',
 113         predicate => 'has_predicate',
 114     ))
 115 );
 116
 117 Class::MOP::Attribute->meta->add_attribute(
 118     Class::MOP::Attribute->new('init_arg' => (
 119         reader    => 'init_arg',
 120         predicate => 'has_init_arg',
 121     ))
 122 );
 123
 124 Class::MOP::Attribute->meta->add_attribute(
 125     Class::MOP::Attribute->new('default' => (
 126         # default has a custom 'reader' method ...
 127         predicate => 'has_default',
 128     ))
 129 );
 130
 131
 132 # NOTE: (meta-circularity)
 133 # This should be one of the last things done
 134 # it will "tie the knot" with Class::MOP::Attribute
 135 # so that it uses the attributes meta-objects
 136 # to construct itself.
 137 Class::MOP::Attribute->meta->add_method('new' => sub {
 138     my $class   = shift;
 139     my $name    = shift;
 140     my %options = @_;
 141
 142     (defined $name && $name)
 143         || confess "You must provide a name for the attribute";
 144     $options{init_arg} = $name
 145         if not exists $options{init_arg};
 146
 147     # return the new object
 148     $class->meta->new_object(name => $name, %options);
 149 });
 150
 151 Class::MOP::Attribute->meta->add_method('clone' => sub {
 152     my $self  = shift;
 153     my $class = $self->associated_class;
 154     $self->detach_from_class() if defined $class;
 155     my $clone = $self->meta->clone_object($self, @_);
 156     if (defined $class) {
 157         $self->attach_to_class($class);
 158         $clone->attach_to_class($class);
 159     }
 160     return $clone;
 161 });
 162
 163 1;
 164
 165 __END__
 166
 167 =pod
 168
 169 =head1 NAME
 170
 171 Class::MOP - A Meta Object Protocol for Perl 5
 172
 173 =head1 SYNOPSIS
 174
 175   # ... This will come later, for now see
 176   # the other SYNOPSIS for more information
 177
 178 =head1 DESCRIPTON
 179
 180 This module is an attempt to create a meta object protocol for the
 181 Perl 5 object system. It makes no attempt to change the behavior or
 182 characteristics of the Perl 5 object system, only to create a
 183 protocol for its manipulation and introspection.
 184
 185 That said, it does attempt to create the tools for building a rich
 186 set of extensions to the Perl 5 object system. Every attempt has been
 187 made for these tools to keep to the spirit of the Perl 5 object
 188 system that we all know and love.
 189
 190 =head2 What is a Meta Object Protocol?
 191
 192 A meta object protocol is an API to an object system.
 193
 194 To be more specific, it is a set of abstractions of the components of
 195 an object system (typically things like; classes, object, methods,
 196 object attributes, etc.). These abstractions can then be used to both
 197 inspect and manipulate the object system which they describe.
 198
 199 It can be said that there are two MOPs for any object system; the
 200 implicit MOP, and the explicit MOP. The implicit MOP handles things
 201 like method dispatch or inheritance, which happen automatically as
 202 part of how the object system works. The explicit MOP typically
 203 handles the introspection/reflection features of the object system.
 204 All object systems have implicit MOPs, without one, they would not
 205 work. Explict MOPs however as less common, and depending on the
 206 language can vary from restrictive (Reflection in Java or C#) to
 207 wide open (CLOS is a perfect example).
 208
 209 =head2 Yet Another Class Builder!! Why?
 210
 211 This is B<not> a class builder so much as it is a I<class builder
 212 B<builder>>. My intent is that an end user does not use this module
 213 directly, but instead this module is used by module authors to
 214 build extensions and features onto the Perl 5 object system.
 215
 216 =head2 Who is this module for?
 217
 218 This module is specifically for anyone who has ever created or
 219 wanted to create a module for the Class:: namespace. The tools which
 220 this module will provide will hopefully make it easier to do more
 221 complex things with Perl 5 classes by removing such barriers as
 222 the need to hack the symbol tables, or understand the fine details
 223 of method dispatch.
 224
 225 =head2 What changes do I have to make to use this module?
 226
 227 This module was designed to be as unintrusive as possible. Many of
 228 its features are accessible without B<any> change to your existsing
 229 code at all. It is meant to be a compliment to your existing code and
 230 not an intrusion on your code base. Unlike many other B<Class::>
 231 modules, this module B<does not> require you subclass it, or even that
 232 you C<use> it in within your module's package.
 233
 234 The only features which requires additions to your code are the
 235 attribute handling and instance construction features, and these are
 236 both completely optional features. The only reason for this is because
 237 Perl 5's object system does not actually have these features built
 238 in. More information about this feature can be found below.
 239
 240 =head2 A Note about Performance?
 241
 242 It is a common misconception that explict MOPs are performance drains.
 243 But this is not a universal truth at all, it is an side-effect of
 244 specific implementations. For instance, using Java reflection is much
 245 slower because the JVM cannot take advantage of any compiler
 246 optimizations, and the JVM has to deal with much more runtime type
 247 information as well. Reflection in C# is marginally better as it was
 248 designed into the language and runtime (the CLR). In contrast, CLOS
 249 (the Common Lisp Object System) was built to support an explicit MOP,
 250 and so performance is tuned for it.
 251
 252 This library in particular does it's absolute best to avoid putting
 253 B<any> drain at all upon your code's performance. In fact, by itself
 254 it does nothing to affect your existing code. So you only pay for
 255 what you actually use.
 256
 257 =head2 About Metaclass compatibility
 258
 259 This module makes sure that all metaclasses created are both upwards
 260 and downwards compatible. The topic of metaclass compatibility is
 261 highly esoteric and is something only encountered when doing deep and
 262 involved metaclass hacking. There are two basic kinds of metaclass
 263 incompatibility; upwards and downwards.
 264
 265 Upwards metaclass compatibility means that the metaclass of a
 266 given class is either the same as (or a subclass of) all of the
 267 class's ancestors.
 268
 269 Downward metaclass compatibility means that the metaclasses of a
 270 given class's anscestors are all either the same as (or a subclass
 271 of) that metaclass.
 272
 273 Here is a diagram showing a set of two classes (C<A> and C<B>) and
 274 two metaclasses (C<Meta::A> and C<Meta::B>) which have correct
 275 metaclass compatibility both upwards and downwards.
 276
 277     +---------+     +---------+
 278     | Meta::A |<----| Meta::B |      <....... (instance of  )
 279     +---------+     +---------+      <------- (inherits from)
 280          ^               ^
 281          :               :
 282     +---------+     +---------+
 283     |    A    |<----|    B    |
 284     +---------+     +---------+
 285
 286 As I said this is a highly esoteric topic and one you will only run
 287 into if you do a lot of subclassing of B<Class::MOP::Class>. If you
 288 are interested in why this is an issue see the paper
 289 I<Uniform and safe metaclass composition> linked to in the
 290 L<SEE ALSO> section of this document.
 291
 292 =head2 Using custom metaclasses
 293
 294 Always use the metaclass pragma when using a custom metaclass, this
 295 will ensure the proper initialization order and not accidentely
 296 create an incorrect type of metaclass for you. This is a very rare
 297 problem, and one which can only occur if you are doing deep metaclass
 298 programming. So in other words, don't worry about it.
 299
 300 =head1 PROTOCOLS
 301
 302 The protocol is divided into 3 main sub-protocols:
 303
 304 =over 4
 305
 306 =item The Class protocol
 307
 308 This provides a means of manipulating and introspecting a Perl 5
 309 class. It handles all of symbol table hacking for you, and provides
 310 a rich set of methods that go beyond simple package introspection.
 311
 312 See L<Class::MOP::Class> for more details.
 313
 314 =item The Attribute protocol
 315
 316 This provides a consistent represenation for an attribute of a
 317 Perl 5 class. Since there are so many ways to create and handle
 318 atttributes in Perl 5 OO, this attempts to provide as much of a
 319 unified approach as possible, while giving the freedom and
 320 flexibility to subclass for specialization.
 321
 322 See L<Class::MOP::Attribute> for more details.
 323
 324 =item The Method protocol
 325
 326 This provides a means of manipulating and introspecting methods in
 327 the Perl 5 object system. As with attributes, there are many ways to
 328 approach this topic, so we try to keep it pretty basic, while still
 329 making it possible to extend the system in many ways.
 330
 331 See L<Class::MOP::Method> for more details.
 332
 333 =back
 334
 335 =head1 SEE ALSO
 336
 337 =head2 Books
 338
 339 There are very few books out on Meta Object Protocols and Metaclasses
 340 because it is such an esoteric topic. The following books are really
 341 the only ones I have found. If you know of any more, B<I<please>>
 342 email me and let me know, I would love to hear about them.
 343
 344 =over 4
 345
 346 =item "The Art of the Meta Object Protocol"
 347
 348 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
 349
 350 =item "Putting MetaClasses to Work"
 351
 352 =item "Smalltalk: The Language"
 353
 354 =back
 355
 356 =head2 Papers
 357
 358 =over 4
 359
 360 =item Uniform and safe metaclass composition
 361
 362 An excellent paper by the people who brought us the original Traits paper.
 363 This paper is on how Traits can be used to do safe metaclass composition,
 364 and offers an excellent introduction section which delves into the topic of
 365 metaclass compatibility.
 366
 367 L<http://www.iam.unibe.ch/~scg/Archive/Papers/Duca05ySafeMetaclassTrait.pdf>
 368
 369 =item Safe Metaclass Programming
 370
 371 This paper seems to precede the above paper, and propose a mix-in based
 372 approach as opposed to the Traits based approach. Both papers have similar
 373 information on the metaclass compatibility problem space.
 374
 375 L<http://citeseer.ist.psu.edu/37617.html>
 376
 377 =back
 378
 379 =head2 Prior Art
 380
 381 =over 4
 382
 383 =item The Perl 6 MetaModel work in the Pugs project
 384
 385 =over 4
 386
 387 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel>
 388
 389 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-ObjectSpace>
 390
 391 =back
 392
 393 =back
 394
 395 =head1 SIMILAR MODULES
 396
 397 As I have said above, this module is a class-builder-builder, so it is
 398 not the same thing as modules like L<Class::Accessor> and
 399 L<Class::MethodMaker>. That being said there are very few modules on CPAN
 400 with similar goals to this module. The one I have found which is most
 401 like this module is L<Class::Meta>, although it's philosophy and the MOP it
 402 creates are very different from this modules.
 403
 404 =head1 BUGS
 405
 406 All complex software has bugs lurking in it, and this module is no
 407 exception. If you find a bug please either email me, or add the bug
 408 to cpan-RT.
 409
 410 =head1 ACKNOWLEDGEMENTS
 411
 412 =over 4
 413
 414 =item Rob Kinyon E<lt>rob@iinteractive.comE<gt>
 415
 416 Thanks to Rob for actually getting the development of this module kick-started.
 417
 418 =back
 419
 420 =head1 AUTHOR
 421
 422 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 423
 424 =head1 COPYRIGHT AND LICENSE
 425
 426 Copyright 2006 by Infinity Interactive, Inc.
 427
 428 L<http://www.iinteractive.com>
 429
 430 This library is free software; you can redistribute it and/or modify
 431 it under the same terms as Perl itself.
 432
 433 =cut