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