hexchat_unsafe_plugin/

lib.rs

// Hexchat Plugin API Bindings for Rust
// Copyright (C) 2018, 2021, 2022 Soni L.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Write hexchat plugins in Rust!
//!
//! This library provides safe API bindings for hexchat, but doesn't attempt to fix hexchat's own
//! bugs. It makes no effort to stop you from unloading your own code while it's still running, for
//! example.
//!
//! When using this library, it's strongly recommended to avoid heap-allocated statics (static
//! mutexes, lazy_static, etc). This is because it's currently impossible to deallocate those on
//! plugin unload. This can be worked around by placing those statics as fields in your plugin
//! struct.
//!
//! This caveat does not apply to static assets (`static FOO: &'static str`, for example), but it
//! does apply to thread-local storage.
//!
//! # Panics
//!
//! Unless otherwise stated, all functions in this crate taking strings (be
//! that `&str`, `String`, etc) panic when the string contains embedded `NUL`
//! characters (`\0`).
//! 
//! # Examples
//!
//! ```no_run
//! #[macro_use]
//! extern crate hexchat_unsafe_plugin;
//!
//! use std::pin::Pin;
//! use std::sync::Mutex;
//! use hexchat_unsafe_plugin::{Plugin, PluginHandle, HookHandle};
//!
//! #[derive(Default)]
//! struct MyPlugin<'ph> {
//!     cmd: Mutex<Option<HookHandle<'ph, 'ph>>>
//! }
//!
//! unsafe impl<'ph> Plugin<'ph> for MyPlugin<'ph> {
//!     fn init(self: Pin<&mut Self>, ph: &mut PluginHandle<'ph>, filename: &str, arg: Option<&str>) -> bool {
//!         ph.register("myplugin", "0.1.0", "my simple plugin");
//!         *self.cmd.lock().unwrap() = Some(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
//!         }));
//!         true
//!     }
//! }
//!
//! hexchat_plugin!('ph, MyPlugin<'ph>);
//!
//! # fn main() { } // satisfy the compiler, we can't actually run the code
//! ```

/*
 * Some info about how HexChat does things:
 *
 * All strings passed across the C API are UTF-8.
 * - Except `hexchat_get_info(ph, "libdirfs")`, so we need to be careful with
 *     that one.
 *
 * The pointers
 * `name: *mut *const char, desc: *mut *const char, vers: *mut *const char`
 * point to inside the ph - that is, they're aliased. Thus, we must never
 * convert a ph to an & or &mut except as part of retrieving or setting values
 * in it (e.g. `(*ph).hexchat_get_info` or `(*ph).userdata = value`).
 *
 * `hexchat_plugin_get_info` is never used, so we omit it. It would be
 * impractical not to.
 *
 * These cause UB:
 * - `hexchat_command` may invalidate the plugin context.
 * - `hexchat_find_context` and `hexchat_nickcmp` use the plugin context
 *     without checking it.
 * - `hexchat_get_prefs` uses the plugin context if name == "state_cursor" or
 *     "id" (or anything with the same hash).
 * - `hexchat_list_get` uses the plugin context if name == "notify" (or
 *     anything with the same hash).
 * - `hexchat_list_str`, `hexchat_list_int`, 
 * - `hexchat_emit_print`, `hexchat_emit_print_attrs` use the plugin context.
 * - `hexchat_send_modes` uses the plugin context.
 * We need to wrap them (or, alternatively, hexchat_command). However, there's
 * no (safe) way to get a valid context afterwards.
 * - Actually that's a lie. Hexchat does a trick to give you a context as part
 *     of the channel list.
 *     We can use that to our advantage. I'm not sure if it's better to wrap
 *     hexchat_command or the other functions, tho.
 *     (Do we want to walk a linked list every time we use hexchat_command?
 *     I'd think hexchat_command is the most used API function... Plus,
 *     emit_print could indirectly invalidate the context as well.)
 *
 * `hexchat_send_modes` should only be used with channels; however, it doesn't
 * cause UB - it just doesn't work.
 *
 * `hexchat_pluginpref_get_int`, `hexchat_pluginpref_get_str`,
 * `hexchat_pluginpref_set_int`, `hexchat_pluginpref_set_str` cannot be used
 * while `name`, `desc`, `vers` are null.
 *
 * `hexchat_plugin_init` receives an arg string. it may be null. this isn't
 * documented anywhere.
 *
 * We can add the "close context" hook as the first thing when registering a
 * plugin, and invalidate known contexts from it. this is because hexchat
 * always adds new hooks with the same priority before old hooks.
 *
 * Borrowing can be scary. Things that can invalidate borrows must be &mut, but
 * borrows by themselves are generally fine. Unless they're not.
 *
 * Some get_info calls may be unsound on some platforms when threads are
 * involved, as they use getenv. This should be fixed by libc. We still need to
 * copy them into a String/CString.
 */

/*
 * Some info about how we do things:
 *
 * DO NOT CALL printf/commandf/etc FAMILY OF FUNCTIONS. You can't avoid allocations, so just
 * allocate some CStrings on the Rust side. It has the exact same effect, since those functions
 * allocate internally anyway.
 */

/*
 * Big list o' TODO:
 * -[ ] Finish API support. [PRI-HIGH]
 *     -[x] word
 *     -[x] word_eol
 *     -[x] HEXCHAT_PRI_{HIGHEST, HIGH, NORM, LOW, LOWEST}
 *     -[x] HEXCHAT_EAT_{NONE, HEXCHAT, PLUGIN, ALL}
 *     -[ ] HEXCHAT_FD_{READ, WRITE, EXCEPTION, NOTSOCKET}
 *     -[x] hexchat_command (for commandf, use command(&format!("...")), it is equivalent.)
 *     -[x] hexchat_print (for printf, use print(&format!("...")), it is equivalent.)
 *     -[x] hexchat_emit_print
 *     -[x] hexchat_emit_print_attrs
 *     -[x] hexchat_send_modes
 *     -[x] hexchat_nickcmp
 *     -[x] hexchat_strip
 *     -[x] ~~hexchat_free~~ not available - use Drop impls.
 *     -[x] ~~hexchat_event_attrs_create~~ not available - converted as needed
 *     -[x] ~~hexchat_event_attrs_free~~ not available - use Drop impls.
 *     -[#] hexchat_get_info (with the below as separate methods)
 *         -[x] libdirfs
 *         -[ ] gtkwin_ptr
 *         -[ ] win_ptr
 *     -[x] hexchat_get_prefs
 *     -[x] hexchat_list_get
 *     -[x] ~~hexchat_list_fields~~ not available. no alternative provided.
 *     -[x] hexchat_list_next
 *     -[x] hexchat_list_str
 *     -[x] hexchat_list_int
 *     -[ ] hexchat_list_time
 *     -[x] ~~hexchat_list_free~~ not available - use Drop impls.
 *     -[x] hexchat_hook_command
 *     -[ ] hexchat_hook_fd
 *     -[x] hexchat_hook_print
 *     -[x] hexchat_hook_print_attrs
 *     -[#] hexchat_hook_server (implemented through _attrs)
 *     -[x] hexchat_hook_server_attrs
 *     -[x] hexchat_hook_timer
 *     -[x] ~~hexchat_unhook~~ not available - use Drop impls
 *     -[x] hexchat_find_context
 *     -[x] hexchat_get_context
 *     -[x] hexchat_set_context
 *     -[x] hexchat_pluginpref_set_str
 *     -[x] hexchat_pluginpref_get_str
 *     -[x] ~~hexchat_pluginpref_set_int~~ not available - use `format!`
 *     -[x] ~~hexchat_pluginpref_get_int~~ not available - use `str::parse`
 *     -[x] hexchat_pluginpref_delete
 *     -[x] hexchat_pluginpref_list
 *     -[x] hexchat_plugingui_add
 *     -[x] ~~hexchat_plugingui_remove~~ not available - use Drop impls.
 * -[x] Wrap contexts within something we keep track of. Mark them invalid when contexts are
 *     closed.
 * -[x] Anchor closures on the stack using Rc<T>. Many (most?) hooks are reentrant. As far as I
 *     know, all of them need this.
 *     -[x] Additionally, use a Cell<bool> for timers.
 * -[ ] ???
 */

#![cfg_attr(feature="nightly_tests", feature(c_variadic))]

#[macro_use]
extern crate impl_trait;
#[doc(hidden)]
pub extern crate libc;

// private macros

/// Calls a function on a PluginHandle struct.
macro_rules! ph_call {
    ($f:ident($ph:expr, $($args:expr),*)) => {
        ((*$ph.data.ph).$f)($ph.plugin, $($args),*)
    };
    ($f:ident($ph:expr $(,)?)) => {
        ((*$ph.data.ph).$f)($ph.plugin)
    };
}

mod eat;
mod extra_tests;
mod infoid;
mod internals;
pub mod list;
#[doc(hidden)]
#[cfg(feature="nightly_tests")]
pub mod mock;
mod pluginfo;
mod strip;
mod word;

pub use eat::*;
pub use infoid::InfoId;
pub use strip::*;
pub use word::*;

use internals::HexchatEventAttrs as RawAttrs;
use internals::Ph as RawPh;
use pluginfo::PluginInfo;

use std::borrow::Cow;
use std::cell::Cell;
use std::cell::RefCell;
use std::collections::HashSet;
use std::convert::TryInto;
use std::ffi::{CString, CStr};
use std::fmt;
use std::marker::PhantomData;
use std::mem;
use std::mem::ManuallyDrop;
use std::mem::MaybeUninit;
use std::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe, catch_unwind};
use std::pin::Pin;
use std::ptr;
use std::rc::Rc;
use std::rc::Weak as RcWeak;
use std::str::FromStr;
use std::thread;
use std::time::{SystemTime, UNIX_EPOCH, Duration};

#[doc(hidden)]
pub use libc::{c_char, c_int, c_void, time_t};

// ****** //
// PUBLIC //
// ****** //

// Consts

