lib/Class/MOP.pm

   1
   2 package Class::MOP;
   3
   4 use strict;
   5 use warnings;
   6
   7 use Scalar::Util 'blessed';
   8
   9 our $VERSION = '0.01';
  10
  11 my %METAS;
  12 sub UNIVERSAL::meta {
  13     my $class = blessed($_[0]) || $_[0];
  14     $METAS{$class} ||= Class::MOP::Class->initialize($class)
  15 }
  16
  17 1;
  18
  19 __END__
  20
  21 =pod
  22
  23 =head1 NAME
  24
  25 Class::MOP - A Meta Object Protocol for Perl 5
  26
  27 =head1 SYNOPSIS
  28
  29   # ... coming soon
  30
  31 =head1 DESCRIPTON
  32
  33 This module is an attempt to create a meta object protocol for the
  34 Perl 5 object system. It makes no attempt to change the behavior or
  35 characteristics of the Perl 5 object system, only to create a
  36 protocol for its manipulation and introspection.
  37
  38 That said, it does attempt to create the tools for building a rich
  39 set of extensions to the Perl 5 object system. Every attempt has been
  40 made for these tools to keep to the spirit of the Perl 5 object
  41 system that we all know and love.
  42
  43 =head2 Who is this module for?
  44
  45 This module is specifically for anyone who has ever created or
  46 wanted to create a module for the Class:: namespace. The tools which
  47 this module will provide will hopefully make it easier to do more
  48 complex things with Perl 5 classes by removing such barriers as
  49 the need to hack the symbol tables, or understand the fine details
  50 of method dispatch.
  51
  52 =head1 PROTOCOLS
  53
  54 The protocol is divided into 3 main sub-protocols:
  55
  56 =over 4
  57
  58 =item The Class protocol
  59
  60 This provides a means of manipulating and introspecting a Perl 5
  61 class. It handles all of symbol table hacking for you, and provides
  62 a rich set of methods that go beyond simple package introspection.
  63
  64 =item The Attribute protocol
  65
  66 This provides a consistent represenation for an attribute of a
  67 Perl 5 class. Since there are so many ways to create and handle
  68 atttributes in Perl 5 OO, this attempts to provide as much of a
  69 unified approach as possible, while giving the freedom and
  70 flexibility to subclass for specialization.
  71
  72 =item The Method protocol
  73
  74 This provides a means of manipulating and introspecting methods in
  75 the Perl 5 object system. As with attributes, there are many ways to
  76 approach this topic, so we try to keep it pretty basic, while still
  77 making it possible to extend the system in many ways.
  78
  79 =back
  80
  81 What follows is a more detailed documentation on each specific sub
  82 protocol.
  83
  84 =head2 The Class protocol
  85
  86 =head3 Class construction
  87
  88 These methods handle creating Class objects, which can be used to
  89 both create new classes, and analyze pre-existing ones.
  90
  91 Class::MOP will internally store weakened references to all the
  92 instances you create with these methods, so that they do not need
  93 to be created any more than nessecary.
  94
  95 =over 4
  96
  97 =item B<create ($package_name, ?$package_version,
  98                 superclasses => ?@superclasses,
  99                 methods      => ?%methods,
 100                 attributes   => ?%attributes)>
 101
 102 This returns the basic Class object, bringing the specified
 103 C<$package_name> into existence and adding any of the
 104 C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes>
 105 to it.
 106
 107 =item B<initialize ($package_name)>
 108
 109 This initializes a Class object for a given a C<$package_name>.
 110
 111 =back
 112
 113 =head3 Instance construction
 114
 115 =over 4
 116
 117 =item B<construct_instance ($canidate, %params)>
 118
 119 This will construct and instance using the C<$canidate> as storage
 120 (currently only HASH references are supported). This will collect all
 121 the applicable attribute meta-objects and layout out the fields in the
 122 C<$canidate>, it will then initialize them using either use the
 123 corresponding key in C<%params> or any default value or initializer
 124 found in the attribute meta-object.
 125
 126 =back
 127
 128 =head3 Informational
 129
 130 =over 4
 131
 132 =item B<name>
 133
 134 This is a read-only attribute which returns the package name that
 135 the Class is stored in.
 136
 137 =item B<version>
 138
 139 This is a read-only attribute which returns the C<$VERSION> of the
 140 package the Class is stored in.
 141
 142 =back
 143
 144 =head3 Inheritance Relationships
 145
 146 =over 4
 147
 148 =item B<superclasses (?@superclasses)>
 149
 150 This is a read-write attribute which represents the superclass
 151 relationships of this Class. Basically, it can get and set the
 152 C<@ISA> for you.
 153
 154 =item B<class_precedence_list>
 155
 156 This computes the a list of the Class's ancestors in the same order
 157 in which method dispatch will be done.
 158
 159 =back
 160
 161 =head3 Methods
 162
 163 B<NOTE>: These methods makes every attempt to ignore subroutines
 164 which have been exported by other packages into this one.
 165
 166 =over 4
 167
 168 =item B<add_method ($method_name, $method)>
 169
 170 This will take a C<$method_name> and CODE reference to that
 171 C<$method> and install it into the Class.
 172
 173 B<NOTE> : This does absolutely nothing special to C<$method>
 174 other than use B<Sub::Name> to make sure it is tagged with the
 175 correct name, and therefore show up correctly in stack traces and
 176 such.
 177
 178 =item B<has_method ($method_name)>
 179
 180 This just provides a simple way to check if the Class implements
 181 a specific C<$method_name>. It will I<not> however, attempt to check
 182 if the class inherits the method.
 183
 184 =item B<get_method ($method_name)>
 185
 186 This will return a CODE reference of the specified C<$method_name>,
 187 or return undef if that method does not exist.
 188
 189 =item B<remove_method ($method_name)>
 190
 191 This will attempt to remove a given C<$method_name> from the Class.
 192 It will return the CODE reference that it has removed, and will
 193 attempt to use B<Sub::Name> to clear the methods associated name.
 194
 195 =item B<get_method_list>
 196
 197 This will return a list of method names for all I<locally> defined
 198 methods. It does B<not> provide a list of all applicable methods,
 199 including any inherited ones. If you want a list of all applicable
 200 methods, use the C<compute_all_applicable_methods> method.
 201
 202 =item B<compute_all_applicable_methods>
 203
 204 This will return a list of all the methods names this Class will
 205 support, taking into account inheritance. The list will be a list of
 206 HASH references, each one containing the following information; method
 207 name, the name of the class in which the method lives and a CODE
 208 reference for the actual method.
 209
 210 =item B<find_all_methods_by_name ($method_name)>
 211
 212 This will traverse the inheritence hierarchy and locate all methods
 213 with a given C<$method_name>. Similar to
 214 C<compute_all_applicable_methods> it returns a list of HASH references
 215 with the following information; method name (which will always be the
 216 same as C<$method_name>), the name of the class in which the method
 217 lives and a CODE reference for the actual method.
 218
 219 =back
 220
 221 =head3 Attributes
 222
 223 It should be noted that since there is no one consistent way to define
 224 the attributes of a class in Perl 5. These methods can only work with
 225 the information given, and can not easily discover information on
 226 their own.
 227
 228 =over 4
 229
 230 =item B<add_attribute ($attribute_name, $attribute_meta_object)>
 231
 232 This stores a C<$attribute_meta_object> in the Class object and
 233 associates it with the C<$attribute_name>. Unlike methods, attributes
 234 within the MOP are stored as meta-information only. They will be used
 235 later to construct instances from (see C<construct_instance> above).
 236 More details about the attribute meta-objects can be found in the
 237 L<The Attribute protocol> section of this document.
 238
 239 =item B<has_attribute ($attribute_name)>
 240
 241 Checks to see if this Class has an attribute by the name of
 242 C<$attribute_name> and returns a boolean.
 243
 244 =item B<get_attribute ($attribute_name)>
 245
 246 Returns the attribute meta-object associated with C<$attribute_name>,
 247 if none is found, it will return undef.
 248
 249 =item B<remove_attribute ($attribute_name)>
 250
 251 This will remove the attribute meta-object stored at
 252 C<$attribute_name>, then return the removed attribute meta-object.
 253
 254 B<NOTE:> Removing an attribute will only affect future instances of
 255 the class, it will not make any attempt to remove the attribute from
 256 any existing instances of the class.
 257
 258 =item B<get_attribute_list>
 259
 260 This returns a list of attribute names which are defined in the local
 261 class. If you want a list of all applicable attributes for a class,
 262 use the C<compute_all_applicable_attributes> method.
 263
 264 =item B<compute_all_applicable_attributes>
 265
 266 This will traverse the inheritance heirachy and return a list of HASH
 267 references for all the applicable attributes for this class. The HASH
 268 references will contain the following information; the attribute name,
 269 the class which the attribute is associated with and the actual
 270 attribute meta-object
 271
 272 =item B<create_all_accessors>
 273
 274 This will communicate with all of the classes attributes to create
 275 and install the appropriate accessors. (see L<The Attribute Protocol>
 276 below for more details).
 277
 278 =back
 279
 280 =head2 The Attribute Protocol
 281
 282 This protocol is almost entirely an invention of this module. This is
 283 because Perl 5 does not have consistent notion of what is an attribute
 284 of a class. There are so many ways in which this is done, and very few
 285 (if any) are discoverable by this module.
 286
 287 So, all that said, this module attempts to inject some order into this
 288 chaos, by introducing a more consistent approach.
 289
 290 =head3 Creation
 291
 292 =over 4
 293
 294 =item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)>
 295
 296   Class::MOP::Attribute->new('$foo' => (
 297       accessor => 'foo',        # dual purpose get/set accessor
 298       init_arg => '-foo',       # class->new will look for a -foo key
 299       default  => 'BAR IS BAZ!' # if no -foo key is provided, use this
 300   ));
 301
 302   Class::MOP::Attribute->new('$.bar' => (
 303       reader   => 'bar',        # getter
 304       writer   => 'set_bar',    # setter
 305       init_arg => '-bar',       # class->new will look for a -bar key
 306       # no default value means it is undef
 307   ));
 308
 309 =back
 310
 311 =head3 Informational
 312
 313 =over 4
 314
 315 =item B<name>
 316
 317 =item B<accessor>
 318
 319 =item B<reader>
 320
 321 =item B<writer>
 322
 323 =item B<init_arg>
 324
 325 =item B<default>
 326
 327 =back
 328
 329 =head3 Informational predicates
 330
 331 =over 4
 332
 333 =item B<has_accessor>
 334
 335 Returns true if this attribute uses a get/set accessor, and false
 336 otherwise
 337
 338 =item B<has_reader>
 339
 340 Returns true if this attribute has a reader, and false otherwise
 341
 342 =item B<has_writer>
 343
 344 Returns true if this attribute has a writer, and false otherwise
 345
 346 =item B<has_init_arg>
 347
 348 Returns true if this attribute has a class intialization argument, and
 349 false otherwise
 350
 351 =item B<has_default>
 352
 353 Returns true if this attribute has a default value, and false
 354 otherwise.
 355
 356 =back
 357
 358 =head3 Attribute Accessor generation
 359
 360 =over 4
 361
 362 =item B<generate_accessors>
 363
 364 This allows the attribute to generate code for it's own accessor
 365 methods. This is mostly part of an internal protocol between the class
 366 and it's own attributes, see the C<create_all_accessors> method above.
 367
 368 =back
 369
 370 =head2 The Method Protocol
 371
 372 This protocol is very small, since methods in Perl 5 are just
 373 subroutines within the particular package. Basically all we do is to
 374 bless the subroutine and provide some very simple introspection
 375 methods for it.
 376
 377 =head1 SEE ALSO
 378
 379 =over 4
 380
 381 =item "The Art of the Meta Object Protocol"
 382
 383 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
 384
 385 =back
 386
 387 =head1 AUTHOR
 388
 389 Stevan Little E<gt>stevan@iinteractive.comE<lt>
 390
 391 =head1 COPYRIGHT AND LICENSE
 392
 393 Copyright 2006 by Infinity Interactive, Inc.
 394
 395 L<http://www.iinteractive.com>
 396
 397 This library is free software; you can redistribute it and/or modify
 398 it under the same terms as Perl itself.
 399
 400 =cut