WeeChat Plugin API Reference

This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page: http://www.weechat.org/doc

1. Introduction

WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems.

This manual documents WeeChat plugins API, used by C plugins to interact with WeeChat core.

2. Plugins in WeeChat

A plugin is a C program which can call WeeChat functions defined in an interface.

This C program does not need WeeChat sources to compile and can be dynamically loaded into WeeChat with command /plugin.

The plugin has to be a dynamic library, for dynamic loading by operating system. Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.

The plugin has to include "weechat-plugin.h" file (available in WeeChat source code). This file defines structures and types used to communicate with WeeChat.

2.1. Macros

The plugin must use some macros (to define some variables):

WEECHAT_PLUGIN_NAME("name"): plugin name
WEECHAT_PLUGIN_DESCRIPTION("description"): short description of plugin
WEECHAT_PLUGIN_VERSION("1.0"): plugin version
WEECHAT_PLUGIN_LICENSE("GPL3"): plugin license

2.2. Main functions

The plugin must use two functions:

weechat_plugin_init
weechat_plugin_end

2.2.1. weechat_plugin_init

This function is called when plugin is loaded by WeeChat.

Prototype:

int weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[]);

Arguments:

plugin: pointer to WeeChat plugin structure
argc: number of arguments for plugin (given on command line by user)
argv: arguments for plugin

Return value:

WEECHAT_RC_OK if successful (plugin will be loaded)
WEECHAT_RC_ERROR if error (plugin will NOT be loaded)

2.2.2. weechat_plugin_end

This function is called when plugin is unloaded by WeeChat.

Prototype:

int weechat_plugin_end (struct t_weechat_plugin *plugin);

Arguments:

plugin: pointer to WeeChat plugin structure

Return value:

WEECHAT_RC_OK if successful
WEECHAT_RC_ERROR if error

2.3. Compile plugin

Compile does not need WeeChat sources, only file weechat-plugin.h is required.

To compile a plugin which has one file "toto.c" (under GNU/Linux):

$ gcc -fPIC -Wall -c toto.c
$ gcc -shared -fPIC -o libtoto.so toto.o

2.4. Load plugin

Copy file libtoto.so into system plugins directory (for example /usr/local/lib/weechat/plugins) or into user’s plugins directory (for example /home/xxx/.weechat/plugins).

Under WeeChat:

/plugin load toto

2.5. Plugin example

Full example of plugin, which adds a command /double: displays two times arguments on current buffer, or execute two times a command (ok that’s not very useful, but that’s just an example!):

#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


/* callback for command "/double" */

int
command_double_cb (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* make C compiler happy */
    (void) data;
    (void) buffer;
    (void) argv;

    if (argc > 1)
    {
        weechat_command (NULL, argv_eol[1]);
        weechat_command (NULL, argv_eol[1]);
    }

    return WEECHAT_RC_OK;
}

int
weechat_plugin_init (struct t_weechat_plugin *plugin,
                     int argc, char *argv[])
{
    weechat_plugin = plugin;

    weechat_hook_command ("double",
                          "Display two times a message "
                          "or execute two times a command",
                          "message | command",
                          "message: message to display two times\n"
                          "command: command to execute two times",
                          NULL,
                          &command_double_cb, NULL);

    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* make C compiler happy */
    (void) plugin;

    return WEECHAT_RC_OK;
}

3. Plugin API

Following chapters describe functions in API, sorted by category.

For each function, we give:

description of function,
C prototype,
detail of arguments,
return value,
C example,
example in Python script (syntax for other scripting languages is similar).

3.1. Plugins

Functions to get infos about plugins.

3.1.1. weechat_plugin_get_name

Get plugin name.

Prototype:

const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

Arguments:

plugin: pointer to WeeChat plugin structure (can be NULL)

Return value:

name of plugin, "core" for WeeChat core (if plugin pointer is NULL)

C example:

const char *name = weechat_plugin_get_name (plugin);

Script (Python):

# prototype
name = weechat.plugin_get_name(plugin)

# example
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
name = weechat.plugin_get_name(plugin)

3.2. Strings

Many string functions below are already available thru standard C functions, but it’s recommended to use functions in this API because they are ok with UTF-8 and locale.

3.2.1. weechat_charset_set

Set new plugin charset (default charset is UTF-8, so if your plugin uses UTF-8, you don’t need to call this function).

Prototype:

void weechat_charset_set (const char *charset);

Arguments:

charset: new charset to use

C example:

weechat_charset_set (plugin, "iso-8859-1");

Script (Python):

# prototype
weechat.charset_set(charset)

# example
weechat.charset_set("iso-8859-1")

3.2.2. weechat_iconv_to_internal

Convert string to WeeChat internal charset (UTF-8).

Prototype:

char *weechat_iconv_to_internal (const char *charset, const char *string);

Arguments:

charset: charset to convert
string: string to convert

Return value:

converted string (must be freed by calling "free" after use)

C example:

char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.iconv_to_internal(charset, string)

# example
str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")

3.2.3. weechat_iconv_from_internal

Convert string from internal WeeChat charset (UTF-8) to another.

Prototype:

char *weechat_iconv_from_internal (const char *charset, const char *string);

Arguments:

charset: target charset
string: string to convert

Return value:

converted string (must be freed by calling "free" after use)

C example:

char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.iconv_from_internal(charset, string)

# example
str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")

3.2.4. weechat_gettext

Return translated string (depends on local language).

Prototype:

const char *weechat_gettext (const char *string);

Arguments:

string: string to translate

Return value:

translated string

C example:

char *str = weechat_gettext ("hello");

Script (Python):

# prototype
str = weechat.gettext(string)

# example
str = weechat.gettext("hello")

3.2.5. weechat_ngettext

Return translated string, using single or plural form, according to count argument.

Prototype:

const char *weechat_ngettext (const char *string, const char *plural,
                              int count);

Arguments:

string: string to translate, single form
plural: string to translate, plural form
count: used to choose between single and plural form (choice is made according to local language)

Return value:

translated string

C example:

char *str = weechat_ngettext ("file", "files", num_files);

Script (Python):

# prototype
str = weechat.ngettext(string, plural, count)

# example
num_files = 2
str = weechat.ngettext("file", "files", num_files)

3.2.6. weechat_strndup

Return duplicated string, with length chars max.

Prototype:

char *weechat_strndup (const char *string, int length);

Arguments:

string: string to duplicate
length: max chars to duplicate

Return value:

duplicated string (must be freed by calling "free" after use)

C example:

char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */
/* ... */
free (str);

3.2.7. weechat_string_tolower

Convert UTF-8 string to lower case.

Prototype:

void weechat_string_tolower (const char *string);

Arguments:

string: string to convert

C example:

char *str = "AbCdé";
weechat_string_tolower (str); /* str is now: "abcdé" */

3.2.8. weechat_string_toupper

Convert UTF-8 string to upper case.

Prototype:

void weechat_string_toupper (const char *string);

Arguments:

string: string to convert

C example:

char *str = "AbCdé";
weechat_string_tolower (str); /* str is now: "ABCDé" */

3.2.9. weechat_strcasecmp

Locale and case independent string comparison.

Prototype:

int weechat_strcasecmp (const char *string1, const char *string2);

Arguments:

string1: first string for comparison
string2: second string for comparison

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */

3.2.10. weechat_strcmp_ignore_chars

Locale (and optionally case independent) string comparison, ignoring some chars.

Prototype:

int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);

Arguments:

