Experimental/oneof combinator

Numscript.g4

@@ -85,6 +85,7 @@ source:
 	| valueExpr							# srcAccount
 	| LBRACE allotmentClauseSrc+ RBRACE	# srcAllotment
 	| LBRACE source* RBRACE				# srcInorder
+	| 'oneof' LBRACE source+ RBRACE		# srcOneof
 	| MAX cap = valueExpr FROM source	# srcCapped;
 allotmentClauseSrc: allotment FROM source;
 
@@ -94,9 +95,10 @@ keptOrDestination:
 destinationInOrderClause: MAX valueExpr keptOrDestination;
 
 destination:
-	valueExpr																# destAccount
-	| LBRACE allotmentClauseDest+ RBRACE									# destAllotment
-	| LBRACE destinationInOrderClause* REMAINING keptOrDestination RBRACE	# destInorder;
+	valueExpr																		# destAccount
+	| LBRACE allotmentClauseDest+ RBRACE											# destAllotment
+	| LBRACE destinationInOrderClause* REMAINING keptOrDestination RBRACE			# destInorder
+	| 'oneof' LBRACE destinationInOrderClause* REMAINING keptOrDestination RBRACE	# destOneof;
 allotmentClauseDest: allotment keptOrDestination;
 
 sentValue: valueExpr # sentLiteral | sentAllLit # sentAll;

internal/analysis/check.go

@@ -503,6 +503,11 @@
 			res.checkSource(source)
 		}
 
+	case *parser.SourceOneof:
+		for _, source := range source.Sources {
+			res.checkSource(source)
+		}
+
 	case *parser.SourceCapped:
 		onExit := res.enterCappedSource()
 
@@ -571,6 +576,13 @@
 		}
 		res.checkKeptOrDestination(destination.Remaining)
 
+	case *parser.DestinationOneof:
+		for _, clause := range destination.Clauses {
+			res.checkExpression(clause.Cap, TypeMonetary)
+			res.checkKeptOrDestination(clause.To)
+		}
+		res.checkKeptOrDestination(destination.Remaining)
+
 	case *parser.DestinationAllotment:
 		var remainingAllotment *parser.RemainingAllotment
 		var variableLiterals []parser.Variable

internal/analysis/check_test.go

@@ -197,6 +197,31 @@ func TestUnboundVarInSource(t *testing.T) {
 	)
 }
 
