IncludeCPP 3.8.9__py3-none-any.whl → 4.0.2__py3-none-any.whl

includecpp/core/cssl_bridge.pyi

@@ -1,9 +1,96 @@
 """
 CSSL Bridge - Type Stubs for Python API
+
+CSSL (C-Style Scripting Language) is a scripting language that bridges Python and C++ style syntax.
+This module provides the Python API for executing CSSL code and sharing objects between Python and CSSL.
+
+Quick Start:
+    from includecpp import CSSL
+
+    # Execute CSSL code directly
+    CSSL.run('printl("Hello from CSSL!");')
+
+    # Execute a CSSL file
+    CSSL.run("script.cssl", arg1, arg2)
+
+    # Share Python objects with CSSL (live reference)
+    my_data = {"count": 0}
+    CSSL.share(my_data, "data")
+    CSSL.run('$data.count = $data.count + 1;')
+    print(my_data["count"])  # 1
+
+    # Create reusable modules
+    math_mod = CSSL.makemodule('''
+        int add(int a, int b) { return a + b; }
+    ''')
+    result = math_mod.add(2, 3)  # 5
 """
 
 import threading
-from typing import Any, List, Optional, Callable, Dict
+from typing import Any, List, Optional, Callable, Dict, Union
+
+
+class CSSLScript:
+    """
+    A typed CSSL script object.
+
+    Created via CSSL.script() - represents a bundle of CSSL code that can be
+    executed multiple times or combined into modules.
+
+    Script Types:
+        - "cssl": Main script - the primary entry point
+        - "cssl-pl": Payload - helper code loaded via payload()
+
+    Usage:
+        from includecpp import CSSL
+
+        # Create a main script
+        main = CSSL.script("cssl", '''
+            printl("Running main script");
+            helper();
+        ''')
+
+        # Create a payload (helper functions)
+        helpers = CSSL.script("cssl-pl", '''
+            void helper() {
+                printl("Helper called!");
+            }
+        ''')
+
+        # Execute the script
+        main.run()
+
+        # Or combine into a module
+        mod = CSSL.makemodule(main, helpers, "mymodule")
+    """
+
+    def __init__(self, cssl_instance: 'CsslLang', script_type: str, code: str, *params: Any) -> None: ...
+
+    @property
+    def code(self) -> str:
+        """Get the script's CSSL source code."""
+        ...
+
+    @property
+    def is_payload(self) -> bool:
+        """Check if this script is a payload (cssl-pl) type."""
+        ...
+
+    def run(self, *args: Any) -> Any:
+        """
+        Execute this script with optional arguments.
+
+        Args:
+            *args: Arguments accessible in CSSL via parameter.get(index)
+
+        Returns:
+            Execution result
+        """
+        ...
+
+    def __call__(self, *args: Any) -> Any:
+        """Allow calling the script directly: script() is same as script.run()"""
+        ...
 
 
 class CSSLModule:
@@ -12,12 +99,34 @@ class CSSLModule:
 
     Created via CSSL.module() - the code is executed each time the module is called,
     with arguments accessible via parameter.get(index).
+
+    Usage:
+        from includecpp import CSSL
+
+        # Create a simple greeting module
+        greet = CSSL.module('''
+            string name = parameter.get(0);
+            printl("Hello, " + name + "!");
+        ''')
+
+        greet("World")   # Prints: Hello, World!
+        greet("Alice")   # Prints: Hello, Alice!
+
+        # Module with multiple parameters
+        calc = CSSL.module('''
+            int a = parameter.get(0);
+            int b = parameter.get(1);
+            parameter.return(a + b);
+        ''')
+        result = calc(10, 20)  # Returns 30
     """
 
     def __init__(self, cssl_instance: 'CsslLang', code: str) -> None: ...
+
     def __call__(self, *args: Any) -> Any:
         """Execute the module code with the given arguments."""
         ...
+
     def __repr__(self) -> str: ...
 
 
@@ -26,28 +135,84 @@ class CSSLFunctionModule:
     A CSSL module with accessible functions as methods.
 
     Created via CSSL.makemodule() - functions defined in the CSSL code
-    become callable attributes on this module.
+    become callable attributes on this module. This is the recommended way
+    to create reusable CSSL libraries.
+
+    Usage:
+        from includecpp import CSSL
+
+        # Create a math module with multiple functions
+        math_mod = CSSL.makemodule('''
+            int add(int a, int b) {
+                return a + b;
+            }
+
+            int multiply(int a, int b) {
+                return a * b;
+            }
+
+            float average(int a, int b) {
+                return (a + b) / 2.0;
+            }
+        ''')
+
+        # Call functions as attributes
+        print(math_mod.add(2, 3))       # 5
+        print(math_mod.multiply(4, 5))  # 20
+        print(math_mod.average(10, 20)) # 15.0
+
+        # List available functions
+        print(dir(math_mod))  # ['add', 'average', 'multiply']
     """
 
     def __init__(self, cssl_instance: 'CsslLang', code: str) -> None: ...