// PRI_*
/// Equivalent to HEXCHAT_PRI_HIGHEST
pub const PRI_HIGHEST: i32 = 127;
/// Equivalent to HEXCHAT_PRI_HIGH
pub const PRI_HIGH: i32 = 64;
/// Equivalent to HEXCHAT_PRI_NORM
pub const PRI_NORM: i32 = 0;
/// Equivalent to HEXCHAT_PRI_LOW
pub const PRI_LOW: i32 = -64;
/// Equivalent to HEXCHAT_PRI_LOWEST
pub const PRI_LOWEST: i32 = -128;

// Traits

/// A hexchat plugin.
///
/// # Safety
///
/// Modern operating systems cannot deal with dynamic unloading when threads
/// are involved, because we still haven't figured out how to track which code
/// address started a syscall that spawned a thread for some reason, so there's
/// no way for the dynamic loader to stop those threads when unloading.
///
/// *Fortunately* we can just shift that responsibility onto the unsuspecting
/// Rust user. Because Rust is a safe language, this makes writing plugins
/// inherently unsafe!
///
/// At least Unsafe Rust is still safer than writing C. So you have that going.
///
/// TL;DR: Either don't use threads, or ensure they're dead in `Drop`/`deinit`.
pub unsafe trait Plugin<'ph> {
    /// Called to initialize the plugin.
    fn init(self: Pin<&mut Self>, ph: &mut PluginHandle<'ph>, filename: &str, arg: Option<&str>) -> bool;

    /// Called to deinitialize the plugin.
    ///
    /// This is always called immediately prior to Drop::drop.
    ///
    /// # A note about unwinding
    ///
    /// Panics in deinit will prevent the plugin from being correctly unloaded!
    /// Be careful!
    fn deinit(self: Pin<&mut Self>, ph: &mut PluginHandle<'ph>) {
        let _ = ph;
    }
}

// Structs

/// A `*mut RawPh` with a lifetime bolted to it.
///
/// This allows us to enforce a non-`'static` lifetime on the `Plugin`.
// this is NOT public API
#[doc(hidden)]
#[repr(transparent)]
#[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Eq, Ord, Hash)]
pub struct LtPhPtr<'ph> {
    ph: *mut RawPh,
    // 'ph has to be invariant because RawPh is self-referential.
    // "ideally" we'd want `&'ph mut RawPh<'ph>`, tho the `*mut` above would've
    // had the same effect if `RawPh` were `RawPh<'ph>`.
    _lt: PhantomData<fn(&'ph ()) -> &'ph ()>,
}

/// A hexchat plugin handle, used to register hooks and interact with hexchat.
///
/// # Examples
///
/// ```no_run
/// use hexchat_unsafe_plugin::{PluginHandle};
///
/// fn init(ph: &mut PluginHandle) {
///     ph.register("myplug", "0.1.0", "my awesome plug");
/// }
/// ```
pub struct PluginHandle<'ph> {
    data: LtPhPtr<'ph>,
    plugin: *mut RawPh,
    contexts: Contexts,
    // Used for registration
    info: PluginInfo,
}

/// A setting value, returned by [`ValidContext::get_prefs`].
#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Debug)]
pub enum PrefValue {
    String(String),
    Int(i32),
    Bool(bool),
}

mod valid_context {
    use std::ptr;

    use crate::list;
    use crate::PluginHandle;

    /// A `PluginHandle` operating on a valid context.
    ///
    /// Methods that require a valid plugin context are only available through
    /// this. Methods that may invalidate the plugin context also consume this.
    ///
    /// See also [`PluginHandle::ensure_valid_context`].
    pub struct ValidContext<'a, 'ph: 'a> {
        // NOTE: NOT mut(!)
        pub(crate) ph: &'a PluginHandle<'ph>,
        fields: list::Fields<'a, 'ph, list::Contexts>,
        _hidden: (),
    }

    impl<'a, 'ph: 'a> ValidContext<'a, 'ph> {
        /// Wraps a PluginHandle in a ValidContext.
        ///
        /// # Safety
        ///
        /// The PluginHandle's context must be valid.
        pub(crate) unsafe fn new(ph: &'a mut PluginHandle<'ph>) -> Self {
            static CONTEXTS: list::Contexts = list::Contexts;
            Self {
                ph: &*ph,
                fields: list::Fields {
                    context: &*ph,
                    // this isn't actually documented but hexchat explicitly
                    // supports passing in NULL for the current context.
                    // this gives access to some properties that aren't
                    // available through get_info.
                    list: ptr::null_mut(),
                    _t: &CONTEXTS,
                },
                _hidden: (),
            }
        }
    }

    impl<'a, 'ph: 'a> std::ops::Deref for ValidContext<'a, 'ph> {
        type Target = list::Fields<'a, 'ph, list::Contexts>;
        fn deref(&self) -> &Self::Target {
            &self.fields
        }
    }
}
pub use valid_context::ValidContext;

/// Event attributes.
// TODO better docs.
#[derive(Clone)]
pub struct EventAttrs<'a> {
    /// Server time.
    #[deprecated(since="2.3.0", note="Use raw_server_time instead")]
    pub server_time: Option<SystemTime>,
    /// Raw server time. Only does anything if `use_raw_server_time` is set.
    pub raw_server_time: libc::time_t,
    /// Whether to pass `server_time` or `raw_server_time` to hexchat.
    pub use_raw_server_time: bool,
    _dummy: PhantomData<&'a ()>,
}

/// A hook handle.
///
/// Likes to get caught on stuff. Unhooks when dropped.
#[must_use = "Hooks must be stored somewhere and are automatically unhooked on Drop"]
pub struct HookHandle<'ph, 'f> where 'f: 'ph {
    ph: LtPhPtr<'ph>,
    hh: *const internals::HexchatHook,
    freed: Rc<Cell<bool>>,
    // this does actually store an Rc<...>, but on the other side of the FFI.
    _f: PhantomData<Rc<HookUd<'f>>>,
}

/// A virtual plugin.
#[must_use = "Virtual plugins must be stored somewhere and are automatically unregistered on Drop"]
pub struct PluginEntryHandle<'ph> {
    ph: LtPhPtr<'ph>,
    entry: *const internals::PluginGuiHandle,
}

/// A context.
#[derive(Clone)]
pub struct Context<'ph> {
    contexts: Contexts,
    ctx: RcWeak<*const internals::HexchatContext>,
    _ph: PhantomData<&'ph RawPh>,
}

/// The error returned by [`PluginHandle::with_context`] when the context is
/// not valid.
// #[derive(Debug)] // doesn't work
pub struct InvalidContextError<F>(F);

/// An iterable list of plugin pref names.
pub struct PluginPrefList {
    inner: Vec<u8>,
}

/// An iterator over `PluginPrefList`.
pub struct PluginPrefListIter<'a> {
    list: Option<&'a [u8]>,
}

// Enums

/// Errors returned by `pluginpref_*` functions.
#[derive(Debug)]
pub enum PluginPrefError {
    /// The var contains a forbidden character: `[ ,=\n]` (space, comma,
    /// equals, newline), is too long (max 126 bytes), is empty, or contains
    /// trailing ASCII whitespace.
    ///
    /// Returned by anything that interacts with vars. `pluginpref_list` only
    /// returns these during iteration.
    InvalidVar,
    /// The value starts with space.
    ///
    /// Returned by `pluginpref_set`.
    InvalidValue,
    /// The input (var + value) was too long after encoding.
    ///
    /// Returned by `pluginpref_set`.
    TooLong,
    /// The returned value was not valid UTF-8.
    ///
    /// Returned by `pluginpref_get`.
    Utf8Error(::std::ffi::IntoStringError),
    /// The returned var was not valid UTF-8.
    ///
    /// Returned while iterating a `pluginpref_list`.
    VarUtf8Error(::std::str::Utf8Error),
    /// The operation failed.
    ///
    /// Returned by anything that interacts with pluginprefs. Iterating a
    /// `pluginpref_list` never returns this.
    Failed,
}

// ***** //
// impls //
// ***** //

impl<'a> Iterator for PluginPrefListIter<'a> {
    type Item = Result<&'a str, PluginPrefError>;

    fn next(&mut self) -> Option<Self::Item> {
        let mut splitter = self.list?.splitn(2, |x| *x == 0);
        let ret = splitter.next().unwrap();
        let ret = test_pluginpref_var(ret).and_then(|_| {
            std::str::from_utf8(ret).map_err(|e| PluginPrefError::VarUtf8Error(e))
        });
        self.list = splitter.next();
        Some(ret)
    }
}

impl<'a> IntoIterator for &'a PluginPrefList {
    type Item = Result<&'a str, PluginPrefError>;

    type IntoIter = PluginPrefListIter<'a>;

    fn into_iter(self) -> Self::IntoIter {
        PluginPrefListIter {
            list: self.inner.split_last().map(|(_, x)| x),
        }
    }
}

impl<F> InvalidContextError<F> {
    /// Returns the closure wrapped within this error.
    pub fn get_closure(self) -> F {
        self.0
    }
}

impl_trait! {
    impl PrefValue {
        /// Projects this `PrefValue` as `&str`, if it is a `String`. Returns
        /// `None` otherwise.
        pub fn as_str(&self) -> Option<&str> {
            match self {
                &Self::String(ref s) => Some(s),
                _ => None,
            }
        }

        /// Projects this `PrefValue` as `i32`, if it is an `Int`. Returns
        /// `None` otherwise.
        pub fn as_i32(&self) -> Option<i32> {
            match self {
                &Self::Int(i) => Some(i),
                _ => None,
            }
        }

        /// Projects this `PrefValue` as `bool`, if it is a `Bool`. Returns
        /// `None` otherwise.
        pub fn as_bool(&self) -> Option<bool> {
            match self {
                &Self::Bool(b) => Some(b),
                _ => None,
            }
        }

        /// Consumes this `PrefValue` and attempts to take a `String` out of
        /// it.
        pub fn into_string(self) -> Option<String> {
            match self {
                Self::String(s) => Some(s),
                _ => None,
            }
        }

        impl trait From<String> {
            fn from(s: String) -> Self {
                Self::String(s)
            }
        }
        impl trait From<i32> {
            fn from(i: i32) -> Self {
                Self::Int(i)
            }
        }
        impl trait From<bool> {
            fn from(b: bool) -> Self {
                Self::Bool(b)
            }
        }
    }
}

