WeeChat / scripts API

register
print
print_infobar
add_message_handler
add_command_handler
remove_handler
command
get_info
get_dcc_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 )

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!")

print

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

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

Ruby 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 occured.

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")

print_infobar

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

Python prototype: weechat.print_infobar ( time, message )

Ruby 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 occured.

Examples:

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

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

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

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 )

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

  • function: function called when message is received

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

Examples:

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

# python
weechat.add_message_handler ("privmsg", my_function)
def ma_fonction(server, args):
    weechat.prnt("server="+serveur)
    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

Note: function called when message is received has to return one of following values (prefixed by weechat::" for Perl, "weechat." for Python or "Weechat." for Ruby):

  • 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] )

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

Paramètres :

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

  • function: fonction appelée lorsque la commande est exécutée

  • 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 occured.

Examples:

# perl
weechat::add_command_handler ("command", my_command);
sub my_command
{
    weechat::print("Server: $_[0], arguments: $_[1]\n");
    return weechat::PLUGIN_RC_OK;
}

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

Notes: function called when command is executed has to return one of following values (prefixed by "weechat::" for Perl, "weechat." for Python or "Weechat." for Ruby):

  • 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 )

Remove a handler.

Arguments:

  • name: name of IRC message or command

  • function: function

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

Examples:

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

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

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

command

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

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

Ruby 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 occured.

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")

get_info

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

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

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

Return an info about WeeChat or a channel.

Arguments:

Return value: information asked, empty string if an error occured

Examples:

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

# python
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 ( )

Return list of DCC currently active or finished.

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

get_config

Perl prototype: weechat::get_config ( option );

Python prototype: weechat.get_config ( option )

Ruby 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")

set_config

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

Python prototype: weechat.set_config ( option, value )

Ruby 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 occured.

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")

get_plugin_config

Perl prototype: weechat::get_plugin_config ( option );

Python prototype: weechat.get_plugin_config ( option )

Ruby 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")

set_plugin_config

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

Python prototype: weechat.set_plugin_config ( option, valeur )

Ruby prototype: Weechat.set_plugin_config ( option, valeur )

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 occured.

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")