+
     def __getattr__(self, name: str) -> Callable[..., Any]:
-        """Get a function from the module."""
+        """Get a function from the module by name."""
         ...
+
     def __dir__(self) -> List[str]:
-        """List available functions."""
+        """List all available functions in this module."""
         ...
+
     def __repr__(self) -> str: ...
 
 
 class CsslLang:
     """
-    CSSL Language interface for Python.
+    CSSL Language runtime interface for Python.
 
-    Usage:
+    This is the main class for interacting with CSSL from Python. It provides
+    methods for executing code, sharing objects, creating modules, and more.
+
+    Basic Usage:
         from includecpp import CSSL
+
+        # Get default instance
         cssl = CSSL.CsslLang()
-        result = cssl.exec("script.cssl", arg1, arg2)
-        cssl.T_exec("async_script.cssl", arg1)  # Threaded
+
+        # Or use module-level functions directly
+        CSSL.run("printl('Hello');")
+
+    Execution Methods:
+        - run(): Execute CSSL code or file (recommended)
+        - exec(): Alias for run() (deprecated)
+        - T_run(): Execute asynchronously in a thread
+
+    Object Sharing:
+        - share(): Share Python object with CSSL (live reference)
+        - unshare(): Remove shared object
+        - shared(): Get a shared object by name
+
+    Module Creation:
+        - module(): Create callable code block
+        - makemodule(): Create module with callable functions
+        - script(): Create typed script (cssl or cssl-pl)
+        - code(): Register inline payload
+
+    Globals:
+        - set_global(): Set CSSL global variable
+        - get_global(): Get CSSL global variable
     """
 
     def __init__(self, output_callback: Optional[Callable[[str, str], None]] = ...) -> None:
@@ -55,97 +220,225 @@ class CsslLang:
         Initialize CSSL runtime.
 
         Args:
-            output_callback: Optional callback for output (text, level)
+            output_callback: Optional callback for capturing output.
+                             Called with (text, level) where level is
+                             'normal', 'debug', 'warning', or 'error'.
+
+        Usage:
+            def my_output(text, level):
+                if level == 'error':
+                    log_error(text)
+                else:
+                    print(text)
+
+            cssl = CSSL.CsslLang(output_callback=my_output)
         """
         ...
 
-    def exec(self, path_or_code: str, *args: Any) -> Any:
+    def run(self, path_or_code: str, *args: Any) -> Any:
         """
-        Execute CSSL code or file.
+        Execute CSSL code or file. This is the primary execution method.
 
         Args:
-            path_or_code: Path to .cssl file or CSSL code string
-            *args: Arguments to pass to the script
+            path_or_code: Either a path to a .cssl file or CSSL code string.
+                          File paths must end in .cssl, .cssl-pl, or .cssl-mod
+            *args: Arguments passed to the script, accessible via parameter.get(index)
 
         Returns:
