{"id":15390243,"url":"https://github.com/gajus/pianola","last_synced_at":"2025-04-15T21:27:23.046Z","repository":{"id":57323369,"uuid":"80570914","full_name":"gajus/pianola","owner":"gajus","description":"A declarative function composition and evaluation engine.","archived":false,"fork":false,"pushed_at":"2019-11-21T21:40:06.000Z","size":44,"stargazers_count":20,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-08T12:50:28.623Z","etag":null,"topics":["declarative","evaluator","pipe-operator"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gajus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-31T22:58:02.000Z","updated_at":"2023-09-18T17:14:57.000Z","dependencies_parsed_at":"2022-08-25T22:42:32.437Z","dependency_job_id":null,"html_url":"https://github.com/gajus/pianola","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fpianola","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fpianola/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fpianola/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fpianola/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gajus","download_url":"https://codeload.github.com/gajus/pianola/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233690486,"owners_count":18714783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["declarative","evaluator","pipe-operator"],"created_at":"2024-10-01T15:05:04.217Z","updated_at":"2025-01-13T04:12:45.945Z","avatar_url":"https://github.com/gajus.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pianola\n\n[![Travis build status](http://img.shields.io/travis/gajus/pianola/master.svg?style=flat-square)](https://travis-ci.org/gajus/pianola)\n[![Coveralls](https://img.shields.io/coveralls/gajus/pianola.svg?style=flat-square)](https://coveralls.io/github/gajus/pianola)\n[![NPM version](http://img.shields.io/npm/v/pianola.svg?style=flat-square)](https://www.npmjs.org/package/pianola)\n[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)\n[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social\u0026label=Follow)](https://twitter.com/kuizinas)\n\nA declarative function composition and evaluation engine.\n\n* [Use cases](#use-cases)\n* [Configuration](#configuration)\n* [Subroutines](#subroutines)\n  * [Defining subroutines](#defining-subroutines)\n  * [Inline subroutines](#inline-subroutines)\n* [Sentinels](#sentinels)\n  * [`FinalResultSentinel`](#finalresultsentinel)\n* [Expression reference](#expression-reference)\n  * [The pipeline operator (`|`)](#the-pipeline-operator-)\n  * [The aggregate pipeline operator (`\u003e|`)](#the-aggregate-pipeline-operator-)\n* [Cookbook](#cookbook)\n  * [Map multiple results](#map-multiple-results)\n  * [Name results](#name-results)\n* [Error handling](#error-handling)\n* [Debugging](#debugging)\n\n## Use cases\n\n* [Surgeon](https://github.com/gajus/surgeon) uses Pianola to extract information from HTML documents using a declarative API.\n\n## Configuration\n\n|Name|Type|Description|Default value|\n|---|---|---|---|\n|`bindle`|`Object`|(optional) A user-defined object that is passed to every subroutine.|\n|`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 |\n|`subroutines`|[`$PropertyType\u003cUserConfigurationType, 'subroutines'\u003e`](./src/types.js)|User defined subroutines. See [subroutines](#subroutines).|N/A|\n\n## Subroutines\n\nA subroutine is a function used to advance the evaluator, e.g.\n\n```js\nx('foo | bar baz', 'qux');\n\n```\n\nIn the above example, Pianola expression uses two subroutines: `foo` and `bar`.\n\n* `foo` subroutine is invoked without values.\n* `bar` subroutine is executed with 1 value (\"baz\").\n\nSubroutines 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.\n\nMultiple subroutines can be written as an array. The following example is equivalent to the earlier example.\n\n```js\nx([\n  'foo',\n  'bar baz'\n], 'qux');\n\n```\n\n\u003e Note:\n\u003e\n\u003e These functions are called subroutines to emphasise the cross-platform nature of the declarative API.\n\n### Defining subroutines\n\nSubroutines are defined using the [`subroutines` configuration](#configuration).\n\nA subroutine is a function. A subroutine function is invoked with the following parameters:\n\n|Parameter name|\n|---|\n|Subject value, i.e. value used to start the evaluator or result of the parent subroutine.|\n|An array of parameter values used in the expression.|\n|Bindle. See [`subroutines` configuration](#configuration).|\n\nExample:\n\n```js\nconst x = pianola({\n  subroutines: {\n    mySubourtine: (subjectValue, [firstParameterValue, secondParameterValue]) =\u003e {\n      console.log(subjectValue, firstParameterValue, secondParameterValue);\n\n      return parseInt(subjectValue, 10) + 1;\n    }\n  }\n});\n\nx('mySubourtine foo bar | mySubourtine baz qux', 0);\n\n```\n\nThe above example prints:\n\n```\n0 \"foo\" \"bar\"\n1 \"baz\" \"qux\"\n\n```\n\n### Inline subroutines\n\nSubroutines can be inlined by adding a function to the instructions array, e.g.\n\n```js\nx([\n  'foo',\n  'bar',\n  (subjectValue) =\u003e {\n    return subjectValue.toUpperCase();\n  },\n], 'qux');\n\n```\n\n## Sentinels\n\n### `FinalResultSentinel`\n\n`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`.\n\nExample:\n\n```js\nimport pianola, {\n  FinalResultSentinel\n} from 'pianola';\n\nconst x = pianola({\n  subroutines: {\n    a: () =\u003e {\n      return new FinalResultSentinel(null);\n    },\n    b: () =\u003e {\n      throw new Error('This method is never invoked.');\n    }\n  }\n});\n\nx('a | b', 0);\n\n```\n\n## Expression reference\n\nPianola subroutines are described using expressions.\n\nAn expression is defined using the following pseudo-grammar:\n\n```\nsubroutines -\u003e\n    subroutines _ \"\u003e|\" _ subroutine\n  | subroutines _ \"|\" _ subroutine\n  | subroutine\n\nsubroutine -\u003e\n    subroutineName \" \" parameters\n  | subroutineName\n\nsubroutineName -\u003e\n  [a-zA-Z0-9\\-_]:+\n\nparameters -\u003e\n    parameters \" \" parameter\n  | parameter\n\n```\n\nExample:\n\n```js\nx('foo bar baz', 'qux');\n\n```\n\nIn this example,\n\n* Pianola expression evaluator (`x`) is invoked with `foo bar baz` expression and `qux` starting value.\n* The expression tells the expression evaluator to run `foo` subroutine with parameter values \"bar\" and \"baz\".\n* The expression evaluator runs `foo` subroutine with parameter values \"bar\" and \"baz\" and a subject value \"qux\".\n\nMultiple subroutines can be combined using an array:\n\n```js\nx([\n  'foo bar baz',\n  'corge grault garply'\n], 'qux');\n\n```\n\nIn this example,\n\n* Pianola expression evaluator (`x`) is invoked with two expressions (`foo bar baz` and `corge grault garply`).\n* The first subroutine is executed with the subject value \"qux\".\n* The second subroutine is executed with a value that is the result of the parent subroutine.\n\nThe result of the query is the result of the last subroutine.\n\nRead [define subroutines](#define-subroutines) documentation for broader explanation of the role of the parameter values and the subject value.\n\n### The pipeline operator (`|`)\n\nMultiple subroutines can be combined using the pipeline operator (`|`).\n\nThe 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.\n\nThe following examples are equivalent:\n\n```js\nx([\n  'foo bar baz',\n  'qux quux quuz'\n]);\n\nx([\n  'foo bar baz | foo bar baz'\n]);\n\nx('foo bar baz | foo bar baz');\n\n```\n\n### The aggregate pipeline operator (`\u003e|`)\n\nMultiple subroutines can be combined using the aggregate pipeline operator (`\u003e|`).\n\nThe 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.\n\nThe following examples are equivalent:\n\n```js\nx('foo \u003e| bar');\n\n```\n\n## Cookbook\n\nUnless redefined, all examples assume the following initialisation:\n\n```js\nimport pianola from 'pianola';\n\n/**\n * @param configuration {@see https://github.com/gajus/pianola#configuration}\n */\nconst x = pianola();\n\n```\n\n### Map multiple results\n\nWhen a subroutine results multiple results, then the rest of the expression is evaluated for each of the result.\n\n```js\nconst foo = () =\u003e {\n  return [\n    1,\n    2,\n    3\n  ];\n};\n\nconst bar = (value) =\u003e {\n  if (value === 1) {\n    return 'one';\n  }\n\n  if (value === 2) {\n    return 'two';\n  }\n\n  if (value === 3) {\n    return 'three';\n  }\n};\n\nconst x = pianola({\n  subroutines: {\n    bar,\n    foo\n  }\n});\n\nx('foo | bar');\n\n// [\n//   'one',\n//   'two',\n//   'three'\n// ]\n\n```\n\n### Name results\n\nUse a [`QueryChildrenType`](./src/types.js) object (a plain object whose values are Pianola expressions) to name the results.\n\n```js\nconst foo = (subjectValue, [name]) =\u003e {\n  return name;\n};\n\nconst x = pianola({\n  subroutines: {\n    foo\n  }\n});\n\nx([\n  {\n    foo0: 'foo corge',\n    foo1: 'foo grault',\n    foo2: 'foo garply'\n  }\n]);\n\n// [\n//   {\n//     name: 'corge'\n//   },\n//   {\n//     name: 'grault'\n//   },\n//   {\n//     name: 'garply'\n//   }\n// ]\n\n```\n\n## Error handling\n\nPianola throws the following errors to indicate a predictable error state. All Pianola errors can be imported. Use `instanceof` operator to determine the error type.\n\n|Name|Description|\n|---|---|\n|`NotFoundError`|Used to indicate that a resource is not found, e.g. when a subroutine is not found.|\n|`PianolaError`|A generic error. All other Pianola errors extend from `PianolaError`.|\n\n## Logging\n\nThis package is using [`roarr`](https://www.npmjs.com/package/roarr) logger to log the program's state.\n\nExport `ROARR_LOG=true` environment variable to enable log printing to stdout.\n\nUse [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fpianola","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgajus%2Fpianola","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fpianola/lists"}