# iv4n-ga6l/go-lispinterpreter architecture

> Architecture diagram of the GitHub repository iv4n-ga6l/go-lispinterpreter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iv4n-ga6l/go-lispinterpreter
- Repository: https://github.com/iv4n-ga6l/go-lispinterpreter

## Overview

##### Project Type and Purpose
- This is a language interpreter that supports a subset of Lisp. The primary goal is to parse, evaluate, and execute Lisp expressions and scripts.
- The interpreter implements key components such as a lexer for tokenizing input, a parser for building an abstract syntax tree (AST), and an evaluator (or interpreter) to process and compute the results of expressions.

##### Analyzing the File Structure
- Top-Level Files: Files like main.go, ast.go, builtin.go, lexer.go, parser.go, and interpreter.go indicate a clear separation of concerns:
- main.go: Entry point handling execution mode (REPL versus script file execution).
- lexer.go: Contains the tokenization logic. Tokens are defined (e.g., FORMAT, PLUS, MINUS, etc.) to identify different symbols in Lisp.
- parser.go: Constructs the AST from the sequence of tokens.
- ast.go: Defines the various Lisp value types (atoms, numbers, strings, lists, functions, etc.) that represent the nodes of the AST.
- builtin.go: Implements built-in functions (arithmetic operations, logical operations, list manipulation, etc.) and possibly helps in function resolution within the interpreter.
- interpreter.go: Contains the evaluation logic that recursively processes the AST.
- main_test.go: Holds tests for validating the interpreter’s behavior.
- The presence of a script.lisp file implies the interpreter can execute Lisp scripts.
- .github/workflows indicates that CI has been set up for automated testing/deployment, which is a secondary but important piece for continuous integration.

- Main Components:
- Input Layer: Accepts input either from an interactive REPL or a script file.
- Lexer Component: Processes raw string input and tokenizes it (lexer.go).
- Parser Component: Builds an AST from tokenized input (parser.go).
- Abstract Syntax Tree (AST) & Value Types: Represents the structure of Lisp expressions (ast.go and builtin.go).
- Interpreter/Evaluator: Recursively processes the AST to compute outputs (interpreter.go).
- Execution/REPL Controller: Handles input reading, invocation of the interpreter and output printing (main.go).
- Unit Testing Module: Ensures the correctness of components (main_test.go).
- Relationships and Interactions:
- The Input Layer feeds raw strings to the Lexer.
- The Lexer outputs a sequence of tokens, which is then consumed by the Parser.
- The Parser generates an AST, built using types defined in ast.go.
- The Interpreter component evaluates the AST, invoking built-in functions and handling user-defined functions.
- The main function serves as the central orchestrator, managing the REPL loop and delegating operations to the Lexer, Parser, and Evaluator.
- GitHub Workflows ensure code quality by running tests on code changes.
- Architectural Patterns and Design Principles:
- Separation of Concerns: Each major function (lexing, parsing, evaluating) lives in its own module.
- Recursion in Evaluation: The interpreter recursively processes nested Lisp expressions.
- Modularity and Extensibility: The built-in functions and ability to support user-defined functions make it easy to extend the interpreter.
- Relevant Technologies and Frameworks:
- Go language as the development platform.
- GitHub Actions for continuous integration.
- Standard testing practices in Go as shown by main_test.go.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Subgraph: Input and Control Layer
    subgraph "Input and Control"
        A["REPL Input"]:::input
        J["Script Input"]:::input
        B["Main Controller"]:::controller
    end

    %% Subgraph: Processing Layer
    subgraph "Processing Layer"
        C["Lexer (Tokenize Input)"]:::process
        D["Parser (Build AST)"]:::process
        E["Abstract Syntax Tree (AST)"]:::process
        F["Built-in Functions"]:::process
        G["Interpreter/Evaluator"]:::process
    end

    %% Subgraph: Support Modules
    subgraph "Support Modules"
        H["Unit Testing"]:::support
        I["CI/CD (GitHub Actions)"]:::support
    end

    %% Flow connections
    A -->|"provides input"| B
    J -->|"provides script"| B
    B -->|"invokes lexer"| C
    C -->|"outputs tokens"| D
    D -->|"builds"| E
    E -->|"feeds AST"| G
    F -->|"supplies built-ins"| G
    B -->|"triggers tests"| H
    I -->|"runs tests"| H

    %% Click Events
    click J "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/script.lisp"
    click B "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/main.go"
    click C "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/lexer.go"
    click D "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/parser.go"
    click E "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/ast.go"
    click F "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/builtin.go"
    click G "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/interpreter.go"
    click H "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/main_test.go"
    click I "https://github.com/iv4n-ga6l/go-lispinterpreter/blob/main/.github/workflows/go.yml"

    %% Styles
    classDef input fill:#fef3bd,stroke:#e4a11b,stroke-width:2px;
    classDef controller fill:#c9f7f5,stroke:#1c64f2,stroke-width:2px;
    classDef process fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px;
    classDef support fill:#f0abfc,stroke:#8b5cf6,stroke-width:2px;
```
