A declarative function composition and evaluation engine.
npm install pianola
A declarative function composition and evaluation engine.
* Use cases
* Configuration
* Subroutines
* Defining subroutines
* Inline subroutines
* Sentinels
* FinalResultSentinel
* Expression reference
* The pipeline operator (|)
* The aggregate pipeline operator (>|)
* Cookbook
* Map multiple results
* Name results
* Error handling
* Debugging
* Surgeon uses Pianola to extract information from HTML documents using a declarative API.
|Name|Type|Description|Default value|
|---|---|---|---|
|bindle|Object|(optional) A user-defined object that is passed to every subroutine.|
|handleResult|ResultHandlerType|(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|User defined subroutines. See subroutines.|N/A|
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.
Subroutines are defined using the subroutines 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.|
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"
`
Subroutines can be inlined by adding a function to the instructions array, e.g.
`js
x([
'foo',
'bar',
(subjectValue) => {
return subjectValue.toUpperCase();
},
], 'qux');
`
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);
`
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.foo
* The expression tells the expression evaluator to run subroutine with parameter values "bar" and "baz".foo
* The expression evaluator runs 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 documentation for broader explanation of the role of the parameter values and the subject value.
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');
`
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');
`
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();
`
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'
// ]
`
Use a QueryChildrenType 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'
// }
// ]
`
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.|
This package is using roarr logger to log the program's state.
Export ROARR_LOG=true environment variable to enable log printing to stdout.
Use roarr-cli` program to pretty-print the logs.