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