-            Execution result
+            Execution result. If parameter.return() was called in CSSL,
+            returns those values. Single value if one, list if multiple.
+
+        Usage:
+            # Execute a file
+            result = cssl.run("script.cssl", "arg1", 42)
+
+            # Execute inline code
+            cssl.run('printl("Hello World!");')
+
+            # Get return value
+            result = cssl.run('''
+                int x = parameter.get(0);
+                parameter.return(x * 2);
+            ''', 21)
+            print(result)  # 42
         """
         ...
 
-    def T_exec(
+    def T_run(
         self,
         path_or_code: str,
         *args: Any,
         callback: Optional[Callable[[Any], None]] = ...
     ) -> threading.Thread:
         """
-        Execute CSSL code asynchronously in a thread.
+        Execute CSSL code asynchronously in a background thread.
 
         Args:
             path_or_code: Path to .cssl file or CSSL code string
             *args: Arguments to pass to the script
-            callback: Optional callback when execution completes
+            callback: Optional callback invoked with result when execution completes
 
         Returns:
-            Thread object
+            Thread object that can be joined or monitored
+
+        Usage:
+            def on_complete(result):
+                print(f"Script finished with: {result}")
+
+            thread = cssl.T_run("long_running.cssl", callback=on_complete)
+            # ... do other work ...
+            thread.join()  # Wait for completion if needed
         """
         ...
 
-    def wait_all(self, timeout: Optional[float] = ...) -> None:
-        """Wait for all async executions to complete."""
-        ...
+    def exec(self, path_or_code: str, *args: Any) -> Any:
+        """
+        Execute CSSL code or file (DEPRECATED - use run() instead).
 
-    def get_output(self) -> List[str]:
-        """Get output buffer from last execution."""
+        This method is kept for backwards compatibility.
+        See run() for documentation.
+        """
         ...
 
-    def clear_output(self) -> None:
-        """Clear output buffer."""
+    def T_exec(
+        self,
+        path_or_code: str,
+        *args: Any,
+        callback: Optional[Callable[[Any], None]] = ...
+    ) -> threading.Thread:
+        """
+        Execute CSSL asynchronously (DEPRECATED - use T_run() instead).
+
+        This method is kept for backwards compatibility.
+        See T_run() for documentation.
+        """
         ...
 
-    def set_global(self, name: str, value: Any) -> None:
-        """Set a global variable in CSSL runtime."""
+    def script(self, script_type: str, code: str, *params: Any) -> CSSLScript:
+        """
+        Create a typed CSSL script object.
+
+        Scripts can be executed multiple times or combined into modules.
+        This is useful for organizing complex CSSL projects.
+
+        Args:
+            script_type: "cssl" for main script, "cssl-pl" for payload
+            code: The CSSL source code
+            *params: Optional default parameters
+
+        Returns:
+            CSSLScript object
+
+        Usage:
+            # Create main script and payload
+            main = cssl.script("cssl", '''
+                printl("Main running");
+                @helper.greet("World");
+            ''')
+
+            payload = cssl.script("cssl-pl", '''
+                void greet(string name) {
+                    printl("Hello, " + name + "!");
+                }
+            ''')
+
+            # Bundle into a .cssl-mod file
+            cssl.makemodule(main, payload, "mymodule")
+        """
         ...
 
-    def get_global(self, name: str) -> Any:
-        """Get a global variable from CSSL runtime."""
+    def code(self, name: str, code: str) -> None:
+        """
+        Register inline CSSL code as a named payload.
+
+        Registered payloads can be loaded in CSSL using payload("name").
+        This allows creating helper libraries from Python without external files.
+
+        Args:
+            name: Unique name for the payload
+            code: CSSL code string
+
+        Usage:
+            # Register helper functions
+            cssl.code("utils", '''
+                global version = "1.0.0";
+
+                void log(string msg) {
+                    printl("[LOG] " + msg);
+                }
+
+                int double(int x) {
+                    return x * 2;
+                }
+            ''')
+
+            # Use in CSSL code
+            cssl.run('''
+                payload("utils");
+                @log("Starting...");
+                printl(@double(21));  // 42
+            ''')
+        """
         ...
 
     def module(self, code: str) -> CSSLModule:
         """
         Create a callable CSSL module from code.
 
-        Usage:
-            module = cssl.module('''
-                printl(parameter.get(0));
-            ''')
-            module("Hello")  # Prints "Hello"
+        The module executes the code each time it's called.
+        Arguments are accessible via parameter.get(index).
 
         Args:
             code: CSSL code string
 
         Returns:
