X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FClass%2FMOP%2FClass.pm;h=8678844af9f6aec808a759a64787ee0fb5e70d87;hb=53edec17bae8aa34a398b0bd50dcd7e78e03b733;hp=f0ea041ec5b45ddc545228f59ff50d172b10f56d;hpb=e00524a03329f89358767302ffc62cd15ec33571;p=gitmo%2FClass-MOP.git diff --git a/lib/Class/MOP/Class.pm b/lib/Class/MOP/Class.pm index f0ea041..8678844 100644 --- a/lib/Class/MOP/Class.pm +++ b/lib/Class/MOP/Class.pm @@ -8,12 +8,14 @@ use Class::MOP::Instance; use Class::MOP::Method::Wrapped; use Class::MOP::Method::Accessor; use Class::MOP::Method::Constructor; -use Class::MOP::Class::Immutable::Class::MOP::Class; use Carp 'confess'; -use Scalar::Util 'blessed', 'weaken'; +use Scalar::Util 'blessed', 'reftype', 'weaken'; +use Sub::Name 'subname'; +use Devel::GlobalDestruction 'in_global_destruction'; +use Try::Tiny; -our $VERSION = '0.83'; +our $VERSION = '0.95'; $VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; @@ -33,19 +35,13 @@ sub initialize { $package_name = $options{package}; } - (defined $package_name && $package_name && !ref($package_name)) + ($package_name && !ref($package_name)) || confess "You must pass a package name and it cannot be blessed"; return Class::MOP::get_metaclass_by_name($package_name) || $class->_construct_class_instance(package => $package_name, @_); } -sub construct_class_instance { - Carp::cluck('The construct_class_instance method has been made private.' - . " The public version is deprecated and will be removed in a future release.\n"); - shift->_construct_class_instance(@_); -} - # NOTE: (meta-circularity) # this is a special form of _construct_instance # (see below), which is used to construct class @@ -74,7 +70,7 @@ sub _construct_class_instance { # get the name of the class appropriately $class = (ref($class) ? ($class->is_immutable - ? $class->get_mutable_metaclass_name() + ? $class->_get_mutable_metaclass_name() : ref($class)) : $class); @@ -106,9 +102,13 @@ sub _construct_class_instance { sub _new { my $class = shift; + + return Class::MOP::Class->initialize($class)->new_object(@_) + if $class ne __PACKAGE__; + my $options = @_ == 1 ? $_[0] : {@_}; - bless { + return bless { # inherited from Class::MOP::Package 'package' => $options->{package}, @@ -121,6 +121,7 @@ sub _new { # should not actually have a value associated # with the slot. 'namespace' => \undef, + 'methods' => {}, # inherited from Class::MOP::Module 'version' => \undef, @@ -129,7 +130,6 @@ sub _new { # defined in Class::MOP::Class 'superclasses' => \undef, - 'methods' => {}, 'attributes' => {}, 'attribute_metaclass' => ( $options->{'attribute_metaclass'} || 'Class::MOP::Attribute' ), @@ -165,13 +165,6 @@ sub update_package_cache_flag { $self->{'_package_cache_flag'} = Class::MOP::check_package_cache_flag($self->name); } - -sub check_metaclass_compatibility { - Carp::cluck('The check_metaclass_compatibility method has been made private.' - . " The public version is deprecated and will be removed in a future release.\n"); - shift->_check_metaclass_compatibility(@_); -} - sub _check_metaclass_compatibility { my $self = shift; @@ -191,21 +184,21 @@ sub _check_metaclass_compatibility { # get the name of the class appropriately my $super_meta_type = $super_meta->is_immutable - ? $super_meta->get_mutable_metaclass_name() + ? $super_meta->_get_mutable_metaclass_name() : ref($super_meta); ($self->isa($super_meta_type)) - || confess "Class::MOP::class_of(" . $self->name . ") => (" + || confess "The metaclass of " . $self->name . " (" . (ref($self)) . ")" . " is not compatible with the " . - "Class::MOP::class_of(".$superclass_name . ") => (" + "metaclass of its superclass, ".$superclass_name . " (" . ($super_meta_type) . ")"; # NOTE: # we also need to check that instance metaclasses # are compatibile in the same the class. ($self->instance_metaclass->isa($super_meta->instance_metaclass)) - || confess "Class::MOP::class_of(" . $self->name . ")->instance_metaclass => (" . ($self->instance_metaclass) . ")" . + || confess "The instance metaclass for " . $self->name . " (" . ($self->instance_metaclass) . ")" . " is not compatible with the " . - "Class::MOP::class_of(" . $superclass_name . ")->instance_metaclass => (" . ($super_meta->instance_metaclass) . ")"; + "instance metaclass of its superclass, " . $superclass_name . " (" . ($super_meta->instance_metaclass) . ")"; } } @@ -228,7 +221,7 @@ sub _check_metaclass_compatibility { sub is_anon_class { my $self = shift; no warnings 'uninitialized'; - $self->name =~ /^$ANON_CLASS_PREFIX/; + $self->name =~ /^$ANON_CLASS_PREFIX/o; } sub create_anon_class { @@ -246,24 +239,26 @@ sub _check_metaclass_compatibility { sub DESTROY { my $self = shift; - return if Class::MOP::in_global_destruction(); # it'll happen soon anyway and this just makes things more complicated + return if in_global_destruction(); # it'll happen soon anyway and this just makes things more complicated no warnings 'uninitialized'; - return unless $self->name =~ /^$ANON_CLASS_PREFIX/; + my $name = $self->name; + return unless $name =~ /^$ANON_CLASS_PREFIX/o; # Moose does a weird thing where it replaces the metaclass for # class when fixing metaclass incompatibility. In that case, # we don't want to clean out the namespace now. We can detect # that because Moose will explicitly update the singleton # cache in Class::MOP. - my $current_meta = Class::MOP::get_metaclass_by_name($self->name); + my $current_meta = Class::MOP::get_metaclass_by_name($name); return if $current_meta ne $self; - my ($serial_id) = ($self->name =~ /^$ANON_CLASS_PREFIX(\d+)/); + my ($serial_id) = ($name =~ /^$ANON_CLASS_PREFIX(\d+)/o); no strict 'refs'; - foreach my $key (keys %{$ANON_CLASS_PREFIX . $serial_id}) { - delete ${$ANON_CLASS_PREFIX . $serial_id}{$key}; - } - delete ${'main::' . $ANON_CLASS_PREFIX}{$serial_id . '::'}; + @{$name . '::ISA'} = (); + %{$name . '::'} = (); + delete ${$ANON_CLASS_PREFIX}{$serial_id . '::'}; + + Class::MOP::remove_metaclass_by_name($name); } } @@ -334,10 +329,8 @@ sub create { # all these attribute readers will be bootstrapped # away in the Class::MOP bootstrap section -sub get_attribute_map { $_[0]->{'attributes'} } +sub _attribute_map { $_[0]->{'attributes'} } sub attribute_metaclass { $_[0]->{'attribute_metaclass'} } -sub method_metaclass { $_[0]->{'method_metaclass'} } -sub wrapped_method_metaclass { $_[0]->{'wrapped_method_metaclass'} } sub instance_metaclass { $_[0]->{'instance_metaclass'} } sub immutable_trait { $_[0]->{'immutable_trait'} } sub constructor_class { $_[0]->{'constructor_class'} } @@ -359,24 +352,22 @@ sub new_object { return $class->_construct_instance(@_); } -sub construct_instance { - Carp::cluck('The construct_instance method has been made private.' - . " The public version is deprecated and will be removed in a future release.\n"); - shift->_construct_instance(@_); -} - sub _construct_instance { my $class = shift; my $params = @_ == 1 ? $_[0] : {@_}; my $meta_instance = $class->get_meta_instance(); - my $instance = $meta_instance->create_instance(); + # FIXME: + # the code below is almost certainly incorrect + # but this is foreign inheritance, so we might + # have to kludge it in the end. + my $instance = $params->{__INSTANCE__} || $meta_instance->create_instance(); foreach my $attr ($class->get_all_attributes()) { $attr->initialize_instance_slot($meta_instance, $instance, $params); } # NOTE: # this will only work for a HASH instance type if ($class->is_anon_class) { - (Scalar::Util::reftype($instance) eq 'HASH') + (reftype($instance) eq 'HASH') || confess "Currently only HASH based instances are supported with instance of anon-classes"; # NOTE: # At some point we should make this official @@ -394,12 +385,6 @@ sub get_meta_instance { $self->{'_meta_instance'} ||= $self->_create_meta_instance(); } -sub create_meta_instance { - Carp::cluck('The create_meta_instance method has been made private.' - . " The public version is deprecated and will be removed in a future release.\n"); - shift->_create_meta_instance(@_); -} - sub _create_meta_instance { my $self = shift; @@ -428,12 +413,6 @@ sub clone_object { $class->_clone_instance($instance, @_); } -sub clone_instance { - Carp::cluck('The clone_instance method has been made private.' - . " The public version is deprecated and will be removed in a future release.\n"); - shift->_clone_instance(@_); -} - sub _clone_instance { my ($class, $instance, %params) = @_; (blessed($instance)) @@ -515,11 +494,16 @@ sub superclasses { # we don't know about $self->_check_metaclass_compatibility(); - $self->update_meta_instance_dependencies(); + $self->_superclasses_updated(); } @{$self->get_package_symbol($var_spec)}; } +sub _superclasses_updated { + my $self = shift; + $self->update_meta_instance_dependencies(); +} + sub subclasses { my $self = shift; my $super_class = $self->name; @@ -527,6 +511,16 @@ sub subclasses { return @{ $super_class->mro::get_isarev() }; } +sub direct_subclasses { + my $self = shift; + my $super_class = $self->name; + + return grep { + grep { + $_ eq $super_class + } Class::MOP::Class->initialize($_)->superclasses + } $self->subclasses; +} sub linearized_isa { return @{ mro::get_linear_isa( (shift)->name ) }; @@ -568,52 +562,6 @@ sub class_precedence_list { ## Methods -sub wrap_method_body { - my ( $self, %args ) = @_; - - ('CODE' eq ref $args{body}) - || confess "Your code block must be a CODE reference"; - - $self->method_metaclass->wrap( - package_name => $self->name, - %args, - ); -} - -sub add_method { - my ($self, $method_name, $method) = @_; - (defined $method_name && $method_name) - || confess "You must define a method name"; - - my $body; - if (blessed($method)) { - $body = $method->body; - if ($method->package_name ne $self->name) { - $method = $method->clone( - package_name => $self->name, - name => $method_name - ) if $method->can('clone'); - } - } - else { - $body = $method; - $method = $self->wrap_method_body( body => $body, name => $method_name ); - } - - $method->attach_to_class($self); - - # This used to call get_method_map, which meant we would build all - # the method objects for the class just because we added one - # method. This is hackier, but quicker too. - $self->{methods}{$method_name} = $method; - - my $full_method_name = ($self->name . '::' . $method_name); - $self->add_package_symbol( - { sigil => '&', type => 'CODE', name => $method_name }, - Class::MOP::subname($full_method_name => $body) - ); -} - { my $fetch_and_prepare_method = sub { my ($self, $method_name) = @_; @@ -630,12 +578,17 @@ sub add_method { # and now make sure to wrap it # even if it is already wrapped # because we need a new sub ref - $method = $wrapped_metaclass->wrap($method); + $method = $wrapped_metaclass->wrap($method, + package_name => $self->name, + name => $method_name, + ); } else { # now make sure we wrap it properly - $method = $wrapped_metaclass->wrap($method) - unless $method->isa($wrapped_metaclass); + $method = $wrapped_metaclass->wrap($method, + package_name => $self->name, + name => $method_name, + ) unless $method->isa($wrapped_metaclass); } $self->add_method($method_name => $method); return $method; @@ -643,31 +596,31 @@ sub add_method { sub add_before_method_modifier { my ($self, $method_name, $method_modifier) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must pass in a method name"; my $method = $fetch_and_prepare_method->($self, $method_name); $method->add_before_modifier( - Class::MOP::subname(':before' => $method_modifier) + subname(':before' => $method_modifier) ); } sub add_after_method_modifier { my ($self, $method_name, $method_modifier) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must pass in a method name"; my $method = $fetch_and_prepare_method->($self, $method_name); $method->add_after_modifier( - Class::MOP::subname(':after' => $method_modifier) + subname(':after' => $method_modifier) ); } sub add_around_method_modifier { my ($self, $method_name, $method_modifier) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must pass in a method name"; my $method = $fetch_and_prepare_method->($self, $method_name); $method->add_around_modifier( - Class::MOP::subname(':around' => $method_modifier) + subname(':around' => $method_modifier) ); } @@ -685,92 +638,40 @@ sub add_method { # to, and so don't need the fully qualified name. } -sub alias_method { - Carp::cluck("The alias_method method is deprecated. Use add_method instead.\n"); - - shift->add_method(@_); -} - -sub has_method { - my ($self, $method_name) = @_; - (defined $method_name && $method_name) - || confess "You must define a method name"; - - exists $self->{methods}{$method_name} || exists $self->get_method_map->{$method_name}; -} - -sub get_method { - my ($self, $method_name) = @_; - (defined $method_name && $method_name) - || confess "You must define a method name"; - - return $self->{methods}{$method_name} || $self->get_method_map->{$method_name}; -} - -sub remove_method { - my ($self, $method_name) = @_; - (defined $method_name && $method_name) - || confess "You must define a method name"; - - my $removed_method = delete $self->get_method_map->{$method_name}; - - $self->remove_package_symbol( - { sigil => '&', type => 'CODE', name => $method_name } - ); - - $removed_method->detach_from_class if $removed_method; - - $self->update_package_cache_flag; # still valid, since we just removed the method from the map - - return $removed_method; -} - -sub get_method_list { - my $self = shift; - keys %{$self->get_method_map}; -} - sub find_method_by_name { my ($self, $method_name) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must define a method name to find"; foreach my $class ($self->linearized_isa) { - # fetch the meta-class ... - my $meta = $self->initialize($class); - return $meta->get_method($method_name) - if $meta->has_method($method_name); + my $method = $self->initialize($class)->get_method($method_name); + return $method if defined $method; } return; } sub get_all_methods { my $self = shift; - my %methods = map { %{ $self->initialize($_)->get_method_map } } reverse $self->linearized_isa; - return values %methods; -} -sub compute_all_applicable_methods { - Carp::cluck('The compute_all_applicable_methods method is deprecated.' - . " Use get_all_methods instead.\n"); - - return map { - { - name => $_->name, - class => $_->package_name, - code => $_, # sigh, overloading - }, - } shift->get_all_methods(@_); + my %methods; + for my $class ( reverse $self->linearized_isa ) { + my $meta = $self->initialize($class); + + $methods{$_} = $meta->get_method($_) + for $meta->get_method_list; + } + + return values %methods; } sub get_all_method_names { my $self = shift; my %uniq; - grep { $uniq{$_}++ == 0 } map { $_->name } $self->get_all_methods; + return grep { !$uniq{$_}++ } map { $self->initialize($_)->get_method_list } $self->linearized_isa; } sub find_all_methods_by_name { my ($self, $method_name) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must define a method name to find"; my @methods; foreach my $class ($self->linearized_isa) { @@ -787,15 +688,13 @@ sub find_all_methods_by_name { sub find_next_method_by_name { my ($self, $method_name) = @_; - (defined $method_name && $method_name) + (defined $method_name && length $method_name) || confess "You must define a method name to find"; my @cpl = $self->linearized_isa; shift @cpl; # discard ourselves foreach my $class (@cpl) { - # fetch the meta-class ... - my $meta = $self->initialize($class); - return $meta->get_method($method_name) - if $meta->has_method($method_name); + my $method = $self->initialize($class)->get_method($method_name); + return $method if defined $method; } return; } @@ -816,25 +715,35 @@ sub add_attribute { # about the class which it is attached to $attribute->attach_to_class($self); + my $attr_name = $attribute->name; + # then we remove attributes of a conflicting # name here so that we can properly detach # the old attr object, and remove any # accessors it would have generated - if ( $self->has_attribute($attribute->name) ) { - $self->remove_attribute($attribute->name); + if ( $self->has_attribute($attr_name) ) { + $self->remove_attribute($attr_name); } else { $self->invalidate_meta_instances(); } + + # get our count of previously inserted attributes and + # increment by one so this attribute knows its order + my $order = (scalar keys %{$self->_attribute_map}); + $attribute->_set_insertion_order($order); # then onto installing the new accessors - $self->get_attribute_map->{$attribute->name} = $attribute; + $self->_attribute_map->{$attr_name} = $attribute; # invalidate package flag here - my $e = do { local $@; eval { $attribute->install_accessors() }; $@ }; - if ( $e ) { - $self->remove_attribute($attribute->name); - die $e; + try { + local $SIG{__DIE__}; + $attribute->install_accessors(); } + catch { + $self->remove_attribute($attr_name); + die $_; + }; return $attribute; } @@ -902,16 +811,16 @@ sub invalidate_meta_instance { sub has_attribute { my ($self, $attribute_name) = @_; - (defined $attribute_name && $attribute_name) + (defined $attribute_name) || confess "You must define an attribute name"; - exists $self->get_attribute_map->{$attribute_name}; + exists $self->_attribute_map->{$attribute_name}; } sub get_attribute { my ($self, $attribute_name) = @_; - (defined $attribute_name && $attribute_name) + (defined $attribute_name) || confess "You must define an attribute name"; - return $self->get_attribute_map->{$attribute_name} + return $self->_attribute_map->{$attribute_name} # NOTE: # this will return undef anyway, so no need ... # if $self->has_attribute($attribute_name); @@ -920,11 +829,11 @@ sub get_attribute { sub remove_attribute { my ($self, $attribute_name) = @_; - (defined $attribute_name && $attribute_name) + (defined $attribute_name) || confess "You must define an attribute name"; - my $removed_attribute = $self->get_attribute_map->{$attribute_name}; + my $removed_attribute = $self->_attribute_map->{$attribute_name}; return unless defined $removed_attribute; - delete $self->get_attribute_map->{$attribute_name}; + delete $self->_attribute_map->{$attribute_name}; $self->invalidate_meta_instances(); $removed_attribute->remove_accessors(); $removed_attribute->detach_from_class(); @@ -933,22 +842,15 @@ sub remove_attribute { sub get_attribute_list { my $self = shift; - keys %{$self->get_attribute_map}; + keys %{$self->_attribute_map}; } sub get_all_attributes { my $self = shift; - my %attrs = map { %{ $self->initialize($_)->get_attribute_map } } reverse $self->linearized_isa; + my %attrs = map { %{ $self->initialize($_)->_attribute_map } } reverse $self->linearized_isa; return values %attrs; } -sub compute_all_applicable_attributes { - Carp::cluck('The compute_all_applicable_attributes method has been deprecated.' - . " Use get_all_attributes instead.\n"); - - shift->get_all_attributes(@_); -} - sub find_attribute_by_name { my ($self, $attr_name) = @_; foreach my $class ($self->linearized_isa) { @@ -968,12 +870,9 @@ sub is_pristine { return if $self->get_attribute_list; # or any non-declared methods - if ( my @methods = values %{ $self->get_method_map } ) { - my $metaclass = $self->method_metaclass; - foreach my $method ( @methods ) { - return if $method->isa("Class::MOP::Method::Generated"); - # FIXME do we need to enforce this too? return unless $method->isa($metaclass); - } + for my $method ( map { $self->get_method($_) } $self->get_method_list ) { + return if $method->isa("Class::MOP::Method::Generated"); + # FIXME do we need to enforce this too? return unless $method->isa( $self->method_metaclass ); } return 1; @@ -983,7 +882,8 @@ sub is_pristine { sub is_mutable { 1 } sub is_immutable { 0 } -sub immutable_transformer { return } + +sub immutable_options { %{ $_[0]{__immutable}{options} || {} } } sub _immutable_options { my ( $self, @args ) = @_; @@ -1047,41 +947,56 @@ sub _immutable_metaclass { my $trait = $args{immutable_trait} = $self->immutable_trait || confess "no immutable trait specified for $self"; - my $meta_attr = $self->meta->find_attribute_by_name("immutable_trait"); + my $meta = $self->meta; + my $meta_attr = $meta->find_attribute_by_name("immutable_trait"); my $class_name; if ( $meta_attr and $trait eq $meta_attr->default ) { - - # if the trait is the same as the default we try and pick a predictable - # name for the immutable metaclass - $class_name = "Class::MOP::Class::Immutable::" . ref($self); + # if the trait is the same as the default we try and pick a + # predictable name for the immutable metaclass + $class_name = 'Class::MOP::Class::Immutable::' . ref($self); } else { - $class_name - = join( "::", "Class::MOP::Class::Immutable::CustomTrait", $trait, - "ForMetaClass", ref($self) ); + $class_name = join '::', 'Class::MOP::Class::Immutable::CustomTrait', + $trait, 'ForMetaClass', ref($self); } - if ( Class::MOP::is_class_loaded($class_name) ) { - if ( $class_name->isa($trait) ) { - return $class_name; + return $class_name + if Class::MOP::is_class_loaded($class_name); + + # If the metaclass is a subclass of CMOP::Class which has had + # metaclass roles applied (via Moose), then we want to make sure + # that we preserve that anonymous class (see Fey::ORM for an + # example of where this matters). + my $meta_name + = $meta->is_immutable + ? $meta->_get_mutable_metaclass_name + : ref $meta; + + my $immutable_meta = $meta_name->create( + $class_name, + superclasses => [ ref $self ], + ); + + Class::MOP::load_class($trait); + for my $meth ( Class::MOP::Class->initialize($trait)->get_all_methods ) { + my $meth_name = $meth->name; + + if ( $immutable_meta->find_method_by_name( $meth_name ) ) { + $immutable_meta->add_around_method_modifier( $meth_name, $meth->body ); } else { - confess - "$class_name is already defined but does not inherit $trait"; + $immutable_meta->add_method( $meth_name, $meth->clone ); } } - else { - my @super = ( $trait, ref($self) ); - - my $meta = Class::MOP::Class->initialize($class_name); - $meta->superclasses(@super); - $meta->make_immutable; + $immutable_meta->make_immutable( + inline_constructor => 0, + inline_accessors => 0, + ); - return $class_name; - } + return $class_name; } sub _remove_inlined_code { @@ -1119,7 +1034,7 @@ sub _install_inlined_code { sub _rebless_as_mutable { my $self = shift; - bless $self, $self->get_mutable_metaclass_name; + bless $self, $self->_get_mutable_metaclass_name; return $self; } @@ -1137,11 +1052,7 @@ sub _inline_constructor { my $name = $args{constructor_name}; - #if ( my $existing = $self->name->can($args{constructor_name}) ) { - # if ( refaddr($existing) == refaddr(\&Moose::Object::new) ) { - - unless ( $args{replace_constructor} - or !$self->has_method($name) ) { + if ( $self->has_method($name) && !$args{replace_constructor} ) { my $class = $self->name; warn "Not inlining a constructor for $class since it defines" . " its own constructor.\n" @@ -1172,10 +1083,17 @@ sub _inline_constructor { sub _inline_destructor { my ( $self, %args ) = @_; - ( exists $args{destructor_class} ) + ( exists $args{destructor_class} && defined $args{destructor_class} ) || confess "The 'inline_destructor' option is present, but " . "no destructor class was specified"; + if ( $self->has_method('DESTROY') && ! $args{replace_destructor} ) { + my $class = $self->name; + warn "Not inlining a destructor for $class since it defines" + . " its own destructor.\n"; + return; + } + my $destructor_class = $args{destructor_class}; Class::MOP::load_class($destructor_class); @@ -1189,9 +1107,10 @@ sub _inline_destructor { name => 'DESTROY' ); - $self->add_method( 'DESTROY' => $destructor ); - - $self->_add_inlined_method($destructor); + if ( $args{replace_destructor} or $destructor->can_be_inlined ) { + $self->add_method( 'DESTROY' => $destructor ); + $self->_add_inlined_method($destructor); + } } 1; @@ -1214,12 +1133,12 @@ Class::MOP::Class - Class Meta Object # add a method to Foo ... Foo->meta->add_method( 'bar' => sub {...} ) - # get a list of all the classes searched - # the method dispatcher in the correct order - Foo->meta->class_precedence_list() + # get a list of all the classes searched + # the method dispatcher in the correct order + Foo->meta->class_precedence_list() - # remove a method from Foo - Foo->meta->remove_method('bar'); + # remove a method from Foo + Foo->meta->remove_method('bar'); # or use this to actually create classes ... @@ -1228,8 +1147,8 @@ Class::MOP::Class - Class Meta Object version => '0.01', superclasses => ['Foo'], attributes => [ - Class::MOP:: : Attribute->new('$bar'), - Class::MOP:: : Attribute->new('$baz'), + Class::MOP::Attribute->new('$bar'), + Class::MOP::Attribute->new('$baz'), ], methods => { calculate_bar => sub {...}, @@ -1243,7 +1162,7 @@ Class::MOP::Class - Class Meta Object The Class Protocol is the largest and most complex part of the Class::MOP meta-object protocol. It controls the introspection and manipulation of Perl 5 classes, and it can create them as well. The -best way to understand what this module can do, is to read the +best way to understand what this module can do is to read the documentation for each of its methods. =head1 INHERITANCE @@ -1255,7 +1174,7 @@ C is a subclass of L. =head2 Class construction These methods all create new C objects. These -objects can represent existing classes, or they can be used to create +objects can represent existing classes or they can be used to create new classes from scratch. The metaclass object for a given class is a singleton. If you attempt @@ -1267,7 +1186,7 @@ existing object. =item B<< Class::MOP::Class->create($package_name, %options) >> This method creates a new C object with the given -package name. It accepts a number of options. +package name. It accepts a number of options: =over 8 @@ -1286,15 +1205,11 @@ An optional array reference of superclass names. =item * methods An optional hash reference of methods for the class. The keys of the -hash reference are method names, and values are subroutine references. +hash reference are method names and values are subroutine references. =item * attributes -An optional array reference of attributes. - -An attribute can be passed as an existing L -object, I or as a hash reference of options which will be passed -to the attribute metaclass's constructor. +An optional array reference of L objects. =back @@ -1315,7 +1230,7 @@ All instances of an anonymous class keep a special reference to the metaclass object, which prevents the metaclass from going out of scope while any instances exist. -This only works if the instance if based on a hash reference, however. +This only works if the instance is based on a hash reference, however. =item B<< Class::MOP::Class->initialize($package_name, %options) >> @@ -1382,11 +1297,14 @@ does nothing; it is merely a hook. This method is used to create a new object of the metaclass's class. Any parameters you provide are used to initialize the -instance's attributes. +instance's attributes. A special C<__INSTANCE__> key can be passed to +provide an already generated instance, rather than having Class::MOP +generate it for you. This is mostly useful for using Class::MOP with +foreign classes which generate instances using their own constructors. =item B<< $metaclass->instance_metaclass >> -Returns the class name of the instance metaclass, see +Returns the class name of the instance metaclass. See L for more information on the instance metaclass. @@ -1447,54 +1365,24 @@ duplicates removed. =item B<< $metaclass->subclasses >> -This returns a list of subclasses for this class. - -=back - -=head2 Method introspection and creation +This returns a list of all subclasses for this class, even indirect +subclasses. -These methods allow you to introspect a class's methods, as well as -add, remove, or change methods. +=item B<< $metaclass->direct_subclasses >> -Determining what is truly a method in a Perl 5 class requires some -heuristics (aka guessing). +This returns a list of immediate subclasses for this class, which does not +include indirect subclasses. -Methods defined outside the package with a fully qualified name (C) will be included. Similarly, methods named -with a fully qualified name using L are also included. +=back -However, we attempt to ignore imported functions. +=head2 Method introspection -Ultimately, we are using heuristics to determine what truly is a -method in a class, and these heuristics may get the wrong answer in -some edge cases. However, for most "normal" cases the heuristics work -correctly. +See L for +methods that operate only on the current class. Class::MOP::Class adds +introspection capabilities that take inheritance into account. =over 4 -=item B<< $metaclass->get_method($method_name) >> - -This will return a L for the specified -C<$method_name>. If the class does not have the specified method, it -returns C - -=item B<< $metaclass->has_method($method_name) >> - -Returns a boolean indicating whether or not the class defines the -named method. It does not include methods inherited from parent -classes. - -=item B<< $metaclass->get_method_map >> - -Returns a hash reference representing the methods defined in this -class. The keys are method names and the values are -L objects. - -=item B<< $metaclass->get_method_list >> - -This will return a list of method I for all methods defined in -this class. - =item B<< $metaclass->get_all_methods >> This will traverse the inheritance hierarchy and return a list of all @@ -1532,38 +1420,6 @@ This method returns the first method in any superclass matching the given name. It is effectively the method that C would dispatch to. -=item B<< $metaclass->add_method($method_name, $method) >> - -This method takes a method name and a subroutine reference, and adds -the method to the class. - -The subroutine reference can be a L, and you are -strongly encouraged to pass a meta method object instead of a code -reference. If you do so, that object gets stored as part of the -class's method map directly. If not, the meta information will have to -be recreated later, and may be incorrect. - -If you provide a method object, this method will clone that object if -the object's package name does not match the class name. This lets us -track the original source of any methods added from other classes -(notably Moose roles). - -=item B<< $metaclass->remove_method($method_name) >> - -Remove the named method from the class. This method returns the -L object for the method. - -=item B<< $metaclass->method_metaclass >> - -Returns the class name of the method metaclass, see -L for more information on the method metaclass. - -=item B<< $metaclass->wrapped_method_metaclass >> - -Returns the class name of the wrapped method metaclass, see -L for more information on the wrapped -method metaclass. - =back =head2 Attribute introspection and creation @@ -1579,7 +1435,10 @@ attributes which are defined in terms of "regular" Perl 5 methods. This will return a L for the specified C<$attribute_name>. If the class does not have the specified -attribute, it returns C +attribute, it returns C. + +NOTE that get_attribute does not search superclasses, for that you +need to use C. =item B<< $metaclass->has_attribute($attribute_name) >> @@ -1587,12 +1446,6 @@ Returns a boolean indicating whether or not the class defines the named attribute. It does not include attributes inherited from parent classes. -=item B<< $metaclass->get_attribute_map >> - -Returns a hash reference representing the attributes defined in this -class. The keys are attribute names and the values are -L objects. - =item B<< $metaclass->get_attribute_list >> This will return a list of attributes I for all attributes @@ -1607,7 +1460,7 @@ the L objects for this class and its parents. This will return a L for the specified C<$attribute_name>. If the class does not have the specified -attribute, it returns C +attribute, it returns C. Unlike C, this attribute I look for the named attribute in superclasses. @@ -1615,7 +1468,7 @@ attribute in superclasses. =item B<< $metaclass->add_attribute(...) >> This method accepts either an existing L -object, or parameters suitable for passing to that class's C +object or parameters suitable for passing to that class's C method. The attribute provided will be added to the class. @@ -1640,7 +1493,7 @@ object instances created for this class, not existing instances. =item B<< $metaclass->attribute_metaclass >> Returns the class name of the attribute metaclass for this class. By -default, this is L. for more information on +default, this is L. =back @@ -1654,6 +1507,11 @@ Making a class immutable lets us optimize the class by inlining some methods, and also allows us to optimize some methods on the metaclass object itself. +After immutabilization, the metaclass object will cache most informational +methods that returns information about methods or attributes. Methods which +would alter the class, such as C and C, will +throw an error on an immutable metaclass object. + The immutabilization system in L takes much greater advantage of the inlining features than Class::MOP itself does. @@ -1661,23 +1519,72 @@ of the inlining features than Class::MOP itself does. =item B<< $metaclass->make_immutable(%options) >> -This method will create an immutable transformer and uses it to make +This method will create an immutable transformer and use it to make the class and its metaclass object immutable. -Details of how immutabilization works are in L -documentation. +This method accepts the following options: -=item B<< $metaclass->make_mutable >> +=over 8 -Calling this method reverse the immutabilization transformation. +=item * inline_accessors + +=item * inline_constructor + +=item * inline_destructor + +These are all booleans indicating whether the specified method(s) +should be inlined. -=item B<< $metaclass->immutable_transformer >> +By default, accessors and the constructor are inlined, but not the +destructor. -If the class has been made immutable previously, this returns the -L object that was created to do the -transformation. +=item * immutable_trait -If the class was never made immutable, this method will die. +The name of a class which will be used as a parent class for the +metaclass object being made immutable. This "trait" implements the +post-immutability functionality of the metaclass (but not the +transformation itself). + +This defaults to L. + +=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 * replace_constructor + +This is a boolean indicating whether an existing constructor should be +replaced when inlining a constructor. This defaults to false. + +=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 * replace_destructor + +This is a boolean indicating whether an existing destructor should be +replaced when inlining a destructor. This defaults to false. + +=back + +=item B<< $metaclass->immutable_options >> + +Returns a hash of the options used when making the class immutable, including +both defaults and anything supplied by the user in the call to C<< +$metaclass->make_immutable >>. This is useful if you need to temporarily make +a class mutable and then restore immutability as it was before. + +=item B<< $metaclass->make_mutable >> + +Calling this method reverse the immutabilization transformation. =back @@ -1685,7 +1592,7 @@ If the class was never made immutable, this method will die. Method modifiers are hooks which allow a method to be wrapped with I, I and I method modifiers. Every time a -method is called, it's modifiers are also called. +method is called, its modifiers are also called. A class can modify its own methods, as well as methods defined in parent classes. @@ -1729,9 +1636,9 @@ order. So the call tree might looks something like this: Of course there is a performance cost associated with method modifiers, but we have made every effort to make that cost directly -proportional to the number of modifier features you utilize. +proportional to the number of modifier features you use. -The wrapping method does it's best to B do as much work as it +The wrapping method does its best to B do as much work as it absolutely needs to. In order to do this we have moved some of the performance costs to set-up time, where they are easier to amortize.