mercury-lang

🌕 Mercury Parser

This Package does not generate any sound or visuals. This package only parses Mercury code and returns a JSON formatted parse tree. This is used in the Mercury environment to translate the code to sound and visual objects. This is also used in the Mercury-Playground, a browser based lite version of the environment.

📟 Mercury?

Mercury is a minimal and human-readable language for the live coding of algorithmic electronic music.

🚀 Go to the full Mercury Project

👾 Or start sketching in the browser:

🙏 Support Mercury by becoming a Patron

💬 Join the Discord Community!

How to use this parser

• git clone and run npm install

• Open the mercury.ne file to view the grammar in the Nearley language including the moo tokenizer.

• Run npm run build

  • Generates the the grammar.js parser file
  • Generates a minified es5 browser version in /build
  • Generates the railroad graph

• Run a test with npm test and view result in /test/tree

Use via require

Install in node_modules

$ npm install mercury-lang

const Mercury = require('mercury-lang');

Import es5 version

const Mercury = require('mercury-lang/build/mercury.es5.min.js');

Include in html

Include latest or specific version of bundled minified es5 through url in index.html

<script src="https://unpkg.com/mercury-lang@1.0.0/build/mercury.es5.min.js"></script>

Use in a html <script> like so:

// entire package
const Mercury = MercuryParser;

Example

A small code file of Mercury below

// A small example for the Mercury parser
set tempo 140
set nonSetting 10

list myBeat euclidean(8 5 1)

new synth saw time(1/8) play(myBeat) name(s1)
	give s1 fx(reverb 0.9 7)

list notes random 16 0 12)

Input the code in the Mercury parser

const mercury = require('mercury-lang');
const code = fs.readFileSync('example.txt', 'utf-8');

const result = mercury(code);

The result is a JS object consisting of a parseTree...

console.log(result.parseTree);

{
	global: {
		tempo: [ 140 ],
		scale: [ 'chromatic', 'c' ],
		root: [ 'c' ],
		randomSeed: [ 0 ],
		highPass: [ 20000, 0 ],
		lowPass: [ 1, 0 ],
		silence: false
	},
	variables: { 
		myBeat: [
			0, 1, 0, 1,
			1, 0, 1, 1
		] 
	},
	objects: {
		s1: {
		object: 'synth',
		type: 'saw',
		functions: {
			group: [],
			time: [ '1/8' ],
			note: [ 0, 0 ],
			env: [ 5, 500 ],
			beat: [
			[
				0, 1, 0, 1,
				1, 0, 1, 1
			]
			],
			amp: [ 0.7 ],
			wave2: [ 'saw', 0 ],
			add_fx: [ [ 'reverb', 0.9, 7 ] ],
			name: [ 's1' ]
		}
		}
	},
	groups: { all: [ 's1' ] },
	print: [],
	comments: [ '// A small example for the Mercury parser' ]
}

... a syntaxTree...

console.log(result.syntaxTree);

{
	'@main': [
		{
		'@global': { '@comment': '// A small example for the Mercury parser' }
		},
		{
		'@object': {
			'@set': { '@functions': [ { '@number': 140 } ] }
		}
		},
		{
		'@list': {
			'@name': 'myBeat',
			'@params': {
			'@function': {
				'@name': 'euclidean',
				'@args': [ { '@number': 8 }, { '@number': 5 }, { '@number': 1 } ]
			}
			}
		}
		},
		{
		'@object': {
			'@new': {
			'@type': { '@identifier': 'saw' },
			'@functions': [
				{
				'@function': {
					'@name': 'time',
					'@args': [ { '@division': '1/8' } ]
				}
				},
				{
				'@function': {
					'@name': 'beat',
					'@args': [ { '@identifier': 'myBeat' } ]
				}
				},
				{
				'@function': {
					'@name': 'name',
					'@args': [ { '@identifier': 's1' } ]
				}
				}
			]
			}
		}
		},
		{
		'@object': {
			'@set': {
			'@functions': [
				{
				'@function': {
					'@name': 'add_fx',
					'@args': [
					{ '@identifier': 'reverb' },
					{ '@number': 0.9 },
					{ '@number': 7 }
					]
				}
				}
			]
			}
		}
		}
	]
}

an errors array with encountered syntax errors

"errors": [
    "Syntax error at line 9 col 19: Unexpected number: 16 at list notes random 16<-"
  ]

...and a warnings array with warnings that may cause issues

"warnings" : [
	"Warning: Unkown setting name: nonSetting"
]

NPM dependencies

• Nearley Parser Toolkit
• Moo! Tokenizer/Lexer Generator

License

The GNU GPL-v.3