ac39321fc5
* Tinymath is now a Kibana package * Rename to @kbn/tinymath * Update import style * Update README * Use commonjs import syntax * Fix to commonjs export * More commonjs fixes
72 lines
1.8 KiB
Markdown
72 lines
1.8 KiB
Markdown
# kbn-tinymath
|
|
|
|
kbn-tinymath is a tiny arithmetic and function evaluator for simple numbers and arrays. Named properties can be accessed from an optional scope parameter.
|
|
It's available as an expression function called `math` in Canvas, and the grammar/AST structure is available
|
|
for use by Kibana plugins that want to use math.
|
|
|
|
See [Function Documentation](/docs/functions.md) for details on built-in functions available in Tinymath.
|
|
|
|
```javascript
|
|
const { evaluate } = require('@kbn/tinymath');
|
|
|
|
// Simple math
|
|
evaluate('10 + 20'); // 30
|
|
evaluate('round(3.141592)') // 3
|
|
|
|
// Named properties
|
|
evaluate('foo + 20', {foo: 5}); // 25
|
|
|
|
// Arrays
|
|
evaluate('bar + 20', {bar: [1, 2, 3]}); // [21, 22, 23]
|
|
evaluate('bar + baz', {bar: [1, 2, 3], baz: [4, 5, 6]}); // [5, 7, 9]
|
|
evaluate('multiply(bar, baz) / 10', {bar: [1, 2, 3], baz: [4, 5, 6]}); // [0.4, 1, 1.8]
|
|
```
|
|
|
|
### Adding Functions
|
|
|
|
Functions can be injected, and built in function overwritten, via the 3rd argument to `evaluate`:
|
|
|
|
```javascript
|
|
const { evaluate } = require('@kbn/tinymath');
|
|
|
|
evaluate('plustwo(foo)', {foo: 5}, {
|
|
plustwo: function(a) {
|
|
return a + 2;
|
|
}
|
|
}); // 7
|
|
```
|
|
|
|
### Parsing
|
|
|
|
You can get to the parsed AST by importing `parse`
|
|
|
|
```javascript
|
|
const { parse } = require('@kbn/tinymath');
|
|
|
|
parse('1 + random()')
|
|
/*
|
|
{
|
|
"name": "add",
|
|
"args": [
|
|
1,
|
|
{
|
|
"name": "random",
|
|
"args": []
|
|
}
|
|
]
|
|
}
|
|
*/
|
|
```
|
|
|
|
#### Notes
|
|
|
|
* Floating point operations have the normal Javascript limitations
|
|
|
|
### Building kbn-tinymath
|
|
|
|
This package is rebuilt when running `yarn kbn bootstrap`, but can also be build directly
|
|
using `yarn build` from the `packages/kbn-tinymath` directory.
|
|
### Running tests
|
|
|
|
To test `@kbn/tinymath` from Kibana, run `yarn run jest --watch packages/kbn-tinymath` from
|
|
the top level of Kibana.
|