more method modifier stuff
[gitmo/Class-MOP.git] / lib / Class / MOP / Class.pm
CommitLineData
8b978dd5 1
2package Class::MOP::Class;
3
4use strict;
5use warnings;
6
7use Carp 'confess';
0882828e 8use Scalar::Util 'blessed', 'reftype';
8b978dd5 9use Sub::Name 'subname';
8b978dd5 10
d3cb0d4a 11our $VERSION = '0.06';
8b978dd5 12
aa448b16 13# Self-introspection
2eb717d5 14
aa448b16 15sub meta { Class::MOP::Class->initialize(blessed($_[0]) || $_[0]) }
2eb717d5 16
8b978dd5 17# Creation
18
bfe4d0fc 19{
20 # Metaclasses are singletons, so we cache them here.
21 # there is no need to worry about destruction though
22 # because they should die only when the program dies.
23 # After all, do package definitions even get reaped?
651955fb 24 my %METAS;
25
bfe4d0fc 26 sub initialize {
351bd7d4 27 my $class = shift;
28 my $package_name = shift;
22286063 29 (defined $package_name && $package_name && !blessed($package_name))
30 || confess "You must pass a package name and it cannot be blessed";
651955fb 31 $class->construct_class_instance(':package' => $package_name, @_);
727919c5 32 }
33
34 # NOTE: (meta-circularity)
35 # this is a special form of &construct_instance
36 # (see below), which is used to construct class
1a7ebbb3 37 # meta-object instances for any Class::MOP::*
38 # class. All other classes will use the more
39 # normal &construct_instance.
727919c5 40 sub construct_class_instance {
351bd7d4 41 my $class = shift;
651955fb 42 my %options = @_;
43 my $package_name = $options{':package'};
727919c5 44 (defined $package_name && $package_name)
651955fb 45 || confess "You must pass a package name";
46 return $METAS{$package_name} if exists $METAS{$package_name};
1a7ebbb3 47 $class = blessed($class) || $class;
550d56db 48 # now create the metaclass
49 my $meta;
1a7ebbb3 50 if ($class =~ /^Class::MOP::/) {
550d56db 51 $meta = bless {
351bd7d4 52 '$:package' => $package_name,
53 '%:attributes' => {},
550d56db 54 '$:attribute_metaclass' => $options{':attribute_metaclass'} || 'Class::MOP::Attribute',
55 '$:method_metaclass' => $options{':method_metaclass'} || 'Class::MOP::Method',
1a7ebbb3 56 } => $class;
57 }
58 else {
5f3c057a 59 # NOTE:
60 # it is safe to use meta here because
61 # class will always be a subclass of
62 # Class::MOP::Class, which defines meta
550d56db 63 $meta = bless $class->meta->construct_instance(%options) => $class
1a7ebbb3 64 }
550d56db 65 # and check the metaclass compatibility
66 $meta->check_metaclass_compatability();
67 $METAS{$package_name} = $meta;
68 }
69
70 sub check_metaclass_compatability {
71 my $self = shift;
72
73 # this is always okay ...
74 return if blessed($self) eq 'Class::MOP::Class';
75
76 my @class_list = $self->class_precedence_list;
77 shift @class_list; # shift off $self->name
78
79 foreach my $class_name (@class_list) {
550d56db 80 my $meta = $METAS{$class_name};
81 ($self->isa(blessed($meta)))
82 || confess $self->name . "->meta => (" . (blessed($self)) . ")" .
83 " is not compatible with the " .
84 $class_name . "->meta => (" . (blessed($meta)) . ")";
85 }
bfe4d0fc 86 }
8b978dd5 87}
88
89sub create {
90 my ($class, $package_name, $package_version, %options) = @_;
bfe4d0fc 91 (defined $package_name && $package_name)
8b978dd5 92 || confess "You must pass a package name";
93 my $code = "package $package_name;";
94 $code .= "\$$package_name\:\:VERSION = '$package_version';"
95 if defined $package_version;
96 eval $code;
97 confess "creation of $package_name failed : $@" if $@;
bfe4d0fc 98 my $meta = $class->initialize($package_name);
aa448b16 99
100 $meta->add_method('meta' => sub {
101 Class::MOP::Class->initialize(blessed($_[0]) || $_[0]);
102 });
103
8b978dd5 104 $meta->superclasses(@{$options{superclasses}})
105 if exists $options{superclasses};
2eb717d5 106 # NOTE:
107 # process attributes first, so that they can
108 # install accessors, but locally defined methods
109 # can then overwrite them. It is maybe a little odd, but
110 # I think this should be the order of things.
111 if (exists $options{attributes}) {
cbd9f942 112 foreach my $attr (@{$options{attributes}}) {
113 $meta->add_attribute($attr);
2eb717d5 114 }
115 }
bfe4d0fc 116 if (exists $options{methods}) {
117 foreach my $method_name (keys %{$options{methods}}) {
118 $meta->add_method($method_name, $options{methods}->{$method_name});
119 }
2eb717d5 120 }
8b978dd5 121 return $meta;
122}
123
7b31baf4 124## Attribute readers
125
126# NOTE:
127# all these attribute readers will be bootstrapped
128# away in the Class::MOP bootstrap section
129
130sub name { $_[0]->{'$:package'} }
131sub get_attribute_map { $_[0]->{'%:attributes'} }
132sub attribute_metaclass { $_[0]->{'$:attribute_metaclass'} }
133sub method_metaclass { $_[0]->{'$:method_metaclass'} }
134
c9e77dbb 135# Instance Construction & Cloning
136
5f3c057a 137sub new_object {
138 my $class = shift;
651955fb 139 # NOTE:
140 # we need to protect the integrity of the
141 # Class::MOP::Class singletons here, so we
142 # delegate this to &construct_class_instance
143 # which will deal with the singletons
144 return $class->construct_class_instance(@_)
145 if $class->name->isa('Class::MOP::Class');
5f3c057a 146 bless $class->construct_instance(@_) => $class->name;
147}
e16da3e6 148
149sub construct_instance {
cbd9f942 150 my ($class, %params) = @_;
151 my $instance = {};
c9e77dbb 152 foreach my $attr ($class->compute_all_applicable_attributes()) {
651955fb 153 my $init_arg = $attr->init_arg();
cbd9f942 154 # try to fetch the init arg from the %params ...
155 my $val;
156 $val = $params{$init_arg} if exists $params{$init_arg};
157 # if nothing was in the %params, we can use the
158 # attribute's default value (if it has one)
c9e77dbb 159 $val ||= $attr->default($instance) if $attr->has_default();
cbd9f942 160 $instance->{$attr->name} = $val;
161 }
162 return $instance;
e16da3e6 163}
164
5f3c057a 165sub clone_object {
166 my $class = shift;
7b31baf4 167 my $instance = shift;
651955fb 168 (blessed($instance) && $instance->isa($class->name))
169 || confess "You must pass an instance ($instance) of the metaclass (" . $class->name . ")";
170 # NOTE:
171 # we need to protect the integrity of the
172 # Class::MOP::Class singletons here, they
a740253a 173 # should not be cloned.
651955fb 174 return $instance if $instance->isa('Class::MOP::Class');
175 bless $class->clone_instance($instance, @_) => blessed($instance);
5f3c057a 176}
177
c9e77dbb 178sub clone_instance {
651955fb 179 my ($class, $instance, %params) = @_;
180 (blessed($instance))
c9e77dbb 181 || confess "You can only clone instances, \$self is not a blessed instance";
19d4b5b8 182 my $clone = { %$instance, %params };
c9e77dbb 183 return $clone;
184}
185
8b978dd5 186# Informational
187
7b31baf4 188# &name should be here too, but it is above
189# because it gets bootstrapped away
8b978dd5 190
191sub version {
192 my $self = shift;
193 no strict 'refs';
194 ${$self->name . '::VERSION'};
195}
196
197# Inheritance
198
199sub superclasses {
200 my $self = shift;
201 no strict 'refs';
202 if (@_) {
203 my @supers = @_;
204 @{$self->name . '::ISA'} = @supers;
205 }
206 @{$self->name . '::ISA'};
207}
208
209sub class_precedence_list {
210 my $self = shift;
bfe4d0fc 211 # NOTE:
212 # We need to check for ciruclar inheirtance here.
213 # This will do nothing if all is well, and blow
214 # up otherwise. Yes, it's an ugly hack, better
215 # suggestions are welcome.
216 { $self->name->isa('This is a test for circular inheritance') }
217 # ... and no back to our regularly scheduled program
8b978dd5 218 (
219 $self->name,
220 map {
bfe4d0fc 221 $self->initialize($_)->class_precedence_list()
8b978dd5 222 } $self->superclasses()
223 );
224}
225
0882828e 226## Methods
227
228sub add_method {
229 my ($self, $method_name, $method) = @_;
230 (defined $method_name && $method_name)
231 || confess "You must define a method name";
a5eca695 232 # use reftype here to allow for blessed subs ...
ee5e71d4 233 ('CODE' eq (reftype($method) || ''))
0882828e 234 || confess "Your code block must be a CODE reference";
235 my $full_method_name = ($self->name . '::' . $method_name);
de19f115 236
237 $method = Class::MOP::Method->new($method) unless blessed($method);
238
0882828e 239 no strict 'refs';
c9b8b7f9 240 no warnings 'redefine';
22286063 241 *{$full_method_name} = subname $full_method_name => $method;
0882828e 242}
243
ee5e71d4 244sub add_method_modifier {
245
246}
247
663f8198 248sub alias_method {
249 my ($self, $method_name, $method) = @_;
250 (defined $method_name && $method_name)
251 || confess "You must define a method name";
252 # use reftype here to allow for blessed subs ...
ee5e71d4 253 ('CODE' eq (reftype($method) || ''))
663f8198 254 || confess "Your code block must be a CODE reference";
de19f115 255 my $full_method_name = ($self->name . '::' . $method_name);
256
257 $method = Class::MOP::Method->new($method) unless blessed($method);
663f8198 258
259 no strict 'refs';
260 no warnings 'redefine';
261 *{$full_method_name} = $method;
262}
263
de19f115 264sub has_method {
265 my ($self, $method_name) = @_;
266 (defined $method_name && $method_name)
267 || confess "You must define a method name";
bfe4d0fc 268
de19f115 269 my $sub_name = ($self->name . '::' . $method_name);
0882828e 270
de19f115 271 no strict 'refs';
272 return 0 if !defined(&{$sub_name});
273
274 my $method = \&{$sub_name};
275 $method = Class::MOP::Method->new($method) unless blessed($method);
276
277 return 0 if $method->package_name ne $self->name &&
278 $method->name ne '__ANON__';
279 return 1;
0882828e 280}
281
282sub get_method {
c9b8b7f9 283 my ($self, $method_name) = @_;
0882828e 284 (defined $method_name && $method_name)
285 || confess "You must define a method name";
286
de19f115 287 return unless $self->has_method($method_name);
288
0882828e 289 no strict 'refs';
de19f115 290 return \&{$self->name . '::' . $method_name};
c9b8b7f9 291}
292
293sub remove_method {
294 my ($self, $method_name) = @_;
295 (defined $method_name && $method_name)
296 || confess "You must define a method name";
297
298 my $removed_method = $self->get_method($method_name);
299
300 no strict 'refs';
301 delete ${$self->name . '::'}{$method_name}
302 if defined $removed_method;
303
304 return $removed_method;
305}
306
307sub get_method_list {
308 my $self = shift;
309 no strict 'refs';
a5eca695 310 grep { $self->has_method($_) } %{$self->name . '::'};
311}
312
313sub compute_all_applicable_methods {
314 my $self = shift;
315 my @methods;
316 # keep a record of what we have seen
317 # here, this will handle all the
318 # inheritence issues because we are
319 # using the &class_precedence_list
320 my (%seen_class, %seen_method);
321 foreach my $class ($self->class_precedence_list()) {
322 next if $seen_class{$class};
323 $seen_class{$class}++;
324 # fetch the meta-class ...
325 my $meta = $self->initialize($class);
326 foreach my $method_name ($meta->get_method_list()) {
327 next if exists $seen_method{$method_name};
328 $seen_method{$method_name}++;
329 push @methods => {
330 name => $method_name,
331 class => $class,
332 code => $meta->get_method($method_name)
333 };
334 }
335 }
336 return @methods;
337}
338
a5eca695 339sub find_all_methods_by_name {
340 my ($self, $method_name) = @_;
341 (defined $method_name && $method_name)
342 || confess "You must define a method name to find";
343 my @methods;
344 # keep a record of what we have seen
345 # here, this will handle all the
346 # inheritence issues because we are
347 # using the &class_precedence_list
348 my %seen_class;
349 foreach my $class ($self->class_precedence_list()) {
350 next if $seen_class{$class};
351 $seen_class{$class}++;
352 # fetch the meta-class ...
aa448b16 353 my $meta = $self->initialize($class);;
a5eca695 354 push @methods => {
355 name => $method_name,
356 class => $class,
357 code => $meta->get_method($method_name)
358 } if $meta->has_method($method_name);
359 }
360 return @methods;
8b978dd5 361}
362
552e3d24 363## Attributes
364
e16da3e6 365sub add_attribute {
2e41896e 366 my $self = shift;
367 # either we have an attribute object already
368 # or we need to create one from the args provided
369 my $attribute = blessed($_[0]) ? $_[0] : $self->attribute_metaclass->new(@_);
370 # make sure it is derived from the correct type though
371 ($attribute->isa('Class::MOP::Attribute'))
372 || confess "Your attribute must be an instance of Class::MOP::Attribute (or a subclass)";
9ec169fe 373 $attribute->attach_to_class($self);
374 $attribute->install_accessors();
7b31baf4 375 $self->get_attribute_map->{$attribute->name} = $attribute;
e16da3e6 376}
377
378sub has_attribute {
379 my ($self, $attribute_name) = @_;
380 (defined $attribute_name && $attribute_name)
381 || confess "You must define an attribute name";
7b31baf4 382 exists $self->get_attribute_map->{$attribute_name} ? 1 : 0;
e16da3e6 383}
384
385sub get_attribute {
386 my ($self, $attribute_name) = @_;
387 (defined $attribute_name && $attribute_name)
388 || confess "You must define an attribute name";
7b31baf4 389 return $self->get_attribute_map->{$attribute_name}
22286063 390 if $self->has_attribute($attribute_name);
391 return;
e16da3e6 392}
393
394sub remove_attribute {
395 my ($self, $attribute_name) = @_;
396 (defined $attribute_name && $attribute_name)
397 || confess "You must define an attribute name";
7b31baf4 398 my $removed_attribute = $self->get_attribute_map->{$attribute_name};
22286063 399 return unless defined $removed_attribute;
400 delete $self->get_attribute_map->{$attribute_name};
9ec169fe 401 $removed_attribute->remove_accessors();
402 $removed_attribute->detach_from_class();
e16da3e6 403 return $removed_attribute;
404}
405
406sub get_attribute_list {
407 my $self = shift;
7b31baf4 408 keys %{$self->get_attribute_map};
e16da3e6 409}
410
411sub compute_all_applicable_attributes {
412 my $self = shift;
413 my @attrs;
414 # keep a record of what we have seen
415 # here, this will handle all the
416 # inheritence issues because we are
417 # using the &class_precedence_list
418 my (%seen_class, %seen_attr);
419 foreach my $class ($self->class_precedence_list()) {
420 next if $seen_class{$class};
421 $seen_class{$class}++;
422 # fetch the meta-class ...
423 my $meta = $self->initialize($class);
424 foreach my $attr_name ($meta->get_attribute_list()) {
425 next if exists $seen_attr{$attr_name};
426 $seen_attr{$attr_name}++;
c9e77dbb 427 push @attrs => $meta->get_attribute($attr_name);
e16da3e6 428 }
429 }
430 return @attrs;
431}
2eb717d5 432
52e8a34c 433# Class attributes
434
435sub add_package_variable {
436 my ($self, $variable, $initial_value) = @_;
437 (defined $variable && $variable =~ /^[\$\@\%]/)
438 || confess "variable name does not have a sigil";
439
440 my ($sigil, $name) = ($variable =~ /^(.)(.*)$/);
441 if (defined $initial_value) {
442 no strict 'refs';
443 *{$self->name . '::' . $name} = $initial_value;
444 }
445 else {
446 eval $sigil . $self->name . '::' . $name;
447 confess "Could not create package variable ($variable) because : $@" if $@;
448 }
449}
450
451sub has_package_variable {
452 my ($self, $variable) = @_;
453 (defined $variable && $variable =~ /^[\$\@\%]/)
454 || confess "variable name does not have a sigil";
455 my ($sigil, $name) = ($variable =~ /^(.)(.*)$/);
456 no strict 'refs';
457 defined ${$self->name . '::'}{$name} ? 1 : 0;
458}
459
460sub get_package_variable {
461 my ($self, $variable) = @_;
462 (defined $variable && $variable =~ /^[\$\@\%]/)
463 || confess "variable name does not have a sigil";
464 my ($sigil, $name) = ($variable =~ /^(.)(.*)$/);
465 no strict 'refs';
466 # try to fetch it first,.. see what happens
18697ac8 467 my $ref = eval '\\' . $sigil . $self->name . '::' . $name;
52e8a34c 468 confess "Could not get the package variable ($variable) because : $@" if $@;
469 # if we didn't die, then we can return it
18697ac8 470 return $ref;
52e8a34c 471}
472
473sub remove_package_variable {
474 my ($self, $variable) = @_;
475 (defined $variable && $variable =~ /^[\$\@\%]/)
476 || confess "variable name does not have a sigil";
477 my ($sigil, $name) = ($variable =~ /^(.)(.*)$/);
478 no strict 'refs';
479 delete ${$self->name . '::'}{$name};
480}
481
8b978dd5 4821;
483
484__END__
485
486=pod
487
488=head1 NAME
489
490Class::MOP::Class - Class Meta Object
491
492=head1 SYNOPSIS
493
fe122940 494 # use this for introspection ...
495
fe122940 496 # add a method to Foo ...
497 Foo->meta->add_method('bar' => sub { ... })
498
499 # get a list of all the classes searched
500 # the method dispatcher in the correct order
501 Foo->meta->class_precedence_list()
502
503 # remove a method from Foo
504 Foo->meta->remove_method('bar');
505
506 # or use this to actually create classes ...
507
508 Class::MOP::Class->create('Bar' => '0.01' => (
509 superclasses => [ 'Foo' ],
510 attributes => [
511 Class::MOP:::Attribute->new('$bar'),
512 Class::MOP:::Attribute->new('$baz'),
513 ],
514 methods => {
515 calculate_bar => sub { ... },
516 construct_baz => sub { ... }
517 }
518 ));
519
8b978dd5 520=head1 DESCRIPTION
521
fe122940 522This is the largest and currently most complex part of the Perl 5
523meta-object protocol. It controls the introspection and
524manipulation of Perl 5 classes (and it can create them too). The
525best way to understand what this module can do, is to read the
526documentation for each of it's methods.
527
552e3d24 528=head1 METHODS
529
2eb717d5 530=head2 Self Introspection
531
532=over 4
533
534=item B<meta>
535
fe122940 536This will return a B<Class::MOP::Class> instance which is related
537to this class. Thereby allowing B<Class::MOP::Class> to actually
538introspect itself.
539
540As with B<Class::MOP::Attribute>, B<Class::MOP> will actually
541bootstrap this module by installing a number of attribute meta-objects
542into it's metaclass. This will allow this class to reap all the benifits
543of the MOP when subclassing it.
2eb717d5 544
545=back
546
552e3d24 547=head2 Class construction
548
a2e85e6c 549These methods will handle creating B<Class::MOP::Class> objects,
550which can be used to both create new classes, and analyze
551pre-existing classes.
552e3d24 552
553This module will internally store references to all the instances
554you create with these methods, so that they do not need to be
555created any more than nessecary. Basically, they are singletons.
556
557=over 4
558
559=item B<create ($package_name, ?$package_version,
a2e85e6c 560 superclasses =E<gt> ?@superclasses,
561 methods =E<gt> ?%methods,
562 attributes =E<gt> ?%attributes)>
552e3d24 563
a2e85e6c 564This returns a B<Class::MOP::Class> object, bringing the specified
552e3d24 565C<$package_name> into existence and adding any of the
566C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes>
567to it.
568
569=item B<initialize ($package_name)>
570
a2e85e6c 571This initializes and returns returns a B<Class::MOP::Class> object
572for a given a C<$package_name>.
573
651955fb 574=item B<construct_class_instance (%options)>
a2e85e6c 575
576This will construct an instance of B<Class::MOP::Class>, it is
577here so that we can actually "tie the knot" for B<Class::MOP::Class>
578to use C<construct_instance> once all the bootstrapping is done. This
579method is used internally by C<initialize> and should never be called
580from outside of that method really.
552e3d24 581
550d56db 582=item B<check_metaclass_compatability>
583
584This method is called as the very last thing in the
585C<construct_class_instance> method. This will check that the
586metaclass you are creating is compatible with the metaclasses of all
587your ancestors. For more inforamtion about metaclass compatibility
588see the C<About Metaclass compatibility> section in L<Class::MOP>.
589
552e3d24 590=back
591
c9e77dbb 592=head2 Object instance construction and cloning
a2e85e6c 593
c9e77dbb 594These methods are B<entirely optional>, it is up to you whether you want
595to use them or not.
552e3d24 596
597=over 4
598
5f3c057a 599=item B<new_object (%params)>
600
601This is a convience method for creating a new object of the class, and
602blessing it into the appropriate package as well. Ideally your class
603would call a C<new> this method like so:
604
605 sub MyClass::new {
606 my ($class, %param) = @_;
607 $class->meta->new_object(%params);
608 }
609
610Of course the ideal place for this would actually be in C<UNIVERSAL::>
611but that is considered bad style, so we do not do that.
612
cbd9f942 613=item B<construct_instance (%params)>
552e3d24 614
c9e77dbb 615This method is used to construct an instace structure suitable for
616C<bless>-ing into your package of choice. It works in conjunction
617with the Attribute protocol to collect all applicable attributes.
618
cbd9f942 619This will construct and instance using a HASH ref as storage
552e3d24 620(currently only HASH references are supported). This will collect all
a2e85e6c 621the applicable attributes and layout out the fields in the HASH ref,
622it will then initialize them using either use the corresponding key
623in C<%params> or any default value or initializer found in the
624attribute meta-object.
727919c5 625
5f3c057a 626=item B<clone_object ($instance, %params)>
627
628This is a convience method for cloning an object instance, then
19d4b5b8 629blessing it into the appropriate package. This method will call
630C<clone_instance>, which performs a shallow copy of the object,
631see that methods documentation for more details. Ideally your
632class would call a C<clone> this method like so:
5f3c057a 633
634 sub MyClass::clone {
635 my ($self, %param) = @_;
636 $self->meta->clone_object($self, %params);
637 }
638
639Of course the ideal place for this would actually be in C<UNIVERSAL::>
640but that is considered bad style, so we do not do that.
641
c9e77dbb 642=item B<clone_instance($instance, %params)>
643
644This method is a compliment of C<construct_instance> (which means if
19d4b5b8 645you override C<construct_instance>, you need to override this one too),
646and clones the instance shallowly.
a27ae83f 647
648The cloned structure returned is (like with C<construct_instance>) an
649unC<bless>ed HASH reference, it is your responsibility to then bless
650this cloned structure into the right class (which C<clone_object> will
651do for you).
c9e77dbb 652
19d4b5b8 653As of 0.11, this method will clone the C<$instance> structure shallowly,
654as opposed to the deep cloning implemented in prior versions. After much
655thought, research and discussion, I have decided that anything but basic
656shallow cloning is outside the scope of the meta-object protocol. I
657think Yuval "nothingmuch" Kogman put it best when he said that cloning
658is too I<context-specific> to be part of the MOP.
659
552e3d24 660=back
661
662=head2 Informational
663
664=over 4
665
666=item B<name>
667
a2e85e6c 668This is a read-only attribute which returns the package name for the
669given B<Class::MOP::Class> instance.
552e3d24 670
671=item B<version>
672
673This is a read-only attribute which returns the C<$VERSION> of the
a2e85e6c 674package for the given B<Class::MOP::Class> instance.
552e3d24 675
676=back
677
678=head2 Inheritance Relationships
679
680=over 4
681
682=item B<superclasses (?@superclasses)>
683
684This is a read-write attribute which represents the superclass
a2e85e6c 685relationships of the class the B<Class::MOP::Class> instance is
686associated with. Basically, it can get and set the C<@ISA> for you.
552e3d24 687
343203ee 688B<NOTE:>
689Perl will occasionally perform some C<@ISA> and method caching, if
690you decide to change your superclass relationship at runtime (which
691is quite insane and very much not recommened), then you should be
692aware of this and the fact that this module does not make any
693attempt to address this issue.
694
552e3d24 695=item B<class_precedence_list>
696
a2e85e6c 697This computes the a list of all the class's ancestors in the same order
698in which method dispatch will be done. This is similair to
699what B<Class::ISA::super_path> does, but we don't remove duplicate names.
552e3d24 700
701=back
702
703=head2 Methods
704
705=over 4
706
2e41896e 707=item B<method_metaclass>
708
552e3d24 709=item B<add_method ($method_name, $method)>
710
711This will take a C<$method_name> and CODE reference to that
a2e85e6c 712C<$method> and install it into the class's package.
552e3d24 713
a2e85e6c 714B<NOTE>:
715This does absolutely nothing special to C<$method>
552e3d24 716other than use B<Sub::Name> to make sure it is tagged with the
717correct name, and therefore show up correctly in stack traces and
718such.
719
ee5e71d4 720=item B<add_method_modifier ($modifier_type, $code)>
721
663f8198 722=item B<alias_method ($method_name, $method)>
723
724This will take a C<$method_name> and CODE reference to that
725C<$method> and alias the method into the class's package.
726
727B<NOTE>:
728Unlike C<add_method>, this will B<not> try to name the
729C<$method> using B<Sub::Name>, it only aliases the method in
730the class's package.
731
552e3d24 732=item B<has_method ($method_name)>
733
a2e85e6c 734This just provides a simple way to check if the class implements
552e3d24 735a specific C<$method_name>. It will I<not> however, attempt to check
a2e85e6c 736if the class inherits the method (use C<UNIVERSAL::can> for that).
552e3d24 737
738This will correctly handle functions defined outside of the package
739that use a fully qualified name (C<sub Package::name { ... }>).
740
741This will correctly handle functions renamed with B<Sub::Name> and
742installed using the symbol tables. However, if you are naming the
743subroutine outside of the package scope, you must use the fully
744qualified name, including the package name, for C<has_method> to
745correctly identify it.
746
747This will attempt to correctly ignore functions imported from other
748packages using B<Exporter>. It breaks down if the function imported
749is an C<__ANON__> sub (such as with C<use constant>), which very well
750may be a valid method being applied to the class.
751
752In short, this method cannot always be trusted to determine if the
753C<$method_name> is actually a method. However, it will DWIM about
a2e85e6c 75490% of the time, so it's a small trade off I think.
552e3d24 755
756=item B<get_method ($method_name)>
757
758This will return a CODE reference of the specified C<$method_name>,
759or return undef if that method does not exist.
760
761=item B<remove_method ($method_name)>
762
a2e85e6c 763This will attempt to remove a given C<$method_name> from the class.
552e3d24 764It will return the CODE reference that it has removed, and will
765attempt to use B<Sub::Name> to clear the methods associated name.
766
767=item B<get_method_list>
768
769This will return a list of method names for all I<locally> defined
770methods. It does B<not> provide a list of all applicable methods,
771including any inherited ones. If you want a list of all applicable
772methods, use the C<compute_all_applicable_methods> method.
773
774=item B<compute_all_applicable_methods>
775
a2e85e6c 776This will return a list of all the methods names this class will
777respond to, taking into account inheritance. The list will be a list of
552e3d24 778HASH references, each one containing the following information; method
779name, the name of the class in which the method lives and a CODE
780reference for the actual method.
781
782=item B<find_all_methods_by_name ($method_name)>
783
784This will traverse the inheritence hierarchy and locate all methods
785with a given C<$method_name>. Similar to
786C<compute_all_applicable_methods> it returns a list of HASH references
787with the following information; method name (which will always be the
788same as C<$method_name>), the name of the class in which the method
789lives and a CODE reference for the actual method.
790
791The list of methods produced is a distinct list, meaning there are no
792duplicates in it. This is especially useful for things like object
793initialization and destruction where you only want the method called
794once, and in the correct order.
795
796=back
797
798=head2 Attributes
799
800It should be noted that since there is no one consistent way to define
801the attributes of a class in Perl 5. These methods can only work with
802the information given, and can not easily discover information on
a2e85e6c 803their own. See L<Class::MOP::Attribute> for more details.
552e3d24 804
805=over 4
806
2e41896e 807=item B<attribute_metaclass>
808
7b31baf4 809=item B<get_attribute_map>
810
552e3d24 811=item B<add_attribute ($attribute_name, $attribute_meta_object)>
812
a2e85e6c 813This stores a C<$attribute_meta_object> in the B<Class::MOP::Class>
814instance associated with the given class, and associates it with
815the C<$attribute_name>. Unlike methods, attributes within the MOP
816are stored as meta-information only. They will be used later to
817construct instances from (see C<construct_instance> above).
552e3d24 818More details about the attribute meta-objects can be found in the
a2e85e6c 819L<Class::MOP::Attribute> or the L<Class::MOP/The Attribute protocol>
820section.
821
822It should be noted that any accessor, reader/writer or predicate
823methods which the C<$attribute_meta_object> has will be installed
824into the class at this time.
552e3d24 825
826=item B<has_attribute ($attribute_name)>
827
a2e85e6c 828Checks to see if this class has an attribute by the name of
552e3d24 829C<$attribute_name> and returns a boolean.
830
831=item B<get_attribute ($attribute_name)>
832
833Returns the attribute meta-object associated with C<$attribute_name>,
834if none is found, it will return undef.
835
836=item B<remove_attribute ($attribute_name)>
837
838This will remove the attribute meta-object stored at
839C<$attribute_name>, then return the removed attribute meta-object.
840
a2e85e6c 841B<NOTE:>
842Removing an attribute will only affect future instances of
552e3d24 843the class, it will not make any attempt to remove the attribute from
844any existing instances of the class.
845
a2e85e6c 846It should be noted that any accessor, reader/writer or predicate
847methods which the attribute meta-object stored at C<$attribute_name>
848has will be removed from the class at this time. This B<will> make
849these attributes somewhat inaccessable in previously created
850instances. But if you are crazy enough to do this at runtime, then
851you are crazy enough to deal with something like this :).
852
552e3d24 853=item B<get_attribute_list>
854
855This returns a list of attribute names which are defined in the local
856class. If you want a list of all applicable attributes for a class,
857use the C<compute_all_applicable_attributes> method.
858
859=item B<compute_all_applicable_attributes>
860
c9e77dbb 861This will traverse the inheritance heirachy and return a list of all
862the applicable attributes for this class. It does not construct a
863HASH reference like C<compute_all_applicable_methods> because all
864that same information is discoverable through the attribute
865meta-object itself.
552e3d24 866
867=back
868
52e8a34c 869=head2 Package Variables
870
871Since Perl's classes are built atop the Perl package system, it is
872fairly common to use package scoped variables for things like static
873class variables. The following methods are convience methods for
874the creation and inspection of package scoped variables.
875
876=over 4
877
878=item B<add_package_variable ($variable_name, ?$initial_value)>
879
880Given a C<$variable_name>, which must contain a leading sigil, this
881method will create that variable within the package which houses the
882class. It also takes an optional C<$initial_value>, which must be a
883reference of the same type as the sigil of the C<$variable_name>
884implies.
885
886=item B<get_package_variable ($variable_name)>
887
888This will return a reference to the package variable in
889C<$variable_name>.
890
891=item B<has_package_variable ($variable_name)>
892
893Returns true (C<1>) if there is a package variable defined for
894C<$variable_name>, and false (C<0>) otherwise.
895
896=item B<remove_package_variable ($variable_name)>
897
898This will attempt to remove the package variable at C<$variable_name>.
899
900=back
901
8b978dd5 902=head1 AUTHOR
903
a2e85e6c 904Stevan Little E<lt>stevan@iinteractive.comE<gt>
8b978dd5 905
906=head1 COPYRIGHT AND LICENSE
907
908Copyright 2006 by Infinity Interactive, Inc.
909
910L<http://www.iinteractive.com>
911
912This library is free software; you can redistribute it and/or modify
913it under the same terms as Perl itself.
914
915=cut