-            CSSLModule - a callable module
+            CSSLModule - callable that executes the code
+
+        Usage:
+            # Simple greeting
+            greet = cssl.module('''
+                string name = parameter.get(0);
+                printl("Hello, " + name + "!");
+            ''')
+            greet("World")  # Prints: Hello, World!
+
+            # With return value
+            calc = cssl.module('''
+                int a = parameter.get(0);
+                int b = parameter.get(1);
+                parameter.return(a * b);
+            ''')
+            result = calc(6, 7)  # Returns 42
         """
         ...
 
-    def makemodule(self, code: str) -> CSSLFunctionModule:
+    def makemodule(self, code_or_script: Union[str, CSSLScript], *more: Any) -> CSSLFunctionModule:
         """
-        Create a CSSL module with accessible functions.
+        Create a CSSL module with accessible functions as methods.
 
-        Usage:
-            module = cssl.makemodule('''
-                string greet(string name) {
-                    return "Hello, " + name + "!";
-                }
-            ''')
-            module.greet("World")  # Returns "Hello, World!"
+        This is the recommended way to create reusable CSSL libraries.
+        Functions defined in the code become callable Python methods.
 
         Args:
-            code: CSSL code string with function definitions
+            code_or_script: CSSL code string or CSSLScript object
+            *more: Additional scripts or module name
 
         Returns:
-            CSSLFunctionModule - module with callable function attributes
+            CSSLFunctionModule with callable function attributes
+
+        Usage:
+            # From code string
+            math = cssl.makemodule('''
+                int add(int a, int b) { return a + b; }
+                int sub(int a, int b) { return a - b; }
+            ''')
+            print(math.add(10, 5))  # 15
+            print(math.sub(10, 5))  # 5
+
+            # From script objects (for .cssl-mod creation)
+            main = cssl.script("cssl", "...")
+            helpers = cssl.script("cssl-pl", "...")
+            mod = cssl.makemodule(main, helpers, "mymodule")
         """
         ...
 
@@ -153,143 +446,206 @@ class CsslLang:
         """
         Share a Python object with CSSL (LIVE sharing).
 
-        Changes in CSSL reflect back to Python immediately.
+        Changes made in CSSL immediately reflect in the Python object.
+        This enables true bidirectional communication between Python and CSSL.
 
-        Args can be passed in either order:
+        Args can be passed in either order (for convenience):
             cssl.share(my_object, "name")  # Preferred
             cssl.share("name", my_object)  # Also works
 
-        Usage:
-            class Counter:
-                def __init__(self):
-                    self.value = 0
-
-            counter = Counter()
-            cssl.share(counter, "cnt")
-            cssl.exec('''
-                $cnt.value = $cnt.value + 1;
-            ''')
-            print(counter.value)  # 1
-
         Args:
-            instance: Python object to share
+            instance: Python object to share (can be any object)
             name: Name to reference in CSSL as $name
 
         Returns:
             Path to the shared object marker file
+
+        Usage:
+            # Share a simple object
+            counter = {"value": 0}
+            cssl.share(counter, "cnt")
+            cssl.run('$cnt.value = $cnt.value + 1;')
+            print(counter["value"])  # 1
+
+            # Share a class instance
+            class Player:
+                def __init__(self):
+                    self.health = 100
+                    self.name = "Hero"
+
+                def take_damage(self, amount):
+                    self.health -= amount
+
+            player = Player()
+            cssl.share(player, "player")
+            cssl.run('''
+                $player.take_damage(25);
+                printl($player.name + " has " + $player.health + " HP");
+            ''')
+            # Prints: Hero has 75 HP
         """
         ...
 
     def unshare(self, name: str) -> bool:
         """
-        Remove a shared object.
+        Remove a shared object by name.
 
         Args:
             name: Name of the shared object to remove
 
         Returns:
-            True if removed, False if not found
+            True if object was found and removed, False otherwise
+
+        Usage:
+            cssl.share(my_obj, "temp")
+            cssl.run("...")  # Use $temp
+            cssl.unshare("temp")  # Clean up
         """
         ...
 
-    def code(self, name: str, code: str) -> None:
+    def get_shared(self, name: str) -> Optional[Any]:
         """
