@trebco/treb 22.8.0 → 22.12.1

package/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v22.8. Copyright 2018-2022 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v22.12. Copyright 2018-2022 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /** 
  * Global instance. In the base script, this object will be created as an
@@ -203,13 +203,17 @@ export declare class EmbeddedSpreadsheet {
     AddSheet(name?: string): void;
 
     /**
-     * Insert an annotation node. Usually this means inserting a chart.
+     * Insert an annotation node. Usually this means inserting a chart. Regarding
+     * the argument separator, see the Evaluate function.
      *
      * @param formula - annotation formula. For charts, the chart formula.
      * @param type - annotation type. Defaults to `treb-chart`.
      * @param rect - coordinates, or a range reference for layout.
+     *
+     * @param argument_separator - the argument separator to use when evaluating
+     * the function. defaults to current locale.
      */
-    InsertAnnotation(formula: string, type?: string, rect?: IRectangle | RangeReference): void;
+    InsertAnnotation(formula: string, type?: string, rect?: IRectangle | RangeReference, argument_separator?: ',' | ';'): void;
 
     /**
      * Insert an image. This method will open a file chooser and (if an image
@@ -545,9 +549,29 @@ export declare class EmbeddedSpreadsheet {
      * use sheet names when referring to cells, to avoid ambiguity. Otherwise
      * cell references will resolve to the active sheet.
      *
+     * By default, this function will evaluate the expression in the current
+     * locale, meaning it will use the current locale's decimal separator and
+     * argument separator.
+     *
+     * If you do not want that behavior, set the argument separator explicitly.
+     * That will force evaluation using either comma (,) or semicolon (;) as the
+     * argument separator.
+     *
+     * Decimal separator is implied by the argument separator. If you set the
+     * argument separator to comma, the decimal separator will be dot (.). If you
+     * set the argument separator to semicolon, the decimal separator will be
+     * comma (,). You cannot mix-and-match these characters.
+     *
+     * Since you may not know where the code is being executed at run-time,
+     * using consistent argument and decimal separators makes sense. However we
+     * are leaving the original behavior as default for backwards compatibility.
+     *
+     * @param expression - an expression in spreadsheet language
+     * @param argument_separator - comma or semicolon, or leave undefined to use current locale
+     *
      * @public
      */
-    Evaluate(expression: string): CellValue | CellValue[][];
+    Evaluate(expression: string, argument_separator?: ',' | ';'): CellValue | CellValue[][];
 
     /**
      * Returns the current selection, as a string address or range.
@@ -639,7 +663,8 @@ export declare class EmbeddedSpreadsheet {
     SetLink(address?: AddressReference, target?: string): void;
 
     /**
-     * Select a range.
+     * Select a range. This function will change sheets if your reference
+     * refers to a different sheet.
      *
      * @public
      */