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