# abdulrahmankhaled1111/interpreter architecture

> Architecture diagram of the GitHub repository abdulrahmankhaled1111/interpreter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulrahmankhaled1111/interpreter
- Repository: https://github.com/abdulrahmankhaled1111/interpreter

## Overview

- **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: [`src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java`](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java) (Evaluator), [`src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java`](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java) (Parser), [`src/test`](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/test) (Tests), [`src/main/java/de/thm/asc/tiel/interpreter/Main.java`](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/Main.java) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_root["CLI & packaging"]
  node_node_main["Main<br/>cli entrypoint<br/>[Main.java]"]
  node_node_build["Gradle build<br/>build config<br/>[build.gradle.kts]"]
end

subgraph group_group_pipeline["Language pipeline"]
  node_node_scanner["Scanner<br/>lexer<br/>[Scanner.java]"]
  node_node_token["Token<br/>lexical unit<br/>[Token.java]"]
  node_node_tokentype["TokenType<br/>token kinds<br/>[TokenType.java]"]
  node_node_parser["Parser<br/>[Parser.java]"]
  node_node_ast_expr{{"Expr AST<br/>expression nodes"}}
  node_node_ast_stmt{{"Stmt AST<br/>statement nodes"}}
  node_node_astprinter["AstPrinter<br/>tree printer<br/>[AstPrinter.java]"]
  node_node_binder["Binder<br/>semantic pass<br/>[Binder.java]"]
end

subgraph group_group_runtime["Runtime model"]
  node_node_evaluator["Evaluator<br/>interpreter core<br/>[Evaluator.java]"]
  node_node_environment["Environment<br/>scope chain<br/>[Environment.java]"]
  node_node_globals[("Globals<br/>built-ins<br/>[Globals.java]")]
  node_node_value["TiELValue<br/>runtime value<br/>[TiELValue.java]"]
  node_node_callable["TiELCallable<br/>call protocol<br/>[TiELCallable.java]"]
  node_node_function["TiELFunction<br/>function object<br/>[TiELFunction.java]"]
  node_node_class["TiELClass<br/>class object<br/>[TiELClass.java]"]
  node_node_instance["TiELInstance<br/>instance object<br/>[TiELInstance.java]"]
  node_node_returnex["ReturnException<br/>control flow"]
end

subgraph group_group_support["Support & validation"]
  node_node_errors{{"Errors"}}
  node_node_examples["Examples<br/>sample programs"]
  node_node_tests["Tests<br/>unit+integration"]
end

node_node_main -->|"reads source"| node_node_scanner
node_node_main -->|"prints AST"| node_node_astprinter
node_node_main -->|"executes"| node_node_evaluator
node_node_scanner -->|"produces"| node_node_token
node_node_scanner -->|"classifies"| node_node_tokentype
node_node_token -->|"consumed by"| node_node_parser
node_node_parser -->|"builds"| node_node_ast_expr
node_node_parser -->|"builds"| node_node_ast_stmt
node_node_ast_expr -->|"rendered by"| node_node_astprinter
node_node_ast_stmt -->|"rendered by"| node_node_astprinter
node_node_parser -->|"feeds"| node_node_binder
node_node_binder -->|"prepares"| node_node_evaluator
node_node_evaluator -->|"uses"| node_node_environment
node_node_environment -->|"extends"| node_node_globals
node_node_evaluator -->|"operates on"| node_node_value
node_node_evaluator -->|"invokes"| node_node_callable
node_node_callable -->|"implements"| node_node_function
node_node_callable -->|"implements"| node_node_class
node_node_class -->|"creates"| node_node_instance
node_node_evaluator -->|"unwinds"| node_node_returnex
node_node_main -->|"reports"| node_node_errors
node_node_scanner -->|"throws"| node_node_errors
node_node_parser -->|"throws"| node_node_errors
node_node_evaluator -->|"throws"| node_node_errors
node_node_examples -->|"mirrors"| node_node_tests
node_node_tests -->|"covers"| node_node_scanner
node_node_tests -->|"covers"| node_node_parser
node_node_tests -->|"covers"| node_node_binder
node_node_tests -->|"covers"| node_node_evaluator
node_node_build -->|"packages"| node_node_main

