tidal.pegjs

tidal.pegjs is a parsing expression grammar for the TidalCycles pattern language, written using PEG.js. The goal of the PEG is to easily translate strings of Tidal patterns into annotated JavaScript data structures for use in sequencing. The project also provides a Pattern object that can be queried for events by passing start and ending times.

Usage

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 = Pattern( '[0 [1 2]*4 <5 6 7> 8]' )

// start at time 0 and query for 3 cycles
const events = p.query( 0, 3 )
// events now holds the query results, but we can also
// call p.print to pretty-print them to the JS console.

p.print()

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: 0 },
    { type: 'number', value: 1 },
    { type: 'number', value: 2 },
  ],
  type: '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:0,
    arc: { start: Fraction(0), end:Fraction(1,3) }
  },
  {
    value:1,
    arc: { start: Fraction(1,3), end:Fraction(2,3) }
  },
  {
    value:2,
    arc: { start: Fraction(2,3), end:Fraction(1) }
  }
]

Rational numbers are provided by the fraction.js library.

Development

Installing dependencies

To install all dependencies run npm install

Using Gulp

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:

  • Run gulp build

  • Pass any Tidal pattern to the parse function as:

  const parser = require( './dist/peg-parse.js' ); // Modify path to this file if necessary
  
  parser.parse(' 1 2 3 ')

  The peg-parse.js file can be required as a module in Node.js or in the browser using browserify, etc.

  For more instructions on compiling parsers, see https://pegjs.org/documentation#generating-a-parser-javascript-api.

• Run the mocha tests: gulp test

• Watch for changes in any file or tests and run tests automatically whenever this happens: gulp watch

• Clean everything that was generated with gulp from the dist folder: gulp clean

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.

Installing dependencies

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.

For more instructions on compiling parsers, see https://pegjs.org/documentation#generating-a-parser-javascript-api.

Testing

Tests are done with Mocha, you'll need to have it installed globally. You should also have peg.js installed locally: npm install pegjs

Then run mocha from the top-level directory to run the parsing tests.

Issues

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.

Credits

This library is developed by Charlie Roberts and Mariana Pachon Puentes.