Registry / serialization / pegjs-util

pegjs-util

JSON →
library2.0.2jsnpmunverified

pegjs-util is a utility library for the Peggy parser generator (formerly PEG.js), currently at stable version 2.0.2. It enhances Peggy's core `parse` function by injecting convenient utilities directly into grammar actions. The library provides three main features: Parser Tree Token Unrolling, which simplifies common patterns of extracting tokens from repeated grammar rule matches; Abstract Syntax Tree (AST) Node Generation, which assists in building structured ASTs directly within grammar rules; and improved, "cooked" Error Reporting, offering more user-friendly diagnostics than Peggy's default output. Releases appear to follow the development of Peggy itself, with the latest versions published as needed. It differentiates itself by streamlining common parser generator tasks, reducing boilerplate in `.peggy` grammar files, and providing a more robust parsing and error reporting experience.

serialization
npm install pegjs-util
github ↗package ↗
INSTALL
IMPORT
SIG · PEGJS-UTIL
P
pegjs-util
serializationjavascriptv2.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PEGUtil
✓ const PEGUtil = require('pegjs-util');
✗ import PEGUtil from 'pegjs-util';
pegjs-util is currently a CommonJS module (version 2.0.2); direct native ESM imports are not supported. Use CommonJS require syntax.
makeUnroll
✓ var unroll = options.util.makeUnroll(location, options);
✗ import { makeUnroll } from 'pegjs-util';
The `makeUnroll` function is not a direct export. It is provided to the grammar via the `options.util` object when `PEGUtil.parse` is used to run the parser.
makeAST
✓ var ast = options.util.makeAST(location, options);
✗ import { makeAST } from 'pegjs-util';
The `makeAST` function is not a direct export. It is provided to the grammar via the `options.util` object when `PEGUtil.parse` is used, and typically relies on a user-provided `makeAST` callback in the parse options.

Demonstrates how to use `pegjs-util` to parse a simple language, generate an Abstract Syntax Tree (AST) with `asty`, and benefit from enhanced error reporting. It shows the integration of `unroll` and `ast` helpers within a Peggy grammar, enabled by `PEGUtil.parse`.

const fs = require("fs"); const ASTY = require("asty"); // Companion library, install separately if needed const PEG = require("peggy"); const PEGUtil = require("pegjs-util"); const pegjsGrammar = ` { var unroll = options.util.makeUnroll(location, options); var ast = options.util.makeAST(location, options); } start = _ seq:id_seq _ { return ast("Sample").add(seq); } id_seq = id:id ids:(_ "," _ id)* { return ast("IdentifierSequence").add(unroll(id, ids, 3)); } id = id:$([a-zA-Z_][a-zA-Z0-9_]*) { return ast("Identifier").set("name", id); } _ "blank" = (co / ws)* co "comment" = "//" (![\r\n] .)* / "/*" (!"*/" .)* "*/" ws "whitespaces" = [ \t\r\n]+ `; const asty = new ASTY(); const parser = PEG.generate(pegjsGrammar); // Simulate input for parsing const sampleInputOk = "/* some ok input */\nfoo, bar, quux"; const sampleInputBad = "/* some bad input */\nfoo, bar, quux baz"; function parseInput(inputString, fileName) { console.log(`\n--- Parsing ${fileName || 'input'} ---`); const result = PEGUtil.parse(parser, inputString, { startRule: "start", makeAST: function (line, column, offset, args) { // This callback is what the 'ast' helper in the grammar calls return asty.create.apply(asty, args).pos(line, column, offset); } }); if (result.error !== null) { console.error("ERROR: Parsing Failure:\n" + PEGUtil.errorMessage(result.error, true).replace(/^/mg, "ERROR: ")); } else { console.log(result.ast.dump().replace(/\n$/, "")); } } // To run this code, ensure you have installed: // npm install peggy asty pegjs-util parseInput(sampleInputOk, "sample-input-ok.txt"); parseInput(sampleInputBad, "sample-input-bad.txt");
Debug
Known issues
gotchapegjs-util is published as a CommonJS module. It does not officially support native ES module (ESM) imports (e.g., `import PEGUtil from 'pegjs-util'`) in its current version (2.0.2). Users attempting ESM imports may encounter errors.
fix
Use `const PEGUtil = require('pegjs-util');` for importing the library in Node.js environments.
affects: <=2.0.2
gotchaThe `makeUnroll` and `makeAST` utilities are only injected into the grammar's `options.util` object when parsing via `PEGUtil.parse`. If you use Peggy's standard `PEG.parse` method directly, these utilities will be undefined within your grammar rules, leading to runtime errors like `options.util is undefined`.
fix
Always use `PEGUtil.parse(parser, input, options)` to leverage the utility features within your Peggy grammars.
affects: >=1.0.0
gotchaWhile `pegjs-util`'s examples extensively use `asty` for Abstract Syntax Tree (AST) generation, `asty` is not a direct runtime dependency of `pegjs-util`. Users who wish to utilize the AST generation features shown in the examples must explicitly install `asty` (i.e., `npm install asty`) in their project.
fix
If using the AST generation features as demonstrated, ensure `asty` is installed: `npm install asty`.
affects: >=1.0.0
breakingThe underlying parser generator transitioned from 'PEG.js' to 'Peggy'. While `pegjs-util` is compatible with 'Peggy', older projects or grammars specifically tied to 'PEG.js' (pre-1.0 versions) might require updates to `peggy` and potentially slight grammar adjustments.
fix
Ensure your project uses `peggy` (version 1.x or newer) and update `require('pegjs')` or `import 'pegjs'` statements to `require('peggy')` or `import 'peggy'` respectively. Consult Peggy's migration guide for details.
affects: >=2.0.0
Errors
Common errors & fixes
ERROR: Parsing Failure:\nERROR: line X (column Y): ...\nERROR: ---^\nERROR: Expected "Z" or end of input but "A" found.
The input string does not conform to the defined Peggy grammar, leading to a parsing error reported by pegjs-util's enhanced error handling.
fix
Examine the error message, specifically the expected tokens and the found character at the indicated line and column, and correct the input string or adjust the grammar definition.
TypeError: Cannot read properties of undefined (reading 'util')
This error occurs within a Peggy grammar action (e.g., when calling `options.util.makeUnroll` or `options.util.makeAST`) if the parser was not invoked using `PEGUtil.parse`. `PEGUtil.parse` is responsible for injecting the `util` object into the options passed to grammar actions.
fix
Ensure that your parser execution uses `PEGUtil.parse(parser, input, options)` instead of Peggy's direct `parser.parse(input, options)`.
ReferenceError: asty is not defined
This error typically occurs in the `makeAST` callback provided to `PEGUtil.parse` if the `asty` library is used within that callback but has not been properly imported or installed.
fix
Install the `asty` package (`npm install asty`) and ensure it is correctly imported (`const ASTY = require('asty');`) in the file where the `makeAST` callback is defined.
Upgrade
Version history
2.0.2latest on npm
Audit
Dependencies
peggyrequiredCore parser generator this library extends and integrates with.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/rse/pegjs-util ↗
packagehttps://www.npmjs.com/package/pegjs-util ↗