gglang 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGLang Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+<![CDATA[```
+   ██████╗  ██████╗ ██╗      █████╗ ███╗   ██╗ ██████╗
+  ██╔════╝ ██╔════╝ ██║     ██╔══██╗████╗  ██║██╔════╝
+  ██║  ███╗██║  ███╗██║     ███████║██╔██╗ ██║██║  ███╗
+  ██║   ██║██║   ██║██║     ██╔══██║██║╚██╗██║██║   ██║
+  ╚██████╔╝╚██████╔╝███████╗██║  ██║██║ ╚████║╚██████╔╝
+   ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝
+```
+
+# 🎮 GGLang — The Gaming-Themed Programming Language
+
+> **GG** stands for *Good Game*. Write code like you're playing one.
+
+[![Language](https://img.shields.io/badge/language-TypeScript-blue)]()
+[![File Extension](https://img.shields.io/badge/extension-.gg-brightgreen)]()
+[![License](https://img.shields.io/badge/license-MIT-yellow)]()
+
+---
+
+## 🕹️ What is GGLang?
+
+**GGLang** is a toy programming language where every keyword is a gaming term. Variables are **equipped**, functions are **skills**, loops are **grinds**, and errors are **glitches**. It's built entirely in TypeScript and is designed to make learning about interpreters and compilers fun.
+
+Instead of writing boring old `if / else`, you embark on a `quest` — and if things go south, you `retreat`. Instead of a `while` loop, you `grind` until you're done. Your programs don't just *start* — they `spawn`.
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| 🎮 **Gaming keywords** | Every keyword maps to a gaming concept |
+| 🧮 **Full expressions** | Arithmetic, comparison, logical, and assignment operators |
+| 🔁 **Control flow** | `quest` / `side_quest` / `retreat` (if/else if/else) |
+| 🔄 **Loops** | `grind` (while) with `rage_quit` (break) and `respawn` (continue) |
+| ⚔️ **Functions** | `skill` (function) with `loot` (return) and recursion support |
+| 🛡️ **Error handling** | `boss_fight` / `revive` / `glitch` (try/catch/throw) |
+| 📢 **I/O** | `broadcast` (print) and `interact` (input) |
+| 📝 **Comments** | Single-line `//` and multi-line `/* */` |
+| 🏗️ **Built with TypeScript** | Clean, hackable, and easy to extend |
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd toy-programming-language
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+### Hello, World!
+
+Create a file called `hello.gg`:
+
+```
+spawn {
+  broadcast("Hello, World!");
+  broadcast("Welcome to GGLang! 🎮");
+}
+```
+
+Run it:
+
+```bash
+npm start -- hello.gg
+```
+
+### Try the REPL
+
+```bash
+npm start
+```
+
+---
+
+## 📖 A Taste of GGLang
+
+```
+spawn {
+  // Equip your variables like items in your inventory
+  equip playerName = interact("Enter your name, adventurer: ");
+  equip health = 100;
+  artifact maxHealth = 100;  // Artifacts are constants — permanent relics
+
+  // Define a skill (function)
+  skill battleCry(name) {
+    broadcast("⚔️ " + name + " charges into battle!");
+  }
+
+  // Embark on a quest (if/else)
+  quest (health == maxHealth) {
+    battleCry(playerName);
+  } retreat {
+    broadcast("You need to heal first!");
+  }
+
+  // Grind through enemies (while loop)
+  equip enemiesDefeated = 0;
+  grind (enemiesDefeated < 5) {
+    broadcast("Enemy #" + (enemiesDefeated + 1) + " defeated!");
+    enemiesDefeated += 1;
+  }
+
+  broadcast("GG, " + playerName + "! 🏆");
+}
+```
+
+---
+
+## 📚 Documentation
+
+For the complete language reference, syntax guide, and example programs, see the **[Full Documentation](docs/DOCUMENTATION.md)**.
+
+---
+
+## 📂 Example Programs
+
+| File | Description |
+|---|---|
+| [`hello.gg`](examples/hello.gg) | Hello World — your first spawn |
+| [`fibonacci.gg`](examples/fibonacci.gg) | Recursive Fibonacci sequence |
+| [`fizzbuzz.gg`](examples/fizzbuzz.gg) | Classic FizzBuzz challenge |
+| [`adventure.gg`](examples/adventure.gg) | Mini text adventure game |
+
+---
+
+## 🗺️ Keyword Cheat Sheet
+
+| Concept | GGLang | You'd normally write… |
+|---|---|---|
+| Start program | `spawn { }` | `main()` |
+| Variable | `equip x = 5;` | `let x = 5;` |
+| Constant | `artifact PI = 3.14;` | `const PI = 3.14;` |
+| Print | `broadcast("hi");` | `console.log("hi");` |
+| If / Else if / Else | `quest / side_quest / retreat` | `if / else if / else` |
+| While loop | `grind (cond) { }` | `while (cond) { }` |
+| Break / Continue | `rage_quit / respawn` | `break / continue` |
+| Function / Return | `skill fn() { loot val; }` | `function fn() { return val; }` |
+| True / False / Null | `victory / defeat / phantom` | `true / false / null` |
+| Try / Catch | `boss_fight { } revive(e) { }` | `try { } catch(e) { }` |
+| Throw error | `glitch "msg";` | `throw "msg";` |
+| Input | `interact("prompt")` | `readline("prompt")` |
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — do whatever you want with it. GG! 🎮
+]]>

package/dist/environment.d.ts

@@ -0,0 +1,45 @@
+import { RuntimeValue } from './types';
+export declare class Environment {
+    /** Map of variable names to their entries in the current scope */
+    private variables;
+    /** Reference to the enclosing (parent) scope, or null for global */
+    private parent;
+    /**
+     * Creates a new environment scope.
+     * @param parent - The enclosing environment. Omit for the global scope.
+     */
+    constructor(parent?: Environment);
+    /**
+     * Declares a new variable in the current scope.
+     * Throws if a variable with the same name already exists in this scope.
+     *
+     * @param name - The variable name
+     * @param value - The initial value
+     * @param constant - Whether this variable is a constant (artifact)
+     */
+    declare(name: string, value: RuntimeValue, constant: boolean): void;
+    /**
+     * Looks up a variable by name, walking up the parent chain.
+     * Throws GGRuntimeError if the variable is not found in any scope.
+     *
+     * @param name - The variable name to look up
+     * @returns The variable's current runtime value
+     */
+    get(name: string): RuntimeValue;
+    /**
+     * Updates an existing variable's value, walking up the parent chain.
+     * Throws if the variable is not found or if it's a constant (artifact).
+     *
+     * @param name - The variable name to update
+     * @param value - The new value to assign
+     */
+    set(name: string, value: RuntimeValue): void;
+    /**
+     * Checks whether a variable exists in the current scope or any parent scope.
+     *
+     * @param name - The variable name to check
+     * @returns true if the variable is declared somewhere in the scope chain
+     */
+    has(name: string): boolean;
+}
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAkB,MAAM,SAAS,CAAC;AAavD,qBAAa,WAAW;IACtB,kEAAkE;IAClE,OAAO,CAAC,SAAS,CAA6B;IAE9C,oEAAoE;IACpE,OAAO,CAAC,MAAM,CAAqB;IAEnC;;;OAGG;gBACS,MAAM,CAAC,EAAE,WAAW;IAKhC;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAUnE;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAkB/B;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IA2B5C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAW3B"}

package/dist/environment.js

@@ -0,0 +1,95 @@
+"use strict";
+// ============================================================
+// GGLang — Environment (Scope Management)
+// Manages variable declarations, lookups, and assignments
+// with support for lexical scoping via parent chain traversal.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Environment = void 0;
+const types_1 = require("./types");
+// ---- Environment Class ----
+class Environment {
+    /**
+     * Creates a new environment scope.
+     * @param parent - The enclosing environment. Omit for the global scope.
+     */
+    constructor(parent) {
+        this.variables = new Map();
+        this.parent = parent ?? null;
+    }
+    /**
+     * Declares a new variable in the current scope.
+     * Throws if a variable with the same name already exists in this scope.
+     *
+     * @param name - The variable name
+     * @param value - The initial value
+     * @param constant - Whether this variable is a constant (artifact)
+     */
+    declare(name, value, constant) {
+        if (this.variables.has(name)) {
+            throw new types_1.GGRuntimeError(`Variable '${name}' is already equipped in this scope! Cannot re-declare.`);
+        }
+        this.variables.set(name, { value, constant });
+    }
+    /**
+     * Looks up a variable by name, walking up the parent chain.
+     * Throws GGRuntimeError if the variable is not found in any scope.
+     *
+     * @param name - The variable name to look up
+     * @returns The variable's current runtime value
+     */
+    get(name) {
+        const entry = this.variables.get(name);
+        if (entry !== undefined) {
+            return entry.value;
+        }
+        // Walk up the scope chain
+        if (this.parent) {
+            return this.parent.get(name);
+        }
+        // Variable not found in any scope
+        throw new types_1.GGRuntimeError(`Variable '${name}' is not equipped! You must equip it before using it.`);
+    }
+    /**
+     * Updates an existing variable's value, walking up the parent chain.
+     * Throws if the variable is not found or if it's a constant (artifact).
+     *
+     * @param name - The variable name to update
+     * @param value - The new value to assign
+     */
+    set(name, value) {
+        const entry = this.variables.get(name);
+        if (entry !== undefined) {
+            // Found in current scope — check if it's a constant
+            if (entry.constant) {
+                throw new types_1.GGRuntimeError(`Cannot reassign artifact '${name}'! Artifacts are immutable legendary items.`);
+            }
+            entry.value = value;
+            return;
+        }
+        // Walk up the scope chain
+        if (this.parent) {
+            this.parent.set(name, value);
+            return;
+        }
+        // Variable not found in any scope
+        throw new types_1.GGRuntimeError(`Variable '${name}' is not equipped! You must equip it before assigning to it.`);
+    }
+    /**
+     * Checks whether a variable exists in the current scope or any parent scope.
+     *
+     * @param name - The variable name to check
+     * @returns true if the variable is declared somewhere in the scope chain
+     */
+    has(name) {
+        if (this.variables.has(name)) {
+            return true;
+        }
+        if (this.parent) {
+            return this.parent.has(name);
+        }
+        return false;
+    }
+}
+exports.Environment = Environment;
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,0CAA0C;AAC1C,0DAA0D;AAC1D,+DAA+D;AAC/D,+DAA+D;;;AAE/D,mCAAuD;AAWvD,8BAA8B;AAE9B,MAAa,WAAW;IAOtB;;;OAGG;IACH,YAAY,MAAoB;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,IAAI,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,IAAY,EAAE,KAAmB,EAAE,QAAiB;QAC1D,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,sBAAc,CACtB,aAAa,IAAI,yDAAyD,CAC3E,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAY;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC;QAED,0BAA0B;QAC1B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAED,kCAAkC;QAClC,MAAM,IAAI,sBAAc,CACtB,aAAa,IAAI,uDAAuD,CACzE,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAY,EAAE,KAAmB;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,oDAAoD;YACpD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM,IAAI,sBAAc,CACtB,6BAA6B,IAAI,6CAA6C,CAC/E,CAAC;YACJ,CAAC;YAED,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;YACpB,OAAO;QACT,CAAC;QAED,0BAA0B;QAC1B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,kCAAkC;QAClC,MAAM,IAAI,sBAAc,CACtB,aAAa,IAAI,8DAA8D,CAChF,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,IAAY;QACd,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AA9GD,kCA8GC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+"use strict";
+// ============================================================
+// GGLang — CLI Entry Point
+// Run a .gg source file or start an interactive REPL session.
+//
+// Usage:
+//   gglang <filename.gg>    — execute a source file
+//   gglang                  — start the REPL
+// ============================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const lexer_1 = require("./lexer");
+const parser_1 = require("./parser");
+const interpreter_1 = require("./interpreter");
+// ---- Constants ----
+const VERSION = '1.0.0';
+const VICTORY_BANNER = '\n🏆 VICTORY ROYALE! Program executed successfully.\n';
+const GAME_OVER_BANNER = '\n💀 GAME OVER!\n';
+// ============================================================
+// File Execution Mode
+// ============================================================
+/**
+ * Reads a .gg source file, tokenizes it, parses the AST,
+ * and executes it through the interpreter.
+ *
+ * @param filePath - Path to the .gg source file
+ */
+function runFile(filePath) {
+    // Resolve to an absolute path
+    const resolvedPath = path.resolve(filePath);
+    // Check that the file exists
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(`${GAME_OVER_BANNER}❌ File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    // Read the source code
+    const source = fs.readFileSync(resolvedPath, 'utf-8');
+    try {
+        // Pipeline: Source → Tokens → AST → Execution
+        const lexer = new lexer_1.Lexer();
+        const tokens = lexer.tokenize(source);
+        const parser = new parser_1.Parser();
+        const program = parser.parse(tokens);
+        const interpreter = new interpreter_1.Interpreter();
+        interpreter.execute(program);
+        console.log(VICTORY_BANNER);
+    }
+    catch (error) {
+        console.error(GAME_OVER_BANNER);
+        if (error instanceof Error) {
+            console.error(`  ${error.message}\n`);
+        }
+        else {
+            console.error(`  Unknown error: ${error}\n`);
+        }
+        process.exit(1);
+    }
+}
+// ============================================================
+// REPL Mode (Read-Eval-Print Loop)
+// ============================================================
+/**
+ * Starts an interactive REPL session.
+ * Each line is independently lexed, parsed, and executed.
+ * State persists across lines (same interpreter instance).
+ *
+ * In REPL mode, the `spawn { }` wrapper is NOT required —
+ * statements are executed directly.
+ */
+function startRepl() {
+    // Print the welcome banner
+    console.log('');
+    console.log('╔══════════════════════════════════════════════╗');
+    console.log('║  🎮 GGLang REPL v' + VERSION + ' — Type your code, hero! ║');
+    console.log('║  Type "exit" or press Ctrl+C to quit.       ║');
+    console.log('╚══════════════════════════════════════════════╝');
+    console.log('');
+    // Create readline interface for interactive input
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: '⚔️ > ',
+    });
+    // Persistent interpreter instance — state carries across lines
+    const interpreter = new interpreter_1.Interpreter();
+    // Buffer for multi-line input (tracks unmatched braces)
+    let inputBuffer = '';
+    let braceDepth = 0;
+    rl.prompt();
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        // ---- Exit command ----
+        if (trimmed === 'exit' && braceDepth === 0) {
+            console.log('\n👋 GG, hero! Until next time.\n');
+            rl.close();
+            process.exit(0);
+        }
+        // Accumulate input and track brace depth for multi-line blocks
+        inputBuffer += line + '\n';
+        braceDepth += countChar(line, '{') - countChar(line, '}');
+        // If braces are balanced, attempt to execute the buffered input
+        if (braceDepth <= 0) {
+            braceDepth = 0;
+            const source = inputBuffer.trim();
+            inputBuffer = '';
+            if (source.length === 0) {
+                rl.prompt();
+                return;
+            }
+            try {
+                // In REPL mode, we wrap the input so it doesn't need `spawn { }`
+                const lexer = new lexer_1.Lexer();
+                const tokens = lexer.tokenize(source);
+                const parser = new parser_1.Parser();
+                const program = parser.parse(tokens);
+                interpreter.execute(program);
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    console.error(`  💥 ${error.message}`);
+                }
+                else {
+                    console.error(`  💥 Unknown error: ${error}`);
+                }
+            }
+            rl.prompt();
+        }
+        else {
+            // Still waiting for more input — show continuation prompt
+            process.stdout.write('... ');
+        }
+    });
+    rl.on('close', () => {
+        console.log('\n👋 GG, hero! Until next time.\n');
+        process.exit(0);
+    });
+}
+// ---- Utilities ----
+/**
+ * Counts occurrences of a character in a string.
+ * Used for tracking brace depth in the REPL.
+ */
+function countChar(str, char) {
+    let count = 0;
+    for (const c of str) {
+        if (c === char)
+            count++;
+    }
+    return count;
+}
+// ============================================================
+// Main — Parse CLI args and dispatch
+// ============================================================
+const filename = process.argv[2];
+if (filename) {
+    // File execution mode
+    runFile(filename);
+}
+else {
+    // Interactive REPL mode
+    startRepl();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AACA,+DAA+D;AAC/D,2BAA2B;AAC3B,8DAA8D;AAC9D,EAAE;AACF,SAAS;AACT,oDAAoD;AACpD,6CAA6C;AAC7C,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE/D,uCAAyB;AACzB,2CAA6B;AAC7B,mDAAqC;AAErC,mCAAgC;AAChC,qCAAkC;AAClC,+CAA4C;AAE5C,sBAAsB;AAEtB,MAAM,OAAO,GAAG,OAAO,CAAC;AACxB,MAAM,cAAc,GAAG,uDAAuD,CAAC;AAC/E,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAE7C,+DAA+D;AAC/D,sBAAsB;AACtB,+DAA+D;AAE/D;;;;;GAKG;AACH,SAAS,OAAO,CAAC,QAAgB;IAC/B,8BAA8B;IAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5C,6BAA6B;IAC7B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,GAAG,gBAAgB,qBAAqB,YAAY,EAAE,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,uBAAuB;IACvB,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAEtD,IAAI,CAAC;QACH,8CAA8C;QAC9C,MAAM,KAAK,GAAG,IAAI,aAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEtC,MAAM,MAAM,GAAG,IAAI,eAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAErC,MAAM,WAAW,GAAG,IAAI,yBAAW,EAAE,CAAC;QACtC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE7B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAEhC,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,oBAAoB,KAAK,IAAI,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,mCAAmC;AACnC,+DAA+D;AAE/D;;;;;;;GAOG;AACH,SAAS,SAAS;IAChB,2BAA2B;IAC3B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,qBAAqB,GAAG,OAAO,GAAG,4BAA4B,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,kDAAkD;IAClD,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO;KAChB,CAAC,CAAC;IAEH,+DAA+D;IAC/D,MAAM,WAAW,GAAG,IAAI,yBAAW,EAAE,CAAC;IAEtC,wDAAwD;IACxD,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,EAAE,CAAC,MAAM,EAAE,CAAC;IAEZ,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAE5B,yBAAyB;QACzB,IAAI,OAAO,KAAK,MAAM,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;YACjD,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,+DAA+D;QAC/D,WAAW,IAAI,IAAI,GAAG,IAAI,CAAC;QAC3B,UAAU,IAAI,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAE1D,gEAAgE;QAChE,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;YACpB,UAAU,GAAG,CAAC,CAAC;YAEf,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;YAClC,WAAW,GAAG,EAAE,CAAC;YAEjB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,EAAE,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,IAAI,CAAC;gBACH,iEAAiE;gBACjE,MAAM,KAAK,GAAG,IAAI,aAAK,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAEtC,MAAM,MAAM,GAAG,IAAI,eAAM,EAAE,CAAC;gBAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAErC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;oBAC3B,OAAO,CAAC,KAAK,CAAC,QAAQ,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBACzC,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,KAAK,CAAC,uBAAuB,KAAK,EAAE,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;YAED,EAAE,CAAC,MAAM,EAAE,CAAC;QACd,CAAC;aAAM,CAAC;YACN,0DAA0D;YAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QAClB,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,sBAAsB;AAEtB;;;GAGG;AACH,SAAS,SAAS,CAAC,GAAW,EAAE,IAAY;IAC1C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC,KAAK,IAAI;YAAE,KAAK,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+DAA+D;AAC/D,qCAAqC;AACrC,+DAA+D;AAE/D,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEjC,IAAI,QAAQ,EAAE,CAAC;IACb,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,CAAC;AACpB,CAAC;KAAM,CAAC;IACN,wBAAwB;IACxB,SAAS,EAAE,CAAC;AACd,CAAC"}

package/dist/interpreter.d.ts

@@ -0,0 +1,121 @@
+import { Program } from './types';
+export declare class Interpreter {
+    /** The top-level global environment */
+    private globalEnv;
+    constructor();
+    /**
+     * Executes a parsed GGLang program.
+     * Iterates over every statement in the program body and executes it
+     * within the global environment.
+     *
+     * @param program - The AST root node (Program)
+     */
+    execute(program: Program): void;
+    /**
+     * Dispatches a statement to its corresponding handler based on type.
+     *
+     * @param stmt - The AST statement node
+     * @param env - The current environment scope
+     */
+    private executeStatement;
+    /**
+     * equip / artifact — Declare a new variable or constant.
+     */
+    private executeVariableDeclaration;
+    /**
+     * name = expr — Assign a new value to an existing variable.
+     */
+    private executeAssignment;
+    /**
+     * name += expr (and -=, *=, /=) — Compound assignment.
+     * Reads the current value, applies the operator, and writes back.
+     */
+    private executeCompoundAssignment;
+    /**
+     * broadcast(expr) — Print a value to stdout with GGLang formatting.
+     * Strings are printed without surrounding quotes.
+     * null → 'phantom', true → 'victory', false → 'defeat'
+     */
+    private executePrint;
+    /**
+     * quest / side_quest / retreat — Conditional branching.
+     */
+    private executeIf;
+    /**
+     * grind { ... } — While loop with break/continue support.
+     */
+    private executeWhile;
+    /**
+     * skill name(params) { ... } — Declare a function with closure capture.
+     * The function remembers the environment where it was declared.
+     */
+    private executeFunctionDeclaration;
+    /**
+     * loot expr — Return a value from a function.
+     * Throws a ReturnSignal that carries the return value up the stack.
+     */
+    private executeReturn;
+    /**
+     * glitch expr — Throw a runtime error with a user-defined message.
+     */
+    private executeThrow;
+    /**
+     * boss_fight { ... } revive(err) { ... } — Try/catch for error handling.
+     * Only catches GGRuntimeError (user-level errors), not internal signals.
+     */
+    private executeTryCatch;
+    /**
+     * Evaluates an expression node and returns its runtime value.
+     *
+     * @param expr - The AST expression node
+     * @param env - The current environment scope
+     * @returns The evaluated RuntimeValue
+     */
+    private evaluateExpression;
+    /**
+     * Evaluates binary expressions: arithmetic, comparison, and string concatenation.
+     */
+    private evaluateBinaryExpression;
+    /**
+     * Evaluates unary expressions: negation (-) and logical not (!).
+     */
+    private evaluateUnaryExpression;
+    /**
+     * Evaluates logical expressions with short-circuit semantics.
+     * && returns the first falsy value or the last value.
+     * || returns the first truthy value or the last value.
+     */
+    private evaluateLogicalExpression;
+    /**
+     * Evaluates a function call expression.
+     * Handles the built-in 'interact' function (reads user input from stdin)
+     * and user-defined functions (with closure support).
+     */
+    private evaluateCallExpression;
+    /**
+     * Executes a block of statements in a new child scope.
+     * This ensures variables declared inside the block don't leak out.
+     */
+    private executeBlock;
+    /**
+     * Determines the truthiness of a GGLang value.
+     * - false, null, 0, and "" are falsy
+     * - Everything else (including functions) is truthy
+     */
+    private isTruthy;
+    /**
+     * Asserts that a value is a number, throwing a runtime error if not.
+     * Used by arithmetic operators to enforce type safety.
+     */
+    private assertNumber;
+    /**
+     * Formats a RuntimeValue for display (used by broadcast and string coercion).
+     * - Strings are returned as-is (no surrounding quotes)
+     * - null → 'phantom'
+     * - true → 'victory', false → 'defeat'
+     * - Numbers are stringified normally
+     * - Functions show as '<skill name>'
+     */
+    private formatValue;
+}
+//# sourceMappingURL=interpreter.d.ts.map

package/dist/interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../src/interpreter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,OAAO,EAqBR,MAAM,SAAS,CAAC;AA0EjB,qBAAa,WAAW;IACtB,uCAAuC;IACvC,OAAO,CAAC,SAAS,CAAc;;IAQ/B;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAQ/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAiDxB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAQlC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAgDjC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,SAAS;IAqBjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAclC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAoC1B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqEhC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAsBjC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAiE9B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAQhB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;CAUpB"}