@trebco/treb 29.6.2 → 29.8.1

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v29.6. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v29.8. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -389,7 +389,7 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      * grid stops broadcasting events for the duration of the function call,
      * and collects them instead. After the function call we update as necessary.
      */
-    Batch(func: () => void, paint?: boolean): Promise<void>;
+    Batch(func: () => void, paint?: boolean): void;
 
     /** set freeze area */
     Freeze(rows?: number, columns?: number): void;
@@ -781,7 +781,7 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      *
      * @public
      */
-    Recalculate(): Promise<void>;
+    Recalculate(): void;
 
     /**
      * Save document to local storage.
@@ -963,19 +963,18 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     Select(range?: RangeReference): void;
 
     /**
+     * override for paste method omits the data parameter.
+     */
+    Paste(target?: RangeReference, options?: PasteOptions): void;
+
+    /**
+     * standard paste method accepts data argument
      *
-     * @param target - the target to paste data into. this can be larger
-     * than the clipboard data, in which case values will be recycled in
-     * blocks. if the target is smaller than the source data, we will expand
-     * it.
-     *
-     * @param data - clipboard data to paste.
-     *
-     * @param style - optional paste style. default is to paste formulas and
-     * source formatting. paste options can be usef to paste values, values
-     * and number formats, or retain the target formatting.
+     * @param target
+     * @param data
+     * @param options
      */
-    Paste(target?: RangeReference, data?: ClipboardData | undefined, options?: PasteOptions): Promise<void>;
+    Paste(target?: RangeReference, data?: ClipboardData, options?: PasteOptions): void;
 
     /**
      * copy data. this method returns the copied data. it does not put it on
@@ -1034,50 +1033,6 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     Cancel(token: number): void;
 }
 
-/**
- * this is a structure for copy/paste data. clipboard data may include
- * relative formauls and resolved styles, so it's suitable for pasting into
- * other areas of the spreadsheet.
- */
-export interface ClipboardDataElement {
-
-    /** calculated cell value */
-    calculated: CellValue;
-
-    /** the actual cell value or formula */
-    value: CellValue;
-
-    /** cell style. this may include row/column styles from the copy source */
-    style?: CellStyle;
-}
-
-/** clipboard data is a 2d array */
-export type ClipboardData = ClipboardDataElement[][];
-
-/**
- * optional paste options. we can paste formulas or values, and we
- * can use the source style, target style, or just use the source
- * number formats.
- */
-export interface PasteOptions {
-
-    /**
-     * when clipboard data includes formulas, optionally paste calculated
-     * values instead of the original formulas. defaults to false.
-     */
-    values?: boolean;
-
-    /**
-     * when pasting data from the clipboard, we can copy formatting/style
-     * from the original data, or we can retain the target range formatting
-     * and just paste data. a third option allows pasting source number
-     * formats but dropping other style information.
-     *
-     * defaults to "source", meaning paste source styles.
-     */
-    formatting?: 'source' | 'target' | 'number-formats';
-}
-
 /**
  * options for saving files. we add the option for JSON formatting.
  */
