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 (or try nearley live in your browser here!)
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 also implements Joop Leo's optimizations for right-recursion, making it effectively linear-time for LL(k) grammars.
• nearley 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, use a tokenizer for extra performance, 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 exactly 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.
  
• You can export nearley parsers as railroad diagrams, which provide easy-to-understand documentation of your grammar.

Projects using nearley

• Artificial Intelligence and NLP: 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).
• Standard formats: node-dmi is a module that reads iconstate metadata from BYOND DMI files, edtf.js is a parser for Extended Date Time Format, node-krl-parser is a KRL parser for node, bibliography is a BibTeX-to-HTML converter, biblatex-csl-converter converts between bibtex/CSL/JSON, scalpel parses CSS selectors, rfc5545-rrule helps parse iCalendar data.
• Templating and files: uPresent is a markdown-based presentation authoring system, saison is a minimal templating language, Packdown is a tool to generate human-readable archives of multiple files.
• Programming languages: Carbon is a C subset that compiles to JavaScript, optimized for game development, ezlang is a simple language, tlnccuwagnf is a fun general-purpose language, nanalang is a silly esoteric language, english is a less esoteric programming language, ecmaless is an easily-extensible language, hm-parser parses Haskell-like Hindley-Milner type signatures, kozily implements the Oz language, abstract-machine inspects execution models.
• Mathematics: Solvent is a powerful desktop calculator, Truth-table is a tool to visualize propositional logic in truth tables, Emunotes is a personal Wiki with inline graphing and computation.
• Domain-specific languages: Hexant is a cellular automata simulator with a DSL for custom automata, Dicetower is an advanced dice plugin for hubot, deck.zone is a language to create board games, in-seconds is a time calculator for music applications, website-spec is a tool for functional web testing, idyll is a markup language for data-driven documents, virtsecgroup provides virtual AWS security groups.
• Parsing libraries: 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, explore nearley in your browser on the playground, or try out the calculator demo for more action.