Struct PluginEngine 

pub struct PluginEngine { /* private fields */ }

The v1 plugin engine: an embedded Lua interpreter with Trail’s hook API.

Holds a single mlua::Lua state shared across all loaded plugins. Callbacks are stored as mlua::RegistryKey values so they remain 'static while the Lua state is alive.

The hook API is intentionally minimal for v1 — resist expanding it until a real plugin author needs more (coding standard §13 / decision log).

Implementations

impl PluginEngine

pub fn new() -> Result<Self, PluginError>

Creates a new PluginEngine and installs the Trail Lua API surface.

Sets up the trail global table with on_select, on_enter_dir, register_action, and log functions for use by plugins.

Errors

Returns PluginError::Lua if the Lua state cannot be created or the API table cannot be installed.

pub fn load_plugin(&mut self, path: &Path) -> Result<(), PluginError>

Loads and executes a Lua plugin from path.

The plugin chunk runs once; any trail.* registration calls are captured and stored as registry keys.

Errors

Returns PluginError::Io if the file cannot be read, or PluginError::Lua if the chunk fails to compile or execute.

pub fn load_plugin_str( &mut self, name: &str, source: &str, ) -> Result<(), PluginError>

Loads a Lua plugin from a source string.

name is used as a debug label in error messages. This is the preferred path for embedded (built-in) plugins and unit tests.

Errors

Returns PluginError::Lua if the chunk fails to compile or execute.

pub fn fire_on_select(&self, path: &Path)

Fires all registered on_select hooks with the path of the selected entry.

Hook errors are logged at debug level and do not propagate.

pub fn fire_on_enter_dir(&self, dir: &Path)

Fires all registered on_enter_dir hooks with the entered directory path.

Hook errors are logged at debug level and do not propagate.

pub fn fire_action(&self, action_name: &str, arg: &str) -> bool

Calls the registered handler for action_name with arg.

Returns true if an action with that name was found and called, false if no plugin registered it. Handler errors are logged at debug level and do not propagate.

pub fn action_names(&self) -> impl Iterator<Item = &str>

Returns an iterator over the names of all registered custom actions.

Used by the command parser to offer tab-completion for plugin actions.

pub fn is_empty(&self) -> bool

Returns true if no plugins have registered any hooks or actions.

Trait Implementations

impl Debug for PluginEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.