Gem Documentation

# Clone the repository
git clone https://github.com/SimuCorps/Gem.git
cd Gem

# Build Gem with standard library (recommended)
make

# Or build without standard library for minimal installation
make no-stl

# Install system-wide (optional)
sudo make install

# hello.gem - Your first Gem program
puts "Hello, World!"

# Variables with type safety
string name = "Gem"
int version = 1

puts "Welcome to #{name} v#{version}!"

# Functions
def greet(string person) string
    return "Hello, #{person}!"
end

puts greet("Developer")

# Run your program
./gemc hello.gem

# Start the interactive shell
./gemc

# Basic types
int age = 25
string name = "Alice"
bool isActive = true

# Type errors are caught at compile time
# age = "not a number"  # ❌ Error!

# Immutable by default
string message = "Hello"

# Mutable with 'mut' keyword (recommended)
mut string mutableMessage = "Hello"
mutableMessage = "Changed!"

# Mutable with '!' suffix (alternative)
string! altMutableMessage = "Hello"
altMutableMessage = "Changed!"

# Nullable variable
string? optionalName = nil
optionalName = "Alice"

# Must check before use
if (optionalName != nil)
    puts "Hello, #{optionalName}!"
end

# Function with parameters and return type
def add(int a, int b) int
    return a + b
end

# Function with no return value
def greet(string name) void
    puts "Hello, #{name}!"
end

# Comments start with #
# This is a simple Gem program

# Variable declarations
string message = "Hello, World!"
int count = 42

# Function definition
def greet(string name) string
    return "Hello, #{name}!"
end

# Main execution
puts message
puts greet("Gem")

# Newline-terminated statements (recommended)
string name = "Alice"
int age = 30
puts "Hello, " + name

# Semicolon-terminated statements (traditional)
string name = "Alice";
int age = 30;
puts "Hello, " + name;

# Mixed style (both work)
string name = "Alice"
int age = 30;
puts "Hello, " + name

# Multiple statements on one line require semicolons
int x = 10; int y = 20; puts x + y

# This would be an error:
# int x = 10 int y = 20 puts x + y  # ❌ Error

# Prefer separate lines for better readability:
int x = 10
int y = 20
puts x + y

# Primitive types
int number = 42;           # Integer numbers
string text = "Hello";     # Text strings
bool flag = true;          # Boolean values (true/false)

# Special types
void                       # Used for functions that don't return a value
func                       # Function type for first-class functions
obj                        # Object type for class instances

# Mutability with 'mut' keyword (recommended)
mut string mutableText = "Can change";     # Mutable variable
mutableText = "Changed!";                  # ✅ Valid

# Mutability with '!' suffix (syntactic sugar)
string! alsoMutable = "Can change";        # Alternative syntax
alsoMutable = "Changed!";                  # ✅ Valid

# Nullability modifier (?)
string? optionalText = nil;                # Can be nil
optionalText = "Some text";                # ✅ Valid
optionalText = nil;                        # ✅ Valid

# Combined: mutable and nullable
mut string? mutableOptional = nil;         # Recommended syntax
string?! alsoMutableOptional = nil;        # Alternative syntax
mutableOptional = "Text";                  # ✅ Valid
mutableOptional = nil;                     # ✅ Valid

# Hash declaration with explicit mutability
hash! userInfo = {"name": "Alice", "age": 30, "active": true};

# Immutable hash (read-only after creation)
hash readonlyData = {"version": "1.0", "stable": true};

# Empty hash
hash! emptyHash = {};

# Access values using bracket notation
hash! person = {"name": "Bob", "age": 25, "city": "New York"};

string name = person["name"] as string;     # "Bob"
int age = person["age"] as int;             # 25
string city = person["city"] as string;    # "New York"

# Non-existent keys return nil
string missing = person["missing"] as string;  # "nil"

# Only mutable hashes can be modified
hash! mutableHash = {"count": 0, "status": "pending"};

# Update existing values
mutableHash["count"] = 5;
mutableHash["status"] = "completed";

# Add new key-value pairs
mutableHash["timestamp"] = "2025-01-01";

# This would be an error with immutable hash:
# hash immutableHash = {"key": "value"};
# immutableHash["key"] = "new value";  # ❌ Error: Cannot modify immutable hash

# String keys (most common)
hash! stringKeys = {"name": "Alice", "role": "admin"};

# Numeric keys (automatically converted to strings)
hash! numericKeys = {1: "first", 2: "second", 42: "answer"};

# Mixed keys
hash! mixedKeys = {"name": "Bob", 1: "first", "active": true};

# Number to string conversion
int number = 42;
string numberStr = number as string;        # "42"

# String to number conversion
string numericStr = "123";
int parsed = numericStr as int;             # 123

