package namespace::clean;
+# ABSTRACT: Keep imports and functions out of your namespace
-=head1 NAME
+use warnings;
+use strict;
-namespace::clean - Keep imports and functions out of your namespace
+use vars qw( $STORAGE_VAR );
+use Package::Stash;
-=cut
+our $VERSION = '0.21';
-use warnings;
-use strict;
+$STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
-use vars qw( $VERSION $STORAGE_VAR $SCOPE_HOOK_KEY $SCOPE_EXPLICIT );
-use Symbol qw( qualify_to_ref gensym );
-use B::Hooks::EndOfScope;
-use Sub::Identify qw(sub_fullname);
-use Sub::Name qw(subname);
+BEGIN {
-=head1 VERSION
+ use warnings;
+ use strict;
-0.12
+ # when changing also change in Makefile.PL
+ my $b_h_eos_req = '0.07';
-=cut
+ if (! $ENV{NAMESPACE_CLEAN_USE_PP} and eval {
+ require B::Hooks::EndOfScope;
+ B::Hooks::EndOfScope->VERSION($b_h_eos_req);
+ 1
+ } ) {
+ B::Hooks::EndOfScope->import('on_scope_end');
+ }
+ else {
+ eval <<'PP' or die $@;
+
+ use Tie::Hash ();
+
+ {
+ package namespace::clean::_TieHintHash;
+
+ use warnings;
+ use strict;
+
+ use base 'Tie::ExtraHash';
+ }
+
+ {
+ package namespace::clean::_ScopeGuard;
+
+ use warnings;
+ use strict;
+
+ sub arm { bless [ $_[1] ] }
+
+ sub DESTROY { $_[0]->[0]->() }
+ }
+
+
+ sub on_scope_end (&) {
+ $^H |= 0x020000;
+
+ if( my $stack = tied( %^H ) ) {
+ if ( (my $c = ref $stack) ne 'namespace::clean::_TieHintHash') {
+ die <<EOE;
+========================================================================
+ !!! F A T A L E R R O R !!!
+
+ foreign tie() of %^H detected
+========================================================================
+
+namespace::clean is currently operating in pure-perl fallback mode, because
+your system is lacking the necessary dependency B::Hooks::EndOfScope $b_h_eos_req.
+In this mode namespace::clean expects to be able to tie() the hinthash %^H,
+however it is apparently already tied by means unknown to the tie-class
+$c
+
+Since this is a no-win situation execution will abort here and now. Please
+try to find out which other module is relying on hinthash tie() ability,
+and file a bug for both the perpetrator and namespace::clean, so that the
+authors can figure out an acceptable way of moving forward.
+
+EOE
+ }
+ push @$stack, namespace::clean::_ScopeGuard->arm(shift);
+ }
+ else {
+ my %old_contents = %^H;
+ %^H = ();
+ tie( %^H, 'namespace::clean::_TieHintHash', namespace::clean::_ScopeGuard->arm(shift) );
+ $^H{$_} = $old_contents{$_} for keys %old_contents;
+ }
+ }
+
+ 1;
+
+PP
+
+ }
+}
-$VERSION = '0.12';
-$STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
+=head1 NAME
+
+namespace::clean - Keep imports and functions out of your namespace
=head1 SYNOPSIS
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 via multiple inheritance by loading them as
+classes that are included via multiple inheritance by loading them as
base classes.
The C<namespace::clean> pragma will remove all previously declared or
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
+=head2 Explicitly removing functions when your scope is compiled
-It is also possible to explicitely tell C<namespace::clean> what packages
+It is also possible to explicitly tell C<namespace::clean> what packages
to remove when the surrounding scope has finished compiling. Here is an
example:
=head1 METHODS
-You shouldn't need to call any of these. Just C<use> the package at the
-appropriate place.
-
-=cut
-
=head2 clean_subroutines
This exposes the actual subroutine-removal logic.
=cut
-my $RemoveSubs = sub {
+# Constant to optimise away the unused code branches
+use constant RENAME_SUB => $] > 5.008_008_9 && $] < 5.013_006_1;
+{ no strict; delete ${__PACKAGE__."::"}{RENAME_SUB} }
+
+# In perl 5.8.9-5.12, it assumes that sub_fullname($sub) can
+# always be used to find the CV again.
+# In perl 5.8.8 and 5.14, it assumes that the name of the glob
+# passed to entersub can be used to find the CV.
+# since we are deleting the glob where the subroutine was originally
+# defined, those assumptions no longer hold.
+#
+# So in 5.8.9-5.12 we need to move it elsewhere and point the
+# CV's name to the new glob.
+#
+# In 5.8.8 and 5.14 we move it elsewhere and rename the
+# original glob by assigning the new glob back to it.
+my $sub_utils_loaded;
+my $DebuggerFixup = sub {
+ my ($f, $sub, $cleanee_stash, $deleted_stash) = @_;
+
+ if (RENAME_SUB) {
+ if (! defined $sub_utils_loaded ) {
+ $sub_utils_loaded = do {
+
+ # when changing version also change in Makefile.PL
+ my $sn_ver = 0.04;
+ eval { require Sub::Name; Sub::Name->VERSION($sn_ver) }
+ or die "Sub::Name $sn_ver required when running under -d or equivalent: $@";
+
+ # when changing version also change in Makefile.PL
+ my $si_ver = 0.04;
+ eval { require Sub::Identify; Sub::Identify->VERSION($si_ver) }
+ or die "Sub::Identify $si_ver required when running under -d or equivalent: $@";
+
+ 1;
+ } ? 1 : 0;
+ }
+ if ( Sub::Identify::sub_fullname($sub) eq ($cleanee_stash->name . "::$f") ) {
+ my $new_fq = $deleted_stash->name . "::$f";
+ Sub::Name::subname($new_fq, $sub);
+ $deleted_stash->add_symbol("&$f", $sub);
+ }
+ }
+ else {
+ $deleted_stash->add_symbol("&$f", $sub);
+ }
+};
+
+my $RemoveSubs = sub {
my $cleanee = shift;
my $store = shift;
+ my $cleanee_stash = Package::Stash->new($cleanee);
+ my $deleted_stash;
+
SYMBOL:
for my $f (@_) {
- my $fq = "${cleanee}::$f";
# ignore already removed symbols
next SYMBOL if $store->{exclude}{ $f };
- no strict 'refs';
-
- next SYMBOL unless exists ${ "${cleanee}::" }{ $f };
-
- if (ref(\${ "${cleanee}::" }{ $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 = \&$fq;
- if ( sub_fullname($sub) eq $fq ) {
- my $new_fq = "namespace::clean::deleted::$fq";
- subname($new_fq, $sub);
- *{$new_fq} = $sub;
- }
-
- local *__tmp;
-
- # keep original value to restore non-code slots
- { no warnings 'uninitialized'; # fix possible unimports
- *__tmp = *{ ${ "${cleanee}::" }{ $f } };
- delete ${ "${cleanee}::" }{ $f };
- }
-
- SLOT:
- # restore non-code slots to symbol.
- # omit the FORMAT slot, since perl erroneously puts it into the
- # SCALAR slot of the new glob.
- for my $t (qw( SCALAR ARRAY HASH IO )) {
- next SLOT unless defined *__tmp{ $t };
- *{ "${cleanee}::$f" } = *__tmp{ $t };
- }
+
+ my $sub = $cleanee_stash->get_symbol("&$f")
+ or next SYMBOL;
+
+ my $need_debugger_fixup =
+ $^P
+ &&
+ ref(my $globref = \$cleanee_stash->namespace->{$f}) eq 'GLOB'
+ ;
+
+ if ($need_debugger_fixup) {
+ # convince the Perl debugger to work
+ # see the comment on top of $DebuggerFixup
+ $DebuggerFixup->(
+ $f,
+ $sub,
+ $cleanee_stash,
+ $deleted_stash ||= Package::Stash->new("namespace::clean::deleted::$cleanee"),
+ );
}
- else {
- # A non-glob in the stash is assumed to stand for some kind
- # of function. So far they all do, but the core might change
- # this some day. Watch perl5-porters.
- delete ${ "${cleanee}::" }{ $f };
+
+ my @symbols = map {
+ my $name = $_ . $f;
+ my $def = $cleanee_stash->get_symbol($name);
+ defined($def) ? [$name, $def] : ()
+ } '$', '@', '%', '';
+
+ $cleanee_stash->remove_glob($f);
+
+ # if this perl needs no renaming trick we need to
+ # rename the original glob after the fact
+ # (see commend of $DebuggerFixup
+ if (!RENAME_SUB && $need_debugger_fixup) {
+ *$globref = $deleted_stash->namespace->{$f};
}
+
+ $cleanee_stash->add_symbol(@$_) for @symbols;
}
};
# calling class, all current functions and our storage
my $functions = $pragma->get_functions($cleanee);
my $store = $pragma->get_class_store($cleanee);
+ my $stash = Package::Stash->new($cleanee);
# except parameter can be array ref or single value
my %except = map {( $_ => 1 )} (
# register symbols for removal, if they have a CODE entry
for my $f (keys %$functions) {
next if $except{ $f };
- next unless $functions->{ $f }
- and *{ $functions->{ $f } }{CODE};
+ next unless $stash->has_symbol("&$f");
$store->{remove}{ $f } = 1;
}
=head2 get_class_store
-This returns a reference to a hash in a passed package containing
+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 = Package::Stash->new($class);
+ my $var = "%$STORAGE_VAR";
+ $stash->add_symbol($var, {})
+ unless $stash->has_symbol($var);
+ return $stash->get_symbol($var);
}
=head2 get_functions
sub get_functions {
my ($pragma, $class) = @_;
+ my $stash = Package::Stash->new($class);
return {
- map { @$_ } # key => value
- grep { *{ $_->[1] }{CODE} } # only functions
- map { [$_, qualify_to_ref( $_, $class )] } # get globref
- grep { $_ !~ /::$/ } # no packages
- do { no strict 'refs'; keys %{ "${class}::" } } # symbol entries
+ map { $_ => $stash->get_symbol("&$_") }
+ $stash->list_all_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
+This module works through the effect that a
delete $SomePackage::{foo};
Just for completeness sake, if you want to remove the symbol completely,
use C<undef> instead.
+=head1 CAVEATS
+
+This module is fully functional in a pure-perl environment, where
+L<B::Hooks::EndOfScope> (with the XS dependency L<Variable::Magic>), may
+not be available. However in this case this module falls back to a
+L<tie()|perlfunc/tie> of L<%^H|perlvar/%^H> which may or may not interfere
+with some crack you may be doing independently of namespace::clean.
+
+If you want to ensure that your codebase is protected from this unlikely
+clash, you need to explicitly depend on L<B::Hooks::EndOfScope>.
+
=head1 SEE ALSO
L<B::Hooks::EndOfScope>
-=head1 AUTHOR AND COPYRIGHT
+=head1 THANKS
+
+Many thanks to Matt S Trout for the inspiration on the whole idea.
+
+=head1 AUTHORS
+
+=over
+
+=item *
+
+Robert 'phaylon' Sedlacek <rs@474.at>
+
+=item *
+
+Florian Ragwitz <rafl@debian.org>
+
+=item *
+
+Jesse Luehrs <doy@tozt.net>
+
+=item *
+
+Peter Rabbitson <ribasushi@cpan.org>
+
+=back
-Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
-Matt S Trout for the inspiration on the whole idea.
+=head1 COPYRIGHT AND LICENSE
-=head1 LICENSE
+This software is copyright (c) 2011 by Robert 'phaylon' Sedlacek.
-This program is free software; you can redistribute it and/or modify
-it under the same terms as perl itself.
+This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
=cut