@qrvey/formula-lang/README.md

QFormula support for qrvey projects

# Qrvey Formula Language
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)


## Usage

### Transpile function
```js
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

```js
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
```js
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`
1. _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`
1. _timezone_: Optional (Object). `{ offset: 'String' }` Set the timezone offset in String format.
1. _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
1. _model_: Optional (Object)
    1. _label_: (String): Visualization 
    1. _id_: (String): ID of item (Column)
    1. _replacement_: Optional (String): The ID will be replaced by this value.
    1. _type_: (AST_PRIMITIVES) Native type
    1. _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**
```js
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

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

```