impl<'ph, 'f> HookHandle<'ph, 'f> where 'f: 'ph {
    /// If this is a timer hook, returns whether the hook has expired.
    ///
    /// Otherwise, returns false.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::{HookHandle};
    ///
    /// /// Remove timers that have expired.
    /// fn clean_up_timers(timers: &mut Vec<HookHandle<'_, '_>>) {
    ///     timers.retain(|timer| {
    ///         !timer.expired()
    ///     });
    /// }
    /// ```
    pub fn expired(&self) -> bool {
        self.freed.get()
    }
}

impl<'ph, 'f> Drop for HookHandle<'ph, 'f> where 'f: 'ph {
    fn drop(&mut self) {
        if self.freed.get() {
            // already free'd.
            return;
        }
        self.freed.set(true);
        unsafe {
            let b = ((*self.ph.ph).hexchat_unhook)(self.ph.ph, self.hh) as *mut HookUd<'f>;
            // we assume b is not null. this should be safe.
            // just drop it
            drop(Rc::from_raw(b));
        }
    }
}

impl<'ph> Drop for PluginEntryHandle<'ph> {
    fn drop(&mut self) {
        unsafe {
            ((*self.ph.ph).hexchat_plugingui_remove)(self.ph.ph, self.entry);
        }
    }
}

impl_trait! {
    impl<'ph> Context<'ph> {
        impl trait UnwindSafe {}
        impl trait RefUnwindSafe {}
        impl trait Drop {
            fn drop(&mut self) {
                // check if we need to clean anything up
                if self.ctx.strong_count() == 1 && self.ctx.weak_count() == 1 {
                    let strong = self.ctx.upgrade().unwrap();
                    self.contexts.borrow_mut().remove(&strong);
                }
            }
        }
    }
}

/// Logs a panic message.
///
/// # Safety
///
/// `ph` must be a valid pointer (see `std::ptr::read`).
unsafe fn log_panic(ph: *mut RawPh, e: Box<dyn std::any::Any + Send + 'static>) {
    // if it's a &str or String, just print it
    if let Some(s) = e.downcast_ref::<&str>() {
        hexchat_print_str(ph, s, false);
    } else if let Some(s) = e.downcast_ref::<String>() {
        hexchat_print_str(ph, &s, false);
    } else if let Some(s) = e.downcast_ref::<Cow<'static, str>>() {
        hexchat_print_str(ph, &s, false);
    } else {
        hexchat_print_str(ph, "couldn't log panic message", false);
        if let Err(e) = catch_unwind(AssertUnwindSafe(|| drop(e))) {
            // eprintln panics, hexchat_print_str doesn't.
            hexchat_print_str(ph, "ERROR: panicked while trying to log panic!", false);
            mem::forget(e);
            std::process::abort();
        }
    }
}

/// Handles a hook panic at the C-Rust ABI boundary.
///
/// # Safety
///
/// `ph` must be a valid pointer (see `std::ptr::read`).
unsafe fn call_hook_protected<F: FnOnce() -> Eat + UnwindSafe>(
    ph: *mut RawPh,
    f: F
) -> Eat {
    match catch_unwind(f) {
        Result::Ok(v @ _) => v,
        Result::Err(e @ _) => {
            log_panic(ph, e);
            EAT_NONE
        }
    }
}

impl<'ph> PluginHandle<'ph> {
    /// Wraps the raw handle.
    ///
    /// # Safety
    ///
    /// `ph` must be a valid pointer (see `std::ptr::read`).
    unsafe fn new(data: LtPhPtr<'ph>, info: PluginInfo, contexts: Contexts) -> PluginHandle<'ph> {
        PluginHandle {
            data, plugin: data.ph, info, contexts
        }
    }

    /// 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
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn init(ph: &mut PluginHandle<'_>) {
    ///     ph.register("foo", "0.1.0", "my foo plugin");
    /// }
    /// ```
    pub fn register(&mut self, name: &str, desc: &str, ver: &str) {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't be registered");
        unsafe {
            let info = self.info;
            if !(*info.name).is_null() || !(*info.desc).is_null() || !(*info.vers).is_null() {
                panic!("Attempt to re-register a plugin");
            }
            let name = CString::new(name).unwrap();
            let desc = CString::new(desc).unwrap();
            let ver = CString::new(ver).unwrap();
            // these shouldn't panic. if they do, we'll need to free them afterwards.
            (*info.name) = name.into_raw();
            (*info.desc) = desc.into_raw();
            (*info.vers) = ver.into_raw();
        }
    }

    /// Returns this plugin's registered name.
    ///
    /// # Panics
    ///
    /// This function panics if this plugin is not registered.
    pub fn get_name(&self) -> &str {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't be registered");
        unsafe {
            let info = self.info;
            if !(*info.name).is_null() || !(*info.desc).is_null() || !(*info.vers).is_null() {
                std::str::from_utf8_unchecked(CStr::from_ptr(*info.name).to_bytes())
            } else {
                panic!("Attempt to get the name of a plugin that was not yet registered.");
            }
        }
    }

    /// Returns this plugin's registered description.
    ///
    /// # Panics
    ///
    /// This function panics if this plugin is not registered.
    pub fn get_description(&self) -> &str {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't be registered");
        unsafe {
            let info = self.info;
            if !(*info.name).is_null() || !(*info.desc).is_null() || !(*info.vers).is_null() {
                std::str::from_utf8_unchecked(CStr::from_ptr(*info.desc).to_bytes())
            } else {
                panic!("Attempt to get the description of a plugin that was not yet registered.");
            }
        }
    }

    /// Returns this plugin's registered version.
    ///
    /// # Panics
    ///
    /// This function panics if this plugin is not registered.
    pub fn get_version(&self) -> &str {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't be registered");
        unsafe {
            let info = self.info;
            if !(*info.name).is_null() || !(*info.desc).is_null() || !(*info.vers).is_null() {
                std::str::from_utf8_unchecked(CStr::from_ptr(*info.vers).to_bytes())
            } else {
                panic!("Attempt to get the version of a plugin that was not yet registered.");
            }
        }
    }

    /// Ensures the current context is valid.
    ///
    /// # Panics
    ///
    /// This function may panic if it's called while hexchat is closing.
    pub fn ensure_valid_context<F, R>(&mut self, f: F) -> R where F: for<'a> FnOnce(ValidContext<'a, 'ph>) -> R {
        let ctx = self.get_context();
        let res = self.with_context(&ctx, f);
        match res {
            Result::Ok(r @ _) => r,
            Result::Err(e @ _) => {
                let nctx = self.find_valid_context().expect("ensure_valid_context failed (find_valid_context failed), was hexchat closing?");
                self.with_context(&nctx, e.get_closure()).ok().expect("ensure_valid_context failed, was hexchat closing?")
            }
        }
    }

    /// Operates on a virtual plugin.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 for_entry_mut<F, R>(&mut self, entry: &mut PluginEntryHandle<'ph>, f: F) -> R where F: FnOnce(&mut PluginHandle<'ph>) -> R {
        // we're doing something kinda (very) weird here, but this is the only
        // way to get and set pluginprefs for virtual plugins. (not that we
        // support those yet...)
        // this should be sound?
        let data = self.data;
        let info = self.info;
        let contexts = Rc::clone(&self.contexts);
        let mut handle = unsafe { Self::new(data, info, contexts) };
        handle.plugin = entry.entry as *mut RawPh;
        handle.set_context(&self.get_context());
        f(&mut handle)
    }

