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

Latest version of this document can be found on this page: http://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("Sébastien Helleu <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 ("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 ("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);
Note
This function is not available in scripting API.

3.2.7. weechat_string_tolower

Convert UTF-8 string to lower case.

Prototype:

void weechat_string_tolower (char *string);

Arguments:

  • string: string to convert

C example:

char str[] = "AbCdé";
weechat_string_tolower (str);  /* str is now: "abcdé" */
Note
This function is not available in scripting API.

3.2.8. weechat_string_toupper

Convert UTF-8 string to upper case.

Prototype:

void weechat_string_toupper (char *string);

Arguments:

  • string: string to convert

C example:

char str[] = "AbCdé";
weechat_string_toupper (str);  /* str is now: "ABCDé" */
Note
This function is not available in scripting API.

3.2.9. weechat_strcasecmp

Updated in 1.0.

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:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_strcasecmp ("aaa", "CCC");  /* == -2 */
Note
This function is not available in scripting API.

3.2.10. weechat_strcasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0.

Locale and case independent string comparison, using a range for case comparison.

Prototype:

int weechat_strcasecmp_range (const char *string1, const char *string2, int range);

Arguments:

  • string1: first string for comparison

  • string2: second string for comparison

  • range: number of chars in case comparison, for example:

    • 26: "A-Z" are lowered to "a-z"

    • 29: "A-Z [ \ ]" are lowered to "a-z { | }"

    • 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~"

Note
Values 29 and 30 are used by some protocols like IRC.

Return value:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */
Note
This function is not available in scripting API.

3.2.11. weechat_strncasecmp

Updated in 1.0.

Locale and case independent string comparison, for max chars.

Prototype:

int weechat_strncasecmp (const char *string1, const char *string2, int max);

Arguments:

  • string1: first string for comparison

  • string2: second string for comparison

  • max: max chars to compare

Return value:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_strncasecmp ("aabb", "aacc", 2);  /* == 0 */
Note
This function is not available in scripting API.

3.2.12. weechat_strncasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0.

Locale and case independent string comparison, for max chars, using a range for case comparison.

Prototype:

int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);

Arguments:

  • string1: first string for comparison

  • string2: second string for comparison

  • max: max chars to compare

  • range: number of chars in case comparison, for example:

    • 26: "A-Z" are lowered to "a-z"

    • 29: "A-Z [ \ ]" are lowered to "a-z { | }"

    • 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~"

Note
Values 29 and 30 are used by some protocols like IRC.

Return value:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */
Note
This function is not available in scripting API.

3.2.13. weechat_strcmp_ignore_chars

Updated in 1.0.

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:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */
Note
This function is not available in scripting API.

3.2.14. 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" */
Note
This function is not available in scripting API.

3.2.15. weechat_strlen_screen

WeeChat ≥ 0.4.2.

Return number of chars needed on screen to display UTF-8 string. Non-printable chars have a width of 1 (this is the difference with the function weechat_utf8_strlen_screen).

Prototype:

int weechat_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_strlen_screen ("é");  /* == 1 */

Script (Python):

# prototype
length = weechat.strlen_screen(string)

# example
length = weechat.strlen_screen("é")  # 1

3.2.16. weechat_string_match

Updated in 1.0.

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 with wildcards ("*"), each wildcard matches 0 or more chars in the string

  • case_sensitive: 1 for case sensitive comparison, otherwise 0

Note
Since version 1.0, wildcards are allowed inside the mask (not only beginning/end of 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 */
int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */

Script (Python):

# prototype
match = weechat.string_match(string, mask, case_sensitive)

# examples
match1 = weechat.string_match("abcdef", "abc*", 0)   # 1
match2 = weechat.string_match("abcdef", "*dd*", 0)   # 0
match3 = weechat.string_match("abcdef", "*def", 0)   # 1
match4 = weechat.string_match("abcdef", "*de*", 0)   # 1
match5 = weechat.string_match("abcdef", "*b*d*", 0)  # 1

3.2.17. weechat_string_expand_home

WeeChat ≥ 0.3.3.

Replace leading ~ by string with home directory. If string does not start with ~, then same string is returned.

Prototype:

char *weechat_string_expand_home (const char *path);

Arguments:

  • path: path

Return value:

  • path with leading ~ replaced by home directory (must be freed by calling "free" after use)

C example:

char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/xxx/file.txt" */
/* ... */
free (str);
Note
This function is not available in scripting API.

3.2.18. 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);
Note
This function is not available in scripting API.

3.2.19. 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);
Note
This function is not available in scripting API.

3.2.20. weechat_string_convert_escaped_chars

WeeChat ≥ 1.0.

Convert escaped chars to their value:

  • \": double quote

  • \\: backslash

  • \a: alert (BEL)

  • \b: backspace

  • \e: escape

  • \f: form feed

  • \n: new line

  • \r: carriage return

  • \t: horizontal tab

  • \v: vertical tab

  • \0ooo: char as octal value (ooo is 0 to 3 digits)

  • \xhh: char as hexadecimal value (hh is 1 to 2 digits)

  • \uhhhh: unicode char as hexadecimal value (hhhh is 1 to 4 digits)

  • \Uhhhhhhhh: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)

Prototype:

char *weechat_string_convert_escaped_chars (const char *string);

Arguments:

  • string: string

Return value:

  • string with escaped chars replaced by their value (must be freed by calling "free" after use)

C example:

char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
/* str == "snowman: ☃" */
/* ... */
free (str);
Note
This function is not available in scripting API.

3.2.21. 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);

Script (Python):

# prototype
regex = weechat.string_mask_to_regex(mask)

# example
regex = weechat.string_mask_to_regex("test*mask")  # "test.*mask"

3.2.22. weechat_string_regex_flags

WeeChat ≥ 0.3.7.

Get pointer on string after flags and mask with flags to compile regular expression.

Prototype:

const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)

Arguments:

  • regex: POSIX extended regular expression

  • default_flags: combination of following values (see man regcomp):

    • REG_EXTENDED

    • REG_ICASE

    • REG_NEWLINE

    • REG_NOSUB

  • flags: pointer value is set with flags used in regular expression (default flags + flags set in regular expression)

Flags must be at beginning of regular expression. Format is: "(?eins-eins)string".

Allowed flags are:

  • e: POSIX extended regular expression (REG_EXTENDED)

  • i: case insensitive (REG_ICASE)

  • n: match-any-character operators don’t match a newline (REG_NEWLINE)

  • s: support for substring addressing of matches is not required (REG_NOSUB)

Return value:

  • pointer in regex, after flags

C example:

const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */
Note
This function is not available in scripting API.

3.2.23. weechat_string_regcomp

WeeChat ≥ 0.3.7.

Compile a POSIX extended regular expression using optional flags at beginning of string (for format of flags, see weechat_string_regex_flags).

Prototype:

int weechat_string_regcomp (void *preg, const char *regex, int default_flags)

Arguments:

  • preg: pointer to regex_t structure

  • regex: POSIX extended regular expression

  • default_flags: combination of following values (see man regcomp):

    • REG_EXTENDED

    • REG_ICASE

    • REG_NEWLINE

    • REG_NOSUB

Return value:

  • same return code as function regcomp (0 if OK, other value for error, see man regcomp)

C example:

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0)
{
    /* error */
}
Note
This function is not available in scripting API.

3.2.24. 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 */

Script (Python):

# prototype
highlight = weechat.string_has_highlight(string, highlight_words)

# example
highlight = weechat.string_has_highlight("my test string", "test,word2")  # 1

3.2.25. weechat_string_has_highlight_regex

WeeChat ≥ 0.3.4.

Check if a string has one or more highlights, using a POSIX extended regular expression.
For at least one match of regular expression on string, it must be surrounded by delimiters (chars different from: alphanumeric, "-", "_" and "|").

Prototype:

int weechat_string_has_highlight_regex (const char *string, const char *regex);

Arguments:

  • string: string

  • regex: POSIX extended regular expression

Return value:

  • 1 if string has one or more highlights, otherwise 0

C example:

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

Script (Python):

# prototype
highlight = weechat.string_has_highlight_regex(string, regex)

# example
highlight = weechat.string_has_highlight_regex("my test string", "test|word2")  # 1

3.2.26. weechat_string_replace

Replace all occurrences 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);
Note
This function is not available in scripting API.

3.2.27. weechat_string_replace_regex

WeeChat ≥ 1.0.

Replace text in a string using a regular expression, replacement text and optional callback.

Prototype:

char *weechat_string_replace_regex (const char *string, void *regex,
                                    const char *replace, const char reference_char,
                                    char *(*callback)(void *data, const char *text),
                                    void *callback_data);

Arguments:

  • string: string

  • regex: pointer to a regular expression (regex_t structure) compiled with WeeChat function weechat_string_regcomp or regcomp (see man regcomp)

  • replace: replacement text, where following references are allowed:

    • $0 to $99: match 0 to 99 in regular expression (0 is the whole match, 1 to 99 are groups captured between parentheses)

    • $+: the last match (with highest number)

    • $.*N: match N (can be + or 0 to 99), with all chars replaced by * (the * char can be any char between space (32) and ~ (126))

  • reference_char: the char used for reference to match (commonly $)

  • callback: an optional callback called for each reference in replace (except for matches replaced by a char); the callback must return:

    • newly allocated string: it is used as replacement text (it is freed after use)

    • NULL: the text received in callback is used as replacement text (without changes)

  • callback_data: pointer given to callback when it is called

Return value:

  • string with text replaced, NULL if problem (must be freed by calling "free" after use)

C example:

regex_t my_regex;
char *string;
if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
                            REG_EXTENDED) == 0)
{
    string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
                                           "$3/$2/$1", '$', NULL, NULL);
    /* string == "date: 14/02/2014" */
    if (string)
        free (string);
    regfree (&my_regex);
}
Note
This function is not available in scripting API.

3.2.28. 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:

    • 0: each string will contain one word

    • 1: each string will contain all string until end of line (see example below)

    • 2: same as 1, but do not remove separators at end of string before split (WeeChat ≥ 0.3.6)

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

C example:

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);
Note
This function is not available in scripting API.

3.2.29. weechat_string_split_shell

WeeChat ≥ 1.0.

Split a string like the shell does for a command with arguments.

This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in Python repository), see: http://docs.python.org/3/library/shlex.html.

Prototype:

char **weechat_string_split_shell (const char *string, int *num_items);

Arguments:

  • string: string to split

  • num_items: pointer to int which will contain number of items created

Return value:

C example:

char **argv;
int argc;
argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
/* result: argv[0] == "test"
           argv[1] == "first arg"
           argv[2] == "second arg"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);
Note
This function is not available in scripting API.

3.2.30. weechat_string_free_split

Free memory used by a split string.

Prototype:

void weechat_string_free_split (char **split_string);

Arguments:

C example:

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
Note
This function is not available in scripting API.

3.2.31. 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);
Note
This function is not available in scripting API.

3.2.32. 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:

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
*/
weechat_free_split_command (argv);
Note
This function is not available in scripting API.

3.2.33. weechat_string_free_split_command

Free memory used by a split command.

Prototype:

void weechat_string_free_split_command (char **split_command);

Arguments:

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
Note
This function is not available in scripting API.

3.2.34. 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 long size);

Arguments:

  • size: size (in bytes)

Return value:

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

C examples:

/* examples with English locale */

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

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

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

char *str = weechat_string_format_size (15200);  /* str == "15.2 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152);  /* str == "2.10 MB" */
/* ... */
free (str);
Note
This function is not available in scripting API.

3.2.35. 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)

C 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.2.36. weechat_string_encode_base64

WeeChat ≥ 0.3.2.

Encode a string in base64.

Prototype:

void weechat_string_encode_base64 (const char *from, int length, char *to);

Arguments:

  • from: string to encode

  • length: length of string to encode (for example strlen(from))

  • to: pointer to string to store result (must be long enough, result is longer than initial string)

