IncludeCPP 3.7.1__py3-none-any.whl → 3.7.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.7.0"
+__version__ = "3.7.9"
 __all__ = ["CppApi", "CSSL"]
 
 # Module-level cache for C++ modules

includecpp/cli/commands.py

@@ -1193,7 +1193,7 @@ def build(ctx, clean, keep, verbose, no_incremental, incremental, parallel, jobs
 @cli.command()
 @click.argument('module_name')
 def add(module_name):
-    """Create a new module template."""
+    """Create a new module template with sample C++ code."""
     plugins_dir = Path("plugins")
     if not plugins_dir.exists():
         click.echo("Error: plugins/ directory not found")
@@ -1204,6 +1204,7 @@ def add(module_name):
         click.echo(f"Module {module_name} already exists")
         return
 
+    # Create .cp config file
     template = f"""SOURCE(include/{module_name}.cpp) {module_name}
 
 PUBLIC(
@@ -1215,7 +1216,41 @@ PUBLIC(
         f.write(template)
 
     click.echo(f"Created {cp_file}")
-    click.echo(f"Now create include/{module_name}.cpp with your C++ code")
+
+    # Create include/ directory if it doesn't exist
+    include_dir = Path("include")
+    include_dir.mkdir(exist_ok=True)
+
+    # Create .cpp file with sample code
+    cpp_file = include_dir / f"{module_name}.cpp"
+    if not cpp_file.exists():
+        cpp_template = f"""#include <string>
+#include <vector>
+
+namespace includecpp {{
+
+// Example function - returns a greeting
+std::string example_function(const std::string& name) {{
+    return "Hello, " + name + "!";
+}}
+
+// Add more functions here...
+// int add(int a, int b) {{ return a + b; }}
+// std::vector<int> range(int n) {{ ... }}
+
+}} // namespace includecpp
+"""
+        with open(cpp_file, 'w', encoding='utf-8') as f:
+            f.write(cpp_template)
+
+        click.echo(f"Created {cpp_file}")
+    else:
+        click.echo(f"Note: {cpp_file} already exists, skipped")
+
+    click.echo(f"\nNext steps:")
+    click.echo(f"  1. Edit include/{module_name}.cpp to add your functions")
+    click.echo(f"  2. Update plugins/{module_name}.cp to expose functions")
+    click.echo(f"  3. Run: includecpp rebuild")
 
 @cli.command('list')
 def list_modules():
@@ -7480,13 +7515,12 @@ def cssl_exec(path, code):
     # Execute
     click.secho("--- Output ---", fg='green')
     try:
-        result = cssl_lang.exec(source)
+        result = cssl_lang.run(source)
 
         # Output is already printed to stdout during execution via runtime.output()
-        # No need to print buffer again - this was causing double output
-
-        if result is not None:
-            click.echo(f"Result: {result}")
+        # Don't print "Result:" automatically - users should use printl() for output
+        # This prevents unwanted output for function calls like: Function();
+        pass
 
     except Exception as e:
         click.secho(f"CSSL Error: {e}", fg='red')
@@ -7535,10 +7569,29 @@ def cssl_makemodule(path, output):
 
 
 @cssl.command(name='doc')
-def cssl_doc():
-    """Show CSSL documentation."""
+@click.argument('search', required=False, default=None)
+@click.option('--list', '-l', 'list_sections', is_flag=True, help='List all documentation sections')
+def cssl_doc(search, list_sections):
+    """Show CSSL documentation.
+
+    \b
+    Usage:
+      includecpp cssl doc              # Show full documentation
+      includecpp cssl doc "open"       # Search for 'open' keyword
+      includecpp cssl doc "$"          # Search for shared variable syntax
+      includecpp cssl doc "define"     # Search for define keyword
+      includecpp cssl doc --list       # List all sections
+
+    \b
+    Examples:
+      includecpp cssl doc "class"      # Show OOP/class documentation
+      includecpp cssl doc "json::"     # Show JSON functions
+      includecpp cssl doc "this->"     # Show this-> keyword usage
+      includecpp cssl doc "map"        # Show Map container docs
+    """
     from pathlib import Path as PathLib
     import os
+    import re
 
     # Find the documentation file in the cssl package directory
     cssl_dir = PathLib(__file__).parent.parent / 'core' / 'cssl'
@@ -7558,8 +7611,116 @@ def cssl_doc():
 
     if doc_path.exists():
         content = doc_path.read_text(encoding='utf-8')
-        # Use pager for long content
-        click.echo_via_pager(content)
+
+        # List sections mode
+        if list_sections:
+            click.secho("CSSL Documentation Sections", fg='cyan', bold=True)
+            click.secho("=" * 40, fg='cyan')
+            sections = re.findall(r'^##\s+(.+)$', content, re.MULTILINE)
+            for i, section in enumerate(sections, 1):
+                click.echo(f"  {i:2d}. {section}")
+            click.echo()
+            click.echo("Use: includecpp cssl doc \"<keyword>\" to search")
+            return
+
+        # Search mode
+        if search:
+            click.secho(f"Searching for: '{search}'", fg='cyan', bold=True)
+            click.secho("=" * 50, fg='cyan')
+            click.echo()
+
+            # Split into subsections (### headers) for focused results
+            subsections = re.split(r'(?=^### )', content, flags=re.MULTILINE)
+
+            # Also split into main sections (## headers)
+            main_sections = re.split(r'(?=^## )', content, flags=re.MULTILINE)
+
+            # Find matching subsections (### level) - most focused
+            matching_subsections = []
+            for subsection in subsections:
+                if search.lower() in subsection.lower():
+                    # Extract title
+                    title_match = re.match(r'^###\s+(.+)$', subsection, re.MULTILINE)
+                    if title_match:
+                        # Trim subsection to just the content until next ### or ##
+                        lines = subsection.split('\n')
+                        trimmed_lines = []
+                        for line in lines:
+                            if line.startswith('## ') and not line.startswith('### '):
+                                break
+                            trimmed_lines.append(line)
+                        matching_subsections.append((title_match.group(1), '\n'.join(trimmed_lines)))
+
+            if matching_subsections:
+                click.secho(f"Found {len(matching_subsections)} matching subsection(s):", fg='green')
+                click.echo()
+
+                # Show focused subsections (limit output)
+                for title, sub_content in matching_subsections[:5]:
+                    click.secho(f"### {title}", fg='yellow', bold=True)
+                    # Highlight search term in content
+                    highlighted = re.sub(
+                        f'({re.escape(search)})',
+                        click.style(r'\1', fg='green', bold=True),
+                        sub_content,
+                        flags=re.IGNORECASE
+                    )
+                    # Limit lines per subsection
+                    lines = highlighted.split('\n')
+                    if len(lines) > 30:
+                        click.echo('\n'.join(lines[:30]))
+                        click.secho(f"  ... ({len(lines) - 30} more lines)", fg='cyan')
+                    else:
+                        click.echo(highlighted)
+                    click.echo()
+                    click.secho("-" * 40, fg='cyan')
+                    click.echo()
+
+                if len(matching_subsections) > 5:
+                    click.secho(f"... and {len(matching_subsections) - 5} more subsections", fg='cyan')
+                    click.echo("Use --list to see all sections")
+            else:
+                # Fall back to main section search (## level)
+                found_sections = []
+                for section in main_sections:
+                    if search.lower() in section.lower():
+                        title_match = re.match(r'^##\s+(.+)$', section, re.MULTILINE)
+                        if title_match:
+                            found_sections.append((title_match.group(1), section))
+
+                if found_sections:
+                    click.secho(f"Found in {len(found_sections)} section(s):", fg='green')
+                    for title, _ in found_sections:
+                        click.echo(f"  - {title}")
+                    click.echo()
+
+                    # Show first matching section, trimmed
+                    title, section = found_sections[0]
+                    click.secho(f"## {title}", fg='yellow', bold=True)
+                    highlighted = re.sub(
+                        f'({re.escape(search)})',
+                        click.style(r'\1', fg='green', bold=True),
+                        section,
+                        flags=re.IGNORECASE
+                    )
+                    lines = highlighted.split('\n')
+                    if len(lines) > 40:
+                        click.echo('\n'.join(lines[:40]))
+                        click.secho(f"\n... ({len(lines) - 40} more lines in this section)", fg='cyan')
+                    else:
+                        click.echo(highlighted)
+                else:
+                    click.secho(f"No matches found for '{search}'", fg='yellow')
+                    click.echo()
+                    click.echo("Try searching for:")
+                    click.echo("  - Keywords: class, function, define, open, global, shuffled")
+                    click.echo("  - Syntax: $, @, ::, this->, <<==, <==, #$")
+                    click.echo("  - Types: string, int, stack, vector, map, json")
+                    click.echo()
+                    click.echo("Or use: includecpp cssl doc --list")
+        else:
+            # Full documentation mode
+            click.echo_via_pager(content)
     else:
         click.secho("Documentation file not found.", fg='yellow')
         click.echo("Looking for: CSSL_DOCUMENTATION.md")

includecpp/core/cssl/CSSL_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # CSSL - C-Style Scripting Language
 
-> Version 3.7.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.
 
 ---
 
@@ -41,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
@@ -701,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();
 ```
 
 ---
@@ -1143,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.

includecpp/core/cssl/cssl_parser.py

@@ -108,6 +108,8 @@ class TokenType(Enum):
     COMMENT = auto()
     NEWLINE = auto()
     EOF = auto()
+    # Super-functions for .cssl-pl payload files (v3.8.0)
+    SUPER_FUNC = auto()    # #$run(), #$exec(), #$printl() - pre-execution hooks
 
 
 KEYWORDS = {
@@ -212,9 +214,14 @@ class CSSLLexer:
 
             char = self.source[self.pos]
 
-            # Comments: both # and // style
+            # Super-functions (#$) or Comments (# and // style)
             if char == '#':
-                self._skip_comment()
+                if self._peek(1) == '$':
+                    # Super-function: #$run(), #$exec(), #$printl()
+                    self._read_super_function()
+                else:
+                    # Regular comment
+                    self._skip_comment()
             elif char == '/' and self._peek(1) == '/':
                 # C-style // comment - NEW
                 self._skip_comment()
@@ -446,6 +453,31 @@ class CSSLLexer:
         else:
             self._add_token(TokenType.IDENTIFIER, value)
 
+    def _read_super_function(self):
+        """Read #$<name>(...) super-function call for .cssl-pl payloads.
+
+        Super-functions are pre-execution hooks that run when a payload is loaded.
+        Valid super-functions: #$run(), #$exec(), #$printl()
+
+        Syntax:
+            #$run(initFunction);        // Call a function at load time
+            #$exec(setup());            // Execute expression at load time
+            #$printl("Payload loaded"); // Print at load time
+        """
+        start = self.pos
+        self._advance()  # skip '#'
+        self._advance()  # skip '$'
+
+        # Read the super-function name (run, exec, printl, etc.)
+        name_start = self.pos
+        while self.pos < len(self.source) and (self.source[self.pos].isalnum() or self.source[self.pos] == '_'):
+            self._advance()
+        func_name = self.source[name_start:self.pos]
+
+        # Store as #$<name> token value
+        value = f'#${func_name}'
+        self._add_token(TokenType.SUPER_FUNC, value)
+
     def _read_self_ref(self):
         """Read s@<name> or s@<name>.<member>... self-reference"""
         start = self.pos
@@ -1377,6 +1409,9 @@ class CSSLParser:
         elif self._looks_like_function_declaration():
             # Nested typed function (e.g., void Level2() { ... })
             return self._parse_typed_function()
+        elif self._check(TokenType.SUPER_FUNC):
+            # Super-function for .cssl-pl payload files
+            return self._parse_super_function()
         elif (self._check(TokenType.IDENTIFIER) or self._check(TokenType.AT) or
               self._check(TokenType.CAPTURED_REF) or self._check(TokenType.SHARED_REF) or
               self._check(TokenType.GLOBAL_REF) or self._check(TokenType.SELF_REF) or
@@ -1594,23 +1629,42 @@ class CSSLParser:
         return ASTNode('c_for_update', value={'var': var_name, 'op': 'none'})
 
     def _parse_python_style_for(self) -> ASTNode:
-        """Parse Python-style for loop: for (i in range(...)) { }
+        """Parse Python-style for loop: for (i in range(...)) { } or for (item in collection) { }
 
         Supports:
             for (i in range(n)) { }           - 0 to n-1
             for (i in range(start, end)) { }  - start to end-1
             for (i in range(start, end, step)) { }
+            for (item in collection) { }      - iterate over list/vector
+            for (item in @global_collection) { } - iterate over global
         """
         var_name = self._advance().value
         self._expect(TokenType.KEYWORD)  # 'in'
 
-        # 'range' can be keyword or identifier
+        # Check if this is range() or collection iteration
+        is_range = False
         if self._check(TokenType.KEYWORD) and self._peek().value == 'range':
             self._advance()  # consume 'range' keyword
+            is_range = True
         elif self._check(TokenType.IDENTIFIER) and self._peek().value == 'range':
             self._advance()  # consume 'range' identifier
-        else:
-            self.error(f"Expected 'range', got {self._peek().value}")
+            is_range = True
+
+        # If not range, parse as collection iteration
+        if not is_range:
+            iterable = self._parse_expression()
+            self._expect(TokenType.PAREN_END)
+
+            node = ASTNode('foreach', value={'var': var_name, 'iterable': iterable}, children=[])
+            self._expect(TokenType.BLOCK_START)
+
+            while not self._check(TokenType.BLOCK_END) and not self._is_at_end():
+                stmt = self._parse_statement()
+                if stmt:
+                    node.children.append(stmt)
+
+            self._expect(TokenType.BLOCK_END)
+            return node
 
         self._expect(TokenType.PAREN_START)
         first_arg = self._parse_expression()
@@ -1722,11 +1776,56 @@ class CSSLParser:
         return node
 
     def _parse_return(self) -> ASTNode:
-        value = None
+        """Parse return statement, supporting multiple values for shuffled functions.
+
+        Syntax:
+            return;                    // Return None
+            return value;              // Return single value
+            return a, b, c;            // Return multiple values (for shuffled)
+        """
+        values = []
         if not self._check(TokenType.SEMICOLON) and not self._check(TokenType.BLOCK_END):
-            value = self._parse_expression()
+            values.append(self._parse_expression())
+
+            # Check for comma-separated return values (shuffled return)
+            while self._check(TokenType.COMMA):
+                self._advance()  # consume comma
+                values.append(self._parse_expression())
+
+        self._match(TokenType.SEMICOLON)
+
+        if len(values) == 0:
+            return ASTNode('return', value=None)
+        elif len(values) == 1:
+            return ASTNode('return', value=values[0])
+        else:
+            # Multiple return values - create tuple return
+            return ASTNode('return', value={'multiple': True, 'values': values})
+
+    def _parse_super_function(self) -> ASTNode:
+        """Parse super-function for .cssl-pl payload files.
+
+        Syntax:
+            #$run(initFunction);           // Call function at load time
+            #$exec(setup());               // Execute expression at load time
+            #$printl("Payload loaded");    // Print at load time
+
+        These are pre-execution hooks that run when payload() loads the file.
+        """
+        token = self._advance()  # Get the SUPER_FUNC token
+        super_name = token.value  # e.g., "#$run", "#$exec", "#$printl"
+
+        # Parse the arguments
+        self._expect(TokenType.PAREN_START)
+        args = []
+        if not self._check(TokenType.PAREN_END):
+            args.append(self._parse_expression())
+            while self._match(TokenType.COMMA):
+                args.append(self._parse_expression())
+        self._expect(TokenType.PAREN_END)
         self._match(TokenType.SEMICOLON)
-        return ASTNode('return', value=value)
+
+        return ASTNode('super_func', value={'name': super_name, 'args': args})
 
     def _parse_try(self) -> ASTNode:
         node = ASTNode('try', children=[])
@@ -1813,6 +1912,25 @@ class CSSLParser:
     def _parse_expression_statement(self) -> Optional[ASTNode]:
         expr = self._parse_expression()
 
+        # === TUPLE UNPACKING: a, b, c = shuffled_func() ===
+        # Check if we have comma-separated identifiers before =
+        if expr.type == 'identifier' and self._check(TokenType.COMMA):
+            targets = [expr]
+            while self._match(TokenType.COMMA):
+                next_expr = self._parse_expression()
+                if next_expr.type == 'identifier':
+                    targets.append(next_expr)
+                else:
+                    # Not a simple identifier list, this is something else
+                    # Restore and fall through to normal parsing
+                    break
+
+            # Check if followed by =
+            if self._match(TokenType.EQUALS):
+                value = self._parse_expression()
+                self._match(TokenType.SEMICOLON)
+                return ASTNode('tuple_assignment', value={'targets': targets, 'value': value})
+
         # === BASIC INJECTION: <== (replace target with source) ===
         if self._match(TokenType.INJECT_LEFT):
             # Check if this is a createcmd injection with a code block
@@ -2335,17 +2453,62 @@ class CSSLParser:
             self._expect(TokenType.COMPARE_GT)  # consume >
             return ASTNode('instance_ref', value=instance_name)
 
-        # Check for type generic instantiation: stack<string>, vector<int>, etc.
+        # Check for type generic instantiation: stack<string>, vector<int>, map<string, int>, etc.
         # This creates a new instance of the type with the specified element type
         if name in TYPE_GENERICS and self._check(TokenType.COMPARE_LT):
             self._advance()  # consume <
             element_type = 'dynamic'
+            value_type = None  # For map<K, V>
+
             if self._check(TokenType.KEYWORD) or self._check(TokenType.IDENTIFIER):
                 element_type = self._advance().value
+
+            # Check for second type parameter (map<K, V>)
+            if name == 'map' and self._check(TokenType.COMMA):
+                self._advance()  # consume ,
+                if self._check(TokenType.KEYWORD) or self._check(TokenType.IDENTIFIER):
+                    value_type = self._advance().value
+                else:
+                    value_type = 'dynamic'
+
             self._expect(TokenType.COMPARE_GT)  # consume >
+
+            # Check for inline initialization: map<K,V>{"key": "value", ...}
+            init_values = None
+            if self._check(TokenType.BLOCK_START):
+                self._advance()  # consume {
+                init_values = {}
+
+                while not self._check(TokenType.BLOCK_END) and not self._is_at_end():
+                    # Parse key
+                    if self._check(TokenType.STRING):
+                        key = self._advance().value
+                    elif self._check(TokenType.IDENTIFIER):
+                        key = self._advance().value
+                    else:
+                        key = str(self._parse_expression().value) if hasattr(self._parse_expression(), 'value') else 'key'
+
+                    # Expect : or =
+                    if self._check(TokenType.COLON):
+                        self._advance()
+                    elif self._check(TokenType.EQUALS):
+                        self._advance()
+
+                    # Parse value
+                    value = self._parse_expression()
+                    init_values[key] = value
+
+                    # Optional comma
+                    if self._check(TokenType.COMMA):
+                        self._advance()
+
+                self._expect(TokenType.BLOCK_END)  # consume }
+
             return ASTNode('type_instantiation', value={
                 'type': name,
-                'element_type': element_type
+                'element_type': element_type,
+                'value_type': value_type,
+                'init_values': init_values
             })
 
         # Check for type-parameterized function call: OpenFind<string>(0)