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

includecpp/core/cssl/cssl_types.py

@@ -1624,10 +1624,181 @@ class CSSLInstance:
         return f"<{self._class.name} instance at 0x{id(self):x}>"
 
 
+class UniversalInstance:
+    """Universal shared container accessible from CSSL, Python, and C++.
+
+    Created via instance<"name"> syntax in CSSL or getInstance("name") in Python.
+    Supports dynamic member/method injection via +<<== operator.
+
+    Example CSSL:
+        instance<"myContainer"> container;
+        container +<<== { void sayHello() { printl("Hello!"); } }
+        container.sayHello();
+
+    Example Python:
+        container = cssl.getInstance("myContainer")
+        container.sayHello()
+    """
+
+    # Global registry for all universal instances
+    _registry: Dict[str, 'UniversalInstance'] = {}
+
+    def __init__(self, name: str):
+        self._name = name
+        self._members: Dict[str, Any] = {}
+        self._methods: Dict[str, Any] = {}  # Method name -> AST node or callable
+        self._injections: List[Any] = []  # Code blocks injected via +<<==
+        self._runtime = None  # Weak reference to CSSL runtime for method calls
+        # Register globally
+        UniversalInstance._registry[name] = self
+
+    @classmethod
+    def get_or_create(cls, name: str) -> 'UniversalInstance':
+        """Get existing instance or create new one."""
+        if name in cls._registry:
+            return cls._registry[name]
+        return cls(name)
+
+    @classmethod
+    def get(cls, name: str) -> Optional['UniversalInstance']:
+        """Get existing instance by name, returns None if not found."""
+        return cls._registry.get(name)
+
+    @classmethod
+    def exists(cls, name: str) -> bool:
+        """Check if instance exists."""
+        return name in cls._registry
+
+    @classmethod
+    def delete(cls, name: str) -> bool:
+        """Delete instance from registry."""
+        if name in cls._registry:
+            del cls._registry[name]
+            return True
+        return False
+
+    @classmethod
+    def clear_all(cls) -> int:
+        """Clear all instances. Returns count of cleared instances."""
+        count = len(cls._registry)
+        cls._registry.clear()
+        return count
+
+    @classmethod
+    def list_all(cls) -> List[str]:
+        """List all instance names."""
+        return list(cls._registry.keys())
+
+    @property
+    def name(self) -> str:
+        """Get instance name."""
+        return self._name
+
+    def set_member(self, name: str, value: Any) -> None:
+        """Set a member value."""
+        self._members[name] = value
+
+    def get_member(self, name: str) -> Any:
+        """Get a member value."""
+        if name in self._members:
+            return self._members[name]
+        raise AttributeError(f"Instance '{self._name}' has no member '{name}'")
+
+    def has_member(self, name: str) -> bool:
+        """Check if member exists."""
+        return name in self._members
+
+    def set_runtime(self, runtime: Any) -> None:
+        """Set the runtime reference for method calls from Python."""
+        import weakref
+        self._runtime = weakref.ref(runtime)
+
+    def set_method(self, name: str, method: Any, runtime: Any = None) -> None:
+        """Set a method (AST node or callable)."""
+        self._methods[name] = method
+        if runtime is not None and self._runtime is None:
+            self.set_runtime(runtime)
+
+    def get_method(self, name: str) -> Any:
+        """Get a method by name."""
+        if name in self._methods:
+            return self._methods[name]
+        raise AttributeError(f"Instance '{self._name}' has no method '{name}'")
+
+    def has_method(self, name: str) -> bool:
+        """Check if method exists."""
+        return name in self._methods
+
+    def add_injection(self, code_block: Any) -> None:
+        """Add a code injection (from +<<== operator)."""
+        self._injections.append(code_block)
+
+    def get_injections(self) -> List[Any]:
+        """Get all injected code blocks."""
+        return self._injections
+
+    def get_all_members(self) -> Dict[str, Any]:
+        """Get all members."""
+        return dict(self._members)
+
+    def get_all_methods(self) -> Dict[str, Any]:
+        """Get all methods."""
+        return dict(self._methods)
+
+    def __getattr__(self, name: str) -> Any:
+        """Allow direct attribute access for members and methods."""
+        if name.startswith('_'):
+            raise AttributeError(name)
+        if name in object.__getattribute__(self, '_members'):
+            return object.__getattribute__(self, '_members')[name]
+        if name in object.__getattribute__(self, '_methods'):
+            method = object.__getattribute__(self, '_methods')[name]
+            runtime_ref = object.__getattribute__(self, '_runtime')
+
+            # If method is an AST node and we have a runtime, create a callable wrapper
+            if hasattr(method, 'type') and method.type == 'function' and runtime_ref is not None:
+                runtime = runtime_ref()  # Dereference weakref
+                if runtime is not None:
+                    instance = self
+                    def method_caller(*args, **kwargs):
+                        # Set 'this' context and call the method
+                        old_this = runtime.scope.get('this')
+                        runtime.scope.set('this', instance)
+                        try:
+                            return runtime._call_function(method, list(args))
+                        finally:
+                            if old_this is not None:
+                                runtime.scope.set('this', old_this)
+                            elif hasattr(runtime.scope, 'remove'):
+                                runtime.scope.remove('this')
+                    return method_caller
+            # Return method directly if already callable or no runtime
+            return method
+        raise AttributeError(f"Instance '{object.__getattribute__(self, '_name')}' has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Allow direct attribute setting for members."""
+        if name.startswith('_'):
+            object.__setattr__(self, name, value)
+        else:
+            if hasattr(self, '_members'):
+                self._members[name] = value
+            else:
+                object.__setattr__(self, name, value)
+
+    def __repr__(self):
+        members = len(self._members)
+        methods = len(self._methods)
+        return f"<UniversalInstance '{self._name}' ({members} members, {methods} methods)>"
+
+    def __str__(self):
+        return f"<UniversalInstance '{self._name}'>"
+
+
 __all__ = [
     'DataStruct', 'Shuffled', 'Iterator', 'Combo', 'DataSpace', 'OpenQuote',
     'OpenFind', 'Parameter', 'Stack', 'Vector', 'Array', 'List', 'Dictionary', 'Map',
-    'CSSLClass', 'CSSLInstance',
+    'CSSLClass', 'CSSLInstance', 'UniversalInstance',
     'create_datastruct', 'create_shuffled', 'create_iterator',
     'create_combo', 'create_dataspace', 'create_openquote', 'create_parameter',
     'create_stack', 'create_vector', 'create_array', 'create_list', 'create_dictionary', 'create_map'

includecpp/core/cssl_bridge.py

@@ -266,8 +266,8 @@ class CSSLFunctionModule:
 
         from .cssl import CSSLRuntime, parse_cssl_program, ASTNode
 
-        # Create a dedicated runtime for this module
-        self._runtime = CSSLRuntime()
+        # Create a dedicated runtime for this module, preserving output_callback
+        self._runtime = CSSLRuntime(output_callback=self._cssl._output_callback)
 
         # If we have a payload, load it first (defines functions/globals for main)
         if self._payload_code:
@@ -330,7 +330,12 @@ class CSSLFunctionModule:
                 self._runtime.global_scope.set('parameter', Parameter(list(args)))
                 self._runtime.global_scope.set('args', list(args))
                 self._runtime.global_scope.set('argc', len(args))
-                return self._runtime._call_function(func_node, list(args))
+                # Enable running flag for function execution
+                self._runtime._running = True
+                try:
+                    return self._runtime._call_function(func_node, list(args))
+                finally:
+                    self._runtime._running = False
 
             return wrapper
 
@@ -603,7 +608,8 @@ class CsslLang:
         self,
         main_script: Union[str, 'CSSLScript'],
         payload_script: Union[str, 'CSSLScript', None] = None,
-        name: str = None
+        name: str = None,
+        bind: str = None
     ) -> 'CSSLFunctionModule':
         """
         Create a CSSL module with accessible functions.
@@ -612,13 +618,22 @@ class CsslLang:
         Optionally registers the module for payload() access in other scripts.
 
         Args:
-            main_script: Main CSSL code (string or CSSLScript)
+            main_script: Main CSSL code, file path, or CSSLScript
             payload_script: Optional payload code (string or CSSLScript)
             name: Optional name to register for payload(name) access
+            bind: Optional payload name to auto-prepend (from makepayload)
 
         Returns:
             CSSLFunctionModule - module with callable function attributes
 
+        Usage (simplified - with file path and bind):
+            # First register the payload
+            cssl.makepayload("api", "lib/api/einkaufsmanager.cssl-pl")
+
+            # Then create module from file, binding to payload
+            mod = cssl.makemodule("writer", "lib/writer.cssl", bind="api")
+            mod.SaySomething("Hello!")  # Functions are now accessible
+
         Usage (v3.8.0 - with CSSLScript objects):
             main = cssl.script("cssl", '''
                 printl("Main");
@@ -644,6 +659,28 @@ class CsslLang:
             ''')
             module.greet("World")  # Returns "Hello, World!"
         """
+        # Handle simplified API: makemodule(name, path, bind=...)
+        # Check if main_script looks like a short identifier and payload_script looks like a path
+        if (isinstance(main_script, str) and isinstance(payload_script, str) and
+            not '\n' in main_script and not ';' in main_script and not '{' in main_script):
+            # main_script is likely a name, payload_script is likely a path
+            module_name = main_script
+            path = payload_script
+
+            # Check if it's actually a file path
+            path_obj = Path(path)
+            if path_obj.exists():
+                main_code = path_obj.read_text(encoding='utf-8')
+
+                # If bind is specified, prepend that payload's code
+                payload_code = None
+                if bind:
+                    runtime = self._get_runtime()
+                    if hasattr(runtime, '_inline_payloads') and bind in runtime._inline_payloads:
+                        payload_code = runtime._inline_payloads[bind]
+
+                return CSSLFunctionModule(self, main_code, payload_code, module_name)
+
         # Extract code from CSSLScript objects if provided
         if isinstance(main_script, CSSLScript):
             main_code = main_script.code
@@ -657,6 +694,12 @@ class CsslLang:
             else:
                 payload_code = payload_script
 
+        # If bind is specified and no payload_script, use the bound payload
+        if bind and payload_code is None:
+            runtime = self._get_runtime()
+            if hasattr(runtime, '_inline_payloads') and bind in runtime._inline_payloads:
+                payload_code = runtime._inline_payloads[bind]
+
         return CSSLFunctionModule(self, main_code, payload_code, name)
 
     def load(self, path: str, name: str) -> None:
@@ -781,6 +824,45 @@ class CsslLang:
             runtime._inline_payloads = {}
         runtime._inline_payloads[name] = code
 
+    def makepayload(self, name: str, path: str) -> str:
+        """
+        Register a payload from a file path.
+
+        Reads the file and registers it as a payload accessible via payload(name) in CSSL.
+        This is a convenience method that combines reading a file and calling code().
+
+        Usage:
+            from includecpp import CSSL
+            cssl = CSSL.CsslLang()
+
+            # Register a payload from file
+            cssl.makepayload("api", "lib/api/myapi.cssl-pl")
+
+            # Now use in CSSL code
+            cssl.run('''
+                payload("api");  // Load the payload
+                myApiFunction();  // Call functions from it
+            ''')
+
+            # Or use with makemodule for automatic binding
+            mod = cssl.makemodule("writer", "lib/writer.cssl", bind="api")
+            mod.SaySomething("Hello!")
+
+        Args:
+            name: Name to register the payload under (used in payload(name) and bind=name)
+            path: Path to the .cssl-pl or .cssl file
+
+        Returns:
+            The payload code that was registered
+        """
+        path_obj = Path(path)
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Payload file not found: {path}")
+
+        code = path_obj.read_text(encoding='utf-8')
+        self.code(name, code)
+        return code
+
     def share(self, instance: Any, name: str = None) -> str:
         """
         Share a Python object instance with CSSL scripts (LIVE sharing).
@@ -979,6 +1061,73 @@ class CsslLang:
         """
         return self.get_shared(name)
 
+    def getInstance(self, name: str) -> Optional[Any]:
+        """
+        Get a universal instance by name (for Python-side access).
+
+        Universal instances are shared containers accessible from CSSL, Python, and C++.
+        They support dynamic member/method access and are mutable across all contexts.
+
+        Usage:
+            from includecpp import CSSL
+            cssl = CSSL.CsslLang()
+
+            # In CSSL: instance<"myContainer"> container;
+            # Then in Python:
+            container = cssl.getInstance("myContainer")
+            container.member = "value"
+            print(container.member)  # value
+
+        Args:
+            name: Name of the instance (without quotes)
+
+        Returns:
+            The UniversalInstance or None if not found
+        """
+        from .cssl.cssl_types import UniversalInstance
+        return UniversalInstance.get(name)
+
+    def createInstance(self, name: str) -> Any:
+        """
+        Create or get a universal instance by name (for Python-side creation).
+
+        Usage:
+            container = cssl.createInstance("myContainer")
+            container.data = {"key": "value"}
+            # Now accessible in CSSL via instance<"myContainer">
+
+        Args:
+            name: Name for the instance
+
+        Returns:
+            The UniversalInstance (new or existing)
+        """
+        from .cssl.cssl_types import UniversalInstance
+        return UniversalInstance.get_or_create(name)
+
+    def deleteInstance(self, name: str) -> bool:
+        """
+        Delete a universal instance by name.
+
+        Args:
+            name: Name of the instance to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        from .cssl.cssl_types import UniversalInstance
+        return UniversalInstance.delete(name)
+
+    def listInstances(self) -> list:
+        """
+        List all universal instance names.
+
+        Returns:
+            List of instance names
+        """
+        from .cssl.cssl_types import UniversalInstance
+        return UniversalInstance.list_all()
+
 
 # Global shared objects registry (for cross-instance sharing)
 _global_shared_objects: Dict[str, str] = {}
@@ -1303,14 +1452,49 @@ def module(code: str) -> CSSLModule:
     return get_cssl().module(code)
 
 
+def makepayload(name: str, path: str) -> str:
+    """
+    Register a payload from a file path.
+
+    Reads the file and registers it as a payload accessible via payload(name) in CSSL.
+
+    Usage:
+        from includecpp import CSSL
+
+        # Register a payload from file
+        CSSL.makepayload("api", "lib/api/myapi.cssl-pl")
+
+        # Use with makemodule for automatic binding
+        mod = CSSL.makemodule("writer", "lib/writer.cssl", bind="api")
+        mod.SaySomething("Hello!")
+
+    Args:
+        name: Name to register the payload under (used in payload(name) and bind=name)
+        path: Path to the .cssl-pl or .cssl file
+
+    Returns:
+        The payload code that was registered
+    """
+    return get_cssl().makepayload(name, path)
+
+
 def makemodule(
     main_script: Union[str, CSSLScript],
     payload_script: Union[str, CSSLScript, None] = None,
-    name: str = None
+    name: str = None,
+    bind: str = None
 ) -> CSSLFunctionModule:
     """
     Create a CSSL module with accessible functions.
 
+    Usage (simplified - with file path and bind):
+        # First register the payload
+        CSSL.makepayload("api", "lib/api/einkaufsmanager.cssl-pl")
+
+        # Then create module from file, binding to payload
+        mod = CSSL.makemodule("writer", "lib/writer.cssl", bind="api")
+        mod.SaySomething("Hello!")
+
     Usage (v3.8.0 - with CSSLScript):
         main = CSSL.script("cssl", '''printl("Main");''')
         payload = CSSL.script("cssl-pl", '''void helper() {}''')
@@ -1323,14 +1507,15 @@ def makemodule(
         math_mod.add(2, 3)  # Returns 5
 
     Args:
-        main_script: Main CSSL code (string or CSSLScript)
+        main_script: Main CSSL code, file path, or CSSLScript
         payload_script: Optional payload code (string or CSSLScript)
         name: Optional name to register for payload(name) access
+        bind: Optional payload name to auto-prepend (from makepayload)
 
     Returns:
         CSSLFunctionModule - module with callable function attributes
     """
-    return get_cssl().makemodule(main_script, payload_script, name)
+    return get_cssl().makemodule(main_script, payload_script, name, bind)
 
 
 # Export all
@@ -1360,6 +1545,7 @@ __all__ = [
     'get_output',
     'clear_output',
     'module',
+    'makepayload',
     'makemodule',
     'share',
     'unshare',

includecpp/core/cssl_bridge.pyi

@@ -412,7 +412,37 @@ class CsslLang:
         """
         ...
 
-    def makemodule(self, code_or_script: Union[str, CSSLScript], *more: Any) -> CSSLFunctionModule:
+    def makepayload(self, name: str, path: str) -> str:
+        """
+        Register a payload from a file path.
+
+        Reads the file and registers it as a payload accessible via payload(name) in CSSL.
+        This is a convenience method for loading payload files.
+
+        Args:
+            name: Name to register the payload under (used in payload(name) and bind=name)
+            path: Path to the .cssl-pl or .cssl file
+
+        Returns:
+            The payload code that was registered
+
+        Usage:
+            # Register a payload from file
+            cssl.makepayload("api", "lib/api/myapi.cssl-pl")
+
+            # Use with makemodule for automatic binding
+            mod = cssl.makemodule("writer", "lib/writer.cssl", bind="api")
+            mod.SaySomething("Hello!")
+        """
+        ...
+
+    def makemodule(
+        self,
+        main_script: Union[str, CSSLScript],
+        payload_script: Union[str, CSSLScript, None] = ...,
+        name: str = ...,
+        bind: str = ...
+    ) -> CSSLFunctionModule:
         """
         Create a CSSL module with accessible functions as methods.
 
@@ -420,14 +450,23 @@ class CsslLang:
         Functions defined in the code become callable Python methods.
 
         Args:
-            code_or_script: CSSL code string or CSSLScript object
-            *more: Additional scripts or module name
+            main_script: CSSL code string, file path, or CSSLScript object
+            payload_script: Optional payload code (string or CSSLScript)
+            name: Optional name to register for payload(name) access
+            bind: Optional payload name to auto-prepend (from makepayload)
 
         Returns:
             CSSLFunctionModule with callable function attributes
 
-        Usage:
-            # From code string
+        Usage (simplified - with file path and bind):
+            # First register the payload
+            cssl.makepayload("api", "lib/api/einkaufsmanager.cssl-pl")
+
+            # Then create module from file, binding to payload
+            mod = cssl.makemodule("writer", "lib/writer.cssl", bind="api")
+            mod.SaySomething("Hello!")  # Functions are now accessible
+
+        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; }
@@ -435,7 +474,7 @@ class CsslLang:
             print(math.add(10, 5))  # 15
             print(math.sub(10, 5))  # 5
 
-            # From script objects (for .cssl-mod creation)
+        Usage (from script objects):
             main = cssl.script("cssl", "...")
             helpers = cssl.script("cssl-pl", "...")
             mod = cssl.makemodule(main, helpers, "mymodule")
@@ -541,6 +580,66 @@ class CsslLang:
         """
         ...
 
+    def getInstance(self, name: str) -> Optional[Any]:
+        """
+        Get a universal instance by name (for Python-side access).
+
+        Universal instances are shared containers accessible from CSSL, Python, and C++.
+        They support dynamic member/method access and are mutable across all contexts.
+
+        Args:
+            name: Name of the instance (without quotes)
+
+        Returns:
+            The UniversalInstance or None if not found
+
+        Usage:
+            # In CSSL: instance<"myContainer"> container;
+            # Then in Python:
+            container = cssl.getInstance("myContainer")
+            container.member = "value"
+            print(container.member)  # value
+        """
+        ...
+
+    def createInstance(self, name: str) -> Any:
+        """
+        Create or get a universal instance by name (for Python-side creation).
+
+        Args:
+            name: Name for the instance
+
+        Returns:
+            The UniversalInstance (new or existing)
+
+        Usage:
+            container = cssl.createInstance("myContainer")
+            container.data = {"key": "value"}
+            # Now accessible in CSSL via instance<"myContainer">
+        """
+        ...
+
+    def deleteInstance(self, name: str) -> bool:
+        """
+        Delete a universal instance by name.
+
+        Args:
+            name: Name of the instance to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        ...
+
+    def listInstances(self) -> List[str]:
+        """
+        List all universal instance names.
+
+        Returns:
+            List of instance names
+        """
+        ...
+
     def set_global(self, name: str, value: Any) -> None:
         """
         Set a global variable in the CSSL runtime.
@@ -733,20 +832,59 @@ def module(code: str) -> CSSLModule:
     ...
 
 
-def makemodule(code_or_script: Union[str, CSSLScript], *more: Any) -> CSSLFunctionModule:
+def makepayload(name: str, path: str) -> str:
+    """
+    Register a payload from a file path.
+
+    Reads the file and registers it as a payload accessible via payload(name) in CSSL.
+
+    Args:
+        name: Name to register the payload under (used in payload(name) and bind=name)
+        path: Path to the .cssl-pl or .cssl file
+
+    Returns:
+        The payload code that was registered
+
+    Usage:
+        from includecpp import CSSL
+
+        # Register a payload from file
+        CSSL.makepayload("api", "lib/api/myapi.cssl-pl")
+
+        # Use with makemodule for automatic binding
+        mod = CSSL.makemodule("writer", "lib/writer.cssl", bind="api")
+        mod.SaySomething("Hello!")
+    """
+    ...
+
+
+def makemodule(
+    main_script: Union[str, CSSLScript],
+    payload_script: Union[str, CSSLScript, None] = ...,
+    name: str = ...,
+    bind: str = ...
+) -> CSSLFunctionModule:
     """
     Create a CSSL module with accessible functions.
 
     Args:
-        code_or_script: CSSL code string or CSSLScript object
-        *more: Additional scripts or module name
+        main_script: CSSL code string, file path, or CSSLScript object
+        payload_script: Optional payload code (string or CSSLScript)
+        name: Optional name to register for payload(name) access
+        bind: Optional payload name to auto-prepend (from makepayload)
 
     Returns:
         CSSLFunctionModule with callable function attributes
 
-    Usage:
+    Usage (simplified):
         from includecpp import CSSL
 
+        # Register payload and create module
+        CSSL.makepayload("api", "lib/api/myapi.cssl-pl")
+        mod = CSSL.makemodule("writer", "lib/writer.cssl", bind="api")
+        mod.SaySomething("Hello!")
+
+    Usage (code string):
         math = CSSL.makemodule('''
             int add(int a, int b) { return a + b; }
         ''')