C example:

char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */
Note
This function is not available in scripting API.

3.2.37. weechat_string_decode_base64

WeeChat ≥ 0.3.2.

Decode a base64 string.

Prototype:

int weechat_string_decode_base64 (const char *from, char *to);

Arguments:

  • from: string to decode

  • to: pointer to string to store result (must be long enough, result is shorter than initial string)

Return value:

  • length of string stored in *to (does not count final \0)

C example:

char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */
Note
This function is not available in scripting API.

3.2.38. weechat_string_is_command_char

WeeChat ≥ 0.3.2.

Check if first char of string is a command char (default command char is /).

Prototype:

int weechat_string_is_command_char (const char *string);

Arguments:

  • string: string

Return value:

  • 1 if first char of string is a command char, otherwise 0

C examples:

int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */

Script (Python):

# prototype
is_cmdchar = weechat.string_is_command_char(string)

# examples
command_char1 = weechat.string_is_command_char("/test")  # == 1
command_char2 = weechat.string_is_command_char("test")   # == 0

3.2.39. weechat_string_input_for_buffer

WeeChat ≥ 0.3.2.

Return pointer to input text for buffer (pointer inside "string" argument), or NULL if it’s a command.

Prototype:

const char *weechat_string_input_for_buffer (const char *string);

Arguments:

  • string: string

Return value:

  • pointer into "string", or NULL

C examples:

const char *str1 = weechat_string_input_for_buffer ("test");    /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");   /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test");  /* "/test" */

Script (Python):

# prototype
str = weechat.string_input_for_buffer(string)

# examples
str1 = weechat.string_input_for_buffer("test")    # "test"
str2 = weechat.string_input_for_buffer("/test")   # ""
str3 = weechat.string_input_for_buffer("//test")  # "/test"

3.2.40. weechat_string_eval_expression

WeeChat ≥ 0.4.0, updated in 0.4.2.

Evaluate an expression and return result as a string. Special variables with format ${variable} are expanded (see command /eval in WeeChat User’s guide).

Note
Since version 1.0, nested variables are supported, for example: ${color:${variable}}.

Prototype:

char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);

Arguments:

  • expr: the expression to evaluate

  • pointers: hashtable with pointers (keys must be string, values must be pointer); pointers "window" and "buffer" are automatically added if they are not in hashtable (with pointer to current window/buffer) (can be NULL)

  • extra_vars: extra variables that will be expanded (can be NULL)

  • options: a hashtable with some options (keys and values must be string) (can be NULL):

    • type: default behavior is just to replace values in expression, other types can be selected:

      • condition: the expression is evaluated as a condition: operators and parentheses are used, result is a boolean ("0" or "1")

    • prefix: prefix before variables to replace (default: "${")

    • suffix: suffix after variables to replace (default: "}")

Return value:

  • evaluated expression (must be freed by calling "free" after use), or NULL if problem (invalid expression or not enough memory)

C examples:

struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
    weechat_hashtable_set (options, "type", "condition");
char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);           /* "core.weechat" */
char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options);  /* "1" */
char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                 /* "0" */

Script (Python):

# prototype
str = weechat.string_eval_expression(expr, pointers, extra_vars, options)

# examples
str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                           # "core.weechat"
str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"

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))
{
    /* ... */
}
Note
This function is not available in scripting API.

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 */
}
Note
This function is not available in scripting API.

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 (char *string, char replacement);

Arguments:

  • string: string

  • replacement: replacement char for invalid chars

C example:

weechat_utf8_normalize (string, '?');
Note
This function is not available in scripting API.

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);
Note
This function is not available in scripting API.

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);
Note
This function is not available in scripting API.

3.3.6. weechat_utf8_char_int

Return UTF-8 char as integer.

Prototype:

int weechat_utf8_char_int (const char *string);

Arguments:

  • string: string

Return value:

  • UTF-8 char as integer

C example:

int char_int = weechat_utf8_char_int ("être");  /* "ê" as integer */
Note
This function is not available in scripting API.

3.3.7. 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 */
Note
This function is not available in scripting API.

3.3.8. 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 */
Note
This function is not available in scripting API.

3.3.9. 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 */
Note
This function is not available in scripting API.

3.3.10. 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 */
Note
This function is not available in scripting API.

3.3.11. weechat_utf8_charcmp

Updated in 1.0.

Compare two UTF-8 chars.

Prototype:

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

Arguments:

  • string1: first string for comparison

  • string2: second string for comparison

Return value:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_utf8_charcmp ("aaa", "ccc");  /* == -2 */
Note
This function is not available in scripting API.

3.3.12. weechat_utf8_charcasecmp

Updated in 1.0.

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:

  • -1 if string1 < string2

  • 0 if string1 == string2

  • 1 if string1 > string2

C example:

int diff = weechat_utf8_charcasecmp ("aaa", "CCC");  /* == -2 */
Note
This function is not available in scripting API.

3.3.13. 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 */
Note
This function is not available in scripting API.

3.3.14. 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" */
Note
This function is not available in scripting API.

3.3.15. 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 */
Note
This function is not available in scripting API.

3.3.16. 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 */
Note
This function is not available in scripting API.

3.3.17. 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);
Note
This function is not available in scripting API.

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 occurred

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 occurred

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 occurred

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);
Note
This function is not available in scripting API.

3.4.5. weechat_file_get_content

WeeChat ≥ 0.3.1.

Get content of text file in a string.

Prototype:

char *weechat_file_get_content (const char *filename);

Arguments:

  • filename: path and file name

Return value:

  • content of file as string (must be freed by calling "free" after use)

C example:

char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);
Note
This function is not available in scripting API.

3.5. Util

Some useful functions.

3.5.1. weechat_util_timeval_cmp

Compare two "timeval" structures.

Prototype:

int weechat_util_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_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
Note
This function is not available in scripting API.

3.5.2. weechat_util_timeval_diff

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

Prototype:

long weechat_util_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_util_timeval_diff (&tv1, &tv2);
Note
This function is not available in scripting API.

3.5.3. weechat_util_timeval_add

Add interval (in milliseconds) to a timeval structure.

Prototype:

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

Arguments:

  • tv: timeval structure

  • interval: interval (in milliseconds)

C example:

weechat_util_timeval_add (&tv, 2000);  /* add 2 seconds */
Note
This function is not available in scripting API.

3.5.4. weechat_util_get_time_string

WeeChat ≥ 0.3.2.

Get date/time as a string built with "strftime".

Prototype:

char *weechat_util_get_time_string (const time_t *date);

Arguments:

  • date: pointer to date

C example:

time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));
Note
This function is not available in scripting API.

3.5.5. weechat_util_version_number

WeeChat ≥ 0.3.9.

Convert a string with WeeChat version to a number.

Prototype:

int weechat_util_version_number (const char *version);

Arguments:

  • version: WeeChat version as string (example: "0.3.9" or "0.3.9-dev")

C example:

version_number = weechat_util_version_number ("0.3.8");      /* == 0x00030800 */
version_number = weechat_util_version_number ("0.3.9-dev");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9-rc1");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9");      /* == 0x00030900 */
Note
This function is not available in scripting API.

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

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_search_pos

WeeChat ≥ 0.3.4.

Search an item position in a list.

Prototype:

int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);

Arguments:

  • weelist: list pointer

  • data: data to search in list

Return value:

  • position of item found, -1 if item was not found

C example:

int pos_item = weechat_list_search_pos (list, "my data");

Script (Python):

# prototype
pos_item = weechat.list_search_pos(list, data)

# example
pos_item = weechat.list_search_pos(list, "my data")

3.6.5. 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.6. weechat_list_casesearch_pos

WeeChat ≥ 0.3.4.

Search an item position in a list, ignoring case.

Prototype:

int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);

Arguments:

  • weelist: list pointer

  • data: data to search in list

Return value:

  • position of item found, -1 if item was not found

C example:

int pos_item = weechat_list_casesearch_pos (list, "my data");

Script (Python):

# prototype
pos_item = weechat.list_casesearch_pos(list, data)

# example
pos_item = weechat.list_casesearch_pos(list, "my data")

3.6.7. 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.8. 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.9. 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.10. 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 first 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.11. 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.12. 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.13. 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.14. 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.15. 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. Hashtables

Hashtable functions.

3.7.1. weechat_hashtable_new

WeeChat ≥ 0.3.3.

Create a new hashtable.

Prototype:

struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned long long (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                                   const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));

Arguments:

  • size: size of internal array to store hashed keys, a high value uses more memory, but has better performance (this is not a limit for number of items in hashtable)

  • type_keys: type for keys in hashtable:

    • WEECHAT_HASHTABLE_INTEGER

    • WEECHAT_HASHTABLE_STRING

    • WEECHAT_HASHTABLE_POINTER

    • WEECHAT_HASHTABLE_BUFFER

    • WEECHAT_HASHTABLE_TIME

  • type_values: type for values in hashtable:

    • WEECHAT_HASHTABLE_INTEGER

    • WEECHAT_HASHTABLE_STRING

    • WEECHAT_HASHTABLE_POINTER

    • WEECHAT_HASHTABLE_BUFFER

    • WEECHAT_HASHTABLE_TIME

  • callback_hash_key: callback used to "hash" a key (key as integer value), can be NULL if key type is not "buffer" (a default hash function is used), arguments and return value:

    • struct t_hashtable *hashtable: hashtable pointer

    • const void *key: key

    • return value: hash of the key

  • callback_keycmp: callback used to compare two keys, can be NULL if key type is not "buffer" (a default comparison function is used), arguments and return value:

    • struct t_hashtable *hashtable: hashtable pointer

    • const void *key1: first key

    • const void *key2: second key

    • return value:

      • negative number if key1 is less than key2

      • 0 if key1 equals key2

      • positive number if key1 is greater than key2

Return value:

  • pointer to new hashtable, NULL if an error occurred

C example:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
Note
This function is not available in scripting API.

3.7.2. weechat_hashtable_set_with_size

WeeChat ≥ 0.3.3, updated in 0.4.2.

Add or update item in a hashtable with size for key and value.

Prototype:

struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                                          const void *key, int key_size,
                                                          const void *value, int value_size);

Arguments:

  • hashtable: hashtable pointer

  • key: key pointer

  • key_size: size of key (in bytes), used only if type of keys in hashtable is "buffer"

  • value: value pointer

  • value_size: size of value (in bytes), used only if type of values in hashtable is "buffer"

Return value:

  • pointer to item created/updated, NULL if error

C example:

weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));
Note
This function is not available in scripting API.

3.7.3. weechat_hashtable_set

WeeChat ≥ 0.3.3, updated in 0.4.2.

Add or update item in a hashtable.

Prototype:

struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);

Arguments:

  • hashtable: hashtable pointer

  • key: key pointer

  • value: value pointer

Return value:

  • pointer to item created/updated, NULL if error

C example:

weechat_hashtable_set (hashtable, "my_key", "my_value");
Note
This function is not available in scripting API.

3.7.4. weechat_hashtable_get

WeeChat ≥ 0.3.3.

Get value associated with a key in a hashtable.

Prototype:

void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);

Arguments:

  • hashtable: hashtable pointer

  • key: key pointer

Return value:

  • value for key, NULL if key is not found

C example:

void *value = weechat_hashtable_get (hashtable, "my_key");
Note
This function is not available in scripting API.

3.7.5. weechat_hashtable_has_key

WeeChat ≥ 0.3.4.

Check if a key is in the hashtable.

Prototype:

int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);

Arguments:

  • hashtable: hashtable pointer

  • key: key pointer

Return value:

  • 1 if key is in hashtable, 0 if key is not in hashtable

C example:

if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* key is in hashtable */
    /* ... */
}
Note
This function is not available in scripting API.

3.7.6. weechat_hashtable_map

WeeChat ≥ 0.3.3.

Call a function on all hashtable entries.

Prototype:

