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