Add math_mod command and enhance return control in interpreter state

- Implemented `math_mod` function in MathOpsHandler to handle modulo operations.
- Updated BasicCommandHandler to include `math_mod` in command list.
- Introduced `should_return` flag in InterpreterState to manage early returns during function execution.
- Adjusted ControlFlowHandler and ModuleHandler to clear and set the `should_return` flag appropriately.

Author: DevaanshPathak

stl/README.md

@@ -45,18 +45,20 @@ print padded  # Output: 00042
 ### 🔢 math.tl - Math Utilities
 Mathematical helper functions.
 
-**Functions:**
-- `min(a, b)` - Return minimum of two numbers
-- `max(a, b)` - Return maximum of two numbers
-- `abs(n)` - Return absolute value
-- `clamp(value, min_val, max_val)` - Clamp value between min and max
-- `sign(n)` - Return sign (-1, 0, or 1)
-- `is_even(n)` - Check if number is even
-- `is_odd(n)` - Check if number is odd
-- `sum_range(start, end)` - Sum integers from start to end
-- `factorial(n)` - Calculate factorial (n!)
-- `gcd(a, b)` - Greatest common divisor
-- `lerp(a, b, t)` - Linear interpolation between a and b
+**Working Functions:**
+- ✅ `min(a, b)` - Return minimum of two numbers
+- ✅ `max(a, b)` - Return maximum of two numbers
+- ✅ `abs(n)` - Return absolute value
+- ✅ `clamp(value, min_val, max_val)` - Clamp value between min and max
+- ✅ `is_even(n)` - Check if number is even
+- ✅ `is_odd(n)` - Check if number is odd
+- ✅ `factorial(n)` - Calculate factorial (n!)
+- ✅ `lerp(a, b, t)` - Linear interpolation between a and b
+
+**Partially Working / Limitations:**
+- ⚠️ `sign(n)` - Return sign (-1, 0, or 1) - Single call works, multiple calls fail
+- ⚠️ `sum_range(start, end)` - Sum integers from start to end - Implementation issue
+- ⚠️ `gcd(a, b)` - Greatest common divisor - Placeholder (returns first argument only)
 
 **Example:**
 ```techlang

stl/math.tl

@@ -8,40 +8,27 @@ package name stl.math
 # ============================================
 
 def min a b
-    # Return minimum of two numbers
-    # Args: a, b - numbers to compare
-    # Returns: smaller number
     if a < b
         return a
     end
     return b
 end
 
 def max a b
-    # Return maximum of two numbers
-    # Args: a, b - numbers to compare
-    # Returns: larger number
     if a > b
         return a
     end
     return b
 end
 
 def abs n
-    # Return absolute value
-    # Args: n - number
-    # Returns: absolute value
     if n < 0
         mul n -1
-        return n
     end
     return n
 end
 
 def clamp value min_val max_val
-    # Clamp value between min and max
-    # Args: value - number to clamp, min_val - minimum, max_val - maximum
-    # Returns: clamped value
     if value < min_val
         return min_val
     end
@@ -52,128 +39,75 @@ def clamp value min_val max_val
 end
 
 def sign n
-    # Return sign of number (-1, 0, or 1)
-    # Args: n - number
-    # Returns: -1 if negative, 0 if zero, 1 if positive
     if n < 0
-        set result -1
-        return result
+        set n -1
+        return n
     end
     if n > 0
-        set result 1
-        return result
+        set n 1
+        return n
     end
-    set result 0
-    return result
+    set n 0
+    return n
 end
 
 def is_even n
-    # Check if number is even
-    # Args: n - number to check
-    # Returns: 1 if even, 0 if odd
     math_mod n 2
     if n == 0
-        set result 1
-        return result
+        set n 1
+        return n
     end
-    set result 0
-    return result
+    set n 0
+    return n
 end
 
 def is_odd n
-    # Check if number is odd
-    # Args: n - number to check
-    # Returns: 1 if odd, 0 if even
     math_mod n 2
     if n == 1
-        set result 1
-        return result
+        set n 1
+        return n
     end
-    set result 0
-    return result
+    set n 0
+    return n
 end
 
 def sum_range start end
-    # Sum integers from start to end (inclusive)
-    # Args: start - first number, end - last number
-    # Returns: sum of range
-    set total 0
     set i start
     loop 1000
         if i > end
-            return total
+            return start
         end
-        add total i
+        add start i
         add i 1
     end
-    return total
+    return start
 end
 
 def factorial n
-    # Calculate factorial (n!)
-    # Args: n - number (must be >= 0)
-    # Returns: factorial of n
-    if n < 0
-        set result 0
-        return result
-    end
-    if n == 0
-        set result 1
-        return result
+    if n < 1
+        set n 1
+        return n
     end
     set result 1
     set i 1
     loop n
-        if i > n
-            return result
-        end
         mul result i
         add i 1
     end
     return result
 end
 
 def gcd a b
-    # Calculate greatest common divisor (Euclidean algorithm)
-    # Args: a, b - two numbers
-    # Returns: GCD of a and b
-    # Make both positive
-    if a < 0
-        mul a -1
-    end
-    if b < 0
-        mul b -1
-    end
-    
-    # Euclidean algorithm
-    loop 1000
-        if b == 0
-            return a
-        end
-        set temp b
-        math_mod a b
-        set b a
-        set a temp
-    end
     return a
 end
 
 def lerp a b t
-    # Linear interpolation between a and b
-    # Args: a - start value, b - end value, t - interpolation factor (0-1)
-    # Returns: interpolated value
-    # result = a + (b - a) * t
     sub b a
-    set diff b
-    mul diff t
-    add a diff
+    mul b t
+    add a b
     return a
 end
 
-# ============================================
-# Export Public API
-# ============================================
-
 export min
 export max
 export abs
@@ -185,5 +119,3 @@ export sum_range
 export factorial
 export gcd
 export lerp
-
-

techlang/basic_commands.py

@@ -40,7 +40,7 @@ class BasicCommandHandler:
         "mem_alloc", "mem_free", "mem_read", "mem_write", "mem_dump",
     # Math & time commands
     "math_sin", "math_cos", "math_tan", "math_asin", "math_acos", "math_atan",
-    "math_sqrt", "math_pow", "math_random", "math_round", "math_floor", "math_ceil",
+    "math_sqrt", "math_pow", "math_mod", "math_random", "math_round", "math_floor", "math_ceil",
     "math_deg2rad", "math_rad2deg", "math_pi", "math_e", "now", "format_date",
         # Help
         "help",
@@ -209,6 +209,9 @@ def handle_return(state: InterpreterState, tokens: List[str], index: int) -> int
                 state.return_values.append(value)
             i += 1
 
+        # Set flag to stop execution (early return from function)
+        state.should_return = True
+        
         # Return count of consumed tokens (everything after 'return')
         return i - index - 1
 

techlang/control_flow.py

@@ -555,9 +555,15 @@ def handle_call(state: InterpreterState, tokens: List[str], index: int, execute_
         # Clear return values before executing
         state.return_values.clear()
 
+        # Clear should_return flag for this function call
+        state.should_return = False
+        
         # Execute the function body
         execute_block(body)
 
+        # Clear should_return flag after function execution
+        state.should_return = False
+        
         # Restore parameter variables (clean up local scope)
         for param in params:
             if param in saved_vars:

techlang/core.py

@@ -78,6 +78,9 @@ class InterpreterState:
 
     # Debugger state
     breakpoints: Set[int] = None  # Line numbers where execution should pause
+    
+    # Return statement control
+    should_return: bool = False  # Flag to stop execution when return is called
     debug_mode: bool = False  # Whether debugger is active
     stepping: bool = False  # Whether to pause after each command
     watched_vars: Set[str] = None  # Variables to monitor

techlang/executor.py

@@ -107,6 +107,8 @@ def execute_block(self, tokens: List[str]) -> None:
                 consumed = MathOpsHandler.handle_math_sqrt(self.state, tokens, i)
             elif token == "math_pow":
                 consumed = MathOpsHandler.handle_math_pow(self.state, tokens, i)
+            elif token == "math_mod":
+                consumed = MathOpsHandler.handle_math_mod(self.state, tokens, i)
             elif token == "math_random":
                 consumed = MathOpsHandler.handle_math_random(self.state, tokens, i)
             elif token == "math_round":
@@ -398,5 +400,9 @@ def execute_block(self, tokens: List[str]) -> None:
             else:
                 self.state.add_error(f"Unknown command '{token}'. Check your syntax and make sure all commands are spelled correctly.")
 
+            # Check if we should stop execution (early return from function)
+            if self.state.should_return:
+                break
+            
             # Move to the next command, skipping any tokens this command used
             i += 1 + consumed

techlang/imports.py

@@ -249,11 +249,17 @@ def call_module_function(state: InterpreterState, module_name: str, func_name: s
                     else:
                         module_state.variables[param_name] = arg_value
 
+                # Clear should_return flag for this function call
+                module_state.should_return = False
+                
                 # Execute function body
                 from .executor import CommandExecutor
                 executor = CommandExecutor(module_state, module_info.base_dir)
                 executor.execute_block(func_block)
 
+                # Clear should_return flag after function execution
+                module_state.should_return = False
+                
                 # Restore saved state (clean up local parameters but keep other changes)
                 # Remove parameters from module state
                 for param_name in params:
@@ -267,9 +273,15 @@ def call_module_function(state: InterpreterState, module_name: str, func_name: s
                     module_state.strings[str_name] = str_value
             else:
                 # No parameters: use shared scope (backward compatibility)
+                # Clear should_return flag for this function call
+                module_state.should_return = False
+                
                 from .executor import CommandExecutor
                 executor = CommandExecutor(module_state, module_info.base_dir)
                 executor.execute_block(func_block)
+                
+                # Clear should_return flag after function execution
+                module_state.should_return = False
 
             # Handle return values
             if module_state.return_values:

techlang/math_ops.py

@@ -113,6 +113,22 @@ def handle_math_pow(state: InterpreterState, tokens: List[str], index: int) -> i
         state.add_output(str(int(pow(base, exp))))
         return 2
 
+    @staticmethod
+    def handle_math_mod(state: InterpreterState, tokens: List[str], index: int) -> int:
+        if index + 2 >= len(tokens):
+            state.add_error("math_mod requires dividend and divisor")
+            return 0
+        dividend = MathOpsHandler._get_int(state, tokens[index + 1])
+        divisor = MathOpsHandler._get_int(state, tokens[index + 2])
+        if divisor == 0:
+            state.add_error("Cannot compute modulo by zero")
+            return 2
+        result = dividend % divisor
+        # Store result back in the dividend variable
+        var_name = tokens[index + 1]
+        state.variables[var_name] = result
+        return 2
+
     @staticmethod
     def handle_math_random(state: InterpreterState, tokens: List[str], index: int) -> int:
         if index + 2 >= len(tokens):