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

includecpp/__init__.py

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

includecpp/core/cssl/CSSL_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # CSSL - C-Style Scripting Language
 
-> Version 3.7.6 | A modern scripting language with C++-style syntax and unique features like CodeInfusion and BruteInjection.
+> Version 3.8.9 | A modern scripting language with C++-style syntax and unique features like CodeInfusion, BruteInjection, and Python Interop.
 
 ---
 
@@ -1696,6 +1696,412 @@ string result = b.add("Hello ").add("World!").build();
 printl(result);  // prints: "Hello World!"
 ```
 
+### Class Inheritance (extends)
+
+CSSL supports class inheritance using the `: extends` syntax:
+
+```cssl
+// Base class
+class Animal {
+    string name;
+
+    void Animal(string n) {
+        this->name = n;
+    }
+
+    void speak() {
+        printl("Some sound");
+    }
+}
+
+// Derived class - inherits all members and methods from Animal
+class Dog : extends Animal {
+    void Dog(string n) {
+        this->name = n;
+    }
+
+    // Override parent method
+    void speak() {
+        printl("Woof! I'm " + this->name);
+    }
+
+    // New method only in Dog
+    void fetch() {
+        printl(this->name + " fetches the ball!");
+    }
+}
+
+Dog d = new Dog("Buddy");
+d.speak();    // "Woof! I'm Buddy"
+d.fetch();    // "Buddy fetches the ball!"
+```
+
+### Extending Python Objects
+
+You can extend Python classes/objects directly:
+
+```cssl
+// Extend a Python object using $
+class ExtendedGame : extends $GameEngine {
+    void newFeature() {
+        printl("New CSSL feature!");
+    }
+
+    // Override a Python method
+    void showUsername() {
+        printl("Custom username display: " + this->username);
+    }
+}
+```
+
+In Python:
+```python
+class GameEngine:
+    def __init__(self):
+        self.username = "Player1"
+    def showUsername(self):
+        print(f"Username: {self.username}")
+
+cssl = CSSL.CsslLang()
+cssl.share('GameEngine', GameEngine())
+cssl.run('''
+    class MyGame : extends $GameEngine {
+        void customMethod() {
+            printl("Extended from Python!");
+        }
+    }
+''')
+```
+
+### Class Overwrites
+
+Use `: overwrites` to replace methods in an existing class/object:
+
+```cssl
+// Overwrite methods in a Python object
+class MyOverrides : extends $GameEngine : overwrites $GameEngine {
+    // This method will REPLACE the original showUsername() in $GameEngine
+    void showUsername() {
+        printl("OVERWRITTEN: " + this->username);
+    }
+}
+```
+
+When you use `: overwrites TargetClass`, all methods defined in your class will replace the corresponding methods in the target. This works with:
+- Other CSSL classes
+- Python objects via `$ObjectName`
+- Shared objects
+
+### python::csslize() - Import Python Objects
+
+Convert Python objects to CSSL-compatible wrappers:
+
+```cssl
+// Import a Python object
+py_obj <== python::csslize($MyPythonInstance);
+
+// Now use it like a CSSL object
+py_obj.someMethod();
+printl(py_obj.someProperty);
+
+// Or use it as a base class
+class Extended : extends py_obj {
+    void newMethod() { ... }
+}
+```
+
+In Python:
+```python
+class MyPythonClass:
+    def __init__(self, name):
+        self.name = name
+    def greet(self):
+        return f"Hello, {self.name}!"
+
+cssl = CSSL.CsslLang()
+cssl.share('MyPython', MyPythonClass("World"))
+result = cssl.run('''
+    py_obj <== python::csslize($MyPython);
+    printl(py_obj.greet());  // "Hello, World!"
+''')
+```
+
+### Function Extends & Overwrites
+
+Functions can also extend or overwrite other functions:
+
+```cssl
+// Base function
+define baseFunction() {
+    string greeting = "Hello";
+    int count = 42;
+    printl(greeting);
+}
+
+// Extend: inherit local variables from baseFunction
+define extendedFunc : extends baseFunction() {
+    // 'greeting' and 'count' are available here!
+    printl(greeting + " World! Count: " + count);
+}
+
+// Overwrite: replace the original function
+define myReplacement : overwrites baseFunction() {
+    printl("This replaces baseFunction entirely!");
+}
+
+// After defining myReplacement, calling baseFunction()
+// will now execute myReplacement instead
+baseFunction();  // prints: "This replaces baseFunction entirely!"
+```
+
+Overwriting Python functions:
+```cssl
+// Replace a shared Python function
+define myVersion : overwrites $pythonFunc() {
+    printl("CSSL implementation replaces Python!");
+}
+```
+
+### Non-Null Declarations
+
+Use `*` prefix to declare non-nullable items:
+
+```cssl
+// Non-null variable - can never be None
+vector<dynamic> *myList;  // Always initialized, never null
+
+// Non-null function - must never return None
+define *alwaysReturns() {
+    return "Always a value";  // Error if returns null
+}
+
+// Non-null class - all methods return non-null
+class *MyClass {
+    string getValue() {
+        return "Value";  // All methods must return non-null
+    }
+}
+
+// Non-null open parameter - filters out None values
+define process(open *Params) {
+    // Params will never contain None values
+    foreach item in Params {
+        printl(item);  // Guaranteed non-null
+    }
+}
+```
+
+### Class Constructors with `constr` Keyword
+
+The `constr` keyword defines explicit constructors inside classes. Multiple constructors can be defined and will be executed in order.
+
+```cssl
+// Class with constructor parameters in declaration
+class Vehicle (string brand, int year) {
+    string make;
+    int modelYear;
+
+    // Constructor using constr keyword
+    constr Initialize() {
+        // brand and year are available from class parameters
+        this->make = brand;
+        this->modelYear = year;
+    }
+
+    // Additional constructor - executed after Initialize
+    constr SetupDefaults() {
+        printl("Vehicle created: " + this->make);
+    }
+}
+
+Vehicle v = new Vehicle("Toyota", 2024);
+```
+
+### Constructor Inheritance with `super()`
+
+Use `super()` to call parent class constructors and methods:
+
+```cssl
+class Animal {
+    string name;
+
+    void Animal(string n) {
+        this->name = n;
+    }
+
+    void speak() {
+        printl("Generic sound");
+    }
+}
+
+class Dog : extends Animal {
+    string breed;
+
+    constr DogInit(string n, string b) {
+        super(n);  // Call parent constructor with name
+        this->breed = b;
+    }
+
+    void speak() {
+        super::speak();  // Call parent's speak method
+        printl("Woof! I'm " + this->name);
+    }
+}
+
+Dog d = new Dog("Buddy", "Labrador");
+d.speak();
+// Output:
+// Generic sound
+// Woof! I'm Buddy
+```
+
+### Constructor Extends with Arguments
+
+Pass arguments to parent constructors in class declaration:
+
+```cssl
+class Parent {
+    int value;
+
+    void Parent(int v) {
+        this->value = v;
+    }
+}
+
+// Pass arguments to parent constructor using extends (arg1, arg2)
+class Child : extends Parent ("defaultValue") {
+    constr ChildInit() {
+        // Parent constructor already called with "defaultValue"
+        printl("Child value: " + this->value);
+    }
+}
+```
+
+### Method-Level Extends & Overwrites
+
+Functions and methods can extend or overwrite specific methods in parent classes using `::` syntax:
+
+```cssl
+class Base {
+    constr Init() {
+        printl("Base init");
+    }
+
+    void process() {
+        printl("Base processing");
+    }
+}
+
+class Derived : extends Base {
+    // Extend specific parent constructor
+    constr DerivedInit() :: extends Base::Init {
+        // Base::Init local vars are available here
+        printl("Derived init");
+    }
+
+    // Or define a method that extends parent method
+    define customProcess :: extends Base::process() {
+        // Has access to Base::process local variables
+        printl("Extended processing");
+    }
+}
+```
+
+### Append Mode with `++` Operator
+
+The `++` append operator allows you to extend constructors and functions by keeping the original code and adding new code. This is useful for extending behavior without completely replacing it.
+
+#### Basic Function Append
+
+```cssl
+// Original function
+define BaseFunc() {
+    printl("Base functionality");
+}
+
+// Append to BaseFunc - keeps original + adds new
+define ExtendedFunc() &BaseFunc ++ {
+    printl("Extended functionality");
+}
+
+ExtendedFunc();
+// Output:
+// Base functionality
+// Extended functionality
+```
+
+#### Constructor Append with Class Reference
+
+```cssl
+class MyClass {
+    constr MyClassConstructor() {
+        printl("MyClass constructor");
+        this->value = 10;
+    }
+}
+
+class BetterClass :: extends MyClass {
+    // Append to specific parent constructor
+    constr BetterConstructor() &MyClass::MyClassConstructor ++ {
+        printl("BetterClass - added code");
+        this->extra = 20;
+    }
+}
+
+$instance = new BetterClass();
+// Output:
+// MyClass constructor
+// BetterClass - added code
+printl($instance.value);  // 10
+printl($instance.extra);  // 20
+```
+
+#### Method Append
+
+```cssl
+class Parent {
+    define greet() {
+        printl("Hello from Parent");
+    }
+}
+
+class Child :: extends Parent {
+    // Append to parent method
+    define betterGreet() &Parent::greet ++ {
+        printl("And also from Child!");
+    }
+}
+
+$child = new Child();
+$child.betterGreet();
+// Output:
+// Hello from Parent
+// And also from Child!
+```
+
+#### Dynamic Instance Reference
+
+You can also reference methods from instances using `&$instanceVar::member`:
+
+```cssl
+global $myInstance = new SomeClass();
+
+class Extended {
+    define extendedMethod() &$myInstance::originalMethod ++ {
+        printl("Added to instance method");
+    }
+}
+```
+
+#### Append Mode Syntax Summary
+
+| Syntax | Description |
+|--------|-------------|
+| `&FunctionName ++` | Append to a function |
+| `&ClassName::member ++` | Append to a class member (constructor/method) |
+| `&$instanceVar::member ++` | Append to an instance member |
+| `&ClassName::constructors ++` | Append to all constructors of a class |
+
 ---
 
 ## Map Container
@@ -2064,6 +2470,7 @@ print(result)  # ["Missing colon after def"]
 | `-<==` | BruteInjection | Move data |
 | `==>` | BruteInjection | Replace data |
 | `==>-` | BruteInjection | Remove matching items |
+| `++` | AppendMode | Append to parent (with `&ref`) |
 
 ### Special Syntax
 
@@ -2075,6 +2482,9 @@ print(result)  # ["Missing colon after def"]
 | `$name` | Access shared Python object |
 | `s@name` | Self-reference to struct |
 | `r@name` | Global variable declaration |
+| `&ClassName::member` | Reference class member for append mode |
+| `&$instance::member` | Reference instance member for append mode |
+| `&FunctionName ++` | Append to function (keeps old + adds new) |
 
 ---
 

includecpp/core/cssl/cssl_builtins.py

@@ -209,6 +209,8 @@ class CSSLBuiltins:
         self._functions['python::pythonize'] = self.builtin_python_pythonize
         self._functions['python::wrap'] = self.builtin_python_pythonize  # Alias
         self._functions['python::export'] = self.builtin_python_pythonize  # Alias
+        self._functions['python::csslize'] = self.builtin_python_csslize
+        self._functions['python::import'] = self.builtin_python_csslize  # Alias
 
         # Regex functions
         self._functions['match'] = self.builtin_match
@@ -2524,6 +2526,137 @@ class CSSLBuiltins:
 
         return PythonizedCSSLInstance(cssl_instance, self.runtime)
 
+    def builtin_python_csslize(self, python_obj: Any) -> Any:
+        """Convert a Python object (class instance or function) to a CSSL-compatible wrapper.
+
+        Syntax:
+            cssl_obj <== python::csslize($python_instance);
+            cssl_func <== python::csslize($python_function);
+
+        Example:
+            # In Python:
+            class MyPythonClass:
+                def __init__(self, name):
+                    self.name = name
+                def greet(self):
+                    return f"Hello, {self.name}!"
+
+            cssl = CSSL.CsslLang()
+            cssl.set_variable('MyPython', MyPythonClass("World"))
+            result = cssl.run('''
+                py_obj <== python::csslize($MyPython);
+                printl(py_obj.greet());  // "Hello, World!"
+            ''')
+
+        For class inheritance:
+            py_class <== python::csslize($MyPythonClass);
+            class MyExtended : extends py_class {
+                void newMethod() { ... }
+            }
+
+        Args:
+            python_obj: A Python object (class instance, function, or class)
+
+        Returns:
+            CSSLizedPythonObject - A CSSL-compatible wrapper
+        """
+        if python_obj is None:
+            return None
+
+        # Already csslized
+        if isinstance(python_obj, CSSLizedPythonObject):
+            return python_obj
+
+        # Wrap the Python object
+        return CSSLizedPythonObject(python_obj, self.runtime)
+
+
+class CSSLizedPythonObject:
+    """CSSL wrapper for Python objects (classes, instances, functions).
+
+    Allows Python objects to be used within CSSL code, including as base classes.
+    """
+
+    def __init__(self, python_obj: Any, runtime: Any = None):
+        self._python_obj = python_obj
+        self._runtime = runtime
+        self._is_class = isinstance(python_obj, type)
+        self._is_callable = callable(python_obj) and not self._is_class
+
+    def __repr__(self):
+        if self._is_class:
+            return f"<CSSLizedPythonClass: {self._python_obj.__name__}>"
+        elif self._is_callable:
+            return f"<CSSLizedPythonFunction: {getattr(self._python_obj, '__name__', 'anonymous')}>"
+        else:
+            return f"<CSSLizedPythonInstance: {type(self._python_obj).__name__}>"
+
+    def __call__(self, *args, **kwargs):
+        """Call the wrapped object (for functions or class instantiation)."""
+        return self._python_obj(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """Get attribute from wrapped Python object."""
+        if name.startswith('_'):
+            raise AttributeError(f"Cannot access private attribute '{name}'")
+
+        obj = object.__getattribute__(self, '_python_obj')
+
+        if hasattr(obj, name):
+            attr = getattr(obj, name)
+            # If it's a method, wrap it for CSSL calling
+            if callable(attr):
+                return CSSLizedPythonMethod(attr, self._runtime)
+            return attr
+
+        raise AttributeError(f"Python object has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any):
+        """Set attribute on wrapped Python object."""
+        if name.startswith('_'):
+            object.__setattr__(self, name, value)
+        else:
+            setattr(self._python_obj, name, value)
+
+    def has_member(self, name: str) -> bool:
+        """Check if the Python object has a member."""
+        return hasattr(self._python_obj, name)
+
+    def get_member(self, name: str) -> Any:
+        """Get a member from the Python object."""
+        return getattr(self._python_obj, name, None)
+
+    def set_member(self, name: str, value: Any):
+        """Set a member on the Python object."""
+        setattr(self._python_obj, name, value)
+
+    def get_method(self, name: str):
+        """Get a method from the Python object."""
+        if hasattr(self._python_obj, name):
+            method = getattr(self._python_obj, name)
+            if callable(method):
+                return CSSLizedPythonMethod(method, self._runtime)
+        return None
+
+    def get_python_obj(self):
+        """Get the underlying Python object (for inheritance)."""
+        return self._python_obj
+
+
+class CSSLizedPythonMethod:
+    """Wrapper for Python methods to be called from CSSL."""
+
+    def __init__(self, method: Any, runtime: Any = None):
+        self._method = method
+        self._runtime = runtime
+
+    def __call__(self, *args, **kwargs):
+        """Call the Python method."""
+        return self._method(*args, **kwargs)
+
+    def __repr__(self):
+        return f"<CSSLizedPythonMethod: {getattr(self._method, '__name__', 'anonymous')}>"
+
 
 class PythonizedCSSLInstance:
     """Python wrapper for CSSL class instances.