X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FClass%2FMOP%2FImmutable.pm;h=0231dc10437fe9b938f6afd307477b59eea3df8e;hb=f1dc35403251ed96f803ff9977f41a53b64eb1cd;hp=2b4e0d38c7b7f0b159074eb348d69cbba58c4a6b;hpb=127d39a79d936afd136ccfd8ff8271eea2bc0cbb;p=gitmo%2FClass-MOP.git diff --git a/lib/Class/MOP/Immutable.pm b/lib/Class/MOP/Immutable.pm index 2b4e0d3..0231dc1 100644 --- a/lib/Class/MOP/Immutable.pm +++ b/lib/Class/MOP/Immutable.pm @@ -9,45 +9,155 @@ use Class::MOP::Method::Constructor; use Carp 'confess'; use Scalar::Util 'blessed'; -our $VERSION = '0.04'; +our $VERSION = '0.78'; +$VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; -sub new { - my ($class, $metaclass, $options) = @_; +use base 'Class::MOP::Object'; - my $self = bless { - '$!metaclass' => $metaclass, - '%!options' => $options, - '$!immutable_metaclass' => undef, - } => $class; +sub new { + my ($class, @args) = @_; + + unshift @args, 'metaclass' if @args % 2 == 1; + + my %options = ( + inline_accessors => 1, + inline_constructor => 1, + inline_destructor => 0, + constructor_name => 'new', + constructor_class => 'Class::MOP::Method::Constructor', + debug => 0, + @args, + ); - # NOTE: - # we initialize the immutable - # version of the metaclass here - $self->create_immutable_metaclass; + my $self = $class->_new( + 'metaclass' => delete $options{metaclass}, + 'options' => \%options, + 'immutable_metaclass' => undef, + 'inlined_constructor' => undef, + ); return $self; } -sub immutable_metaclass { (shift)->{'$!immutable_metaclass'} } -sub metaclass { (shift)->{'$!metaclass'} } -sub options { (shift)->{'%!options'} } +sub _new { + my $class = shift; + my $options = @_ == 1 ? $_[0] : {@_}; -sub create_immutable_metaclass { + bless $options, $class; +} + +sub immutable_metaclass { my $self = shift; - # NOTE: - # The immutable version of the - # metaclass is just a anon-class - # which shadows the methods - # appropriately - $self->{'$!immutable_metaclass'} = Class::MOP::Class->create_anon_class( + return $self->{'immutable_metaclass'} ||= $self->_create_immutable_metaclass; +} + +sub metaclass { (shift)->{'metaclass'} } +sub options { (shift)->{'options'} } +sub inlined_constructor { (shift)->{'inlined_constructor'} } + +sub _create_immutable_metaclass { + my $self = shift; + + # NOTE: The immutable version of the metaclass is just a + # anon-class which shadows the methods appropriately + return Class::MOP::Class->create_anon_class( superclasses => [ blessed($self->metaclass) ], - methods => $self->create_methods_for_immutable_metaclass, + methods => $self->_create_methods_for_immutable_metaclass, + ); +} + +sub make_metaclass_immutable { + my $self = shift; + + $self->_inline_accessors; + $self->_inline_constructor; + $self->_inline_destructor; + $self->_check_memoized_methods; + + my $metaclass = $self->metaclass; + + $metaclass->{'___original_class'} = blessed($metaclass); + bless $metaclass => $self->immutable_metaclass->name; +} + +sub _inline_accessors { + my $self = shift; + + return unless $self->options->{inline_accessors}; + + foreach my $attr_name ( $self->metaclass->get_attribute_list ) { + $self->metaclass->get_attribute($attr_name)->install_accessors(1); + } +} + +sub _inline_constructor { + my $self = shift; + + return unless $self->options->{inline_constructor}; + + return + unless $self->options->{replace_constructor} + or !$self->metaclass->has_method( + $self->options->{constructor_name} + ); + + my $constructor_class = $self->options->{constructor_class}; + + my $constructor = $constructor_class->new( + options => $self->options, + metaclass => $self->metaclass, + is_inline => 1, + package_name => $self->metaclass->name, + name => $self->options->{constructor_name}, ); + + if ( $self->options->{replace_constructor} + or $constructor->can_be_inlined ) { + $self->metaclass->add_method( + $self->options->{constructor_name} => $constructor ); + $self->{inlined_constructor} = $constructor; + } +} + +sub _inline_destructor { + my $self = shift; + + return unless $self->options->{inline_destructor}; + + ( exists $self->options->{destructor_class} ) + || confess "The 'inline_destructor' option is present, but " + . "no destructor class was specified"; + + my $destructor_class = $self->options->{destructor_class}; + + return unless $destructor_class->is_needed( $self->metaclass ); + + my $destructor = $destructor_class->new( + options => $self->options, + metaclass => $self->metaclass, + package_name => $self->metaclass->name, + name => 'DESTROY' + ); + + return unless $destructor->is_needed; + + $self->metaclass->add_method( 'DESTROY' => $destructor ); } +sub _check_memoized_methods { + my $self = shift; + my $memoized_methods = $self->options->{memoize}; + foreach my $method_name ( keys %{$memoized_methods} ) { + my $type = $memoized_methods->{$method_name}; + + ( $self->metaclass->can($method_name) ) + || confess "Could not find the method '$method_name' in " + . $self->metaclass->name; + } +} my %DEFAULT_METHODS = ( # I don't really understand this, but removing it breaks tests (groditi) meta => sub { @@ -57,118 +167,163 @@ my %DEFAULT_METHODS = ( return Class::MOP::Class->initialize($self) unless blessed($self); # otherwise, they are asking for the metaclass # which has been made immutable, which is itself - return $self; + # except in the cases where it is a metaclass itself + # that has been made immutable and for that we need + # to dig a bit ... + if ($self->isa('Class::MOP::Class')) { + return $self->{'___original_class'}->meta; + } + else { + return $self; + } }, is_mutable => sub { 0 }, is_immutable => sub { 1 }, make_immutable => sub { () }, ); -# NOTE: -# this will actually convert the -# existing metaclass to an immutable -# version of itself -sub make_metaclass_immutable { - my ($self, $metaclass, $options) = @_; - - foreach my $pair ( - [ inline_accessors => 1 ], - [ inline_constructor => 1 ], - [ inline_destructor => 0 ], - [ constructor_name => 'new' ], - [ debug => 0 ], - ) { - $options->{$pair->[0]} = $pair->[1] unless exists $options->{$pair->[0]}; - } +sub _create_methods_for_immutable_metaclass { + my $self = shift; - my %options = %$options; + my $metaclass = $self->metaclass; + my $meta = $metaclass->meta; + + return { + %DEFAULT_METHODS, + $self->_make_read_only_methods, + $self->_make_uncallable_methods, + $self->_make_memoized_methods, + $self->_make_wrapped_methods, + get_mutable_metaclass_name => sub { (shift)->{'___original_class'} }, + immutable_transformer => sub {$self}, + }; +} - if ($options{inline_accessors}) { - foreach my $attr_name ($metaclass->get_attribute_list) { - # inline the accessors - $metaclass->get_attribute($attr_name) - ->install_accessors(1); - } - } +sub _make_read_only_methods { + my $self = shift; + + my $metameta = $self->metaclass->meta; + + my %methods; + foreach my $read_only_method ( @{ $self->options->{read_only} } ) { + my $method = $metameta->find_method_by_name($read_only_method); - if ($options{inline_constructor}) { - my $constructor_class = $options{constructor_class} || 'Class::MOP::Method::Constructor'; - $metaclass->add_method( - $options{constructor_name}, - $constructor_class->new( - options => \%options, - metaclass => $metaclass, - is_inline => 1, - ) - ) unless $metaclass->has_method($options{constructor_name}); + ( defined $method ) + || confess "Could not find the method '$read_only_method' in " + . $self->metaclass->name; + + $methods{$read_only_method} = sub { + confess "This method is read-only" if scalar @_ > 1; + goto &{ $method->body }; + }; } - if ($options{inline_destructor}) { - (exists $options{destructor_class}) - || confess "The 'inline_destructor' option is present, but " - . "no destructor class was specified"; - - my $destructor_class = $options{destructor_class}; - - my $destructor = $destructor_class->new( - options => \%options, - metaclass => $metaclass, - ); - - $metaclass->add_method('DESTROY' => $destructor) - # NOTE: - # we allow the destructor to determine - # if it is needed or not, it can perform - # all sorts of checks because it has the - # metaclass instance - if $destructor->is_needed; + return %methods; +} + +sub _make_uncallable_methods { + my $self = shift; + + my %methods; + foreach my $cannot_call_method ( @{ $self->options->{cannot_call} } ) { + $methods{$cannot_call_method} = sub { + confess + "This method ($cannot_call_method) cannot be called on an immutable instance"; + }; } - my $memoized_methods = $self->options->{memoize}; - foreach my $method_name (keys %{$memoized_methods}) { - my $type = $memoized_methods->{$method_name}; + return %methods; +} + +sub _make_memoized_methods { + my $self = shift; - ($metaclass->can($method_name)) - || confess "Could not find the method '$method_name' in " . $metaclass->name; + my %methods; - if ($type eq 'ARRAY') { - $metaclass->{'___' . $method_name} = [ $metaclass->$method_name ]; + my $metameta = $self->metaclass->meta; + + my $memoized_methods = $self->options->{memoize}; + foreach my $method_name ( keys %{$memoized_methods} ) { + my $type = $memoized_methods->{$method_name}; + my $key = '___' . $method_name; + my $method = $metameta->find_method_by_name($method_name); + + if ( $type eq 'ARRAY' ) { + $methods{$method_name} = sub { + @{ $_[0]->{$key} } = $method->execute( $_[0] ) + if !exists $_[0]->{$key}; + return @{ $_[0]->{$key} }; + }; } - elsif ($type eq 'HASH') { - $metaclass->{'___' . $method_name} = { $metaclass->$method_name }; + elsif ( $type eq 'HASH' ) { + $methods{$method_name} = sub { + %{ $_[0]->{$key} } = $method->execute( $_[0] ) + if !exists $_[0]->{$key}; + return %{ $_[0]->{$key} }; + }; } - elsif ($type eq 'SCALAR') { - $metaclass->{'___' . $method_name} = $metaclass->$method_name; + elsif ( $type eq 'SCALAR' ) { + $methods{$method_name} = sub { + $_[0]->{$key} = $method->execute( $_[0] ) + if !exists $_[0]->{$key}; + return $_[0]->{$key}; + }; } } - $metaclass->{'___original_class'} = blessed($metaclass); - bless $metaclass => $self->immutable_metaclass->name; + return %methods; +} + +sub _make_wrapped_methods { + my $self = shift; + + my %methods; + + my $wrapped_methods = $self->options->{wrapped}; + + my $metameta = $self->metaclass->meta; + + foreach my $method_name ( keys %{$wrapped_methods} ) { + my $method = $metameta->find_method_by_name($method_name); + + ( defined $method ) + || confess "Could not find the method '$method_name' in " + . $self->metaclass->name; + + my $wrapper = $wrapped_methods->{$method_name}; + + $methods{$method_name} = sub { $wrapper->( $method, @_ ) }; + } + + return %methods; } sub make_metaclass_mutable { - my ($self, $immutable, $options) = @_; + my $self = shift; - my %options = %$options; + my $metaclass = $self->metaclass; - my $original_class = $immutable->get_mutable_metaclass_name; - delete $immutable->{'___original_class'} ; - bless $immutable => $original_class; + my $original_class = $metaclass->get_mutable_metaclass_name; + delete $metaclass->{'___original_class'}; + bless $metaclass => $original_class; my $memoized_methods = $self->options->{memoize}; - foreach my $method_name (keys %{$memoized_methods}) { + foreach my $method_name ( keys %{$memoized_methods} ) { my $type = $memoized_methods->{$method_name}; - ($immutable->can($method_name)) - || confess "Could not find the method '$method_name' in " . $immutable->name; - if ($type eq 'SCALAR' || $type eq 'ARRAY' || $type eq 'HASH' ) { - delete $immutable->{'___' . $method_name}; + ( $metaclass->can($method_name) ) + || confess "Could not find the method '$method_name' in " + . $metaclass->name; + if ( $type eq 'SCALAR' || $type eq 'ARRAY' || $type eq 'HASH' ) { + delete $metaclass->{ '___' . $method_name }; } } - if ($options{inline_destructor} && $immutable->has_method('DESTROY')) { - $immutable->remove_method('DESTROY') - if $immutable->get_method('DESTROY')->blessed eq $options{destructor_class}; + if ( $self->options->{inline_destructor} + && $metaclass->has_method('DESTROY') ) { + $metaclass->remove_method('DESTROY') + if blessed( $metaclass->get_method('DESTROY') ) eq + $self->options->{destructor_class}; } # NOTE: @@ -188,55 +343,20 @@ sub make_metaclass_mutable { # 14:26 <@stevan> the only user of ::Method::Constructor is immutable # 14:27 <@stevan> if someone uses it outside of immutable,.. they are either: mst or groditi # 14:27 <@stevan> so I am not worried - if ($options{inline_constructor}) { - my $constructor_class = $options{constructor_class} || 'Class::MOP::Method::Constructor'; - $immutable->remove_method( $options{constructor_name} ) - if $immutable->get_method($options{constructor_name})->blessed eq $constructor_class; - } -} - -sub create_methods_for_immutable_metaclass { - my $self = shift; - - my %methods = %DEFAULT_METHODS; - - foreach my $read_only_method (@{$self->options->{read_only}}) { - my $method = $self->metaclass->meta->find_method_by_name($read_only_method); - - (defined $method) - || confess "Could not find the method '$read_only_method' in " . $self->metaclass->name; - - $methods{$read_only_method} = sub { - confess "This method is read-only" if scalar @_ > 1; - goto &{$method->body} - }; - } - - foreach my $cannot_call_method (@{$self->options->{cannot_call}}) { - $methods{$cannot_call_method} = sub { - confess "This method ($cannot_call_method) cannot be called on an immutable instance"; - }; - } - - my $memoized_methods = $self->options->{memoize}; - foreach my $method_name (keys %{$memoized_methods}) { - my $type = $memoized_methods->{$method_name}; - if ($type eq 'ARRAY') { - $methods{$method_name} = sub { @{$_[0]->{'___' . $method_name}} }; - } - elsif ($type eq 'HASH') { - $methods{$method_name} = sub { %{$_[0]->{'___' . $method_name}} }; - } - elsif ($type eq 'SCALAR') { - $methods{$method_name} = sub { $_[0]->{'___' . $method_name} }; + if ( $self->options->{inline_constructor} + && $metaclass->has_method( $self->options->{constructor_name} ) ) { + my $constructor_class = $self->options->{constructor_class} + || 'Class::MOP::Method::Constructor'; + + if ( + blessed( + $metaclass->get_method( $self->options->{constructor_name} ) + ) eq $constructor_class + ) { + $metaclass->remove_method( $self->options->{constructor_name} ); + $self->{inlined_constructor} = undef; } } - - $methods{get_mutable_metaclass_name} = sub { (shift)->{'___original_class'} }; - - $methods{immutable_transformer} = sub { $self }; - - return \%methods; } 1; @@ -272,65 +392,115 @@ Class::MOP::Immutable - A class to transform Class::MOP::Class metaclasses } }); - $immutable_metaclass->make_metaclass_immutable(@_) + $immutable_metaclass->make_metaclass_immutable; =head1 DESCRIPTION -This is basically a module for applying a transformation on a given -metaclass. Current features include making methods read-only, -making methods un-callable and memoizing methods (in a type specific -way too). +This class encapsulates the logic behind immutabilization. -This module is not for the feint of heart, it does some whacky things -to the metaclass in order to make it immutable. If you are just curious, -I suggest you turn back now, there is nothing to see here. +This class provides generic immutabilization logic. Decisions about +I gets transformed are up to the caller. + +Immutabilization allows for a number of transformations. It can ask +the calling metaclass to inline methods such as the constructor, +destructor, or accessors. It can memoize metaclass accessors +themselves. It can also turn read-write accessors in the metaclass +into read-only methods, and make attempting to set these values an +error. Finally, it can make some methods throw an exception when they +are called. This is used to disable methods that can alter the class. =head1 METHODS =over 4 -=item B +=item B<< Class::MOP::Immutable->new($metaclass, %options) >> -Given a C<$metaclass> and a set of C<%options> this module will -prepare an immutable version of the C<$metaclass>, which can then -be applied to the C<$metaclass> using the C -method. +This method takes a metaclass object (typically a L +object) and a hash of options. -=item B +It returns a new transformer, but does not actually do any +transforming yet. -Returns the options HASH set in C. +This method accepts the following options: -=item B +=over 8 -Returns the metaclass set in C. +=item * inline_accessors -=item B +=item * inline_constructor -Returns the immutable metaclass created within C. +=item * inline_destructor -=back +These are all booleans indicating whether the specified method(s) +should be inlined. -=over 4 +By default, accessors and the constructor are inlined, but not the +destructor. + +=item * replace_constructor + +This is a boolean indicating whether an existing constructor should be +replaced when inlining a constructor. This defaults to false. + +=item * constructor_name + +This is the constructor method name. This defaults to "new". + +=item * constructor_class + +The name of the method metaclass for constructors. It will be used to +generate the inlined constructor. This defaults to +"Class::MOP::Method::Constructor". + +=item * destructor_class + +The name of the method metaclass for destructors. It will be used to +generate the inlined destructor. This defaults to +"Class::MOP::Method::Denstructor". + +=item * memoize + +This option takes a hash reference. They keys are method names to be +memoized, and the values are the type of data the method returns. This +can be one of "SCALAR", "ARRAY", or "HASH". + +=item * read_only + +This option takes an array reference of read-write methods which will +be made read-only. After they are transformed, attempting to set them +will throw an error. + +=item * cannot_call + +This option takes an array reference of methods which cannot be called +after immutabilization. Attempting to call these methods will throw an +error. + +=item * wrapped + +This option takes a hash reference. The keys are method names and the +body is a subroutine reference which will wrap the named method. This +allows you to do some sort of custom transformation to a method. + +=back -=item B +=item B<< $transformer->options >> -This will create the immutable version of the C<$metaclass>, but will -not actually change the original metaclass. +Returns a hash reference of the options passed to C. -=item B +=item B<< $transformer->metaclass >> -This will create all the methods for the immutable metaclass based -on the C<%options> passed into C. +Returns the metaclass object passed to C. -=item B +=item B<< $transformer->immutable_metaclass >> -This will actually change the C<$metaclass> into the immutable version. +Returns the immutable metaclass object that is created by the +transformation process. -=item B +=item B<< $transformer->inlined_constructor >> -This will change the C<$metaclass> into the mutable version by reversing -the immutable process. C<%options> should be the same options that were -given to make_metaclass_immutable. +If the constructor was inlined, this returns the constructor method +object that was created to do this. =back @@ -340,7 +510,7 @@ Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE -Copyright 2006-2008 by Infinity Interactive, Inc. +Copyright 2006-2009 by Infinity Interactive, Inc. L