# joaovictorlopezpereira/jvlisp architecture

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

- Interactive diagram: https://gitdiagram.com/joaovictorlopezpereira/jvlisp
- Repository: https://github.com/joaovictorlopezpereira/jvlisp

## Overview

JVLISP is a small C-based Scheme interpreter. Its user workflow is either interactive input or a `.jlp` file: the executable selects the mode, the REPL/script runner tokenizes and parses expressions, and the evaluator computes results in an environment; interactive results are printed. The graph also preserves the documented language features, built-in primitives, and interactive test command. Edges follow the shown calls and documented workflows; unsampled evaluator and primitive dispatch details are not expanded.

Main entry points: [`src/repl.c`](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/repl.c) (REPL and scripts), [`src/object.c`](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/object.c) (Scheme objects), [`src/eval.c`](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/eval.c) (Evaluator), [`src/main.c`](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/main.c) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and interaction"]
  node_entrypoint["CLI entry<br/>[main.c]"]
  node_repl["REPL and scripts<br/>[repl.c]"]
end

subgraph group_language["Language front end"]
  node_tokenizer["Tokenizer<br/>[tokenizer.c]"]
  node_parser["Parser<br/>[parser.c]"]
end

subgraph group_runtime["Evaluation runtime"]
  node_evaluator["Evaluator<br/>[eval.c]"]
  node_environment["Environments<br/>[environment.c]"]
  node_objects["Scheme objects<br/>[object.c]"]
  node_types["Runtime types<br/>[types.h]"]
end

subgraph group_capabilities["Language capabilities"]
  node_primitives["Built-in primitives<br/>[primitives.c]"]
  node_specialforms["Special forms<br/>[eval.c]"]
  node_tests["Primitive test suite<br/>[tests.c]"]
end

node_user(("Scheme user"))
node_source["Scheme source"]

node_user -->|"starts"| node_entrypoint
node_source -->|"supplies file"| node_entrypoint
node_entrypoint -->|"selects mode"| node_repl
node_repl -->|"tokenizes input"| node_tokenizer
node_repl -->|"parses tokens"| node_parser
node_repl -->|"evaluates expressions"| node_evaluator
node_repl -->|"prints results"| node_objects
node_repl -->|"initializes bindings"| node_environment
node_repl -->|"registers command"| node_tests
node_parser -->|"constructs values"| node_objects
node_evaluator -->|"looks up bindings"| node_environment
node_environment -->|"loads primitive map"| node_primitives
node_objects -->|"uses definitions"| node_types
node_tokenizer -->|"creates values"| node_objects
node_evaluator -->|"implements forms"| node_specialforms
node_user -->|"enters expressions"| node_repl
node_source -->|"runs expressions"| node_repl

click node_entrypoint "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/main.c"
click node_repl "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/repl.c"
click node_tokenizer "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/tokenizer.c"
click node_parser "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/parser.c"
click node_evaluator "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/eval.c"
click node_environment "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/environment.c"
click node_objects "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/object.c"
click node_types "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/types.h"
click node_primitives "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/primitives.c"
click node_specialforms "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/eval.c"
click node_tests "https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/tests.c"

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_entrypoint,node_repl,node_user toneBlue
class node_tokenizer,node_parser toneAmber
class node_evaluator,node_environment,node_objects,node_types toneMint
class node_primitives,node_specialforms,node_tests toneRose
class node_source toneIndigo
```

## Components

### Entry and interaction

- [CLI entry](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/main.c): `src/main.c`
- [REPL and scripts](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/repl.c): `src/repl.c`

### Language front end

- [Tokenizer](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/tokenizer.c): `src/tokenizer.c`
- [Parser](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/parser.c): `src/parser.c`

### Evaluation runtime

- [Evaluator](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/eval.c): `src/eval.c`
- [Environments](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/environment.c): `src/environment.c`
- [Scheme objects](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/object.c): `src/object.c`
- [Runtime types](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/types.h): `src/types.h`

### Language capabilities

- [Built-in primitives](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/primitives.c): `src/primitives.c`
- [Special forms](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/eval.c): `src/eval.c`
- [Primitive test suite](https://github.com/joaovictorlopezpereira/jvlisp/blob/main/src/tests.c): `src/tests.c`

### Other components

- **Scheme user**
- **Scheme source**

## Connections

- Scheme user → CLI entry: starts (evidence: `README.md`)
- Scheme source → CLI entry: supplies file (evidence: `README.md`)
- CLI entry → REPL and scripts: selects mode (evidence: `src/main.c`)
- REPL and scripts → Tokenizer: tokenizes input (evidence: `src/repl.c`)
- REPL and scripts → Parser: parses tokens (evidence: `src/repl.c`)
- REPL and scripts → Evaluator: evaluates expressions (evidence: `src/repl.c`)
- REPL and scripts → Scheme objects: prints results (evidence: `src/repl.c`)
- REPL and scripts → Environments: initializes bindings (evidence: `src/repl.c`)
- REPL and scripts → Primitive test suite: registers command (evidence: `src/repl.c`)
- Parser → Scheme objects: constructs values (evidence: `src/parser.c`)
- Evaluator → Environments: looks up bindings (evidence: `src/eval.c`)
- Environments → Built-in primitives: loads primitive map (evidence: `src/environment.c`)
- Scheme objects → Runtime types: uses definitions (evidence: `src/object.c`)
- Tokenizer → Scheme objects: creates values (evidence: `src/tokenizer.c`)
- Evaluator → Special forms: implements forms (evidence: `src/eval.c`)
- Scheme user → REPL and scripts: enters expressions (evidence: `README.md`)
- Scheme source → REPL and scripts: runs expressions (evidence: `README.md`)