# Decimal strings are converted to their numeric value
string decimalStr = "3.14159";
int decimal = decimalStr as int;            # 3.14159

# Boolean to string conversion
bool isActive = true;
string activeStr = isActive as string;     # "true"

# Nil to string conversion
string nilStr = nil as string;             # "nil"

# Numbers are truthy (including zero!)
int zero = 0;
int negative = -5;
int positive = 42;

bool zeroIsTruthy = zero as bool;           # true
bool negativeIsTruthy = negative as bool;   # true
bool positiveIsTruthy = positive as bool;   # true

# Strings are truthy (including empty strings!)
string empty = "";
string nonEmpty = "hello";

bool emptyIsTruthy = empty as bool;         # true
bool nonEmptyIsTruthy = nonEmpty as bool;   # true

# Only false and nil are falsey
bool stillFalse = false as bool;            # false
bool stillNil = nil as bool;                # false (nil converts to false)

# Extract and convert hash values
hash! userData = {"name": "Charlie", "age": 28, "score": 0, "active": true};

# Extract with type coercion
string name = userData["name"] as string;
int age = userData["age"] as int;
bool active = userData["active"] as bool;

# Zero from hash is still truthy
bool scoreActive = userData["score"] as bool;  # true (0 is truthy!)

# Missing keys return nil, which converts to "nil" string or false boolean
string missing = userData["missing"] as string;  # "nil"
bool missingBool = userData["missing"] as bool;  # false

# Casting to the same type (no-op, but sometimes useful for clarity)
string alreadyString = "test";
string stillString = alreadyString as string;  # "test"

int alreadyInt = 100;
int stillInt = alreadyInt as int;              # 100

bool alreadyBool = true;
bool stillBool = alreadyBool as bool;          # true

# Recommended syntax with 'mut' keyword
int age = 25;                        # Immutable integer
mut string name = "Alice";           # Mutable string
bool? isActive = nil;                # Nullable boolean
mut string? status = "pending";      # Mutable and nullable

# Alternative syntax with '!' suffix (syntactic sugar)
string! altName = "Bob";             # Mutable string (alternative)
string?! altStatus = "active";       # Mutable and nullable (alternative)

# Variables are scoped to their declaration block
int x = 10;

begin
    int y = 20;
    puts x;  # ✅ Valid: x is in scope
    puts y;  # ✅ Valid: y is in scope
end

puts x;  # ✅ Valid: x is still in scope
# puts y;  # ❌ Error: y is out of scope

# Immutable variables (default)
string greeting = "Hello";
# greeting = "Hi";  # ❌ Error: Cannot modify immutable variable

# Mutable variables (recommended syntax)
mut string mutableGreeting = "Hello";
mutableGreeting = "Hi";  # ✅ Valid: Variable is mutable

# Mutable variables (alternative syntax with '!' suffix)
string! altMutableGreeting = "Hello";
altMutableGreeting = "Hi";  # ✅ Valid: Variable is mutable

# Function parameters are immutable by default
def processText(string text) string
    # text = "modified";  # ❌ Error: Parameter is immutable
    return "Processed: " + text;
end

# Basic function syntax
def functionName(type param1, type param2) returnType
    # function body
    return value;
end

# Examples
def add(int x, int y) int
    return x + y;
end

def greet(string name) string
    return "Hello, #{name}!";
end

def printMessage(string message) void
    puts message;
    # void functions don't need explicit return
end

# Parameters with different modifiers
def processData(
    string data,               # Immutable parameter
    mut string buffer,         # Mutable parameter (recommended)
    string? optional,          # Nullable parameter
    mut string? mutableOpt     # Mutable and nullable (recommended)
) string
    if (optional != nil)
        buffer = buffer + optional;
    end
    return buffer + data;
end

# Alternative syntax with '!' suffix
def processDataAlt(
    string data,               # Immutable parameter
    string! buffer,            # Mutable parameter (alternative)
    string? optional,          # Nullable parameter
    string?! mutableOpt        # Mutable and nullable (alternative)
) string
    if (optional != nil)
        buffer = buffer + optional;
    end
    return buffer + data;
end

# Functions as parameters
def applyOperation(int x, int y, func operation) int
    return operation(x, y);
end

def multiply(int a, int b) int
    return a * b;
end

# Usage
int result = applyOperation(5, 3, multiply);  # 15

# Basic class structure
class ClassName
    # Constructor
    def init(parameters) void
        # Initialize instance variables
    end
    
    # Methods
    def methodName(parameters) returnType
        # method body
    end
end

# Example
class Person
    def init(string name, int age) void
        this.name = name;
        this.age = age;
    end
    
    def getName() string
        return this.name;
    end
    
    def getAge() int
        return this.age;
    end
    
    def introduce() string
        return "Hi, I'm " + this.name + ", age " + this.age;
    end
