@barchart/chart-lib 2.330.1 → 2.331.0

chart-lib/barchart.chart.d.ts

@@ -2434,16 +2434,35 @@ declare module "@barchart/chart-lib" {
     /** A helper method to return a simplified structure of the chart. */
     function getChartOutline(definitionOrTemplate: string): IChartOutline;
 
-    /** Please consider this as an opaque structure. */
-    interface ExpressionInternalModel {}
+    /** An operator of an expression, including syntetic (internal) operators
+     * like 'sym', 'num' and 'grp'.
+     */
+    export type ExprOperator = "+" | "-" | "*" | "/" | "^" | "sym" | "num" | "grp";
+
+    /** A root node of the expression AST.
+     * You will rarely if ever need to look at or navigate this tree.
+     */
+    export interface ExprNode {
+        op: ExprOperator;
+        left: ExprNodeOrVal;
+        right: ExprNodeOrVal;
+    }
+
+    /** The only three possible values stored in an expression. */
+    export type ExprValue = string | number | null;
+
+    /** The expression AST tree is heterogenous, each node can be a value (a leaf)
+     * or a node pointing at other nodes.
+     */
+    export type ExprNodeOrVal = ExprNode | ExprValue;
 
     /** A structure representing a successful parse of an expression. */
     export interface ExpressionSuccess {
         /** The expression given to be parsed. */
         text: string;
-        /** An internal expression model, basically an AST of the expression. */
-        model: ExpressionInternalModel;
-        /** The same expression given on input but parsed and formatter - basically a cleaned up version of the expression with most whitespace thrown out. */
+        /** The (root of the) AST of the expression. */
+        model: ExprNode;
+        /** The same expression given on input but parsed and formatted - basically a cleaned up version of the expression with most whitespace thrown out. */
         clean: string;
         /** The list of symbols found while parsing the expression. */
         symbols: string[];
@@ -2460,18 +2479,40 @@ declare module "@barchart/chart-lib" {
     /** If you would like to parse expressions yourself (chart will do this automatically for you).
      * @param text The text of the expression. Syntax is described in detail on our documentation site.
      * @param useCache (`false` by default) If the parsing code should cache the expressions parsed.
-     * @returns Either a successful parse result @see ExpressionSuccess or a failed result @see ExpressionError
+     * @returns Either a successful parse result {@link ExpressionSuccess} or a failed result {@link ExpressionError}
      */
     function parseExpression(text: string, useCache?: boolean): ExpressionSuccess | ExpressionError;
 
     export type ValueProviderFunc = (symbol: string, field?: string) => number | null;
 
     /** If you would like to evaluate an expression yourself.
-     * @param model Same as @see model property of the @see ExpressionSuccess
+     * @param model The expression AST (see {@link ExprNode})
      * @param valueProvider A function which, given a symbol name, returns a price.
      * @returns The computed value of the expression.
      */
-    function evaluateExpression(model: ExpressionInternalModel, valueProvider: ValueProviderFunc): number;
+    function evaluateExpression(model: ExprNode, valueProvider: ValueProviderFunc): number;
+
+    /** Produces well-formatted string out of the expression AST
+     * @param model The expression AST (see {@link ExprNode})
+     * @returns Expression formatted as a string
+     */
+    function formatExpression(model: ExprNode): string;
+
+    /** Returns a list of symbols found in the expression AST
+     * @param model The expression AST (see {@link ExprNode})
+     * @returns Symbols as an array of strings
+     */
+    function getExpressionSymbols(model: ExprNode): string[];
+
+    export type StringReplacerFunc = (symbol: string) => string;
+
+    /** Replace symbols in an expression. The library will traverse the tree and call you back
+     * for each symbol name found, you may return the same name or a different one.
+     * @param model The expression AST (see {@link ExprNode})
+     * @param replacer A callback which performs the replacement
+     * @returns A new AST tree (see {@link ExprNode}) with the symbols replaced
+     */
+    function replaceExpressionSymbols(model: ExprNode, replacer: StringReplacerFunc): ExprNode;
 
     interface StudyMetaRange {
         min: number;
@@ -2845,6 +2886,9 @@ declare module "@barchart/chart-lib" {
         SnapshotDataFeed,
         parseExpression,
         evaluateExpression,
+        formatExpression,
+        getExpressionSymbols,
+        replaceExpressionSymbols,
         Topics,
         PubSub,
     };