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 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.

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.
• str
  Conversion to and from C strings.
• 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.