[−][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 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::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.

[−][src]Crate hexavalent

Examples

Safety

Modules

Macros

Structs

Traits