string1: first string for comparison
string2: second string for comparison
chars_ignored: string with chars to ignored
case_sensitive: 1 for case sensitive comparison, otherwise 0

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */

3.2.11. weechat_strcasestr

Locale and case independent string search.

Prototype:

char *weechat_strcasestr (const char *string, const char *search);

Arguments:

string: string
search: string to search in string

Return value:

pointer to string found, or NULL if not found

C example:

char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */

3.2.12. weechat_string_match

Check if a string matches a mask.

Prototype:

int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);

Arguments:

string: string
mask: mask, can begin or end with "*" (no other "*" are allowed inside mask)

Return value:

1 if string matches mask, otherwise 0

C example:

int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */
int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */
int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */
int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */

3.2.13. weechat_string_replace

Replace all occurences of a string by another string.

Prototype:

char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);

Arguments:

string: string
search: string to replace
replace: replacement for string search

Return value:

string with search replaced by replace (must be freed by calling "free" after use)

C example:

char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */
/* ... */
free (str);

3.2.14. weechat_string_remove_quotes

Remove quotes at beginning and end of string (ignore spaces if there are before first quote or after last quote).

Prototype:

char *weechat_string_remove_quotes (const char *string, const char *quotes);

Arguments:

string: string
quotes: string with list of quotes

Return value:

string without quotes at beginning/end (must be freed by calling "free" after use)

C example:

char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'");
/* result: "I can't" */
/* ... */
free (str);

3.2.15. weechat_string_strip

Strip chars at beginning and/or end of string.

Prototype:

char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);

Arguments:

string: string
left: strip left chars if different from 0
right: strip right chars if different from 0
chars: string with chars to strip

Return value:

stripped string (must be freed by calling "free" after use)

C example:

char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* result: ".abc" */
/* ... */
free (str);

3.2.16. weechat_string_has_highlight

Check if a string has one or more highlights, using list of highlight words.

Prototype:

int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);

Arguments:

string: string
highlight_words: list of highlight words, separated by comma

Return value:

1 if string has one or more highlights, otherwise 0

C example:

int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */

3.2.17. weechat_string_mask_to_regex

Return a regex, built with a mask, where only special char is "*". All other special chars for regex are escaped.

Prototype:

char *weechat_string_mask_to_regex (const char *mask);

Arguments:

mask: mask

Return value:

regular expression, as string (must be freed by calling "free" after use)

C example:

char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);

3.2.18. weechat_string_split

Split a string according to one or more delimiter(s).

Prototype:

char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);

Arguments:

string: string to split
separators: delimiters used for split
keep_eol: if different from 0, then each argument will contain all string until end of line (see example below)
num_items_max: maximum number of items created (0 = no limit)
num_items: pointer to int which will contain number of items created

Return value:

array of strings, NULL if problem (must be freed by calling [_weechat_string_free_split] after use)

Examples:

char **argv;
int argc;
argv = weechat_string_split ("abc de  fghi", " ", 0, 0, &argc);
/* result: argv[0] == "abc"
           argv[1] == "de"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi", " ", 1, 0, &argc);
/* result: argv[0] == "abc de  fghi"
           argv[1] == "de  fghi"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

3.2.19. weechat_string_free_split

Free memory used by a split string.

Prototype:

void weechat_string_free_split (char **split_string);

Arguments:

split_string: string split by function [_weechat_string_split]

C example:

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);

3.2.20. weechat_string_build_with_split_string

Build a string with a split string.

Prototype:

char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);

Arguments:

split_string: string split by function [_weechat_string_split]
separator: string used to separate strings

Return value:

string built with split string (must be freed by calling "free" after use)

C example:

char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (argv, ";");
/* str == "abc;def;ghi" */
/* ... */
free (str);

3.2.21. weechat_string_split_command

Split a list of commands separated by separator (which can be escaped by "\" in string).

Prototype:

char **weechat_string_split_command (const char *command, char separator);

Arguments:

command: command to split
separator: separator

Return value:

array of strings, NULL if problem (must be freed by calling [_weechat_free_split_command] after use)

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
*/
weechat_free_split_command (argv);

3.2.22. weechat_string_free_split_command

Free memory used by a split command.

Prototype:

void weechat_string_free_split_command (char **split_command);

Arguments:

split_command: command split by [_weechat_string_split_command]

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);

3.2.23. weechat_string_format_size

Build a string with formatted file size and a unit translated to local language.

Prototype:

char *weechat_string_format_size (unsigned long size);

Arguments:

size: size (in bytes)

Return value:

formatted string (must be freed by calling "free" after use)

Examples:

/* examples with english locale */

char *str = weechat_string_format_size (0); /* str == "0 byte" */
/* ... */
free (str);

char *str = weechat_string_format_size (200); /* str == "200 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (1536); /* str == "1.5 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152); /* str == "2 MB" */
/* ... */
free (str);

3.2.24. weechat_string_remove_color

Remove WeeChat colors from a string.

Prototype:

char *weechat_string_remove_color (const char *string,
                                   const char *replacement);

Arguments:

string: string
replacement: if not NULL and not empty, WeeChat color codes are replaced by first char of this string, otherwise WeeChat color codes and following chars (if related to color) are removed from string

Return value:

string without color (must be freed by calling "free" after use)

Examples:

/* remove color codes */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* replace color codes by "?" */
char *str = weechat_string_remove_color (my_string2, "?");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.string_remove_color(string, replacement)

# example
str = weechat.string_remove_color(my_string, "?")

3.3. UTF-8

Some UTF-8 string functions.

3.3.1. weechat_utf8_has_8bits

Check if a string has 8-bits chars.

Prototype:

int weechat_utf8_has_8bits (const char *string);

Arguments:

string: string

Return value:

1 if string has 8-bits chars, 0 if only 7-bits chars

C example:

if (weechat_utf8_has_8bits (string))
{
    /* ... */
}

3.3.2. weechat_utf8_is_valid

Check if a string is UTF-8 valid.

Prototype:

int weechat_utf8_is_valid (const char *string, char **error);

Arguments:

string: string
error: if not NULL, error is set with pointer to first non valid UTF-8 char in string, if any

Return value:

1 if UTF-8 string is valid, otherwise 0

C example:

char *error;
if (weechat_utf8_is_valid (string, &error))
{
    /* ... */
}
else
{
    /* "error" points to first invalid char */
}

3.3.3. weechat_utf8_normalize

Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char.

Prototype:

void weechat_utf8_normalize (const char *string, char replacement);

Arguments:

string: string
replacement: replacement char for invalid chars

C example:

weechat_utf8_normalize (string, '?');

3.3.4. weechat_utf8_prev_char

Return pointer to previous UTF-8 char in a string.

Prototype:

char *weechat_utf8_prev_char (const char *string_start, const char *string);

Arguments:

string_start: start of string (function will not return a char before this pointer)
string: pointer to string (must be > = string_start)

Return value:

pointer to previous UTF-8 char, NULL if not found (start of string reached)

C example:

char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

3.3.5. weechat_utf8_next_char

Return pointer to next UTF-8 char in a string.

Prototype:

char *weechat_utf8_next_char (const char *string);

Arguments:

string: string

Return value:

pointer to next UTF-8 char, NULL if not found (end of string reached)

C example:

char *next_char = weechat_utf8_next_char (string);

3.3.6. weechat_utf8_char_size

Return UTF-8 char size (in bytes).

Prototype:

int weechat_utf8_char_size (const char *string);

Arguments:

string: string