@@ -1161,6 +1116,46 @@ export interface SheetScrollOptions {
  * function type used for filtering tables
  */
 export type TableFilterFunction = (value: CellValue, calculated_value: CellValue, style: CellStyle) => boolean;
+export interface FreezePane {
+    rows: number;
+    columns: number;
+}
+
+/**
+ * options for serializing data
+ */
+export interface SerializeOptions {
+
+    /** optimize for size */
+    optimize?: 'size' | 'speed';
+
+    /** include the rendered/calculated value in export */
+    rendered_values?: boolean;
+
+    /** translate colors to xlsx-friendly values */
+    export_colors?: boolean;
+
+    /** export cells that have no value, but have a border or background color */
+    decorated_cells?: boolean;
+
+    /** prune unused rows/columns */
+    shrink?: boolean;
+
+    /**
+     * include tables. tables will be serialized in the model, so we can
+     * drop them from cells. but you can leave them in if that's useful.
+     */
+    tables?: boolean;
+
+    /** share resources (images, for now) to prevent writing data URIs more than once */
+    share_resources?: boolean;
+
+    /**
+     * if a function has an export() handler, call that
+     */
+    export_functions?: boolean;
+}
+export type AnnotationType = 'treb-chart' | 'image' | 'textbox' | 'external';
 
 /**
  * Structure represents a 2d range of cells.
@@ -1302,6 +1297,10 @@ export interface Complex {
     real: number;
     imaginary: number;
 }
+
+/**
+ * dimensioned quantity: 3.2 m/s, 2kg, 5m, &c.
+ */
 export interface DimensionedQuantity {
     value: number;
     unit: string;
@@ -1384,46 +1383,53 @@ export interface EvaluateOptions {
      */
     r1c1?: boolean;
 }
-export interface FreezePane {
-    rows: number;
-    columns: number;
-}
+
+/** clipboard data is a 2d array */
+export type ClipboardData = ClipboardDataElement[][];
 
 /**
- * options for serializing data
+ * optional paste options. we can paste formulas or values, and we
+ * can use the source style, target style, or just use the source
+ * number formats.
  */
-export interface SerializeOptions {
-
-    /** optimize for size */
-    optimize?: 'size' | 'speed';
+export interface PasteOptions {
 
-    /** include the rendered/calculated value in export */
-    rendered_values?: boolean;
+    /**
+     * when clipboard data includes formulas, optionally paste calculated
+     * values instead of the original formulas. defaults to false.
+     */
+    values?: boolean;
 
-    /** translate colors to xlsx-friendly values */
-    export_colors?: boolean;
+    /**
+     * when pasting data from the clipboard, we can copy formatting/style
+     * from the original data, or we can retain the target range formatting
+     * and just paste data. a third option allows pasting source number
+     * formats but dropping other style information.
+     *
+     * defaults to "source", meaning paste source styles.
+     */
+    formatting?: 'source' | 'target' | 'number-formats';
+}
 
-    /** export cells that have no value, but have a border or background color */
-    decorated_cells?: boolean;
+/**
+ * this is a structure for copy/paste data. clipboard data may include
+ * relative formauls and resolved styles, so it's suitable for pasting into
+ * other areas of the spreadsheet.
+ */
+export interface ClipboardDataElement {
 
-    /** prune unused rows/columns */
-    shrink?: boolean;
+    /** calculated cell value */
+    calculated: CellValue;
 
-    /**
-     * include tables. tables will be serialized in the model, so we can
-     * drop them from cells. but you can leave them in if that's useful.
-     */
-    tables?: boolean;
+    /** the actual cell value or formula */
+    value: CellValue;
 
-    /** share resources (images, for now) to prevent writing data URIs more than once */
-    share_resources?: boolean;
+    /** cell style. this may include row/column styles from the copy source */
+    style?: CellStyle;
 
-    /**
-     * if a function has an export() handler, call that
-     */
-    export_functions?: boolean;
+    /** area. if this cell is part of an array, this is the array range */
+    area?: IArea;
 }
-export type AnnotationType = 'treb-chart' | 'image' | 'textbox' | 'external';
 export declare type BorderConstants = "none" | "all" | "outside" | "top" | "bottom" | "left" | "right";
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebco/treb",
-  "version": "29.6.2",
+  "version": "29.8.1",
   "license": "LGPL-3.0-or-later",
   "homepage": "https://treb.app",
   "repository": {

package/treb-base-types/src/cells.ts

@@ -1210,6 +1210,40 @@ export class Cells {
 
   }
 
+  /**
+   * yet another iterator, this one returns cell and address. 
+   * iterates all cells; does not create missing cells.
+   * 
+   * UPDATE: adding area parameter; not shrinking it (don't call w/ infinities)
+   */
+  public *IterateRC(area?: IArea) {
+
+    if (area) {
+      for (let row = area.start.row; row <= area.end.row; row++) {
+        const block = this.data[row];
+        if (block) {
+          for (let column = area.start.column; column <= area.end.column; column++) {
+            const cell = block[column];
+            if (cell) {
+              yield { cell, row, column };
+            }
+          }
+        }
+      }
+    }
+    else {
+      for (const [row, r] of this.data.entries()) {
+        if (r) {
+          for (const [column, cell] of r.entries()) {
+            if (cell) {
+              yield { cell, row, column };
+            }
+          }
+        }
+      }
+    }
+  }
+
   /**
    * replacement for old callback iterator. this is a composite 
    * of iterating all and iterating an area. I want to remove the

package/treb-base-types/src/evaluate-options.ts

@@ -1,4 +1,7 @@
 
+import type { ExpressionUnit } from 'treb-parser';
+import type { ICellAddress } from './area';
+
 /**
  * options for the evaluate function
  */
@@ -17,5 +20,23 @@ export interface EvaluateOptions {
    * so we optionally support that behind this flag.
    */
   r1c1?: boolean;
-  
+ 
+  /** 
+   * @internal
+   * 
+   * @privateRemarks
+   * in some cases we may call this method after parsing an expression.
+   * we don't need the evaluate method to parse it again.
+   */
+  preparsed?: ExpressionUnit;
+
+  /** 
+   * @internal
+   * 
+   * @privateRemarks
+   * we also might want to pass the address of the expression, if (or as if)
+   * it was originally in the spreadsheet.
+   */
+  address?: ICellAddress;
+
 }

package/treb-base-types/src/union.ts

@@ -105,15 +105,6 @@ export type UnionValue
     | ErrorUnion
     ;
 
-// common types
-
-/** 
- * this is a factory instead of a constant value to prevent any accidental pollution
- */
-// export const CreateUndefinedUnion = (): UnionValue => { 
-//  return { type: ValueType.undefined, value: undefined };
-//};
-
 /** 
  * shortcut, although this is wasteful 
  * 
@@ -136,8 +127,6 @@ export const Box = (value: unknown, type?: ValueType): UnionValue => {
   
 };
 
-// export type UnionOrArray = UnionValue|UnionValue[][];
-
 /**
  * box a complex value in a union, potentially switching to a real if
  * there's no imaginary component.

package/treb-base-types/src/value-type.ts

@@ -19,9 +19,6 @@
  * 
  */
 
-// split from cell for separate import, 
-// @see format-index.ts
-
 /**
  * Complex number type
  */
@@ -67,6 +64,9 @@ export const ComplexToString = (value: Complex): string => {
   }
 };
 
+/**
+ * dimensioned quantity: 3.2 m/s, 2kg, 5m, &c.
+ */
 export interface DimensionedQuantity {
   value: number;
   unit: string;

package/treb-calculator/src/calculator.ts

@@ -43,6 +43,7 @@ import { InformationFunctionLibrary } from './functions/information-functions';
 import { StatisticsFunctionLibrary, StatisticsFunctionAliases } from './functions/statistics-functions';
 import { ComplexFunctionLibrary } from './functions/complex-functions';
 import { MatrixFunctionLibrary } from './functions/matrix-functions';
+import { RegexFunctionLibrary } from './functions/regex-functions';
 
 import { Variance } from './functions/statistics-functions';
 
@@ -222,7 +223,7 @@ export class Calculator extends Graph {
       InformationFunctionLibrary, // etc
       ComplexFunctionLibrary,
       MatrixFunctionLibrary,
-
+      RegexFunctionLibrary,
       );
    
     // aliases
@@ -1589,45 +1590,54 @@ export class Calculator extends Graph {
   /** moved from embedded sheet */
   public Evaluate(expression: string, active_sheet?: Sheet, options: EvaluateOptions = {}, raw_result = false) {
     
-    // const current = this.parser.argument_separator;
-    // const r1c1_state = this.parser.flags.r1c1;
+    let parse_expression = options?.preparsed;
+
+    if (!parse_expression) {
 
-    this.parser.Save();
+      this.parser.Save();
 
-    if (options.argument_separator) {
-      if (options.argument_separator === ',') {
-        this.parser.SetLocaleSettings(DecimalMarkType.Period);
+      if (options.argument_separator) {
+        if (options.argument_separator === ',') {
+          this.parser.SetLocaleSettings(DecimalMarkType.Period);
+
+          // this.parser.argument_separator = ArgumentSeparatorType.Comma;
+          // this.parser.decimal_mark = DecimalMarkType.Period;
+        }
+        else {
+          this.parser.SetLocaleSettings(DecimalMarkType.Comma);
 
-        // this.parser.argument_separator = ArgumentSeparatorType.Comma;
-        // this.parser.decimal_mark = DecimalMarkType.Period;
+          // this.parser.argument_separator = ArgumentSeparatorType.Semicolon;
+          // this.parser.decimal_mark = DecimalMarkType.Comma;
+        }
       }
-      else {
-        this.parser.SetLocaleSettings(DecimalMarkType.Comma);
 
-        // this.parser.argument_separator = ArgumentSeparatorType.Semicolon;
-        // this.parser.decimal_mark = DecimalMarkType.Comma;
+      if (options.r1c1) {
+        this.parser.flags.r1c1 = options.r1c1;
       }
-    }
 
-    if (options.r1c1) {
-      this.parser.flags.r1c1 = options.r1c1;
-    }
+      const parse_result = this.parser.Parse(expression);
+
+      // reset
 
-    const parse_result = this.parser.Parse(expression);
+      // this.parser.argument_separator = current;
+      // this.parser.decimal_mark = (current === ArgumentSeparatorType.Comma) ? DecimalMarkType.Period : DecimalMarkType.Comma;
+      // this.parser.flags.r1c1 = r1c1_state;
 
-    // reset
+      this.parser.Restore();
 
-    // this.parser.argument_separator = current;
-    // this.parser.decimal_mark = (current === ArgumentSeparatorType.Comma) ? DecimalMarkType.Period : DecimalMarkType.Comma;
-    // this.parser.flags.r1c1 = r1c1_state;
+      parse_expression = parse_result.expression;
 
-    this.parser.Restore();
+      if (parse_result.error) {
+        throw new Error(parse_result.error);
+      }
+
+    }
 
     // OK
 
-    if (parse_result && parse_result.expression ){ 
+    if (parse_expression ){ 
 
-      this.parser.Walk(parse_result.expression, (unit) => {
+      this.parser.Walk(parse_expression, (unit) => {
         if (unit.type === 'address' || unit.type === 'range') {
 
           // don't allow offset references, even in R1C1
@@ -1648,7 +1658,7 @@ export class Calculator extends Graph {
       });
 
       // console.info({expression: parse_result.expression})
-      const result = this.CalculateExpression(parse_result.expression);
+      const result = this.CalculateExpression(parse_expression, options.address);
       if (raw_result) {
         return result;
       }
@@ -1664,10 +1674,6 @@ export class Calculator extends Graph {
 
     // or? (...)
 
-    if (parse_result.error) {
-      throw new Error(parse_result.error);
-    }
-
     throw new Error('invalid expression');
 
   }

package/treb-calculator/src/descriptors.ts

@@ -76,6 +76,8 @@ export interface ArgumentDescriptor {
    * 
    * if this flag is set in any argument descriptor in a function, we'll
    * apply arrays. that's done when the function is installed. 
+   * 
+   * FIXME: this should maybe be the default, and we have an !unroll flag
    */
   unroll?: boolean;