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
    rgb  ( -29.889%,7,8172)
  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
    See a demo here.


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, mangudai parses RMS scripts for Age of Empires II, tf-hcl parses and generates HCL config files, css-selector-inspector parses and tokenizes CSS3 selectors, node-scad-parser parses OpenSCAD 3D models, js-sql-parse parses SQL statements.

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, fbp-types provides typechecking primitives for flow-based systems, lp5562 is an assembler for the TI LP5562 LED driver, VSL is a Versatile Scripting Language, while-typescript is an implementation of the WHILE language.

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, react-equation parses and renders equations in React.

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, pianola allows declarative function composition, idyll is a markup language for data-driven documents, virtsecgroup provides virtual AWS security groups, deadfad is a hex editor that lets you specify structs, bishbosh helps you create command-line interfaces, syso codifies aspects of French legal contracts, siteswap parses Siteswap notation for juggling patterns, jsgrep provides syntactic grep for JavaScript, electro-grammar parses descriptions of electronic components like resistors and capacitors.

Parsing libraries: nearley is a parser toolkit for JavaScript. It has a nearley-based DSL to specify parsers.