    /// Registers a virtual plugin.
    pub fn plugingui_add(&self, filename: &str, name: &str, description: &str, version: &str) -> PluginEntryHandle<'ph> {
        let filename = CString::new(filename).unwrap();
        let name = CString::new(name).unwrap();
        let description = CString::new(description).unwrap();
        let version = CString::new(version).unwrap();
        let res = unsafe {
            ph_call!(hexchat_plugingui_add(self, filename.as_ptr(), name.as_ptr(), description.as_ptr(), version.as_ptr(), ptr::null_mut()))
        };
        PluginEntryHandle { ph: self.data, entry: res }
    }

    /// Returns the current context.
    ///
    /// Note: The returned context may be invalid. Use [`Self::set_context`] to
    /// check.
    pub fn get_context(&self) -> Context<'ph> {
        let ctxp = unsafe { ph_call!(hexchat_get_context(self)) };
        // This needs to be fixed by hexchat. I cannot make the value become
        // null when it's invalid without invoking UB. This is because I can't
        // set_context to null.
        let ok = unsafe { ph_call!(hexchat_set_context(self, ctxp)) };
        unsafe { wrap_context(self, if ok == 0 { ptr::null() } else { ctxp }) }
    }

    /// Sets the current context.
    ///
    /// Returns `true` if the context is valid, `false` otherwise.
    pub fn set_context(&mut self, ctx: &Context<'ph>) -> bool {
        // we could've made this &self but we didn't. avoid breaking API.
        self.set_context_internal(ctx)
    }

    /// 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.
    ///
    /// [`set_context`]: #method.set_context
    #[inline]
    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 {
        if !self.set_context(ctx) {
            Err(InvalidContextError(f))
        } else {
            Ok(f(unsafe { ValidContext::new(self) }))
        }
    }

    /// Sets a command hook.
    ///
    /// # Panics
    ///
    /// Panics if this is a borrowed [`PluginEntryHandle`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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_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 {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        unsafe extern "C" fn callback(word: *const *const c_char, word_eol: *const *const c_char, ud: *mut c_void) -> c_int {
            let f: Rc<HookUd> = rc_clone_from_raw(ud as *const HookUd);
            (f)(word, word_eol, ptr::null()).do_eat as c_int
        }
        let b: Rc<HookUd> = {
            let ph = self.data;
            let info = self.info;
            let contexts = Rc::clone(&self.contexts);
            Rc::new(Box::new(move |word, word_eol, _| {
                let cb = &cb;
                let contexts = Rc::clone(&contexts);
                unsafe {
                    call_hook_protected(ph.ph, move || {
                        let mut ph = PluginHandle::new(ph, info, contexts);
                        let word = Word::new(word);
                        let word_eol = WordEol::new(word_eol);
                        cb(&mut ph, word, word_eol)
                    })
                }
            }))
        };
        let name = CString::new(cmd).unwrap();
        let help_text = help.map(CString::new).map(Result::unwrap);
        let bp = Rc::into_raw(b);
        unsafe {
            let res = ph_call!(hexchat_hook_command(self, name.as_ptr(), pri as c_int, callback, help_text.as_ref().map(|s| s.as_ptr()).unwrap_or(ptr::null()), bp as *mut _));
            assert!(!res.is_null());
            HookHandle { ph: self.data, hh: res, freed: Default::default(), _f: PhantomData }
        }
    }
    /// Sets a server hook.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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<'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 {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        self.hook_server_attrs(cmd, pri, move |ph, w, we, _| cb(ph, w, we))
    }
    /// Sets a server hook, with attributes.
    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 {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        unsafe extern "C" fn callback(word: *const *const c_char, word_eol: *const *const c_char, attrs: *const RawAttrs, ud: *mut c_void) -> c_int {
            let f: Rc<HookUd> = rc_clone_from_raw(ud as *const HookUd);
            (f)(word, word_eol, attrs).do_eat as c_int
        }
        let b: Rc<HookUd> = {
            let ph = self.data;
            let info = self.info;
            let contexts = Rc::clone(&self.contexts);
            Rc::new(Box::new(move |word, word_eol, attrs| {
                let cb = &cb;
                let contexts = Rc::clone(&contexts);
                unsafe {
                    call_hook_protected(ph.ph, move || {
                        let mut ph = PluginHandle::new(ph, info, contexts);
                        let word = Word::new(word);
                        let word_eol = WordEol::new(word_eol);
                        let attrs = (&*attrs).into();
                        cb(&mut ph, word, word_eol, attrs)
                    })
                }
            }))
        };
        let name = CString::new(cmd).unwrap();
        let bp = Rc::into_raw(b);
        unsafe {
            let res = ph_call!(hexchat_hook_server_attrs(self, name.as_ptr(), pri as c_int, callback, bp as *mut _));
            assert!(!res.is_null());
            HookHandle { ph: self.data, hh: res, freed: Default::default(), _f: PhantomData }
        }
    }
    /// Sets a print hook.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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<'f, F>(&self, name: &str, pri: i32, cb: F) -> HookHandle<'ph, 'f> where F: Fn(&mut PluginHandle<'ph>, Word) -> Eat + 'f + RefUnwindSafe, 'f: 'ph {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        // hmm, is there any way to avoid this code duplication?
        // hook_print is special because dummy prints (keypresses, Close Context) are handled
        // through here, but never through hook_print_attrs. :/
        unsafe extern "C" fn callback(word: *const *const c_char, ud: *mut c_void) -> c_int {
            let f: Rc<HookUd> = rc_clone_from_raw(ud as *const HookUd);
            (f)(word, ptr::null(), ptr::null()).do_eat as c_int
        }
        // we use "Close Context" to clean up dangling pointers.
        // hexchat lets plugins/hooks eat "Close Context" from eachother (tho
        // not from hexchat, for good reason), so this can still be unsound
        // if other plugins eat "Close Context". in those cases, we'd consider
        // those plugins to be faulty, tho it'd be nice if hexchat handled it.
        // we still do our best to be well-behaved.
        let suppress_eat = name.eq_ignore_ascii_case("Close Context");
        let b: Rc<HookUd> = {
            let ph = self.data;
            let info = self.info;
            let contexts = Rc::clone(&self.contexts);
            Rc::new(Box::new(move |word, _, _| {
                let cb = &cb;
                let contexts = Rc::clone(&contexts);
                unsafe {
                    call_hook_protected(ph.ph, move || {
                        let mut ph = PluginHandle::new(ph, info, contexts);
                        let word = Word::new(word);
                        match cb(&mut ph, word) {
                            _ if suppress_eat => EAT_NONE,
                            eat => eat,
                        }
                    })
                }
            }))
        };
        let name = CString::new(name).unwrap();
        let bp = Rc::into_raw(b);
        unsafe {
            let res = ph_call!(hexchat_hook_print(self, name.as_ptr(), pri as c_int, callback, bp as *mut _));
            assert!(!res.is_null());
            HookHandle { ph: self.data, hh: res, freed: Default::default(), _f: PhantomData }
        }
    }
    /// Sets a print hook, with attributes.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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_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 {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        unsafe extern "C" fn callback(word: *const *const c_char, attrs: *const RawAttrs, ud: *mut c_void) -> c_int {
            let f: Rc<HookUd> = rc_clone_from_raw(ud as *const HookUd);
            (f)(word, ptr::null(), attrs).do_eat as c_int
        }
        let b: Rc<HookUd> = {
            let ph = self.data;
            let info = self.info;
            let contexts = Rc::clone(&self.contexts);
            Rc::new(Box::new(move |word, _, attrs| {
                let cb = &cb;
                let contexts = Rc::clone(&contexts);
                unsafe {
                    call_hook_protected(ph.ph, move || {
                        let mut ph = PluginHandle::new(ph, info, contexts);
                        let word = Word::new(word);
                        let attrs = (&*attrs).into();
                        cb(&mut ph, word, attrs)
                    })
                }
            }))
        };
        let name = CString::new(name).unwrap();
        let bp = Rc::into_raw(b);
        unsafe {
            let res = ph_call!(hexchat_hook_print_attrs(self, name.as_ptr(), pri as c_int, callback, bp as *mut _));
            assert!(!res.is_null());
            HookHandle { ph: self.data, hh: res, freed: Default::default(), _f: PhantomData }
        }
    }
    /// Sets a timer hook
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 hook_timer<'f, F>(&self, timeout: i32, cb: F) -> HookHandle<'ph, 'f> where F: Fn(&mut PluginHandle<'ph>) -> bool + 'f + RefUnwindSafe, 'f: 'ph {
        assert_eq!(self.data.ph, self.plugin, "PluginEntryHandle can't have hooks");
        unsafe extern "C" fn callback(ud: *mut c_void) -> c_int {
            let f: Rc<HookUd> = rc_clone_from_raw(ud as *const HookUd);
            (f)(ptr::null(), ptr::null(), ptr::null()).do_eat as c_int
        }
        let freed = Rc::new(Cell::new(false));
        // helps us clean up the thing when returning false
        let dropper = Rc::new(Cell::new(None));
        let b: Rc<HookUd> = {
            let ph = self.data;
            let info = self.info;
            let contexts = Rc::clone(&self.contexts);
            let freed = AssertUnwindSafe(Rc::clone(&freed));
            let dropper = AssertUnwindSafe(Rc::clone(&dropper));
            Rc::new(Box::new(move |_, _, _| {
                let cb = &cb;
                let contexts = Rc::clone(&contexts);
                let res = unsafe {
                    call_hook_protected(ph.ph, move || {
                        let mut ph = PluginHandle::new(ph, info, contexts);
                        if cb(&mut ph) {
                            EAT_HEXCHAT
                        } else {
                            EAT_NONE
                        }
                    })
                };
                if res == EAT_NONE && !freed.get() {
                    freed.set(true);
                    unsafe {
                        // drop may panic
                        // and so may unwrap
                        // but we must not panic
                        // (kinda silly to abuse call_hook_protected here
                        // but hey, it works and it helps with stuff)
                        call_hook_protected(ph.ph, || {
                            drop(Rc::from_raw(dropper.take().unwrap()));
                            EAT_NONE
                        });
                    }
                }
                res
            }))
        };
        let bp = Rc::into_raw(b);
        dropper.set(Some(bp));
        unsafe {
            let res = ph_call!(hexchat_hook_timer(self, timeout as c_int, callback, bp as *mut _));
            assert!(!res.is_null());
            HookHandle { ph: self.data, hh: res, freed: freed, _f: PhantomData }
        }
    }

    /// Prints to the hexchat buffer.
    // this checks the context internally. if it didn't, it wouldn't be safe to
    // have here.
    pub fn print<T: ToString>(&self, s: T) {
        let s = s.to_string();
        unsafe {
            hexchat_print_str(self.data.ph, &*s, true);
        }
    }

    /// 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
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn hello_world(ph: &mut PluginHandle<'_>) {
    ///     write!(ph, "Hello, world!");
    /// }
    /// ```
    pub fn write_fmt(&self, fmt: fmt::Arguments<'_>) {
        if let Some(s) = fmt.as_str() {
            // "fast" path. hexchat_print_str still has to allocate, and
            // hexchat is slow af.
            unsafe {
                hexchat_print_str(self.data.ph, s, true);
            }
        } else {
            self.print(fmt);
        }
    }

    /// Returns context and client information.
    ///
    /// See [`InfoId`] for the kinds of information that can be retrieved.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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_info<'a>(&'a self, id: InfoId) -> Option<Cow<'a, str>> {
        let id_cstring = CString::new(&*id.name()).unwrap();
        unsafe {
            let res = ph_call!(hexchat_get_info(self, id_cstring.as_ptr()));
            if res.is_null() {
                None
            } else {
                let s = CStr::from_ptr(res).to_str();
                // FIXME: figure out which InfoId's are safe to borrow.
                Some(s.expect("broken hexchat").to_owned().into())
            }
        }
    }

    /// 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
    ///
    /// ```no_run
    /// 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 get_libdirfs(&self) -> Option<CString> {
        let id_cstring = CString::new("libdirfs").unwrap();
        unsafe {
            let res = ph_call!(hexchat_get_info(self, id_cstring.as_ptr()));
            if res.is_null() {
                None
            } else {
                Some(CStr::from_ptr(res).to_owned())
            }
        }
    }

    /// Strips attributes from text. See [`Strip`] for which attributes can
    /// be stripped.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::{PluginHandle, Strip};
    ///
    /// /// Removes colors
    /// fn strip_colors(ph: &PluginHandle<'_>, s: &str) -> String {
    ///     ph.strip(s, Strip::new().colors(true))
    /// }
    /// ```
    #[cfg(feature = "nul_in_strip")]
    pub fn strip(&self, s: &str, strip: Strip) -> String {
        // ironically the single API where we can pass embedded NULs.
        // we also don't need to worry about terminating it with NUL.
        let mut out = Vec::with_capacity(s.len());
        let in_ptr = s.as_ptr() as *const _;
        let in_len = s.len().try_into().unwrap();
        let flags = strip.flags();
        // NOTE: avoid panicking from here.
        let stripped = unsafe {
            ph_call!(hexchat_strip(self, in_ptr, in_len, flags))
        };
        // tho annoyingly we don't know the out len, so we need to count NULs.
        let in_nuls = s.as_bytes().into_iter().filter(|&&x| x == 0).count();
        let mut out_len = 0;
        for _ in 0..=in_nuls {
            while unsafe { *stripped.add(out_len) } != 0 {
                out_len += 1;
            }
            out_len += 1;
        }
        out.extend_from_slice(unsafe {
            // take out the extra NUL at the end.
            std::slice::from_raw_parts(stripped as *const _, out_len - 1)
        });
        unsafe {
            ph_call!(hexchat_free(self, stripped as *const _));
        }
        // we can panic again here, tho this should never panic.
        String::from_utf8(out).unwrap()
    }

    /// Strips attributes from text. See [`Strip`] for which attributes can
    /// be stripped.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::{PluginHandle, Strip};
    ///
    /// /// Removes colors
    /// fn strip_colors(ph: &PluginHandle<'_>, s: &str) -> String {
    ///     ph.strip(s, Strip::new().colors(true))
    /// }
    /// ```
    #[cfg(not(feature = "nul_in_strip"))]
    pub fn strip(&self, s: &str, strip: Strip) -> String {
        // make sure s doesn't contain nuls
        assert!(!s.as_bytes().contains(&0), "embedded nuls are not allowed");
        let mut out = Vec::with_capacity(s.len());
        let in_ptr = s.as_ptr() as *const _;
        let in_len = s.len().try_into().unwrap();
        let flags = strip.flags();
        // NOTE: avoid panicking from here.
        let stripped = unsafe {
            ph_call!(hexchat_strip(self, in_ptr, in_len, flags))
        };
        out.extend_from_slice(unsafe { CStr::from_ptr(stripped) }.to_bytes());
        unsafe {
            ph_call!(hexchat_free(self, stripped as *const _));
        }
        // we can panic again here, tho this should never panic.
        String::from_utf8(out).unwrap()
    }

    /// Sets a pluginpref.
    ///
    /// Note: If two pluginprefs exist with the same name, but different ASCII
    /// case, only one will be available through `pluginpref_get`.
    ///
    /// # Panics
    ///
    /// Panics if the plugin is not registered.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn set_str(ph: &PluginHandle<'_>, val: &str) {
    ///     ph.pluginpref_set("string", val);
    /// }
    ///
    /// fn set_int(ph: &PluginHandle<'_>, val: i32) {
    ///     ph.pluginpref_set("int", &format!("{}", val));
    /// }
    /// ```
    pub fn pluginpref_set(
        &self,
        var: &str,
        value: &str,
    ) -> Result<(), PluginPrefError> {
        assert!(!self.info.name.is_null(), "must register plugin first");
        if value.starts_with(' ') {
            return Err(PluginPrefError::InvalidValue)
        }
        let var_len = var.len();
        let var = check_pluginpref_var(var)?;
        let mut val_len = value.len();
        // octal is \000 - \377, adds 3 bytes
        val_len += 3 * value.bytes().filter(|&x| x < 32 || x > 127).count();
        // special chars are \t \n etc, or octal - 2 bytes
        val_len -= 2 * value.bytes().filter(|&x| {
            matches!(
                x,
                | b'\n'
                | b'\r'
                | b'\t'
                | b'\x0C' // \f
                | b'\x08' // \b
            )
        }).count();
        // additionally \ and " also get an extra byte
        val_len += value.bytes().filter(|&x| x == b'"' || x == b'\\').count();
        // 3 bytes from " = ", < 512 because 511 + NUL
        if var_len + val_len + 3 < 512 {
            let value = CString::new(value).unwrap();
            let success = unsafe {
                ph_call!(
                    hexchat_pluginpref_set_str(
                        self,
                        var.as_ptr(),
                        value.as_ptr()
                    )
                )
            } != 0;
            if !success {
                Err(PluginPrefError::Failed)
            } else {
                Ok(())
            }
        } else {
            Err(PluginPrefError::TooLong)
        }
    }

    /// Retrieves a pluginpref.
    ///
    /// # Panics
    ///
    /// Panics if the plugin is not registered.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn get_str(ph: &PluginHandle<'_>) -> String {
    ///     ph.pluginpref_get("string").unwrap_or(String::new())
    /// }
    ///
    /// fn get_int(ph: &PluginHandle<'_>) -> i32 {
    ///     ph.pluginpref_get("int").unwrap_or(String::new()).parse().unwrap_or(-1)
    /// }
    /// ```
    pub fn pluginpref_get(
        &self,
        var: &str,
    ) -> Result<String, PluginPrefError> {
        assert!(!self.info.name.is_null(), "must register plugin first");
        let var = check_pluginpref_var(var)?;
        let mut buffer: [MaybeUninit<c_char>; 512] = unsafe {
            MaybeUninit::uninit().assume_init()
        };
        let success = unsafe {
            ph_call!(
                hexchat_pluginpref_get_str(
                    self,
                    var.as_ptr(),
                    buffer.as_mut_ptr() as *mut _
                )
            )
        } != 0;
        if !success {
            Err(PluginPrefError::Failed)
        } else {
            match unsafe {
                CStr::from_ptr(buffer.as_ptr() as *const _)
            }.to_owned().into_string() {
                Ok(s) => Ok(s),
                Err(e) => Err(PluginPrefError::Utf8Error(e)),
            }
        }
    }

    /// Removes a pluginpref.
    ///
    /// # Panics
    ///
    /// Panics if the plugin is not registered.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn del_str(ph: &PluginHandle<'_>) {
    ///     let _ = ph.pluginpref_delete("string");
    /// }
    ///
    /// fn del_int(ph: &PluginHandle<'_>) {
    ///     let _ = ph.pluginpref_delete("int");
    /// }
    /// ```
    pub fn pluginpref_delete(&self, var: &str) -> Result<(), PluginPrefError> {
        assert!(!self.info.name.is_null(), "must register plugin first");
        let var = check_pluginpref_var(var)?;
        let success = unsafe {
            ph_call!(hexchat_pluginpref_delete(self, var.as_ptr()))
        } != 0;
        if !success {
            Err(PluginPrefError::Failed)
        } else {
            Ok(())
        }
    }

    /// Lists pluginprefs.
    ///
    /// # Panics
    ///
    /// Panics if the plugin is not registered.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::PluginHandle;
    ///
    /// fn list_prefs(ph: &PluginHandle<'_>) {
    ///     match ph.pluginpref_list() {
    ///         Ok(it) => for pref in &it {
    ///             match pref {
    ///                 Ok(pref) => write!(ph, "{}", pref),
    ///                 _ => (),
    ///             }
    ///         },
    ///         _ => (),
    ///     }
    /// }
    /// ```
    pub fn pluginpref_list(&self) -> Result<PluginPrefList, PluginPrefError> {
        assert!(!self.info.name.is_null(), "must register plugin first");
        let mut buffer: [MaybeUninit<c_char>; 4096] = unsafe {
            MaybeUninit::uninit().assume_init()
        };
        let success = unsafe {
            ph_call!(
                hexchat_pluginpref_list(self, buffer.as_mut_ptr() as *mut _)
            )
        } != 0;
        if !success {
            Err(PluginPrefError::Failed)
        } else {
            let mut list = PluginPrefList {
                inner: unsafe {
                    CStr::from_ptr(buffer.as_ptr() as *const _)
                }.to_owned().into_bytes(),
            };
            list.inner.iter_mut().for_each(|x| if *x == b',' { *x = 0; });
            Ok(list)
        }
    }

    // ******* //
    // PRIVATE //
    // ******* //

    fn find_valid_context(&self) -> Option<Context<'ph>> {
        unsafe {
            let channel_key = cstr(b"channels\0");
            let context_key = cstr(b"context\0");
            // TODO wrap this in a safer API, with proper Drop
            #[allow(unused_mut)]
            let mut list = ph_call!(hexchat_list_get(self, channel_key));
            // hexchat does this thing where it puts a context in a list_str.
            // this *is* the proper way to do this, but it looks weird.
            let ctx = if ph_call!(hexchat_list_next(self, list)) != 0 {
                Some(ph_call!(hexchat_list_str(self, list, context_key)) as *const internals::HexchatContext)
            } else {
                None
            };
            ph_call!(hexchat_list_free(self, list));
            ctx.map(|ctx| wrap_context(self, ctx))
        }
    }

    /// Same as `set_context` but it takes `&self`.
    fn set_context_internal(&self, ctx: &Context<'ph>) -> bool {
        if let Some(ctx) = ctx.ctx.upgrade() {
            unsafe {
                ph_call!(hexchat_set_context(self, *ctx)) != 0
            }
        } else {
            false
        }
    }
}

