lib/Class/MOP.pm

   1
   2 package Class::MOP;
   3
   4 use strict;
   5 use warnings;
   6
   7 our $VERSION = '0.01';
   8
   9 1;
  10
  11 __END__
  12
  13 =pod
  14
  15 =head1 NAME
  16
  17 Class::MOP - A Meta Object Protocol for Perl 5
  18
  19 =head1 SYNOPSIS
  20
  21   # ... coming soon
  22
  23 =head1 DESCRIPTON
  24
  25 This module is an attempt to create a meta object protocol for the
  26 Perl 5 object system. It makes no attempt to change the behavior or
  27 characteristics of the Perl 5 object system, only to create a
  28 protocol for it's manipulation and introspection.
  29
  30 That said, it does attempt to create the tools for building a rich
  31 set of extensions to the Perl 5 object system. Every attempt has been
  32 made for these tools to keep to the spirit of the Perl 5 object
  33 system that we all know and love.
  34
  35 =head2 Who is this module for?
  36
  37 This module is specifically for anyone who has ever created or
  38 wanted to create a module for the Class:: namespace. The tools which
  39 this module will provide will hopefully make it easier to do more
  40 complex things with Perl 5 classes by removing such barriers as
  41 the need to hack the symbol tables, or understand the fine details
  42 of method dispatch.
  43
  44 =head1 PROTOCOLS
  45
  46 The protocol is divided into 3 main sub-protocols:
  47
  48 =over 4
  49
  50 =item The Class protocol
  51
  52 This provides a means of manipulating and introspecting a Perl 5
  53 class. It handles all of symbol table hacking for you, and provides
  54 a rich set of methods that go beyond simple package introspection.
  55
  56 =item The Attribute protocol
  57
  58 This provides a consistent represenation for an attribute of a
  59 Perl 5 class. Since there are so many ways to create and handle
  60 atttributes in Perl 5 OO, this attempts to provide as much of a
  61 unified approach as possible, while giving the freedom and
  62 flexibility to subclass for specialization.
  63
  64 =item The Method protocol
  65
  66 This provides a means of manipulating and introspecting methods in
  67 the Perl 5 object system. As with attributes, there are many ways to
  68 approach this topic, so we try to keep it pretty basic, while still
  69 making it possible to extend the system in many ways.
  70
  71 =back
  72
  73 What follows is a more detailed documentation on each specific sub
  74 protocol.
  75
  76 =head2 The Class protocol
  77
  78 =head3 Creation
  79
  80 These methods handle creating Class objects, which can be used to
  81 both create new classes, and analyze pre-existing ones.
  82
  83 Class::MOP will internally store weakened references to all the
  84 instances you create with these methods, so that they do not need
  85 to be created any more than nessecary.
  86
  87 =over 4
  88
  89 =item B<create ($package_name, ?@superclasses, ?%methods, ?%attributes)>
  90
  91 This returns the basic Class object, bringing the specified
  92 C<$package_name> into existence and adding any of the
  93 C<@superclasses>, C<%methods> and C<%attributes> to it.
  94
  95 =item B<load ($package_name)>
  96
  97 This returns the basic Class object, after examining the given
  98 C<$package_name> and attempting to discover it's components (the
  99 methods, attributes and superclasses).
 100
 101 B<NOTE>: This method makes every attempt to ignore subroutines
 102 which have been exported by other packages into this one.
 103
 104 =item B<initialize ($package_name, @superclasses, %methods, %attributes)>
 105
 106 This creates the actual Class object given a C<$package_nam>,
 107 an array of C<@superclasses>, a hash of C<%methods> and a hash
 108 of C<%attributes>. This method is used by both C<load> and
 109 C<create>.
 110
 111 This method also stores the Class object for you inside Class::MOP.
 112
 113 =back
 114
 115 =head3 Informational
 116
 117 =over 4
 118
 119 =item C<name>
 120
 121 This is a read-only attribute which returns the package name that
 122 the Class is stored in.
 123
 124 =item C<version>
 125
 126 This is a read-only attribute which returns the C<$VERSION> of the
 127 package the Class is stored in.
 128
 129 =back
 130
 131 =head3 Inheritance Relationships
 132
 133 =over 4
 134
 135 =item C<superclasses (?@superclasses)>
 136
 137 This is a read-write attribute which represents the superclass
 138 relationships of this Class. Basically, it can get and set the
 139 C<@ISA> for you.
 140
 141 =item C<class_precendence_list>
 142
 143 This computes the a list of the Class's ancestors in the same order
 144 in which method dispatch will be done.
 145
 146 =back
 147
 148 =head3 Methods
 149
 150 =over 4
 151
 152 =item C<add_method ($method_name, $method)>
 153
 154 This will take a C<$method_name> and CODE reference to that
 155 C<$method> and install it into the Class.
 156
 157 B<NOTE> : This does absolutely nothing special to C<$method>
 158 other than use B<Sub::Name> to make sure it is tagged with the
 159 correct name, and therefore show up correctly in stack traces and
 160 such.
 161
 162 =item C<has_method ($method_name)>
 163
 164 This just provides a simple way to check if the Class implements
 165 a specific C<$method_name>. It will I<not> however, attempt to check
 166 if the class inherits the method.
 167
 168 =item C<get_method ($method_name)>
 169
 170 This will return a CODE reference of the specified C<$method_name>,
 171 or return undef if that method does not exist.
 172
 173 =item C<remove_method ($method_name)>
 174
 175 This will attempt to remove a given C<$method_name> from the Class.
 176 It will return the CODE reference that it has removed, and will
 177 attempt to use B<Sub::Name> to clear the methods associated name.
 178
 179 =item C<get_method_list>
 180
 181 This will return a list of method names for all I<locally> defined
 182 methods. It does B<not> provide a list of all applicable methods,
 183 including any inherited ones. If you want a list of all applicable
 184 methods, use the C<compute_all_applicable_methods> method.
 185
 186 =item C<compute_all_applicable_methods>
 187
 188 This will return a list of all the methods names this Class will
 189 support, taking into account inheritance. The list will be a list of
 190 HASH references, each one containing the following information; method
 191 name, the name of the class in which the method lives and a CODE reference
 192 for the actual method.
 193
 194 =item C<find_methods_by_name ($method_name)>
 195
 196 This will traverse the inheritence hierarchy and locate all methods
 197 with a given C<$method_name>. Similar to C<compute_all_applicable_methods>
 198 it returns a list of HASH references with the following information;
 199 method name (which will always be the same as C<$method_name), the name of
 200 the class in which the method lives and a CODE reference for the actual method.
 201
 202 =back
 203
 204 =head2 Attributes
 205
 206 It should be noted that since there is no one consistent way to define the
 207 attributes of a class in Perl 5. These methods can only work with the
 208 information given, and can not easily discover information on their own.
 209
 210 =over 4
 211
 212 =item C<>
 213
 214 =item C<>
 215
 216 =item C<>
 217
 218 =item C<>
 219
 220 =item C<>
 221
 222 =item C<>
 223
 224 =back
 225
 226 =head1 SEE ALSO
 227
 228 =over 4
 229
 230 =item "The Art of the Meta Object Protocol"
 231
 232 =item CLOS
 233
 234 =back
 235
 236 =head1 AUTHOR
 237
 238 Stevan Little E<gt>stevan@iinteractive.comE<lt>
 239
 240 =head1 COPYRIGHT AND LICENSE
 241
 242 Copyright 2006 by Infinity Interactive, Inc.
 243
 244 L<http://www.iinteractive.com>
 245
 246 This library is free software; you can redistribute it and/or modify
 247 it under the same terms as Perl itself.
 248
 249 =cut
 250
 251
 252