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

lua

4050

15

perl

4040

16

php

4030

17

python

4020

18

ruby

4010

19

tcl

4000

20

script

3000

21

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

Register the script.

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

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

string_tolower

Updated in 3.8.

Return a string with uppercase letters converted to lowercase.

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

string_toupper

Updated in 3.8.

Return a string with lowercase letters converted to uppercase.

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

string_charcasecmp

Updated in 1.0, 3.8.

Compare two chars, ignoring case.

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

strcasecmp

Updated in 1.0, 3.8.

Case insensitive string comparison.

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  */
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 { | } ~

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

strncasecmp

Updated in 1.0, 3.8.

Case insensitive string comparison, for max chars.

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 */
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 { | } ~

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

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

strcasestr

Updated in 1.3, 3.8.

Case insensitive string search.

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" */
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

Since version 1.0, wildcards are allowed inside the mask (not only beginning/end of mask).
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

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

  1. replace leading %h by a WeeChat directory (data by default),

  2. replace leading ~ by user home directory (call to string_expand_home),

  3. 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);
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);
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);
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 */
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)

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 */
    /* ... */
}
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);
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);
}
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");
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

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

C example:

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
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);
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);
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:

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
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=" */
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" */
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           "  */
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).

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 (1)

(1) 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 (1)

(1) 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 (1)

(1) ,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 (1)

>> ${color:*214}bold orange text
== bold orange text (2)

(1) In red
(2) 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 (1)

(1) 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);
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 */
}
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))
    {
        /* ... */
    }
}
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);
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)

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" */
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))
{
    /* ... */
}
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 */
}
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, '?');
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);
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);
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 */
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 */
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 */
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 */
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 */
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 */
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" */
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 potision (in bytes)

C example:

int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */
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 */
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);
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 */
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 */
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 */
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 */
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 */
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);
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);
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 */
}
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 */
}
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 */
}
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

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

C example:

long long diff = weechat_util_timeval_diff (&tv1, &tv2);
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)

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

C example:

weechat_util_timeval_add (&tv, 2000000);  /* add 2 seconds */
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));
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 */
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 */
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 */
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));
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);
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));
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 */
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);
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 */
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);
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);
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 */
}
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);
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);
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));
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");
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");
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 */
    /* ... */
}
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);
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

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);
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);
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");
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"));
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);
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"
*/
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"
*/
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");
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);
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);
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

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

lua.conf

4050

18

perl.conf

4040

19

php.conf

4030

20

python.conf

4020

21

ruby.conf

4010

22

tcl.conf

4000

23

script.conf

3000

24

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 can not 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,
    "", "",
    "", "",
    "", "")
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 */
}
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 */
}
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

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");
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");
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")
autoconect = 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

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.

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

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

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).
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)
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'")
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'")
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")
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")
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")
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")
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 calbacks */
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:

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

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

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

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

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