How lucassus/lucky-script works
Project Type & Purpose
• The project is a full-fledged interpreter for a custom programming language.
• It supports arithmetic operations, user-defined functions (including higher-order functions), control flow (if statements), recursion, lexical scoping, and dynamic scoping.
• It also includes a sandbox directory (lark-sandbox) which seems to experiment with grammar definitions (e.g., JSON, lucky_script) using Lark (a parsing framework), likely to validate or compare grammar definitions.
Identifying Main Components
• REPL: The entry point (src/repl.ts) that accepts user input and drives the process.
• Lexer: Responsible for tokenizing the input. Located under src/Lexer with clear submodules for recognizers (e.g., Comment, Identifier, Numeral) and associated tests.
• Parser: Located under src/Parser, it takes tokens from the Lexer and builds an Abstract Syntax Tree (AST). It includes utility files like Lookahead.
• Interpreter: Found in src/Interpreter, it executes the AST, uses a Symbol Table for managing scope, and processes language constructs like functions and closures.
• Object System: The Interpreter has subcomponents for various runtime objects, such as LuckyNumber, LuckyBoolean, LuckyFunction, and LuckyObject.
• Error Handling: Each component includes its own error modules (e.g., src/Interpreter/errors.ts, src/Parser/errors.ts, src/Lexer/errors.ts) to manage syntax, lexical, and runtime issues.
• Testing & CI: There are test files across the modules (using Jest) plus GitHub workflows (.github/workflows) for CI, ensuring quality.
Relationships & Flow
• Data Flow: Start with the REPL accepting source code → passes to Lexer for tokenization → Lexer outputs tokens to the Parser → Parser generates an AST → AST is fed to the Interpreter for execution.
• Error Propagation: At each stage (Lexer, Parser, Interpreter), if errors occur, they are caught by the respective error mechanisms and communicated (possibly with custom error messages) back to the REPL.
• Scope and Closure Handling: Highlight that the Symbol Table managed by the Interpreter supports dynamic scopes and closure properties, meaning variable bindings can change based on runtime environment.
Architectural Patterns & Technologies
• Layered Pipeline: A clear pipeline where each phase (Lexing, Parsing, Interpreting) is a distinct layer.
• Modularity: The separation into distinct directories (Lexer, Parser, Interpreter) showcases a modular approach.
• Test-Driven Structure: Numerous test files in each module indicate a strong focus on unit testing.
• Use of TypeScript and Node.js with yarn and ts-node to facilitate rapid development and easy execution of the REPL.