IncludeCPP 3.5.0__py3-none-any.whl → 3.7.1__py3-none-any.whl

includecpp/core/cssl/CSSL_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # CSSL - C-Style Scripting Language
 
-> Version 3.4.20 | A modern scripting language with C++-style syntax and unique features like CodeInfusion and BruteInjection.
+> Version 3.7.0 | A modern scripting language with C++-style syntax and unique features like CodeInfusion and BruteInjection.
 
 ---
 
@@ -15,16 +15,22 @@
 7. [Functions](#functions)
 8. [Function Keywords](#function-keywords)
 9. [String Methods](#string-methods)
-10. [Live Object Sharing](#live-object-sharing)
-11. [CodeInfusion](#codeinfusion)
-12. [BruteInjection](#bruteinjection)
-13. [Filter Syntax](#filter-syntax)
-14. [Module System](#module-system)
-15. [Parameter Bridge](#parameter-bridge)
-16. [Structures](#structures)
-17. [Error Handling](#error-handling)
-18. [CLI Commands](#cli-commands)
-19. [Examples](#examples)
+10. [File I/O](#file-io)
+11. [JSON Functions](#json-functions)
+12. [Instance Management](#instance-management)
+13. [Live Object Sharing](#live-object-sharing)
+14. [CodeInfusion](#codeinfusion)
+15. [Value Capture](#value-capture)
+16. [BruteInjection](#bruteinjection)
+17. [Filter Syntax](#filter-syntax)
+18. [Module System](#module-system)
+19. [Parameter Bridge](#parameter-bridge)
+20. [Classes & OOP](#classes--oop)
+21. [Map Container](#map-container)
+22. [Structures](#structures)
+23. [Error Handling](#error-handling)
+24. [CLI Commands](#cli-commands)
+25. [Examples](#examples)
 
 ---
 
@@ -336,14 +342,26 @@ int number = 42;
 // Declaration with 'global'
 global myGlobal = "visible everywhere";
 
-// Access with '@'
+// Access with '@' prefix
 printl(@myGlobal);
 
-// Alternative: r@ syntax
+// Or access directly without '@' (since v3.5.9)
+printl(myGlobal);  // Works the same!
+
+// Alternative: r@ syntax for declaration
 r@anotherGlobal = "also global";
 printl(@anotherGlobal);
+printl(anotherGlobal);  // Also works
 ```
 
+### Lookup Order
+
+When accessing a variable, CSSL checks in order:
+1. Local scope
+2. Global scope
+3. Promoted globals
+4. Built-in functions
+
 ### Usage in Functions
 
 ```cssl
@@ -539,6 +557,29 @@ string n = getName();
 int sum = add(5, 3);
 ```
 
+### Named Parameters
+
+Functions can be called with named parameters for clarity.
+
+```cssl
+// Define function
+int calculate(int base, int multiplier, int offset) {
+    return base * multiplier + offset;
+}
+
+// Call with positional arguments
+int r1 = calculate(10, 5, 3);  // 53
+
+// Call with named parameters
+int r2 = calculate(base=10, multiplier=5, offset=3);  // 53
+
+// Mix positional and named (positional must come first)
+int r3 = calculate(10, multiplier=5, offset=3);  // 53
+
+// Named parameters can be in any order
+int r4 = calculate(offset=3, base=10, multiplier=5);  // 53
+```
+
 ### Nested Functions
 
 ```cssl
@@ -798,6 +839,247 @@ string padded2 = num.padEnd(5, ".");    // "42..."
 
 ---
 
+## File I/O
+
+CSSL provides built-in functions for file operations.
+
+### Basic File Operations
+
+```cssl
+// Read entire file
+string content = read("/path/to/file.txt");
+printl(content);
+
+// Read specific line (1-indexed)
+string line5 = readline(5, "/path/to/file.txt");
+printl(line5);
+
+// Write to file (overwrites)
+write("/path/to/file.txt", "Hello World");
+
+// Write/replace specific line
+writeline(3, "New line content", "/path/to/file.txt");
+```
+
+### Extended File Functions
+
+```cssl
+// Read all lines as array
+stack<string> lines = readlines("/path/to/file.txt");
+
+// Append to file
+appendfile("/path/to/file.txt", "\nNew content");
+
+// File checks
+bool exists = pathexists("/path/to/file.txt");
+bool isFile = isfile("/path/to/file.txt");
+bool isDir = isdir("/path/to/folder");
+
+// File size
+int size = filesize("/path/to/file.txt");
+
+// Directory listing
+stack<string> files = listdir("/path/to/folder");
+```
+
+### Path Functions
+
+```cssl
+// Path manipulation
+string base = basename("/path/to/file.txt");    // "file.txt"
+string dir = dirname("/path/to/file.txt");       // "/path/to"
+string full = joinpath("/path", "to", "file.txt"); // "/path/to/file.txt"
+string abs = abspath("./file.txt");              // "/current/dir/file.txt"
+```
+
+### All File I/O Functions
+
+| Function | Description |
+|----------|-------------|
+| `read(path)` | Read entire file content |
+| `readline(line, path)` | Read specific line (1-indexed) |
+| `write(path, content)` | Write content to file |
+| `writeline(line, content, path)` | Write/replace specific line |
+| `readfile(path)` | Read file (alias for read) |
+| `writefile(path, content)` | Write file (alias for write) |
+| `readlines(path)` | Read all lines as array |
+| `appendfile(path, content)` | Append to file |
+| `pathexists(path)` | Check if path exists |
+| `isfile(path)` | Check if is file |
+| `isdir(path)` | Check if is directory |
+| `filesize(path)` | Get file size in bytes |
+| `listdir(path)` | List directory contents |
+| `makedirs(path)` | Create directories |
+| `removefile(path)` | Delete file |
+| `removedir(path)` | Delete empty directory |
+| `copyfile(src, dst)` | Copy file |
+| `movefile(src, dst)` | Move file |
+
+---
+
+## JSON Functions
+
+CSSL provides namespace-style JSON functions with the `json::` prefix.
+
+### Reading & Writing JSON Files
+
+```cssl
+// Read and parse JSON file
+json data = json::read("/path/to/config.json");
+printl(data.name);
+
+// Write data to JSON file
+json::write("/path/to/output.json", data);
+```
+
+### JSON Parsing & Stringifying
+
+```cssl
+// Parse JSON string
+string jsonStr = '{"name": "Alice", "age": 30}';
+json obj = json::parse(jsonStr);
+
+// Convert to JSON string
+string str = json::stringify(obj);
+
+// Pretty print with indentation
+string pretty = json::pretty(obj);
+printl(pretty);
+```
+
+### JSON Path Operations
+
+```cssl
+json data = json::read("config.json");
+
+// Get value by dot-path
+string name = json::get(data, "user.name");
+int age = json::get(data, "user.profile.age");
+string city = json::get(data, "address.city", "Unknown");  // with default
+
+// Set value by dot-path
+data = json::set(data, "user.name", "Bob");
+data = json::set(data, "settings.theme", "dark");
+
+// Check if path exists
+if (json::has(data, "user.email")) {
+    printl("Email exists");
+}
+```
+
+### JSON Object Operations
+
+```cssl
+json obj = json::read("data.json");
+
+// Get all keys
+stack<string> keys = json::keys(obj);
+foreach (key in keys) {
+    printl(key);
+}
+
+// Get all values
+stack<dynamic> values = json::values(obj);
+
+// Deep merge objects
+json merged = json::merge(obj1, obj2, obj3);
+```
+
+### All JSON Functions
+
+| Function | Description |
+|----------|-------------|
+| `json::read(path)` | Read and parse JSON file |
+| `json::write(path, data)` | Write data to JSON file |
+| `json::parse(str)` | Parse JSON string to object |
+| `json::stringify(data)` | Convert to JSON string |
+| `json::pretty(data)` | Pretty print JSON |
+| `json::get(data, path, default)` | Get value by dot-path |
+| `json::set(data, path, value)` | Set value by dot-path |
+| `json::has(data, path)` | Check if path exists |
+| `json::keys(data)` | Get all keys |
+| `json::values(data)` | Get all values |
+| `json::merge(obj1, obj2, ...)` | Deep merge objects |
+
+---
+
+## Instance Management
+
+CSSL provides `instance<"name">` syntax and `instance::` namespace for working with shared instances.
+
+### Instance Declaration
+
+```cssl
+// Get/create shared instance by name
+instance<"MyApp"> app;
+
+// With initialization
+instance<"tk"> tk = include("tkinter.cssl-mod");
+
+// Register object as shared instance
+myModule ==> $AppModule
+// Or using instance syntax:
+myModule ==> instance<"AppModule">
+```
+
+### Instance Introspection
+
+```cssl
+@tk = include("tk.cssl-mod");
+
+// Get all methods from module
+stack<string> methods = instance::getMethods(@tk);
+foreach (m in methods) {
+    printl("Method: " + m);
+}
+
+// Get all classes
+stack<string> classes = instance::getClasses(@tk);
+
+// Get all variables
+stack<string> vars = instance::getVars(@tk);
+
+// Get everything categorized
+json all = instance::getAll(@tk);
+printl(all.methods);   // ["method1", "method2", ...]
+printl(all.classes);   // ["Class1", "Class2", ...]
+printl(all.vars);      // ["var1", "var2", ...]
+```
+
+### Dynamic Method Calls
+
+```cssl
+// Call method dynamically by name
+result = instance::call(@module, "methodName", arg1, arg2);
+
+// Check if method/attribute exists
+if (instance::has(@module, "initialize")) {
+    instance::call(@module, "initialize");
+}
+
+// Get type name
+string typeName = instance::type(@module);
+printl(typeName);  // "module"
+```
+
+### All Instance Functions
+
+| Function | Description |
+|----------|-------------|
+| `instance<"name"> var` | Declare instance variable |
+| `obj ==> instance<"name">` | Register as shared instance |
+| `instance::getMethods(obj)` | Get all method names |
+| `instance::getClasses(obj)` | Get all class names |
+| `instance::getVars(obj)` | Get all variable names |
+| `instance::getAll(obj)` | Get categorized dict |
+| `instance::call(obj, 'name', ...)` | Call method dynamically |
+| `instance::has(obj, 'name')` | Check if attribute exists |
+| `instance::type(obj)` | Get type name |
+| `isavailable("name")` | Check if shared instance exists |
+| `instance::exists("name")` | Alias for isavailable |
+
+---
+
 ## Live Object Sharing
 
 Share Python objects with CSSL. Changes in CSSL reflect back to Python.
@@ -934,6 +1216,74 @@ exit();  // Executes injection
 
 ---
 
+## Value Capture
+
+The `%identifier` syntax captures values at registration time, useful for saving original functions before replacement.
+
+### Capturing Variables
+
+```cssl
+string version = "1.0.0";
+
+// Capture current value
+v <== { %version; }
+printl(v);  // "1.0.0"
+
+// Even if version changes later, v keeps captured value
+version = "2.0.0";
+printl(v);  // Still "1.0.0"
+```
+
+### Capturing Functions
+
+```cssl
+// Save original exit function before replacing
+originalExit <<== { %exit(); }
+
+// Replace exit with custom behavior
+exit() <<== {
+    printl("Custom cleanup...");
+    originalExit();  // Call saved original
+}
+
+exit();
+// Output:
+// Custom cleanup...
+// (original exit behavior)
+```
+
+### Use Cases
+
+```cssl
+// 1. Preserving original behavior
+void myFunc() {
+    printl("Original");
+}
+
+savedFunc <<== { %myFunc(); }
+
+myFunc() <<== {
+    printl("Modified");
+}
+
+myFunc();      // "Modified"
+savedFunc();   // "Original"
+
+// 2. Capturing configuration at startup
+global config = loadConfig();
+startupConfig <== { %config; }
+
+// 3. Snapshot values for later comparison
+int counter = 0;
+initial <== { %counter; }
+// ... operations ...
+if (counter != initial) {
+    printl("Counter changed!");
+}
+```
+
+---
+
 ## BruteInjection
 
 BruteInjection copies/moves data between containers.
@@ -981,6 +1331,26 @@ container ==> data;
 
 ---
 
+### ==>- (Receive Minus)
+
+Removes matching items from target.
+
+```cssl
+stack<string> names;
+names.push("Alice");
+names.push("Bob");
+names.push("Alice");
+
+stack<string> toRemove;
+toRemove.push("Alice");
+
+// Remove all "Alice" from names
+names ==>- toRemove;
+printl(names);  // ["Bob"]
+```
+
+---
+
 ## Filter Syntax
 
 Filters enable targeted data operations in BruteInjection.
@@ -1014,6 +1384,30 @@ result +<== [string::contains="App"] fruits;  // Apple, Apricot
 result +<== [string::length=5] fruits;  // Apple
 ```
 
+### String Cutting Filters
+
+Cut strings at specific positions or substrings.
+
+```cssl
+string version = "1.0.0-beta";
+
+// Cut at position (integer index)
+x = <==[string::cut=3] version;
+printl(x);  // "1.0" (first 3 chars)
+
+// Cut at substring position
+x = <==[string::cut="0-"] version;
+printl(x);  // "1.0." (before "0-")
+
+// Get everything after substring
+x = <==[string::cutAfter=".0."] version;
+printl(x);  // "0-beta" (after ".0.")
+
+// Cut after at position
+x = <==[string::cutAfter=4] version;
+printl(x);  // ".0-beta" (after index 4)
+```
+
 ### All Filters
 
 | Filter | Description |
@@ -1022,6 +1416,10 @@ result +<== [string::length=5] fruits;  // Apple
 | `string::not=VALUE` | Everything except this value |
 | `string::contains=VALUE` | Contains substring |
 | `string::length=LENGTH` | Exact string length |
+| `string::cut=INDEX` | Cut at index (returns first N chars) |
+| `string::cut="SUBSTR"` | Cut at substring position |
+| `string::cutAfter=INDEX` | Get everything after index |
+| `string::cutAfter="SUBSTR"` | Get everything after substring |
 | `integer::where=VALUE` | Exact int match |
 | `json::key=KEYNAME` | Filter by JSON key |
 | `json::value=VALUE` | Filter by JSON value |
@@ -1157,6 +1555,188 @@ parameter.return(myObject);       // JSON/dict
 
 ---
 
+## Classes & OOP
+
+CSSL supports object-oriented programming with classes, constructors, and the `this->` keyword for member access.
+
+### Defining a Class
+
+```cssl
+class Person {
+    // Member variables
+    string name;
+    int age;
+
+    // Constructor (same name as class)
+    void Person(string n, int a) {
+        this->name = n;
+        this->age = a;
+    }
+
+    // Methods
+    void greet() {
+        printl("Hello, I'm " + this->name);
+    }
+
+    string getName() {
+        return this->name;
+    }
+
+    void setAge(int a) {
+        this->age = a;
+    }
+}
+```
+
+### Creating Instances
+
+```cssl
+// Use 'new' keyword to instantiate
+Person p = new Person("Alice", 30);
+
+// Call methods
+p.greet();                    // prints: "Hello, I'm Alice"
+string name = p.getName();    // returns "Alice"
+
+// Access members (if public)
+printl(p.name);              // prints: "Alice"
+p.age = 31;                  // set member directly
+```
+
+### The `this->` Keyword
+
+Inside class methods, use `this->` to access instance members:
+
+```cssl
+class Counter {
+    int count;
+
+    void Counter() {
+        this->count = 0;
+    }
+
+    void increment() {
+        this->count = this->count + 1;
+    }
+
+    void add(int n) {
+        this->count = this->count + n;
+    }
+
+    int get() {
+        return this->count;
+    }
+}
+
+Counter c = new Counter();
+c.increment();
+c.add(5);
+printl(c.get());  // prints: 6
+```
+
+### Constructor Variations
+
+```cssl
+class MyClass {
+    // Constructor with same name as class
+    void MyClass(int x) {
+        this->value = x;
+    }
+}
+
+// Alternative: use __init__
+class MyClass2 {
+    void __init__(int x) {
+        this->value = x;
+    }
+}
+```
+
+### Method Chaining
+
+```cssl
+class Builder {
+    string result;
+
+    void Builder() {
+        this->result = "";
+    }
+
+    Builder add(string s) {
+        this->result = this->result + s;
+        return this;
+    }
+
+    string build() {
+        return this->result;
+    }
+}
+
+Builder b = new Builder();
+string result = b.add("Hello ").add("World!").build();
+printl(result);  // prints: "Hello World!"
+```
+
+---
+
+## Map Container
+
+The `map<>` type provides C++ style ordered key-value storage.
+
+### Creating Maps
+
+```cssl
+map<string, int> ages;
+map<string, string> config;
+```
+
+### Basic Operations
+
+```cssl
+map<string, int> ages;
+
+// Insert values
+ages.insert("Alice", 30);
+ages.insert("Bob", 25);
+
+// Find values
+int age = ages.find("Alice");  // returns 30
+
+// Check existence
+if (ages.contains("Alice")) {
+    printl("Found!");
+}
+
+// Erase entries
+ages.erase("Bob");
+
+// Get with exception if not found
+int a = ages.at("Alice");  // throws if not found
+
+// Size and empty check
+int size = ages.size();
+bool empty = ages.empty();
+```
+
+### Iteration and Bounds
+
+```cssl
+map<string, int> data;
+data.insert("apple", 1);
+data.insert("banana", 2);
+data.insert("cherry", 3);
+
+// Get first/last elements
+tuple first = data.begin();  // ("apple", 1)
+tuple last = data.end();     // ("cherry", 3)
+
+// Find bounds (for sorted keys)
+string lb = data.lower_bound("b");  // "banana" (first key >= "b")
+string ub = data.upper_bound("b");  // "cherry" (first key > "b")
+```
+
+---
+
 ## Structures
 
 Structures are user-defined data types.
@@ -1457,12 +2037,25 @@ print(result)  # ["Missing colon after def"]
 
 | Operator | Type | Description |
 |----------|------|-------------|
-| `<<==` | CodeInfusion | Replace |
-| `+<<==` | CodeInfusion | Add |
-| `-<<==` | CodeInfusion | Remove |
-| `+<==` | BruteInjection | Copy |
-| `-<==` | BruteInjection | Move |
-| `==>` | BruteInjection | Replace |
+| `<<==` | CodeInfusion | Replace function |
+| `+<<==` | CodeInfusion | Add code (before) |
+| `-<<==` | CodeInfusion | Remove code |
+| `<==` | ValueCapture | Capture/assign value |
+| `+<==` | BruteInjection | Copy data |
+| `-<==` | BruteInjection | Move data |
+| `==>` | BruteInjection | Replace data |
+| `==>-` | BruteInjection | Remove matching items |
+
+### Special Syntax
+
+| Syntax | Description |
+|--------|-------------|
+| `%identifier` | Capture value at registration time |
+| `json::func()` | Namespace function call |
+| `@name` | Access global variable |
+| `$name` | Access shared Python object |
+| `s@name` | Self-reference to struct |
+| `r@name` | Global variable declaration |
 
 ---
 
@@ -1479,4 +2072,4 @@ print(result)  # ["Missing colon after def"]
 
 ---
 
-*CSSL v3.4.20 - Developed as part of IncludeCPP*
+*CSSL v3.6.3 - Developed as part of IncludeCPP*