[−][src]Crate hexavalent
Write HexChat plugins in Rust.
To create your plugin:
- Make a library crate with
crate-type = "cdylib"
. - Define a type, e.g.
struct MyPlugin
, to hold any state your plugin needs. - Implement the
Plugin
trait forMyPlugin
. - Call
export_plugin
with the typeMyPlugin
, its name, description, and version.
On Windows, it is recommended to add -C target-feature=+crt-static
to your RUSTFLAGS
,
for example in <project root>/.cargo/config
.
This ensures that your DLL does not dynamically import the MSVCRT.
Examples
The following is a port of HexChat's example "auto-op" plugin.
It will automatically OP everyone who joins (so don't try this if you're in a real channel!),
and can be toggled on and off with /autooptoggle
.
use std::cell::Cell; use hexavalent::{Plugin, PluginHandle, export_plugin}; use hexavalent::event::Event; use hexavalent::event::print::Join; use hexavalent::hook::{Eat, Priority}; struct AutoOpPlugin { enabled: Cell<bool>, } impl Default for AutoOpPlugin { fn default() -> Self { Self { enabled: Cell::new(true), } } } impl AutoOpPlugin { fn autooptoggle_cb(&self, ph: PluginHandle<'_, Self>, _words: &[&str]) -> Eat { if !self.enabled.get() { self.enabled.set(true); ph.print("Auto-Oping now enabled!"); } else { self.enabled.set(false); ph.print("Auto-Oping now disabled!"); } // eat this command so HexChat and other plugins can't process it Eat::All } fn join_cb(&self, ph: PluginHandle<'_, Self>, args: <Join as Event<'_>>::Args) -> Eat { let [nick, _channel, _host, _account] = args; if self.enabled.get() { // op ANYONE who joins ph.command(&format!("OP {}", nick)); } // don't eat this event, HexChat needs to see it Eat::None } } impl Plugin for AutoOpPlugin { fn init(&self, ph: PluginHandle<'_, Self>) { ph.hook_command( "AutoOpToggle", "Usage: AUTOOPTOGGLE, turns OFF/ON Auto-Oping", Priority::Normal, Self::autooptoggle_cb, ); ph.hook_print(Join, Priority::Normal, Self::join_cb); ph.print("AutoOpPlugin loaded successfully!"); } fn deinit(&self, ph: PluginHandle<'_, Self>) { ph.print("Unloading AutoOpPlugin..."); } } export_plugin!(AutoOpPlugin, "AutoOp", "Auto-Ops anyone who joins", "0.1");
Safety
In general, this library depends on HexChat invoking the plugin from only one thread. If that is not the case, this library provides no guarantees. (Although it is never explicitly stated that this is true, HexChat's plugin documentation says nothing of synchronization, and none of the example plugins have any. It also seems true in practice.)
In debug mode (specifically, when debug_assertions
is enabled), the current thread ID is checked every time the plugin is invoked,
which can help detect misbehavior.
Modules
context | Server/channel contexts. |
event | Print and server events. |
gui | Fake plugins. |
hook | Hook callbacks. |
info | Context info. |
list | Info lists. |
mode | Sending modes. |
pref | Global preferences. |
strip | String format stripping. |
Macros
export_plugin | Defines the necessary exports for HexChat to load your plugin. |
Structs
PluginHandle | Interacts with HexChat's plugin API. |
Traits
Plugin | Must be implemented by all HexChat plugins. |