X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FClass%2FMOP%2FPackage.pm;h=d7c8fa9822a1bf6a55bb5869a32a96272f6c30d8;hb=936e37acb41fce39498ffe721741bedf01ac818e;hp=193934a914d076765fcb1fcab15457d97fad3c71;hpb=3be6bc1cd2696af20ddf45679ca3cb5930eab371;p=gitmo%2FClass-MOP.git diff --git a/lib/Class/MOP/Package.pm b/lib/Class/MOP/Package.pm index 193934a..d7c8fa9 100644 --- a/lib/Class/MOP/Package.pm +++ b/lib/Class/MOP/Package.pm @@ -4,10 +4,12 @@ package Class::MOP::Package; use strict; use warnings; -use Scalar::Util 'blessed'; +use Scalar::Util 'blessed', 'reftype'; use Carp 'confess'; +use Sub::Name 'subname'; -our $VERSION = '0.65'; +our $VERSION = '0.96'; +$VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; use base 'Class::MOP::Object'; @@ -26,15 +28,15 @@ sub initialize { # we hand-construct the class # until we can bootstrap it if ( my $meta = Class::MOP::get_metaclass_by_name($package_name) ) { - return $meta; + return $meta; } else { - my $meta = ( ref $class || $class )->_new({ - 'package' => $package_name, - }); + my $meta = ( ref $class || $class )->_new({ + 'package' => $package_name, + %options, + }); + Class::MOP::store_metaclass_by_name($package_name, $meta); - Class::MOP::store_metaclass_by_name($package_name, $meta); - - return $meta; + return $meta; } } @@ -44,30 +46,42 @@ sub reinitialize { unshift @args, "package" if @args % 2; my %options = @args; - my $package_name = $options{package}; + my $package_name = delete $options{package}; - (defined $package_name && $package_name && !blessed($package_name)) - || confess "You must pass a package name and it cannot be blessed"; + (defined $package_name && $package_name + && (!blessed $package_name || $package_name->isa('Class::MOP::Package'))) + || confess "You must pass a package name or an existing Class::MOP::Package instance"; + + $package_name = $package_name->name + if blessed $package_name; Class::MOP::remove_metaclass_by_name($package_name); - $class->initialize('package' => $package_name, @_); + $class->initialize($package_name, %options); # call with first arg form for compat } sub _new { my $class = shift; - my $options = @_ == 1 ? $_[0] : {@_}; - # NOTE: - # because of issues with the Perl API - # to the typeglob in some versions, we - # need to just always grab a new - # reference to the hash in the accessor. - # Ideally we could just store a ref and - # it would Just Work, but oh well :\ - $options->{namespace} ||= \undef; + return Class::MOP::Class->initialize($class)->new_object(@_) + if $class ne __PACKAGE__; - bless $options, $class; + my $params = @_ == 1 ? $_[0] : {@_}; + + return bless { + package => $params->{package}, + + # NOTE: + # because of issues with the Perl API + # to the typeglob in some versions, we + # need to just always grab a new + # reference to the hash in the accessor. + # Ideally we could just store a ref and + # it would Just Work, but oh well :\ + + namespace => \undef, + + } => $class; } # Attributes @@ -76,7 +90,6 @@ sub _new { # all these attribute readers will be bootstrapped # away in the Class::MOP bootstrap section -sub name { $_[0]->{'package'} } sub namespace { # NOTE: # because of issues with the Perl API @@ -89,6 +102,15 @@ sub namespace { \%{$_[0]->{'package'} . '::'} } +sub method_metaclass { $_[0]->{'method_metaclass'} } +sub wrapped_method_metaclass { $_[0]->{'wrapped_method_metaclass'} } + +# This doesn't always get initialized in a constructor because there is a +# weird object construction path for subclasses of Class::MOP::Class. At one +# point, this always got initialized by calling into the XS code first, but +# that is no longer guaranteed to happen. +sub _method_map { $_[0]->{'methods'} ||= {} } + # utility methods { @@ -126,13 +148,13 @@ sub add_package_symbol { my ($name, $sigil, $type) = ref $variable eq 'HASH' ? @{$variable}{qw[name sigil type]} - : $self->_deconstruct_variable_name($variable); + : $self->_deconstruct_variable_name($variable); my $pkg = $self->{'package'}; no strict 'refs'; - no warnings 'redefine', 'misc'; - *{$pkg . '::' . $name} = ref $initial_value ? $initial_value : \$initial_value; + no warnings 'redefine', 'misc', 'prototype'; + *{$pkg . '::' . $name} = ref $initial_value ? $initial_value : \$initial_value; } sub remove_package_glob { @@ -144,34 +166,31 @@ sub remove_package_glob { # ... these functions deal with stuff on the namespace level sub has_package_symbol { - my ($self, $variable) = @_; + my ( $self, $variable ) = @_; - my ($name, $sigil, $type) = ref $variable eq 'HASH' + my ( $name, $sigil, $type ) + = ref $variable eq 'HASH' ? @{$variable}{qw[name sigil type]} : $self->_deconstruct_variable_name($variable); - + my $namespace = $self->namespace; - - return 0 unless exists $namespace->{$name}; - - # FIXME: - # For some really stupid reason - # a typeglob will have a default - # value of \undef in the SCALAR - # slot, so we need to work around - # this. Which of course means that - # if you put \undef in your scalar - # then this is broken. - - if (ref($namespace->{$name}) eq 'SCALAR') { - return ($type eq 'CODE'); - } - elsif ($type eq 'SCALAR') { - my $val = *{$namespace->{$name}}{$type}; - return defined(${$val}); + + return 0 unless exists $namespace->{$name}; + + my $entry_ref = \$namespace->{$name}; + if ( reftype($entry_ref) eq 'GLOB' ) { + if ( $type eq 'SCALAR' ) { + return defined( ${ *{$entry_ref}{SCALAR} } ); + } + else { + return defined( *{$entry_ref}{$type} ); + } } else { - defined(*{$namespace->{$name}}{$type}); + + # a symbol table entry can be -1 (stub), string (stub with prototype), + # or reference (constant) + return $type eq 'CODE'; } } @@ -184,21 +203,24 @@ sub get_package_symbol { my $namespace = $self->namespace; + # FIXME $self->add_package_symbol($variable) unless exists $namespace->{$name}; - if (ref($namespace->{$name}) eq 'SCALAR') { - if ($type eq 'CODE') { + my $entry_ref = \$namespace->{$name}; + + if ( ref($entry_ref) eq 'GLOB' ) { + return *{$entry_ref}{$type}; + } + else { + if ( $type eq 'CODE' ) { no strict 'refs'; - return \&{$self->name.'::'.$name}; + return \&{ $self->name . '::' . $name }; } else { return undef; } } - else { - return *{$namespace->{$name}}{$type}; - } } sub remove_package_symbol { @@ -273,30 +295,134 @@ sub list_all_package_symbols { } } -sub get_all_package_symbols { - my ($self, $type_filter) = @_; - my $namespace = $self->namespace; +## Methods - return %$namespace unless defined $type_filter; +sub wrap_method_body { + my ( $self, %args ) = @_; - # for some reason this nasty impl is orders of magnitude aster than a clean version - if ( $type_filter eq 'CODE' ) { - my $pkg; - no strict 'refs'; - return map { - (ref($namespace->{$_}) - ? ( $_ => \&{$pkg ||= $self->name . "::$_"} ) - : ( *{$namespace->{$_}}{CODE} - ? ( $_ => *{$namespace->{$_}}{$type_filter} ) - : ())) - } keys %$namespace; - } else { - return map { - $_ => *{$namespace->{$_}}{$type_filter} - } grep { - !ref($namespace->{$_}) && *{$namespace->{$_}}{$type_filter} - } keys %$namespace; + ('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 && length $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'); + } + + $method->attach_to_class($self); + } + else { + # If a raw code reference is supplied, its method object is not created. + # The method object won't be created until required. + $body = $method; + } + + $self->_method_map->{$method_name} = $method; + + my ( $current_package, $current_name ) = Class::MOP::get_code_info($body); + + if ( !defined $current_name || $current_name =~ /^__ANON__/ ) { + my $full_method_name = ($self->name . '::' . $method_name); + subname($full_method_name => $body); + } + + $self->add_package_symbol( + { sigil => '&', type => 'CODE', name => $method_name }, + $body, + ); +} + +sub _code_is_mine { + my ( $self, $code ) = @_; + + my ( $code_package, $code_name ) = Class::MOP::get_code_info($code); + + return $code_package && $code_package eq $self->name + || ( $code_package eq 'constant' && $code_name eq '__ANON__' ); +} + +sub has_method { + my ($self, $method_name) = @_; + + (defined $method_name && length $method_name) + || confess "You must define a method name"; + + return defined($self->get_method($method_name)); +} + +sub get_method { + my ( $self, $method_name ) = @_; + + (defined $method_name && length $method_name) + || confess "You must define a method name"; + + my $method_map = $self->_method_map; + my $map_entry = $method_map->{$method_name}; + my $code = $self->get_package_symbol( + { + name => $method_name, + sigil => '&', + type => 'CODE', + } + ); + + # This seems to happen in some weird cases where methods modifiers are + # added via roles or some other such bizareness. Honestly, I don't totally + # understand this, but returning the entry works, and keeps various MX + # modules from blowing up. - DR + return $map_entry if blessed $map_entry && !$code; + + return $map_entry if blessed $map_entry && $map_entry->body == $code; + + unless ($map_entry) { + return unless $code && $self->_code_is_mine($code); } + + $code ||= $map_entry; + + return $method_map->{$method_name} = $self->wrap_method_body( + body => $code, + name => $method_name, + associated_metaclass => $self, + ); +} + +sub remove_method { + my ($self, $method_name) = @_; + (defined $method_name && length $method_name) + || confess "You must define a method name"; + + my $removed_method = delete $self->_full_method_map->{$method_name}; + + $self->remove_package_symbol( + { sigil => '&', type => 'CODE', name => $method_name } + ); + + $removed_method->detach_from_class if $removed_method && blessed $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; + return grep { $self->has_method($_) } keys %{ $self->namespace }; } 1; @@ -311,79 +437,158 @@ Class::MOP::Package - Package Meta Object =head1 DESCRIPTION -This is an abstraction of a Perl 5 package, it is a superclass of -L and provides all of the symbol table -introspection methods. +The Package Protocol provides an abstraction of a Perl 5 package. A +package is basically namespace, and this module provides methods for +looking at and changing that namespace's symbol table. =head1 METHODS =over 4 -=item B +=item B<< Class::MOP::Package->initialize($package_name) >> + +This method creates a new C instance which +represents specified package. If an existing metaclass object exists +for the package, that will be returned instead. -Returns a metaclass for this package. +=item B<< Class::MOP::Package->reinitialize($package) >> -=item B +This method forcibly removes any existing metaclass for the package +before calling C. In contrast to C, you may +also pass an existing C instance instead of just +a package name as C<$package>. -This will initialize a Class::MOP::Package instance which represents -the package of C<$package_name>. +Do not call this unless you know what you are doing. -=item B +=item B<< $metapackage->name >> -This removes the old metaclass, and creates a new one in it's place. -Do B use this unless you really know what you are doing, it could -very easily make a very large mess of your program. +This is returns the package's name, as passed to the constructor. -=item B +=item B<< $metapackage->namespace >> + +This returns a hash reference to the package's symbol table. The keys +are symbol names and the values are typeglob references. + +=item B<< $metapackage->add_package_symbol($variable_name, $initial_value) >> + +This method accepts a variable name and an optional initial value. The +C<$variable_name> must contain a leading sigil. + +This method creates the variable in the package's symbol table, and +sets it to the initial value if one was provided. + +=item B<< $metapackage->get_package_symbol($variable_name) >> + +Given a variable name, this method returns the variable as a reference +or undef if it does not exist. The C<$variable_name> must contain a +leading sigil. + +=item B<< $metapackage->has_package_symbol($variable_name) >> + +Returns true if there is a package variable defined for +C<$variable_name>. The C<$variable_name> must contain a leading sigil. + +=item B<< $metapackage->remove_package_symbol($variable_name) >> + +This will remove the package variable specified C<$variable_name>. The +C<$variable_name> must contain a leading sigil. + +=item B<< $metapackage->remove_package_glob($glob_name) >> + +Given the name of a glob, this will remove that glob from the +package's symbol table. Glob names do not include a sigil. Removing +the glob removes all variables and subroutines with the specified +name. + +=item B<< $metapackage->list_all_package_symbols($type_filter) >> + +This will list all the glob names associated with the current +package. These names do not have leading sigils. + +You can provide an optional type filter, which should be one of +'SCALAR', 'ARRAY', 'HASH', or 'CODE'. + +=item B<< $metapackage->get_all_package_symbols($type_filter) >> + +This works much like C, but it returns a +hash reference. The keys are glob names and the values are references +to the value for that name. + +=back + +=head2 Method introspection and creation + +These methods allow you to introspect a class's methods, as well as +add, remove, or change methods. + +Determining what is truly a method in a Perl 5 class requires some +heuristics (aka guessing). + +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. + +However, we attempt to ignore imported functions. + +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. + +=over 4 -This is a read-only attribute which returns the package name for the -given instance. +=item B<< $metapackage->get_method($method_name) >> -=item B +This will return a L for the specified +C<$method_name>. If the class does not have the specified method, it +returns C -This returns a HASH reference to the symbol table. The keys of the -HASH are the symbol names, and the values are typeglob references. +=item B<< $metapackage->has_method($method_name) >> -=item B +Returns a boolean indicating whether or not the class defines the +named method. It does not include methods inherited from parent +classes. -Given a C<$variable_name>, which must contain a leading sigil, this -method will create that variable within the package which houses the -class. It also takes an optional C<$initial_value>, which must be a -reference of the same type as the sigil of the C<$variable_name> -implies. +=item B<< $metapackage->get_method_list >> -=item B +This will return a list of method I for all methods defined in +this class. -This will return a reference to the package variable in -C<$variable_name>. +=item B<< $metapackage->add_method($method_name, $method) >> -=item B +This method takes a method name and a subroutine reference, and adds +the method to the class. -Returns true (C<1>) if there is a package variable defined for -C<$variable_name>, and false (C<0>) otherwise. +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. -=item B +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). -This will attempt to remove the package variable at C<$variable_name>. +=item B<< $metapackage->remove_method($method_name) >> -=item B +Remove the named method from the class. This method returns the +L object for the method. -This will attempt to remove the entire typeglob associated with -C<$glob_name> from the package. +=item B<< $metapackage->method_metaclass >> -=item B +Returns the class name of the method metaclass, see +L for more information on the method metaclass. -This will list all the glob names associated with the current package. -By inspecting the globs returned you can discern all the variables in -the package. +=item B<< $metapackage->wrapped_method_metaclass >> -By passing a C<$type_filter>, you can limit the list to only those -which match the filter (either SCALAR, ARRAY, HASH or CODE). +Returns the class name of the wrapped method metaclass, see +L for more information on the wrapped +method metaclass. -=item B +=item B<< Class::MOP::Package->meta >> -Works exactly like C but returns a HASH of -name => thing mapping instead of just an ARRAY of names. +This will return a L instance for this class. =back @@ -393,7 +598,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