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