click node_node_main "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/Main.java"
click node_node_build "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/build.gradle.kts"
click node_node_scanner "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/Scanner.java"
click node_node_token "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/Token.java"
click node_node_tokentype "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/TokenType.java"
click node_node_parser "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java"
click node_node_ast_expr "https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/ast/expr"
click node_node_ast_stmt "https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/ast/stmt"
click node_node_astprinter "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/ast/AstPrinter.java"
click node_node_binder "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/semantic/Binder.java"
click node_node_evaluator "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java"
click node_node_environment "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Environment.java"
click node_node_globals "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Globals.java"
click node_node_value "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELValue.java"
click node_node_callable "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELCallable.java"
click node_node_function "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELFunction.java"
click node_node_class "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELClass.java"
click node_node_instance "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELInstance.java"
click node_node_returnex "https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/ReturnException.java"
click node_node_errors "https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/error"
click node_node_examples "https://github.com/abdulrahmankhaled1111/interpreter/tree/main/examples"
click node_node_tests "https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_build toneBlue
class node_node_scanner,node_node_token,node_node_tokentype,node_node_parser,node_node_ast_expr,node_node_ast_stmt,node_node_astprinter,node_node_binder toneAmber
class node_node_evaluator,node_node_environment,node_node_globals,node_node_value,node_node_callable,node_node_function,node_node_class,node_node_instance,node_node_returnex toneMint
class node_node_errors,node_node_examples,node_node_tests toneRose
```

## Components

### CLI & packaging

Entry point, build, and distribution for the interpreter

- [Main](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/Main.java): cli entrypoint · Command-line entry that selects token dump, AST print, or execution · `src/main/java/de/thm/asc/tiel/interpreter/Main.java`
- [Gradle build](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/build.gradle.kts): build config · Gradle project setup and shaded JAR packaging · `build.gradle.kts`

### Language pipeline

Source processing from lexing through execution

- [Scanner](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/Scanner.java): lexer · Converts source text into tokens · `src/main/java/de/thm/asc/tiel/interpreter/lexical/Scanner.java`
- [Token](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/Token.java): lexical unit · Token representation carried through the front end · `src/main/java/de/thm/asc/tiel/interpreter/lexical/Token.java`
- [TokenType](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/lexical/TokenType.java): token kinds · Enumeration of lexical categories recognized by the scanner · `src/main/java/de/thm/asc/tiel/interpreter/lexical/TokenType.java`
- [Parser](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java): parser · Builds the typed AST from token streams · `src/main/java/de/thm/asc/tiel/interpreter/syntax/Parser.java`
- [Expr AST](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/ast/expr): expression nodes · Expression tree nodes such as binary, call, variable, array, and access forms · `src/main/java/de/thm/asc/tiel/interpreter/ast/expr`
- [Stmt AST](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/ast/stmt): statement nodes · Statement tree nodes such as blocks, declarations, control flow, returns, and classes · `src/main/java/de/thm/asc/tiel/interpreter/ast/stmt`
- [AstPrinter](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/ast/AstPrinter.java): tree printer · Renders ASTs for inspection and debugging · `src/main/java/de/thm/asc/tiel/interpreter/ast/AstPrinter.java`
- [Binder](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/semantic/Binder.java): semantic pass · 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](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java): interpreter core · Executes the bound program against runtime environments · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/Evaluator.java`
- [Environment](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Environment.java): scope chain · Variable scopes and bindings used during evaluation · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/Environment.java`
- [Globals](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/Globals.java): built-ins · Root runtime state and built-in values/functions · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/Globals.java`
- [TiELValue](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELValue.java): runtime value · Common value abstraction for interpreter data · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELValue.java`
- [TiELCallable](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELCallable.java): call protocol · Interface for functions and other callable runtime objects · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELCallable.java`
- [TiELFunction](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELFunction.java): function object · Callable implementation for user-defined functions and closures · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELFunction.java`
- [TiELClass](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELClass.java): class object · Runtime representation of classes and constructors · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELClass.java`
- [TiELInstance](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELInstance.java): instance object · Runtime representation of class instances and fields · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/TiELInstance.java`
- [ReturnException](https://github.com/abdulrahmankhaled1111/interpreter/blob/main/src/main/java/de/thm/asc/tiel/interpreter/evaluation/ReturnException.java): control flow · Internal exception used to unwind function returns · `src/main/java/de/thm/asc/tiel/interpreter/evaluation/ReturnException.java`

### Support & validation

Errors, examples, and tests

- [Errors](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/main/java/de/thm/asc/tiel/interpreter/error): phase errors · Shared error hierarchy for scanning, parsing, and runtime failures · `src/main/java/de/thm/asc/tiel/interpreter/error`
- [Examples](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/examples): sample programs · Canonical TiEL programs demonstrating language features · `examples`
- [Tests](https://github.com/abdulrahmankhaled1111/interpreter/tree/main/src/test): unit+integration · Scanner, parser, binder, evaluator, and staged integration validation · `src/test`

## Connections

- 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
