WeeChat / scripts API

register
print
print_infobar
remove_infobar
log
add_message_handler
add_command_handler
add_timer_handler
remove_handler
remove_timer_handler
command
get_info
get_dcc_info
get_server_info
get_channel_info
get_nick_info
get_config
set_config
get_plugin_config
set_plugin_config

register

Perl prototype: weechat::register(name, version, end_function, description);

Python prototype: weechat.register(name, version, end_function, description)

Ruby prototype: Weechat.register(name, version, end_function, description)

Lua prototype: weechat.register(name, version, end_function, description)

This is first function to call in script. All WeeChat scripts have to call this function.

Arguments:

  • name: unique name to identify script (each script must have unique name)

  • version: script version

  • end_function: function called when script is unloaded (optional parameter, empty string means nothing is called at the end)

  • description: short description of script

Return value: 1 if script was registered, 0 if an error occured.

Examples:

# perl
weechat::register("test", "1.0", "end_test", "Test script!");

# python
weechat.register("test", "1.0", "end_test", "Test script!")

# ruby
Weechat.register("test", "1.0", "end_test", "Test script!")

-- lua
weechat.register("test", "1.0", "end_test", "Test script!")

print

Perl prototype: weechat::print(message, [channel, [server]])

Python prototype: weechat.prnt(message, [channel, [server]])

Ruby prototype: Weechat.print(message, [channel, [server]])

Lua prototype: weechat.print(message, [channel, [server]])

Display a message on a WeeChat buffer, identified by server and channel.

Arguments:

  • message: message

  • channel: name of channel to find buffer for message display

  • server: internal name of server to find buffer for message display

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::print("message");
weechat::print("message", "#weechat");
weechat::print("message", "#weechat", "freenode");

# python
weechat.prnt("message")
weechat.prnt("message", "#weechat")
weechat.prnt("message", "#weechat", "freenode")

# ruby
Weechat.print("message")
Weechat.print("message", "#weechat")
Weechat.print("message", "#weechat", "freenode")

-- lua
weechat.print("message")
weechat.print("message", "#weechat")
weechat.print("message", "#weechat", "freenode")

print_infobar

Perl prototype: weechat::print_infobar(time, message);

Python prototype: weechat.print_infobar(time, message)

Ruby prototype: Weechat.print_infobar(time, message)

Lua prototype: weechat.print_infobar(time, message)

Display a message in infobar for a specified time.

Arguments:

  • time: time (in seconds) for displaying message (0 = never erased)

  • message: message

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::print_infobar(5, "message");

# python
weechat.print_infobar(5, "message")

# ruby
Weechat.print_infobar(5, "message")

-- lua
weechat.print_infobar(5, "message")

remove_infobar

Perl prototype: weechat::remove_infobar([count]);

Python prototype: weechat.remove_infobar([count])

Ruby prototype: Weechat.remove_infobar([count])

Lua prototype: weechat.remove_infobar([count])

Remove one or more messages in infobar stack.

Arguments:

  • count: number of messages to remove (if argument not given or <= 0, then all messages are removed)

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::remove_infobar(1);

# python
weechat.remove_infobar(1)

# ruby
Weechat.remove_infobar(1)

-- lua
weechat.remove_infobar(1)

log

Perl prototype: weechat::log(message, [channel, [server]]);

Python prototype: weechat.log(message, [channel, [server]])

Ruby prototype: Weechat.log(message, [channel, [server]])

Lua prototype: weechat.log(message, [channel, [server]])

Write a message in log file for a server or a channel.

Arguments:

  • message: message

  • channel: name of channel to find buffer for log

  • server: internal name of server to find buffer for log

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::log("message", "#weechat", "freenode");

# python
weechat.log("message", "#weechat", "freenode")

# ruby
Weechat.log("message", "#weechat", "freenode")

-- lua
weechat.log("message", "#weechat", "freenode")

add_message_handler

Perl prototype: weechat::add_message_handler(message, function);

Python prototype: weechat.add_message_handler(message, function)

Ruby prototype: Weechat.add_message_handler(message, function)

Lua prototype: weechat.add_message_handler(message, function)

Add an IRC message handler, called when an IRC message is received.

