Home

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.

Install: $ npm install -g nearley (or try nearley live in your browser here!)

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

Compile your grammar:
```
$ nearleyc csscolor.ne -o csscolor.js
```

Test your grammar:

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

Turn your grammar into a generator:

$ nearley-unparse -n 3 csscolor.js

#Ab21F2
rgb  ( -29.889%,7,8172)
#a40

You try it! Type a CSS color here:

…and the parsed output will appear here!

Create beautiful railroad diagrams to document your grammar formally. See a demo here.
```
$ nearley-railroad csscolor.ne -o csscolor.html
```

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.