Struct hexchat_unsafe_plugin::PluginHandle

pub struct PluginHandle<'ph> { /* private fields */ }

A hexchat plugin handle, used to register hooks and interact with hexchat.

Examples

use hexchat_unsafe_plugin::{PluginHandle};

fn init(ph: &mut PluginHandle) {
    ph.register("myplug", "0.1.0", "my awesome plug");
}

Implementations

impl<'ph> PluginHandle<'ph>

pub fn register(&mut self, name: &str, desc: &str, ver: &str)

Registers this hexchat plugin. This must be called exactly once when the plugin is loaded.

Panics

This function panics if this plugin is already registered.

Examples

use hexchat_unsafe_plugin::PluginHandle;

fn init(ph: &mut PluginHandle<'_>) {
    ph.register("foo", "0.1.0", "my foo plugin");
}

pub fn get_name(&self) -> &str

Returns this plugin’s registered name.

Panics

This function panics if this plugin is not registered.

pub fn get_description(&self) -> &str

Returns this plugin’s registered description.

Panics

This function panics if this plugin is not registered.

pub fn get_version(&self) -> &str

Returns this plugin’s registered version.

Panics

This function panics if this plugin is not registered.

pub fn ensure_valid_context<F, R>(&mut self, f: F) -> R where
    F: for<'a> FnOnce(ValidContext<'a, 'ph>) -> R, 

Ensures the current context is valid.

Panics

This function may panic if it’s called while hexchat is closing.

pub fn for_entry_mut<F, R>(
    &mut self,
    entry: &mut PluginEntryHandle<'ph>,
    f: F
) -> R where
    F: FnOnce(&mut PluginHandle<'ph>) -> R, 

Operates on a virtual plugin.

Examples

use hexchat_unsafe_plugin::{PluginHandle};

fn contexts_can_be_passed_around(ph: &mut PluginHandle<'_>) {
    let ctx = ph.get_context();
    let mut vplug = ph.plugingui_add("foo", "bar", "baz", "qux");
    ph.for_entry_mut(&mut vplug, |ph| {
        ph.set_context(&ctx);
        ph.get_context()
    });
}

pub fn plugingui_add(
    &self,
    filename: &str,
    name: &str,
    description: &str,
    version: &str
) -> PluginEntryHandle<'ph>

Registers a virtual plugin.

pub fn get_context(&self) -> Context<'ph>

Returns the current context.

Note: The returned context may be invalid. Use Self::set_context to check.

pub fn set_context(&mut self, ctx: &Context<'ph>) -> bool

Sets the current context.

Returns true if the context is valid, false otherwise.

pub fn with_context<F, R>(
    &mut self,
    ctx: &Context<'ph>,
    f: F
) -> Result<R, InvalidContextError<F>> where
    F: for<'a> FnOnce(ValidContext<'a, 'ph>) -> R, 

Do something in a valid context.

Note that this changes the active context and doesn’t change it back (but that should be fine for most use-cases).

Errors

Returns Err(InvalidContextError(f)) if the context is invalid. See set_context. Otherwise, returns Ok(f(...)).

Note that InvalidContextError contains the original closure. This allows you to retry, if you so wish.

pub fn hook_command<'f, F>(
    &self,
    cmd: &str,
    pri: i32,
    help: Option<&str>,
    cb: F
) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>, Word<'_>, WordEol<'_>) -> Eat + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a command hook.

Panics

Panics if this is a borrowed PluginEntryHandle.

Examples

use hexchat_unsafe_plugin::{PluginHandle, HookHandle};

fn register_commands<'ph>(ph: &mut PluginHandle<'ph>) -> Vec<HookHandle<'ph, 'ph>> {
    vec![
    ph.hook_command("hello-world", hexchat_unsafe_plugin::PRI_NORM, Some("prints 'Hello, World!'"), |ph, arg, arg_eol| {
        ph.print("Hello, World!");
        hexchat_unsafe_plugin::EAT_ALL
    }),
    ]
}

pub fn hook_server<'f, F>(
    &self,
    cmd: &str,
    pri: i32,
    cb: F
) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>, Word<'_>, WordEol<'_>) -> Eat + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a server hook.

Examples

use hexchat_unsafe_plugin::{PluginHandle, HookHandle};

fn register_server_hooks<'ph>(ph: &mut PluginHandle<'ph>) -> Vec<HookHandle<'ph, 'ph>> {
    vec![
    ph.hook_server("PRIVMSG", hexchat_unsafe_plugin::PRI_NORM, |ph, word, word_eol| {
        if word.len() > 0 && word[0].starts_with('@') {
            ph.print("We have message tags!?");
        }
        hexchat_unsafe_plugin::EAT_NONE
    }),
    ]
}

