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

includecpp/DOCUMENTATION.md

@@ -1,132 +1,128 @@
 # IncludeCPP Documentation
 
-Version 4.2.0 | C++ Performance in Python, Zero Hassle
+Version 4.3.0
 
 ---
 
-## Overview
+## What is IncludeCPP?
 
-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
-```
+IncludeCPP lets you write C++ code and use it directly in Python. You write your C++ functions and classes, run a few commands, and then import them in Python like any other module.
 
 ---
 
-## Project Setup
+## Getting Started
 
-### Initialize Project
+### Installation
 
 ```bash
-includecpp init
+pip install IncludeCPP
 ```
 
-Creates:
-- `cpp.proj` - project configuration
-- `include/` - C++ source files
-- `plugins/` - generated binding definitions
+### Create Your First Project
 
-### Project Structure
-
-```
-myproject/
-  cpp.proj           # Configuration
-  include/           # Your C++ code
-    math.cpp
-    utils.cpp
-  plugins/           # Auto-generated binding files
-    math.cp
-    utils.cp
+```bash
+mkdir myproject
+cd myproject
+includecpp init
 ```
 
----
+This creates three things:
+- `cpp.proj` - Project settings
+- `include/` - Your C++ source files go here
+- `plugins/` - Generated binding files
 
-## Writing C++ Code
+### Write C++ Code
 
-All C++ code must be in `namespace includecpp`:
+Create a file `include/math.cpp`:
 
 ```cpp
-// include/math.cpp
-#include <vector>
-
 namespace includecpp {
 
-class Calculator {
+int add(int a, int b) {
+    return a + b;
+}
+
+class Counter {
 public:
-    int add(int a, int b) { return a + b; }
-    int multiply(int a, int b) { return a * b; }
+    Counter() : value(0) {}
+    void increment() { value++; }
+    int get() { return value; }
 private:
-    int memory = 0;
+    int value;
 };
 
-int square(int x) { return x * x; }
-
-}  // namespace includecpp
+}
 ```
 
-The parser only scans code inside `namespace includecpp`. Everything else is ignored.
-
----
-
-## Generate Bindings
+Important: All your code must be inside `namespace includecpp`. Anything outside is ignored.
 
-Create a plugin file from C++ source:
+### Generate Bindings
 
 ```bash
 includecpp plugin math include/math.cpp
 ```
 
-This creates `plugins/math.cp` with binding instructions.
+This creates `plugins/math.cp` with instructions for building the Python module.
 
-### Plugin File Format
+### Build
 
+```bash
+includecpp rebuild
 ```
-SOURCE(math.cpp) math
 
-PUBLIC(
-    math CLASS(Calculator) {
-        CONSTRUCTOR()
-        METHOD(add)
-        METHOD(multiply)
-    }
+### Use in Python
 
-    math FUNC(square)
-)
-```
+```python
+from includecpp import math
 
-### Key Directives
+# Use function
+result = math.add(5, 3)
+print(result)  # 8
 
-| 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 |
+# Use class
+counter = math.Counter()
+counter.increment()
+counter.increment()
+print(counter.get())  # 2
+```
 
 ---
 
-## Build
+## Project Structure
 
-```bash
-includecpp rebuild
 ```
+myproject/
+    cpp.proj           # Project configuration
+    include/           # Your C++ source files
+        math.cpp
+        utils.cpp
+    plugins/           # Generated binding files
+        math.cp
+        utils.cp
+```
+
+---
+
+## CLI Commands
+
+### Basic Commands
 
-Compiles C++ into Python extension (`.pyd` on Windows, `.so` on Linux/Mac).
+| Command | Description |
+|---------|-------------|
+| `includecpp init` | Create new project |
+| `includecpp plugin <name> <file>` | Generate bindings from C++ file |
+| `includecpp rebuild` | Build all modules |
+| `includecpp auto <name>` | Regenerate + rebuild in one step |
+| `includecpp get <name>` | Show module API |
 
-### Build Flags
+### Build Options
 
 ```bash
 includecpp rebuild                  # Standard build
-includecpp rebuild --clean          # Full rebuild, clear caches
-includecpp rebuild --fast           # Fast incremental (~0.4s if unchanged)
+includecpp rebuild --fast           # Skip unchanged files (~0.4s)
+includecpp rebuild --clean          # Full rebuild from scratch
 includecpp rebuild --verbose        # Show compiler output
-includecpp rebuild -m crypto        # Build specific module only
+includecpp rebuild -m mymodule      # Build specific module only
 includecpp rebuild -j 8             # Use 8 parallel jobs
 ```
 
@@ -134,98 +130,62 @@ includecpp rebuild -j 8             # Use 8 parallel jobs
 
 | Scenario | Time |
 |----------|------|
-| No changes (--fast) | ~0.4s |
-| Source changed | ~5-10s |
+| Nothing changed (--fast) | ~0.4s |
+| Source file 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
+## Plugin File Format (.cp)
 
-### Auto Command
+Plugin files define what gets exposed to Python. They're auto-generated but you can edit them.
 
-For active development:
-
-```bash
-includecpp auto math
 ```
+SOURCE(math.cpp) math
 
