# sohammalakar/fun-assembly architecture

> Architecture diagram of the GitHub repository sohammalakar/fun-assembly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sohammalakar/fun-assembly
- Repository: https://github.com/sohammalakar/fun-assembly

## Overview

##### Project Type & Purpose
- This project is an interpreter for a custom, token-based procedural programming language called “Fun Assembly.” Its purpose is to read and execute programs written in its simple assembly-like syntax. The language supports a variety of operations (arithmetic, string manipulation, file I/O, control flow with jumps, module system, and functions) using a modular design.
- The README emphasizes that it is written in C++ and uses a hash table for symbol storage. In addition, there are sample programs (with .fasml extension) that demonstrate language features. This clearly marks the project as an interpreter with built-in tooling (e.g., syntax highlighter extension for VS Code).

##### File Structure
- Top-level files such as main.cpp, Makefile, install.bat, and README.md indicate the core engine is in C++ and the build/deployment is scripted.
- The resources folder contains images (like the logo and code theme previews) used for branding and IDE integration.
- The samples directory holds numerous .fasml files showcasing language features (e.g., loops via jumps, function calls, module system, file I/O, arithmetic expressions). These act both as tests and documentation.
- The presence of test.sh and configuration files (e.g., .gitattributes, LICENSE) reflects good project organization and release management.

##### Main Components of the System (to be included
a. Interpreter Core:
- Main Execution Engine: Entry point is main.cpp which initializes and runs the interpreter.
- Tokenizer/Lexer: Parses the input .fasml files into tokens (based on spaces and keywords).
- Parser/Interpreter: Processes tokens, handles control structures (labels, jumps) and interprets language syntax based on the simplified rules.
- Expression Evaluator: Specifically handles arithmetic and logical expressions (e.g., EXPR keyword).
- Variable/Symbol Table Manager: Uses a hash table to store variables, arrays, and their dynamic (effectively global) context.

b. Module & Function Handling:
- Module Loader: Manages the built-in module system where individual .fasml files can be loaded and executed.
- Function Manager: Handles user-defined functions (via labels and FCALL/FRET) within a single file.

c. Input/Output Handlers:
- File I/O Subsystem: Implements operations like FREAD, FWRITE, and FDEL for file manipulation.
- Terminal I/O Management: Supports reading command line arguments as well as interactive inputs (SCN and SCNL).

d. Extension and Integration Layers:
- Command Line Interface (CLI): Facilitates program execution with arguments (`fasml <filename> [args]`).
- IDE Integration: Although part of the broader ecosystem, the provided syntax highlighter resources indicate an extension layer, for example with Visual Studio Code.

##### Relationships & Interactions
- The CLI sends a .fasml file as input to the interpreter core.
- The interpreter core (main.cpp) first tokenizes the code, then uses the parser to build/extract control flow elements (labels, jumps, function definitions).
- The Expression Evaluator processes arithmetic and logical operations.
- All components consult the Variable/Symbol Table Manager to read/write variables during execution.
- On encountering module or function calls, the corresponding Module Loader or Function Manager is invoked, and control is transferred accordingly.
- I/O Handlers process file reading/writing operations and interact with the system’s file system, while CLI arguments are mapped into internal variables ($ARGC, $0, $1, etc.).

##### Architectural Patterns & Technologies
- The design follows a procedural programming paradigm with a modular plugin-like system (for modules and functions).
- The interpreter’s processing stages resemble a traditional compiler/interpreter architecture – tokenize, parse, then execute.
- Usage of a hash table for variable management is an essential detail that should be highlighted.
- C++ as the implementation language, and mention build tools (Makefile) and platform-specific install scripts (install.bat).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface
    cli["\"CLI Interface\""]:::cliStyle
    click cli "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"

    %% Interpreter Core
    subgraph "Interpreter Core"
        tok["\"Tokenizer/Lexer\""]:::coreStyle
        par["\"Parser/Interpreter\""]:::coreStyle
        expr["\"Expression Evaluator\""]:::coreStyle
        sym["\"Variable/Symbol Table Manager\""]:::coreStyle
        tok -->|"parses to"| par
        par -->|"evaluates"| expr
        expr ---|"accesses"| sym
    end
    click tok "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"
    click par "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"
    click expr "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"
    click sym "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"

    %% Flow from CLI to Interpreter Core
    cli -->|"provides source"| tok

    %% Module & Function Handling
    subgraph "Module & Function Handling"
        mod["\"Module Loader\""]:::moduleStyle
        func["\"Function Manager\""]:::moduleStyle
        %% Arrows from Parser/Interpreter to module handling components
        par -->|"invokes"| mod
        par -->|"calls"| func
    end
    click mod "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"
    click func "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"

    %% I/O Handlers
    subgraph "I/O Handlers"
        io1["\"File I/O Subsystem\""]:::ioStyle
        io2["\"Terminal I/O\""]:::ioStyle
        par -->|"triggers"| io1
        par -->|"reads-input"| io2
    end
    click io1 "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"
    click io2 "https://github.com/sohammalakar/fun-assembly/blob/master/main.cpp"

    %% Supporting Resources
    subgraph "Supporting Resources"
        make["\"Makefile\""]:::supportStyle
        bat["\"install.bat\""]:::supportStyle
        res["\"resources\""]:::supportStyle
        readme["\"README.md\""]:::supportStyle
    end
    click make "https://github.com/sohammalakar/fun-assembly/tree/master/Makefile"
    click bat "https://github.com/sohammalakar/fun-assembly/blob/master/install.bat"
    click res "https://github.com/sohammalakar/fun-assembly/tree/master/resources"
    click readme "https://github.com/sohammalakar/fun-assembly/blob/master/README.md"

    %% Sample Programs
    subgraph "Sample Programs"
        samples["\"samples\""]:::sampleStyle
    end
    click samples "https://github.com/sohammalakar/fun-assembly/tree/master/samples"

    %% Styles
    classDef cliStyle fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef coreStyle fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef moduleStyle fill:#a9dfbf,stroke:#1e8449,stroke-width:2px;
    classDef ioStyle fill:#f9c4a6,stroke:#d35400,stroke-width:2px;
    classDef supportStyle fill:#d7dbdd,stroke:#566573,stroke-width:2px;
    classDef sampleStyle fill:#f5b7b1,stroke:#a93226,stroke-width:2px;
```
