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