lib/Class/MOP.pm

   1
   2 package Class::MOP;
   3
   4 use strict;
   5 use warnings;
   6
   7 use Scalar::Util 'blessed';
   8 use Carp         'confess';
   9
  10 use Class::MOP::Class;
  11 use Class::MOP::Attribute;
  12 use Class::MOP::Method;
  13
  14 our $VERSION = '0.01';
  15
  16 sub import {
  17     shift;
  18     return unless @_;
  19     if ($_[0] eq ':universal') {
  20         *UNIVERSAL::meta = sub {
  21             Class::MOP::Class->initialize(blessed($_[0]) || $_[0])
  22         };
  23     }
  24 }
  25
  26 ## ----------------------------------------------------------------------------
  27 ## Bootstrapping
  28 ## ----------------------------------------------------------------------------
  29 ## The code below here is to bootstrap our MOP with itself. This is also
  30 ## sometimes called "tying the knot". By doing this, we make it much easier
  31 ## to extend the MOP through subclassing and such since now you can use the
  32 ## MOP itself to extend itself.
  33 ##
  34 ## Yes, I know, thats weird and insane, but it's a good thing, trust me :)
  35 ## ----------------------------------------------------------------------------
  36
  37 # We need to add in the meta-attributes here so that
  38 # any subclass of Class::MOP::* will be able to
  39 # inherit them using &construct_instance
  40
  41 ## Class::MOP::Class
  42
  43 Class::MOP::Class->meta->add_attribute(
  44     Class::MOP::Attribute->new('$:pkg' => (
  45         init_arg => ':pkg'
  46     ))
  47 );
  48
  49 Class::MOP::Class->meta->add_attribute(
  50     Class::MOP::Attribute->new('%:attrs' => (
  51         init_arg => ':attrs',
  52         default  => sub { {} }
  53     ))
  54 );
  55
  56 ## Class::MOP::Attribute
  57
  58 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('name'));
  59 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('accessor'));
  60 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('reader'));
  61 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('writer'));
  62 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('predicate'));
  63 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('init_arg'));
  64 Class::MOP::Attribute->meta->add_attribute(Class::MOP::Attribute->new('default'));
  65
  66 # NOTE: (meta-circularity)
  67 # This should be one of the last things done
  68 # it will "tie the knot" with Class::MOP::Attribute
  69 # so that it uses the attributes meta-objects
  70 # to construct itself.
  71 Class::MOP::Attribute->meta->add_method('new' => sub {
  72     my $class   = shift;
  73     my $name    = shift;
  74     my %options = @_;
  75
  76     (defined $name && $name)
  77         || confess "You must provide a name for the attribute";
  78     (!exists $options{reader} && !exists $options{writer})
  79         || confess "You cannot declare an accessor and reader and/or writer functions"
  80             if exists $options{accessor};
  81
  82     bless $class->meta->construct_instance(name => $name, %options) => $class;
  83 });
  84
  85 # NOTE: (meta-circularity)
  86 # This is how we "tie the knot" for the class
  87 # meta-objects. This is used to construct the
  88 # Class::MOP::Class instances after all the
  89 # bootstrapping is complete.
  90 Class::MOP::Class->meta->add_method('construct_class_instance' => sub {
  91     my ($class, $package_name) = @_;
  92     (defined $package_name && $package_name)
  93         || confess "You must pass a package name";
  94     bless Class::MOP::Class->meta->construct_instance(':pkg' => $package_name) => blessed($class) || $class
  95 });
  96
  97 1;
  98
  99 __END__
 100
 101 =pod
 102
 103 =head1 NAME
 104
 105 Class::MOP - A Meta Object Protocol for Perl 5
 106
 107 =head1 SYNOPSIS
 108
 109   # ...
 110
 111 =head1 DESCRIPTON
 112
 113 This module is an attempt to create a meta object protocol for the
 114 Perl 5 object system. It makes no attempt to change the behavior or
 115 characteristics of the Perl 5 object system, only to create a
 116 protocol for its manipulation and introspection.
 117
 118 That said, it does attempt to create the tools for building a rich
 119 set of extensions to the Perl 5 object system. Every attempt has been
 120 made for these tools to keep to the spirit of the Perl 5 object
 121 system that we all know and love.
 122
 123 =head2 What is a Meta Object Protocol?
 124
 125 A meta object protocol is an API to an object system.
 126
 127 To be more specific, it is a set of abstractions of the components of
 128 an object system (typically things like; classes, object, methods,
 129 object attributes, etc.). These abstractions can then be used to both
 130 inspect and manipulate the object system which they describe.
 131
 132 It can be said that there are two MOPs for any object system; the
 133 implicit MOP, and the explicit MOP. The implicit MOP handles things
 134 like method dispatch or inheritance, which happen automatically as
 135 part of how the object system works. The explicit MOP typically
 136 handles the introspection/reflection features of the object system.
 137 All object systems have implicit MOPs, without one, they would not
 138 work. Explict MOPs however as less common, and depending on the
 139 language can vary from restrictive (Reflection in Java or C#) to
 140 wide open (CLOS is a perfect example).
 141
 142 =head2 Yet Another Class Builder!! Why?
 143
 144 This is B<not> a class builder so much as it is a I<class builder
 145 B<builder>>. My intent is that an end user does not use this module
 146 directly, but instead this module is used by module authors to
 147 build extensions and features onto the Perl 5 object system.
 148
 149 =head2 Who is this module for?
 150
 151 This module is specifically for anyone who has ever created or
 152 wanted to create a module for the Class:: namespace. The tools which
 153 this module will provide will hopefully make it easier to do more
 154 complex things with Perl 5 classes by removing such barriers as
 155 the need to hack the symbol tables, or understand the fine details
 156 of method dispatch.
 157
 158 =head2 What changes do I have to make to use this module?
 159
 160 This module was designed to be as unintrusive as possible. Many of
 161 it's features are accessible without B<any> change to your existsing
 162 code at all. It is meant to be a compliment to your existing code and
 163 not an intrusion on your code base. Unlike many other B<Class::>
 164 modules, this module does require you subclass it, or even that you
 165 C<use> it in within your module's package.
 166
 167 The only features which requires additions to your code are the
 168 attribute handling and instance construction features, and these are
 169 both optional features as well. The only reason for this is because
 170 Perl 5's object system does not actually have these features built
 171 in. More information about this feature can be found below.
 172
 173 =head2 A Note about Performance?
 174
 175 It is a common misconception that explict MOPs are performance drains.
 176 But this is not a universal truth at all, it is an side-effect of
 177 specific implementations. For instance, using Java reflection is much
 178 slower because the JVM cannot take advantage of any compiler
 179 optimizations, and the JVM has to deal with much more runtime type
 180 information as well. Reflection in C# is marginally better as it was
 181 designed into the language and runtime (the CLR). In contrast, CLOS
 182 (the Common Lisp Object System) was built to support an explicit MOP,
 183 and so performance is tuned for it.
 184
 185 This library in particular does it's absolute best to avoid putting
 186 B<any> drain at all upon your code's performance. In fact, by itself
 187 it does nothing to affect your existing code. So you only pay for
 188 what you actually use.
 189
 190 =head1 PROTOCOLS
 191
 192 The protocol is divided into 3 main sub-protocols:
 193
 194 =over 4
 195
 196 =item The Class protocol
 197
 198 This provides a means of manipulating and introspecting a Perl 5
 199 class. It handles all of symbol table hacking for you, and provides
 200 a rich set of methods that go beyond simple package introspection.
 201
 202 See L<Class::MOP::Class> for more details.
 203
 204 =item The Attribute protocol
 205
 206 This provides a consistent represenation for an attribute of a
 207 Perl 5 class. Since there are so many ways to create and handle
 208 atttributes in Perl 5 OO, this attempts to provide as much of a
 209 unified approach as possible, while giving the freedom and
 210 flexibility to subclass for specialization.
 211
 212 See L<Class::MOP::Attribute> for more details.
 213
 214 =item The Method protocol
 215
 216 This provides a means of manipulating and introspecting methods in
 217 the Perl 5 object system. As with attributes, there are many ways to
 218 approach this topic, so we try to keep it pretty basic, while still
 219 making it possible to extend the system in many ways.
 220
 221 See L<Class::MOP::Method> for more details.
 222
 223 =back
 224
 225 head1 BUGS
 226
 227 All complex software has bugs lurking in it, and this module is no
 228 exception. If you find a bug please either email me, or add the bug
 229 to cpan-RT.
 230
 231 =head1 SEE ALSO
 232
 233 =head2 Books
 234
 235 =over 4
 236
 237 =item "The Art of the Meta Object Protocol"
 238
 239 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
 240
 241 =item "Putting MetaClasses to Work"
 242
 243 =back
 244
 245 =head2 Prior Art
 246
 247 =over 4
 248
 249 =item The Perl 6 MetaModel work in the Pugs project
 250
 251 =over 4
 252
 253 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel>
 254
 255 =item L<http://svn.openfoundry.org/pugs/perl5/Perl6-ObjectSpace>
 256
 257 =back
 258
 259 =back
 260
 261 =head1 AUTHOR
 262
 263 Stevan Little E<gt>stevan@iinteractive.comE<lt>
 264
 265 Rob Kinyon E<gt>rob@iinteractive.comE<lt>
 266
 267 =head1 COPYRIGHT AND LICENSE
 268
 269 Copyright 2006 by Infinity Interactive, Inc.
 270
 271 L<http://www.iinteractive.com>
 272
 273 This library is free software; you can redistribute it and/or modify
 274 it under the same terms as Perl itself.
 275
 276 =cut