Arguments:

  • message: name of IRC message. To know list of IRC messages, please consult RFCs 1459 and 2812. Moreover you can use a special name, prefixed by "weechat_" to catch special events (see the section called “msg_handler_add”).

  • function: function called when message is received

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::add_message_handler ("privmsg", "my_function");
sub my_function
{
    weechat::print("server=$_[0]");
    ($null, $channel, $message) = split ":",$_[1],3;
    ($mask, $null, $channel) = split " ", $channel;
    weechat::print("mask=$mask, channel=$channel, msg=$message");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_message_handler ("privmsg", "my_function")
def my_function(server, args):
    weechat.prnt("server="+server)
    null, channel, message = string.split(args, ":", 2)
    masque, null, channel = string.split(string.strip(channel), " ", 2)
    weechat.prnt("mask="+mask+", canal="+channel+", message="+message)
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_message_handler("privmsg", "my_function")
def my_function(server, args)
    Weechat.print("server=#{server}, args=#{args}")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_message_handler ("privmsg", "my_function")
function my_function(server, args)
    weechat.print("server=" .. server .. ", args=" .. args)
    return weechat.PLUGIN_RC_OK()
end

Note: function called when message is received has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

  • PLUGIN_RC_OK_IGNORE_WEECHAT: message will not be sent to WeeChat

  • PLUGIN_RC_OK_IGNORE_PLUGINS: message will not be sent to other plugins

  • PLUGIN_RC_OK_IGNORE_ALL: message will not be sent to WeeChat neither other plugins

add_command_handler

Perl prototype: weechat::add_command_handler(command, function, [description, arguments, arguments_description, completion_template]);

Python prototype: weechat.add_command_handler(command, function, [description, arguments, arguments_description, completion_template])

Ruby prototype: Weechat.add_command_handler(command, function, [description, arguments, arguments_description, completion_template])

Lua prototype: weechat.add_command_handler(command, function, [description, arguments, arguments_description, completion_template])

Add a WeeChat command handler, called when user uses command (for example /command).

Arguments:

  • command: the new command name, which may be an existing command (be careful, replaced command will not be available until script is unloaded)

  • function: function called when command is executed

  • arguments: short description of command arguments (displayed by /help command)

  • arguments_description: long description of command arguments (displayed by /help command)

  • completion_template: template for completion, like "abc|%w def|%i" which means "abc" or a WeeChat command for first argument, "def" or IRC command for second. (see the section called “cmd_handler_add”)

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::add_command_handler("command", "my_command");
sub my_command
{
    weechat::print("server= $_[0], args: $_[1]");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_command_handler("command", "my_command")
def my_command(server, args):
    weechat.prnt("server="+server+", args="+args)
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_command_handler("command", "my_command")
def my_command(server, args)
    Weechat.print("server=#{server}, args=#{args}")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_command_handler("command", "my_command")
def my_command(server, args)
    weechat.print("server="..server..", args="..args)
    return weechat.PLUGIN_RC_OK()
end

Notes: function called when command is executed has to return one of following values:

  • PLUGIN_RC_KO : function failed

  • PLUGIN_RC_OK : function successfully completed

add_timer_handler

Perl prototype: weechat::add_timer_handler(message, function);

Python prototype: weechat.add_timer_handler(message, function)

Ruby prototype: Weechat.add_timer_handler(message, function)

Lua prototype: weechat.add_timer_handler(message, function)

Add a timer handler which periodically calls a function.

Arguments:

  • interval: interval (in seconds) between two calls of function.

  • function: function called

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::add_timer_handler(60, "my_timer");
sub my_timer
{
    weechat::print("this is timer handler");
    return weechat::PLUGIN_RC_OK;
}

# python
weechat.add_timer_handler(60, "my_timer")
def my_timer(server, args):
    weechat.prnt("this is timer handler")
    return weechat.PLUGIN_RC_OK

# ruby
Weechat.add_timer_handler(60, "my_timer")
def my_timer(server, args)
    Weechat.print("this is timer handler")
    return Weechat::PLUGIN_RC_OK
end

-- lua
weechat.add_timer_handler(60, "my_timer")
function my_timer(server, args)
    weechat.print("this is timer handler)
    return weechat.PLUGIN_RC_OK()
end

Note: function called has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

remove_handler

Perl prototype: weechat::remove_handler(name, function);

Python prototype: weechat.remove_handler(name, function)

Ruby prototype: Weechat.remove_handler(name, function)

Lua prototype: weechat.remove_handler(name, function)

Remove a message or command handler.

Arguments:

  • name: name of IRC message or command

  • function: function

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::remove_handler("command", "my_command");

# python
weechat.remove_handler("command", "my_command")

# ruby
Weechat.remove_handler("command", "my_command")

-- lua
weechat.remove_handler("command", "my_command")

remove_timer_handler

Perl prototype: weechat::remove_timer_handler(function);

Python prototype: weechat.remove_timer_handler(function)

Ruby prototype: Weechat.remove_timer_handler(function)

Lua prototype: weechat.remove_timer_handler(function)

Remove a timer handler.

Arguments:

  • function: function

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::remove_timer_handler("my_timer");

# python
weechat.remove_timer_handler("my_timer")

# ruby
Weechat.remove_timer_handler("my_timer")

-- lua
weechat.remove_timer_handler("my_timer")

command

Perl prototype: weechat::command(command, [channel, [server]]);

Python prototype: weechat.command(command, [channel, [server]])

Ruby prototype: Weechat.command(command, [channel, [server]])

Lua prototype: weechat.command(command, [channel, [server]])

Execute a WeeChat command (or send a message to a channel).

Arguments:

  • command: command

  • channel: name of channel for executing command

  • server: internal name of server for executing command

Return value: 1 if success, 0 if an error occurred.

Examples:

# perl
weechat::command("hello everybody!");
weechat::command("/kick toto please leave this channel", "#weechat");
weechat::command("/nick newnick", "", "freenode");

# python
weechat.command("hello everybody!")
weechat.command("/kick toto please leave this channel", "#weechat")
weechat.command("/nick newnick", "", "freenode")

# ruby
Weechat.command("hello everybody!")
Weechat.command("/kick toto please leave this channel", "#weechat")
Weechat.command("/nick newnick", "", "freenode")

-- lua
weechat.command("hello everybody!")
weechat.command("/kick toto please leave this channel", "#weechat")
weechat.command("/nick newnick", "", "freenode")

get_info

Perl prototype: weechat::get_info(name, [server]);

Python prototype: weechat.get_info(name, [server])

Ruby prototype: Weechat.get_info(name, [server])

Lua prototype: weechat.get_info(name, [server])

Return an info about WeeChat or a channel.

Arguments:

Return value: information asked, empty string if an error occurred.

Examples:

# perl
$version = get_info("version");
$nick = get_info("nick", "freenode");

# python
version = weechat.get_info("version")
nick = weechat.get_info("nick", "freenode")

# ruby
version = Weechat.get_info("version")
nick = Weechat.get_info("nick", "freenode")

-- lua
version = weechat.get_info("version")
nick = weechat.get_info("nick", "freenode")

get_dcc_info

Perl prototype: weechat::get_dcc_info();

Python prototype: weechat.get_dcc_info()

Ruby prototype: Weechat.get_dcc_info()

Lua prototype: weechat.get_dcc_info()

Return list of DCC currently active or finished.

Return value: list of DCC (see the section called “get_dcc_info”).

Examples:

# perl
my @dccs = weechat::get_dcc_info();
if (@dccs)
{
    foreach my $dcc (@dccs)
    {
        while (my ($key, $value) = each %$dcc)
        {
            weechat::print("$key = '$value'");
        }
    }
}
else
{
    weechat::print("no DCC");
}

# python
dccs = weechat.get_dcc_info()
if dccs != None:
    if dccs == []:
        weechat.prnt("no DCC")
    else:
        for d in dccs:
            for b in d.keys():
                weechat.prnt("%s = '%s'" %(b, d[b]))
else:
    weechat.prnt("error while getting DCC")

# ruby
dccs = Weechat.get_dcc_info()
if dccs != nil   
    if dccs == []
        Weechat.print("no DCC")
    else
        dccs.each do |m|
            m.each do |key, value|
                Weechat.print("#{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting DCC")
end

-- lua
dccs = weechat.get_dcc_info()
if dccs ~= nil then
    if dccs then
        dcc, dccinfos = next (dccs, nil)
        while (dcc) do
            key, value = next (dccinfos, nil)
            while (key) do
                weechat.print(key.." = '"..value.."'")
                key, value = next (dccinfos, key)
            end
            dcc, dccinfos = next (dccs, dcc)
        end 
    else
        weechat.print("no DCC")
    end
else
    weechat.print("error while getting DCC")
end

get_server_info

Perl prototype: weechat::get_server_info();

Python prototype: weechat.get_server_info()

Ruby prototype: Weechat.get_server_info()

Lua prototype: weechat.get_server_info()

Return list of IRC servers (connected or not).

Return value: list of servers (see the section called “get_server_info”).

Examples:

# perl
my $servers = weechat::get_server_info();
if ($servers)
{
    while (my ($srvname, $srvinfos) = each %$servers)
    {
        while ( my ($key, $value) = each %$srvinfos)
        {
            weechat::print("$srvname -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no server");
}

# python
servers = weechat.get_server_info()
if servers != None:
    if servers == {}:
        weechat.prnt("no server")
    else:
        for s in servers:
            for i in servers[s]:
                weechat.prnt("%s -> %s = '%s'" % (s, i, str(servers[s][i])))
else:
    weechat.prnt("error while getting servers")

# ruby
servers = Weechat.get_server_info()
if servers != nil
    if servers == []
        Weechat.print("no server")
    else
        servers.each do |n, s|
            s.each do |key, value|
                Weechat.print("#{n} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting servers")
end

-- lua
servers = weechat.get_server_info()
if servers ~= nil then
    if servers then
        srv, srvinfos = next (servers, nil)
        while (srv) do
            key, value = next (srvinfos, nil)
            while (key) do
                weechat.print(srv.." -> "..key.." = '"..value.."'")
                key, value = next (srvinfos, key)
            end	
            srv, srvinfos = next (servers, srv)
        end
    else
        weechat.print("no server")
    end
else
    weechat.print("error while getting servers")
end

get_channel_info

Perl prototype: weechat::get_channel_info(server);

Python prototype: weechat.get_channel_info(server)

Ruby prototype: Weechat.get_channel_info(server)

Lua prototype: weechat.get_channel_info(server)

Return list of IRC channels for a server.

Return value: list of IRC channels for server (see the section called “get_channel_info”).

Examples:

# perl
my $channels = weechat::get_channel_info(weechat::get_info("server"));
if ($channels)
{
    while (my ($channame, $chaninfos) = each %$channels)
    {
        while (my ($key, $value) = each %$chaninfos)
        {
            weechat::print("$channame -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no channel");
}

# python
chans = weechat.get_channel_info(weechat.get_info("server"))
if chans != None:
    if chans == {}:
        weechat.prnt("no channel")
    else:
        for s in chans:
            for i in chans[s]:
                weechat.prnt("%s -> %s = '%s'" % (s, i, str(chans[s][i])))
else:
    weechat.prnt("error while getting channels")

# ruby
channels = Weechat.get_channel_info(Weechat.get_info("server"))
if channels != nil
    if channels == {}
        Weechat.print("no channel")
    else
        channels.each do |n, c|
            c.each do |key, value|
                Weechat.print("#{n} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting channels")
end

-- lua
chans = weechat.get_channel_info(weechat.get_info("server"))
if chans ~= nil then
    if chans then
        chan, chaninfos = next (chans, nil)
        while (chan) do
            key, value = next (chaninfos, nil)
            while (key) do
                weechat.print(chan.." -> "..key.." = '"..value.."'")
                key, value = next (chaninfos, key)
            end
            chan, chaninfos = next (chans, chan)
        end
    else
        weechat.print("no channel")
    end
else
    weechat.print("error while getting channels")
end

get_nick_info

Perl prototype: weechat::get_nick_info(server, channel);

Python prototype: weechat.get_nick_info(server, channel)

Ruby prototype: Weechat.get_nick_info(server, channel)

Lua prototype: weechat.get_nick_info(server, channel)

Return list of nicks for a channel.

Return value: list of nicks on channel (see the section called “get_nick_info”).

Examples:

# perl
my $nicks = weechat::get_nick_info("freenode", "#weechat");
if ($nicks)
{
    while (my ($nickname, $nickinfos) = each %$nicks)
    {
        while ( my ($key, $value) = each %$nickinfos)
        {
            weechat::print("$nickname -> $key = '$value'");
        }
    }
}
else
{
    weechat::print("no nick");
}

# python
nicks = weechat.get_nick_info("freenode", "#weechat")
if nicks != None:
    if nicks == {}:
        weechat.prnt("no nick")
    else:
        for n in nicks:
            for f in nicks[n]:
                weechat.prnt("%s -> %s = '%s'" % (n, f, str(nicks[n][f])))
else:
    weechat.prnt("error while getting nicks")

# ruby
nicks = Weechat.get_nick_info("freenode", "#weechat")
if nicks != nil
    if nicks == {}
        Weechat.print("no nick")
    else
        nicks.each do |nk, nattr|
            nattr.each do |key, value|
                Weechat.print("#{nk} -> #{key} = '#{value}'")
            end
        end
    end
else
    Weechat.print("error while getting nicks")
end

-- lua
nicks = weechat.get_nick_info("freenode", "#weechat")
if nicks ~= nil then
    if nicks then	
        nick, nickinfos = next (nicks, nil)
        while (nick) do
            key, value = next (nickinfos, nil)
            while (key) do
                weechat.print(nick.." -> "..key.." = '"..value.."'")
                key, value = next (nickinfos, key)
            end
            nick, nickinfos = next (nicks, nick)
        end
    else
        weechat.print("no nick")
    end
else
    weechat.print("error while getting nicks")
end

get_config

Perl prototype: weechat::get_config(option);

Python prototype: weechat.get_config(option)

Ruby prototype: Weechat.get_config(option)

Lua prototype: weechat.get_config(option)

Return value of a WeeChat config option.

Arguments:

  • option: name of option to read

Return value: option value, empty string if not found.

Examples:

# perl
$value1 = weechat::get_config("look_nicklist");
$value2 = weechat::get_config("freenode.server_autojoin");

# python
value1 = weechat.get_config("look_nicklist")
value2 = weechat.get_config("freenode.server_autojoin")

# ruby
value1 = Weechat.get_config("look_nicklist")
value2 = Weechat.get_config("freenode.server_autojoin")

-- lua
value1 = weechat.get_config("look_nicklist")
value2 = weechat.get_config("freenode.server_autojoin")

set_config

Perl prototype: weechat::set_config(option, value);

Python prototype: weechat.set_config(option, value)

Ruby prototype: Weechat.set_config(option, value)

Lua prototype: weechat.set_config(option, value)

Update value of a WeeChat config option.

Arguments:

  • option: name of option to update

  • value: new value for option

Return value: 1 if option was successfully updated, 0 if an error occurred.

Examples:

# perl
weechat::set_config("look_nicklist", "off");
weechat::set_config("freenode.server_autojoin, "#weechat");

# python
weechat.set_config("look_nicklist", "off")
weechat.set_config("freenode.server_autojoin, "#weechat")

# ruby
Weechat.set_config("look_nicklist", "off")
Weechat.set_config("freenode.server_autojoin, "#weechat")

-- lua
weechat.set_config("look_nicklist", "off")
weechat.set_config("freenode.server_autojoin, "#weechat")

get_plugin_config

Perl prototype: weechat::get_plugin_config(option);

Python prototype: weechat.get_plugin_config(option)

Ruby prototype: Weechat.get_plugin_config(option)

Lua prototype: weechat.get_plugin_config(option)

Return value of a plugin option. Option is read from file "~/.weechat/plugins.rc" and is like: "plugin.option=value" (note: plugin name is automatically added).

Arguments:

  • option: name of option to read

Return value: value of option, empty string if not found.

Examples :

# perl
$value = weechat::get_plugin_config("my_var");

# python
value = weechat.get_plugin_config("my_var")

# ruby
value = Weechat.get_plugin_config("my_var")

-- lua
value = weechat.get_plugin_config("my_var")

set_plugin_config

Perl prototype: weechat::set_plugin_config(option, value);

Python prototype: weechat.set_plugin_config(option, value)

Ruby prototype: Weechat.set_plugin_config(option, value)

Lua prototype: weechat.set_plugin_config(option, value)

Update value of a plugin option. Option is written in file "~/.weechat/plugins.rc" and is like: "plugin.option=value" (note: plugin name is automatically added).

Arguments:

  • option: name of option to update

  • value: new value for option

Return value: 1 if option was successfully updated, 0 if an error occurred.

Examples:

# perl
weechat::set_plugin_config("my_var", "value");

# python
weechat.set_plugin_config("my_var", "value")

# ruby
Weechat.set_plugin_config("my_var", "value")

-- lua
weechat.set_plugin_config("my_var", "value")