end

# Creating objects
obj person = Person("Alice", 30);

# Calling methods
string name = person.getName();
string intro = person.introduce();
puts intro;  # "Hi, I'm Alice, age 30"

# Base class
class Animal
    def init(string name) void
        this.name = name;
    end
    
    def speak() string
        return "Some sound";
    end
end

# Derived class
class Dog : Animal
    def init(string name, string breed) void
        super.init(name);  # Call parent constructor
        this.breed = breed;
    end
    
    def speak() string  # Override parent method
        return "Woof!";
    end
    
    def getBreed() string
        return this.breed;
    end
end

# Usage
obj dog = Dog("Buddy", "Labrador");
puts dog.speak();     # "Woof!"
puts dog.getBreed();  # "Labrador"

# if-else statements
if (condition)
    # code block
else if (otherCondition)
    # code block
else
    # code block
end

# Example
int age = 20;
if (age >= 18)
    puts "Adult";
else
    puts "Minor";
end

# Ternary operator
string status = age >= 18 ? "Adult" : "Minor";

# For loops
for (int! i = 0; i < 10; i = i + 1)
    puts i;
end

# While loops
int! count = 0;
while (count < 5)
    puts "Count: " + count;
    count = count + 1;
end

# Loop with break and continue
for (int! i = 0; i < 20; i = i + 1)
    if (i % 2 == 0)
        continue;  # Skip even numbers
    end
    
    if (i > 15)
        break;     # Exit loop
    end
    
    puts i;
end

# math_utils.gem
module MathUtils
    def square(int x) int
        return x * x;
    end
    
    def cube(int x) int
        return x * x * x;
    end
    
    def factorial(int n) int
        if (n <= 1)
            return 1;
        else
            return n * factorial(n - 1);
        end
    end
end

# Import and use modules
require "math_utils";

int squared = MathUtils.square(5);      # 25
int cubed = MathUtils.cube(3);          # 27
int fact = MathUtils.factorial(5);      # 120

# Built-in modules
require "math";

# Math utilities
int sum = Math.add(10, 5);
int max = Math.max(10, 20);
int power = Math.power(2, 8);

# Objects are automatically cleaned up when scope ends
def processData() void
    begin
        obj resource = DataResource("file.txt");
        resource.process();
        # resource is automatically cleaned up here
    end
    # resource is no longer accessible
end

# Gem prevents use-after-drop at compile time
def borrowExample() void
    obj resource = SomeResource("data");
    
    begin
        # resource is borrowed here
        string some_variable = resource.process()
    end
    
    puts some_variable;  # ❌ Compile error: use after potential drop
end

# String concatenation (built-in)
string combined = "Hello" + " World";  # Returns "Hello World"

# String literals
string greeting = "Hello, Gem!";
string empty = "";

# Import math module
require "math";

# Import HTTP module
require "http";

# Use imported modules
int sum = Math.add(10, 5);
hash response = Http.get("https://api.example.com");

require "math";

# Basic operations
int sum = Math.add(10, 5);           # Returns 15
int difference = Math.subtract(10, 5); # Returns 5
int product = Math.multiply(10, 5);   # Returns 50
int quotient = Math.divide(10, 5);    # Returns 2
int remainder = Math.modulo(10, 3);   # Returns 1

# Exponentiation
int squared = Math.power(5, 2);      # Returns 25
int cubed = Math.power(3, 3);        # Returns 27
int power = Math.power(2, 8);        # Returns 256

# Min/Max operations
int minimum = Math.min(10, 5);       # Returns 5
int maximum = Math.max(10, 5);       # Returns 10

# Absolute value
int abs1 = Math.abs(-5);             # Returns 5
int abs2 = Math.abs(5);              # Returns 5
int abs3 = Math.abs(0);              # Returns 0

# Complete Math module API
Math.add(int a, int b) int              # Addition
Math.subtract(int a, int b) int         # Subtraction
Math.multiply(int a, int b) int         # Multiplication
Math.divide(int a, int b) int           # Division
Math.modulo(int a, int b) int           # Modulo operation
Math.power(int base, int exp) int       # Exponentiation
Math.abs(int x) int                     # Absolute value
Math.min(int a, int b) int              # Minimum of two values
Math.max(int a, int b) int              # Maximum of two values

require "http";

# Simple GET request
hash response = Http.get("https://api.example.com/data");

# Check if request was successful
bool success = response["success"] as bool;
int status = response["status"] as int;
string body = response["body"] as string;

if (success)
    puts "Request successful!";
    puts "Status: " + status;
    puts "Response: " + body;
