IncludeCPP 3.9.1__tar.gz → 3.9.2__tar.gz

{includecpp-3.9.1 → includecpp-3.9.2}/IncludeCPP.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IncludeCPP
-Version: 3.9.1
+Version: 3.9.2
 Summary: Professional C++ Python bindings with type-generic templates, pystubs and native threading
 Home-page: https://github.com/liliassg/IncludeCPP
 Author: Lilias Hatterscheidt

{includecpp-3.9.1 → includecpp-3.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IncludeCPP
-Version: 3.9.1
+Version: 3.9.2
 Summary: Professional C++ Python bindings with type-generic templates, pystubs and native threading
 Home-page: https://github.com/liliassg/IncludeCPP
 Author: Lilias Hatterscheidt

{includecpp-3.9.1 → includecpp-3.9.2}/includecpp/__init__.py

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

{includecpp-3.9.1 → includecpp-3.9.2}/includecpp/core/cssl/CSSL_DOCUMENTATION.md

@@ -168,6 +168,42 @@ isnull(null);         // true
 
 ## Variables & Globals
 
+### Scope Behavior
+
+Variables are **local by default**. Each function/class has its own scope - variables defined inside a function only exist within that function.
+
+```cssl
+define myFunction() {
+    string name = "Alice";  // Local to myFunction
+    printl(name);           // Works
+}
+
+myFunction();
+// printl(name);  // Error! 'name' doesn't exist here
+
+// Same variable name in different scopes = different variables
+string name = "Bob";
+
+define otherFunction() {
+    string name = "Charlie";  // Different variable, local to otherFunction
+    printl(name);             // "Charlie"
+}
+
+otherFunction();
+printl(name);  // "Bob" - outer scope unchanged
+```
+
+### Everything is Local by Default
+
+All elements (variables, functions, classes) are **local by default** and must be explicitly marked global.
+
+| Element | Local (default) | Global |
+|---------|-----------------|--------|
+| **Variables** | `string x = "text";` | `global x = "text";` or `@x = "text";` |
+| **Functions** | `define myFunc() { }` | `global define myFunc() { }` or `define @myFunc() { }` |
+| **Typed functions** | `void myFunc() { }` | `global void myFunc() { }` or `void @myFunc() { }` |
+| **Classes** | `class MyClass { }` | `global class MyClass { }` or `class @MyClass { }` |
+
 ### Local Variables
 
 ```cssl
@@ -179,6 +215,8 @@ bool active = true;
 
 ### Global Variables
 
+Use `global` keyword or `@`/`r@` prefix to create/access global variables:
+
 ```cssl
 // Declaration with 'global' keyword
 global myGlobal = "visible everywhere";
@@ -186,11 +224,60 @@ global myGlobal = "visible everywhere";
 // Access with '@' prefix
 printl(@myGlobal);
 
-// Alternative: r@ syntax
-r@anotherGlobal = "also global";
-printl(@anotherGlobal);
+// Direct global assignment with @ or r@
+@anotherGlobal = "also global";
+r@yetAnother = "and this too";
+
+// Always read globals with @
+printl(@x);
+```
+
+### Global Functions
+
+```cssl
+// Global function with 'global' keyword
+global define helper() {
+    printl("I'm global!");
+}
+
+// Alternative: @ prefix syntax
+define @anotherHelper() {
+    printl("Also global!");
+}
+
+// Global typed function
+global void @utilityFunc(string msg) {
+    printl(msg);
+}
+```
+
+### Global Classes
+
+```cssl
+// Global class with 'global' keyword
+global class SharedClass {
+    string value;
+}
+
+// Alternative: @ prefix syntax
+class @AnotherShared {
+    int count;
+}
+
+// Instantiate global class with @ prefix
+instance = new @SharedClass();
 ```
 
+### Prefix Reference
+
+| Prefix | Name | Usage |
+|--------|------|-------|
+| `@` | Global/Module | Read global vars, access modules: `@myVar`, `@os.getcwd()` |
+| `r@` | Global Ref | Assign to global scope: `r@name = value` |
+| `$` | Shared | Access Python objects: `$counter.value` |
+| `%` | Captured | Capture value at registration: `%version` |
+| `s@` | Self-Ref | Access global structs: `s@Backend.config` |
+
 ### Shared Objects ($)
 
 Access Python objects shared via `CSSL.share()`:
@@ -215,6 +302,20 @@ version = "2.0";
 printl(savedVersion);  // Still "1.0"
 ```
 
+### Class Member Access (this->)
+
+Inside classes, use `this->` to access instance members:
+
+```cssl
+class Person {
+    string name;
+
+    void setName(string n) {
+        this->name = n;  // Instance member
+    }
+}
+```
+
 ---
 
 ## Operators
@@ -1332,7 +1433,9 @@ assert(x > 0, "x must be positive");
 
 | Syntax | Description |
 |--------|-------------|
-| `@name` | Global variable |
+| `@name` | Global variable access |
+| `@name = value` | Global variable assignment |
+| `r@name = value` | Global reference assignment |
 | `$name` | Shared Python object |
 | `%name` | Captured value |
 | `this->` | Class member access |
@@ -1342,6 +1445,11 @@ assert(x > 0, "x must be positive");
 | `&FunctionName ++` | Append to function |
 | `*func()` | Non-null function |
 | `*[type]func()` | Type exclusion filter |
+| `global class Name` | Global class declaration |
+| `class @Name` | Global class (alt syntax) |
+| `global define func()` | Global function declaration |
+| `define @func()` | Global function (alt syntax) |
+| `new @ClassName()` | Instantiate global class |
 
 ---
 

{includecpp-3.9.1 → includecpp-3.9.2}/includecpp/core/cssl/cssl_parser.py

@@ -816,11 +816,13 @@ class CSSLParser:
         self.pos = saved_pos
         return False
 
-    def _parse_typed_function(self) -> ASTNode:
+    def _parse_typed_function(self, is_global: bool = False) -> ASTNode:
         """Parse C-style typed function declaration.
 
         Patterns:
-        - int Add(int a, int b) { }
+        - int Add(int a, int b) { }           // Local function
+        - global int Add(int a, int b) { }    // Global function
+        - int @Add(int a, int b) { }          // Global function (alternative)
         - undefined int Func() { }
         - open void Handler(open Params) { }
         - vector<string> GetNames() { }
@@ -869,6 +871,11 @@ class CSSLParser:
             else:
                 non_null = True
 
+        # Check for @ prefix (global function): void @FuncName()
+        if self._check(TokenType.AT):
+            self._advance()  # consume @
+            is_global = True
+
         # Get function name
         name = self._advance().value
 
@@ -966,6 +973,7 @@ class CSSLParser:
         # Parse function body
         node = ASTNode('function', value={
             'name': name,
+            'is_global': is_global,
             'params': params,
             'return_type': return_type,
             'generic_type': generic_type,
@@ -1131,19 +1139,30 @@ class CSSLParser:
                 root.children.append(self._parse_package_includes())
             # Handle global declarations
             elif self._match_keyword('global'):
-                stmt = self._parse_expression_statement()
-                if stmt:
-                    # Wrap in global_assignment to mark as global variable
-                    global_stmt = ASTNode('global_assignment', value=stmt)
-                    root.children.append(global_stmt)
+                # Check if followed by class or define (global class/function)
+                if self._match_keyword('class'):
+                    root.children.append(self._parse_class(is_global=True))
+                elif self._match_keyword('define'):
+                    root.children.append(self._parse_define(is_global=True))
+                elif self._looks_like_function_declaration():
+                    # global void MyFunc() { } or global int MyFunc() { }
+                    root.children.append(self._parse_typed_function(is_global=True))
+                else:
+                    stmt = self._parse_expression_statement()
+                    if stmt:
+                        # Wrap in global_assignment to mark as global variable
+                        global_stmt = ASTNode('global_assignment', value=stmt)
+                        root.children.append(global_stmt)
             elif self._check(TokenType.GLOBAL_REF):
                 stmt = self._parse_expression_statement()
                 if stmt:
                     # Wrap in global_assignment to mark as global variable (same as 'global' keyword)
                     global_stmt = ASTNode('global_assignment', value=stmt)
                     root.children.append(global_stmt)
-            # Handle statements
-            elif self._check(TokenType.IDENTIFIER) or self._check(TokenType.AT) or self._check(TokenType.SELF_REF) or self._check(TokenType.SHARED_REF):
+            # Handle statements - keywords like 'instance', 'list', 'map' can be variable names
+            elif (self._check(TokenType.IDENTIFIER) or self._check(TokenType.AT) or
+                  self._check(TokenType.SELF_REF) or self._check(TokenType.SHARED_REF) or
+                  self._check(TokenType.KEYWORD)):
                 stmt = self._parse_expression_statement()
                 if stmt:
                     root.children.append(stmt)
@@ -1380,20 +1399,14 @@ class CSSLParser:
         self._expect(TokenType.BLOCK_END)
         return node
 
-    def _parse_class(self) -> ASTNode:
+    def _parse_class(self, is_global: bool = False) -> ASTNode:
         """Parse class declaration with members and methods.
 
         Syntax:
-            class ClassName {
-                string name;
-                int age;
-
-                void ClassName(string n) { this->name = n; }
-
-                void sayHello() {
-                    printl("Hello " + this->name);
-                }
-            }
+            class ClassName { ... }           // Local class
+            global class ClassName { ... }    // Global class
+            class @ClassName { ... }          // Global class (alternative)
+            class *ClassName { ... }          // Non-null class
 
         Non-null class (all methods return non-null):
             class *MyClass { ... }
@@ -1403,6 +1416,11 @@ class CSSLParser:
         if self._match(TokenType.MULTIPLY):
             non_null = True
 
+        # Check for @ prefix (global class): class @ClassName
+        if self._check(TokenType.AT):
+            self._advance()  # consume @
+            is_global = True
+
         class_name = self._advance().value
 
         # Check for class-level constructor parameters: class MyClass (int x, string y) { ... }
@@ -1459,6 +1477,7 @@ class CSSLParser:
 
         node = ASTNode('class', value={
             'name': class_name,
+            'is_global': is_global,
             'non_null': non_null,
             'class_params': class_params,
             'extends': extends_class,
@@ -1693,12 +1712,14 @@ class CSSLParser:
 
         return params
 
-    def _parse_define(self) -> ASTNode:
+    def _parse_define(self, is_global: bool = False) -> ASTNode:
         """Parse define function declaration.
 
         Syntax:
-            define MyFunc(args) { }
-            define *MyFunc(args) { }  // Non-null: must never return None
+            define MyFunc(args) { }           // Local function
+            global define MyFunc(args) { }    // Global function
+            define @MyFunc(args) { }          // Global function (alternative)
+            define *MyFunc(args) { }          // Non-null: must never return None
             define MyFunc : extends OtherFunc() { }  // Inherit local vars
             define MyFunc : overwrites OtherFunc() { }  // Replace OtherFunc
             define MyFunc :: extends Parent::Method :: overwrites Parent::Method() { }  // Method-level inheritance
@@ -1716,6 +1737,11 @@ class CSSLParser:
             else:
                 non_null = True
 
+        # Check for @ prefix (global function): define @FuncName
+        if self._check(TokenType.AT):
+            self._advance()  # consume @
+            is_global = True
+
         name = self._advance().value
 
         # Check for extends/overwrites: define func : extends/overwrites target() { }
@@ -1859,6 +1885,7 @@ class CSSLParser:
 
         node = ASTNode('function', value={
             'name': name,
+            'is_global': is_global,
             'params': params,
             'non_null': non_null,
             'exclude_type': exclude_type,  # *[type] - must NOT return this type
@@ -2791,16 +2818,21 @@ class CSSLParser:
                 # Just 'this' keyword alone - return as identifier for now
                 return ASTNode('identifier', value='this')
 
-        # Handle 'new ClassName(args)' instantiation
+        # Handle 'new ClassName(args)' or 'new @ClassName(args)' instantiation
         if self._check(TokenType.KEYWORD) and self._current().value == 'new':
             self._advance()  # consume 'new'
+            # Check for @ prefix (global class reference)
+            is_global_ref = False
+            if self._check(TokenType.AT):
+                self._advance()  # consume @
+                is_global_ref = True
             class_name = self._advance().value  # get class name
             args = []
             kwargs = {}
             if self._match(TokenType.PAREN_START):
                 args, kwargs = self._parse_call_arguments()
                 self._expect(TokenType.PAREN_END)
-            node = ASTNode('new', value={'class': class_name, 'args': args, 'kwargs': kwargs})
+            node = ASTNode('new', value={'class': class_name, 'args': args, 'kwargs': kwargs, 'is_global_ref': is_global_ref})
             # Continue to check for member access, calls on the new object
             while True:
                 if self._match(TokenType.DOT):
@@ -2819,7 +2851,18 @@ class CSSLParser:
             return node
 
         if self._match(TokenType.AT):
+            # Check for @* (global non-null reference): @*name
+            is_non_null = False
+            if self._check(TokenType.MULTIPLY):
+                self._advance()  # consume *
+                is_non_null = True
+
             node = self._parse_module_reference()
+
+            # Wrap in non_null_assert if @* was used
+            if is_non_null:
+                node = ASTNode('non_null_assert', value={'operand': node, 'is_global': True})
+
             # Continue to check for calls, indexing, member access on module refs
             while True:
                 if self._match(TokenType.PAREN_START):

{includecpp-3.9.1 → includecpp-3.9.2}/includecpp/core/cssl/cssl_runtime.py

@@ -99,6 +99,89 @@ ERROR_HINTS = {
 }
 
 
+def _find_similar_names(name: str, candidates: list, max_distance: int = 2) -> list:
+    """Find similar names for 'did you mean' suggestions using Levenshtein distance."""
+    if not candidates:
+        return []
+
+    def levenshtein(s1: str, s2: str) -> int:
+        if len(s1) < len(s2):
+            s1, s2 = s2, s1
+        if len(s2) == 0:
+            return len(s1)
+        prev_row = range(len(s2) + 1)
+        for i, c1 in enumerate(s1):
+            curr_row = [i + 1]
+            for j, c2 in enumerate(s2):
+                insertions = prev_row[j + 1] + 1
+                deletions = curr_row[j] + 1
+                substitutions = prev_row[j] + (c1.lower() != c2.lower())
+                curr_row.append(min(insertions, deletions, substitutions))
+            prev_row = curr_row
+        return prev_row[-1]
+
+    similar = []
+    name_lower = name.lower()
+    for candidate in candidates:
+        if candidate.startswith('_'):
+            continue
+        dist = levenshtein(name, candidate)
+        # Also check case-insensitive exact match
+        if name_lower == candidate.lower() and name != candidate:
+            similar.insert(0, candidate)  # Exact case mismatch goes first
+        elif dist <= max_distance:
+            similar.append(candidate)
+
+    return similar[:3]  # Return top 3 suggestions
+
+
+def _get_available_classes(scope: 'Scope', global_scope: 'Scope', promoted_globals: dict) -> list:
+    """Get list of all available class names."""
+    classes = []
+    # Check current scope chain
+    current = scope
+    while current:
+        for name, val in current.variables.items():
+            if isinstance(val, CSSLClass) and name not in classes:
+                classes.append(name)
+        current = current.parent
+    # Check global scope
+    for name, val in global_scope.variables.items():
+        if isinstance(val, CSSLClass) and name not in classes:
+            classes.append(name)
+    # Check promoted globals
+    for name, val in promoted_globals.items():
+        if isinstance(val, CSSLClass) and name not in classes:
+            classes.append(name)
+    return classes
+
+
+def _get_available_functions(scope: 'Scope', global_scope: 'Scope', builtins) -> list:
+    """Get list of all available function names."""
+    functions = []
+    # Check current scope chain
+    current = scope
+    while current:
+        for name, val in current.variables.items():
+            if callable(val) or (isinstance(val, ASTNode) and val.type == 'function'):
+                if name not in functions:
+                    functions.append(name)
+        current = current.parent
+    # Check global scope
+    for name, val in global_scope.variables.items():
+        if callable(val) or (isinstance(val, ASTNode) and val.type == 'function'):
+            if name not in functions:
+                functions.append(name)
+    # Check builtins
+    if builtins:
+        for name in dir(builtins):
+            if name.startswith('builtin_'):
+                func_name = name[8:]  # Remove 'builtin_' prefix
+                if func_name not in functions:
+                    functions.append(func_name)
+    return functions
+
+
 class CSSLBreak(Exception):
     """Break statement"""
     pass
@@ -716,9 +799,12 @@ class CSSLRuntime:
         Parses class members and methods, creating a CSSLClass object
         that can be instantiated with 'new'.
         Supports inheritance via 'extends' keyword and method overwriting via 'overwrites'.
+
+        Classes are local by default. Use 'global class' or 'class @Name' for global classes.
         """
         class_info = node.value
         class_name = class_info.get('name')
+        is_global = class_info.get('is_global', False)
         extends_class_name = class_info.get('extends')
         extends_is_python = class_info.get('extends_is_python', False)
         overwrites_class_name = class_info.get('overwrites')
@@ -745,7 +831,22 @@ class CSSLRuntime:
                     parent_class = self.global_scope.get(extends_class_name)
 
             if parent_class is None:
-                raise ValueError(f"Cannot extend unknown class '{extends_class_name}'")
+                # Build detailed error for extends
+                available_classes = _get_available_classes(self.scope, self.global_scope, self._promoted_globals)
+                similar = _find_similar_names(extends_class_name, available_classes)
+
+                if similar:
+                    hint = f"Did you mean: {', '.join(similar)}?"
+                elif extends_is_python:
+                    hint = f"Python object '${extends_class_name}' not found. Use share() to share Python objects first."
+                else:
+                    hint = f"Define class '{extends_class_name}' before this class, or use 'extends $PyObject' for Python objects"
+
+                raise self._format_error(
+                    node.line,
+                    f"Cannot extend unknown class '{extends_class_name}'",
+                    hint
+                )
 
             # Auto-wrap Python objects for inheritance
             from .cssl_builtins import CSSLizedPythonObject
@@ -803,9 +904,11 @@ class CSSLRuntime:
         class_def.class_params = class_params  # Class-level constructor parameters
         class_def.extends_args = extends_args  # Arguments to pass to parent constructor
 
-        # Register class in scope
+        # Register class in scope (local by default, global if marked)
         self.scope.set(class_name, class_def)
-        self.global_scope.set(class_name, class_def)
+        if is_global:
+            self.global_scope.set(class_name, class_def)
+            self._promoted_globals[class_name] = class_def
 
         # Handle class overwrites - replace methods in target class
         if overwrites_class_name:
@@ -888,12 +991,15 @@ class CSSLRuntime:
         """Execute function definition - registers it and handles extends/overwrites.
 
         Syntax:
-            define func() { ... }
-            define func : extends otherFunc() { ... }  - Inherit local vars
-            define func : overwrites otherFunc() { ... }  - Replace otherFunc
+            define func() { ... }                           - Local function
+            global define func() { ... }                    - Global function
+            define @func() { ... }                          - Global function (alternative)
+            define func : extends otherFunc() { ... }       - Inherit local vars
+            define func : overwrites otherFunc() { ... }    - Replace otherFunc
         """
         func_info = node.value
         func_name = func_info.get('name')
+        is_global = func_info.get('is_global', False)
         extends_func = func_info.get('extends')
         extends_is_python = func_info.get('extends_is_python', False)
         overwrites_func = func_info.get('overwrites')
@@ -922,8 +1028,11 @@ class CSSLRuntime:
                     self.scope.set(overwrites_func, node)
                     self.global_scope.set(overwrites_func, node)
 
-        # Register the function
+        # Register the function (local by default, global if marked)
         self.scope.set(func_name, node)
+        if is_global:
+            self.global_scope.set(func_name, node)
+            self._promoted_globals[func_name] = node
         return None
 
     def _resolve_function_target(self, name: str, is_python: bool) -> Any:
@@ -2734,7 +2843,21 @@ class CSSLRuntime:
             scoped_val = self.global_scope.get(f'${name}')
             if scoped_val is not None:
                 return scoped_val
-            raise CSSLRuntimeError(f"Shared object '${name}' not found. Use share() to share objects.")
+            # List available shared objects for helpful error
+            available_shared = list(_live_objects.keys())
+            similar = _find_similar_names(name, available_shared)
+            if similar:
+                hint = f"Did you mean: ${', $'.join(similar)}?"
+            elif available_shared:
+                hint = f"Available shared objects: ${', $'.join(available_shared[:5])}"
+            else:
+                hint = "Use share(name, object) from Python to share objects first."
+
+            raise self._format_error(
+                node.line if hasattr(node, 'line') else 0,
+                f"Shared object '${name}' not found",
+                hint
+            )
 
         if node.type == 'captured_ref':
             # %<name> captured reference - use value captured at infusion registration time
@@ -2761,7 +2884,13 @@ class CSSLRuntime:
                 value = self._original_functions.get(name)
             if value is not None:
                 return value
-            raise CSSLRuntimeError(f"Captured reference '%{name}' not found.")
+            # Build helpful error for captured reference
+            hint = f"Variable '{name}' must exist when the infusion is registered. Check that '%{name}' is defined before the <<== operator."
+            raise self._format_error(
+                node.line if hasattr(node, 'line') else 0,
+                f"Captured reference '%{name}' not found",
+                hint
+            )
 
         if node.type == 'instance_ref':
             # instance<"name"> - get shared instance by name
@@ -2855,7 +2984,22 @@ class CSSLRuntime:
             operand = node.value.get('operand')
             value = self._evaluate(operand)
             if value is None:
-                raise CSSLError(f"Non-null assertion failed: value is null/None")
+                # Get name of the operand for better error message
+                operand_name = "unknown"
+                if isinstance(operand, ASTNode):
+                    if operand.type == 'identifier':
+                        operand_name = operand.value
+                    elif operand.type == 'shared_ref':
+                        operand_name = f"${operand.value}"
+                    elif operand.type == 'module_ref':
+                        operand_name = f"@{operand.value}"
+                    elif operand.type == 'global_ref':
+                        operand_name = f"r@{operand.value}"
+                raise self._format_error(
+                    node.line if hasattr(node, 'line') else 0,
+                    f"Non-null assertion failed: '{operand_name}' is null/None",
+                    f"The value accessed via '*{operand_name}' must not be null. Check that it is defined and initialized."
+                )
             return value
 
         if node.type == 'type_exclude_assert':
@@ -2880,7 +3024,11 @@ class CSSLRuntime:
 
             excluded_py_type = type_map.get(exclude_type.lower())
             if excluded_py_type and isinstance(value, excluded_py_type):
-                raise CSSLError(f"Type exclusion assertion failed: value is of excluded type '{exclude_type}'")
+                raise self._format_error(
+                    node.line if hasattr(node, 'line') else 0,
+                    f"Type exclusion assertion failed: value is of excluded type '{exclude_type}'",
+                    f"The expression was marked *[{exclude_type}] meaning it must NOT return {exclude_type}, but it did."
+                )
             return value
 
         if node.type == 'call':
@@ -3160,12 +3308,33 @@ class CSSLRuntime:
             return self._call_function(callee, args, kwargs)
 
         callee_name = callee_node.value if isinstance(callee_node, ASTNode) and hasattr(callee_node, 'value') else str(callee_node)
-        raise CSSLRuntimeError(
-            f"Cannot call '{callee_name}' - it is not a function",
-            node.line,
-            context=f"Type: {type(callee).__name__}",
-            hint=ERROR_HINTS['undefined_function']
-        )
+
+        # Build detailed error with suggestions
+        available_funcs = _get_available_functions(self.scope, self.global_scope, self.builtins)
+        similar = _find_similar_names(callee_name, available_funcs)
+
+        if callee is None:
+            # Function not found at all
+            if similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            else:
+                hint = f"Function '{callee_name}' is not defined. Define it with: define {callee_name}() {{ }}"
+            raise self._format_error(
+                node.line,
+                f"Function '{callee_name}' not found",
+                hint
+            )
+        else:
+            # Found something but it's not callable
+            if similar:
+                hint = f"'{callee_name}' is a {type(callee).__name__}, not a function. Did you mean: {', '.join(similar)}?"
+            else:
+                hint = f"'{callee_name}' is a {type(callee).__name__}. Functions must be defined with 'define' keyword."
+            raise self._format_error(
+                node.line,
+                f"Cannot call '{callee_name}' - it is not a function",
+                hint
+            )
 
     def _eval_typed_call(self, node: ASTNode) -> Any:
         """Evaluate typed function call like OpenFind<string>(0) or OpenFind<dynamic, "name">"""
@@ -3231,26 +3400,53 @@ class CSSLRuntime:
         )
 
     def _eval_new(self, node: ASTNode) -> CSSLInstance:
-        """Evaluate 'new ClassName(args)' expression.
+        """Evaluate 'new ClassName(args)' or 'new @ClassName(args)' expression.
 
         Creates a new instance of a CSSL class and calls its constructor.
         Supports multiple constructors (constr keyword), class parameters,
         and automatic parent constructor calling.
+
+        With '@' prefix (new @ClassName), looks only in global scope.
         """
         class_name = node.value.get('class')
+        is_global_ref = node.value.get('is_global_ref', False)
         args = [self._evaluate(arg) for arg in node.value.get('args', [])]
         kwargs = {k: self._evaluate(v) for k, v in node.value.get('kwargs', {}).items()}
 
         # Get class definition from scope
-        class_def = self.scope.get(class_name)
-        if class_def is None:
-            class_def = self.global_scope.get(class_name)
+        if is_global_ref:
+            # With @ prefix, only look in global scope
+            class_def = self._promoted_globals.get(class_name)
+            if class_def is None:
+                class_def = self.global_scope.get(class_name)
+        else:
+            # Normal lookup: local scope first, then global
+            class_def = self.scope.get(class_name)
+            if class_def is None:
+                class_def = self.global_scope.get(class_name)
 
         if class_def is None:
-            raise CSSLRuntimeError(
-                f"Class '{class_name}' not found",
+            # Build detailed error with suggestions
+            source_line = self._get_source_line(node.line)
+            available_classes = _get_available_classes(self.scope, self.global_scope, self._promoted_globals)
+            similar = _find_similar_names(class_name, available_classes)
+
+            # Check if class exists in global scope (user forgot @)
+            global_class = self._promoted_globals.get(class_name) or self.global_scope.get(class_name)
+            if global_class and isinstance(global_class, CSSLClass) and not is_global_ref:
+                hint = f"Class '{class_name}' exists in global scope. Use: new @{class_name}()"
+            elif similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            elif available_classes:
+                hint = f"Available classes: {', '.join(available_classes[:5])}"
+            else:
+                hint = "Define the class before instantiation, or use 'global class' / 'class @Name' for global classes"
+
+            context = f"in expression: {source_line.strip()}" if source_line else None
+            raise self._format_error(
                 node.line,
-                hint="Make sure the class is defined before instantiation"
+                f"Class '{class_name}' not found",
+                hint
             )
 
         if not isinstance(class_def, CSSLClass):
@@ -3542,9 +3738,24 @@ class CSSLRuntime:
                 return lambda *args, **kwargs: python_method(*args, **kwargs)
             return lambda *args, **kwargs: self._call_method(instance, method_node, list(args), kwargs)
 
-        raise CSSLRuntimeError(
-            f"'{instance._class.name}' has no member or method '{member}'",
-            node.line if hasattr(node, 'line') else 0
+        # Build helpful error with available members
+        class_name = instance._class.name
+        available_members = list(instance._members.keys()) if hasattr(instance, '_members') else []
+        available_methods = list(instance._methods.keys()) if hasattr(instance, '_methods') else []
+        all_available = available_members + available_methods
+        similar = _find_similar_names(member, all_available)
+
+        if similar:
+            hint = f"Did you mean: {', '.join(similar)}?"
+        elif all_available:
+            hint = f"Available: {', '.join(all_available[:5])}"
+        else:
+            hint = f"Class '{class_name}' has no accessible members. Check class definition."
+
+        raise self._format_error(
+            node.line if hasattr(node, 'line') else 0,
+            f"'{class_name}' has no member or method '{member}'",
+            hint
         )
 
     def _call_method(self, instance: CSSLInstance, method_node: ASTNode, args: list, kwargs: dict = None) -> Any:
@@ -3639,7 +3850,25 @@ class CSSLRuntime:
                     python_method = method_node[1]
                     return lambda *args, **kwargs: python_method(*args, **kwargs)
                 return lambda *args, **kwargs: self._call_method(obj, method_node, list(args), kwargs)
-            raise CSSLRuntimeError(f"'{obj._class.name}' has no member or method '{member}'")
+            # Build helpful error with available members
+            class_name = obj._class.name
+            available_members = list(obj._members.keys()) if hasattr(obj, '_members') else []
+            available_methods = list(obj._methods.keys()) if hasattr(obj, '_methods') else []
+            all_available = available_members + available_methods
+            similar = _find_similar_names(member, all_available)
+
+            if similar:
+                hint = f"Did you mean: {', '.join(similar)}?"
+            elif all_available:
+                hint = f"Available: {', '.join(all_available[:5])}"
+            else:
+                hint = f"Class '{class_name}' has no accessible members."
+
+            raise self._format_error(
+                node.line,
+                f"'{class_name}' has no member or method '{member}'",
+                hint
+            )
 
         # === STRING METHODS ===
         if isinstance(obj, str):

{includecpp-3.9.1 → includecpp-3.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "IncludeCPP"
-version = "3.9.1"
+version = "3.9.2"
 description = "Professional C++ Python bindings with type-generic templates, pystubs and native threading"
 readme = "README.md"
 requires-python = ">=3.9"