This closes #2303, support 3D references across sheet ranges

Formulas of the shape SUM(Sheet1:SheetN!A1) failed with
#NAME? invalid reference because parseReference split the
reference on ':' and handed the leading sheet token to parseRef,
which treats it as a cell name. No code path recognised the 3D
shape.

Add parse3DRef / split3DRef / readSheetToken / expand3DSheetRange
ahead of parseReference. On a match the reference is expanded
across the workbook-order sheet range and each sheet's cell or
range is evaluated recursively, yielding a matrix that existing
aggregates (SUM, AVERAGE, MIN, MAX, COUNT, COUNTA, PRODUCT)
consume unchanged. Non-ASCII sheet names work unquoted, e.g.
SUM(Jänner:Dezember!M40), matching Excel's behaviour.

The quoted-name form SUM('A':'B'!ref) is mis-tokenised by
github.com/xuri/efp before parseReference sees it, so it is
tracked separately and not handled here.

Signed-off-by: Christopher Albert <albert@tugraz.at>

Author: krystophny

calc.go

@@ -1627,6 +1627,9 @@ func (cr *cellRange) prepareCellRange(col, row bool, cellRef cellRef) error {
 // characters and default sheet name.
 func (f *File) parseReference(ctx *calcContext, sheet, reference string) (formulaArg, error) {
 	reference = strings.ReplaceAll(reference, "$", "")
+	if result, is3D, err := f.parse3DRef(ctx, reference); is3D {
+		return result, err
+	}
 	ranges, cellRanges, cellRefs := strings.Split(reference, ":"), list.New(), list.New()
 	if len(ranges) > 1 {
 		var cr cellRange
@@ -1666,6 +1669,104 @@ func (f *File) parseReference(ctx *calcContext, sheet, reference string) (formul
 	return f.rangeResolver(ctx, cellRefs, cellRanges)
 }
 
+// parse3DRef detects a 3D reference of the form
+//
+//	Sheet1 : Sheet2 ! CellOrRange
+//
+// and expands it across the workbook-order sheet range. On a 3D hit it
+// returns the expanded matrix as a formulaArg, is3D=true, and any
+// evaluation error encountered. On a non-3D reference it returns
+// is3D=false and callers fall through to the regular 2D parse path.
+// The quoted-name form `SUM('A':'B'!ref)` is mis-tokenised by the efp
+// tokeniser upstream of parseReference and is not handled here.
+func (f *File) parse3DRef(ctx *calcContext, reference string) (formulaArg, bool, error) {
+	sheet1, sheet2, innerRef, ok := split3DRef(reference)
+	if !ok {
+		return formulaArg{}, false, nil
+	}
+	sheets, err := f.expand3DSheetRange(sheet1, sheet2)
+	if err != nil {
+		return newErrorFormulaArg(formulaErrorREF, formulaErrorREF), true, errors.New(formulaErrorREF)
+	}
+	var matrix [][]formulaArg
+	for _, sn := range sheets {
+		sub, subErr := f.parseReference(ctx, sn, innerRef)
+		if subErr != nil {
+			return sub, true, subErr
+		}
+		switch sub.Type {
+		case ArgMatrix:
+			matrix = append(matrix, sub.Matrix...)
+		default:
+			matrix = append(matrix, []formulaArg{sub})
+		}
+	}
+	return newMatrixFormulaArg(matrix), true, nil
+}
+
+// split3DRef parses `sheet1:sheet2!ref` with optional single-quote
+// quoting of sheet names. Returns (sheet1, sheet2, innerRef, true) on a
+// 3D shape; otherwise returns ok=false.
+func split3DRef(reference string) (sheet1, sheet2, innerRef string, ok bool) {
+	bang := strings.Index(reference, "!")
+	if bang < 0 || bang == len(reference)-1 {
+		return
+	}
+	left, right := reference[:bang], reference[bang+1:]
+	s1, rest, ok := readSheetToken(left)
+	if !ok || len(rest) < 2 || rest[0] != ':' {
+		return "", "", "", false
+	}
+	s2, rest, ok := readSheetToken(rest[1:])
+	if !ok || rest != "" {
+		return "", "", "", false
+	}
+	if s1 == "" || s2 == "" {
+		return "", "", "", false
+	}
+	return s1, s2, right, true
+}
+
+// readSheetToken reads an unquoted sheet name from the front of s and
+// returns (name, remaining, ok). A `:` ends the name; a `!` or `'` is
+// rejected as malformed for the 3D shape parser.
+func readSheetToken(s string) (name, rest string, ok bool) {
+	if s == "" {
+		return "", "", false
+	}
+	for i, r := range s {
+		if r == ':' {
+			return s[:i], s[i:], true
+		}
+		if r == '!' || r == '\'' {
+			return "", "", false
+		}
+	}
+	return s, "", true
+}
+
+// expand3DSheetRange returns the workbook-order slice of sheet names
+// from sheet1 to sheet2 inclusive. Returns an error if either sheet is
+// missing, or if sheet1's index is greater than sheet2's in workbook
+// order. Callers surface the error as a #REF! formulaArg. Sheet lookup
+// is case-insensitive (GetSheetIndex uses strings.EqualFold); the
+// returned names preserve the workbook's stored casing.
+func (f *File) expand3DSheetRange(sheet1, sheet2 string) ([]string, error) {
+	i1, err := f.GetSheetIndex(sheet1)
+	if err != nil || i1 < 0 {
+		return nil, fmt.Errorf("sheet %q not found", sheet1)
+	}
+	i2, err := f.GetSheetIndex(sheet2)
+	if err != nil || i2 < 0 {
+		return nil, fmt.Errorf("sheet %q not found", sheet2)
+	}
+	if i1 > i2 {
+		return nil, fmt.Errorf("sheet range %q:%q reversed in workbook order", sheet1, sheet2)
+	}
+	names := f.GetSheetList()
+	return names[i1 : i2+1], nil
+}
+
 // prepareValueRange prepare value range.
 func prepareValueRange(cr cellRange, valueRange []int) {
 	if cr.From.Row < valueRange[0] || valueRange[0] == 0 {

calc_test.go

@@ -7094,3 +7094,75 @@ func TestCalcImplicitIntersect(t *testing.T) {
 		newMatrixFormulaArg([][]formulaArg{{newNumberFormulaArg(1)}})).Type,
 	)
 }
+
+func TestCalc3DRef(t *testing.T) {
+	// setup builds a workbook with four sheets `Jan`, `Feb`, `Mar`, `Apr`
+	// (creation order = workbook order) and fills A1 / A2 / B1 with
+	// predictable values on each so range shapes can be asserted.
+	setup := func() *File {
+		f := NewFile()
+		assert.NoError(t, f.SetSheetName("Sheet1", "Jan"))
+		_, err := f.NewSheet("Feb")
+		assert.NoError(t, err)
+		_, err = f.NewSheet("Mar")
+		assert.NoError(t, err)
+		_, err = f.NewSheet("Apr")
+		assert.NoError(t, err)
+		for i, sn := range []string{"Jan", "Feb", "Mar", "Apr"} {
+			base := int64(i + 1)
+			assert.NoError(t, f.SetCellInt(sn, "A1", base*10))
+			assert.NoError(t, f.SetCellInt(sn, "A2", base))
+			assert.NoError(t, f.SetCellInt(sn, "B1", base*100))
+		}
+		return f
+	}
+
+	cases := map[string]string{
+		// Single cell per sheet across the whole range.
+		"SUM(Jan:Apr!A1)":   "100", // 10+20+30+40
+		"SUM(Jan:Apr!$A$1)": "100",
+		"SUM(Jan:Mar!A1)":   "60",
+		"SUM(Feb:Apr!A1)":   "90",
+		"SUM(Jan:Jan!A1)":   "10", // degenerate single-sheet range
+		// Multi-cell ranges on each sheet.
+		"SUM(Jan:Apr!A1:A2)": "110", // (10+1)+(20+2)+(30+3)+(40+4)
+		"SUM(Jan:Apr!A1:B1)": "1100",
+		// Other aggregates.
+		"AVERAGE(Jan:Apr!A1)": "25",
+		"MIN(Jan:Apr!A1)":     "10",
+		"MAX(Jan:Apr!A1)":     "40",
+		"COUNT(Jan:Apr!A1)":   "4",
+		"COUNTA(Jan:Apr!A1)":  "4",
+		"PRODUCT(Jan:Apr!A1)": "240000",
+		// Error paths.
+		"SUM(Apr:Jan!A1)": "#REF!", // reversed order
+		"SUM(Jan:Xyz!A1)": "#REF!", // missing end sheet
+		"SUM(Xyz:Mar!A1)": "#REF!", // missing start sheet
+	}
+	for formula, expected := range cases {
+		f := setup()
+		assert.NoError(t, f.SetCellFormula("Jan", "Z1", formula))
+		result, _ := f.CalcCellValue("Jan", "Z1")
+		assert.Equal(t, expected, result, formula)
+	}
+
+	// Non-ASCII sheet names must work unquoted, matching Excel's
+	// behaviour. Uses the month-name shape common in European workbooks.
+	t.Run("non-ascii sheet names", func(t *testing.T) {
+		f := NewFile()
+		assert.NoError(t, f.SetSheetName("Sheet1", "Jänner"))
+		_, err := f.NewSheet("Februar")
+		assert.NoError(t, err)
+		_, err = f.NewSheet("März")
+		assert.NoError(t, err)
+		_, err = f.NewSheet("Dezember")
+		assert.NoError(t, err)
+		for i, sn := range []string{"Jänner", "Februar", "März", "Dezember"} {
+			assert.NoError(t, f.SetCellInt(sn, "M40", int64((i+1)*100)))
+		}
+		assert.NoError(t, f.SetCellFormula("Jänner", "A1", "SUM(Jänner:Dezember!$M$40)"))
+		result, err := f.CalcCellValue("Jänner", "A1")
+		assert.NoError(t, err)
+		assert.Equal(t, "1000", result)
+	})
+}