-        Register inline CSSL code as a named payload.
+        Get a shared object by name (Python-side access).
 
-        Usage:
-            cssl.code("helpers", '''
-                void log(string msg) {
-                    printl("[LOG] " + msg);
-                }
-            ''')
-            cssl.exec('''
-                payload("helpers");
-                @log("Hello");
-            ''')
+        Returns the actual live object reference, not a copy.
 
         Args:
-            name: Name for the payload
-            code: CSSL code string
+            name: Name of the shared object (without $ prefix)
+
+        Returns:
+            The live shared object, or None if not found
         """
         ...
 
-    def get_shared(self, name: str) -> Optional[Any]:
+    def shared(self, name: str) -> Optional[Any]:
         """
-        Get a shared object by name (for Python-side access).
+        Get a shared object by name (alias for get_shared).
 
-        Returns the actual live object reference, not a copy.
+        Works with both Python cssl.share() and CSSL ==> $name exports.
 
         Args:
-            name: Name of the shared object
+            name: Name of the shared object (without $ prefix)
 
         Returns:
-            The live shared object or None if not found
+            The live shared object, or None if not found
+
+        Usage:
+            # Share from Python
+            data = {"x": 1}
+            cssl.share(data, "mydata")
+
+            # Later retrieve it
+            same_data = cssl.shared("mydata")
+            same_data["x"] = 2
+            print(data["x"])  # 2 (same object)
         """
         ...
 
-    def shared(self, name: str) -> Optional[Any]:
+    def set_global(self, name: str, value: Any) -> None:
         """
-        Get a shared object by name (alias for get_shared).
+        Set a global variable in the CSSL runtime.
 
-        Returns the actual live object reference, not a copy.
-        Works with both Python cssl.share() and CSSL ==> $name shared objects.
+        These globals persist across multiple run() calls on the same instance.
+
+        Args:
+            name: Variable name (accessible as @name in CSSL)
+            value: Value to set
 
         Usage:
-            from includecpp import CSSL
-            cssl = CSSL.CsslLang()
+            cssl.set_global("config_path", "/etc/myapp.conf")
+            cssl.run('printl(@config_path);')
+        """
+        ...
+
+    def get_global(self, name: str) -> Any:
+        """
+        Get a global variable from the CSSL runtime.
+
+        Args:
+            name: Variable name
 
-            # Share an object
-            my_obj = {"value": 42}
-            cssl.share(my_obj, "data")
+        Returns:
+            The variable's value, or None if not found
+        """
+        ...
 
-            # Retrieve it later
-            obj = cssl.shared("data")
-            print(obj["value"])  # 42
+    def wait_all(self, timeout: Optional[float] = ...) -> None:
+        """
+        Wait for all async executions (T_run) to complete.
 
         Args:
-            name: Name of the shared object (without $ prefix)
+            timeout: Maximum seconds to wait (None = wait forever)
+
+        Usage:
+            cssl.T_run("script1.cssl")
+            cssl.T_run("script2.cssl")
+            cssl.wait_all()  # Wait for both to finish
+        """
+        ...
+
+    def get_output(self) -> List[str]:
+        """
+        Get the output buffer from the last execution.
 
         Returns:
-            The live shared object or None if not found
+            List of output lines
         """
         ...
 
+    def clear_output(self) -> None:
+        """Clear the output buffer."""
+        ...
+
+
+# =============================================================================
+# Module-Level Functions (Convenience API)
+# =============================================================================
+# These functions operate on a default global CSSL instance.
+# For most use cases, you can use these directly instead of creating a CsslLang.
 
 def get_cssl() -> CsslLang:
-    """Get default CSSL instance."""
+    """Get the default global CSSL instance."""
     ...
 
 
-def exec(path_or_code: str, *args: Any) -> Any:
+def run(path_or_code: str, *args: Any) -> Any:
     """
-    Execute CSSL code or file.
+    Execute CSSL code or file using the default instance.
 
