=head1 NAME
-namespace::clean - Keep imports out of your namespace
+namespace::clean - Keep imports and functions out of your namespace
=cut
use warnings;
use strict;
-use vars qw( $VERSION $STORAGE_VAR );
-use Symbol qw( qualify_to_ref );
-use Filter::EOF;
+use vars qw( $VERSION $STORAGE_VAR $SCOPE_HOOK_KEY $SCOPE_EXPLICIT );
+use B::Hooks::EndOfScope;
+use Stash::Manip;
+use Sub::Identify qw(sub_fullname);
+use Sub::Name qw(subname);
=head1 VERSION
-0.02
+0.13
=cut
-$VERSION = 0.02;
-$STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
+$VERSION = '0.14';
+$STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
=head1 SYNOPSIS
use warnings;
use strict;
- use Carp qw(croak); # will be removed
+ use Carp qw(croak); # 'croak' will be removed
- sub bar { 23 } # will be removed
+ sub bar { 23 } # 'bar' will be removed
+ # remove all previously defined functions
use namespace::clean;
- sub baz { bar() } # still defined, 'bar' still bound
+ sub baz { bar() } # 'baz' still defined, 'bar' still bound
+ # begin to collection function names from here again
no namespace::clean;
- sub quux { baz() } # will be removed again
+ sub quux { baz() } # 'quux' will be removed
+ # remove all functions defined after the 'no' unimport
use namespace::clean;
- ### Will print:
- # No
- # No
- # Yes
- # No
+ # Will print: 'No', 'No', 'Yes' and 'No'
print +(__PACKAGE__->can('croak') ? 'Yes' : 'No'), "\n";
print +(__PACKAGE__->can('bar') ? 'Yes' : 'No'), "\n";
print +(__PACKAGE__->can('baz') ? 'Yes' : 'No'), "\n";
=head1 DESCRIPTION
+=head2 Keeping packages clean
+
When you define a function, or import one, into a Perl package, it will
naturally also be available as a method. This does not per se cause
problems, but it can complicate subclassing and, for example, plugin
-classes that are included by loading them as base classes.
+classes that are included via multiple inheritance by loading them as
+base classes.
The C<namespace::clean> pragma will remove all previously declared or
imported symbols at the end of the current package's compile cycle.
-This means that functions are already bound by their name, and calls to
-them still work. But they will not be available as methods on your class
-or instances.
+Functions called in the package itself will still be bound by their
+name, but they won't show up as methods on your class or instances.
+
+By unimporting via C<no> you can tell C<namespace::clean> to start
+collecting functions for the next C<use namespace::clean;> specification.
+
+You can use the C<-except> flag to tell C<namespace::clean> that you
+don't want it to remove a certain function or method. A common use would
+be a module exporting an C<import> method along with some functions:
+
+ use ModuleExportingImport;
+ use namespace::clean -except => [qw( import )];
+
+If you just want to C<-except> a single sub, you can pass it directly.
+For more than one value you have to use an array reference.
+
+=head2 Explicitely removing functions when your scope is compiled
+
+It is also possible to explicitely tell C<namespace::clean> what packages
+to remove when the surrounding scope has finished compiling. Here is an
+example:
+
+ package Foo;
+ use strict;
+
+ # blessed NOT available
+
+ sub my_class {
+ use Scalar::Util qw( blessed );
+ use namespace::clean qw( blessed );
+
+ # blessed available
+ return blessed shift;
+ }
+
+ # blessed NOT available
+
+=head2 Moose
+
+When using C<namespace::clean> together with L<Moose> you want to keep
+the installed C<meta> method. So your classes should look like:
+
+ package Foo;
+ use Moose;
+ use namespace::clean -except => 'meta';
+ ...
+
+Same goes for L<Moose::Role>.
+
+=head2 Cleaning other packages
+
+You can tell C<namespace::clean> that you want to clean up another package
+instead of the one importing. To do this you have to pass in the C<-cleanee>
+option like this:
+
+ package My::MooseX::namespace::clean;
+ use strict;
+
+ use namespace::clean (); # no cleanup, just load
+
+ sub import {
+ namespace::clean->import(
+ -cleanee => scalar(caller),
+ -except => 'meta',
+ );
+ }
+
+If you don't care about C<namespace::clean>s discover-and-C<-except> logic, and
+just want to remove subroutines, try L</clean_subroutines>.
=head1 METHODS
You shouldn't need to call any of these. Just C<use> the package at the
appropriate place.
-=head2 import
+=cut
-Makes a snapshot of the current defined functions and registers a
-L<Filter::EOF> cleanup routine to remove those symbols from the package
-at the end of the compile-time.
+=head2 clean_subroutines
+
+This exposes the actual subroutine-removal logic.
+
+ namespace::clean->clean_subroutines($cleanee, qw( subA subB ));
+
+will remove C<subA> and C<subB> from C<$cleanee>. Note that this will remove the
+subroutines B<immediately> and not wait for scope end. If you want to have this
+effect at a specific time (e.g. C<namespace::clean> acts on scope compile end)
+it is your responsibility to make sure it runs at that time.
=cut
-sub import {
- my ($pragma) = @_;
+my $RemoveSubs = sub {
+
+ my $cleanee = shift;
+ my $store = shift;
+ my $cleanee_stash = Stash::Manip->new($cleanee);
+ my $deleted_stash = Stash::Manip->new("namespace::clean::deleted::$cleanee");
+ SYMBOL:
+ for my $f (@_) {
+ my $variable = "&$f";
+ # ignore already removed symbols
+ next SYMBOL if $store->{exclude}{ $f };
+
+ next SYMBOL unless $cleanee_stash->has_package_symbol($variable);
+
+ if (ref(\$cleanee_stash->namespace->{$f}) eq 'GLOB') {
+ # convince the Perl debugger to work
+ # it assumes that sub_fullname($sub) can always be used to find the CV again
+ # since we are deleting the glob where the subroutine was originally
+ # defined, that assumption no longer holds, so we need to move it
+ # elsewhere and point the CV's name to the new glob.
+ my $sub = $cleanee_stash->get_package_symbol($variable);
+ if ( sub_fullname($sub) eq ($cleanee_stash->name . "::$f") ) {
+ my $new_fq = $deleted_stash->name . "::$f";
+ subname($new_fq, $sub);
+ $deleted_stash->add_package_symbol($variable, $sub);
+ }
+ }
- my $cleanee = caller;
- my $functions = $pragma->get_functions($cleanee);
- my $store = $pragma->get_class_store($cleanee);
-
- for my $f (keys %$functions) {
- next unless $functions->{ $f }
- and *{ $functions->{ $f } }{CODE};
- $store->{remove}{ $f } = 1;
+ $cleanee_stash->remove_package_symbol($variable);
}
+};
- unless ($store->{handler_is_installed}) {
- Filter::EOF->on_eof_call(sub {
- for my $f (keys %{ $store->{remove} }) {
- next if $store->{exclude}{ $f };
- no strict 'refs';
- delete ${ "${cleanee}::" }{ $f };
- }
- });
- $store->{handler_is_installed} = 1;
+sub clean_subroutines {
+ my ($nc, $cleanee, @subs) = @_;
+ $RemoveSubs->($cleanee, {}, @subs);
+}
+
+=head2 import
+
+Makes a snapshot of the current defined functions and installs a
+L<B::Hooks::EndOfScope> hook in the current scope to invoke the cleanups.
+
+=cut
+
+sub import {
+ my ($pragma, @args) = @_;
+
+ my (%args, $is_explicit);
+
+ ARG:
+ while (@args) {
+
+ if ($args[0] =~ /^\-/) {
+ my $key = shift @args;
+ my $value = shift @args;
+ $args{ $key } = $value;
+ }
+ else {
+ $is_explicit++;
+ last ARG;
+ }
}
- return 1;
+ my $cleanee = exists $args{ -cleanee } ? $args{ -cleanee } : scalar caller;
+ if ($is_explicit) {
+ on_scope_end {
+ $RemoveSubs->($cleanee, {}, @args);
+ };
+ }
+ else {
+
+ # calling class, all current functions and our storage
+ my $functions = $pragma->get_functions($cleanee);
+ my $store = $pragma->get_class_store($cleanee);
+ my $stash = Stash::Manip->new($cleanee);
+
+ # except parameter can be array ref or single value
+ my %except = map {( $_ => 1 )} (
+ $args{ -except }
+ ? ( ref $args{ -except } eq 'ARRAY' ? @{ $args{ -except } } : $args{ -except } )
+ : ()
+ );
+
+ # register symbols for removal, if they have a CODE entry
+ for my $f (keys %$functions) {
+ next if $except{ $f };
+ next unless $stash->has_package_symbol("&$f");
+ $store->{remove}{ $f } = 1;
+ }
+
+ # register EOF handler on first call to import
+ unless ($store->{handler_is_installed}) {
+ on_scope_end {
+ $RemoveSubs->($cleanee, $store, keys %{ $store->{remove} });
+ };
+ $store->{handler_is_installed} = 1;
+ }
+
+ return 1;
+ }
}
=head2 unimport
=cut
sub unimport {
- my ($pragma) = @_;
+ my ($pragma, %args) = @_;
- my $cleanee = caller;
+ # the calling class, the current functions and our storage
+ my $cleanee = exists $args{ -cleanee } ? $args{ -cleanee } : scalar caller;
my $functions = $pragma->get_functions($cleanee);
my $store = $pragma->get_class_store($cleanee);
+ # register all unknown previous functions as excluded
for my $f (keys %$functions) {
next if $store->{remove}{ $f }
or $store->{exclude}{ $f };
=head2 get_class_store
-This returns a reference to a hash in your package containing information
-about function names included and excluded from removal.
+This returns a reference to a hash in a passed package containing
+information about function names included and excluded from removal.
=cut
sub get_class_store {
my ($pragma, $class) = @_;
- no strict 'refs';
- return \%{ "${class}::${STORAGE_VAR}" };
+ my $stash = Stash::Manip->new($class);
+ return $stash->get_package_symbol("%$STORAGE_VAR");
}
=head2 get_functions
sub get_functions {
my ($pragma, $class) = @_;
+ my $stash = Stash::Manip->new($class);
return {
- map { @$_ }
- grep { *{ $_->[1] }{CODE} }
- map { [$_, qualify_to_ref( $_, $class )] }
- grep { $_ !~ /::$/ }
- do { no strict 'refs'; keys %{ "${class}::" } }
+ map { $_ => $stash->get_package_symbol("&$_") }
+ $stash->list_all_package_symbols('CODE')
};
}
+=head1 BUGS
+
+C<namespace::clean> will clobber any formats that have the same name as
+a deleted sub. This is due to a bug in perl that makes it impossible to
+re-assign the FORMAT ref into a new glob.
+
+=head1 IMPLEMENTATION DETAILS
+
+This module works through the effect that a
+
+ delete $SomePackage::{foo};
+
+will remove the C<foo> symbol from C<$SomePackage> for run time lookups
+(e.g., method calls) but will leave the entry alive to be called by
+already resolved names in the package itself. C<namespace::clean> will
+restore and therefor in effect keep all glob slots that aren't C<CODE>.
+
+A test file has been added to the perl core to ensure that this behaviour
+will be stable in future releases.
+
+Just for completeness sake, if you want to remove the symbol completely,
+use C<undef> instead.
+
=head1 SEE ALSO
-L<Filter::EOF>
+L<B::Hooks::EndOfScope>
=head1 AUTHOR AND COPYRIGHT
=cut
-1;
+no warnings;
+'Danger! Laws of Thermodynamics may not apply.'
projects / p5sagit/namespace-clean.git / blobdiff