Add caveats and tests for Symbol::delete_package().

p4raw-id: //depot/perl@20922

2 files changed, 22 insertions, 3 deletions

diff --git a/lib/Symbol.pm b/lib/Symbol.pm
index 98fb6763fe..5c0843e7d7 100644
--- a/lib/Symbol.pm
+++ b/lib/Symbol.pm
@@ -34,7 +34,6 @@ Symbol - manipulate Perl symbols and their names
     delete_package('Foo::Bar');
     print "deleted\n" unless exists $Foo::{'Bar::'};
 
-
 =head1 DESCRIPTION
 
 C<Symbol::gensym> creates an anonymous glob and returns a reference
@@ -68,6 +67,16 @@ C<Symbol::delete_package> wipes out a whole package namespace.  Note
 this routine is not exported by default--you may want to import it
 explicitly.
 
+=head1 BUGS
+
+C<Symbol::delete_package> is a bit too powerful. It undefines every symbol
+that lives in the specified package and in its sub-packages. Since perl,
+for performance reasons, does not perform a symbol table lookup each time
+a function is called or a global variable is accessed, some code that has
+already been loaded and that makes use of symbols in package C<Foo> may
+stop working after you delete C<Foo>, even if you reload the C<Foo> module
+afterwards.
+
 =cut
 
 BEGIN { require 5.005; }
@@ -77,7 +86,7 @@ require Exporter;
 @EXPORT = qw(gensym ungensym qualify qualify_to_ref);
 @EXPORT_OK = qw(delete_package geniosym);
 
-$VERSION = 1.04;
+$VERSION = '1.05';
 
 my $genpkg = "Symbol::";
 my $genseq = 0;
diff --git a/lib/Symbol.t b/lib/Symbol.t
index 5763e5420e..c8a7c0773f 100755
--- a/lib/Symbol.t
+++ b/lib/Symbol.t
@@ -5,7 +5,7 @@ BEGIN {
     @INC = '../lib';
 }
 
-use Test::More tests => 14;
+use Test::More tests => 19;
 
 BEGIN { $_ = 'foo'; }  # because Symbol used to clobber $_
 
@@ -65,3 +65,13 @@ use Symbol qw(qualify);  # must import into this package too
     'qualify() with an identifier starting with a _' );
 ::ok( qualify("^FOO") eq "main::\cFOO",
     'qualify() with an identifier starting with a ^' );
+
+# tests for delete_package
+package main;
+$Transient::variable = 42;
+ok( exists $::{'Transient::'}, 'transient stash exists' );
+ok( defined $Transient::{variable}, 'transient variable in stash' );
+Symbol::delete_package('Transient');
+ok( !exists $Transient::{variable}, 'transient variable no longer in stash' );
+is( scalar(keys %Transient::), 0, 'transient stash is empty' );
+ok( !exists $::{'Transient::'}, 'no transient stash' );