{"id":15146,"library":"nearley","title":"nearley Parser Toolkit","description":"nearley is a comprehensive parsing toolkit for JavaScript that enables developers to define and parse custom languages. It utilizes the Earley parsing algorithm, making it capable of handling any context-free grammar, including notoriously difficult cases like left recursion, which often trip up other parser generators like PEG.js or Jison. The current stable version is 2.20.1, with releases synchronized to Zenodo for academic citation. Key differentiators include its streaming capabilities, graceful error handling, support for ambiguous grammars by providing all possible parsings, and compatibility with various lexers (e.g., moo). It also provides a robust toolchain for testing, railroad diagrams, and fuzzers, and works seamlessly in both Node.js and browser environments.","status":"active","version":"2.20.1","language":"javascript","source_language":"en","source_url":"https://github.com/hardmath123/nearley","tags":["javascript","parser","parse","generator","compiler","compile","grammar","language"],"install":[{"cmd":"npm install nearley","lang":"bash","label":"npm"},{"cmd":"yarn add nearley","lang":"bash","label":"yarn"},{"cmd":"pnpm add nearley","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended lexer for tokenizing input before parsing.","package":"moo","optional":true}],"imports":[{"note":"Used to create a Grammar object from compiled rules. While CommonJS `require` works, `import` is preferred for modern projects.","wrong":"const Grammar = require('nearley').Grammar;","symbol":"Grammar","correct":"import { Grammar } from 'nearley';"},{"note":"The core Earley parser class. Instantiate with a compiled grammar to parse input.","wrong":"const Parser = require('nearley').Parser;","symbol":"Parser","correct":"import { Parser } from 'nearley';"},{"note":"nearleyc is primarily a command-line tool for compiling `.ne` grammar files into JavaScript modules. Direct programmatic import is less common for end-users, but possible if building tooling around nearley.","wrong":"import nearleyc from 'nearley/lib/compile';","symbol":"nearleyc","correct":"npx nearleyc mygrammar.ne -o mygrammar.js"}],"quickstart":{"code":"const nearley = require('nearley');\nconst fs = require('fs');\nconst path = require('path');\n\n// 1. Define your grammar in a .ne file or directly as a JS object\n// For this example, let's create a simple grammar dynamically\nconst grammarSource = `\n@{% function id(x) {return x[0];} %}\nstart -> expression:id\nexpression -> number:id (operation number):id* {% function(data) {\n  let result = data[0];\n  for (let i = 0; i < data[1].length; i++) {\n    const op = data[1][i][0];\n    const num = data[1][i][1];\n    if (op === '+') result += num;\n    if (op === '-') result -= num;\n  }\n  return result;\n} %}\nnumber -> [0-9]:+ {% function(data) { return parseInt(data.join('')); } %}\noperation -> '+' | '-'\n`;\n\n// In a real scenario, you'd compile this via CLI:\n// npx nearleyc mygrammar.ne -o mygrammar.js\n// Then load it: const grammar = require('./mygrammar.js');\n\n// For a quickstart, we'll compile it in-memory (requires nearley compiler)\nconst compile = require('nearley/lib/compile');\nconst generate = require('nearley/lib/generate');\nconst nearleyGrammar = require('nearley/lib/nearley-language-grammar');\n\nconst compiledGrammar = compile(nearley.Grammar.fromCompiled(nearleyGrammar), grammarSource);\nconst grammar = nearley.Grammar.fromCompiled(eval(generate(compiledGrammar, {}))); // Eval is risky, avoid in production\n\n// 2. Create a Parser instance\nconst parser = new nearley.Parser(grammar);\n\n// 3. Feed input to the parser\ntry {\n  parser.feed('10+20-5');\n  console.log('Parsed results:', parser.results); // Should output [25]\n  parser.feed('3*4'); // This will fail as '*' is not in grammar\n} catch (error) {\n  console.error('Parsing error:', error.message);\n}\n\n// Example of parsing another valid input\nconst parser2 = new nearley.Parser(grammar);\nparser2.feed('1+2+3-1');\nconsole.log('Another result:', parser2.results); // Should output [5]\n","lang":"javascript","description":"This quickstart defines a simple arithmetic grammar, compiles it dynamically (for demonstration), and then uses the nearley Parser to parse an input string and print the result. It also demonstrates error handling for invalid input."},"warnings":[{"fix":"Thoroughly test your lexer rules, often by integrating a separate lexer like 'moo' and inspecting its output. Use nearley's built-in `nearley-test` tool.","message":"When defining grammars, ensure all lexer rules (like string literals or regexes) are unambiguous and exhaustive to avoid parsing errors or unexpected tokenization. The grammar expects a continuous stream of tokens.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"If ambiguity is not desired, refine your grammar rules to be more specific or introduce precedence rules. The `nearley-test` tool can help visualize parse trees and identify ambiguities.","message":"nearley uses the Earley algorithm which can return multiple parse trees for ambiguous grammars. If your grammar is intentionally ambiguous, `parser.results` will be an array of all possible parses. If it's unintended, this indicates an issue in your grammar design.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"Run `npx nearleyc mygrammar.ne -o mygrammar.js` as part of your build process or development workflow. Then `require` or `import` the generated `.js` file.","message":"Grammars defined in `.ne` files must be pre-compiled into JavaScript using `nearleyc` before they can be used at runtime. Attempting to load a `.ne` file directly will result in a file loading error.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"Unset or appropriately manage `process.env.DEBUG` for production builds. Use `DEBUG=nearley:*` for more specific debugging control.","message":"The `process.env.DEBUG` environment variable can significantly change nearley's output, enabling detailed debugging logs. While useful for development, ensure it's not set in production environments to avoid performance overhead and verbose logging.","severity":"gotcha","affected_versions":">=2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review your input string and the corresponding grammar rules. Ensure your lexer is producing the expected tokens and that your grammar handles all possible sequences of these tokens. Use `nearley-test` for debugging.","cause":"The input stream contains a token that does not fit any of the defined grammar rules at the current parsing state.","error":"Error: nearley: unexpected token"},{"fix":"Carefully review your `.ne` file for syntax errors. The `nearleyc` compiler will often provide a more specific line number for the error.","cause":"The grammar definition file (`.ne`) is syntactically incomplete or malformed, often missing a closing brace, parenthesis, or statement terminator.","error":"Error: Could not parse Earley grammar: Unexpected EOF"},{"fix":"Ensure `nearley.Grammar.fromCompiled(myGrammar)` is correctly called with the output from your `.ne` file's compilation, and that `myGrammar` is indeed the object exported by the compiled grammar file.","cause":"This usually indicates that the `Parser` was initialized without a valid, compiled grammar object, or the grammar object itself is malformed.","error":"TypeError: Cannot read properties of undefined (reading 'length') at Parser.feed"}],"ecosystem":"npm"}