Merge branch 'master' of gitmo@git.moose.perl.org:Class-MOP
[gitmo/Class-MOP.git] / lib / Class / MOP / Attribute.pm
1
2 package Class::MOP::Attribute;
3
4 use strict;
5 use warnings;
6
7 use Class::MOP::Method::Accessor;
8
9 use Carp         'confess';
10 use Scalar::Util 'blessed', 'weaken';
11
12 our $VERSION   = '0.89';
13 $VERSION = eval $VERSION;
14 our $AUTHORITY = 'cpan:STEVAN';
15
16 use base 'Class::MOP::Object';
17
18 # NOTE: (meta-circularity)
19 # This method will be replaced in the
20 # boostrap section of Class::MOP, by
21 # a new version which uses the
22 # &Class::MOP::Class::construct_instance
23 # method to build an attribute meta-object
24 # which itself is described with attribute
25 # meta-objects.
26 #     - Ain't meta-circularity grand? :)
27 sub new {
28     my ( $class, @args ) = @_;
29
30     unshift @args, "name" if @args % 2 == 1;
31     my %options = @args;
32
33     my $name = $options{name};
34
35     (defined $name && $name)
36         || confess "You must provide a name for the attribute";
37
38     $options{init_arg} = $name
39         if not exists $options{init_arg};
40     if(exists $options{builder}){
41         confess("builder must be a defined scalar value which is a method name")
42             if ref $options{builder} || !(defined $options{builder});
43         confess("Setting both default and builder is not allowed.")
44             if exists $options{default};
45     } else {
46         (is_default_a_coderef(\%options))
47             || confess("References are not allowed as default values, you must ".
48                        "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
49                 if exists $options{default} && ref $options{default};
50     }
51     if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) {
52         confess("A required attribute must have either 'init_arg', 'builder', or 'default'");
53     }
54
55     $class->_new(\%options);
56 }
57
58 sub _new {
59     my $class = shift;
60     my $options = @_ == 1 ? $_[0] : {@_};
61
62     bless {
63         'name'               => $options->{name},
64         'accessor'           => $options->{accessor},
65         'reader'             => $options->{reader},
66         'writer'             => $options->{writer},
67         'predicate'          => $options->{predicate},
68         'clearer'            => $options->{clearer},
69         'builder'            => $options->{builder},
70         'init_arg'           => $options->{init_arg},
71         'default'            => $options->{default},
72         'initializer'        => $options->{initializer},
73         'definition_context' => $options->{definition_context},
74         # keep a weakened link to the
75         # class we are associated with
76         'associated_class' => undef,
77         # and a list of the methods
78         # associated with this attr
79         'associated_methods' => [],
80         # this let's us keep track of
81         # our order inside the associated
82         # class
83         'insertion_order'    => undef,
84     }, $class;
85 }
86
87 # NOTE:
88 # this is a primative (and kludgy) clone operation
89 # for now, it will be replaced in the Class::MOP
90 # bootstrap with a proper one, however we know
91 # that this one will work fine for now.
92 sub clone {
93     my $self    = shift;
94     my %options = @_;
95     (blessed($self))
96         || confess "Can only clone an instance";
97     return bless { %{$self}, %options } => ref($self);
98 }
99
100 sub initialize_instance_slot {
101     my ($self, $meta_instance, $instance, $params) = @_;
102     my $init_arg = $self->{'init_arg'};
103
104     # try to fetch the init arg from the %params ...
105
106     # if nothing was in the %params, we can use the
107     # attribute's default value (if it has one)
108     if(defined $init_arg and exists $params->{$init_arg}){
109         $self->_set_initial_slot_value(
110             $meta_instance, 
111             $instance,
112             $params->{$init_arg},
113         );
114     } 
115     elsif (defined $self->{'default'}) {
116         $self->_set_initial_slot_value(
117             $meta_instance, 
118             $instance,
119             $self->default($instance),
120         );
121     } 
122     elsif (defined( my $builder = $self->{'builder'})) {
123         if ($builder = $instance->can($builder)) {
124             $self->_set_initial_slot_value(
125                 $meta_instance, 
126                 $instance,
127                 $instance->$builder,
128             );
129         } 
130         else {
131             confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
132         }
133     }
134 }
135
136 sub _set_initial_slot_value {
137     my ($self, $meta_instance, $instance, $value) = @_;
138
139     my $slot_name = $self->name;
140
141     return $meta_instance->set_slot_value($instance, $slot_name, $value)
142         unless $self->has_initializer;
143
144     my $callback = sub {
145         $meta_instance->set_slot_value($instance, $slot_name, $_[0]);
146     };
147     
148     my $initializer = $self->initializer;
149
150     # most things will just want to set a value, so make it first arg
151     $instance->$initializer($value, $callback, $self);
152 }
153
154 # NOTE:
155 # the next bunch of methods will get bootstrapped
156 # away in the Class::MOP bootstrapping section
157
158 sub associated_class   { $_[0]->{'associated_class'}   }
159 sub associated_methods { $_[0]->{'associated_methods'} }
160
161 sub has_accessor    { defined($_[0]->{'accessor'}) }
162 sub has_reader      { defined($_[0]->{'reader'}) }
163 sub has_writer      { defined($_[0]->{'writer'}) }
164 sub has_predicate   { defined($_[0]->{'predicate'}) }
165 sub has_clearer     { defined($_[0]->{'clearer'}) }
166 sub has_builder     { defined($_[0]->{'builder'}) }
167 sub has_init_arg    { defined($_[0]->{'init_arg'}) }
168 sub has_default     { defined($_[0]->{'default'}) }
169 sub has_initializer { defined($_[0]->{'initializer'}) }
170 sub has_insertion_order { defined($_[0]->{'insertion_order'}) }
171
172 sub accessor           { $_[0]->{'accessor'}    }
173 sub reader             { $_[0]->{'reader'}      }
174 sub writer             { $_[0]->{'writer'}      }
175 sub predicate          { $_[0]->{'predicate'}   }
176 sub clearer            { $_[0]->{'clearer'}     }
177 sub builder            { $_[0]->{'builder'}     }
178 sub init_arg           { $_[0]->{'init_arg'}    }
179 sub initializer        { $_[0]->{'initializer'} }
180 sub definition_context { $_[0]->{'definition_context'} }
181 sub insertion_order    { $_[0]->{'insertion_order'} }
182 sub _set_insertion_order { $_[0]->{'insertion_order'} = $_[1] }
183
184 # end bootstrapped away method section.
185 # (all methods below here are kept intact)
186
187 sub has_read_method  { $_[0]->has_reader || $_[0]->has_accessor }
188 sub has_write_method { $_[0]->has_writer || $_[0]->has_accessor }
189
190 sub get_read_method  { 
191     my $self   = shift;    
192     my $reader = $self->reader || $self->accessor;
193     # normal case ...
194     return $reader unless ref $reader;
195     # the HASH ref case
196     my ($name) = %$reader;
197     return $name;
198 }
199
200 sub get_write_method { 
201     my $self   = shift;
202     my $writer = $self->writer || $self->accessor; 
203     # normal case ...
204     return $writer unless ref $writer;
205     # the HASH ref case
206     my ($name) = %$writer;
207     return $name;    
208 }
209
210 sub get_read_method_ref {
211     my $self = shift;
212     if ((my $reader = $self->get_read_method) && $self->associated_class) {   
213         return $self->associated_class->get_method($reader);
214     }
215     else {
216         my $code = sub { $self->get_value(@_) };
217         if (my $class = $self->associated_class) {
218             return $class->method_metaclass->wrap(
219                 $code,
220                 package_name => $class->name,
221                 name         => '__ANON__'
222             );
223         }
224         else {
225             return $code;
226         }
227     }
228 }
229
230 sub get_write_method_ref {
231     my $self = shift;    
232     if ((my $writer = $self->get_write_method) && $self->associated_class) {         
233         return $self->associated_class->get_method($writer);
234     }
235     else {
236         my $code = sub { $self->set_value(@_) };
237         if (my $class = $self->associated_class) {
238             return $class->method_metaclass->wrap(
239                 $code,
240                 package_name => $class->name,
241                 name         => '__ANON__'
242             );
243         }
244         else {
245             return $code;
246         }
247     }
248 }
249
250 sub is_default_a_coderef {
251     my ($value) = $_[0]->{'default'};
252     return unless ref($value);
253     return ref($value) eq 'CODE' || (blessed($value) && $value->isa('Class::MOP::Method'));
254 }
255
256 sub default {
257     my ($self, $instance) = @_;
258     if (defined $instance && $self->is_default_a_coderef) {
259         # if the default is a CODE ref, then
260         # we pass in the instance and default
261         # can return a value based on that
262         # instance. Somewhat crude, but works.
263         return $self->{'default'}->($instance);
264     }
265     $self->{'default'};
266 }
267
268 # slots
269
270 sub slots { (shift)->name }
271
272 # class association
273
274 sub attach_to_class {
275     my ($self, $class) = @_;
276     (blessed($class) && $class->isa('Class::MOP::Class'))
277         || confess "You must pass a Class::MOP::Class instance (or a subclass)";
278     weaken($self->{'associated_class'} = $class);
279 }
280
281 sub detach_from_class {
282     my $self = shift;
283     $self->{'associated_class'} = undef;
284 }
285
286 # method association
287
288 sub associate_method {
289     my ($self, $method) = @_;
290     push @{$self->{'associated_methods'}} => $method;
291 }
292
293 ## Slot management
294
295 sub set_initial_value {
296     my ($self, $instance, $value) = @_;
297     $self->_set_initial_slot_value(
298         Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
299         $instance,
300         $value
301     );
302 }
303
304 sub set_value {
305     my ($self, $instance, $value) = @_;
306
307     Class::MOP::Class->initialize(ref($instance))
308                      ->get_meta_instance
309                      ->set_slot_value($instance, $self->name, $value);
310 }
311
312 sub get_value {
313     my ($self, $instance) = @_;
314
315     Class::MOP::Class->initialize(ref($instance))
316                      ->get_meta_instance
317                      ->get_slot_value($instance, $self->name);
318 }
319
320 sub has_value {
321     my ($self, $instance) = @_;
322
323     Class::MOP::Class->initialize(ref($instance))
324                      ->get_meta_instance
325                      ->is_slot_initialized($instance, $self->name);
326 }
327
328 sub clear_value {
329     my ($self, $instance) = @_;
330
331     Class::MOP::Class->initialize(ref($instance))
332                      ->get_meta_instance
333                      ->deinitialize_slot($instance, $self->name);
334 }
335
336 ## load em up ...
337
338 sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
339
340 sub process_accessors {
341     Carp::cluck('The process_accessors method has been made private.'
342         . " The public version is deprecated and will be removed in a future release.\n");
343     shift->_process_accessors(@_);
344 }
345
346 sub _process_accessors {
347     my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
348
349     my $method_ctx;
350
351     if ( my $ctx = $self->definition_context ) {
352         $method_ctx = { %$ctx };
353     }
354
355     if (ref($accessor)) {
356         (ref($accessor) eq 'HASH')
357             || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
358         my ($name, $method) = %{$accessor};
359         $method = $self->accessor_metaclass->wrap(
360             $method,
361             package_name => $self->associated_class->name,
362             name         => $name,
363             definition_context => $method_ctx,
364         );
365         $self->associate_method($method);
366         return ($name, $method);
367     }
368     else {
369         my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
370         my $method;
371         eval {
372             if ( $method_ctx ) {
373                 my $desc = "accessor $accessor";
374                 if ( $accessor ne $self->name ) {
375                     $desc .= " of attribute " . $self->name;
376                 }
377
378                 $method_ctx->{description} = $desc;
379             }
380
381             $method = $self->accessor_metaclass->new(
382                 attribute     => $self,
383                 is_inline     => $inline_me,
384                 accessor_type => $type,
385                 package_name  => $self->associated_class->name,
386                 name          => $accessor,
387                 definition_context => $method_ctx,
388             );
389         };
390         confess "Could not create the '$type' method for " . $self->name . " because : $@" if $@;
391         $self->associate_method($method);
392         return ($accessor, $method);
393     }
394 }
395
396 sub install_accessors {
397     my $self   = shift;
398     my $inline = shift;
399     my $class  = $self->associated_class;
400
401     $class->add_method(
402         $self->_process_accessors('accessor' => $self->accessor(), $inline)
403     ) if $self->has_accessor();
404
405     $class->add_method(
406         $self->_process_accessors('reader' => $self->reader(), $inline)
407     ) if $self->has_reader();
408
409     $class->add_method(
410         $self->_process_accessors('writer' => $self->writer(), $inline)
411     ) if $self->has_writer();
412
413     $class->add_method(
414         $self->_process_accessors('predicate' => $self->predicate(), $inline)
415     ) if $self->has_predicate();
416
417     $class->add_method(
418         $self->_process_accessors('clearer' => $self->clearer(), $inline)
419     ) if $self->has_clearer();
420
421     return;
422 }
423
424 {
425     my $_remove_accessor = sub {
426         my ($accessor, $class) = @_;
427         if (ref($accessor) && ref($accessor) eq 'HASH') {
428             ($accessor) = keys %{$accessor};
429         }
430         my $method = $class->get_method($accessor);
431         $class->remove_method($accessor)
432             if (ref($method) && $method->isa('Class::MOP::Method::Accessor'));
433     };
434
435     sub remove_accessors {
436         my $self = shift;
437         # TODO:
438         # we really need to make sure to remove from the
439         # associates methods here as well. But this is
440         # such a slimly used method, I am not worried
441         # about it right now.
442         $_remove_accessor->($self->accessor(),  $self->associated_class()) if $self->has_accessor();
443         $_remove_accessor->($self->reader(),    $self->associated_class()) if $self->has_reader();
444         $_remove_accessor->($self->writer(),    $self->associated_class()) if $self->has_writer();
445         $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate();
446         $_remove_accessor->($self->clearer(),   $self->associated_class()) if $self->has_clearer();
447         return;
448     }
449
450 }
451
452 1;
453
454 __END__
455
456 =pod
457
458 =head1 NAME
459
460 Class::MOP::Attribute - Attribute Meta Object
461
462 =head1 SYNOPSIS
463
464   Class::MOP::Attribute->new(
465       foo => (
466           accessor  => 'foo',           # dual purpose get/set accessor
467           predicate => 'has_foo',       # predicate check for defined-ness
468           init_arg  => '-foo',          # class->new will look for a -foo key
469           default   => 'BAR IS BAZ!'    # if no -foo key is provided, use this
470       )
471   );
472
473   Class::MOP::Attribute->new(
474       bar => (
475           reader    => 'bar',           # getter
476           writer    => 'set_bar',       # setter
477           predicate => 'has_bar',       # predicate check for defined-ness
478           init_arg  => ':bar',          # class->new will look for a :bar key
479                                         # no default value means it is undef
480       )
481   );
482
483 =head1 DESCRIPTION
484
485 The Attribute Protocol is almost entirely an invention of
486 C<Class::MOP>. Perl 5 does not have a consistent notion of
487 attributes. There are so many ways in which this is done, and very few
488 (if any) are easily discoverable by this module.
489
490 With that said, this module attempts to inject some order into this
491 chaos, by introducing a consistent API which can be used to create
492 object attributes.
493
494 =head1 METHODS
495
496 =head2 Creation
497
498 =over 4
499
500 =item B<< Class::MOP::Attribute->new($name, ?%options) >>
501
502 An attribute must (at the very least), have a C<$name>. All other
503 C<%options> are added as key-value pairs.
504
505 =over 8
506
507 =item * init_arg
508
509 This is a string value representing the expected key in an
510 initialization hash. For instance, if we have an C<init_arg> value of
511 C<-foo>, then the following code will Just Work.
512
513   MyClass->meta->new_object( -foo => 'Hello There' );
514
515 If an init_arg is not assigned, it will automatically use the
516 attribute's name. If C<init_arg> is explicitly set to C<undef>, the
517 attribute cannot be specified during initialization.
518
519 =item * builder
520
521 This provides the name of a method that will be called to initialize
522 the attribute. This method will be called on the object after it is
523 constructed. It is expected to return a valid value for the attribute.
524
525 =item * default
526
527 This can be used to provide an explicit default for initializing the
528 attribute. If the default you provide is a subroutine reference, then
529 this reference will be called I<as a method> on the object.
530
531 If the value is a simple scalar (string or number), then it can be
532 just passed as is. However, if you wish to initialize it with a HASH
533 or ARRAY ref, then you need to wrap that inside a subroutine
534 reference:
535
536   Class::MOP::Attribute->new(
537       'foo' => (
538           default => sub { [] },
539       )
540   );
541
542   # or ...
543
544   Class::MOP::Attribute->new(
545       'foo' => (
546           default => sub { {} },
547       )
548   );
549
550 If you wish to initialize an attribute with a subroutine reference
551 itself, then you need to wrap that in a subroutine as well:
552
553   Class::MOP::Attribute->new(
554       'foo' => (
555           default => sub {
556               sub { print "Hello World" }
557           },
558       )
559   );
560
561 And lastly, if the value of your attribute is dependent upon some
562 other aspect of the instance structure, then you can take advantage of
563 the fact that when the C<default> value is called as a method:
564
565   Class::MOP::Attribute->new(
566       'object_identity' => (
567           default => sub { Scalar::Util::refaddr( $_[0] ) },
568       )
569   );
570
571 Note that there is no guarantee that attributes are initialized in any
572 particular order, so you cannot rely on the value of some other
573 attribute when generating the default.
574
575 =item * initializer
576
577 This option can be either a method name or a subroutine
578 reference. This method will be called when setting the attribute's
579 value in the constructor. Unlike C<default> and C<builder>, the
580 initializer is only called when a value is provided to the
581 constructor. The initializer allows you to munge this value during
582 object construction.
583
584 The initializer is called as a method with three arguments. The first
585 is the value that was passed to the constructor. The second is a
586 subroutine reference that can be called to actually set the
587 attribute's value, and the last is the associated
588 C<Class::MOP::Attribute> object.
589
590 This contrived example shows an initializer that sets the attribute to
591 twice the given value.
592
593   Class::MOP::Attribute->new(
594       'doubled' => (
595           initializer => sub {
596               my ( $instance, $value, $set ) = @_;
597               $set->( $value * 2 );
598           },
599       )
600   );
601
602 Since an initializer can be a method name, you can easily make
603 attribute initialization use the writer:
604
605   Class::MOP::Attribute->new(
606       'some_attr' => (
607           writer      => 'some_attr',
608           initializer => 'some_attr',
609       )
610   );
611
612 Your writer will need to examine C<@_> and determine under which
613 context it is being called.
614
615 =back
616
617 The C<accessor>, C<reader>, C<writer>, C<predicate> and C<clearer>
618 options all accept the same parameters. You can provide the name of
619 the method, in which case an appropriate default method will be
620 generated for you. Or instead you can also provide hash reference
621 containing exactly one key (the method name) and one value. The value
622 should be a subroutine reference, which will be installed as the
623 method itself.
624
625 =over 8
626
627 =item * accessor
628
629 An C<accessor> is a standard Perl-style read/write accessor. It will
630 return the value of the attribute, and if a value is passed as an
631 argument, it will assign that value to the attribute.
632
633 Note that C<undef> is a legitimate value, so this will work:
634
635   $object->set_something(undef);
636
637 =item * reader
638
639 This is a basic read-only accessor. It returns the value of the
640 attribute.
641
642 =item * writer
643
644 This is a basic write accessor, it accepts a single argument, and
645 assigns that value to the attribute.
646
647 Note that C<undef> is a legitimate value, so this will work:
648
649   $object->set_something(undef);
650
651 =item * predicate
652
653 The predicate method returns a boolean indicating whether or not the
654 attribute has been explicitly set.
655
656 Note that the predicate returns true even if the attribute was set to
657 a false value (C<0> or C<undef>).
658
659 =item * clearer
660
661 This method will uninitialize the attribute. After an attribute is
662 cleared, its C<predicate> will return false.
663
664 =item * definition_context
665
666 Mostly, this exists as a hook for the benefit of Moose.
667
668 This option should be a hash reference containing several keys which
669 will be used when inlining the attribute's accessors. The keys should
670 include C<line>, the line number where the attribute was created, and
671 either C<file> or C<description>.
672
673 This information will ultimately be used when eval'ing inlined
674 accessor code so that error messages report a useful line and file
675 name.
676
677 =back
678
679 =item B<< $attr->clone(%options) >>
680
681 This clones the attribute. Any options you provide will override the
682 settings of the original attribute. You can change the name of the new
683 attribute by passing a C<name> key in C<%options>.
684
685 =back
686
687 =head2 Informational
688
689 These are all basic read-only accessors for the values passed into
690 the constructor.
691
692 =over 4
693
694 =item B<< $attr->name >>
695
696 Returns the attribute's name.
697
698 =item B<< $attr->accessor >>
699
700 =item B<< $attr->reader >>
701
702 =item B<< $attr->writer >>
703
704 =item B<< $attr->predicate >>
705
706 =item B<< $attr->clearer >>
707
708 The C<accessor>, C<reader>, C<writer>, C<predicate>, and C<clearer>
709 methods all return exactly what was passed to the constructor, so it
710 can be either a string containing a method name, or a hash reference.
711
712 =item B<< $attr->initializer >>
713
714 Returns the initializer as passed to the constructor, so this may be
715 either a method name or a subroutine reference.
716
717 =item B<< $attr->init_arg >>
718
719 =item B<< $attr->is_default_a_coderef >>
720
721 =item B<< $attr->default($instance) >>
722
723 The C<$instance> argument is optional. If you don't pass it, the
724 return value for this method is exactly what was passed to the
725 constructor, either a simple scalar or a subroutine reference.
726
727 If you I<do> pass an C<$instance> and the default is a subroutine
728 reference, then the reference is called as a method on the
729 C<$instance> and the generated value is returned.
730
731 =item B<< $attr->slots >>
732
733 Return a list of slots required by the attribute. This is usually just
734 one, the name of the attribute.
735
736 A slot is the name of the hash key used to store the attribute in an
737 object instance.
738
739 =item B<< $attr->get_read_method >>
740
741 =item B<< $attr->get_write_method >>
742
743 Returns the name of a method suitable for reading or writing the value
744 of the attribute in the associated class.
745
746 If an attribute is read- or write-only, then these methods can return
747 C<undef> as appropriate.
748
749 =item B<< $attr->has_read_method >>
750
751 =item B<< $attr->has_write_method >>
752
753 This returns a boolean indicating whether the attribute has a I<named>
754 read or write method.
755
756 =item B<< $attr->get_read_method_ref >>
757
758 =item B<< $attr->get_write_method_ref >>
759
760 Returns the subroutine reference of a method suitable for reading or
761 writing the attribute's value in the associated class. These methods
762 always return a subroutine reference, regardless of whether or not the
763 attribute is read- or write-only.
764
765 =item B<< $attr->insertion_order >>
766
767 If this attribute has been inserted into a class, this returns a zero
768 based index regarding the order of insertion.
769
770 =back
771
772 =head2 Informational predicates
773
774 These are all basic predicate methods for the values passed into C<new>.
775
776 =over 4
777
778 =item B<< $attr->has_accessor >>
779
780 =item B<< $attr->has_reader >>
781
782 =item B<< $attr->has_writer >>
783
784 =item B<< $attr->has_predicate >>
785
786 =item B<< $attr->has_clearer >>
787
788 =item B<< $attr->has_initializer >>
789
790 =item B<< $attr->has_init_arg >>
791
792 This will be I<false> if the C<init_arg> was set to C<undef>.
793
794 =item B<< $attr->has_default >>
795
796 This will be I<false> if the C<default> was set to C<undef>, since
797 C<undef> is the default C<default> anyway.
798
799 =item B<< $attr->has_builder >>
800
801 =item B<< $attr->has_insertion_order >>
802
803 This will be I<false> if this attribute has not be inserted into a class
804
805 =back
806
807 =head2 Value management
808
809 These methods are basically "back doors" to the instance, and can be
810 used to bypass the regular accessors, but still stay within the MOP.
811
812 These methods are not for general use, and should only be used if you
813 really know what you are doing.
814
815 =over 4
816
817 =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >>
818
819 This method is used internally to initialize the attribute's slot in
820 the object C<$instance>.
821
822 The C<$params> is a hash reference of the values passed to the object
823 constructor.
824
825 It's unlikely that you'll need to call this method yourself.
826
827 =item B<< $attr->set_value($instance, $value) >>
828
829 Sets the value without going through the accessor. Note that this
830 works even with read-only attributes.
831
832 =item B<< $attr->set_initial_value($instance, $value) >>
833
834 Sets the value without going through the accessor. This method is only
835 called when the instance is first being initialized.
836
837 =item B<< $attr->get_value($instance) >>
838
839 Returns the value without going through the accessor. Note that this
840 works even with write-only accessors.
841
842 =item B<< $attr->has_value($instance) >>
843
844 Return a boolean indicating whether the attribute has been set in
845 C<$instance>. This how the default C<predicate> method works.
846
847 =item B<< $attr->clear_value($instance) >>
848
849 This will clear the attribute's value in C<$instance>. This is what
850 the default C<clearer> calls.
851
852 Note that this works even if the attribute does not have any
853 associated read, write or clear methods.
854
855 =back
856
857 =head2 Class association
858
859 These methods allow you to manage the attributes association with
860 the class that contains it. These methods should not be used
861 lightly, nor are they very magical, they are mostly used internally
862 and by metaclass instances.
863
864 =over 4
865
866 =item B<< $attr->associated_class >>
867
868 This returns the C<Class::MOP::Class> with which this attribute is
869 associated, if any.
870
871 =item B<< $attr->attach_to_class($metaclass) >>
872
873 This method stores a weakened reference to the C<$metaclass> object
874 internally.
875
876 This method does not remove the attribute from its old class,
877 nor does it create any accessors in the new class.
878
879 It is probably best to use the L<Class::MOP::Class> C<add_attribute>
880 method instead.
881
882 =item B<< $attr->detach_from_class >>
883
884 This method removes the associate metaclass object from the attribute
885 it has one.
886
887 This method does not remove the attribute itself from the class, or
888 remove its accessors.
889
890 It is probably best to use the L<Class::MOP::Class>
891 C<remove_attribute> method instead.
892
893 =back
894
895 =head2 Attribute Accessor generation
896
897 =over 4
898
899 =item B<< $attr->accessor_metaclass >>
900
901 Accessor methods are generated using an accessor metaclass. By
902 default, this is L<Class::MOP::Method::Accessor>. This method returns
903 the name of the accessor metaclass that this attribute uses.
904
905 =item B<< $attr->associate_method($method) >>
906
907 This associates a L<Class::MOP::Method> object with the
908 attribute. Typically, this is called internally when an attribute
909 generates its accessors.
910
911 =item B<< $attr->associated_methods >>
912
913 This returns the list of methods which have been associated with the
914 attribute.
915
916 =item B<< $attr->install_accessors >>
917
918 This method generates and installs code the attributes various
919 accessors. It is typically called from the L<Class::MOP::Class>
920 C<add_attribute> method.
921
922 =item B<< $attr->remove_accessors >>
923
924 This method removes all of the accessors associated with the
925 attribute.
926
927 This does not currently remove methods from the list returned by
928 C<associated_methods>.
929
930 =back
931
932 =head2 Introspection
933
934 =over 4
935
936 =item B<< Class::MOP::Attribute->meta >>
937
938 This will return a L<Class::MOP::Class> instance for this class.
939
940 It should also be noted that L<Class::MOP> will actually bootstrap
941 this module by installing a number of attribute meta-objects into its
942 metaclass.
943
944 =back
945
946 =head1 AUTHORS
947
948 Stevan Little E<lt>stevan@iinteractive.comE<gt>
949
950 =head1 COPYRIGHT AND LICENSE
951
952 Copyright 2006-2009 by Infinity Interactive, Inc.
953
954 L<http://www.iinteractive.com>
955
956 This library is free software; you can redistribute it and/or modify
957 it under the same terms as Perl itself.
958
959 =cut
960
961