# carrotdlaw/jlox-rs architecture

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

- Interactive diagram: https://gitdiagram.com/carrotdlaw/jlox-rs
- Repository: https://github.com/carrotdlaw/jlox-rs

## Overview

jlox-rs is a Rust tree-walk interpreter for Lox. A user supplies source through the command-line program; the runtime scans it into tokens, parses statements and expressions, resolves lexical scopes, then interprets the program and prints results or reports errors. The runtime also models environments, callable functions, classes, instances, and native functions. The README documents script execution but no broader product features. Edges are limited to calls shown in excerpts, source-index references, or the README; unsampled wiring is not inferred.

Main entry points: [`jlox/src/interpreter.rs`](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/interpreter.rs) (Interpreter), [`jlox/src/lox.rs`](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox.rs) (Lox runner), [`jlox/src/parser.rs`](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/parser.rs) (Parser), [`jlox/src/lox_function.rs`](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_function.rs) (Lox functions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Source Front End"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_runner["Lox runner<br/>[lox.rs]"]
  node_scanner["Scanner<br/>[scanner.rs]"]
  node_tokens["Tokens and values<br/>[token.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_ast["Expression AST<br/>[expr.rs]"]
  node_statements["Statement AST<br/>[stmt.rs]"]
  node_printer["AST printer<br/>[ast_printer.rs]"]
end

subgraph group_analysis["Resolution"]
  node_resolver["Resolver<br/>[resolver.rs]"]
end

subgraph group_runtime["Interpretation"]
  node_interpreter["Interpreter<br/>[interpreter.rs]"]
  node_environment[("Environment<br/>[environment.rs]")]
  node_errors["Errors<br/>[error.rs]"]
end

subgraph group_objects["Lox Objects"]
  node_callable["Callable interface<br/>[lox_callable.rs]"]
  node_function["Lox functions<br/>[lox_function.rs]"]
  node_native["Native functions"]
  node_class["Lox classes<br/>[lox_class.rs]"]
  node_instance["Lox instances<br/>[lox_instance.rs]"]
end

node_user(("Script user"))

node_user -->|"runs script"| node_cli
node_cli -->|"starts runtime"| node_runner
node_runner -->|"scans source"| node_scanner
node_scanner -->|"emits tokens"| node_tokens
node_runner -->|"parses tokens"| node_parser
node_parser -->|"builds expressions"| node_ast
node_parser -->|"builds statements"| node_statements
node_runner -->|"resolves statements"| node_resolver
node_resolver -->|"records local scopes"| node_interpreter
node_runner -->|"interprets program"| node_interpreter
node_interpreter -->|"reads and writes"| node_environment
node_interpreter -->|"dispatches calls"| node_callable
node_function -->|"implements"| node_callable
node_native -->|"implements"| node_callable
node_class -->|"implements"| node_callable
node_interpreter -->|"creates functions"| node_function
node_interpreter -->|"creates classes"| node_class
node_interpreter -->|"registers natives"| node_native
node_function -->|"captures closure"| node_environment
node_function -->|"executes body"| node_interpreter
node_class -->|"creates instances"| node_instance
node_instance -->|"looks up methods"| node_class
node_interpreter -->|"reports runtime faults"| node_errors
node_scanner -->|"reports scan faults"| node_errors
node_parser -->|"reports parse faults"| node_errors
node_printer -->|"prints expressions"| node_ast

click node_cli "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/main.rs"
click node_runner "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox.rs"
click node_scanner "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/scanner.rs"
click node_tokens "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/token.rs"
click node_parser "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/parser.rs"
click node_ast "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/expr.rs"
click node_statements "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/stmt.rs"
click node_resolver "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/resolver.rs"
click node_interpreter "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/interpreter.rs"
click node_environment "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/environment.rs"
click node_errors "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/error.rs"
click node_callable "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_callable.rs"
click node_function "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_function.rs"
click node_native "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_native_function.rs"
click node_class "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_class.rs"
click node_instance "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_instance.rs"
click node_printer "https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/ast_printer.rs"

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_cli,node_runner,node_scanner,node_tokens,node_parser,node_ast,node_statements,node_printer,node_user toneBlue
class node_resolver toneAmber
class node_interpreter,node_environment,node_errors toneMint
class node_callable,node_function,node_native,node_class,node_instance toneRose
```

## Components

### Source Front End

- [CLI entry](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/main.rs): `jlox/src/main.rs`
- [Lox runner](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox.rs): `jlox/src/lox.rs`
- [Scanner](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/scanner.rs): `jlox/src/scanner.rs`
- [Tokens and values](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/token.rs): `jlox/src/token.rs`
- [Parser](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/parser.rs): `jlox/src/parser.rs`
- [Expression AST](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/expr.rs): `jlox/src/expr.rs`
- [Statement AST](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/stmt.rs): `jlox/src/stmt.rs`
- [AST printer](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/ast_printer.rs): `jlox/src/ast_printer.rs`

### Resolution

- [Resolver](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/resolver.rs): `jlox/src/resolver.rs`

### Interpretation

- [Interpreter](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/interpreter.rs): `jlox/src/interpreter.rs`
- [Environment](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/environment.rs): `jlox/src/environment.rs`
- [Errors](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/error.rs): `jlox/src/error.rs`

### Lox Objects

- [Callable interface](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_callable.rs): `jlox/src/lox_callable.rs`
- [Lox functions](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_function.rs): `jlox/src/lox_function.rs`
- [Native functions](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_native_function.rs): `jlox/src/lox_native_function.rs`
- [Lox classes](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_class.rs): `jlox/src/lox_class.rs`
- [Lox instances](https://github.com/carrotdlaw/jlox-rs/blob/master/jlox/src/lox_instance.rs): `jlox/src/lox_instance.rs`

### Other components

- **Script user**

## Connections

- Script user → CLI entry: runs script (evidence: `README.md`)
- CLI entry → Lox runner: starts runtime
- Lox runner → Scanner: scans source (evidence: `jlox/src/lox.rs`)
- Scanner → Tokens and values: emits tokens (evidence: `jlox/src/scanner.rs`)
- Lox runner → Parser: parses tokens (evidence: `jlox/src/lox.rs`)
- Parser → Expression AST: builds expressions (evidence: `jlox/src/parser.rs`)
- Parser → Statement AST: builds statements (evidence: `jlox/src/parser.rs`)
- Lox runner → Resolver: resolves statements (evidence: `jlox/src/lox.rs`)
- Resolver → Interpreter: records local scopes (evidence: `jlox/src/resolver.rs`)
- Lox runner → Interpreter: interprets program (evidence: `jlox/src/lox.rs`)
- Interpreter → Environment: reads and writes (evidence: `jlox/src/interpreter.rs`)
- Interpreter → Callable interface: dispatches calls (evidence: `jlox/src/interpreter.rs`)
- Lox functions → Callable interface: implements (evidence: `jlox/src/lox_function.rs`)
- Native functions → Callable interface: implements (evidence: `jlox/src/lox_native_function.rs`)
- Lox classes → Callable interface: implements (evidence: `jlox/src/lox_class.rs`)
- Interpreter → Lox functions: creates functions (evidence: `jlox/src/interpreter.rs`)
- Interpreter → Lox classes: creates classes (evidence: `jlox/src/interpreter.rs`)
- Interpreter → Native functions: registers natives (evidence: `jlox/src/interpreter.rs`)
- Lox functions → Environment: captures closure (evidence: `jlox/src/lox_function.rs`)
- Lox functions → Interpreter: executes body (evidence: `jlox/src/lox_function.rs`)
- Lox classes → Lox instances: creates instances (evidence: `jlox/src/lox_class.rs`)
- Lox instances → Lox classes: looks up methods (evidence: `jlox/src/lox_instance.rs`)
- Interpreter → Errors: reports runtime faults (evidence: `jlox/src/interpreter.rs`)
- Scanner → Errors: reports scan faults (evidence: `jlox/src/scanner.rs`)
- Parser → Errors: reports parse faults (evidence: `jlox/src/parser.rs`)
- AST printer → Expression AST: prints expressions (evidence: `jlox/src/ast_printer.rs`)