impl<'a> EventAttrs<'a> {
    /// Creates a new `EventAttrs`.
    #[allow(deprecated)]
    pub fn new() -> EventAttrs<'a> {
        EventAttrs {
            server_time: None,
            raw_server_time: 0,
            use_raw_server_time: false,
            _dummy: PhantomData,
        }
    }
}

impl<'a> From<&'a RawAttrs> for EventAttrs<'a> {
    #[allow(deprecated)]
    fn from(other: &'a RawAttrs) -> EventAttrs<'a> {
        EventAttrs {
            server_time: if other.server_time_utc > 0 { Some(UNIX_EPOCH + Duration::from_secs(other.server_time_utc as u64)) } else { None },
            raw_server_time: other.server_time_utc,
            // Defaults to false for API compatibility.
            use_raw_server_time: false,
            _dummy: PhantomData,
        }
    }
}

impl<'a, 'ph: 'a> ValidContext<'a, 'ph> {
/*
 * These cause UB:
 * `hexchat_command` may invalidate the plugin context.
 * `hexchat_find_context` and `hexchat_nickcmp` use the plugin context without checking it.
 * `hexchat_get_prefs` uses the plugin context if name == "state_cursor" or "id" (or anything with
 * the same hash).
 * `hexchat_list_get` uses the plugin context if name == "notify" (or anything with the same hash).
 * `hexchat_list_str`, `hexchat_list_int`, 
 * `hexchat_emit_print`, `hexchat_emit_print_attrs` use the plugin context.
 * `hexchat_send_modes` uses the plugin context.
 * We need to wrap them (or, alternatively, hexchat_command). However, there's no (safe) way to get
 * a valid context afterwards.
 * - Actually that's a lie. Hexchat does a trick to give you a context as part of the channel list.
 *     We can use that to our advantage. I'm not sure if it's better to wrap hexchat_command or the
 *     other functions, tho.
 *     (Do we want to walk a linked list every time we use hexchat_command? I'd think
 *     hexchat_command is the most used API function... Plus, emit_print could indirectly
 *     invalidate the context as well.)
 *
 * For performance we put them behind an ValidContext - things that don't invalidate the
 * context take an `&mut self`, things that do take an `self`.
 */

    /// Finds an open context for the given servname and channel.
    pub fn find_context(&self, servname: Option<&str>, channel: Option<&str>) -> Option<Context<'ph>> {
        let ph = &self.ph;
        let servname = servname.map(|x| CString::new(x).unwrap());
        let channel = channel.map(|x| CString::new(x).unwrap());
        let ctx = unsafe {
            let sptr = servname.map(|x| x.as_ptr()).unwrap_or(ptr::null());
            let cptr = channel.map(|x| x.as_ptr()).unwrap_or(ptr::null());
            ph_call!(hexchat_find_context(ph, sptr, cptr))
        };
        if ctx.is_null() {
            None
        } else {
            Some(unsafe { wrap_context(self.ph, ctx) })
        }
    }

    /// Compares two nicks based on the server's case mapping.
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::ValidContext;
    ///
    /// /// Checks if the two nicks below are equal.
    /// fn compare_nicks(context: ValidContext<'_, '_>) -> bool {
    ///     context.nickcmp("hello", "HELLO").is_eq()
    /// }
    /// ```
    pub fn nickcmp(&self, nick1: &str, nick2: &str) -> std::cmp::Ordering {
        use std::cmp::Ordering;
        let ph = &self.ph;
        // need to put this in a more permanent position than temporaries
        let nick1 = CString::new(nick1).unwrap();
        let nick2 = CString::new(nick2).unwrap();
        let res = unsafe {
            ph_call!(hexchat_nickcmp(ph, nick1.as_ptr(), nick2.as_ptr()))
        };
        if res < 0 {
            Ordering::Less
        } else if res > 0 {
            Ordering::Greater
        } else {
            Ordering::Equal
        }
    }

    /// Sends a list of modes to the current channel.
    pub fn send_modes<'b, I: IntoIterator<Item=&'b str>>(&mut self, iter: I, mpl: i32, sign: char, mode: char) {
        let ph = &self.ph;
        assert!(sign == '+' || sign == '-', "sign must be + or -");
        assert!(mode.is_ascii(), "mode must be ascii");
        assert!(mpl >= 0, "mpl must be non-negative");
        let v: Vec<CString> = iter.into_iter().map(|s| CString::new(s).unwrap()).collect();
        let mut v2: Vec<*const c_char> = (&v).iter().map(|x| x.as_ptr()).collect();
        let arr: &mut [*const c_char] = &mut *v2;
        unsafe {
            ph_call!(hexchat_send_modes(ph, arr.as_mut_ptr(), arr.len() as c_int,
                mpl as c_int, sign as c_char, mode as c_char));
        }
        // some hexchat forks may invalidate the context here.
        // just pretend everything is fine and don't bump the major version.
        if !self.set_context(&self.get_context()) {
            let context = self.ph.find_valid_context().unwrap();
            if !self.set_context(&context) { panic!(); }
        }
    }

    /// Returns a client setting.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::ValidContext;
    ///
    /// /// Returns the user's configured main nick.
    /// fn main_nick(context: ValidContext<'_, '_>) -> String {
    ///     context.get_prefs("irc_nick1").unwrap().into_string().unwrap()
    /// }
    /// ```
    pub fn get_prefs(&self, name: &str) -> Option<PrefValue> {
        let ph = &self.ph;
        let name = CString::new(name).unwrap();
        let mut string = 0 as *const c_char;
        let mut int: c_int = 0;
        match unsafe {
            ph_call!(hexchat_get_prefs(ph, name.as_ptr(), &mut string, &mut int))
        } {
            0 => None,
            1 => Some(PrefValue::String(unsafe {
                CStr::from_ptr(string).to_owned().into_string().unwrap()
            })),
            2 => Some(PrefValue::Int(int as _)),
            3 => Some(PrefValue::Bool(int != 0)),
            _ => panic!("unsupported type in get_prefs"),
        }
    }

    /// Executes a command.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::{ValidContext};
    ///
    /// fn join(context: ValidContext<'_, '_>, channel: &str) {
    ///     context.command(&format!("join {}", channel));
    /// }
    /// ```
    pub fn command(self, cmd: &str) {
        let ph = self.ph;
        // need to put this in a more permanent position than temporaries
        let cmd = CString::new(cmd).unwrap();
        unsafe {
            ph_call!(hexchat_command(ph, cmd.as_ptr()))
        }
    }

    /// Prints an event message, and returns a success status (whether or not
    /// the event exists).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::{ValidContext};
    ///
    /// fn emit_channel_message(context: ValidContext<'_, '_>, nick: &str, msg: &str) {
    ///     context.emit_print("Channel Message", [nick, msg]);
    /// }
    /// ```
    pub fn emit_print<'b, I: IntoIterator<Item=&'b str>>(self, event: &str, args: I) -> bool {
        let ph = self.ph;
        let event = CString::new(event).unwrap();
        let mut args_cs: [Option<CString>; 4] = [None, None, None, None];
        {
            let mut iter = args.into_iter();
            for i in 0..4 {
                args_cs[i] = iter.next().map(|x| CString::new(x).unwrap());
                if args_cs[i].is_none() {
                    break;
                }
            }
            if iter.next().is_some() {
                // it's better to panic so as to get bug reports when we need to increase this
                panic!("too many arguments to emit_print (max 4), or iterator not fused");
            }
        }
        let mut argv: [*const c_char; 5] = [ptr::null(); 5];
        for i in 0..4 {
            argv[i] = args_cs[i].as_ref().map_or(ptr::null(), |s| s.as_ptr());
        }
        unsafe {
            ph_call!(hexchat_emit_print(ph, event.as_ptr(), argv[0], argv[1], argv[2], argv[3], argv[4])) != 0
        }
    }

    /// Prints an event message, and returns a success status (whether or not
    /// the event exists).
    ///
    /// Also allows setting event attributes.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::time::SystemTime;
    /// use hexchat_unsafe_plugin::{EventAttrs, ValidContext};
    ///
    /// fn emit_channel_message_at(context: ValidContext<'_, '_>, time: Option<SystemTime>, nick: &str, msg: &str) {
    ///     let mut attrs = EventAttrs::new();
    ///     attrs.server_time = time;
    ///     context.emit_print_attrs(attrs, "Channel Message", [nick, msg]);
    /// }
    /// ```
    pub fn emit_print_attrs<'b, I: IntoIterator<Item=&'b str>>(self, attrs: EventAttrs, event: &str, args: I) -> bool {
        let ph = self.ph;
        let event = CString::new(event).unwrap();
        let mut args_cs: [Option<CString>; 4] = [None, None, None, None];
        {
            let mut iter = args.into_iter();
            for i in 0..4 {
                args_cs[i] = iter.next().map(|x| CString::new(x).unwrap());
                if args_cs[i].is_none() {
                    break;
                }
            }
            if let Some(_) = iter.next() {
                // it's better to panic so as to get bug reports when we need to increase this
                panic!("too many arguments to emit_print_attrs (max 4), or iterator not fused");
            }
        }
        let mut argv: [*const c_char; 5] = [ptr::null(); 5];
        for i in 0..4 {
            argv[i] = args_cs[i].as_ref().map_or(ptr::null(), |s| s.as_ptr());
        }
        let helper = unsafe { HexchatEventAttrsHelper::new_with(ph, attrs) };
        unsafe {
            ph_call!(hexchat_emit_print_attrs(ph, helper.0, event.as_ptr(), argv[0], argv[1], argv[2], argv[3], argv[4])) != 0
        }
    }

    /// Retrieves a list.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use hexchat_unsafe_plugin::list::Contexts;
    /// use hexchat_unsafe_plugin::PluginHandle;
    /// 
    /// fn print_contexts(ph: &mut PluginHandle<'_>) {
    ///     ph.ensure_valid_context(|ph| {
    ///         let mut contexts = ph.list(&Contexts);
    ///         while let Some(context) = contexts.next() {
    ///             write!(ph, "{}", context.name().unwrap());
    ///         }
    ///     })
    /// }
    /// ```
    pub fn list<T: list::List>(&'a self, t: &'a T) -> list::Entries<'a, 'ph, T> {
        let ph = &self.ph;
        let list = CString::new(&*t.name()).unwrap();
        let list = unsafe {
            ph_call!(hexchat_list_get(ph, list.as_ptr()))
        };
        list::Entries {
            context: self.ph,
            list: list,
            t: t,
        }
    }

    // ******** //
    // FORWARDS //
    // ******** //
    // We can't just deref because then you could recursively ensure valid context and then it'd no
    // longer work.

    /// Returns the current context.
    ///
    /// See [`PluginHandle::get_context`].
    pub fn get_context(&self) -> Context<'ph> {
        self.ph.get_context()
    }

    /// Sets the current context.
    ///
    /// Returns `true` if the context is valid, `false` otherwise.
    ///
    /// See [`PluginHandle::set_context`].
    // One would think this is unsound, but if the given context isn't valid,
    // the current context is unchanged and still valid.
    // But if the given context is valid, it becomes the new, valid, current
    // context.
    // So either way we're still in a valid context when this returns.
    pub fn set_context(&mut self, ctx: &Context<'ph>) -> bool {
        self.ph.set_context_internal(ctx)
    }

    /// Prints to the hexchat buffer.
    ///
    /// See [`PluginHandle::print`].
    pub fn print<T: ToString>(&self, s: T) {
        self.ph.print(s)
    }

    /// Prints to the hexchat buffer.
    ///
    /// Glue for usage of the [`write!`] macro with hexchat.
    ///
    /// See [`PluginHandle::write_fmt`].
    ///
    /// # Panics
    ///
    /// This panics if any broken formatting trait implementations are used in
    /// the format arguments. See also [`format!`].
    pub fn write_fmt(&self, fmt: fmt::Arguments<'_>) {
        self.ph.write_fmt(fmt)
    }

    /// Sets a command hook.
    ///
    /// See [`PluginHandle::hook_command`].
    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 {
        self.ph.hook_command(cmd, pri, help, cb)
    }
    /// Sets a server hook.
    ///
    /// See [`PluginHandle::hook_server`].
    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 {
        self.ph.hook_server(cmd, pri, cb)
    }
    /// Sets a server hook with attributes.
    ///
    /// See [`PluginHandle::hook_server_attrs`].
    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 {
        self.ph.hook_server_attrs(cmd, pri, cb)
    }
    /// Sets a print hook.
    ///
    /// See [`PluginHandle::hook_print`].
    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 {
        self.ph.hook_print(name, pri, cb)
    }
    /// Sets a print hook with attributes.
    ///
    /// See [`PluginHandle::hook_print_attrs`].
    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 {
        self.ph.hook_print_attrs(name, pri, cb)
    }
    /// Sets a timer hook.
    ///
    /// See [`PluginHandle::hook_timer`].
    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 {
        self.ph.hook_timer(timeout, cb)
    }
    /// Returns context and client information.
    ///
    /// See [`PluginHandle::get_info`].
    pub fn get_info<'b>(&'b self, id: InfoId) -> Option<Cow<'b, str>> {
        self.ph.get_info(id)
    }
    /// Returns the plugin directory.
    ///
    /// See [`PluginHandle::get_libdirfs`].
    pub fn get_libdirfs(&self) -> Option<CString> {
        self.ph.get_libdirfs()
    }
    /// Strips attributes from text.
    ///
    /// See [`PluginHandle::strip`].
    pub fn strip(&self, s: &str, strip: Strip) -> String {
        self.ph.strip(s, strip)
    }
    /// Sets a pluginpref.
    ///
    /// See [`PluginHandle::pluginpref_set`].
    pub fn pluginpref_set(
        &self,
        var: &str,
        value: &str,
    ) -> Result<(), PluginPrefError> {
        self.ph.pluginpref_set(var, value)
    }
    /// Retrieves a pluginpref.
    ///
    /// See [`PluginHandle::pluginpref_get`].
    pub fn pluginpref_get(
        &self,
        var: &str,
    ) -> Result<String, PluginPrefError> {
        self.ph.pluginpref_get(var)
    }
    /// Removes a pluginpref.
    ///
    /// See [`PluginHandle::pluginpref_delete`].
    pub fn pluginpref_delete(&self, var: &str) -> Result<(), PluginPrefError> {
        self.ph.pluginpref_delete(var)
    }
    /// Lists pluginprefs.
    ///
    /// See [`PluginHandle::pluginpref_list`].
    pub fn pluginpref_list(&self) -> Result<PluginPrefList, PluginPrefError> {
        self.ph.pluginpref_list()
    }
}

