support for C<exists &func> (from Spider Boardman)

p4raw-id: //depot/perl@4827

3 files changed, 37 insertions, 1 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 15b60ba0db..cd596e2044 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -425,6 +425,12 @@ This is rather similar to how the arrow may be omitted from
 C<$foo[10]->{'foo'}>.  Note however, that the arrow is still
 required for C<foo(10)->('bar')>.
 
+=head2 exists() is supported on subroutine names
+
+The exists() builtin now works on subroutine names.  A subroutine
+is considered to exist if it has been declared (even if implicitly).
+See L<perlfunc/exists> for examples.
+
 =head2 exists() and delete() are supported on array elements
 
 The exists() and delete() builtins now work on simple arrays as well.
@@ -1115,6 +1121,10 @@ File test operators.
 
 Verify operations that access pad objects (lexicals and temporaries).
 
+=item	op/exists_sub
+
+Verify C<exists &sub> operations.
+
 =back
 
 =head1 Modules and Pragmata
@@ -1593,6 +1603,11 @@ definition ahead of the call to get proper prototype checking.  Alternatively,
 if you are certain that you're calling the function correctly, you may put
 an ampersand before the name to avoid the warning.  See L<perlsub>.
 
+=item %s argument is not a subroutine name
+
+(F) The argument to exists() for C<exists &sub> must be a subroutine
+name, and not a subroutine call.  C<exists &sub()> will generate this error.
+
 =item %s package attribute may clash with future reserved word: %s
 
 (W) A lowercase attribute name was used that had a package-specific handler.
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index f82cd25409..752605d2f8 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -159,6 +159,11 @@ or a hash or array slice, such as:
     @foo[$bar, $baz, $xyzzy]
     @{$ref->[12]}{"susie", "queue"}
 
+=item %s argument is not a subroutine name
+
+(F) The argument to exists() for C<exists &sub> must be a subroutine
+name, and not a subroutine call.  C<exists &sub()> will generate this error.
+
 =item %s did not return a true value
 
 (F) A required (or used) file must return a true value to indicate that
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d730b43e47..dbefd85ee4 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1422,8 +1422,16 @@ element is not autovivified if it doesn't exist.
 A hash or array element can be true only if it's defined, and defined if
 it exists, but the reverse doesn't necessarily hold true.
 
+Given an expression that specifies the name of a subroutine,
+returns true if the specified subroutine has ever been declared, even
+if it is undefined.  Mentioning a subroutine name for exists or defined
+does not count as declaring it.
+
+    print "Exists\n" 	if exists &subroutine;
+    print "Defined\n" 	if defined &subroutine;
+
 Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash or array key lookup:
+operation is a hash or array key lookup or subroutine name:
 
     if (exists $ref->{A}->{B}->{$key}) 	{ }
     if (exists $hash{A}{B}{$key}) 	{ }
@@ -1431,6 +1439,8 @@ operation is a hash or array key lookup:
     if (exists $ref->{A}->{B}->[$ix]) 	{ }
     if (exists $hash{A}{B}[$ix]) 	{ }
 
+    if (exists &{$ref->{A}{B}{$key}})   { }
+
 Although the deepest nested array or hash will not spring into existence
 just because its existence was tested, any intervening ones will.
 Thus C<$ref-E<gt>{"A"}> and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring
@@ -1448,6 +1458,12 @@ release.
 See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
 used on a pseudo-hash.
 
+Use of a subroutine call, rather than a subroutine name, as an argument
+to exists() is an error.
+
+    exists &sub;	# OK
+    exists &sub();	# Error
+
 =item exit EXPR
 
 Evaluates EXPR and exits immediately with that value.    Example: