Canopy

0.4.1 verified Fri May 01 auth: no javascript maintenance

Canopy is a parser compiler for parsing expression grammars (PEG) targeting JavaScript, Java, Python, and Ruby. Version 0.4.1 is the latest stable release; the project appears to be in maintenance mode with no recent activity. It generates standalone parsers with no runtime dependencies, making it lightweight. Unlike PEG.js or Nearley, Canopy offers multi-language code generation from a single grammar file.

Common errors

error Cannot find module './parser.js' ↓

cause Output file not generated or wrong path.

fix

Run canopy grammar.peg --lang javascript --output parser.js to generate the parser.

error SyntaxError: Unexpected token ILLEGAL ↓

cause Grammar contains invalid PEG syntax or characters.

fix

Check grammar for non-ASCII characters or misplaced operators. Refer to PEG specification.

error ReferenceError: process is not defined ↓

cause Generated parser used in non-Node environment without browser polyfill.

fix

Use a bundler like Webpack or include a shim for process.env if needed. Alternatively, avoid using environment variable features.

Warnings

gotcha Generated parsers use strict mode and may fail with 'use strict' conflicts. ↓

fix Ensure your code is compatible with strict mode. Avoid using reserved words as node labels.

breaking Output format changes between versions; generated parsers from different Canopy versions may not be compatible. ↓

fix Regenerate parsers after upgrading Canopy to avoid silent failures.

gotcha Left recursion in grammars causes infinite loops or stack overflow. ↓

fix Rewrite left-recursive rules using iteration or right recursion. Canopy does not support left recursion.

deprecated Canopy does not generate ESM modules by default; output uses CommonJS in older versions. ↓

fix Use version 0.4 or later, or manually convert to ESM.

Install

npm install canopy

yarn add canopy

pnpm add canopy

Imports

default

wrong

const Parser = require('./path/to/generated-parser')

correct

import Parser from './path/to/generated-parser'

Generated parsers are ESM modules; use ES2015 import syntax.

parse

import Parser from './parser'; const result = Parser.parse('input');

The generated parser exports a parse function as the default export.

SyntaxTree
wrong
```
import { SyntaxTree } from './parser'
```
correct
```
import { SyntaxTree } from 'canopy'
```
SyntaxTree is a helper type from the main 'canopy' package, not from generated parsers.

Quickstart

Shows how to create a simple PEG grammar, compile it with Canopy CLI, and use the generated parser in JavaScript.

// Install canopy globally
// npm install -g canopy

// grammar.peg
/*
program <- expr+
expr <- number / '(' expr ')'
number <- [0-9]+
*/

// Compile to JavaScript
// canopy grammar.peg --lang javascript --output parser.js

// In app.js
import Parser from './parser.js'
const result = Parser.parse('(42)')
console.log(result)