Return value:

UTF-8 char size (in bytes)

C example:

int char_size = weechat_utf8_char_size ("être"); /* == 2 */

3.3.7. weechat_utf8_strlen

Return UTF-8 string length (in UTF-8 chars).

Prototype:

int weechat_utf8_strlen (const char *string);

Arguments:

string: string

Return value:

UTF-8 string length (number of UTF-8 chars)

C example:

int length = weechat_utf8_strlen ("chêne"); /* == 5 */

3.3.8. weechat_utf8_strnlen

Return UTF-8 string length (in UTF-8 chars), for max bytes in string.

Prototype:

int weechat_utf8_strnlen (const char *string, int bytes);

Arguments:

string: string
bytes: max bytes

Return value:

UTF-8 string length (number of UTF-8 chars)

C example:

int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */

3.3.9. weechat_utf8_strlen_screen

Return number of chars needed on screen to display UTF-8 string.

Prototype:

int weechat_utf8_strlen_screen (const char *string);

Arguments:

string: string

Return value:

number of chars needed on screen to display UTF-8 string

C example:

int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */

3.3.10. weechat_utf8_charcasecmp

Compare two UTF-8 chars, ignoring case.

Prototype:

int weechat_utf8_charcasecmp (const char *string1, const char *string2);

Arguments:

string1: first string for comparison
string2: second string for comparison

Return value:

difference between first char of each string:
- negative if char1 < char2
- zero if char1 == char2
- positive if char1 > char2

C example:

int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */

3.3.11. weechat_utf8_char_size_screen

Return number of chars needed on screen to display UTF-8 char.

Prototype:

int weechat_utf8_char_size_screen (const char *string);

Arguments:

string: string

Return value:

number of chars needed on screen to display UTF-8 char

C example:

int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */

3.3.12. weechat_utf8_add_offset

Move forward N chars in an UTF-8 string.

Prototype:

char *weechat_utf8_add_offset (const char *string, int offset);

Arguments:

string: string
offset: number of chars

Return value:

pointer to string, N chars after (NULL if it’s not reachable)

C example:

char *str = "chêne";
char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */

3.3.13. weechat_utf8_real_pos

Return real position in UTF-8 string.

Prototype:

int weechat_utf8_real_pos (const char *string, int pos);

Arguments:

string: string
pos: position (number of chars)

Return value:

real potision (in bytes)

C example:

int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */

3.3.14. weechat_utf8_pos

Return position in UTF-8 string.

Prototype:

int weechat_utf8_pos (const char *string, int real_pos);

Arguments:

string: string
real_pos: position (bytes)

Return value:

position (number of chars)

C example:

int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */

3.3.15. weechat_utf8_strndup

Return duplicate string, with length chars max.

Prototype:

char *weechat_utf8_strndup (const char *string, int length);

Arguments:

string: string
length: max chars to duplicate

Return value:

duplicated string (must be freed by calling "free" after use)

C example:

char *string = weechat_utf8_strndup ("chêne", 3); /* returns "chê" */
/* ... */
free (string);

3.4. Directories

Some functions related to directories.

3.4.1. weechat_mkdir_home

Create a directory in WeeChat home.

Prototype:

int weechat_mkdir_home (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occured

C example:

if (!weechat_mkdir_home ("temp", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir_home(directory, mode)

# example
weechat.mkdir_home("temp", 0755)

3.4.2. weechat_mkdir

Create a directory.

Prototype:

int weechat_mkdir (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occured

C example:

if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir(directory, mode)

# example
weechat.mkdir("/tmp/mydir", 0755)

3.4.3. weechat_mkdir_parents

Create a directory and make parent directories as needed.

Prototype:

int weechat_mkdir_parents (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occured

C example:

if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir_parents(directory, mode)

# example
weechat.mkdir_parents("/tmp/my/dir", 0755)

3.4.4. weechat_exec_on_files

Find files in a directory and execute a callback on each file.

Prototype:

void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void *data,
                            void (*callback)(void *data,
                                             const char *filename));

Arguments:

directory: directory for searching files
hidden_files: 1 to include hidden files, otherwise 0
data: pointer given to callback when it is called by WeeChat
callback: function called for each file found, arguments:
- void *data: pointer
- const char *filename: filename found

C example:

void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, NULL, &callback);

3.5. Util

Some useful functions.

3.5.1. weechat_timeval_cmp

Compare two "timeval" structures.

Prototype:

int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2);

Arguments:

tv1: first "timeval" structure
tv2: second "timeval" structure

Return value:

-1 if tv1 < tv2
zero if tv1 == tv2
+1 if tv1 > tv2

C example:

if (weechat_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}

3.5.2. weechat_timeval_diff

Return difference (in milliseconds) between two "timeval" structures.

Prototype:

long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2);

Arguments:

tv1: first "timeval" structure
tv2: second "timeval" structure

Return value:

difference in milliseconds

C example:

long diff = weechat_timeval_diff (&tv1, &tv2);

3.5.3. weechat_timeval_add

Add interval (in milliseconds) to a timeval structure.

Prototype:

void weechat_timeval_add (struct timeval *tv, long interval);

Arguments:

tv: timeval structure
interval: interval (in milliseconds)

C example:

weechat_timeval_add (&tv, 2000); /* add 2 seconds */

3.6. Sorted lists

Sorted list functions.

3.6.1. weechat_list_new

Create a new list.

Prototype:

struct t_weelist *weechat_list_new ();

Return value:

pointer to new list

C example:

struct t_weelist *list = weechat_list_new ();

Script (Python):

# prototype
list = weechat.list_new()

# example
list = weechat.list_new()

3.6.2. weechat_list_add

Add an item in a list.

Prototype:

struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);

Arguments:

weelist: list pointer
data: data to insert in list
where: position in list:
- WEECHAT_LIST_POS_SORT: add in list, keeping list sorted
- WEECHAT_LIST_POS_BEGINNING: add to beginning of list
- WEECHAT_LIST_POS_END: add to end of list
user_data: any pointer

Return value:

pointer to new item

C example:

struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);

Script (Python):

# prototype
item = weechat.list_add(list, data, where, user_data)

# example
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")

3.6.3. weechat_list_search

Search an item in a list.

Prototype:

struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_search (list, "my data");

Script (Python):

# prototype
item = weechat.list_search(list, data)

# example
item = weechat.list_search(list, "my data")

3.6.4. weechat_list_casesearch

Search an item in a list, ignoring case.

Prototype:

struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

Script (Python):

# prototype
item = weechat.list_casesearch(list, data)

# example
item = weechat.list_casesearch(list, "my data")

3.6.5. weechat_list_get

Return an item in a list by position.

Prototype:

struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);

Arguments:

weelist: list pointer
position: position in list (first item is 0)

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */

Script (Python):

# prototype
item = weechat.list_get(list, position)

# example
item = weechat.list_get(list, 0)

3.6.6. weechat_list_set

Set new value for an item.

Prototype:

void weechat_list_set (struct t_weelist_item *item, const char *value);

Arguments:

item: item pointer
value: new value for item

C example:

weechat_list_set (item, "new data");

Script (Python):

# prototype
weechat.list_set(item, value)

# example
weechat.list_set(item, "new data")

3.6.7. weechat_list_next

Return next item in list.

Prototype:

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

pointer to next item, NULL if pointer was last item in list

C example:

struct t_weelist_item *next_item = weechat_list_next (item);

Script (Python):

