Create new OP_MULTIPARAM to implement subroutine signatures

Creates a new UNOP_AUX op type, `OP_MULTIPARAM`, that handles all of the
initial behaviour of assigning values to parameters of a subroutine
signature out of values passed by the caller. This is created in a
similar style to other multi-ops like `OP_MULTIDEREF` and
`OP_MULTICONCAT` where the op's aux structure contains a sub-program of
sorts, which describes all of the small details of operation.

Also adds a LOGOP, `OP_PARAMTEST` and UNOP `OP_PARAMSTORE` which are
responsible for implementing the default expressions of optional
parameters. These use the `SvPADSTALE` flag set on pad lexicals used as
parameters to remember whether assignment has happened, ensuring that
missing vs present-but-undef can be detected in a way that does not
depend on counting arguments on the stack.

This change is carefully designed to support two future ideas:

  * Named parameters as per PPC0024
    https://github.com/Perl/PPCs/blob/main/ppcs/ppc0024-signature-named-parameters.md

  * "no-snails"; the performance optimisation that avoids storing
    incoming argument values in the `@_` AV and instead consumes them
    directly from the stack

Author: leonerd

dump.c

@@ -1665,6 +1665,7 @@ S_do_op_dump_bar(pTHX_ I32 level, UV bar, PerlIO *file, const OP *o,
     case OP_ENTERWHEN:
     case OP_ENTERTRY:
     case OP_ONCE:
+    case OP_PARAMTEST:
         S_opdump_indent(aTHX_ o, level, bar, file, "OTHER");
         S_opdump_link(aTHX_ o, cLOGOPo->op_other, file);
         break;
@@ -1782,6 +1783,35 @@ S_do_op_dump_bar(pTHX_ I32 level, UV bar, PerlIO *file, const OP *o,
         break;
     }
 
+    case OP_MULTIPARAM:
+    {
+        struct op_multiparam_aux *aux = (struct op_multiparam_aux *)cUNOP_AUXo->op_aux;
+        UV min_args = aux->min_args;
+        UV n_positional = aux->n_positional;
+        if(n_positional > min_args)
+            S_opdump_indent(aTHX_ o, level, bar, file, "ARGS = %" UVuf " .. %" UVuf "\n",
+                    min_args, n_positional);
+        else
+            S_opdump_indent(aTHX_ o, level, bar, file, "ARGS = %" UVuf "\n",
+                    min_args);
+
+        for(Size_t i = 0; i < n_positional; i++) {
+            PADOFFSET padix = aux->param_padix[i];
+            if(padix)
+                S_opdump_indent(aTHX_ o, level, bar, file, "  PARAM [%zd] PADIX = %" UVuf "%s\n",
+                        i, aux->param_padix[i], i >= min_args ? " OPT" : "");
+            else
+                S_opdump_indent(aTHX_ o, level, bar, file, "  PARAM [%zd] ANON\n",
+                        i);
+        }
+
+        if(aux->slurpy)
+            S_opdump_indent(aTHX_ o, level, bar, file, "SLURPY = '%c' PADIX = %" UVuf "\n",
+                    aux->slurpy, aux->slurpy_padix);
+
+        break;
+    }
+
     case OP_CUSTOM:
     {
         void (*custom_dumper)(pTHX_ const OP *o, struct Perl_OpDumpContext *ctx) =

ext/B/B.pm

@@ -20,7 +20,7 @@ sub import {
 # walkoptree comes from B.xs
 
 BEGIN {
-    $B::VERSION = '1.89';
+    $B::VERSION = '1.90';
     @B::EXPORT_OK = ();
 
     # Our BOOT code needs $VERSION set, and will append to @EXPORT_OK.

ext/B/B.xs

@@ -1393,6 +1393,20 @@ aux_list(o, cv)
                 XSRETURN(len);
 
             } /* OP_MULTIDEREF */
+
+        case OP_MULTIPARAM:
+            {
+                struct op_multiparam_aux *p = (struct op_multiparam_aux *)aux;
+                UV nparams = p->n_positional;
+                EXTEND(SP, (IV)(3 + nparams + 1));
+                mPUSHu(p->min_args);
+                mPUSHu(p->n_positional);
+                PUSHs(sv_2mortal(p->slurpy ? newSVpvf("%c", p->slurpy) : &PL_sv_no));
+                for(UV parami = 0; parami < nparams; parami++)
+                    mPUSHu(p->param_padix[parami]);
+                mPUSHu(p->slurpy_padix);
+                XSRETURN(3 + nparams + 1);
+            }
         } /* switch */
 
 

ext/Opcode/Opcode.pm

@@ -1,4 +1,4 @@
-package Opcode 1.69;
+package Opcode 1.70;
 
 use strict;
 
@@ -309,6 +309,7 @@ invert_opset function.
 
     rv2hv helem hslice kvhslice each values keys exists delete
     aeach akeys avalues multideref argelem argdefelem argcheck
+    multiparam paramtest paramstore
 
     preinc i_preinc predec i_predec postinc i_postinc
     postdec i_postdec int hex oct abs pow multiply i_multiply

ext/XS-APItest/APItest.pm

@@ -4,7 +4,7 @@ use strict;
 use warnings;
 use Carp;
 
-our $VERSION = '1.44';
+our $VERSION = '1.45';
 
 require XSLoader;
 

ext/XS-APItest/APItest.xs

@@ -1200,6 +1200,29 @@ static OP *THX_parse_keyword_subsignature(pTHX)
                     newSVpvf(kid->op_flags & OPf_KIDS ? "argelem:%s:d" : "argelem:%s", namepv)));
                 break;
             }