void weechat_hashtable_map (struct t_hashtable *hashtable,
                            void (*callback_map)(void *data,
                                                 struct t_hashtable *hashtable,
                                                 const void *key,
                                                 const void *value),
                            void *callback_map_data);

Arguments:

  • hashtable: hashtable pointer

  • callback_map: function called for each entry in hashtable

  • callback_map_data: pointer given to map callback when it is called

C example:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* display key and value (they are both strings here) */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);
Note
This function is not available in scripting API.

3.7.7. weechat_hashtable_map_string

WeeChat ≥ 0.3.7.

Call a function on all hashtable entries, sending keys and values as strings.

Prototype:

void weechat_hashtable_map_string (struct t_hashtable *hashtable,
                                   void (*callback_map)(void *data,
                                                        struct t_hashtable *hashtable,
                                                        const char *key,
                                                        const char *value),
                                   void *callback_map_data);

Arguments:

  • hashtable: hashtable pointer

  • callback_map: function called for each entry in hashtable

  • callback_map_data: pointer given to map callback when it is called

Note
The strings key and value sent to callback are temporary strings, they are deleted after call to callback.

C example:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* display key and value */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);
Note
This function is not available in scripting API.

3.7.8. weechat_hashtable_dup

WeeChat ≥ 1.0.

Duplicate a hashtable.

Prototype:

struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);

Arguments:

  • hashtable: hashtable pointer

Return value:

  • duplicated hashtable

C example:

struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);
Note
This function is not available in scripting API.

3.7.9. weechat_hashtable_get_integer

WeeChat ≥ 0.3.3.

Return integer value of a hashtable property.

Prototype:

int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);

Arguments:

  • hashtable: hashtable pointer

  • property: property name:

    • size: size of internal array "htable" in hashtable

    • items_count: number of items in hashtable

Return value:

  • integer value of property

C example:

int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
Note
This function is not available in scripting API.

3.7.10. weechat_hashtable_get_string

WeeChat ≥ 0.3.4.

Return string value of a hashtable property.

Prototype:

const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *property);

Arguments:

  • hashtable: hashtable pointer

  • property: property name:

    • type_keys: type for keys:

      • integer: integer

      • string: string

      • pointer: pointer

      • buffer: buffer

      • time: time

    • type_values: type for values:

      • integer: integer

      • string: string

      • pointer: pointer

      • buffer: buffer

      • time: time

    • keys: string with list of keys (format: "key1,key2,key3")

    • keys_sorted: string with list of sorted keys (format: "key1,key2,key3")

    • values: string with list of values (format: "value1,value2,value3")

    • keys_values: string with list of keys and values (format: "key1:value1,key2:value2,key3:value3")

    • keys_values_sorted: string with list of keys and values (sorted by keys) (format: "key1:value1,key2:value2,key3:value3")

Return value:

  • string value of property

C examples:

weechat_printf (NULL, "keys are type: %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "list of keys: %s",
                weechat_hashtable_get_string (hashtable, "keys"));
Note
This function is not available in scripting API.

3.7.11. weechat_hashtable_set_pointer

WeeChat ≥ 0.3.4.

Set pointer value of a hashtable property.

Prototype:

void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);

Arguments:

  • hashtable: hashtable pointer

  • property: property name:

    • callback_free_key: set callback function used to free keys in hashtable (WeeChat ≥ 0.4.2)

    • callback_free_value: set callback function used to free values in hashtable

  • pointer: new pointer value for property

C example:

void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

void
my_free_key_cb (struct t_hashtable *hashtable, void *key)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb);
Note
This function is not available in scripting API.

3.7.12. weechat_hashtable_add_to_infolist

WeeChat ≥ 0.3.3.

Add hashtable items to an infolist item.

Prototype:

int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);

Arguments:

  • hashtable: hashtable pointer

  • infolist_item: infolist item pointer

  • prefix: string used as prefix for names in infolist

Return value:

  • 1 if OK, 0 if error

C example:

weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* if hashtable contains:
     "key1" => "value 1"
     "key2" => "value 2"
   then following variables will be added to infolist item:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
*/
Note
This function is not available in scripting API.

3.7.13. weechat_hashtable_remove

WeeChat ≥ 0.3.3.

Remove an item in a hashtable.

Prototype:

void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);

Arguments:

  • hashtable: hashtable pointer

  • key: key pointer

C example:

weechat_hashtable_remove (hashtable, "my_key");
Note
This function is not available in scripting API.

3.7.14. weechat_hashtable_remove_all

WeeChat ≥ 0.3.3.

Remove all items in a hashtable.

Prototype:

void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

Arguments:

  • hashtable: hashtable pointer

C example:

weechat_hashtable_remove_all (hashtable);
Note
This function is not available in scripting API.

3.7.15. weechat_hashtable_free

WeeChat ≥ 0.3.3.

Free a hashtable.

Prototype:

void weechat_hashtable_free (struct t_hashtable *hashtable);

Arguments:

  • hashtable: hashtable pointer

C example:

weechat_hashtable_free (hashtable);
Note
This function is not available in scripting API.

3.8. Configuration files

Functions for configuration files.

3.8.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 and return value:

    • void *data: pointer

    • struct t_config_file *config_file: configuration file pointer

    • return value:

      • WEECHAT_CONFIG_READ_OK

      • WEECHAT_CONFIG_READ_MEMORY_ERROR

      • WEECHAT_CONFIG_READ_FILE_NOT_FOUND

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

Note
File is NOT created on disk by this function. It will be created by call to function weechat_config_write. 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.8.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 and return value:

    • 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

    • return value:

      • WEECHAT_CONFIG_READ_OK

      • WEECHAT_CONFIG_READ_MEMORY_ERROR

      • WEECHAT_CONFIG_READ_FILE_NOT_FOUND

  • 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 and return value:

    • 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

    • return value:

      • WEECHAT_CONFIG_WRITE_OK

      • WEECHAT_CONFIG_WRITE_ERROR

      • WEECHAT_CONFIG_WRITE_MEMORY_ERROR

  • 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 and return value:

    • void *data: pointer

    • struct t_config_file *config_file: configuration file pointer

    • const char *section_name: name of section

    • return value:

      • WEECHAT_CONFIG_WRITE_OK

      • WEECHAT_CONFIG_WRITE_ERROR

      • WEECHAT_CONFIG_WRITE_MEMORY_ERROR

  • 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 and return value:

    • 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

    • return value:

      • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

      • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

      • WEECHAT_CONFIG_OPTION_SET_ERROR

      • WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

  • 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 and return value:

    • 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

    • return value:

      • WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET

      • WEECHAT_CONFIG_OPTION_UNSET_OK_RESET

      • WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

      • WEECHAT_CONFIG_OPTION_UNSET_ERROR

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

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_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

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

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

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

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

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_CONFIG_OPTION_SET_OK_SAME_VALUE;
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

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_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* 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_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

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

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

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

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

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.8.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.8.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,
    void (*callback_change)(void *data,
                            struct t_config_option *option),
    void *callback_change_data,
    void (*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 and return value:

    • void *data: pointer

    • struct t_config_option *option: option pointer

    • const char *value: new value for option

    • return value:

      • 1 if value is OK

      • 0 if value is invalid

  • 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 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

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, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")
Note
In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat Scripting Guide for more info (fixed in version 0.4.1).

3.8.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.8.6. weechat_config_search_section_option

Search a section and an option in a configuration file or section.

Prototype:

void weechat_config_search_section_option (struct t_config_file *config_file,
                                           struct t_config_section *section,
                                           const char *option_name,
                                           struct t_config_section **section_found,
                                           struct t_config_option **option_found);

Arguments:

  • config_file: configuration file pointer

  • section: section pointer

  • option_name: option name

  • section_found: pointer to section pointer, will be set to section of option, if found

  • option_found: pointer to an option pointer, will be set to option pointer, if found

C example:

struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_section_option(config_file,
                                     section,
                                     "option",
                                     &ptr_section,
                                     &ptr_option);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}
Note
This function is not available in scripting API.

3.8.7. weechat_config_search_with_string

Get file/section/option info about 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,
                                        char **pos_option_name);

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

  • pos_option_name: pointer to a string pointer, will be set to pointer to name of option, if found

C example:

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

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option,
                                   &option_name);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}
Note
This function is not available in scripting API.

3.8.8. 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.8.9. 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 occurred

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.8.10. 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 change 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 occurred

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.8.11. 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 change 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 occurred

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.8.12. 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 occurred

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.8.13. 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.8.14. 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");
Note
This function is not available in scripting API.

3.8.15. 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
is_null = weechat.config_option_is_null(option)

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

3.8.16. 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
is_null = weechat.config_option_default_is_null(option)

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

3.8.17. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_boolean(option)

# example
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...

3.8.18. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_boolean_default(option)

# example
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...

3.8.19. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);

Script (Python):

# prototype
value = weechat.config_integer(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)

3.8.20. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);

Script (Python):

# prototype
value = weechat.config_integer_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)

3.8.21. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);

Script (Python):

# prototype
value = weechat.config_string(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)

3.8.22. weechat_config_string_default

Return default string value of option.

Prototype:

const char *weechat_config_string_default (struct t_config_option *option);

Arguments:

  • option: option pointer

Return value:

  • default string value of option

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);

Script (Python):

# prototype
value = weechat.config_string_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)

3.8.23. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);

Script (Python):

# prototype
value = weechat.config_color(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_color(option)

3.8.24. 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:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);

Script (Python):

# prototype
value = weechat.config_color_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_color_default(option)

3.8.25. 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.8.26. 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.8.27. 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 occurred

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.8.28. 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.8.29. 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.8.30. 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.8.31. 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.8.32. weechat_config_section_free

Free a section.

Prototype:

void weechat_config_section_free (struct t_config_section *section);

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.8.33. 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.8.34. 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.8.35. 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.8.36. 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.8.37. 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 occurred

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_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.8.38. weechat_config_set_desc_plugin

WeeChat ≥ 0.3.5.

Set description for option in plugins configuration file (plugins.conf).

Prototype:

void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);

Arguments:

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

  • description: description for option

Note
It is not a problem if option (plugins.var.xxx.option_name) does not exist. A future creation of option with this name will use this description.

C example:

weechat_config_set_desc_plugin ("option", "description of option");

Script (Python):

# prototype
weechat.config_set_desc_plugin(option_name, description)

# example
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")

3.8.39. 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 occurred

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.9. Key bindings

Functions for key bindings.

3.9.1. weechat_key_bind

WeeChat ≥ 0.3.6.

Add new key bindings.

Note
Unlike command /key bind, this function will never change an existing key binding, only new keys are created. To remove a key binding, use weechat_key_unbind.

Prototype:

int weechat_key_bind (const char *context, struct t_hashtable *keys);

Arguments:

  • context: context for keys:

    • default: default context (common actions)

    • search: search context (when searching text in buffer)

    • cursor: free movement of cursor on screen

    • mouse: keys for mouse events

  • keys: hashtable with key bindings

Return value:

  • number of key bindings added

C example:

struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}

Script (Python):

# prototype
num_keys = weechat.key_bind(context, keys)

# example
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)

3.9.2. weechat_key_unbind

WeeChat ≥ 0.3.6.

Remove key binding(s).

Warning
When calling this function, ensure that you will not remove a user key binding.

Prototype:

int weechat_key_unbind (const char *context, const char *key);

Arguments:

  • context: context for keys (see weechat_key_bind)

  • key: key to remove or a special value "area:XXX" to remove all keys having XXX as first or second area

Return value:

  • number of key bindings removed

C examples:

/* remove a single key */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* remove all keys with area "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");

Script (Python):

# prototype
num_keys = weechat.key_unbind(context, key)

# examples

# remove a single key
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# remove all keys with area "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")

3.10. Display

Functions to display text in buffers.

3.10.1. weechat_prefix

Return a prefix.

Prototype:

const char *weechat_prefix (const char *prefix);