# prototype
item = weechat.list_next(item)

# example
item = weechat.list_next(item)

3.6.8. weechat_list_prev

Return previous item in list.

Prototype:

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

pointer to previous item, NULL if pointer was last item in list

C example:

struct t_weelist_item *prev_item = weechat_list_prev (item);

Script (Python):

# prototype
item = weechat.list_prev(item)

# example
item = weechat.list_prev(item)

3.6.9. weechat_list_string

Return string value of an item.

Prototype:

const char *weechat_list_string (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

string value of item

C example:

weechat_printf (NULL, "value of item: %s", weechat_list_string (item));

Script (Python):

# prototype
value = weechat.list_string(item)

# example
weechat.prnt("", "value of item: %s" % weechat.list_string(item))

3.6.10. weechat_list_size

Return size of list (number of items).

Prototype:

char *weechat_list_size (struct t_weelist *weelist);

Arguments:

weelist: list pointer

Return value:

size of list (number of items), 0 if list is empty

C example:

weechat_printf (NULL, "size of list: %d", weechat_list_size (list));

Script (Python):

# prototype
size = weechat.list_size(list)

# example
weechat.prnt("", "size of list: %d" % weechat.list_size(list))

3.6.11. weechat_list_remove

Remove an item in a list.

Prototype:

void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);

Arguments:

weelist: list pointer
item: item pointer

C example:

weechat_list_remove (list, item);

Script (Python):

# prototype
weechat.list_remove(list, item)

# example
weechat.list_remove(list, item)

3.6.12. weechat_list_remove_all

Remove all items in a list.

Prototype:

void weechat_list_remove_all (struct t_weelist *weelist);

Arguments:

weelist: list pointer

C example:

weechat_list_remove_all (list);

Script (Python):

# prototype
weechat.list_remove_all(list)

# example
weechat.list_remove_all(list)

3.6.13. weechat_list_free

Free a list.

Prototype:

void weechat_list_free (struct t_weelist *weelist);

Arguments:

weelist: list pointer

C example:

weechat_list_free (list);

Script (Python):

# prototype
weechat.list_free(list)

# example
weechat.list_free(list)

3.7. Configuration files

Functions for configuration files.

3.7.1. weechat_config_new

Create a new configuration file.

Prototype:

struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(void *data,
                                                                 struct t_config_file *config_file),
                                          void *callback_reload_data);

Arguments:

name: name of configuration file (without path or extension)
callback_reload: function called when configuration file is reloaded with /reload (optional, can be NULL), arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
callback_reload_data: pointer given to reload callback when it is called by WeeChat

Return value:

pointer to new configuration file, NULL if an error occured

Note	File is NOT created on disk by this function. It will be created by call to function [_weechat_write_config]. You should call this function only after adding some sections (with [_weechat_config_new_section]) and options (with [_weechat_config_new_option]).

C example:

int
my_config_reload_cb (void *data, struct t_config_file *config_file)
{
    /* ... */

    return WEECHAT_RC_OK;
}

struct t_config_file *config_file = weechat_config_new ("test",
                                                        &my_config_reload_cb,
                                                        NULL);

Script (Python):

# prototype
config_file = weechat.config_new(name, calback_reload, callback_reload_data)

# example
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")

3.7.2. weechat_config_new_section

Create a new section in configuration file.

Prototype:

struct t_config_section *weechat_config_new_section (
    struct t_config_file *config_file,
    const char *name,
    int user_can_add_options,
    int user_can_delete_options,
    int (*callback_read)(void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    void *callback_read_data,
    int (*callback_write)(void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    void *callback_write_data,
    int (*callback_write_default)(void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name);
    void *callback_write_default_data,
    int (*callback_create_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    void *callback_create_option_data,
    int (*callback_delete_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    void *callback_delete_option_data);

Arguments:

config_file: configuration file pointer
name: name of section
user_can_add_options: 1 if user can create new options in section, or 0 if it is forbidden
user_can_delete_options: 1 if user can delete options in section, or 0 if it is forbidden
callback_read: function called when an option in section is read from disk (should be NULL in most cases, except if options in section need custom function), arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- struct t_config_section *section: section pointer
- const char *option_name: name of option
- const char *value: value
callback_read_data: pointer given to callback when it is called by WeeChat
callback_write: function called when section is written in file (should be NULL for most cases, except if section needs to be written by a custom function), arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- struct t_config_section *section: section pointer
- const char *option_name: name of option
callback_write_data: pointer given to callback when it is called by WeeChat
callback_write_default: function called when default values for section must be written in file, arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- const char *section_name: name of section
callback_write_default_data: pointer given to callback when it is called by WeeChat
callback_create_option: function called when a new option is created in section (NULL if section does not allow new options to be created), arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- struct t_config_section *section: section pointer
- const char *option_name: name of option
- const char *value: value
callback_create_option_data: pointer given to callback when it is called by WeeChat
callback_delete_option: function called when an option is deleted in section (NULL if section does not allow options to be deleted), arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- struct t_config_section *section: section pointer
- struct t_config_option *option: option pointer
callback_delete_option_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new section in configuration file, NULL if an error occured

C example:

int
my_section_read_cb (void *data, struct t_config_file *config_file,
                    struct t_config_section *section, const char *option_name,
                    const char *value)
{
    /* ... */

    return WEECHAT_RC_OK;
}

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_RC_OK;
}

int
my_section_write_default_cb (void *data, struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_RC_OK;
}

int
my_section_create_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name, const char *value)
{
    /* ... */

    return WEECHAT_RC_OK;
}

int
my_section_delete_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */

    return WEECHAT_RC_OK;
}

/* standard section, user can not add/delete options */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, /* read callback */
                                NULL, NULL, /* write callback */
                                NULL, NULL, /* write default callback */
                                NULL, NULL, /* create option callback */
                                NULL, NULL); /* delete option callback */

/* special section, user can add/delete options, and options need
   callback to be read/written */
struct t_config_section *new_section2 =
    weechat_config_new_section (config_file, "section2", 1, 1,
                                &my_section_read_cb, NULL,
                                &my_section_write_cb, NULL,
                                &my_section_write_default_cb, NULL,
                                &my_section_create_option_cb, NULL,
                                &my_section_delete_option_cb, NULL);

Script (Python):

# prototype
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

# example
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_RC_OK

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_RC_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_RC_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_RC_OK

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_RC_OK

section = weechat.config_new_section(config_file, "section1", 1, 1,
    "my_section_read_cb", "",
    "my_section_write_cb", "",
    "my_section_write_default_cb", "",
    "my_section_create_option_cb", "",
    "my_section_delete_option_cb", "")

3.7.3. weechat_config_search_section

Search a section in a configuration file.

Prototype:

struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);

Arguments:

config_file: configuration file pointer
section_name: name of section to search

Return value:

pointer to section found, NULL if section was not found

C example:

struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");

Script (Python):

# prototype
section = weechat.config_search_section(config_file, section_name)

# example
section = weechat.config_search_section(config_file, "section")

3.7.4. weechat_config_new_option

Create a new option in a section of a configuration file.

Prototype:

struct t_config_option *weechat_config_new_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *name,
    const char *type,
    const char *description,
    const char *string_values,
    int min,
    int max,
    const char *default_value,
    const char *value,
    int null_value_allowed,
    int (*callback_check_value)(void *data,
                                struct t_config_option *option,
                                const char *value),
    void *callback_check_value_data,
    int (*callback_change)(void *data,
                           struct t_config_option *option),
    void *callback_change_data,
    int (*callback_delete)(void *data,
                           struct t_config_option *option),
    void *callback_delete_data);

