gglang 1.0.0

package/docs/DOCUMENTATION.md

@@ -0,0 +1,904 @@
+<![CDATA[# 📖 GGLang — Complete Language Documentation
+
+> **Version 1.0** · The Gaming-Themed Programming Language
+
+---
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Language Basics](#language-basics)
+3. [Variables & Constants](#variables--constants)
+4. [Data Types](#data-types)
+5. [Operators](#operators)
+6. [Control Flow](#control-flow)
+7. [Loops](#loops)
+8. [Functions](#functions)
+9. [Input / Output](#input--output)
+10. [Error Handling](#error-handling)
+11. [Complete Example Programs](#complete-example-programs)
+12. [Keyword Reference Table](#keyword-reference-table)
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd toy-programming-language
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+### Running a GGLang File
+
+GGLang source files use the `.gg` extension. To run a program:
+
+```bash
+npm start -- path/to/your/program.gg
+```
+
+For example:
+
+```bash
+npm start -- examples/hello.gg
+```
+
+### Using the REPL
+
+Launch the interactive Read-Eval-Print Loop by running without arguments:
+
+```bash
+npm start
+```
+
+In the REPL, you can type GGLang expressions and statements directly and see results immediately. Type `exit` or press `Ctrl+C` to quit.
+
+---
+
+## Language Basics
+
+### Program Structure
+
+Every GGLang program is wrapped in a `spawn { }` block. This is the entry point — like a player spawning into the game world.
+
+```
+spawn {
+  // Your code goes here
+}
+```
+
+Everything outside `spawn { }` is ignored. You must have exactly one `spawn` block.
+
+### Comments
+
+GGLang supports two styles of comments:
+
+```
+// This is a single-line comment
+
+/*
+  This is a
+  multi-line comment
+*/
+```
+
+### Semicolons
+
+Statements must end with a semicolon (`;`).
+
+```
+equip x = 10;       // ✅ Correct
+broadcast("hello"); // ✅ Correct
+equip y = 20        // ❌ Missing semicolon
+```
+
+### Blocks
+
+Code blocks are delimited by curly braces `{ }`. They are used with control flow statements, loops, functions, and error handling.
+
+```
+quest (x > 0) {
+  broadcast("positive");
+}
+```
+
+---
+
+## Variables & Constants
+
+### Variables: `equip`
+
+Use `equip` to declare a mutable variable — like equipping an item to your inventory.
+
+```
+spawn {
+  equip health = 100;
+  equip playerName = "Hero";
+  equip isAlive = victory;
+
+  // Variables can be reassigned
+  health = 75;
+  playerName = "Champion";
+}
+```
+
+Variables must be initialized at declaration. They can be reassigned at any time.
+
+### Constants: `artifact`
+
+Use `artifact` to declare an immutable constant — artifacts are permanent relics that never change.
+
+```
+spawn {
+  artifact maxHealth = 100;
+  artifact gameName = "Dungeon Quest";
+  artifact PI = 3.14159;
+
+  // maxHealth = 200;  // ❌ Error! Artifacts cannot be reassigned
+}
+```
+
+### Scope
+
+Variables and constants are block-scoped. A variable declared inside a block is only accessible within that block and its nested blocks.
+
+```
+spawn {
+  equip outer = "I'm outside";
+
+  quest (victory) {
+    equip inner = "I'm inside";
+    broadcast(outer);  // ✅ Can access outer variable
+    broadcast(inner);  // ✅ Can access inner variable
+  }
+
+  broadcast(outer);    // ✅ Still accessible
+  // broadcast(inner); // ❌ Error! inner is not defined here
+}
+```
+
+---
+
+## Data Types
+
+GGLang supports four primitive data types:
+
+### Numbers
+
+Integer and floating-point numbers. No distinction between the two.
+
+```
+spawn {
+  equip age = 25;
+  equip pi = 3.14159;
+  equip negative = -42;
+  equip zero = 0;
+}
+```
+
+### Strings
+
+Text enclosed in double quotes (`"`) or single quotes (`'`). Strings can be concatenated with `+`.
+
+```
+spawn {
+  equip greeting = "Hello, World!";
+  equip name = 'GGLang';
+  equip full = greeting + " Welcome to " + name + "!";
+
+  // Numbers are auto-converted when concatenated with strings
+  equip level = 5;
+  broadcast("You are level " + level);  // "You are level 5"
+}
+```
+
+### Booleans
+
+`victory` for true, `defeat` for false.
+
+```
+spawn {
+  equip isWinning = victory;
+  equip isGameOver = defeat;
+
+  quest (isWinning) {
+    broadcast("You're winning!");
+  }
+}
+```
+
+### Null
+
+`phantom` represents the absence of a value — like a phantom, there's nothing there.
+
+```
+spawn {
+  equip result = phantom;
+
+  quest (result == phantom) {
+    broadcast("Nothing here... 👻");
+  }
+}
+```
+
+---
+
+## Operators
+
+### Arithmetic Operators
+
+| Operator | Description    | Example       | Result |
+|----------|--------------- |---------------|--------|
+| `+`      | Addition       | `10 + 3`      | `13`   |
+| `-`      | Subtraction    | `10 - 3`      | `7`    |
+| `*`      | Multiplication | `10 * 3`      | `30`   |
+| `/`      | Division       | `10 / 3`      | `3.33…`|
+| `%`      | Modulo         | `10 % 3`      | `1`    |
+
+The `+` operator also works for string concatenation:
+
+```
+"Hello" + " " + "World"   // "Hello World"
+"Level: " + 5             // "Level: 5"
+```
+
+### Comparison Operators
+
+| Operator | Description           | Example    | Result    |
+|----------|-----------------------|------------|-----------|
+| `==`     | Equal to              | `5 == 5`   | `victory` |
+| `!=`     | Not equal to          | `5 != 3`   | `victory` |
+| `>`      | Greater than          | `5 > 3`    | `victory` |
+| `<`      | Less than             | `5 < 3`    | `defeat`  |
+| `>=`     | Greater than or equal | `5 >= 5`   | `victory` |
+| `<=`     | Less than or equal    | `3 <= 5`   | `victory` |
+
+### Logical Operators
+
+| Operator | Description | Example                    | Result    |
+|----------|-------------|----------------------------|-----------|
+| `&&`     | Logical AND | `victory && defeat`        | `defeat`  |
+| `\|\|`   | Logical OR  | `victory \|\| defeat`      | `victory` |
+| `!`      | Logical NOT | `!defeat`                  | `victory` |
+
+### Assignment Operators
+
+| Operator | Description         | Equivalent To |
+|----------|---------------------|---------------|
+| `=`      | Assignment          | `x = 5`       |
+| `+=`     | Add and assign      | `x = x + 5`  |
+| `-=`     | Subtract and assign | `x = x - 5`  |
+| `*=`     | Multiply and assign | `x = x * 5`  |
+| `/=`     | Divide and assign   | `x = x / 5`  |
+
+```
+spawn {
+  equip score = 0;
+  score += 10;    // score is now 10
+  score *= 2;     // score is now 20
+  score -= 5;     // score is now 15
+  score /= 3;     // score is now 5
+}
+```
+
+### Operator Precedence
+
+From **highest** to **lowest** precedence:
+
+| Precedence | Operators           | Description          |
+|------------|---------------------|----------------------|
+| 1 (highest)| `!`, unary `-`      | Logical NOT, negation |
+| 2          | `*`, `/`, `%`       | Multiplication, Division, Modulo |
+| 3          | `+`, `-`            | Addition, Subtraction |
+| 4          | `>`, `<`, `>=`, `<=`| Comparison           |
+| 5          | `==`, `!=`          | Equality             |
+| 6          | `&&`                | Logical AND          |
+| 7 (lowest) | `\|\|`              | Logical OR           |
+
+Use parentheses `( )` to override precedence:
+
+```
+equip result = (2 + 3) * 4;   // 20, not 14
+```
+
+---
+
+## Control Flow
+
+### `quest` (if)
+
+Execute a block of code when a condition is `victory` (true).
+
+```
+spawn {
+  equip health = 75;
+
+  quest (health > 50) {
+    broadcast("You're doing fine!");
+  }
+}
+```
+
+### `side_quest` (else if)
+
+Check additional conditions when the previous `quest` or `side_quest` was `defeat` (false).
+
+```
+spawn {
+  equip score = 85;
+
+  quest (score >= 90) {
+    broadcast("S Rank! 🌟");
+  } side_quest (score >= 80) {
+    broadcast("A Rank! ⭐");
+  } side_quest (score >= 70) {
+    broadcast("B Rank");
+  } side_quest (score >= 60) {
+    broadcast("C Rank");
+  }
+}
+```
+
+### `retreat` (else)
+
+The fallback block when all previous conditions are `defeat`.
+
+```
+spawn {
+  equip level = 3;
+
+  quest (level >= 10) {
+    broadcast("You are a veteran!");
+  } side_quest (level >= 5) {
+    broadcast("You are experienced.");
+  } retreat {
+    broadcast("You are a beginner.");
+  }
+}
+```
+
+### Nesting
+
+Control flow statements can be nested:
+
+```
+spawn {
+  equip class = "mage";
+  equip level = 15;
+
+  quest (class == "mage") {
+    quest (level >= 10) {
+      broadcast("You can cast Fireball! 🔥");
+    } retreat {
+      broadcast("Keep training your magic...");
+    }
+  } side_quest (class == "warrior") {
+    broadcast("Swing that sword! ⚔️");
+  }
+}
+```
+
+---
+
+## Loops
+
+### `grind` (while)
+
+Repeat a block of code as long as a condition is `victory` (true). Perfect for grinding levels.
+
+```
+spawn {
+  equip level = 1;
+
+  grind (level <= 10) {
+    broadcast("Level " + level + " reached!");
+    level += 1;
+  }
+
+  broadcast("Max level! 🎉");
+}
+```
+
+### `rage_quit` (break)
+
+Exit a loop immediately — you've had enough.
+
+```
+spawn {
+  equip attempts = 0;
+
+  grind (victory) {  // Infinite loop
+    attempts += 1;
+    broadcast("Attempt #" + attempts);
+
+    quest (attempts >= 5) {
+      broadcast("That's it, I'm done!");
+      rage_quit;
+    }
+  }
+
+  broadcast("Rage quit after " + attempts + " attempts.");
+}
+```
+
+### `respawn` (continue)
+
+Skip the rest of the current iteration and jump to the next one — like respawning to try again.
+
+```
+spawn {
+  equip i = 0;
+
+  grind (i < 10) {
+    i += 1;
+
+    // Skip even numbers
+    quest (i % 2 == 0) {
+      respawn;
+    }
+
+    broadcast(i);  // Only prints odd numbers: 1, 3, 5, 7, 9
+  }
+}
+```
+
+### Loop Patterns
+
+**Counting loop:**
+```
+equip i = 0;
+grind (i < 10) {
+  // do something
+  i += 1;
+}
+```
+
+**Sentinel loop (until condition):**
+```
+equip input = "";
+grind (input != "quit") {
+  input = interact("Enter command (or 'quit'): ");
+  broadcast("You entered: " + input);
+}
+```
+
+**Infinite loop with break:**
+```
+grind (victory) {
+  // do something
+  quest (someCondition) {
+    rage_quit;
+  }
+}
+```
+
+---
+
+## Functions
+
+### `skill` (function)
+
+Define reusable skills (functions) with `skill`. Functions can accept parameters and return values.
+
+```
+spawn {
+  skill greet(name) {
+    broadcast("Hello, " + name + "! 👋");
+  }
+
+  greet("Player");    // "Hello, Player! 👋"
+  greet("GGLang");    // "Hello, GGLang! 👋"
+}
+```
+
+### `loot` (return)
+
+Return a value from a skill using `loot` — the reward for executing the skill.
+
+```
+spawn {
+  skill add(a, b) {
+    loot a + b;
+  }
+
+  skill square(n) {
+    loot n * n;
+  }
+
+  equip sum = add(3, 4);         // 7
+  equip squared = square(5);     // 25
+  broadcast(add(10, square(3))); // 19
+}
+```
+
+### Multiple Parameters
+
+Functions can take any number of parameters:
+
+```
+spawn {
+  skill calculateDamage(base, level, multiplier) {
+    loot base + (level * multiplier);
+  }
+
+  equip damage = calculateDamage(10, 5, 1.5);
+  broadcast("Damage dealt: " + damage);  // "Damage dealt: 17.5"
+}
+```
+
+### Early Return
+
+`loot` immediately exits the function, like returning loot and leaving the dungeon:
+
+```
+spawn {
+  skill absoluteValue(n) {
+    quest (n < 0) {
+      loot -n;
+    }
+    loot n;
+  }
+
+  broadcast(absoluteValue(-42));  // 42
+  broadcast(absoluteValue(7));    // 7
+}
+```
+
+### Recursion
+
+Skills can call themselves — perfect for recursive algorithms:
+
+```
+spawn {
+  // Factorial using recursion
+  skill factorial(n) {
+    quest (n <= 1) {
+      loot 1;
+    }
+    loot n * factorial(n - 1);
+  }
+
+  broadcast("5! = " + factorial(5));   // "5! = 120"
+  broadcast("10! = " + factorial(10)); // "10! = 3628800"
+}
+```
+
+### Functions Without Return
+
+If a skill doesn't use `loot`, it implicitly returns `phantom`:
+
+```
+spawn {
+  skill sayHello() {
+    broadcast("Hello!");
+  }
+
+  equip result = sayHello();
+  broadcast(result);  // phantom
+}
+```
+
+---
+
+## Input / Output
+
+### `broadcast` (print)
+
+Output a value to the console. Accepts any data type.
+
+```
+spawn {
+  broadcast("Hello, World!");       // String
+  broadcast(42);                    // Number
+  broadcast(victory);              // Boolean
+  broadcast(3 + 4);                // Expression result
+  broadcast("Score: " + 100);      // String concatenation
+}
+```
+
+### `interact` (input)
+
+Read input from the user. `interact` takes an optional prompt string and returns the user's input as a string.
+
+```
+spawn {
+  equip name = interact("What is your name? ");
+  equip age = interact("How old are you? ");
+
+  broadcast("Hello, " + name + "! You are " + age + " years old.");
+}
+```
+
+> **Note:** `interact` always returns a **string**. If you need a number, you may need to use it in an arithmetic context where auto-conversion occurs.
+
+---
+
+## Error Handling
+
+### `boss_fight` / `revive` (try / catch)
+
+Wrap risky code in a `boss_fight` block. If a `glitch` (error) is thrown, execution jumps to the `revive` block.
+
+```
+spawn {
+  boss_fight {
+    broadcast("Entering the boss room...");
+    glitch "The boss is too powerful!";
+    broadcast("This line never executes.");
+  } revive (error) {
+    broadcast("Caught a glitch: " + error);
+  }
+
+  broadcast("Game continues after recovery.");
+}
+```
+
+**Output:**
+```
+Entering the boss room...
+Caught a glitch: The boss is too powerful!
+Game continues after recovery.
+```
+
+### `glitch` (throw)
+
+Throw an error with a message. This immediately exits the current execution and jumps to the nearest `revive` block.
+
+```
+spawn {
+  skill divide(a, b) {
+    quest (b == 0) {
+      glitch "Cannot divide by zero!";
+    }
+    loot a / b;
+  }
+
+  boss_fight {
+    broadcast(divide(10, 2));   // 5
+    broadcast(divide(10, 0));   // Throws!
+  } revive (err) {
+    broadcast("Error: " + err);
+  }
+}
+```
+
+### Nested Error Handling
+
+`boss_fight` blocks can be nested. The innermost `revive` catches the error:
+
+```
+spawn {
+  boss_fight {
+    broadcast("Outer boss fight...");
+
+    boss_fight {
+      broadcast("Inner boss fight...");
+      glitch "Inner glitch!";
+    } revive (e) {
+      broadcast("Inner revive caught: " + e);
+    }
+
+    broadcast("Outer continues normally.");
+  } revive (e) {
+    broadcast("Outer revive caught: " + e);
+  }
+}
+```
+
+**Output:**
+```
+Outer boss fight...
+Inner boss fight...
+Inner revive caught: Inner glitch!
+Outer continues normally.
+```
+
+### Unhandled Glitches
+
+If a `glitch` is thrown outside of any `boss_fight`, the program crashes with an error message:
+
+```
+spawn {
+  glitch "Fatal error!";
+  // Program terminates here
+}
+```
+
+---
+
+## Complete Example Programs
+
+### Hello World
+
+```
+// hello.gg — Your first GGLang program
+spawn {
+  broadcast("Hello, World!");
+  broadcast("Welcome to GGLang! 🎮");
+}
+```
+
+### FizzBuzz
+
+```
+// fizzbuzz.gg — The classic interview question, GGLang style
+spawn {
+  equip i = 1;
+  grind (i <= 30) {
+    quest (i % 15 == 0) {
+      broadcast("FizzBuzz");
+    } side_quest (i % 3 == 0) {
+      broadcast("Fizz");
+    } side_quest (i % 5 == 0) {
+      broadcast("Buzz");
+    } retreat {
+      broadcast(i);
+    }
+    i = i + 1;
+  }
+}
+```
+
+### Fibonacci (Recursive)
+
+```
+// fibonacci.gg — Fibonacci with recursion
+spawn {
+  skill fibonacci(n) {
+    quest (n <= 1) {
+      loot n;
+    }
+    loot fibonacci(n - 1) + fibonacci(n - 2);
+  }
+
+  equip i = 0;
+  grind (i <= 15) {
+    broadcast("fibonacci(" + i + ") = " + fibonacci(i));
+    i = i + 1;
+  }
+}
+```
+
+### Number Guessing Game
+
+```
+// guess.gg — Guess the secret number
+spawn {
+  artifact secret = 7;
+  artifact maxAttempts = 5;
+
+  broadcast("🎮 Guess the number between 1 and 10!");
+  broadcast("You have " + maxAttempts + " attempts.");
+
+  equip attempts = 0;
+  equip won = defeat;
+
+  grind (attempts < maxAttempts && won == defeat) {
+    attempts += 1;
+    equip guess = interact("Attempt " + attempts + "/" + maxAttempts + " — Enter your guess: ");
+
+    quest (guess == secret) {
+      broadcast("🎉 Correct! You won in " + attempts + " attempts!");
+      won = victory;
+    } side_quest (guess < secret) {
+      broadcast("📈 Too low! Try higher.");
+    } retreat {
+      broadcast("📉 Too high! Try lower.");
+    }
+  }
+
+  quest (won == defeat) {
+    broadcast("💀 Game over! The number was " + secret + ".");
+  }
+}
+```
+
+### Calculator
+
+```
+// calculator.gg — A simple calculator
+spawn {
+  skill calculate(a, op, b) {
+    quest (op == "+") {
+      loot a + b;
+    } side_quest (op == "-") {
+      loot a - b;
+    } side_quest (op == "*") {
+      loot a * b;
+    } side_quest (op == "/") {
+      quest (b == 0) {
+        glitch "Division by zero!";
+      }
+      loot a / b;
+    } side_quest (op == "%") {
+      loot a % b;
+    } retreat {
+      glitch "Unknown operator: " + op;
+    }
+  }
+
+  broadcast("🧮 GGLang Calculator");
+  broadcast("Type 'quit' to exit.");
+
+  grind (victory) {
+    equip a = interact("Enter first number (or 'quit'): ");
+    quest (a == "quit") {
+      rage_quit;
+    }
+
+    equip op = interact("Enter operator (+, -, *, /, %): ");
+    equip b = interact("Enter second number: ");
+
+    boss_fight {
+      equip result = calculate(a, op, b);
+      broadcast("📊 Result: " + a + " " + op + " " + b + " = " + result);
+    } revive (err) {
+      broadcast("❌ Error: " + err);
+    }
+  }
+
+  broadcast("Thanks for calculating! GG 🎮");
+}
+```
+
+---
+
+## Keyword Reference Table
+
+| GGLang Keyword | Traditional Equivalent | Description |
+|---|---|---|
+| `spawn { }` | `main()` / program start | Entry point — player spawns into the game |
+| `equip` | `let` / `var` | Declare a mutable variable |
+| `artifact` | `const` | Declare an immutable constant |
+| `broadcast` | `print` / `console.log` | Output a value to the console |
+| `interact("…")` | `input` / `readline` | Read user input (returns string) |
+| `quest` | `if` | Conditional — embark on a quest |
+| `side_quest` | `else if` | Alternative conditional path |
+| `retreat` | `else` | Fallback when all conditions fail |
+| `grind` | `while` | Loop — keep grinding |
+| `rage_quit` | `break` | Exit the loop immediately |
+| `respawn` | `continue` | Skip to the next loop iteration |
+| `skill` | `function` | Define a reusable function |
+| `loot` | `return` | Return a value from a function |
+| `victory` | `true` | Boolean true |
+| `defeat` | `false` | Boolean false |
+| `phantom` | `null` | Absence of a value |
+| `boss_fight` | `try` | Attempt risky code |
+| `revive` | `catch` | Handle an error |
+| `glitch` | `throw` | Throw an error |
+
+---
+
+## Supported Operators — Quick Reference
+
+| Category | Operators |
+|---|---|
+| **Arithmetic** | `+` `-` `*` `/` `%` |
+| **Comparison** | `==` `!=` `>` `<` `>=` `<=` |
+| **Logical** | `&&` `\|\|` `!` |
+| **Assignment** | `=` `+=` `-=` `*=` `/=` |
+
+---
+
+## File Extension
+
+All GGLang source files use the `.gg` extension.
+
+```
+my_program.gg
+hello.gg
+adventure.gg
+```
+
+---
+
+*GG! 🎮 — Happy coding with GGLang!*
+]]>