Arguments:

  • prefix: name of prefix (see table below)

Return value:

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

List of prefixes:

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.

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.10.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 attributes/background (see below)

    • 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

      • emphasis: toggle the emphasis for text (note: this should be used only in bars, because WeeChat uses text emphasis when searching text in buffer) (WeeChat ≥ 0.4.2)

    • bar color name:

      • bar_fg: foreground color for bar

      • bar_delim: delimiters color for bar

      • bar_bg: background color for bar

    • reset:

      • reset: reset color and attributes

      • resetcolor: reset color (keep attributes) (WeeChat ≥ 0.3.6)

Format of color is: attributes (optional) + color name + ",background" (optional). Possible attributes are:

  • * : bold text

  • ! : reverse video

  • / : italic

  • _ : underlined text

  • | : keep attributes: do not reset bold/reverse/italic/underlined when changing color (WeeChat ≥ 0.3.6)

Examples:

  • yellow : yellow

  • _green : underlined green

  • *214 : bold orange

  • yellow,red : yellow on red

  • |cyan : cyan (and keep any attribute which was set previously)

Return value:

  • string with color code, or an empty string 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("", "Color: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

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

Note
The first tabulation in message ("\t") is used to separate prefix from message.
If your message has some tabs and if you don’t want prefix, then use a space, a tab, then message (see example below): this will disable prefix (the space before tab will not be displayed).
Note
With two tabs ("\t") at beginning of message, time will not be displayed and message will have no alignment at all. Moreover, the date in message will be set to 0.

C example:

weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");
weechat_printf (buffer, "%sThis is an error!", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessage without prefix but with \t some \t tabs");
weechat_printf (buffer, "\t\tMessage without time/alignment");
weechat_printf (buffer, "\t\t");  /* empty line (without time) */

Script (Python):

# prototype
weechat.prnt(buffer, message)

# example
weechat.prnt("", "Hello on WeeChat buffer")
weechat.prnt(buffer, "Hello on this buffer")
weechat.prnt(buffer, "%sThis is an error!" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessage without prefix but with \t some \t tabs")
weechat.prnt(buffer, "\t\tMessage without time/alignment")
weechat.prnt(buffer, "\t\t")  # empty line (without time)
Note
Function is called "print" in scripts ("prnt" in Python).

3.10.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 (0 means current date/time)

  • message: message to display

C example:

weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");
Note
This function is not available in scripting API.

3.10.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'");
Note
This function is not available in scripting API.

3.10.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 (0 means current date/time)

  • tags: comma separated list of tags

  • message: message to display

Tags commonly used (non-exhaustive list):

Tag Description

no_filter

Line can not be filtered

no_highlight

No highlight is possible on line

no_log

Line is not written in log file

log0 … log9

Level of log for line (see /help logger)

notify_none

Buffer with line is not added to hotlist

notify_message

Buffer with line is added to hotlist with level "message"

notify_private

Buffer with line is added to hotlist with level "private"

notify_highlight

Buffer with line is added to hotlist with level "highlight"

nick_xxx

Message is from nick "xxx"

prefix_nick_ccc

Prefix is a nick with color "ccc"

host_xxx

Username and host in message

irc_xxx

IRC message "xxx" (can be a command or a 3-digits number)

irc_numeric

IRC numeric message

irc_error

Error from IRC server

irc_action

Action from a nick (command /me)

irc_ctcp

CTCP message

irc_ctcp_reply

Reply to CTCP message

irc_smart_filter

IRC message that can be filtered with the "smart filter"

away_info

Message with away info

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.10.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); a negative value adds a line after last line displayed: absolute value of y is the number of lines after last line (for example -1 is immediately after last line, -2 is 2 lines after last line) (WeeChat ≥ 1.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.10.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.11. Hooks

Hook priority

WeeChat ≥ 0.3.4.

In some hooks, you can set a priority. A hook with higher priority is at the beginning of hooks list, so it will be found and executed before other hooks. It’s useful for modifiers, because execution order is important.

To set a priority, you must use this syntax, for argument where priority is allowed: "nnn|name" where "nnn" is non-negative integer with priority and "name" the name for argument (priority does not appear in name, it is automatically removed from string).

Default priority is 1000.

C example:

/* hook modifier with priority = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL);

Following hook types allow priority: command, command_run, signal, hsignal, config, completion, modifier, info, info_hashtable, infolist, hdata, focus.

3.11.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 (priority allowed, see note about priority)

  • 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 and return value:

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

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Default completion codes are:

Plugin Name Description

alias

alias

list of aliases

alias

alias_value

value of alias

aspell

aspell_dicts

list of aspell installed dictionaries

aspell

aspell_langs

list of all languages supported by aspell

exec

exec_commands_ids

ids (numbers and names) of executed commands

guile

guile_script

list of scripts

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_kick

default kick message

irc

irc_msg_part

default part message for IRC channel

irc

irc_notify_nicks

nicks in notify list

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

script

script_files

files in script directories

script

script_scripts

list of scripts in repository

script

script_scripts_installed

list of scripts installed (from repository)

script

script_tags

tags of scripts in repository

tcl

tcl_script

list of scripts

trigger

trigger_hook_arguments

default arguments for a hook

trigger

trigger_hook_command

default command for a hook

trigger

trigger_hook_conditions

default conditions for a hook

trigger

trigger_hook_rc

default return codes for hook callback

trigger

trigger_hook_regex

default regular expression for a hook

trigger

trigger_hooks

hooks for triggers

trigger

trigger_hooks_filter

hooks for triggers (for filter in monitor buffer)

trigger

trigger_names

triggers

trigger

trigger_option_value

value of a trigger option

trigger

trigger_options

options for triggers

weechat

bars_names

names of bars

weechat

bars_options

options for bars

weechat

buffer_properties_get

properties that can be read on a buffer

weechat

buffer_properties_set

properties that can be set on a buffer

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

cursor_areas

areas ("chat" or bar name) for free cursor movement

weechat

env_value

value of an environment variable

weechat

env_vars

environment variables

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

keys_codes_for_reset

key codes that can be reset (keys added, redefined or removed)

weechat

keys_contexts

key contexts

weechat

layouts_names

names of layouts

weechat

nicks

nicks in nicklist of current buffer

weechat

palette_colors

palette colors

weechat

plugins_commands

commands defined by plugins

weechat

plugins_installed

names of plugins installed

weechat

plugins_names

names of plugins

weechat

proxies_names

names of proxies

weechat

proxies_options

options for proxies

weechat

secured_data

names of secured data (file sec.conf, section data)

weechat

weechat_commands

weechat commands

weechat

windows_numbers

numbers of windows

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 occurred

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 have following values:

  • argv:

    • argv[0] == "/command"

    • argv[1] == "abc"

    • argv[2] == "def"

    • argv[3] == "ghi"

  • argv_eol:

    • argv_eol[0] == "/command abc def ghi"

    • argv_eol[1] == "abc def ghi"

    • argv_eol[2] == "def ghi"

    • argv_eol[3] == "ghi"

For scripts, args has value "abc def 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.11.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 (wildcard "*" is allowed) (priority allowed, see note about priority)

  • callback: function called when command is run, arguments and return value:

    • void *data: pointer

    • struct t_gui_buffer *buffer: buffer where command is executed

    • const char *command: the command executed, with its arguments

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_OK_EAT

      • WEECHAT_RC_ERROR

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

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.11.3. weechat_hook_timer

Hook a timer.

Prototype:

struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int 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 0

  • max_calls: number of calls to timer (if 0, then timer has no end)

  • callback: function called when time is reached, arguments and return value:

    • void *data: pointer

    • int remaining_calls: remaining calls (-1 if timer has no end)

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

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.11.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 and return value:

    • void *data: pointer

    • int fd: file descriptor

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

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.11.5. weechat_hook_process

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

Note
Since version 0.3.9.2, the shell is not used any more to execute the command. WeeChat makes an automatic split of the command and its arguments (like the shell does).
If the split is not correct (according to quotes in your command), or if you want to use shell, you can use function weechat_hook_process_hashtable with arguments in the hashtable options (WeeChat ≥ 0.4.0).

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 or URL (WeeChat ≥ 0.3.7) (see below)

  • 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 and return value:

    • void *data: pointer

    • const char *command: command executed by child

    • int return_code: return code:

      • >= 0: child return code for a command, and for URL possible values are:

        • 0: transfer OK

        • 1: invalid URL

        • 2: transfer error

        • 3: not enough memory

        • 4: error with a file

      • < 0: WEECHAT_HOOK_PROCESS_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)

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

When command has ended, or if timeout is reached, WeeChat will automatically unhook (and kill process if it is still running).

The command can be an URL with format: "url:http://www.example.com", to download content of URL (WeeChat ≥ 0.3.7). Options are possible for URL with function weechat_hook_process_hashtable.

Tip
If you want to retrieve infos about WeeChat (like current stable version, latest git commit, …), you can use URLs on page http://weechat.org/dev/info
Note
Buffer size for sending data to callback is 64KB (there are 2 buffers: one for stdout and one for stderr). If output from child process (stdout or stderr) is longer than 64KB, callback will be called more than one time.
Important
Even if most of times your callback is called only once, you must ensure that many calls to callback are OK in your code: you must concatenate data issued by many calls and use data only when return code is non-negative.

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.11.6. weechat_hook_process_hashtable

WeeChat ≥ 0.3.7.

Hook a process (launched with fork) using options in a hashtable, and catch output.

Prototype:

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

Arguments are the same as function weechat_hook_process, with an extra argument:

  • options: options for command executed; the hashtable is duplicated in function, so it’s safe to free it after this call

For a standard command (not beginning with "url:"), following options are available:

Option Value Description

argN (N ≥ 1)
(WeeChat ≥ 0.4.0)

any string

Arguments for command; if no argument is given with these options, the command is automatically split like the shell does (and then command arguments are read in the command argument)

stdin
(WeeChat ≥ 0.4.3)

(not used)

Create a pipe for writing data on standard input (stdin) of child process (see function weechat_hook_set)

buffer_flush
(WeeChat ≥ 1.0)

number of bytes

Minimum number of bytes to flush stdout/stderr (to send output to callback), between 1 and 65536 (default); 1 = send any output immediately to the callback

detached
(WeeChat ≥ 1.0)

(not used)

Run the process in a detached mode: stdout and stderr are redirected to /dev/null

For command "url:…", following options are available (see man curl_easy_setopt for a description of each option):

Option Type Constants (1)

verbose

long

header

long

noprogress

long

nosignal

long

wildcardmatch

long

failonerror

long

protocols

mask

http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, all

redir_protocols

mask

http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, all

proxy

string

proxyport

long

proxytype

long

http, http_1_0, socks4, socks5, socks4a, socks5_hostname

noproxy

string

httpproxytunnel

long

socks5_gssapi_service

string

socks5_gssapi_nec

long

interface

string

localport

long

localportrange

long

dns_cache_timeout

long

buffersize

long

port

long

tcp_nodelay

long

address_scope

long

tcp_keepalive

long

tcp_keepidle

long

tcp_keepintvl

long

netrc

long

ignored, optional, required

netrc_file

string

userpwd

string

proxyuserpwd

string

username

string

password

string

proxyusername

string

proxypassword

string

login_options

string

httpauth

mask

none, basic, digest, gssnegotiate, ntlm, digest_ie, ntlm_wb, only, any, anysafe

tlsauth_type

mask

none, srp

tlsauth_username

string

tlsauth_password

string

proxyauth

mask

none, basic, digest, gssnegotiate, ntlm, digest_ie, ntlm_wb, only, any, anysafe

sasl_ir

long

xoauth2_bearer

string

autoreferer

long

accept_encoding

string

transfer_encoding

long

followlocation

long

unrestricted_auth

long

maxredirs

long

postredir

mask

post_301, post_302

put

long

post

long

postfields

string

postfieldsize

long

postfieldsize_large

long long

copypostfields

string

referer

string

useragent

string

headeropt

mask

unified, separate

cookie

string

cookiefile

string

cookiejar

string

cookiesession

long

cookielist

string

httpget

long

http_version

long

none, 1_0, 1_1

ignore_content_length

long

http_content_decoding

long

http_transfer_decoding

long

expect_100_timeout_ms

long

mail_from

string

mail_auth

string

tftp_blksize

long

ftpport

string

dirlistonly

long

append

long

ftp_use_eprt

long

ftp_use_epsv

long

ftp_use_pret

long

ftp_create_missing_dirs

long

ftp_response_timeout

long

ftp_alternative_to_user

string

ftp_skip_pasv_ip

long

ftpsslauth

long

default, ssl, tls

ftp_ssl_ccc

long

ccc_none, ccc_passive, ccc_active

ftp_account

string

ftp_filemethod

long

multicwd, nocwd, singlecwd

rtsp_request

long

options, describe, announce, setup, play, pause, teardown, get_parameter, set_parameter, record, receive

rtsp_session_id

string

rtsp_stream_uri

string

rtsp_transport

string

rtsp_client_cseq

long

rtsp_server_cseq

long

transfertext

long

proxy_transfer_mode

long

crlf

long

range

string

resume_from

long

resume_from_large

long long

customrequest

string

filetime

long

nobody

long

infilesize

long

infilesize_large

long long

upload

long

maxfilesize

long

maxfilesize_large

long long

timecondition

long

none, ifmodsince, ifunmodsince, lastmod

timevalue

long

timeout

long

timeout_ms

long

low_speed_limit

long

low_speed_time

long

max_send_speed_large

long long

max_recv_speed_large

long long

maxconnects

long

fresh_connect

long

forbid_reuse

long

connecttimeout

long

connecttimeout_ms

long

ipresolve

long

whatever, v4, v6

connect_only

long

use_ssl

long

none, try, control, all

dns_interface

string

dns_local_ip4

string

dns_local_ip6

string

dns_servers

string

accepttimeout_ms

long

sslcert

string

sslcerttype

string

sslkey

string

sslkeytype

string

keypasswd

string

ssl_enable_alpn

long

ssl_enable_npn

long

sslengine

string

sslengine_default

long

sslversion

long

default, tlsv1, sslv2, sslv3

ssl_verifypeer

long

cainfo

string

issuercert

string

capath

string

crlfile

string

ssl_verifyhost

long

certinfo

long

random_file

string

egdsocket

string

ssl_cipher_list

string

ssl_sessionid_cache

long

ssl_options

long

allow_beast

krblevel

string

gssapi_delegation

long

none, policy_flag, flag

ssh_auth_types

mask

none, policy_flag, flag

ssh_host_public_key_md5

string

ssh_public_keyfile

string

ssh_private_keyfile

string

ssh_knownhosts

string

new_file_perms

long

new_directory_perms

long

Note
(1) When constants are available they must be used as value for option. For options with type "mask", format is: "value1+value2+value3".

For URL, two extra options (strings) are allowed for input/output file:

  • file_in: file to read and send with URLs (post file)

  • file_out: write downloaded URL/file in this file (instead of standard output)

Return value:

  • pointer to new hook, NULL if error occurred

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;
}

/* example 1: download URL */
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
{
    weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://weechat.org/",
                                                                     options,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options);
}

/* example 2: execute a notify program with a message from someone */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message);  /* untrusted argument */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* example 3: call shell to execute a command (command must be SAFE) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd2);
}