+            case OP_MULTIPARAM: {
+                struct op_multiparam_aux *p =
+                    (struct op_multiparam_aux *)(cUNOP_AUXx(kid)->op_aux);
+                PADNAMELIST *names = PadlistNAMES(CvPADLIST(find_runcv(0)));
+                SV *retsv = newSVpvf("multiparam:%" UVuf "..%" UVuf ":%c",
+                        p->min_args, p->n_positional, p->slurpy ? p->slurpy : '-');
+                for (UV paramidx = 0; paramidx < p->n_positional; paramidx++) {
+                    char *namepv = PadnamePV(padnamelist_fetch(names, p->param_padix[paramidx]));
+                    if(namepv)
+                        sv_catpvf(retsv, ":%s=%" UVf, namepv, paramidx);
+                    else
+                        sv_catpvf(retsv, ":(anon)=%" UVf, paramidx);
+                    if(paramidx >= p->min_args)
+                        sv_catpvs(retsv, "?");
+                }
+                if (p->slurpy_padix)
+                    sv_catpvf(retsv, ":%s=*",
+                        PadnamePV(padnamelist_fetch(names, p->slurpy_padix)));
+                retop = op_append_list(OP_LIST, retop, newSVOP(OP_CONST, 0, retsv));
+                break;
+            }
+            case OP_PARAMTEST:
+                break;
             default:
                 fprintf(stderr, "TODO: examine kid %p (optype=%s)\n", kid, PL_op_name[kid->op_type]);
                 break;

ext/XS-APItest/t/subsignature.t

@@ -19,11 +19,11 @@ eval q{
 };
 is $@, "";
 is_deeply \@t, [
-	['nextstate:4', 'argcheck:2:0:-', 'argelem:$x', 'argelem:$y'],
-	['nextstate:5', 'argcheck:2:0:-', 'argelem:$z',],
-	['nextstate:6', 'argcheck:0:0:@', 'argelem:@rest'],
-	['nextstate:7', 'argcheck:0:0:%', 'argelem:%rest'],
-	['nextstate:8', 'argcheck:1:1:-', 'argelem:$one:d'],
+	['nextstate:4', 'multiparam:2..2:-:$x=0:$y=1' ],
+	['nextstate:5', 'multiparam:2..2:-:$z=0:(anon)=1',],
+	['nextstate:6', 'multiparam:0..0:@:@rest=*'],
+	['nextstate:7', 'multiparam:0..0:%:%rest=*'],
+	['nextstate:8', 'multiparam:0..1:-:$one=0?'],
 ];
 
 done_testing;

lib/B/Deparse.pm

@@ -7,7 +7,7 @@
 # This is based on the module of the same name by Malcolm Beattie,
 # but essentially none of his code remains.
 