// ******* //
// PRIVATE //
// ******* //

// Type aliases, used for safety type checking.
// /// Userdata type used by a command hook.
// We actually do want RefUnwindSafe. This function may be called multiple times, and it's not
// automatically invalidated if it panics, so it may be called again after it panics. If you need
// mutable state, std provides std::sync::Mutex which has poisoning. Other interior mutability with
// poisoning could also be used. std doesn't have anything for single-threaded performance (yet),
// but hexchat isn't particularly performance-critical.
// type CommandHookUd = Box<dyn Fn(Word, WordEol) -> Eat + std::panic::RefUnwindSafe>;
// /// Userdata type used by a server hook.
// type ServerHookUd = Box<dyn Fn(Word, WordEol, EventAttrs) -> Eat + std::panic::RefUnwindSafe>;
// /// Userdata type used by a print hook.
// type PrintHookUd = Box<dyn Fn(Word, EventAttrs) -> Eat + std::panic::RefUnwindSafe>;
// /// Userdata type used by a timer hook.
// type TimerHookUd = Box<dyn Fn() -> bool + std::panic::RefUnwindSafe>;
/// Userdata type used by a hook
type HookUd<'f> = Box<dyn Fn(*const *const c_char, *const *const c_char, *const RawAttrs) -> Eat + RefUnwindSafe + 'f>;
/// Contexts
type Contexts = Rc<AssertUnwindSafe<RefCell<HashSet<Rc<*const internals::HexchatContext>>>>>;

