refactor load_first_existing_class
[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';
a8344505 11use Try::Tiny;
2eb717d5 12
f6ca0704 13our $VERSION = '0.94';
d519662a 14$VERSION = eval $VERSION;
f0480c45 15our $AUTHORITY = 'cpan:STEVAN';
8b978dd5 16
b1897d4d 17use base 'Class::MOP::Object';
18
727919c5 19# NOTE: (meta-circularity)
1d68af04 20# This method will be replaced in the
21# boostrap section of Class::MOP, by
22# a new version which uses the
727919c5 23# &Class::MOP::Class::construct_instance
24# method to build an attribute meta-object
25# which itself is described with attribute
1d68af04 26# meta-objects.
727919c5 27# - Ain't meta-circularity grand? :)
8b978dd5 28sub new {
649efb63 29 my ( $class, @args ) = @_;
30
31 unshift @args, "name" if @args % 2 == 1;
32 my %options = @args;
33
34 my $name = $options{name};
1d68af04 35
d9330488 36 (defined $name)
8b978dd5 37 || confess "You must provide a name for the attribute";
1d68af04 38
39 $options{init_arg} = $name
5659d76e 40 if not exists $options{init_arg};
1d68af04 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};
8fe581e5 46 } else {
47 (is_default_a_coderef(\%options))
48 || confess("References are not allowed as default values, you must ".
3c0a8087 49 "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
8fe581e5 50 if exists $options{default} && ref $options{default};
1d68af04 51 }
2e877f58 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 }
8683db0e 55
cb75020f 56 $class->_new(\%options);
4b698b1a 57}
58
59sub _new {
0bfc85b8 60 my $class = shift;
ec9e38e5 61
62 return Class::MOP::Class->initialize($class)->new_object(@_)
812d58f9 63 if $class ne __PACKAGE__;
ec9e38e5 64
0bfc85b8 65 my $options = @_ == 1 ? $_[0] : {@_};
4b698b1a 66
8b978dd5 67 bless {
d9d99689 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},
1d68af04 79 # keep a weakened link to the
9ec169fe 80 # class we are associated with
8683db0e 81 'associated_class' => undef,
1d68af04 82 # and a list of the methods
3545c727 83 # associated with this attr
8683db0e 84 'associated_methods' => [],
dc9d420c 85 # this let's us keep track of
86 # our order inside the associated
87 # class
88 'insertion_order' => undef,
0bfc85b8 89 }, $class;
8b978dd5 90}
91
7b31baf4 92# NOTE:
1d68af04 93# this is a primative (and kludgy) clone operation
16e960bd 94# for now, it will be replaced in the Class::MOP
1d68af04 95# bootstrap with a proper one, however we know
5659d76e 96# that this one will work fine for now.
97sub clone {
98 my $self = shift;
99 my %options = @_;
100 (blessed($self))
101 || confess "Can only clone an instance";
b3fa93c7 102 return bless { %{$self}, %options } => ref($self);
5659d76e 103}
104
bd4e03f9 105sub initialize_instance_slot {
f892c0f0 106 my ($self, $meta_instance, $instance, $params) = @_;
8683db0e 107 my $init_arg = $self->{'init_arg'};
108
bd4e03f9 109 # try to fetch the init arg from the %params ...
8d2d4c67 110
1d68af04 111 # if nothing was in the %params, we can use the
bd4e03f9 112 # attribute's default value (if it has one)
2e877f58 113 if(defined $init_arg and exists $params->{$init_arg}){
8ee74136 114 $self->_set_initial_slot_value(
115 $meta_instance,
0ab65f99 116 $instance,
0ab65f99 117 $params->{$init_arg},
0ab65f99 118 );
b7bdffc3 119 }
8683db0e 120 elsif (defined $self->{'default'}) {
8ee74136 121 $self->_set_initial_slot_value(
122 $meta_instance,
0ab65f99 123 $instance,
0ab65f99 124 $self->default($instance),
0ab65f99 125 );
b7bdffc3 126 }
8683db0e 127 elsif (defined( my $builder = $self->{'builder'})) {
b7bdffc3 128 if ($builder = $instance->can($builder)) {
8ee74136 129 $self->_set_initial_slot_value(
130 $meta_instance,
0ab65f99 131 $instance,
0ab65f99 132 $instance->$builder,
0ab65f99 133 );
b7bdffc3 134 }
135 else {
b3fa93c7 136 confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
8fe581e5 137 }
1d68af04 138 }
bd4e03f9 139}
140
8ee74136 141sub _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
5659d76e 159# NOTE:
1d68af04 160# the next bunch of methods will get bootstrapped
7b31baf4 161# away in the Class::MOP bootstrapping section
162
8683db0e 163sub associated_class { $_[0]->{'associated_class'} }
164sub associated_methods { $_[0]->{'associated_methods'} }
165
b3fa93c7 166sub has_accessor { defined($_[0]->{'accessor'}) }
167sub has_reader { defined($_[0]->{'reader'}) }
168sub has_writer { defined($_[0]->{'writer'}) }
169sub has_predicate { defined($_[0]->{'predicate'}) }
170sub has_clearer { defined($_[0]->{'clearer'}) }
171sub has_builder { defined($_[0]->{'builder'}) }
172sub has_init_arg { defined($_[0]->{'init_arg'}) }
173sub has_default { defined($_[0]->{'default'}) }
174sub has_initializer { defined($_[0]->{'initializer'}) }
dc9d420c 175sub has_insertion_order { defined($_[0]->{'insertion_order'}) }
8683db0e 176
d9d99689 177sub accessor { $_[0]->{'accessor'} }
178sub reader { $_[0]->{'reader'} }
179sub writer { $_[0]->{'writer'} }
180sub predicate { $_[0]->{'predicate'} }
181sub clearer { $_[0]->{'clearer'} }
182sub builder { $_[0]->{'builder'} }
183sub init_arg { $_[0]->{'init_arg'} }
184sub initializer { $_[0]->{'initializer'} }
185sub definition_context { $_[0]->{'definition_context'} }
dc9d420c 186sub insertion_order { $_[0]->{'insertion_order'} }
943cbe2d 187sub _set_insertion_order { $_[0]->{'insertion_order'} = $_[1] }
c50c603e 188
7b31baf4 189# end bootstrapped away method section.
190# (all methods below here are kept intact)
191
9e517e01 192sub has_read_method { $_[0]->has_reader || $_[0]->has_accessor }
193sub has_write_method { $_[0]->has_writer || $_[0]->has_accessor }
194
d14f6cbe 195sub 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
205sub 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}
b25109b1 214
5da16d1b 215sub get_read_method_ref {
216 my $self = shift;
742fb371 217 if ((my $reader = $self->get_read_method) && $self->associated_class) {
5da16d1b 218 return $self->associated_class->get_method($reader);
219 }
220 else {
def5c0b5 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 }
5da16d1b 232 }
233}
234
235sub get_write_method_ref {
236 my $self = shift;
d14f6cbe 237 if ((my $writer = $self->get_write_method) && $self->associated_class) {
742fb371 238 return $self->associated_class->get_method($writer);
5da16d1b 239 }
240 else {
def5c0b5 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 }
5da16d1b 252 }
253}
254
1d68af04 255sub is_default_a_coderef {
ed337aad 256 my ($value) = $_[0]->{'default'};
257 return unless ref($value);
258 return ref($value) eq 'CODE' || (blessed($value) && $value->isa('Class::MOP::Method'));
c0cbf4d9 259}
260
1d68af04 261sub default {
c0cbf4d9 262 my ($self, $instance) = @_;
9363ea89 263 if (defined $instance && $self->is_default_a_coderef) {
1d68af04 264 # if the default is a CODE ref, then
727919c5 265 # we pass in the instance and default
1d68af04 266 # can return a value based on that
727919c5 267 # instance. Somewhat crude, but works.
8683db0e 268 return $self->{'default'}->($instance);
1d68af04 269 }
8683db0e 270 $self->{'default'};
c50c603e 271}
8b978dd5 272
c57c8b10 273# slots
274
275sub slots { (shift)->name }
276
1d68af04 277# class association
727919c5 278
9ec169fe 279sub 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)";
8683db0e 283 weaken($self->{'associated_class'} = $class);
9ec169fe 284}
285
286sub detach_from_class {
287 my $self = shift;
8683db0e 288 $self->{'associated_class'} = undef;
9ec169fe 289}
290
1d68af04 291# method association
3545c727 292
293sub associate_method {
294 my ($self, $method) = @_;
8683db0e 295 push @{$self->{'associated_methods'}} => $method;
3545c727 296}
297
16e960bd 298## Slot management
299
ef91a0e2 300sub set_initial_value {
301 my ($self, $instance, $value) = @_;
e76b01fb 302 $self->_set_initial_slot_value(
b3fa93c7 303 Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
8ee74136 304 $instance,
305 $value
306 );
ef91a0e2 307}
308
7e5efe15 309sub set_value { shift->set_raw_value(@_) }
310sub get_value { shift->get_raw_value(@_) }
311
312sub set_raw_value {
1396f86b 313 my ($self, $instance, $value) = @_;
16e960bd 314
b3fa93c7 315 Class::MOP::Class->initialize(ref($instance))
da34f054 316 ->get_meta_instance
317 ->set_slot_value($instance, $self->name, $value);
16e960bd 318}
319
7e5efe15 320sub get_raw_value {
1396f86b 321 my ($self, $instance) = @_;
16e960bd 322
b3fa93c7 323 Class::MOP::Class->initialize(ref($instance))
da34f054 324 ->get_meta_instance
325 ->get_slot_value($instance, $self->name);
16e960bd 326}
327
3545c727 328sub has_value {
329 my ($self, $instance) = @_;
1d68af04 330
b3fa93c7 331 Class::MOP::Class->initialize(ref($instance))
da34f054 332 ->get_meta_instance
333 ->is_slot_initialized($instance, $self->name);
3545c727 334}
335
336sub clear_value {
337 my ($self, $instance) = @_;
1d68af04 338
b3fa93c7 339 Class::MOP::Class->initialize(ref($instance))
da34f054 340 ->get_meta_instance
341 ->deinitialize_slot($instance, $self->name);
3545c727 342}
343
ba38bf08 344## load em up ...
c0cbf4d9 345
ba38bf08 346sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
c0cbf4d9 347
45a183fb 348sub _process_accessors {
c0cbf4d9 349 my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
d9d99689 350
351 my $method_ctx;
352
353 if ( my $ctx = $self->definition_context ) {
354 $method_ctx = { %$ctx };
355 }
356
9b522fc4 357 if (ref($accessor)) {
358 (ref($accessor) eq 'HASH')
7d28758b 359 || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
4d47b77f 360 my ($name, $method) = %{$accessor};
4c105333 361 $method = $self->accessor_metaclass->wrap(
362 $method,
363 package_name => $self->associated_class->name,
364 name => $name,
d9d99689 365 definition_context => $method_ctx,
4c105333 366 );
3545c727 367 $self->associate_method($method);
1d68af04 368 return ($name, $method);
2eb717d5 369 }
9ec169fe 370 else {
1d68af04 371 my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
ba38bf08 372 my $method;
a8344505 373 try {
d9d99689 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
ba38bf08 383 $method = $self->accessor_metaclass->new(
384 attribute => $self,
d90b42a6 385 is_inline => $inline_me,
ba38bf08 386 accessor_type => $type,
4c105333 387 package_name => $self->associated_class->name,
388 name => $accessor,
d9d99689 389 definition_context => $method_ctx,
1d68af04 390 );
a8344505 391 }
392 catch {
393 confess "Could not create the '$type' method for " . $self->name . " because : $_";
ba38bf08 394 };
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 {
ea62c8ab 600 my ( $self, $value, $set, $attr ) = @_;
2e23f7dc 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
7e5efe15 836=item B<< $attr->set_raw_value($instance, $value) >>
837
838Sets the value with no side effects such as a trigger.
839
840This doesn't actually apply to Class::MOP attributes, only to subclasses.
841
2e23f7dc 842=item B<< $attr->set_initial_value($instance, $value) >>
c50c603e 843
2e23f7dc 844Sets the value without going through the accessor. This method is only
845called when the instance is first being initialized.
7d28758b 846
2e23f7dc 847=item B<< $attr->get_value($instance) >>
0ab65f99 848
2e23f7dc 849Returns the value without going through the accessor. Note that this
850works even with write-only accessors.
552e3d24 851
7e5efe15 852=item B<< $sttr->get_raw_value($instance) >>
853
854Returns the value without any side effects such as lazy attributes.
855
856Doesn't actually apply to Class::MOP attributes, only to subclasses.
857
2e23f7dc 858=item B<< $attr->has_value($instance) >>
552e3d24 859
2e23f7dc 860Return a boolean indicating whether the attribute has been set in
861C<$instance>. This how the default C<predicate> method works.
862
863=item B<< $attr->clear_value($instance) >>
864
865This will clear the attribute's value in C<$instance>. This is what
866the default C<clearer> calls.
867
868Note that this works even if the attribute does not have any
869associated read, write or clear methods.
bf731086 870
552e3d24 871=back
872
9ec169fe 873=head2 Class association
874
1d68af04 875These methods allow you to manage the attributes association with
876the class that contains it. These methods should not be used
2367814a 877lightly, nor are they very magical, they are mostly used internally
878and by metaclass instances.
879
9ec169fe 880=over 4
881
2e23f7dc 882=item B<< $attr->associated_class >>
883
884This returns the C<Class::MOP::Class> with which this attribute is
885associated, if any.
886
887=item B<< $attr->attach_to_class($metaclass) >>
9ec169fe 888
2e23f7dc 889This method stores a weakened reference to the C<$metaclass> object
890internally.
2367814a 891
2e23f7dc 892This method does not remove the attribute from its old class,
893nor does it create any accessors in the new class.
9ec169fe 894
2e23f7dc 895It is probably best to use the L<Class::MOP::Class> C<add_attribute>
896method instead.
2367814a 897
2e23f7dc 898=item B<< $attr->detach_from_class >>
9ec169fe 899
2e23f7dc 900This method removes the associate metaclass object from the attribute
901it has one.
902
903This method does not remove the attribute itself from the class, or
904remove its accessors.
905
906It is probably best to use the L<Class::MOP::Class>
907C<remove_attribute> method instead.
2367814a 908
9ec169fe 909=back
910
552e3d24 911=head2 Attribute Accessor generation
912
913=over 4
914
2e23f7dc 915=item B<< $attr->accessor_metaclass >>
ba38bf08 916
2e23f7dc 917Accessor methods are generated using an accessor metaclass. By
918default, this is L<Class::MOP::Method::Accessor>. This method returns
2367814a 919the name of the accessor metaclass that this attribute uses.
920
2e23f7dc 921=item B<< $attr->associate_method($method) >>
2367814a 922
2e23f7dc 923This associates a L<Class::MOP::Method> object with the
924attribute. Typically, this is called internally when an attribute
925generates its accessors.
3545c727 926
2e23f7dc 927=item B<< $attr->associated_methods >>
3545c727 928
2e23f7dc 929This returns the list of methods which have been associated with the
930attribute.
2367814a 931
2e23f7dc 932=item B<< $attr->install_accessors >>
2eb717d5 933
2e23f7dc 934This method generates and installs code the attributes various
935accessors. It is typically called from the L<Class::MOP::Class>
936C<add_attribute> method.
2eb717d5 937
2e23f7dc 938=item B<< $attr->remove_accessors >>
2eb717d5 939
2e23f7dc 940This method removes all of the accessors associated with the
941attribute.
2eb717d5 942
2e23f7dc 943This does not currently remove methods from the list returned by
944C<associated_methods>.
2367814a 945
2eb717d5 946=back
947
948=head2 Introspection
949
950=over 4
552e3d24 951
45b4c423 952=item B<< Class::MOP::Attribute->meta >>
552e3d24 953
2e23f7dc 954This will return a L<Class::MOP::Class> instance for this class.
fe122940 955
2e23f7dc 956It should also be noted that L<Class::MOP> will actually bootstrap
957this module by installing a number of attribute meta-objects into its
958metaclass.
fe122940 959
552e3d24 960=back
961
1a09d9cc 962=head1 AUTHORS
8b978dd5 963
a2e85e6c 964Stevan Little E<lt>stevan@iinteractive.comE<gt>
8b978dd5 965
966=head1 COPYRIGHT AND LICENSE
967
070bb6c9 968Copyright 2006-2009 by Infinity Interactive, Inc.
8b978dd5 969
970L<http://www.iinteractive.com>
971
972This library is free software; you can redistribute it and/or modify
1d68af04 973it under the same terms as Perl itself.
8b978dd5 974
16e960bd 975=cut
976
7d28758b 977