Struct weechat::Weechat

pub struct Weechat { /* fields omitted */ }

Main Weechat struct that encapsulates common weechat API functions. It has a similar API as the weechat script API.

Implementations

impl Weechat

pub unsafe fn weechat() -> &'static mut Weechat

Get the Weechat plugin.

Safety

It is generally safe to call this method, the plugin pointer is valid for the durration of the plugin lifetime. The problem is that many Weechat objects need to have a lifetime bound to a Weechat context object that is only valid for the duration of a callback.

Since this one will have a static lifetime, objects that are fetched from this object may have a longer lifetime than they should.

pub fn log(msg: &str)

Write a message in WeeChat log file (weechat.log).

Panics

Panics if the method is not called from the main Weechat thread.

pub fn print(msg: &str)

Display a message on the core weechat buffer.

Panics

Panics if the method is not called from the main Weechat thread.

pub fn color(color_name: &str) -> &str

Return a string color code for display.

Arguments

color_name - name of the color

Panics

Panics if the method is not called from the main Weechat thread.

pub fn color_pair(foreground_color: &str, background_color: &str) -> String

Return a string color pair for display.

Arguments

foreground_color - Name of the color that should be used for the foreground.

background_color - Name of the color that should be used for the background.

Panics

Panics if the method is not called from the main Weechat thread.

pub fn prefix(prefix: &str) -> &str

Retrieve a prefix value

Arguments:

prefix - The name of the prefix.

Valid prefixes are:

• error
• network
• action
• join
• quit

An empty string will be returned if the prefix is not found

Panics

Panics if the method is not called from the main Weechat thread.

pub fn info_get(name: &str, arguments: &str) -> Option<String>

Get some info from Weechat or a plugin.

Arguments

• name - name the info

• arguments - arguments for the info

pub fn remove_color(string: &str) -> String

Remove WeeChat colors from a string.

Arguments

• string - The string that should be stripped from Weechat colors.

Panics

Panics if the method is not called from the main Weechat thread.

pub fn eval_string_expression(expression: &str) -> Result<String, ()>

Evaluate a Weechat expression and return the result.

Arguments

• expression - The expression that should be evaluated.

Panics

Panics if the method is not called from the main Weechat thread.

pub fn home_dir() -> PathBuf

Get the Weechat homedir.

pub fn execute_modifier(
    modifier: &str,
    modifier_data: &str,
    input_string: &str
) -> Result<String, ()>

Execute a modifier.

A modifier takes a string and modifies it in some way, Weechat has a list of defined modifiers. For example to parse a string with some color format (ansi, irc...) and to convert it to another format.

Returns the modified string or an empty error if the string couldn't be modified.

Arguments

• modifier - The name of a modifier. The list of modifiers can be found in the official Weechat documentation.

• modifier_data - Data that will be passed to the modifier, this depends on the modifier that was chosen, consult the list of modifiers in the Weechat documentation.

• input_string - The string that should be modified.

Panics

Panics if the method is not called from the main Weechat thread.

pub fn spawn<F, R>(future: F) -> JoinHandle<R, ()>ⓘ

Important traits for JoinHandle<R, T>

impl<R, T> Future for JoinHandle<R, T> type Output = Option<R>;

where
    F: Future<Output = R> + 'static,
    R: 'static, 

Spawn a new Future on the main Weechat thread.

Panics

Panics if the method is not called from the main Weechat thread.

Example

use weechat::Weechat;
use async_std::sync::{channel, Receiver};
use futures::executor::block_on;

pub async fn task(receiver: Receiver<String>) {
    loop {
        match receiver.recv().await {
            Ok(m) => {
                Weechat::print(&format!("Received message: {}", m));
            },
            Err(e) => {
                Weechat::print(
                    &format!("Error receiving on channel {:?}", e)
                );
                return;
            }
        }
    }
}

let (tx, rx) = channel(1000);

Weechat::spawn(task(rx));
block_on(tx.send("Hello wordl".to_string()));

pub fn spawn_from_thread<F>(future: F) where
    F: Future<Output = ()> + Send + 'static, 

Spawn a new Future on the main Weechat thread.

This can be called from any thread and will execute the future on the main Weechat thread.

impl Weechat

pub fn buffer_search(
    &self,
    plugin_name: &str,
    buffer_name: &str
) -> Option<Buffer>

Search a buffer by plugin and/or name.

Returns a Buffer if one is found, otherwise None.

Arguments

• plugin_name - name of a plugin, the following special value is allowed: "==", the buffer name used is the buffers full name.

• buffer_name - name of a buffer, if this is an empty string, the current buffer is returned (buffer displayed by current window); if the name starts with (?i), the search is case insensitive.

pub fn current_buffer(&self) -> Buffer

Get the currently open buffer

pub fn buffer_new_with_async(
    settings: BufferSettingsAsync
) -> Result<BufferHandle, ()>

Create a new Weechat buffer with an async input callback.

• settings - Settings for the new buffer.

Returns a Buffer if one has been created, otherwise an empty Error.

Panics

Panics if the method is not called from the main Weechat thread.

Example

fn input_cb(buffer: BufferHandle, input: String) -> LocalBoxFuture<'static, ()> {
    async move {
        let buffer = buffer.upgrade().unwrap();
        buffer.print(&input);
    }.boxed_local()
}

let buffer_settings = BufferSettingsAsync::new("test_buffer")
    .input_callback(input_cb)
    .close_callback(|weechat: &Weechat, buffer: &Buffer| {
        Ok(())
});