/// The contents of an empty CStr.
///
/// This is useful where you need a non-null CStr.
// NOTE: MUST BE b"\0"!
const EMPTY_CSTRING_DATA: &[u8] = b"\0";

/// Converts a nul-terminated const bstring to a C string.
///
/// # Panics
///
/// Panics if b contains embedded nuls.
// TODO const fn, once that's possible
fn cstr(b: &'static [u8]) -> *const c_char {
    CStr::from_bytes_with_nul(b).unwrap().as_ptr()
}

/// Clones an Rc straight from a raw pointer.
///
/// # Safety
///
/// This function is unsafe because `ptr` must hame come from `Rc::into_raw`.
unsafe fn rc_clone_from_raw<T>(ptr: *const T) -> Rc<T> {
    let rc = ManuallyDrop::new(Rc::from_raw(ptr));
    Rc::clone(&rc)
}

/// Converts a **valid** context pointer into a Context (Rust-managed) struct.
///
/// # Safety
///
/// This function doesn't validate the context.
unsafe fn wrap_context<'ph>(ph: &PluginHandle<'ph>, ctx: *const internals::HexchatContext) -> Context<'ph> {
    let contexts = ph.contexts.clone();
    if ctx.is_null() {
        Context { contexts, ctx: RcWeak::new(), _ph: PhantomData }
    } else {
        let weak_ctxp = (|| {
            // need to drop the borrow(), so use an (|| IIFE)()
            contexts.borrow().get(&ctx).map(|x| {
                Rc::downgrade(x)
            })
        })().unwrap_or_else(|| {
            let ctxp = Rc::new(ctx);
            let weak_ctxp = Rc::downgrade(&ctxp);
            contexts.borrow_mut().insert(ctxp);
            weak_ctxp
        });
        Context { contexts, ctx: weak_ctxp, _ph: PhantomData }
    }
}

/// Prints an &str to hexchat, trying to avoid allocations.
///
/// # Safety
///
/// This function does not check the passed in argument.
///
/// # Panics
///
/// Panics if panic_on_nul is true and the string contains embedded nuls.
unsafe fn hexchat_print_str(ph: *mut RawPh, s: &str, panic_on_nul: bool) {
    match CString::new(s) {
        Result::Ok(cs @ _) => {
            let csr: &CStr = &cs;
            ((*ph).hexchat_print)(ph, csr.as_ptr())
        },
        e @ _ => if panic_on_nul {e.unwrap();}, // TODO nul_position?
    }
}

/// Helper to manage owned RawAttrs
struct HexchatEventAttrsHelper<'a, 'ph>(*mut RawAttrs, &'a PluginHandle<'ph>) where 'ph: 'a;

impl<'a, 'ph> HexchatEventAttrsHelper<'a, 'ph> where 'ph: 'a {
    /// Creates a new, empty `HexchatEventAttrsHelper`.
    ///
    /// # Safety
    ///
    /// `ph` must be a valid raw plugin handle.
    unsafe fn new(ph: &'a PluginHandle<'ph>) -> Self {
        HexchatEventAttrsHelper(ph_call!(hexchat_event_attrs_create(ph)), ph)
    }

    /// Creates a new `HexchatEventAttrsHelper` for a given `EventAttrs`.
    ///
    /// # Safety
    ///
    /// `ph` must be a valid raw plugin handle.
    unsafe fn new_with(ph: &'a PluginHandle<'ph>, attrs: EventAttrs<'_>) -> Self {
        let helper = Self::new(ph);
        #[allow(deprecated)]
        let v = if attrs.use_raw_server_time {
            attrs.raw_server_time
        } else {
            attrs.server_time.or(Some(UNIX_EPOCH)).map(|st| {
                match st.duration_since(UNIX_EPOCH) {
                    Ok(n) => n.as_secs(),
                    Err(_) => 0
                }
            }).filter(|&st| {
                st < (time_t::max_value() as u64)
            }).unwrap() as time_t
        };
        (*helper.0).server_time_utc = v;
        helper
    }
}

