How abdulrahmankhaled1111/interpreter works
• Project type and runtime: This is a self-contained Java 25 interpreter for the educational language TiEL. The repo is organized as a single Gradle project (build.gradle.kts) and produces a runnable shaded JAR via the Shadow plugin.
• Top-level execution path: The entry point is Main.java, which drives a command-line interface that accepts a source file plus flags like --tokens and --ast. The CLI is responsible for choosing whether to print lexical tokens, print the AST, or execute the program.
• Language processing pipeline: The architecture follows the classic interpreter flow:
1. read TiEL source from an input file,
2. scan it into tokens,
3. parse tokens into an AST,
4. run semantic binding,
5. evaluate the program.
• Lexical layer: lexical/Scanner, Token, and TokenType handle raw source text and convert it into a token stream. This is the first real language boundary and is also exposed through the --tokens CLI mode.
• Syntax layer / AST construction: syntax/Parser builds the tree of expression and statement nodes under ast/expr and ast/stmt. The AST is explicit and typed, with separate nodes for things like binary operations, function calls, variable declarations, blocks, loops, conditionals, classes, and inheritance-related constructs.
• AST utilities: AstPrinter is a support component for inspecting the generated syntax tree, likely used by the CLI --ast mode and for debugging or coursework validation.
• Semantic analysis: semantic/Binder sits between parsing and execution. Its role is to resolve names and enforce semantic rules before runtime, acting as a distinct phase rather than folding all checks into evaluation.
• Evaluation/runtime model: evaluation/Evaluator executes the bound AST using Environment scopes. Runtime support is split into explicit object types: TiELValue for values, TiELCallable for callable behavior, TiELFunction for functions, TiELClass and TiELInstance for object-oriented features, plus ReturnException to implement function returns.
• Global built-ins and runtime state: Globals defines the interpreter’s built-in runtime environment. This is where any language-provided functions or root-level values would live, separating built-in behavior from user program state.
• Error handling boundary: The error package separates failures by phase: ScanningError, ParsingError, and RuntimeError, all under a shared error abstraction. This makes it easy to tell whether a failure occurred in source reading, syntax/semantic processing, or execution.
• Language features visible in the repo: The examples and AST classes show TiEL supports variables, arithmetic, booleans, strings, arrays, functions, local functions, control flow, classes, and inheritance. The examples/ directory is the canonical source of small programs demonstrating those capabilities.
• Testing and validation: The test suite mirrors the interpreter pipeline with unit tests for scanner, parser, binder, and evaluator, plus integration tests that execute staged TiEL programs and compare output against golden files in src/test/resources/integration_tests/. This suggests the repo is validated as a full language pipeline, not just isolated components.
• Packaging and distribution: The repository is designed to be run from IDE during development, but also packaged as a portable executable JAR (tiel-1.0-SNAPSHOT-all.jar). That makes the interpreter easy to distribute and run as a command-line tool without external dependencies.
Main entry points: Evaluator.java Evaluator · Parser.java Parser · test Tests · Main.java Main
Components 22
CLI & packaging
Entry point, build, and distribution for the interpreter
- Main · Command-line entry that selects token dump, AST print, or execution
src/main/java/de/thm/asc/tiel/interpreter/Main.java - Gradle build · Gradle project setup and shaded JAR packaging
build.gradle.kts
Language pipeline
Source processing from lexing through execution
- Scanner · Converts source text into tokens
src/main/java/de/thm/asc/tiel/interpreter/lexical/Scanner.java - Token · Token representation carried through the front end
src/main/java/de/thm/asc/tiel/interpreter/lexical/Token.java - TokenType · Enumeration of lexical categories recognized by the scanner
src/main/java/de/thm/asc/tiel/interpreter/lexical/TokenType.java - Parser · Builds the typed AST from token streams
src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java - Expr AST · Expression tree nodes such as binary, call, variable, array, and access forms
src/main/java/de/thm/asc/tiel/interpreter/ast/expr - Stmt AST · Statement tree nodes such as blocks, declarations, control flow, returns, and classes
src/main/java/de/thm/asc/tiel/interpreter/ast/stmt - AstPrinter · Renders ASTs for inspection and debugging
src/main/java/de/thm/asc/tiel/interpreter/ast/AstPrinter.java - Binder · Resolves names and performs semantic checks before execution
src/main/java/de/thm/asc/tiel/interpreter/semantic/Binder.java
Runtime model
Execution state, objects, and callable behavior
- Evaluator · Executes the bound program against runtime environments
src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java - Environment · Variable scopes and bindings used during evaluation
src/main/java/de/thm/asc/tiel/interpreter/evaluation/Environment.java - Globals · Root runtime state and built-in values/functions
src/main/java/de/thm/asc/tiel/interpreter/evaluation/Globals.java - TiELValue · Common value abstraction for interpreter data
src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELValue.java - TiELCallable · Interface for functions and other callable runtime objects
src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELCallable.java - TiELFunction · Callable implementation for user-defined functions and closures
src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELFunction.java - TiELClass · Runtime representation of classes and constructors
src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELClass.java - TiELInstance · Runtime representation of class instances and fields
src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELInstance.java - ReturnException · Internal exception used to unwind function returns
src/main/java/de/thm/asc/tiel/interpreter/evaluation/ReturnException.java
Support & validation
Errors, examples, and tests
Connections 30
- Main → Scanner: reads source · CLI loads a source file and begins lexical analysis
- Main → AstPrinter: prints AST · AST mode renders parsed syntax trees
- Main → Evaluator: executes · Default mode runs the full interpreter pipeline
- Scanner → Token: produces · Scanner emits token stream items
- Scanner → TokenType: classifies · Token kinds guide scanning decisions
- Token → Parser: consumed by · Parser consumes tokens from the scanner
- Parser → Expr AST: builds · Parser constructs expression nodes
- Parser → Stmt AST: builds · Parser constructs statement nodes
- Expr AST → AstPrinter: rendered by · Expression nodes can be inspected with the AST printer
- Stmt AST → AstPrinter: rendered by · Statement nodes can be inspected with the AST printer
- Parser → Binder: feeds · Parsed AST is handed to semantic binding
- Binder → Evaluator: prepares · Bound program is ready for execution
- Evaluator → Environment: uses · Evaluation runs within lexical scopes
- Environment → Globals: extends · Global built-ins seed the outermost environment
- Evaluator → TiELValue: operates on · Runtime computation is expressed in TiEL values
- Evaluator → TiELCallable: invokes · Call expressions dispatch through the callable protocol
- TiELCallable → TiELFunction: implements · Functions are callable runtime objects
- TiELCallable → TiELClass: implements · Classes behave as callable constructors
- TiELClass → TiELInstance: creates · Class calls produce instances
- Evaluator → ReturnException: unwinds · Returns propagate through a dedicated control-flow exception
- Main → Errors: reports · CLI surfaces phase-specific failures
- Scanner → Errors: throws · Lexical failures are reported as scanning errors
- Parser → Errors: throws · Syntax failures are reported as parsing errors
- Evaluator → Errors: throws · Execution failures are reported as runtime errors
- Examples → Tests: mirrors · Examples and golden integration cases demonstrate supported language features
- Tests → Scanner: covers · Scanner unit tests validate tokenization
- Tests → Parser: covers · Parser unit tests validate AST construction
- Tests → Binder: covers · Binder tests validate semantic resolution
- Tests → Evaluator: covers · Evaluator tests validate runtime behavior
- Gradle build → Main: packages · Build produces the runnable shaded JAR around the main entry point