IncludeCPP 3.6.0__py3-none-any.whl → 3.7.9__py3-none-any.whl

includecpp/core/cssl/CSSL_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # CSSL - C-Style Scripting Language
 
-> Version 3.6.0 | A modern scripting language with C++-style syntax and unique features like CodeInfusion and BruteInjection.
+> Version 3.7.6 | A modern scripting language with C++-style syntax and unique features like CodeInfusion and BruteInjection.
 
 ---
 
@@ -17,17 +17,20 @@
 9. [String Methods](#string-methods)
 10. [File I/O](#file-io)
 11. [JSON Functions](#json-functions)
-12. [Live Object Sharing](#live-object-sharing)
-13. [CodeInfusion](#codeinfusion)
-14. [Value Capture](#value-capture)
-15. [BruteInjection](#bruteinjection)
-16. [Filter Syntax](#filter-syntax)
-17. [Module System](#module-system)
-18. [Parameter Bridge](#parameter-bridge)
-19. [Structures](#structures)
-20. [Error Handling](#error-handling)
-21. [CLI Commands](#cli-commands)
-22. [Examples](#examples)
+12. [Instance Management](#instance-management)
+13. [Live Object Sharing](#live-object-sharing)
+14. [CodeInfusion](#codeinfusion)
+15. [Value Capture](#value-capture)
+16. [BruteInjection](#bruteinjection)
+17. [Filter Syntax](#filter-syntax)
+18. [Module System](#module-system)
+19. [Parameter Bridge](#parameter-bridge)
+20. [Classes & OOP](#classes--oop)
+21. [Map Container](#map-container)
+22. [Structures](#structures)
+23. [Error Handling](#error-handling)
+24. [CLI Commands](#cli-commands)
+25. [Examples](#examples)
 
 ---
 
@@ -38,22 +41,25 @@
 ```python
 from includecpp import CSSL
 
-# Initialize CSSL
-CSSL.CsslLang()
-
-# Execute code
-CSSL.exec("""
+# Execute code (v3.7.6+: use run() instead of exec())
+CSSL.run("""
     printl("Hello CSSL!");
 """)
 
 # With parameters and return value
-result = CSSL.exec("""
+result = CSSL.run("""
     string name = parameter.get(0);
     printl("Hello " + name);
     parameter.return(true);
 """, "World")
 
 print(result)  # True
+
+# Create typed scripts and modules (v3.7.6+)
+main = CSSL.script("cssl", '''printl("Main");''')
+payload = CSSL.script("cssl-pl", '''void helper() { printl("Helper!"); }''')
+mod = CSSL.makemodule(main, payload, "mymod")
+mod.helper()  # Call function directly
 ```
 
 ### CLI Execution
@@ -698,12 +704,24 @@ super void forceRun() {
 
 ### shuffled
 
-Allows multiple return values.
+Allows multiple return values with tuple unpacking.
 
 ```cssl
 shuffled string getNames() {
     return "Alice", "Bob", "Charlie";
 }
+
+// Tuple unpacking (v3.7.6+)
+a, b, c = getNames();
+printl(a);  // "Alice"
+printl(b);  // "Bob"
+printl(c);  // "Charlie"
+
+// Works with any types
+shuffled getValues() {
+    return "text", 42, true;
+}
+name, num, flag = getValues();
 ```
 
 ---
@@ -1000,6 +1018,83 @@ json merged = json::merge(obj1, obj2, obj3);
 
 ---
 
+## Instance Management
+
+CSSL provides `instance<"name">` syntax and `instance::` namespace for working with shared instances.
+
+### Instance Declaration
+
+```cssl
+// Get/create shared instance by name
+instance<"MyApp"> app;
+
+// With initialization
+instance<"tk"> tk = include("tkinter.cssl-mod");
+
+// Register object as shared instance
+myModule ==> $AppModule
+// Or using instance syntax:
+myModule ==> instance<"AppModule">
+```
+
+### Instance Introspection
+
+```cssl
+@tk = include("tk.cssl-mod");
+
+// Get all methods from module
+stack<string> methods = instance::getMethods(@tk);
+foreach (m in methods) {
+    printl("Method: " + m);
+}
+
+// Get all classes
+stack<string> classes = instance::getClasses(@tk);
+
+// Get all variables
+stack<string> vars = instance::getVars(@tk);
+
+// Get everything categorized
+json all = instance::getAll(@tk);
+printl(all.methods);   // ["method1", "method2", ...]
+printl(all.classes);   // ["Class1", "Class2", ...]
+printl(all.vars);      // ["var1", "var2", ...]
+```
+
+### Dynamic Method Calls
+
+```cssl
+// Call method dynamically by name
+result = instance::call(@module, "methodName", arg1, arg2);
+
+// Check if method/attribute exists
+if (instance::has(@module, "initialize")) {
+    instance::call(@module, "initialize");
+}
+
+// Get type name
+string typeName = instance::type(@module);
+printl(typeName);  // "module"
+```
+
+### All Instance Functions
+
+| Function | Description |
+|----------|-------------|
+| `instance<"name"> var` | Declare instance variable |
+| `obj ==> instance<"name">` | Register as shared instance |
+| `instance::getMethods(obj)` | Get all method names |
+| `instance::getClasses(obj)` | Get all class names |
+| `instance::getVars(obj)` | Get all variable names |
+| `instance::getAll(obj)` | Get categorized dict |
+| `instance::call(obj, 'name', ...)` | Call method dynamically |
+| `instance::has(obj, 'name')` | Check if attribute exists |
+| `instance::type(obj)` | Get type name |
+| `isavailable("name")` | Check if shared instance exists |
+| `instance::exists("name")` | Alias for isavailable |
+
+---
+
 ## Live Object Sharing
 
 Share Python objects with CSSL. Changes in CSSL reflect back to Python.
@@ -1063,6 +1158,10 @@ print(stats.total)  # 50 - Persisted!
 
 CodeInfusion enables modifying functions at runtime.
 
+> **Important**: Injection operators must be written **without spaces**:
+> - ✓ `func() <<==` / `func() +<<==` / `func() -<<==` (correct)
+> - ✗ `func() < <==` / `func() + <<==` / `func() - <<==` (wrong)
+
 ### <<== (Replace)
 
 Replaces function content.
@@ -1475,6 +1574,188 @@ parameter.return(myObject);       // JSON/dict
 
 ---
 
+## Classes & OOP
+
+CSSL supports object-oriented programming with classes, constructors, and the `this->` keyword for member access.
+
+### Defining a Class
+
+```cssl
+class Person {
+    // Member variables
+    string name;
+    int age;
+
+    // Constructor (same name as class)
+    void Person(string n, int a) {
+        this->name = n;
+        this->age = a;
+    }
+
+    // Methods
+    void greet() {
+        printl("Hello, I'm " + this->name);
+    }
+
+    string getName() {
+        return this->name;
+    }
+
+    void setAge(int a) {
+        this->age = a;
+    }
+}
+```
+
+### Creating Instances
+
+```cssl
+// Use 'new' keyword to instantiate
+Person p = new Person("Alice", 30);
+
+// Call methods
+p.greet();                    // prints: "Hello, I'm Alice"
+string name = p.getName();    // returns "Alice"
+
+// Access members (if public)
+printl(p.name);              // prints: "Alice"
+p.age = 31;                  // set member directly
+```
+
+### The `this->` Keyword
+
+Inside class methods, use `this->` to access instance members:
+
+```cssl
+class Counter {
+    int count;
+
+    void Counter() {
+        this->count = 0;
+    }
+
+    void increment() {
+        this->count = this->count + 1;
+    }
+
+    void add(int n) {
+        this->count = this->count + n;
+    }
+
+    int get() {
+        return this->count;
+    }
+}
+
+Counter c = new Counter();
+c.increment();
+c.add(5);
+printl(c.get());  // prints: 6
+```
+
+### Constructor Variations
+
+```cssl
+class MyClass {
+    // Constructor with same name as class
+    void MyClass(int x) {
+        this->value = x;
+    }
+}
+
+// Alternative: use __init__
+class MyClass2 {
+    void __init__(int x) {
+        this->value = x;
+    }
+}
+```
+
+### Method Chaining
+
+```cssl
+class Builder {
+    string result;
+
+    void Builder() {
+        this->result = "";
+    }
+
+    Builder add(string s) {
+        this->result = this->result + s;
+        return this;
+    }
+
+    string build() {
+        return this->result;
+    }
+}
+
+Builder b = new Builder();
+string result = b.add("Hello ").add("World!").build();
+printl(result);  // prints: "Hello World!"
+```
+
+---
+
+## Map Container
+
+The `map<>` type provides C++ style ordered key-value storage.
+
+### Creating Maps
+
+```cssl
+map<string, int> ages;
+map<string, string> config;
+```
+
+### Basic Operations
+
+```cssl
+map<string, int> ages;
+
+// Insert values
+ages.insert("Alice", 30);
+ages.insert("Bob", 25);
+
+// Find values
+int age = ages.find("Alice");  // returns 30
+
+// Check existence
+if (ages.contains("Alice")) {
+    printl("Found!");
+}
+
+// Erase entries
+ages.erase("Bob");
+
+// Get with exception if not found
+int a = ages.at("Alice");  // throws if not found
+
+// Size and empty check
+int size = ages.size();
+bool empty = ages.empty();
+```
+
+### Iteration and Bounds
+
+```cssl
+map<string, int> data;
+data.insert("apple", 1);
+data.insert("banana", 2);
+data.insert("cherry", 3);
+
+// Get first/last elements
+tuple first = data.begin();  // ("apple", 1)
+tuple last = data.end();     // ("cherry", 3)
+
+// Find bounds (for sorted keys)
+string lb = data.lower_bound("b");  // "banana" (first key >= "b")
+string ub = data.upper_bound("b");  // "cherry" (first key > "b")
+```
+
+---
+
 ## Structures
 
 Structures are user-defined data types.
@@ -1810,4 +2091,4 @@ print(result)  # ["Missing colon after def"]
 
 ---
 
-*CSSL v3.6.0 - Developed as part of IncludeCPP*
+*CSSL v3.6.3 - Developed as part of IncludeCPP*

includecpp/core/cssl/cssl_builtins.py

@@ -194,6 +194,17 @@ class CSSLBuiltins:
         self._functions['json::has'] = self.builtin_json_has
         self._functions['json::merge'] = self.builtin_json_merge
 
+        # Instance introspection functions (instance::getMethods, etc.)
+        self._functions['instance::getMethods'] = self.builtin_instance_getMethods
+        self._functions['instance::getClasses'] = self.builtin_instance_getClasses
+        self._functions['instance::getVars'] = self.builtin_instance_getVars
+        self._functions['instance::getAll'] = self.builtin_instance_getAll
+        self._functions['instance::call'] = self.builtin_instance_call
+        self._functions['instance::has'] = self.builtin_instance_has
+        self._functions['instance::type'] = self.builtin_instance_type
+        self._functions['isavailable'] = self.builtin_isavailable
+        self._functions['instance::exists'] = self.builtin_isavailable  # Alias
+
         # Regex functions
         self._functions['match'] = self.builtin_match
         self._functions['search'] = self.builtin_search
@@ -1026,6 +1037,109 @@ class CSSLBuiltins:
                 result = deep_merge(result, d)
         return result
 
+    # ============= Instance Introspection Functions =============
+
+    def builtin_instance_getMethods(self, obj: Any) -> list:
+        """Get all methods from an object/module.
+        Usage: instance::getMethods(@module) or instance::getMethods($obj)
+        Returns list of method names.
+        """
+        import inspect
+        methods = []
+        for name in dir(obj):
+            if not name.startswith('_'):
+                attr = getattr(obj, name, None)
+                if callable(attr):
+                    methods.append(name)
+        return methods
+
+    def builtin_instance_getClasses(self, obj: Any) -> list:
+        """Get all classes from an object/module.
+        Usage: instance::getClasses(@module)
+        Returns list of class names.
+        """
+        import inspect
+        classes = []
+        for name in dir(obj):
+            if not name.startswith('_'):
+                attr = getattr(obj, name, None)
+                if inspect.isclass(attr):
+                    classes.append(name)
+        return classes
+
+    def builtin_instance_getVars(self, obj: Any) -> list:
+        """Get all variables/attributes (non-callable) from an object.
+        Usage: instance::getVars(@module)
+        Returns list of variable names.
+        """
+        vars_list = []
+        for name in dir(obj):
+            if not name.startswith('_'):
+                attr = getattr(obj, name, None)
+                if not callable(attr):
+                    vars_list.append(name)
+        return vars_list
+
+    def builtin_instance_getAll(self, obj: Any) -> dict:
+        """Get all attributes from an object, categorized.
+        Usage: instance::getAll(@module)
+        Returns dict with 'methods', 'classes', 'vars' keys.
+        """
+        import inspect
+        result = {
+            'methods': [],
+            'classes': [],
+            'vars': []
+        }
+        for name in dir(obj):
+            if not name.startswith('_'):
+                attr = getattr(obj, name, None)
+                if inspect.isclass(attr):
+                    result['classes'].append(name)
+                elif callable(attr):
+                    result['methods'].append(name)
+                else:
+                    result['vars'].append(name)
+        return result
+
+    def builtin_instance_call(self, obj: Any, method_name: str, *args, **kwargs) -> Any:
+        """Dynamically call a method on an object.
+        Usage: instance::call(@module, 'methodName', arg1, arg2)
+        """
+        method = getattr(obj, method_name, None)
+        if method and callable(method):
+            return method(*args, **kwargs)
+        raise RuntimeError(f"Method '{method_name}' not found on object")
+
+    def builtin_instance_has(self, obj: Any, name: str) -> bool:
+        """Check if object has an attribute.
+        Usage: instance::has(@module, 'methodName')
+        """
+        return hasattr(obj, name)
+
+    def builtin_instance_type(self, obj: Any) -> str:
+        """Get the type name of an object.
+        Usage: instance::type(@module)
+        """
+        return type(obj).__name__
+
+    def builtin_isavailable(self, name_or_obj: Any) -> bool:
+        """Check if a shared instance exists.
+        Usage:
+            isavailable("MyInstance")     - check by name string
+            isavailable($MyInstance)      - check shared ref (returns True if not None)
+            instance::exists("MyInstance") - alias
+        """
+        from ..cssl_bridge import _live_objects
+
+
+        # If it's a string, check by name
+        if isinstance(name_or_obj, str):
+            return name_or_obj in _live_objects
+
+        # Otherwise, check if the object is not None (for $name or instance<"name">)
+        return name_or_obj is not None
+
     # ============= Regex Functions =============
 
     def builtin_match(self, pattern: str, string: str) -> Optional[dict]: