perlsub.pod patch

Following is a patch of perlsub.pod that clarifies the use of backslashed
prototype characters (\$ requires a SCALAR VARIABLE, not an expression
returing a scalar variable (example in POD)), and warns not to use \&.  It
also adds that a prototype of & can accept a subroutine reference, and not
just an anonymous subroutine.

-- 
MIDN 4/C PINYAN, NROTCURPI, US Naval Reserve             japhy@pobox.com
http://www.pobox.com/~japhy/                  http://pinyaj.stu.rpi.edu/
PerlMonth - An Online Perl Magazine            http://www.perlmonth.com/
The Perl Archive - Articles, Forums, etc.    http://www.perlarchive.com/



--- perlsub.pod	Wed Mar 24 19:26:36 1999
+++ perlsub.pod.new	Fri Feb  4 10:12:31 2000
@@ -852,19 +852,33 @@
     sub myrand ($)	     myrand 42
     sub mytime ()	     mytime
 
-Any backslashed prototype character represents an actual argument
-that absolutely must start with that character.  The value passed
-to the subroutine (as part of C<@_>) will be a reference to the
-actual argument given in the subroutine call, obtained by applying
-C<\> to that argument.
+A backslashed prototype character of C<$>, C<@>, C<%>, or C<*> represents
+an actual argument that must be a variable of that type, I<not> an
+expression returning a variable of that type.  The value passed to the
+subroutine (as part of C<@_>) will be a reference to the actual argument
+given in the subroutine call, obtained by implicitly applying C<\> to
+that argument.  Because Perl demands the argument be a variable of that
+type, the following function prototype and function call will elicit a
+compile-time error:
+
+    sub myfunc (\$);
+    myfunc $array[2];
+
+Perl will respond with "Type of arg 1 to main::myfunc must be scalar (not
+array element) ..." at compile-time.
+
+A backslashed C<&> is currently broken, and will not accept an anonymous
+subroutine nor a reference to a subroutine.
 
 Unbackslashed prototype characters have special meanings.  Any
 unbackslashed C<@> or C<%> eats all the rest of the arguments, and forces
-list context.  An argument represented by C<$> forces scalar context.  An
-C<&> requires an anonymous subroutine, which, if passed as the first
-argument, does not require the "C<sub>" keyword or a subsequent comma.  A
-C<*> does whatever it has to do to turn the argument into a reference to a
-symbol table entry.
+list context.  C<%> does not check the argument list to ensure an even
+number of arguments remain.  An argument represented by C<$> forces scalar
+context.  An C<&> requires an anonymous subroutine, or a reference to a
+subroutine; if passed an anonymous subroutine as the first argument, the
+"C<sub>" keyword is not required before the subroutine definition, nor is
+the comma after the subroutine definition.  C<*> does whatever it has to
+do to turn the argument into a reference to a symbol table entry.
 
 A semicolon separates mandatory arguments from optional arguments.
 (It is redundant before C<@> or C<%>.)

• perlsub.pod patch by Jeff Pinyan
• Re: perlsub.pod patch by Gurusamy Sarathy
• Re: perlsub.pod patch by sthoenna
• Re: perlsub.pod patch by Ilya Zakharevich