# Модуль Rhai: `src/interpreter/rhei.rs`

Интеграция скриптового движка [Rhai](https://rhai.rs/) — компиляция, кеширование AST и выполнение выражений/скриптов.

---

## `RHEI_PREFIX` — префикс Rhai-выражений

```rust
pub const RHEI_PREFIX: &str = "__rhei:";
```

Константа-маркер для свойств элементов, содержимое которых должно интерпретироваться как Rhai-выражение. Используется в `collect_and_precompile()` для выборки свойств вида `!rhei:...`.

---

## `RheiContext` — контекст выполнения Rhai

```rust
pub struct RheiContext {
    engine: Engine,
    init_ast: AST,
    scope: RefCell<Scope<'static>>,
    action_cache: RefCell<HashMap<String, AST>>,
    expr_cache: RefCell<HashMap<String, AST>>,
}
```

| Поле | Назначение |
|---|---|
| `engine` | Настроенный экземпляр `rhai::Engine` |
| `init_ast` | Объединённое AST всех скриптов инициализации (включая определения функций) |
| `scope` | Общая область видимости (`Scope`), разделяемая между вызовами; обёрнута в `RefCell` для interior mutability |
| `action_cache` | Кеш скомпилированных скриптов (действий), ключ — исходный код |
| `expr_cache` | Кеш скомпилированных выражений, ключ — исходный код |

---

## Конструкторы

### `new(scripts)`

```rust
pub fn new(scripts: &[String]) -> Self
```

Создаёт контекст через `new_empty()` и сразу прекомпилирует все переданные скрипты вызовом `precompile_scripts()`.

### `new_empty(scripts)`

```rust
fn new_empty(scripts: &[String]) -> Self
```

1. Создаёт `Engine::new()`.
2. Настраивает обработчики `on_print` (вывод в stdout с префиксом `[rhei]`) и `on_debug` (вывод в stderr).
3. Компилирует все скрипты и сливает их AST в единое дерево через `merge()`. Ошибки компиляции отдельных блоков логируются, но не прерывают процесс.
4. Из объединённого AST создаёт модуль (`Module::eval_ast_as_new`) с пустым скопом — в нём регистрируются глобальные функции, определённые в скриптах. Модуль регистрируется в движке как глобальный (`register_global_module`).
5. Инициализирует пустой `Scope`, пустые кеши `action_cache` и `expr_cache`.

---

## `sync_scope()` — синхронизация переменных

```rust
pub fn sync_scope(&self, variables: &HashMap<String, Value>)
```

Синхронизирует значения из внешнего `HashMap` в Rhai `Scope`:
- Если переменная уже есть в скопе и её значение не изменилось — пропускает.
- Если переменная есть — обновляет через `set_value()`.
- Если переменной нет — добавляет через `push_dynamic()`.

Преобразование `Value → Dynamic` выполняется через `value_to_dynamic()`.

---

## `initialize()` — инициализация

```rust
pub fn initialize(&self, variables: &mut HashMap<String, Value>)
```

1. Синхронизирует переменные через `sync_scope()`.
2. Запускает `init_ast` (объединённое AST всех скриптов) через `run_ast_with_scope()`.
3. Обходит все переменные скопа через `iter_raw()` и записывает обратно в `HashMap` те, чьи значения изменились.

---

## `eval_expr()` — вычисление выражения

```rust
pub fn eval_expr(&self, expr: &str, variables: &HashMap<String, Value>) -> Value
```

1. Синхронизирует переменные.
2. Получает (компилирует или берёт из кеша) AST выражения через `get_or_compile_expr()`.
3. Выполняет через `eval_ast_with_scope::<Dynamic>()`.
4. Преобразует результат `Dynamic → Value` через `dynamic_to_value()`.
5. При ошибке возвращает `Value::None`.

---

## `eval_condition()` — вычисление условия

```rust
pub fn eval_condition(&self, expr: &str, variables: &HashMap<String, Value>) -> bool
```

Аналогичен `eval_expr()`, но типизирован как `bool`. При ошибке возвращает `false`.

---

## `execute_action()` — выполнение скрипта

```rust
pub fn execute_action(&self, script: &str, variables: &mut HashMap<String, Value>)
```

1. Синхронизирует переменные.
2. Получает AST скрипта через `get_or_compile_action()`.
3. Выполняет через `run_ast_with_scope()`.
4. После выполнения обходит скоп и записывает обратно в `HashMap` изменившиеся переменные.

---

## Кеширование AST

### `get_or_compile_action(script)`

```rust
fn get_or_compile_action(&self, script: &str) -> Option<AST>
```

Проверяет `action_cache`. При промахе компилирует через `engine.compile()`, сохраняет в кеш.

### `get_or_compile_expr(expr)`

```rust
fn get_or_compile_expr(&self, expr: &str) -> Option<AST>
```

Проверяет `expr_cache`. При промахе компилирует через `engine.compile_expression()`, сохраняет в кеш.

Оба метода при ошибке компиляции логируют её и возвращают `None`.

---

## Пакетная прекомпиляция

```rust
pub fn precompile_scripts(&self, scripts: &[String])
pub fn precompile_actions(&self, actions: &[String])
pub fn precompile_exprs(&self, exprs: &[String])
pub fn precompile_all_from_doc(&self, doc: &super::Document)
```

| Метод | Действие |
|---|---|
| `precompile_scripts` | Компилирует каждый скрипт как действие |
| `precompile_actions` | То же, что `precompile_scripts` (алиас) |
| `precompile_exprs` | Компилирует каждое выражение |
| `precompile_all_from_doc` | Компилирует все `doc.rhei_scripts` и рекурсивно обходит дерево элементов |

### `collect_and_precompile()`

```rust
fn collect_and_precompile(el: &super::Element, ctx: &RheiContext)
```

Рекурсивно обходит дерево `Element`:
- Для свойств, начинающихся с `__on:*` и непустых — компилирует как действие.
- Для свойств, начинающихся с `RHEI_PREFIX` (`!rhei:`) — компилирует оставшуюся часть как выражение.

---

## Конвертация типов

### `value_to_dynamic(v: &Value) -> Dynamic`

```rust
Value::Int(i)   → Dynamic::from(*i)
Value::Float(f) → Dynamic::from(*f)
Value::Bool(b)  → Dynamic::from(*b)
Value::Str(s)   → str_to_dynamic(s)
Value::None     → Dynamic::UNIT
Value::Array(a) → Dynamic::from_iter(value_to_dynamic каждого элемента)
```

### `dynamic_to_value(d: &Dynamic) -> Value`

Проверяет тип через `is_string()`, `is_int()`, `is_float()`, `is_bool()`, `is_array()` в порядке приоритета. Если тип не распознан — возвращает `Value::None`.

### `str_to_dynamic(s: &str) -> Dynamic`

Эвристический парсер строки, пробует последовательно:
1. `s.parse::<i64>()` — целое число
2. `s.parse::<f64>()` — дробное число
3. `s.parse::<bool>()` — булево значение
4. Иначе — `Dynamic::from(s)` как строка