lib/Class/MOP/Attribute.pm

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