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