-    Usage:
-        from includecpp import CSSL
-        CSSL.exec("script.cssl", arg1, arg2)
-        CSSL.exec("printl('Hello World');")
+    This is the primary way to run CSSL code. Supports both file paths
+    and inline code strings.
 
     Args:
         path_or_code: Path to .cssl file or CSSL code string
-        *args: Arguments to pass to the script
+        *args: Arguments accessible via parameter.get(index)
 
     Returns:
         Execution result
+
+    Usage:
+        from includecpp import CSSL
+
+        # Run inline code
+        CSSL.run('printl("Hello World!");')
+
+        # Run a file with arguments
+        CSSL.run("process.cssl", input_data, output_path)
+
+        # Get return value
+        result = CSSL.run('''
+            parameter.return(42);
+        ''')
     """
     ...
 
 
-def T_exec(
+def T_run(
     path_or_code: str,
     *args: Any,
     callback: Optional[Callable[[Any], 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)
+    Execute CSSL code asynchronously in a background thread.
 
     Args:
         path_or_code: Path to .cssl file or CSSL code string
@@ -298,117 +654,103 @@ def T_exec(
 
     Returns:
         Thread object
-    """
-    ...
 
+    Usage:
+        from includecpp import CSSL
 
-def set_global(name: str, value: Any) -> None:
-    """Set a global variable in CSSL runtime."""
+        def on_done(result):
+            print(f"Finished: {result}")
+
+        CSSL.T_run("background_task.cssl", callback=on_done)
+    """
     ...
 
 
-def get_global(name: str) -> Any:
-    """Get a global variable from CSSL runtime."""
-    ...
+def script(script_type: str, code: str, *params: Any) -> CSSLScript:
+    """
+    Create a typed CSSL script.
 
+    Args:
+        script_type: "cssl" for main script, "cssl-pl" for payload
+        code: The CSSL code
+        *params: Optional parameters
 
-def get_output() -> List[str]:
-    """Get output buffer from last execution."""
-    ...
+    Returns:
+        CSSLScript object
 
+    Usage:
+        from includecpp import CSSL
 
-def clear_output() -> None:
-    """Clear output buffer."""
+        main = CSSL.script("cssl", '''printl("Main");''')
+        payload = CSSL.script("cssl-pl", '''void helper() {}''')
+    """
     ...
 
 
-# Aliases to avoid conflict with Python builtin exec
-def _exec(code: str, *args: Any) -> Any:
+def code(name: str, code: str) -> None:
     """
-    Execute CSSL code directly (alias for exec).
+    Register inline CSSL code as a named payload.
+
+    Payloads can be loaded in CSSL using payload("name").
 
-    Supports triple-quoted docstrings for inline CSSL code:
+    Args:
+        name: Unique name for the payload
+        code: CSSL code string
 
     Usage:
         from includecpp import CSSL
-        CSSL._exec('''
-            global base = include("abc.cssl-mod");
-
-            void TestFunc() {
-                printl("hey");
-                @base.RechneWas(4, 5);
-            }
 
-            TestFunc();
+        CSSL.code("utils", '''
+            void log(string msg) { printl("[LOG] " + msg); }
         ''')
 
-    Args:
-        code: CSSL code string (supports triple-quoted docstrings)
-        *args: Arguments to pass to the script
-
-    Returns:
-        Execution result
+        CSSL.run('''
+            payload("utils");
+            @log("Hello!");
+        ''')
     """
     ...
 
 
-def _T_exec(
-    code: str,
-    *args: Any,
-    callback: Optional[Callable[[Any], None]] = ...
-) -> threading.Thread:
+def module(code: str) -> CSSLModule:
     """
-    Execute CSSL code asynchronously in a thread (alias for T_exec).
+    Create a callable CSSL module from code.
 
     Args:
         code: CSSL code string
-        *args: Arguments to pass to the script
-        callback: Optional callback when execution completes
 
     Returns:
-        Thread object
-    """
-    ...
-
-
-def module(code: str) -> CSSLModule:
-    """
-    Create a callable CSSL module from code.
+        CSSLModule - callable that executes the code
 
     Usage:
         from includecpp import CSSL
+
         greet = CSSL.module('''
             printl("Hello, " + parameter.get(0) + "!");
         ''')
-        greet("World")  # Prints "Hello, World!"
-
-    Args:
-        code: CSSL code string
-
-    Returns:
-        CSSLModule - a callable module
+        greet("World")  # Prints: Hello, World!
     """
     ...
 
 
-def makemodule(code: str) -> CSSLFunctionModule:
+def makemodule(code_or_script: Union[str, CSSLScript], *more: Any) -> 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;
-            }
-        ''')
-        math_mod.add(2, 3)  # Returns 5
-
     Args:
