# edubart/nelua-lang architecture

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

- Interactive diagram: https://gitdiagram.com/edubart/nelua-lang
- Repository: https://github.com/edubart/nelua-lang

## Overview

##### Project Type and Purpose
- Nelua is essentially a compiler and toolchain for a statically-typed, meta-programmable systems programming language.
- Its purpose is to offer a blend of Lua’s syntactic simplicity and C-like performance by generating readable C code, then using a standard C compiler to produce native binaries.
- Meta programming is key: compile-time manipulation of the source code via Lua, allowing for extensions and high-level language constructs without modifying the core specification.

##### Main Components
a. Compiler Infrastructure:
- Frontend/Parser: Responsible for parsing Nelua source files and generating the Abstract Syntax Tree (AST). This is reflected in files within the “lualib/nelua” directory (e.g., astdefs.lua, astnode.lua, syntaxdefs.lua).
- Preprocessor & Meta Programming Engine: The modules that allow compile-time Lua-based macros and AST manipulations (e.g., preprocessor.lua, plugins like nldecl.lua).
- Analyzer & Type Checker: Parts such as analyzer.lua, analyzercontext.lua, and various utilities for type checking are crucial.
- Code Generation: Components that emit C code from the Nelua AST (modules like cemitter.lua, cgenerator.lua, and luagenerator.lua) and handle emission of native code after C compilation.
b. Runtime and Standard Library:
- Core library files in “lib” include modules for fundamental operations (strings, math, memory, hashmaps, etc.) and various allocators (GC, manual, arena, etc.) that illustrate design choices for memory management.
- “lualib” holds the Nelua runtime, which includes compiler support scripts and built-in libraries.
- “src” contains low-level C files and integration with external components like the Lua core, srpmalloc, and lpeglabel – these reflect the language’s dependence on traditional C libraries and the adaptation of Lua components.
c. Testing and Examples:
- The “tests” directory is important for validating compiler components and libraries.
- The “examples” directory showcases sample Nelua programs (like a Snake game using SDL2) that demonstrate how users interact with the generated code and runtime.
d. Documentation & DevOps:
- The “docs” folder and GitHub workflows indicate the presence of automated testing, continuous integration, and documentation pipelines.
- The Makefile, Dockerfile, and CI configurations are part of the overall ecosystem used for building and deploying the language/toolchain.

##### Relationships & Interactions
- Data Flow: Begin with Nelua source code input → Frontend (parsing into AST) → Preprocessor & analyzer (for metaprogramming and type checking) → Code generation phase (emitting C code) → External C Compiler (GCC/Clang) that produces native binary.
- Interaction: The compiler interacts with the runtime libraries present in “lualib” and “lib” for built-in operations and memory management.
- Test and CI: Represent parallel paths where testing frameworks validate different components (referring to “tests” and the CI workflows).

##### Architectural Patterns and Design Principles
- Modular design: Each compiler phase (frontend, analysis, code generation) is isolated with its own source files, promoting separation of concerns.
- Dual memory management: Both garbage-collected and manual memory models exist – emphasize this choice in the runtime/memory subsystem.
- Interoperability with C: Highlight how the generated C code bridges into existing C-land, which underpins the portability and performance of Nelua.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compiler Pipeline Subgraph
    subgraph "Compiler Pipeline"
        A1["Nelua Source Code"]:::compiler
        A2["Frontend/Parser"]:::compiler
        A3["Preprocessor & Meta Programming Engine"]:::compiler
        A3p["Plugins"]:::compiler
        A4["Analyzer & Type Checker"]:::compiler
        A4c["Analyzer Context"]:::compiler
        subgraph "Code Generation"
            A5_1["C Emitter"]:::compiler
            A5_2["C Generator"]:::compiler
            A5_3["Lua Generator"]:::compiler
            A5_1 --> A5_2
            A5_2 --> A5_3
        end
        A6["External C Compiler (GCC/Clang)"]:::external
        A7["Native Binary"]:::compiler
    end

    %% Runtime & Standard Library Subgraph
    subgraph "Runtime & Standard Library"
        R1["Runtime Support"]:::library
        R2["Standard Library"]:::library
    end

    %% DevOps & Testing Subgraph
    subgraph "DevOps & Testing"
        D1["Testing Infrastructure"]:::testing
        D2["Examples"]:::examples
        D3["Docs & CI/DevOps"]:::docs
    end

    %% Main Flow Connections
    A1 --> A2
    A2 --> A3
    A3 --> A3p
    A3p --> A4
    A4 --> A4c
    A4c --> A5_1
    A5_3 --> A6
    A6 --> A7

    %% Interaction between Compiler and Runtime Components
    A5_3 -->|"links_with"| R1
    R2 -->|"provides"| R1

    %% Additional DevOps/Testing Interactions
    D1 -->|"tests"| A2
    D2 -->|"demonstrates"| A7
    D3 -->|"CI_builds"| A7

    %% Click Events for Component Mapping
    click A2 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/astdefs.lua"
    click A3 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/preprocessor.lua"
    click A3p "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/plugins/nldecl.lua"
    click A4 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/analyzer.lua"
    click A4c "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/analyzercontext.lua"
    click A5_1 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/cemitter.lua"
    click A5_2 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/cgenerator.lua"
    click A5_3 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua/luagenerator.lua"
    click R1 "https://github.com/edubart/nelua-lang/blob/master/lualib/nelua.lua"
    click R2 "https://github.com/edubart/nelua-lang/tree/master/lib"
    click D1 "https://github.com/edubart/nelua-lang/tree/master/tests"
    click D2 "https://github.com/edubart/nelua-lang/tree/master/examples"
    click D3 "https://github.com/edubart/nelua-lang/tree/master/docs"

    %% Styling Classes
    classDef compiler fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef library fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef testing fill:#fff0b3,stroke:#d48806,stroke-width:2px;
    classDef examples fill:#e6e6fa,stroke:#6a0dad,stroke-width:2px;
    classDef docs fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