Script (Python):

# prototype
hook = weechat.hook_process_hashtable(command, options, 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

# example 1: download URL
hook1 = weechat.hook_process_hashtable("url:http://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# example 2: execute a notify program with a message from someone
hook2 = weechat.hook_process_hashtable("my-notify-command",
                                       {"arg1": "-from",
                                        "arg2": nick,
                                        "arg3": "-msg",
                                        "arg4": message},  # untrusted argument
                                       20000, "my_process_cb", "")

# example 3: call shell to execute a command (command must be SAFE)
hook3 = weechat.hook_process_hashtable("sh",
                                       {"arg1": "-c",
                                        "arg2": "ls -l /tmp | grep something"},
                                       20000, "my_process_cb", "")

3.11.7. 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 ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     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

  • ipv6: 1 to use IPv6 (with fallback to IPv4), 0 to use only IPv4

  • retry: retry count, used to fallback to IPv4 hosts if IPv6 hosts connect but then fail to accept the client

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

  • gnutls_priorities: priorities for gnutls (for syntax, see documentation of function gnutls_priority_init in gnutls manual), basic values are:

    • PERFORMANCE

    • NORMAL (default)

    • SECURE128

    • SECURE256

    • EXPORT

    • NONE

  • local_hostname: local hostname to use for connection (optional)

  • callback: function called when connection is OK or failed, arguments and return value:

    • 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

      • WEECHAT_HOOK_CONNECT_TIMEOUT: timeout

      • WEECHAT_HOOK_CONNECT_SOCKET_ERROR: unable to create socket

    • gnutls_rc: return value of gnutls_handshake()

    • sock: socket used to connect

    • const char *error: return value of gnutls_strerror(gnutls_rc)

    • const char *ip_address: IP address found

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

int
my_connect_cb (void *data, int status, int gnutls_rc, int sock,
               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;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

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

Script (Python):

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

# example
def my_connect_cb(data, status, gnutls_rc, sock, 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:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

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

3.11.8. weechat_hook_print

Updated in 0.4.3 and 1.0.

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: catch only messages with these tags (optional):

    • with WeeChat ≥ 0.4.3: comma-separated list of tags that must be in message (logical "or"); it is possible to combine many tags as a logical "and" with separator "+"; wildcard "*" is allowed in tags

    • with WeeChat ≤ 0.4.2: comma-separated list of tags that must all be in message (logical "and")

  • message: only messages with this string will be caught (optional, case insensitive)

  • strip_colors: if 1, colors will be stripped from message displayed, before calling callback

  • callback: function called when a message is printed, arguments and return value:

    • 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

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

Important
In scripts, with WeeChat ≥ 1.0, the callback arguments displayed and highlight are integers (with WeeChat ≤ 0.4.3, they were strings).
To be compatible with all versions, it is recommended to convert the argument to integer before testing it, for example in Python: "if int(highlight):".

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):
    if int(highlight):
        # ...
    return weechat.WEECHAT_RC_OK

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

3.11.9. 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, wildcard "*" is allowed (priority allowed, see note about priority) (see table below)

  • callback: function called when signal is received, arguments and return value:

    • void *data: pointer

    • const char *signal: signal received

    • const char *type_data: type of data sent with signal:

      • WEECHAT_HOOK_SIGNAL_STRING: string

      • WEECHAT_HOOK_SIGNAL_INT: integer number

      • WEECHAT_HOOK_SIGNAL_POINTER: pointer

    • void *signal_data: data sent with signal

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_OK_EAT (stop sending the signal immediately) (WeeChat ≥ 0.4.0)

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

List of signals sent by WeeChat and plugins:

Plugin Signal Arguments Description

aspell

aspell_suggest
(WeeChat ≥ 0.4.0)

Pointer: buffer

New suggestions for a misspelled word

guile

guile_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Scheme script loaded

guile

guile_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Scheme script unloaded

guile

guile_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Scheme script(s) installed

guile

guile_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Scheme script(s) removed

irc

xxx,irc_in_yyy (1)

String: message

IRC message from server (before irc plugin uses it, signal sent only if message is not ignored)

irc

xxx,irc_in2_yyy (1)

String: message

IRC message from server (after irc plugin uses it, signal sent only if message is not ignored)

irc

xxx,irc_raw_in_yyy (1)
(WeeChat ≥ 0.3.2)

String: message

IRC message from server (before irc plugin uses it, signal sent even if message is ignored)

irc

xxx,irc_raw_in2_yyy (1)
(WeeChat ≥ 0.3.2)

String: message

IRC message from server (after irc plugin uses it, signal sent even if message is ignored)

irc

xxx,irc_out1_yyy (1)
(WeeChat ≥ 0.3.7)

String: message

IRC message sent to server (before automatic split to fit in 512 bytes)

irc

xxx,irc_out_yyy (1)

String: message

IRC message sent to server (after automatic split to fit in 512 bytes)

irc

xxx,irc_outtags_yyy (1)
(WeeChat ≥ 0.3.4)

String: tags + ";" + message

Tags + 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_opened
(WeeChat ≥ 0.3.7)

Pointer: buffer

Server buffer 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

irc

irc_notify_join
(WeeChat ≥ 0.3.8)

String: server name + "," + nick

A nick in notify list has joined server

irc

irc_notify_quit
(WeeChat ≥ 0.3.8)

String: server name + "," + nick

A nick in notify list has quit server

irc

irc_notify_away
(WeeChat ≥ 0.3.8)

String: server name + "," + nick + "," + away message

A nick in notify list is now away on server

irc

irc_notify_still_away
(WeeChat ≥ 0.3.8)

String: server name + "," + nick + "," + away message

A nick in notify list is still away on server (away message has changed)

irc

irc_notify_back
(WeeChat ≥ 0.3.8)

String: server name + "," + nick

A nick in notify list is back (away status 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

lua

lua_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Lua script loaded

lua

lua_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Lua script unloaded

lua

lua_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Lua script(s) installed

lua

lua_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Lua script(s) removed

perl

perl_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Perl script loaded

perl

perl_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Perl script unloaded

perl

perl_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Perl script(s) installed

perl

perl_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Perl script(s) removed

python

python_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Python script loaded

python

python_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Python script unloaded

python

python_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Python script(s) installed

python

python_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Python script(s) removed

relay

relay_client_connecting
(WeeChat ≥ 1.0)

Pointer: relay client

A relay client is connecting

relay

relay_client_waiting_auth
(WeeChat ≥ 1.0)

Pointer: relay client

Waiting for authentication from a relay client

relay

relay_client_auth_ok
(WeeChat ≥ 1.0)

Pointer: relay client

Successful authentication from a relay client

relay

relay_client_connected
(WeeChat ≥ 1.0)

Pointer: relay client

A relay client is connected

relay

relay_client_auth_failed
(WeeChat ≥ 1.0)

Pointer: relay client

Authentication of a relay client has failed

relay

relay_client_disconnected
(WeeChat ≥ 1.0)

Pointer: relay client

A relay client is disconnected

ruby

ruby_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Ruby script loaded

ruby

ruby_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Ruby script unloaded

ruby

ruby_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Ruby script(s) installed

ruby

ruby_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Ruby script(s) removed

tcl

tcl_script_loaded
(WeeChat ≥ 0.3.9)

String: path to script

Tcl script loaded

tcl

tcl_script_unloaded
(WeeChat ≥ 0.3.9)

String: path to script

Tcl script unloaded

tcl

tcl_script_installed
(WeeChat ≥ 0.3.9)

String: comma-separated list of paths to scripts installed

Tcl script(s) installed

tcl

tcl_script_removed
(WeeChat ≥ 0.3.9)

String: comma-separated list of scripts removed

Tcl script(s) removed

weechat

buffer_opened

Pointer: buffer

Buffer opened

weechat

buffer_closing

Pointer: buffer

Closing buffer

weechat

buffer_closed

Pointer: buffer

Buffer closed

weechat

buffer_cleared

Pointer: buffer

Buffer cleared

weechat

buffer_hidden

Pointer: buffer

Buffer hidden

weechat

buffer_unhidden

Pointer: buffer

Buffer unhidden

weechat

buffer_line_added
(WeeChat ≥ 0.3.7)

Pointer: line

Line added in a buffer

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_merged

Pointer: buffer

Buffer merged

weechat

buffer_unmerged

Pointer: buffer

Buffer unmerged

weechat

buffer_moved

Pointer: buffer

Buffer moved

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

buffer_zoomed
(WeeChat ≥ 0.4.3)

Pointer: buffer

Merged buffer zoomed

weechat

buffer_unzoomed
(WeeChat ≥ 0.4.3)

Pointer: buffer

Merged buffer unzoomed

weechat

day_changed
(WeeChat ≥ 0.3.2)

String: new date, format: "2010-01-31"

Day of system date has changed

weechat

debug_dump

String: plugin name

Dump request

weechat

debug_libs

-

Display external libraries used

weechat

filter_added

Pointer: filter

Filter added

weechat

filter_removing

Pointer: filter

Removing filter

weechat

filter_removed

-

Filter removed

weechat

filters_enabled

-

Filters enabled

weechat

filters_disabled

-

Filters disabled

weechat

hotlist_changed

-

Hotlist changed

weechat

input_paste_pending

-

Paste pending

weechat

input_search

Pointer: buffer

Text search in buffer

weechat

input_text_changed

Pointer: buffer

Input text changed

weechat

input_text_cursor_moved

Pointer: buffer

Input text cursor moved

weechat

key_bind

String: key

Key added

weechat

key_unbind

String: key

Key removed

weechat

key_pressed

String: key pressed

Key pressed

weechat

key_combo_default
(WeeChat ≥ 1.0)

String: key combo

Key combo in default context

weechat

key_combo_search
(WeeChat ≥ 1.0)

String: key combo

Key combo in search context

weechat

key_combo_cursor
(WeeChat ≥ 1.0)

String: key combo

Key combo in cursor context

weechat

nicklist_group_added
(WeeChat ≥ 0.3.2)

String: buffer pointer + "," + group name

Group added in nicklist

weechat

nicklist_group_changed
(WeeChat ≥ 0.3.4)

String: buffer pointer + "," + group name

Group changed in nicklist

weechat

nicklist_group_removing
(WeeChat ≥ 0.4.1)

String: buffer pointer + "," + group name

Removing group from nicklist

weechat

nicklist_group_removed
(WeeChat ≥ 0.3.2)

String: buffer pointer + "," + group name

Group removed from nicklist

weechat

nicklist_nick_added
(WeeChat ≥ 0.3.2)

String: buffer pointer + "," + nick name

Nick added in nicklist

weechat

nicklist_nick_changed
(WeeChat ≥ 0.3.4)

String: buffer pointer + "," + nick name

Nick changed in nicklist

weechat

nicklist_nick_removing
(WeeChat ≥ 0.4.1)

String: buffer pointer + "," + nick name

Removing nick from nicklist

weechat

nicklist_nick_removed
(WeeChat ≥ 0.3.2)

String: buffer pointer + "," + nick name

Nick removed from nicklist

weechat

partial_completion

-

Partial completion happened

weechat

plugin_loaded
(WeeChat ≥ 0.3.9)

String: path to plugin loaded

Plugin loaded

weechat

plugin_unloaded
(WeeChat ≥ 0.3.9)

String: name of plugin unloaded (example: "irc")

Plugin unloaded

weechat

quit

String: arguments for /quit

Command /quit issued by user

weechat

signal_sigwinch
(WeeChat ≥ 0.4.3)

-

Signal SIGWINCH received (terminal was resized)

weechat

upgrade

String: "quit" if "-quit" argument was given for /upgrade, otherwise NULL

Command /upgrade issued by user

weechat

upgrade_ended
(WeeChat ≥ 0.3.4)

-

End of upgrade process (command /upgrade)

weechat

weechat_highlight

String: message with prefix

Highlight happened

weechat

weechat_pv

String: message with prefix

Private message displayed

weechat

window_closing
(WeeChat ≥ 0.3.6)

Pointer: window

Closing window

weechat

window_closed
(WeeChat ≥ 0.3.6)

Pointer: window

Window closed

weechat

window_opened
(WeeChat ≥ 0.4.1)

Pointer: window

Window opened

weechat

window_scrolled

Pointer: window

Scroll in window

weechat

window_switch
(WeeChat ≥ 0.3.7)

Pointer: window

Switching window

weechat

window_zoom

Pointer: current window

Zomming window

weechat

window_zoomed

Pointer: current window

Window zoomed

weechat

window_unzoom

Pointer: current window

Unzooming window

weechat

window_unzoomed

Pointer: current window

Window unzoomed

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

Accept xfer resume

xfer

xfer_send_accept_resume

Pointer: infolist with xfer info

Xfer resumed

xfer

xfer_start_resume

Pointer: infolist with xfer info

Start resume

xfer

xfer_resume_ready

Pointer: infolist with xfer info

Xfer resume ready

xfer

xfer_ended
(WeeChat ≥ 0.3.2)

Pointer: infolist with xfer info

Xfer has ended

Note
(1) xxx is IRC server name, yyy is IRC command name.

C example:

int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_signal(signal, callback, callback_data)

# example
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# catch signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")

3.11.10. weechat_hook_signal_send

Updated in 1.0.

Send a signal.

Prototype:

int weechat_hook_signal_send (const char *signal, const char *type_data,
                              void *signal_data);

Arguments:

  • signal: signal to send

  • type_data: type of data sent with signal (see weechat_hook_signal)

  • signal_data: data sent with signal

Return value (WeeChat ≥ 1.0):

  • return code of last callback executed (WEECHAT_RC_OK if no callback was executed):

    • WEECHAT_RC_OK

    • WEECHAT_RC_OK_EAT

    • WEECHAT_RC_ERROR

C example:

int rc = weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);

Script (Python):

# prototype
rc = weechat.hook_signal_send(signal, type_data, signal_data)

# example
rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
Signal logger_backlog

The signal "logger_backlog" can be sent to display backlog (chat history) in buffer (for example if you open your own buffer in your plugin/script).

Argument is a pointer to buffer.

C example:

weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);

Script (Python):

weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
Signals xxx_script_install

Five signals can be sent to install a script, according to language:

  • perl_script_install

  • python_script_install

  • ruby_script_install

  • lua_script_install

  • tcl_script_install

The callback will do following actions when receiving signal:

  1. unload and remove installed script

  2. move new script to directory ~/.weechat/xxx/ (where xxx is language)

  3. create link to new script in directory ~/.weechat/xxx/autoload/

  4. load new script

These signals are used by script plugin to install scripts.

Argument is a string with path to script to install.

C example:

weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");

Script (Python):

weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")
Signals xxx_script_remove

Five signals can be sent to remove list of scripts, according to language:

  • perl_script_remove

  • python_script_remove

  • ruby_script_remove

  • lua_script_remove

  • tcl_script_remove

For each script in list, the callback will unload then remove script.

These signals are used by script plugin to remove scripts.

Argument is a string with comma-separated list of script to remove (script is name without path, for example script.py).

C example:

/* unload and remove scripts test.py and script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");

Script (Python):

# unload and remove scripts test.py and script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
Signal irc_input_send

WeeChat ≥ 0.3.4.

The signal "irc_input_send" can be sent to simulate input in an irc buffer (server, channel or private).

Argument is a string with following format:

  • internal server name (required)

  • semicolon

  • channel name (optional)

  • semicolon

  • flags used when sending message (optional, default is 1):

    • 1: queue with high priority (like user messages)

    • 2: queue with low priority (like messages automatically sent by WeeChat)

  • semicolon

  • comma-separated list of tags used when sending message (optional)

  • semicolon

  • text or command (required)

C examples:

/* say "Hello!" on freenode server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* send command "/whois FlashCode" on freenode server, with low priority */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");

Script (Python):

# say "Hello!" on freenode server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# send command "/whois FlashCode" on freenode server, with low priority
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")

3.11.11. weechat_hook_hsignal

WeeChat ≥ 0.3.4.

Hook a hsignal (signal with hashtable).

Prototype:

struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     void *callback_data);

Arguments:

  • signal: signal to catch, wildcard "*" is allowed (priority allowed, see note about priority) (see table below)

  • callback: function called when signal is received, arguments and return value:

    • void *data: pointer

    • const char *signal: signal received

    • struct t_hashtable *hashtable: hashtable

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_OK_EAT (stop sending the signal immediately) (WeeChat ≥ 0.4.0)

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

List of hsignals:

Plugin Signal Arguments Description

irc

irc_redirection_xxx_yyy (1)
(WeeChat ≥ 0.3.4)

See hsignal_irc_redirect_command

Redirection output

weechat

nicklist_group_added
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
group (struct t_gui_nick_group *): group

Group added in nicklist

weechat

nicklist_nick_added
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
nick (struct t_gui_nick *): nick

Nick added in nicklist

weechat

nicklist_group_removing
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
group (struct t_gui_nick_group *): group

Removing group from nicklist

weechat

nicklist_nick_removing
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
nick (struct t_gui_nick *): nick

Removing nick from nicklist

weechat

nicklist_group_changed
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
group (struct t_gui_nick_group *): group

Group changed in nicklist

weechat

nicklist_nick_changed
(WeeChat ≥ 0.4.1)

buffer (struct t_gui_buffer *): buffer
parent_group (struct t_gui_nick_group *): parent group
nick (struct t_gui_nick *): nick

Nick changed in nicklist

Note
(1) xxx is signal argument used in redirection, yyy is redirection pattern.

C example:

int
my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_hsignal(signal, callback, callback_data)

# example
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")

3.11.12. weechat_hook_hsignal_send

WeeChat ≥ 0.3.4, updated in 1.0.

Send a hsignal (signal with hashtable).

Prototype:

int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);