+func TestUnboundVarInSourceOneof(t *testing.T) {
+	t.Parallel()
+
+	input := `send [C 1] (
+  source = oneof { $unbound_var }
+  destination = @dest
+)`
+
+	program := parser.Parse(input).Value
+
+	diagnostics := analysis.CheckProgram(program).Diagnostics
+	require.Len(t, diagnostics, 1)
+
+	assert.Equal(t,
+		[]analysis.Diagnostic{
+			{
+				Range: parser.RangeOfIndexed(input, "$unbound_var", 0),
+				Kind:  &analysis.UnboundVariable{Name: "unbound_var"},
+			},
+		},
+		diagnostics,
+	)
+
+}
+
 func TestUnboundVarInDest(t *testing.T) {
 	t.Parallel()
 

internal/cmd/run.go

@@ -27,6 +27,7 @@
 var runOutFormatOpt string
 
 var overdraftFeatureFlag bool
+var oneOfFeatureFlag bool
 
 type inputOpts struct {
 	Script    string                       `json:"script"`
@@ -121,6 +122,9 @@
 	if overdraftFeatureFlag {
 		featureFlags[interpreter.ExperimentalOverdraftFunctionFeatureFlag] = struct{}{}
 	}
+	if oneOfFeatureFlag {
+		featureFlags[interpreter.ExperimentalOneofFeatureFlag] = struct{}{}
+	}
 
 	result, err := interpreter.RunProgram(context.Background(), parseResult.Value, opt.Variables, interpreter.StaticStore{
 		Balances: opt.Balances,
@@ -201,6 +205,7 @@
 
 	// Feature flag
 	cmd.Flags().BoolVar(&overdraftFeatureFlag, interpreter.ExperimentalOverdraftFunctionFeatureFlag, false, "feature flag to enable the overdraft() function")
+	cmd.Flags().BoolVar(&oneOfFeatureFlag, interpreter.ExperimentalOneofFeatureFlag, false, "feature flag to enable the oneof combinator")
 
 	// Output options
 	cmd.Flags().StringVar(&runOutFormatOpt, "output-format", OutputFormatPretty, "Set the output format. Available options: pretty, json.")

internal/interpreter/batch_balances_query.go

@@ -128,6 +128,15 @@
 		}
 		return nil
 
+	case *parser.SourceOneof:
+		for _, subSource := range source.Sources {
+			err := st.findBalancesQueries(subSource)
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+
 	case *parser.SourceCapped:
 		// TODO can this be optimized in some cases?
 		return st.findBalancesQueries(source.From)

internal/interpreter/interpreter.go

@@ -179,7 +179,10 @@
 
 type FeatureFlag = string
 
-const ExperimentalOverdraftFunctionFeatureFlag FeatureFlag = "experimental-overdraft-function"
+const (
+	ExperimentalOverdraftFunctionFeatureFlag FeatureFlag = "experimental-overdraft-function"
+	ExperimentalOneofFeatureFlag             FeatureFlag = "experimental-oneof"
+)
 
 func RunProgram(
 	ctx context.Context,
@@ -198,10 +201,7 @@
 
 		CurrentBalanceQuery: BalanceQuery{},
 		ctx:                 ctx,
-	}
-
-	if _, ok := featureFlags[ExperimentalOverdraftFunctionFeatureFlag]; ok {
-		st.OverdraftFunctionFeatureFlag = true
+		FeatureFlags:        featureFlags,
 	}
 
 	err := st.parseVars(program.Vars, vars)
@@ -261,7 +261,7 @@
 
 	CurrentBalanceQuery BalanceQuery
 
-	OverdraftFunctionFeatureFlag bool
+	FeatureFlags map[string]struct{}
 }
 
 func (st *programState) pushSender(name string, monetary *big.Int) {
@@ -476,6 +476,16 @@
 		}
 		return totalSent, nil
 
+	case *parser.SourceOneof:
+		err := s.checkFeatureFlag(ExperimentalOneofFeatureFlag)
+		if err != nil {
+			return nil, err
+		}
+
+		// we can safely access the first one because empty oneof is parsing err
+		first := source.Sources[0]
+		return s.sendAll(first)
+
 	case *parser.SourceCapped:
 		monetary, err := evaluateExprAs(s, source.Cap, expectMonetaryOfAsset(s.CurrentAsset))
 		if err != nil {
@@ -567,6 +577,36 @@
 		}
 		return new(big.Int).Sub(amount, totalLeft), nil
 
+	case *parser.SourceOneof:
+		err := s.checkFeatureFlag(ExperimentalOneofFeatureFlag)
+		if err != nil {
+			return nil, err
+		}
+
+		// empty oneof is parsing err
+		leadingSources := source.Sources[0 : len(source.Sources)-1]
+
+		for _, source := range leadingSources {
+
+			// do not move this line below (as .trySendingUpTo() will mutate senders' length)
+			backtrackingIndex := len(s.Senders)
+
+			sentAmt, err := s.trySendingUpTo(source, amount)
+			if err != nil {
+				return nil, err
+			}
+
+			// if this branch managed to sent all the required amount, return now
+			if sentAmt.Cmp(amount) == 0 {
+				return amount, nil
+			}
+
+			// else, backtrack to remove this branch's sendings
+			s.Senders = s.Senders[0:backtrackingIndex]
+		}
+
+		return s.trySendingUpTo(source.Sources[len(source.Sources)-1], amount)
+
 	case *parser.SourceAllotment:
 		var items []parser.AllotmentValue
 		for _, i := range source.Items {
@@ -675,6 +715,27 @@
 		// passing "remainingAmount" directly breaks the code
 		return handler(destination.Remaining, remainingAmountCopy)
 
+	case *parser.DestinationOneof:
+		err := s.checkFeatureFlag(ExperimentalOneofFeatureFlag)
+		if err != nil {
+			return err
+		}
+		for _, destinationClause := range destination.Clauses {
+			cap, err := evaluateExprAs(s, destinationClause.Cap, expectMonetaryOfAsset(s.CurrentAsset))
+			if err != nil {
+				return err
+			}
+
+			// if the clause cap is >= the amount we're trying to receive, only go through this branch
+			switch cap.Cmp(amount) {
+			case 0, 1:
+				return s.receiveFromKeptOrDest(destinationClause.To, amount)
+			}
+
+			// otherwise try next clause (keep looping)
+		}
+		return s.receiveFromKeptOrDest(destination.Remaining, amount)
+
 	default:
 		utils.NonExhaustiveMatchPanic[any](destination)
 		return nil
@@ -853,15 +914,16 @@
 	r parser.Range,
 	args []Value,
 ) (*Monetary, InterpreterError) {
-	if !s.OverdraftFunctionFeatureFlag {
-		return nil, ExperimentalFeature{FlagName: ExperimentalOverdraftFunctionFeatureFlag}
+	err := s.checkFeatureFlag(ExperimentalOverdraftFunctionFeatureFlag)
+	if err != nil {
+		return nil, err
 	}
 
 	// TODO more precise args range location
 	p := NewArgsParser(args)
 	account := parseArg(p, r, expectAccount)
 	asset := parseArg(p, r, expectAsset)
-	err := p.parse()
+	err = p.parse()
 	if err != nil {
 		return nil, err
 	}
@@ -982,3 +1044,12 @@
 
 	return res, nil
 }
+
+func (s programState) checkFeatureFlag(flag string) InterpreterError {
+	_, ok := s.FeatureFlags[flag]
+	if ok {
+		return nil
+	} else {
+		return ExperimentalFeature{FlagName: flag}
+	}
+}