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 What is a Meta Object Protocol?
  44
  45 A meta object protocol is an API to an object system.
  46
  47 To be more specific, it is a set of abstractions of the components of
  48 an object system (typically things like; classes, object, methods,
  49 object attributes, etc.). These abstractions can then be used to both
  50 inspect and manipulate the object system which they describe.
  51
  52 It can be said that there are two MOPs for any object system; the
  53 implicit MOP, and the explicit MOP. The implicit MOP handles things
  54 like method dispatch or inheritance, which happen automatically as
  55 part of how the object system works. The explicit MOP typically
  56 handles the introspection/reflection features of the object system.
  57 All object systems have implicit MOPs, without one, they would not
  58 work. Explict MOPs however as less common, and depending on the
  59 language can vary from restrictive (Reflection in Java or C#) to
  60 wide open (CLOS is a perfect example).
  61
  62 =head2 Who is this module for?
  63
  64 This module is specifically for anyone who has ever created or
  65 wanted to create a module for the Class:: namespace. The tools which
  66 this module will provide will hopefully make it easier to do more
  67 complex things with Perl 5 classes by removing such barriers as
  68 the need to hack the symbol tables, or understand the fine details
  69 of method dispatch.
  70
  71 =head2 What changes do I have to make to use this module?
  72
  73 This module was designed to be as unintrusive as possible. So many of
  74 it's features are accessible without B<any> change to your existsing
  75 code at all. It is meant to be a compliment to your existing code and
  76 not an intrusion on your code base.
  77
  78 The only feature which requires additions to your code are the
  79 attribute handling and instance construction features. The only reason
  80 for this is because Perl 5's object system does not actually have
  81 these features built in. More information about this feature can be
  82 found below.
  83
  84 =head2 A Note about Performance?
  85
  86 It is a common misconception that explict MOPs are performance drains.
  87 But this is not a universal truth at all, it is an side-effect of
  88 specific implementations. For instance, using Java reflection is much
  89 slower because the JVM cannot take advantage of any compiler
  90 optimizations, and the JVM has to deal with much more runtime type
  91 information as well. Reflection in C# is marginally better as it was
  92 designed into the language and runtime (the CLR). In contrast, CLOS
  93 (the Common Lisp Object System) was built to support an explicit MOP,
  94 and so performance is tuned for it.
  95
  96 This library in particular does it's absolute best to avoid putting
  97 B<any> drain at all upon your code's performance, while still trying
  98 to make sure it is fast as well (although only as a secondary
  99 concern).
 100
 101 =head1 PROTOCOLS
 102
 103 The protocol is divided into 3 main sub-protocols:
 104
 105 =over 4
 106
 107 =item The Class protocol
 108
 109 This provides a means of manipulating and introspecting a Perl 5
 110 class. It handles all of symbol table hacking for you, and provides
 111 a rich set of methods that go beyond simple package introspection.
 112
 113 =item The Attribute protocol
 114
 115 This provides a consistent represenation for an attribute of a
 116 Perl 5 class. Since there are so many ways to create and handle
 117 atttributes in Perl 5 OO, this attempts to provide as much of a
 118 unified approach as possible, while giving the freedom and
 119 flexibility to subclass for specialization.
 120
 121 =item The Method protocol
 122
 123 This provides a means of manipulating and introspecting methods in
 124 the Perl 5 object system. As with attributes, there are many ways to
 125 approach this topic, so we try to keep it pretty basic, while still
 126 making it possible to extend the system in many ways.
 127
 128 =back
 129
 130 What follows is a more detailed documentation on each specific sub
 131 protocol.
 132
 133 =head2 The Class protocol
 134
 135 =head3 Class construction
 136
 137 These methods handle creating Class objects, which can be used to
 138 both create new classes, and analyze pre-existing ones.
 139
 140 Class::MOP will internally store weakened references to all the
 141 instances you create with these methods, so that they do not need
 142 to be created any more than nessecary.
 143
 144 =over 4
 145
 146 =item B<create ($package_name, ?$package_version,
 147                 superclasses => ?@superclasses,
 148                 methods      => ?%methods,
 149                 attributes   => ?%attributes)>
 150
 151 This returns the basic Class object, bringing the specified
 152 C<$package_name> into existence and adding any of the
 153 C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes>
 154 to it.
 155
 156 =item B<initialize ($package_name)>
 157
 158 This initializes a Class object for a given a C<$package_name>.
 159
 160 =back
 161
 162 =head3 Instance construction
 163
 164 =over 4
 165
 166 =item B<construct_instance ($canidate, %params)>
 167
 168 This will construct and instance using the C<$canidate> as storage
 169 (currently only HASH references are supported). This will collect all
 170 the applicable attribute meta-objects and layout out the fields in the
 171 C<$canidate>, it will then initialize them using either use the
 172 corresponding key in C<%params> or any default value or initializer
 173 found in the attribute meta-object.
 174
 175 =back
 176
 177 =head3 Informational
 178
 179 =over 4
 180
 181 =item B<name>
 182
 183 This is a read-only attribute which returns the package name that
 184 the Class is stored in.
 185
 186 =item B<version>
 187
 188 This is a read-only attribute which returns the C<$VERSION> of the
 189 package the Class is stored in.
 190
 191 =back
 192
 193 =head3 Inheritance Relationships
 194
 195 =over 4
 196
 197 =item B<superclasses (?@superclasses)>
 198
 199 This is a read-write attribute which represents the superclass
 200 relationships of this Class. Basically, it can get and set the
 201 C<@ISA> for you.
 202
 203 =item B<class_precedence_list>
 204
 205 This computes the a list of the Class's ancestors in the same order
 206 in which method dispatch will be done.
 207
 208 =back
 209
 210 =head3 Methods
 211
 212 =over 4
 213
 214 =item B<add_method ($method_name, $method)>
 215
 216 This will take a C<$method_name> and CODE reference to that
 217 C<$method> and install it into the Class.
 218
 219 B<NOTE> : This does absolutely nothing special to C<$method>
 220 other than use B<Sub::Name> to make sure it is tagged with the
 221 correct name, and therefore show up correctly in stack traces and
 222 such.
 223
 224 =item B<has_method ($method_name)>
 225
 226 This just provides a simple way to check if the Class implements
 227 a specific C<$method_name>. It will I<not> however, attempt to check
 228 if the class inherits the method.
 229
 230 This will correctly handle functions defined outside of the package
 231 that use a fully qualified name (C<sub Package::name { ... }>).
 232
 233 This will correctly handle functions renamed with B<Sub::Name> and
 234 installed using the symbol tables. However, if you are naming the
 235 subroutine outside of the package scope, you must use the fully
 236 qualified name, including the package name, for C<has_method> to
 237 correctly identify it.
 238
 239 This will attempt to correctly ignore functions imported from other
 240 packages using B<Exporter>. It breaks down if the function imported
 241 is an C<__ANON__> sub (such as with C<use constant>), which very well
 242 may be a valid method being applied to the class.
 243
 244 In short, this method cannot always be trusted to determine if the
 245 C<$method_name> is actually a method. However, it will DWIM about
 246 90% of the time, so it's a small trade off IMO.
 247
 248 =item B<get_method ($method_name)>
 249
 250 This will return a CODE reference of the specified C<$method_name>,
 251 or return undef if that method does not exist.
 252
 253 =item B<remove_method ($method_name)>
 254
 255 This will attempt to remove a given C<$method_name> from the Class.
 256 It will return the CODE reference that it has removed, and will
 257 attempt to use B<Sub::Name> to clear the methods associated name.
 258
 259 =item B<get_method_list>
 260
 261 This will return a list of method names for all I<locally> defined
 262 methods. It does B<not> provide a list of all applicable methods,
 263 including any inherited ones. If you want a list of all applicable
 264 methods, use the C<compute_all_applicable_methods> method.
 265
 266 =item B<compute_all_applicable_methods>
 267
 268 This will return a list of all the methods names this Class will
 269 support, taking into account inheritance. The list will be a list of
 270 HASH references, each one containing the following information; method
 271 name, the name of the class in which the method lives and a CODE
 272 reference for the actual method.
 273
 274 =item B<find_all_methods_by_name ($method_name)>
 275
 276 This will traverse the inheritence hierarchy and locate all methods
 277 with a given C<$method_name>. Similar to
 278 C<compute_all_applicable_methods> it returns a list of HASH references
 279 with the following information; method name (which will always be the
 280 same as C<$method_name>), the name of the class in which the method
 281 lives and a CODE reference for the actual method.
 282
 283 The list of methods produced is a distinct list, meaning there are no
 284 duplicates in it. This is especially useful for things like object
 285 initialization and destruction where you only want the method called
 286 once, and in the correct order.
 287
 288 =back
 289
 290 =head3 Attributes
 291
 292 It should be noted that since there is no one consistent way to define
 293 the attributes of a class in Perl 5. These methods can only work with
 294 the information given, and can not easily discover information on
 295 their own.
 296
 297 =over 4
 298
 299 =item B<add_attribute ($attribute_name, $attribute_meta_object)>
 300
 301 This stores a C<$attribute_meta_object> in the Class object and
 302 associates it with the C<$attribute_name>. Unlike methods, attributes
 303 within the MOP are stored as meta-information only. They will be used
 304 later to construct instances from (see C<construct_instance> above).
 305 More details about the attribute meta-objects can be found in the
 306 L<The Attribute protocol> section of this document.
 307
 308 =item B<has_attribute ($attribute_name)>
 309
 310 Checks to see if this Class has an attribute by the name of
 311 C<$attribute_name> and returns a boolean.
 312
 313 =item B<get_attribute ($attribute_name)>
 314
 315 Returns the attribute meta-object associated with C<$attribute_name>,
 316 if none is found, it will return undef.
 317
 318 =item B<remove_attribute ($attribute_name)>
 319
 320 This will remove the attribute meta-object stored at
 321 C<$attribute_name>, then return the removed attribute meta-object.
 322
 323 B<NOTE:> Removing an attribute will only affect future instances of
 324 the class, it will not make any attempt to remove the attribute from
 325 any existing instances of the class.
 326
 327 =item B<get_attribute_list>
 328
 329 This returns a list of attribute names which are defined in the local
 330 class. If you want a list of all applicable attributes for a class,
 331 use the C<compute_all_applicable_attributes> method.
 332
 333 =item B<compute_all_applicable_attributes>
 334
 335 This will traverse the inheritance heirachy and return a list of HASH
 336 references for all the applicable attributes for this class. The HASH
 337 references will contain the following information; the attribute name,
 338 the class which the attribute is associated with and the actual
 339 attribute meta-object
 340
 341 =item B<create_all_accessors>
 342
 343 This will communicate with all of the classes attributes to create
 344 and install the appropriate accessors. (see L<The Attribute Protocol>
 345 below for more details).
 346
 347 =back
 348
 349 =head2 The Attribute Protocol
 350
 351 This protocol is almost entirely an invention of this module. This is
 352 because Perl 5 does not have consistent notion of what is an attribute
 353 of a class. There are so many ways in which this is done, and very few
 354 (if any) are discoverable by this module.
 355
 356 So, all that said, this module attempts to inject some order into this
 357 chaos, by introducing a more consistent approach.
 358
 359 =head3 Creation
 360
 361 =over 4
 362
 363 =item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)>
 364
 365   Class::MOP::Attribute->new('$foo' => (
 366       accessor => 'foo',        # dual purpose get/set accessor
 367       init_arg => '-foo',       # class->new will look for a -foo key
 368       default  => 'BAR IS BAZ!' # if no -foo key is provided, use this
 369   ));
 370
 371   Class::MOP::Attribute->new('$.bar' => (
 372       reader   => 'bar',        # getter
 373       writer   => 'set_bar',    # setter
 374       init_arg => '-bar',       # class->new will look for a -bar key
 375       # no default value means it is undef
 376   ));
 377
 378 =back
 379
 380 =head3 Informational
 381
 382 =over 4
 383
 384 =item B<name>
 385
 386 =item B<accessor>
 387
 388 =item B<reader>
 389
 390 =item B<writer>
 391
 392 =item B<init_arg>
 393
 394 =item B<default>
 395
 396 =back
 397
 398 =head3 Informational predicates
 399
 400 =over 4
 401
 402 =item B<has_accessor>
 403
 404 Returns true if this attribute uses a get/set accessor, and false
 405 otherwise
 406
 407 =item B<has_reader>
 408
 409 Returns true if this attribute has a reader, and false otherwise
 410
 411 =item B<has_writer>
 412
 413 Returns true if this attribute has a writer, and false otherwise
 414
 415 =item B<has_init_arg>
 416
 417 Returns true if this attribute has a class intialization argument, and
 418 false otherwise
 419
 420 =item B<has_default>
 421
 422 Returns true if this attribute has a default value, and false
 423 otherwise.
 424
 425 =back
 426
 427 =head3 Attribute Accessor generation
 428
 429 =over 4
 430
 431 =item B<generate_accessors>
 432
 433 This allows the attribute to generate code for it's own accessor
 434 methods. This is mostly part of an internal protocol between the class
 435 and it's own attributes, see the C<create_all_accessors> method above.
 436
 437 =back
 438
 439 =head2 The Method Protocol
 440
 441 This protocol is very small, since methods in Perl 5 are just
 442 subroutines within the particular package. Basically all we do is to
 443 bless the subroutine and provide some very simple introspection
 444 methods for it.
 445
 446 =head1 SEE ALSO
 447
 448 =over 4
 449
 450 =item "The Art of the Meta Object Protocol"
 451
 452 =item "Advances in Object-Oriented Metalevel Architecture and Reflection"
 453
 454 =back
 455
 456 =head1 AUTHOR
 457
 458 Stevan Little E<gt>stevan@iinteractive.comE<lt>
 459
 460 =head1 COPYRIGHT AND LICENSE
 461
 462 Copyright 2006 by Infinity Interactive, Inc.
 463
 464 L<http://www.iinteractive.com>
 465
 466 This library is free software; you can redistribute it and/or modify
 467 it under the same terms as Perl itself.
 468
 469 =cut