Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gajus/pianola
A declarative function composition and evaluation engine.
https://github.com/gajus/pianola
declarative evaluator pipe-operator
Last synced: about 1 month ago
JSON representation
A declarative function composition and evaluation engine.
- Host: GitHub
- URL: https://github.com/gajus/pianola
- Owner: gajus
- License: other
- Created: 2017-01-31T22:58:02.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-11-21T21:40:06.000Z (almost 5 years ago)
- Last Synced: 2024-10-05T13:48:24.853Z (about 2 months ago)
- Topics: declarative, evaluator, pipe-operator
- Language: JavaScript
- Size: 43 KB
- Stars: 20
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pianola
[](https://travis-ci.org/gajus/pianola)
[](https://coveralls.io/github/gajus/pianola)
[](https://www.npmjs.org/package/pianola)
[](https://github.com/gajus/canonical)
[](https://twitter.com/kuizinas)
A declarative function composition and evaluation engine.
* [Use cases](#use-cases)
* [Configuration](#configuration)
* [Subroutines](#subroutines)
* [Defining subroutines](#defining-subroutines)
* [Inline subroutines](#inline-subroutines)
* [Sentinels](#sentinels)
* [`FinalResultSentinel`](#finalresultsentinel)
* [Expression reference](#expression-reference)
* [The pipeline operator (`|`)](#the-pipeline-operator-)
* [The aggregate pipeline operator (`>|`)](#the-aggregate-pipeline-operator-)
* [Cookbook](#cookbook)
* [Map multiple results](#map-multiple-results)
* [Name results](#name-results)
* [Error handling](#error-handling)
* [Debugging](#debugging)
## Use cases
* [Surgeon](https://github.com/gajus/surgeon) uses Pianola to extract information from HTML documents using a declarative API.
## Configuration
|Name|Type|Description|Default value|
|---|---|---|---|
|`bindle`|`Object`|(optional) A user-defined object that is passed to every subroutine.|
|`handleResult`|[`ResultHandlerType`](./src/types.js)|(optional) A function invoked after each subroutine with the result of the current subroutine and the subject value used to execute the subroutine. Use this method to throw an error. Return |
|`subroutines`|[`$PropertyType`](./src/types.js)|User defined subroutines. See [subroutines](#subroutines).|N/A|
## Subroutines
A subroutine is a function used to advance the evaluator, e.g.
```js
x('foo | bar baz', 'qux');
```
In the above example, Pianola expression uses two subroutines: `foo` and `bar`.
* `foo` subroutine is invoked without values.
* `bar` subroutine is executed with 1 value ("baz").
Subroutines are executed in the order in which they are defined – the result of the last subroutine is passed on to the next one. The first subroutine receives the value used to start the evaluator.
Multiple subroutines can be written as an array. The following example is equivalent to the earlier example.
```js
x([
'foo',
'bar baz'
], 'qux');
```
> Note:
>
> These functions are called subroutines to emphasise the cross-platform nature of the declarative API.
### Defining subroutines
Subroutines are defined using the [`subroutines` configuration](#configuration).
A subroutine is a function. A subroutine function is invoked with the following parameters:
|Parameter name|
|---|
|Subject value, i.e. value used to start the evaluator or result of the parent subroutine.|
|An array of parameter values used in the expression.|
|Bindle. See [`subroutines` configuration](#configuration).|
Example:
```js
const x = pianola({
subroutines: {
mySubourtine: (subjectValue, [firstParameterValue, secondParameterValue]) => {
console.log(subjectValue, firstParameterValue, secondParameterValue);
return parseInt(subjectValue, 10) + 1;
}
}
});
x('mySubourtine foo bar | mySubourtine baz qux', 0);
```
The above example prints:
```
0 "foo" "bar"
1 "baz" "qux"
```
### Inline subroutines
Subroutines can be inlined by adding a function to the instructions array, e.g.
```js
x([
'foo',
'bar',
(subjectValue) => {
return subjectValue.toUpperCase();
},
], 'qux');
```
## Sentinels
### `FinalResultSentinel`
`FinalResultSentinel` is used to signal the final value, i.e. it will interrupt the routine and return the value used to construct an instance of `FinalResultSentinel`.
Example:
```js
import pianola, {
FinalResultSentinel
} from 'pianola';
const x = pianola({
subroutines: {
a: () => {
return new FinalResultSentinel(null);
},
b: () => {
throw new Error('This method is never invoked.');
}
}
});
x('a | b', 0);
```
## Expression reference
Pianola subroutines are described using expressions.
An expression is defined using the following pseudo-grammar:
```
subroutines ->
subroutines _ ">|" _ subroutine
| subroutines _ "|" _ subroutine
| subroutine
subroutine ->
subroutineName " " parameters
| subroutineName
subroutineName ->
[a-zA-Z0-9\-_]:+
parameters ->
parameters " " parameter
| parameter
```
Example:
```js
x('foo bar baz', 'qux');
```
In this example,
* Pianola expression evaluator (`x`) is invoked with `foo bar baz` expression and `qux` starting value.
* The expression tells the expression evaluator to run `foo` subroutine with parameter values "bar" and "baz".
* The expression evaluator runs `foo` subroutine with parameter values "bar" and "baz" and a subject value "qux".
Multiple subroutines can be combined using an array:
```js
x([
'foo bar baz',
'corge grault garply'
], 'qux');
```
In this example,
* Pianola expression evaluator (`x`) is invoked with two expressions (`foo bar baz` and `corge grault garply`).
* The first subroutine is executed with the subject value "qux".
* The second subroutine is executed with a value that is the result of the parent subroutine.
The result of the query is the result of the last subroutine.
Read [define subroutines](#define-subroutines) documentation for broader explanation of the role of the parameter values and the subject value.
### The pipeline operator (`|`)
Multiple subroutines can be combined using the pipeline operator (`|`).
The pipeline operator tells expression evaluator to pass the result of the previous subroutine to the next subroutine. If the subroutine on the left-hand side returns an array, then the receiving subroutine is called for every value in the array.
The following examples are equivalent:
```js
x([
'foo bar baz',
'qux quux quuz'
]);
x([
'foo bar baz | foo bar baz'
]);
x('foo bar baz | foo bar baz');
```
### The aggregate pipeline operator (`>|`)
Multiple subroutines can be combined using the aggregate pipeline operator (`>|`).
The pipeline operator tells expression evaluator to pass the result of the previous subroutine to the next subroutine. If the subroutine on the left-hand side returns an array, then the receiving subroutine is called with an array of values.
The following examples are equivalent:
```js
x('foo >| bar');
```
## Cookbook
Unless redefined, all examples assume the following initialisation:
```js
import pianola from 'pianola';
/**
* @param configuration {@see https://github.com/gajus/pianola#configuration}
*/
const x = pianola();
```
### Map multiple results
When a subroutine results multiple results, then the rest of the expression is evaluated for each of the result.
```js
const foo = () => {
return [
1,
2,
3
];
};
const bar = (value) => {
if (value === 1) {
return 'one';
}
if (value === 2) {
return 'two';
}
if (value === 3) {
return 'three';
}
};
const x = pianola({
subroutines: {
bar,
foo
}
});
x('foo | bar');
// [
// 'one',
// 'two',
// 'three'
// ]
```
### Name results
Use a [`QueryChildrenType`](./src/types.js) object (a plain object whose values are Pianola expressions) to name the results.
```js
const foo = (subjectValue, [name]) => {
return name;
};
const x = pianola({
subroutines: {
foo
}
});
x([
{
foo0: 'foo corge',
foo1: 'foo grault',
foo2: 'foo garply'
}
]);
// [
// {
// name: 'corge'
// },
// {
// name: 'grault'
// },
// {
// name: 'garply'
// }
// ]
```
## Error handling
Pianola throws the following errors to indicate a predictable error state. All Pianola errors can be imported. Use `instanceof` operator to determine the error type.
|Name|Description|
|---|---|
|`NotFoundError`|Used to indicate that a resource is not found, e.g. when a subroutine is not found.|
|`PianolaError`|A generic error. All other Pianola errors extend from `PianolaError`.|
## Logging
This package is using [`roarr`](https://www.npmjs.com/package/roarr) logger to log the program's state.
Export `ROARR_LOG=true` environment variable to enable log printing to stdout.
Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs.