feat: make numeric-string arithmetic opt-in via Options flag

The "+" fix for issue #342 restored v4 behavior ("10" + 5 == 15), but
that flips the v5/v6 string-concatenation behavior ("10" + 5 == "105"),
which is itself a breaking change for current users.

Gate the arithmetic path behind a new Options.NumericStringArithmetic
flag (default false), so the v5/v6 behavior is preserved unless a caller
explicitly opts in. This makes the fix non-breaking and mergeable.

Add TestIssue342DefaultIsConcatenation to lock in the default behavior;
existing TestIssue342 now enables the flag.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Richtermeister

options.go

@@ -10,19 +10,28 @@ type Options struct {
 	// If this is set to true leading spaces and tabs are stripped from the
 	// start of a line to a block. Defaults to false
 	LStripBlocks bool
+
+	// If this is set to true the "+" operator treats a numeric string and a
+	// number as numbers and performs arithmetic addition (e.g. "10" + 5 == 15),
+	// restoring pongo2 v4 behavior. Defaults to false, in which case "+"
+	// performs string concatenation whenever either operand is a string (the
+	// v5/v6 behavior, e.g. "10" + 5 == "105"). See issue #342.
+	NumericStringArithmetic bool
 }
 
 func newOptions() *Options {
 	return &Options{
-		TrimBlocks:   false,
-		LStripBlocks: false,
+		TrimBlocks:              false,
+		LStripBlocks:            false,
+		NumericStringArithmetic: false,
 	}
 }
 
 // Update updates this options from another options.
 func (opt *Options) Update(other *Options) *Options {
 	opt.TrimBlocks = other.TrimBlocks
 	opt.LStripBlocks = other.LStripBlocks
+	opt.NumericStringArithmetic = other.NumericStringArithmetic
 
 	return opt
 }

parser_expression.go

@@ -254,7 +254,10 @@ func (expr *simpleExpression) Evaluate(ctx *ExecutionContext) (*Value, error) {
 		case "+":
 			// If one operand is a number and the other is a numeric string,
 			// treat both as numbers and do arithmetic (fixes issue #342).
-			if (result.IsNumber() && t2.CanBeNumber()) || (t2.IsNumber() && result.CanBeNumber()) {
+			// This is opt-in (restores pongo2 v4 behavior); when disabled the
+			// default v5/v6 string-concatenation behavior below is used.
+			if ctx.template.Options.NumericStringArithmetic &&
+				((result.IsNumber() && t2.CanBeNumber()) || (t2.IsNumber() && result.CanBeNumber())) {
 				if result.IsFloat() || t2.IsFloat() || (result.IsString() && strings.Contains(result.String(), ".")) || (t2.IsString() && strings.Contains(t2.String(), ".")) {
 					// Result will be a float
 					return AsValue(result.Float() + t2.Float()), nil

pongo2_issues_test.go

@@ -417,9 +417,11 @@ func TestIssue209(t *testing.T) {
 }
 
 func TestIssue342(t *testing.T) {
-	// Test that adding a numeric string and a number results in arithmetic addition.
+	// Test that, with the opt-in NumericStringArithmetic option enabled, adding
+	// a numeric string and a number results in arithmetic addition.
 	// Bug: In v6, "10" + 5 returns "105" (string concatenation).
-	// Expected: "10" + 5 should return 15 (arithmetic addition) as in v4.
+	// With the option on, "10" + 5 returns 15 (arithmetic addition) as in v4.
+	// The option is off by default; see TestIssue342DefaultIsConcatenation.
 	// See: https://github.com/flosch/pongo2/issues/342
 
 	tests := []struct {
@@ -485,6 +487,45 @@ func TestIssue342(t *testing.T) {
 				t.Fatalf("failed to parse template: %v", err)
 			}
 
+			// Opt in to the v4 numeric-string arithmetic behavior.
+			tpl.Options.NumericStringArithmetic = true
+
+			result, err := tpl.Execute(tt.context)
+			if err != nil {
+				t.Fatalf("failed to execute template: %v", err)
+			}
+
+			if result != tt.expected {
+				t.Errorf("expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}
+
+func TestIssue342DefaultIsConcatenation(t *testing.T) {
+	// With the NumericStringArithmetic option left at its default (false), the
+	// "+" operator keeps the v5/v6 string-concatenation behavior. This guards
+	// against the fix re-introducing a breaking change for existing users.
+	// See: https://github.com/flosch/pongo2/issues/342
+
+	tests := []struct {
+		name     string
+		context  pongo2.Context
+		expected string
+	}{
+		{"numeric string + integer", pongo2.Context{"a": "10", "b": 5}, "105"},
+		{"integer + numeric string", pongo2.Context{"a": 5, "b": "10"}, "510"},
+		{"numeric string + float", pongo2.Context{"a": "10.5", "b": 2.5}, "10.52.500000"},
+		{"non-numeric string + integer", pongo2.Context{"a": "hello", "b": 5}, "hello5"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tpl, err := pongo2.FromString("{{ a + b }}")
+			if err != nil {
+				t.Fatalf("failed to parse template: %v", err)
+			}
+
 			result, err := tpl.Execute(tt.context)
 			if err != nil {
 				t.Fatalf("failed to execute template: %v", err)