Arguments:

  • signal: signal to send

  • hashtable: hashtable

Return value (WeeChat ≥ 1.0):

  • return code of last callback executed (WEECHAT_RC_OK if no callback was executed):

    • WEECHAT_RC_OK

    • WEECHAT_RC_OK_EAT

    • WEECHAT_RC_ERROR

C example:

int rc;
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}

Script (Python):

# prototype
rc = weechat.hook_hsignal_send(signal, hashtable)

# example
rc = weechat.hook_hsignal_send("my_hsignal", {"key": "value"})
Hsignal irc_redirect_command

WeeChat ≥ 0.3.4.

The hsignal "irc_redirect_command" can be sent to redirect output of irc command to a callback.

Argument is a hashtable with following entries (keys and values are string):

  • server: internal server name (required)

  • pattern: redirect pattern to use (required), either a default one (defined by irc plugin), or a user pattern (see [hsignal_irc_redirect_pattern]), default patterns are:

    • ison

    • list

    • mode_channel

    • mode_channel_ban ("mode #channel b")

    • mode_channel_ban_exception ("mode #channel e")

    • mode_channel_invite ("mode #channel I")

    • mode_user

    • monitor

    • names

    • ping

    • time

    • topic

    • userhost

    • who

    • whois

    • whowas

  • signal: signal name (required)

  • count: number of times redirection will work (optional, 1 by default)

  • string: string that must be in irc messages received (optional, but recommended, if a string can be used to identify messages)

  • timeout: timeout for redirect, in seconds (optional, 60 by default)

  • cmd_filter: comma-separated list of irc commands to filter (only these commands will be sent to callbacks, other will be ignored) (optional)

Immediately after sending this hsignal, you must send command to irc server, and redirection will be used for this command.

When complete answer to your command has been be received, a hsignal will be send. This hsignal has name irc_redirection_xxx_yyy where xxx is the signal and yyy the pattern used.

Hashtable sent in hsignal has following content (key and values are strings):

  • output: output of command (messages are separated by "\n")

  • output_size: number of bytes in output (as string)

  • error: error string (if an error occurred):

    • timeout: redirection stopped after timeout

  • server: internal server name

  • pattern: redirect pattern

  • signal: signal name

  • command: redirected command

C example:

int
test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}

Script (Python):

