2 package Class::MOP::Attribute;
7 use Class::MOP::Method::Accessor;
10 use Scalar::Util 'blessed', 'weaken';
12 our $VERSION = '0.93';
13 $VERSION = eval $VERSION;
14 our $AUTHORITY = 'cpan:STEVAN';
16 use base 'Class::MOP::Object';
18 # NOTE: (meta-circularity)
19 # This method will be replaced in the
20 # boostrap section of Class::MOP, by
21 # a new version which uses the
22 # &Class::MOP::Class::construct_instance
23 # method to build an attribute meta-object
24 # which itself is described with attribute
26 # - Ain't meta-circularity grand? :)
28 my ( $class, @args ) = @_;
30 unshift @args, "name" if @args % 2 == 1;
33 my $name = $options{name};
36 || confess "You must provide a name for the attribute";
38 $options{init_arg} = $name
39 if not exists $options{init_arg};
40 if(exists $options{builder}){
41 confess("builder must be a defined scalar value which is a method name")
42 if ref $options{builder} || !(defined $options{builder});
43 confess("Setting both default and builder is not allowed.")
44 if exists $options{default};
46 (is_default_a_coderef(\%options))
47 || confess("References are not allowed as default values, you must ".
48 "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])")
49 if exists $options{default} && ref $options{default};
51 if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) {
52 confess("A required attribute must have either 'init_arg', 'builder', or 'default'");
55 $class->_new(\%options);
61 return Class::MOP::Class->initialize($class)->new_object(@_)
62 if $class ne __PACKAGE__;
64 my $options = @_ == 1 ? $_[0] : {@_};
67 'name' => $options->{name},
68 'accessor' => $options->{accessor},
69 'reader' => $options->{reader},
70 'writer' => $options->{writer},
71 'predicate' => $options->{predicate},
72 'clearer' => $options->{clearer},
73 'builder' => $options->{builder},
74 'init_arg' => $options->{init_arg},
75 'default' => $options->{default},
76 'initializer' => $options->{initializer},
77 'definition_context' => $options->{definition_context},
78 # keep a weakened link to the
79 # class we are associated with
80 'associated_class' => undef,
81 # and a list of the methods
82 # associated with this attr
83 'associated_methods' => [],
84 # this let's us keep track of
85 # our order inside the associated
87 'insertion_order' => undef,
92 # this is a primative (and kludgy) clone operation
93 # for now, it will be replaced in the Class::MOP
94 # bootstrap with a proper one, however we know
95 # that this one will work fine for now.
100 || confess "Can only clone an instance";
101 return bless { %{$self}, %options } => ref($self);
104 sub initialize_instance_slot {
105 my ($self, $meta_instance, $instance, $params) = @_;
106 my $init_arg = $self->{'init_arg'};
108 # try to fetch the init arg from the %params ...
110 # if nothing was in the %params, we can use the
111 # attribute's default value (if it has one)
112 if(defined $init_arg and exists $params->{$init_arg}){
113 $self->_set_initial_slot_value(
116 $params->{$init_arg},
119 elsif (defined $self->{'default'}) {
120 $self->_set_initial_slot_value(
123 $self->default($instance),
126 elsif (defined( my $builder = $self->{'builder'})) {
127 if ($builder = $instance->can($builder)) {
128 $self->_set_initial_slot_value(
135 confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'");
140 sub _set_initial_slot_value {
141 my ($self, $meta_instance, $instance, $value) = @_;
143 my $slot_name = $self->name;
145 return $meta_instance->set_slot_value($instance, $slot_name, $value)
146 unless $self->has_initializer;
149 $meta_instance->set_slot_value($instance, $slot_name, $_[0]);
152 my $initializer = $self->initializer;
154 # most things will just want to set a value, so make it first arg
155 $instance->$initializer($value, $callback, $self);
159 # the next bunch of methods will get bootstrapped
160 # away in the Class::MOP bootstrapping section
162 sub associated_class { $_[0]->{'associated_class'} }
163 sub associated_methods { $_[0]->{'associated_methods'} }
165 sub has_accessor { defined($_[0]->{'accessor'}) }
166 sub has_reader { defined($_[0]->{'reader'}) }
167 sub has_writer { defined($_[0]->{'writer'}) }
168 sub has_predicate { defined($_[0]->{'predicate'}) }
169 sub has_clearer { defined($_[0]->{'clearer'}) }
170 sub has_builder { defined($_[0]->{'builder'}) }
171 sub has_init_arg { defined($_[0]->{'init_arg'}) }
172 sub has_default { defined($_[0]->{'default'}) }
173 sub has_initializer { defined($_[0]->{'initializer'}) }
174 sub has_insertion_order { defined($_[0]->{'insertion_order'}) }
176 sub accessor { $_[0]->{'accessor'} }
177 sub reader { $_[0]->{'reader'} }
178 sub writer { $_[0]->{'writer'} }
179 sub predicate { $_[0]->{'predicate'} }
180 sub clearer { $_[0]->{'clearer'} }
181 sub builder { $_[0]->{'builder'} }
182 sub init_arg { $_[0]->{'init_arg'} }
183 sub initializer { $_[0]->{'initializer'} }
184 sub definition_context { $_[0]->{'definition_context'} }
185 sub insertion_order { $_[0]->{'insertion_order'} }
186 sub _set_insertion_order { $_[0]->{'insertion_order'} = $_[1] }
188 # end bootstrapped away method section.
189 # (all methods below here are kept intact)
191 sub has_read_method { $_[0]->has_reader || $_[0]->has_accessor }
192 sub has_write_method { $_[0]->has_writer || $_[0]->has_accessor }
194 sub get_read_method {
196 my $reader = $self->reader || $self->accessor;
198 return $reader unless ref $reader;
200 my ($name) = %$reader;
204 sub get_write_method {
206 my $writer = $self->writer || $self->accessor;
208 return $writer unless ref $writer;
210 my ($name) = %$writer;
214 sub get_read_method_ref {
216 if ((my $reader = $self->get_read_method) && $self->associated_class) {
217 return $self->associated_class->get_method($reader);
220 my $code = sub { $self->get_value(@_) };
221 if (my $class = $self->associated_class) {
222 return $class->method_metaclass->wrap(
224 package_name => $class->name,
234 sub get_write_method_ref {
236 if ((my $writer = $self->get_write_method) && $self->associated_class) {
237 return $self->associated_class->get_method($writer);
240 my $code = sub { $self->set_value(@_) };
241 if (my $class = $self->associated_class) {
242 return $class->method_metaclass->wrap(
244 package_name => $class->name,
254 sub is_default_a_coderef {
255 my ($value) = $_[0]->{'default'};
256 return unless ref($value);
257 return ref($value) eq 'CODE' || (blessed($value) && $value->isa('Class::MOP::Method'));
261 my ($self, $instance) = @_;
262 if (defined $instance && $self->is_default_a_coderef) {
263 # if the default is a CODE ref, then
264 # we pass in the instance and default
265 # can return a value based on that
266 # instance. Somewhat crude, but works.
267 return $self->{'default'}->($instance);
274 sub slots { (shift)->name }
278 sub attach_to_class {
279 my ($self, $class) = @_;
280 (blessed($class) && $class->isa('Class::MOP::Class'))
281 || confess "You must pass a Class::MOP::Class instance (or a subclass)";
282 weaken($self->{'associated_class'} = $class);
285 sub detach_from_class {
287 $self->{'associated_class'} = undef;
292 sub associate_method {
293 my ($self, $method) = @_;
294 push @{$self->{'associated_methods'}} => $method;
299 sub set_initial_value {
300 my ($self, $instance, $value) = @_;
301 $self->_set_initial_slot_value(
302 Class::MOP::Class->initialize(ref($instance))->get_meta_instance,
308 sub set_value { shift->set_raw_value(@_) }
309 sub get_value { shift->get_raw_value(@_) }
312 my ($self, $instance, $value) = @_;
314 Class::MOP::Class->initialize(ref($instance))
316 ->set_slot_value($instance, $self->name, $value);
320 my ($self, $instance) = @_;
322 Class::MOP::Class->initialize(ref($instance))
324 ->get_slot_value($instance, $self->name);
328 my ($self, $instance) = @_;
330 Class::MOP::Class->initialize(ref($instance))
332 ->is_slot_initialized($instance, $self->name);
336 my ($self, $instance) = @_;
338 Class::MOP::Class->initialize(ref($instance))
340 ->deinitialize_slot($instance, $self->name);
345 sub accessor_metaclass { 'Class::MOP::Method::Accessor' }
347 sub _process_accessors {
348 my ($self, $type, $accessor, $generate_as_inline_methods) = @_;
352 if ( my $ctx = $self->definition_context ) {
353 $method_ctx = { %$ctx };
356 if (ref($accessor)) {
357 (ref($accessor) eq 'HASH')
358 || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref";
359 my ($name, $method) = %{$accessor};
360 $method = $self->accessor_metaclass->wrap(
362 package_name => $self->associated_class->name,
364 definition_context => $method_ctx,
366 $self->associate_method($method);
367 return ($name, $method);
370 my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable);
374 my $desc = "accessor $accessor";
375 if ( $accessor ne $self->name ) {
376 $desc .= " of attribute " . $self->name;
379 $method_ctx->{description} = $desc;
382 $method = $self->accessor_metaclass->new(
384 is_inline => $inline_me,
385 accessor_type => $type,
386 package_name => $self->associated_class->name,
388 definition_context => $method_ctx,
391 confess "Could not create the '$type' method for " . $self->name . " because : $@" if $@;
392 $self->associate_method($method);
393 return ($accessor, $method);
397 sub install_accessors {
400 my $class = $self->associated_class;
403 $self->_process_accessors('accessor' => $self->accessor(), $inline)
404 ) if $self->has_accessor();
407 $self->_process_accessors('reader' => $self->reader(), $inline)
408 ) if $self->has_reader();
411 $self->_process_accessors('writer' => $self->writer(), $inline)
412 ) if $self->has_writer();
415 $self->_process_accessors('predicate' => $self->predicate(), $inline)
416 ) if $self->has_predicate();
419 $self->_process_accessors('clearer' => $self->clearer(), $inline)
420 ) if $self->has_clearer();
426 my $_remove_accessor = sub {
427 my ($accessor, $class) = @_;
428 if (ref($accessor) && ref($accessor) eq 'HASH') {
429 ($accessor) = keys %{$accessor};
431 my $method = $class->get_method($accessor);
432 $class->remove_method($accessor)
433 if (ref($method) && $method->isa('Class::MOP::Method::Accessor'));
436 sub remove_accessors {
439 # we really need to make sure to remove from the
440 # associates methods here as well. But this is
441 # such a slimly used method, I am not worried
442 # about it right now.
443 $_remove_accessor->($self->accessor(), $self->associated_class()) if $self->has_accessor();
444 $_remove_accessor->($self->reader(), $self->associated_class()) if $self->has_reader();
445 $_remove_accessor->($self->writer(), $self->associated_class()) if $self->has_writer();
446 $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate();
447 $_remove_accessor->($self->clearer(), $self->associated_class()) if $self->has_clearer();
461 Class::MOP::Attribute - Attribute Meta Object
465 Class::MOP::Attribute->new(
467 accessor => 'foo', # dual purpose get/set accessor
468 predicate => 'has_foo', # predicate check for defined-ness
469 init_arg => '-foo', # class->new will look for a -foo key
470 default => 'BAR IS BAZ!' # if no -foo key is provided, use this
474 Class::MOP::Attribute->new(
476 reader => 'bar', # getter
477 writer => 'set_bar', # setter
478 predicate => 'has_bar', # predicate check for defined-ness
479 init_arg => ':bar', # class->new will look for a :bar key
480 # no default value means it is undef
486 The Attribute Protocol is almost entirely an invention of
487 C<Class::MOP>. Perl 5 does not have a consistent notion of
488 attributes. There are so many ways in which this is done, and very few
489 (if any) are easily discoverable by this module.
491 With that said, this module attempts to inject some order into this
492 chaos, by introducing a consistent API which can be used to create
501 =item B<< Class::MOP::Attribute->new($name, ?%options) >>
503 An attribute must (at the very least), have a C<$name>. All other
504 C<%options> are added as key-value pairs.
510 This is a string value representing the expected key in an
511 initialization hash. For instance, if we have an C<init_arg> value of
512 C<-foo>, then the following code will Just Work.
514 MyClass->meta->new_object( -foo => 'Hello There' );
516 If an init_arg is not assigned, it will automatically use the
517 attribute's name. If C<init_arg> is explicitly set to C<undef>, the
518 attribute cannot be specified during initialization.
522 This provides the name of a method that will be called to initialize
523 the attribute. This method will be called on the object after it is
524 constructed. It is expected to return a valid value for the attribute.
528 This can be used to provide an explicit default for initializing the
529 attribute. If the default you provide is a subroutine reference, then
530 this reference will be called I<as a method> on the object.
532 If the value is a simple scalar (string or number), then it can be
533 just passed as is. However, if you wish to initialize it with a HASH
534 or ARRAY ref, then you need to wrap that inside a subroutine
537 Class::MOP::Attribute->new(
539 default => sub { [] },
545 Class::MOP::Attribute->new(
547 default => sub { {} },
551 If you wish to initialize an attribute with a subroutine reference
552 itself, then you need to wrap that in a subroutine as well:
554 Class::MOP::Attribute->new(
557 sub { print "Hello World" }
562 And lastly, if the value of your attribute is dependent upon some
563 other aspect of the instance structure, then you can take advantage of
564 the fact that when the C<default> value is called as a method:
566 Class::MOP::Attribute->new(
567 'object_identity' => (
568 default => sub { Scalar::Util::refaddr( $_[0] ) },
572 Note that there is no guarantee that attributes are initialized in any
573 particular order, so you cannot rely on the value of some other
574 attribute when generating the default.
578 This option can be either a method name or a subroutine
579 reference. This method will be called when setting the attribute's
580 value in the constructor. Unlike C<default> and C<builder>, the
581 initializer is only called when a value is provided to the
582 constructor. The initializer allows you to munge this value during
585 The initializer is called as a method with three arguments. The first
586 is the value that was passed to the constructor. The second is a
587 subroutine reference that can be called to actually set the
588 attribute's value, and the last is the associated
589 C<Class::MOP::Attribute> object.
591 This contrived example shows an initializer that sets the attribute to
592 twice the given value.
594 Class::MOP::Attribute->new(
597 my ( $self, $value, $set, $attr ) = @_;
598 $set->( $value * 2 );
603 Since an initializer can be a method name, you can easily make
604 attribute initialization use the writer:
606 Class::MOP::Attribute->new(
608 writer => 'some_attr',
609 initializer => 'some_attr',
613 Your writer will need to examine C<@_> and determine under which
614 context it is being called.
618 The C<accessor>, C<reader>, C<writer>, C<predicate> and C<clearer>
619 options all accept the same parameters. You can provide the name of
620 the method, in which case an appropriate default method will be
621 generated for you. Or instead you can also provide hash reference
622 containing exactly one key (the method name) and one value. The value
623 should be a subroutine reference, which will be installed as the
630 An C<accessor> is a standard Perl-style read/write accessor. It will
631 return the value of the attribute, and if a value is passed as an
632 argument, it will assign that value to the attribute.
634 Note that C<undef> is a legitimate value, so this will work:
636 $object->set_something(undef);
640 This is a basic read-only accessor. It returns the value of the
645 This is a basic write accessor, it accepts a single argument, and
646 assigns that value to the attribute.
648 Note that C<undef> is a legitimate value, so this will work:
650 $object->set_something(undef);
654 The predicate method returns a boolean indicating whether or not the
655 attribute has been explicitly set.
657 Note that the predicate returns true even if the attribute was set to
658 a false value (C<0> or C<undef>).
662 This method will uninitialize the attribute. After an attribute is
663 cleared, its C<predicate> will return false.
665 =item * definition_context
667 Mostly, this exists as a hook for the benefit of Moose.
669 This option should be a hash reference containing several keys which
670 will be used when inlining the attribute's accessors. The keys should
671 include C<line>, the line number where the attribute was created, and
672 either C<file> or C<description>.
674 This information will ultimately be used when eval'ing inlined
675 accessor code so that error messages report a useful line and file
680 =item B<< $attr->clone(%options) >>
682 This clones the attribute. Any options you provide will override the
683 settings of the original attribute. You can change the name of the new
684 attribute by passing a C<name> key in C<%options>.
690 These are all basic read-only accessors for the values passed into
695 =item B<< $attr->name >>
697 Returns the attribute's name.
699 =item B<< $attr->accessor >>
701 =item B<< $attr->reader >>
703 =item B<< $attr->writer >>
705 =item B<< $attr->predicate >>
707 =item B<< $attr->clearer >>
709 The C<accessor>, C<reader>, C<writer>, C<predicate>, and C<clearer>
710 methods all return exactly what was passed to the constructor, so it
711 can be either a string containing a method name, or a hash reference.
713 =item B<< $attr->initializer >>
715 Returns the initializer as passed to the constructor, so this may be
716 either a method name or a subroutine reference.
718 =item B<< $attr->init_arg >>
720 =item B<< $attr->is_default_a_coderef >>
722 =item B<< $attr->default($instance) >>
724 The C<$instance> argument is optional. If you don't pass it, the
725 return value for this method is exactly what was passed to the
726 constructor, either a simple scalar or a subroutine reference.
728 If you I<do> pass an C<$instance> and the default is a subroutine
729 reference, then the reference is called as a method on the
730 C<$instance> and the generated value is returned.
732 =item B<< $attr->slots >>
734 Return a list of slots required by the attribute. This is usually just
735 one, the name of the attribute.
737 A slot is the name of the hash key used to store the attribute in an
740 =item B<< $attr->get_read_method >>
742 =item B<< $attr->get_write_method >>
744 Returns the name of a method suitable for reading or writing the value
745 of the attribute in the associated class.
747 If an attribute is read- or write-only, then these methods can return
748 C<undef> as appropriate.
750 =item B<< $attr->has_read_method >>
752 =item B<< $attr->has_write_method >>
754 This returns a boolean indicating whether the attribute has a I<named>
755 read or write method.
757 =item B<< $attr->get_read_method_ref >>
759 =item B<< $attr->get_write_method_ref >>
761 Returns the subroutine reference of a method suitable for reading or
762 writing the attribute's value in the associated class. These methods
763 always return a subroutine reference, regardless of whether or not the
764 attribute is read- or write-only.
766 =item B<< $attr->insertion_order >>
768 If this attribute has been inserted into a class, this returns a zero
769 based index regarding the order of insertion.
773 =head2 Informational predicates
775 These are all basic predicate methods for the values passed into C<new>.
779 =item B<< $attr->has_accessor >>
781 =item B<< $attr->has_reader >>
783 =item B<< $attr->has_writer >>
785 =item B<< $attr->has_predicate >>
787 =item B<< $attr->has_clearer >>
789 =item B<< $attr->has_initializer >>
791 =item B<< $attr->has_init_arg >>
793 This will be I<false> if the C<init_arg> was set to C<undef>.
795 =item B<< $attr->has_default >>
797 This will be I<false> if the C<default> was set to C<undef>, since
798 C<undef> is the default C<default> anyway.
800 =item B<< $attr->has_builder >>
802 =item B<< $attr->has_insertion_order >>
804 This will be I<false> if this attribute has not be inserted into a class
808 =head2 Value management
810 These methods are basically "back doors" to the instance, and can be
811 used to bypass the regular accessors, but still stay within the MOP.
813 These methods are not for general use, and should only be used if you
814 really know what you are doing.
818 =item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >>
820 This method is used internally to initialize the attribute's slot in
821 the object C<$instance>.
823 The C<$params> is a hash reference of the values passed to the object
826 It's unlikely that you'll need to call this method yourself.
828 =item B<< $attr->set_value($instance, $value) >>
830 Sets the value without going through the accessor. Note that this
831 works even with read-only attributes.
833 =item B<< $attr->set_raw_value($instance, $value) >>
835 Sets the value with no side effects such as a trigger.
837 This doesn't actually apply to Class::MOP attributes, only to subclasses.
839 =item B<< $attr->set_initial_value($instance, $value) >>
841 Sets the value without going through the accessor. This method is only
842 called when the instance is first being initialized.
844 =item B<< $attr->get_value($instance) >>
846 Returns the value without going through the accessor. Note that this
847 works even with write-only accessors.
849 =item B<< $sttr->get_raw_value($instance) >>
851 Returns the value without any side effects such as lazy attributes.
853 Doesn't actually apply to Class::MOP attributes, only to subclasses.
855 =item B<< $attr->has_value($instance) >>
857 Return a boolean indicating whether the attribute has been set in
858 C<$instance>. This how the default C<predicate> method works.
860 =item B<< $attr->clear_value($instance) >>
862 This will clear the attribute's value in C<$instance>. This is what
863 the default C<clearer> calls.
865 Note that this works even if the attribute does not have any
866 associated read, write or clear methods.
870 =head2 Class association
872 These methods allow you to manage the attributes association with
873 the class that contains it. These methods should not be used
874 lightly, nor are they very magical, they are mostly used internally
875 and by metaclass instances.
879 =item B<< $attr->associated_class >>
881 This returns the C<Class::MOP::Class> with which this attribute is
884 =item B<< $attr->attach_to_class($metaclass) >>
886 This method stores a weakened reference to the C<$metaclass> object
889 This method does not remove the attribute from its old class,
890 nor does it create any accessors in the new class.
892 It is probably best to use the L<Class::MOP::Class> C<add_attribute>
895 =item B<< $attr->detach_from_class >>
897 This method removes the associate metaclass object from the attribute
900 This method does not remove the attribute itself from the class, or
901 remove its accessors.
903 It is probably best to use the L<Class::MOP::Class>
904 C<remove_attribute> method instead.
908 =head2 Attribute Accessor generation
912 =item B<< $attr->accessor_metaclass >>
914 Accessor methods are generated using an accessor metaclass. By
915 default, this is L<Class::MOP::Method::Accessor>. This method returns
916 the name of the accessor metaclass that this attribute uses.
918 =item B<< $attr->associate_method($method) >>
920 This associates a L<Class::MOP::Method> object with the
921 attribute. Typically, this is called internally when an attribute
922 generates its accessors.
924 =item B<< $attr->associated_methods >>
926 This returns the list of methods which have been associated with the
929 =item B<< $attr->install_accessors >>
931 This method generates and installs code the attributes various
932 accessors. It is typically called from the L<Class::MOP::Class>
933 C<add_attribute> method.
935 =item B<< $attr->remove_accessors >>
937 This method removes all of the accessors associated with the
940 This does not currently remove methods from the list returned by
941 C<associated_methods>.
949 =item B<< Class::MOP::Attribute->meta >>
951 This will return a L<Class::MOP::Class> instance for this class.
953 It should also be noted that L<Class::MOP> will actually bootstrap
954 this module by installing a number of attribute meta-objects into its
961 Stevan Little E<lt>stevan@iinteractive.comE<gt>
963 =head1 COPYRIGHT AND LICENSE
965 Copyright 2006-2009 by Infinity Interactive, Inc.
967 L<http://www.iinteractive.com>
969 This library is free software; you can redistribute it and/or modify
970 it under the same terms as Perl itself.