postscriptum 0.1.1

Multi-interpreted-language scripting engine for Rust with Rhai and Python backends
Documentation
# postscriptum — Quickstart

`postscriptum` is a **multi-interpreted-language scripting engine for Rust**.
It lets you embed scripts in your application, keep interpreter state between
evaluations, and expose your own Rust functions callable from the scripts —
on **native** and **WASM** targets, with no Bevy dependency.

This guide walks through the core concepts and shows the patterns used by the
`pyopyo` demo app. For short, runnable programs see the [`examples/`](examples/)
directory (`basic_rhai`, `basic_python`, `thread_safe`).

---

## 1. The concept

Everything revolves around a few pieces:

- **`ScriptEngine`** — the core trait: `fn eval(&mut self, &str) -> Result<String>`.
  Each backend implements it and is **stateful**: variables set by one script
  persist across later evaluations of the same engine.
- **`EngineType`** — selects the backend: `Rhai | Python`.
- **`FunctionBundle`** — registers Rust functions so scripts can call them
  (`add_rhai_fn0..4`, `add_python_fn0..4`).
- **`ThreadSafeEngine`** — a `Clone` wrapper around
  `Arc<Mutex<Box<dyn ScriptEngine>>>` that makes engines shareable across
  threads (the Python engine is not `Send` by itself).

| Backend  | Native                | WASM                 |
| -------- | --------------------- | -------------------- |
| **Rhai** | rhai (pure Rust)      | rhai (pure Rust)     |
| **Python** | pyo3                | Pyodide (JS interop) |

---

## 2. Add the dependency

```bash
cargo add postscriptum
# or, from a workspace/path:
# postscriptum = { path = "postscriptum" }
```

---

## 3. Create an engine and evaluate a script

```rust
use postscriptum::{EngineType, get_engine};

let mut engine = get_engine(EngineType::Rhai);
let result = engine.eval("40 + 2")?;
assert_eq!(result, "42");
```

Python works the same way with `EngineType::Python`.

---

## 4. Expose Rust functions to scripts

Build a `FunctionBundle` for the language you want, add functions by arity, and
create an engine with the bundle registered:

```rust
use postscriptum::{EngineType, FunctionBundle, get_engine_with_bundle};

let mut bundle = FunctionBundle::new(EngineType::Rhai);
bundle.add_rhai_fn0::<fn() -> i64, i64>("get_answer", || 42);
bundle.add_rhai_fn1::<fn(i64) -> i64, i64, i64>("double", |x: i64| x * 2);
bundle.add_rhai_fn2::<fn(i64, i64) -> i64, i64, i64, i64>("add", |a: i64, b: i64| a + b);

let mut engine = get_engine_with_bundle(EngineType::Rhai, &bundle);
assert_eq!(engine.eval("double(get_answer())")?, "84");
```

For Python, use the matching `add_python_fn0..4` methods and `EngineType::Python`.

### Available arity adders

| Arity | Rhai                  | Python (native / wasm)   |
| ----- | --------------------- | ------------------------ |
| 0     | `add_rhai_fn0`        | `add_python_fn0`         |
| 1     | `add_rhai_fn1`        | `add_python_fn1`         |
| 2     | `add_rhai_fn2`        | `add_python_fn2`         |
| 3     | `add_rhai_fn3`        | `add_python_fn3`         |
| 4     | `add_rhai_fn4`        | `add_python_fn4`         |

### The functions the `pyopyo` demo registers

The demo app's `StandardFunctionBundle` registers the same set on both engines
and documents them in its UI. Use them as a template for your own:

| Function          | Signature                | Notes                          |
| ----------------- | ------------------------ | ------------------------------ |
| `get_pi()`        | `() -> f64`              | `std::f64::consts::PI`         |
| `get_answer()`    | `() -> i64`              | Always `42` 🙂                 |
| `square(x)`       | `(i64) -> i64`           | `x * x`                        |
| `double(x)`       | `(i64) -> i64`           | `x * 2`                        |
| `plusone(x)`      | `(i64) -> i64`           | `x + 1`                        |
| `multiply(a, b)`  | `(i64, i64) -> i64`      | `a * b`                        |
| `power(base, exp)`| `(f64, f64) -> f64`      | `base.powf(exp)`               |

Registering them looks like this (native, Python side):

```rust
let mut bundle = FunctionBundle::new_python();
bundle.add_python_fn0::<fn() -> f64, f64>("get_pi", || std::f64::consts::PI);
bundle.add_python_fn1::<fn(i64) -> i64, i64, i64>("double", |x: i64| x * 2);
bundle.add_python_fn2::<fn(f64, f64) -> f64, f64, f64, f64>(
    "power",
    |base: f64, exp: f64| base.powf(exp),
);
```

---

## 5. Scripts keep state between runs

An engine remembers its variables across evaluations. This is how the app runs
a counter: seed the value, then increment it per call:

```rust
let mut engine = get_engine(EngineType::Python);

assert_eq!(engine.eval("counter = 1\ncounter")?, "1");
assert_eq!(engine.eval("counter += 1\ncounter")?, "2");
assert_eq!(engine.eval("counter += 1\ncounter")?, "3");
```

> Note: Rhai needs a `let` for the first binding (`let counter = 1; counter`).

---

## 6. Share an engine across threads (`ThreadSafeEngine`)

To use an engine from multiple threads (e.g. inside Bevy's parallel systems),
wrap it in a `ThreadSafeEngine` and `clone()` the handle:

```rust
use postscriptum::{EngineType, ThreadSafeEngine, get_engine};

let engine = ThreadSafeEngine::new(get_engine(EngineType::Rhai));
engine.eval("let x = 0")?;

let handle = engine.clone();
std::thread::spawn(move || {
    handle.eval("x = x + 1; x").unwrap()
});
```

The `pyopyo` app goes one step further with an `EngineContextRegistry` that maps
script **names** to `ThreadSafeEngine`s, preserving per-script state:

```rust
// app-side pattern (pseudo-code)
registry.create_or_update_with_bundle("my_script", EngineType::Python, source, &python_bundle)?;
let result = registry.eval("my_script", "counter += 1\ncounter")?;
```

---

## 7. Native vs WASM

- **Rhai** runs everywhere (pure Rust).
- **Python** runs natively through `pyo3` (needs a Python interpreter available
  at link/runtime) and in the browser through **Pyodide** — the WASM path is
  compiled in automatically for `wasm32-unknown-unknown` targets.

Feature flags (see `Cargo.toml`): `rhai` (default), `python` (default),
`wasm-python`, `native-python`.

---

## 8. Examples

Run any example with the matching features enabled:

```bash
cargo run --example basic_rhai        # needs `rhai`
cargo run --example basic_python      # needs `python`
cargo run --example thread_safe       # needs `rhai`
```