IncludeCPP 3.7.1__py3-none-any.whl → 3.7.9__py3-none-any.whl

includecpp/core/cssl_bridge.py

@@ -1,14 +1,23 @@
 """
 CSSL Bridge - Python API for CSSL Language
 Provides CsslLang class for executing CSSL code from Python.
+
+v3.8.0 API:
+    cssl.run(code, *args)          - Execute CSSL code
+    cssl.script("cssl", code)      - Create typed script
+    cssl.makemodule(script, pl)    - Bundle main script + payload
+    cssl.load(path, name)          - Load .cssl/.cssl-pl file
+    cssl.execute(name)             - Execute loaded script
+    cssl.include(path, name)       - Register for payload(name)
 """
 
 import os
 import pickle
 import random
 import threading
+import warnings
 from pathlib import Path
-from typing import Any, List, Optional, Callable, Dict
+from typing import Any, List, Optional, Callable, Dict, Union, Tuple
 
 
 def _get_share_directory() -> Path:
@@ -142,6 +151,79 @@ class CSSLModule:
         return f"<CSSLModule code_len={len(self._code)}>"
 
 
+class CSSLScript:
+    """
+    A typed CSSL script object.
+
+    Created via cssl.script("cssl", code) or cssl.script("cssl-pl", code).
+    Can be executed directly or bundled into a module.
+
+    Usage:
+        main = cssl.script("cssl", '''
+            printl("Main script");
+            myFunc();
+        ''')
+
+        payload = cssl.script("cssl-pl", '''
+            void myFunc() {
+                printl("From payload!");
+            }
+        ''')
+
+        # Execute directly
+        main.run()
+
+        # Or bundle into module
+        mod = cssl.makemodule(main, payload, "mymod")
+    """
+
+    def __init__(self, cssl_instance: 'CsslLang', script_type: str, code: str, params: Tuple = ()):
+        """
+        Initialize a CSSL script.
+
+        Args:
+            cssl_instance: The parent CsslLang instance
+            script_type: "cssl" for main script, "cssl-pl" for payload
+            code: The CSSL code
+            params: Optional parameters accessible via parameter.get(index)
+        """
+        if script_type not in ('cssl', 'cssl-pl'):
+            raise ValueError(f"Invalid script type '{script_type}'. Must be 'cssl' or 'cssl-pl'")
+
+        self._cssl = cssl_instance
+        self._type = script_type
+        self._code = code
+        self._params = params
+        self._name: Optional[str] = None
+
+    @property
+    def type(self) -> str:
+        """Get script type ('cssl' or 'cssl-pl')."""
+        return self._type
+
+    @property
+    def code(self) -> str:
+        """Get the script code."""
+        return self._code
+
+    @property
+    def is_payload(self) -> bool:
+        """Check if this is a payload script."""
+        return self._type == 'cssl-pl'
+
+    def run(self, *args) -> Any:
+        """Execute this script with optional arguments."""
+        all_args = self._params + args
+        return self._cssl.run(self._code, *all_args)
+
+    def __call__(self, *args) -> Any:
+        """Allow calling the script directly."""
+        return self.run(*args)
+
+    def __repr__(self) -> str:
+        return f"<CSSLScript type='{self._type}' code_len={len(self._code)}>"
+
+
 class CSSLFunctionModule:
     """
     A CSSL module with accessible functions as methods.
@@ -150,9 +232,11 @@ class CSSLFunctionModule:
     become callable attributes on this module.
     """
 
-    def __init__(self, cssl_instance: 'CsslLang', code: str):
+    def __init__(self, cssl_instance: 'CsslLang', code: str, payload_code: str = None, name: str = None):
         self._cssl = cssl_instance
         self._code = code
+        self._payload_code = payload_code
+        self._name = name
         self._runtime = None
         self._functions: Dict[str, Any] = {}
         self._initialized = False
@@ -167,7 +251,22 @@ class CSSLFunctionModule:
         # Create a dedicated runtime for this module
         self._runtime = CSSLRuntime()
 
-        # Parse the code
+        # If we have a payload, load it first (defines functions/globals for main)
+        if self._payload_code:
+            payload_ast = parse_cssl_program(self._payload_code)
+            for child in payload_ast.children:
+                if child.type == 'function':
+                    func_info = child.value
+                    func_name = func_info.get('name')
+                    self._functions[func_name] = child
+                    self._runtime.scope.set(func_name, child)
+                else:
+                    try:
+                        self._runtime._execute_node(child)
+                    except Exception:
+                        pass
+
+        # Parse the main code
         ast = parse_cssl_program(self._code)
 
         # Execute to register all function definitions
