# whiteheadbanger/lunfardo architecture

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

- Interactive diagram: https://gitdiagram.com/whiteheadbanger/lunfardo
- Repository: https://github.com/whiteheadbanger/lunfardo

## Overview

##### Main Components
- Entry Point & Interpreter: The execution begins at run.py (in the src directory), which sets up and invokes the interpreter. The interpreter itself is implemented in interpreter.py.
- Lexical Analysis: The lexer defined in lexer.py tokenizes the Lunfardo source code.
- Parsing: The parser (lunfardo_parser.py) consumes tokens and builds the internal AST (Abstract Syntax Tree). The nodes in the AST are described in nodes.py.
- AST & Node Management: nodes.py represents various AST nodes, while rtresult.py manages runtime results.
- Error Handling: Error modules (found in src/errors) provide error definitions, markings, and some error-handling logic.
- Built-in Functions & Libraries: The src/builtin directory holds Lunfardo’s built-in scripts (with .lunf files) as well as Python library counterparts that help implement built-in functionality.
- Type System: Within src/lunfardo_types you find various modules (like boloodean, chamuyo, cheto, etc.) that indicate the introduction of dynamic types within Lunfardo.
- Library Registry: The file library_registry.py helps register or manage available libraries.

##### Their Interactions and Relationships
- The run.py file serves as the system’s starting point, initializing the interpreter. It calls modules for lexing (lexer.py) then parsing (lunfardo_parser.py), followed by execution in interpreter.py.
- The lexer transforms source code (potentially coming from example .lunf files inside the examples folder) into tokens, relying on constants defined in the constants directory.
- The parser uses these tokens, builds an AST using definitions in nodes.py and potentially validates grammar or syntax based on structures defined in grammar.txt.
- The interpreter then processes the AST, invoking built-in functions (via the src/builtin folder and library_registry) and managing type conversions with modules in src/lunfardo_types.
- Error and exception handling are integrated within the execution cycle with modules in the src/errors folder.
- The examples folder demonstrates sample Lunfardo programs, which are interpreted in the same runtime context.

##### Architectural Patterns and Design Principles
- Modular Separation: Components (lexer, parser, interpreter, error handling) are each placed in separate modules to encourage separation of concerns.
- Pipeline Flow: There is a clear sequential processing pipeline: source input → lexing → parsing → interpretation.
- Extensibility: The built-in library mechanism and a registry for libraries suggest that the interpreter is extensible, allowing additional functionalities without disturbing the core components.
- Dynamic Typing: The use of different type modules in lunfardo_types underscores a dynamic type system integrated in the interpreter.

##### Detail Specific Elements
- Role of the "src" folder as the core system.
- "examples" folder separately to show how example programs are used as input to test or demonstrate the interpreter.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Source
    subgraph "Examples"
        EX["Example Programs"]:::support
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        A["Entry Point (run.py)"]:::core
        LEX["Lexer (lexer.py)"]:::core
        P["Parser (lunfardo_parser.py)"]:::core
        N["AST Nodes (nodes.py)"]:::core
        RT["Runtime Results (rtresult.py)"]:::core
        INT["Interpreter (interpreter.py)"]:::core
    end

    %% Constants & Configuration
    subgraph "Constants & Config"
        CNS["Constants & Configuration"]:::data
    end

    %% Built-in Functions & Library Registry
    subgraph "Built-in & Library Management"
        BLT["Built-in Functions"]:::support
        BLT_GUA["gualichos.lunf"]:::support
        BLT_LAC["lacompu.lunf"]:::support
        BLT_LIB["lib (Directory)"]:::support
        LR["Library Registry"]:::support
    end

    %% Type System
    subgraph "Type System"
        TYP["Lunfardo Types"]:::data
    end

    %% Error Handling
    subgraph "Error Handling"
        ERR["Error Handling"]:::support
    end

    %% Connections for Pipeline Flow
    EX --> A
    A --> LEX
    LEX --> P
    P --> N
    P --> RT
    P --> INT

    %% Constants used by Lexer and Parser
    CNS --- LEX
    CNS --- P

    %% Interpreter Dependencies
    INT --> BLT
    INT --> TYP
    INT --> ERR

    %% Built-in Subgroup Dependencies
    BLT --> BLT_GUA
    BLT --> BLT_LAC
    BLT --> BLT_LIB
    BLT --> LR

    %% Styling Classes
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef data fill:#ABEBC6,stroke:#239B56,stroke-width:2px;

    %% Click Events
    click A "https://github.com/whiteheadbanger/lunfardo/blob/master/src/run.py"
    click INT "https://github.com/whiteheadbanger/lunfardo/blob/master/src/interpreter.py"
    click LEX "https://github.com/whiteheadbanger/lunfardo/blob/master/src/lexer.py"
    click P "https://github.com/whiteheadbanger/lunfardo/blob/master/src/lunfardo_parser.py"
    click N "https://github.com/whiteheadbanger/lunfardo/blob/master/src/nodes.py"
    click RT "https://github.com/whiteheadbanger/lunfardo/blob/master/src/rtresult.py"
    
    click ERR "https://github.com/whiteheadbanger/lunfardo/tree/master/src/errors/"
    
    click BLT "https://github.com/whiteheadbanger/lunfardo/tree/master/src/builtin/"
    click BLT_GUA "https://github.com/whiteheadbanger/lunfardo/blob/master/src/builtin/gualichos.lunf"
    click BLT_LAC "https://github.com/whiteheadbanger/lunfardo/blob/master/src/builtin/lacompu.lunf"
    click BLT_LIB "https://github.com/whiteheadbanger/lunfardo/tree/master/src/builtin/lib/"
    
    click CNS "https://github.com/whiteheadbanger/lunfardo/tree/master/src/constants/"
    click TYP "https://github.com/whiteheadbanger/lunfardo/tree/master/src/lunfardo_types/"
    click LR "https://github.com/whiteheadbanger/lunfardo/blob/master/src/library_registry.py"
    click EX "https://github.com/whiteheadbanger/lunfardo/tree/master/src/examples/"
```
