nearley.js2.0.0

Parsers turn strings of characters into meaningful data structures (like a JSON object!). nearley is a fast, feature-rich, and modern parser toolkit for JavaScript. nearley is an npm Staff Pick.

nearley 101

1. Install: $ npm install -g nearley
2. Write your grammar:

   # Match a CSS color
   # http://www.w3.org/TR/css3-color/#colorunits
   
   @builtin "whitespace.ne" # `_` means arbitrary amount of whitespace
   @builtin "number.ne"     # `int`, `decimal`, and `percentage` number primitives
   
   csscolor -> "#" hexdigit hexdigit hexdigit hexdigit hexdigit hexdigit
             | "#" hexdigit hexdigit hexdigit
             | "rgb"  _ "(" _ colnum _ "," _ colnum _ "," _ colnum _ ")"
             | "hsl"  _ "(" _ colnum _ "," _ colnum _ "," _ colnum _ ")"
             | "rgba" _ "(" _ colnum _ "," _ colnum _ "," _ colnum _ "," _ decimal _ ")"
             | "hsla" _ "(" _ colnum _ "," _ colnum _ "," _ colnum _ "," _ decimal _ ")"
   
   hexdigit -> [a-fA-F0-9]
   colnum   -> int | percentage
   

3. Compile your grammar:

   $ nearleyc csscolor.ne -o csscolor.js

4. Test your grammar:

   $ nearley-test -i "#00ff00" csscolor.js
   Parse results: 
   [ [ '#', [ '0' ], [ '0' ], [ 'f' ], [ 'f' ], [ '0' ], [ '0' ] ] ]
   

5. Turn your grammar into a generator:

   $ nearley-unparse -n 3 csscolor.js
   #Ab21F2
   rgb  ( -29.889%,7,8172)
   #a40
   

6. You try it! Type a CSS color here:

   …and the parsed output will appear here!
   

7. Create beautiful railroad diagrams to document your grammar formally.

   $ nearley-railroad csscolor.ne -o csscolor.html

   Output looks like:
   

   See a bigger example here.

Features

• nearley is the first JS parser to use the Earley algorithm (insert your own ‘early bird’ pun here). It lives happily in node, but doesn't mind the browser.
• nearley outputs small files. And its expressive DSL comes with plenty of syntactic sugar to keep your source files short. And sweet.
• nearley's grammar language is powerful and expressive: you can use macros, import from a large builtin library of pre-defined parser-pieces, and more.
• nearley is built on an idiomatic streaming API. You even have access to partial parses to build predictive user interfaces.
• nearley processes left recursion without choking. In fact, nearley will parse anything you throw at it without complaining or going into a sulk infinite loop.
• nearley handles ambiguous grammars gracefully. Ambiguous grammars can be parsed in multiple ways: instead of getting confused, nearley gives you all the parsings (in a deterministic order!).
• nearley allows for debugging with generous error detection. When it catches a parse-time error, nearley tells you what went wrong and where.
• nearley is powerful enough to be bootstrapped. That means nearley uses nearley to compile parts of nearley. nearleyception!
• nearley parsers can be inverted to form generators which output random strings that match a grammar. Useful for writing test cases, fuzzers, and Mad-Libs.
  

Projects using nearley

• Shrdlite is a programming project in Artificial Intelligence, a course given at the University of Gothenburg and Chalmers University of Technology. It uses nearley for reading instructions in natural language (i.e. English).
• node-dmi is a module that reads iconstate metadata from BYOND DMI files.
• uPresent is a markdown-based presentation authoring system.
• Carbon is a C subset that compiles to JavaScript, optimized for game development.
• Packdown is a tool to generate human-readable archives of multiple files.
• Hexant is a cellular automata simulator with a DSL for custom automata.
• Dicetower is an advanced dice plugin for hubot.
• Truth-table is a tool to visualize propositional logic in truth tables.
• nearley is a parser toolkit for JavaScript. It has a nearley-based DSL to specify parsers.

Excited? Get started on Github, visit us on npm, or play with the calculator demo for more action.