Lib.rs

AST and parser for Kailua.

Kailua parses a single source file in this order:

1. The file contents are read into kailua_env::Source in the caller-dependent manner. This step is flexible enough that the caller is free to make the contents up. Source emits a single span for the entire file.

2. The lexer (kailua_syntax::lex::Lexer) receives the span and Source and yields a list of tokens (kailua_syntax::lex::Tok) with the associated span.

   Tokens produced by the lexer include ordinary Lua tokens, Kailua-specific meta comments (e.g. --# = DashDashHash), newlines at the end of meta comments, normal comments and the end of file. Therefore they are sufficient for highlighting any Lua or Kailua code.

   Later steps rely on Kailua-specific tokens to produce Kailua-specific AST nodes. Care should be taken when tokens are generated by the other means.

3. The nesting analyzer (kailua_syntax::lex::Nest) adds additional informations to the spanned tokens so that the parser can recover from errors.

   The "nesting" is roughly a range of tokens that should be skipped on a parsing error. The nesting can be, well, nested and roughly gives an outline of the source code.

   The resulting tokens with nesting informations (kailua_syntax::lex::NestedToken) have no actual information about the nesting. Instead, the compact data to distinguish different nestings are calculated and recorded.

4. The parser (kailua_syntax::Parser) converts a series of tokens with nesting informations into the chunk (kailua_syntax::ast::Chunk).

   The chunk also contains a list of spanned scopes, names in each scope, globally assigned names and additional hints for each token. This allows for basic analyses without even touching the type checker.