X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fnamespace%2Fclean.pm;h=1e6d51af071b7d54d8109ef8aced866a1df00ea6;hb=656ec55b51c454ca3d8a06a728a4f6c06d6db5d5;hp=d11a7c46a348ac3d2448c382a7772321c2beb3ea;hpb=99d2e6b61c03d29efc6848f563f67308cb0da816;p=p5sagit%2Fnamespace-clean.git

diff --git a/lib/namespace/clean.pm b/lib/namespace/clean.pm
index d11a7c4..1e6d51a 100644
--- a/lib/namespace/clean.pm
+++ b/lib/namespace/clean.pm
@@ -1,26 +1,102 @@
 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 );
-use Symbol            qw( qualify_to_ref );
-use Filter::EOF;
+BEGIN {
 
-=head1 VERSION
+  use warnings;
+  use strict;
 
-0.06
+  # 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 $@;
 
-$VERSION     = 0.06;
-$STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
+  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
+
+  }
+}
+
+=head1 NAME
+
+namespace::clean - Keep imports and functions out of your namespace
 
 =head1 SYNOPSIS
 
@@ -55,10 +131,12 @@ $STORAGE_VAR = '__NAMESPACE_CLEAN_STORAGE';
 
 =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 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
@@ -79,72 +157,243 @@ be a module exporting an C<import> method along with some functions:
 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 Explicitly removing functions when your scope is compiled
+
+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:
+
+  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 clean_subroutines
 
-=cut
+This exposes the actual subroutine-removal logic.
 
-=head2 import
+  namespace::clean->clean_subroutines($cleanee, qw( subA subB ));
 
-Makes a snapshot of the current defined functions and registers a 
-L<Filter::EOF> cleanup routine to remove those symbols at the end 
-of the compile-time.
+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, %args) = @_;
+# 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;
+    }
 
-    # calling class, all current functions and our storage
-    my $cleanee   = caller;
-    my $functions = $pragma->get_functions($cleanee);
-    my $store     = $pragma->get_class_store($cleanee);
+    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 (@_) {
+
+        # ignore already removed symbols
+        next SYMBOL if $store->{exclude}{ $f };
+
+        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"),
+          );
+        }
+
+        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;
+    }
+};
 
-    # except parameter can be array ref or single value
-    my %except = map {( $_ => 1 )} (
-        $args{ -except }
-        ? ( ref $args{ -except } eq 'ARRAY' ? @{ $args{ -except } } : $args{ -except } )
-        : ()
-    );
+sub clean_subroutines {
+    my ($nc, $cleanee, @subs) = @_;
+    $RemoveSubs->($cleanee, {}, @subs);
+}
 
-    # 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};
-        $store->{remove}{ $f } = 1;
-    }
+=head2 import
 
-    # register EOF handler on first call to import
-    unless ($store->{handler_is_installed}) {
-        Filter::EOF->on_eof_call(sub {
-          SYMBOL:
-            for my $f (keys %{ $store->{remove} }) {
-
-                # ignore already removed symbols
-                next SYMBOL if $store->{exclude}{ $f };
-                no strict 'refs';
-
-                # keep original value to restore non-code slots
-                {   no warnings 'uninitialized';    # fix possible unimports
-                    local *__tmp = *{ ${ "${cleanee}::" }{ $f } };
-                    delete ${ "${cleanee}::" }{ $f };
-                }
-
-              SLOT:
-                # restore non-code slots to symbol
-                for my $t (qw( SCALAR ARRAY HASH IO FORMAT )) {
-                    next SLOT unless defined *__tmp{ $t };
-                    *{ "${cleanee}::$f" } = *__tmp{ $t };
-                }
-            }
-        });
-        $store->{handler_is_installed} = 1;
+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     = Package::Stash->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_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
@@ -158,10 +407,10 @@ It will start a new section of code that defines functions to clean up.
 =cut
 
 sub unimport {
-    my ($pragma) = @_;
+    my ($pragma, %args) = @_;
 
     # the calling class, the current functions and our storage
-    my $cleanee   = caller;
+    my $cleanee   = exists $args{ -cleanee } ? $args{ -cleanee } : scalar caller;
     my $functions = $pragma->get_functions($cleanee);
     my $store     = $pragma->get_class_store($cleanee);
 
@@ -177,15 +426,18 @@ sub unimport {
 
 =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
@@ -199,18 +451,16 @@ reference to the symbol as value.
 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 IMPLEMENTATION DETAILS
 
-This module works through the effect that a 
+This module works through the effect that a
 
   delete $SomePackage::{foo};
 
@@ -225,20 +475,54 @@ will be stable in future releases.
 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<Filter::EOF>
+L<B::Hooks::EndOfScope>
+
+=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>
 
-=head1 AUTHOR AND COPYRIGHT
+=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
 
-1;
+no warnings;
+'Danger! Laws of Thermodynamics may not apply.'