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