def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          {"server": "freenode", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
Hsignal irc_redirect_pattern

WeeChat ≥ 0.3.4.

The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc redirect (see [hsignal_irc_redirect_command]).

Argument is a hashtable with following entries (keys and values are string):

  • pattern: name of pattern (required)

  • timeout: default timeout for pattern, in seconds (optional, 60 by default)

  • cmd_start: comma-separated list of commands starting redirect (optional)

  • cmd_stop: comma-separated list of commands stopping redirect (required)

  • cmd_extra: comma-separated list of commands that may be received after stop commands (optional)

For each command in cmd_start, cmd_stop and cmd_extra, it is possible to give integer with position of "string" that must be found in received message, for example:

352:1,354,401:1

For commands 352 and 401, "string" must be found in received message, as first argument.

Important
The pattern is destroyed when it is used by a redirection. If you need pattern for many redirections, you must create pattern before each redirect.

C example:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}

Script (Python):

weechat.hook_hsignal_send("irc_redirect_pattern",
                          {"pattern": "my_whois", "timeout": "30",
                           "cmd_start": "311:1",
                           "cmd_stop": "318:1,401:1,402:1,431:1,461",
                           "cmd_extra": "318:1"})
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...

3.11.13. weechat_hook_config

Hook a configuration option.

Prototype:

struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);

Arguments:

  • option: option, format is full name, as used with command /set (for example: weechat.look.item_time_format), wildcard "*" is allowed (priority allowed, see note about priority)

  • callback: function called when configuration option is changed, arguments and return value:

    • void *data: pointer

    • const char *option: name of option

    • const char *value: new value for option

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch changes to option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_config(option, callback, callback_data)

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

# catch changes to option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")

3.11.14. weechat_hook_completion

Hook a completion.

Prototype:

struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);

Arguments:

  • completion_item: name of completion item, after you can use %(name) in a command hooked (argument completion) (priority allowed, see note about priority)

  • description: description of completion

  • callback: function called when completion item is used (user is completing something using this item), arguments and return value:

    • void *data: pointer

    • const char *completion_item: name of completion item

    • struct t_gui_buffer *buffer: buffer where completion is made

    • struct t_gui_completion *completion: structure used to add words for completion (see weechat_hook_completion_list_add)

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Note
Completion names are global (shared across WeeChat and plugins). So it is recommended to choose a name with a unique prefix, like "plugin_xxx" (where "xxx" is your item name).
Important
The callback must only call function weechat_hook_completion_list_add and must NOT update the command line.
To update the command line when Tab is pressed, you can use the function weechat_hook_command_run with command: "/input complete_next" (and you must return WEECHAT_RC_OK_EAT if your callback has updated the command line, so that WeeChat will not perform the completion).

Return value:

  • pointer to new hook, NULL if error occurred

C example:

int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_word2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")

3.11.15. weechat_hook_completion_get_string

WeeChat ≥ 0.3.4.

Get a completion property as string.

Prototype:

const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);

Arguments:

  • completion: completion pointer

  • property: property name:

    • base_command: command used for completion

    • base_word: word being completed

    • args: command arguments (including base word)

C example:

int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_hook_completion_get_string (completion, "args");

    /* completion depending on args */
    /* ... */

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
value = weechat.hook_completion_get_string(completion, property)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    # get arguments of command
    args = weechat.hook_completion_get_string(completion, "args")
    # completion depending on args
    # ...
    return weechat.WEECHAT_RC_OK

3.11.16. weechat_hook_completion_list_add

Add a word for a completion.

Prototype:

void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);

Arguments:

  • completion: completion pointer

  • word: word to add

  • nick_completion: 1 if word is a nick, otherwise 0

  • where: position where word will be inserted in list:

    • WEECHAT_LIST_POS_SORT: any position, to keep list sorted

    • WEECHAT_LIST_POS_BEGINNING: beginning of list

    • WEECHAT_LIST_POS_END: end of list

C example: see weechat_hook_completion.

Script (Python):

# prototype
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# example: see function hook_completion above

3.11.17. weechat_hook_modifier

Hook a modifier.

Prototype:

struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);

Arguments:

  • modifier: modifier name, list of modifiers used by Weechat or plugins (priority allowed, see note about priority) (see table below)

  • callback: function called when modifier is used, arguments and return value:

    • void *data: pointer

    • const char *modifier: name of modifier

    • const char *modifier_data: data for modifier

    • const char *string: string to modify

    • return value: new string

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

List of modifiers used by WeeChat and plugins:

Modifier Modifier data String Output

charset_decode

plugin.buffer_name

Any string

String decoded from charset found for plugin/buffer to UTF-8

charset_encode

plugin.buffer_name

Any string

String encoded from UTF-8 to charset found for plugin/buffer

irc_color_decode

"1" to keep colors, "0" to remove colors

Any string

String with IRC colors converted to WeeChat colors (or IRC colors removed)

irc_color_encode

"1" to keep colors, "0" to remove colors

Any string

String with IRC colors (or IRC colors removed)

irc_color_decode_ansi
(WeeChat ≥ 1.0)

"1" to keep colors, "0" to remove colors

Any string

String with ANSI colors converted to IRC colors (or ANSI colors removed)

irc_command_auth
(WeeChat ≥ 0.4.1)

Server name

Authentication command (for example: /msg nickserv identify password)

command with hidden password (for example: /msg nickserv identify ********)

irc_message_auth
(WeeChat ≥ 0.4.1)

Server name

Message displayed after /msg sent to nickserv

Message with hidden password

irc_in_xxx (1)

Server name

Content of message received from IRC server (before charset decoding)

New content of message

irc_in2_xxx (1)
(WeeChat ≥ 0.3.5)

Server name

Content of message received from IRC server (after charset decoding)

New content of message

irc_out1_xxx (1)
(WeeChat ≥ 0.3.7)

Server name

Content of message about to be sent to IRC server (before automatic split to fit in 512 bytes)

New content of message

irc_out_xxx (1)

Server name

Content of message about to be sent to IRC server (after automatic split to fit in 512 bytes)

New content of message

color_decode_ansi
(WeeChat ≥ 1.0)

"1" to keep colors, "0" to remove colors

Any string

String with ANSI colors converted to WeeChat colors (or ANSI colors removed)

bar_condition_yyy (2)

String with window pointer ("0x123..")

Empty string

"1" to display bar, "0" to hide it

history_add
(WeeChat ≥ 0.3.2)

String with buffer pointer ("0x123..")

Content of command line to add in command history (buffer and global)

String added to command history

input_text_content

String with buffer pointer ("0x123..")

Content of command line

New content of command line

input_text_display

String with buffer pointer ("0x123..")

Content of command line, without cursor tag

New string, for display only (command line is not changed)

input_text_display_with_cursor

String with buffer pointer ("0x123..")

Content of command line, with cursor tag

New string, for display only (command line is not changed)

input_text_for_buffer
(WeeChat ≥ 0.3.7)

String with buffer pointer ("0x123..")

Content of command line sent to buffer (text or command)

New content of command line sent to buffer

weechat_print

plugin + ";" + buffer_name + ";" + tags

Message printed

New message printed

Note
(1) xxx is IRC command name.
(2) yyy is bar name.

C example:

char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;

    if (!string)
        return NULL;

    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* add "xxx" to any message printed */
        snprintf (result, length, "%s xxx", string);
    }

    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_modifier(modifier, callback, callback_data)

# example
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")

3.11.18. weechat_hook_modifier_exec

Execute modifier(s).

Prototype:

char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);

Arguments:

  • modifier: modifier name

  • modifier_data: modifier data

  • string: string to modify

Return value:

  • string modified, NULL if error occurred

C example:

char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);

Script (Python):

# prototype
weechat.hook_modifier_exec(modifier, modifier_data, string)

# example
weechat.hook_modifier_exec("my_modifier", my_data, my_string)

3.11.19. weechat_hook_info

Hook an information (callback takes and returns a string).

Prototype:

struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);

Arguments:

  • info_name: name of info (priority allowed, see note about priority)

  • description: description

  • args_description: description of arguments (optional, can be NULL)

  • callback: function called when info is asked, arguments and return value:

    • void *data: pointer

    • const char *info_name: name of info

    • const char *arguments: additional arguments, depending on info

    • return value: value of info asked

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* add info "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# example
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")

3.11.20. weechat_hook_info_hashtable

WeeChat ≥ 0.3.4.

Hook an information (callback takes and returns a hashtable).

Prototype:

struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            void *callback_data);

Arguments:

  • info_name: name of info (priority allowed, see note about priority)

  • description: description

  • args_description: description of expected hashtable (optional, can be NULL)

  • output_description: description of hashtable returned by callback (optional, can be NULL)

  • callback: function called when info is asked, arguments and return value:

    • void *data: pointer

    • const char *info_name: name of info

    • struct t_hashtable *hashtable: hashtable, depending on info

    • return value: hashtable asked

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

struct t_hashtable *
my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# example
def my_info_hashtable_cb(data, info_name, hashtable):
    return {"test_key": "test_value"}

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")

3.11.21. weechat_hook_infolist

Hook an infolist: callback will return pointer to infolist asked.

Prototype:

struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      struct t_infolist *(*callback)(void *data,
                                                                     const char *infolist_name,
                                                                     void *pointer,
                                                                     const char *arguments),
                                      void *callback_data);

Arguments:

  • infolist_name: name of infolist (priority allowed, see note about priority)

  • description: description

  • pointer_description: description of pointer (optional, can be NULL)

  • args_description: description of arguments (optional, can be NULL)

  • callback: function called when infolist is asked, arguments and return value:

    • void *data: pointer

    • const char *infolist_name: name of infolist

    • void *pointer: pointer to an object that infolist must return (to get only one item in infolist)

    • const char *arguments: additional arguments, depending on infolist

    • return value: infolist asked

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;

    /* build infolist */
    /* ... */

    return my_infolist;
}

/* add infolist "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# example
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")

3.11.22. weechat_hook_hdata

Hook a hdata: callback will return pointer to hdata asked.

Prototype:

struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(void *data,
                                                               const char *hdata_name),
                                   void *callback_data);

Arguments:

  • hdata_name: name of hdata (priority allowed, see note about priority)

  • description: description

  • callback: function called when hdata is asked, arguments and return value:

    • void *data: pointer

    • const char *hdata_name: name of hdata

    • return value: hdata asked

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new hook, NULL if error occurred

C example:

struct t_hdata *
my_hdata_cb (void *data, const char *hdata_name)
{
    struct t_hdata *my_hdata;

    /* build hdata */
    /* ... */

    return my_hdata;
}

