src: some documentation on parser and model

[nit.git] / src / parser / README.md

diff --git a/src/parser/README.md b/src/parser/README.md
new file mode 100644 (file)
index 0000000..3595aa7
--- /dev/null
+++ b/src/parser/README.md
@@ -0,0 +1,42 @@
+Parser and AST for the Nit language
+
+The parser ans the AST are mostly used by all tools.
+
+The `parser` is the tool that transform source-files into abstract syntax trees (AST) (see `parser_nodes`)
+While the AST is a higher abstraction than blob of text, the AST is still limited and represents only *What the programmer says*.
+
+Classes of nodes of the AST starts with the letter `A` (for most things, eg. `AClassdef`) or `T` (for token eg. `TId`), there is no real reason except historical that might be solved with a new parser.
+
+Variable names of the AST usually starts with `n` (for node). This is also historical but some names with a `a` (to mimic the class name) remains.
+
+## SableCC
+
+Most files in this directory are generated from a grammar for sablecc3 ( http://www.sablecc.org ).
+In order to generate nit parser, you need the alternate SableCC3 generator ( http://www.mare.ee/indrek/sablecc/ ).
+
+## Contents
+
+* fact_parser.pl: Script used to factorize parser.nit
+* Makefile: Update grammar and generate .nit files
+* nit.sablecc3xx: Extended sablecc3 grammar (see prescc.pl)
+* prescc.pl: Program to transform an extended sablecc3 to a standard one
+* parser_nodes.nit: token and nodes classes hierarchy used by the parser and the lexer
+* tables.nit, tables_nit.h: Interfaces to access the tables needed by the parser and the lexer
+* xss/*.xss: alternate SableCC3 template files for the Nit language
+
+
+The following are generated but present to avoid the need of sablecc3:
+
+* lexer.nit: generated lexer
+* parser.nit: generated parser
+* parser_prod.nit: All production with generated visit methods
+* tables_nit.c: The tables needed by the parser and the lexer
+* parser_abs.nit: Raw generated token and nodes classes used to maintain coherence of parser_nodes.nit
+
+
+Other temp files produced by the Makefile:
+
+* .nit.sablecc3: Sablecc3 grammar after processing
+* .nit.sablecc3.dump: Dump of the grammar to improve sablecc3 multiple runs
+* .parser-nofact.nit: The parser generated by SableCC3 before factorization by fact_parser.pl
+