Arguments:

config_file: configuration file pointer
section: section pointer
name: name of option
type: type of option:
- boolean: boolean value (on/off)
- integer: integer value (with optional strings for values)
- string: string value
- color: color
description: description of option
string_values: values as string (separated by "|"), used for type integer (optional)
min: minimum value (for type integer)
max: maximum value (for type integer)
default_value: default value for option (used when option is reset)
value: value for option
null_value_allowed: 1 if null (undefined value) is allowed for option, otherwise 0
callback_check_value: function called to check new value for option (optional), arguments:
- void *data: pointer
- struct t_config_option *option: option pointer
- const char *value: new value for option
callback_check_value_data: pointer given to check_value callback when it is called by WeeChat
callback_change: function called when value of option has changed (optional), arguments:
- void *data: pointer
- struct t_config_option *option: option pointer
callback_change_data: pointer given to change callback when it is called by WeeChat
callback_delete: function called when option will be deleted (optional), arguments:
- void *data: pointer
- struct t_config_option *option: option pointer
callback_delete_data: pointer given to delete callback when it is called by WeeChat

Return value:

pointer to new option in section, NULL if an error

C example:

/* boolean */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "on", /* default */
                               "on", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer"
                               NULL, /* string values */
                               0, 100, /* min, max */
                               "15", /* default */
                               "15", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer (with string values) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)"
                               "top|bottom|left|right", /* string values */
                               0, 0, /* min, max */
                               "bottom", /* default */
                               "bottom", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* string */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "test", /* default */
                               "test", /* value */
                               1, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* color */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "lightblue", /* default */
                               "lightblue", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

Script (Python):

# prototype
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

# example
def option4_check_value_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

def option4_change_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

def option4_delete_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "My option, type integer",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "My option, type integer (with string values)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", ""
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "My option, type color",
    "", 0, 100, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")

3.7.5. weechat_config_search_option

Search an option in a section of a configuration file.

Prototype:

struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);

Arguments:

config_file: configuration file pointer
section: section pointer
name: name of option to search

Return value:

pointer to option found, NULL if option was not found

C example:

struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");

Script (Python):

# prototype
option = weechat.config_search_option(config_file, section, option_name)

# example
option = weechat.config_search_option(config_file, section, "option")

3.7.6. weechat_config_search_with_string

Search an option with full name.

Prototype:

void weechat_config_search_with_string (const char *option_name,
                                        struct t_config_file **config_file,
                                        struct t_config_section **section,
                                        struct t_config_option **option);

Arguments:

option_name: full option name (format: "file.section.option")
config_file: pointer to configuration file pointer, will be set with pointer to configuration file of option found
section: pointer to section pointer, will be set to section of option, if found
option: pointer to an option pointer, will be set to option pointer, if found

C example:

struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}

3.7.7. weechat_config_string_to_boolean

Check if a text is "true" or "false", as boolean value.

Prototype:

int weechat_config_string_to_boolean (const char *text);

Arguments:

text: text to analyze

Return value:

1 if text is "true" ("on", "yes", "y", "true", "t", "1")
0 if text is "false" ("off", "no", "n", "false", "f", "0")

C example:

if (weechat_config_string_to_boolean (option_value))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_string_to_boolean(text)

# example
if weechat.config_string_to_boolean(text):
    # ...

3.7.8. weechat_config_option_reset

Reset an option to its default value.

Prototype:

int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);

Arguments:

option: option pointer
run_callback: 1 for calling callback if value of option is changed, otherwise 0

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been reset
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured

C example:

