X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FClass%2FMOP%2FAttribute.pm;h=d0cf23477fb3303c46e2485343b544e59b7d4c1b;hb=53362bcb1b32d87630190fbf50679dc37bb51adf;hp=85480f1ed08d7957e31ef16363dd1f6a5294c476;hpb=be960ba18045b2874c9151ff9e0006fc9ede1ced;p=gitmo%2FClass-MOP.git diff --git a/lib/Class/MOP/Attribute.pm b/lib/Class/MOP/Attribute.pm index 85480f1..d0cf234 100644 --- a/lib/Class/MOP/Attribute.pm +++ b/lib/Class/MOP/Attribute.pm @@ -4,307 +4,436 @@ package Class::MOP::Attribute; use strict; use warnings; +use Class::MOP::Method::Accessor; + use Carp 'confess'; -use Scalar::Util 'blessed', 'reftype', 'weaken'; +use Scalar::Util 'blessed', 'weaken'; +use Try::Tiny; -our $VERSION = '0.09'; +our $VERSION = '1.11'; +$VERSION = eval $VERSION; +our $AUTHORITY = 'cpan:STEVAN'; -sub meta { - require Class::MOP::Class; - Class::MOP::Class->initialize(blessed($_[0]) || $_[0]); -} +use base 'Class::MOP::Object', 'Class::MOP::Mixin::AttributeCore'; # NOTE: (meta-circularity) -# This method will be replaces in the -# boostrap section of Class::MOP, by -# a new version which uses the +# This method will be replaced in the +# boostrap section of Class::MOP, by +# a new version which uses the # &Class::MOP::Class::construct_instance # method to build an attribute meta-object # which itself is described with attribute -# meta-objects. +# meta-objects. # - Ain't meta-circularity grand? :) sub new { - my $class = shift; - my $name = shift; - my %options = @_; - - (defined $name && $name) + my ( $class, @args ) = @_; + + unshift @args, "name" if @args % 2 == 1; + my %options = @args; + + my $name = $options{name}; + + (defined $name) || confess "You must provide a name for the attribute"; - $options{init_arg} = $name + + $options{init_arg} = $name if not exists $options{init_arg}; - + if(exists $options{builder}){ + confess("builder must be a defined scalar value which is a method name") + if ref $options{builder} || !(defined $options{builder}); + confess("Setting both default and builder is not allowed.") + if exists $options{default}; + } else { + ($class->is_default_a_coderef(\%options)) + || confess("References are not allowed as default values, you must ". + "wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])") + if exists $options{default} && ref $options{default}; + } + if( $options{required} and not( defined($options{builder}) || defined($options{init_arg}) || exists $options{default} ) ) { + confess("A required attribute must have either 'init_arg', 'builder', or 'default'"); + } + + $class->_new(\%options); +} + +sub _new { + my $class = shift; + + return Class::MOP::Class->initialize($class)->new_object(@_) + if $class ne __PACKAGE__; + + my $options = @_ == 1 ? $_[0] : {@_}; + bless { - name => $name, - accessor => $options{accessor}, - reader => $options{reader}, - writer => $options{writer}, - predicate => $options{predicate}, - init_arg => $options{init_arg}, - default => $options{default}, - # keep a weakened link to the + 'name' => $options->{name}, + 'accessor' => $options->{accessor}, + 'reader' => $options->{reader}, + 'writer' => $options->{writer}, + 'predicate' => $options->{predicate}, + 'clearer' => $options->{clearer}, + 'builder' => $options->{builder}, + 'init_arg' => $options->{init_arg}, + exists $options->{default} + ? ('default' => $options->{default}) + : (), + 'initializer' => $options->{initializer}, + 'definition_context' => $options->{definition_context}, + # keep a weakened link to the # class we are associated with - associated_class => undef, - } => $class; + 'associated_class' => undef, + # and a list of the methods + # associated with this attr + 'associated_methods' => [], + # this let's us keep track of + # our order inside the associated + # class + 'insertion_order' => undef, + }, $class; } # NOTE: -# this is a primative (and kludgy) clone operation -# for now, it will be repleace in the Class::MOP -# bootstrap with a proper one, however we know +# this is a primative (and kludgy) clone operation +# for now, it will be replaced in the Class::MOP +# bootstrap with a proper one, however we know # that this one will work fine for now. sub clone { my $self = shift; my %options = @_; (blessed($self)) || confess "Can only clone an instance"; - return bless { %{$self}, %options } => blessed($self); + return bless { %{$self}, %options } => ref($self); } sub initialize_instance_slot { my ($self, $meta_instance, $instance, $params) = @_; - my $init_arg = $self->{init_arg}; + my $init_arg = $self->{'init_arg'}; + # try to fetch the init arg from the %params ... - my $val; - $val = $params->{$init_arg} if exists $params->{$init_arg}; - # if nothing was in the %params, we can use the + + # if nothing was in the %params, we can use the # attribute's default value (if it has one) - if (!defined $val && defined $self->{default}) { - $val = $self->default($instance); + if(defined $init_arg and exists $params->{$init_arg}){ + $self->_set_initial_slot_value( + $meta_instance, + $instance, + $params->{$init_arg}, + ); + } + elsif (exists $self->{'default'}) { + $self->_set_initial_slot_value( + $meta_instance, + $instance, + $self->default($instance), + ); + } + elsif (defined( my $builder = $self->{'builder'})) { + if ($builder = $instance->can($builder)) { + $self->_set_initial_slot_value( + $meta_instance, + $instance, + $instance->$builder, + ); + } + else { + confess(ref($instance)." does not support builder method '". $self->{'builder'} ."' for attribute '" . $self->name . "'"); + } } - $meta_instance->set_slot_value($instance, $self->name, $val); } -# NOTE: -# the next bunch of methods will get bootstrapped -# away in the Class::MOP bootstrapping section +sub _set_initial_slot_value { + my ($self, $meta_instance, $instance, $value) = @_; -sub name { $_[0]->{name} } + my $slot_name = $self->name; -sub associated_class { $_[0]->{associated_class} } + return $meta_instance->set_slot_value($instance, $slot_name, $value) + unless $self->has_initializer; -sub has_accessor { defined($_[0]->{accessor}) ? 1 : 0 } -sub has_reader { defined($_[0]->{reader}) ? 1 : 0 } -sub has_writer { defined($_[0]->{writer}) ? 1 : 0 } -sub has_predicate { defined($_[0]->{predicate}) ? 1 : 0 } -sub has_init_arg { defined($_[0]->{init_arg}) ? 1 : 0 } -sub has_default { defined($_[0]->{default}) ? 1 : 0 } + my $callback = sub { + $meta_instance->set_slot_value($instance, $slot_name, $_[0]); + }; + + my $initializer = $self->initializer; -sub accessor { $_[0]->{accessor} } -sub reader { $_[0]->{reader} } -sub writer { $_[0]->{writer} } -sub predicate { $_[0]->{predicate} } -sub init_arg { $_[0]->{init_arg} } + # most things will just want to set a value, so make it first arg + $instance->$initializer($value, $callback, $self); +} -# end bootstrapped away method section. -# (all methods below here are kept intact) +sub get_read_method { + my $self = shift; + my $reader = $self->reader || $self->accessor; + # normal case ... + return $reader unless ref $reader; + # the HASH ref case + my ($name) = %$reader; + return $name; +} -sub is_default_a_coderef { - (reftype($_[0]->{default}) && reftype($_[0]->{default}) eq 'CODE') +sub get_write_method { + my $self = shift; + my $writer = $self->writer || $self->accessor; + # normal case ... + return $writer unless ref $writer; + # the HASH ref case + my ($name) = %$writer; + return $name; } -sub default { - my ($self, $instance) = @_; - if ($instance && $self->is_default_a_coderef) { - # if the default is a CODE ref, then - # we pass in the instance and default - # can return a value based on that - # instance. Somewhat crude, but works. - return $self->{default}->($instance); - } - $self->{default}; +sub get_read_method_ref { + my $self = shift; + if ((my $reader = $self->get_read_method) && $self->associated_class) { + return $self->associated_class->get_method($reader); + } + else { + my $code = sub { $self->get_value(@_) }; + if (my $class = $self->associated_class) { + return $class->method_metaclass->wrap( + $code, + package_name => $class->name, + name => '__ANON__' + ); + } + else { + return $code; + } + } +} + +sub get_write_method_ref { + my $self = shift; + if ((my $writer = $self->get_write_method) && $self->associated_class) { + return $self->associated_class->get_method($writer); + } + else { + my $code = sub { $self->set_value(@_) }; + if (my $class = $self->associated_class) { + return $class->method_metaclass->wrap( + $code, + package_name => $class->name, + name => '__ANON__' + ); + } + else { + return $code; + } + } } # slots sub slots { (shift)->name } -# class association +# class association sub attach_to_class { my ($self, $class) = @_; (blessed($class) && $class->isa('Class::MOP::Class')) || confess "You must pass a Class::MOP::Class instance (or a subclass)"; - weaken($self->{associated_class} = $class); + weaken($self->{'associated_class'} = $class); } sub detach_from_class { my $self = shift; - $self->{associated_class} = undef; + $self->{'associated_class'} = undef; } -## Method generation helpers +# method association -sub generate_accessor_method { - my $self = shift; - my $attr_name = $self->name; - return sub { - my $meta_instance = Class::MOP::Class->initialize(Scalar::Util::blessed($_[0]))->get_meta_instance; - $meta_instance->set_slot_value($_[0], $attr_name, $_[1]) if scalar(@_) == 2; - $meta_instance->get_slot_value($_[0], $attr_name); - }; +sub associate_method { + my ($self, $method) = @_; + push @{$self->{'associated_methods'}} => $method; } -sub generate_accessor_method_inline { - my $self = shift; - my $attr_name = $self->name; - my $meta_instance = $self->associated_class->instance_metaclass; - - my $code = eval 'sub {' - . $meta_instance->inline_set_slot_value('$_[0]', "'$attr_name'", '$_[1]') . ' if scalar(@_) == 2; ' - . $meta_instance->inline_get_slot_value('$_[0]', "'$attr_name'") - . '}'; - confess "Could not generate inline accessor because : $@" if $@; +## Slot management - return $code; +sub set_initial_value { + my ($self, $instance, $value) = @_; + $self->_set_initial_slot_value( + Class::MOP::Class->initialize(ref($instance))->get_meta_instance, + $instance, + $value + ); } -sub generate_reader_method { - my $self = shift; - my $attr_name = $self->name; - return sub { - confess "Cannot assign a value to a read-only accessor" if @_ > 1; - Class::MOP::Class->initialize(Scalar::Util::blessed($_[0])) - ->get_meta_instance - ->get_slot_value($_[0], $attr_name); - }; -} - -sub generate_reader_method_inline { - my $self = shift; - my $attr_name = $self->name; - my $meta_instance = $self->associated_class->instance_metaclass; +sub set_value { shift->set_raw_value(@_) } +sub get_value { shift->get_raw_value(@_) } - my $code = eval 'sub {' - . 'confess "Cannot assign a value to a read-only accessor" if @_ > 1;' - . $meta_instance->inline_get_slot_value('$_[0]', "'$attr_name'") - . '}'; - confess "Could not generate inline accessor because : $@" if $@; +sub set_raw_value { + my ($self, $instance, $value) = @_; - return $code; + Class::MOP::Class->initialize(ref($instance)) + ->get_meta_instance + ->set_slot_value($instance, $self->name, $value); } -sub generate_writer_method { - my $self = shift; - my $attr_name = $self->name; - return sub { - Class::MOP::Class->initialize(Scalar::Util::blessed($_[0])) - ->get_meta_instance - ->set_slot_value($_[0], $attr_name, $_[1]); - }; -} +sub get_raw_value { + my ($self, $instance) = @_; -sub generate_writer_method_inline { - my $self = shift; - my $attr_name = $self->name; - my $meta_instance = $self->associated_class->instance_metaclass; + Class::MOP::Class->initialize(ref($instance)) + ->get_meta_instance + ->get_slot_value($instance, $self->name); +} - my $code = eval 'sub {' - . $meta_instance->inline_set_slot_value('$_[0]', "'$attr_name'", '$_[1]') - . '}'; - confess "Could not generate inline accessor because : $@" if $@; +sub has_value { + my ($self, $instance) = @_; - return $code; + Class::MOP::Class->initialize(ref($instance)) + ->get_meta_instance + ->is_slot_initialized($instance, $self->name); } -sub generate_predicate_method { - my $self = shift; - my $attr_name = $self->name; - return sub { - defined Class::MOP::Class->initialize(Scalar::Util::blessed($_[0])) - ->get_meta_instance - ->get_slot_value($_[0], $attr_name) ? 1 : 0; - }; -} +sub clear_value { + my ($self, $instance) = @_; -sub generate_predicate_method_inline { - my $self = shift; - my $attr_name = $self->name; - my $meta_instance = $self->associated_class->instance_metaclass; + Class::MOP::Class->initialize(ref($instance)) + ->get_meta_instance + ->deinitialize_slot($instance, $self->name); +} - my $code = eval 'sub {' - . 'defined ' . $meta_instance->inline_get_slot_value('$_[0]', "'$attr_name'") . ' ? 1 : 0' - . '}'; - confess "Could not generate inline accessor because : $@" if $@; +## load em up ... - return $code; -} +sub accessor_metaclass { 'Class::MOP::Method::Accessor' } -sub process_accessors { +sub _process_accessors { my ($self, $type, $accessor, $generate_as_inline_methods) = @_; - if (reftype($accessor)) { - (reftype($accessor) eq 'HASH') - || confess "bad accessor/reader/writer/predicate format, must be a HASH ref"; + + my $method_ctx; + + if ( my $ctx = $self->definition_context ) { + $method_ctx = { %$ctx }; + } + + if (ref($accessor)) { + (ref($accessor) eq 'HASH') + || confess "bad accessor/reader/writer/predicate/clearer format, must be a HASH ref"; my ($name, $method) = %{$accessor}; - return ($name, Class::MOP::Attribute::Accessor->wrap($method)); + $method = $self->accessor_metaclass->wrap( + $method, + package_name => $self->associated_class->name, + name => $name, + definition_context => $method_ctx, + ); + $self->associate_method($method); + return ($name, $method); } else { - my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable); - my $generator = $self->can('generate_' . $type . '_method' . ($inline_me ? '_inline' : '')); - ($generator) - || confess "There is no method generator for the type='$type'"; - if (my $method = $self->$generator($self->name)) { - return ($accessor => Class::MOP::Attribute::Accessor->wrap($method)); + my $inline_me = ($generate_as_inline_methods && $self->associated_class->instance_metaclass->is_inlinable); + my $method; + try { + if ( $method_ctx ) { + my $desc = "accessor $accessor"; + if ( $accessor ne $self->name ) { + $desc .= " of attribute " . $self->name; + } + + $method_ctx->{description} = $desc; + } + + $method = $self->accessor_metaclass->new( + attribute => $self, + is_inline => $inline_me, + accessor_type => $type, + package_name => $self->associated_class->name, + name => $accessor, + definition_context => $method_ctx, + ); } - confess "Could not create the '$type' method for " . $self->name . " because : $@"; - } + catch { + confess "Could not create the '$type' method for " . $self->name . " because : $_"; + }; + $self->associate_method($method); + return ($accessor, $method); + } } sub install_accessors { my $self = shift; my $inline = shift; my $class = $self->associated_class; - + $class->add_method( - $self->process_accessors('accessor' => $self->accessor(), $inline) + $self->_process_accessors('accessor' => $self->accessor(), $inline) ) if $self->has_accessor(); - $class->add_method( - $self->process_accessors('reader' => $self->reader(), $inline) + $class->add_method( + $self->_process_accessors('reader' => $self->reader(), $inline) ) if $self->has_reader(); $class->add_method( - $self->process_accessors('writer' => $self->writer(), $inline) + $self->_process_accessors('writer' => $self->writer(), $inline) ) if $self->has_writer(); $class->add_method( - $self->process_accessors('predicate' => $self->predicate(), $inline) + $self->_process_accessors('predicate' => $self->predicate(), $inline) ) if $self->has_predicate(); - + + $class->add_method( + $self->_process_accessors('clearer' => $self->clearer(), $inline) + ) if $self->has_clearer(); + return; } { my $_remove_accessor = sub { my ($accessor, $class) = @_; - if (reftype($accessor) && reftype($accessor) eq 'HASH') { + if (ref($accessor) && ref($accessor) eq 'HASH') { ($accessor) = keys %{$accessor}; - } - my $method = $class->get_method($accessor); - $class->remove_method($accessor) - if (blessed($method) && $method->isa('Class::MOP::Attribute::Accessor')); + } + my $method = $class->get_method($accessor); + $class->remove_method($accessor) + if (ref($method) && $method->isa('Class::MOP::Method::Accessor')); }; - + sub remove_accessors { my $self = shift; + # TODO: + # we really need to make sure to remove from the + # associates methods here as well. But this is + # such a slimly used method, I am not worried + # about it right now. $_remove_accessor->($self->accessor(), $self->associated_class()) if $self->has_accessor(); $_remove_accessor->($self->reader(), $self->associated_class()) if $self->has_reader(); $_remove_accessor->($self->writer(), $self->associated_class()) if $self->has_writer(); $_remove_accessor->($self->predicate(), $self->associated_class()) if $self->has_predicate(); - return; + $_remove_accessor->($self->clearer(), $self->associated_class()) if $self->has_clearer(); + return; } } -package Class::MOP::Attribute::Accessor; +sub inline_get { + my $self = shift; + my ($instance) = @_; -use strict; -use warnings; + return $self->associated_class->get_meta_instance->inline_get_slot_value( + $instance, $self->name ); +} + +sub inline_set { + my $self = shift; + my ( $instance, $value ) = @_; + + return $self->associated_class->get_meta_instance->inline_set_slot_value( + $instance, $self->name, $value ); +} + +sub inline_has { + my $self = shift; + my ($instance) = @_; -use Class::MOP::Method; + return + $self->associated_class->get_meta_instance + ->inline_is_slot_initialized( $instance, $self->name ); +} -our $VERSION = '0.01'; +sub inline_clear { + my $self = shift; + my ($instance) = @_; -our @ISA = ('Class::MOP::Method'); + return + $self->associated_class->get_meta_instance + ->inline_deinitialize_slot( $instance, $self->name ); +} 1; @@ -312,37 +441,40 @@ __END__ =pod -=head1 NAME +=head1 NAME Class::MOP::Attribute - Attribute Meta Object =head1 SYNOPSIS - - Class::MOP::Attribute->new('$foo' => ( - accessor => 'foo', # dual purpose get/set accessor - predicate => 'has_foo' # predicate check for defined-ness - init_arg => '-foo', # class->new will look for a -foo key - default => 'BAR IS BAZ!' # if no -foo key is provided, use this - )); - - Class::MOP::Attribute->new('$.bar' => ( - reader => 'bar', # getter - writer => 'set_bar', # setter - predicate => 'has_bar' # predicate check for defined-ness - init_arg => ':bar', # class->new will look for a :bar key - # no default value means it is undef - )); + + Class::MOP::Attribute->new( + foo => ( + accessor => 'foo', # dual purpose get/set accessor + predicate => 'has_foo', # predicate check for defined-ness + init_arg => '-foo', # class->new will look for a -foo key + default => 'BAR IS BAZ!' # if no -foo key is provided, use this + ) + ); + + Class::MOP::Attribute->new( + bar => ( + reader => 'bar', # getter + writer => 'set_bar', # setter + predicate => 'has_bar', # predicate check for defined-ness + init_arg => ':bar', # class->new will look for a :bar key + # no default value means it is undef + ) + ); =head1 DESCRIPTION -The Attribute Protocol is almost entirely an invention of this module, -and is completely optional to this MOP. This is because Perl 5 does not -have consistent notion of what is an attribute of a class. There are -so many ways in which this is done, and very few (if any) are -easily discoverable by this module. +The Attribute Protocol is almost entirely an invention of +C. Perl 5 does not have a consistent notion of +attributes. There are so many ways in which this is done, and very few +(if any) are easily discoverable by this module. -So, all that said, this module attempts to inject some order into this -chaos, by introducing a consistent API which can be used to create +With that said, this module attempts to inject some order into this +chaos, by introducing a consistent API which can be used to create object attributes. =head1 METHODS @@ -351,159 +483,275 @@ object attributes. =over 4 -=item B +=item B<< Class::MOP::Attribute->new($name, ?%options) >> -An attribute must (at the very least), have a C<$name>. All other -C<%options> are contained added as key-value pairs. Acceptable keys -are as follows: +An attribute must (at the very least), have a C<$name>. All other +C<%options> are added as key-value pairs. -=over 4 +=over 8 + +=item * init_arg + +This is a string value representing the expected key in an +initialization hash. For instance, if we have an C value of +C<-foo>, then the following code will Just Work. + + MyClass->meta->new_object( -foo => 'Hello There' ); + +If an init_arg is not assigned, it will automatically use the +attribute's name. If C is explicitly set to C, the +attribute cannot be specified during initialization. + +=item * builder + +This provides the name of a method that will be called to initialize +the attribute. This method will be called on the object after it is +constructed. It is expected to return a valid value for the attribute. -=item I - -This should be a string value representing the expected key in -an initialization hash. For instance, if we have an I -value of C<-foo>, then the following code will Just Work. - - MyClass->meta->construct_instance(-foo => "Hello There"); - -In an init_arg is not assigned, it will automatically use the -value of C<$name>. - -=item I - -The value of this key is the default value which -C will initialize the -attribute to. - -B -If the value is a simple scalar (string or number), then it can -be just passed as is. However, if you wish to initialize it with -a HASH or ARRAY ref, then you need to wrap that inside a CODE -reference, like so: - - Class::MOP::Attribute->new('@foo' => ( - default => sub { [] }, - )); - - # or ... - - Class::MOP::Attribute->new('%foo' => ( - default => sub { {} }, - )); - -If you wish to initialize an attribute with a CODE reference -itself, then you need to wrap that in a subroutine as well, like -so: - - Class::MOP::Attribute->new('&foo' => ( - default => sub { sub { print "Hello World" } }, - )); - -And lastly, if the value of your attribute is dependent upon -some other aspect of the instance structure, then you can take -advantage of the fact that when the I value is a CODE -reference, it is passed the raw (unblessed) instance structure -as it's only argument. So you can do things like this: - - Class::MOP::Attribute->new('$object_identity' => ( - default => sub { Scalar::Util::refaddr($_[0]) }, - )); - -This last feature is fairly limited as there is no gurantee of -the order of attribute initializations, so you cannot perform -any kind of dependent initializations. However, if this is -something you need, you could subclass B and -this class to acheive it. However, this is currently left as -an exercise to the reader :). +=item * default + +This can be used to provide an explicit default for initializing the +attribute. If the default you provide is a subroutine reference, then +this reference will be called I on the object. + +If the value is a simple scalar (string or number), then it can be +just passed as is. However, if you wish to initialize it with a HASH +or ARRAY ref, then you need to wrap that inside a subroutine +reference: + + Class::MOP::Attribute->new( + 'foo' => ( + default => sub { [] }, + ) + ); + + # or ... + + Class::MOP::Attribute->new( + 'foo' => ( + default => sub { {} }, + ) + ); + +If you wish to initialize an attribute with a subroutine reference +itself, then you need to wrap that in a subroutine as well: + + Class::MOP::Attribute->new( + 'foo' => ( + default => sub { + sub { print "Hello World" } + }, + ) + ); + +And lastly, if the value of your attribute is dependent upon some +other aspect of the instance structure, then you can take advantage of +the fact that when the C value is called as a method: + + Class::MOP::Attribute->new( + 'object_identity' => ( + default => sub { Scalar::Util::refaddr( $_[0] ) }, + ) + ); + +Note that there is no guarantee that attributes are initialized in any +particular order, so you cannot rely on the value of some other +attribute when generating the default. + +=item * initializer + +This option can be either a method name or a subroutine +reference. This method will be called when setting the attribute's +value in the constructor. Unlike C and C, the +initializer is only called when a value is provided to the +constructor. The initializer allows you to munge this value during +object construction. + +The initializer is called as a method with three arguments. The first +is the value that was passed to the constructor. The second is a +subroutine reference that can be called to actually set the +attribute's value, and the last is the associated +C object. + +This contrived example shows an initializer that sets the attribute to +twice the given value. + + Class::MOP::Attribute->new( + 'doubled' => ( + initializer => sub { + my ( $self, $value, $set, $attr ) = @_; + $set->( $value * 2 ); + }, + ) + ); + +Since an initializer can be a method name, you can easily make +attribute initialization use the writer: + + Class::MOP::Attribute->new( + 'some_attr' => ( + writer => 'some_attr', + initializer => 'some_attr', + ) + ); + +Your writer will need to examine C<@_> and determine under which +context it is being called. =back -The I, I, I and I keys can -contain either; the name of the method and an appropriate default -one will be generated for you, B a HASH ref containing exactly one -key (which will be used as the name of the method) and one value, -which should contain a CODE reference which will be installed as -the method itself. +The C, C, C, C and C +options all accept the same parameters. You can provide the name of +the method, in which case an appropriate default method will be +generated for you. Or instead you can also provide hash reference +containing exactly one key (the method name) and one value. The value +should be a subroutine reference, which will be installed as the +method itself. -=over 4 +=over 8 -=item I +=item * accessor -The I is a standard perl-style read/write accessor. It will -return the value of the attribute, and if a value is passed as an argument, -it will assign that value to the attribute. +An C is a standard Perl-style read/write accessor. It will +return the value of the attribute, and if a value is passed as an +argument, it will assign that value to the attribute. -B -This method will properly handle the following code, by assigning an -C value to the attribute. +Note that C is a legitimate value, so this will work: $object->set_something(undef); -=item I +=item * reader -This is a basic read-only accessor, it will just return the value of -the attribute. +This is a basic read-only accessor. It returns the value of the +attribute. + +=item * writer + +This is a basic write accessor, it accepts a single argument, and +assigns that value to the attribute. + +Note that C is a legitimate value, so this will work: + + $object->set_something(undef); -=item I +=item * predicate -This is a basic write accessor, it accepts a single argument, and -assigns that value to the attribute. This method does not intentially -return a value, however perl will return the result of the last -expression in the subroutine, which returns in this returning the -same value that it was passed. +The predicate method returns a boolean indicating whether or not the +attribute has been explicitly set. -B -This method will properly handle the following code, by assigning an -C value to the attribute. +Note that the predicate returns true even if the attribute was set to +a false value (C<0> or C). - $object->set_something(); +=item * clearer -=item I +This method will uninitialize the attribute. After an attribute is +cleared, its C will return false. -This is a basic test to see if the value of the attribute is not -C. It will return true (C<1>) if the attribute's value is -defined, and false (C<0>) otherwise. +=item * definition_context + +Mostly, this exists as a hook for the benefit of Moose. + +This option should be a hash reference containing several keys which +will be used when inlining the attribute's accessors. The keys should +include C, the line number where the attribute was created, and +either C or C. + +This information will ultimately be used when eval'ing inlined +accessor code so that error messages report a useful line and file +name. =back -=item B +=item B<< $attr->clone(%options) >> -=item B +This clones the attribute. Any options you provide will override the +settings of the original attribute. You can change the name of the new +attribute by passing a C key in C<%options>. -=back +=back =head2 Informational -These are all basic read-only value accessors for the values -passed into C. I think they are pretty much self-explanitory. +These are all basic read-only accessors for the values passed into +the constructor. =over 4 -=item B +=item B<< $attr->name >> + +Returns the attribute's name. + +=item B<< $attr->accessor >> + +=item B<< $attr->reader >> + +=item B<< $attr->writer >> + +=item B<< $attr->predicate >> + +=item B<< $attr->clearer >> + +The C, C, C, C, and C +methods all return exactly what was passed to the constructor, so it +can be either a string containing a method name, or a hash reference. + +=item B<< $attr->initializer >> + +Returns the initializer as passed to the constructor, so this may be +either a method name or a subroutine reference. + +=item B<< $attr->init_arg >> + +=item B<< $attr->is_default_a_coderef >> + +=item B<< $attr->default($instance) >> + +The C<$instance> argument is optional. If you don't pass it, the +return value for this method is exactly what was passed to the +constructor, either a simple scalar or a subroutine reference. + +If you I pass an C<$instance> and the default is a subroutine +reference, then the reference is called as a method on the +C<$instance> and the generated value is returned. + +=item B<< $attr->slots >> + +Return a list of slots required by the attribute. This is usually just +one, the name of the attribute. + +A slot is the name of the hash key used to store the attribute in an +object instance. + +=item B<< $attr->get_read_method >> -=item B +=item B<< $attr->get_write_method >> -=item B +Returns the name of a method suitable for reading or writing the value +of the attribute in the associated class. -=item B +If an attribute is read- or write-only, then these methods can return +C as appropriate. -=item B +=item B<< $attr->has_read_method >> -=item B +=item B<< $attr->has_write_method >> -=item B +This returns a boolean indicating whether the attribute has a I +read or write method. -=item B +=item B<< $attr->get_read_method_ref >> -As noted in the documentation for C above, if the I -value is a CODE reference, this accessor will pass a single additional -argument C<$instance> into it and return the value. +=item B<< $attr->get_write_method_ref >> -=item B +Returns the subroutine reference of a method suitable for reading or +writing the attribute's value in the associated class. These methods +always return a subroutine reference, regardless of whether or not the +attribute is read- or write-only. -Returns a list of slots required by the attribute. This is usually -just one, which is the name of the attribute. +=item B<< $attr->insertion_order >> + +If this attribute has been inserted into a class, this returns a zero +based index regarding the order of insertion. =back @@ -513,88 +761,181 @@ These are all basic predicate methods for the values passed into C. =over 4 -=item B +=item B<< $attr->has_accessor >> + +=item B<< $attr->has_reader >> + +=item B<< $attr->has_writer >> + +=item B<< $attr->has_predicate >> + +=item B<< $attr->has_clearer >> + +=item B<< $attr->has_initializer >> -=item B +=item B<< $attr->has_init_arg >> -=item B +This will be I if the C was set to C. -=item B +=item B<< $attr->has_default >> -=item B +This will be I if the C was set to C, since +C is the default C anyway. -=item B +=item B<< $attr->has_builder >> + +=item B<< $attr->has_insertion_order >> + +This will be I if this attribute has not be inserted into a class =back -=head2 Class association +=head2 Value management + +These methods are basically "back doors" to the instance, and can be +used to bypass the regular accessors, but still stay within the MOP. + +These methods are not for general use, and should only be used if you +really know what you are doing. =over 4 -=item B +=item B<< $attr->initialize_instance_slot($meta_instance, $instance, $params) >> + +This method is used internally to initialize the attribute's slot in +the object C<$instance>. + +The C<$params> is a hash reference of the values passed to the object +constructor. + +It's unlikely that you'll need to call this method yourself. + +=item B<< $attr->set_value($instance, $value) >> + +Sets the value without going through the accessor. Note that this +works even with read-only attributes. + +=item B<< $attr->set_raw_value($instance, $value) >> + +Sets the value with no side effects such as a trigger. + +This doesn't actually apply to Class::MOP attributes, only to subclasses. + +=item B<< $attr->set_initial_value($instance, $value) >> + +Sets the value without going through the accessor. This method is only +called when the instance is first being initialized. + +=item B<< $attr->get_value($instance) >> -=item B +Returns the value without going through the accessor. Note that this +works even with write-only accessors. -=item B +=item B<< $attr->get_raw_value($instance) >> -=item B +Returns the value without any side effects such as lazy attributes. -=item B +Doesn't actually apply to Class::MOP attributes, only to subclasses. -=item B +=item B<< $attr->has_value($instance) >> + +Return a boolean indicating whether the attribute has been set in +C<$instance>. This how the default C method works. + +=item B<< $attr->clear_value($instance) >> + +This will clear the attribute's value in C<$instance>. This is what +the default C calls. + +Note that this works even if the attribute does not have any +associated read, write or clear methods. =back -=head2 Attribute Accessor generation +=head2 Class association + +These methods allow you to manage the attributes association with +the class that contains it. These methods should not be used +lightly, nor are they very magical, they are mostly used internally +and by metaclass instances. =over 4 -=item B +=item B<< $attr->associated_class >> -This allows the attribute to generate and install code for it's own -I methods. This is called by -C. +This returns the C with which this attribute is +associated, if any. -This method will call C for each of the possible -method types (accessor, reader, writer & predicate). +=item B<< $attr->attach_to_class($metaclass) >> -=item B +This method stores a weakened reference to the C<$metaclass> object +internally. -This takes a C<$type> (accessor, reader, writer or predicate), and -a C<$value> (the value passed into the constructor for each of the -different types). It will then either generate the method itself -(using the C methods listed below) or it will -use the custom method passed through the constructor. +This method does not remove the attribute from its old class, +nor does it create any accessors in the new class. -=over 4 +It is probably best to use the L C +method instead. -=item B +=item B<< $attr->detach_from_class >> -=item B +This method removes the associate metaclass object from the attribute +it has one. -=item B +This method does not remove the attribute itself from the class, or +remove its accessors. -=item B +It is probably best to use the L +C method instead. =back +=head2 Attribute Accessor generation + =over 4 -=item B +=item B<< $attr->accessor_metaclass >> -=item B +Accessor methods are generated using an accessor metaclass. By +default, this is L. This method returns +the name of the accessor metaclass that this attribute uses. -=item B +=item B<< $attr->associate_method($method) >> -=item B +This associates a L object with the +attribute. Typically, this is called internally when an attribute +generates its accessors. -=back +=item B<< $attr->associated_methods >> -=item B +This returns the list of methods which have been associated with the +attribute. -This allows the attribute to remove the method for it's own -I. This is called by -C. +=item B<< $attr->install_accessors >> + +This method generates and installs code the attributes various +accessors. It is typically called from the L +C method. + +=item B<< $attr->remove_accessors >> + +This method removes all of the accessors associated with the +attribute. + +This does not currently remove methods from the list returned by +C. + +=item B<< $attr->inline_get >> + +=item B<< $attr->inline_set >> + +=item B<< $attr->inline_has >> + +=item B<< $attr->inline_clear >> + +These methods return a code snippet suitable for inlining the relevant +operation. They expect strings containing variable names to be used in the +inlining, like C<'$self'> or C<'$_[1]'>. =back @@ -602,29 +943,29 @@ C. =over 4 -=item B +=item B<< Class::MOP::Attribute->meta >> -This will return a B instance which is related -to this class. +This will return a L instance for this class. -It should also be noted that B will actually bootstrap -this module by installing a number of attribute meta-objects into -it's metaclass. This will allow this class to reap all the benifits -of the MOP when subclassing it. +It should also be noted that L will actually bootstrap +this module by installing a number of attribute meta-objects into its +metaclass. =back -=head1 AUTHOR +=head1 AUTHORS Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE -Copyright 2006 by Infinity Interactive, Inc. +Copyright 2006-2010 by Infinity Interactive, Inc. L This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +it under the same terms as Perl itself. + +=cut + -=cut \ No newline at end of file