-Regenerates `.cp` file from source and rebuilds in one command.
-
-### Rebuild All
+PUBLIC(
+    math CLASS(Counter) {
+        CONSTRUCTOR()
+        METHOD(increment)
+        METHOD(get)
+    }
 
-```bash
-includecpp auto --all
-includecpp auto --all -x tests    # All except tests
+    math FUNC(add)
+)
 ```
 
----
+### Directives
 
-## 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
+| Directive | Use |
+|-----------|-----|
+| `SOURCE(file) name` | Link source file to module name |
+| `CLASS(Name)` | Expose a class |
+| `STRUCT(Name)` | Expose a struct |
+| `FUNC(name)` | Expose a function |
+| `METHOD(name)` | Expose a method |
+| `CONSTRUCTOR()` | Expose default constructor |
+| `CONSTRUCTOR(int, string)` | Expose constructor with parameters |
+| `FIELD(name)` | Expose member variable |
+| `DEPENDS(mod1, mod2)` | Module dependencies |
 
 ### Overloaded Methods
 
+When a class has multiple methods with the same name:
+
 ```
-MODULE CLASS(Circle) {
+CLASS(Shape) {
     METHOD_CONST(intersects, const Circle&)
     METHOD_CONST(intersects, const Rect&)
 }
 ```
 
-### Template Instantiation
+### Templates
 
 ```
-MODULE TEMPLATE_FUNC(maximum) TYPES(int, float, double)
+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.
+Creates: `maximum_int`, `maximum_float`, `maximum_double`
 
 ---
 
@@ -245,21 +205,84 @@ Ensures dependent modules build first.
 }
 ```
 
-### 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) |
+| `compiler.standard` | C++ standard (c++11, c++14, c++17, c++20) |
+| `compiler.optimization` | Optimization level (O0, O1, O2, O3) |
+
+---
+
+## Using Modules in Python
+
+### Direct Import
+
+```python
+from includecpp import math
+
+result = math.add(1, 2)
+```
+
+### CppApi
+
+```python
+from includecpp import CppApi
+
+api = CppApi()
+math = api.include("math")
+```
+
+---
+
+## Requirements
+
+- Python 3.9 or newer
+- C++ compiler (g++, clang++, or MSVC)
+- CMake
+- pybind11 (installed automatically)
+
+---
+
+## Troubleshooting
+
+### "Module not found"
+
+Run `includecpp rebuild` to compile your modules.
+
+### Build errors
+
+- Check your C++ code compiles normally
+- Make sure code is inside `namespace includecpp`
+- Run `includecpp rebuild --verbose` for details
+
+### Changes not showing
+
+Run `includecpp rebuild --clean` to force a full rebuild.
+
+---
+
+## Support
+
+Report issues: https://github.com/liliassg/IncludeCPP/issues
+
+```bash
+includecpp bug     # Report a bug
+includecpp update  # Update to latest version
+```
+
+---
+
+# Experimental Features
+
+The following features are experimental and may change between versions.
 
 ---
 
 ## CSSL Scripting
 
-IncludeCPP includes CSSL (C-Style Scripting Language) for runtime scripting.
+CSSL (C-Style Scripting Language) is an embedded scripting language included with IncludeCPP.
 
 ### Basic Usage
 
@@ -277,7 +300,7 @@ CSSL.run('''
 ''')
 ```
 
-### Parameters and Return
+### Parameters and Return Values
 
 ```python
 result = CSSL.run('''
@@ -289,70 +312,46 @@ result = CSSL.run('''
 print(result)  # 8
 ```
 
-### Shared Objects
-
-Share Python objects with CSSL:
+### Sharing Python Objects
 
 ```python
-class Counter:
+from includecpp import CSSL
+
+class Player:
     def __init__(self):
-        self.value = 100
+        self.health = 100
 
-counter = Counter()
+player = Player()
 cssl = CSSL.CsslLang()
-cssl.share(counter, "cnt")
+cssl.share(player, "player")
 
 cssl.run('''
-    $cnt.value = $cnt.value - 10;
-    printl($cnt.value);  // 90
+    $player.health = $player.health - 10;
+    printl($player.health);
 ''')
 
-print(counter.value)  # 90 - Changed!
+print(player.health)  # 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
+### Data Types
 
 ```cssl
 int x = 42;
 float pi = 3.14;
-string name = "CSSL";
+string name = "test";
 bool active = true;
-dynamic any = "flexible";
-```
 
-### Collections
+array<int> numbers;
+numbers.push(1);
+numbers.push(2);
 
-```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};
+dict data = {"key": "value"};
 ```
 
----
-
-## CSSL Control Flow
+### Control Flow
 
 ```cssl
-// If/elif/else
 if (x > 10) {
     printl("big");
 } elif (x > 5) {
@@ -361,46 +360,28 @@ if (x > 10) {
     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
+### Functions
 
 ```cssl
-// Basic function
-void greet(string name) {
+define greet(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
+### Classes
 
 ```cssl
 class Person {
@@ -417,177 +398,49 @@ class Person {
     }
 }
 
-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;
-    }
-}
+person = new Person("Alice", 30);
+person.greet();
 ```
 
----
-
-## CSSL Injection Operators
+### Payloads
 
-### Data Movement
+Load reusable CSSL code from files:
 
 ```cssl
-target <== source;     // Move data (replace)
-target +<== source;    // Copy & add
-target -<== source;    // Move & remove from source
+payload("helpers");              // Loads helpers.cssl-pl
+payload("mylib", "mylib");       // Loads into namespace mylib::
 ```
 
-### Code Infusion
-
+With namespaces:
 ```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
+payload("engine", "Engine");
+myengine = new Engine::GameEngine();
+Engine::init();
 ```
 
 ---
 
-## Pythonize CSSL Classes
-
-Return CSSL classes to Python:
+## AI Commands
 
-```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
+OpenAI-powered code assistance (requires API key).
 
 ```bash
-includecpp ai key sk-your-api-key
+includecpp ai key sk-your-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
+## CPPY Conversion
 
-### Python to C++
+Convert code between Python and 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 cppy convert file.py --cpp --ai
 ```