lib/Moose/Meta/Attribute.pm

   1
   2 package Moose::Meta::Attribute;
   3
   4 use strict;
   5 use warnings;
   6
   7 use Scalar::Util 'blessed', 'weaken', 'reftype';
   8 use Carp         'confess';
   9 use Sub::Name    'subname';
  10 use overload     ();
  11
  12 our $VERSION   = '0.22';
  13 our $AUTHORITY = 'cpan:STEVAN';
  14
  15 use Moose::Meta::Method::Accessor;
  16 use Moose::Util::TypeConstraints ();
  17
  18 use base 'Class::MOP::Attribute';
  19
  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'));
  25
  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',
  36 ));
  37 __PACKAGE__->meta->add_attribute('trigger' => (
  38     reader    => 'trigger',
  39     predicate => 'has_trigger',
  40 ));
  41 __PACKAGE__->meta->add_attribute('handles' => (
  42     reader    => 'handles',
  43     predicate => 'has_handles',
  44 ));
  45 __PACKAGE__->meta->add_attribute('documentation' => (
  46     reader    => 'documentation',
  47     predicate => 'has_documentation',
  48 ));
  49
  50 sub new {
  51     my ($class, $name, %options) = @_;
  52     $class->_process_options($name, \%options);
  53     return $class->SUPER::new($name, %options);
  54 }
  55
  56 sub clone_and_inherit_options {
  57     my ($self, %options) = @_;
  58     # you can change default, required, coerce, documentation and lazy
  59     my %actual_options;
  60     foreach my $legal_option (qw(default coerce required documentation lazy)) {
  61         if (exists $options{$legal_option}) {
  62             $actual_options{$legal_option} = $options{$legal_option};
  63             delete $options{$legal_option};
  64         }
  65     }
  66
  67     # handles can only be added, not changed
  68     if ($options{handles}) {
  69         confess "You can only add the 'handles' option, you cannot change it"
  70             if $self->has_handles;
  71         $actual_options{handles} = $options{handles};
  72         delete $options{handles};
  73     }
  74
  75     # isa can be changed, but only if the
  76     # new type is a subtype
  77     if ($options{isa}) {
  78         my $type_constraint;
  79         if (blessed($options{isa}) && $options{isa}->isa('Moose::Meta::TypeConstraint')) {
  80             $type_constraint = $options{isa};
  81         }
  82         else {
  83             $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint(
  84                 $options{isa}
  85             );
  86             (defined $type_constraint)
  87                 || confess "Could not find the type constraint '" . $options{isa} . "'";
  88         }
  89         # NOTE:
  90         # check here to see if the new type
  91         # is a subtype of the old one
  92         ($type_constraint->is_subtype_of($self->type_constraint->name))
  93             || confess "New type constraint setting must be a subtype of inherited one"
  94                 # iff we have a type constraint that is ...
  95                 if $self->has_type_constraint;
  96         # then we use it :)
  97         $actual_options{type_constraint} = $type_constraint;
  98         delete $options{isa};
  99     }
 100     (scalar keys %options == 0)
 101         || confess "Illegal inherited options => (" . (join ', ' => keys %options) . ")";
 102     $self->clone(%actual_options);
 103 }
 104
 105 sub _process_options {
 106     my ($class, $name, $options) = @_;
 107
 108     if (exists $options->{is}) {
 109         if ($options->{is} eq 'ro') {
 110             $options->{reader} ||= $name;
 111             (!exists $options->{trigger})
 112                 || confess "Cannot have a trigger on a read-only attribute";
 113         }
 114         elsif ($options->{is} eq 'rw') {
 115             $options->{accessor} = $name;
 116             ((reftype($options->{trigger}) || '') eq 'CODE')
 117                 || confess "Trigger must be a CODE ref"
 118                     if exists $options->{trigger};
 119         }
 120         else {
 121             confess "I do not understand this option (is => " . $options->{is} . ")"
 122         }
 123     }
 124
 125     if (exists $options->{isa}) {
 126         if (exists $options->{does}) {
 127             if (eval { $options->{isa}->can('does') }) {
 128                 ($options->{isa}->does($options->{does}))
 129                     || confess "Cannot have an isa option and a does option if the isa does not do the does";
 130             }
 131             else {
 132                 confess "Cannot have an isa option which cannot ->does()";
 133             }
 134         }
 135
 136         # allow for anon-subtypes here ...
 137         if (blessed($options->{isa}) && $options->{isa}->isa('Moose::Meta::TypeConstraint')) {
 138             $options->{type_constraint} = $options->{isa};
 139         }
 140         else {
 141             $options->{type_constraint} = Moose::Util::TypeConstraints::find_or_create_type_constraint(
 142                 $options->{isa} => {
 143                     parent     => Moose::Util::TypeConstraints::find_type_constraint('Object'),
 144                     constraint => sub { $_[0]->isa($options->{isa}) }
 145                 }
 146             );
 147         }
 148     }
 149     elsif (exists $options->{does}) {
 150         # allow for anon-subtypes here ...
 151         if (blessed($options->{does}) && $options->{does}->isa('Moose::Meta::TypeConstraint')) {
 152                 $options->{type_constraint} = $options->{does};
 153         }
 154         else {
 155             $options->{type_constraint} = Moose::Util::TypeConstraints::find_or_create_type_constraint(
 156                 $options->{does} => {
 157                     parent     => Moose::Util::TypeConstraints::find_type_constraint('Role'),
 158                     constraint => sub {
 159                         Moose::Util::does_role($_[0], $options->{does})
 160                     }
 161                 }
 162             );
 163         }
 164     }
 165
 166     if (exists $options->{coerce} && $options->{coerce}) {
 167         (exists $options->{type_constraint})
 168             || confess "You cannot have coercion without specifying a type constraint";
 169         confess "You cannot have a weak reference to a coerced value"
 170             if $options->{weak_ref};
 171     }
 172
 173     if (exists $options->{auto_deref} && $options->{auto_deref}) {
 174         (exists $options->{type_constraint})
 175             || confess "You cannot auto-dereference without specifying a type constraint";
 176         ($options->{type_constraint}->is_a_type_of('ArrayRef') ||
 177          $options->{type_constraint}->is_a_type_of('HashRef'))
 178             || confess "You cannot auto-dereference anything other than a ArrayRef or HashRef";
 179     }
 180
 181     if (exists $options->{lazy_build} && $options->{lazy_build} == 1) {
 182         confess("You can not use lazy_build and default for the same attribute")
 183             if exists $options->{default};
 184         $options->{lazy}      = 1;
 185         $options->{required}  = 1;
 186         $options->{builder} ||= "_build_${name}";
 187         if ($name =~ /^_/) {
 188             $options->{clearer}   ||= "_clear${name}";
 189             $options->{predicate} ||= "_has${name}";
 190         }
 191         else {
 192             $options->{clearer}   ||= "clear_${name}";
 193             $options->{predicate} ||= "has_${name}";
 194         }
 195     }
 196
 197     if (exists $options->{lazy} && $options->{lazy}) {
 198         (exists $options->{default} || defined $options->{builder} )
 199             || confess "You cannot have lazy attribute without specifying a default value for it";
 200     }
 201
 202     if ( $options->{required} && !( ( !exists $options->{init_arg} || defined $options->{init_arg} ) || exists $options->{default} || defined $options->{builder} ) ) {
 203         confess "You cannot have a required attribute without a default, builder, or an init_arg";
 204     }
 205
 206 }
 207
 208 sub initialize_instance_slot {
 209     my ($self, $meta_instance, $instance, $params) = @_;
 210     my $init_arg = $self->init_arg();
 211     # try to fetch the init arg from the %params ...
 212
 213     my $val;
 214     my $value_is_set;
 215     if ( defined($init_arg) and exists $params->{$init_arg}) {
 216         $val = $params->{$init_arg};
 217         $value_is_set = 1;
 218     }
 219     else {
 220         # skip it if it's lazy
 221         return if $self->is_lazy;
 222         # and die if it's required and doesn't have a default value
 223         confess "Attribute (" . $self->name . ") is required"
 224             if $self->is_required && !$self->has_default && !$self->has_builder;
 225
 226         # if nothing was in the %params, we can use the
 227         # attribute's default value (if it has one)
 228         if ($self->has_default) {
 229             $val = $self->default($instance);
 230             $value_is_set = 1;
 231         }
 232         elsif ($self->has_builder) {
 233             if (my $builder = $instance->can($self->builder)){
 234                 $val = $instance->$builder;
 235                 $value_is_set = 1;
 236             }
 237             else {
 238                 confess(blessed($instance)." does not support builder method '".$self->builder."' for attribute '" . $self->name . "'");
 239             }
 240         }
 241     }
 242
 243     return unless $value_is_set;
 244
 245     if ($self->has_type_constraint) {
 246         my $type_constraint = $self->type_constraint;
 247         if ($self->should_coerce && $type_constraint->has_coercion) {
 248             $val = $type_constraint->coerce($val);
 249         }
 250         $type_constraint->check($val)
 251             || confess "Attribute ("
 252                      . $self->name
 253                      . ") does not pass the type constraint because: "
 254                      . $type_constraint->get_message($val);
 255     }
 256
 257     $self->set_initial_value($instance, $val);
 258     $meta_instance->weaken_slot_value($instance, $self->name)
 259         if ref $val && $self->is_weak_ref;
 260 }
 261
 262 ## Slot management
 263
 264 # FIXME:
 265 # this duplicates too much code from
 266 # Class::MOP::Attribute, we need to
 267 # refactor these bits eventually.
 268 # - SL
 269 sub _set_initial_slot_value {
 270     my ($self, $meta_instance, $instance, $value) = @_;
 271
 272     my $slot_name = $self->name;
 273
 274     return $meta_instance->set_slot_value($instance, $slot_name, $value)
 275         unless $self->has_initializer;
 276
 277     my ($type_constraint, $can_coerce);
 278     if ($self->has_type_constraint) {
 279         $type_constraint = $self->type_constraint;
 280         $can_coerce      = ($self->should_coerce && $type_constraint->has_coercion);
 281     }
 282
 283     my $callback = sub {
 284         my $val = shift;
 285         if ($type_constraint) {
 286             $val = $type_constraint->coerce($val)
 287                 if $can_coerce;
 288             $type_constraint->check($val)
 289                 || confess "Attribute ("
 290                          . $slot_name
 291                          . ") does not pass the type constraint because: "
 292                          . $type_constraint->get_message($val);
 293         }
 294         $meta_instance->set_slot_value($instance, $slot_name, $val);
 295     };
 296
 297     my $initializer = $self->initializer;
 298
 299     # most things will just want to set a value, so make it first arg
 300     $instance->$initializer($value, $callback, $self);
 301 }
 302
 303 sub set_value {
 304     my ($self, $instance, $value) = @_;
 305
 306     my $attr_name = $self->name;
 307
 308     if ($self->is_required) {
 309         defined($value)
 310             || confess "Attribute ($attr_name) is required, so cannot be set to undef";
 311     }
 312
 313     if ($self->has_type_constraint) {
 314
 315         my $type_constraint = $self->type_constraint;
 316
 317         if ($self->should_coerce) {
 318             $value = $type_constraint->coerce($value);
 319         }
 320         $type_constraint->_compiled_type_constraint->($value)
 321             || confess "Attribute ("
 322                      . $self->name
 323                      . ") does not pass the type constraint because "
 324                      . $type_constraint->get_message($value);
 325     }
 326
 327     my $meta_instance = Class::MOP::Class->initialize(blessed($instance))
 328                                          ->get_meta_instance;
 329
 330     $meta_instance->set_slot_value($instance, $attr_name, $value);
 331
 332     if (ref $value && $self->is_weak_ref) {
 333         $meta_instance->weaken_slot_value($instance, $attr_name);
 334     }
 335
 336     if ($self->has_trigger) {
 337         $self->trigger->($instance, $value, $self);
 338     }
 339 }
 340
 341 sub get_value {
 342     my ($self, $instance) = @_;
 343
 344     if ($self->is_lazy) {
 345         unless ($self->has_value($instance)) {
 346             if ($self->has_default) {
 347                 my $default = $self->default($instance);
 348                 $self->set_initial_value($instance, $default);
 349             }
 350             if ( $self->has_builder ){
 351                 if (my $builder = $instance->can($self->builder)){
 352                     $self->set_initial_value($instance, $instance->$builder);
 353                 }
 354                 else {
 355                     confess(blessed($instance)
 356                           . " does not support builder method '"
 357                           . $self->builder
 358                           . "' for attribute '"
 359                           . $self->name
 360                           . "'");
 361                 }
 362             }
 363             else {
 364                 $self->set_initial_value($instance, undef);
 365             }
 366         }
 367     }
 368
 369     if ($self->should_auto_deref) {
 370
 371         my $type_constraint = $self->type_constraint;
 372
 373         if ($type_constraint->is_a_type_of('ArrayRef')) {
 374             my $rv = $self->SUPER::get_value($instance);
 375             return unless defined $rv;
 376             return wantarray ? @{ $rv } : $rv;
 377         }
 378         elsif ($type_constraint->is_a_type_of('HashRef')) {
 379             my $rv = $self->SUPER::get_value($instance);
 380             return unless defined $rv;
 381             return wantarray ? %{ $rv } : $rv;
 382         }
 383         else {
 384             confess "Can not auto de-reference the type constraint '" . $type_constraint->name . "'";
 385         }
 386
 387     }
 388     else {
 389
 390         return $self->SUPER::get_value($instance);
 391     }
 392 }
 393
 394 ## installing accessors
 395
 396 sub accessor_metaclass { 'Moose::Meta::Method::Accessor' }
 397
 398 sub install_accessors {
 399     my $self = shift;
 400     $self->SUPER::install_accessors(@_);
 401
 402     if ($self->has_handles) {
 403
 404         # NOTE:
 405         # Here we canonicalize the 'handles' option
 406         # this will sort out any details and always
 407         # return an hash of methods which we want
 408         # to delagate to, see that method for details
 409         my %handles = $self->_canonicalize_handles();
 410
 411         # find the accessor method for this attribute
 412         my $accessor = $self->get_read_method_ref;
 413         # then unpack it if we need too ...
 414         $accessor = $accessor->body if blessed $accessor;
 415
 416         # install the delegation ...
 417         my $associated_class = $self->associated_class;
 418         foreach my $handle (keys %handles) {
 419             my $method_to_call = $handles{$handle};
 420             my $class_name = $associated_class->name;
 421             my $name = "${class_name}::${handle}";
 422
 423             (!$associated_class->has_method($handle))
 424                 || confess "You cannot overwrite a locally defined method ($handle) with a delegation";
 425
 426             # NOTE:
 427             # handles is not allowed to delegate
 428             # any of these methods, as they will
 429             # override the ones in your class, which
 430             # is almost certainly not what you want.
 431
 432             # FIXME warn when $handle was explicitly specified, but not if the source is a regex or something
 433             #cluck("Not delegating method '$handle' because it is a core method") and
 434             next if $class_name->isa("Moose::Object") and $handle =~ /^BUILD|DEMOLISH$/ || Moose::Object->can($handle);
 435
 436             if ((reftype($method_to_call) || '') eq 'CODE') {
 437                 $associated_class->add_method($handle => subname $name, $method_to_call);
 438             }
 439             else {
 440                 # NOTE:
 441                 # we used to do a goto here, but the
 442                 # goto didn't handle failure correctly
 443                 # (it just returned nothing), so I took
 444                 # that out. However, the more I thought
 445                 # about it, the less I liked it doing
 446                 # the goto, and I prefered the act of
 447                 # delegation being actually represented
 448                 # in the stack trace.
 449                 # - SL
 450                 $associated_class->add_method($handle => subname $name, sub {
 451                     my $proxy = (shift)->$accessor();
 452                     (defined $proxy)
 453                         || confess "Cannot delegate $handle to $method_to_call because " .
 454                                    "the value of " . $self->name . " is not defined";
 455                     $proxy->$method_to_call(@_);
 456                 });
 457             }
 458         }
 459     }
 460
 461     return;
 462 }
 463
 464 # private methods to help delegation ...
 465
 466 sub _canonicalize_handles {
 467     my $self    = shift;
 468     my $handles = $self->handles;
 469     if (my $handle_type = ref($handles)) {
 470         if ($handle_type eq 'HASH') {
 471             return %{$handles};
 472         }
 473         elsif ($handle_type eq 'ARRAY') {
 474             return map { $_ => $_ } @{$handles};
 475         }
 476         elsif ($handle_type eq 'Regexp') {
 477             ($self->has_type_constraint)
 478                 || confess "Cannot delegate methods based on a RegExpr without a type constraint (isa)";
 479             return map  { ($_ => $_) }
 480                    grep { /$handles/ } $self->_get_delegate_method_list;
 481         }
 482         elsif ($handle_type eq 'CODE') {
 483             return $handles->($self, $self->_find_delegate_metaclass);
 484         }
 485         else {
 486             confess "Unable to canonicalize the 'handles' option with $handles";
 487         }
 488     }
 489     else {
 490         my $role_meta = eval { $handles->meta };
 491         if ($@) {
 492             confess "Unable to canonicalize the 'handles' option with $handles because : $@";
 493         }
 494
 495         (blessed $role_meta && $role_meta->isa('Moose::Meta::Role'))
 496             || confess "Unable to canonicalize the 'handles' option with $handles because ->meta is not a Moose::Meta::Role";
 497
 498         return map { $_ => $_ } (
 499             $role_meta->get_method_list,
 500             $role_meta->get_required_method_list
 501         );
 502     }
 503 }
 504
 505 sub _find_delegate_metaclass {
 506     my $self = shift;
 507     if (my $class = $self->_isa_metadata) {
 508         # if the class does have
 509         # a meta method, use it
 510         return $class->meta if $class->can('meta');
 511         # otherwise we might be
 512         # dealing with a non-Moose
 513         # class, and need to make
 514         # our own metaclass
 515         return Moose::Meta::Class->initialize($class);
 516     }
 517     elsif (my $role = $self->_does_metadata) {
 518         # our role will always have
 519         # a meta method
 520         return $role->meta;
 521     }
 522     else {
 523         confess "Cannot find delegate metaclass for attribute " . $self->name;
 524     }
 525 }
 526
 527 sub _get_delegate_method_list {
 528     my $self = shift;
 529     my $meta = $self->_find_delegate_metaclass;
 530     if ($meta->isa('Class::MOP::Class')) {
 531         return map  { $_->{name}                     }  # NOTE: !never! delegate &meta
 532                grep { $_->{class} ne 'Moose::Object' && $_->{name} ne 'meta' }
 533                     $meta->compute_all_applicable_methods;
 534     }
 535     elsif ($meta->isa('Moose::Meta::Role')) {
 536         return $meta->get_method_list;
 537     }
 538     else {
 539         confess "Unable to recognize the delegate metaclass '$meta'";
 540     }
 541 }
 542
 543 1;
 544
 545 __END__
 546
 547 =pod
 548
 549 =head1 NAME
 550
 551 Moose::Meta::Attribute - The Moose attribute metaclass
 552
 553 =head1 DESCRIPTION
 554
 555 This is a subclass of L<Class::MOP::Attribute> with Moose specific
 556 extensions.
 557
 558 For the most part, the only time you will ever encounter an
 559 instance of this class is if you are doing some serious deep
 560 introspection. To really understand this class, you need to refer
 561 to the L<Class::MOP::Attribute> documentation.
 562
 563 =head1 METHODS
 564
 565 =head2 Overridden methods
 566
 567 These methods override methods in L<Class::MOP::Attribute> and add
 568 Moose specific features. You can safely assume though that they
 569 will behave just as L<Class::MOP::Attribute> does.
 570
 571 =over 4
 572
 573 =item B<new>
 574
 575 =item B<initialize_instance_slot>
 576
 577 =item B<install_accessors>
 578
 579 =item B<accessor_metaclass>
 580
 581 =item B<get_value>
 582
 583 =item B<set_value>
 584
 585   eval { $point->meta->get_attribute('x')->set_value($point, 'fourty-two') };
 586   if($@) {
 587     print "Oops: $@\n";
 588   }
 589
 590 I<Attribute (x) does not pass the type constraint (Int) with 'fourty-two'>
 591
 592 Before setting the value, a check is made on the type constraint of
 593 the attribute, if it has one, to see if the value passes it. If the
 594 value fails to pass, the set operation dies with a L<Carp/confess>.
 595
 596 Any coercion to convert values is done before checking the type constraint.
 597
 598 To check a value against a type constraint before setting it, fetch the
 599 attribute instance using L<Class::MOP::Class/find_attribute_by_name>,
 600 fetch the type_constraint from the attribute using L<Moose::Meta::Attribute/type_constraint>
 601 and call L<Moose::Meta::TypeConstraint/check>. See L<Moose::Cookbook::RecipeX>
 602 for an example.
 603
 604 =back
 605
 606 =head2 Additional Moose features
 607
 608 Moose attributes support type-constraint checking, weak reference
 609 creation and type coercion.
 610
 611 =over 4
 612
 613 =item B<clone_and_inherit_options>
 614
 615 This is to support the C<has '+foo'> feature, it clones an attribute
 616 from a superclass and allows a very specific set of changes to be made
 617 to the attribute.
 618
 619 =item B<has_type_constraint>
 620
 621 Returns true if this meta-attribute has a type constraint.
 622
 623 =item B<type_constraint>
 624
 625 A read-only accessor for this meta-attribute's type constraint. For
 626 more information on what you can do with this, see the documentation
 627 for L<Moose::Meta::TypeConstraint>.
 628
 629 =item B<has_handles>
 630
 631 Returns true if this meta-attribute performs delegation.
 632
 633 =item B<handles>
 634
 635 This returns the value which was passed into the handles option.
 636
 637 =item B<is_weak_ref>
 638
 639 Returns true if this meta-attribute produces a weak reference.
 640
 641 =item B<is_required>
 642
 643 Returns true if this meta-attribute is required to have a value.
 644
 645 =item B<is_lazy>
 646
 647 Returns true if this meta-attribute should be initialized lazily.
 648
 649 NOTE: lazy attributes, B<must> have a C<default> or C<builder> field set.
 650
 651 =item B<is_lazy_build>
 652
 653 Returns true if this meta-attribute should be initialized lazily through
 654 the builder generated by lazy_build. Using C<lazy_build =E<gt> 1> will
 655 make your attribute required and lazy. In addition it will set the builder, clearer
 656 and predicate options for you using the following convention.
 657
 658    #If your attribute name starts with an underscore:
 659    has '_foo' => (lazy_build => 1);
 660    #is the same as
 661    has '_foo' => (lazy => 1, required => 1, predicate => '_has_foo', clearer => '_clear_foo', builder => '_build__foo);
 662    # or
 663    has '_foo' => (lazy => 1, required => 1, predicate => '_has_foo', clearer => '_clear_foo', default => sub{shift->_build__foo});
 664
 665    #If your attribute name does not start with an underscore:
 666    has 'foo' => (lazy_build => 1);
 667    #is the same as
 668    has 'foo' => (lazy => 1, required => 1, predicate => 'has_foo', clearer => 'clear_foo', builder => '_build_foo);
 669    # or
 670    has 'foo' => (lazy => 1, required => 1, predicate => 'has_foo', clearer => 'clear_foo', default => sub{shift->_build_foo});
 671
 672 The reason for the different naming of the C<builder> is that the C<builder>
 673 method is a private method while the C<clearer> and C<predicate> methods
 674 are public methods.
 675
 676 NOTE: This means your class should provide a method whose name matches the value
 677 of the builder part, in this case _build__foo or _build_foo.
 678
 679 =item B<should_coerce>
 680
 681 Returns true if this meta-attribute should perform type coercion.
 682
 683 =item B<should_auto_deref>
 684
 685 Returns true if this meta-attribute should perform automatic
 686 auto-dereferencing.
 687
 688 NOTE: This can only be done for attributes whose type constraint is
 689 either I<ArrayRef> or I<HashRef>.
 690
 691 =item B<has_trigger>
 692
 693 Returns true if this meta-attribute has a trigger set.
 694
 695 =item B<trigger>
 696
 697 This is a CODE reference which will be executed every time the
 698 value of an attribute is assigned. The CODE ref will get two values,
 699 the invocant and the new value. This can be used to handle I<basic>
 700 bi-directional relations.
 701
 702 =item B<documentation>
 703
 704 This is a string which contains the documentation for this attribute.
 705 It serves no direct purpose right now, but it might in the future
 706 in some kind of automated documentation system perhaps.
 707
 708 =item B<has_documentation>
 709
 710 Returns true if this meta-attribute has any documentation.
 711
 712 =back
 713
 714 =head1 BUGS
 715
 716 All complex software has bugs lurking in it, and this module is no
 717 exception. If you find a bug please either email me, or add the bug
 718 to cpan-RT.
 719
 720 =head1 AUTHOR
 721
 722 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 723
 724 Yuval Kogman E<lt>nothingmuch@woobling.comE<gt>
 725
 726 =head1 COPYRIGHT AND LICENSE
 727
 728 Copyright 2006-2008 by Infinity Interactive, Inc.
 729
 730 L<http://www.iinteractive.com>
 731
 732 This library is free software; you can redistribute it and/or modify
 733 it under the same terms as Perl itself.
 734
 735 =cut