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.18';
  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         (defined($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                 if defined($value);
 287     }
 288
 289     my $meta_instance = Class::MOP::Class->initialize(blessed($instance))
 290                                          ->get_meta_instance;
 291
 292     $meta_instance->set_slot_value($instance, $attr_name, $value);
 293
 294     if (ref $value && $self->is_weak_ref) {
 295         $meta_instance->weaken_slot_value($instance, $attr_name);
 296     }
 297
 298     if ($self->has_trigger) {
 299         $self->trigger->($instance, $value, $self);
 300     }
 301 }
 302
 303 sub get_value {
 304     my ($self, $instance) = @_;
 305
 306     if ($self->is_lazy) {
 307         unless ($self->has_value($instance)) {
 308             if ($self->has_default) {
 309                 my $default = $self->default($instance);
 310                 $self->set_initial_value($instance, $default);
 311             }
 312             if ( $self->has_builder ){
 313                 if (my $builder = $instance->can($self->builder)){
 314                     $self->set_initial_value($instance, $instance->$builder);
 315                 }
 316                 else {
 317                     confess(blessed($instance)
 318                           . " does not support builder method '"
 319                           . $self->builder
 320                           . "' for attribute '"
 321                           . $self->name
 322                           . "'");
 323                 }
 324             }
 325             else {
 326                 $self->set_initial_value($instance, undef);
 327             }
 328         }
 329     }
 330
 331     if ($self->should_auto_deref) {
 332
 333         my $type_constraint = $self->type_constraint;
 334
 335         if ($type_constraint->is_a_type_of('ArrayRef')) {
 336             my $rv = $self->SUPER::get_value($instance);
 337             return unless defined $rv;
 338             return wantarray ? @{ $rv } : $rv;
 339         }
 340         elsif ($type_constraint->is_a_type_of('HashRef')) {
 341             my $rv = $self->SUPER::get_value($instance);
 342             return unless defined $rv;
 343             return wantarray ? %{ $rv } : $rv;
 344         }
 345         else {
 346             confess "Can not auto de-reference the type constraint '" . $type_constraint->name . "'";
 347         }
 348
 349     }
 350     else {
 351
 352         return $self->SUPER::get_value($instance);
 353     }
 354 }
 355
 356 ## installing accessors
 357
 358 sub accessor_metaclass { 'Moose::Meta::Method::Accessor' }
 359
 360 sub install_accessors {
 361     my $self = shift;
 362     $self->SUPER::install_accessors(@_);
 363
 364     if ($self->has_handles) {
 365
 366         # NOTE:
 367         # Here we canonicalize the 'handles' option
 368         # this will sort out any details and always
 369         # return an hash of methods which we want
 370         # to delagate to, see that method for details
 371         my %handles = $self->_canonicalize_handles();
 372
 373         # find the accessor method for this attribute
 374         my $accessor = $self->get_read_method_ref;
 375         # then unpack it if we need too ...
 376         $accessor = $accessor->body if blessed $accessor;
 377
 378         # install the delegation ...
 379         my $associated_class = $self->associated_class;
 380         foreach my $handle (keys %handles) {
 381             my $method_to_call = $handles{$handle};
 382             my $class_name = $associated_class->name;
 383             my $name = "${class_name}::${handle}";
 384
 385             (!$associated_class->has_method($handle))
 386                 || confess "You cannot overwrite a locally defined method ($handle) with a delegation";
 387
 388             # NOTE:
 389             # handles is not allowed to delegate
 390             # any of these methods, as they will
 391             # override the ones in your class, which
 392             # is almost certainly not what you want.
 393
 394             # FIXME warn when $handle was explicitly specified, but not if the source is a regex or something
 395             #cluck("Not delegating method '$handle' because it is a core method") and
 396             next if $class_name->isa("Moose::Object") and $handle =~ /^BUILD|DEMOLISH$/ || Moose::Object->can($handle);
 397
 398             if ((reftype($method_to_call) || '') eq 'CODE') {
 399                 $associated_class->add_method($handle => subname $name, $method_to_call);
 400             }
 401             else {
 402                 $associated_class->add_method($handle => subname $name, sub {
 403                     my $proxy = (shift)->$accessor();
 404                     @_ = ($proxy, @_);
 405                     (defined $proxy)
 406                         || confess "Cannot delegate $handle to $method_to_call because " .
 407                                    "the value of " . $self->name . " is not defined";
 408                     goto &{ $proxy->can($method_to_call) || return };
 409                 });
 410             }
 411         }
 412     }
 413
 414     return;
 415 }
 416
 417 # private methods to help delegation ...
 418
 419 sub _canonicalize_handles {
 420     my $self    = shift;
 421     my $handles = $self->handles;
 422     if (my $handle_type = ref($handles)) {
 423         if ($handle_type eq 'HASH') {
 424             return %{$handles};
 425         }
 426         elsif ($handle_type eq 'ARRAY') {
 427             return map { $_ => $_ } @{$handles};
 428         }
 429         elsif ($handle_type eq 'Regexp') {
 430             ($self->has_type_constraint)
 431                 || confess "Cannot delegate methods based on a RegExpr without a type constraint (isa)";
 432             return map  { ($_ => $_) }
 433                    grep { /$handles/ } $self->_get_delegate_method_list;
 434         }
 435         elsif ($handle_type eq 'CODE') {
 436             return $handles->($self, $self->_find_delegate_metaclass);
 437         }
 438         else {
 439             confess "Unable to canonicalize the 'handles' option with $handles";
 440         }
 441     }
 442     else {
 443         my $role_meta = eval { $handles->meta };
 444         if ($@) {
 445             confess "Unable to canonicalize the 'handles' option with $handles because : $@";
 446         }
 447
 448         (blessed $role_meta && $role_meta->isa('Moose::Meta::Role'))
 449             || confess "Unable to canonicalize the 'handles' option with $handles because ->meta is not a Moose::Meta::Role";
 450
 451         return map { $_ => $_ } (
 452             $role_meta->get_method_list,
 453             $role_meta->get_required_method_list
 454         );
 455     }
 456 }
 457
 458 sub _find_delegate_metaclass {
 459     my $self = shift;
 460     if (my $class = $self->_isa_metadata) {
 461         # if the class does have
 462         # a meta method, use it
 463         return $class->meta if $class->can('meta');
 464         # otherwise we might be
 465         # dealing with a non-Moose
 466         # class, and need to make
 467         # our own metaclass
 468         return Moose::Meta::Class->initialize($class);
 469     }
 470     elsif (my $role = $self->_does_metadata) {
 471         # our role will always have
 472         # a meta method
 473         return $role->meta;
 474     }
 475     else {
 476         confess "Cannot find delegate metaclass for attribute " . $self->name;
 477     }
 478 }
 479
 480 sub _get_delegate_method_list {
 481     my $self = shift;
 482     my $meta = $self->_find_delegate_metaclass;
 483     if ($meta->isa('Class::MOP::Class')) {
 484         return map  { $_->{name}                     }  # NOTE: !never! delegate &meta
 485                grep { $_->{class} ne 'Moose::Object' && $_->{name} ne 'meta' }
 486                     $meta->compute_all_applicable_methods;
 487     }
 488     elsif ($meta->isa('Moose::Meta::Role')) {
 489         return $meta->get_method_list;
 490     }
 491     else {
 492         confess "Unable to recognize the delegate metaclass '$meta'";
 493     }
 494 }
 495
 496 1;
 497
 498 __END__
 499
 500 =pod
 501
 502 =head1 NAME
 503
 504 Moose::Meta::Attribute - The Moose attribute metaclass
 505
 506 =head1 DESCRIPTION
 507
 508 This is a subclass of L<Class::MOP::Attribute> with Moose specific
 509 extensions.
 510
 511 For the most part, the only time you will ever encounter an
 512 instance of this class is if you are doing some serious deep
 513 introspection. To really understand this class, you need to refer
 514 to the L<Class::MOP::Attribute> documentation.
 515
 516 =head1 METHODS
 517
 518 =head2 Overridden methods
 519
 520 These methods override methods in L<Class::MOP::Attribute> and add
 521 Moose specific features. You can safely assume though that they
 522 will behave just as L<Class::MOP::Attribute> does.
 523
 524 =over 4
 525
 526 =item B<new>
 527
 528 =item B<initialize_instance_slot>
 529
 530 =item B<install_accessors>
 531
 532 =item B<accessor_metaclass>
 533
 534 =item B<get_value>
 535
 536 =item B<set_value>
 537
 538   eval { $point->meta->get_attribute('x')->set_value($point, 'fourty-two') };
 539   if($@) {
 540     print "Oops: $@\n";
 541   }
 542
 543 I<Attribute (x) does not pass the type constraint (Int) with 'fourty-two'>
 544
 545 Before setting the value, a check is made on the type constraint of
 546 the attribute, if it has one, to see if the value passes it. If the
 547 value fails to pass, the set operation dies with a L<Carp/confess>.
 548
 549 Any coercion to convert values is done before checking the type constraint.
 550
 551 To check a value against a type constraint before setting it, fetch the
 552 attribute instance using L<Class::MOP::Class/find_attribute_by_name>,
 553 fetch the type_constraint from the attribute using L<Moose::Meta::Attribute/type_constraint>
 554 and call L<Moose::Meta::TypeConstraint/check>. See L<Moose::Cookbook::RecipeX>
 555 for an example.
 556
 557 =back
 558
 559 =head2 Additional Moose features
 560
 561 Moose attributes support type-constraint checking, weak reference
 562 creation and type coercion.
 563
 564 =over 4
 565
 566 =item B<clone_and_inherit_options>
 567
 568 This is to support the C<has '+foo'> feature, it clones an attribute
 569 from a superclass and allows a very specific set of changes to be made
 570 to the attribute.
 571
 572 =item B<has_type_constraint>
 573
 574 Returns true if this meta-attribute has a type constraint.
 575
 576 =item B<type_constraint>
 577
 578 A read-only accessor for this meta-attribute's type constraint. For
 579 more information on what you can do with this, see the documentation
 580 for L<Moose::Meta::TypeConstraint>.
 581
 582 =item B<has_handles>
 583
 584 Returns true if this meta-attribute performs delegation.
 585
 586 =item B<handles>
 587
 588 This returns the value which was passed into the handles option.
 589
 590 =item B<is_weak_ref>
 591
 592 Returns true if this meta-attribute produces a weak reference.
 593
 594 =item B<is_required>
 595
 596 Returns true if this meta-attribute is required to have a value.
 597
 598 =item B<is_lazy>
 599
 600 Returns true if this meta-attribute should be initialized lazily.
 601
 602 NOTE: lazy attributes, B<must> have a C<default> or C<builder> field set.
 603
 604 =item B<is_lazy_build>
 605
 606 Returns true if this meta-attribute should be initialized lazily through
 607 the builder generated by lazy_build. Using C<lazy_build =E<gt> 1> will
 608 make your attribute required and lazy. In addition it will set the builder, clearer
 609 and predicate options for you using the following convention.
 610
 611    #If your attribute name starts with an underscore:
 612    has '_foo' => (lazy_build => 1);
 613    #is the same as
 614    has '_foo' => (lazy => 1, required => 1, predicate => '_has_foo', clearer => '_clear_foo', builder => '_build__foo);
 615    # or
 616    has '_foo' => (lazy => 1, required => 1, predicate => '_has_foo', clearer => '_clear_foo', default => sub{shift->_build__foo});
 617
 618    #If your attribute name does not start with an underscore:
 619    has 'foo' => (lazy_build => 1);
 620    #is the same as
 621    has 'foo' => (lazy => 1, required => 1, predicate => 'has_foo', clearer => 'clear_foo', builder => '_build_foo);
 622    # or
 623    has 'foo' => (lazy => 1, required => 1, predicate => 'has_foo', clearer => 'clear_foo', default => sub{shift->_build_foo});
 624
 625 The reason for the different naming of the C<builder> is that the C<builder>
 626 method is a private method while the C<clearer> and C<predicate> methods
 627 are public methods.
 628
 629 NOTE: This means your class should provide a method whose name matches the value
 630 of the builder part, in this case _build__foo or _build_foo.
 631
 632 =item B<should_coerce>
 633
 634 Returns true if this meta-attribute should perform type coercion.
 635
 636 =item B<should_auto_deref>
 637
 638 Returns true if this meta-attribute should perform automatic
 639 auto-dereferencing.
 640
 641 NOTE: This can only be done for attributes whose type constraint is
 642 either I<ArrayRef> or I<HashRef>.
 643
 644 =item B<has_trigger>
 645
 646 Returns true if this meta-attribute has a trigger set.
 647
 648 =item B<trigger>
 649
 650 This is a CODE reference which will be executed every time the
 651 value of an attribute is assigned. The CODE ref will get two values,
 652 the invocant and the new value. This can be used to handle I<basic>
 653 bi-directional relations.
 654
 655 =item B<documentation>
 656
 657 This is a string which contains the documentation for this attribute.
 658 It serves no direct purpose right now, but it might in the future
 659 in some kind of automated documentation system perhaps.
 660
 661 =item B<has_documentation>
 662
 663 Returns true if this meta-attribute has any documentation.
 664
 665 =back
 666
 667 =head1 BUGS
 668
 669 All complex software has bugs lurking in it, and this module is no
 670 exception. If you find a bug please either email me, or add the bug
 671 to cpan-RT.
 672
 673 =head1 AUTHOR
 674
 675 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 676
 677 Yuval Kogman E<lt>nothingmuch@woobling.comE<gt>
 678
 679 =head1 COPYRIGHT AND LICENSE
 680
 681 Copyright 2006-2008 by Infinity Interactive, Inc.
 682
 683 L<http://www.iinteractive.com>
 684
 685 This library is free software; you can redistribute it and/or modify
 686 it under the same terms as Perl itself.
 687
 688 =cut