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