move rhailib to herolib

rhailib/_archive/engine/README.md

@@ -0,0 +1,135 @@
+# HeroModels Rhai Engine (`engine`)
+
+The `engine` crate provides a central Rhai scripting engine for the HeroModels project. It offers a unified way to interact with various HeroModels modules (like Calendar, Flow, Legal, etc.) through Rhai scripts, leveraging a shared database connection.
+
+## Overview
+
+This crate facilitates:
+
+1.  **Centralized Engine Creation**: A function `create_heromodels_engine` to instantiate a Rhai engine pre-configured with common settings and all enabled HeroModels modules.
+2.  **Modular Registration**: HeroModels modules (Calendar, Flow, etc.) can be registered with a Rhai engine based on feature flags.
+3.  **Script Evaluation Utilities**: Helper functions for compiling Rhai scripts into Abstract Syntax Trees (ASTs) and for evaluating scripts or ASTs.
+4.  **Mock Database**: Includes a `mock_db` module for testing and running examples without needing a live database.
+
+## Core Components & Usage
+
+### Library (`src/lib.rs`)
+
+-   **`create_heromodels_engine(db: Arc<OurDB>) -> Engine`**:
+    Creates and returns a new `rhai::Engine` instance. This engine is configured with default settings (e.g., max expression depths, string/array/map sizes) and then all available HeroModels modules (controlled by feature flags) are registered with it, using the provided `db` (an `Arc<OurDB>`) instance.
+
+-   **`register_all_modules(engine: &mut Engine, db: Arc<OurDB>)`**:
+    Registers all HeroModels modules for which features are enabled (e.g., `calendar`, `flow`, `legal`, `projects`, `biz`) with the given Rhai `engine`. Each module is passed the shared `db` instance.
+
+-   **`eval_script(engine: &Engine, script: &str) -> Result<rhai::Dynamic, Box<rhai::EvalAltResult>>`**:
+    A utility function to directly evaluate a Rhai script string using the provided `engine`.
+
+-   **`compile_script(engine: &Engine, script: &str) -> Result<AST, Box<rhai::EvalAltResult>>`**:
+    Compiles a Rhai script string into an `AST` (Abstract Syntax Tree) for potentially faster repeated execution.
+
+-   **`run_ast(engine: &Engine, ast: &AST, scope: &mut Scope) -> Result<rhai::Dynamic, Box<rhai::EvalAltResult>>`**:
+    Runs a pre-compiled `AST` with a given `scope` using the provided `engine`.
+
+-   **`mock_db` module**:
+    Provides `create_mock_db()` which returns an `Arc<OurDB>` instance suitable for testing and examples. This allows scripts that interact with database functionalities to run without external database dependencies.
+
+### Basic Usage
+
+```rust
+use std::sync::Arc;
+use engine::{create_heromodels_engine, eval_script};
+use engine::mock_db::create_mock_db; // For example usage
+use heromodels::db::hero::OurDB; // Actual DB type
+
+// Create a mock database (or connect to a real one)
+let db: Arc<OurDB> = create_mock_db();
+
+// Create the Rhai engine with all enabled modules registered
+let engine = create_heromodels_engine(db);
+
+// Run a Rhai script
+let script = r#"
+    // Example: Assuming 'calendar' feature is enabled
+    let cal = new_calendar("My Test Calendar");
+    cal.set_description("This is a test.");
+    print(`Created calendar: ${cal.get_name()}`);
+    cal.get_id() // Return the ID
+"#;
+
+match eval_script(&engine, script) {
+    Ok(val) => println!("Script returned: {:?}", val),
+    Err(err) => eprintln!("Script error: {}", err),
+}
+```
+
+### Using Specific Modules Manually
+
+If you need more fine-grained control or only want specific modules (and prefer not to rely solely on feature flags at compile time for `create_heromodels_engine`), you can initialize an engine and register modules manually:
+
+```rust
+use std::sync::Arc;
+use rhai::Engine;
+use engine::mock_db::create_mock_db; // For example usage
+use heromodels::db::hero::OurDB;
+// Import the specific module registration function
+use heromodels::models::calendar::register_calendar_rhai_module;
+
+
+// Create a mock database
+let db: Arc<OurDB> = create_mock_db();
+
+// Create a new Rhai engine
+let mut engine = Engine::new();
+
+// Register only the calendar module
+register_calendar_rhai_module(&mut engine, db.clone());
+
+// Now you can use calendar-related functions in your scripts
+let result = engine.eval::<String>(r#" let c = new_calendar("Solo Cal"); c.get_name() "#);
+match result {
+    Ok(name) => println!("Calendar name: {}", name),
+    Err(err) => eprintln!("Error: {}", err),
+}
+```
+
+## Examples
+
+This crate includes several examples demonstrating how to use different HeroModels modules with Rhai. Each example typically requires its corresponding feature to be enabled.
+
+-   `calendar_example`: Working with calendars, events, and attendees (requires `calendar` feature).
+-   `flow_example`: Working with flows, steps, and signature requirements (requires `flow` feature).
+-   `finance_example`: Working with financial models (requires `finance` feature).
+-   *(Additional examples for `legal`, `projects`, `biz` would follow the same pattern if present).*
+
+To run an example (e.g., `calendar_example`):
+
+```bash
+cargo run --example calendar_example --features calendar
+```
+*(Note: Examples in `Cargo.toml` already specify `required-features`, so simply `cargo run --example calendar_example` might suffice if those features are part of the default set or already enabled.)*
+
+## Features
+
+The crate uses feature flags to control which HeroModels modules are compiled and registered:
+
+-   `calendar`: Enables the Calendar module.
+-   `finance`: Enables the Finance module.
+-   `flow`: Enables the Flow module.
+-   `legal`: Enables the Legal module.
+-   `projects`: Enables the Projects module.
+-   `biz`: Enables the Business module.
+
+The `default` features are `["calendar", "finance"]`. You can enable other modules by specifying them during the build or in your project's `Cargo.toml` if this `engine` crate is a dependency.
+
+## Dependencies
+
+Key dependencies include:
+-   `rhai`: The Rhai scripting engine.
+-   `heromodels`: Provides the core data models and database interaction logic, including the Rhai registration functions for each module.
+-   `heromodels_core`: Core utilities for HeroModels.
+-   `chrono`: For date/time utilities.
+-   `heromodels-derive`: Procedural macros used by HeroModels.
+
+## License
+
+This crate is part of the HeroModels project and shares its license.