@fileverse-dev/formula-parser/README.md

Formula parser

:warning: This repository is deprecated. We've released new and improved [HyperFormula](https://github.com/handsontable/hyperformula/) engine.

<details>

# Formula Parser [![Build Status](https://travis-ci.org/handsontable/formula-parser.png?branch=master)](https://travis-ci.org/handsontable/formula-parser) [![Test Coverage](https://codeclimate.com/github/handsontable/formula-parser/badges/coverage.svg)](https://codeclimate.com/github/handsontable/formula-parser/coverage) [![hot-formula-parser](https://img.shields.io/npm/v/hot-formula-parser.svg)](https://www.npmjs.com/package/hot-formula-parser)

Library provides a `Parser` class that evaluates excel and mathematical formulas.

---

## Install

A recommended way to install Formula Parser is through [NPM](https://www.npmjs.com/) using the following command:

```sh
$ npm install hot-formula-parser --save
```

Node.js:

```js
var FormulaParser = require("hot-formula-parser").Parser;
var parser = new FormulaParser();

parser.parse("SUM(1, 6, 7)"); // It returns `Object {error: null, result: 14}`
```

Browser:

```html
<script src="/node_modules/hot-formula-parser/dist/formula-parser.min.js"></script>
<script>
  var parser = new formulaParser.Parser();

  parser.parse("SUM(1, 6, 7)"); // It returns `Object {error: null, result: 14}`
</script>
```

## Features

It supports:

- Any numbers, negative and positive as float or integer;
- Arithmetic operations like `+`, `-`, `/`, `*`, `%`, `^`;
- Logical operations like `AND()`, `OR()`, `NOT()`, `XOR()`;
- Comparison operations like `=`, `>`, `>=`, `<`, `<=`, `<>`;
- All JavaScript Math constants like `PI()`, `E()`, `LN10()`, `LN2()`, `LOG10E()`, `LOG2E()`, `SQRT1_2()`, `SQRT2()`;
- String operations like `&` (concatenation eq. `parser.parse('-(2&5)');` will return `-25`);
- All excel formulas defined in [formula.js](https://github.com/handsontable/formula.js);
- Relative and absolute cell coordinates like `A1`, `$A1`, `A$1`, `$A$1`;
- Build-in variables like `TRUE`, `FALSE`, `NULL`
- Custom variables;
- Custom functions/formulas;
- Node and Browser environment.

## API (methods)

```js
var parser = new formulaParser.Parser();
```

### .parse(expression)

Parses and evaluates provided expression. It always returns an object with `result` and `error` properties. `result` property
always keep evaluated value. If error occurs `error` property will be set as:

- `#ERROR!` General error;
- `#DIV/0!` Divide by zero error;
- `#NAME?` Not recognised function name or variable name;
- `#N/A` Indicates that a value is not available to a formula;
- `#NUM!` Occurs when formula encounters an invalid number;
- `#VALUE!` Occurs when one of formula arguments is of the wrong type.

```js
parser.parse("(1 + 5 + (5 * 10)) / 10"); // returns `Object {error: null, result: 5.6}`
parser.parse("SUM(MY_VAR)"); // returns `Object {error: "#NAME?", result: null}`
parser.parse("1;;1"); // returns `Object {error: "#ERROR!", result: null}`
```

### .setVariable(name, value)

Set predefined variable name which can be visible while parsing formula expression.

```js
parser.setVariable("MY_VARIABLE", 5);
parser.setVariable("fooBar", 10);

parser.parse("(1 + MY_VARIABLE + (5 * fooBar)) / fooBar"); // returns `5.6`
```

### .getVariable(name)

Get variable name.

```js
parser.setVariable("fooBar", 10);

parser.getVariable("fooBar"); // returns `10`
```

### .setFunction(name, fn)

Set custom function which can be visible while parsing formula expression.

```js
parser.setFunction("ADD_5", function (params) {
  return params[0] + 5;
});
parser.setFunction("GET_LETTER", function (params) {
  var string = params[0];
  var index = params[1] - 1;

  return string.charAt(index);
});

parser.parse("SUM(4, ADD_5(1))"); // returns `10`
parser.parse('GET_LETTER("Some string", 3)'); // returns `m`
```

### .getFunction(name)

Get custom function.

```js
parser.setFunction("ADD_5", function (params) {
  return params[0] + 5;
});

parser.getFunction("ADD_5")([1]); // returns `6`
```

### .SUPPORTED_FORMULAS

List of all supported formulas function.

```js
require("hot-formula-parser").SUPPORTED_FORMULAS; // An array of formula names
```

## API (hooks)

### 'callVariable' (name, done)

Fired while retrieving variable. If variable was defined earlier using `setVariable` you can overwrite it by this hook.

```js
parser.on("callVariable", function (name, done) {
  if (name === "foo") {
    done(Math.PI / 2);
  }
});

parser.parse("SUM(SIN(foo), COS(foo))"); // returns `1`
```

### 'callFunction' (name, params, done)

Fired while calling function. If function was defined earlier using `setFunction` you can overwrite it's result by this hook.
You can also use this to override result of build-in formulas.

```js
parser.on("callFunction", function (name, params, done) {
  if (name === "ADD_5") {
    done(params[0] + 5);
  }
});

parser.parse("ADD_5(3)"); // returns `8`
```

### 'callCellValue' (cellCoord, done)

Fired while retrieving cell value by its label (eq: `B3`, `B$3`, `B$3`, `$B$3`).

```js
parser.on("callCellValue", function (cellCoord, done) {
  // using label
  if (cellCoord.label === "B$6") {
    done("hello");
  }
  // or using indexes
  if (
    cellCoord.row.index === 5 &&
    cellCoord.row.isAbsolute &&
    cellCoord.column.index === 1 &&
    !cellCoord.column.isAbsolute
  ) {
    done("hello");
  }

  if (cellCoord.label === "C6") {
    done(0.75);
  }
});

parser.parse("B$6"); // returns `"hello"`
parser.parse('B$6&" world"'); // returns `"hello world"`
parser.parse("FISHER(C6)"); // returns `0.9729550745276566`
```

### 'callRangeValue' (startCellCoord, endCellCoord, done)

Fired while retrieving cells range value (eq: `A1:B3`, `$A1:B$3`, `A$1:B$3`, `$A$1:$B$3`).

```js
parser.on("callRangeValue", function (startCellCoord, endCellCoord, done) {
  var data = [
    [1, 2, 3, 4, 5],
    [6, 7, 8, 9, 10],
    [11, 12, 13, 14, 15],
    [16, 17, 18, 19, 20],
  ];
  var fragment = [];

  for (
    var row = startCellCoord.row.index;
    row <= endCellCoord.row.index;
    row++
  ) {
    var rowData = data[row];
    var colFragment = [];

    for (
      var col = startCellCoord.column.index;
      col <= endCellCoord.column.index;
      col++
    ) {
      colFragment.push(rowData[col]);
    }
    fragment.push(colFragment);
  }

  if (fragment) {
    done(fragment);
  }
});

parser.parse("JOIN(A1:E2)"); // returns `"1,2,3,4,5,6,7,8,9,10"`
parser.parse("COLUMNS(A1:E2)"); // returns `5`
parser.parse("ROWS(A1:E2)"); // returns `2`
parser.parse("COUNT(A1:E2)"); // returns `10`
parser.parse('COUNTIF(A1:E2, ">5")'); // returns `5`
```

### Want to help?

Please see [CONTRIBUTING.md](CONTRIBUTING.md).

### Changelog

To see the list of recent changes, see [Releases section](https://github.com/handsontable/formula-parser/releases).

### License

The MIT License (see the [LICENSE](https://github.com/handsontable/formula-parser/blob/master/LICENSE) file for the full text).

### Contact

You can contact us at hello@handsontable.com.

</details>