IncludeCPP 3.6.0__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.6.0"
+__version__ = "3.7.9"
 __all__ = ["CppApi", "CSSL"]
 
 # Module-level cache for C++ modules

includecpp/cli/commands.py

@@ -5,6 +5,7 @@ import platform
 import os
 import sys
 import json
+import re
 import urllib.request
 import urllib.error
 from pathlib import Path
@@ -1192,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")
@@ -1203,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(
@@ -1214,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():
@@ -7479,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')
@@ -7534,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'
@@ -7557,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")
@@ -7729,6 +7891,423 @@ def cssl_vscode():
 cli.add_command(cssl)
 
 
+# ============================================================================
+# VSCODE - Initialize/Update VSCode Configuration
+# ============================================================================
+
+@cli.command()
+@click.option('--force', '-f', is_flag=True, help='Force overwrite existing files')
+@click.option('--stubs-only', is_flag=True, help='Only update stubs, skip extension files')
+def vscode(force, stubs_only):
+    """Initialize or update VSCode configuration for IncludeCPP/CSSL.
+
+    Sets up .vscode folder with:
+    - CSSL language support (syntax highlighting, snippets)
+    - Type stubs for builtins (.pyi files)
+    - Auto-generated stubs for your plugins and modules
+
+    \b
+    Usage:
+      includecpp vscode           # Initialize .vscode
+      includecpp vscode --force   # Force overwrite existing
+      includecpp vscode --stubs-only  # Only update stubs
+
+    \b
+    What it creates:
+      .vscode/
+        settings.json         - VSCode settings for CSSL
+        cssl/                 - CSSL language extension
+        stubs/                - Type stubs for IDE support
+          cssl_builtins.pyi   - CSSL builtin functions
+          plugins/            - Stubs for your .cp plugins
+          modules/            - Stubs for your modules
+    """
+    from pathlib import Path as PathLib
+
+    cwd = PathLib.cwd()
+    vscode_dir = cwd / '.vscode'
+    stubs_dir = vscode_dir / 'stubs'
+    plugins_stubs_dir = stubs_dir / 'plugins'
+    modules_stubs_dir = stubs_dir / 'modules'
+    cssl_ext_dir = vscode_dir / 'cssl'
+
+    # Create directories
+    vscode_dir.mkdir(exist_ok=True)
+    stubs_dir.mkdir(exist_ok=True)
+    plugins_stubs_dir.mkdir(exist_ok=True)
+    modules_stubs_dir.mkdir(exist_ok=True)
+
+    click.secho("=" * 60, fg='cyan')
+    click.secho("IncludeCPP VSCode Configuration", fg='cyan', bold=True)
+    click.secho("=" * 60, fg='cyan')
+    click.echo()
+
+    updated_count = 0
+    created_count = 0
+
+    # 1. Copy CSSL extension files (unless stubs-only)
+    if not stubs_only:
+        click.secho("Setting up CSSL language support...", fg='yellow')
+
+        # Find source extension directory
+        source_ext_dir = PathLib(__file__).parent.parent / 'vscode' / 'cssl'
+
+        if source_ext_dir.exists():
+            cssl_ext_dir.mkdir(exist_ok=True)
+
+            # Copy extension files
+            ext_files = [
+                'language-configuration.json',
+                'package.json',
+            ]
+
+            for fname in ext_files:
+                src = source_ext_dir / fname
+                dst = cssl_ext_dir / fname
+                if src.exists():
+                    if not dst.exists() or force:
+                        shutil.copy2(src, dst)
+                        created_count += 1
+                        click.echo(f"  Created: .vscode/cssl/{fname}")
+
+            # Copy syntaxes folder
+            syntaxes_src = source_ext_dir / 'syntaxes'
+            syntaxes_dst = cssl_ext_dir / 'syntaxes'
+            if syntaxes_src.exists():
+                syntaxes_dst.mkdir(exist_ok=True)
+                for f in syntaxes_src.glob('*.json'):
+                    dst = syntaxes_dst / f.name
+                    if not dst.exists() or force:
+                        shutil.copy2(f, dst)
+                        created_count += 1
+                        click.echo(f"  Created: .vscode/cssl/syntaxes/{f.name}")
+
+            # Copy snippets folder
+            snippets_src = source_ext_dir / 'snippets'
+            snippets_dst = cssl_ext_dir / 'snippets'
+            if snippets_src.exists():
+                snippets_dst.mkdir(exist_ok=True)
+                for f in snippets_src.glob('*.json'):
+                    dst = snippets_dst / f.name
+                    if not dst.exists() or force:
+                        shutil.copy2(f, dst)
+                        created_count += 1
+                        click.echo(f"  Created: .vscode/cssl/snippets/{f.name}")
+
+            click.secho("  CSSL extension configured", fg='green')
+        else:
+            click.secho("  Warning: CSSL extension source not found", fg='yellow')
+
+        click.echo()
+
+    # 2. Copy CSSL builtins stub
+    click.secho("Updating type stubs...", fg='yellow')
+
+    builtins_src = PathLib(__file__).parent.parent / 'core' / 'cssl' / 'cssl_builtins.pyi'
+    builtins_dst = stubs_dir / 'cssl_builtins.pyi'
+
+    if builtins_src.exists():
+        if not builtins_dst.exists() or force:
+            shutil.copy2(builtins_src, builtins_dst)
+            created_count += 1
+            click.echo(f"  Created: .vscode/stubs/cssl_builtins.pyi")
+        else:
+            # Check if source is newer
+            if builtins_src.stat().st_mtime > builtins_dst.stat().st_mtime:
+                shutil.copy2(builtins_src, builtins_dst)
+                updated_count += 1
+                click.echo(f"  Updated: .vscode/stubs/cssl_builtins.pyi")
+            else:
+                click.echo(f"  Up-to-date: .vscode/stubs/cssl_builtins.pyi")
+    else:
+        click.secho("  Warning: cssl_builtins.pyi not found in package", fg='yellow')
+
+    # 3. Generate stubs for user plugins (.cp files)
+    click.echo()
+    click.secho("Scanning for plugins...", fg='yellow')
+
+    plugins_dir = cwd / 'plugins'
+    cp_files = []
+
+    # Find all .cp files
+    for pattern in ['*.cp', '**/*.cp']:
+        cp_files.extend(cwd.glob(pattern))
+
+    if plugins_dir.exists():
+        cp_files.extend(plugins_dir.glob('**/*.cp'))
+
+    # Deduplicate
+    cp_files = list(set(cp_files))
+
+    if cp_files:
+        click.echo(f"  Found {len(cp_files)} plugin(s)")
+
+        for cp_file in cp_files:
+            stub_name = cp_file.stem + '.pyi'
+            stub_path = plugins_stubs_dir / stub_name
+
+            # Generate stub from .cp file
+            stub_content = _generate_plugin_stub(cp_file)
+
+            if stub_content:
+                # Check if needs update
+                needs_write = not stub_path.exists() or force
+                if stub_path.exists() and not force:
+                    existing = stub_path.read_text(encoding='utf-8')
+                    if existing != stub_content:
+                        needs_write = True
+                        updated_count += 1
+                        click.echo(f"  Updated: .vscode/stubs/plugins/{stub_name}")
+                    else:
+                        click.echo(f"  Up-to-date: .vscode/stubs/plugins/{stub_name}")
+                else:
+                    if needs_write:
+                        created_count += 1
+                        click.echo(f"  Created: .vscode/stubs/plugins/{stub_name}")
+
+                if needs_write:
+                    stub_path.write_text(stub_content, encoding='utf-8')
+    else:
+        click.echo("  No .cp plugins found")
+
+    # 4. Generate stubs for modules in registry
+    click.echo()
+    click.secho("Scanning for modules...", fg='yellow')
+
+    try:
+        from ..core.cpp_api import CppApi
+        api = CppApi()
+        modules = list(api.registry.keys())
+
+        if modules:
+            click.echo(f"  Found {len(modules)} registered module(s)")
+
+            for mod_name in modules:
+                stub_name = mod_name + '.pyi'
+                stub_path = modules_stubs_dir / stub_name
+
+                # Generate stub from module
+                stub_content = _generate_module_stub(api, mod_name)
+
+                if stub_content:
+                    needs_write = not stub_path.exists() or force
+                    if stub_path.exists() and not force:
+                        existing = stub_path.read_text(encoding='utf-8')
+                        if existing != stub_content:
+                            needs_write = True
+                            updated_count += 1
+                            click.echo(f"  Updated: .vscode/stubs/modules/{stub_name}")
+                        else:
+                            click.echo(f"  Up-to-date: .vscode/stubs/modules/{stub_name}")
+                    else:
+                        if needs_write:
+                            created_count += 1
+                            click.echo(f"  Created: .vscode/stubs/modules/{stub_name}")
+
+                    if needs_write:
+                        stub_path.write_text(stub_content, encoding='utf-8')
+        else:
+            click.echo("  No modules registered")
+
+    except Exception as e:
+        click.echo(f"  Could not scan modules: {e}")
+
+    # 5. Create/update settings.json
+    if not stubs_only:
+        click.echo()
+        click.secho("Configuring VSCode settings...", fg='yellow')
+
+        settings_path = vscode_dir / 'settings.json'
+        settings = {}
+
+        if settings_path.exists():
+            try:
+                settings = json.loads(settings_path.read_text(encoding='utf-8'))
+            except:
+                pass
+
+        # Add CSSL settings
+        cssl_settings = {
+            "files.associations": {
+                "*.cssl": "cssl",
+                "*.cssl-pl": "cssl",
+                "*.cssl-mod": "cssl",
+                "*.cp": "cpp"
+            },
+            "python.analysis.extraPaths": [
+                ".vscode/stubs"
+            ],
+            "python.autoComplete.extraPaths": [
+                ".vscode/stubs"
+            ]
+        }
+
+        # Merge settings
+        for key, value in cssl_settings.items():
+            if key not in settings:
+                settings[key] = value
+            elif isinstance(value, dict) and isinstance(settings[key], dict):
+                settings[key].update(value)
+            elif isinstance(value, list) and isinstance(settings[key], list):
+                for item in value:
+                    if item not in settings[key]:
+                        settings[key].append(item)
+
+        settings_path.write_text(json.dumps(settings, indent=4), encoding='utf-8')
+        click.echo(f"  Updated: .vscode/settings.json")
+
+    # Summary
+    click.echo()
+    click.secho("=" * 60, fg='cyan')
+    click.secho("Summary", fg='cyan', bold=True)
+    click.secho("=" * 60, fg='cyan')
+    click.echo(f"  Created: {created_count} file(s)")
+    click.echo(f"  Updated: {updated_count} file(s)")
+    click.echo()
+    click.secho("VSCode configuration complete!", fg='green', bold=True)
+    click.echo()
+    click.echo("Tips:")
+    click.echo("  - Re-run 'includecpp vscode' after adding new plugins")
+    click.echo("  - Use --force to overwrite all files")
+    click.echo("  - Use --stubs-only to only regenerate stubs")
+
+
+def _generate_plugin_stub(cp_file: Path) -> str:
+    """Generate a .pyi stub file from a .cp plugin file."""
+    try:
+        content = cp_file.read_text(encoding='utf-8')
+    except:
+        return ""
+
+    lines = [
+        f'"""',
+        f'Type stubs for {cp_file.name}',
+        f'Auto-generated by: includecpp vscode',
+        f'"""',
+        f'from typing import Any, Optional, List, Dict, Union',
+        f'',
+    ]
+
+    # Parse function definitions from .cp file
+    # Look for patterns like: type name(params) { or @export type name(params)
+    func_pattern = re.compile(
+        r'(?:@export\s+)?'
+        r'(int|float|string|void|bool|auto|[A-Z]\w*)\s+'
+        r'(\w+)\s*\(([^)]*)\)',
+        re.MULTILINE
+    )
+
+    found_functions = set()
+
+    for match in func_pattern.finditer(content):
+        ret_type, func_name, params = match.groups()
+
+        if func_name in found_functions:
+            continue
+        found_functions.add(func_name)
+
+        # Convert C++ types to Python types
+        py_ret = _cpp_to_python_type(ret_type)
+        py_params = _parse_cpp_params(params)
+
+        lines.append(f'def {func_name}({py_params}) -> {py_ret}:')
+        lines.append(f'    """Function from {cp_file.name}"""')
+        lines.append(f'    ...')
+        lines.append(f'')
+
+    if len(found_functions) == 0:
+        lines.append(f'# No exported functions found in {cp_file.name}')
+        lines.append(f'')
+
+    return '\n'.join(lines)
+
+
+def _generate_module_stub(api, module_name: str) -> str:
+    """Generate a .pyi stub file from a registered module."""
+    lines = [
+        f'"""',
+        f'Type stubs for module: {module_name}',
+        f'Auto-generated by: includecpp vscode',
+        f'"""',
+        f'from typing import Any, Optional, List, Dict, Union',
+        f'',
+    ]
+
+    try:
+        module = api.registry.get(module_name)
+        if not module:
+            return ""
+
+        # Get module functions
+        funcs = getattr(module, '_functions', {})
+        if not funcs and hasattr(module, '__dict__'):
+            # Try to introspect
+            for name, obj in module.__dict__.items():
+                if callable(obj) and not name.startswith('_'):
+                    lines.append(f'def {name}(*args: Any, **kwargs: Any) -> Any:')
+                    lines.append(f'    """Function from {module_name}"""')
+                    lines.append(f'    ...')
+                    lines.append(f'')
+
+        for func_name, func_info in funcs.items():
+            ret_type = func_info.get('return_type', 'Any')
+            params = func_info.get('params', [])
+
+            py_ret = _cpp_to_python_type(ret_type)
+            py_params = ', '.join([f'{p["name"]}: {_cpp_to_python_type(p.get("type", "Any"))}' for p in params]) if params else ''
+
+            lines.append(f'def {func_name}({py_params}) -> {py_ret}:')
+            lines.append(f'    """Function from {module_name}"""')
+            lines.append(f'    ...')
+            lines.append(f'')
+
+    except Exception:
+        lines.append(f'# Could not introspect module: {module_name}')
+        lines.append(f'')
+
+    return '\n'.join(lines)
+
+
+def _cpp_to_python_type(cpp_type: str) -> str:
+    """Convert C++ type to Python type annotation."""
+    type_map = {
+        'void': 'None',
+        'int': 'int',
+        'float': 'float',
+        'double': 'float',
+        'string': 'str',
+        'bool': 'bool',
+        'auto': 'Any',
+        'char*': 'str',
+        'const char*': 'str',
+    }
+    return type_map.get(cpp_type.strip(), 'Any')
+
+
+def _parse_cpp_params(params_str: str) -> str:
+    """Parse C++ parameter list to Python type annotations."""
+    if not params_str.strip():
+        return ''
+
+    params = []
+    for param in params_str.split(','):
+        param = param.strip()
+        if not param:
+            continue
+
+        # Parse "type name" or "type name = default"
+        parts = param.split('=')[0].strip().split()
+        if len(parts) >= 2:
+            param_type = parts[-2]
+            param_name = parts[-1].strip('&*')
+            py_type = _cpp_to_python_type(param_type)
+            params.append(f'{param_name}: {py_type}')
+        elif len(parts) == 1:
+            params.append(f'arg: Any')
+
+    return ', '.join(params)
+
+
 # ============================================================================
 # Conditional Registration of Experimental Commands
 # ============================================================================