@qrvey/formula-lang

Qrvey Formula Language

Usage

Transpile function

import { ENGINES, Transpile } from "@qrvey/formula-lang";

const program = "MID(MID(\"This is a test\", 1, 5), 1, 2)"
const transpiled = Transpile(program, ENGINES.ELASTICSEARCH)
console.log(transpiled)

the output will be

'This is a test'.substring(1, 5).substring(1, 2)

TranspileAST function

import { ENGINES, TranspileAST } from "@qrvey/formula-lang";

const ast = {
    "type": "Program",
    "exp": "1 + 2",
    "lang": "QrveyLang",
    "version": "0.0.0",
    "body": {
        "operator": "+",
        "type": "BinaryExpression",
        "left": {
            "type": "Literal",
            "dataType": "number",
            "value": 1
        },
        "right": {
            "type": "Literal",
            "dataType": "number",
            "value": 2
        }
    }
}
const transpiled = TranspileAST(ast, ENGINES.ELASTICSEARCH)
console.log(transpiled)

the output will be

(1 + 2)

codemirror editor

import { EditorState } from "@codemirror/state";
import { basicSetup } from "codemirror";
import { FormulaHighlight, calculateAST } from "@qrvey/formula-lang"

// set the editor state with the QFormula plugin. This adds the support for 
this._state = EditorState.create({
    doc: 'Test formula',
    extensions: [
    basicSetup,
    FormulaHighlight(),
    ...
    ]
})

// On every edit update you can calculate the AST
private dispatchTextUpdate(state: EditorState) {
    const tree = (state as any).tree;
    const text = ((state.doc as any).text as Array<string>).join('\n');
    const ast = calculateAST(text, tree.topNode);
    // dispatch event after return
    return { text, ast }
}

How create a context

The context is a object where implementor can build the information required for the transpiler. For example, the columns that will be used in the formula.

The properties needed are:

1. useSampleData: (Boolean) If you want to overwrite columns/externalFormulas by custom data, enable this flag. Default: false
2. sampleData: Optional (Object) Object to overwrite columns for custom data. Key represent the ID of the column, Value represent the replacement. See: __tests__/__mocks__/context.ts > testContext
3. timezone: Optional (Object). { offset: 'String' } Set the timezone offset in String format.
4. currentFormulaId: Optional (String): ID of the current formula if you are edited one. This flag help to avoid any Circular Dependency when edit one formula, to avoid call itself
5. model: Optional (Object)
   1. label: (String): Visualization
   2. id: (String): ID of item (Column)
   3. replacement: Optional (String): The ID will be replaced by this value.
   4. type: (AST_PRIMITIVES) Native type
   5. isExternalFormula: Optional (Boolean): If the item is a Formula created by this Package, need to set this flag in true

Use this Interfaces and Constants to build a Context

import { FormulaContext, AST_PRIMITIVES } from '"@qrvey/formula-lang"';

How create clean the context

In some scenarios will be necessary to clean the Context, for example: Delete columns that will cause Circular Dependencies. This package have a utility call: cleanInvalidItemsInContext for that

import { cleanInvalidItemsInContext } from "@qrvey/formula-lang";
const cleanContext = cleanInvalidItemsInContext(dirtyContext);