WeeChat plugin API reference

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

Latest version of this document can be found on this page ^↗.

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.

In order to call WeeChat functions in the format displayed in Plugin API, the following global pointer must be declared and initialized in the function weechat_plugin_init:

struct t_weechat_plugin *weechat_plugin;

2.1. Macros

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

WEECHAT_PLUGIN_NAME("name"): the plugin name
WEECHAT_PLUGIN_DESCRIPTION("description"): a short description of plugin
WEECHAT_PLUGIN_AUTHOR("author"): the author name
WEECHAT_PLUGIN_VERSION("1.0"): the plugin version
WEECHAT_PLUGIN_LICENSE("GPL3"): the plugin license
WEECHAT_PLUGIN_PRIORITY(1000): the plugin priority (optional, see below)

2.2. Main functions

The plugin must use two functions:

weechat_plugin_init
weechat_plugin_end

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, used to initialize the convenience global pointer weechat_plugin
argc: number of arguments for plugin
argv: arguments for plugin (see below)

Return value:

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

Plugin arguments

When the plugin is loaded by WeeChat, it receives the list of arguments in parameter argv and the number of arguments in argc.

The arguments can be:

command line arguments when running the WeeChat binary,
arguments given to the command /plugin load xxx, when the plugin is manually loaded by the user.

When the arguments come from the command line, only these arguments are sent to the plugin:

-a, --no-connect: Disable auto-connect to servers when WeeChat is starting.
-s, --no-script: Disable scripts auto-load.
plugin:option: Option for a plugin: only the plugin-related options are sent, for example only the options starting with irc: are sent to the plugin called "irc".

Plugin priority

When plugins are auto-loaded (for example on startup), WeeChat first loads all plugins, and then calls the init functions, using the priority defined in each plugin. A high priority means that the init function is called first.

Default priority is 1000 (with such priority, the plugin is loaded after all default plugins).

The default WeeChat plugins are initialized in this order:

Rank	Plugin	Priority
1	charset	16000
2	logger	15000
3	exec	14000
4	trigger	13000
5	spell	12000
6	alias	11000
7	buflist	10000
8	fifo	9000
9	typing	8000
10	xfer	7000
11	irc	6000
12	relay	5000
13	guile	4070
14	javascript	4060
15	lua	4050
16	perl	4040
17	php	4030
18	python	4020
19	ruby	4010
20	tcl	4000
21	script	3000
22	fset	2000

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 toto.so toto.o

2.4. Load plugin