@@ -184,6 +283,16 @@ class CSSLFunctionModule:
                 except Exception:
                     pass
 
+        # If module has a name, register for payload() access
+        if self._name:
+            cssl_instance = self._cssl
+            runtime = cssl_instance._get_runtime()
+            if not hasattr(runtime, '_inline_payloads'):
+                runtime._inline_payloads = {}
+            # Store combined code for payload() access
+            combined = (self._payload_code or '') + '\n' + self._code
+            runtime._inline_payloads[self._name] = combined
+
         self._initialized = True
 
     def __getattr__(self, name: str) -> Callable:
@@ -224,11 +333,27 @@ class CsslLang:
     """
     CSSL Language interface for Python.
 
-    Usage:
+    v3.8.0 API:
         from includecpp import CSSL
         cssl = CSSL.CsslLang()
-        result = cssl.exec("script.cssl", arg1, arg2)
-        cssl.T_exec("async_script.cssl", arg1)  # Threaded
+
+        # Execute CSSL code
+        result = cssl.run("script.cssl", arg1, arg2)
+        result = cssl.run('''printl("Hello");''')
+
+        # Create typed scripts
+        main = cssl.script("cssl", '''printl("Main");''')
+        payload = cssl.script("cssl-pl", '''void helper() {}''')
+
+        # Bundle into module
+        mod = cssl.makemodule(main, payload, "mymod")
+
+        # Load and execute files
+        cssl.load("utils.cssl-pl", "utils")
+        cssl.execute("utils")
+
+        # Register for payload() access
+        cssl.include("helpers.cssl-pl", "helpers")
     """
 
     def __init__(self, output_callback: Optional[Callable[[str, str], None]] = None):
@@ -241,6 +366,7 @@ class CsslLang:
         self._output_callback = output_callback
         self._runtime = None
         self._threads: List[threading.Thread] = []
+        self._loaded_scripts: Dict[str, Dict[str, Any]] = {}
 
     def _get_runtime(self):
         """Lazy load CSSL runtime."""
@@ -249,23 +375,38 @@ class CsslLang:
             self._runtime = CSSLRuntime(output_callback=self._output_callback)
         return self._runtime
 
-    def exec(self, path_or_code: str, *args) -> Any:
+    def _detect_type(self, path: str) -> str:
+        """Detect script type from file extension."""
+        path_obj = Path(path)
+        if path_obj.suffix == '.cssl-pl':
+            return 'cssl-pl'
+        return 'cssl'
+
+    def run(self, path_or_code: str, *args) -> Any:
         """
         Execute CSSL code or file.
 
+        This is the primary method for running CSSL code in v3.8.0+.
+
         Args:
             path_or_code: Path to .cssl file or CSSL code string
-            *args: Arguments to pass to the script
+            *args: Arguments to pass to the script (accessible via parameter.get())
 
         Returns:
             Execution result. If parameter.return() was called, returns
             the list of returned values (or single value if only one).
+
+        Usage:
+            cssl.run("script.cssl", "arg1", 42)
+            cssl.run('''
+                printl("Hello " + parameter.get(0));
+            ''', "World")
         """
         runtime = self._get_runtime()
 
         # Check if it's a file path
         path = Path(path_or_code)
-        if path.exists() and path.suffix in ('.cssl', '.cssl-mod'):
+        if path.exists() and path.suffix in ('.cssl', '.cssl-mod', '.cssl-pl'):
             source = path.read_text(encoding='utf-8')
         else:
             source = path_or_code
@@ -296,7 +437,27 @@ class CsslLang:
                 raise RuntimeError(error_msg) from e
             raise RuntimeError(f"CSSL Error:\n{error_msg}") from e
 