let buffer_handle = Weechat::buffer_new_with_async(buffer_settings)
    .expect("Can't create new room buffer");

let buffer = buffer_handle
    .upgrade()
    .expect("Can't upgrade newly created buffer");

buffer.enable_nicklist();
buffer.print("Hello world");

pub fn buffer_new(settings: BufferSettings) -> Result<BufferHandle, ()>

Create a new Weechat buffer

• settings - Settings for the new buffer.

Panics

Panics if the method is not called from the main Weechat thread.

Returns a Buffer if one has been created, otherwise an empty Error.

Example

fn input_cb(weechat: &Weechat, buffer: &Buffer, input: Cow<str>) -> Result<(), ()> {
    buffer.print(&input);
    Ok(())
}

let buffer_settings = BufferSettings::new("test_buffer")
    .input_callback(input_cb)
    .close_callback(|weechat: &Weechat, buffer: &Buffer| {
        Ok(())
});

let buffer_handle = Weechat::buffer_new(buffer_settings)
    .expect("Can't create new room buffer");

let buffer = buffer_handle
    .upgrade()
    .expect("Can't upgrade newly created buffer");

buffer.enable_nicklist();
buffer.print("Hello world");

impl Weechat

pub fn config_new(name: &str) -> Result<Config, ()>

Create a new Weechat configuration file, returns a Config object. The configuration file is freed when the Config object is dropped.

Arguments

• name - Name of the new configuration file

Panics

Panics if the method is not called from the main Weechat thread.

pub fn config_new_with_callback(
    name: &str,
    reload_callback: impl ConfigReloadCallback
) -> Result<Config, ()>

Create a new Weechat configuration file, returns a Config object. The configuration file is freed when the Config object is dropped.

Arguments

• name - Name of the new configuration file

• reload_callback - Callback that will be called when the configuration file is reloaded.

Examples

use weechat::Weechat;
use weechat::config::Conf;

let config = Weechat::config_new_with_callback("server_buffer",
    |weechat: &Weechat, conf: &Conf| {
        Weechat::print("Config was reloaded");
    }
);

Panics

Panics if the method is not called from the main Weechat thread.

pub fn config_get(&self, option_name: &str) -> Option<ConfigOption>

Search an option with a full name.

Arguments

• option_name - The full name of the option that should be searched for (format: "file.section.option").

pub fn get_plugin_option(&self, option: &str) -> Option<Cow<str>>

Get value of a plugin option

pub fn set_plugin_option(&self, option: &str, value: &str) -> OptionChanged

Set the value of a plugin option

impl Weechat

pub fn hook_signal_send<'a, D: Into<SignalData<'a>>>(
    signal_name: &str,
    data: D
) -> ReturnCode

Send a signal.

This will send out a signal and callbacks that are registered with a SignalHook to listen to that signal wil get called.

Arguments

• signal_name - The name of the signal that should be sent out. Common signals can be found in the Weechat plugin API reference.

• data - Data that should be provided to the signal callback. This can be a string, an i32 number, or a buffer.

// Fetch the chat history for the buffer.
Weechat::hook_signal_send("logger_backlog", buffer);

// Signal that the input text changed.
Weechat::hook_signal_send("input_text_changed", "");

impl Weechat

pub fn new_bar_item(
    name: &str,
    callback: impl BarItemCallback
) -> Result<BarItemHandle, ()>

Create a new bar item that can be added by a user.

Arguments

• name - The name of the new bar item.

• callback - The callback that should be called after the bar items is marked to be updated.

Panics

Panics if the method is not called from the main Weechat thread.

Example

let item = Weechat::new_bar_item("buffer_plugin", |weechat:&Weechat,
buffer: &Buffer| {
    "rust/sample".to_owned()
});

pub fn bar_item_update(name: &str)

Update the content of a bar item, by calling its build callback.

Arguments

• name - The name of the bar item that should be updated.

impl Weechat

pub fn hook_timer(
    &self,
    interval: Duration,
    align_second: i32,
    max_calls: i32,
    callback: impl TimerCallback + 'static
) -> Result<TimerHook, ()>

Create a timer that will repeatedly fire.

Arguments

• interval - The delay between calls in milliseconds.

• align_second - The alignment on a second. For example, if the current time is 09:00, if the interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute on the 0th second.

• max_calls - The number of times the callback should be called, 0 means it's called forever.

• callback - A function that will be called when the timer fires, the remaining argument will be -1 if the timer has no end.

• callback_data - Data that will be passed to the callback every time the callback runs. This data will be freed when the hook is unhooked.

impl Weechat

pub fn get_infolist(
    &self,
    infolist_name: &str,
    arguments: Option<&str>
) -> Result<Infolist, ()>

Get the infolist with the given name.

Arguments

• infolist_name - The name of the infolist to fetch, valid values for this can be found in the Weechat documentation.

• arguments - Arguments that should be passed to Weechat while fetching the infolist, the format of this will depend on the infolist that is being fetched. A list of infolists and their accompanying arguments can be found in the Weechat documentation.

Example

let infolist = weechat.get_infolist("logger_buffer", None).unwrap();

for item in infolist {
    let info_buffer = if let Some(buffer) = item.get("buffer") {
        buffer
    } else {
        continue;
    };

    if let InfolistVariable::Buffer(info_buffer) = info_buffer {
        info_buffer.print("Hello world");
    }
}