else
    puts "Request failed with status: " + status;
end

# GET request with custom headers
hash headers = {};
headers["Authorization"] = "Bearer your-token-here";
headers["Content-Type"] = "application/json";
headers["User-Agent"] = "MyApp/1.0";

hash response = Http.get("https://api.example.com/protected", headers);

# Access response details
bool success = response["success"] as bool;
int status = response["status"] as int;
string body = response["body"] as string;
int responseTime = response["response_time"] as int;

# POST request with form data
hash data = {};
data["name"] = "John Doe";
data["email"] = "john@example.com";
data["age"] = "30";

hash response = Http.post("https://api.example.com/users", data);

if (response["success"] as bool)
    puts "User created successfully!";
    puts "Response: " + (response["body"] as string);
end

# POST request with JSON data and custom headers
hash headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = "Bearer token123";

hash jsonData = {};
jsonData["title"] = "New Post";
jsonData["content"] = "This is the post content";
jsonData["published"] = "true";

hash response = Http.post("https://api.example.com/posts", jsonData, headers);

# Check response
bool success = response["success"] as bool;
int status = response["status"] as int;

if (success)
    puts "Post created! Status: " + status;
else
    puts "Failed to create post. Status: " + status;
end

# PUT request to update a resource
hash updateData = {};
updateData["name"] = "Jane Doe";
updateData["email"] = "jane@example.com";

hash headers = {};
headers["Content-Type"] = "application/json";

hash response = Http.put("https://api.example.com/users/123", updateData, headers);

if (response["success"] as bool)
    puts "User updated successfully!";
    puts "Response time: " + (response["response_time"] as int) + "ms";
end

# DELETE request with authorization
hash headers = {};
headers["Authorization"] = "Bearer admin-token";

hash response = Http.delete("https://api.example.com/users/123", headers);

bool success = response["success"] as bool;
int status = response["status"] as int;

if (success)
    puts "Resource deleted successfully!";
else
    puts "Failed to delete resource. Status: " + status;
end

# Comprehensive error handling
hash response = Http.get("https://invalid-url-example.com");

bool success = response["success"] as bool;
int status = response["status"] as int;

if (!success)
    if (status == 0)
        puts "Network error or invalid URL";
    elsif (status == 404)
        puts "Resource not found";
    elsif (status == 500)
        puts "Server error";
    else
        puts "Request failed with status: " + status;
    end
else
    puts "Request successful!";
    string body = response["body"] as string;
    puts "Response: " + body;
end

# Complete HTTP module API

# GET requests
Http.get(string url) hash                           # Simple GET
Http.get(string url, hash headers) hash             # GET with headers

# POST requests  
Http.post(string url, hash data) hash               # POST with data
Http.post(string url, hash data, hash headers) hash # POST with data and headers

# PUT requests
Http.put(string url, hash data) hash                # PUT with data
Http.put(string url, hash data, hash headers) hash  # PUT with data and headers

# DELETE requests
Http.delete(string url) hash                        # Simple DELETE
Http.delete(string url, hash headers) hash          # DELETE with headers

# Response hash structure:
# {
#   "success": bool,        # Whether request succeeded
#   "status": int,          # HTTP status code (0 for network errors)
#   "body": string,         # Response body content
#   "response_time": int    # Response time in microseconds
# }

require "time";

# Get current time as floating-point timestamp
puts "Current timestamp: #{Time.now()}";

# Sleep for a specified number of milliseconds
puts "Starting operation...";
Time.sleep(2000);  # Sleep for 2 seconds (2000 milliseconds)
puts "Operation completed after delay";

# Measure execution time of a function
def slowOperation() void
    Time.sleep(1000);  # Sleep for 1 second (1000 milliseconds)
    puts "Slow operation completed";
end

# Measure function execution
Time.measure(slowOperation);

# Attempt to run function with timeout
def quickOperation() void
    puts "Quick operation";
end

def slowOperation() void
    Time.sleep(5000);  # Sleep for 5 seconds (5000 milliseconds)
    puts "This takes too long";
end

Time.timeout(quickOperation, 2);  # 2 second timeout
Time.timeout(slowOperation, 2);   # 2 second timeout

# Simple timing and sleep operations
def timedWork() void
    puts "Starting work...";
    Time.sleep(1500);  # 1.5 seconds of work
    puts "Work completed";
end

# Measure the work
puts "Timing work operation:";
Time.measure(timedWork);

# Multiple sleep operations
puts "Sleep sequence:";
Time.sleep(500);   # 0.5 seconds
puts "Step 1 complete";
Time.sleep(1000);  # 1.0 seconds  
puts "Step 2 complete";
Time.sleep(750);   # 0.75 seconds
puts "All steps complete";