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