impl<'a, 'ph> Drop for HexchatEventAttrsHelper<'a, 'ph> where 'ph: 'a {
    fn drop(&mut self) {
        unsafe {
            ph_call!(hexchat_event_attrs_free(self.1, self.0))
        }
    }
}

/// Plugin data stored in the hexchat plugin_handle.
struct PhUserdata<'ph> {
    plug: Pin<Box<dyn Plugin<'ph> + 'ph>>,
    contexts: Contexts,
    // this is never read, but we need to not drop it until we can drop it
    _context_hook: HookHandle<'ph, 'ph>,
    pluginfo: PluginInfo,
}

/// Puts the userdata in the plugin handle.
///
/// # Safety
///
/// This function is unsafe because it doesn't check if the pointer is valid.
///
/// Improper use of this function can leak memory.
unsafe fn put_userdata<'ph>(ph: LtPhPtr<'ph>, ud: Box<PhUserdata<'ph>>) {
    (*ph.ph).userdata = Box::into_raw(ud) as *mut c_void;
}

/// Pops the userdata from the plugin handle.
///
/// # Safety
///
/// This function is unsafe because it doesn't check if the pointer is valid.
unsafe fn pop_userdata<'ph>(ph: LtPhPtr<'ph>) -> Box<PhUserdata<'ph>> {
    Box::from_raw(mem::replace(&mut (*ph.ph).userdata, ptr::null_mut()) as *mut PhUserdata<'ph>)
}

fn test_pluginpref_var(var: &[u8]) -> Result<(), PluginPrefError> {
    if var.len() >= 127
    || var.len() < 1
    // rust uses the same definition of ascii whitespace
    || var.last().unwrap().is_ascii_whitespace()
    || var.contains(&b' ')
    || var.contains(&b'=')
    || var.contains(&b'\n')
    || var.contains(&b',') {
        Err(PluginPrefError::InvalidVar)
    } else {
        Ok(())
    }
}

fn check_pluginpref_var(var: impl Into<Vec<u8>>) -> Result<CString, PluginPrefError> {
    let var = var.into();
    test_pluginpref_var(&var)?;
    Ok(CString::new(var).unwrap())
}

// *********************** //
// PUBLIC OUT OF NECESSITY //
// *********************** //

#[doc(hidden)]
pub unsafe fn hexchat_plugin_init<'ph, T>(plugin_handle: LtPhPtr<'ph>,
                                     plugin_name: *mut *const c_char,
                                     plugin_desc: *mut *const c_char,
                                     plugin_version: *mut *const c_char,
                                     arg: *const c_char) -> c_int
                                     where T: Plugin<'ph> + Default + 'ph {
    if plugin_handle.ph.is_null() || plugin_name.is_null() || plugin_desc.is_null() || plugin_version.is_null() {
        // we can't really do anything here. just hope this doesn't panic.
        eprintln!("hexchat_plugin_init called with a null pointer that shouldn't be null - broken hexchat");
        std::process::abort();
    }
    let ph = plugin_handle.ph as *mut RawPh;
    // clear the "userdata" field first thing - if the deinit function gets called (wrong hexchat
    // version, other issues), we don't wanna try to drop the hexchat_dummy or hexchat_read_fd
    // function as if it were a Box!
    (*ph).userdata = ptr::null_mut();
    // read the filename so we can pass it on later.
    let filename = if !(*plugin_name).is_null() {
        if let Ok(fname) = CStr::from_ptr(*plugin_name).to_owned().into_string() {
            fname
        } else {
            hexchat_print_str(ph, "failed to convert filename to utf8 - broken hexchat", false);
            return 0;
        }
    } else {
        // no filename specified for some reason, but we can still load
        String::new() // empty string
    };
    // these may be null, unless initialization is successful.
    // we set them to null as markers.
    *plugin_name = ptr::null();
    *plugin_desc = ptr::null();
    *plugin_version = ptr::null();
    // do some version checks for safety
    // NOTE: calling hexchat functions with null plugin_name, plugin_desc, plugin_version is a bit
    // dangerous. this particular case is "ok".
    {
        let ver = ((*ph).hexchat_get_info)(ph, cstr(b"version\0")); // this shouldn't panic
        let cstr = CStr::from_ptr(ver);
        if let Ok(ver) = cstr.to_str() {
            let mut iter = ver.split('.');
            let a = iter.next().map(i32::from_str).and_then(Result::ok).unwrap_or(0);
            let b = iter.next().map(i32::from_str).and_then(Result::ok).unwrap_or(0);
            let c = iter.next().map(i32::from_str).and_then(Result::ok).unwrap_or(0);
            // 2.9.6 or greater
            if !(a > 2 || (a == 2 && (b > 9 || (b == 9 && (c > 6 || (c == 6)))))) {
                return 0;
            }
        } else {
            return 0;
        }
    }
    // we got banned from an IRC network over the following line of code.
    hexchat_print_str(ph, "hexchat-unsafe-plugin  Copyright (C) 2018, 2021, 2022 Soni L.  GPL-3.0-or-later  This software is made with love by a queer trans person.", false);
    let mut pluginfo = if let Some(pluginfo) = PluginInfo::new(plugin_name, plugin_desc, plugin_version) {
        pluginfo
    } else {
        return 0;
    };
    let r: thread::Result<Option<Box<_>>> = {
        catch_unwind(move || {
            // AssertUnwindSafe not Default at the time of writing this
            let contexts = Rc::new(AssertUnwindSafe(Default::default()));
            let mut pluginhandle = PluginHandle::new(plugin_handle, pluginfo, contexts);
            let contexts = Rc::clone(&pluginhandle.contexts);
            // must register this before the plugin registers anything else!
            let context_hook = pluginhandle.hook_print("Close Context", c_int::min_value(), move |ph, _| {
                // just remove the context! it's that simple!
                let ctx = ph_call!(hexchat_get_context(ph));
                contexts.borrow_mut().remove(&ctx);
                EAT_NONE
            });
            let contexts = Rc::clone(&pluginhandle.contexts);
            let mut plug = Box::pin(T::default());
            if plug.as_mut().init(&mut pluginhandle, &filename, if !arg.is_null() { Some(CStr::from_ptr(arg).to_str().expect("arg not valid utf-8 - broken hexchat")) } else { None }) {
                if !(pluginfo.name.is_null() || pluginfo.desc.is_null() || pluginfo.vers.is_null()) {
                    Some(Box::new(PhUserdata { plug, pluginfo, contexts, _context_hook: context_hook }))
                } else {
                    // TODO log: forgot to call register
                    None
                }
            } else {
                if !(pluginfo.name.is_null() || pluginfo.desc.is_null() || pluginfo.vers.is_null()) {
                    pluginfo.drop_info()
                }
                None
            }
        })
    };
    match r {
        Result::Ok(Option::Some(plug @ _)) => {
            put_userdata(plugin_handle, plug);
            1
        },
        r @ _ => {
            if let Err(e) = r {
                log_panic(ph, e);
            }
            0
        },
    }
}

#[doc(hidden)]
pub unsafe fn hexchat_plugin_deinit<'ph, T>(plugin_handle: LtPhPtr<'ph>) -> c_int where T: Plugin<'ph> {
    let mut safe_to_unload = 1;
    // plugin_handle should never be null, but just in case.
    if !plugin_handle.ph.is_null() {
        let ph = plugin_handle.ph as *mut RawPh;
        // userdata should also never be null.
        if !(*ph).userdata.is_null() {
            {
                let mut info: Option<PluginInfo> = None;
                {
                    let mut ausinfo = AssertUnwindSafe(&mut info);
                    safe_to_unload = match catch_unwind(move || {
                        let mut userdata = pop_userdata(plugin_handle);
                        let pluginfo = userdata.pluginfo;
                        if let Err(e) = catch_unwind(AssertUnwindSafe(|| {
                            userdata.plug.as_mut().deinit(&mut {
                                PluginHandle::new(
                                    plugin_handle,
                                    pluginfo,
                                    Rc::clone(&userdata.contexts)
                                )
                            });
                        })) {
                            // panics in deinit may be retried.
                            // however, one may need to close hexchat if that
                            // happens.
                            put_userdata(plugin_handle, userdata);
                            std::panic::resume_unwind(e);
                        }
                        **ausinfo = Some(pluginfo);
                        drop(userdata);
                    }) {
                        Ok(_) => 1,
                        Err(e) => {
                            log_panic(ph, e);
                            0
                        }
                    };
                }
                if let Some(mut info) = info {
                    info.drop_info();
                    safe_to_unload = 1;
                }
            }
        } else {
            hexchat_print_str(ph, "plugin userdata was null, broken hexchat-unsafe-plugin?", false);
        }
    } else {
        // we are once again hoping for the best here.
        eprintln!("hexchat_plugin_deinit called with a null plugin_handle - broken hexchat");
        std::process::abort();
    }
    safe_to_unload
}

/// Exports a hexchat plugin.
#[macro_export]
macro_rules! hexchat_plugin {
    ($l:lifetime, $t:ty) => {
        #[no_mangle]
        pub unsafe extern "C" fn hexchat_plugin_init<$l>(plugin_handle: $crate::LtPhPtr<$l>,
                                              plugin_name: *mut *const $crate::c_char,
                                              plugin_desc: *mut *const $crate::c_char,
                                              plugin_version: *mut *const $crate::c_char,
                                              arg: *const $crate::c_char) -> $crate::c_int {
            $crate::hexchat_plugin_init::<$l, $t>(plugin_handle, plugin_name, plugin_desc, plugin_version, arg)
        }
        #[no_mangle]
        pub unsafe extern "C" fn hexchat_plugin_deinit<$l>(plugin_handle: $crate::LtPhPtr<$l>) -> $crate::c_int {
            $crate::hexchat_plugin_deinit::<$l, $t>(plugin_handle)
        }
        // unlike what the documentation states, there's no need to define hexchat_plugin_get_info.
        // so we don't. it'd be impossible to make it work well with rust anyway.
    };
}