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)
  36         || confess "You must provide a name for the attribute";
  37
  38     $options{init_arg} = $name
  39         if not exists $options{init_arg};
  40     if(exists $options{builder}){
  41         confess("builder must be a defined scalar value which is a method name")
  42             if ref $options{builder} || !(defined $options{builder});
  43         confess("Setting both default and builder is not allowed.")
  44             if exists $options{default};
  45     } else {
  46         (is_default_a_coderef(\%options))
  47             || confess("References are not allowed as default values, you must ".
  48                        "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
  49                 if exists $options{default} && ref $options{default};
  50     }
  51     if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) {
  52         confess("A required attribute must have either 'init_arg', 'builder', or 'default'");
  53     }
  54
  55     $class->_new(\%options);
  56 }
  57
  58 sub _new {
  59     my $class = shift;
  60
  61     return Class::MOP::Class->initialize($class)->new_object(@_)
  62         if $class ne __PACKAGE__;
  63
  64     my $options = @_ == 1 ? $_[0] : {@_};
  65
  66     bless {
  67         'name'               => $options->{name},
  68         'accessor'           => $options->{accessor},
  69         'reader'             => $options->{reader},
  70         'writer'             => $options->{writer},
  71         'predicate'          => $options->{predicate},
  72         'clearer'            => $options->{clearer},
  73         'builder'            => $options->{builder},
  74         'init_arg'           => $options->{init_arg},
  75         'default'            => $options->{default},
  76         'initializer'        => $options->{initializer},
  77         'definition_context' => $options->{definition_context},
  78         # keep a weakened link to the
  79         # class we are associated with
  80         'associated_class' => undef,
  81         # and a list of the methods
  82         # associated with this attr
  83         'associated_methods' => [],
  84         # this let's us keep track of
  85         # our order inside the associated
  86         # class
  87         'insertion_order'    => undef,
  88     }, $class;
  89 }
  90
  91 # NOTE:
  92 # this is a primative (and kludgy) clone operation
  93 # for now, it will be replaced in the Class::MOP
  94 # bootstrap with a proper one, however we know
  95 # that this one will work fine for now.
  96 sub clone {
  97     my $self    = shift;
  98     my %options = @_;
  99     (blessed($self))
 100         || confess "Can only clone an instance";
 101     return bless { %{$self}, %options } => ref($self);
 102 }
 103
 104 sub initialize_instance_slot {
 105     my ($self, $meta_instance, $instance, $params) = @_;
 106     my $init_arg = $self->{'init_arg'};
 107
 108     # try to fetch the init arg from the %params ...
 109
 110     # if nothing was in the %params, we can use the
 111     # attribute's default value (if it has one)
 112     if(defined $init_arg and exists $params->{$init_arg}){
 113         $self->_set_initial_slot_value(
 114             $meta_instance,
 115             $instance,
 116             $params->{$init_arg},
 117         );
 118     }
 119     elsif (defined $self->{'default'}) {
 120         $self->_set_initial_slot_value(
 121             $meta_instance,
 122             $instance,
 123             $self->default($instance),
 124         );
 125     }
 126     elsif (defined( my $builder = $self->{'builder'})) {
 127         if ($builder = $instance->can($builder)) {
 128             $self->_set_initial_slot_value(
 129                 $meta_instance,
 130                 $instance,
 131                 $instance->$builder,
 132             );
 133         }
 134         else {
 135             confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
 136         }
 137     }
 138 }
 139
 140 sub _set_initial_slot_value {
 141     my ($self, $meta_instance, $instance, $value) = @_;
 142
 143     my $slot_name = $self->name;
 144
 145     return $meta_instance->set_slot_value($instance, $slot_name, $value)
 146         unless $self->has_initializer;
 147
 148     my $callback = sub {
 149         $meta_instance->set_slot_value($instance, $slot_name, $_[0]);
 150     };
 151
 152     my $initializer = $self->initializer;
 153
 154     # most things will just want to set a value, so make it first arg
 155     $instance->$initializer($value, $callback, $self);
 156 }
 157
 158 # NOTE:
 159 # the next bunch of methods will get bootstrapped
 160 # away in the Class::MOP bootstrapping section
 161
 162 sub associated_class   { $_[0]->{'associated_class'}   }
 163 sub associated_methods { $_[0]->{'associated_methods'} }
 164
 165 sub has_accessor    { defined($_[0]->{'accessor'}) }
 166 sub has_reader      { defined($_[0]->{'reader'}) }
 167 sub has_writer      { defined($_[0]->{'writer'}) }
 168 sub has_predicate   { defined($_[0]->{'predicate'}) }
 169 sub has_clearer     { defined($_[0]->{'clearer'}) }
 170 sub has_builder     { defined($_[0]->{'builder'}) }
 171 sub has_init_arg    { defined($_[0]->{'init_arg'}) }
 172 sub has_default     { defined($_[0]->{'default'}) }
 173 sub has_initializer { defined($_[0]->{'initializer'}) }
 174 sub has_insertion_order { defined($_[0]->{'insertion_order'}) }
 175
 176 sub accessor           { $_[0]->{'accessor'}    }
 177 sub reader             { $_[0]->{'reader'}      }
 178 sub writer             { $_[0]->{'writer'}      }
 179 sub predicate          { $_[0]->{'predicate'}   }
 180 sub clearer            { $_[0]->{'clearer'}     }
 181 sub builder            { $_[0]->{'builder'}     }
 182 sub init_arg           { $_[0]->{'init_arg'}    }
 183 sub initializer        { $_[0]->{'initializer'} }
 184 sub definition_context { $_[0]->{'definition_context'} }
 185 sub insertion_order    { $_[0]->{'insertion_order'} }
 186 sub _set_insertion_order { $_[0]->{'insertion_order'} = $_[1] }
 187
 188 # end bootstrapped away method section.
 189 # (all methods below here are kept intact)
 190
 191 sub has_read_method  { $_[0]->has_reader || $_[0]->has_accessor }
 192 sub has_write_method { $_[0]->has_writer || $_[0]->has_accessor }
 193
 194 sub get_read_method  {
 195     my $self   = shift;
 196     my $reader = $self->reader || $self->accessor;
 197     # normal case ...
 198     return $reader unless ref $reader;
 199     # the HASH ref case
 200     my ($name) = %$reader;
 201     return $name;
 202 }
 203
 204 sub get_write_method {
 205     my $self   = shift;
 206     my $writer = $self->writer || $self->accessor;
 207     # normal case ...
 208     return $writer unless ref $writer;
 209     # the HASH ref case
 210     my ($name) = %$writer;
 211     return $name;
 212 }
 213
 214 sub get_read_method_ref {
 215     my $self = shift;
 216     if ((my $reader = $self->get_read_method) && $self->associated_class) {
 217         return $self->associated_class->get_method($reader);
 218     }
 219     else {
 220         my $code = sub { $self->get_value(@_) };
 221         if (my $class = $self->associated_class) {
 222             return $class->method_metaclass->wrap(
 223                 $code,
 224                 package_name => $class->name,
 225                 name         => '__ANON__'
 226             );
 227         }
 228         else {
 229             return $code;
 230         }
 231     }
 232 }
 233
 234 sub get_write_method_ref {
 235     my $self = shift;
 236     if ((my $writer = $self->get_write_method) && $self->associated_class) {
 237         return $self->associated_class->get_method($writer);
 238     }
 239     else {
 240         my $code = sub { $self->set_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 is_default_a_coderef {
 255     my ($value) = $_[0]->{'default'};
 256     return unless ref($value);
 257     return ref($value) eq 'CODE' || (blessed($value) && $value->isa('Class::MOP::Method'));
 258 }
 259
 260 sub default {
 261     my ($self, $instance) = @_;
 262     if (defined $instance && $self->is_default_a_coderef) {
 263         # if the default is a CODE ref, then
 264         # we pass in the instance and default
 265         # can return a value based on that
 266         # instance. Somewhat crude, but works.
 267         return $self->{'default'}->($instance);
 268     }
 269     $self->{'default'};
 270 }
 271
 272 # slots
 273
 274 sub slots { (shift)->name }
 275
 276 # class association
 277
 278 sub attach_to_class {
 279     my ($self, $class) = @_;
 280     (blessed($class) && $class->isa('Class::MOP::Class'))
 281         || confess "You must pass a Class::MOP::Class instance (or a subclass)";
 282     weaken($self->{'associated_class'} = $class);
 283 }
 284
 285 sub detach_from_class {
 286     my $self = shift;
 287     $self->{'associated_class'} = undef;
 288 }
 289
 290 # method association
 291
 292 sub associate_method {
 293     my ($self, $method) = @_;
 294     push @{$self->{'associated_methods'}} => $method;
 295 }
 296
 297 ## Slot management
 298
 299 sub set_initial_value {
 300     my ($self, $instance, $value) = @_;
 301     $self->_set_initial_slot_value(
 302         Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
 303         $instance,
 304         $value
 305     );
 306 }
 307
 308 sub set_value {
 309     my ($self, $instance, $value) = @_;
 310
 311     Class::MOP::Class->initialize(ref($instance))
 312                      ->get_meta_instance
 313                      ->set_slot_value($instance, $self->name, $value);
 314 }
 315
 316 sub get_value {
 317     my ($self, $instance) = @_;
 318
 319     Class::MOP::Class->initialize(ref($instance))
 320                      ->get_meta_instance
 321                      ->get_slot_value($instance, $self->name);
 322 }
 323
 324 sub has_value {
 325     my ($self, $instance) = @_;
 326
 327     Class::MOP::Class->initialize(ref($instance))
 328                      ->get_meta_instance
 329                      ->is_slot_initialized($instance, $self->name);
 330 }
 331
 332 sub clear_value {
 333     my ($self, $instance) = @_;
 334
 335     Class::MOP::Class->initialize(ref($instance))
 336                      ->get_meta_instance
 337                      ->deinitialize_slot($instance, $self->name);
 338 }
 339
 340 ## load em up ...
 341
 342 sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
 343
 344 sub process_accessors {
 345     Carp::cluck('The process_accessors method has been made private.'
 346         . " The public version is deprecated and will be removed in a future release.\n");
 347     shift->_process_accessors(@_);
 348 }
 349
 350 sub _process_accessors {
 351     my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
 352
 353     my $method_ctx;
 354
 355     if ( my $ctx = $self->definition_context ) {
 356         $method_ctx = { %$ctx };
 357     }
 358
 359     if (ref($accessor)) {
 360         (ref($accessor) eq 'HASH')
 361             || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
 362         my ($name, $method) = %{$accessor};
 363         $method = $self->accessor_metaclass->wrap(
 364             $method,
 365             package_name => $self->associated_class->name,
 366             name         => $name,
 367             definition_context => $method_ctx,
 368         );
 369         $self->associate_method($method);
 370         return ($name, $method);
 371     }
 372     else {
 373         my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
 374         my $method;
 375         eval {
 376             if ( $method_ctx ) {
 377                 my $desc = "accessor $accessor";
 378                 if ( $accessor ne $self->name ) {
 379                     $desc .= " of attribute " . $self->name;
 380                 }
 381
 382                 $method_ctx->{description} = $desc;
 383             }
 384
 385             $method = $self->accessor_metaclass->new(
 386                 attribute     => $self,
 387                 is_inline     => $inline_me,
 388                 accessor_type => $type,
 389                 package_name  => $self->associated_class->name,
 390                 name          => $accessor,
 391                 definition_context => $method_ctx,
 392             );
 393         };
 394         confess "Could not create the '$type' method for " . $self->name . " because : $@" if $@;
 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 ( $instance, $value, $set ) = @_;
 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_initial_value($instance, $value) >>
 837
 838 Sets the value without going through the accessor. This method is only
 839 called when the instance is first being initialized.
 840
 841 =item B<< $attr->get_value($instance) >>
 842
 843 Returns the value without going through the accessor. Note that this
 844 works even with write-only accessors.
 845
 846 =item B<< $attr->has_value($instance) >>
 847
 848 Return a boolean indicating whether the attribute has been set in
 849 C<$instance>. This how the default C<predicate> method works.
 850
 851 =item B<< $attr->clear_value($instance) >>
 852
 853 This will clear the attribute's value in C<$instance>. This is what
 854 the default C<clearer> calls.
 855
 856 Note that this works even if the attribute does not have any
 857 associated read, write or clear methods.
 858
 859 =back
 860
 861 =head2 Class association
 862
 863 These methods allow you to manage the attributes association with
 864 the class that contains it. These methods should not be used
 865 lightly, nor are they very magical, they are mostly used internally
 866 and by metaclass instances.
 867
 868 =over 4
 869
 870 =item B<< $attr->associated_class >>
 871
 872 This returns the C<Class::MOP::Class> with which this attribute is
 873 associated, if any.
 874
 875 =item B<< $attr->attach_to_class($metaclass) >>
 876
 877 This method stores a weakened reference to the C<$metaclass> object
 878 internally.
 879
 880 This method does not remove the attribute from its old class,
 881 nor does it create any accessors in the new class.
 882
 883 It is probably best to use the L<Class::MOP::Class> C<add_attribute>
 884 method instead.
 885
 886 =item B<< $attr->detach_from_class >>
 887
 888 This method removes the associate metaclass object from the attribute
 889 it has one.
 890
 891 This method does not remove the attribute itself from the class, or
 892 remove its accessors.
 893
 894 It is probably best to use the L<Class::MOP::Class>
 895 C<remove_attribute> method instead.
 896
 897 =back
 898
 899 =head2 Attribute Accessor generation
 900
 901 =over 4
 902
 903 =item B<< $attr->accessor_metaclass >>
 904
 905 Accessor methods are generated using an accessor metaclass. By
 906 default, this is L<Class::MOP::Method::Accessor>. This method returns
 907 the name of the accessor metaclass that this attribute uses.
 908
 909 =item B<< $attr->associate_method($method) >>
 910
 911 This associates a L<Class::MOP::Method> object with the
 912 attribute. Typically, this is called internally when an attribute
 913 generates its accessors.
 914
 915 =item B<< $attr->associated_methods >>
 916
 917 This returns the list of methods which have been associated with the
 918 attribute.
 919
 920 =item B<< $attr->install_accessors >>
 921
 922 This method generates and installs code the attributes various
 923 accessors. It is typically called from the L<Class::MOP::Class>
 924 C<add_attribute> method.
 925
 926 =item B<< $attr->remove_accessors >>
 927
 928 This method removes all of the accessors associated with the
 929 attribute.
 930
 931 This does not currently remove methods from the list returned by
 932 C<associated_methods>.
 933
 934 =back
 935
 936 =head2 Introspection
 937
 938 =over 4
 939
 940 =item B<< Class::MOP::Attribute->meta >>
 941
 942 This will return a L<Class::MOP::Class> instance for this class.
 943
 944 It should also be noted that L<Class::MOP> will actually bootstrap
 945 this module by installing a number of attribute meta-objects into its
 946 metaclass.
 947
 948 =back
 949
 950 =head1 AUTHORS
 951
 952 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 953
 954 =head1 COPYRIGHT AND LICENSE
 955
 956 Copyright 2006-2009 by Infinity Interactive, Inc.
 957
 958 L<http://www.iinteractive.com>
 959
 960 This library is free software; you can redistribute it and/or modify
 961 it under the same terms as Perl itself.
 962
 963 =cut
 964
 965