[IMP] spreadsheet: add named ranges feature

This commits adds the named ranges feature, that allows to defined a
custom name for a range of cells, and use that name in formulas.

closes #7605

Task: 5380498
Signed-off-by: Lucas Lefèvre (lul) <lul@odoo.com>

Author: hokolomopo

demo/data.js

@@ -48,8 +48,8 @@ export const demoData = {
         C5: "42",
         C7: "3",
         C9: "= SUM( C4:C5 )",
-        C10: "=SUM(C4:C7)",
-        C11: "=-(3 + C7 *SUM(C4:C7))",
+        C10: "=SUM(MyNamedRange)",
+        C11: "=-(3 + C7 *SUM(MyNamedRange))",
         C12: "=SUM(C9:C11)",
         C14: "=C14",
         C15: "=(+",
@@ -3902,6 +3902,9 @@ export const demoData = {
   },
   pivotNextId: 2,
   customTableStyles: {},
+  namedRanges: {
+    MyNamedRange: "Sheet1!C4:C7",
+  },
 };
 
 // Performance dataset

packages/o-spreadsheet-engine/src/collaborative/ot/ot.ts

@@ -1,5 +1,10 @@
 import { getAddHeaderStartIndex, isDefined } from "../../helpers/misc";
-import { getRangeAdapter, rangeAdapterRegistry } from "../../helpers/range";
+import {
+  getIdentityRangeAdapter,
+  getNamedRangeAdapter,
+  getRangeAdapter,
+  rangeAdapterRegistry,
+} from "../../helpers/range";
 import {
   moveHeaderIndexesOnHeaderAddition,
   moveHeaderIndexesOnHeaderDeletion,
@@ -77,9 +82,12 @@ function adaptTransform(toTransform: CoreCommand, executed: CoreCommand): CoreCo
   if (!adaptFn) {
     return toTransform;
   }
-  const rangeAdapter = getRangeAdapter(executed);
-  if (rangeAdapter) {
-    return adaptFn(toTransform, rangeAdapter);
+  let rangeAdapter = getRangeAdapter(executed);
+  let namedRangeAdapter = getNamedRangeAdapter(executed);
+  if (rangeAdapter || namedRangeAdapter) {
+    rangeAdapter = rangeAdapter || getIdentityRangeAdapter();
+    namedRangeAdapter = namedRangeAdapter || ((name) => name);
+    return adaptFn(toTransform, rangeAdapter, namedRangeAdapter);
   }
   return toTransform;
 }

packages/o-spreadsheet-engine/src/collaborative/ot/ot_specific.ts

@@ -15,6 +15,7 @@ import {
   CreateTableCommand,
   DeleteChartCommand,
   DeleteFigureCommand,
+  DeleteNamedRangeCommand,
   DeleteSheetCommand,
   DuplicatePivotCommand,
   FoldHeaderGroupCommand,
@@ -33,6 +34,7 @@ import {
   UpdateCarouselCommand,
   UpdateChartCommand,
   UpdateFigureCommand,
+  UpdateNamedRangeCommand,
   UpdatePivotCommand,
   UpdateTableCommand,
 } from "../../types/commands";
@@ -107,6 +109,12 @@ otRegistry.addTransformation(
   pivotZoneTransformation
 );
 
+otRegistry.addTransformation(
+  "UPDATE_NAMED_RANGE",
+  ["UPDATE_NAMED_RANGE", "DELETE_NAMED_RANGE"],
+  updateNamedRangeTransformation
+);
+
 function pivotZoneTransformation(
   toTransform: AddPivotCommand | UpdatePivotCommand,
   executed: AddColumnsRowsCommand | RemoveColumnsRowsCommand
@@ -348,3 +356,22 @@ function groupHeadersTransformation(
 
   return { ...toTransform, start: Math.min(...results), end: Math.max(...results) };
 }
+
+function updateNamedRangeTransformation(
+  toTransform: UpdateNamedRangeCommand | DeleteNamedRangeCommand,
+  executed: UpdateNamedRangeCommand
+): UpdateNamedRangeCommand | DeleteNamedRangeCommand | undefined {
+  if (executed.newRangeName === executed.oldRangeName) {
+    return toTransform;
+  }
+  if (toTransform.type === "DELETE_NAMED_RANGE" && toTransform.name === executed.oldRangeName) {
+    return { ...toTransform, name: executed.newRangeName };
+  }
+  if (
+    toTransform.type === "UPDATE_NAMED_RANGE" &&
+    toTransform.oldRangeName === executed.oldRangeName
+  ) {
+    return { ...toTransform, oldRangeName: executed.newRangeName };
+  }
+  return toTransform;
+}

packages/o-spreadsheet-engine/src/collaborative/ot/srt_specific.ts

@@ -1,5 +1,5 @@
 import { transformDefinition } from "../../helpers/figures/charts/chart_factory";
-import { adaptFormulaStringRanges, adaptStringRange } from "../../helpers/formulas";
+import { adaptFormulaString, adaptStringRange } from "../../helpers/formulas";
 import { deepCopy } from "../../helpers/misc";
 import { specificRangeTransformRegistry } from "../../registries/srt_registry";
 import {
@@ -11,42 +11,52 @@ import {
   UpdateChartCommand,
   UpdatePivotCommand,
 } from "../../types/commands";
-import { RangeAdapter } from "../../types/misc";
+import { ApplyRenameNamedRange, RangeAdapter } from "../../types/misc";
 
 function updateCellCommandAdaptRange(
   cmd: UpdateCellCommand,
-  applyChange: RangeAdapter
+  applyChange: RangeAdapter,
+  namedRangeAdapter: ApplyRenameNamedRange
 ): UpdateCellCommand {
-  const content = cmd.content && adaptFormulaStringRanges(cmd.sheetId, cmd.content, applyChange);
+  const content =
+    cmd.content && adaptFormulaString(cmd.sheetId, cmd.content, applyChange, namedRangeAdapter);
   return { ...cmd, content };
 }
 specificRangeTransformRegistry.add("UPDATE_CELL", updateCellCommandAdaptRange);
 
 function addConditionalFormatCommandAdaptRange(
   cmd: AddConditionalFormatCommand,
-  applyChange: RangeAdapter
+  applyChange: RangeAdapter,
+  namedRangeAdapter: ApplyRenameNamedRange
 ): AddConditionalFormatCommand {
   const rule = cmd.cf.rule;
   cmd = { ...cmd, cf: { ...cmd.cf } };
   if (rule.type === "CellIsRule") {
     cmd.cf.rule = {
       ...rule,
-      values: rule.values.map((val) => adaptFormulaStringRanges(cmd.sheetId, val, applyChange)),
+      values: rule.values.map((val) =>
+        adaptFormulaString(cmd.sheetId, val, applyChange, namedRangeAdapter)
+      ),
     };
   } else if (rule.type === "ColorScaleRule") {
     const { minimum: min, maximum: max, midpoint: mid } = rule;
     cmd.cf.rule = {
       ...rule,
       minimum: {
         ...min,
-        value: min.value && adaptFormulaStringRanges(cmd.sheetId, min.value, applyChange),
+        value:
+          min.value && adaptFormulaString(cmd.sheetId, min.value, applyChange, namedRangeAdapter),
       },
       maximum: {
         ...max,
-        value: max.value && adaptFormulaStringRanges(cmd.sheetId, max.value, applyChange),
+        value:
+          max.value && adaptFormulaString(cmd.sheetId, max.value, applyChange, namedRangeAdapter),
       },
       midpoint: mid
-        ? { ...mid, value: adaptFormulaStringRanges(cmd.sheetId, mid.value, applyChange) }
+        ? {
+            ...mid,
+            value: adaptFormulaString(cmd.sheetId, mid.value, applyChange, namedRangeAdapter),
+          }
         : undefined,
     };
   } else if (rule.type === "IconSetRule") {
@@ -55,11 +65,11 @@ function addConditionalFormatCommandAdaptRange(
       ...rule,
       upperInflectionPoint: {
         ...uip,
-        value: adaptFormulaStringRanges(cmd.sheetId, uip.value, applyChange),
+        value: adaptFormulaString(cmd.sheetId, uip.value, applyChange, namedRangeAdapter),
       },
       lowerInflectionPoint: {
         ...lip,
-        value: adaptFormulaStringRanges(cmd.sheetId, lip.value, applyChange),
+        value: adaptFormulaString(cmd.sheetId, lip.value, applyChange, namedRangeAdapter),
       },
     };
   } else if (rule.type === "DataBarRule") {
@@ -76,27 +86,30 @@ specificRangeTransformRegistry.add("ADD_CONDITIONAL_FORMAT", addConditionalForma
 
 function addDataValidationCommandAdaptRange(
   cmd: AddDataValidationCommand,
-  applyChange: RangeAdapter
+  applyChange: RangeAdapter,
+  namedRangeAdapter: ApplyRenameNamedRange
 ): AddDataValidationCommand {
   cmd = { ...cmd, rule: { ...cmd.rule, criterion: { ...cmd.rule.criterion } } };
   cmd.rule.criterion.values = cmd.rule.criterion.values.map((val) =>
-    adaptFormulaStringRanges(cmd.sheetId, val, applyChange)
+    adaptFormulaString(cmd.sheetId, val, applyChange, namedRangeAdapter)
   );
   return cmd;
 }
 specificRangeTransformRegistry.add("ADD_DATA_VALIDATION_RULE", addDataValidationCommandAdaptRange);
 
 function addPivotCommandAdaptRange<Cmd extends AddPivotCommand | UpdatePivotCommand>(
   cmd: Cmd,
-  applyChange: RangeAdapter
+  applyChange: RangeAdapter,
+  namedRangeAdapter: ApplyRenameNamedRange
 ): Cmd {
   cmd = deepCopy(cmd);
   cmd.pivot.measures.map((measure) => {
     if (measure.computedBy) {
-      measure.computedBy.formula = adaptFormulaStringRanges(
+      measure.computedBy.formula = adaptFormulaString(
         measure.computedBy.sheetId,
         measure.computedBy.formula,
-        applyChange
+        applyChange,
+        namedRangeAdapter
       );
     }
   });
@@ -110,10 +123,11 @@ specificRangeTransformRegistry.add("UPDATE_CHART", updateChartRangesTransformati
 
 function updateChartRangesTransformation<Cmd extends UpdateChartCommand | CreateChartCommand>(
   cmd: Cmd,
-  applyChange: RangeAdapter
+  applyChange: RangeAdapter,
+  namedRangeAdapter: ApplyRenameNamedRange
 ): Cmd {
   return {
     ...cmd,
-    definition: transformDefinition(cmd.sheetId, cmd.definition, applyChange),
+    definition: transformDefinition(cmd.sheetId, cmd.definition, applyChange, namedRangeAdapter),
   };
 }

packages/o-spreadsheet-engine/src/formulas/compiler.ts

@@ -1,11 +1,19 @@
 import { argTargeting } from "../functions/arguments";
 import { functionRegistry } from "../functions/function_registry";
 import { concat, parseNumber, unquote } from "../helpers";
+import { canBeNamedRangeToken } from "../helpers/formulas";
 import { _t } from "../translation";
 import { CoreGetters } from "../types/core_getters";
 import { BadExpressionError, UnknownFunctionError } from "../types/errors";
 import { DEFAULT_LOCALE } from "../types/locale";
-import { FormulaToExecute, LiteralValues, UID } from "../types/misc";
+import {
+  ApplyRangeChange,
+  ApplyRenameNamedRange,
+  FormulaToExecute,
+  LiteralValues,
+  NamedRange,
+  UID,
+} from "../types/misc";
 import { Range, RangeStringOptions } from "../types/range";
 import { FunctionCode, FunctionCodeBuilder, Scope } from "./code_builder";
 import { AST, ASTFuncall, iterateAstNodes, parseTokens } from "./parser";
@@ -135,6 +143,19 @@ export class CompiledFormula implements Omit<ICompiledFormula, "tokens" | "depen
     );
   }
 
+  getNamedRangesInFormula(getters: CoreGetters): NamedRange[] {
+    const namedRanges: NamedRange[] = [];
+    for (let i = 0; i < this.tokens.length; i++) {
+      if (canBeNamedRangeToken(this.tokens, i)) {
+        const namedRange = getters.getNamedRange(this.tokens[i].value);
+        if (namedRange) {
+          namedRanges.push(namedRange);
+        }
+      }
+    }
+    return namedRanges;
+  }
+
   usesSymbol(symbol: string) {
     return this.symbols.some((s) => collator.compare(s, symbol) === 0);
   }
@@ -174,6 +195,64 @@ export class CompiledFormula implements Omit<ICompiledFormula, "tokens" | "depen
     );
   }
 
+  adaptCompiledFormula(
+    applyChange: ApplyRangeChange,
+    applyUpdateNamedRange: ApplyRenameNamedRange
+  ): CompiledFormula {
+    const newDependencies: Range[] = [];
+    let hasChanges = false;
+    for (const range of this.rangeDependencies) {
+      const change = applyChange(range);
+      newDependencies.push(change.range);
+      if (change.changeType !== "NONE") {
+        hasChanges = true;
+      }
+    }
+
+    const tokenChanges = this.renameNamedRangeTokens(applyUpdateNamedRange);
+
+    if (hasChanges || tokenChanges) {
+      return new CompiledFormula(
+        this.sheetId,
+        tokenChanges?.newTokens || this.tokens,
+        this.literalValues,
+        tokenChanges?.newSymbols || this.symbols,
+        newDependencies,
+        this.isBadExpression,
+        compilationCacheKey(tokenChanges?.newTokens || this.tokens),
+        this.execute
+      );
+    }
+    return this;
+  }
+
+  /** Change the symbols and tokens on a named range change. Return undefined if nothing has changed. */
+  private renameNamedRangeTokens(
+    applyUpdateNamedRange: ApplyRenameNamedRange
+  ): { newSymbols: string[]; newTokens: Token[] } | undefined {
+    let hasChanged = false;
+    const newTokens: Token[] = [];
+    const newSymbols: string[] = [];
+    for (let i = 0; i < this.tokens.length; i++) {
+      let newToken = this.tokens[i];
+
+      if (canBeNamedRangeToken(this.tokens, i)) {
+        const newName = applyUpdateNamedRange(this.tokens[i].value);
+        if (newName !== this.tokens[i].value) {
+          hasChanged = true;
+          newToken = { ...this.tokens[i], value: newName };
+        }
+      }
+
+      newTokens.push(newToken);
+      if (newToken.type === "SYMBOL") {
+        newSymbols.push(newToken.value);
+      }
+    }
+
+    return hasChanged ? { newSymbols, newTokens } : undefined;
+  }
+
   static IsBadExpression(formula: string): boolean {
     const tokens = rangeTokenize(formula);
     const compiledFormula = compileTokens(tokens);
@@ -450,7 +529,9 @@ function compileTokensOrThrow(tokens: Token[]): ICompiledFormula {
         }
         case "SYMBOL":
           const symbolIndex = symbols.indexOf(ast.value);
-          return code.return(`getSymbolValue(this.symbols[${symbolIndex}])`);
+          return code.return(
+            `getSymbolValue(this.symbols[${symbolIndex}], ${hasRange}, ${isMeta})`
+          );
         case "EMPTY":
           return code.return("undefined");
       }

packages/o-spreadsheet-engine/src/formulas/parser.ts

@@ -189,11 +189,7 @@ function parseOperand(tokens: TokenList): AST {
     case "SYMBOL":
       const value = current.value;
       const nextToken = tokens.current;
-      if (
-        nextToken?.type === "LEFT_PAREN" &&
-        functionRegex.test(current.value) &&
-        value === unquote(value, "'")
-      ) {
+      if (isFuncallToken(current, nextToken)) {
         const { args, rightParen } = parseFunctionArgs(tokens);
         return {
           type: "FUNCALL",
@@ -471,3 +467,11 @@ export function mapAst<T extends AST["type"]>(
       return ast;
   }
 }
+
+export function isFuncallToken(currentToken: Token, nextToken: Token | undefined) {
+  return (
+    nextToken?.type === "LEFT_PAREN" &&
+    functionRegex.test(currentToken.value) &&
+    currentToken.value === unquote(currentToken.value, "'")
+  );
+}

packages/o-spreadsheet-engine/src/functions/module_lookup.ts

@@ -336,7 +336,10 @@ export const INDIRECT: AddFunctionDescription = {
       this.updateDependencies?.(originPosition);
     }
 
-    const range = this.getters.getRangeFromSheetXC(sheetId, _reference);
+    const namedRange = this.getters.getNamedRange(_reference);
+    const range = namedRange
+      ? namedRange.range
+      : this.getters.getRangeFromSheetXC(sheetId, _reference);
     if (range === undefined || range.invalidXc || range.invalidSheetName) {
       return new InvalidReferenceError();
     }