pub fn hook_server_attrs<'f, F>(
    &self,
    cmd: &str,
    pri: i32,
    cb: F
) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>, Word<'_>, WordEol<'_>, EventAttrs<'_>) -> Eat + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a server hook, with attributes.

pub fn hook_print<'f, F>(
    &self,
    name: &str,
    pri: i32,
    cb: F
) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>, Word<'_>) -> Eat + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a print hook.

Examples

use hexchat_unsafe_plugin::{PluginHandle, HookHandle};

fn register_print_hooks<'ph>(ph: &mut PluginHandle<'ph>) -> Vec<HookHandle<'ph, 'ph>> {
    vec![
    ph.hook_print("Channel Message", hexchat_unsafe_plugin::PRI_NORM, |ph, arg| {
        if let Some(nick) = arg.get(0) {
            if *nick == "KnOwN_SpAmMeR" {
                return hexchat_unsafe_plugin::EAT_ALL
            }
        }
        hexchat_unsafe_plugin::EAT_NONE
    }),
    ]
}

pub fn hook_print_attrs<'f, F>(
    &self,
    name: &str,
    pri: i32,
    cb: F
) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>, Word<'_>, EventAttrs<'_>) -> Eat + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a print hook, with attributes.

Examples

use hexchat_unsafe_plugin::{PluginHandle, HookHandle};

fn register_print_hooks<'ph>(ph: &mut PluginHandle<'ph>) -> Vec<HookHandle<'ph, 'ph>> {
    vec![
    ph.hook_print_attrs("Channel Message", hexchat_unsafe_plugin::PRI_NORM, |ph, arg, attrs| {
        if let Some(nick) = arg.get(0) {
            if *nick == "KnOwN_SpAmMeR" {
                return hexchat_unsafe_plugin::EAT_ALL
            }
        }
        hexchat_unsafe_plugin::EAT_NONE
    }),
    ]
}

pub fn hook_timer<'f, F>(&self, timeout: i32, cb: F) -> HookHandle<'ph, 'f> where
    F: Fn(&mut PluginHandle<'ph>) -> bool + 'f + RefUnwindSafe,
    'f: 'ph, 

Sets a timer hook

Examples

use hexchat_unsafe_plugin::{PluginHandle, HookHandle};

fn register_timers<'ph>(ph: &mut PluginHandle<'ph>) -> Vec<HookHandle<'ph, 'ph>> {
    vec![
    ph.hook_timer(2000, |ph| {
        ph.print("timer up!");
        false
    }),
    ]
}

pub fn print<T: ToString>(&self, s: T)

Prints to the hexchat buffer.

pub fn write_fmt(&self, fmt: Arguments<'_>)

Prints to this hexchat buffer.

Glue for usage of the write! macro with hexchat.

Panics

This panics if any broken formatting trait implementations are used in the format arguments. See also format!.

Examples

use hexchat_unsafe_plugin::PluginHandle;

fn hello_world(ph: &mut PluginHandle<'_>) {
    write!(ph, "Hello, world!");
}

pub fn get_info<'a>(&'a self, id: InfoId<'_>) -> Option<Cow<'a, str>>

Returns context and client information.

See InfoId for the kinds of information that can be retrieved.

Examples

use hexchat_unsafe_plugin::{InfoId, PluginHandle};

/// Returns whether we are currently away.
fn is_away(ph: &mut PluginHandle<'_>) -> bool {
    ph.get_info(InfoId::Away).is_some()
}

pub fn get_libdirfs(&self) -> Option<CString>

Returns the path to the plugin directory, used for auto-loading plugins.

The returned CStr is not guaranteed to be valid UTF-8, but local file system encoding.

Examples

use std::path::PathBuf;

use hexchat_unsafe_plugin::PluginHandle;

// On Unix, we can treat this as an array-of-bytes filesystem path.
#[cfg(unix)]
fn plugin_dir(ph: &PluginHandle<'_>) -> PathBuf {
    use std::ffi::OsString;
    use std::os::unix::ffi::OsStringExt;

    let libdirfs = ph.get_libdirfs().expect("should exist");
    OsString::from_vec(libdirfs.into_bytes()).into()
}

pub fn strip(&self, s: &str, strip: Strip) -> String

Strips attributes from text. See Strip for which attributes can be stripped.

Examples

use hexchat_unsafe_plugin::{PluginHandle, Strip};

/// Removes colors
fn strip_colors(ph: &PluginHandle<'_>, s: &str) -> String {
    ph.strip(s, Strip::new().colors(true))
}