2 package Class::MOP::Attribute;
7 use Class::MOP::Method::Accessor;
10 use Scalar::Util 'blessed', 'weaken';
13 use base 'Class::MOP::Object', 'Class::MOP::Mixin::AttributeCore';
15 # NOTE: (meta-circularity)
16 # This method will be replaced in the
17 # boostrap section of Class::MOP, by
18 # a new version which uses the
19 # &Class::MOP::Class::construct_instance
20 # method to build an attribute meta-object
21 # which itself is described with attribute
23 # - Ain't meta-circularity grand? :)
25 my ( $class, @args ) = @_;
27 unshift @args, "name" if @args % 2 == 1;
30 my $name = $options{name};
33 || confess "You must provide a name for the attribute";
35 $options{init_arg} = $name
36 if not exists $options{init_arg};
37 if(exists $options{builder}){
38 confess("builder must be a defined scalar value which is a method name")
39 if ref $options{builder} || !(defined $options{builder});
40 confess("Setting both default and builder is not allowed.")
41 if exists $options{default};
43 ($class->is_default_a_coderef(\%options))
44 || confess("References are not allowed as default values, you must ".
45 "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
46 if exists $options{default} && ref $options{default};
48 if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) {
49 confess("A required attribute must have either 'init_arg', 'builder', or 'default'");
52 $class->_new(\%options);
58 return Class::MOP::Class->initialize($class)->new_object(@_)
59 if $class ne __PACKAGE__;
61 my $options = @_ == 1 ? $_[0] : {@_};
64 'name' => $options->{name},
65 'accessor' => $options->{accessor},
66 'reader' => $options->{reader},
67 'writer' => $options->{writer},
68 'predicate' => $options->{predicate},
69 'clearer' => $options->{clearer},
70 'builder' => $options->{builder},
71 'init_arg' => $options->{init_arg},
72 exists $options->{default}
73 ? ('default' => $options->{default})
75 'initializer' => $options->{initializer},
76 'definition_context' => $options->{definition_context},
77 # keep a weakened link to the
78 # class we are associated with
79 'associated_class' => undef,
80 # and a list of the methods
81 # associated with this attr
82 'associated_methods' => [],
83 # this let's us keep track of
84 # our order inside the associated
86 'insertion_order' => undef,
91 # this is a primative (and kludgy) clone operation
92 # for now, it will be replaced in the Class::MOP
93 # bootstrap with a proper one, however we know
94 # that this one will work fine for now.
99 || confess "Can only clone an instance";
100 return bless { %{$self}, %options } => ref($self);
103 sub initialize_instance_slot {
104 my ($self, $meta_instance, $instance, $params) = @_;
105 my $init_arg = $self->{'init_arg'};
107 # try to fetch the init arg from the %params ...
109 # if nothing was in the %params, we can use the
110 # attribute's default value (if it has one)
111 if(defined $init_arg and exists $params->{$init_arg}){
112 $self->_set_initial_slot_value(
115 $params->{$init_arg},
118 elsif (exists $self->{'default'}) {
119 $self->_set_initial_slot_value(
122 $self->default($instance),
125 elsif (defined( my $builder = $self->{'builder'})) {
126 if ($builder = $instance->can($builder)) {
127 $self->_set_initial_slot_value(
134 confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
139 sub _set_initial_slot_value {
140 my ($self, $meta_instance, $instance, $value) = @_;
142 my $slot_name = $self->name;
144 return $meta_instance->set_slot_value($instance, $slot_name, $value)
145 unless $self->has_initializer;
147 my $callback = $self->_make_initializer_writer_callback(
148 $meta_instance, $instance, $slot_name
151 my $initializer = $self->initializer;
153 # most things will just want to set a value, so make it first arg
154 $instance->$initializer($value, $callback, $self);
157 sub _make_initializer_writer_callback {
159 my ($meta_instance, $instance, $slot_name) = @_;
162 $meta_instance->set_slot_value($instance, $slot_name, $_[0]);
166 sub get_read_method {
168 my $reader = $self->reader || $self->accessor;
170 return $reader unless ref $reader;
172 my ($name) = %$reader;
176 sub get_write_method {
178 my $writer = $self->writer || $self->accessor;
180 return $writer unless ref $writer;
182 my ($name) = %$writer;
186 sub get_read_method_ref {
188 if ((my $reader = $self->get_read_method) && $self->associated_class) {
189 return $self->associated_class->get_method($reader);
192 my $code = sub { $self->get_value(@_) };
193 if (my $class = $self->associated_class) {
194 return $class->method_metaclass->wrap(
196 package_name => $class->name,
206 sub get_write_method_ref {
208 if ((my $writer = $self->get_write_method) && $self->associated_class) {
209 return $self->associated_class->get_method($writer);
212 my $code = sub { $self->set_value(@_) };
213 if (my $class = $self->associated_class) {
214 return $class->method_metaclass->wrap(
216 package_name => $class->name,
228 sub slots { (shift)->name }
232 sub attach_to_class {
233 my ($self, $class) = @_;
234 (blessed($class) && $class->isa('Class::MOP::Class'))
235 || confess "You must pass a Class::MOP::Class instance (or a subclass)";
236 weaken($self->{'associated_class'} = $class);
239 sub detach_from_class {
241 $self->{'associated_class'} = undef;
246 sub associate_method {
247 my ($self, $method) = @_;
248 push @{$self->{'associated_methods'}} => $method;
253 sub set_initial_value {
254 my ($self, $instance, $value) = @_;
255 $self->_set_initial_slot_value(
256 Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
262 sub set_value { shift->set_raw_value(@_) }
266 my ($instance, $value) = @_;
268 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
269 return $mi->set_slot_value($instance, $self->name, $value);
272 sub _inline_set_value {
274 return $self->_inline_instance_set(@_) . ';';
277 sub _inline_instance_set {
279 my ($instance, $value) = @_;
281 my $mi = $self->associated_class->get_meta_instance;
282 return $mi->inline_set_slot_value($instance, $self->name, $value);
285 sub get_value { shift->get_raw_value(@_) }
291 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
292 return $mi->get_slot_value($instance, $self->name);
295 sub _inline_get_value {
297 return $self->_inline_instance_get(@_) . ';';
300 sub _inline_instance_get {
304 my $mi = $self->associated_class->get_meta_instance;
305 return $mi->inline_get_slot_value($instance, $self->name);
312 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
313 return $mi->is_slot_initialized($instance, $self->name);
316 sub _inline_has_value {
318 return $self->_inline_instance_has(@_) . ';';
321 sub _inline_instance_has {
325 my $mi = $self->associated_class->get_meta_instance;
326 return $mi->inline_is_slot_initialized($instance, $self->name);
333 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
334 return $mi->deinitialize_slot($instance, $self->name);
337 sub _inline_clear_value {
339 return $self->_inline_instance_clear(@_) . ';';
342 sub _inline_instance_clear {
346 my $mi = $self->associated_class->get_meta_instance;
347 return $mi->inline_deinitialize_slot($instance, $self->name);
352 sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
354 sub _process_accessors {
355 my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
357 my $method_ctx = { %{ $self->definition_context || {} } };
359 if (ref($accessor)) {
360 (ref($accessor) eq 'HASH')
361 || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
362 my ($name, $method) = %{$accessor};
364 $method_ctx->{description} = $self->_accessor_description($name, $type);
366 $method = $self->accessor_metaclass->wrap(
369 package_name => $self->associated_class->name,
371 associated_metaclass => $self->associated_class,
372 definition_context => $method_ctx,
374 $self->associate_method($method);
375 return ($name, $method);
378 my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
381 $method_ctx->{description} = $self->_accessor_description($accessor, $type);
383 $method = $self->accessor_metaclass->new(
385 is_inline => $inline_me,
386 accessor_type => $type,
387 package_name => $self->associated_class->name,
389 associated_metaclass => $self->associated_class,
390 definition_context => $method_ctx,
394 confess "Could not create the '$type' method for " . $self->name . " because : $_";
396 $self->associate_method($method);
397 return ($accessor, $method);
401 sub _accessor_description {
403 my ($name, $type) = @_;
405 my $desc = "$type " . $self->associated_class->name . "::$name";
406 if ( $name ne $self->name ) {
407 $desc .= " of attribute " . $self->name;
413 sub install_accessors {
416 my $class = $self->associated_class;
419 $self->_process_accessors('accessor' => $self->accessor(), $inline)
420 ) if $self->has_accessor();
423 $self->_process_accessors('reader' => $self->reader(), $inline)
424 ) if $self->has_reader();
427 $self->_process_accessors('writer' => $self->writer(), $inline)
428 ) if $self->has_writer();
431 $self->_process_accessors('predicate' => $self->predicate(), $inline)
432 ) if $self->has_predicate();
435 $self->_process_accessors('clearer' => $self->clearer(), $inline)
436 ) if $self->has_clearer();
442 my $_remove_accessor = sub {
443 my ($accessor, $class) = @_;
444 if (ref($accessor) && ref($accessor) eq 'HASH') {
445 ($accessor) = keys %{$accessor};
447 my $method = $class->get_method($accessor);
448 $class->remove_method($accessor)
449 if (ref($method) && $method->isa('Class::MOP::Method::Accessor'));
452 sub remove_accessors {
455 # we really need to make sure to remove from the
456 # associates methods here as well. But this is
457 # such a slimly used method, I am not worried
458 # about it right now.
459 $_remove_accessor->($self->accessor(), $self->associated_class()) if $self->has_accessor();
460 $_remove_accessor->($self->reader(), $self->associated_class()) if $self->has_reader();
461 $_remove_accessor->($self->writer(), $self->associated_class()) if $self->has_writer();
462 $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate();
463 $_remove_accessor->($self->clearer(), $self->associated_class()) if $self->has_clearer();
471 # ABSTRACT: Attribute Meta Object
479 Class::MOP::Attribute->new(
481 accessor => 'foo', # dual purpose get/set accessor
482 predicate => 'has_foo', # predicate check for defined-ness
483 init_arg => '-foo', # class->new will look for a -foo key
484 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
488 Class::MOP::Attribute->new(
490 reader => 'bar', # getter
491 writer => 'set_bar', # setter
492 predicate => 'has_bar', # predicate check for defined-ness
493 init_arg => ':bar', # class->new will look for a :bar key
494 # no default value means it is undef
500 The Attribute Protocol is almost entirely an invention of
501 C<Class::MOP>. Perl 5 does not have a consistent notion of
502 attributes. There are so many ways in which this is done, and very few
503 (if any) are easily discoverable by this module.
505 With that said, this module attempts to inject some order into this
506 chaos, by introducing a consistent API which can be used to create
515 =item B<< Class::MOP::Attribute->new($name, ?%options) >>
517 An attribute must (at the very least), have a C<$name>. All other
518 C<%options> are added as key-value pairs.
524 This is a string value representing the expected key in an
525 initialization hash. For instance, if we have an C<init_arg> value of
526 C<-foo>, then the following code will Just Work.
528 MyClass->meta->new_object( -foo => 'Hello There' );
530 If an init_arg is not assigned, it will automatically use the
531 attribute's name. If C<init_arg> is explicitly set to C<undef>, the
532 attribute cannot be specified during initialization.
536 This provides the name of a method that will be called to initialize
537 the attribute. This method will be called on the object after it is
538 constructed. It is expected to return a valid value for the attribute.
542 This can be used to provide an explicit default for initializing the
543 attribute. If the default you provide is a subroutine reference, then
544 this reference will be called I<as a method> on the object.
546 If the value is a simple scalar (string or number), then it can be
547 just passed as is. However, if you wish to initialize it with a HASH
548 or ARRAY ref, then you need to wrap that inside a subroutine
551 Class::MOP::Attribute->new(
553 default => sub { [] },
559 Class::MOP::Attribute->new(
561 default => sub { {} },
565 If you wish to initialize an attribute with a subroutine reference
566 itself, then you need to wrap that in a subroutine as well:
568 Class::MOP::Attribute->new(
571 sub { print "Hello World" }
576 And lastly, if the value of your attribute is dependent upon some
577 other aspect of the instance structure, then you can take advantage of
578 the fact that when the C<default> value is called as a method:
580 Class::MOP::Attribute->new(
581 'object_identity' => (
582 default => sub { Scalar::Util::refaddr( $_[0] ) },
586 Note that there is no guarantee that attributes are initialized in any
587 particular order, so you cannot rely on the value of some other
588 attribute when generating the default.
592 This option can be either a method name or a subroutine
593 reference. This method will be called when setting the attribute's
594 value in the constructor. Unlike C<default> and C<builder>, the
595 initializer is only called when a value is provided to the
596 constructor. The initializer allows you to munge this value during
599 The initializer is called as a method with three arguments. The first
600 is the value that was passed to the constructor. The second is a
601 subroutine reference that can be called to actually set the
602 attribute's value, and the last is the associated
603 C<Class::MOP::Attribute> object.
605 This contrived example shows an initializer that sets the attribute to
606 twice the given value.
608 Class::MOP::Attribute->new(
611 my ( $self, $value, $set, $attr ) = @_;
612 $set->( $value * 2 );
617 Since an initializer can be a method name, you can easily make
618 attribute initialization use the writer:
620 Class::MOP::Attribute->new(
622 writer => 'some_attr',
623 initializer => 'some_attr',
627 Your writer (actually, a wrapper around the writer, using
628 L<method modifications|Moose::Manual::MethodModifiers>) will need to examine
629 C<@_> and determine under which
630 context it is being called:
632 around 'some_attr' => sub {
635 # $value is not defined if being called as a reader
636 # $setter and $attr are only defined if being called as an initializer
637 my ($value, $setter, $attr) = @_;
639 # the reader behaves normally
640 return $self->$orig if not @_;
642 # mutate $value as desired
643 # $value = <something($value);
645 # if called as an initializer, set the value and we're done
646 return $setter->($row) if $setter;
648 # otherwise, call the real writer with the new value
655 The C<accessor>, C<reader>, C<writer>, C<predicate> and C<clearer>
656 options all accept the same parameters. You can provide the name of
657 the method, in which case an appropriate default method will be
658 generated for you. Or instead you can also provide hash reference
659 containing exactly one key (the method name) and one value. The value
660 should be a subroutine reference, which will be installed as the
667 An C<accessor> is a standard Perl-style read/write accessor. It will
668 return the value of the attribute, and if a value is passed as an
669 argument, it will assign that value to the attribute.
671 Note that C<undef> is a legitimate value, so this will work:
673 $object->set_something(undef);
677 This is a basic read-only accessor. It returns the value of the
682 This is a basic write accessor, it accepts a single argument, and
683 assigns that value to the attribute.
685 Note that C<undef> is a legitimate value, so this will work:
687 $object->set_something(undef);
691 The predicate method returns a boolean indicating whether or not the
692 attribute has been explicitly set.
694 Note that the predicate returns true even if the attribute was set to
695 a false value (C<0> or C<undef>).
699 This method will uninitialize the attribute. After an attribute is
700 cleared, its C<predicate> will return false.
702 =item * definition_context
704 Mostly, this exists as a hook for the benefit of Moose.
706 This option should be a hash reference containing several keys which
707 will be used when inlining the attribute's accessors. The keys should
708 include C<line>, the line number where the attribute was created, and
709 either C<file> or C<description>.
711 This information will ultimately be used when eval'ing inlined
712 accessor code so that error messages report a useful line and file
717 =item B<< $attr->clone(%options) >>
719 This clones the attribute. Any options you provide will override the
720 settings of the original attribute. You can change the name of the new
721 attribute by passing a C<name> key in C<%options>.
727 These are all basic read-only accessors for the values passed into
732 =item B<< $attr->name >>
734 Returns the attribute's name.
736 =item B<< $attr->accessor >>
738 =item B<< $attr->reader >>
740 =item B<< $attr->writer >>
742 =item B<< $attr->predicate >>
744 =item B<< $attr->clearer >>
746 The C<accessor>, C<reader>, C<writer>, C<predicate>, and C<clearer>
747 methods all return exactly what was passed to the constructor, so it
748 can be either a string containing a method name, or a hash reference.
750 =item B<< $attr->initializer >>
752 Returns the initializer as passed to the constructor, so this may be
753 either a method name or a subroutine reference.
755 =item B<< $attr->init_arg >>
757 =item B<< $attr->is_default_a_coderef >>
759 =item B<< $attr->builder >>
761 =item B<< $attr->default($instance) >>
763 The C<$instance> argument is optional. If you don't pass it, the
764 return value for this method is exactly what was passed to the
765 constructor, either a simple scalar or a subroutine reference.
767 If you I<do> pass an C<$instance> and the default is a subroutine
768 reference, then the reference is called as a method on the
769 C<$instance> and the generated value is returned.
771 =item B<< $attr->slots >>
773 Return a list of slots required by the attribute. This is usually just
774 one, the name of the attribute.
776 A slot is the name of the hash key used to store the attribute in an
779 =item B<< $attr->get_read_method >>
781 =item B<< $attr->get_write_method >>
783 Returns the name of a method suitable for reading or writing the value
784 of the attribute in the associated class.
786 If an attribute is read- or write-only, then these methods can return
787 C<undef> as appropriate.
789 =item B<< $attr->has_read_method >>
791 =item B<< $attr->has_write_method >>
793 This returns a boolean indicating whether the attribute has a I<named>
794 read or write method.
796 =item B<< $attr->get_read_method_ref >>
798 =item B<< $attr->get_write_method_ref >>
800 Returns the subroutine reference of a method suitable for reading or
801 writing the attribute's value in the associated class. These methods
802 always return a subroutine reference, regardless of whether or not the
803 attribute is read- or write-only.
805 =item B<< $attr->insertion_order >>
807 If this attribute has been inserted into a class, this returns a zero
808 based index regarding the order of insertion.
812 =head2 Informational predicates
814 These are all basic predicate methods for the values passed into C<new>.
818 =item B<< $attr->has_accessor >>
820 =item B<< $attr->has_reader >>
822 =item B<< $attr->has_writer >>
824 =item B<< $attr->has_predicate >>
826 =item B<< $attr->has_clearer >>
828 =item B<< $attr->has_initializer >>
830 =item B<< $attr->has_init_arg >>
832 This will be I<false> if the C<init_arg> was set to C<undef>.
834 =item B<< $attr->has_default >>
836 This will be I<false> if the C<default> was set to C<undef>, since
837 C<undef> is the default C<default> anyway.
839 =item B<< $attr->has_builder >>
841 =item B<< $attr->has_insertion_order >>
843 This will be I<false> if this attribute has not be inserted into a class
847 =head2 Value management
849 These methods are basically "back doors" to the instance, and can be
850 used to bypass the regular accessors, but still stay within the MOP.
852 These methods are not for general use, and should only be used if you
853 really know what you are doing.
857 =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >>
859 This method is used internally to initialize the attribute's slot in
860 the object C<$instance>.
862 The C<$params> is a hash reference of the values passed to the object
865 It's unlikely that you'll need to call this method yourself.
867 =item B<< $attr->set_value($instance, $value) >>
869 Sets the value without going through the accessor. Note that this
870 works even with read-only attributes.
872 =item B<< $attr->set_raw_value($instance, $value) >>
874 Sets the value with no side effects such as a trigger.
876 This doesn't actually apply to Class::MOP attributes, only to subclasses.
878 =item B<< $attr->set_initial_value($instance, $value) >>
880 Sets the value without going through the accessor. This method is only
881 called when the instance is first being initialized.
883 =item B<< $attr->get_value($instance) >>
885 Returns the value without going through the accessor. Note that this
886 works even with write-only accessors.
888 =item B<< $attr->get_raw_value($instance) >>
890 Returns the value without any side effects such as lazy attributes.
892 Doesn't actually apply to Class::MOP attributes, only to subclasses.
894 =item B<< $attr->has_value($instance) >>
896 Return a boolean indicating whether the attribute has been set in
897 C<$instance>. This how the default C<predicate> method works.
899 =item B<< $attr->clear_value($instance) >>
901 This will clear the attribute's value in C<$instance>. This is what
902 the default C<clearer> calls.
904 Note that this works even if the attribute does not have any
905 associated read, write or clear methods.
909 =head2 Class association
911 These methods allow you to manage the attributes association with
912 the class that contains it. These methods should not be used
913 lightly, nor are they very magical, they are mostly used internally
914 and by metaclass instances.
918 =item B<< $attr->associated_class >>
920 This returns the C<Class::MOP::Class> with which this attribute is
923 =item B<< $attr->attach_to_class($metaclass) >>
925 This method stores a weakened reference to the C<$metaclass> object
928 This method does not remove the attribute from its old class,
929 nor does it create any accessors in the new class.
931 It is probably best to use the L<Class::MOP::Class> C<add_attribute>
934 =item B<< $attr->detach_from_class >>
936 This method removes the associate metaclass object from the attribute
939 This method does not remove the attribute itself from the class, or
940 remove its accessors.
942 It is probably best to use the L<Class::MOP::Class>
943 C<remove_attribute> method instead.
947 =head2 Attribute Accessor generation
951 =item B<< $attr->accessor_metaclass >>
953 Accessor methods are generated using an accessor metaclass. By
954 default, this is L<Class::MOP::Method::Accessor>. This method returns
955 the name of the accessor metaclass that this attribute uses.
957 =item B<< $attr->associate_method($method) >>
959 This associates a L<Class::MOP::Method> object with the
960 attribute. Typically, this is called internally when an attribute
961 generates its accessors.
963 =item B<< $attr->associated_methods >>
965 This returns the list of methods which have been associated with the
968 =item B<< $attr->install_accessors >>
970 This method generates and installs code the attributes various
971 accessors. It is typically called from the L<Class::MOP::Class>
972 C<add_attribute> method.
974 =item B<< $attr->remove_accessors >>
976 This method removes all of the accessors associated with the
979 This does not currently remove methods from the list returned by
980 C<associated_methods>.
982 =item B<< $attr->inline_get >>
984 =item B<< $attr->inline_set >>
986 =item B<< $attr->inline_has >>
988 =item B<< $attr->inline_clear >>
990 These methods return a code snippet suitable for inlining the relevant
991 operation. They expect strings containing variable names to be used in the
992 inlining, like C<'$self'> or C<'$_[1]'>.
1000 =item B<< Class::MOP::Attribute->meta >>
1002 This will return a L<Class::MOP::Class> instance for this class.
1004 It should also be noted that L<Class::MOP> will actually bootstrap
1005 this module by installing a number of attribute meta-objects into its