IncludeCPP 3.7.3__py3-none-any.whl

includecpp/core/cssl_bridge.pyi

@@ -0,0 +1,488 @@
+"""
+CSSL Bridge - Type Stubs for Python API
+"""
+
+import threading
+from typing import Any, List, Optional, Callable, Dict
+
+
+class CSSLModule:
+    """
+    A callable CSSL module that executes code with arguments.
+
+    Created via CSSL.module() - the code is executed each time the module is called,
+    with arguments accessible via parameter.get(index).
+    """
+
+    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: ...
+
+
+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.
+    """
+
+    def __init__(self, cssl_instance: 'CsslLang', code: str) -> None: ...
+    def __getattr__(self, name: str) -> Callable[..., Any]:
+        """Get a function from the module."""
+        ...
+    def __dir__(self) -> List[str]:
+        """List available functions."""
+        ...
+    def __repr__(self) -> str: ...
+
+
+class CsslLang:
+    """
+    CSSL Language interface for Python.
+
+    Usage:
+        from includecpp import CSSL
+        cssl = CSSL.CsslLang()
+        result = cssl.exec("script.cssl", arg1, arg2)
+        cssl.T_exec("async_script.cssl", arg1)  # Threaded
+    """
+
+    def __init__(self, output_callback: Optional[Callable[[str, str], None]] = ...) -> None:
+        """
+        Initialize CSSL runtime.
+
+        Args:
+            output_callback: Optional callback for output (text, level)
+        """
+        ...
+
+    def exec(self, path_or_code: str, *args: Any) -> Any:
+        """
+        Execute CSSL code or file.
+
+        Args:
+            path_or_code: Path to .cssl file or CSSL code string
+            *args: Arguments to pass to the script
+
+        Returns:
+            Execution result
+        """
+        ...
+
+    def T_exec(
+        self,
+        path_or_code: str,
+        *args: Any,
+        callback: Optional[Callable[[Any], None]] = ...
+    ) -> threading.Thread:
+        """
+        Execute CSSL code asynchronously in a 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
+
+        Returns:
+            Thread object
+        """
+        ...
+
+    def wait_all(self, timeout: Optional[float] = ...) -> None:
+        """Wait for all async executions to complete."""
+        ...
+
+    def get_output(self) -> List[str]:
+        """Get output buffer from last execution."""
+        ...
+
+    def clear_output(self) -> None:
+        """Clear output buffer."""
+        ...
+
+    def set_global(self, name: str, value: Any) -> None:
+        """Set a global variable in CSSL runtime."""
+        ...
+
+    def get_global(self, name: str) -> Any:
+        """Get a global variable from CSSL runtime."""
+        ...
+
+    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"
+
+        Args:
+            code: CSSL code string
+
+        Returns:
+            CSSLModule - a callable module
+        """
+        ...
+
+    def makemodule(self, code: str) -> CSSLFunctionModule:
+        """
+        Create a CSSL module with accessible functions.
+
+        Usage:
+            module = cssl.makemodule('''
+                string greet(string name) {
+                    return "Hello, " + name + "!";
+                }
+            ''')
+            module.greet("World")  # Returns "Hello, World!"
+
+        Args:
+            code: CSSL code string with function definitions
+
+        Returns:
+            CSSLFunctionModule - module with callable function attributes
+        """
+        ...
+
+    def share(self, instance: Any, name: str = ...) -> str:
+        """
+        Share a Python object with CSSL (LIVE sharing).
+
+        Changes in CSSL reflect back to Python immediately.
+
+        Args can be passed in either order:
+            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
+            name: Name to reference in CSSL as $name
+
+        Returns:
+            Path to the shared object marker file
+        """
+        ...
+
+    def unshare(self, name: str) -> bool:
+        """
+        Remove a shared object.
+
+        Args:
+            name: Name of the shared object to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        ...
+
+    def code(self, name: str, code: str) -> None:
+        """
+        Register inline CSSL code as a named payload.
+
+        Usage:
+            cssl.code("helpers", '''
+                void log(string msg) {
+                    printl("[LOG] " + msg);
+                }
+            ''')
+            cssl.exec('''
+                payload("helpers");
+                @log("Hello");
+            ''')
+
+        Args:
+            name: Name for the payload
+            code: CSSL code string
+        """
+        ...
+
+    def get_shared(self, name: str) -> Optional[Any]:
+        """
+        Get a shared object by name (for Python-side access).
+
+        Returns the actual live object reference, not a copy.
+
+        Args:
+            name: Name of the shared object
+
+        Returns:
+            The live shared object or None if not found
+        """
+        ...
+
+    def shared(self, name: str) -> Optional[Any]:
+        """
+        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 shared objects.
+
+        Usage:
+            from includecpp import CSSL
+            cssl = CSSL.CsslLang()
+
+            # 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)
+
+        Returns:
+            The live shared object or None if not found
+        """
+        ...
+
+
+def get_cssl() -> CsslLang:
+    """Get default CSSL instance."""
+    ...
+
+
+def exec(path_or_code: str, *args: Any) -> Any:
+    """
+    Execute CSSL code or file.
+
+    Usage:
+        from includecpp import CSSL
+        CSSL.exec("script.cssl", arg1, arg2)
+        CSSL.exec("printl('Hello World');")
+
+    Args:
+        path_or_code: Path to .cssl file or CSSL code string
+        *args: Arguments to pass to the script
+
+    Returns:
+        Execution result
+    """
+    ...
+
+
+def T_exec(
+    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)
+
+    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
+
+    Returns:
+        Thread object
+    """
+    ...
+
+
+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."""
+    ...
+
+
+# Aliases to avoid conflict with Python builtin exec
+def _exec(code: str, *args: Any) -> Any:
+    """
+    Execute CSSL code directly (alias for exec).
+
+    Supports triple-quoted docstrings for inline CSSL code:
+
+    Usage:
+        from includecpp import CSSL
+        CSSL._exec('''
+            global base = include("abc.cssl-mod");
+
+            void TestFunc() {
+                printl("hey");
+                @base.RechneWas(4, 5);
+            }
+
+            TestFunc();
+        ''')
+
+    Args:
+        code: CSSL code string (supports triple-quoted docstrings)
+        *args: Arguments to pass to the script
+
+    Returns:
+        Execution result
+    """
+    ...
+
+
+def _T_exec(
+    code: str,
+    *args: Any,
+    callback: Optional[Callable[[Any], None]] = ...
+) -> threading.Thread:
+    """
+    Execute CSSL code asynchronously in a thread (alias for T_exec).
+
+    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.
+
+    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
+    """
+    ...
+
+
+def makemodule(code: str) -> 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
+
+    Returns:
+        CSSLFunctionModule - module with callable function attributes
+    """
+    ...
+
+
+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
+
+    Args:
+        instance: Python object to share
+        name: Name to reference in CSSL as $name
+
+    Returns:
+        Path to the shared object marker file
+    """
+    ...
+
+
+def unshare(name: str) -> bool:
+    """
+    Remove a globally shared object.
+
+    Args:
+        name: Name of the shared object to remove
+
+    Returns:
+        True if removed, False if not found
+    """
+    ...
+
+
+def get_shared(name: str) -> Optional[Any]:
+    """
+    Get a globally shared object by name.
+
+    Args:
+        name: Name of the shared object
+
+    Returns:
+        The live shared object or None if not found
+    """
+    ...
+
+
+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)
+
+    Returns:
+        The live shared object or None if not found
+    """
+    ...
+
+
+__all__: List[str]