hexavalent

Write HexChat plugins in Rust.

Read the docs or see the examples directory to get started.

Why the name?

"Hex" from HexChat, of course. "Hexavalent" because CrO₃ looks similar to Fe₂O₃.

...and hexavalent chromium is unsafe to handle, much like HexChat's API.

lib.rs:

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 for MyPlugin.
• Call export_plugin with the type MyPlugin, 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::print::Join;
use hexavalent::hook::{Eat, Priority};
use hexavalent::str::HexStr;

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: &[&HexStr]) -> 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: [&HexStr; 4]) -> 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.