@trebco/treb 22.8.0 → 22.13.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.13. 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
@@ -68,24 +68,6 @@ export interface GetRangeOptions {
     type?: 'formatted' | 'formula';
 }
 
-/**
- * options for the SetRange method
- */
-export interface SetRangeOptions {
-
-    /** transpose rectangular array before inserting */
-    transpose?: boolean;
-
-    /** recycle values (R-style) */
-    recycle?: boolean;
-
-    /** apply as an array (as if you pressed ctrl+shift+enter) */
-    array?: boolean;
-
-    /** spill over */
-    spill?: boolean;
-}
-
 /**
  * options for the ScrollTo method.
  *
@@ -203,13 +185,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 +531,12 @@ export declare class EmbeddedSpreadsheet {
      * use sheet names when referring to cells, to avoid ambiguity. Otherwise
      * cell references will resolve to the active sheet.
      *
+     * @param expression - an expression in spreadsheet language
+     * @param options - options for parsing the passed function
+     *
      * @public
      */
-    Evaluate(expression: string): CellValue | CellValue[][];
+    Evaluate(expression: string, options?: EvaluateOptions): CellValue | CellValue[][];
 
     /**
      * Returns the current selection, as a string address or range.
@@ -639,7 +628,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
      */
@@ -712,6 +702,45 @@ export interface SerializeOptions {
     shrink?: boolean;
 }
 
+/**
+ * options for the SetRange method
+ */
+export interface SetRangeOptions {
+
+    /** transpose rectangular array before inserting */
+    transpose?: boolean;
+
+    /** recycle values (R-style) */
+    recycle?: boolean;
+
+    /** apply as an array (as if you pressed ctrl+shift+enter) */
+    array?: boolean;
+
+    /** spill over */
+    spill?: boolean;
+
+    /**
+     * argument separator to use when parsing the input formula. by default,
+     * parsing uses the current locale. that is not optimal, because you
+     * do not necessarily know ahead of time where a spreadsheet may be viewed.
+     *
+     * set this option to call SetRange with a consistent argument separator.
+     * the decimal separator is implied; if the argument separator is set to
+     * comma (',') the decimal mark will be a dot ('.'); and if the argument
+     * separator is set to semicolon (';') the decimal mark will be set to
+     * comma (','). you cannot mix and match these values.
+     *
+     * @see EvaluateOptions for more discussion of this option.
+     */
+    argument_separator?: ',' | ';';
+
+    /**
+     * allow R1C1-style references; these can be either
+     * direct (e.g. R2C4) or offset (e.g. R[-3]C[0]).
+     */
+    r1c1?: boolean;
+}
+
 /**
  * Structure represents a cell address. Note that row and column are 0-based.
  */
@@ -1106,3 +1135,37 @@ export interface DocumentChangeEvent {
 export interface SelectionEvent {
     type: 'selection';
 }
+
+/**
+ * options for the evaluate function
+ */
+export interface EvaluateOptions {
+
+    /**
+     * By default, the Evaluate 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.
+     */
+    argument_separator?: ',' | ';';
+
+    /**
+     * allow R1C1-style references. the Evaluate function cannot use
+     * offset references (e.g. R[-1]C[0]), so those will always fail.
+     * however it may be useful to use direct R1C1 references (e.g. R3C4),
+     * so we optionally support that behind this flag.
+     */
+    r1c1?: boolean;
+}