IncludeCPP 3.7.3__tar.gz → 3.7.4__tar.gz

{includecpp-3.7.3 → includecpp-3.7.4}/IncludeCPP.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IncludeCPP
-Version: 3.7.3
+Version: 3.7.4
 Summary: Professional C++ Python bindings with type-generic templates, pystubs and native threading
 Home-page: https://github.com/liliassg/IncludeCPP
 Author: Lilias Hatterscheidt

{includecpp-3.7.3 → includecpp-3.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IncludeCPP
-Version: 3.7.3
+Version: 3.7.4
 Summary: Professional C++ Python bindings with type-generic templates, pystubs and native threading
 Home-page: https://github.com/liliassg/IncludeCPP
 Author: Lilias Hatterscheidt

{includecpp-3.7.3 → includecpp-3.7.4}/includecpp/__init__.py

@@ -2,7 +2,7 @@ from .core.cpp_api import CppApi
 from .core import cssl_bridge as CSSL
 import warnings
 
-__version__ = "3.7.3"
+__version__ = "3.7.4"
 __all__ = ["CppApi", "CSSL"]
 
 # Module-level cache for C++ modules

{includecpp-3.7.3 → includecpp-3.7.4}/includecpp/core/cssl/cssl_parser.py

@@ -108,6 +108,8 @@ class TokenType(Enum):
     COMMENT = auto()
     NEWLINE = auto()
     EOF = auto()
+    # Super-functions for .cssl-pl payload files (v3.8.0)
+    SUPER_FUNC = auto()    # #$run(), #$exec(), #$printl() - pre-execution hooks
 
 
 KEYWORDS = {
@@ -212,9 +214,14 @@ class CSSLLexer:
 
             char = self.source[self.pos]
 
-            # Comments: both # and // style
+            # Super-functions (#$) or Comments (# and // style)
             if char == '#':
-                self._skip_comment()
+                if self._peek(1) == '$':
+                    # Super-function: #$run(), #$exec(), #$printl()
+                    self._read_super_function()
+                else:
+                    # Regular comment
+                    self._skip_comment()
             elif char == '/' and self._peek(1) == '/':
                 # C-style // comment - NEW
                 self._skip_comment()
@@ -446,6 +453,31 @@ class CSSLLexer:
         else:
             self._add_token(TokenType.IDENTIFIER, value)
 
+    def _read_super_function(self):
+        """Read #$<name>(...) super-function call for .cssl-pl payloads.
+
+        Super-functions are pre-execution hooks that run when a payload is loaded.
+        Valid super-functions: #$run(), #$exec(), #$printl()
+
+        Syntax:
+            #$run(initFunction);        // Call a function at load time
+            #$exec(setup());            // Execute expression at load time
+            #$printl("Payload loaded"); // Print at load time
+        """
+        start = self.pos
+        self._advance()  # skip '#'
+        self._advance()  # skip '$'
+
+        # Read the super-function name (run, exec, printl, etc.)
+        name_start = self.pos
+        while self.pos < len(self.source) and (self.source[self.pos].isalnum() or self.source[self.pos] == '_'):
+            self._advance()
+        func_name = self.source[name_start:self.pos]
+
+        # Store as #$<name> token value
+        value = f'#${func_name}'
+        self._add_token(TokenType.SUPER_FUNC, value)
+
     def _read_self_ref(self):
         """Read s@<name> or s@<name>.<member>... self-reference"""
         start = self.pos
@@ -1377,6 +1409,9 @@ class CSSLParser:
         elif self._looks_like_function_declaration():
             # Nested typed function (e.g., void Level2() { ... })
             return self._parse_typed_function()
+        elif self._check(TokenType.SUPER_FUNC):
+            # Super-function for .cssl-pl payload files
+            return self._parse_super_function()
         elif (self._check(TokenType.IDENTIFIER) or self._check(TokenType.AT) or
               self._check(TokenType.CAPTURED_REF) or self._check(TokenType.SHARED_REF) or
               self._check(TokenType.GLOBAL_REF) or self._check(TokenType.SELF_REF) or
@@ -1728,6 +1763,31 @@ class CSSLParser:
         self._match(TokenType.SEMICOLON)
         return ASTNode('return', value=value)
 
+    def _parse_super_function(self) -> ASTNode:
+        """Parse super-function for .cssl-pl payload files.
+
+        Syntax:
+            #$run(initFunction);           // Call function at load time
+            #$exec(setup());               // Execute expression at load time
+            #$printl("Payload loaded");    // Print at load time
+
+        These are pre-execution hooks that run when payload() loads the file.
+        """
+        token = self._advance()  # Get the SUPER_FUNC token
+        super_name = token.value  # e.g., "#$run", "#$exec", "#$printl"
+
+        # Parse the arguments
+        self._expect(TokenType.PAREN_START)
+        args = []
+        if not self._check(TokenType.PAREN_END):
+            args.append(self._parse_expression())
+            while self._match(TokenType.COMMA):
+                args.append(self._parse_expression())
+        self._expect(TokenType.PAREN_END)
+        self._match(TokenType.SEMICOLON)
+
+        return ASTNode('super_func', value={'name': super_name, 'args': args})
+
     def _parse_try(self) -> ASTNode:
         node = ASTNode('try', children=[])
 

{includecpp-3.7.3 → includecpp-3.7.4}/includecpp/core/cssl/cssl_runtime.py

@@ -401,6 +401,9 @@ class CSSLRuntime:
             elif child.type == 'instance_declaration':
                 # Handle instance declaration: instance<"name"> varName;
                 result = self._exec_instance_declaration(child)
+            elif child.type == 'super_func':
+                # Super-function for .cssl-pl payload files (#$run, #$exec, #$printl)
+                result = self._exec_super_func(child)
             elif child.type in ('assignment', 'expression', 'inject', 'receive', 'flow',
                                'if', 'while', 'for', 'c_for', 'foreach', 'switch', 'try'):
                 result = self._execute_node(child)
@@ -820,6 +823,82 @@ class CSSLRuntime:
         self.scope.set(var_name, instance)
         return instance
 
+    def _exec_super_func(self, node: ASTNode) -> Any:
+        """Execute super-function for .cssl-pl payload files.
+
+        Super-functions are pre-execution hooks that run when payload() loads a file.
+
+        Supported super-functions:
+            #$run(funcName)        - Call a function defined in the payload
+            #$exec(expression)     - Execute an expression immediately
+            #$printl(message)      - Print a message during load
+
+        Example .cssl-pl file:
+            void initDatabase() {
+                printl("DB initialized");
+            }
+
+            #$run(initDatabase);       // Calls initDatabase when payload loads
+            #$printl("Payload loaded"); // Prints during load
+        """
+        super_info = node.value
+        super_name = super_info.get('name', '')  # e.g., "#$run", "#$exec", "#$printl"
+        args = super_info.get('args', [])
+
+        # Extract the function name part (after #$)
+        if super_name.startswith('#$'):
+            func_type = super_name[2:]  # "run", "exec", "printl"
+        else:
+            func_type = super_name
+
+        if func_type == 'run':
+            # #$run(funcName) - Call a function by name
+            if args:
+                func_ref = args[0]
+                if isinstance(func_ref, ASTNode):
+                    if func_ref.type == 'identifier':
+                        func_name = func_ref.value
+                    elif func_ref.type == 'call':
+                        # Direct call like #$run(setup())
+                        return self._eval_call(func_ref)
+                    else:
+                        func_name = self._evaluate(func_ref)
+                else:
+                    func_name = str(func_ref)
+
+                # Look up and call the function
+                func_node = self.scope.get(func_name)
+                if func_node and isinstance(func_node, ASTNode) and func_node.type == 'function':
+                    return self._call_function(func_node, [])
+                else:
+                    raise CSSLRuntimeError(f"#$run: Function '{func_name}' not found", node.line)
+
+        elif func_type == 'exec':
+            # #$exec(expression) - Execute an expression
+            if args:
+                return self._evaluate(args[0])
+
+        elif func_type == 'printl':
+            # #$printl(message) - Print a message
+            if args:
+                msg = self._evaluate(args[0])
+                print(str(msg))
+                self.output_buffer.append(str(msg))
+                return None
+
+        elif func_type == 'print':
+            # #$print(message) - Print without newline
+            if args:
+                msg = self._evaluate(args[0])
+                print(str(msg), end='')
+                self.output_buffer.append(str(msg))
+                return None
+
+        else:
+            raise CSSLRuntimeError(f"Unknown super-function: {super_name}", node.line)
+
+        return None
+
     def _exec_global_assignment(self, node: ASTNode) -> Any:
         """Execute global variable assignment: global Name = value
 
@@ -1778,9 +1857,12 @@ class CSSLRuntime:
 
         if node.type == 'literal':
             value = node.value
-            # NEW: String interpolation - replace <variable> with scope values
-            if isinstance(value, str) and '<' in value and '>' in value:
-                value = self._interpolate_string(value)
+            # String interpolation - replace {var} or <var> with scope values
+            if isinstance(value, str):
+                has_fstring = '{' in value and '}' in value
+                has_legacy = '<' in value and '>' in value
+                if has_fstring or has_legacy:
+                    value = self._interpolate_string(value)
             return value
 
         # NEW: Type literals (list, dict) - create empty instances
@@ -2725,14 +2807,24 @@ class CSSLRuntime:
         elif isinstance(obj, dict):
             obj[final_attr] = value
 
-    # NEW: String interpolation
+    # String interpolation (supports both <var> and {var} syntax)
     def _interpolate_string(self, string: str) -> str:
-        """Replace <variable> placeholders with values from scope - NEW
+        """Replace {variable} and <variable> placeholders with values from scope.
+
+        Both syntaxes are supported (variables only, not expressions):
+            "Hello {name}!"   -> "Hello John!"  (f-string style)
+            "Hello <name>!"   -> "Hello John!"  (legacy CSSL style)
+
+        Examples:
+            string name = "Alice";
+            int age = 30;
+            printl("Hello {name}, you are {age} years old!");
+            printl("Hello <name>, you are <age> years old!");
 
-        Example: "Hello <name>!" becomes "Hello John!" if name = "John"
+        Note: Only simple variable names are supported, not expressions.
+        Use string concatenation for complex expressions.
         """
         import re
-        pattern = r'<([A-Za-z_][A-Za-z0-9_]*)>'
 
         def replacer(match):
             var_name = match.group(1)
@@ -2744,10 +2836,23 @@ class CSSLRuntime:
             # Try modules
             if value is None:
                 value = self._modules.get(var_name)
+            # Try global scope
+            if value is None:
+                value = self.global_scope.get(var_name)
             # Return string representation or empty string if None
             return str(value) if value is not None else ''
 
-        return re.sub(pattern, replacer, string)
+        # Support both {var} and <var> syntax - simple variable names only
+        # Pattern: {identifier} or <identifier>
+        patterns = [
+            r'\{([A-Za-z_][A-Za-z0-9_]*)\}',  # {name} f-string style
+            r'<([A-Za-z_][A-Za-z0-9_]*)>',     # <name> legacy CSSL style
+        ]
+
+        result = string
+        for pattern in patterns:
+            result = re.sub(pattern, replacer, result)
+        return result
 
     # NEW: Promote variable to global scope via global()
     def promote_to_global(self, s_ref_name: str):

{includecpp-3.7.3 → includecpp-3.7.4}/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',

{includecpp-3.7.3 → includecpp-3.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "IncludeCPP"
-version = "3.7.3"
+version = "3.7.4"
 description = "Professional C++ Python bindings with type-generic templates, pystubs and native threading"
 readme = "README.md"
 requires-python = ">=3.9"

{includecpp-3.7.3 → includecpp-3.7.4}/setup.py

@@ -6,7 +6,7 @@ long_description = (this_directory / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="IncludeCPP",
-    version="3.7.3",
+    version="3.7.4",
     author="Lilias Hatterscheidt",
     author_email="lilias@includecpp.dev",
     description="Professional C++ Python bindings with type-generic templates and native threading",