2 package Class::MOP::Attribute;
7 use Class::MOP::Method::Accessor;
10 use Scalar::Util 'blessed', 'weaken';
13 our $VERSION = '1.11';
14 $VERSION = eval $VERSION;
15 our $AUTHORITY = 'cpan:STEVAN';
17 use base 'Class::MOP::Object', 'Class::MOP::Mixin::AttributeCore';
19 # NOTE: (meta-circularity)
20 # This method will be replaced in the
21 # boostrap section of Class::MOP, by
22 # a new version which uses the
23 # &Class::MOP::Class::construct_instance
24 # method to build an attribute meta-object
25 # which itself is described with attribute
27 # - Ain't meta-circularity grand? :)
29 my ( $class, @args ) = @_;
31 unshift @args, "name" if @args % 2 == 1;
34 my $name = $options{name};
37 || confess "You must provide a name for the attribute";
39 $options{init_arg} = $name
40 if not exists $options{init_arg};
41 if(exists $options{builder}){
42 confess("builder must be a defined scalar value which is a method name")
43 if ref $options{builder} || !(defined $options{builder});
44 confess("Setting both default and builder is not allowed.")
45 if exists $options{default};
47 ($class->is_default_a_coderef(\%options))
48 || confess("References are not allowed as default values, you must ".
49 "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
50 if exists $options{default} && ref $options{default};
52 if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) {
53 confess("A required attribute must have either 'init_arg', 'builder', or 'default'");
56 $class->_new(\%options);
62 return Class::MOP::Class->initialize($class)->new_object(@_)
63 if $class ne __PACKAGE__;
65 my $options = @_ == 1 ? $_[0] : {@_};
68 'name' => $options->{name},
69 'accessor' => $options->{accessor},
70 'reader' => $options->{reader},
71 'writer' => $options->{writer},
72 'predicate' => $options->{predicate},
73 'clearer' => $options->{clearer},
74 'builder' => $options->{builder},
75 'init_arg' => $options->{init_arg},
76 exists $options->{default}
77 ? ('default' => $options->{default})
79 'initializer' => $options->{initializer},
80 'definition_context' => $options->{definition_context},
81 # keep a weakened link to the
82 # class we are associated with
83 'associated_class' => undef,
84 # and a list of the methods
85 # associated with this attr
86 'associated_methods' => [],
87 # this let's us keep track of
88 # our order inside the associated
90 'insertion_order' => undef,
95 # this is a primative (and kludgy) clone operation
96 # for now, it will be replaced in the Class::MOP
97 # bootstrap with a proper one, however we know
98 # that this one will work fine for now.
103 || confess "Can only clone an instance";
104 return bless { %{$self}, %options } => ref($self);
107 sub initialize_instance_slot {
108 my ($self, $meta_instance, $instance, $params) = @_;
109 my $init_arg = $self->{'init_arg'};
111 # try to fetch the init arg from the %params ...
113 # if nothing was in the %params, we can use the
114 # attribute's default value (if it has one)
115 if(defined $init_arg and exists $params->{$init_arg}){
116 $self->_set_initial_slot_value(
119 $params->{$init_arg},
122 elsif (exists $self->{'default'}) {
123 $self->_set_initial_slot_value(
126 $self->default($instance),
129 elsif (defined( my $builder = $self->{'builder'})) {
130 if ($builder = $instance->can($builder)) {
131 $self->_set_initial_slot_value(
138 confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
143 sub _set_initial_slot_value {
144 my ($self, $meta_instance, $instance, $value) = @_;
146 my $slot_name = $self->name;
148 return $meta_instance->set_slot_value($instance, $slot_name, $value)
149 unless $self->has_initializer;
152 $meta_instance->set_slot_value($instance, $slot_name, $_[0]);
155 my $initializer = $self->initializer;
157 # most things will just want to set a value, so make it first arg
158 $instance->$initializer($value, $callback, $self);
161 sub get_read_method {
163 my $reader = $self->reader || $self->accessor;
165 return $reader unless ref $reader;
167 my ($name) = %$reader;
171 sub get_write_method {
173 my $writer = $self->writer || $self->accessor;
175 return $writer unless ref $writer;
177 my ($name) = %$writer;
181 sub get_read_method_ref {
183 if ((my $reader = $self->get_read_method) && $self->associated_class) {
184 return $self->associated_class->get_method($reader);
187 my $code = sub { $self->get_value(@_) };
188 if (my $class = $self->associated_class) {
189 return $class->method_metaclass->wrap(
191 package_name => $class->name,
201 sub get_write_method_ref {
203 if ((my $writer = $self->get_write_method) && $self->associated_class) {
204 return $self->associated_class->get_method($writer);
207 my $code = sub { $self->set_value(@_) };
208 if (my $class = $self->associated_class) {
209 return $class->method_metaclass->wrap(
211 package_name => $class->name,
223 sub slots { (shift)->name }
227 sub attach_to_class {
228 my ($self, $class) = @_;
229 (blessed($class) && $class->isa('Class::MOP::Class'))
230 || confess "You must pass a Class::MOP::Class instance (or a subclass)";
231 weaken($self->{'associated_class'} = $class);
234 sub detach_from_class {
236 $self->{'associated_class'} = undef;
241 sub associate_method {
242 my ($self, $method) = @_;
243 push @{$self->{'associated_methods'}} => $method;
248 sub set_initial_value {
249 my ($self, $instance, $value) = @_;
250 $self->_set_initial_slot_value(
251 Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
257 sub set_value { shift->set_raw_value(@_) }
261 my ($instance, $value) = @_;
263 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
264 return $mi->set_slot_value($instance, $self->name, $value);
267 sub _inline_set_value {
269 return $self->_inline_instance_set(@_) . ';';
272 sub _inline_instance_set {
274 my ($instance, $value) = @_;
276 my $mi = $self->associated_class->get_meta_instance;
277 return $mi->inline_set_slot_value($instance, $self->name, $value);
280 sub get_value { shift->get_raw_value(@_) }
286 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
287 return $mi->get_slot_value($instance, $self->name);
290 sub _inline_get_value {
292 return $self->_inline_instance_get(@_) . ';';
295 sub _inline_instance_get {
299 my $mi = $self->associated_class->get_meta_instance;
300 return $mi->inline_get_slot_value($instance, $self->name);
307 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
308 return $mi->is_slot_initialized($instance, $self->name);
311 sub _inline_has_value {
313 return $self->_inline_instance_has(@_) . ';';
316 sub _inline_instance_has {
320 my $mi = $self->associated_class->get_meta_instance;
321 return $mi->inline_is_slot_initialized($instance, $self->name);
328 my $mi = Class::MOP::Class->initialize(ref($instance))->get_meta_instance;
329 return $mi->deinitialize_slot($instance, $self->name);
332 sub _inline_clear_value {
334 return $self->_inline_instance_clear(@_) . ';';
337 sub _inline_instance_clear {
341 my $mi = $self->associated_class->get_meta_instance;
342 return $mi->inline_deinitialize_slot($instance, $self->name);
347 sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
349 sub _process_accessors {
350 my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
354 if ( my $ctx = $self->definition_context ) {
355 $method_ctx = { %$ctx };
358 if (ref($accessor)) {
359 (ref($accessor) eq 'HASH')
360 || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
361 my ($name, $method) = %{$accessor};
362 $method = $self->accessor_metaclass->wrap(
364 package_name => $self->associated_class->name,
366 definition_context => $method_ctx,
368 $self->associate_method($method);
369 return ($name, $method);
372 my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
376 my $desc = "accessor $accessor";
377 if ( $accessor ne $self->name ) {
378 $desc .= " of attribute " . $self->name;
381 $method_ctx->{description} = $desc;
384 $method = $self->accessor_metaclass->new(
386 is_inline => $inline_me,
387 accessor_type => $type,
388 package_name => $self->associated_class->name,
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 install_accessors {
404 my $class = $self->associated_class;
407 $self->_process_accessors('accessor' => $self->accessor(), $inline)
408 ) if $self->has_accessor();
411 $self->_process_accessors('reader' => $self->reader(), $inline)
412 ) if $self->has_reader();
415 $self->_process_accessors('writer' => $self->writer(), $inline)
416 ) if $self->has_writer();
419 $self->_process_accessors('predicate' => $self->predicate(), $inline)
420 ) if $self->has_predicate();
423 $self->_process_accessors('clearer' => $self->clearer(), $inline)
424 ) if $self->has_clearer();
430 my $_remove_accessor = sub {
431 my ($accessor, $class) = @_;
432 if (ref($accessor) && ref($accessor) eq 'HASH') {
433 ($accessor) = keys %{$accessor};
435 my $method = $class->get_method($accessor);
436 $class->remove_method($accessor)
437 if (ref($method) && $method->isa('Class::MOP::Method::Accessor'));
440 sub remove_accessors {
443 # we really need to make sure to remove from the
444 # associates methods here as well. But this is
445 # such a slimly used method, I am not worried
446 # about it right now.
447 $_remove_accessor->($self->accessor(), $self->associated_class()) if $self->has_accessor();
448 $_remove_accessor->($self->reader(), $self->associated_class()) if $self->has_reader();
449 $_remove_accessor->($self->writer(), $self->associated_class()) if $self->has_writer();
450 $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate();
451 $_remove_accessor->($self->clearer(), $self->associated_class()) if $self->has_clearer();
465 Class::MOP::Attribute - Attribute Meta Object
469 Class::MOP::Attribute->new(
471 accessor => 'foo', # dual purpose get/set accessor
472 predicate => 'has_foo', # predicate check for defined-ness
473 init_arg => '-foo', # class->new will look for a -foo key
474 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
478 Class::MOP::Attribute->new(
480 reader => 'bar', # getter
481 writer => 'set_bar', # setter
482 predicate => 'has_bar', # predicate check for defined-ness
483 init_arg => ':bar', # class->new will look for a :bar key
484 # no default value means it is undef
490 The Attribute Protocol is almost entirely an invention of
491 C<Class::MOP>. Perl 5 does not have a consistent notion of
492 attributes. There are so many ways in which this is done, and very few
493 (if any) are easily discoverable by this module.
495 With that said, this module attempts to inject some order into this
496 chaos, by introducing a consistent API which can be used to create
505 =item B<< Class::MOP::Attribute->new($name, ?%options) >>
507 An attribute must (at the very least), have a C<$name>. All other
508 C<%options> are added as key-value pairs.
514 This is a string value representing the expected key in an
515 initialization hash. For instance, if we have an C<init_arg> value of
516 C<-foo>, then the following code will Just Work.
518 MyClass->meta->new_object( -foo => 'Hello There' );
520 If an init_arg is not assigned, it will automatically use the
521 attribute's name. If C<init_arg> is explicitly set to C<undef>, the
522 attribute cannot be specified during initialization.
526 This provides the name of a method that will be called to initialize
527 the attribute. This method will be called on the object after it is
528 constructed. It is expected to return a valid value for the attribute.
532 This can be used to provide an explicit default for initializing the
533 attribute. If the default you provide is a subroutine reference, then
534 this reference will be called I<as a method> on the object.
536 If the value is a simple scalar (string or number), then it can be
537 just passed as is. However, if you wish to initialize it with a HASH
538 or ARRAY ref, then you need to wrap that inside a subroutine
541 Class::MOP::Attribute->new(
543 default => sub { [] },
549 Class::MOP::Attribute->new(
551 default => sub { {} },
555 If you wish to initialize an attribute with a subroutine reference
556 itself, then you need to wrap that in a subroutine as well:
558 Class::MOP::Attribute->new(
561 sub { print "Hello World" }
566 And lastly, if the value of your attribute is dependent upon some
567 other aspect of the instance structure, then you can take advantage of
568 the fact that when the C<default> value is called as a method:
570 Class::MOP::Attribute->new(
571 'object_identity' => (
572 default => sub { Scalar::Util::refaddr( $_[0] ) },
576 Note that there is no guarantee that attributes are initialized in any
577 particular order, so you cannot rely on the value of some other
578 attribute when generating the default.
582 This option can be either a method name or a subroutine
583 reference. This method will be called when setting the attribute's
584 value in the constructor. Unlike C<default> and C<builder>, the
585 initializer is only called when a value is provided to the
586 constructor. The initializer allows you to munge this value during
589 The initializer is called as a method with three arguments. The first
590 is the value that was passed to the constructor. The second is a
591 subroutine reference that can be called to actually set the
592 attribute's value, and the last is the associated
593 C<Class::MOP::Attribute> object.
595 This contrived example shows an initializer that sets the attribute to
596 twice the given value.
598 Class::MOP::Attribute->new(
601 my ( $self, $value, $set, $attr ) = @_;
602 $set->( $value * 2 );
607 Since an initializer can be a method name, you can easily make
608 attribute initialization use the writer:
610 Class::MOP::Attribute->new(
612 writer => 'some_attr',
613 initializer => 'some_attr',
617 Your writer will need to examine C<@_> and determine under which
618 context it is being called.
622 The C<accessor>, C<reader>, C<writer>, C<predicate> and C<clearer>
623 options all accept the same parameters. You can provide the name of
624 the method, in which case an appropriate default method will be
625 generated for you. Or instead you can also provide hash reference
626 containing exactly one key (the method name) and one value. The value
627 should be a subroutine reference, which will be installed as the
634 An C<accessor> is a standard Perl-style read/write accessor. It will
635 return the value of the attribute, and if a value is passed as an
636 argument, it will assign that value to the attribute.
638 Note that C<undef> is a legitimate value, so this will work:
640 $object->set_something(undef);
644 This is a basic read-only accessor. It returns the value of the
649 This is a basic write accessor, it accepts a single argument, and
650 assigns that value to the attribute.
652 Note that C<undef> is a legitimate value, so this will work:
654 $object->set_something(undef);
658 The predicate method returns a boolean indicating whether or not the
659 attribute has been explicitly set.
661 Note that the predicate returns true even if the attribute was set to
662 a false value (C<0> or C<undef>).
666 This method will uninitialize the attribute. After an attribute is
667 cleared, its C<predicate> will return false.
669 =item * definition_context
671 Mostly, this exists as a hook for the benefit of Moose.
673 This option should be a hash reference containing several keys which
674 will be used when inlining the attribute's accessors. The keys should
675 include C<line>, the line number where the attribute was created, and
676 either C<file> or C<description>.
678 This information will ultimately be used when eval'ing inlined
679 accessor code so that error messages report a useful line and file
684 =item B<< $attr->clone(%options) >>
686 This clones the attribute. Any options you provide will override the
687 settings of the original attribute. You can change the name of the new
688 attribute by passing a C<name> key in C<%options>.
694 These are all basic read-only accessors for the values passed into
699 =item B<< $attr->name >>
701 Returns the attribute's name.
703 =item B<< $attr->accessor >>
705 =item B<< $attr->reader >>
707 =item B<< $attr->writer >>
709 =item B<< $attr->predicate >>
711 =item B<< $attr->clearer >>
713 The C<accessor>, C<reader>, C<writer>, C<predicate>, and C<clearer>
714 methods all return exactly what was passed to the constructor, so it
715 can be either a string containing a method name, or a hash reference.
717 =item B<< $attr->initializer >>
719 Returns the initializer as passed to the constructor, so this may be
720 either a method name or a subroutine reference.
722 =item B<< $attr->init_arg >>
724 =item B<< $attr->is_default_a_coderef >>
726 =item B<< $attr->default($instance) >>
728 The C<$instance> argument is optional. If you don't pass it, the
729 return value for this method is exactly what was passed to the
730 constructor, either a simple scalar or a subroutine reference.
732 If you I<do> pass an C<$instance> and the default is a subroutine
733 reference, then the reference is called as a method on the
734 C<$instance> and the generated value is returned.
736 =item B<< $attr->slots >>
738 Return a list of slots required by the attribute. This is usually just
739 one, the name of the attribute.
741 A slot is the name of the hash key used to store the attribute in an
744 =item B<< $attr->get_read_method >>
746 =item B<< $attr->get_write_method >>
748 Returns the name of a method suitable for reading or writing the value
749 of the attribute in the associated class.
751 If an attribute is read- or write-only, then these methods can return
752 C<undef> as appropriate.
754 =item B<< $attr->has_read_method >>
756 =item B<< $attr->has_write_method >>
758 This returns a boolean indicating whether the attribute has a I<named>
759 read or write method.
761 =item B<< $attr->get_read_method_ref >>
763 =item B<< $attr->get_write_method_ref >>
765 Returns the subroutine reference of a method suitable for reading or
766 writing the attribute's value in the associated class. These methods
767 always return a subroutine reference, regardless of whether or not the
768 attribute is read- or write-only.
770 =item B<< $attr->insertion_order >>
772 If this attribute has been inserted into a class, this returns a zero
773 based index regarding the order of insertion.
777 =head2 Informational predicates
779 These are all basic predicate methods for the values passed into C<new>.
783 =item B<< $attr->has_accessor >>
785 =item B<< $attr->has_reader >>
787 =item B<< $attr->has_writer >>
789 =item B<< $attr->has_predicate >>
791 =item B<< $attr->has_clearer >>
793 =item B<< $attr->has_initializer >>
795 =item B<< $attr->has_init_arg >>
797 This will be I<false> if the C<init_arg> was set to C<undef>.
799 =item B<< $attr->has_default >>
801 This will be I<false> if the C<default> was set to C<undef>, since
802 C<undef> is the default C<default> anyway.
804 =item B<< $attr->has_builder >>
806 =item B<< $attr->has_insertion_order >>
808 This will be I<false> if this attribute has not be inserted into a class
812 =head2 Value management
814 These methods are basically "back doors" to the instance, and can be
815 used to bypass the regular accessors, but still stay within the MOP.
817 These methods are not for general use, and should only be used if you
818 really know what you are doing.
822 =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >>
824 This method is used internally to initialize the attribute's slot in
825 the object C<$instance>.
827 The C<$params> is a hash reference of the values passed to the object
830 It's unlikely that you'll need to call this method yourself.
832 =item B<< $attr->set_value($instance, $value) >>
834 Sets the value without going through the accessor. Note that this
835 works even with read-only attributes.
837 =item B<< $attr->set_raw_value($instance, $value) >>
839 Sets the value with no side effects such as a trigger.
841 This doesn't actually apply to Class::MOP attributes, only to subclasses.
843 =item B<< $attr->set_initial_value($instance, $value) >>
845 Sets the value without going through the accessor. This method is only
846 called when the instance is first being initialized.
848 =item B<< $attr->get_value($instance) >>
850 Returns the value without going through the accessor. Note that this
851 works even with write-only accessors.
853 =item B<< $attr->get_raw_value($instance) >>
855 Returns the value without any side effects such as lazy attributes.
857 Doesn't actually apply to Class::MOP attributes, only to subclasses.
859 =item B<< $attr->has_value($instance) >>
861 Return a boolean indicating whether the attribute has been set in
862 C<$instance>. This how the default C<predicate> method works.
864 =item B<< $attr->clear_value($instance) >>
866 This will clear the attribute's value in C<$instance>. This is what
867 the default C<clearer> calls.
869 Note that this works even if the attribute does not have any
870 associated read, write or clear methods.
874 =head2 Class association
876 These methods allow you to manage the attributes association with
877 the class that contains it. These methods should not be used
878 lightly, nor are they very magical, they are mostly used internally
879 and by metaclass instances.
883 =item B<< $attr->associated_class >>
885 This returns the C<Class::MOP::Class> with which this attribute is
888 =item B<< $attr->attach_to_class($metaclass) >>
890 This method stores a weakened reference to the C<$metaclass> object
893 This method does not remove the attribute from its old class,
894 nor does it create any accessors in the new class.
896 It is probably best to use the L<Class::MOP::Class> C<add_attribute>
899 =item B<< $attr->detach_from_class >>
901 This method removes the associate metaclass object from the attribute
904 This method does not remove the attribute itself from the class, or
905 remove its accessors.
907 It is probably best to use the L<Class::MOP::Class>
908 C<remove_attribute> method instead.
912 =head2 Attribute Accessor generation
916 =item B<< $attr->accessor_metaclass >>
918 Accessor methods are generated using an accessor metaclass. By
919 default, this is L<Class::MOP::Method::Accessor>. This method returns
920 the name of the accessor metaclass that this attribute uses.
922 =item B<< $attr->associate_method($method) >>
924 This associates a L<Class::MOP::Method> object with the
925 attribute. Typically, this is called internally when an attribute
926 generates its accessors.
928 =item B<< $attr->associated_methods >>
930 This returns the list of methods which have been associated with the
933 =item B<< $attr->install_accessors >>
935 This method generates and installs code the attributes various
936 accessors. It is typically called from the L<Class::MOP::Class>
937 C<add_attribute> method.
939 =item B<< $attr->remove_accessors >>
941 This method removes all of the accessors associated with the
944 This does not currently remove methods from the list returned by
945 C<associated_methods>.
947 =item B<< $attr->inline_get >>
949 =item B<< $attr->inline_set >>
951 =item B<< $attr->inline_has >>
953 =item B<< $attr->inline_clear >>
955 These methods return a code snippet suitable for inlining the relevant
956 operation. They expect strings containing variable names to be used in the
957 inlining, like C<'$self'> or C<'$_[1]'>.
965 =item B<< Class::MOP::Attribute->meta >>
967 This will return a L<Class::MOP::Class> instance for this class.
969 It should also be noted that L<Class::MOP> will actually bootstrap
970 this module by installing a number of attribute meta-objects into its
977 Stevan Little E<lt>stevan@iinteractive.comE<gt>
979 =head1 COPYRIGHT AND LICENSE
981 Copyright 2006-2010 by Infinity Interactive, Inc.
983 L<http://www.iinteractive.com>
985 This library is free software; you can redistribute it and/or modify
986 it under the same terms as Perl itself.