switch (weechat_config_option_reset (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_option_reset(option, run_callback)

# example
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.7.9. weechat_config_option_set

Set new value for an option.

Prototype:

int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);

Arguments:

option: option pointer
value: new value for option
run_callback: 1 for calling chang callback if value of option is changed, otherwise 0

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured

C example:

switch (weechat_config_option_set (option, "new_value", 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_option_set(option, value, run_callback)

# example
rc = weechat.config_option_set(option, "new_value", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.7.10. weechat_config_option_set_null

Set null (undefined value) for an option.

Prototype:

int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);

Arguments:

option: option pointer
run_callback: 1 for calling chang callback if value of option is changed (if it was not null), otherwise 0

Note	You can set value to null only if it is allowed for option (see [_weechat_config_new_option]).

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured

C example:

switch (weechat_config_option_set_null (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_option_set_null(option, run_callback)

# example
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.7.11. weechat_config_option_unset

Unset/reset option.

Prototype:

int weechat_config_option_unset (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET if option value has not been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET if option value has been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED if option has been removed
WEECHAT_CONFIG_OPTION_UNSET_ERROR if an error occured

C example:

switch (weechat_config_option_unset (option))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* .... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_option_unset(option)

# example
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...

3.7.12. weechat_config_option_rename

Rename an option.

Prototype:

void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);

Arguments:

option: option pointer
new_name: new name for option

C example:

weechat_config_option_rename (option, "new_name");

Script (Python):

# prototype
weechat.config_option_rename(option, new_name)

# example
weechat.config_option_rename(option, "new_name")

3.7.13. weechat_config_option_get_pointer

Return a pointer on an option property.

Prototype:

void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);

Arguments:

option: option pointer
property: property name:
- config_file: configuration file pointer (struct t_config_file *)
- section: section pointer (struct t_config_section *)
- name: option name (char *)
- type: option type (int *)
- description: option description (char *)
- string_values: string values (char *)
- min: minimum value (int *)
- max: maximum value (int *)
- default_value: default value (depends on type)
- value: current value (depends on type)
- prev_option: previous option pointer (struct t_config_option *)
- next_option: next option pointer (struct t_config_option *)

Return value:

pointer to property asked

C example:

char *description = weechat_config_option_get_pointer (option, "description");

3.7.14. weechat_config_option_is_null

Check if an option is "null" (undefined value).

Prototype:

int weechat_config_option_is_null (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

1 if value of option is "null"
0 if value of option is not "null"

C example:

if (weechat_config_option_is_null (option))
{
    /* value is "null" */
}
else
{
    /* value is not "null" */
}

Script (Python):

# prototype
weechat.config_option_is_null(option)

# example
if weechat.config_option_is_null(option):
    # ...

3.7.15. weechat_config_option_default_is_null

Check if default value for an option is "null" (undefined value).

Prototype:

int weechat_config_option_default_is_null (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

1 if default value of option is "null"
0 if default value of option is not "null"

C example:

if (weechat_config_option_default_is_null (option))
{
    /* default value is "null" */
}
else
{
    /* default value is not "null" */
}

Script (Python):

# prototype
weechat.config_option_default_is_null(option)

# example
if weechat.config_option_default_is_null(option):
    # ...

3.7.16. weechat_config_boolean

Return boolean value of option.

Prototype:

int weechat_config_boolean (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

boolean value of option (0 or 1)

C example:

if (weechat_config_boolean (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_option_boolean(option)

# example
if weechat.config_option_boolean(option):
    # ...

3.7.17. weechat_config_boolean_default

Return default boolean value of option.

Prototype:

int weechat_config_boolean_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default boolean value of option (0 or 1)

C example:

if (weechat_config_boolean_default (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_option_boolean_default(option)

# example
if weechat.config_option_boolean_default(option):
    # ...

3.7.18. weechat_config_integer

Return integer value of option.

Prototype:

int weechat_config_integer (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

integer value of option

C example:

int value = weechat_config_integer (option);

Script (Python):

# prototype
value = weechat.config_option_integer(option)

# example
if weechat.config_option_integer(option):
    # ...

3.7.19. weechat_config_integer_default

Return default integer value of option.

Prototype:

int weechat_config_integer_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default integer value of option

C example:

int value = weechat_config_integer_default (option);

Script (Python):

# prototype
value = weechat.config_option_integer_default(option)

# example
if weechat.config_option_integer_default(option):
    # ...

3.7.20. weechat_config_string

Return string value of option.

Prototype:

const char *weechat_config_string (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

string value of option

C example:

const char *value = weechat_config_string (option);

Script (Python):

# prototype
value = weechat.config_option_string(option)

# example
value = weechat.config_option_string(option):

3.7.21. weechat_config_string_default

Return default string value of option.

Prototype:

const char *weechat_config_integer_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default string value of option

C example:

const char *value = weechat_config_string_default (option);

Script (Python):

# prototype
value = weechat.config_option_string_default(option)

# example
value = weechat.config_option_string_default(option):

3.7.22. weechat_config_color

Return color value of option.

Prototype:

const char *weechat_config_color (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

color value of option (string with name of color)

C example:

const char *color = weechat_config_color (option);

Script (Python):

# prototype
value = weechat.config_option_color(option)

# example
value = weechat.config_option_color(option):

3.7.23. weechat_config_color_default

Return default color value of option.

Prototype:

const char *weechat_config_color_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default color value of option (string with name of color)

C example:

const char *color = weechat_config_color_default (option);

Script (Python):

# prototype
value = weechat.config_option_color_default(option)

# example
value = weechat.config_option_color_default(option):

3.7.24. weechat_config_write_option

Write a line in a configuration file with option and its value (this function should be called only in "write" or "write_default" callbacks for a section).

Prototype:

void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);

Arguments:

config_file: configuration file pointer
option: option pointer

C example:

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_option (config_file, option);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
weechat.config_write_option(config_file, option)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK

3.7.25. weechat_config_write_line

Write a line in a configuration file (this function should be called only in "write" or "write_default" callbacks for a section).

Prototype:

void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);

Arguments:

config_file: configuration file pointer
option_name: option name
value: value (if NULL, then line with section name is written, for example: "[section]")

C example:

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
weechat.config_write_line(config_file, option_name, value)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_line(config_file, "option", "value")
    return weechat.WEECHAT_RC_OK

3.7.26. weechat_config_write

Write configuration file to disk.

Prototype:

int weechat_config_write (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

Return value:

WEECHAT_CONFIG_WRITE_OK if configuration was written
WEECHAT_CONFIG_WRITE_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_WRITE_ERROR if another error occured

C example:

switch (weechat_config_write (config_file))
{
    case WEECHAT_CONFIG_WRITE_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_write(config_file)

# example
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...

3.7.27. weechat_config_read

Read configuration file from disk.

Prototype:

int weechat_config_read (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

Return value:

WEECHAT_CONFIG_READ_OK if configuration was loaded
WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found

C example:

switch (weechat_config_read (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_read(config_file)

# example
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...

3.7.28. weechat_config_reload

Reload configuration file from disk.

Prototype:

int weechat_config_reload (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

Return value:

WEECHAT_CONFIG_READ_OK if configuration was reloaded
WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found

C example:

switch (weechat_config_reload (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_reload(config_file)

# example
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...

3.7.29. weechat_config_option_free

Free an option.

Prototype:

void weechat_config_option_free (struct t_config_option *option);

Arguments:

option: option pointer

C example:

weechat_config_option_free (option);

Script (Python):

# prototype
weechat.config_option_free(option)

# example
weechat.config_option_free(option)

3.7.30. weechat_config_section_free_options

Free all options in a section.

Prototype:

void weechat_config_section_free_options (struct t_config_section *section);

Arguments:

section: section pointer

C example:

weechat_config_section_free_options (section);

Script (Python):

# prototype
weechat.config_section_free_options(section)

# example
weechat.config_section_free_options(section)

3.7.31. weechat_config_section_free

Free a section.

Prototype:

void weechat_config_section_free (struct t_config_option *option);

Arguments:

section: section pointer

C example:

weechat_config_section_free (section);

Script (Python):

# prototype
weechat.config_section_free(section)

# example
weechat.config_section_free(section)

3.7.32. weechat_config_free

Free a configuration file.

Prototype:

void weechat_config_free (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

C example:

weechat_config_free (config_file);

Script (Python):

# prototype
weechat.config_free(config_file)

# example
weechat.config_free(config_file)

3.7.33. weechat_config_get

Search an option with full name.

Prototype:

struct t_config_option *weechat_config_get (const char *option_name);

Arguments:

option_name: full option name (format: "file.section.option")

Return value:

pointer to option found, NULL if option was not found

C example:

struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

Script (Python):

# prototype
option = weechat.config_get(option_name)

# example
option = weechat.config_get("weechat.look.item_time_format")

3.7.34. weechat_config_get_plugin

Search an option in plugins configuration file (plugins.conf).

Prototype:

const char *weechat_config_get_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)

Return value:

value of option found, NULL if option was not found

C example:

/* if current plugin is "test", then look for value of option
   "plugins.var.test.option" in file plugins.conf */
char *value = weechat_config_get_plugin ("option");

Script (Python):

# prototype
value = weechat.config_get_plugin(option_name)

# example
value = weechat.config_get_plugin("option")

3.7.35. weechat_config_is_set_plugin

Check if option is set in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_is_set_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)

Return value:

1 if option is set, 0 if option does not exist

C example:

if (weechat_config_is_set_plugin ("option"))
{
    /* option is set */
}
else
{
    /* option does not exist */
}

Script (Python):

# prototype
value = weechat.config_is_set_plugin(option_name)

# example
if weechat.config_is_set_plugin("option"):
    # option is set
    # ...
else:
    # option does not exist
    # ...

3.7.36. weechat_config_set_plugin

Set new value for option in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_set_plugin (const char *option_name, const char *value);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)
value: new value for option

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND if option was not found
WEECHAT_CONFIG_OPTION_SET_ERROR if other error occured

C example:

switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_set_plugin(option_name, value)

# example
rc = weechat.config_is_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.7.37. weechat_config_unset_plugin

Unset option in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_unset_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where xxx is current plugin name)

Return value:

WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET if option value has not been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET if option value has been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED if option has been removed
WEECHAT_CONFIG_OPTION_UNSET_ERROR if an error occured

C example:

switch (weechat_config_unset_plugin ("option"))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_unset_plugin(option_name)

# example
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...

3.8. Display

Functions to display text in buffers.

3.8.1. weechat_prefix

Return a prefix.

Prototype:

const char *weechat_prefix (const char *prefix);

Arguments:

prefix: name of prefix:

Prefix	Value	Color	Description
error	`=!=`	yellow	error message
network	`--`	magenta	message from network
action	`*`	white	self action
join	`-->`	lightgreen	someone joins current chat
quit	`<--`	lightred	someone leaves current chat

Note	Values and colors can be customized with command `/set`.

Return value:

prefix value (string with prefix and color codes), empty string if prefix is not found

C example:

weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));

Script (Python):

# prototype
value = weechat.prefix(prefix)

# example
weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))

3.8.2. weechat_color

Return a string color code for display.

Prototype:

const char *weechat_color (const char *color_name);

Arguments:

color_name: name of color, one of:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional background, for example yellow or yellow,red
- attribute:
  - bold: set bold
  - -bold: remove bold
  - reverse: set reverse
  - -reverse: remove reverse
  - italic: set italic
  - -italic: remove italic
  - underline: set underline
  - -underline: remove underline
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar

Return value:

string with color code, or a "reset color" code if color is not found

C example:

weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));

Script (Python):

# prototype
value = weechat.color(color_name)

# example
weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

3.8.3. weechat_printf

Display a message on a buffer.

Prototype:

void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
message: message to display

C example:

weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");

Script (Python):

# prototype
weechat.prnt(buffer, message)

# example
weechat.prnt("", "Hello on WeeChat buffer")
weechat.prnt(buffer, "Hello on this buffer")

Note	Function is called "print" in scripts ("prnt" in Python).

3.8.4. weechat_printf_date

Display a message on a buffer, using a custom date.

Prototype:

void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message
message: message to display

C example:

weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");

3.8.5. weechat_printf_tags

Display a message on a buffer, using a custom tags.

Prototype:

void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
tags: comma separated list of tags
message: message to display

C example:

weechat_printf_tags (NULL, "notify_message",
                     "Message with a tag 'notify_message'");

3.8.6. weechat_printf_date_tags

Display a message on a buffer, using a custom date and tags.

Prototype:

void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message
tags: comma separated list of tags
message: message to display

C example:

weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message 2 minutes ago, with a tag 'notify_message'");

Script (Python):

# prototype
weechat.prnt_date_tags(buffer, date, tags, message)

# example
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message 2 minutes ago, with a tag 'notify_message'")

Note	Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python).

3.8.7. weechat_printf_y

Display a message on a line of a buffer with free content.

Prototype:

void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *message, ...);

Arguments:

buffer: buffer pointer
y: line number (first line is 0)
message: message to display

C example:

weechat_printf_y (buffer, 2, "My message on third line");

Script (Python):

# prototype
weechat.prnt_y(buffer, y, message)

# example
weechat.prnt_y("", 2, "My message on third line")

Note	Function is called "print_y" in scripts ("prnt_y" in Python).

3.8.8. weechat_log_printf

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

Prototype:

void weechat_log_printf (const char *message, ...);

Arguments:

message: message to write

C example:

weechat_log_printf ("My message in log file");

Script (Python):

# prototype
weechat.log_print(message)

# example
weechat.log_print("My message in log file")

Note	Function is called "log_print" in scripts.

3.9. Hooks

3.9.1. weechat_hook_command

Hook a command.

Prototype:

struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     void *callback_data);

Arguments:

command: command name
description: description for command (displayed with /help command)
args: arguments for command (displayed with /help command)
args_description: description of arguments (displayed with /help command)
completion: completion template for command: list of completions for each argument, separated by space. Many completions are possible for one argument, separated by "|". Many templates are possible for same command, separated by "||".
callback: function called when command is used, arguments:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer where command is executed
- int argc: number of arguments given for command
- char **argv: arguments given for command
- char **argv_eol: arguments given for command (until end of line for each argument)
callback_data: pointer given to callback when it is called by WeeChat

Default completion codes are:

Plugin	Name	Description
alias	alias	list of aliases
aspell	aspell_langs	list of supported langs for aspell
irc	irc_channel	current IRC channel
irc	irc_channel_nicks_hosts	nicks and hostnames of current IRC channel
irc	irc_channel_topic	topic of current IRC channel
irc	irc_channels	channels on all IRC servers
irc	irc_ignores_numbers	numbers for defined ignores
irc	irc_msg_part	default part message for IRC channel
irc	irc_privates	privates on all IRC servers
irc	irc_server	current IRC server
irc	irc_server_channels	channels on current IRC server
irc	irc_server_nick	nick on current IRC server
irc	irc_server_nicks	nicks on all channels of current IRC server
irc	irc_server_privates	privates on current IRC server
irc	irc_servers	IRC servers (internal names)
irc	nick	nicks of current IRC channel
lua	lua_script	list of scripts
perl	perl_script	list of scripts
python	python_script	list of scripts
relay	relay_free_port	first free port for relay plugin
relay	relay_protocol_name	all possible protocol.name for relay plugin
relay	relay_relays	protocol.name of current relays for relay plugin
ruby	ruby_script	list of scripts
tcl	tcl_script	list of scripts
weechat	bars_names	names of bars
weechat	bars_options	options for bars
weechat	buffers_names	names of buffers
weechat	buffers_numbers	numbers of buffers
weechat	buffers_plugins_names	names of buffers (including plugins names)
weechat	commands	commands (weechat and plugins)
weechat	config_files	configuration files
weechat	config_option_values	values for a configuration option
weechat	config_options	configuration options
weechat	filename	filename
weechat	filters_names	names of filters
weechat	infolists	names of infolists hooked
weechat	infos	names of infos hooked
weechat	keys_codes	key codes
weechat	nicks	nicks in nicklist of current buffer
weechat	plugins_commands	commands defined by plugins
weechat	plugins_names	names of plugins
weechat	proxies_names	names of proxies
weechat	proxies_options	options for proxies
weechat	weechat_commands	weechat commands
xfer	nick	nicks of DCC chat

Special codes:

%%command: reuse completion template from command command
%-: stop completion
%*: repeat last completion

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_command_cb (void *data, struct t_gui_buffer *buffer, int argc,
               char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* this example is inspired by command /filter */
struct t_hook *my_command_hook =
    weechat_hook_command (/* command name */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);

For example, if command called is /command abc def ghi, then argv and argv_eol contain following values:

argv:
- argv[0] == "abc"
- argv[1] == "def"
- argv[2] == "ghi"
argv_eol:
- argv_eol[0] == "abc def ghi"
- argv_eol[1] == "def ghi"
- argv_eol[2] == "ghi"

Script (Python):

# prototype
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# example
def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "description of myfilter",
    "[list] | [enable|disable|toggle [name]] | "
    "[add name plugin.buffer tags regex] | "
    "[del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")

3.9.2. weechat_hook_command_run

Hook a command when WeeChat runs it.

Prototype:

struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);

Arguments:

command: command to hook, may start or end with "*" as joker
callback: function called when command is run, arguments:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer where command is executed
- const char *command: the command executed, with its arguments
callback_data: pointer given to callback when it is called by WeeChat

Note	Callback can return WEECHAT_RC_OK or WEECHAT_RC_OK_EAT (command will not be executed by WeeChat after callback).

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
                    "You want to complete? I'm eating the completion ahah!");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_command_run(command, callback, callback_data)

# example
def my_command_run_cb(data, buffer, command):
    weechat.prnt("", "You want to complete? I'm eating the completion, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")

3.9.3. weechat_hook_timer

Hook a timer.

Prototype:

struct t_hook *weechat_hook_timer (long interval,
                                   const char *align_second,
                                   const char *max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);

Arguments:

interval: interval between two calls (milliseconds, so 1000 = 1 second)
align_second: alignment on a second. For example, if current time is 09:00, if interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute when second is 00
max_calls: number of calls to timer (if 0, then timer has no end)
callback: function called when time is reached, arguments:
- void *data: pointer
- int remaining_calls: remaining calls (-1 if timer has no end)
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_timer_cb (void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* timer called each 20 seconds */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# example
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each 20 seconds
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")

3.9.4. weechat_hook_fd

Hook a file descriptor (file or socket).

Prototype:

struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);

Arguments:

fd: file descriptor
flag_read: 1 = catch read event, 0 = ignore
flag_write: 1 = catch write event, 0 = ignore
flag_exception: 1 = catch exception event, 0 = ignore
callback: function called a selected event occurs for file (or socket), arguments:
- void *data: pointer
- int fd: file descriptor
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_fd_cb (void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# example
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")

3.9.5. weechat_hook_process

Hook a process (launched with fork), and catch output.

Prototype:

struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);

Arguments:

command: command to launch in child process
timeout: timeout for command (in milliseconds): after this timeout, child process is killed (0 means no timeout)
callback: function called when data from child is available, or when child has ended, arguments:
- void *data: pointer
- const char *command: command executed by child
- int return_code: return code:
  - >= 0: child command return code
  - < 0: WEECHAT_HOOK_PROCESS_OK_RUNNING (data available, but child still running) or WEECHAT_HOOK_PROCESS_ERROR (error when launching command)
- out: standard output of command (stdout)
- err: error output of command (stderr)
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_process(command, timeout, callback, callback_data)

# example
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout: %s" % out)
    if err != "":
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")

3.9.6. weechat_hook_connect

Hook a connection (background connection to a remote host).

Prototype:

struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int sock,
                                     int ipv6,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     const char *errpr,
                                                     const char *ip_address),
                                     void *callback_data);

Arguments:

proxy: name of proxy to use for connection (optional, NULL means connection without proxy)
address: name or IP address to connect to
port: port number
sock: socket used to connect
ipv6: 1 to use IPv6, 0 to use IPv4
gnutls_sess: GnuTLS session (optional)
gnutls_cb: GnuTLS callback (optional)
gnutls_dhkey_size: size of the key used during the Diffie-Hellman Key Exchange (GnuTLS)
callback: function called when connection is ok or failed, arguments:
- void *data: pointer
- int status: connection status:
  - WEECHAT_HOOK_CONNECT_OK: connection ok
  - WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: address not found
  - WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: IP address not found
  - WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: connection refused
  - WEECHAT_HOOK_CONNECT_PROXY_ERROR: error with proxy
  - WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: error with local hostname
  - WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: GnuTLS init error
  - WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: GnuTLS handshake error
  - WEECHAT_HOOK_CONNECT_MEMORY_ERROR: insufficient memory
- gnutls_rc: result value of gnutls_handshake()
- const char *error: result value of gnutls_strerror(gnutls_rc)
- const char *ip_address: IP address found
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_connect_cb (void *data, int status, int gnutls_rc, const char *error,
               const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       sock, 0,
                                                       NULL, NULL, 0, /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_connect(proxy, address, port, sock, ipv6, local_hostname,
    callback, callback_data)

# example
def my_connect_cb(data, status, gnutls_rc, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, sock, 0, "",
                            "my_connect_cb", "")

3.9.7. weechat_hook_print

Hook a message printed.

Prototype:

struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);

Arguments:

buffer: buffer pointer, if NULL, messages from any buffer are caught
tags: only messages with these tags (comma separated list) will be caught (optional)
message: only messages with this string will be caught (optional)
strip_colors: if 1, colors will be stripped from message displayed, before calling callback
callback: function called when a message is printed, arguments:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- time_t date: date
- int tags_count: number of tags for line
- const char **tags: array with tags for line
- int displayed: 1 if line is displayed, 0 if it is filtered (hidden)
- int highlight: 1 if line has highlight, otherwise 0
- const char *prefix: prefix
- const char *message: message
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occured

C example:

int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch all messages, on all buffers, without color */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# example
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    # ...
    return weechat.WEECHAT_RC_OK

# catch all messages, on all buffers, without color
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")

3.9.8. weechat_hook_signal

Hook a signal.

Prototype:

struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);

Arguments:

signal: signal to catch, can begin or end with "*":

Plugin	Signal	Arguments	Description
irc	xxx,irc_in_yyy ¹	string: message	irc message from server (before irc plugin uses it)
irc	xxx,irc_in2_yyy ¹	string: message	irc message from server (after irc plugin uses it)
irc	xxx,irc_out_yyy ¹	string: message	irc message sent to server
irc	irc_ctcp	string: message	CTCP received
irc	irc_dcc	string: message	new DCC
irc	irc_pv	string: message	private message received
irc	irc_channel_opened	pointer: buffer	channel opened
irc	irc_pv_opened	pointer: buffer	private opened
irc	irc_server_connecting	string: server name	connecting to server
irc	irc_server_connected	string: server name	connected to server
irc	irc_server_disconnected	string: server name	disconnected from server
irc	irc_ignore_removing	pointer: ignore	removing ignore
irc	irc_ignore_removed	-	ignore removed
logger	logger_start	pointer: buffer	start logging for buffer
logger	logger_stop	pointer: buffer	stop logging for buffer
logger	logger_backlog	pointer: buffer	display backlog for buffer
weechat	buffer_closing	pointer: buffer	closing buffer
weechat	buffer_closed	pointer: buffer	buffer closed
weechat	buffer_lines_hidden	pointer: buffer	lines hidden in buffer
weechat	buffer_localvar_added	pointer: buffer	local variable has been added
weechat	buffer_localvar_changed	pointer: buffer	local variable has changed
weechat	buffer_localvar_removed	pointer: buffer	local variable has been removed
weechat	buffer_moved	pointer: buffer	buffer moved
weechat	buffer_opened	pointer: buffer	buffer opened
weechat	buffer_renamed	pointer: buffer	buffer renamed
weechat	buffer_switch	pointer: buffer	switching buffer
weechat	buffer_title_changed	pointer: buffer	title of buffer changed
weechat	buffer_type_changed	pointer: buffer	type of buffer changed
weechat	debug_dump	-	dump request
weechat	filter_added	pointer: filter	filter added
weechat	filter_removing	pointer: filter	removing filter
weechat	filter_removed	-	filter added
weechat	filter_enabled	-	filters enabled
weechat	filter_disabled	-	filters disabled
weechat	hotlist_changed	-	hotlist changed
weechat	input_paste_pending	-	paste pending
weechat	input_search	-	text search in buffer
weechat	input_text_changed	-	input text changed
weechat	input_text_cursor_moved	-	input text cursor moved
weechat	key_pressed	string: key pressed	key pressed
weechat	nicklist_changed	-	nicklist has changed
weechat	partial_completion	-	partial completion happened
weechat	quit	string: arguments for /quit	command `/quit` issued by user
weechat	upgrade	-	command `/upgrade` issued by user
weechat	weechat_highlight	string: message with prefix	highlight happened
weechat	weechat_pv	string: message with prefix	private message displayed
weechat	window_scrolled	pointer: window	scroll in window
weechat	window_unzooming	pointer: current window	unzooming window
weechat	window_unzoomed	pointer: current window	window unzoomed
weechat	window_zooming	pointer: current window	zomming window
weechat	window_zoomed	pointer: current window	window zoomed
xfer	xfer_add	pointer: infolist with xfer info	new xfer
xfer	xfer_send_ready	pointer: infolist with xfer info	xfer ready
xfer	xfer_accept_resume	pointer: infolist with xfer info	xfer accepts resume (send)
xfer	xfer_send_accept_resume	pointer: infolist with xfer info	xfer accepts resume (send)
xfer	xfer_start_resume	pointer: infolist with xfer info	start resume
xfer	xfer_resume_ready	pointer: infolist with xfer inf