-package B::Deparse 1.86;
+package B::Deparse 1.87;
 use strict;
 use Carp;
 use B qw(class main_root main_start main_cv svref_2object opnumber perlstring
@@ -26,6 +26,7 @@ use B qw(class main_root main_start main_cv svref_2object opnumber perlstring
          OPpMULTICONCAT_APPEND OPpMULTICONCAT_STRINGIFY OPpMULTICONCAT_FAKE
          OPpTRUEBOOL OPpINDEX_BOOLNEG OPpDEFER_FINALLY
          OPpARG_IF_UNDEF OPpARG_IF_FALSE
+         OPpPARAM_IF_UNDEF OPpPARAM_IF_FALSE
 	 SVf_IOK SVf_NOK SVf_ROK SVf_POK SVf_FAKE SVs_RMG SVs_SMG
 	 SVs_PADTMP
          CVf_NOWARN_AMBIGUOUS CVf_LVALUE CVf_IsMETHOD
@@ -1180,6 +1181,94 @@ sub pad_subs {
 }
 
 
+# deparse_multiparam(): deparse, if possible, a sequence of ops into a
+# subroutine signature. If possible, returns a string representing the
+# signature syntax, minus the surrounding parentheses.
+
+sub deparse_multiparam {
+    my ($self, $topop, $cv) = @_;
+
+    $topop = $topop->first;
+    return unless $$topop and $topop->name eq 'lineseq';
+
+    # last op should be nextstate
+    my $last = $topop->last;
+    return unless $$last
+                    and (   _op_is_or_was($last, OP_NEXTSTATE)
+                         or _op_is_or_was($last, OP_DBSTATE));
+
+    # first OP_NEXTSTATE
+
+    my $o = $topop->first;
+    return unless $$o;
+    return if $o->label;
+
+    # OP_MULTIPARAM
+
+    $o = $o->sibling;
+    return unless $$o and $o->name eq 'multiparam';
+
+    my ($min_args, $max_args, $slurpy, @rest) = $o->aux_list($cv);
+    my $nparams = $max_args;
+    my @param_padix = splice @rest, 0, $nparams, ();
+    my ($slurpy_padix) = @rest;
+
+    my @sig;
+    my %parami_for_padix;
+
+    # Initial scalars
+    foreach my $parami ( 0 .. $max_args-1 ) {
+        my $padix = $param_padix[$parami];
+        $sig[$parami] = $self->padname($padix) || '$';
+        $parami_for_padix{$padix} = $parami;
+    }
+
+    $o = $o->sibling;
+    for (; $o and !null $o; $o = $o->sibling) {
+        # Look for OP_NULL[OP_PARAMTEST[OP_PARAMSTORE]]
+        my $ofirst;
+        if ($o->name eq 'null' and $o->flags & OPf_KIDS and
+                ($ofirst = $o->first)->name eq 'paramtest' and
+                $ofirst->first->name eq 'paramstore') {
+            # A defaulting expression
+
+            my $parami = $parami_for_padix{$ofirst->targ};
+
+            my $assign = "=";
+            $assign = "//=" if $ofirst->private == OPpPARAM_IF_UNDEF;
+            $assign = "||=" if $ofirst->private == OPpPARAM_IF_FALSE;
+
+            length $sig[$parami] > 1 ?
+                ( $sig[$parami] .= ' ' ) :
+                ( $sig[$parami] = '$' ); # intentionally no trailing space
+
+            my $defop = $ofirst->first->first;
+            if ($defop->name eq "stub") {
+                $sig[$parami] .= "$assign";
+            }
+            else {
+                my $def = $self->deparse($defop, 7);
+                $def = "($def)" if $defop->flags & OPf_PARENS;
+
+                $sig[$parami] .= "$assign $def";
+            }
+        }
+    }
+
+    if ($cv->CvFLAGS & CVf_IsMETHOD) {
+        # Remove the implied `$self` argument
+        warn "Expected first signature argument to be named \$self"
+            unless @sig and $sig[0] eq '$self';
+        shift @sig;
+    }
+
+    if ($slurpy) {
+        push @sig, $slurpy_padix ? $self->padname($slurpy_padix) : $slurpy;
+    }
+
+    return join(", ", @sig);
+}
+
 # deparse_argops(): deparse, if possible, a sequence of argcheck + argelem
 # ops into a subroutine signature. If successful, return the first op
 # following the signature ops plus the signature string; else return the
@@ -1377,7 +1466,8 @@ Carp::confess("SPECIAL in deparse_sub") if $cv->isa("B::SPECIAL");
             and $firstop->name eq 'null'
             and $firstop->targ == OP_ARGCHECK
         ) {
-            my ($mysig) = $self->deparse_argops($firstop, $cv);
+            my ($mysig) = $self->deparse_multiparam($firstop, $cv) //
+                          $self->deparse_argops($firstop, $cv);
             if (defined $mysig) {
                 $sig = $mysig;
                 $firstop = $is_list ? $firstop->sibling : undef;