-        code: CSSL code string with function definitions
+        code_or_script: CSSL code string or CSSLScript object
+        *more: Additional scripts or module name
 
     Returns:
-        CSSLFunctionModule - module with callable function attributes
+        CSSLFunctionModule with callable function attributes
+
+    Usage:
+        from includecpp import CSSL
+
+        math = CSSL.makemodule('''
+            int add(int a, int b) { return a + b; }
+        ''')
+        result = math.add(2, 3)  # 5
     """
     ...
 
@@ -417,11 +759,7 @@ def share(instance: Any, name: str = ...) -> str:
     """
     Share a Python object globally for all CSSL instances (LIVE sharing).
 
-    Changes made through CSSL will reflect back to the original object.
-
-    Args can be passed in either order:
-        share(my_object, "name")  # Preferred
-        share("name", my_object)  # Also works
+    Changes made in CSSL immediately reflect in the Python object.
 
     Args:
         instance: Python object to share
@@ -429,6 +767,14 @@ def share(instance: Any, name: str = ...) -> str:
 
     Returns:
         Path to the shared object marker file
+
+    Usage:
+        from includecpp import CSSL
+
+        data = {"count": 0}
+        CSSL.share(data, "data")
+        CSSL.run('$data.count = 10;')
+        print(data["count"])  # 10
     """
     ...
 
@@ -463,19 +809,6 @@ def shared(name: str) -> Optional[Any]:
     """
     Get a shared object by name (alias for get_shared).
 
-    Works with both Python share() and CSSL ==> $name shared objects.
-
-    Usage:
-        from includecpp import CSSL
-
-        # Share an object
-        my_obj = {"value": 42}
-        CSSL.share(my_obj, "data")
-
-        # Retrieve it later
-        obj = CSSL.shared("data")
-        print(obj["value"])  # 42
-
     Args:
         name: Name of the shared object (without $ prefix)
 
@@ -485,4 +818,64 @@ def shared(name: str) -> Optional[Any]:
     ...
 
 
+def set_global(name: str, value: Any) -> None:
+    """Set a global variable in CSSL runtime."""
+    ...
+
+
+def get_global(name: str) -> Any:
+    """Get a global variable from CSSL runtime."""
+    ...
+
+
+def get_output() -> List[str]:
+    """Get output buffer from last execution."""
+    ...
+
+
+def clear_output() -> None:
+    """Clear output buffer."""
+    ...
+
+
+# =============================================================================
+# Deprecated Aliases (for backwards compatibility)
+# =============================================================================
+
+def exec(path_or_code: str, *args: Any) -> Any:
+    """DEPRECATED: Use run() instead."""
+    ...
+
+
+def T_exec(
+    path_or_code: str,
+    *args: Any,
+    callback: Optional[Callable[[Any], None]] = ...
+) -> threading.Thread:
+    """DEPRECATED: Use T_run() instead."""
+    ...
+
+
+def _exec(code: str, *args: Any) -> Any:
+    """
+    Execute CSSL code directly (alias to avoid conflict with Python builtin exec).
+
+    Usage:
+        from includecpp import CSSL
+        CSSL._exec('''
+            printl("Hello from CSSL!");
+        ''')
+    """
+    ...
+
+
+def _T_exec(
+    code: str,
+    *args: Any,
+    callback: Optional[Callable[[Any], None]] = ...
+) -> threading.Thread:
+    """Execute CSSL code asynchronously (alias for T_exec)."""
+    ...
+
+
 __all__: List[str]