Copy file toto.so into system plugins directory (for example /usr/local/lib/weechat/plugins) or into user’s plugins directory (for example /home/user/.local/share/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 (const void *pointer, void *data,
                   struct t_gui_buffer *buffer,
                   int argc, char **argv, char **argv_eol)
{
    /* make C compiler happy */
    (void) pointer;
    (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, 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. Registering

Functions to register a script: used only by scripting API, not the C API.

register

For more information, see the WeeChat scripting guide ^↗.

Script (Python):

# prototype
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...

Note	This function is not available in the C API.

3.2. Plugins

Functions to get infos about plugins.

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
def plugin_get_name(plugin: str) -> str: ...

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

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

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
def charset_set(charset: str) -> int: ...

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

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
def iconv_to_internal(charset: str, string: str) -> str: ...

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

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
def iconv_from_internal(charset: str, string: str) -> str: ...

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

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 or string if there is no translation available in local language

C example:

char *str = weechat_gettext ("hello");

Script (Python):

# prototype
def gettext(string: str) -> str: ...

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

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 or string / plural if there is no translation available in local language

C example:

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

Script (Python):

# prototype
def ngettext(string: str, plural: str, count: int) -> str: ...

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

asprintf

WeeChat ≥ 4.3.0.

Format a message in a string allocated by the function.

Note	This function is defined for systems where the GNU function `asprintf()` is not available. The behavior is almost the same except that `*result` is set to NULL on error.

Prototype:

int weechat_asprintf (char **result, const char *fmt, ...);

Arguments:

result: pointer to a string pointer
fmt: format string

Return value:

number of bytes written in *result (excluding the final null byte), a negative value in case of error.

C example:

char *str;

if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
{
    /* *str == "test, 42" */
    /* ... */
    free (str);
}
else
{
    /* error: *str == NULL */
}

Note	This function is not available in scripting API.

strndup

Return duplicated string, with a max number of bytes.

Prototype:

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

Arguments:

string: string to duplicate
bytes: max bytes 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.

string_cut

WeeChat ≥ 3.3.

Cut a string after a given number of chars, add an optional suffix after the string if it is cut.

Prototype:

char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);

Arguments:

string: string to cut
length: max chars
count_suffix: if 1, the length of suffix is counted in the max length
screen: if 1, the cut is based on width of chars displayed
cut_suffix: the suffix added after the string if it is cut

Return value:

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

C example:

char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
/* ... */
free (str);

Note	This function is not available in scripting API.

string_tolower

Updated in 3.8.

Return a string with uppercase letters converted to lowercase.

Note	Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`. Moreover, a newly allocated string is returned and must be freed after use.

Prototype:

char *weechat_string_tolower (const char *string);

Arguments:

string: string to convert

Return value:

string with lowercase letters (must be freed by calling "free" after use)

C example:

char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_é" */
/* ... */
free (str);

Note	This function is not available in scripting API.

string_toupper

Updated in 3.8.

Return a string with lowercase letters converted to uppercase.

Note	Behavior has changed in version 3.8: now all lowercase letters are properly converted to uppercase (by calling function `towupper`), in addition to the range `a` to `z`. Moreover, a newly allocated string is returned and must be freed after use.

Prototype:

char *weechat_string_toupper (const char *string);

Arguments:

string: string to convert

Return value:

string with uppercase letters (must be freed by calling "free" after use)

C example:

char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_É" */
/* ... */
free (str);

Note	This function is not available in scripting API.

string_charcmp

Updated in 1.0, 3.8.

Compare two chars.

Prototype:

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

Arguments:

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

Return value:

arithmetic result of subtracting the first UTF-8 char in string2 from the first UTF-8 char in string1:
- < 0 if char1 < char2
- 0 if char1 == char2
- > 0 if char1 > char2

C example:

int diff = weechat_string_charcmp ("aaa", "ccc");  /* == -2 */

Note	This function is not available in scripting API.

string_charcasecmp

Updated in 1.0, 3.8.

Compare two chars, ignoring case.

Note	Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Prototype:

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

Arguments:

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

Return value:

arithmetic result of subtracting the first UTF-8 char in string2 (converted to lowercase) from the first UTF-8 char in string1 (converted to lowercase):
- < 0 if char1 < char2
- 0 if char1 == char2
- > 0 if char1 > char2

C example:

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

Note	This function is not available in scripting API.

strcmp

WeeChat ≥ 3.8.

Case-sensitive string comparison.

Prototype:

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

Arguments:

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

Return value:

arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 if string1 > string2

C example:

int diff = weechat_strcmp ("aaa", "ccc");  /* == -2 */

Note	This function is not available in scripting API.

strncmp

WeeChat ≥ 3.8.

Case-sensitive string comparison, for max chars.

Prototype:

int weechat_strncmp (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:

arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 if string1 > string2

C example:

int diff = weechat_strncmp ("aabb", "aacc", 2);  /* == 0 */

Note	This function is not available in scripting API.

strcasecmp

Updated in 1.0, 3.8.

Case-insensitive string comparison.

Note	Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Prototype:

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

Arguments:

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

Return value:

arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 if string1 > string2

C example:

int diff;
diff = weechat_strcasecmp ("aaa", "CCC");    /* == -2 */
diff = weechat_strcasecmp ("noël", "NOËL");  /* == 0  */

Note	This function is not available in scripting API.

strcasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0, 3.8.

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:

arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 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.

strncasecmp

Updated in 1.0, 3.8.

Case-insensitive string comparison, for max chars.

Note	Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

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:

arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 if string1 > string2

C example:

int diff = weechat_strncasecmp ("aabb", "AACC", 2);  /* == 0 */

Note	This function is not available in scripting API.

strncasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0, 3.8.

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:

arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 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.

strcmp_ignore_chars

Updated in 1.0, 3.8.

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

Note	Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Return value:

arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase if case_sensitive is set to 0) from the last compared UTF-8 char in string1 (converted to lowercase if case_sensitive is set to 0):
- < 0 if string1 < string2
- 0 if string1 == string2
- > 0 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.

strcasestr

Updated in 1.3, 3.8.

Case-insensitive string search.

Note	Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Prototype:

const 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 (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

C example:

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

Note	This function is not available in scripting API.

strlen_screen

WeeChat ≥ 0.4.2, updated in 3.8.

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

WeeChat color codes are skipped and don’t count in the result (this is the only difference with the function 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
def strlen_screen(string: str) -> int: ...

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

string_match

Updated in 1.0, 3.8.

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

Note	Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

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
def string_match(string: str, mask: str, case_sensitive: int) -> int: ...

# 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

string_match_list

WeeChat ≥ 2.5, updated in 3.8.

Check if a string matches a list of masks where negative mask is allowed with the format "!word". A negative mask has higher priority than a standard mask.

Prototype:

int weechat_string_match_list (const char *string, const char **masks,
                               int case_sensitive);

Arguments:

string: string
masks: list of masks, with a NULL after the last mask in list; each mask is compared to the string with the function string_match
case_sensitive: 1 for case-sensitive comparison, otherwise 0

Note	Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Return value:

1 if string matches list of masks (at least one mask matches and no negative mask matches), otherwise 0

C example:

const char *masks[3] = { "*", "!abc*", NULL };
int match1 = weechat_string_match_list ("abc", masks, 0);     /* == 0 */
int match2 = weechat_string_match_list ("abcdef", masks, 0);  /* == 0 */
int match3 = weechat_string_match_list ("def", masks, 0);     /* == 1 */

Script (Python):

# prototype
def string_match_list(string: str, masks: str, case_sensitive: int) -> int: ...

# examples
match1 = weechat.string_match("abc", "*,!abc*", 0)     # == 0
match2 = weechat.string_match("abcdef", "*,!abc*", 0)  # == 0
match3 = weechat.string_match("def", "*,!abc*", 0)     # == 1

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/user/file.txt" */
/* ... */
free (str);

Note	This function is not available in scripting API.

string_eval_path_home

WeeChat ≥ 1.3, updated in 3.2.

Evaluate a path in 3 steps:

replace leading %h by a WeeChat directory (data by default),
replace leading ~ by user home directory (call to string_expand_home),
evaluate variables (see string_eval_expression).

Prototype:

char *weechat_string_eval_path_home (const char *path,
                                     struct t_hashtable *pointers,
                                     struct t_hashtable *extra_vars,
                                     struct t_hashtable *options);

Arguments:

path: path
pointers: hashtable for call to function string_eval_expression
extra_vars: hashtable for call to function string_eval_expression
options: hashtable for call to function string_eval_expression, with one extra key supported:
- directory: WeeChat directory to use when replacing %h, one of:
  - config
  - data (default)
  - cache
  - runtime

Return value:

evaluated path (must be freed by calling "free" after use)

C example:

char *str = weechat_string_eval_path_home ("${weechat_config_dir}/test.conf", NULL, NULL, NULL);
/* result: "/home/user/.config/weechat/test.conf" */
/* ... */
free (str);

Script (Python):

# prototype
def string_eval_path_home(path: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# example
path = weechat.string_eval_path_home("${weechat_config_dir}/test.conf", {}, {}, {})
# path == "/home/user/.config/weechat/test.conf"

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.

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.

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.

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
def string_mask_to_regex(mask: str) -> str: ...

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

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.

string_regcomp

WeeChat ≥ 0.3.7.

Compile a POSIX extended regular expression using optional flags at beginning of string (for format of flags, see 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)

Note	Regular expression preg must be cleaned by calling "regfree" after use, if the function returned 0 (OK).

C example:

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
{
    /* OK */
    /* ... */
    regfree (&my_regex);
}
else
{
    /* error */
    /* ... */
}

Note	This function is not available in scripting API.

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
def string_has_highlight(string: str, highlight_words: str) -> int: ...

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

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
def string_has_highlight_regex(string: str, regex: str) -> int: ...

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

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.

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

string_translate_chars

WeeChat ≥ 3.8.

Translate chars in a string.

Prototype:

char *string_translate_chars (const char *string, const char *chars1, const char *chars2);

Arguments:

string: string
chars1: string with chars to translate
chars2: string with replacement chars; it must contain the same number of UTF-8 chars than chars1

Return value:

string with translated chars, NULL if problem (must be freed by calling "free" after use)

C examples:

/* "test" => "tEst" */
char *str = weechat_string_translate_chars ("test", "abcdef", "ABCDEF");

/* "clean the boat" => "CleAn the BoAt" */
char *str = weechat_string_translate_chars ("clean the boat", "abc", "ABC");

Note	This function is not available in scripting API.

string_split

Updated in 2.5, 2.6.

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

Prototype:

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

Arguments:

string: string to split
separators: delimiters used for split
strip_items: chars to strip from returned items (left/right); optional, can be NULL
flags: combination values to change the default behavior; if the value is 0, the default behavior is used (no strip of separators at beginning/end of string, multiple separators are kept as-is so empty strings can be returned); the following flags are accepted:
- WEECHAT_STRING_SPLIT_STRIP_LEFT: strip separators on the left (beginning of string)
- WEECHAT_STRING_SPLIT_STRIP_RIGHT: strip separators on the right (end of string)
- WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: collapse multiple consecutive separators into a single one
- WEECHAT_STRING_SPLIT_KEEP_EOL: keep end of line for each value
num_items_max: maximum number of items created (0 = no limit)
num_items: pointer to int which will contain number of items created

Note	With WeeChat ≤ 2.4, the flags argument was called keep_eol and took other values, which must be converted like that:

keep_eol	flags
0	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
1	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
2	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL

Return value:

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

C example:

char **argv;
int argc;

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

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                             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 ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                             | WEECHAT_STRING_SPLIT_KEEP_EOL,
                             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);

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                             | WEECHAT_STRING_SPLIT_KEEP_EOL,
                             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);

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

Note	This function is not available in scripting API.

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 this page ^↗.

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:

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

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.

string_free_split

Free memory used by a split string.

Prototype:

void weechat_string_free_split (char **split_string);

Arguments:

split_string: string split by function string_split

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.

string_rebuild_split_string

Updated in 3.7.

Rebuild a string with a split string, using optional separator and index of first/last string to use.

Prototype:

char *weechat_string_rebuild_split_string (char **split_string,
                                           const char *separator,
                                           int index_start, int index_end);

Arguments:

split_string: string split by function string_split
separator: string used to separate strings (can be NULL or empty string)
index_start: index of first string to use (≥ 0)
index_end: index of last string to use (must be ≥ index_start; special value -1 can be used to use all arguments until NULL is found)

Return value:

string rebuilt 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_rebuild_split_string (argv, ";", 0, -1);
/* str == "abc;def;ghi" */
/* ... */
free (str);

Note	This function is not available in scripting API.

string_split_command

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

Prototype:

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

Arguments:

command: command to split
separator: separator

Return value:

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

C example:

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

Note	This function is not available in scripting API.

string_free_split_command

Free memory used by a split command.

Prototype:

void weechat_string_free_split_command (char **split_command);

Arguments:

split_command: command split by string_split_command

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.

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

Script (Python), WeeChat ≥ 2.2:

# prototype
def string_format_size(size: int) -> str: ...

# example
str = weechat.string_format_size(15200)  # == "15.2 KB"

string_parse_size

WeeChat ≥ 3.7.

Parse a string with a size and optional unit and return the size in bytes.

Prototype:

unsigned long long weechat_string_parse_size (const char *size);

Arguments:

size: the size as string: positive integer number followed by optional spaces and optional unit (lower or upper case), which is one of:
- b: bytes
- k: kilobytes (1k = 1000 bytes)
- m: megabytes (1m = 1000k = 1,000,000 bytes)
- g: gigabytes (1g = 1000m = 1,000,000,000 bytes)
- t: terabytes (1t = 1000g = 1,000,000,000,000 bytes)

Return value:

size in bytes, 0 if error

C example:

unsigned long long size = weechat_parse_size ("1.34m");  /* size == 1340000 */

Script (Python):

# prototype
def string_parse_size(size: str) -> int: ...

# example
size = weechat.string_parse_size("1.34m")  # 1340000

string_color_code_size

WeeChat ≥ 3.0.

Return the size (in bytes) of the WeeChat color code at the beginning of the string.

Prototype:

int weechat_string_color_code_size (const char *string);

Arguments:

string: string

Return value:

size (in bytes) of the WeeChat color code at the beginning of the string; if the string is NULL, empty or does not start with a color code, 0 is returned; if the string begins with multiple color codes, only the size of the first one is returned

C examples:

int size;

size = weechat_string_color_code_size ("test");  /* size == 0 */
size = weechat_string_color_code_size (weechat_color ("bold"));  /* size == 2 */
size = weechat_string_color_code_size (weechat_color ("yellow,red"));  /* size == 7 */

Script (Python):

# prototype
def string_color_code_size(string: str) -> int: ...

# examples
size = weechat.string_color_code_size("test")  # size == 0
size = weechat.string_color_code_size(weechat.color("bold"))  # size == 2
size = weechat.string_color_code_size(weechat.color("yellow,red"))  # size == 7

string_remove_color

Updated in 4.3.0.

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 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, "[color]");
/* ... */
free (str);

Script (Python):

# prototype
def string_remove_color(string: str, replacement: str) -> str: ...

# example
str = weechat.string_remove_color(my_string, "[color]")

string_base_encode

WeeChat ≥ 2.4, updated in 4.3.0.

Encode a string in base 16, 32, or 64.

Prototype:

int weechat_string_base_encode (const char *base, const char *from, int length, char *to);

Arguments:

base: "16", "32", "64" or "64url"
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)

Return value:

length of string stored in *to (does not count final \0), -1 if error

C example:

char *string = "abcdefgh", result[128];
int length;
length = weechat_string_base_encode ("16", string, strlen (string), result);
/* length == 16, result == "6162636465666768" */
length = weechat_string_base_encode ("32", string, strlen (string), result);
/* length == 16, result == "MFRGGZDFMZTWQ===" */
length = weechat_string_base_encode ("64", string, strlen (string), result);
/* length == 12, result == "YWJjZGVmZ2g=" */

Note	This function is not available in scripting API.

string_base_decode

WeeChat ≥ 2.4, updated in 4.3.0.

Decode a string encoded in base 16, 32, or 64.

Prototype:

int weechat_string_base_decode (const char *base, const char *from, char *to);

Arguments:

base: "16", "32", "64" or "64url"
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), -1 if error

C example:

char result[128];
int length;
length = weechat_string_base_decode ("16", "6162636465666768", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode ("32", "MFRGGZDFMZTWQ===", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode ("64", "YWJjZGVmZ2g=", result);
/* length == 8, result == "abcdefgh" */

Note	This function is not available in scripting API.

string_hex_dump

WeeChat ≥ 1.4.

Display a dump of data as hexadecimal and ascii bytes.

Prototype:

char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                       const char *prefix, const char *suffix);

Arguments:

data: the data to dump
data_size: number of bytes to dump in data
bytes_per_line: number of bytes to display in each line
prefix: the prefix to display at the beginning of each line (optional, can be NULL)
suffix: the suffix to display at the end of each line (optional, can be NULL)

Return value:

string with dump of data (must be freed by calling "free" after use)

C example:

char *string = "abc def-ghi";
char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL);
/* dump == " >> 61 62 63 20 64 65 66 2D   a b c   d e f - \n"
           " >> 67 68 69                  g h i           "  */

Note	This function is not available in scripting API.

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
def string_is_command_char(string: str) -> int: ...

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

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
def string_input_for_buffer(string: str) -> str: ...

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

string_eval_expression

WeeChat ≥ 0.4.0, updated in 0.4.2, 0.4.3, 1.0, 1.1, 1.2, 1.3, 1.6, 1.8, 2.0, 2.2, 2.3, 2.7, 2.9, 3.1, 3.2, 3.3, 3.4, 3.6, 3.8, 4.0.0, 4.2.0, 4.3.0, 4.4.0.

Evaluate an expression and return result as a string. Special variables with format ${variable} are expanded (see table below).

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 (see conditions and variables)
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):
- regex: pointer to a regular expression (regex_t structure) compiled with WeeChat function string_regcomp or regcomp (see man regcomp); this option is similar to regex in hashtable options (below), but is used for better performance
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: })
- extra: default behavior is to just replace extra variables (extra_vars), other behavior can be selected:
  - eval: extra variables (extra_vars) are evaluated themselves before replacing (WeeChat ≥ 1.6)
- regex: a regex used to replace text in expr (which is then not evaluated)
- regex_replace: the replacement text to use with regex, to replace text in expr (the regex_replace is evaluated on each match of regex against expr, until no match is found)
- debug: debug level (string with integer number ≥ 1), if enabled, a key "debug_output" is added in hashtable options:
  - 1: enable debug
  - 2: enable more verbose debug

Return value:

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

C examples:

/* conditions */
struct t_hashtable *options1 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
weechat_hashtable_set (options1, "type", "condition");
char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */

/* simple expression */
char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */

/* replace with regex */
struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
/* add brackets around URLs */
weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+");
weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
char *str4 = weechat_string_eval_expression ("test: https://weechat.org", NULL, NULL, NULL);  /* "test: [ https://weechat.org ]" */

/* hide passwords */
weechat_hashtable_set (options2, "regex", "(password=)([^ ]+)");
weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */

Script (Python):

# prototype
def string_eval_expression(expr: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# examples

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

# simple expression
str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"

# replace with regex: add brackets around URLs
options = {
    "regex": "[a-zA-Z0-9_]+://[^ ]+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options)  # "test: [ https://weechat.org ]"

# replace with regex: hide passwords
options = {
    "regex": "(password=)([^ ]+)",
    "regex_replace": "${re:1}${hide:*,${re:2}}",
}
str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"

Conditions

List of logical operators that can be used in conditions (by order of priority, from first used to last):

Operator Min WeeChat Description Examples

&&

Logical "and"

>> 25 && 77
== 1

>> 25 && 0
== 0

||

Logical "or"

>> 25 || 0
== 1

>> 0 || 0
== 0

List of comparison operators that can be used in conditions (by order of priority, from first used to last):

Operator Min WeeChat Description Examples

=~

Is matching POSIX extended regex (optional flags are allowed, see function string_regcomp)

>> abc def =~ ab.*ef
== 1

>> abc def =~ y.*z
== 0

!~

Is NOT matching POSIX extended regex (optional flags are allowed, see function string_regcomp)

>> abc def !~ ab.*ef
== 0

>> abc def !~ y.*z
== 1

==*

2.9

Is matching mask where "*" is allowed, case-sensitive (see function string_match)

>> abc def ==* a*f
== 1

>> abc def ==* y*z
== 0

!!*

2.9

Is NOT wildcard mask where "*" is allowed, case-sensitive (see function string_match)

>> abc def !!* a*f
== 0

>> abc def !!* y*z
== 1

=*

1.8

Is matching mask where "*" is allowed, case-insensitive (see function string_match)

>> abc def =* A*F
== 1

>> abc def =* Y*Z
== 0

!*

1.8

Is NOT wildcard mask where "*" is allowed, case-insensitive (see function string_match)

>> abc def !* A*F
== 0

>> abc def !* Y*Z
== 1

==-

2.9

Is included, case-sensitive

>> abc def ==- bc
== 1

>> abc def ==- xyz
== 0

!!-

2.9

Is NOT included, case-sensitive

>> abc def !!- bc
== 0

>> abc def !!- xyz
== 1

=-

2.9

Is included, case-insensitive

>> abc def =- BC
== 1

>> abc def =- XYZ
== 0

!-

2.9

Is NOT included, case-insensitive

>> abc def !- BC
== 0

>> abc def !- XYZ
== 1

==

Equal

>> test == test
== 1

>> test == string
== 0

!=

Not equal

>> test != test
== 0

>> test != string
== 1

<=

Less or equal

>> abc <= defghi
== 1

>> abc <= abc
== 1

>> defghi <= abc
== 0

>> 15 <= 2
== 0

<

Less

>> abc < defghi
== 1

>> abc < abc
== 0

>> defghi < abc
== 0

>> 15 < 2
== 0

>=

Greater or equal

>> defghi >= abc
== 1

>> abc >= abc
== 1

>> abc >= defghi
== 0

>> 15 >= 2
== 1

>

Greater

>> defghi > abc
== 1

>> abc > abc
== 0

>> abc > defghi
== 0

>> 15 > 2
== 1

The comparison is made using floating point numbers if the two expressions are valid numbers, with one of the following formats:

integer (examples: 5, -7)
floating point number (examples: 5.2, -7.5, 2.83e-2) (WeeChat ≥ 2.0)
hexadecimal number (examples: 0xA3, -0xA3) (WeeChat ≥ 2.0)

To force a string comparison, you can add double quotes around each expression, for example:

50 > 100 returns 0 (number comparison)
"50" > "100" returns 1 (string comparison)

Variables

List of variables expanded in expression (by order of priority, from first expanded to last):

Format Min WeeChat Description Examples

${raw_hl:xxx}

4.2.0

Raw string (not evaluated), with syntax highlighting (using colors).

>> ${raw_hl:${cut:1,,${rev:hello}}}
== ${cut:1,,${rev:hello}} (with colors)

${raw:xxx}

3.1

Raw string (not evaluated).

>> ${raw:${info:version}}
== ${info:version}

${hl:xxx}

4.2.0

String with syntax highlighting (using colors).

>> ${hl:${file.section.option}}
== test ${variable} (with colors)

${name}

3.4

User variable (defined with ${define:name,value}).

>> ${name}
== value

${name}

Variable name from hashtable extra_vars.

>> ${name}
== value

${weechat_xxx_dir}

3.2

A WeeChat directory: ${weechat_config_dir}, ${weechat_data_dir}, ${weechat_state_dir}, ${weechat_cache_dir} or ${weechat_runtime_dir}.

>> ${weechat_config_dir}
== /home/user/.config/weechat

>> ${weechat_data_dir}
== /home/user/.local/share/weechat

>> ${weechat_state_dir}
== /home/user/.local/state/weechat

>> ${weechat_cache_dir}
== /home/user/.cache/weechat

>> ${weechat_runtime_dir}
== /run/user/1000/weechat

${eval:xxx}

1.3

String to evaluate.

>> ${eval:${date:${weechat.look.buffer_time_format}}}
== 19:02:45 ⁽¹⁾

⁽¹⁾ With colors if there are color codes in the option weechat.look.buffer_time_format

${eval_cond:xxx}

3.1

String to evaluate as condition.

>> ${eval_cond:${window.win_width} > 100}
== 1

${esc:xxx}
${\xxx}

1.0

String with escaped chars.

>> ${esc:prefix\tmessage}
== prefix<TAB>message

>> ${\ua9}
== ©

${chars:range}

3.8

String with a range of chars, where range is one of:
- digit (0123456789)
- xdigit (0123456789abcdefABCDEF)
- lower (all lower case letters)
- upper (all upper case letters)
- alpha (all letters)
- alnum (all letters and digits)
- a range of chars with format c1-c2 (c1 code point must be lower or equal to c2)

>> ${chars:digit}
== 0123456789

>> ${chars:xdigit}
== 0123456789abcdefABCDEF

>> ${chars:lower}
== abcdefghijklmnopqrstuvwxyz

>> ${chars:J-V}
== JKLMNOPQRSTUV

>> ${chars:←-↓}
== ←↑→↓

${lower:string}

3.6

String converted to lower case.

>> ${lower:TEST}
== test

${upper:string}

3.6

String converted to upper case.

>> ${upper:test}
== TEST

${hide:x,string}

1.1

String with hidden chars (all chars in string replaced by x).

>> ${hide:*,password}
== ********

${cut:max,suffix,string}
${cut:+max,suffix,string}

1.8

String with max chars, and optional suffix if string is cut.
With the format +max, the suffix is counted in max length.

>> ${cut:4,…,this is a test}
== this…

>> ${cut:+4,…,this is a test}
== t…

>> ${cut:2,>>,こんにちは世界}
== こん>>

${cutscr:max,suffix,string}
${cutscr:+max,suffix,string}

1.8

String with max chars displayed on screen, and optional suffix if string is cut.
With the format +max, the suffix is counted in max length.

>> ${cutscr:4,…,this is a test}
== this…

>> ${cutscr:+4,…,this is a test}
== thi…

>> ${cutscr:2,>>,こんにちは世界}
== こ>>

${rev:xxx}

2.2

Reversed string (color codes are reversed, so the string should not contain color codes).

>> ${rev:Hello, world!}
== !dlrow ,olleH

>> ${rev:Hello, ${color:red}world!}
== !dlrow30F ,olleH ⁽¹⁾

⁽¹⁾ No color, the color code is reversed

${revscr:xxx}

2.7

Reversed string for screen, color codes are not reversed.

>> ${revscr:Hello, world!}
== !dlrow ,olleH

>> ${revscr:Hello, ${color:red}world!}
== !dlrow ,olleH ⁽¹⁾

⁽¹⁾ ,olleH in red

${repeat:count,string}

2.3

Repeated string.

>> ${repeat:5,-}
== -----

${length:xxx}

2.7

Length of string (number of UTF-8 chars), color codes are ignored.

>> ${length:test}
== 4

>> ${length:こんにちは世界}
== 7

${lengthscr:xxx}

2.7

Length of string displayed on screen, color codes are ignored.

>> ${lengthscr:test}
== 4

>> ${lengthscr:こんにちは世界}
== 14

${split:number,seps,flags,xxx}

3.3

Split string, and return, according to number:
- count: the number of items after split
- random: a random item
- integer ≥ 1: the item by index (1 = first item)
- integer ≤ -1: the item by index from the end (-1 = last item, -2 = penultimate item, etc.),
seps is a list of chars that are used as separators (if empty, a comma is used),
flags is a list of flags separated by +:
- strip_left: strip separators on the left (beginning of string)
- strip_right: strip separators on the right (end of string)
- collapse_seps: collapse multiple consecutive separators into a single one
- keep_eol: keep end of line for each value
- strip_items=xyz: strip chars x, y and z from beginning/end of items
- max_items=N: return max N items

>> ${split:1,,,abc,def,ghi}
== abc

>> ${split:-1,,,abc,def,ghi}
== ghi

>> ${split:count,,,abc,def,ghi}
== 3

>> ${split:random,,,abc,def,ghi}
== def

>> ${split:3,,collapse_seps,abc,,,def,,,ghi}
== ghi

>> ${split:3,,strip_items=-_,_-abc-_,_-def-_,_-ghi-_}
== ghi

>> ${split:2, ,,this is a test}
== is

>> ${split:2, ,strip_left+strip_right, this is a test }
== is

>> ${split:2, ,keep_eol,this is a test}
== is a test

${split_shell:number,xxx}

3.3

Split shell arguments, and return, according to number:
- count: the number of arguments after split
- random: a random argument
- integer ≥ 1: the argument by index (1 = first argument)
- integer ≤ -1: the argument by index from the end (-1 = last argument, -2 = penultimate argument, etc.)

>> ${split_shell:1,"first arg" arg2}
== first arg

>> ${split_shell:-1,"first arg" arg2}
== arg2

>> ${split_shell:count,"first arg" arg2}
== 2

>> ${split_shell:random,"first arg" arg2}
== arg2

${re:xxx}

1.1

Regex data:
0 = whole string matching,
1 to 99 = group captured,
+ = last group captured,
# = index of last group captured (WeeChat ≥ 1.8),
repl_index = index of replacement being done (starts to 1) (WeeChat ≥ 3.3).

>> ${re:0}
== test1 test2

>> ${re:1}
== test1

>> ${re:2}
== test2

>> ${re:+}
== test2

>> ${re:#}
== 2

>> ${re:repl_index}
== 1

${color:name}

0.4.2

WeeChat color code (the name of color has optional attributes), see function color for supported formats.

>> ${color:red}red text
== red text ⁽¹⁾

>> ${color:*214}bold orange text
== bold orange text ⁽²⁾

⁽¹⁾ In red
⁽²⁾ In bold orange

${modifier:name,data,string}

2.7

Result of a modifier, see function hook_modifier_exec.

>> ${modifier:eval_path_home,,~}
== /home/user

>> ${modifier:eval_path_home,directory=config,%h/irc.conf}
== /home/user/.config/weechat/irc.conf

${info:name}
${info:name,arguments}

0.4.3

Info from WeeChat or a plugin, see function info_get.

>> ${info:version}
== 1.0

>> ${info:nick_color_name,foo}
== lightblue

${base_encode:base,xxx}

2.9

String encoded in base 16, 32 or 64.

>> ${base_encode:16,test string}
== 7465737420737472696E67

>> ${base_encode:32,test string}
== ORSXG5BAON2HE2LOM4======

>> ${base_encode:64,test string}
== dGVzdCBzdHJpbmc=

${base_decode:base,xxx}

2.9

String decoded from base 16, 32 or 64.

>> ${base_decode:16,7465737420737472696E67}
== test string

>> ${base_decode:32,ORSXG5BAON2HE2LOM4======}
== test string

>> ${base_decode:64,dGVzdCBzdHJpbmc=}
== test string

${date}
${date:xxx}

1.3

Current date/time, with custom format (see function util_strftimeval), default format is %F %T.

>> ${date}
== 2015-06-30 19:02:45

>> ${date:%H:%M:%S}
== 19:02:45

>> ${date:%!.%.3}
== 1435683765.482

${env:NAME}

1.2

Value of the environment variable NAME.

>> ${env:HOME}
== /home/user

${if:condition}
${if:condition?true} ${if:condition?true:false}

1.8

Ternary operator with a condition, a value if the condition is true (optional) and another value if the condition is false (optional). If values are not given, "1" or "0" are returned, according to the result of the condition.

>> ${if:${info:term_width}>80?big:small}
== big

${calc:xxx}

2.7

Result of expression, where parentheses and the following operators are supported:
+: addition
-: subtraction
*: multiplication
/: division
//: result of division without fractional part
%: remainder of division
**: power.

>> ${calc:5+2*3}
== 11

>> ${calc:(5+2)*3}
== 21

>> ${calc:10/4}
== 2.5

>> ${calc:10//4}
== 2

>> ${calc:9.2%3}
== 0.2

>> ${calc:2**16}
== 65536

${random:min,max}

3.3

Random integer number in the range from min to max (inclusive).

>> ${random:0,10}
== 3

${translate:xxx}

3.2

Translated string (depends on the language used by WeeChat to display messages).

>> ${translate:Plugin}
== Extension ⁽¹⁾

⁽¹⁾ Example in French

${define:name,value}

3.4

Define a variable name set to value, which can then be used in the same evaluated expression with ${name}.

>> ${define:len,${calc:5+3}}${len}x${len}
== 8x8

${hdata_count:name[list]}
${hdata_count:name[pointer]}

4.4.0

Number of items in a hdata list or starting at pointer.

>> ${hdata_count:buffer[gui_buffers]}
== 15

${sec.data.name}

Value of the secured data name.

>> ${sec.data.libera_pass}
== my_password

${file.section.option}

Value of the option.

>> ${weechat.look.buffer_time_format}
== %H:%M:%S

${name}

Value of local variable name in buffer.

>> ${nick}
== FlashCode

${pointer}

Variable pointer from hashtable pointers.

>> ${buffer}
== 0x1234abcd

${hdata.var1.var2...}
${hdata[list].var1.var2...}

Hdata value (pointers window and buffer are set by default with current window/buffer), list can be a list name (example: "gui_buffers"), a pointer (example: "0x1234abcd") or a pointer name (example: "my_pointer").
When var1 is a hashtable, methods keys(), values(), keys_sorted(), keys_values() and keys_values_sorted() can be called.

>> ${buffer[gui_buffers].full_name}
== core.weechat

>> ${buffer[my_buffer_pointer].full_name}
== core.weechat

>> ${window.buffer.number}
== 1

>> ${buffer.local_variables.keys_values()}
== plugin:core,name:weechat

>> ${buffer.local_variables.plugin}
== core

string_dyn_alloc

WeeChat ≥ 1.8.

Allocate a dynamic string, with a variable length.
Internally, a structure is allocated with the string pointer, the allocated size and current length of string.

Only the pointer to string pointer (**string) is used in all the string_dyn_* functions.

Prototype:

char **weechat_string_dyn_alloc (int size_alloc);

Arguments:

size_alloc: the initial allocated size (must be greater than zero)

Return value:

pointer to the dynamic string

C example:

char **string = weechat_string_dyn_alloc (256);

Note	This function is not available in scripting API.

string_dyn_copy

WeeChat ≥ 1.8.

Copy a string in a dynamic string.

The pointer *string can change if the string is reallocated (if there is not enough space to copy the string).

Prototype:

int weechat_string_dyn_copy (char **string, const char *new_string);

Arguments:

string: pointer to dynamic string
new_string: the string to copy

Return value:

1 if OK, 0 if error

C example:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}

Note	This function is not available in scripting API.

string_dyn_concat

WeeChat ≥ 1.8, updated in 3.0.

Concatenate a string to a dynamic string.

The pointer *string can change if the string is reallocated (if there is not enough space to concatenate the string).

Prototype:

int weechat_string_dyn_concat (char **string, const char *add, int bytes);

Arguments:

string: pointer to dynamic string
add: the string to add
bytes: max number of bytes in add to concatenate, must be lower or equal to length of add (-1 = automatic: concatenate whole string add) (WeeChat ≥ 3.0)

Return value:

1 if OK, 0 if error

C example:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    if (weechat_string_dyn_concat (string, "abc", -1))
    {
        /* ... */
    }
}

Note	This function is not available in scripting API.

string_dyn_free

WeeChat ≥ 1.8.

Free a dynamic string.

Prototype:

char *weechat_string_dyn_free (char **string, int free_string);

Arguments:

string: pointer to dynamic string
free_string: free the string itself; if 0, the content of *string remains valid after the call to this function

Return value:

string pointer if free_string is 0, otherwise NULL

C example:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_concat (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
/* ... */
weechat_string_dyn_free (string, 1);

Note	This function is not available in scripting API.

string_concat

WeeChat ≥ 4.2.0.

Concatenate multiple strings using a separator.

Prototype:

const char *weechat_string_concat (const char *separator, ...);

Arguments:

separator: the separator string which is inserted between concatenated strings (can be NULL or empty string)

Note	Last argument MUST always be NULL. A macro called `WEECHAT_STR_CONCAT` can be used, where the final NULL value is not needed (usage of this macro is recommended).

Return value:

concatenated string

C example:

const char *result = weechat_string_concat (" / ", "abc", "def", "ghi", NULL);  /* result == "abc / def / ghi" */

/* with macro */
const char *result = WEECHAT_STR_CONCAT(" / ", "abc", "def", "ghi");  /* result == "abc / def / ghi" */

Note	This function is not available in scripting API.

3.4. UTF-8

Some UTF-8 string functions.

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.

utf8_is_valid

Updated in 1.4.

Check if a string is UTF-8 valid.

Prototype:

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

Arguments:

string: string
length: max number of UTF-8 chars to check; if ≤ 0, the whole string is checked (WeeChat ≥ 1.4)
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, -1, &error))
{
    /* ... */
}
else
{
    /* "error" points to first invalid char */
}

Note	This function is not available in scripting API.

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.

utf8_prev_char

Updated in 1.3.

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

Prototype:

const 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) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

C example:

const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

Note	This function is not available in scripting API.

utf8_next_char

Updated in 1.3.

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

Prototype:

const 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) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

C example:

const char *next_char = weechat_utf8_next_char (string);

Note	This function is not available in scripting API.

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.

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.

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.

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.

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.

utf8_char_size_screen

Updated in 3.8.

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:
- -1: non printable char
- ≥ 0: printable char

The result is the return value of function wcwidth (see man wcwidth), with exception for the following chars, that have a specific behavior in WeeChat:

U+0009 (Tabulation): value of option weechat.look.tab_width ^↗
U+0001 (1) to U+001F (31), except U+0009 (Tabulation): 1
U+00AD (173, soft hyphen): -1
U+200B (8203, zero width space): -1

C example:

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

Note	This function is not available in scripting API.

utf8_add_offset

Updated in 1.3.

Move forward N chars in an UTF-8 string.

Prototype:

const 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) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

C example:

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

Note	This function is not available in scripting API.

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 position (in bytes)

C example:

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

Note	This function is not available in scripting API.

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.

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.

utf8_strncpy

WeeChat ≥ 3.8.

Copy length chars max in another string and add null byte at the end.

Prototype:

void weechat_utf8_strncpy (char *dest, const char *string, int length);

Arguments:

dest: destination string (must be long enough)
string: string
length: max chars to copy

C example:

char dest[256];

weechat_utf8_strncpy (dest, "chêne", 3);  /* copies "chê" to dest */

Note	This function is not available in scripting API.

3.5. Cryptography

Some cryptographic functions.

crypto_hash

WeeChat ≥ 2.8.

Compute hash of data.

Prototype:

int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo,
                         void *hash, int *hash_size);

Arguments:

data: the data to hash
data_size: number of bytes to hash in data
hash_algo: the hash algorithm, see table below
hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table below)
hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Supported hash algorithms:

Value Algorithm Hash size Notes

crc32

CRC32

4 bytes (32 bits)

Not a hash algorithm in the cryptographic sense.

md5

MD5

16 bytes (128 bits)

Weak, not recommended for cryptography usage.

sha1

SHA-1

20 bytes (160 bits)

Weak, not recommended for cryptography usage.

sha224

SHA-224

28 bytes (224 bits)

sha256

SHA-256

32 bytes (256 bits)

sha384

SHA-384

48 bytes (384 bits)

sha512

SHA-512

64 bytes (512 bits)

sha512-224

SHA-512/224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.9.4.

sha512-256

SHA-512/256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.9.4.

sha3-224

SHA3-224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-256

SHA3-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-384

SHA3-384

48 bytes (384 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-512

SHA3-512

64 bytes (512 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

blake2b-160

BLAKE2B-160

20 bytes (160 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-256

BLAKE2B-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-384

BLAKE2B-384

48 bytes (384 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-512

BLAKE2B-512

64 bytes (512 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-128

BLAKE2S-128

16 bytes (128 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-160

BLAKE2S-160

20 bytes (160 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-224

BLAKE2S-224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-256

BLAKE2S-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

Return value:

1 if OK, 0 if error

C example:

const char *data = "abcdefghijklmnopqrstuvwxyz";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

Note	This function is not available in scripting API.

crypto_hash_file

WeeChat ≥ 3.7.

Compute hash of a file.

Prototype:

int weechat_crypto_hash_file (const char *filename, const char *hash_algo,
                              void *hash, int *hash_size);

Arguments:

filename: path and file name
hash_algo: the hash algorithm, see table in function crypto_hash
hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)
hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Return value:

1 if OK, 0 if error

C example:

char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_file ("/path/to/file", "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

Note	This function is not available in scripting API.

crypto_hash_pbkdf2

WeeChat ≥ 2.8.

Compute PKCS#5 Passphrase Based Key Derivation Function number 2 (PBKDF2) hash of data.

Prototype:

int weechat_crypto_hash_pbkdf2 (const void *data, int data_size,
                                const char *hash_algo,
                                const void *salt, int salt_size,
                                int iterations,
                                void *hash, int *hash_size);

Arguments:

data: the data to hash
data_size: number of bytes to hash in data
hash_algo: hash algorithm used by the key derivation function, see table in function crypto_hash
salt: the salt
salt_size: number of bytes in salt
iterations: number of iterations
hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)
hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Return value:

1 if OK, 0 if error

C example:

const char *data = "abcdefghijklmnopqrstuvwxyz";
const char *salt = "12345678901234567890123456789012";  /* 32 bytes */
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000,
                                 hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */

Note	This function is not available in scripting API.

crypto_hmac

WeeChat ≥ 3.2.

Compute keyed-hash message authentication code (HMAC).

Prototype:

int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size,
                         int hash_algo, void *hash, int *hash_size);

Arguments:

key: the key
key_size: number of bytes in key
message: the message
message_size: number of bytes in message
hash_algo: the hash algorithm, see table in function crypto_hash
hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)
hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Return value:

1 if OK, 0 if error

C example:

const char *key = "the key";
const char *message = "the message";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */

Note	This function is not available in scripting API.

3.6. Directories

Some functions related to directories.

mkdir_home

Updated in 3.2.

Create a directory in WeeChat home.

Prototype:

int weechat_mkdir_home (char *directory, int mode);

Arguments:

directory: name of directory to create; it can start with one of these strings to force a specific WeeChat directory (WeeChat ≥ 3.2):
- ${weechat_config_dir}
- ${weechat_data_dir} (default)
- ${weechat_state_dir}
- ${weechat_cache_dir}
- ${weechat_runtime_dir}
mode: mode for directory

Return value:

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

C example:

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

Script (Python):

# prototype
def mkdir_home(directory: str, mode: int) -> int: ...

# example
weechat.mkdir_home("${weechat_cache_dir}/temp", 0755)

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
def mkdir(directory: str, mode: int) -> int: ...

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

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
def mkdir_parents(directory: str, mode: int) -> int: ...

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

exec_on_files

Updated in 1.5, 2.0.

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

Prototype:

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

Arguments:

directory: directory for searching files
recurse_subdirs: 1 to recurse into sub-directories (WeeChat ≥ 2.0)
hidden_files: 1 to include hidden files, otherwise 0
callback: function called for each file found, arguments:
- void *data: pointer
- const char *filename: filename found
callback_data: pointer given to callback when it is called by WeeChat

C example:

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

Note	This function is not available in scripting API.

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.

file_copy

WeeChat ≥ 3.3.

Copy a file to another location.

Prototype:

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

Arguments:

from: source file
to: destination file

Return value:

1 if OK, 0 if error

C example:

if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
{
    /* OK */
}

Note	This function is not available in scripting API.

file_compress

WeeChat ≥ 3.7.

Compress a file with gzip or zstd.

Prototype:

int weechat_file_compress (const char *from, const char *to,
                           const char *compressor, int compression_level);

Arguments:

from: source file
to: destination file
compressor: the compressor to use, one of:
- gzip: gzip compression
- zstd: zstandard compression (available only if zstd was enabled when WeeChat was compiled)
compression_level: compression level, between 1 (fast, low compression) to 100 (slow, best compression)

Return value:

1 if OK, 0 if error

C example:

if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
{
    /* OK */
}

Note	This function is not available in scripting API.

3.7. Util

Some useful functions.

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.

util_timeval_diff

Updated in 1.1.

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

Prototype:

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

Arguments:

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

Return value:

difference in microseconds

Note	With WeeChat ≤ 1.0, the returned value was in milliseconds.

C example:

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

Note	This function is not available in scripting API.

util_timeval_add

Updated in 1.1.

Add interval (in microseconds) to a timeval structure.

Prototype:

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

Arguments:

tv: timeval structure
interval: interval (in microseconds)

Note	With WeeChat ≤ 1.0, the interval was expressed in milliseconds.

C example:

weechat_util_timeval_add (&tv, 2000000);  /* add 2 seconds */

Note	This function is not available in scripting API.

util_get_time_string

WeeChat ≥ 0.3.2, updated in 1.3.

Get date/time as a string built with "strftime" and the format defined in option weechat.look.time_format.

Prototype:

const char *weechat_util_get_time_string (const time_t *date);

Arguments:

date: pointer to date

Return value:

pointer to a string with date/time

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.

util_strftimeval

WeeChat ≥ 4.2.0, updated in 4.3.0.

Format date and time like function strftime in C library, using struct timeval as input, and supporting extra specifiers.

Prototype:

int weechat_util_strftimeval (char *string, int max, const char *format, struct timeval *tv);

Arguments:

string: buffer where the formatted string is stored
max: string size
format: format, the same as strftime function, with these extra specifiers:
- %.N where N is between 1 and 6: zero-padded microseconds on N digits (for example %.3 for milliseconds)
- %f: alias of %.6
- %!: timestamp as integer, in seconds (value of tv→tv_sec)

Return value:

number of bytes put in string (value returned from strftime function)

C example:

char time[256];
struct timeval tv;
gettimeofday (&tv, NULL);
weechat_util_strftimeval (time, sizeof (time), "%FT%T.%f", &tv);
/* result: 2023-12-26T18:10:04.460509 */

Note	This function is not available in scripting API.

util_parse_time

WeeChat ≥ 4.2.0.

Parse date/time with support of microseconds.

Prototype:

int util_parse_time (const char *datetime, struct timeval *tv);

Arguments:

date: date/time
tv: parsed date/time ("timeval" structure)

Return value:

1 if OK, 0 if error

C example:

struct timeval tv;
weechat_util_parse_time ("2023-12-25T10:29:09.456789Z", &tv);  /* == 1 */
/* result: tv.tv_sec == 1703500149, tv.tv_usec = 456789 */

Note	This function is not available in scripting API.

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 */
version_number = weechat_util_version_number ("1.0");        /* == 0x01000000 */
version_number = weechat_util_version_number ("4.0.0");      /* == 0x04000000 */

Note	This function is not available in scripting API.

3.8. Sorted lists

Sorted list functions.

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
def list_new() -> str: ...

# example
list = weechat.list_new()

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
def list_add(list: str, data: str, where: str, user_data: str) -> str: ...

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

list_search

Search an item in a list.

Prototype:

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

Arguments:

weelist: list pointer
data: data to search in list

Return value:

pointer to item found, NULL if item was not found

C example:

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

Script (Python):

# prototype
def list_search(list: str, data: str) -> str: ...

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

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
def list_search_pos(list: str, data: str) -> int: ...

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

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
def list_casesearch(list: str, data: str) -> str: ...

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

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
def list_casesearch_pos(list: str, data: str) -> int: ...

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

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
def list_get(list: str, position: int) -> str: ...

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

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
def list_set(item: str, value: str) -> int: ...

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

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
def list_next(item: str) -> str: ...

# example
item = weechat.list_next(item)

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
def list_prev(item: str) -> str: ...

# example
item = weechat.list_prev(item)

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
def list_string(item: str) -> str: ...

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

list_user_data

WeeChat ≥ 2.6.

Return pointer to the user data of an item.

Prototype:

void *weechat_list_user_data (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

pointer to the user data of item

C example:

weechat_printf (NULL, "user data of item: %p", weechat_list_user_data (item));

Note	This function is not available in scripting API.

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
def list_size(list: str) -> int: ...

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

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
def list_remove(list: str, item: str) -> int: ...

# example
weechat.list_remove(list, item)

list_remove_all

Remove all items from 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
def list_remove_all(list: str) -> int: ...

# example
weechat.list_remove_all(list)

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
def list_free(list: str) -> int: ...

# example
weechat.list_free(list)

3.9. Array lists

Array list functions.

An array list is a list of pointers with a dynamic size and optional sort.

arraylist_new

WeeChat ≥ 1.8.

Create a new array list.

Prototype:

struct t_arraylist *weechat_arraylist_new (int initial_size,
                                           int sorted,
                                           int allow_duplicates,
                                           int (*callback_cmp)(void *data,
                                                               struct t_arraylist *arraylist,
                                                               void *pointer1,
                                                               void *pointer2),
                                           void *callback_cmp_data,
                                           void (*callback_free)(void *data,
                                                                 struct t_arraylist *arraylist,
                                                                 void *pointer),
                                           void *callback_free_data);

Arguments:

initial_size: initial size of the array list (not the number of items)
sorted: 1 to sort the array list, 0 for no sort
allow_duplicates: 1 to allow duplicate entries, 0 to prevent a same entry to be added again
callback_cmp: callback used to compare two items (optional), arguments and return value:
- void *data: pointer
- struct t_arraylist *arraylist: array list pointer
- void *pointer1: pointer to first item
- void *pointer2: pointer to second item
- return value:
  - negative number if first item is less than second item
  - 0 if first item equals second item
  - positive number if first item is greater than second item
callback_cmp_data: pointer given to callback when it is called by WeeChat
callback_free: callback used to free an item (optional), arguments:
- void *data: pointer
- struct t_arraylist *arraylist: array list pointer
- void *pointer: pointer to item
callback_free_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new array list

C example:

int
cmp_cb (void *data, struct t_arraylist *arraylist,
        void *pointer1, void *pointer2)
{
    if (...)
        return -1;
    else if (...)
        return 1;
    else
        return 0;
}

struct t_arraylist *list = weechat_arraylist_new (32, 1, 1,
                                                  &cmp_cb, NULL, NULL, NULL);

Note	This function is not available in scripting API.

arraylist_size

WeeChat ≥ 1.8.

Return size of array list (number of item pointers).

Prototype:

int weechat_list_size (struct t_arraylist *arraylist);

Arguments:

arraylist: array list pointer

Return value:

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

C example:

weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));

Note	This function is not available in scripting API.

arraylist_get

WeeChat ≥ 1.8.

Return an item pointer by position.

Prototype:

void *weechat_arraylist_get (struct t_arraylist *arraylist, int index);

Arguments:

arraylist: array list pointer
index: index in list (first pointer is 0)

Return value:

pointer found, NULL if pointer was not found

C example:

void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */

Note	This function is not available in scripting API.

arraylist_search

WeeChat ≥ 1.8.

Search an item in an array list.

Prototype:

void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer,
                                int *index, int *index_insert);

Arguments:

arraylist: array list pointer
pointer: pointer to the item to search in array list
index: pointer to integer that will be set to the index found, or -1 if not found (optional)
index_insert: pointer to integer that will be set with the index that must be used to insert the element in the arraylist (to keep arraylist sorted) (optional)

Return value:

pointer to item found, NULL if item was not found

C example:

int index, index_insert;
void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);

Note	This function is not available in scripting API.

arraylist_insert

WeeChat ≥ 1.8.

Insert an item in an array list.

Prototype:

int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer);

Arguments:

arraylist: array list pointer
index: position of the item in array list or -1 to add at the end (this argument is used only if the array list is not sorted, it is ignored if the array list is sorted)
pointer: pointer to the item to insert

Return value:

index of new item (≥ 0), -1 if error.

C example:

int index = weechat_arraylist_insert (arraylist, -1, pointer);  /* insert at the end if not sorted */

Note	This function is not available in scripting API.

arraylist_add

WeeChat ≥ 1.8.

Add an item in an array list.

Prototype:

int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer);

Arguments:

arraylist: array list pointer
pointer: pointer to the item to add

Return value:

index of new item (≥ 0), -1 if error.

C example:

int index = weechat_arraylist_add (arraylist, pointer);

Note	This function is not available in scripting API.

arraylist_remove

WeeChat ≥ 1.8.

Remove an item from an array list.

Prototype:

int weechat_arraylist_remove (struct t_arraylist *arraylist, int index);

Arguments:

arraylist: array list pointer
index: index of the item to remove

Return value:

index of item removed, -1 if error.

C example:

int index_removed = weechat_arraylist_remove (arraylist, index);

Note	This function is not available in scripting API.

arraylist_clear

WeeChat ≥ 1.8.

Remove all items from an array list.

Prototype:

int weechat_arraylist_clear (struct t_arraylist *arraylist);

Arguments:

arraylist: array list pointer

Return value:

1 if OK, 0 if error

C example:

if (weechat_arraylist_clear (arraylist))
{
    /* OK */
}

Note	This function is not available in scripting API.

arraylist_free

WeeChat ≥ 1.8.

Free an array list.

Prototype:

void weechat_arraylist_free (struct t_arraylist *arraylist);

Arguments:

arraylist: array list pointer

C example:

weechat_arraylist_free (arraylist);

Note	This function is not available in scripting API.

3.10. Hashtables

Hashtable functions.

hashtable_new

WeeChat ≥ 0.3.3, updated in 4.4.0.

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
- WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)
type_values: type for values in hashtable:
- WEECHAT_HASHTABLE_INTEGER
- WEECHAT_HASHTABLE_STRING
- WEECHAT_HASHTABLE_POINTER
- WEECHAT_HASHTABLE_BUFFER
- WEECHAT_HASHTABLE_TIME
- WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)
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.

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.

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.

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.

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.

hashtable_map

WeeChat ≥ 0.3.3.

Call a function on all hashtable entries, by insertion order in the hashtable (from oldest to newest one).

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.

hashtable_map_string

WeeChat ≥ 0.3.7.

Call a function on all hashtable entries, by insertion order in the hashtable (from oldest to newest one), 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.

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.

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.

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
  - longlong: long long integer
- type_values: type for values:
  - integer: integer
  - string: string
  - pointer: pointer
  - buffer: buffer
  - time: time
  - longlong: long long integer
- 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.

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.

hashtable_add_to_infolist

WeeChat ≥ 0.3.3.

Add hashtable items to an infolist item, by insertion order in the hashtable (from oldest to newest one).

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.

hashtable_add_from_infolist

WeeChat ≥ 2.2.

Add infolist items in a hashtable.

Prototype:

int weechat_hashtable_add_from_infolist (struct t_hashtable *hashtable,
                                         struct t_infolist *infolist,
                                         const char *prefix);

Arguments:

hashtable: hashtable pointer
infolist: infolist pointer
prefix: string used as prefix for names in infolist

Return value:

1 if OK, 0 if error

C example:

weechat_hashtable_add_from_infolist (hashtable, infolist, "testhash");

/* if infolist contains:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
   then following variables will be added to hashtable:
     "key1" => "value 1"
     "key2" => "value 2"
*/

Note	This function is not available in scripting API.

hashtable_remove

WeeChat ≥ 0.3.3.

Remove an item from 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.

hashtable_remove_all

WeeChat ≥ 0.3.3.

Remove all items from 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.

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.11. Configuration files

Functions for configuration files.

config_new

Updated in 1.5, 4.0.0.

Create a new configuration file.

Prototype:

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

Arguments:

name: name of configuration file (without path or extension); a priority is allowed before the name, with format nnn|name where nnn is non-negative integer with priority; default priority is 1000; files are sorted by priority from higher to lower when running command /reload (see priority of configuration files below)
callback_reload: function called when configuration file is reloaded with /reload (optional, can be NULL, see below), arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_reload_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed

Reload callback:

The callback must only call the function config_reload, it must not remove the configuration file.
A callback is needed only if it does some things before and/or after the call to the function config_reload.
If no callback is given, WeeChat will call its internal reload function, so the configuration file will be reloaded in all cases.

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 config_write. You should call this function only after adding some sections (with config_new_section) and options (with config_new_option).

Priority of default configuration files:

Rank	File	Priority
1	sec.conf	120000
2	weechat.conf	110000
3	plugins.conf	100000
4	charset.conf	16000
5	logger.conf	15000
6	exec.conf	14000
7	trigger.conf	13000
8	spell.conf	12000
9	alias.conf	11000
10	buflist.conf	10000
11	fifo.conf	9000
12	typing.conf	8000
13	xfer.conf	7000
14	irc.conf	6000
15	relay.conf	5000
16	guile.conf	4070
17	javascript.conf	4060
18	lua.conf	4050
19	perl.conf	4040
20	php.conf	4030
21	python.conf	4020
22	ruby.conf	4010
23	tcl.conf	4000
24	script.conf	3000
25	fset.conf	2000

C example:

int
my_config_reload_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ...

# example
def my_config_reload_cb(data: str, config_file: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

config_set_version

WeeChat ≥ 4.0.0.

Set configuration file version and a callback to update config sections/options on-the-fly when the config is read.

Prototype:

int config_file_set_version (struct t_config_file *config_file,
                             int version,
                             struct t_hashtable *(*callback_update)(const void *pointer,
                                                                    void *data,
                                                                    struct t_config_file *config_file,
                                                                    int version_read,
                                                                    struct t_hashtable *data_read),
                             const void *callback_update_pointer,
                             void *callback_update_data);

Arguments:

config_file: configuration file pointer
version: version, must be ≥ 2
callback_update: function called when configuration file is read, for each section and each option, if the version read is less than the expected version, (optional, can be NULL, see below), arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- int version_read: version read in configuration file (1 by default)
- struct t_hashtable *data_read: hashtable with data read from configuration file (see below)
- return value:
  - either "data_read" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string")
callback_update_pointer: pointer given to callback when it is called by WeeChat
callback_update_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed

Update callback:

The callback receives a hashtable with data read from configuration file:

Key Availability Value

config

Always set

Name of configuration file, without extension (eg: weechat)

section

Always set

Name of section being read

option

For option only

Name of the option

value

For option only

Value of the option (if not NULL)

value_null

For option only

Option as NULL value (value is always 1)

The callback can update "section" for a line with a section and "option", "value" and "value_null" for a line with an option.
If "option" is set to empty string by the callback, the line read in configuration file is ignored.
Field "value_null" is set to force a NULL value for the option.

Return value:

1 if OK, 0 if error

C example:

struct t_hashtable *
my_config_update_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     int version_read,
                     struct t_hashtable *data_read)
{
    const char *ptr_section, *ptr_option;

    /* return now if version is already up-to-date */
    if (version_read >= 2)
        return NULL;

    ptr_section = hashtable_get (data_read, "section");
    ptr_option = hashtable_get (data_read, "option");

    /* rename section "abc" to "def" */
    if (ptr_section && !ptr_option && (strcmp (ptr_section, "abc") == 0))
    {
        hashtable_set (data_read, "section", "def");
        return data_read;
    }

    /* limit other changes to section "test" */
    if (!ptr_section || !ptr_option || (strcmp (ptr_section, "test") != 0))
        return NULL;

    /* rename option "test1" to "test2" */
    if (strcmp (ptr_option, "test1") == 0)
    {
        hashtable_set (data_read, "option", "test2");
        return data_read;
    }

    /* set value to "xxx" for option "test" */
    if (strcmp (ptr_option, "test") == 0)
    {
        hashtable_set (data_read, "value", "xxx");
        return data_read;
    }

    /* set value to NULL for option "test_null" */
    if (strcmp (ptr_option, "test_null") == 0)
    {
        hashtable_set (data_read, "value_null", "1");
        return data_read;
    }

    /* no changes */
    return NULL;
}

struct t_config_file *config_file = weechat_config_new ("test", NULL, NULL, NULL);
weechat_config_set_version (config_file, 2, &my_config_update_cb, NULL, NULL);
weechat_config_read (config_file);

Script (Python):

# prototype
def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int: ...

# example
def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]:
    # return now if version is already up-to-date
    if version_read >= 2:
        return {}

    section = data_read.get("section")
    option = data_read.get("option")

    # rename section "abc" to "def"
    if section and not option and section == "abc":
        data_read["section"] = "def"
        return data_read

    # limit other changes to section "test"
    if not section or not option or section != "test":
        return {}

    # rename option "test1" to "test2"
    if option == "test1":
        data_read["option"] = "test2"
        return data_read

    # set value to "xxx" for option "test"
    if option == "test":
        data_read["value"] = "xxx"
        return data_read

    # set value to NULL for option "test_null"
    if option == "test_null":
        data_read["value_null"] = "1"
        return data_read

    # no changes
    return {}

config_file = weechat.config_new("test", "", "")
weechat.config_set_version(config_file, 2, "my_config_update_cb", "")
weechat.config_read(config_file)

config_new_section

Updated in 1.5.

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)(const void *pointer,
                         void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    const void *callback_read_pointer,
    void *callback_read_data,
    int (*callback_write)(const void *pointer,
                          void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    const void *callback_write_pointer,
    void *callback_write_data,
    int (*callback_write_default)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name),
    const void *callback_write_default_pointer,
    void *callback_write_default_data,
    int (*callback_create_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    const void *callback_create_option_pointer,
    void *callback_create_option_data,
    int (*callback_delete_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    const void *callback_delete_option_pointer,
    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:
- const void *pointer: pointer
- 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_read_pointer: pointer given to callback when it is called by WeeChat
callback_read_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed
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:
- const void *pointer: pointer
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- struct t_config_section *section: section 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_pointer: pointer given to callback when it is called by WeeChat
callback_write_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed
callback_write_default: function called when default values for section must be written in file, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_write_default_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed
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:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_create_option_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed
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:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_delete_option_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

Return value:

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

C example:

int
my_section_read_cb (const void *pointer, 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_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

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

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

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

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_create_option_cb (const void *pointer, 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_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_delete_option_cb (const void *pointer, 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_OK_NO_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* standard section, user cannot add/delete options */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL);

/* 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, NULL,
                                &my_section_write_cb, NULL, NULL,
                                &my_section_write_default_cb, NULL, NULL,
                                &my_section_create_option_cb, NULL, NULL,
                                &my_section_delete_option_cb, NULL, NULL);

Script (Python):

# prototype
def config_new_section(config_file: str, name: str,
                       user_can_add_options: int, user_can_delete_options: int,
                       callback_read: str, callback_read_data: str,
                       callback_write: str, callback_write_data: str,
                       callback_write_default: str, callback_write_default_data: str,
                       callback_create_option: str, callback_create_option_data: str,
                       callback_delete_option: str, callback_delete_option_data: str) -> str: ...

# example
def my_section_read_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_write_default_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_create_option_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_delete_option_cb(data: str, config_file: str, section: str, option: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR

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

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
def config_search_section(config_file: str, section_name: str) -> str: ...

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

config_new_option

Updated in 1.5, 4.1.0.

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)(const void *pointer,
                                void *data,
                                struct t_config_option *option,
                                const char *value),
    const void *callback_check_value_pointer,
    void *callback_check_value_data,
    void (*callback_change)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_change_pointer,
    void *callback_change_data,
    void (*callback_delete)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_delete_pointer,
    void *callback_delete_data);

Arguments:

config_file: configuration file pointer
section: section pointer
name: name of option; with WeeChat ≥ 1.4, the name can include a parent option name (the value of parent option will be displayed in /set command output if this option is "null"), the syntax is then: "name << file.section.option"
type: type of option:
- boolean: boolean value (on/off)
- integer: integer value
- string: string value
- color: color
- enum: list of string values (stored as integer internally)
description: description of option
string_values: values as string (separated by |) (optional, required for type enum)
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:
- const void *pointer: pointer
- 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_pointer: pointer given to check_value callback when it is called by WeeChat
callback_check_value_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed
callback_change: function called when value of option has changed (optional), arguments:
- const void *pointer: pointer
- void *data: pointer
- struct t_config_option *option: option pointer
callback_change_pointer: pointer given to change callback when it is called by WeeChat
callback_change_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed
callback_delete: function called when option will be deleted (optional), arguments:
- const void *pointer: pointer
- void *data: pointer
- struct t_config_option *option: option pointer
callback_delete_pointer: pointer given to delete callback when it is called by WeeChat
callback_delete_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed

Return value:

pointer to new option in section, NULL if an error

C example:

/* boolean */
struct t_config_option *option_bool =
    weechat_config_new_option (config_file, section, "option_bool", "boolean",
                               "My option, type boolean",
                               NULL,
                               0, 0,
                               "on",
                               "on",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* integer */
struct t_config_option *option_int =
    weechat_config_new_option (config_file, section, "option_int", "integer",
                               "My option, type integer",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* string */
struct t_config_option *option_str =
    weechat_config_new_option (config_file, section, "option_str", "string",
                               "My option, type string",
                               NULL,
                               0, 0,
                               "test",
                               "test",
                               1,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* color */
struct t_config_option *option_col =
    weechat_config_new_option (config_file, section, "option_col", "color",
                               "My option, type color",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* enum */
struct t_config_option *option_enum =
    weechat_config_new_option (config_file, section, "option_enum", "enum",
                               "My option, type enum",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

Script (Python):

# prototype
def config_new_option(config_file: str, section: str, name: str, type: str, description: str,
                      string_values: str, min: int, max: int,
                      default_value: Union[str, None], value: Union[str, None], null_value_allowed: int,
                      callback_check_value: str, callback_check_value_data: str,
                      callback_change: str, callback_change_data: str,
                      callback_delete: str, callback_delete_data: str) -> str: ...

# example
def option_str_check_value_cb(data: str, option: str, value: str) -> int:
    # ...
    return 1
    # return 0

def option_str_change_cb(data: str, option: str) -> None:
    # ...

def option_str_delete_cb(data: str, option: str) -> None:
    # ...

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

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

option_str = weechat.config_new_option(config_file, section, "option_str", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option_str_check_value_cb", "",
    "option_str_change_cb", "",
    "option_str_delete_cb", "")

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

option_enum = weechat.config_new_option(config_file, section, "option_enum", "enum",
    "My option, type enum",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 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).

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
def config_search_option(config_file: str, section: str, option_name: str) -> str: ...

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

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.

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.

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
def config_string_to_boolean(text: str) -> int: ...

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

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
def config_option_reset(option: str, run_callback: int) -> int: ...

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

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, special values are possible according to the type of option:
- boolean:
  - toggle: toggle the current value
- integer, color or enum:
  - ++N: add N (any integer) to the current value
  - --N: subtract N (any integer) from the current value
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
def config_option_set(option: str, value: str, run_callback: int) -> int: ...

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

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 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
def config_option_set_null(option: str, run_callback: int) -> int: ...

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

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
def config_option_unset(option: str) -> int: ...

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

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
def config_option_rename(option: str, new_name: str) -> int: ...

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

config_option_get_string

WeeChat ≥ 1.9.

Return string value of an option property.

Prototype:

const char *weechat_config_option_get_string (struct t_config_option *option,
                                              const char *property);

Arguments:

option: option pointer
property: property name:
- config_name: file name
- section_name: section name
- name: option name
- parent_name: name of parent option
- type: option type, one of:
  - boolean
  - integer
  - string
  - color
  - enum
- description: option description

Return value:

string value of property

C example:

const char *type = weechat_config_option_get_string (option, "type");

Note	This function is not available in scripting API.

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 *)
- parent_name: name of parent option (char *) (WeeChat ≥ 1.4)
- 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.

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
def config_option_is_null(option: str) -> int: ...

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

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
def config_option_default_is_null(option: str) -> int: ...

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

config_boolean

Return boolean value of option.

Prototype:

int weechat_config_boolean (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: boolean value of option (0 or 1)
integer: 0
string: 0
color: 0
enum: 0

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
def config_boolean(option: str) -> int: ...

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

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, depending on the option type:

boolean: default boolean value of option (0 or 1)
integer: 0
string: 0
color: 0
enum: 0

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
def config_boolean_default(option: str) -> int: ...

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

config_boolean_inherited

WeeChat ≥ 4.3.0.

Return inherited boolean value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype:

int weechat_config_boolean_inherited (struct t_config_option *option);

Arguments:

option: option pointer

Return value: see functions config_boolean and config_boolean_default.

C example:

struct t_config_option *option = weechat_config_get ("irc.server.libera.autoconnect");
int autoconnect = weechat_config_boolean_inherited (option);

Script (Python):

# prototype
def config_boolean_inherited(option: str) -> int: ...

# example
option = weechat.config_get("irc.server.libera.autoconnect")
autoconnect = weechat.config_boolean_inherited(option)

config_integer

Return integer value of option.

Prototype:

int weechat_config_integer (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: boolean value of option (0 or 1)
integer: integer value of option
string: 0
color: color index
enum: integer value of option (index of enum value)

C example:

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

Script (Python):

# prototype
def config_integer(option: str) -> int: ...

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

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, depending on the option type:

boolean: default boolean value of option (0 or 1)
integer: default integer value of option
string: 0
color: default color index
enum: default integer value of option (index of enum value)

C example:

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

Script (Python):

# prototype
def config_integer_default(option: str) -> int: ...

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

config_integer_inherited

WeeChat ≥ 4.3.0.

Return inherited integer value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype:

int weechat_config_integer_inherited (struct t_config_option *option);

Arguments:

option: option pointer

Return value: see functions config_integer and config_integer_default.

C example:

struct t_config_option *option = weechat_config_get ("irc.server.libera.autojoin_delay");
int delay = weechat_config_integer_inherited (option);

Script (Python):

# prototype
def config_integer_inherited(option: str) -> int: ...

# example
option = weechat.config_get("irc.server.libera.autojoin_delay")
delay = weechat.config_integer_inherited(option)

config_string

Return string value of option.

Prototype:

const char *weechat_config_string (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: "on" if value is true, otherwise "off"
integer: NULL
string: string value of option
color: name of color
enum: 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
def config_string(option: str) -> str: ...

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

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, depending on the option type:

boolean: "on" if default value is true, otherwise "off"
integer: NULL
string: default string value of option
color: name of default color
enum: 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
def config_string_default(option: str) -> str: ...

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

config_string_inherited

WeeChat ≥ 4.3.0.

Return inherited string value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype:

const char *weechat_config_string_inherited (struct t_config_option *option);

Arguments:

option: option pointer

Return value: see functions config_string and config_string_default.

C example:

struct t_config_option *option = weechat_config_get ("irc.server.libera.msg_quit");
const char *msg_quit = weechat_config_string_inherited (option);

Script (Python):

# prototype
def config_string_inherited(option: str) -> str: ...

# example
option = weechat.config_get("irc.server.libera.msg_quit")
msg_quit = weechat.config_string_inherited(option)

config_color

Return color value of option.

Prototype:

const char *weechat_config_color (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: NULL
integer: NULL
string: NULL
color: name of color
enum: NULL

C example:

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

Script (Python):

# prototype
def config_color(option: str) -> str: ...

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

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, depending on the option type:

boolean: NULL
integer: NULL
string: NULL
color: name of default color
enum: NULL

C example:

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

Script (Python):

# prototype
def config_color_default(option: str) -> str: ...

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

config_color_inherited

WeeChat ≥ 4.3.0.

Return inherited color value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype:

const char *weechat_config_color_inherited (struct t_config_option *option);

Arguments:

option: option pointer

Return value: see functions config_color and config_color_default.

C example:

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

Script (Python):

# prototype
def config_color_inherited(option: str) -> str: ...

# example
option = weechat.config_get("plugin.section.option")
color = weechat.config_color_inherited(option)

config_enum

WeeChat ≥ 4.1.0.

Return enum value of option, as integer.

Prototype:

int weechat_config_enum (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: boolean value of option (0 or 1)
integer: integer value of option
string: 0
color: color index
enum: integer value of option (index of enum value)

C example:

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

Script (Python):

# prototype
def config_enum(option: str) -> int: ...

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

config_enum_default

WeeChat ≥ 4.1.0.

Return default enum value of option, as integer.

Prototype:

int weechat_config_enum_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value, depending on the option type:

boolean: default boolean value of option (0 or 1)
integer: default integer value of option
string: 0
color: default color index
enum: integer value of option (index of enum value)

C example:

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

Script (Python):

# prototype
def config_enum_default(option: str) -> int: ...

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

config_enum_inherited

WeeChat ≥ 4.3.0.

Return inherited enum value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype:

int weechat_config_enum_inherited (struct t_config_option *option);

Arguments:

option: option pointer

Return value: see functions config_enum and config_enum_default.

C example:

struct t_config_option *option = weechat_config_get ("irc.server.libera.sasl_fail");
int sasl_fail = weechat_config_enum_inherited (option);

Script (Python):

# prototype
def config_enum_inherited(option: str) -> int: ...

# example
option = weechat.config_get("irc.server.libera.sasl_fail")
sasl_fail = weechat.config_enum_inherited(option)

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 (const void *pointer, 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
def config_write_option(config_file: str, option: str) -> int: ...

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

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 (const void *pointer, 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
def config_write_line(config_file: str, option_name: str, value: str) -> int: ...

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

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
def config_write(config_file: str) -> int: ...

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

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
def config_read(config_file: str) -> int: ...

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

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
def config_reload(config_file: str) -> int: ...

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

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
def config_option_free(option: str) -> int: ...

# example
weechat.config_option_free(option)

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
def config_section_free_options(section: str) -> int: ...

# example
weechat.config_section_free_options(section)

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
def config_section_free(section: str) -> int: ...

# example
weechat.config_section_free(section)

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
def config_free(config_file: str) -> int: ...

# example
weechat.config_free(config_file)

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
def config_get(option_name: str) -> str: ...

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

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
def config_get_plugin(option_name: str) -> str: ...

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

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
def config_is_set_plugin(option_name: str) -> int: ...

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

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
def config_set_plugin(option_name: str, value: str) -> int: ...

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

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
def config_set_desc_plugin(option_name: str, description: str) -> int: ...

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

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
def config_unset_plugin(option_name: str) -> int: ...

# 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.12. Key bindings

Functions for key bindings.

key_bind

WeeChat ≥ 0.3.6, updated in 1.8.

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 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; it can contain following special keys:
- __quiet: do not display the keys added in core buffer (WeeChat ≥ 1.8)

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
def key_bind(context: str, keys: Dict[str, str]) -> int: ...

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

key_unbind

WeeChat ≥ 0.3.6, updated in 2.0.

Remove key binding(s).

Caution

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 key_bind)
key: key to remove or a special value "area:XXX" to remove all keys having XXX as first or second area; if the key starts with "quiet:", the keys removed are not displayed in core buffer (WeeChat ≥ 2.0).

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
def key_unbind(context: str, key: str) -> int: ...

# 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.13. Display

Functions to display text in buffers.

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
def prefix(prefix: str) -> str: ...

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

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 color option name (from weechat.color.xxx), for example chat_delimiters
- option name (format: file.section.option), for example irc.color.message_quit (WeeChat ≥ 1.2)
- color with optional attributes/background (see below)
- attribute:
  - blink: set blink
  - -blink: remove blink
  - dim: set "dim" (half bright)
  - -dim: remove "dim" (half bright)
  - 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:

%: blink
.: "dim" (half bright)
*: 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
def color(color_name: str) -> str: ...

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

printf

Display a message on a buffer.

Prototype:

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

This function is a shortcut for function printf_datetime_tags.
These two calls give exactly same result:

weechat_printf (buffer, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "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
def prnt(buffer: str, message: str) -> int: ...

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

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

This function is a shortcut for function printf_datetime_tags.
These two calls give exactly same result:

weechat_printf_date_tags (buffer, 0, NULL, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "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 (NULL means no tags)
message: message to display

See the WeeChat user’s guide / Lines tags ^↗ for a list of commonly used tags in WeeChat.

C example:

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

Script (Python):

# prototype
def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ...

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

printf_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a buffer, using a custom date/time (with microseconds) and tags.

Prototype:

void weechat_printf_datetime_tags (struct t_gui_buffer *buffer, time_t date,
                                   int date_usec, 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)
date_usec: microseconds of date (between 0 and 999999)
tags: comma separated list of tags (NULL means no tags)
message: message to display

See the WeeChat user’s guide / Lines tags ^↗ for a list of commonly used tags in WeeChat.

C example:

struct timeval tv_now;

gettimeofday (&tv_now, NULL);
weechat_printf_datetime_tags (NULL, tv_now.tv_sec - 120, tv_now.tv_usec,
                              "notify_message",
                              "Message 2 minutes ago, with a tag 'notify_message'");

Script (Python):

# prototype
def prnt_datetime_tags(buffer: str, date: int, date_usec: int, tags: str, message: str) -> int: ...

# example
now = time.time()
time_sec = int(now)
time_usec = int((now * 1000000) % 1000000)
weechat.prnt_datetime_tags("", time_sec - 120, time_usec, "notify_message",
                           "Message 2 minutes ago, with a tag 'notify_message'")

Note	Function is called "print_datetime_tags" in scripts ("prnt_datetime_tags" in Python).

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

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

weechat_printf_y (buffer, 0, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "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
def prnt_y(buffer: str, y: int, message: str) -> int: ...

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

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

printf_y_date_tags

WeeChat ≥ 3.5.

Display a message on a line of a buffer with free content, using a custom date and tags.

Prototype:

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

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

weechat_printf_y_date_tags (buffer, 0, 0, NULL, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "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)
date: date for message (0 means current date/time)
tags: comma separated list of tags (NULL means no tags)
message: message to display

C example:

weechat_printf_y_date_tags (buffer, 2, 0, "my_tag", "My message on third line with a tag");

Script (Python):

# prototype
def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ...

# example
weechat.prnt_y_date_tags("", 2, 0, "my_tag", "My message on third line with a tag")

Note	Function is called "print_y_date_tags" in scripts ("prnt_y_date_tags" in Python).

printf_y_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a line of a buffer with free content, using a custom date/time (with microseconds) and tags.

Prototype:

void weechat_printf_y_datetime_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                     int date_usec, const char *tags, 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)
date: date for message (0 means current date/time)
date_usec: microseconds of date (between 0 and 999999)
tags: comma separated list of tags (NULL means no tags)
message: message to display

C example:

weechat_printf_y_datetime_tags (buffer, 2, 0, 0, "my_tag", "My message on third line with a tag");

Script (Python):

# prototype
def prnt_y_datetime_tags(buffer: str, y: int, date: int, date_usec: int, tags: str, message: str) -> int: ...

# example
weechat.prnt_y_datetime_tags("", 2, 0, 0, "my_tag", "My message on third line with a tag")

Note	Function is called "print_y_datetime_tags" in scripts ("prnt_y_datetime_tags" in Python).

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
def log_print(message: str) -> int: ...

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

Note	Function is called "log_print" in scripts.

3.14. 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).
Only a single priority per hook is allowed.

Default priority is 1000.

C examples:

/* hook modifier with priority = 2000 */
/* high priority: called before other modifier callbacks */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

/* hook two signals with priority = 3000 */
/* high priority: called before other signal callbacks */
weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL);

/* hook lines printed in formatted buffers with priority = 500 */
/* low priority: called after other line callbacks */
weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL);

Following hook types allow priority:

command
completion
command_run
line
signal
hsignal
config
modifier
info
info_hashtable
infolist
hdata
focus

hook_command

Updated in 1.5, 1.7.

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)(const void *pointer,
                                                     void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     const void *callback_pointer,
                                     void *callback_data);

Arguments:

command: command name (a priority is allowed before the command, 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 (see format below)
callback: function called when command is used, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

The completion template is a list of completions for each argument, separated by spaces. Many completions are possible for one argument, separated by |. Many templates are possible for same command, separated by ||.

The format of a completion can be:

%(name): the completion name
%(name:arguments): the completion name with arguments sent to the callback (WeeChat ≥ 1.7)
any string: it is used as-is in completion

For example the template list || add %(filters_names) || del %(filters_names)|-all will complete with following values in command arguments:

first argument: list, add and del
second argument, depending on first argument:
- list: nothing
- add: names of filters
- del: names of filters and -all

Default completion codes are:

Plugin

Name

Description

alias

list of aliases

alias

alias_value

value of alias

buflist

buflist_items

buflist bar items

buflist

buflist_items_used

buflist bar items used (according to option buflist.look.use_items)

exec

exec_commands_ids

ids (numbers and names) of executed commands

fset

fset_options

configuration files, sections, options and words of options

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_channels_autojoin

channels automatically joined on the current server (option "autojoin")

irc

irc_ignores_numbers

numbers for defined ignores

irc

irc_modelist_masks

modelist masks of current IRC channel; required argument: modelist mode

irc

irc_modelist_numbers

modelist numbers of current IRC channel; required argument: modelist mode

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_raw_filters

filters for irc raw buffer

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_prefix_modes_filter

arguments to filter by prefix mode (for example: "-o", "-h", "-v", "-*")

irc

irc_server_privates

privates on current IRC server

irc

irc_servers

IRC servers (internal names)

irc

nick

nicks of current IRC channel

javascript

javascript_script

list of scripts

lua

lua_script

list of scripts

perl

perl_script

list of scripts

php

php_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

relay

relay_remotes

relay remotes

ruby

ruby_script

list of scripts

script

script_extensions

list of script extensions

script

script_files

files in script directories

script

script_languages

list of script languages

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

spell

spell_dicts

list of installed dictionaries

spell

spell_langs

list of all languages supported

tcl

tcl_script

list of scripts

trigger

trigger_add_arguments

arguments for command that adds a trigger: trigger name, hooks, hook arguments, hook conditions, hook regex, hook command, hook return code, post actions

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_names_default

default triggers

trigger

trigger_names_disabled

disabled triggers

trigger

trigger_names_enabled

enabled triggers

trigger

trigger_option_value

value of a trigger option

trigger

trigger_options

options for triggers

trigger

trigger_post_action

trigger post actions

weechat

bars_items

names of bar items

weechat

bars_names

names of bars

weechat

bars_options

options for bars

weechat

buffer_local_variable_value

value of a buffer local variable

weechat

buffer_local_variables

buffer local variables

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

buffer_properties_setauto

properties that can be automatically 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

colors

color names

weechat

commands

commands (weechat and plugins); optional argument: prefix to add before the commands

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

custom_bar_item_add_arguments

arguments for command that adds a custom bar item: item name, conditions, content

weechat

custom_bar_item_conditions

conditions for custom bar item

weechat

custom_bar_item_contents

contents for custom bar item

weechat

custom_bar_items_names

names of custom bar items

weechat

env_value

value of an environment variable

weechat

env_vars

environment variables

weechat

eval_variables

variables that can be used in /eval command

weechat

filename

filename; optional argument: default path (evaluated, see /help eval)

weechat

filters_names

names of filters

weechat

filters_names_disabled

names of disabled filters

weechat

filters_names_enabled

names of enabled filters

weechat

hook_types

hook types

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; optional argument: prefix to add before the commands

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; optional argument: prefix to add before the 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 (const void *pointer, 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 ("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, NULL, 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
def hook_command(command: str, description: str, args: str, args_description: str,
                 completion: str, callback: str, callback_data: str) -> str: ...

# example
def my_command_cb(data: str, buffer: str, args: str) -> int:
    # ...
    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", "")

hook_completion

Updated in 1.5, 1.7.

Hook a completion.

Prototype:

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

Arguments:

completion_item: name of completion item, after you can use %(name) (or %(name:arguments) with WeeChat ≥ 1.7) in a command hooked (argument completion) (a priority is allowed before the completion item, 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:
- const void *pointer: pointer
- void *data: pointer
- const char *completion_item: name of completion item (with WeeChat ≥ 1.7 it can include arguments, with the format: name:arguments)
- struct t_gui_buffer *buffer: buffer where completion is made
- struct t_gui_completion *completion: structure used to add words for completion (see completion_list_add)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

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 completion functions like completion_list_add and must NOT update the command line.
To update the command line when Tab is pressed, you can use the function 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 (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_completion_list_add (completion, "word1", 0, WEECHAT_LIST_POS_SORT);
    weechat_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, NULL);

Script (Python):

# prototype
def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ...

# example
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    weechat.completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.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", "")

hook_completion_get_string

WeeChat ≥ 0.3.4.

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_get_string.

hook_completion_list_add

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_list_add.

hook_command_run

Updated in 1.5.

Hook a command when WeeChat runs it.

Prototype:

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

Arguments:

command: command to hook (wildcard * is allowed) (a priority is allowed before the command, see note about priority)
callback: function called when command is run, arguments and return value:
- const void *pointer: pointer
- 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: command will not be executed by WeeChat after callback
  - WEECHAT_RC_ERROR
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

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

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

Script (Python):

# prototype
def hook_command_run(command: str, callback: str, callback_data: str) -> str: ...

# example
def my_command_run_cb(data: str, buffer: str, command: str) -> int:
    weechat.prnt("", "I'm eating the completion!")
    return weechat.WEECHAT_RC_OK_EAT

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

hook_timer

Updated in 1.5.

Hook a timer.

Prototype:

struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int max_calls,
                                   int (*callback)(const void *pointer,
                                                   void *data,
                                                   int remaining_calls),
                                   const void *callback_pointer,
                                   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:
- const void *pointer: pointer
- void *data: pointer
- int remaining_calls: remaining calls (-1 if timer has no end)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_timer_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_timer(interval: int, align_second: int, max_calls: int, callback: str, callback_data: str) -> str: ...

# example
def my_timer_cb(data: str, remaining_calls: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

hook_fd

Updated in 1.3, 1.5, 2.0.

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)(const void *pointer,
                                                void *data,
                                                int fd),
                                const void *callback_pointer,
                                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 (WeeChat ≥ 1.3: this argument is ignored and not used anymore)
callback: function called a selected event occurs for file (or socket), arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- int fd: file descriptor
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

Important

In scripts, with WeeChat ≥ 2.0, the callback argument fd is an integer (with WeeChat ≤ 1.9, it was a string).
To be compatible with all versions, it is recommended to convert the argument to integer before using it, for example in Python: int(fd).

C example:

int
my_fd_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_fd(fd: int, flag_read: int, flag_write: int, flag_exception: int, callback: str, callback_data: str) -> str: ...

# example
def my_fd_cb(data: str, fd: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

hook_process

Updated in 1.5.

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

Note

Since version 0.3.9.2, the shell is not used anymore 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 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)(const void *pointer,
                                                     void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     const void *callback_pointer,
                                     void *callback_data);

Arguments:

command: command to launch in child process, URL (WeeChat ≥ 0.3.7) or function (WeeChat ≥ 1.5) (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:
- const void *pointer: pointer
- 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 (-1): data available, but child still running
    
    WEECHAT_HOOK_PROCESS_ERROR (-2): error when launching command
    
    WEECHAT_HOOK_PROCESS_CHILD (-3): callback is called in the child process (used only in C API, not scripting API)
- out: standard output of command (stdout)
- err: error output of command (stderr)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
  - child process return code (in case of function with "func:" in command)
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

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:https://www.example.com", to download content of URL (WeeChat ≥ 0.3.7). Options are possible for URL with function hook_process_hashtable.

The command can also be a function name with format: "func:name", to execute the function "name" (WeeChat ≥ 1.5). This function receives a single argument (data) and must return a string, which is sent to the callback.
In C API, the callback is called with the return code set to WEECHAT_HOOK_PROCESS_CHILD, which means the callback is running in the child process (after fork).
In scripting API, the function name is called directly and its result (string) is sent to the callback (like the output of an external command).

Tip	If you want to retrieve infos about WeeChat (like current stable version, latest git commit, etc.), you can use URLs on this page ^↗.

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:

/* example with an external command */
int
my_process_cb (const void *pointer, 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, NULL);

/* example with the callback called in the child process */
int
my_process_func_cb (const void *pointer, void *data, const char *command,
                    int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
    {
        /* do something blocking... */
        /* ... */

        /* the stdout will be sent as "out" in the parent callback */
        printf ("this is the result");

        /* return code of the process */
        return 0;
    }
    else
    {
        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 ("func:get_status", 5000,
                                                       &my_process_func_cb, NULL, NULL);

Script (Python):

# prototype
def hook_process(command: str, timeout: int, callback: str, callback_data: str) -> str: ...

# example with an external command
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    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", "")

# example with a script function
def get_status(data: str) -> str:
    # do something blocking...
    # ...
    return "this is the result"

def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    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("func:get_status", 5000, "my_process_cb", "")

hook_process_hashtable

WeeChat ≥ 0.3.7, updated in 1.5.

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)(const void *pointer,
                                                               void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               const void *callback_pointer,
                                               void *callback_data);

Arguments are the same as function 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

Min WeeChat

Value

Default

Description

argN (N ≥ 1)

0.4.0

any string

no arguments

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

0.4.3

(not used)

no stdin

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

buffer_flush

1.0

number of bytes

65536

Minimum number of bytes to flush stdout/stderr (to send output to callback), between 1 and 65536. With the value 1, the output is sent immediately to the callback.

detached

1.0

(not used)

not detached

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

For command "url:…", see available options in function hook_url.

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_process_cb (const void *pointer, 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_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                     options_url1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* example 2: open URL with custom HTTP headers */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: value1\n"
                           "Header2: value2");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://localhost:8080/",
                                                                     options_url2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}

/* example 3: 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, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* example 4: 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, NULL);
    weechat_hashtable_free (options_cmd2);
}

Script (Python):

# prototype
def hook_process_hashtable(command: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# example
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    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:https://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# example 2: open URL with custom HTTP headers
options = {
    "httpheader": "\n".join([
        "Header1: value1",
        "Header2: value2",
    ]),
}
hook2 = weechat.hook_process_hashtable("url:http://localhost:8080/",
                                       options,
                                       20000, "my_process_cb", "")

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

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

hook_url

WeeChat ≥ 4.1.0.

URL transfer.

Prototype:

struct t_hook *weechat_hook_url (const char *url,
                                 struct t_hashtable *options,
                                 int timeout,
                                 int (*callback)(const void *pointer,
                                                 void *data,
                                                 const char *url,
                                                 struct t_hashtable *options,
                                                 struct t_hashtable *output),
                                 const void *callback_pointer,
                                 void *callback_data);

Arguments:

url: URL
options: options for URL transfer (see below); the hashtable is duplicated in function, so it’s safe to free it after this call
timeout: timeout for URL transfer (in milliseconds): after this timeout, the transfer is stopped (0 means no timeout)
callback: function called when the transfer has ended, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- const char *url: URL
- struct t_hashtable *options: options
- struct t_hashtable *output: result (keys and values are strings), which may contain the following keys:
  - response_code: HTTP response code
  - headers: HTTP headers in response
  - output: standard output (set only if file_out was not set in options)
  - error: error message (set only in case of error)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

The following Curl options are available (see man curl_easy_setopt for a description of each option):

Option

Type ⁽¹⁾

Constants ⁽²⁾

verbose

long

header

long

noprogress

long

nosignal

long

wildcardmatch

long

failonerror

long

keep_sending_on_error

long

proxy

string

proxyport

long

port

long

pre_proxy

string

httpproxytunnel

long

interface

string

dns_cache_timeout

long

proxytype

long

http, socks4, socks5, socks4a, socks5_hostname, http_1_0, https

buffersize

long

tcp_nodelay

long

localport

long

localportrange

long

address_scope

long

noproxy

string

socks5_gssapi_nec

long

tcp_keepalive

long

tcp_keepidle

long

tcp_keepintvl

long

unix_socket_path

string

abstract_unix_socket

string

path_as_is

long

proxy_service_name

string

service_name

string

default_protocol

string

tcp_fastopen

long

socks5_auth

long

haproxyprotocol

long

doh_url

string

protocols_str

string

redir_protocols_str

string

netrc

long

ignored, optional, required

userpwd

string

proxyuserpwd

string

httpauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, negotiate, gssapi, bearer, aws_sigv4

proxyauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, negotiate, gssapi, bearer, aws_sigv4

netrc_file

string

username

string

password

string

proxyusername

string

proxypassword

string

tlsauth_type

mask

none, srp

tlsauth_username

string

tlsauth_password

string

sasl_authzid

string

sasl_ir

long

xoauth2_bearer

string

login_options

string

disallow_username_in_url

long

autoreferer

long

followlocation

long

post

long

postfields

string

referer

string

useragent

string

httpheader

list

string

cookiefile

string

postfieldsize

long

maxredirs

long

httpget

long

cookiejar

string

http_version

long

none, 1_0, 1_1, 2_0, 2, 2tls, 2_prior_knowledge, 3

cookiesession

long

http200aliases

list

unrestricted_auth

long

postfieldsize_large

long long

cookielist

string

ignore_content_length

long

accept_encoding

string

transfer_encoding

long

http_content_decoding

long

http_transfer_decoding

long

copypostfields

string

postredir

mask

post_301, post_302

expect_100_timeout_ms

long

headeropt

mask

unified, separate

proxyheader

list

pipewait

long

stream_weight

long

request_target

string

http09_allowed

long

hsts

string

hsts_ctrl

mask

enable, readonlyfile

mail_from

string

mail_rcpt

list

mail_auth

string

mail_rcpt_allowfails

long

tftp_blksize

long

tftp_no_options

long

ftpport

string

quote

list

postquote

list

ftp_use_epsv

long

prequote

list

ftp_use_eprt

long

ftp_create_missing_dirs

long

ftpsslauth

long

default, ssl, tls

ftp_account

string

ftp_skip_pasv_ip

long

ftp_filemethod

long

multicwd, nocwd, singlecwd

ftp_alternative_to_user

string

ftp_ssl_ccc

long

ccc_none, ccc_active, ccc_passive

dirlistonly

long

append

long

ftp_use_pret

long

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

aws_sigv4

string

crlf

long

range

string

resume_from

long

customrequest

string

nobody

long

infilesize

long

upload

long

timecondition

long

none, ifmodsince, ifunmodsince, lastmod

timevalue

long

transfertext

long

filetime

long

maxfilesize

long

proxy_transfer_mode

long

resume_from_large

long long

infilesize_large

long long

maxfilesize_large

long long

timevalue_large

long long

upload_buffersize

long

mime_options

mask

formescape

timeout

long

low_speed_limit

long

low_speed_time

long

fresh_connect

long

forbid_reuse

long

connecttimeout

long

ipresolve

long

whatever, v4, v6

connect_only

long

max_send_speed_large

long long

max_recv_speed_large

long long

timeout_ms

long

connecttimeout_ms

long

maxage_conn

long

maxconnects

long

use_ssl

long

none, try, control, all

resolve

list

dns_servers

string

accepttimeout_ms

long

dns_interface

string

dns_local_ip4

string

dns_local_ip6

string

connect_to

list

happy_eyeballs_timeout_ms

long

dns_shuffle_addresses

long

upkeep_interval_ms

long

maxlifetime_conn

long

sslcert

string

sslversion

long

default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3

ssl_verifypeer

long

cainfo

string

ssl_verifyhost

long

ssl_cipher_list

string

sslcerttype

string

sslkey

string

sslkeytype

string

sslengine

string

sslengine_default

long

capath

string

ssl_sessionid_cache

long

krblevel

string

keypasswd

string

issuercert

string

crlfile

string

certinfo

long

gssapi_delegation

long

none, policy_flag, flag

ssl_options

long

allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert

ssl_enable_alpn

long

pinnedpublickey

string

ssl_verifystatus

long

ssl_falsestart

long

proxy_cainfo

string

proxy_capath

string

proxy_crlfile

string

proxy_keypasswd

string

proxy_pinnedpublickey

string

proxy_sslcert

string

proxy_sslcerttype

string

proxy_sslkey

string

proxy_sslkeytype

string

proxy_sslversion

long

default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3

proxy_ssl_cipher_list

list

proxy_ssl_options

long

allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert

proxy_ssl_verifyhost

long

proxy_ssl_verifypeer

long

proxy_tlsauth_password

string

proxy_tlsauth_type

string

proxy_tlsauth_username

string

tls13_ciphers

list

proxy_tls13_ciphers

list

proxy_issuercert

string

ssl_ec_curves

string

doh_ssl_verifyhost

long

doh_ssl_verifypeer

long

doh_ssl_verifystatus

long

ca_cache_timeout

long

ssh_auth_types

mask

none, policy_flag, flag

ssh_public_keyfile

string

ssh_private_keyfile

string

ssh_host_public_key_md5

string

ssh_knownhosts

string

ssh_compression

long

ssh_host_public_key_sha256

string

telnetoptions

list

ws_options

mask

binary, close, cont, offset, ping, pong, raw_mode, text

new_file_perms

long

new_directory_perms

long

quick_exit

long

Note	⁽¹⁾ For options with type "mask", format is: "value1+value2+value3"; for options with type "list", the list items must be separated by a newline (`\n`). ⁽²⁾ When constants are available they must be used as value for option.

These two extra options (strings) are allowed for input/output file:

Option

Type

Description

file_in

string

file to read and send with URLs (post file)

file_out

string

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_url_cb (const void *pointer, void *data, const char *url,
           struct t_hashtable *options, struct t_hashtable *output)
{
    weechat_printf (NULL, "response_code: %s", weechat_hashtable_get (output, "response_code"));
    weechat_printf (NULL, "headers: %s", weechat_hashtable_get (output, "headers"));
    weechat_printf (NULL, "output: %s", weechat_hashtable_get (output, "output"));
    weechat_printf (NULL, "error: %s", weechat_hashtable_get (output, "error"));
    return WEECHAT_RC_OK;
}

/* example 1: output to a file */
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_url_hook = weechat_hook_url ("https://weechat.org/",
                                                   options_url1,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* example 2: custom HTTP headers, output sent to callback */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: value1\n"
                           "Header2: value2");
    struct t_hook *my_url_hook = weechat_hook_url ("http://localhost:8080/",
                                                   options_url2,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}

Script (Python):

# prototype
def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# example
def my_url_cb(data: str, url: str, options: Dict[str, str], output: Dict[str, str]) -> int:
    weechat.prnt("", "output: %s" % output)
    return weechat.WEECHAT_RC_OK

# example 1: output to a file
hook1 = weechat.hook_url("https://weechat.org/",
                         {"file_out": "/tmp/weechat.org.html"},
                         20000, "my_url_cb", "")

# example 2: custom HTTP headers, output sent to callback
options = {
    "httpheader": "\n".join([
        "Header1: value1",
        "Header2: value2",
    ]),
}
hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "")

hook_connect

Updated in 1.5, 2.0, 4.4.0.

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)(const void *pointer,
                                                     void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     const void *callback_pointer,
                                     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:
- WEECHAT_HOOK_CONNECT_IPV6_DISABLE ⁽¹⁾: disable IPv6 (use only IPv4)
- WEECHAT_HOOK_CONNECT_IPV6_AUTO ⁽¹⁾: use IPv6 with fallback to IPv4
- WEECHAT_HOOK_CONNECT_IPV6_FORCE ⁽¹⁾: force IPv6 (do not use IPv4) (WeeChat ≥ 4.4.0)
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:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Note

⁽¹⁾ Constants for parameter ipv6 are available since WeeChat 4.4.0.
For older releases, allowed values are 1 (use IPv6 with fallback to IPv4) and 0 (disable IPv6, use only IPv4).
⁽²⁾ In scripts, with WeeChat ≥ 2.0, the callback arguments status, gnutls_rc and sock are integers (with WeeChat ≤ 1.9, they were strings).
To be compatible with all versions, it is recommended to convert the argument to integer before using it, for example in Python: int(sock).

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_connect_cb (const void *pointer, 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,
                                                       WEECHAT_HOOK_CONNECT_IPV6_AUTO,
                                                       0,
                                                       NULL, NULL, 0,  /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL, NULL);

Script (Python):

# prototype
def hook_connect(proxy: str, address: str, port: int, ipv6: int, retry: int, local_hostname: str,
                 callback: str, callback_data: str) -> str: ...

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

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

hook_line

WeeChat ≥ 2.3, updated in 4.2.0.

Hook a line to be printed in a buffer.

When a line is printed in a buffer, hooks are called in this order:

hook line (this hook): it can change the buffer, prefix, message, tags, notify level, … (see below)
hook modifier "weechat_print": it can change the prefix and message on a buffer with formatted content
hook print: called when the line has been added in a buffer with formatted content (nothing can be changed directly with this hook).

Note	The "line" hook is the only one among these three hooks that can work on buffers with free content.

Prototype:

struct t_hook *weechat_hook_line (const char *buffer_type,
                                  const char *buffer_name,
                                  const char *tags,
                                  struct t_hashtable *(*callback)(const void *pointer,
                                                                  void *data,
                                                                  struct t_hashtable *line),
                                  const void *callback_pointer,
                                  void *callback_data);

Arguments:

buffer_type: catch lines on the given buffer type (if NULL or empty string, formatted is the default) (WeeChat ≥ 3.7: a priority is allowed before the buffer type, see note about priority):
- formatted: catch lines on formatted buffers only (default)
- free: catch lines on buffers with free content only
- *: catch lines on all buffer types
buffer_name: comma-separated list of buffer masks (see buffer_match_list); NULL, empty string or "*" matches any buffer
tags: catch only messages with these tags (optional): 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
callback: function called when a line is added in a buffer, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_hashtable *line: hashtable with the line info, keys and values are strings (see table below)
- return value: hashtable with new values (see table below)
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

Line data sent to the callback is a hashtable, with following values (keys and values are strings):

Key Value (formatted buffer) Value (free buffer) Examples

buffer

Buffer pointer.

0x1234abcd

buffer_name

Buffer name.

core.weechat
irc.server.libera
irc.libera.#weechat

buffer_type

"formatted"

"free"

formatted
free

N/A ("-1").

Line number (≥ "0").

-1
8

date

Line date (timestamp).

N/A ("0").

1533792000

date_usec

Microseconds of line date (between 0 and 999999).

N/A ("0").

123456

date_printed

Date when line was displayed (timestamp).

N/A ("0").

1533792012

date_usec_printed

Microseconds of date when line was displayed (between 0 and 999999).

N/A ("0").

654321

str_time

Date for display (possible color codes inside).

N/A (empty string).

09:07:20

tags_count

Number of tags in the line (≥ "0").

N/A ("0").

2

hook_print

Updated in 0.4.3, 1.0, 1.5, 4.2.0.

Hook a message printed. It is called when a line has been added in a buffer with formatted content.

For more information on the hooks called when a line is printed, see hook_line.

Prototype:

struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(const void *pointer,
                                                   void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int date_usec,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   const void *callback_pointer,
                                   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:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- time_t date: date
- int date_usec: microseconds of 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

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 (const void *pointer, void *data, struct t_gui_buffer *buffer,
             time_t date, int date_usec, 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, NULL);

Script (Python):

# prototype
def hook_print(buffer: str, tags: str, message: str, strip_colors: int, callback: str, callback_data: str) -> str: ...

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

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

hook_signal

Updated in 1.5, 3.6.

Hook a signal.

Prototype:

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

Arguments:

signal: signal to catch, wildcard * is allowed; multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about priority) (see table below)
callback: function called when signal is received, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

List of signals sent by WeeChat and plugins:

Plugin Signal Min WeeChat Arguments Description

guile

guile_script_loaded

0.3.9

String: path to script.

Scheme script loaded.

guile

guile_script_unloaded

0.3.9

String: path to script.

Scheme script unloaded.

guile

guile_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Scheme script(s) installed.

guile

guile_script_removed

0.3.9

String: comma-separated list of scripts removed.

Scheme script(s) removed.

irc

xxx,irc_in_yyy ⁽¹⁾

String: message.

IRC message from server (before irc plugin uses it, signal sent only if message is not ignored).
Since version 2.2, the whole IRC message is sent, including tags.
If the return code of a callback is WEECHAT_RC_OK_EAT, then the IRC message is immediately destroyed and not processed (WeeChat ≥ 3.3).

irc

xxx,irc_in2_yyy ⁽¹⁾

String: message.

IRC message from server (after irc plugin uses it, signal sent only if message is not ignored).
Since version 2.2, the whole IRC message is sent, including tags.

irc

xxx,irc_raw_in_yyy ⁽¹⁾

0.3.2

String: message.

IRC message from server (before irc plugin uses it, signal sent even if message is ignored).
Since version 2.2, the whole IRC message is sent, including tags.
If the return code of a callback is WEECHAT_RC_OK_EAT, then the IRC message is immediately destroyed and not processed (WeeChat ≥ 3.3).

irc

xxx,irc_raw_in2_yyy ⁽¹⁾

0.3.2

String: message.

IRC message from server (after irc plugin uses it, signal sent even if message is ignored).
Since version 2.2, the whole IRC message is sent, including tags.

irc

xxx,irc_out1_yyy ⁽¹⁾

0.3.7

String: message.

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

irc

xxx,irc_out_yyy ⁽¹⁾

String: message.

IRC message sent to server after automatic split (to fit in 512 bytes by default).
Warning: the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead.

irc

xxx,irc_outtags_yyy ⁽¹⁾

0.3.4

String: tags + ";" + message.

Tags + IRC message sent to server.
Warning: the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead.

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

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_server_lag_changed

1.8

String: server name.

Lag changed on the server.

irc

irc_ignore_removing

Pointer: ignore.

Removing ignore.

irc

irc_ignore_removed

Ignore removed.

irc

irc_notify_join

0.3.8

String: server name + "," + nick.

A nick in notify list has joined server.

irc

irc_notify_quit

0.3.8

String: server name + "," + nick.

A nick in notify list has quit server.

irc

irc_notify_away

0.3.8

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

A nick in notify list is now away on server.

irc

irc_notify_still_away

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

0.3.8

String: server name + "," + nick.

A nick in notify list is back (away status removed).

javascript

javascript_script_loaded

1.2

String: path to script.

JavaScript script loaded.

javascript

javascript_script_unloaded

1.2

String: path to script.

JavaScript script unloaded.

javascript

javascript_script_installed

1.2

String: comma-separated list of paths to scripts installed.

JavaScript script(s) installed.

javascript

javascript_script_removed

1.2

String: comma-separated list of scripts removed.

JavaScript script(s) 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

0.3.9

String: path to script.

Lua script loaded.

lua

lua_script_unloaded

0.3.9

String: path to script.

Lua script unloaded.

lua

lua_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Lua script(s) installed.

lua

lua_script_removed

0.3.9

String: comma-separated list of scripts removed.

Lua script(s) removed.

perl

perl_script_loaded

0.3.9

String: path to script.

Perl script loaded.

perl

perl_script_unloaded

0.3.9

String: path to script.

Perl script unloaded.

perl

perl_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Perl script(s) installed.

perl

perl_script_removed

0.3.9

String: comma-separated list of scripts removed.

Perl script(s) removed.

php

php_script_loaded

2.0

String: path to script.

PHP script loaded.

php

php_script_unloaded

2.0

String: path to script.

PHP script unloaded.

php

php_script_installed

2.0

String: comma-separated list of paths to scripts installed.

PHP script(s) installed.

php

php_script_removed

2.0

String: comma-separated list of scripts removed.

PHP script(s) removed.

python

python_script_loaded

0.3.9

String: path to script.

Python script loaded.

python

python_script_unloaded

0.3.9

String: path to script.

Python script unloaded.

python

python_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Python script(s) installed.

python

python_script_removed

0.3.9

String: comma-separated list of scripts removed.

Python script(s) removed.

relay

relay_client_connecting

1.0

Pointer: relay client.

A relay client is connecting.

relay

relay_client_waiting_auth

1.0

Pointer: relay client.

Waiting for authentication from a relay client.

relay

relay_client_auth_ok

1.0

Pointer: relay client.

Successful authentication from a relay client.

relay

relay_client_connected

1.0

Pointer: relay client.

A relay client is connected.

relay

relay_client_auth_failed

1.0

Pointer: relay client.

Authentication of a relay client has failed.

relay

relay_client_disconnected

1.0

Pointer: relay client.

A relay client is disconnected.

ruby

ruby_script_loaded

0.3.9

String: path to script.

Ruby script loaded.

ruby

ruby_script_unloaded

0.3.9

String: path to script.

Ruby script unloaded.

ruby

ruby_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Ruby script(s) installed.

ruby

ruby_script_removed

0.3.9

String: comma-separated list of scripts removed.

Ruby script(s) removed.

spell

spell_suggest

2.4

Pointer: buffer.

New suggestions for a misspelled word.

tcl

tcl_script_loaded

0.3.9

String: path to script.

Tcl script loaded.

tcl

tcl_script_unloaded

0.3.9

String: path to script.

Tcl script unloaded.

tcl

tcl_script_installed

0.3.9

String: comma-separated list of paths to scripts installed.

Tcl script(s) installed.

tcl

tcl_script_removed

0.3.9

String: comma-separated list of scripts removed.

Tcl script(s) removed.

typing

typing_self_typing

3.3

Pointer: buffer.

User is typing a message (sent by typing plugin, used by irc plugin).

typing

typing_self_paused

3.3

Pointer: buffer.

User paused during typing (sent by typing plugin, used by irc plugin).

typing

typing_self_cleared

3.3

Pointer: buffer.

User cleared the input without sending the message (sent by typing plugin, used by irc plugin).

typing

typing_self_sent

3.3

Pointer: buffer.

Message (not a command) sent to the buffer (sent by typing plugin, used by irc plugin).

typing

typing_set_nick

3.3

String: buffer pointer + ";" + state (one of: "off", "typing", "paused", "cleared") + ";" + nick.

Set typing state for a nick on a buffer (sent by irc plugin, handled by typing plugin).

typing

typing_reset_buffer

3.3

Pointer: buffer.

Remove typing state for all nicks on a buffer (sent by irc plugin, handled by typing plugin).

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_filters_enabled

2.0

Pointer: buffer.

Filters enabled in buffer.

weechat

buffer_filters_disabled

2.0

Pointer: buffer.

Filters disabled in buffer.

weechat

buffer_hidden

Pointer: buffer.

Buffer hidden.

weechat

buffer_unhidden

Pointer: buffer.

Buffer unhidden.

weechat

buffer_line_added

0.3.7

Pointer: line.

Line added in a buffer.

weechat

buffer_line_data_changed

4.4.0

Pointer: line data.

Line data has been updated 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_modes_changed

4.3.0

Pointer: buffer.

Modes of buffer changed.

weechat

buffer_time_for_each_line_changed

4.4.0

Pointer: buffer.

Display time for each line changed.

weechat

buffer_type_changed

Pointer: buffer.

Type of buffer changed.

weechat

buffer_zoomed

0.4.3

Pointer: buffer.

Merged buffer zoomed.

weechat

buffer_unzoomed

0.4.3

Pointer: buffer.

Merged buffer unzoomed.

weechat

buffer_user_input_xxx ⁽²⁾

3.8

String: text sent to buffer.

Text sent to a user buffer as input (sent only for buffers created with /buffer add).
If the return code of a callback is WEECHAT_RC_OK_EAT, then the string "q" cannot be used anymore to close the buffer.

weechat

buffer_user_closing_xxx ⁽²⁾

3.8

User buffer is closing (sent only for buffers created with /buffer add).

weechat

cursor_start

3.2

Start cursor mode.

weechat

cursor_end

3.2

End cursor mode.

weechat

day_changed

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

Pointer: buffer (can be NULL).

Hotlist changed.

weechat

input_paste_pending

Paste pending.

weechat

input_search

Pointer: buffer.

Text search in buffer.

weechat

input_prompt_changed

4.3.0

Pointer: buffer.

Input prompt changed.

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

1.0

String: key combo.

Key combo in default context.

weechat

key_combo_search

1.0

String: key combo.

Key combo in search context.

weechat

key_combo_cursor

1.0

String: key combo.

Key combo in cursor context.

weechat

layout_buffers_applied

4.4.0

String: layout name.

Layout applied for buffers.

weechat

layout_windows_applied

4.4.0

String: layout name.

Layout applied for windows.

weechat

mouse_enabled

1.1

Mouse enabled.

weechat

mouse_disabled

1.1

Mouse disabled.

weechat

nicklist_group_added

0.3.2

String: buffer pointer + "," + group name.

Group added in nicklist.

weechat

nicklist_group_changed

0.3.4

String: buffer pointer + "," + group name.

Group changed in nicklist.

weechat

nicklist_group_removing

0.4.1

String: buffer pointer + "," + group name.

Removing group from nicklist.

weechat

nicklist_group_removed

0.3.2

String: buffer pointer + "," + group name.

Group removed from nicklist.

weechat

nicklist_nick_added

0.3.2

String: buffer pointer + "," + nick name.

Nick added in nicklist.

weechat

nicklist_nick_changed

0.3.4

String: buffer pointer + "," + nick name.

Nick changed in nicklist.

weechat

nicklist_nick_removing

0.4.1

String: buffer pointer + "," + nick name.

Removing nick from nicklist.

weechat

nicklist_nick_removed

0.3.2

String: buffer pointer + "," + nick name.

Nick removed from nicklist.

weechat

partial_completion

Partial completion happened.

weechat

plugin_loaded

0.3.9

String: path to plugin loaded.

Plugin loaded.

weechat

plugin_unloaded

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_sighup

1.3

Signal SIGHUP received.

weechat

signal_sigquit

1.2

Signal SIGQUIT received (quit request with core dump).

weechat

signal_sigterm

1.2

Signal SIGTERM received (graceful termination of WeeChat process).

weechat

signal_sigwinch

0.4.3

Signal SIGWINCH received (terminal was resized).

weechat

upgrade

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

Command /upgrade issued by user.

weechat

upgrade_ended

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

0.3.6

Pointer: window.

Closing window.

weechat

window_closed

0.3.6

Pointer: window.

Window closed.

weechat

window_opened

0.4.1

Pointer: window.

Window opened.

weechat

window_scrolled

Pointer: window.

Scroll in window.

weechat

window_switch

0.3.7

Pointer: window.

Switching window.

weechat

window_zoom

Pointer: current window.

Zooming 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

0.3.2

Pointer: infolist with xfer info.

Xfer has ended.

Note	⁽¹⁾ xxx is IRC server name, yyy is IRC command name. ⁽²⁾ xxx is buffer name.

C example:

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

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

Script (Python):

# prototype
def hook_signal(signal: str, callback: str, callback_data: str) -> str: ...

# example
def my_signal_cb(data: str, signal: str, signal_data: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# catch signals "quit" and "upgrade"
hook = weechat.hook_signal("quit;upgrade", "my_signal_cb", "")

hook_signal_send

Updated in 1.0, 4.5.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; flags are allowed before the signal name (see below) (WeeChat ≥ 4.5.0)
type_data: type of data sent with signal (see hook_signal)
signal_data: data sent with signal

The signal name can contain flags with the following format: [flags:xxx,yyy]signal where xxx and yyy are names of flags, and signal the signal name.
The following flags are supported:

stop_on_error: exit immediately if a callback returns WEECHAT_RC_ERROR (remaining callbacks are then NOT executed) (WeeChat ≥ 4.5.0)
ignore_eat: consider any callback returning WEECHAT_RC_OK_EAT is in fact WEECHAT_RC_OK and execute remaining callbacks (WeeChat ≥ 4.5.0)

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);
int rc2 = weechat_hook_signal_send ("[flags:stop_on_error,ignore_eat]my_signal2",
                                    WEECHAT_HOOK_SIGNAL_STRING, my_string);

Script (Python):

# prototype
def hook_signal_send(signal: str, type_data: str, signal_data: str) -> int: ...

# examples
rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
rc2 = weechat.hook_signal_send("[flags:stop_on_error,ignore_eat]my_signal2",
                               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
guile_script_install
javascript_script_install
php_script_install

The callback will do following actions when receiving signal:

Unload and remove installed script.
Move new script to directory ~/.local/share/weechat/xxx/ (where xxx is language).
Create link to new script in directory ~/.local/share/weechat/xxx/autoload/ (only if the script was already auto-loaded, or if the option script.scripts.autoload is enabled for a new script).
Load new script (if the script was loaded).

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, "/path/to/test.py");

Script (Python):

weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/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
guile_script_remove
javascript_script_remove
php_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, updated in 1.5.

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
comma-separated list of options (optional):
- priority_high: queue with high priority (like user messages); this is the default priority
- priority_low: queue with low priority (like messages automatically sent by WeeChat)
- user_message: force user message (don’t execute a command)
semicolon
comma-separated list of tags used when sending message (optional)
semicolon
text or command (required)

C examples:

/* say "Hello!" on libera server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "libera;#weechat;priority_high,user_message;;Hello!");

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

Script (Python):

# say "Hello!" on libera server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;#weechat;priority_high,user_message;;Hello!")

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

hook_hsignal

WeeChat ≥ 0.3.4, updated in 1.5, 3.6.

Hook a hsignal (signal with hashtable).

Prototype:

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

Arguments:

signal: signal to catch, wildcard * is allowed; multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about priority) (see table below)
callback: function called when signal is received, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

List of hsignals:

Plugin

Signal

Min WeeChat

Arguments

Description

irc

irc_redirection_xxx_yyy ⁽¹⁾

0.3.4

See hsignal_irc_redirect_command

Redirection output.

weechat

nicklist_group_added

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

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

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

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

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

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	⁽¹⁾ xxx is signal argument used in redirection, yyy is redirection pattern.

C example:

int
my_hsignal_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_hsignal(signal: str, callback: str, callback_data: str) -> str: ...

# example
def my_hsignal_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

hook_hsignal_send

WeeChat ≥ 0.3.4, updated in 1.0, 4.5.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; flags are allowed before the signal name (see function hook_signal_send) (WeeChat ≥ 4.5.0)
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, rc2;
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);
    rc2 = weechat_hook_hsignal_send ("[flags:stop_on_error,ignore_eat]my_hsignal2", hashtable);
    weechat_hashtable_free (hashtable);
}

Script (Python):

# prototype
def hook_hsignal_send(signal: str, hashtable: Dict[str, str]) -> int: ...

# examples
rc = weechat.hook_hsignal_send("my_hsignal", {"key": "value"})
rc2 = weechat.hook_hsignal_send("[flags:stop_on_error,ignore_eat]my_hsignal2", {"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 (const void *pointer, 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, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "libera");
    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,
                              "libera;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}

Script (Python):

def test_whois_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    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": "libera", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;;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"
# ...

hook_config

Updated in 1.5.

Hook a configuration option.

Prototype:

struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    const char *option,
                                                    const char *value),
                                    const void *callback_pointer,
                                    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 (a priority is allowed before the option, see note about priority)
callback: function called when configuration option is changed, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_config_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_config(option: str, callback: str, callback_data: str) -> str: ...

# example
def my_config_cb(data: str, option: str, value: str) -> int:
    # ...
    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", "")

hook_modifier

Updated in 1.5.

Hook a modifier.

Prototype:

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

Arguments:

modifier: modifier name (a priority is allowed before the modifier, see note about priority) (see table below)
callback: function called when modifier is used, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

List of modifiers used by WeeChat and plugins:

Modifier

Min WeeChat

Modifier data

String

Output

irc_batch

4.0.0

Server name + "," + batch type + "," + batch parameters

Content of multiple messages, separated by a newline char ("\n").

New content of messages (number can be different), an empty string discards all messages in the batch.

irc_cap_sync_req

4.0.0

Server name + "," + supported capabilities on server (separated by spaces)

Capabilities to request (separated by spaces).

New content of capabilities to request (separated by spaces).

irc_in_xxx ⁽¹⁾

Server name

Content of message received from IRC server (before charset decoding).
Warning: the string may contain invalid UTF-8 data; use only for raw operations on a message. Modifier irc_in2_xxx is recommended instead.

New content of message.

irc_in2_xxx ⁽¹⁾

0.3.5

Server name

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

New content of message.

irc_out1_xxx ⁽¹⁾

0.3.7

Server name

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

New content of message.

irc_out_xxx ⁽¹⁾

Server name

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

New content of message.

relay_client_irc_in

4.0.0

String with relay client pointer (eg: "0x1234abcd")

Content of message received from relay IRC client.

New content of message.

relay_client_irc_out1

4.0.0

String with relay client pointer (eg: "0x1234abcd")

Content of message about to be sent to relay IRC client before automatic split (to fit in 512 bytes by default).

New content of message.

relay_client_irc_out

4.0.0

String with relay client pointer (eg: "0x1234abcd")

Content of message about to be sent to relay IRC client after automatic split (to fit in 512 bytes by default).

New content of message.

bar_condition_yyy ⁽²⁾

String with window pointer (eg: "0x1234abcd")

Empty string.

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

history_add

0.3.2

String with buffer pointer (eg: "0x1234abcd")

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

String added to command history.

input_text_content

String with buffer pointer (eg: "0x1234abcd")

Content of command line.

New content of command line.

input_text_display

String with buffer pointer (eg: "0x1234abcd")

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 (eg: "0x1234abcd")

Content of command line, with cursor tag.

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

input_text_for_buffer

0.3.7

String with buffer pointer (eg: "0x1234abcd")

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

New content of command line sent to buffer.

weechat_print

buffer pointer (eg: "0x1234abcd") + ";" + tags ⁽³⁾

Message printed.

New message printed.
For more information on the hooks called when a line is printed, see hook_line.

Note	⁽¹⁾ xxx is IRC command name. ⁽²⁾ yyy is bar name. ⁽³⁾ With WeeChat ≤ 2.8, the format was: plugin + ";" + buffer_name + ";" + tags.

C example:

char *
my_modifier_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_modifier(modifier: str, callback: str, callback_data: str) -> str: ...

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

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

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

List of modifiers defined by WeeChat and plugins that can be used:

Modifier Min WeeChat 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

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

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

0.4.1

Server name

Message displayed after /msg sent to nickserv.

Message with hidden password.

irc_tag_escape_value

3.3

Any string.

String with IRC tag value escaped, see this page ^↗.

irc_tag_unescape_value

3.3

Any string.

String with IRC tag value unescaped, see this page ^↗.

color_decode

4.3.0

Replacement string for colors removed

Any string.

String with WeeChat colors converted to a replacement string (colors stripped if the replacement string is empty).

color_decode_ansi

1.0

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

Any string.

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

color_encode_ansi

2.7

Any string.

String with WeeChat colors converted to ANSI colors.

eval_path_home

2.7

Optional: directory=xxx where xxx can be: config, data, cache, runtime

Any string.

Evaluated path, result of the function string_eval_path_home.

C example:

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

Script (Python):

# prototype
def hook_modifier_exec(modifier: str, modifier_data: str, string: str) -> str: ...

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

hook_info

Updated in 1.5, 2.5.

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,
                                  char *(*callback)(const void *pointer,
                                                    void *data,
                                                    const char *info_name,
                                                    const char *arguments),
                                  const void *callback_pointer,
                                  void *callback_data);

Arguments:

info_name: name of info (a priority is allowed before the info name, 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:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

Note	With WeeChat ≥ 2.5, the callback returns an allocated string (with WeeChat ≤ 2.4, it was a pointer to a static string).

C example:

char *
my_info_cb (const void *pointer, void *data, const char *info_name,
            const char *arguments)
{
    /* ... */
    return strdup ("some_info");
}

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

Script (Python):

# prototype
def hook_info(info_name: str, description: str, args_description: str,
              callback: str, callback_data: str) -> str: ...

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

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

hook_info_hashtable

WeeChat ≥ 0.3.4, updated in 1.5.

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)(const void *pointer,
                                                                            void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            const void *callback_pointer,
                                            void *callback_data);

Arguments:

info_name: name of info (a priority is allowed before the info name, 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:
- const void *pointer: pointer
- void *data: pointer
- const char *info_name: name of info
- struct t_hashtable *hashtable: hashtable, depending on info
- return value: hashtable asked
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_hashtable *
my_info_hashtable_cb (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_info_hashtable(info_name: str, description: str, args_description: str,
                        output_description: str, callback: str, callback_data: str) -> str: ...

# example
def my_info_hashtable_cb(data: str, info_name: str, hashtable: Dict[str, str]) -> Dict[str, str]:
    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", "")

hook_infolist

Updated in 1.5.

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)(const void *pointer,
                                                                     void *data,
                                                                     const char *infolist_name,
                                                                     void *obj_pointer,
                                                                     const char *arguments),
                                      const void *callback_pointer,
                                      void *callback_data);

Arguments:

infolist_name: name of infolist (a priority is allowed before the infolist name, 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:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_infolist *
my_infolist_cb (const void *pointer, void *data, const char *infolist_name,
                void *obj_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, NULL);

Script (Python):

# prototype
def hook_infolist(infolist_name: str, description: str, pointer_description: str,
                  args_description: str, callback: str, callback_data: str) -> str: ...

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

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

hook_hdata

Updated in 1.5.

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)(const void *pointer,
                                                               void *data,
                                                               const char *hdata_name),
                                   const void *callback_pointer,
                                   void *callback_data);

Arguments:

hdata_name: name of hdata (a priority is allowed before the hdata name, see note about priority)
description: description
callback: function called when hdata is asked, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- const char *hdata_name: name of hdata
- return value: hdata asked
callback_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_hdata *
my_hdata_cb (const void *pointer, 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, NULL);

Note	This function is not available in scripting API.

hook_focus

Updated in 1.5, 4.0.0, 4.1.0.

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)(const void *pointer,
                                                                   void *data,
                                                                   struct t_hashtable *info),
                                   const void *callback_pointer,
                                   void *callback_data);

Arguments:

area: "chat" for chat area, or name of bar item (a priority is allowed before the area, see note about priority)
callback: function called when focus is made, arguments and return value:
- const void *pointer: pointer
- 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_pointer: pointer given to callback when it is called by WeeChat
callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

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 ⁽¹⁾

Description

Value examples

Value if N/A

Column on screen.

"0" … "n"

Line on screen.

"0" … "n"

_key

Key or mouse event.

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

_window

Pointer to window.

"0x1234abcd"

_window_number

Number of window .

"1" … "n"

"*"

_buffer

Pointer to buffer.

"0x1234abcd"

_buffer_number

Number of buffer.

"1" … "n"

"-1"

_buffer_plugin

Plugin name of buffer.

"core", "irc", …

_buffer_name

Name of buffer.

"weechat", "libera.#weechat", …

_buffer_full_name

Full name of buffer.

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

_buffer_localvar_XXX ⁽²⁾

Local variables of buffer.

any value

not set

_chat

Chat area indicator.

"0" or "1"

"0"

_chat_line

Pointer to line (WeeChat ≥ 1.2).

"0x1234abcd"

_chat_line_x

Column in line ⁽³⁾.

"0" … "n"

"-1"

_chat_line_y

Line number ⁽³⁾.

"0" … "n"

"-1"

_chat_line_date

Line date/time.

"1313237175"

"0"

_chat_line_date_usec

Microseconds of line date/time.

"123456"

"0"

_chat_line_date_printed

Line date/time ⁽⁴⁾.

"1313237175"

"0"

_chat_line_date_usec_printed

Microseconds of line printed date/time ⁽⁴⁾.

"123456"

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

Line at (x, y) (WeeChat ≥ 4.0.0).

"Hello world!"

_chat_focused_line_bol

Text from beginning of line to (x-1, y) (WeeChat ≥ 4.1.0).

"Hello"

_chat_focused_line_eol

Text from (x, y) to end of line (WeeChat ≥ 4.1.0).

"llo world!"

_chat_word

Word at (x,y).

"Hello"

_chat_bol

Text from beginning of message to (x-1, y).

"He"

_chat_eol

Text from (x, y) to the end of message.

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

_bar_window

Pointer to bar window (WeeChat ≥ 2.9).

"0x1234abcd"

Note

⁽¹⁾ 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).
⁽²⁾ XXX is name of local variable in buffer.
⁽³⁾ It is set only for buffers with free content.
⁽⁴⁾ It is date when WeeChat adds line in buffer (greater or equal to "_chat_line_date").

Extra info for bar item "buffer_nicklist":

Plugin ⁽¹⁾

Key

Description

irc

irc_nick

Pointer to IRC nick (WeeChat ≥ 3.0).

irc

irc_host

Host for nick (if known).

weechat

nick

Nick name.

weechat

prefix

Prefix for nick.

weechat

group

Group name.

Note	⁽¹⁾ 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 (const void *pointer, 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, NULL);

Script (Python):

# prototype
def hook_focus(area: str, callback: str, callback_data: str) -> str: ...

# example
def my_focus_nicklist_cb(data: str, info: Dict[str, str]) -> Dict[str, str]:
    # build dict
    # ...
    return my_dict

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

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 Min WeeChat 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

0.4.3

process, process_hashtable

any string

Send data on standard input (stdin) of child process.

stdin_close

0.4.3

process, process_hashtable

(not used)

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

signal

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, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");

Script (Python):

# prototype
def hook_set(hook: str, property: str, value: str) -> int: ...

# example
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    # ...
    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

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
def unhook(hook: str) -> int: ...

# example
weechat.unhook(my_hook)

unhook_all

Updated in 1.5.

Unhook everything that has been hooked by current plugin.

Prototype:

void weechat_unhook_all (const char *subplugin);

Arguments:

subplugin: if not NULL, unhook only hooks with this "subplugin" set (this argument is not available in scripting API)

C example:

weechat_unhook_all (NULL);

Script (Python):

# prototype
def unhook_all() -> int: ...

# example
weechat.unhook_all()

3.15. Buffers

Functions to create/query/close buffers.

buffer_new

Updated in 1.5.

Open a new buffer.

Note	If you want to immediately set buffer properties (buffer type, local variables, key bindings, etc.), then better use the function buffer_new_props which sets these properties during the buffer creation, before sending signal buffer_opened.

Prototype:

struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         const void *input_callback_pointer,
                                         void *input_callback_data,
                                         int (*close_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer),
                                         const void *close_callback_pointer,
                                         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:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- const char *input_data: input data
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
input_callback_pointer: pointer given to callback when it is called by WeeChat
input_callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed
close_callback: function called when buffer is closed, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
close_callback_pointer: pointer given to callback when it is called by WeeChat
close_callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed

Return value:

pointer to new buffer, NULL if error occurred

C example:

int
my_input_cb (const void *pointer, 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 (const void *pointer, 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, NULL,
                                                     &my_close_cb, NULL, NULL);

Script (Python):

# prototype
def buffer_new(name: str, input_callback: str, input_callback_data: str,
               close_callback: str, close_callback_data: str) -> str: ...

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

def my_close_cb(data: str, buffer: str) -> int:
    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", "")

buffer_new_props

WeeChat ≥ 3.5.

Open a new buffer and apply properties.

Prototype:

struct t_gui_buffer *weechat_buffer_new_props (const char *name,
                                               struct t_hashtable *properties,
                                               int (*input_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer,
                                                                     const char *input_data),
                                               const void *input_callback_pointer,
                                               void *input_callback_data,
                                               int (*close_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer),
                                               const void *close_callback_pointer,
                                               void *close_callback_data);

Arguments:

name: name of buffer (must be unique for plugin)
properties: properties to apply (see function buffer_set for the allowed properties)
input_callback: function called when input text is entered on buffer, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- const char *input_data: input data
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
input_callback_pointer: pointer given to callback when it is called by WeeChat
input_callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed
close_callback: function called when buffer is closed, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
close_callback_pointer: pointer given to callback when it is called by WeeChat
close_callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed

Return value:

pointer to new buffer, NULL if error occurred

C example:

int
my_input_cb (const void *pointer, 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 (const void *pointer, 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_hashtable *properties = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);
/* buffer with free content */
weechat_hashtable_set (properties, "type", "free");
/* no logging on this buffer */
weechat_hashtable_set (properties, "localvar_set_no_log", "1");
/* bind key alt-c on this buffer */
weechat_hashtable_set (properties, "key_bind_meta-c", "/my_command");

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

Script (Python):

# prototype
def buffer_new_props(name: str, properties: Dict[str, str],
                     input_callback: str, input_callback_data: str,
                     close_callback: str, close_callback_data: str) -> str: ...

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

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

properties = {
    "type": "free",                    # buffer with free content
    "localvar_set_no_log": "1",        # no logging on this buffer
    "key_bind_meta-c": "/my_command",  # bind key alt-c on this buffer
}
buffer = weechat.buffer_new_props("my_buffer", properties, "my_input_cb", "", "my_close_cb", "")

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
def current_buffer() -> str: ...

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

buffer_search

Updated in 1.0, 4.3.0.

Search a buffer by plugin/name, full name or unique identifier (id).

Prototype:

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

Arguments:

plugin: name of plugin, following special values are allowed:
- ==: the name used is the buffer full name (for example: irc.libera.#weechat instead of libera.#weechat) (WeeChat ≥ 1.0)
- ==id: the name used is the buffer unique identifier (id) (WeeChat ≥ 4.3.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", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.libera.#test");  /* WeeChat ≥ 1.0 */
struct t_gui_buffer *buffer3 = weechat_buffer_search ("==id", "1709797810942688");  /* WeeChat ≥ 4.3.0 */

Script (Python):

# prototype
def buffer_search(plugin: str, name: str) -> str: ...

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

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
def buffer_search_main() -> str: ...

# example
buffer = weechat.buffer_search_main()

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
def buffer_clear(buffer: str) -> int: ...

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

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
def buffer_close(buffer: str) -> int: ...

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

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
def buffer_merge(buffer: str, target_buffer: str) -> int: ...

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

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
def buffer_unmerge(buffer: str, number: int) -> int: ...

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

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:
- opening: 1 if buffer is opening, otherwise 0 (WeeChat ≥ 4.2.0)
- number: number of buffer (starts to 1)
- layout_number: number of buffer saved in layout
- layout_number_merge_order: order in merge for layout
- 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)
- closing: 1 if buffer is closing, 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
- next_line_id: next line id in buffer (WeeChat ≥ 3.8)
- 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_visible_count: number of nicks/groups displayed
- nicklist_groups_count: number of groups in nicklist
- nicklist_groups_visible_count: number of groups displayed
- nicklist_nicks_count: number of nicks in nicklist
- nicklist_nicks_visible_count: number of nicks displayed
- input: 1 if input is enabled, otherwise 0
- input_get_any_user_data: 1 if any user data, including commands, are sent to input callback, otherwise 0
- input_get_unknown_commands: 1 if unknown commands are sent to input callback, otherwise 0
- input_get_empty: 1 if empty input is sent to input callback, otherwise 0
- input_multiline: 1 if multiple lines are sent as one message 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: search in buffer lines
  - 2: search in commands history
- text_search_direction: direction for search:
  - 0: backward search (direction: oldest messages/commands)
  - 1: forward search (direction: newest messages/commands)
- text_search_exact: 1 if text search is case-sensitive
- text_search_regex: 1 if searching with a regular expression
- text_search_where:
  - 0: no search at this moment
  - 1: search in message
  - 2: search in prefix
  - 3: search in prefix and message
- text_search_history:
  - 0: no search at this moment
  - 1: search in buffer local history
  - 2: search in global history
- 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
def buffer_get_integer(buffer: str, property: str) -> int: ...

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

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:
- id: unique identifier (WeeChat ≥ 4.3.0)
- 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)
- old_full_name: old full name of buffer ("plugin.name"), set before the buffer is renamed (WeeChat ≥ 2.8)
- 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)
- type: type of buffer: "formatted" or "free" (WeeChat ≥ 4.2.0)
- title: title of buffer
- modes: modes (WeeChat ≥ 4.3.0)
- nicklist_last_id_assigned: last unique identifier used in this buffer for a group or nick (WeeChat ≥ 4.3.0)
- input_prompt: input prompt (WeeChat ≥ 4.3.0)
- input: input text
- text_search_input: input saved before text search
- highlight_words: list of words to highlight
- highlight_disable_regex: POSIX extended regular expression for disabling 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)

Return value:

string value of property

C example:

weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));

Script (Python):

# prototype
def buffer_get_string(buffer: str, property: str) -> str: ...

# example
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))

buffer_get_pointer

Return pointer value of a buffer property.

Prototype:

void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);

Arguments:

buffer: buffer pointer
property: property name:
- plugin: pointer to plugin which created this buffer (NULL for WeeChat main buffer)
- text_search_regex_compiled: compiled regular expression
- text_search_ptr_history: history found
- highlight_disable_regex_compiled: regular expression highlight_disable_regex compiled
- highlight_regex_compiled: regular expression highlight_regex compiled

Return value:

pointer value of property

C example:

weechat_printf (NULL, "plugin pointer of my buffer: %p",
                weechat_buffer_get_pointer (my_buffer, "plugin"));

Script (Python):

# prototype
def buffer_get_pointer(buffer: str, property: str) -> str: ...

# example
weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))

buffer_set

Set string value of a buffer property.

Prototype:

void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);

Arguments:

buffer: buffer pointer
property: property name (see table below)
value: new value for property

Properties:

Name Min WeeChat Value Description

hotlist

"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1"

"+": enable hotlist (global setting, buffer pointer is not used)
"-": disable hotlist (global setting, buffer pointer is not used)
priority: add buffer to hotlist with this priority (conditions defined in option weechat.look.hotlist_add_conditions are NOT checked)
"-1": remove buffer from hotlist (WeeChat ≥ 1.0).

hotlist_conditions

4.5.0

WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT

priority: add buffer to hotlist with this priority (conditions defined in option weechat.look.hotlist_add_conditions are checked).

completion_freeze

"0" or "1"

"0": no freeze of completion (default value) (global setting, buffer pointer is not used)
"1": do not stop completion when command line is updated (global setting, buffer pointer is not used).

unread

empty string, "0", "+N", "-N" or "N" (N is integer)

empty string: set unread marker after last line of buffer
"0": remove unread marker from buffer
"N": move the unread marker N lines from the end towards the first line of buffer
"-N": move the unread marker N lines towards the first line of buffer
"+N": move the unread marker N lines towards the last line of buffer.

display

"1" or "auto"

"1": switch to this buffer in current window
"auto": switch to this buffer in current window, read marker is not reset.

hidden

1.0

"0" or "1"

"0": unhide the buffer
"1": hide the buffer.

number

Move buffer to this number.

name

any string

Set new name for buffer.

short_name

any string

Set new short name for buffer.

type

"formatted" or "free"

Set type for buffer: "formatted" (for printing chat messages), or "free" (for free content); when the value is "free", the property clear is forced to "0" (WeeChat ≥ 1.0).

notify

"0", "1", "2", "3"

Set notify level for buffer: "0" = never add to hotlist, "1" = add for highlights only, "2" = add for highlights and messages, "3" = add for all messages.

print_hooks_enabled

"0" or "1"

"0" to disable print hooks, "1" to enable them (default for a new buffer).

day_change

0.4.3

"0" or "1"

"0" to hide messages for the day change, "1" to see them (default for a new buffer).

clear

1.0

"0" or "1"

"0" to prevent user from clearing buffer with the command /buffer clear, "1" to let user clear the buffer (default for a new buffer) (note: even when it is set to "0", the buffer can still be cleared with the function buffer_clear).

filter

1.0

"0" or "1"

"0": disable filters on buffer
"1": enable filters on buffer.

title

any string

Set new title for buffer.

modes

4.3.0

any string

Set new modes for buffer.

time_for_each_line

"0" or "1"

"0" to hide time for all lines in buffer, "1" to see time for all lines (default for a new buffer).

nicklist

"0" or "1"

"0" to remove nicklist for buffer, "1" to add nicklist for buffer.

nicklist_case_sensitive

"0" or "1"

"0" to have case-insensitive nicklist, "1" to have case-sensitive nicklist.

nicklist_display_groups

"0" or "1"

"0" to hide nicklist groups, "1" to display nicklist groups.

highlight_words

"-" or comma separated list of words

"-" is a special value to disable any highlight on this buffer, or comma separated list of words to highlight in this buffer, for example: "abc,def,ghi".

highlight_words_add

comma separated list of words

Comma separated list of words to highlight in this buffer, these words are added to existing highlighted words in buffer.

highlight_words_del

comma separated list of words

Comma separated list of words to remove from highlighted words on buffer.

highlight_disable_regex

any string

POSIX extended regular expression for disabling highlight.

highlight_regex

any string

POSIX extended regular expression for highlight.

highlight_tags_restrict

comma separated list of tags

Restrict highlights to messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action").

highlight_tags

comma separated list of tags

Force highlight on messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action").

hotlist_max_level_nicks

comma separated list of "nick:level"

Comma separated list of nicks with max level for hotlist on this buffer (level can be: -1: never in hotlist, 0: low, 1: message, 2: private, 3: highlight), for example: "joe:2,mike:-1,robert:-1" (joe will never produce highlight on buffer, mike and robert will never change hotlist).

hotlist_max_level_nicks_add

comma separated list of "nick:level"

Comma separated list of nicks with level for hotlist, these nicks are added to existing nicks in buffer.

hotlist_max_level_nicks_del

comma separated list of nicks

Comma separated list of nicks to remove from hotlist max levels.

key_bind_xxx

any string

Bind a new key xxx, specific to this buffer, value is command to execute for this key.

key_unbind_xxx

Unbind key xxx for this buffer.

input_prompt

4.3.0

any string

Set new value for input prompt.

input

any string

Set new value for buffer input.

input_pos

position

Set cursor position in buffer input.

input_get_any_user_data

4.3.0

"0" or "1"

"0" to get only user messages (default behavior), "1" to get everything, including commands.

input_get_unknown_commands

"0" or "1"

"0" to disable unknown commands on this buffer (default behavior), "1" to get unknown commands, for example if user type "/unknowncmd", buffer will receive it (no error about unknown command).

input_get_empty

"0" or "1"

"0" to disable empty input on this buffer (default behavior), "1" to get empty input.

input_multiline

"0" or "1"

"0" to send each line separately to this buffer (default behavior), "1" to send multiple lines as a single message.

localvar_set_xxx

any string

Set new value for local variable xxx (variable is created if it does not exist).

localvar_del_xxx

Remove local variable xxx.

C example:

/* disable hotlist (for all buffers) */
weechat_buffer_set (NULL, "hotlist", "-");

/* enable again hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* change buffer name */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* add new local variable "toto" with value "abc" */
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

/* remove local variable "toto" */
weechat_buffer_set (my_buffer, "localvar_del_toto", "");

Script (Python):

# prototype
def buffer_set(buffer: str, property: str, value: str) -> int: ...

# examples

# disable hotlist (for all buffers)
weechat.buffer_set("", "hotlist", "-")

# enable again hotlist
weechat.buffer_set("", "hotlist", "+")

# change buffer name
weechat.buffer_set(my_buffer, "name", "my_new_name")

# add new local variable "toto" with value "abc"
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

# remove local variable "toto"
weechat.buffer_set(my_buffer, "localvar_del_toto", "")

buffer_set_pointer

Set pointer value of a buffer property.

Prototype:

void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);

Arguments:

buffer: buffer pointer
property: property name:
- close_callback: set close callback function
- close_callback_data: set close callback data
- input_callback: set input callback function
- input_callback_data: set input callback data
- nickcmp_callback: set nick comparison callback function (this callback is called when searching nick in nicklist) (WeeChat ≥ 0.3.9)
- nickcmp_callback_data: set nick comparison callback data (WeeChat ≥ 0.3.9)
pointer: new pointer value for property

Prototypes for callbacks:

int close_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer);

int input_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (const void *pointer, void *data,
                      struct t_gui_buffer *buffer,
                      const char *nick1, const char *nick2);

C example:

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);

Note	This function is not available in scripting API.

buffer_string_replace_local_var

Replace local variables in a string by their values, using buffer local variables.

Prototype:

char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);

Arguments:

buffer: buffer pointer
string: string with text and local variables using format "$var"

Return value:

string with values of local variables

C example:

weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contains "test with abc" */

Script (Python):

# prototype
def buffer_string_replace_local_var(buffer: str, string: str) -> str: ...

# example
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"

buffer_match_list

WeeChat ≥ 0.3.5, updated in 4.0.0.

Check if buffer matches a list of buffers.

Prototype:

int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);

Arguments:

buffer: buffer pointer
string: comma-separated list of buffers:
- * means all buffers
- name beginning with ! is excluded
- wildcard * is allowed in name

Note	Since version 4.0.0, comparison of buffer names is case-sensitive.

Return value:

1 if buffer matches list of buffers, 0 otherwise

C example:

struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "libera.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.libera.*"));         /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
}

Script (Python):

# prototype
def buffer_match_list(buffer: str, string: str) -> int: ...

# example
buffer = weechat.buffer_search("irc", "libera.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.libera.*"))         # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0

3.16. Buffer lines

Functions for buffer lines.

line_search_by_id

WeeChat ≥ 4.4.0.

Search line in buffer by identifier.

Prototype:

struct t_gui_line *weechat_line_search_by_id (struct t_gui_buffer *buffer, int id);

Return value:

pointer to line found, NULL if not found

C example:

struct t_gui_line *line = weechat_line_search_by_id (buffer, 123);

Script (Python):

# prototype
def line_search_by_id(buffer: str, line_id: int) -> str: ...

# example
line = weechat.line_search_by_id(buffer, 123)

3.17. Windows

Functions to query windows.

current_window

Return pointer to current window.

Prototype:

struct t_gui_window *weechat_current_window ();

Return value:

pointer to current window

C example:

struct t_gui_window *current_window = weechat_current_window ();

Script (Python):

# prototype
def current_window() -> str: ...

# example
current_window = weechat.current_window()

window_search_with_buffer

WeeChat ≥ 0.3.5.

Return pointer to window displaying buffer.

Prototype:

struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

Return value:

pointer to window displaying buffer (NULL if no window is displaying buffer)

C example:

weechat_printf (NULL,
                "window displaying core buffer: %p",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));

Script (Python):

# prototype
def window_search_with_buffer(buffer: str) -> str: ...

# example
weechat.prnt("", "window displaying core buffer: %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))

window_get_integer

Return integer value of a window property.

Prototype:

int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);

Arguments:

window: window pointer
property: property name:
- number: number of window (starts to 1)
- win_x: X position of window in terminal (first column is 0)
- win_y: Y position of window in terminal (first line is 0)
- win_width: width of window, in chars
- win_height: height of window, in chars
- win_width_pct: percentage size, compared to parent window (for example 50 means half size)
- win_height_pct: percentage size, compared to parent window (for example 50 means half size)
- win_chat_x: X position of chat window in terminal (first column is 0)
- win_chat_y: Y position of chat window in terminal (first line is 0)
- win_chat_width: width of chat window, in chars
- win_chat_height: height of chat window, in chars
- first_line_displayed: 1 if first line of buffer is displayed on screen, otherwise 0
- scrolling: 1 if scroll is active on window (last line not displayed)
- lines_after: number of lines not displayed after last one displayed (when scrolling)

Return value:

integer value of property

C example:

weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));

Script (Python):

# prototype
def window_get_integer(window: str, property: str) -> int: ...

# example
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))

window_get_string

Return string value of a window property.

Note	This function is not used today, it is reserved for a future version.

Prototype:

const char *weechat_window_get_string (struct t_gui_window *window,
                                       const char *property);

Arguments:

window: window pointer
property: property name

Return value:

string value of property

Script (Python):

# prototype
def window_get_string(window: str, property: str) -> str: ...

window_get_pointer

Return pointer value of a window property.

Prototype:

void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);

Arguments:

window: window pointer
property: property name:
- current: current window pointer
- buffer: pointer to buffer displayed by window

Return value:

pointer value of property

C example:

weechat_printf (NULL,
                "buffer displayed in current window: %p",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));

Script (Python):

# prototype
def window_get_pointer(window: str, property: str) -> str: ...

# example
weechat.prnt("", "buffer displayed in current window: %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))

window_set_title

Set title for terminal.

Prototype:

void weechat_window_set_title (const char *title);

Arguments:

title: new title for terminal (NULL to reset title); string is evaluated, so variables like ${info:version} can be used (see string_eval_expression)

C example:

weechat_window_set_title ("new title here");

Script (Python):

# prototype
def window_set_title(title: str) -> int: ...

# example
weechat.window_set_title("new title here")

3.18. Nicklist

Functions for buffer nicklist.

nicklist_add_group

Add a group in a nicklist.

Prototype:

struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);

Arguments:

buffer: buffer pointer
parent_group: pointer to parent of group, NULL if group has no parent (nicklist root)
name: group name
color: color option name:
- WeeChat option name, for example weechat.color.nicklist_group
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
visible:
- 1: group and sub-groups/nicks are visible
- 0: group and sub-groups/nicks are hidden

Note	The group name can begin with one or more digits, followed by pipe, and then group name. When such string is found at beginning, it’s used to sort groups in nicklist. For example groups "1\|test" and "2\|abc" will be displayed in that order: first "test" then "abc".

Return value:

pointer to new group, NULL if an error occurred

C example:

struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);

Script (Python):

# prototype
def nicklist_add_group(buffer: str, parent_group: str, name: str, color: str, visible: int) -> str: ...

# example
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)

nicklist_search_group

Updated in 4.3.0.

Search a group in a nicklist by name or unique identifier (id).

Prototype:

struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);

Arguments:

buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: group name to search; with WeeChat ≥ 4.3.0, a unique identifier can be given with the format: ==id:xxx (where xxx is the identifier)

Return value:

pointer to group found, NULL if not found

C example:

struct t_gui_nick_group *ptr_group1 = weechat_nicklist_search_group (my_buffer,
                                                                     NULL, "test_group");
struct t_gui_nick_group *ptr_group2 = weechat_nicklist_search_group (my_buffer,
                                                                     NULL, "==id:1714382231198764");

Script (Python):

# prototype
def nicklist_search_group(buffer: str, from_group: str, name: str) -> str: ...

# examples
group1 = weechat.nicklist_search_group(my_buffer, "", "test_group")
group2 = weechat.nicklist_search_group(my_buffer, "", "==id:1714382231198764")

nicklist_add_nick

Add a nick in a group.

Prototype:

struct t_gui_nick *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                              struct t_gui_nick_group *group,
                                              const char *name,
                                              const char *color,
                                              const char *prefix,
                                              const char *prefix_color,
                                              int visible);

Arguments:

buffer: buffer pointer
group: group pointer
name: nick name
color: color option name:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
prefix: prefix displayed before nick
prefix_color: color option name:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
visible:
- 1: nick is visible
- 0: nick is hidden

Return value:

pointer to new nick, NULL if an error occurred

C example:

struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);

Script (Python):

# prototype
def nicklist_add_nick(buffer: str, group: str, name: str, color: str, prefix: str, prefix_color: str, visible: int) -> str: ...

# example
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)

nicklist_search_nick

Updated in 4.3.0.

Search a nick in a nicklist by name or unique identifier (id).

Prototype:

struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);

Arguments:

buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: nick name to search; with WeeChat ≥ 4.3.0, a unique identifier can be given with the format: ==id:xxx (where xxx is the identifier)

Return value:

pointer to nick found, NULL if not found

C example:

struct t_gui_nick *ptr_nick1 = weechat_nicklist_search_nick (my_buffer,
                                                             NULL, "test_nick");
struct t_gui_nick *ptr_nick2 = weechat_nicklist_search_nick (my_buffer,
                                                             NULL, "==id:1714382252187496");

Script (Python):

# prototype
def nicklist_search_nick(buffer: str, from_group: str, name: str) -> str: ...

# examples
nick1 = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
nick2 = weechat.nicklist_search_nick(my_buffer, "", "==id:1714382252187496")

nicklist_remove_group

Remove a group from a nicklist.

Prototype:

void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);

Arguments:

buffer: buffer pointer
group: group pointer to remove (all sub-groups/nicks will be removed too)

C example:

weechat_nicklist_remove_group (my_buffer, my_group);

Script (Python):

# prototype
def nicklist_remove_group(buffer: str, group: str) -> int: ...

# example
weechat.nicklist_remove_group(my_buffer, my_group)

nicklist_remove_nick

Remove a nick from a nicklist.

Prototype:

void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);

Arguments:

buffer: buffer pointer
nick: nick pointer to remove

C example:

weechat_nicklist_remove_nick (my_buffer, my_nick);

Script (Python):

# prototype
def nicklist_remove_nick(buffer: str, nick: str) -> int: ...

# example
weechat.nicklist_remove_nick(my_buffer, my_nick)

nicklist_remove_all

Remove all groups/nicks from a nicklist.

Prototype:

void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

C example:

weechat_nicklist_remove_all (my_buffer);

Script (Python):

# prototype
def nicklist_remove_all(buffer: str) -> int: ...

# example
weechat.nicklist_remove_all(my_buffer)

nicklist_get_next_item

WeeChat ≥ 0.3.7.

Get next group or nick from nicklist (mainly used to display nicklist).

Prototype:

void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);

Arguments:

buffer: buffer pointer
group: pointer on pointer to group
nick: pointer on pointer to nick

C example:

struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* nick */
        /* ... */
    }
    else
    {
        /* group */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}

Note	This function is not available in scripting API.

nicklist_group_get_integer

WeeChat ≥ 0.3.4.

Return integer value of a group property.

Prototype:

int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- visible: 1 if group is visible, otherwise 0
- level: group level (root is 0)

Return value:

integer value of property

C example:

int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");

Script (Python):

# prototype
def nicklist_group_get_integer(buffer: str, group: str, property: str) -> int: ...

# example
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")

nicklist_group_get_string

WeeChat ≥ 0.3.4.

Return string value of a group property.

Prototype:

const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- id: unique identifier (WeeChat ≥ 4.3.0)
- name: name of group
- color: group color in nicklist

Return value:

string value of property

C example:

const char *color = weechat_nicklist_group_get_string (buffer, group, "color");

Script (Python):

# prototype
def nicklist_group_get_string(buffer: str, group: str, property: str) -> str: ...

# example
color = weechat.nicklist_group_get_string(buffer, group, "color")

nicklist_group_get_pointer

WeeChat ≥ 0.3.4.

Return pointer value of a group property.

Prototype:

void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- parent: pointer to parent group

Return value:

pointer value of property

C example:

struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");

Script (Python):

# prototype
def nicklist_group_get_pointer(buffer: str, group: str, property: str) -> str: ...

# example
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")

nicklist_group_set

WeeChat ≥ 0.3.4, updated in 4.3.0.

Set string value of a group property.

Prototype:

void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name (see table below)
value: new value for property

Properties:

Name

Min WeeChat

Value

Description

4.3.0

long long integer ≥ 0

New id for the group (it must be unique in the buffer).
Note: it is not recommended to change this identifier.

color

WeeChat color option name

See argument "color" of function nicklist_add_group.

visible

"0", "1"

"0" = hidden group, "1" = visible group.

C examples:

/* change group color to "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* change group color to yellow */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* hide group in nicklist */
weechat_nicklist_group_set (buffer, group, "visible", "0");

Script (Python):

# prototype
def nicklist_group_set(buffer: str, group: str, property: str, value: str) -> int: ...

# examples

# change group color to "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# change group color to yellow
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# hide group in nicklist
weechat.nicklist_group_set(buffer, group, "visible", "0")

nicklist_nick_get_integer

WeeChat ≥ 0.3.4.

Return integer value of a nick property.

Prototype:

int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- visible: 1 if nick is visible, otherwise 0

Return value:

integer value of property

C example:

int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");

Script (Python):

# prototype
def nicklist_nick_get_integer(buffer: str, nick: str, property: str) -> int: ...

# example
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")

nicklist_nick_get_string

WeeChat ≥ 0.3.4.

Return string value of a nick property.

Prototype:

const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- id: unique identifier (WeeChat ≥ 4.3.0)
- name: name of nick
- color: nick color in nicklist
- prefix: prefix of nick
- prefix_color: prefix color in nicklist

Return value:

string value of property

C example:

const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");

Script (Python):

# prototype
def nicklist_nick_get_string(buffer: str, nick: str, property: str) -> str: ...

# example
color = weechat.nicklist_nick_get_string(buffer, nick, "color")

nicklist_nick_get_pointer

WeeChat ≥ 0.3.4.

Return pointer value of a nick property.

Prototype:

void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- group: pointer to group containing this nick

Return value:

pointer value of property

C example:

struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");

Script (Python):

# prototype
def nicklist_nick_get_pointer(buffer: str, nick: str, property: str) -> str: ...

# example
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")

nicklist_nick_set

WeeChat ≥ 0.3.4, updated in 4.3.0.

Set string value of a nick property.

Prototype:

void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name (see table below)
value: new value for property

Properties:

Name

Min WeeChat

Value

Description

4.3.0

long long integer ≥ 0

New id for the nick (it must be unique in the buffer).
Note: it is not recommended to change this identifier.

color

WeeChat color option name

See argument "color" of function nicklist_add_nick.

prefix

any string

Prefix of nick.

prefix_color

WeeChat color option name

See argument "prefix_color" of function nicklist_add_nick.

visible

"0", "1"

"0" = hidden nick, "1" = visible nick.

C examples:

/* change nick color to cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* change prefix to "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* change prefix color to yellow */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* hide nick in nicklist */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");

Script (Python):

# prototype
def nicklist_nick_set(buffer: str, nick: str, property: str, value: str) -> int: ...

# examples

# change nick color to cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# change prefix to "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# change prefix color to yellow
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# hide nick in nicklist
weechat.nicklist_nick_set(buffer, nick, "visible", "0")

3.19. Bars

Functions for bars.

bar_item_search

Search a bar item.

Prototype:

struct t_gui_bar_item *weechat_bar_item_search (const char *name);

Arguments:

name: bar item name

Return value:

pointer to bar item found, NULL if bar item was not found

C example:

struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");

Script (Python):

# prototype
def bar_item_search(name: str) -> str: ...

# example
bar_item = weechat.bar_item_search("myitem")

bar_item_new

Updated in 0.4.2, 1.5.

Create a new bar item.

Prototype:

struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             const void *build_callback_pointer,
                                             void *build_callback_data);

Arguments:

name: bar item name
build_callback: function called when bar item is built, arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_gui_bar_item *item: item pointer
- struct t_gui_window *window: window pointer (NULL when called for a root bar)
- struct t_gui_buffer *buffer: buffer displayed in window (if window is NULL, then it is current buffer) or buffer given in bar item with syntax: "@buffer:item" (WeeChat ≥ 0.4.2)
- struct t_hashtable *extra_info: always NULL (argument is reserved for a future version) (WeeChat ≥ 0.4.2)
- return value: content of bar item
build_callback_pointer: pointer given to build callback, when it is called by WeeChat
build_callback_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the bar item is removed

Return value:

pointer to new bar item, NULL if an error occurred

C example:

char *
my_build_callback (const void *pointer, void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL, NULL);

Script (Python):

Important

For compatibility with versions ≤ 0.4.1, the default callback has only 3 arguments: data, item and window (no buffer and extra_info).
To use a callback with all arguments, you must add "(extra)" before the name, see example below (supported only in WeeChat ≥ 0.4.2).

# prototype
def bar_item_new(name: str, build_callback: str, build_callback_data: str) -> str: ...

# example (callback without "buffer" and "extra_info")
def my_build_callback(data: str, item: str, window: str) -> str:
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# example (callback with all arguments, for WeeChat ≥ 0.4.2)
def my_build_callback2(data: str, item: str, window: str, buffer: str, extra_info: Dict[str, str]) -> str:
    return "my content"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat ≥ 0.4.2

bar_item_update

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

Prototype:

void weechat_bar_item_update (const char *name);

Arguments:

name: bar item name

C example:

weechat_bar_item_update ("myitem");

Script (Python):

# prototype
def bar_item_update(name: str) -> int: ...

# example
weechat.bar_item_update("myitem")

bar_item_remove

Remove a bar item.

Prototype:

void weechat_bar_item_remove (struct t_gui_bar_item *item);

Arguments:

item: bar item pointer

C example:

weechat_bar_item_remove (&my_item);

Script (Python):

# prototype
def bar_item_remove(item: str) -> int: ...

# example
weechat.bar_item_remove(myitem)

bar_search

Search a bar.

Prototype:

struct t_gui_bar *weechat_bar_search (const char *name);

Arguments:

name: bar name

Return value:

pointer to bar found, NULL if bar was not found

C example:

struct t_gui_bar *bar = weechat_bar_search ("mybar");

Script (Python):

# prototype
def bar_search(name: str) -> str: ...

# example
bar = weechat.bar_search("mybar")

bar_new

Updated in 2.9, 4.0.0.

Create a new bar.

Prototype:

struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *color_bg_inactive,
                                   const char *separator,
                                   const char *items);

Arguments:

name: bar name
hidden:
- on: bar is hidden
- off: bar is visible
priority: bar priority (integer)
type:
- root: bar displayed once, outside windows
- window: bar displayed in each window
condition: condition for displaying bar:
- active: bar is displayed in active window only
- inactive: bar is displayed in inactive windows only
- nicklist: bar is displayed in windows with nicklist
- evaluated expression: see the WeeChat user’s guide / Bar conditions ^↗
position: top, bottom, left or right
filling_top_bottom:
- horizontal: items are filled horizontally (space after each item)
- vertical: items are filled vertically (new line after each item)
- columns_horizontal: items are filled horizontally, displayed with columns
- columns_vertical: items are filled vertically, displayed with columns
filling_left_right:
- horizontal: items are filled horizontally (space after each item)
- vertical: items are filled vertically (new line after each item)
- columns_horizontal: items are filled horizontally, displayed with columns
- columns_vertical: items are filled vertically, displayed with columns
size: bar size in chars (0 means automatic size)
size_max: max size for bar (0 means no max size)
color_fg: color for text in bar
color_delim: color for delimiters in bar
color_bg: background color for bar
color_bg_inactive: background color for window bar which is not displayed in active window
separator:
- on: bar has separator line with other windows/bars
- off: no separator
items: list of items in bar, separated by comma (space between items), or "+" (glued items)

Return value:

pointer to new bar, NULL if an error occurred

Note	Since version 4.0.0, if the bar already exists, WeeChat sets the values received as default values for bar options and returns the bar pointer instead of NULL.

C example:

struct t_gui_bar *my_bar = weechat_bar_new (
    "mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "darkgray", "off",
    "time,buffer_number+buffer_name");

Script (Python):

# prototype
def bar_new(name: str, hidden: str, priority: str, type: str, condition: str, position: str,
            filling_top_bottom: str, filling_left_right: str, size: str, size_max: str,
            color_fg: str, color_delim: str, color_bg: str, color_bg_inactive: str,
            separator: str, items: str) -> str: ...

# example
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "darkgray", "off", "time,buffer_number+buffer_name")

Note	With WeeChat ≥ 2.9, in Ruby, the 4 colors (color_fg, color_delim, color_bg, color_bg_inactive) must be given in an array of 4 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat scripting guide ^↗ for more info.

bar_set

Set a new value for a bar property.

Prototype:

int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);

Arguments:

bar: bar pointer
property: name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items (see bar_new)
value: new value for property

Return value:

1 if new value was set, 0 if an error occurred

C example:

weechat_bar_set (mybar, "position", "bottom");

Script (Python):

# prototype
def bar_set(bar: str, property: str, value: str) -> int: ...

# example
weechat.bar_set(my_bar, "position", "bottom")

bar_update

Refresh content of a bar on screen.

Prototype:

void weechat_bar_update (const char *name);

Arguments:

name: bar name

C example:

weechat_bar_update ("mybar");

Script (Python):

# prototype
def bar_update(name: str) -> int: ...

# example
weechat.bar_update("mybar")

bar_remove

Remove a bar.

Prototype:

void weechat_bar_remove (struct t_gui_bar *bar);

Arguments:

bar: bar pointer

C example:

weechat_bar_remove (mybar);

Script (Python):

# prototype
def bar_remove(bar: str) -> int: ...

# example
weechat.bar_remove(my_bar)

3.20. Commands

Functions for executing WeeChat commands.

command

Updated in 1.1, 4.0.0.

Execute a command or send text to buffer.

Prototype:

int weechat_command (struct t_gui_buffer *buffer, const char *command);

Arguments:

buffer: buffer pointer (command is executed on this buffer, use NULL for current buffer)
command: command to execute (if beginning with a "/"), or text to send to buffer

Note	On buffer with `input_multiline` set to `0` (default), only the first command is executed (before the first newline char: `\n`).

Return value (WeeChat ≥ 1.1):

WEECHAT_RC_OK if successful
WEECHAT_RC_ERROR if error

C example:

int rc;
rc = weechat_command (weechat_buffer_search ("irc", "libera.#weechat"),
                      "/whois FlashCode");

Script (Python):

# prototype
def command(buffer: str, command: str) -> int: ...

# example
rc = weechat.command(weechat.buffer_search("irc", "libera.#weechat"), "/whois FlashCode")

command_options

WeeChat ≥ 2.5, updated in 4.0.0, 4.5.0.

Execute a command or send text to buffer with options.

Prototype:

int weechat_command_options (struct t_gui_buffer *buffer, const char *command,
                             struct t_hashtable *options);

Arguments:

buffer: buffer pointer (command is executed on this buffer, use NULL for current buffer)
command: command to execute (if beginning with a / or a command char), or text to send to buffer
options: a hashtable with some options (keys and values must be string) (can be NULL):
- commands: a comma-separated list of commands allowed to be executed during this call (see function string_match_list for the format); the special value - (hyphen-minus) disables the execution of commands and the string in command is sent as-is to the buffer (WeeChat ≥ 4.5.0)
- delay: delay to execute command, in milliseconds
- split_newline: 1 to split commands on newline char (\n) (WeeChat ≥ 4.0.0)

Return value:

WEECHAT_RC_OK if successful
WEECHAT_RC_ERROR if error

C example:

/* allow any command except /exec, run command in 2 seconds */
int rc;
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
weechat_hashtable_set (options, "commands", "*,!exec");
weechat_hashtable_set (options, "delay", "2000");
rc = weechat_command_options (NULL, "/some_command arguments", options);

Script (Python):

# prototype
def command_options(buffer: str, command: str, options: Dict[str, str]) -> int: ...

# example: allow any command except /exec
rc = weechat.command_options("", "/some_command arguments", {"commands": "*,!exec", "delay": "2000"})

3.21. Completion

Functions to complete a command line.

completion_new

WeeChat ≥ 2.9.

Create a new completion.

Prototype:

struct t_gui_completion *weechat_completion_new (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

Return value:

pointer to new completion

C example:

struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());

Script (Python):

# prototype
def completion_new(buffer: str) -> str: ...

# example
completion = weechat.completion_new(weechat.buffer_search_main())

completion_search

WeeChat ≥ 2.9.

Search possible words at a given position of a string, in the completion context.

Prototype:

int weechat_completion_search (struct t_gui_completion *completion, const char *data,
                               int position, int direction);

Arguments:

completion: completion pointer
data: the string to complete
position: index of the char in string to complete (starts to 0)
direction: 1 for next completion, -1 for previous completion

Return value:

1 if OK, 0 if error

C example:

struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());
if (weechat_completion_search (completion, "/help filt", 10, 1))
{
    /* ... */
}

Script (Python):

# prototype
def completion_search(completion: str, data: str, position: int, direction: int) -> int: ...

# example
completion = weechat.completion_new(weechat.buffer_search_main())
if weechat.completion_search(completion, "/help filt", 10, 1):
    # ...

completion_get_string

WeeChat ≥ 2.9.

Get a completion property as string.

Prototype:

const char *weechat_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 (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_completion_get_string (completion, "args");

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

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
def completion_get_string(completion: str, property: str) -> str: ...

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

completion_list_add

WeeChat ≥ 2.9.

Add a word for a completion.

Prototype:

void weechat_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 hook_completion.

Script (Python):

# prototype
def completion_list_add(completion: str, word: str, nick_completion: int, where: str) -> int: ...

# example: see function hook_completion

completion_free

WeeChat ≥ 2.9.

Free a completion.

Prototype:

void weechat_completion_free (struct t_gui_completion *completion);

Arguments:

completion: completion pointer

C example:

weechat_completion_free (completion);

Script (Python):

# prototype
def completion_free(completion: str) -> int: ...

# example
weechat.completion_free(completion)

3.22. Network

Network functions.

network_pass_proxy

Establish a connection/authentication to a proxy.

Important

This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat.

Prototype:

int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);

Arguments:

proxy: proxy name to use
sock: socket to use
address: address (hostname or IP address)
port: port

Return value:

1 if connection is OK, 0 if an error occurred

C example:

if (weechat_network_pass_proxy ("my_proxy", sock, "irc.libera.chat", 6667))
{
    /* OK */
}
else
{
    /* error */
}

Note	This function is not available in scripting API.

network_connect_to

Updated in 0.4.3.

Establish a connection to a remote host.

Important

This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat.

Prototype:

int weechat_network_connect_to (const char *proxy,
                                struct sockaddr *address,
                                socklen_t address_length);

Arguments:

proxy: proxy name to use
address: address to connect to (with port)
address_length: length of argument address

Return value:

socket number (≥ 0) if connection is OK, -1 if an error occurred

C example:

struct sockaddr *addr;
socklen_t length;
int sock;

/* allocate/set address and port in _addr_, set _length_ */
/* ... */

sock = weechat_network_connect_to (NULL, addr, length);
if (sock >= 0)
{
    /* OK */
}
else
{
    /* error */
}

Note	This function is not available in scripting API.

3.23. Infos

Functions to get infos.

info_get

Updated in 2.5.

Return info, as string, from WeeChat or a plugin.

Prototype:

char *weechat_info_get (const char *info_name, const char *arguments);

Arguments:

info_name: name of info to read (see table below)
arguments: arguments for info asked (optional, NULL if no argument is needed)

Return value:

string with info asked, NULL if an error occurred (must be freed by calling "free" after use)

Note	With WeeChat ≥ 2.5, the value returned is an allocated string (with WeeChat ≤ 2.4, it was a pointer to a static string).

Infos:

Plugin Name Description Arguments

fifo

fifo_filename

name of FIFO pipe

guile

guile_eval

evaluation of source code

source code to execute

guile

guile_interpreter

name of the interpreter used

guile

guile_version

version of the interpreter used

irc

irc_buffer

get buffer pointer for an IRC server/channel/nick

server,channel,nick (channel and nicks are optional)

irc

irc_is_channel

1 if string is a valid IRC channel name for server

server,channel (server is optional)

irc

irc_is_message_ignored

1 if the nick is ignored (message is not displayed)

server,message (message is the raw IRC message)

irc

irc_is_nick

1 if string is a valid IRC nick name

server,nickname (server is optional)

irc

irc_nick

get current nick on a server

server name

irc

irc_nick_color

get nick color code (deprecated since version 1.5, replaced by "nick_color")

nickname

irc

irc_nick_color_name

get nick color name (deprecated since version 1.5, replaced by "nick_color_name")

nickname

irc

irc_nick_from_host

get nick from IRC host

IRC host (like :nick!name@server.com)

irc

irc_ptr_channel

get pointer to an IRC channel

server,channel

irc

irc_ptr_nick

get pointer to an IRC nick

server,channel,nick

irc

irc_ptr_server

get pointer to an IRC server

server

irc

irc_server_cap

1 if capability is enabled in server

server,capability

irc

irc_server_cap_value

value of capability, if enabled in server

server,capability

irc

irc_server_isupport

1 if server supports this feature (from IRC message 005)

server,feature

irc

irc_server_isupport_value

value of feature, if supported by server (from IRC message 005)

server,feature

javascript

javascript_eval

evaluation of source code

source code to execute

javascript

javascript_interpreter

name of the interpreter used

javascript

javascript_version

version of the interpreter used

logger

logger_log_file

path to current log filename for the buffer

buffer pointer ("0x12345678") or buffer full name ("irc.libera.#weechat")

lua

lua_eval

evaluation of source code

source code to execute

lua

lua_interpreter

name of the interpreter used

lua

lua_version

version of the interpreter used

perl

perl_eval

evaluation of source code

source code to execute

perl

perl_interpreter

name of the interpreter used

perl

perl_version

version of the interpreter used

php

php_eval

evaluation of source code

source code to execute

php

php_interpreter

name of the interpreter used

php

php_version

version of the interpreter used

python

python_eval

evaluation of source code

source code to execute

python

python_interpreter

name of the interpreter used

python

python_version

version of the interpreter used

relay

relay_api_version

relay API version

relay

relay_api_version_number

relay API version (as number)

relay

relay_client_count

number of clients for relay

protocol,status (both are optional, for each argument "*" means all; protocols: irc, weechat; statuses: connecting, waiting_auth, connected, auth_failed, disconnected)

ruby

ruby_eval

evaluation of source code

source code to execute

ruby

ruby_interpreter

name of the interpreter used

ruby

ruby_version

version of the interpreter used

script

script_info

info on a script

script,info (script name with extension and info is a hdata variable

script

script_loaded

1 if script is loaded

script name with extension

spell

spell_dict

comma-separated list of dictionaries used in buffer

buffer pointer ("0x12345678") or buffer full name ("irc.libera.#weechat")

tcl

tcl_eval

evaluation of source code

source code to execute

tcl

tcl_interpreter

name of the interpreter used

tcl

tcl_version

version of the interpreter used

weechat

auto_connect

1 if automatic connection to servers is enabled, 0 if it has been disabled by the user (option "-a" or "--no-connect")

weechat

auto_load_scripts

1 if scripts are automatically loaded, 0 if the auto-load has been disabled by the user (option "-s" or "--no-script")

weechat

buffer

buffer pointer

buffer full name

weechat

charset_internal

WeeChat internal charset

weechat

charset_terminal

terminal charset

weechat

color_ansi_regex

POSIX extended regular expression to search ANSI escape codes

weechat

color_rgb2term

RGB color converted to terminal color (0-255)

rgb,limit (limit is optional and is set to 256 by default)

weechat

color_term2rgb

terminal color (0-255) converted to RGB color

color (terminal color: 0-255)

weechat

cursor_mode

1 if cursor mode is enabled

weechat

date

WeeChat compilation date/time

weechat

dir_separator

directory separator

weechat

filters_enabled

1 if filters are enabled

weechat

inactivity

keyboard inactivity (seconds)

weechat

locale

locale used for translating messages

weechat

mouse

1 if mouse is enabled

weechat

nick_color

get nick color code

nickname;colors (colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat

nick_color_ignore_case

get nick color code, ignoring case

nickname;range;colors (range is a number of chars (see function strcasecmp_range, 0 = convert to lower case without using a range), colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat

nick_color_name

get nick color name

weechat

nick_color_name_ignore_case

get nick color name, ignoring case

weechat

pid

WeeChat PID (process ID)

weechat

plugin_loaded

1 if plugin is loaded

plugin name

weechat

term_color_pairs

number of color pairs supported in terminal

weechat

term_colors

number of colors supported in terminal

weechat

term_height

height of terminal

weechat

term_width

width of terminal

weechat

totp_generate

generate a Time-based One-Time Password (TOTP)

secret (in base32), timestamp (optional, current time by default), number of digits (optional, between 4 and 10, 6 by default)

weechat

totp_validate

validate a Time-based One-Time Password (TOTP): 1 if TOTP is correct, otherwise 0

secret (in base32), one-time password, timestamp (optional, current time by default), number of passwords before/after to test (optional, 0 by default)

weechat

uptime

WeeChat uptime (format: "days:hh:mm:ss")

"days" (number of days) or "seconds" (number of seconds) (optional)

weechat

uptime_current

WeeChat uptime for the current process only (upgrades with /upgrade command are ignored) (format: "days:hh:mm:ss")

"days" (number of days) or "seconds" (number of seconds) (optional)

weechat

version

WeeChat version

weechat

version_git

WeeChat git version (output of command "git describe" for a development version only, empty for a stable release)

weechat

version_number

WeeChat version (as number)

version (optional, by default the version of the running WeeChat is returned)

weechat

weechat_cache_dir

WeeChat cache directory

weechat

weechat_config_dir

WeeChat config directory

weechat

weechat_daemon

1 if WeeChat is running in daemon mode (headless, in background)

weechat

weechat_data_dir

WeeChat data directory

weechat

weechat_dir

WeeChat directory (deprecated since version 3.2, replaced by "weechat_config_dir", "weechat_data_dir", "weechat_state_dir" , "weechat_cache_dir" and "weechat_runtime_dir")

weechat

weechat_headless

1 if WeeChat is running headless

weechat

weechat_libdir

WeeChat "lib" directory

weechat

weechat_localedir

WeeChat "locale" directory

weechat

weechat_runtime_dir

WeeChat runtime directory

weechat

weechat_sharedir

WeeChat "share" directory

weechat

weechat_site

WeeChat site

weechat

weechat_site_download

WeeChat site, download page

weechat

weechat_state_dir

WeeChat state directory

weechat

weechat_upgrading

1 if WeeChat is upgrading (command /upgrade)

weechat

window

window pointer

window number

C example:

char *version = weechat_info_get ("version", NULL);
char *date = weechat_info_get ("date", NULL);
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                version, date);
if (version)
    free (version);
if (date)
    free (date);

char *weechat_config_dir = weechat_info_get ("weechat_config_dir", NULL);
weechat_printf (NULL, "WeeChat config directory is: %s", weechat_config_dir);
if (weechat_config_dir)
    free (weechat_config_dir);

Script (Python):

# prototype
def info_get(info_name: str, arguments: str) -> str: ...

# example
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat config directory is: %s" % weechat.info_get("weechat_config_dir", ""))

info_get_hashtable

WeeChat ≥ 0.3.4.

Return info, as hashtable, from WeeChat or a plugin.

Prototype:

struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);

Arguments:

info_name: name of info to read (see table below)
hashtable: hashtable with arguments (depends on info asked) (optional, NULL if no argument is needed)

Return value:

hashtable with info asked, NULL if an error occurred (must be freed by calling hashtable_free after use)

Infos:

Plugin

Name

Description

Hashtable (input)

Hashtable (output)

irc

irc_message_parse

parse an IRC message

"message": IRC message, "server": server name (optional)

"tags": tags, "tag_xxx": unescaped value of tag "xxx" (one key per tag), "message_without_tags": message without the tags, "nick": nick, "user": user, "host": host, "command": command, "channel": channel, "arguments": arguments (includes channel), "text": text (for example user message), "param1" … "paramN": parsed command parameters, "num_params": number of parsed command parameters, "pos_command": index of "command" message ("-1" if "command" was not found), "pos_arguments": index of "arguments" message ("-1" if "arguments" was not found), "pos_channel": index of "channel" message ("-1" if "channel" was not found), "pos_text": index of "text" message ("-1" if "text" was not found)

irc

irc_message_split

split an IRC message (to fit in 512 bytes by default)

"message": IRC message, "server": server name (optional)

"msg1" … "msgN": messages to send (without final "\r\n"), "args1" … "argsN": arguments of messages, "count": number of messages

weechat

focus_info

get focus info

"x": x coordinate (string with integer >= 0), "y": y coordinate (string with integer >= 0)

see function "hook_focus" in Plugin API reference

weechat

secured_data

secured data

secured data: names and values (be careful: the values are sensitive data: do NOT print/log them anywhere)

C example:

struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (
        hashtable_in,
        "message",
        "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :Hello world!");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "tags"                : "time=2015-06-27T16:40:35.000Z;tag2=value\\sspace"
     *   "tag_time"            : "2015-06-27T16:40:35.000Z"
     *   "tag_tag2"            : "value space"
     *   "message_without_tags": ":nick!user@host PRIVMSG #weechat :Hello world!"
     *   "nick"                : "nick"
     *   "user"                : "user"
     *   "host"                : "nick!user@host"
     *   "command"             : "PRIVMSG"
     *   "channel"             : "#weechat"
     *   "arguments"           : "#weechat :Hello world!"
     *   "text"                : "Hello world!"
     *   "param1"              : "#weechat"
     *   "param2"              : "Hello world!"
     *   "num_params"          : "2"
     *   "pos_command"         : "65"
     *   "pos_arguments"       : "73"
     *   "pos_channel"         : "73"
     *   "pos_text"            : "83"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}

Note	See the WeeChat scripting guide / Parse message ^↗ for more info about "irc_message_parse" output.

Script (Python):

# prototype
def info_get_hashtable(info_name: str, dict_in: Dict[str, str]) -> Dict[str, str]: ...

# example
dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message here"}
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))

3.24. Infolists

An infolist is a list of "items". Each item contains variables.

For example, infolist "irc_server" has N items (N is number of IRC servers defined). For each item, there is variables like "name", "buffer", "is_connected", …

Each variable has a type and a value. Possible types are:

integer: any integer value
string: any string value
pointer: any pointer
buffer: buffer with fixed length, containing any data
time: time value

infolist_new

Create a new infolist.

Prototype:

struct t_infolist *weechat_infolist_new ();

Return value:

pointer to new infolist

C example:

struct t_infolist *infolist = weechat_infolist_new ();

Script (Python):

# prototype
def infolist_new() -> str: ...

# example
infolist = weechat.infolist_new()

infolist_new_item

Add an item in an infolist.

Prototype:

struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

pointer to new item

C example:

struct t_infolist_item *item = weechat_infolist_new_item (infolist);

Script (Python):

# prototype
def infolist_new_item(infolist: str) -> str: ...

# example
item = weechat.infolist_new_item(infolist)

infolist_new_var_integer

Add an integer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);

Arguments:

item: infolist item pointer
name: variable name
value: integer value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);

Script (Python):

# prototype
def infolist_new_var_integer(item: str, name: str, value: int) -> str: ...

# example
var = weechat.infolist_new_var_integer(item, "my_integer", 123)

infolist_new_var_string

Add a string variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);

Arguments:

item: infolist item pointer
name: variable name
value: string value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");

Script (Python):

# prototype
def infolist_new_var_string(item: str, name: str, value: str) -> str: ...

# example
var = weechat.infolist_new_var_string(item, "my_string", "value")

infolist_new_var_pointer

Add a pointer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);

Arguments:

item: infolist item pointer
name: variable name
pointer: pointer

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);

Script (Python):

# prototype
def infolist_new_var_pointer(item: str, name: str, pointer: str) -> str: ...

# example
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)

infolist_new_var_buffer

Add a buffer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);

Arguments:

item: infolist item pointer
name: variable name
pointer: pointer to buffer
size: size of buffer

Return value:

pointer to new variable

C example:

char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                              "my_buffer",
                                                              &buffer,
                                                              sizeof (buffer));

Note	This function is not available in scripting API.

infolist_new_var_time

Add a time variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);

Arguments:

item: infolist item pointer
name: variable name
time: time value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                            "my_time",
                                                            time (NULL));

Script (Python):

# prototype
def infolist_new_var_time(item: str, name: str, time: int) -> str: ...

# example
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))

infolist_get

Return infolist from WeeChat or a plugin.

Important

Content of infolist is a duplication of actual data. So if you are asking infolist with lot of data (like "buffer_lines"), WeeChat will allocate memory to duplicate all data, and this can take some time.
Instead of using big infolist, it is preferable to use hdata (but infolist may have more info than hdata, which is raw data), see hdata.

Prototype:

struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);

Arguments:

infolist_name: name of infolist to read (see table below)
pointer: pointer to an item, to get only this item in infolist (optional, can be NULL)
arguments: arguments for infolist asked (optional, NULL if no argument is needed)

Return value:

pointer to infolist, NULL if an error occurred

Infolists:

Plugin

Name

Description

Pointer

Arguments

alias

list of aliases

alias pointer (optional)

alias name (wildcard "*" is allowed) (optional)

alias

alias_default

list of default aliases

buflist

list of buffers in a buflist bar item

buflist bar item name (optional)

fset

fset_option

list of fset options

fset option pointer (optional)

option name (wildcard "*" is allowed) (optional)

guile

guile_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

irc

irc_channel

list of channels for an IRC server

channel pointer (optional)

server,channel (channel is optional)

irc

irc_color_weechat

mapping between IRC color codes and WeeChat color names

irc

irc_ignore

list of IRC ignores

ignore pointer (optional)

irc

irc_modelist

list of channel mode lists for an IRC channel

mode list pointer (optional)

server,channel,type (type is optional)

irc

irc_modelist_item

list of items in a channel mode list

mode list item pointer (optional)

server,channel,type,number (number is optional)

irc

irc_nick

list of nicks for an IRC channel

nick pointer (optional)

server,channel,nick (nick is optional)

irc

irc_notify

list of notify

notify pointer (optional)

server name (wildcard "*" is allowed) (optional)

irc

irc_server

list of IRC servers

server pointer (optional)

server name (wildcard "*" is allowed) (optional)

javascript

javascript_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

logger

logger_buffer

list of logger buffers

logger pointer (optional)

lua

lua_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

perl

perl_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

php

php_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

python

python_constant

list of scripting API constants

python

python_function

list of scripting API functions

python

python_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

relay

list of relay clients

relay pointer (optional)

ruby

ruby_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

script

script_script

list of scripts

script pointer (optional)

script name with extension (wildcard "*" is allowed) (optional)

tcl

tcl_script

list of scripts

script pointer (optional)

script name (wildcard "*" is allowed) (optional)

weechat

bar

list of bars

bar pointer (optional)

bar name (wildcard "*" is allowed) (optional)

weechat

bar_item

list of bar items

bar item pointer (optional)

bar item name (wildcard "*" is allowed) (optional)

weechat

bar_window

list of bar windows

bar window pointer (optional)

weechat

buffer

list of buffers

buffer pointer (optional)

buffer name (wildcard "*" is allowed) (optional)

weechat

buffer_lines

lines of a buffer

buffer pointer

weechat

filter

list of filters

filter name (wildcard "*" is allowed) (optional)

weechat

history

history of commands

buffer pointer (if not set, return global history) (optional)

weechat

hook

list of hooks

hook pointer (optional)

type,arguments (type is command/timer/.., arguments to get only some hooks (wildcard "*" is allowed), both are optional)

weechat

hotlist

list of buffers in hotlist

weechat

key

list of key bindings

context ("default", "search", "cursor" or "mouse") (optional)

weechat

layout

list of layouts

weechat

nicklist

nicks in nicklist for a buffer

buffer pointer

nick_xxx or group_xxx to get only nick/group xxx (optional)

weechat

option

list of options

option name (wildcard "*" is allowed) (optional)

weechat

plugin

list of plugins

plugin pointer (optional)

plugin name (wildcard "*" is allowed) (optional)

weechat

proxy

list of proxies

proxy pointer (optional)

proxy name (wildcard "*" is allowed) (optional)

weechat

url_options

options for URL

weechat

window

list of windows

window pointer (optional)

"current" for current window or a window number (optional)

xfer

list of xfer

xfer pointer (optional)

C example:

struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);

Script (Python):

# prototype
def infolist_get(infolist_name: str, pointer: str, arguments: str) -> str: ...

# example
infolist = weechat.infolist_get("irc_server", "", "")

infolist_next

Move "cursor" to next item in an infolist. The first call to this function for an infolist moves cursor to first item in infolist.

Prototype:

int weechat_infolist_next (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

1 if cursor has been moved on next item, 0 if end of list was reached

C example:

if (weechat_infolist_next (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}

Script (Python):

# prototype
def infolist_next(infolist: str) -> int: ...

# example
rc = weechat.infolist_next(infolist)
if rc:
    # read variables in item...
else:
    # no more item available

infolist_prev

Move "cursor" to previous item in an infolist. The first call to this function for an infolist moves cursor to last item in infolist.

Prototype:

int weechat_infolist_prev (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

1 if cursor has been moved on previous item, 0 if beginning of list was reached

C example:

if (weechat_infolist_prev (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}

Script (Python):

# prototype
def infolist_prev(infolist: str) -> int: ...

# example
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available

infolist_reset_item_cursor

Reset "cursor" for infolist.

Prototype:

void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

C example:

weechat_infolist_reset_item_cursor (infolist);

Script (Python):

# prototype
def infolist_reset_item_cursor(infolist: str) -> int: ...

# example
weechat.infolist_reset_item_cursor(infolist)

infolist_search_var

WeeChat ≥ 0.4.3.

Search a variable in the current infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                    const char *name);

Arguments:

infolist: infolist pointer
name: variable name

Return value:

pointer to variable found, NULL if the variable was not found

C example:

if (weechat_infolist_search_var (infolist, "name"))
{
    /* variable "name" exists */
    /* ... */
}

Script (Python):

# prototype
def infolist_search_var(infolist: str, name: str) -> str: ...

# example
if weechat.infolist_search_var(infolist, "name"):
    # variable "name" exists
    # ...

infolist_fields

Return list of fields for current infolist item.

Prototype:

const char *weechat_infolist_fields (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

string with list of fields for current infolist item. List is comma separated, and contains letter for type, followed by variable name. Types are: "i" (integer), "s" (string), "p" (pointer), "b" (buffer), "t" (time).

C example:

const char *fields = weechat_infolist_fields (infolist);
/* fields contains something like:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */

Script (Python):

# prototype
def infolist_fields(infolist: str) -> str: ...

# example
fields = weechat.infolist_fields(infolist)
# fields contains something like:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"

infolist_integer

Return value of integer variable in current infolist item.

Prototype:

int weechat_infolist_integer (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "integer")

Return value:

integer value of variable

C example:

weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "my_integer"));

Script (Python):

# prototype
def infolist_integer(infolist: str, var: str) -> int: ...

# example
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))

infolist_string

Return value of string variable in current infolist item.

Prototype:

const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "string")

Return value:

string value of variable

C example:

weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "my_string"));

Script (Python):

# prototype
def infolist_string(infolist: str, var: str) -> str: ...

# example
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))

infolist_pointer

Return value of pointer variable in current infolist item.

Prototype:

void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "pointer")

Return value:

pointer value of variable

C example:

weechat_printf (NULL, "pointer = %p",
                weechat_infolist_pointer (infolist, "my_pointer"));

Script (Python):

# prototype
def infolist_pointer(infolist: str, var: str) -> str: ...

# example
weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer"))

infolist_buffer

Return value of buffer variable in current infolist item.

Prototype:

void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);

Arguments:

infolist: infolist pointer
var: variable name (must be type "buffer")
size: pointer to integer variable, will be set with buffer size

Return value:

buffer pointer

C example:

int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = %p, size = %d", pointer, size);

Note	This function is not available in scripting API.

infolist_time

Return value of time variable in current infolist item.

Prototype:

time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "time")

Return value:

time value of variable

C example:

weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));

Script (Python):

# prototype
def infolist_time(infolist: str, var: str) -> int: ...

# example
weechat.prnt("", "time = %d" % weechat.infolist_time(infolist, "my_time"))

infolist_free

Free an infolist.

Prototype:

void weechat_infolist_free (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

C example:

weechat_infolist_free (infolist);

Script (Python):

# prototype
def infolist_free(infolist: str) -> int: ...

# example
weechat.infolist_free(infolist)

3.25. Hdata

Functions for hdata (raw access to WeeChat or plugins data).

Important

Hdata provides read-only access to data. It is STRICTLY FORBIDDEN to write something in memory pointed by hdata variables.
The only way to update data is to call function hdata_update.

hdata_new

WeeChat ≥ 0.3.6, updated in 0.3.9, 0.4.0.

Create a new hdata.

Note

hdata vs infolist

Hdata is a fast way to read WeeChat or plugins data. It is similar to infolist, but there are some differences:

It is faster and uses less memory: direct read of data without duplication.
It may have different info than infolist: it contains only raw data in structures (infolist may add some extra data for convenience).

Prototype:

struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);

Arguments:

hdata_name: name of hdata
var_prev: name of variable in structure which is a pointer to previous element in list (may be NULL if no such variable is available)
var_next: name of variable in structure which is a pointer to next element in list (may be NULL if no such variable is available)
create_allowed: 1 if create of structure is allowed, otherwise 0 (WeeChat ≥ 0.4.0)
delete_allowed: 1 if delete of structure is allowed, otherwise 0 (WeeChat ≥ 0.3.9)
callback_update: callback to update data in hdata, can be NULL if no update is allowed (WeeChat ≥ 0.3.9), arguments and return value:
- void *data: pointer
- struct t_hdata *hdata: pointer to hdata
- struct t_hashtable *hashtable: hashtable with variables to update (see hdata_update)
- return value: number of variables updated
callback_update_data: pointer given to update callback when it is called by WeeChat (WeeChat ≥ 0.3.9)

Return value:

pointer to new hdata

C example:

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);

Note	This function is not available in scripting API.

hdata_new_var

WeeChat ≥ 0.3.6, updated in 0.3.7, 0.3.9, 0.4.3, 3.4, 4.3.0.

Create a new variable in hdata.

Prototype:

void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);

Arguments:

hdata: hdata pointer
name: variable name
offset: offset of variable in structure
type: variable type, one of:
- WEECHAT_HDATA_CHAR
- WEECHAT_HDATA_INTEGER
- WEECHAT_HDATA_LONG
- WEECHAT_HDATA_LONGLONG (WeeChat ≥ 4.3.0)
- WEECHAT_HDATA_STRING
- WEECHAT_HDATA_SHARED_STRING (WeeChat ≥ 0.4.3)
- WEECHAT_HDATA_POINTER
- WEECHAT_HDATA_TIME
- WEECHAT_HDATA_HASHTABLE (WeeChat ≥ 0.3.7)
- WEECHAT_HDATA_OTHER
update_allowed: 1 if update of variable is allowed, otherwise 0 (WeeChat ≥ 0.3.9)
array_size: not NULL only if a variable is an array, and it can be: (WeeChat ≥ 0.3.9)
- name of variable in hdata: this variable will be used as size of array (dynamic size for array)
- integer (as string): fixed size for array
- *: automatic size: the size of array is computed by looking at values, when the first NULL is found (only for type string, pointer or hashtable)
hdata_name: name of a hdata (if it’s a pointer to a structure with hdata)

With WeeChat ≥ 3.4, the array_size parameter can be prefixed with *, for pointer to dynamically allocated array (without this prefix, the array is considered static).

Examples of variables and the corresponding array size (WeeChat ≥ 3.4):

Variable declaration in C Hdata type Array size Description

int *numbers;

WEECHAT_HDATA_INTEGER

*,2

Allocated array of 2 integers.

int *numbers;

WEECHAT_HDATA_INTEGER

*,array_size

Allocated array of integers, the size is stored in another variable called "array_size".

int numbers[3];

WEECHAT_HDATA_INTEGER

3

Static array of 3 integers.

char **words;

WEECHAT_HDATA_STRING

*,*

Allocated array of strings, dynamic size (NULL pointer must be present after last word).

char **words;

WEECHAT_HDATA_STRING

*,count_words

Allocated array of strings, the size is stored in another variable called "count_words".

C example:

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int numbers[3];
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "numbers", offsetof (struct t_myplugin_list, numbers), WEECHAT_HDATA_INTEGER, 0, "3", NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "*,tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*,*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");

The macro "WEECHAT_HDATA_VAR" can be used to shorten code:

WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, numbers, INTEGER, 0, "3", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "*,tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*,*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");

Note	This function is not available in scripting API.

hdata_new_list

WeeChat ≥ 0.3.6, updated in 1.0.

Create a new list pointer in hdata.

Prototype:

void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);

Arguments:

hdata: hdata pointer
name: variable name
pointer: list pointer
flags: combination of following values: (WeeChat ≥ 1.0)
- WEECHAT_HDATA_LIST_CHECK_POINTERS: list used to check pointers

C example:

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);

The macro "WEECHAT_HDATA_LIST" can be used to shorten code:

WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
WEECHAT_HDATA_LIST(last_buffer, 0);

Note	This function is not available in scripting API.

hdata_get

WeeChat ≥ 0.3.6.

Return hdata for a WeeChat or plugin structure.

Note	Hdata does not contain data, it’s only a hashtable with position of variables in structure. That means you will need this hdata and a pointer to a WeeChat/plugin object to read some data.

Prototype:

struct t_hdata *weechat_hdata_get (const char *hdata_name);

Arguments:

hdata_name: name of hdata (see list below)

Return value:

pointer to hdata, NULL if an error occurred

List of hdata:

Plugin

Name

Description

Lists

Variables

fset

fset_option

fset options

index (integer)
file (string)
section (string)
option (string)
name (string)
parent_name (string)
type (integer)
default_value (string)
value (string)
parent_value (string)
min (string)
max (string)
description (string)
string_values (string)
marked (integer)

guile

guile_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "guile_script")
next_script (pointer, hdata: "guile_script")

irc

irc_batch

irc batch

reference (string)
parent_ref (string)
type (string)
parameters (string)
start_time (time)
messages (pointer)
end_received (integer)
messages_processed (integer)
prev_batch (pointer, hdata: "irc_batch")
next_batch (pointer, hdata: "irc_batch")

irc

irc_channel

irc channel

type (integer)
name (string)
topic (string)
modes (string)
limit (integer)
key (string)
join_msg_received (hashtable)
checking_whox (integer)
away_message (string)
has_quit_server (integer)
cycle (integer)
part (integer)
nick_completion_reset (integer)
pv_remote_nick_color (string)
hook_autorejoin (pointer)
nicks_count (integer)
nicks (pointer, hdata: "irc_nick")
last_nick (pointer, hdata: "irc_nick")
nicks_speaking (pointer)
nicks_speaking_time (pointer, hdata: "irc_channel_speaking")
last_nick_speaking_time (pointer, hdata: "irc_channel_speaking")
modelists (pointer, hdata: "irc_modelist")
last_modelist (pointer, hdata: "irc_modelist")
join_smart_filtered (hashtable)
typing_state (integer)
typing_status_sent (time)
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
prev_channel (pointer, hdata: "irc_channel")
next_channel (pointer, hdata: "irc_channel")

irc

irc_channel_speaking

irc channel_speaking

nick (string)
time_last_message (time)
prev_nick (pointer, hdata: "irc_channel_speaking")
next_nick (pointer, hdata: "irc_channel_speaking")

irc

irc_ignore

irc ignore

irc_ignore_list
last_irc_ignore

number (integer)
mask (string)
regex_mask (pointer)
server (string)
channel (string)
prev_ignore (pointer, hdata: "irc_ignore")
next_ignore (pointer, hdata: "irc_ignore")

irc

irc_list

irc data for /list buffer

buffer (pointer, hdata: "buffer")
channels (pointer)
filter_channels (pointer)
name_max_length (integer)
filter (string)
sort (string)
sort_fields (pointer)
sort_fields_count (integer)
selected_line (integer)

irc

irc_list_channel

irc channel on /list buffer

name (string)
name2 (string)
users (integer)
topic (string)

irc

irc_modelist

irc modelist

type (char)
state (integer)
items (pointer, hdata: "irc_modelist_item")
last_item (pointer, hdata: "irc_modelist_item")
prev_modelist (pointer, hdata: "irc_modelist")
next_modelist (pointer, hdata: "irc_modelist")

irc

irc_modelist_item

irc modelist item

number (integer)
mask (string)
setter (string)
datetime (time)
prev_item (pointer, hdata: "irc_modelist_item")
next_item (pointer, hdata: "irc_modelist_item")

irc

irc_nick

irc nick

name (string)
host (string)
prefixes (string)
prefix (string)
away (integer)
account (string)
realname (string)
color (string)
prev_nick (pointer, hdata: "irc_nick")
next_nick (pointer, hdata: "irc_nick")

irc

irc_notify

irc notify

server (pointer, hdata: "irc_server")
nick (string)
check_away (integer)
is_on_server (integer)
away_message (string)
ison_received (integer)
prev_notify (pointer, hdata: "irc_notify")
next_notify (pointer, hdata: "irc_notify")

irc

irc_redirect

irc redirect

server (pointer, hdata: "irc_server")
pattern (string)
signal (string)
count (integer)
current_count (integer)
string (string)
timeout (integer)
command (string)
assigned_to_command (integer)
start_time (time)
cmd_start (hashtable)
cmd_stop (hashtable)
cmd_extra (hashtable)
cmd_start_received (integer)
cmd_stop_received (integer)
cmd_filter (hashtable)
output (string)
output_size (integer)
prev_redirect (pointer, hdata: "irc_redirect")
next_redirect (pointer, hdata: "irc_redirect")

irc

irc_redirect_pattern

pattern for irc redirect

irc_redirect_patterns
last_irc_redirect_pattern

name (string)
temp_pattern (integer)
timeout (integer)
cmd_start (string)
cmd_stop (string)
cmd_extra (string)
prev_redirect (pointer, hdata: "irc_redirect_pattern")
next_redirect (pointer, hdata: "irc_redirect_pattern")

irc

irc_server

irc server

irc_servers
last_irc_server

name (string)
options (pointer)
temp_server (integer)
fake_server (integer)
reloading_from_config (integer)
reloaded_from_config (integer)
addresses_eval (string)
addresses_count (integer)
addresses_array (string, array_size: "addresses_count")
ports_array (integer, array_size: "addresses_count")
retry_array (integer, array_size: "addresses_count")
index_current_address (integer)
current_address (string)
current_ip (string)
current_port (integer)
current_retry (integer)
sock (integer)
hook_connect (pointer, hdata: "hook")
hook_fd (pointer, hdata: "hook")
hook_timer_connection (pointer, hdata: "hook")
hook_timer_sasl (pointer, hdata: "hook")
hook_timer_anti_flood (pointer, hdata: "hook")
sasl_scram_client_first (string)
sasl_scram_salted_pwd (other)
sasl_scram_salted_pwd_size (integer)
sasl_scram_auth_message (string)
sasl_temp_username (string)
sasl_temp_password (string)
authentication_method (integer)
sasl_mechanism_used (integer)
is_connected (integer)
tls_connected (integer)
disconnected (integer)
gnutls_sess (pointer)
tls_cert (pointer)
tls_cert_key (pointer)
unterminated_message (string)
nicks_count (integer)
nicks_array (string, array_size: "nicks_count")
nick_first_tried (integer)
nick_alternate_number (integer)
nick (string)
nick_modes (string)
host (string)
checking_cap_ls (integer)
cap_ls (hashtable)
checking_cap_list (integer)
cap_list (hashtable)
multiline_max_bytes (integer)
multiline_max_lines (integer)
isupport (string)
prefix_modes (string)
prefix_chars (string)
msg_max_length (integer)
user_max_length (integer)
host_max_length (integer)
casemapping (integer)
utf8mapping (integer)
utf8only (integer)
chantypes (string)
chanmodes (string)
monitor (integer)
monitor_time (time)
clienttagdeny (string)
clienttagdeny_count (integer)
clienttagdeny_array (string, array_size: "clienttagdeny_count")
typing_allowed (integer)
reconnect_delay (integer)
reconnect_start (time)
command_time (time)
autojoin_time (time)
autojoin_done (integer)
disable_autojoin (integer)
is_away (integer)
away_message (string)
away_time (time)
lag (integer)
lag_displayed (integer)
lag_check_time (other)
lag_next_check (time)
lag_last_refresh (time)
cmd_list_regexp (pointer)
list (pointer, hdata: "irc_list")
last_away_check (time)
last_data_purge (time)
outqueue (pointer)
last_outqueue (pointer)
redirects (pointer, hdata: "irc_redirect")
last_redirect (pointer, hdata: "irc_redirect")
notify_list (pointer, hdata: "irc_notify")
last_notify (pointer, hdata: "irc_notify")
notify_count (integer)
join_manual (hashtable)
join_channel_key (hashtable)
join_noswitch (hashtable)
echo_msg_recv (hashtable)
names_channel_filter (hashtable)
batches (pointer, hdata: "irc_batch")
last_batch (pointer, hdata: "irc_batch")
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
channels (pointer, hdata: "irc_channel")
last_channel (pointer, hdata: "irc_channel")
prev_server (pointer, hdata: "irc_server")
next_server (pointer, hdata: "irc_server")

javascript

javascript_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "javascript_script")
next_script (pointer, hdata: "javascript_script")

lua

lua_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "lua_script")
next_script (pointer, hdata: "lua_script")

perl

perl_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "perl_script")
next_script (pointer, hdata: "perl_script")

php

php_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "php_script")
next_script (pointer, hdata: "php_script")

python

python_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "python_script")
next_script (pointer, hdata: "python_script")

ruby

ruby_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "ruby_script")
next_script (pointer, hdata: "ruby_script")

script

script_script

scripts from repository

scripts_repo
last_script_repo

name (string)
name_with_extension (string)
language (integer)
author (string)
mail (string)
version (string)
license (string)
description (string)
tags (string)
requirements (string)
min_weechat (string)
max_weechat (string)
sha512sum (string)
url (string)
popularity (integer)
date_added (time)
date_updated (time)
status (integer)
version_loaded (string)
displayed (integer)
install_order (integer)
prev_script (pointer, hdata: "script_script")
next_script (pointer, hdata: "script_script")

tcl

tcl_script

list of scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "tcl_script")
next_script (pointer, hdata: "tcl_script")

weechat

bar

gui_bars
last_gui_bar

name (string)
options (pointer)
items_count (integer)
items_subcount (pointer)
items_array (pointer)
items_buffer (pointer)
items_prefix (pointer)
items_name (pointer)
items_suffix (pointer)
bar_window (pointer, hdata: "bar_window")
bar_refresh_needed (integer)
prev_bar (pointer, hdata: "bar")
next_bar (pointer, hdata: "bar")

weechat

bar_item

bar item

gui_bar_items
last_gui_bar_item

plugin (pointer, hdata: "plugin")
name (string)
build_callback (pointer)
build_callback_pointer (pointer)
build_callback_data (pointer)
prev_item (pointer, hdata: "bar_item")
next_item (pointer, hdata: "bar_item")

weechat

bar_window

bar window

bar (pointer, hdata: "bar")
x (integer)
y (integer)
width (integer)
height (integer)
scroll_x (integer)
scroll_y (integer)
cursor_x (integer)
cursor_y (integer)
current_size (integer)
items_count (integer)
items_subcount (pointer)
items_content (pointer)
items_num_lines (pointer)
items_refresh_needed (pointer)
screen_col_size (integer)
screen_lines (integer)
coords_count (integer)
coords (pointer)
gui_objects (pointer)
prev_bar_window (pointer, hdata: "bar_window")
next_bar_window (pointer, hdata: "bar_window")

Update allowed:
scroll_x (integer)
scroll_y (integer)

weechat

buffer

gui_buffer_last_displayed
gui_buffers
last_gui_buffer

id (longlong)
opening (integer)
plugin (pointer, hdata: "plugin")
plugin_name_for_upgrade (string)
number (integer)
old_number (integer)
layout_number (integer)
layout_number_merge_order (integer)
name (string)
full_name (string)
old_full_name (string)
short_name (string)
type (integer)
notify (integer)
num_displayed (integer)
active (integer)
hidden (integer)
zoomed (integer)
print_hooks_enabled (integer)
day_change (integer)
clear (integer)
filter (integer)
close_callback (pointer)
close_callback_pointer (pointer)
close_callback_data (pointer)
closing (integer)
title (string)
modes (string)
own_lines (pointer, hdata: "lines")
mixed_lines (pointer, hdata: "lines")
lines (pointer, hdata: "lines")
next_line_id (integer)
time_for_each_line (integer)
chat_refresh_needed (integer)
nicklist (integer)
nicklist_case_sensitive (integer)
nicklist_root (pointer, hdata: "nick_group")
nicklist_max_length (integer)
nicklist_display_groups (integer)
nicklist_count (integer)
nicklist_visible_count (integer)
nicklist_groups_count (integer)
nicklist_groups_visible_count (integer)
nicklist_nicks_count (integer)
nicklist_nicks_visible_count (integer)
nicklist_last_id_assigned (longlong)
nickcmp_callback (pointer)
nickcmp_callback_pointer (pointer)
nickcmp_callback_data (pointer)
input (integer)
input_callback (pointer)
input_callback_pointer (pointer)
input_callback_data (pointer)
input_get_any_user_data (integer)
input_get_unknown_commands (integer)
input_get_empty (integer)
input_multiline (integer)
input_prompt (string)
input_buffer (string)
input_buffer_alloc (integer)
input_buffer_size (integer)
input_buffer_length (integer)
input_buffer_pos (integer)
input_buffer_1st_display (integer)
input_undo_snap (pointer, hdata: "input_undo")
input_undo (pointer, hdata: "input_undo")
last_input_undo (pointer, hdata: "input_undo")
ptr_input_undo (pointer, hdata: "input_undo")
input_undo_count (integer)
completion (pointer, hdata: "completion")
history (pointer, hdata: "history")
last_history (pointer, hdata: "history")
ptr_history (pointer, hdata: "history")
num_history (integer)
text_search (integer)
text_search_direction (integer)
text_search_exact (integer)
text_search_regex (integer)
text_search_regex_compiled (pointer)
text_search_where (integer)
text_search_history (integer)
text_search_found (integer)
text_search_ptr_history (pointer, hdata: "history")
text_search_input (string)
highlight_words (string)
highlight_regex (string)
highlight_regex_compiled (pointer)
highlight_disable_regex (string)
highlight_disable_regex_compiled (pointer)
highlight_tags_restrict (string)
highlight_tags_restrict_count (integer)
highlight_tags_restrict_array (pointer, array_size: "highlight_tags_restrict_count")
highlight_tags (string)
highlight_tags_count (integer)
highlight_tags_array (pointer, array_size: "highlight_tags_count")
hotlist (pointer, hdata: "hotlist")
hotlist_max_level_nicks (hashtable)
keys (pointer, hdata: "key")
last_key (pointer, hdata: "key")
keys_count (integer)
local_variables (hashtable)
prev_buffer (pointer, hdata: "buffer")
next_buffer (pointer, hdata: "buffer")

weechat

buffer_visited

visited buffer

gui_buffers_visited
last_gui_buffer_visited

buffer (pointer, hdata: "buffer")
prev_buffer (pointer, hdata: "buffer_visited")
next_buffer (pointer, hdata: "buffer_visited")

weechat

completion

structure with completion

weechat_completions
last_weechat_completion

plugin (pointer, hdata: "plugin")
buffer (pointer, hdata: "buffer")
context (integer)
case_sensitive (integer)
base_command (string)
base_command_arg_index (integer)
base_word (string)
base_word_pos (integer)
position (integer)
args (string)
direction (integer)
add_space (integer)
force_partial_completion (integer)
reverse_partial_completion (integer)
list (pointer)
word_found (string)
word_found_is_nick (integer)
position_replace (integer)
diff_size (integer)
diff_length (integer)
partial_list (pointer)
prev_completion (pointer, hdata: "completion")
next_completion (pointer, hdata: "completion")

weechat

completion_word

structure with word found for a completion

word (string)
nick_completion (char)
count (integer)

weechat

config_file

config file

config_files
last_config_file

plugin (pointer, hdata: "plugin")
priority (integer)
name (string)
filename (string)
file (pointer)
version (integer)
callback_reload (pointer)
callback_reload_pointer (pointer)
callback_reload_data (pointer)
sections (pointer, hdata: "config_section")
last_section (pointer, hdata: "config_section")
prev_config (pointer, hdata: "config_file")
next_config (pointer, hdata: "config_file")

weechat

config_option

config option

config_file (pointer, hdata: "config_file")
section (pointer, hdata: "config_section")
name (string)
parent_name (string)
type (integer)
description (string)
string_values (string, array_size: "*")
min (integer)
max (integer)
default_value (pointer)
value (pointer)
null_value_allowed (integer)
callback_check_value (pointer)
callback_check_value_pointer (pointer)
callback_check_value_data (pointer)
callback_change (pointer)
callback_change_pointer (pointer)
callback_change_data (pointer)
callback_delete (pointer)
callback_delete_pointer (pointer)
callback_delete_data (pointer)
loaded (integer)
prev_option (pointer, hdata: "config_option")
next_option (pointer, hdata: "config_option")

weechat

config_section

config section

config_file (pointer, hdata: "config_file")
name (string)
user_can_add_options (integer)
user_can_delete_options (integer)
callback_read (pointer)
callback_read_pointer (pointer)
callback_read_data (pointer)
callback_write (pointer)
callback_write_pointer (pointer)
callback_write_data (pointer)
callback_write_default (pointer)
callback_write_default_pointer (pointer)
callback_write_default_data (pointer)
callback_create_option (pointer)
callback_create_option_pointer (pointer)
callback_create_option_data (pointer)
callback_delete_option (pointer)
callback_delete_option_pointer (pointer)
callback_delete_option_data (pointer)
options (pointer, hdata: "config_option")
last_option (pointer, hdata: "config_option")
prev_section (pointer, hdata: "config_section")
next_section (pointer, hdata: "config_section")

weechat

filter

gui_filters
last_gui_filter

enabled (integer)
name (string)
buffer_name (string)
num_buffers (integer)
buffers (pointer)
tags (string)
tags_count (integer)
tags_array (pointer, array_size: "tags_count")
regex (string)
regex_prefix (pointer)
regex_message (pointer)
prev_filter (pointer, hdata: "filter")
next_filter (pointer, hdata: "filter")

weechat

history

history of commands in buffer

gui_history
last_gui_history

text (string)
next_history (pointer, hdata: "history")
prev_history (pointer, hdata: "history")

Update allowed:
__create
__delete

weechat

hotlist

gui_hotlist
last_gui_hotlist

priority (integer)
time (time)
time_usec (long)
buffer (pointer, hdata: "buffer")
count (integer, array_size: "4")
prev_hotlist (pointer, hdata: "hotlist")
next_hotlist (pointer, hdata: "hotlist")

weechat

input_undo

structure with undo for input line

data (string)
pos (integer)
prev_undo (pointer, hdata: "input_undo")
next_undo (pointer, hdata: "input_undo")

weechat

key

a key (keyboard shortcut)

gui_default_keys
gui_default_keys_cursor
gui_default_keys_histsearch
gui_default_keys_mouse
gui_default_keys_search
gui_keys
gui_keys_cursor
gui_keys_histsearch
gui_keys_mouse
gui_keys_search
last_gui_default_key
last_gui_default_key_cursor
last_gui_default_key_histsearch
last_gui_default_key_mouse
last_gui_default_key_search
last_gui_key
last_gui_key_cursor
last_gui_key_histsearch
last_gui_key_mouse
last_gui_key_search

key (string)
area_type (pointer)
area_name (pointer)
area_key (string)
command (string)
score (integer)
prev_key (pointer, hdata: "key")
next_key (pointer, hdata: "key")

weechat

layout

gui_layout_current
gui_layouts
last_gui_layout

name (string)
layout_buffers (pointer, hdata: "layout_buffer")
last_layout_buffer (pointer, hdata: "layout_buffer")
layout_windows (pointer, hdata: "layout_window")
internal_id (integer)
internal_id_current_window (integer)
prev_layout (pointer, hdata: "layout")
next_layout (pointer, hdata: "layout")

weechat

layout_buffer

buffer layout

plugin_name (string)
buffer_name (string)
number (integer)
prev_layout (pointer, hdata: "layout_buffer")
next_layout (pointer, hdata: "layout_buffer")

weechat

layout_window

window layout

internal_id (integer)
parent_node (pointer, hdata: "layout_window")
split_pct (integer)
split_horiz (integer)
child1 (pointer, hdata: "layout_window")
child2 (pointer, hdata: "layout_window")
plugin_name (string)
buffer_name (string)

weechat

line

structure with one line

data (pointer, hdata: "line_data")
prev_line (pointer, hdata: "line")
next_line (pointer, hdata: "line")

weechat

line_data

structure with one line data

buffer (pointer, hdata: "buffer")
id (integer)
y (integer)
date (time)
date_usec (integer)
date_printed (time)
date_usec_printed (integer)
str_time (string)
tags_count (integer)
tags_array (shared_string, array_size: "tags_count")
displayed (char)
notify_level (char)
highlight (char)
refresh_needed (char)
prefix (shared_string)
prefix_length (integer)
message (string)

Update allowed:
    date (time)
    date_usec (integer)
    date_printed (time)
    date_usec_printed (integer)
    tags_array (shared_string)
    prefix (shared_string)
    message (string)

weechat

lines

structure with lines

first_line (pointer, hdata: "line")
last_line (pointer, hdata: "line")
last_read_line (pointer, hdata: "line")
lines_count (integer)
first_line_not_read (integer)
lines_hidden (integer)
buffer_max_length (integer)
buffer_max_length_refresh (integer)
prefix_max_length (integer)
prefix_max_length_refresh (integer)

weechat

nick

nick in nicklist

id (longlong)
group (pointer, hdata: "nick_group")
name (shared_string)
color (shared_string)
prefix (shared_string)
prefix_color (shared_string)
visible (integer)
prev_nick (pointer, hdata: "nick")
next_nick (pointer, hdata: "nick")

weechat

nick_group

group in nicklist

id (longlong)
name (shared_string)
color (shared_string)
visible (integer)
level (integer)
parent (pointer, hdata: "nick_group")
children (pointer, hdata: "nick_group")
last_child (pointer, hdata: "nick_group")
nicks (pointer, hdata: "nick")
last_nick (pointer, hdata: "nick")
prev_group (pointer, hdata: "nick_group")
next_group (pointer, hdata: "nick_group")

weechat

plugin

weechat_plugins
last_weechat_plugin

filename (string)
handle (pointer)
name (string)
description (string)
author (string)
version (string)
license (string)
charset (string)
priority (integer)
initialized (integer)
debug (integer)
upgrading (integer)
unload_with_upgrade (integer)
variables (hashtable)
prev_plugin (pointer, hdata: "plugin")
next_plugin (pointer, hdata: "plugin")

weechat

proxy

weechat_proxies
last_weechat_proxy

name (string)
options (pointer)
prev_proxy (pointer, hdata: "proxy")
next_proxy (pointer, hdata: "proxy")

weechat

window

gui_current_window
gui_windows
last_gui_window

number (integer)
win_x (integer)
win_y (integer)
win_width (integer)
win_height (integer)
win_width_pct (integer)
win_height_pct (integer)
win_chat_x (integer)
win_chat_y (integer)
win_chat_width (integer)
win_chat_height (integer)
win_chat_cursor_x (integer)
win_chat_cursor_y (integer)
bar_windows (pointer, hdata: "bar_window")
last_bar_window (pointer, hdata: "bar_window")
refresh_needed (integer)
gui_objects (pointer)
buffer (pointer, hdata: "buffer")
layout_plugin_name (string)
layout_buffer_name (string)
scroll (pointer, hdata: "window_scroll")
scroll_changed (integer)
ptr_tree (pointer, hdata: "window_tree")
prev_window (pointer, hdata: "window")
next_window (pointer, hdata: "window")

weechat

window_scroll

scroll info in window

buffer (pointer, hdata: "buffer")
first_line_displayed (integer)
start_line (pointer, hdata: "line")
start_line_pos (integer)
scrolling (integer)
start_col (integer)
lines_after (integer)
text_search_start_line (pointer, hdata: "line")
prev_scroll (pointer, hdata: "window_scroll")
next_scroll (pointer, hdata: "window_scroll")

weechat

window_tree

tree of windows

gui_windows_tree

parent_node (pointer, hdata: "window_tree")
split_pct (integer)
split_horizontal (integer)
child1 (pointer, hdata: "window_tree")
child2 (pointer, hdata: "window_tree")
window (pointer, hdata: "window")

C example:

struct t_hdata *hdata = weechat_hdata_get ("irc_server");

Script (Python):

# prototype
def hdata_get(hdata_name: str) -> str: ...

# example
hdata = weechat.hdata_get("irc_server")

hdata_get_var_offset

WeeChat ≥ 0.3.6.

Return offset of variable in hdata.

Prototype:

int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable offset, -1 if an error occurred

C example:

int offset = weechat_hdata_get_var_offset (hdata, "name");

Script (Python):

# prototype
def hdata_get_var_offset(hdata: str, name: str) -> int: ...

# example
offset = weechat.hdata_get_var_offset(hdata, "name")

hdata_get_var_type

WeeChat ≥ 0.3.6.

Return type of variable in hdata (as integer).

Prototype:

int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable type, -1 if an error occurred

C example:

int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_LONGLONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_SHARED_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable not found */
        break;
}

Note	This function is not available in scripting API.

hdata_get_var_type_string

WeeChat ≥ 0.3.6.

Return type of variable in hdata (as string).

Prototype:

const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable type, NULL if an error occurred

C example:

weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));

Script (Python):

# prototype
def hdata_get_var_type_string(hdata: str, name: str) -> str: ...

# example
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name"))

hdata_get_var_array_size

WeeChat ≥ 0.3.9.

Return array size for variable in hdata.

Prototype:

int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

array size for variable, -1 if variable is not an array or if an error occurred

C example:

int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");

Script (Python):

# prototype
def hdata_get_var_array_size(hdata: str, pointer: str, name: str) -> int: ...

# example
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")

hdata_get_var_array_size_string

WeeChat ≥ 0.3.9.

Return array size for variable in hdata (as string).

Prototype:

const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer,
                                                     const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

array size for variable as string, NULL if variable is not an array or if an error occurred

C example:

const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");

Script (Python):

# prototype
def hdata_get_var_array_size_string(hdata: str, pointer: str, name: str) -> str: ...

# example
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")

hdata_get_var_hdata

WeeChat ≥ 0.3.6.

Return hdata for a variable in hdata.

Prototype:

const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

hdata for variable, NULL if no hdata or if an error occurred

C example:

weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));

Script (Python):

# prototype
def hdata_get_var_hdata(hdata: str, name: str) -> str: ...

# example
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))

hdata_get_var

WeeChat ≥ 0.3.6.

Return pointer to content of variable in hdata.

Prototype:

void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

pointer to content of variable, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");

Note	This function is not available in scripting API.

hdata_get_var_at_offset

WeeChat ≥ 0.3.6.

Return pointer to content of variable in hdata, using offset.

Prototype:

void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
offset: offset of variable

Return value:

pointer to content of variable, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);

Note	This function is not available in scripting API.

hdata_get_list

WeeChat ≥ 0.3.6.

Return list pointer from hdata.

Prototype:

void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: list name

Return value:

list pointer, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");

Script (Python):

# prototype
def hdata_get_list(hdata: str, name: str) -> str: ...

# example
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")

hdata_check_pointer

WeeChat ≥ 0.3.7, updated in 1.0.

Check if a pointer is valid for a hdata and a list pointer.

Prototype:

int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);

Arguments:

hdata: hdata pointer
list: list pointer; if NULL (WeeChat ≥ 1.0), the pointer is checked with the lists in hdata that have flag "check pointers" (see hdata_new_list), and if no such list exists, the pointer is considered as valid
pointer: pointer to check

Return value:

1 if pointer is in list, 0 if not found

C example:

/* check if a buffer pointer is valid */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* valid pointer */
}
else
{
    /* invalid pointer */
}

Script (Python):

# prototype
def hdata_check_pointer(hdata: str, list: str, pointer: str) -> int: ...

# example
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # valid pointer
    # ...
else:
    # invalid pointer
    # ...

hdata_move

WeeChat ≥ 0.3.6.

Move pointer to another element in list.

Prototype:

void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);

Arguments:

hdata: hdata pointer
pointer: pointer to a WeeChat/plugin object
count: number of jump(s) to execute (negative or positive integer, different from 0)

Return value:

pointer to element reached, NULL if element is not found (for example end of list), or if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* move to next buffer, 2 times */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* move to previous buffer */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);

Script (Python):

# prototype
def hdata_move(hdata: str, pointer: str, count: int) -> str: ...

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# move to next buffer, 2 times
buffer = weechat.hdata_move(hdata, buffer, 2)

# move to previous buffer
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)

hdata_search

WeeChat ≥ 0.4.1, updated in 3.4.

Search element in a list: the expression search is evaluated for each element in list, until element is found (or end of list).

Prototype:

void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search,
                            struct t_hashtable *pointers, struct t_hashtable *extra_vars,
                            struct t_hashtable *options, int move);

Arguments:

hdata: hdata pointer
pointer: pointer to a WeeChat/plugin object
search: expression to evaluate, default pointer in expression is the name of hdata (and this pointer changes for each element in list); for help on expression, see the WeeChat user’s guide / Command /eval ^↗
pointers: hashtable for call to function string_eval_expression
extra_vars: hashtable for call to function string_eval_expression
options: hashtable for call to function string_eval_expression
move: number of jump(s) to execute after unsuccessful search (negative or positive integer, different from 0)

Important

You must ensure the search expression is safe and does not include any user data. Such unsafe data must be given in the hashtable extra_vars and referenced by ${xxx} in the search expression (see the example below).

Return value:

pointer to element found, NULL if not found

C example:

struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get_list (hdata, "irc_servers");
struct t_hashtable *extra_vars = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);

/* search irc server with name "libera" */
weechat_hashtable_set (extra_vars, "server_name", "libera");
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${server_name}",
                                     NULL, extra_vars, NULL, 1);
if (server)
{
    /* ... */
}
weechat_hashtable_free (extra_vars);

Script (Python):

# prototype
def hdata_search(hdata: str, pointer: str, search: str,
                 pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str],
                 count: int) -> str: ...

# example
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# search irc server with name "libera"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${server_name}",
                              {}, {"server_name": "libera"}, {}, 1)
if server:
    # ...

hdata_char

WeeChat ≥ 0.3.7.

Return value of char variable in structure using hdata.

Prototype:

char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "char"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

char value of variable

C example:

weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));

Script (Python):

# prototype
def hdata_char(hdata: str, pointer: str, name: str) -> int: ...

# example
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))

hdata_integer

WeeChat ≥ 0.3.6.

Return value of integer variable in structure using hdata.

Prototype:

int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "integer"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

integer value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));

Script (Python):

# prototype
def hdata_integer(hdata: str, pointer: str, name: str) -> int: ...

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))

hdata_long

WeeChat ≥ 0.3.6.

Return value of "long" variable in structure using hdata.

Prototype:

long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "long"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

long value of variable

C example:

weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));

Script (Python):

# prototype
def hdata_long(hdata: str, pointer: str, name: str) -> int: ...

# example
weechat.prnt("", "longvar = %d" % weechat.hdata_long(hdata, pointer, "longvar"))

hdata_longlong

WeeChat ≥ 4.3.0.

Return value of "long long" variable in structure using hdata.

Prototype:

long long weechat_hdata_longlong (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "long long"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

long long value of variable

C example:

weechat_printf (NULL, "longlongvar = %lld", weechat_hdata_longlong (hdata, pointer, "longlongvar"));

Script (Python):

# prototype
def hdata_longlong(hdata: str, pointer: str, name: str) -> int: ...

# example
weechat.prnt("", "longlongvar = %d" % weechat.hdata_longlong(hdata, pointer, "longlongvar"))

hdata_string

WeeChat ≥ 0.3.6.

Return value of string variable in structure using hdata.

Prototype:

const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "string"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

string value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));

Script (Python):

# prototype
def hdata_string(hdata: str, pointer: str, name: str) -> str: ...

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))

hdata_pointer

WeeChat ≥ 0.3.6.

Return value of pointer variable in structure using hdata.

Prototype:

void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "pointer"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

pointer value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %p", weechat_hdata_pointer (hdata, buffer, "lines"));

Script (Python):

# prototype
def hdata_pointer(hdata: str, pointer: str, name: str) -> str: ...

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %x" % weechat.hdata_pointer(hdata, buffer, "lines"))

hdata_time

WeeChat ≥ 0.3.6.

Return value of time variable in structure using hdata.

Prototype:

time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "time"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

time value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
        }
    }
}

Script (Python):

# prototype
def hdata_time(hdata: str, pointer: str, name: str) -> int: ...

# example
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date))))

hdata_hashtable

WeeChat ≥ 0.3.7.

Return value of hashtable variable in structure using hdata.

Prototype:

struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "hashtable"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

hashtable value of variable (pointer to hashtable)

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d local variables in core buffer",
                weechat_hashtable_get_integer (hashtable, "items_count"));

Script (Python):

# prototype
def hdata_hashtable(hdata: str, pointer: str, name: str) -> Dict[str, str]: ...

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "local variables in core buffer:")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))

hdata_compare

WeeChat ≥ 1.9, updated in 4.1.0.

Compare a hdata variable of two objects.

Prototype:

int weechat_hdata_compare (struct t_hdata *hdata, void *pointer1, void *pointer2, const char *name, int case_sensitive);

Arguments:

hdata: hdata pointer
pointer1: pointer to first WeeChat/plugin object
pointer2: pointer to second WeeChat/plugin object
name: variable name or path to a variable name; for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"
case_sensitive: 1 for case-sensitive comparison of strings, otherwise 0

Return value:

-1 if variable1 < variable2
0 if variable1 == variable2
1 if variable1 > variable2

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("irc", "libera.#weechat-fr");
weechat_printf (NULL, "comparison of buffer number = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "number", 0));
weechat_printf (NULL, "comparison of number of lines = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "own_lines.lines_count", 0));
weechat_printf (NULL, "comparison of local variable = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "local_variables.myvar", 0));

Script (Python):

# prototype
def hdata_compare(hdata: str, pointer1: str, pointer2: str, name: str, case_sensitive: int) -> int: ...

# example
hdata = weechat.hdata_get("buffer")
buffer1 = weechat.buffer_search("irc", "libera.#weechat")
buffer2 = weechat.buffer_search("irc", "libera.#weechat-fr")
weechat.prnt("", "comparison of buffer number = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "number", 0))
weechat.prnt("", "comparison of number of lines = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "own_lines.lines_count", 0))
weechat.prnt("", "comparison of local variable = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "local_variables.myvar", 0))

hdata_set

WeeChat ≥ 0.3.9.

Set new value for variable in a hdata.

Note	This function can be called only in an update callback (see hdata_new and hdata_update), if the variable can be updated.

Prototype:

int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (types allowed: char, integer, long, string, pointer, time)
value: new value for variable

Return value:

1 if OK, 0 if error

C example:

weechat_hdata_set (hdata, pointer, "message", "test");

Note	This function is not available in scripting API.

hdata_update

WeeChat ≥ 0.3.9.

Update data in a hdata.

Prototype:

int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
hashtable: variables to update: keys are name of variables, values are new values for variables (keys and values are string), some special keys are allowed:
- key __create_allowed (with any value): return 1 if create is allowed for structure, otherwise 0 (WeeChat ≥ 0.4.0)
- key __delete_allowed (with any value): return 1 if delete is allowed for structure, otherwise 0
- key __update_allowed, value is name of a variable: return 1 if update is allowed for this variable, otherwise 0
- key __delete (with any value): delete structure (if allowed)

Return value:

number of variables updated

C example:

/* subtract one hour on last message displayed in current buffer */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}

Script (Python):

# prototype
def hdata_update(hdata: str, pointer: str, hashtable: Dict[str, str]) -> int: ...

# example: subtract one hour on last message displayed in current buffer
own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
        hdata = weechat.hdata_get("line_data")
        weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})

hdata_get_string

WeeChat ≥ 0.3.6.

Return string value of a hdata property.

Prototype:

const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);

Arguments:

hdata: hdata pointer
property: property name:
- var_keys: string with list of keys for variables in hdata (format: "key1,key2,key3")
- var_values: string with list of values for variables in hdata (format: "value1,value2,value3")
- var_keys_values: string with list of keys and values for variables in hdata (format: "key1:value1,key2:value2,key3:value3")
- var_prev: name of variable in structure which is a pointer to previous element in list
- var_next: name of variable in structure which is a pointer to next element in list
- list_keys: string with list of keys for lists in hdata (format: "key1,key2,key3")
- list_values: string with list of values for lists in hdata (format: "value1,value2,value3")
- list_keys_values: string with list of keys and values for lists in hdata (format: "key1:value1,key2:value2,key3:value3")

Return value:

string value of property

C example:

weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys"));

Script (Python):

# prototype
def hdata_get_string(hdata: str, property: str) -> str: ...

# example
weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))

3.26. Upgrade

Functions for upgrading WeeChat (command "/upgrade").

upgrade_new

Updated in 1.5.

Create or read a file for upgrade.

Prototype:

struct t_upgrade_file *upgrade_file_new (const char *filename,
                                         int (*callback_read)(const void *pointer,
                                                              void *data,
                                                              struct t_upgrade_file *upgrade_file,
                                                              int object_id,
                                                              struct t_infolist *infolist),
                                         const void *callback_read_pointer,
                                         void *callback_read_data);

Arguments:

filename: name of file (extension ".upgrade" is added to this name by WeeChat)
callback_read: function called for each object read in upgrade file (if NULL, the upgrade file is opened in write mode), arguments and return value:
- const void *pointer: pointer
- void *data: pointer
- struct t_upgrade_file *upgrade_file: pointer to upgrade file
- int object_id: object id
- struct t_infolist *infolist: infolist with content of object
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_read_pointer: pointer given to callback when it is called by WeeChat
callback_read_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the upgrade file is closed

Return value:

pointer to upgrade file

C example:

struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file",
                                                           NULL, NULL, NULL);

Script (Python):

# prototype
def upgrade_new(filename: str, callback_read: str, callback_read_data: str) -> str: ...

# example
upgrade_file = weechat.upgrade_new("my_file", "", "")

upgrade_write_object

Write an object in upgrade file.

Prototype:

int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);

Arguments:

upgrade_file: upgrade file pointer
object_id: id for object
infolist: infolist to write in file

Return value:

1 if OK, 0 if error

C example:

if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* OK */
}
else
{
    /* error */
}

Script (Python):

# prototype
def upgrade_write_object(upgrade_file: str, object_id: int, infolist: str) -> int: ...

# example
weechat.upgrade_write_object(upgrade_file, 1, infolist)

upgrade_read

Updated in 1.5.

Read an upgrade file.

Prototype:

int weechat_upgrade_read (struct t_upgrade_file *upgrade_file);

Arguments:

upgrade_file: upgrade file pointer

Return value:

1 if OK, 0 if error

C example:

weechat_upgrade_read (upgrade_file);

Script (Python):

# prototype
def upgrade_read(upgrade_file: str) -> int: ...

# example
weechat.upgrade_read(upgrade_file)

upgrade_close

Close an upgrade file.

Prototype:

void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);

Arguments:

upgrade_file: upgrade file pointer

C example:

weechat_upgrade_close (upgrade_file);

Script (Python):

# prototype
def upgrade_close(upgrade_file: str) -> int: ...

# example
weechat.upgrade_close(upgrade_file)