/* add hdata "my_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                              "Hdata for my structure",
                                              &my_hdata_cb, NULL);
Note
This function is not available in scripting API.

3.11.23. weechat_hook_focus

Hook a focus: mouse event or key pressed in cursor mode (free movement of cursor).

Prototype:

struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(void *data,
                                                                   struct t_hashtable *info),
                                   void *callback_data);

Arguments:

  • area: "chat" for chat area, or name of bar item (priority allowed, see note about priority)

  • callback: function called when focus is made, arguments and return value:

    • void *data: pointer

    • struct t_hashtable *info: hashtable with info on focus and strings returned by other calls to focus callbacks (with higher priority) (see table below)

    • return value: either "info" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string"), this new hashtable content will be added to info for other calls to focus callbacks

  • callback_data: pointer given to callback when it is called by WeeChat

Important
For a mouse gesture, your callback will be called two times: first time when button is pressed (here the area always matches your area), second time when button is released, and then the area may not match your area: so you must always test in your callback if area is matching before using info in hashtable.

Content of hashtable sent to callback (keys and values are of type "string"):

Key (1) Description Value examples Value if N/A

_x

Column on screen

"0" … "n"

_y

Line on screen

"0" … "n"

_key

Key or mouse event

"button1", "button2-gesture-left", …

_window

Pointer to window

"0x12345678"

""

_window_number

Number of window

"1" … "n"

"*"

_buffer

Pointer to buffer

"0x12345678"

""

_buffer_number

Number of buffer

"1" … "n"

"-1"

_buffer_plugin

Plugin name of buffer

"core", "irc", …

""

_buffer_name

Name of buffer

"weechat", "freenode.#weechat", …

""

_buffer_full_name

Full name of buffer

"core.weechat", "irc.freenode.#weechat", …

""

_buffer_localvar_XXX (2)

Local variables of buffer

any value

not set

_chat

Chat area indicator

"0" or "1"

"0"

_chat_line_x

Column in line (3)

"0" … "n"

"-1"

_chat_line_y

Line number (3)

"0" … "n"

"-1"

_chat_line_date

Line date/time

"1313237175"

"0"

_chat_line_date_printed

Line date/time (4)

"1313237175"

"0"

_chat_line_time

Time displayed

"14:06:15"

""

_chat_line_tags

Tags of line

"irc_privmsg,nick_flashy,log1"

""

_chat_line_nick

Nick of line

"FlashCode"

""

_chat_line_prefix

Prefix of line

"@FlashCode"

""

_chat_line_message

Message of line

"Hello world!"

""

_chat_word

Word at (x,y)

"Hello"

""

_chat_bol

Beginning of line ⇒ (x-1,y)

"He"

""

_chat_eol

(x,y) ⇒ end of line

"llo world!"

""

_bar_name

Name of bar

"title", "nicklist", …

""

_bar_filling

Filling of bar

"horizontal", "vertical", …

""

_bar_item_name

Name of bar item

"buffer_nicklist", "hotlist", …

""

_bar_item_line

Line in bar item

"0" … "n"

"-1"

_bar_item_col

Column in bar item

"0" … "n"

"-1"

Note
(1) There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", …) with info on second point (useful only for mouse gestures, to know where mouse button has been released).
(2) XXX is name of local variable in buffer.
(3) It is set only for buffers with free content.
(4) It is date when WeeChat adds line in buffer (greater or equal to "_chat_line_date").

Extra info for bar item "buffer_nicklist":

Key Plugin (1) Description

nick

core

Nick name

prefix

core

Prefix for nick

group

core

Group name

irc_host

irc

Host for nick (if known)

Note
(1) The name of plugin which defines a hook_focus to return info for this bar item (so for example if plugin is "irc", such info will be available only on irc buffers).

Return value:

  • pointer to new hook, NULL if error occurred

C example:

struct t_hashtable *
my_focus_nicklist_cb (void *data, struct t_hashtable *info)
{
    /* add strings in hashtable */
    /* ... */

    return info;
}

/* add focus on nicklist */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_focus(area, callback, callback_data)

# example
def my_focus_nicklist_cb(data, info):
    # build dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")

3.11.24. weechat_hook_set

WeeChat ≥ 0.3.9 (script: WeeChat ≥ 0.4.3).

Set string value of a hook property.

Prototype:

void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);

Arguments:

  • hook: something hooked with "weechat_hook_xxx()"

  • property: property name (see table below)

  • value: new value for property

Properties:

Name Hook type Value Description

subplugin

any type

any string

Name of sub plugin (commonly script name, which is displayed in /help command for a hook of type command)

stdin
(WeeChat ≥ 0.4.3)

process, process_hashtable

any string

Send data on standard input (stdin) of child process

stdin_close
(WeeChat ≥ 0.4.3)

process, process_hashtable

(not used)

Close pipe used to send data on standard input (stdin) of child process

signal
(WeeChat ≥ 1.0)

process, process_hashtable

signal number or one of these names: hup, int, quit, kill, term, usr1, usr2

Send a signal to the child process

C example:

struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");

Script (Python):

# prototype
weechat.hook_set(hook, property, value)

# example
def my_process_cb(data, command, return_code, out, err):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process_hashtable("/path/to/command", {"stdin": "1"},
                                      20000, "my_process_cb", "")
weechat.hook_set(hook, "stdin", "data sent to stdin of child process")
weechat.hook_set(hook, "stdin_close", "")  # optional

3.11.25. weechat_unhook

Unhook something hooked.

Prototype:

void weechat_unhook (struct t_hook *hook);

Arguments:

  • hook: something hooked with "weechat_hook_xxx()"

C example:

struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);

Script (Python):

# prototype
weechat.unhook(hook)

# example
weechat.unhook(my_hook)

3.11.26. weechat_unhook_all

Unhook everything that has been hooked by current plugin.

Prototype:

void weechat_unhook_all ();

C example:

weechat_unhook_all ();

Script (Python):

# prototype
weechat.unhook_all()

# example
weechat.unhook_all()

3.12. Buffers

Functions to create/query/close buffers.

3.12.1. weechat_buffer_new

Open a new buffer.

Prototype:

struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);

Arguments:

  • name: name of buffer (must be unique for plugin)

  • input_callback: function called when input text is entered on buffer, arguments and return value:

    • void *data: pointer

    • struct t_gui_buffer *buffer: buffer pointer

    • const char *input_data: input data

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

  • close_callback: function called when buffer is closed, arguments and return value:

    • void *data: pointer

    • struct t_gui_buffer *buffer: buffer pointer

    • return value:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_data: pointer given to callback when it is called by WeeChat

Return value:

  • pointer to new buffer, NULL if error occurred

C example:

int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Text: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Buffer '%s' will be closed!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);

Script (Python):

# prototype
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# example
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Text: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")

3.12.2. weechat_current_buffer

Return pointer to current buffer (buffer displayed by current window).

Prototype:

struct t_gui_buffer *weechat_current_buffer ();

Return value:

  • pointer to current buffer

C example:

weechat_printf (weechat_current_buffer (), "Text on current buffer");

Script (Python):

# prototype
buffer = weechat.current_buffer()

# example
weechat.prnt(weechat.current_buffer(), "Text on current buffer")

Updated in 1.0.

Search a buffer by plugin and/or name.

Prototype:

struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);

Arguments:

  • plugin: name of plugin, following special value is allowed:

    • ==: the name used is the buffer full name (for example: irc.freenode.#weechat instead of freenode.#weechat) (WeeChat ≥ 1.0)

  • name: name of buffer, if it is NULL or empty string, the current buffer is returned (buffer displayed by current window); if the name starts with (?i), the search is case insensitive (WeeChat ≥ 1.0)

Return value:

  • pointer to buffer found, NULL if not found

C examples:

struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "freenode.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.freenode.#test");  /* WeeChat ≥ 1.0 */

Script (Python):

# prototype
buffer = weechat.buffer_search(plugin, name)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")

3.12.4. weechat_buffer_search_main

Search WeeChat main buffer (core buffer, first buffer displayed when WeeChat is starting).

Prototype:

struct t_gui_buffer *weechat_buffer_search_main ();

Return value:

  • pointer to WeeChat main buffer (core buffer)

C example:

struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();

Script (Python):

# prototype
buffer = weechat.buffer_search_main()

# example
buffer = weechat.buffer_search_main()

3.12.5. weechat_buffer_clear

Clear content of a buffer.

Prototype:

void weechat_buffer_clear (struct t_gui_buffer *buffer);

Arguments:

  • buffer: buffer pointer

C example:

struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}

Script (Python):

# prototype
weechat.buffer_clear(buffer)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)

3.12.6. weechat_buffer_close

Close a buffer.

Prototype:

void weechat_buffer_close (struct t_gui_buffer *buffer);

Arguments:

  • buffer: buffer pointer

C example:

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);

Script (Python):

# prototype
weechat.buffer_close(buffer)

# example
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)

3.12.7. weechat_buffer_merge

Merge buffer into another buffer: both buffers will still exist separately, but with same number, and WeeChat will display lines from both buffers (mixed lines).

Prototype:

void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);

Arguments:

  • buffer: buffer pointer

  • target_buffer: target buffer, where buffer will be merged

C example:

/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());

Script (Python):

# prototype
weechat.buffer_merge(buffer, target_buffer)

# example
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())

3.12.8. weechat_buffer_unmerge

Unmerge buffer from a group of merged buffers.

Prototype:

void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);

Arguments:

  • buffer: buffer pointer

  • number: target number for detached buffer, if it is < 1, then buffer will be moved to number of buffer + 1

C example:

weechat_buffer_unmerge (weechat_current_buffer (), 1);

Script (Python):

# prototype
weechat.buffer_unmerge(buffer, number)

# example
weechat.buffer_unmerge(weechat.current_buffer(), 1)

3.12.9. weechat_buffer_get_integer

Return integer value of a buffer property.

Prototype:

int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);

Arguments:

  • buffer: buffer pointer

  • property: property name:

    • number: number of buffer (starts to 1)

    • layout_number: number of buffer saved in layout

    • layout_number_merge_order: order in merge for layout

    • short_name_is_set: 1 if short name is set, 0 if not set

    • type: buffer type (0: formatted, 1: free content)

    • notify: notify level for buffer

    • num_displayed: number of windows displaying buffer

    • active: 2 if buffer is the only active (merged), 1 if buffer is active, 0 if buffer is merged and not selected

    • hidden: 1 if buffer is hidden, otherwise 0 (WeeChat ≥ 1.0)

    • zoomed: 1 if buffer is merged and zoomed, otherwise 0 (WeeChat ≥ 1.0)

    • print_hooks_enabled: 1 if print hooks are enabled, otherwise 0

    • day_change: 1 if messages for the day change are displayed, otherwise 0 (WeeChat ≥ 0.4.3)

    • clear: 1 if buffer can be cleared with command /buffer clear, otherwise 0 (WeeChat ≥ 1.0)

    • filter: 1 if filters are enabled on buffer, otherwise 0 (WeeChat ≥ 1.0)

    • lines_hidden: 1 if at least one line is hidden on buffer (filtered), or 0 if all lines are displayed

    • prefix_max_length: max length for prefix in this buffer

    • time_for_each_line: 1 if time is displayed for each line in buffer (default), otherwise 0

    • nicklist: 1 if nicklist is enabled, otherwise 0

    • nicklist_case_sensitive: 1 if nicks are case sensitive, otherwise 0

    • nicklist_max_length: max length for a nick

    • nicklist_display_groups: 1 if groups are displayed, otherwise 0

    • nicklist_count: number of nicks and groups in nicklist

    • nicklist_groups_count: number of groups in nicklist

    • nicklist_nicks_count: number of nicks in nicklist

    • nicklist_visible_count: number of nicks/groups displayed

    • input: 1 if input is enabled, otherwise 0

    • input_get_unknown_commands: 1 if unknown commands are sent to input callback, otherwise 0

    • input_size: input size (in bytes)

    • input_length: input length (number of chars)

    • input_pos: cursor position in buffer input

    • input_1st_display: first char displayed on screen

    • num_history: number of commands in history

    • text_search: text search type:

      • 0: no search at this moment

      • 1: backward search (direction: oldest messages)

      • 2: forward search (direction: newest messages)

    • text_search_exact: 1 if text search is case sensitive

    • text_search_found: 1 if text found, otherwise 0

Return value:

  • integer value of property

C example:

weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));

Script (Python):

# prototype
value = weechat.buffer_get_integer(buffer, property)

# example
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))

3.12.10. weechat_buffer_get_string

Return string value of a buffer property.

Prototype:

const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);

Arguments:

  • buffer: buffer pointer

  • property: property name:

    • plugin: name of plugin which created this buffer ("core" for WeeChat main buffer)

    • name: name of buffer

    • full_name: full name of buffer ("plugin.name") (WeeChat ≥ 0.3.7)

    • short_name: short name of buffer (note: used for display only and can be changed by user, this must not be used to find name of buffer, use instead name, full_name or local variable channel)

    • title: title of buffer

    • input: input text

    • text_search_input: input saved before text search

    • highlight_words: list of words to highlight

    • highlight_regex: POSIX extended regular expression for highlight

    • highlight_tags_restrict: restrict highlights to messages with these tags

    • highlight_tags: force highlight on messages with these tags

    • hotlist_max_level_nicks: max hotlist level for some nicks

    • localvar_xxx: get content of local variable "xxx" (replace "xxx" by the name of variable to read)