README.md
1## jsparagus/js_parser: Generating a parser for JavaScript
2
3In this directory:
4
5* **esgrammar.pgen** A grammar for the mini-language the ECMAScript
6 standard uses to describe ES grammar.
7
8* **es.esgrammar** - The actual grammar for ECMAScript, in emu-grammar
9 format, extracted automatically from the spec.
10
11* **extract_es_grammar.py** - The script that creates *es.esgrammar*.
12
13* **es-simplified.esgrammar** - A hacked version of *es.esgrammar* that
14 jsparagus can actually handle.
15
16* **generate_js_parser_tables.py** - A script to generate a JS parser
17 based on *es-simplified.esgrammar*. Read on for instructions.
18
19
20## How to run it
21
22To generate a parser, follow these steps:
23
24```console
25$ cd ..
26$ make init
27$ make all
28```
29
30**Note:** The last step currently takes about 35 seconds to run on my
31laptop. jsparagus is slow.
32
33Once you're done, to see your parser run, try this:
34
35```console
36$ cd crates/driver
37$ cargo run --release
38```
39
40The build also produces a copy of the JS parser in Python.
41After `make all`, you can use `make jsdemo` to run that.
42
43
44### How simplified is "es-simplified"?
45
46Here are the differences between *es.esgrammar*, the actual ES grammar,
47and *es-simplified.esgrammar*, the simplified version that jsparagus can
48actually handle:
49
50* The four productions with [~Yield] and [~Await] conditions are dropped.
51 This means that `yield` and `await` do not match *IdentifierReference*
52 or *LabelIdentifier*. I think it's better to do that in the lexer.
53
54* Truncated lookahead.
55
56 `ValueError: unsupported: lookahead > 1 token, [['{'], ['function'], ['async', ('no-LineTerminator-here',), 'function'], ['class'], ['let', '[']]`
57
58* Delete a rule that uses `but not` since it's not implemented.
59
60 Identifier :
61 IdentifierName but not ReservedWord
62
63 Making sense of this rule in the context of an LR parser is an
64 interesting task; see issue #28.
65
66* Ban loops of the form `for (async of EXPR) STMT` by adjusting a
67 lookahead assertion. The grammar is not LR(1).
68