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