2 package Moose::Meta::Attribute;
7 use Scalar::Util 'blessed', 'weaken';
10 our $VERSION = '0.83';
11 our $AUTHORITY = 'cpan:STEVAN';
13 use Moose::Meta::Method::Accessor;
14 use Moose::Meta::Method::Delegation;
16 use Moose::Util::TypeConstraints ();
18 use base 'Class::MOP::Attribute';
20 # options which are not directly used
21 # but we store them for metadata purposes
22 __PACKAGE__->meta->add_attribute('isa' => (reader => '_isa_metadata'));
23 __PACKAGE__->meta->add_attribute('does' => (reader => '_does_metadata'));
24 __PACKAGE__->meta->add_attribute('is' => (reader => '_is_metadata'));
26 # these are actual options for the attrs
27 __PACKAGE__->meta->add_attribute('required' => (reader => 'is_required' ));
28 __PACKAGE__->meta->add_attribute('lazy' => (reader => 'is_lazy' ));
29 __PACKAGE__->meta->add_attribute('lazy_build' => (reader => 'is_lazy_build' ));
30 __PACKAGE__->meta->add_attribute('coerce' => (reader => 'should_coerce' ));
31 __PACKAGE__->meta->add_attribute('weak_ref' => (reader => 'is_weak_ref' ));
32 __PACKAGE__->meta->add_attribute('auto_deref' => (reader => 'should_auto_deref'));
33 __PACKAGE__->meta->add_attribute('type_constraint' => (
34 reader => 'type_constraint',
35 predicate => 'has_type_constraint',
37 __PACKAGE__->meta->add_attribute('trigger' => (
39 predicate => 'has_trigger',
41 __PACKAGE__->meta->add_attribute('handles' => (
43 writer => '_set_handles',
44 predicate => 'has_handles',
46 __PACKAGE__->meta->add_attribute('documentation' => (
47 reader => 'documentation',
48 predicate => 'has_documentation',
50 __PACKAGE__->meta->add_attribute('traits' => (
51 reader => 'applied_traits',
52 predicate => 'has_applied_traits',
55 # we need to have a ->does method in here to
56 # more easily support traits, and the introspection
57 # of those traits. We extend the does check to look
58 # for metatrait aliases.
60 my ($self, $role_name) = @_;
62 Moose::Util::resolve_metatrait_alias(Attribute => $role_name)
64 return 0 if !defined($name); # failed to load class
65 return $self->Moose::Object::does($name);
70 my $class = ( ref $self && $self->associated_class ) || "Moose::Meta::Class";
71 unshift @_, "message" if @_ % 2 == 1;
72 unshift @_, attr => $self if ref $self;
74 my $handler = $class->can("throw_error"); # to avoid incrementing depth by 1
79 my ($class, $name, %options) = @_;
80 $class->_process_options($name, \%options) unless $options{__hack_no_process_options}; # used from clone()... YECHKKK FIXME ICKY YUCK GROSS
81 return $class->SUPER::new($name, %options);
84 sub interpolate_class_and_new {
85 my ($class, $name, @args) = @_;
87 my ( $new_class, @traits ) = $class->interpolate_class(@args);
89 $new_class->new($name, @args, ( scalar(@traits) ? ( traits => \@traits ) : () ) );
92 sub interpolate_class {
93 my ($class, %options) = @_;
95 $class = ref($class) || $class;
97 if ( my $metaclass_name = delete $options{metaclass} ) {
98 my $new_class = Moose::Util::resolve_metaclass_alias( Attribute => $metaclass_name );
100 if ( $class ne $new_class ) {
101 if ( $new_class->can("interpolate_class") ) {
102 return $new_class->interpolate_class(%options);
111 if (my $traits = $options{traits}) {
113 while ($i < @$traits) {
114 my $trait = $traits->[$i++];
115 next if ref($trait); # options to a trait we discarded
117 $trait = Moose::Util::resolve_metatrait_alias(Attribute => $trait)
120 next if $class->does($trait);
122 push @traits, $trait;
125 push @traits, $traits->[$i++]
126 if $traits->[$i] && ref($traits->[$i]);
130 my $anon_class = Moose::Meta::Class->create_anon_class(
131 superclasses => [ $class ],
132 roles => [ @traits ],
136 $class = $anon_class->name;
140 return ( wantarray ? ( $class, @traits ) : $class );
145 my @legal_options_for_inheritance = qw(
146 default coerce required
147 documentation lazy handles
148 builder type_constraint
153 sub legal_options_for_inheritance { @legal_options_for_inheritance }
156 # This method *must* be able to handle
157 # Class::MOP::Attribute instances as
158 # well. Yes, I know that is wrong, but
159 # apparently we didn't realize it was
160 # doing that and now we have some code
161 # which is dependent on it. The real
162 # solution of course is to push this
163 # feature back up into Class::MOP::Attribute
164 # but I not right now, I am too lazy.
165 # However if you are reading this and
166 # looking for something to do,.. please
169 sub clone_and_inherit_options {
170 my ($self, %options) = @_;
177 # we may want to extends a Class::MOP::Attribute
178 # in which case we need to be able to use the
179 # core set of legal options that have always
180 # been here. But we allows Moose::Meta::Attribute
181 # instances to changes them.
183 my @legal_options = $self->can('legal_options_for_inheritance')
184 ? $self->legal_options_for_inheritance
185 : @legal_options_for_inheritance;
187 foreach my $legal_option (@legal_options) {
188 if (exists $options{$legal_option}) {
189 $actual_options{$legal_option} = $options{$legal_option};
190 delete $options{$legal_option};
196 if (blessed($options{isa}) && $options{isa}->isa('Moose::Meta::TypeConstraint')) {
197 $type_constraint = $options{isa};
200 $type_constraint = Moose::Util::TypeConstraints::find_or_create_isa_type_constraint($options{isa});
201 (defined $type_constraint)
202 || $self->throw_error("Could not find the type constraint '" . $options{isa} . "'", data => $options{isa});
205 $actual_options{type_constraint} = $type_constraint;
206 delete $options{isa};
209 if ($options{does}) {
211 if (blessed($options{does}) && $options{does}->isa('Moose::Meta::TypeConstraint')) {
212 $type_constraint = $options{does};
215 $type_constraint = Moose::Util::TypeConstraints::find_or_create_does_type_constraint($options{does});
216 (defined $type_constraint)
217 || $self->throw_error("Could not find the type constraint '" . $options{does} . "'", data => $options{does});
220 $actual_options{type_constraint} = $type_constraint;
221 delete $options{does};
225 # this doesn't apply to Class::MOP::Attributes,
226 # so we can ignore it for them.
228 if ($self->can('interpolate_class')) {
229 ( $actual_options{metaclass}, my @traits ) = $self->interpolate_class(%options);
232 my @all_traits = grep { $seen{$_}++ } @{ $self->applied_traits || [] }, @traits;
233 $actual_options{traits} = \@all_traits if @all_traits;
235 delete @options{qw(metaclass traits)};
238 (scalar keys %options == 0)
239 || $self->throw_error("Illegal inherited options => (" . (join ', ' => keys %options) . ")", data => \%options);
242 $self->clone(%actual_options);
246 my ( $self, %params ) = @_;
248 my $class = $params{metaclass} || ref $self;
250 my ( @init, @non_init );
252 foreach my $attr ( grep { $_->has_value($self) } Class::MOP::class_of($self)->get_all_attributes ) {
253 push @{ $attr->has_init_arg ? \@init : \@non_init }, $attr;
256 my %new_params = ( ( map { $_->init_arg => $_->get_value($self) } @init ), %params );
258 my $name = delete $new_params{name};
260 my $clone = $class->new($name, %new_params, __hack_no_process_options => 1 );
262 foreach my $attr ( @non_init ) {
263 $attr->set_value($clone, $attr->get_value($self));
269 sub _process_options {
270 my ($class, $name, $options) = @_;
272 if (exists $options->{is}) {
274 ### -------------------------
275 ## is => ro, writer => _foo # turns into (reader => foo, writer => _foo) as before
276 ## is => rw, writer => _foo # turns into (reader => foo, writer => _foo)
277 ## is => rw, accessor => _foo # turns into (accessor => _foo)
278 ## is => ro, accessor => _foo # error, accesor is rw
279 ### -------------------------
281 if ($options->{is} eq 'ro') {
282 $class->throw_error("Cannot define an accessor name on a read-only attribute, accessors are read/write", data => $options)
283 if exists $options->{accessor};
284 $options->{reader} ||= $name;
286 elsif ($options->{is} eq 'rw') {
287 if ($options->{writer}) {
288 $options->{reader} ||= $name;
291 $options->{accessor} ||= $name;
294 elsif ($options->{is} eq 'bare') {
295 # do nothing, but don't complain (later) about missing methods
298 $class->throw_error("I do not understand this option (is => " . $options->{is} . ") on attribute ($name)", data => $options->{is});
302 if (exists $options->{isa}) {
303 if (exists $options->{does}) {
304 if (eval { $options->{isa}->can('does') }) {
305 ($options->{isa}->does($options->{does}))
306 || $class->throw_error("Cannot have an isa option and a does option if the isa does not do the does on attribute ($name)", data => $options);
309 $class->throw_error("Cannot have an isa option which cannot ->does() on attribute ($name)", data => $options);
313 # allow for anon-subtypes here ...
314 if (blessed($options->{isa}) && $options->{isa}->isa('Moose::Meta::TypeConstraint')) {
315 $options->{type_constraint} = $options->{isa};
318 $options->{type_constraint} = Moose::Util::TypeConstraints::find_or_create_isa_type_constraint($options->{isa});
321 elsif (exists $options->{does}) {
322 # allow for anon-subtypes here ...
323 if (blessed($options->{does}) && $options->{does}->isa('Moose::Meta::TypeConstraint')) {
324 $options->{type_constraint} = $options->{does};
327 $options->{type_constraint} = Moose::Util::TypeConstraints::find_or_create_does_type_constraint($options->{does});
331 if (exists $options->{coerce} && $options->{coerce}) {
332 (exists $options->{type_constraint})
333 || $class->throw_error("You cannot have coercion without specifying a type constraint on attribute ($name)", data => $options);
334 $class->throw_error("You cannot have a weak reference to a coerced value on attribute ($name)", data => $options)
335 if $options->{weak_ref};
338 if (exists $options->{trigger}) {
339 ('CODE' eq ref $options->{trigger})
340 || $class->throw_error("Trigger must be a CODE ref on attribute ($name)", data => $options->{trigger});
343 if (exists $options->{auto_deref} && $options->{auto_deref}) {
344 (exists $options->{type_constraint})
345 || $class->throw_error("You cannot auto-dereference without specifying a type constraint on attribute ($name)", data => $options);
346 ($options->{type_constraint}->is_a_type_of('ArrayRef') ||
347 $options->{type_constraint}->is_a_type_of('HashRef'))
348 || $class->throw_error("You cannot auto-dereference anything other than a ArrayRef or HashRef on attribute ($name)", data => $options);
351 if (exists $options->{lazy_build} && $options->{lazy_build} == 1) {
352 $class->throw_error("You can not use lazy_build and default for the same attribute ($name)", data => $options)
353 if exists $options->{default};
354 $options->{lazy} = 1;
355 $options->{builder} ||= "_build_${name}";
357 $options->{clearer} ||= "_clear${name}";
358 $options->{predicate} ||= "_has${name}";
361 $options->{clearer} ||= "clear_${name}";
362 $options->{predicate} ||= "has_${name}";
366 if (exists $options->{lazy} && $options->{lazy}) {
367 (exists $options->{default} || defined $options->{builder} )
368 || $class->throw_error("You cannot have lazy attribute ($name) without specifying a default value for it", data => $options);
371 if ( $options->{required} && !( ( !exists $options->{init_arg} || defined $options->{init_arg} ) || exists $options->{default} || defined $options->{builder} ) ) {
372 $class->throw_error("You cannot have a required attribute ($name) without a default, builder, or an init_arg", data => $options);
377 sub initialize_instance_slot {
378 my ($self, $meta_instance, $instance, $params) = @_;
379 my $init_arg = $self->init_arg();
380 # try to fetch the init arg from the %params ...
384 if ( defined($init_arg) and exists $params->{$init_arg}) {
385 $val = $params->{$init_arg};
389 # skip it if it's lazy
390 return if $self->is_lazy;
391 # and die if it's required and doesn't have a default value
392 $self->throw_error("Attribute (" . $self->name . ") is required", object => $instance, data => $params)
393 if $self->is_required && !$self->has_default && !$self->has_builder;
395 # if nothing was in the %params, we can use the
396 # attribute's default value (if it has one)
397 if ($self->has_default) {
398 $val = $self->default($instance);
401 elsif ($self->has_builder) {
402 $val = $self->_call_builder($instance);
407 return unless $value_is_set;
409 $val = $self->_coerce_and_verify( $val, $instance );
411 $self->set_initial_value($instance, $val);
412 $meta_instance->weaken_slot_value($instance, $self->name)
413 if ref $val && $self->is_weak_ref;
417 my ( $self, $instance ) = @_;
419 my $builder = $self->builder();
421 return $instance->$builder()
422 if $instance->can( $self->builder );
424 $self->throw_error( blessed($instance)
425 . " does not support builder method '"
427 . "' for attribute '"
437 # this duplicates too much code from
438 # Class::MOP::Attribute, we need to
439 # refactor these bits eventually.
441 sub _set_initial_slot_value {
442 my ($self, $meta_instance, $instance, $value) = @_;
444 my $slot_name = $self->name;
446 return $meta_instance->set_slot_value($instance, $slot_name, $value)
447 unless $self->has_initializer;
449 my ($type_constraint, $can_coerce);
450 if ($self->has_type_constraint) {
451 $type_constraint = $self->type_constraint;
452 $can_coerce = ($self->should_coerce && $type_constraint->has_coercion);
456 my $val = $self->_coerce_and_verify( shift, $instance );;
458 $meta_instance->set_slot_value($instance, $slot_name, $val);
461 my $initializer = $self->initializer;
463 # most things will just want to set a value, so make it first arg
464 $instance->$initializer($value, $callback, $self);
468 my ($self, $instance, @args) = @_;
469 my $value = $args[0];
471 my $attr_name = $self->name;
473 if ($self->is_required and not @args) {
474 $self->throw_error("Attribute ($attr_name) is required", object => $instance);
477 $value = $self->_coerce_and_verify( $value, $instance );
479 my $meta_instance = Class::MOP::Class->initialize(blessed($instance))
482 $meta_instance->set_slot_value($instance, $attr_name, $value);
484 if (ref $value && $self->is_weak_ref) {
485 $meta_instance->weaken_slot_value($instance, $attr_name);
488 if ($self->has_trigger) {
489 $self->trigger->($instance, $value);
494 my ($self, $instance) = @_;
496 if ($self->is_lazy) {
497 unless ($self->has_value($instance)) {
499 if ($self->has_default) {
500 $value = $self->default($instance);
501 } elsif ( $self->has_builder ) {
502 $value = $self->_call_builder($instance);
505 $value = $self->_coerce_and_verify( $value, $instance );
507 $self->set_initial_value($instance, $value);
511 if ($self->should_auto_deref) {
513 my $type_constraint = $self->type_constraint;
515 if ($type_constraint->is_a_type_of('ArrayRef')) {
516 my $rv = $self->SUPER::get_value($instance);
517 return unless defined $rv;
518 return wantarray ? @{ $rv } : $rv;
520 elsif ($type_constraint->is_a_type_of('HashRef')) {
521 my $rv = $self->SUPER::get_value($instance);
522 return unless defined $rv;
523 return wantarray ? %{ $rv } : $rv;
526 $self->throw_error("Can not auto de-reference the type constraint '" . $type_constraint->name . "'", object => $instance, type_constraint => $type_constraint);
532 return $self->SUPER::get_value($instance);
536 ## installing accessors
538 sub accessor_metaclass { 'Moose::Meta::Method::Accessor' }
540 sub install_accessors {
542 $self->SUPER::install_accessors(@_);
543 $self->install_delegation if $self->has_handles;
545 @{ $self->associated_methods }
546 || ($self->_is_metadata || '') eq 'bare'
549 'Attribute (' . $self->name . ') has no associated methods'
550 . ' (did you mean to provide an "is" argument?)'
557 sub remove_accessors {
559 $self->SUPER::remove_accessors(@_);
560 $self->remove_delegation if $self->has_handles;
564 sub install_delegation {
568 # Here we canonicalize the 'handles' option
569 # this will sort out any details and always
570 # return an hash of methods which we want
571 # to delagate to, see that method for details
572 my %handles = $self->_canonicalize_handles;
575 # install the delegation ...
576 my $associated_class = $self->associated_class;
577 foreach my $handle (keys %handles) {
578 my $method_to_call = $handles{$handle};
579 my $class_name = $associated_class->name;
580 my $name = "${class_name}::${handle}";
582 (!$associated_class->has_method($handle))
583 || $self->throw_error("You cannot overwrite a locally defined method ($handle) with a delegation", method_name => $handle);
586 # handles is not allowed to delegate
587 # any of these methods, as they will
588 # override the ones in your class, which
589 # is almost certainly not what you want.
591 # FIXME warn when $handle was explicitly specified, but not if the source is a regex or something
592 #cluck("Not delegating method '$handle' because it is a core method") and
593 next if $class_name->isa("Moose::Object") and $handle =~ /^BUILD|DEMOLISH$/ || Moose::Object->can($handle);
595 my $method = $self->_make_delegation_method($handle, $method_to_call);
597 $self->associated_class->add_method($method->name, $method);
598 $self->associate_method($method);
602 sub remove_delegation {
604 my %handles = $self->_canonicalize_handles;
605 my $associated_class = $self->associated_class;
606 foreach my $handle (keys %handles) {
607 $self->associated_class->remove_method($handle);
611 # private methods to help delegation ...
613 sub _canonicalize_handles {
615 my $handles = $self->handles;
616 if (my $handle_type = ref($handles)) {
617 if ($handle_type eq 'HASH') {
620 elsif ($handle_type eq 'ARRAY') {
621 return map { $_ => $_ } @{$handles};
623 elsif ($handle_type eq 'Regexp') {
624 ($self->has_type_constraint)
625 || $self->throw_error("Cannot delegate methods based on a Regexp without a type constraint (isa)", data => $handles);
626 return map { ($_ => $_) }
627 grep { /$handles/ } $self->_get_delegate_method_list;
629 elsif ($handle_type eq 'CODE') {
630 return $handles->($self, $self->_find_delegate_metaclass);
632 elsif (blessed($handles) && $handles->isa('Moose::Meta::TypeConstraint::DuckType')) {
633 return map { $_ => $_ } @{ $handles->methods };
636 $self->throw_error("Unable to canonicalize the 'handles' option with $handles", data => $handles);
640 Class::MOP::load_class($handles);
641 my $role_meta = Class::MOP::class_of($handles);
643 (blessed $role_meta && $role_meta->isa('Moose::Meta::Role'))
644 || $self->throw_error("Unable to canonicalize the 'handles' option with $handles because its metaclass is not a Moose::Meta::Role", data => $handles);
646 return map { $_ => $_ } (
647 $role_meta->get_method_list,
648 map { $_->name } $role_meta->get_required_method_list,
653 sub _find_delegate_metaclass {
655 if (my $class = $self->_isa_metadata) {
656 # we might be dealing with a non-Moose class,
657 # and need to make our own metaclass. if there's
658 # already a metaclass, it will be returned
659 return Moose::Meta::Class->initialize($class);
661 elsif (my $role = $self->_does_metadata) {
662 return Class::MOP::class_of($role);
665 $self->throw_error("Cannot find delegate metaclass for attribute " . $self->name);
669 sub _get_delegate_method_list {
671 my $meta = $self->_find_delegate_metaclass;
672 if ($meta->isa('Class::MOP::Class')) {
673 return map { $_->name } # NOTE: !never! delegate &meta
674 grep { $_->package_name ne 'Moose::Object' && $_->name ne 'meta' }
675 $meta->get_all_methods;
677 elsif ($meta->isa('Moose::Meta::Role')) {
678 return $meta->get_method_list;
681 $self->throw_error("Unable to recognize the delegate metaclass '$meta'", data => $meta);
685 sub delegation_metaclass { 'Moose::Meta::Method::Delegation' }
687 sub _make_delegation_method {
688 my ( $self, $handle_name, $method_to_call ) = @_;
692 $method_body = $method_to_call
693 if 'CODE' eq ref($method_to_call);
695 my $curried_arguments = [];
697 ($method_to_call, $curried_arguments) = @$method_to_call
698 if 'ARRAY' eq ref($method_to_call);
700 return $self->delegation_metaclass->new(
701 name => $handle_name,
702 package_name => $self->associated_class->name,
704 delegate_to_method => $method_to_call,
705 curried_arguments => $curried_arguments || [],
709 sub _coerce_and_verify {
712 my $instance = shift;
714 return $val unless $self->has_type_constraint;
716 my $type_constraint = $self->type_constraint;
717 if ($self->should_coerce && $type_constraint->has_coercion) {
718 $val = $type_constraint->coerce($val);
721 $self->verify_against_type_constraint($val, instance => $instance);
726 sub verify_against_type_constraint {
730 return 1 if !$self->has_type_constraint;
732 my $type_constraint = $self->type_constraint;
734 $type_constraint->check($val)
735 || $self->throw_error("Attribute ("
737 . ") does not pass the type constraint because: "
738 . $type_constraint->get_message($val), data => $val, @_);
741 package Moose::Meta::Attribute::Custom::Moose;
742 sub register_implementation { 'Moose::Meta::Attribute' }
752 Moose::Meta::Attribute - The Moose attribute metaclass
756 This class is a subclass of L<Class::MOP::Attribute> that provides
757 additional Moose-specific functionality.
759 To really understand this class, you will need to start with the
760 L<Class::MOP::Attribute> documentation. This class can be understood
761 as a set of additional features on top of the basic feature provided
762 by that parent class.
766 C<Moose::Meta::Attribute> is a subclass of L<Class::MOP::Attribute>.
770 Many of the documented below override methods in
771 L<Class::MOP::Attribute> and add Moose specific features.
777 =item B<< Moose::Meta::Attribute->new(%options) >>
779 This method overrides the L<Class::MOP::Attribute> constructor.
781 Many of the options below are described in more detail in the
782 L<Moose::Manual::Attributes> document.
784 It adds the following options to the constructor:
788 =item * is => 'ro', 'rw', 'bare'
790 This provides a shorthand for specifying the C<reader>, C<writer>, or
791 C<accessor> names. If the attribute is read-only ('ro') then it will
792 have a C<reader> method with the same attribute as the name.
794 If it is read-write ('rw') then it will have an C<accessor> method
795 with the same name. If you provide an explicit C<writer> for a
796 read-write attribute, then you will have a C<reader> with the same
797 name as the attribute, and a C<writer> with the name you provided.
799 Use 'bare' when you are deliberately not installing any methods
800 (accessor, reader, etc.) associated with this attribute; otherwise,
801 Moose will issue a deprecation warning when this attribute is added to a
806 This option accepts a type. The type can be a string, which should be
807 a type name. If the type name is unknown, it is assumed to be a class
810 This option can also accept a L<Moose::Meta::TypeConstraint> object.
812 If you I<also> provide a C<does> option, then your C<isa> option must
813 be a class name, and that class must do the role specified with
816 =item * does => $role
818 This is short-hand for saying that the attribute's type must be an
819 object which does the named role.
821 =item * coerce => $bool
823 This option is only valid for objects with a type constraint
824 (C<isa>). If this is true, then coercions will be applied whenever
825 this attribute is set.
827 You can make both this and the C<weak_ref> option true.
829 =item * trigger => $sub
831 This option accepts a subroutine reference, which will be called after
832 the attribute is set.
834 =item * required => $bool
836 An attribute which is required must be provided to the constructor. An
837 attribute which is required can also have a C<default> or C<builder>,
838 which will satisfy its required-ness.
840 A required attribute must have a C<default>, C<builder> or a
841 non-C<undef> C<init_arg>
843 =item * lazy => $bool
845 A lazy attribute must have a C<default> or C<builder>. When an
846 attribute is lazy, the default value will not be calculated until the
849 =item * weak_ref => $bool
851 If this is true, the attribute's value will be stored as a weak
854 =item * auto_deref => $bool
856 If this is true, then the reader will dereference the value when it is
857 called. The attribute must have a type constraint which defines the
858 attribute as an array or hash reference.
860 =item * lazy_build => $bool
862 Setting this to true makes the attribute lazy and provides a number of
870 is equivalent to this:
875 builder => '_build_size',
876 clearer => 'clear_size',
877 predicate => 'has_size',
880 =item * documentation
882 An arbitrary string that can be retrieved later by calling C<<
883 $attr->documentation >>.
887 =item B<< $attr->clone(%options) >>
889 This creates a new attribute based on attribute being cloned. You must
890 supply a C<name> option to provide a new name for the attribute.
892 The C<%options> can only specify options handled by
893 L<Class::MOP::Attribute>.
897 =head2 Value management
901 =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >>
903 This method is used internally to initialize the attribute's slot in
904 the object C<$instance>.
906 This overrides the L<Class::MOP::Attribute> method to handle lazy
907 attributes, weak references, and type constraints.
913 eval { $point->meta->get_attribute('x')->set_value($point, 'forty-two') };
918 I<Attribute (x) does not pass the type constraint (Int) with 'forty-two'>
920 Before setting the value, a check is made on the type constraint of
921 the attribute, if it has one, to see if the value passes it. If the
922 value fails to pass, the set operation dies with a L<throw_error>.
924 Any coercion to convert values is done before checking the type constraint.
926 To check a value against a type constraint before setting it, fetch the
927 attribute instance using L<Class::MOP::Class/find_attribute_by_name>,
928 fetch the type_constraint from the attribute using L<Moose::Meta::Attribute/type_constraint>
929 and call L<Moose::Meta::TypeConstraint/check>. See L<Moose::Cookbook::Basics::Recipe4>
934 =head2 Attribute Accessor generation
938 =item B<< $attr->install_accessors >>
940 This method overrides the parent to also install delegation methods.
942 If, after installing all methods, the attribute object has no associated
943 methods, it throws an error unless C<< is => 'bare' >> was passed to the
944 attribute constructor. (Trying to add an attribute that has no associated
945 methods is almost always an error.)
947 =item B<< $attr->remove_accessors >>
949 This method overrides the parent to also remove delegation methods.
951 =item B<< $attr->install_delegation >>
953 This method adds its delegation methods to the attribute's associated
954 class, if it has any to add.
956 =item B<< $attr->remove_delegation >>
958 This method remove its delegation methods from the attribute's
961 =item B<< $attr->accessor_metaclass >>
963 Returns the accessor metaclass name, which defaults to
964 L<Moose::Meta::Method::Accessor>.
966 =item B<< $attr->delegation_metaclass >>
968 Returns the delegation metaclass name, which defaults to
969 L<Moose::Meta::Method::Delegation>.
973 =head2 Additional Moose features
975 These methods are not found in the superclass. They support features
980 =item B<< $attr->does($role) >>
982 This indicates whether the I<attribute itself> does the given
983 role. The role can be given as a full class name, or as a resolvable
986 Note that this checks the attribute itself, not its type constraint,
987 so it is checking the attribute's metaclass and any traits applied to
990 =item B<< Moose::Meta::Class->interpolate_class_and_new($name, %options) >>
992 This is an alternate constructor that handles the C<metaclass> and
995 Effectively, this method is a factory that finds or creates the
996 appropriate class for the given C<metaclass> and/or C<traits>.
998 Once it has the appropriate class, it will call C<< $class->new($name,
999 %options) >> on that class.
1001 =item B<< $attr->clone_and_inherit_options(%options) >>
1003 This method supports the C<has '+foo'> feature. It does various bits
1004 of processing on the supplied C<%options> before ultimately calling
1005 the C<clone> method.
1007 One of its main tasks is to make sure that the C<%options> provided
1008 only includes the options returned by the
1009 C<legal_options_for_inheritance> method.
1011 =item B<< $attr->legal_options_for_inheritance >>
1013 This returns a whitelist of options that can be overridden in a
1014 subclass's attribute definition.
1016 This exists to allow a custom metaclass to change or add to the list
1017 of options which can be changed.
1019 =item B<< $attr->type_constraint >>
1021 Returns the L<Moose::Meta::TypeConstraint> object for this attribute,
1024 =item B<< $attr->has_type_constraint >>
1026 Returns true if this attribute has a type constraint.
1028 =item B<< $attr->verify_against_type_constraint($value) >>
1030 Given a value, this method returns true if the value is valid for the
1031 attribute's type constraint. If the value is not valid, it throws an
1034 =item B<< $attr->handles >>
1036 This returns the value of the C<handles> option passed to the
1039 =item B<< $attr->has_handles >>
1041 Returns true if this attribute performs delegation.
1043 =item B<< $attr->is_weak_ref >>
1045 Returns true if this attribute stores its value as a weak reference.
1047 =item B<< $attr->is_required >>
1049 Returns true if this attribute is required to have a value.
1051 =item B<< $attr->is_lazy >>
1053 Returns true if this attribute is lazy.
1055 =item B<< $attr->is_lazy_build >>
1057 Returns true if the C<lazy_build> option was true when passed to the
1060 =item B<< $attr->should_coerce >>
1062 Returns true if the C<coerce> option passed to the constructor was
1065 =item B<< $attr->should_auto_deref >>
1067 Returns true if the C<auto_deref> option passed to the constructor was
1070 =item B<< $attr->trigger >>
1072 This is the subroutine reference that was in the C<trigger> option
1073 passed to the constructor, if any.
1075 =item B<< $attr->has_trigger >>
1077 Returns true if this attribute has a trigger set.
1079 =item B<< $attr->documentation >>
1081 Returns the value that was in the C<documentation> option passed to
1082 the constructor, if any.
1084 =item B<< $attr->has_documentation >>
1086 Returns true if this attribute has any documentation.
1088 =item B<< $attr->applied_traits >>
1090 This returns an array reference of all the traits which were applied
1091 to this attribute. If none were applied, this returns C<undef>.
1093 =item B<< $attr->has_applied_traits >>
1095 Returns true if this attribute has any traits applied.
1101 All complex software has bugs lurking in it, and this module is no
1102 exception. If you find a bug please either email me, or add the bug
1107 Stevan Little E<lt>stevan@iinteractive.comE<gt>
1109 Yuval Kogman E<lt>nothingmuch@woobling.comE<gt>
1111 =head1 COPYRIGHT AND LICENSE
1113 Copyright 2006-2009 by Infinity Interactive, Inc.
1115 L<http://www.iinteractive.com>
1117 This library is free software; you can redistribute it and/or modify
1118 it under the same terms as Perl itself.