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

Use cases

• 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	(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<UserConfigurationType, 'subroutines'>	User defined subroutines. See subroutines.	N/A

Subroutines

A subroutine is a function used to advance the evaluator, e.g.

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.

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.

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:

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.

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:

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:

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:

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.

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:

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:

x('foo >| bar');
 

Cookbook

Unless redefined, all examples assume the following initialisation:

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.

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 object (a plain object whose values are Pianola expressions) to name the results.

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 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.