Crate gravityfile_plugin

Expand description

§gravityfile-plugin

Lua plugins for gravityfile.

This crate exists for the grav binary and its sibling crates. Its API follows their needs and can change in any minor release. Writing plugins is documented in the plugin guide.

Plugins are Lua scripts that subscribe to Hooks (startup, navigation, scan completion, deletion, …). The PluginManager dispatches hooks to a PluginRuntime; in the application that runtime is a ProcessRuntime, which runs each plugin in its own supervised worker process with deadlines and bounded IPC, so a misbehaving plugin cannot block or crash the host. lua::LuaRuntime is the in-process engine the worker uses, with a memory limit, an instruction-count deadline and a sandboxed standard library.

A hook result can show notices in the status line, and can veto the default action (currently deletion) through prevent_default:

return {
  on_delete_start = function(self, hook, ctx)
    for _, path in ipairs(hook.items) do
      if path:match("/%.git$") then
        gf.notify("Not deleting " .. path, "error")
        return { prevent_default = true }
      end
    end
  end,
}

§Licence

MIT or Apache-2.0, at your option.

Modules§

lua: Lua plugin runtime implementation.

Structs§

HookContext: Context provided to plugins when a hook is invoked.
HookResult: Result returned by a plugin hook handler.
Notice: A message a plugin asked the explorer to show, with gf.notify.
PluginConfig: Global plugin system configuration.
PluginHandle: A handle to a loaded plugin.
PluginManager: Manager for all plugin runtimes and loaded plugins.
PluginMetadata: Metadata about a plugin from its plugin.toml file.
ProcessRuntime: Persistent, independently supervised worker process for each loaded plugin. The executable must implement the hidden __plugin-worker LANGUAGE entrypoint.
SandboxConfig: Configuration for plugin sandboxing.

Enums§

Hook: Events that plugins can hook into.
NoticeLevel: How prominent a plugin’s notice is.
Permission: Permission types that can be granted to plugins.
PluginError: Errors that can occur in the plugin system.
PluginKind: Categories of plugins.
Value: A dynamic value that can be passed between Rust and plugin runtimes.

Traits§

IsolatedContext: An isolated execution context for running plugin code safely.
PluginRuntime: Trait that all plugin runtime implementations must satisfy.

Functions§

run_worker: Serve the private framed protocol. Call before initializing CLI logging or printing anything to stdout. Not an authenticated external service.

Type Aliases§

PluginResult: Result type for plugin operations.