move sub attributes before the signature

RT #132141

Attributes such as :lvalue have to come *before* the signature to ensure
that they're applied to any code block within the signature; e.g.

    sub f :lvalue ($a = do { $x = "abc"; return substr($x,0,1)}) {
        ....
    }

So this commit moves sub attributes to come before the signature.  This is
how they were originally, but they were swapped with v5.21.7-394-gabcf453.
This commit is essentially a revert of that commit (and its followups
v5.21.7-395-g71917f6, v5.21.7-421-g63ccd0d), plus some extra work for
Deparse, and an extra test.

See:
    RT #123069 for why they were originally swapped
    RT #132141 for why that broke :lvalue
    http://nntp.perl.org/group/perl.perl5.porters/247999
               for a general discussion about RT #132141

1 files changed, 22 insertions, 11 deletions

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 8490630cd4..a761e3d078 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -15,20 +15,25 @@ X<subroutine, declaration> X<sub>
 
     sub NAME BLOCK		  # A declaration and a definition.
     sub NAME(PROTO) BLOCK	  #  ditto, but with prototypes
-    sub NAME(SIG) BLOCK           #  with a signature instead
     sub NAME : ATTRS BLOCK	  #  with attributes
     sub NAME(PROTO) : ATTRS BLOCK #  with prototypes and attributes
-    sub NAME(SIG) : ATTRS BLOCK   #  with a signature and attributes
+
+    use feature 'signatures';
+    sub NAME(SIG) BLOCK                    # with signature
+    sub NAME :ATTRS (SIG) BLOCK            # with signature, attributes
+    sub NAME :prototype(PROTO) (SIG) BLOCK # with signature, prototype
 
 To define an anonymous subroutine at runtime:
 X<subroutine, anonymous>
 
     $subref = sub BLOCK;		 # no proto
     $subref = sub (PROTO) BLOCK;	 # with proto
-    $subref = sub (SIG) BLOCK;           # with signature
     $subref = sub : ATTRS BLOCK;	 # with attributes
     $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
-    $subref = sub (SIG) : ATTRS BLOCK;   # with signature and attributes
+
+    use feature 'signatures';
+    $subref = sub (SIG) BLOCK;           # with signature
+    $subref = sub : ATTRS(SIG) BLOCK;    # with signature, attributes
 
 To import subroutines:
 X<import>
@@ -317,10 +322,15 @@ a warning unless the "experimental::signatures" warnings category is
 disabled.
 
 The signature is part of a subroutine's body.  Normally the body of a
-subroutine is simply a braced block of code.  When using a signature,
-the signature is a parenthesised list that goes immediately after
-the subroutine name (or, for anonymous subroutines, immediately after
-the C<sub> keyword).  The signature declares lexical variables that are
+subroutine is simply a braced block of code, but when using a signature,
+the signature is a parenthesised list that goes immediately before the
+block, after any name or attributes.
+
+For example,
+
+    sub foo :lvalue ($a, $b = 1, @c) { .... }
+
+The signature declares lexical variables that are
 in scope for the block.  When the subroutine is called, the signature
 takes control first.  It populates the signature variables from the
 list of arguments that were passed.  If the argument list doesn't meet
@@ -490,12 +500,13 @@ a signature.  They do different jobs: the prototype affects compilation
 of calls to the subroutine, and the signature puts argument values into
 lexical variables at runtime.  You can therefore write
 
-    sub foo ($left, $right) : prototype($$) {
+    sub foo :prototype($$) ($left, $right) {
 	return $left + $right;
     }
 
-The prototype attribute, and any other attributes, come after 
-the signature.
+The prototype attribute, and any other attributes, must come before
+the signature.  The signature always immediately precedes the block of
+the subroutine's body.
 
 =head2 Private Variables via my()
 X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>