-    def T_exec(self, path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
+    def exec(self, path_or_code: str, *args) -> Any:
+        """
+        Execute CSSL code or file.
+
+        DEPRECATED: Use run() instead. This method is kept for backwards compatibility.
+
+        Args:
+            path_or_code: Path to .cssl file or CSSL code string
+            *args: Arguments to pass to the script
+
+        Returns:
+            Execution result
+        """
+        warnings.warn(
+            "exec() is deprecated, use run() instead",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.run(path_or_code, *args)
+
+    def T_run(self, path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
         """
         Execute CSSL code asynchronously in a thread.
 
@@ -308,20 +469,33 @@ class CsslLang:
         Returns:
             Thread object
         """
-        def _run():
+        def _run_async():
             try:
-                result = self.exec(path_or_code, *args)
+                result = self.run(path_or_code, *args)
                 if callback:
                     callback(result)
             except Exception as e:
                 if callback:
                     callback(e)
 
-        thread = threading.Thread(target=_run, daemon=True)
+        thread = threading.Thread(target=_run_async, daemon=True)
         thread.start()
         self._threads.append(thread)
         return thread
 
+    def T_exec(self, path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
+        """
+        Execute CSSL code asynchronously in a thread.
+
+        DEPRECATED: Use T_run() instead.
+        """
+        warnings.warn(
+            "T_exec() is deprecated, use T_run() instead",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.T_run(path_or_code, *args, callback=callback)
+
     def wait_all(self, timeout: Optional[float] = None):
         """Wait for all async executions to complete."""
         for thread in self._threads:
@@ -368,32 +542,185 @@ class CsslLang:
         """
         return CSSLModule(self, code)
 
-    def makemodule(self, code: str) -> 'CSSLFunctionModule':
+    def script(self, script_type: str, code: str, *params) -> 'CSSLScript':
+        """
+        Create a typed CSSL script.
+
+        Args:
+            script_type: "cssl" for main script, "cssl-pl" for payload
+            code: The CSSL code
+            *params: Optional parameters accessible via parameter.get(index)
+
+        Returns:
+            CSSLScript object that can be executed or bundled
+
+        Usage:
+            main = cssl.script("cssl", '''
+                printl("Main script running");
+                helper();
+            ''')
+
+            payload = cssl.script("cssl-pl", '''
+                void helper() {
+                    printl("Helper called!");
+                }
+            ''')
+
+            # Execute directly
+            main.run()
+
+            # Or bundle into module
+            mod = cssl.makemodule(main, payload, "mymod")
+        """
+        return CSSLScript(self, script_type, code, params)
+
+    def makemodule(
+        self,
+        main_script: Union[str, 'CSSLScript'],
+        payload_script: Union[str, 'CSSLScript', None] = None,
+        name: str = None
+    ) -> 'CSSLFunctionModule':
         """
         Create a CSSL module with accessible functions.
 
         Functions defined in the code become methods on the returned module.
+        Optionally registers the module for payload() access in other scripts.
 
-        Usage:
-            module = CSSL.makemodule('''
+        Args:
+            main_script: Main CSSL code (string or CSSLScript)
+            payload_script: Optional payload code (string or CSSLScript)
+            name: Optional name to register for payload(name) access
+
+        Returns:
+            CSSLFunctionModule - module with callable function attributes
+
+        Usage (v3.8.0 - with CSSLScript objects):
+            main = cssl.script("cssl", '''
+                printl("Main");
+                helper();
+            ''')
+            payload = cssl.script("cssl-pl", '''
+                void helper() { printl("Helper!"); }
+            ''')
+            mod = cssl.makemodule(main, payload, "mymod")
+            mod.helper()  # Direct call
+
+            # Also available in other scripts:
+            cssl.run('''
+                payload("mymod");
+                helper();  // Works!
+            ''')
+
+        Usage (legacy - code string):
+            module = cssl.makemodule('''
                 string greet(string name) {
                     return "Hello, " + name + "!";
                 }
-
-                int add(int a, int b) {
-                    return a + b;
-                }
             ''')
             module.greet("World")  # Returns "Hello, World!"
-            module.add(2, 3)       # Returns 5
+        """
+        # Extract code from CSSLScript objects if provided
+        if isinstance(main_script, CSSLScript):
+            main_code = main_script.code
+        else:
+            main_code = main_script
+
+        payload_code = None
+        if payload_script is not None:
+            if isinstance(payload_script, CSSLScript):
+                payload_code = payload_script.code
+            else:
+                payload_code = payload_script
+
+        return CSSLFunctionModule(self, main_code, payload_code, name)
+
+    def load(self, path: str, name: str) -> None:
+        """
+        Load a .cssl or .cssl-pl file and register by name.
+
+        The file becomes accessible for execute(name) or payload(name).
+
+        Args:
+            path: Path to the .cssl or .cssl-pl file
+            name: Name to register the script under
+
+        Usage:
+            cssl.load("utils.cssl-pl", "utils")
+            cssl.execute("utils")  # Run it
+
+            # Or in CSSL code:
+            cssl.run('''
+                payload("utils");  // Loads the registered file
+            ''')
+        """
+        path_obj = Path(path)
+        if not path_obj.exists():
+            raise FileNotFoundError(f"CSSL file not found: {path}")
+
+        script_type = self._detect_type(path)
+        code = path_obj.read_text(encoding='utf-8')
+
+        self._loaded_scripts[name] = {
+            'path': str(path_obj.absolute()),
+            'type': script_type,
+            'code': code
+        }
+
+        # Also register for payload() access
+        runtime = self._get_runtime()
+        if not hasattr(runtime, '_inline_payloads'):
+            runtime._inline_payloads = {}
+        runtime._inline_payloads[name] = code
+
+    def execute(self, name: str, *args) -> Any:
+        """
+        Execute a previously loaded script by name.
 
         Args:
-            code: CSSL code string with function definitions
+            name: Name of the loaded script
+            *args: Arguments to pass to the script
 
         Returns:
-            CSSLFunctionModule - module with callable function attributes
+            Execution result
+
+        Usage:
+            cssl.load("utils.cssl-pl", "utils")
+            result = cssl.execute("utils", arg1, arg2)
         """
-        return CSSLFunctionModule(self, code)
+        if name not in self._loaded_scripts:
+            raise KeyError(f"No script loaded with name '{name}'. Use load() first.")
+
+        script_info = self._loaded_scripts[name]
+        return self.run(script_info['code'], *args)
+
+    def include(self, path: str, name: str) -> None:
+        """
+        Register a file to be accessible via payload(name) or include(name) in CSSL.
+
+        Unlike load(), this doesn't store the script for execute() - it only
+        makes it available for payload() calls within CSSL code.
+
+        Args:
+            path: Path to the .cssl or .cssl-pl file
+            name: Name for payload() access
+
+        Usage:
+            cssl.include("helpers.cssl-pl", "helpers")
+            cssl.run('''
+                payload("helpers");
+                // Functions from helpers are now available
+            ''')
+        """
+        path_obj = Path(path)
+        if not path_obj.exists():
+            raise FileNotFoundError(f"CSSL file not found: {path}")
+
+        code = path_obj.read_text(encoding='utf-8')
+
+        runtime = self._get_runtime()
+        if not hasattr(runtime, '_inline_payloads'):
+            runtime._inline_payloads = {}
+        runtime._inline_payloads[name] = code
 
     def code(self, name: str, code: str) -> None:
         """
@@ -748,15 +1075,18 @@ def get_cssl() -> CsslLang:
     return _default_instance
 
 
-# Module-level convenience functions
-def exec(path_or_code: str, *args) -> Any:
+# Module-level convenience functions (v3.8.0 API)
+
+def run(path_or_code: str, *args) -> Any:
     """
     Execute CSSL code or file.
 
+    This is the primary method for running CSSL code in v3.8.0+.
+
     Usage:
         from includecpp import CSSL
-        CSSL.exec("script.cssl", arg1, arg2)
-        CSSL.exec("printl('Hello World');")
+        CSSL.run("script.cssl", arg1, arg2)
+        CSSL.run("printl('Hello World');")
 
     Args:
         path_or_code: Path to .cssl file or CSSL code string
@@ -765,16 +1095,30 @@ def exec(path_or_code: str, *args) -> Any:
     Returns:
         Execution result
     """
-    return get_cssl().exec(path_or_code, *args)
+    return get_cssl().run(path_or_code, *args)
 
 
-def T_exec(path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
+def exec(path_or_code: str, *args) -> Any:
+    """
+    Execute CSSL code or file.
+
+    DEPRECATED: Use run() instead.
+    """
+    warnings.warn(
+        "exec() is deprecated, use run() instead",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return get_cssl().run(path_or_code, *args)
+
+
+def T_run(path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
     """
     Execute CSSL code asynchronously in a thread.
 
     Usage:
         from includecpp import CSSL
-        CSSL.T_exec("async_script.cssl", arg1, callback=on_done)
+        CSSL.T_run("async_script.cssl", arg1, callback=on_done)
 
     Args:
         path_or_code: Path to .cssl file or CSSL code string
@@ -784,7 +1128,75 @@ def T_exec(path_or_code: str, *args, callback: Optional[Callable[[Any], None]] =
     Returns:
         Thread object
     """
-    return get_cssl().T_exec(path_or_code, *args, callback=callback)
+    return get_cssl().T_run(path_or_code, *args, callback=callback)
+
+
+def T_exec(path_or_code: str, *args, callback: Optional[Callable[[Any], None]] = None) -> threading.Thread:
+    """
+    Execute CSSL code asynchronously in a thread.
+
+    DEPRECATED: Use T_run() instead.
+    """
+    warnings.warn(
+        "T_exec() is deprecated, use T_run() instead",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return get_cssl().T_run(path_or_code, *args, callback=callback)
+
+
+def script(script_type: str, code: str, *params) -> CSSLScript:
+    """
+    Create a typed CSSL script.
+
+    Usage:
+        from includecpp import CSSL
+        main = CSSL.script("cssl", '''printl("Main");''')
+        payload = CSSL.script("cssl-pl", '''void helper() {}''')
+        mod = CSSL.makemodule(main, payload, "mymod")
+
+    Args:
+        script_type: "cssl" for main script, "cssl-pl" for payload
+        code: The CSSL code
+        *params: Optional parameters
+
+    Returns:
+        CSSLScript object
+    """
+    return get_cssl().script(script_type, code, *params)
+
+
+def load(path: str, name: str) -> None:
+    """
+    Load a .cssl or .cssl-pl file and register by name.
+
+    Usage:
+        CSSL.load("utils.cssl-pl", "utils")
+        CSSL.execute("utils")
+    """
+    return get_cssl().load(path, name)
+
+
+def execute(name: str, *args) -> Any:
+    """
+    Execute a previously loaded script by name.
+
+    Usage:
+        CSSL.load("utils.cssl-pl", "utils")
+        result = CSSL.execute("utils", arg1, arg2)
+    """
+    return get_cssl().execute(name, *args)
+
+
+def include(path: str, name: str) -> None:
+    """
+    Register a file for payload(name) access in CSSL.
+
+    Usage:
+        CSSL.include("helpers.cssl-pl", "helpers")
+        CSSL.run('payload("helpers");')
+    """
+    return get_cssl().include(path, name)
 
 
 def set_global(name: str, value: Any) -> None:
@@ -808,7 +1220,9 @@ def clear_output() -> None:
 
 
 # Aliases to avoid conflict with Python builtin exec
+_run = run
 _exec = exec
+_T_run = T_run
 _T_exec = T_exec
 
 
@@ -832,43 +1246,58 @@ def module(code: str) -> CSSLModule:
     return get_cssl().module(code)
 
 
-def makemodule(code: str) -> CSSLFunctionModule:
+def makemodule(
+    main_script: Union[str, CSSLScript],
+    payload_script: Union[str, CSSLScript, None] = None,
+    name: str = None
+) -> CSSLFunctionModule:
     """
     Create a CSSL module with accessible functions.
 
-    Usage:
-        from includecpp import CSSL
-        math_mod = CSSL.makemodule('''
-            int add(int a, int b) {
-                return a + b;
-            }
+    Usage (v3.8.0 - with CSSLScript):
+        main = CSSL.script("cssl", '''printl("Main");''')
+        payload = CSSL.script("cssl-pl", '''void helper() {}''')
+        mod = CSSL.makemodule(main, payload, "mymod")
 
-            int multiply(int a, int b) {
-                return a * b;
-            }
+    Usage (legacy - code string):
+        math_mod = CSSL.makemodule('''
+            int add(int a, int b) { return a + b; }
         ''')
-        math_mod.add(2, 3)       # Returns 5
-        math_mod.multiply(4, 5)  # Returns 20
+        math_mod.add(2, 3)  # Returns 5
 
     Args:
-        code: CSSL code string with function definitions
+        main_script: Main CSSL code (string or CSSLScript)
+        payload_script: Optional payload code (string or CSSLScript)
+        name: Optional name to register for payload(name) access
 
     Returns:
         CSSLFunctionModule - module with callable function attributes
     """
-    return get_cssl().makemodule(code)
+    return get_cssl().makemodule(main_script, payload_script, name)
 
 
 # Export all
 __all__ = [
     'CsslLang',
     'CSSLModule',
+    'CSSLScript',
     'CSSLFunctionModule',
     'get_cssl',
+    # v3.8.0 primary API
+    'run',
+    '_run',
+    'T_run',
+    '_T_run',
+    'script',
+    'load',
+    'execute',
+    'include',
+    # Legacy (deprecated)
     'exec',
-    '_exec',  # Alias for exec (avoids Python builtin conflict)
+    '_exec',
     'T_exec',
-    '_T_exec',  # Alias for T_exec
+    '_T_exec',
+    # Other
     'set_global',
     'get_global',
     'get_output',