Pattern object that can be queried for events by passing start and ending times.
The easiest way to use this is by including the
dist/pattern.js file in your HTML; this will provide a global
Pattern object. To then process and query a pattern string:
const p =// start at time 0 and query for 3 cyclesconst events = p// events now holds the query results, but we can also// call p.print to pretty-print them to the JS console.p
There are single-file HTML examples in the
demos folder for reference.
Parsing vs. Querying
Before querying a Tidal pattern for individual events, the pattern must be parsed; this is the functionality that the parsing expression grammar provides. Once parsed, we have a data structure describing the pattern. For example, given the pattern
0 1 2 the PEG generates"
values:type: 'number' value: 0type: 'number' value: 1type: 'number' value: 2type: 'group'
Once we have this data structure, we can then query the data for events. If we use the parsed data aboveand query it for one cycle of events, we get:
value:0arc: start: end:value:1arc: start: end:value:2arc: start: end:
Rational numbers are provided by the fraction.js library.
To install all dependencies run
All files generated by using Gulp will be located in the
dist folder. It is all you will need to use the files as modules to parse and flatten Tidal patterns.
If you want to modify any of the files you can run
gulp watch in the background which will re-compile and run the tests automatically every time there is any modification in any of the files.
Compile the parser into a js module:
const parser = ; // Modify path to this file if necessaryparser
Pass any Tidal pattern to the parse function as:
peg-parse.jsfile can be required as a module in Node.js or in the browser using browserify, etc.
Run the mocha tests:
Watch for changes in any file or tests and run tests automatically whenever this happens:
Clean everything that was generated with gulp from the dist folder:
Without using Gulp
It's recommended to use Gulp since the tasks are clearly defined and the resulting files in the
dist folder are pretty much all you need, but here are instructions to work without it as well.
We haven't done any work making this tidy yet, but will try to do so soon. For now, installing the dependencies can be done with:
npm install pegjs -g
For testing you'll also need
npm install mocha -g
Compiling the parser
To compile the parser into a JS module, use
pegjs tidal.pegjs in the top-level directory of this repo. This will create a file named
tidal.js that can be required as a module in Node.js or in the browser using browserify etc.
To compile the parser as a global variable:
pegjs --format globals --export-var Tidal tidal.pegjs.
Tests are done with Mocha, you'll need to have it installed globally. You should also have peg.js installed locally:
npm install pegjs
mocha from the top-level directory to run the parsing tests.
There are still some issues with this project, which can be found in the
TODO.md file. If you see anything else and fix it feel free to create pull requests.
More about PEGs and musical programming languages
Graham Wakefield and Charlie Roberts ran a workshop on using PEGs to create musical programming languages; check it out for more about how PEGs work and tutorials on creating your own mini-languages.
This library is developed by Charlie Roberts and Mariana Pachon Puentes.