IncludeCPP 4.0.2__py3-none-any.whl → 4.2.2__py3-none-any.whl

includecpp/DOCUMENTATION.md

@@ -0,0 +1,593 @@
+# IncludeCPP Documentation
+
+Version 4.2.0 | C++ Performance in Python, Zero Hassle
+
+---
+
+## Overview
+
+IncludeCPP lets you write C++ code and use it directly in Python. It auto-generates pybind11 bindings from your C++ source files.
+
+```bash
+pip install IncludeCPP
+```
+
+---
+
+## Project Setup
+
+### Initialize Project
+
+```bash
+includecpp init
+```
+
+Creates:
+- `cpp.proj` - project configuration
+- `include/` - C++ source files
+- `plugins/` - generated binding definitions
+
+### Project Structure
+
+```
+myproject/
+  cpp.proj           # Configuration
+  include/           # Your C++ code
+    math.cpp
+    utils.cpp
+  plugins/           # Auto-generated binding files
+    math.cp
+    utils.cp
+```
+
+---
+
+## Writing C++ Code
+
+All C++ code must be in `namespace includecpp`:
+
+```cpp
+// include/math.cpp
+#include <vector>
+
+namespace includecpp {
+
+class Calculator {
+public:
+    int add(int a, int b) { return a + b; }
+    int multiply(int a, int b) { return a * b; }
+private:
+    int memory = 0;
+};
+
+int square(int x) { return x * x; }
+
+}  // namespace includecpp
+```
+
+The parser only scans code inside `namespace includecpp`. Everything else is ignored.
+
+---
+
+## Generate Bindings
+
+Create a plugin file from C++ source:
+
+```bash
+includecpp plugin math include/math.cpp
+```
+
+This creates `plugins/math.cp` with binding instructions.
+
+### Plugin File Format
+
+```
+SOURCE(math.cpp) math
+
+PUBLIC(
+    math CLASS(Calculator) {
+        CONSTRUCTOR()
+        METHOD(add)
+        METHOD(multiply)
+    }
+
+    math FUNC(square)
+)
+```
+
+### Key Directives
+
+| Directive | Description |
+|-----------|-------------|
+| `SOURCE(file) name` | Link source to module name |
+| `CLASS(Name)` | Expose a class |
+| `STRUCT(Name)` | Expose a struct |
+| `FUNC(name)` | Expose a free function |
+| `METHOD(name)` | Expose a class method |
+| `METHOD_CONST(name, sig)` | Overloaded method |
+| `CONSTRUCTOR(args)` | Expose constructor |
+| `FIELD(name)` | Expose member variable |
+| `DEPENDS(mod1, mod2)` | Module dependencies |
+
+---
+
+## Build
+
+```bash
+includecpp rebuild
+```
+
+Compiles C++ into Python extension (`.pyd` on Windows, `.so` on Linux/Mac).
+
+### Build Flags
+
+```bash
+includecpp rebuild                  # Standard build
+includecpp rebuild --clean          # Full rebuild, clear caches
+includecpp rebuild --fast           # Fast incremental (~0.4s if unchanged)
+includecpp rebuild --verbose        # Show compiler output
+includecpp rebuild -m crypto        # Build specific module only
+includecpp rebuild -j 8             # Use 8 parallel jobs
+```
+
+### Build Times
+
+| Scenario | Time |
+|----------|------|
+| No changes (--fast) | ~0.4s |
+| Source changed | ~5-10s |
+| Full rebuild | ~30s |
+
+---
+
+## Using in Python
+
+### Direct Import
+
+```python
+from includecpp import math
+
+calc = math.Calculator()
+print(calc.add(2, 3))      # 5
+print(math.square(4))      # 16
+```
+
+### CppApi
+
+```python
+from includecpp import CppApi
+
+api = CppApi()
+math = api.include("math")
+```
+
+---
+
+## Development Workflow
+
+### Auto Command
+
+For active development:
+
+```bash
+includecpp auto math
+```
+
+Regenerates `.cp` file from source and rebuilds in one command.
+
+### Rebuild All
+
+```bash
+includecpp auto --all
+includecpp auto --all -x tests    # All except tests
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `init` | Create project structure |
+| `plugin <name> <files>` | Generate .cp from C++ sources |
+| `auto <plugin>` | Regenerate .cp and rebuild |
+| `rebuild` / `build` | Compile all modules |
+| `get <module>` | Show module API |
+| `fix <module>` | Analyze C++ code for issues |
+| `--doc` | Show this documentation |
+| `--doc "term"` | Search documentation |
+| `--changelog` | Show latest changes |
+
+---
+
+## Advanced Features
+
+### Overloaded Methods
+
+```
+MODULE CLASS(Circle) {
+    METHOD_CONST(intersects, const Circle&)
+    METHOD_CONST(intersects, const Rect&)
+}
+```
+
+### Template Instantiation
+
+```
+MODULE TEMPLATE_FUNC(maximum) TYPES(int, float, double)
+```
+
+Generates: `maximum_int`, `maximum_float`, `maximum_double`
+
+### Module Dependencies
+
+```
+DEPENDS(math_utils, geometry)
+```
+
+Ensures dependent modules build first.
+
+---
+
+## Configuration
+
+### cpp.proj
+
+```json
+{
+  "project": "MyProject",
+  "include": "/include",
+  "plugins": "/plugins",
+  "compiler": {
+    "standard": "c++17",
+    "optimization": "O3"
+  }
+}
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `project` | Project name |
+| `include` | C++ source directory |
+| `plugins` | Plugin file directory |
+| `compiler.standard` | C++ standard (c++11/14/17/20) |
+| `compiler.optimization` | Optimization level (O0-O3) |
+
+---
+
+## CSSL Scripting
+
+IncludeCPP includes CSSL (C-Style Scripting Language) for runtime scripting.
+
+### Basic Usage
+
+```python
+from includecpp import CSSL
+
+CSSL.run('''
+    printl("Hello from CSSL!");
+
+    int x = 10;
+    for (i in range(0, 5)) {
+        x = x + i;
+    }
+    printl(x);
+''')
+```
+
+### Parameters and Return
+
+```python
+result = CSSL.run('''
+    int a = parameter.get(0);
+    int b = parameter.get(1);
+    parameter.return(a + b);
+''', 5, 3)
+
+print(result)  # 8
+```
+
+### Shared Objects
+
+Share Python objects with CSSL:
+
+```python
+class Counter:
+    def __init__(self):
+        self.value = 100
+
+counter = Counter()
+cssl = CSSL.CsslLang()
+cssl.share(counter, "cnt")
+
+cssl.run('''
+    $cnt.value = $cnt.value - 10;
+    printl($cnt.value);  // 90
+''')
+
+print(counter.value)  # 90 - Changed!
+```
+
+### Object Syntax
+
+| Syntax | Description |
+|--------|-------------|
+| `$name` | Access shared object |
+| `@name` | Access global variable |
+| `%name` | Access captured variable |
+| `this->` | Access instance member |
+
+---
+
+## CSSL Data Types
+
+### Primitives
+
+```cssl
+int x = 42;
+float pi = 3.14;
+string name = "CSSL";
+bool active = true;
+dynamic any = "flexible";
+```
+
+### Collections
+
+```cssl
+array<int> arr;
+arr.push(1);
+arr.push(2);
+
+vector<string> vec;
+stack<int> s;
+map<string, int> ages;
+list items = [1, 2, 3];
+dict data = {"a": 1};
+```
+
+---
+
+## CSSL Control Flow
+
+```cssl
+// If/elif/else
+if (x > 10) {
+    printl("big");
+} elif (x > 5) {
+    printl("medium");
+} else {
+    printl("small");
+}
+
+// For loop
+for (i in range(0, 10)) {
+    printl(i);
+}
+
+// Foreach
+foreach (item in items) {
+    printl(item);
+}
+
+// While
+while (count < 5) {
+    count = count + 1;
+}
+```
+
+---
+
+## CSSL Functions
+
+```cssl
+// Basic function
+void greet(string name) {
+    printl("Hello, " + name + "!");
+}
+
+// Return value
+int add(int a, int b) {
+    return a + b;
+}
+
+// Typed function (C++ style)
+int multiply(int a, int b) {
+    return a * b;
+}
+```
+
+---
+
+## CSSL Classes
+
+```cssl
+class Person {
+    string name;
+    int age;
+
+    constr Person(string n, int a) {
+        this->name = n;
+        this->age = a;
+    }
+
+    void greet() {
+        printl("I am " + this->name);
+    }
+}
+
+instance = new Person("Alice", 30);
+instance.greet();
+```
+
+### Inheritance
+
+```cssl
+class Employee : extends Person {
+    string role;
+
+    constr Employee(string n, int a, string r) {
+        super(n, a);
+        this->role = r;
+    }
+}
+```
+
+---
+
+## CSSL Injection Operators
+
+### Data Movement
+
+```cssl
+target <== source;     // Move data (replace)
+target +<== source;    // Copy & add
+target -<== source;    // Move & remove from source
+```
+
+### Code Infusion
+
+```cssl
+myFunc() <<== {
+    printl("Injected!");
+};
+
+myFunc() +<<== {
+    printl("Added!");
+};
+```
+
+---
+
+## CSSL Modules
+
+### Create Module
+
+```python
+mod = CSSL.module('''
+    int add(int a, int b) {
+        return a + b;
+    }
+''')
+
+result = mod.call("add", 2, 3)  # 5
+```
+
+### Makemodule
+
+```python
+math_mod = CSSL.makemodule('''
+    int square(int x) {
+        return x * x;
+    }
+''')
+
+print(math_mod.square(5))  # 25
+```
+
+---
+
+## Pythonize CSSL Classes
+
+Return CSSL classes to Python:
+
+```python
+greeter = cssl.run('''
+    class Greeter {
+        string name;
+
+        Greeter(string n) {
+            this->name = n;
+        }
+
+        string sayHello() {
+            return "Hello, " + this->name;
+        }
+    }
+
+    instance = new Greeter("World");
+    pyclass = python::pythonize(instance);
+    parameter.return(pyclass);
+''')
+
+print(greeter.sayHello())  # "Hello, World"
+```
+
+---
+
+## Universal Instances
+
+Shared containers across CSSL and Python:
+
+```python
+cssl.run('''
+    instance<"myData"> data;
+    data.value = 42;
+''')
+
+container = cssl.getInstance("myData")
+print(container.value)  # 42
+```
+
+---
+
+## AI Integration
+
+### Setup
+
+```bash
+includecpp ai key sk-your-api-key
+includecpp ai enable
+```
+
+### Commands
+
+```bash
+includecpp ai ask "where is collision detection?"
+includecpp ai edit "add logging" --file utils.cpp
+includecpp ai optimize mymodule
+includecpp fix --ai mymodule
+```
+
+---
+
+## CPPY Code Conversion
+
+### Python to C++
+
+```bash
+includecpp cppy convert math.py --cpp
+```
+
+### C++ to Python
+
+```bash
+includecpp cppy convert utils.cpp --py
+```
+
+### AI-Assisted
+
+```bash
+includecpp cppy convert complex.py --cpp --ai
+```
+
+---
+
+## Requirements
+
+- Python 3.8+
+- C++ compiler (g++, clang++, MSVC)
+- pybind11 (installed automatically)
+- CMake
+
+---
+
+## Support
+
+Report issues: https://github.com/liliassg/IncludeCPP/issues
+
+```bash
+includecpp bug    # Report an issue
+includecpp update # Update IncludeCPP
+```

includecpp/__init__.py

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

includecpp/__init__.pyi

@@ -147,7 +147,10 @@ __version__: str
 # Dynamic module access via: from includecpp import <module_name>
 # Auto-generated module declarations
 # These allow: from includecpp import <module_name>
-# (Run 'includecpp rebuild' to generate declarations for your modules)
+fast_list: Fast_listModuleWrapper
+game_math: Game_mathModuleWrapper
+solar_system: Solar_systemModuleWrapper
+templates: TemplatesModuleWrapper
 
 def __dir__() -> List[str]:
     """List available modules including dynamically loaded C++ modules."""