int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]);
This manual documents WeeChat chat client, it is part of WeeChat.
Latest version of this document can be found on this page: http://www.weechat.org/doc
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.
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.
The plugin must use some macros (to define some variables):
plugin name
short description of plugin
plugin version
plugin license
The plugin must use two functions:
weechat_plugin_init
weechat_plugin_end
This function is called when plugin is loaded by WeeChat.
Prototype:
int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]);
Arguments:
plugin: pointer to WeeChat plugin structure
argc: number of arguments for plugin (given on command line by user)
argv: arguments for plugin
Return value:
WEECHAT_RC_OK if successful (plugin will be loaded)
WEECHAT_RC_ERROR if error (plugin will NOT be loaded)
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
Compile does not need WeeChat sources, only file weechat-plugin.h is required.
To compile a plugin which has one file "toto.c" (under GNU/Linux):
$ gcc -fPIC -Wall -c toto.c $ gcc -shared -fPIC -o libtoto.so toto.o
Copy file libtoto.so into system plugins directory (for example /usr/local/lib/weechat/plugins) or into user’s plugins directory (for example /home/xxx/.weechat/plugins).
Under WeeChat:
/plugin load toto
Full example of plugin, which adds a command /double: displays two times arguments on current buffer, or execute two times a command (ok that’s not very useful, but that’s just an example!):
#include <stdlib.h> #include "weechat-plugin.h" WEECHAT_PLUGIN_NAME("double"); WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>"); WEECHAT_PLUGIN_VERSION("0.1"); WEECHAT_PLUGIN_LICENSE("GPL3"); struct t_weechat_plugin *weechat_plugin = NULL; /* callback for command "/double" */ int command_double_cb (void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* make C compiler happy */ (void) data; (void) buffer; (void) argv; if (argc > 1) { weechat_command (NULL, argv_eol[1]); weechat_command (NULL, argv_eol[1]); } return WEECHAT_RC_OK; } int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]) { weechat_plugin = plugin; weechat_hook_command ("double", "Display two times a message " "or execute two times a command", "message | command", "message: message to display two times\n" "command: command to execute two times", NULL, &command_double_cb, NULL); return WEECHAT_RC_OK; } int weechat_plugin_end (struct t_weechat_plugin *plugin) { /* make C compiler happy */ (void) plugin; return WEECHAT_RC_OK; }
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).
Functions to get infos about plugins.
Get plugin name.
Prototype:
const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);
Arguments:
plugin: pointer to WeeChat plugin structure (can be NULL)
Return value:
name of plugin, "core" for WeeChat core (if plugin pointer is NULL)
C example:
const char *name = weechat_plugin_get_name (plugin);
Script (Python):
# prototype name = weechat.plugin_get_name(plugin) # example plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin") name = weechat.plugin_get_name(plugin)
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.
Set new plugin charset (default charset is UTF-8, so if your plugin uses UTF-8, you don’t need to call this function).
Prototype:
void weechat_charset_set (const char *charset);
Arguments:
charset: new charset to use
C example:
weechat_charset_set (plugin, "iso-8859-1");
Script (Python):
# prototype weechat.charset_set(charset) # example weechat.charset_set("iso-8859-1")
Convert string to WeeChat internal charset (UTF-8).
Prototype:
char *weechat_iconv_to_internal (const char *charset, const char *string);
Arguments:
charset: charset to convert
string: string to convert
Return value:
converted string (must be freed by calling "free" after use)
C example:
char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à"); /* ... */ free (str);
Script (Python):
# prototype str = weechat.iconv_to_internal(charset, string) # example str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")
Convert string from internal WeeChat charset (UTF-8) to another.
Prototype:
char *weechat_iconv_from_internal (const char *charset, const char *string);
Arguments:
charset: target charset
string: string to convert
Return value:
converted string (must be freed by calling "free" after use)
C example:
char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à"); /* ... */ free (str);
Script (Python):
# prototype str = weechat.iconv_from_internal(charset, string) # example str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")
Return translated string (depends on local language).
Prototype:
const char *weechat_gettext (const char *string);
Arguments:
string: string to translate
Return value:
translated string
C example:
char *str = weechat_gettext ("hello");
Script (Python):
# prototype str = weechat.gettext(string) # example str = weechat.gettext("hello")
Return translated string, using single or plural form, according to count argument.
Prototype:
const char *weechat_ngettext (const char *string, const char *plural, int count);
Arguments:
string: string to translate, single form
plural: string to translate, plural form
count: used to choose between single and plural form (choice is made according to local language)
Return value:
translated string
C example:
char *str = weechat_ngettext ("file", "files", num_files);
Script (Python):
# prototype str = weechat.ngettext(string, plural, count) # example num_files = 2 str = weechat.ngettext("file", "files", num_files)
Return duplicated string, with length chars max.
Prototype:
char *weechat_strndup (const char *string, int length);
Arguments:
string: string to duplicate
length: max chars to duplicate
Return value:
duplicated string (must be freed by calling "free" after use)
C example:
char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */ /* ... */ free (str);
Convert UTF-8 string to lower case.
Prototype:
void weechat_string_tolower (const char *string);
Arguments:
string: string to convert
C example:
char *str = "AbCdé"; weechat_string_tolower (str); /* str is now: "abcdé" */
Convert UTF-8 string to upper case.
Prototype:
void weechat_string_toupper (const char *string);
Arguments:
string: string to convert
C example:
char *str = "AbCdé"; weechat_string_tolower (str); /* str is now: "ABCDé" */
Locale and case independent string comparison.
Prototype:
int weechat_strcasecmp (const char *string1, const char *string2);
Arguments:
string1: first string for comparison
string2: second string for comparison
Return value:
difference between two strings:
negative if string1 < string2
zero if string1 == string2
positive if string1 > string2
C example:
int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */
Locale (and optionally case independent) string comparison, ignoring some chars.
Prototype:
int weechat_strcmp_ignore_chars (const char *string1, const char *string2, const char *chars_ignored, int case_sensitive);
Arguments:
string1: first string for comparison
string2: second string for comparison
chars_ignored: string with chars to ignored
case_sensitive: 1 for case sensitive comparison, otherwise 0
Return value:
difference between two strings:
negative if string1 < string2
zero if string1 == string2
positive if string1 > string2
C example:
int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */
Locale and case independent string search.
Prototype:
char *weechat_strcasestr (const char *string, const char *search);
Arguments:
string: string
search: string to search in string
Return value:
pointer to string found, or NULL if not found
C example:
char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */
Check if a string matches a mask.
Prototype:
int weechat_string_match (const char *string, const char *mask, int case_sensitive);
Arguments:
string: string
mask: mask, can begin or end with "*" (no other "*" are allowed inside mask)
Return value:
1 if string matches mask, otherwise 0
C example:
int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */
Replace all occurences of a string by another string.
Prototype:
char *weechat_string_replace (const char *string, const char *search, const char *replace);
Arguments:
string: string
search: string to replace
replace: replacement for string search
Return value:
string with search replaced by replace (must be freed by calling "free" after use)
C example:
char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */ /* ... */ free (str);
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);
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);
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 */
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);
Split a string according to one or more delimiter(s).
Prototype:
char **weechat_string_split (const char *string, const char *separators, int keep_eol, int num_items_max, int *num_items);
Arguments:
string: string to split
separators: delimiters used for split
keep_eol: if different from 0, then each argument will contain all string until end of line (see example below)
num_items_max: maximum number of items created (0 = no limit)
num_items: pointer to int which will contain number of items created
Return value:
array of strings, NULL if problem (must be freed by calling [_weechat_string_free_split] after use)
Examples:
char **argv; int argc; argv = weechat_string_split ("abc de fghi", " ", 0, 0, &argc); /* result: argv[0] == "abc" argv[1] == "de" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_split (argv); argv = weechat_string_split ("abc de fghi", " ", 1, 0, &argc); /* result: argv[0] == "abc de fghi" argv[1] == "de fghi" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_split (argv);
Free memory used by a split string.
Prototype:
void weechat_string_free_split (char **split_string);
Arguments:
split_string: string split by function [_weechat_string_split]
C example:
char *argv; int argc; argv = weechat_string_split (string, " ", 0, 0, &argc); /* ... */ weechat_string_free_split (argv);
Build a string with a split string.
Prototype:
char *weechat_string_build_with_split_string (char **split_string, const char *separator);
Arguments:
split_string: string split by function [_weechat_string_split]
separator: string used to separate strings
Return value:
string built with split string (must be freed by calling "free" after use)
C example:
char **argv; int argc; argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc); char *str = weechat_string_build_with_split_string (argv, ";"); /* str == "abc;def;ghi" */ /* ... */ free (str);
Split a list of commands separated by separator (which can be escaped by "\" in string).
Prototype:
char **weechat_string_split_command (const char *command, char separator);
Arguments:
command: command to split
separator: separator
Return value:
array of strings, NULL if problem (must be freed by calling [_weechat_free_split_command] after use)
C example:
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';'); /* result: argv[0] == "/command1 arg" argv[1] == "/command2" */ weechat_free_split_command (argv);
Free memory used by a split command.
Prototype:
void weechat_string_free_split_command (char **split_command);
Arguments:
split_command: command split by [_weechat_string_split_command]
C example:
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';'); /* ... */ weechat_free_split_command (argv);
Build a string with formatted file size and a unit translated to local language.
Prototype:
char *weechat_string_format_size (unsigned long size);
Arguments:
size: size (in bytes)
Return value:
formatted string (must be freed by calling "free" after use)
Examples:
/* examples with english locale */ char *str = weechat_string_format_size (0); /* str == "0 byte" */ /* ... */ free (str); char *str = weechat_string_format_size (200); /* str == "200 bytes" */ /* ... */ free (str); char *str = weechat_string_format_size (1536); /* str == "1.5 KB" */ /* ... */ free (str); char *str = weechat_string_format_size (2097152); /* str == "2 MB" */ /* ... */ free (str);
Remove WeeChat colors from a string.
Prototype:
char *weechat_string_remove_color (const char *string, const char *replacement);
Arguments:
string: string
replacement: if not NULL and not empty, WeeChat color codes are replaced by first char of this string, otherwise WeeChat color codes and following chars (if related to color) are removed from string
Return value:
string without color (must be freed by calling "free" after use)
Examples:
/* remove color codes */ char *str = weechat_string_remove_color (my_string1, NULL); /* ... */ free (str); /* replace color codes by "?" */ char *str = weechat_string_remove_color (my_string2, "?"); /* ... */ free (str);
Script (Python):
# prototype str = weechat.string_remove_color(string, replacement) # example str = weechat.string_remove_color(my_string, "?")
Some UTF-8 string functions.
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)) { /* ... */ }
Check if a string is UTF-8 valid.
Prototype:
int weechat_utf8_is_valid (const char *string, char **error);
Arguments:
string: string
error: if not NULL, error is set with pointer to first non valid UTF-8 char in string, if any
Return value:
1 if UTF-8 string is valid, otherwise 0
C example:
char *error; if (weechat_utf8_is_valid (string, &error)) { /* ... */ } else { /* "error" points to first invalid char */ }
Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char.
Prototype:
void weechat_utf8_normalize (const char *string, char replacement);
Arguments:
string: string
replacement: replacement char for invalid chars
C example:
weechat_utf8_normalize (string, '?');
Return pointer to previous UTF-8 char in a string.
Prototype:
char *weechat_utf8_prev_char (const char *string_start, const char *string);
Arguments:
string_start: start of string (function will not return a char before this pointer)
string: pointer to string (must be > = string_start)
Return value:
pointer to previous UTF-8 char, NULL if not found (start of string reached)
C example:
char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
Return pointer to next UTF-8 char in a string.
Prototype:
char *weechat_utf8_next_char (const char *string);
Arguments:
string: string
Return value:
pointer to next UTF-8 char, NULL if not found (end of string reached)
C example:
char *next_char = weechat_utf8_next_char (string);
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 */
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 */
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 */
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 */
Compare two UTF-8 chars, ignoring case.
Prototype:
int weechat_utf8_charcasecmp (const char *string1, const char *string2);
Arguments:
string1: first string for comparison
string2: second string for comparison
Return value:
difference between first char of each string:
negative if char1 < char2
zero if char1 == char2
positive if char1 > char2
C example:
int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */
Return number of chars needed on screen to display UTF-8 char.
Prototype:
int weechat_utf8_char_size_screen (const char *string);
Arguments:
string: string
Return value:
number of chars needed on screen to display UTF-8 char
C example:
int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */
Move forward N chars in an UTF-8 string.
Prototype:
char *weechat_utf8_add_offset (const char *string, int offset);
Arguments:
string: string
offset: number of chars
Return value:
pointer to string, N chars after (NULL if it’s not reachable)
C example:
char *str = "chêne"; char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */
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 */
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 */
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);
Some functions related to directories.
Create a directory in WeeChat home.
Prototype:
int weechat_mkdir_home (char *directory, int mode);
Arguments:
directory: name of directory to create
mode: mode for directory
Return value:
1 if directory was successfully created, 0 if an error occured
C example:
if (!weechat_mkdir_home ("temp", 0755)) { /* error */ }
Script (Python):
# prototype weechat.mkdir_home(directory, mode) # example weechat.mkdir_home("temp", 0755)
Create a directory.
Prototype:
int weechat_mkdir (char *directory, int mode);
Arguments:
directory: name of directory to create
mode: mode for directory
Return value:
1 if directory was successfully created, 0 if an error occured
C example:
if (!weechat_mkdir ("/tmp/mydir", 0755)) { /* error */ }
Script (Python):
# prototype weechat.mkdir(directory, mode) # example weechat.mkdir("/tmp/mydir", 0755)
Create a directory and make parent directories as needed.
Prototype:
int weechat_mkdir_parents (char *directory, int mode);
Arguments:
directory: name of directory to create
mode: mode for directory
Return value:
1 if directory was successfully created, 0 if an error occured
C example:
if (!weechat_mkdir_parents ("/tmp/my/dir", 0755)) { /* error */ }
Script (Python):
# prototype weechat.mkdir_parents(directory, mode) # example weechat.mkdir_parents("/tmp/my/dir", 0755)
Find files in a directory and execute a callback on each file.
Prototype:
void weechat_exec_on_files (const char *directory, int hidden_files, void *data, void (*callback)(void *data, const char *filename));
Arguments:
directory: directory for searching files
hidden_files: 1 to include hidden files, otherwise 0
data: pointer given to callback when it is called by WeeChat
callback: function called for each file found, arguments:
void *data: pointer
const char *filename: filename found
C example:
void callback (void *data, const char *filename) { /* ... */ } ... weechat_exec_on_files ("/tmp", 0, NULL, &callback);
Some useful functions.
Compare two "timeval" structures.
Prototype:
int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2);
Arguments:
tv1: first "timeval" structure
tv2: second "timeval" structure
Return value:
-1 if tv1 < tv2
zero if tv1 == tv2
+1 if tv1 > tv2
C example:
if (weechat_timeval_cmp (&tv1, &tv2) > 0) { /* tv1 > tv2 */ }
Return difference (in milliseconds) between two "timeval" structures.
Prototype:
long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2);
Arguments:
tv1: first "timeval" structure
tv2: second "timeval" structure
Return value:
difference in milliseconds
C example:
long diff = weechat_timeval_diff (&tv1, &tv2);
Add interval (in milliseconds) to a timeval structure.
Prototype:
void weechat_timeval_add (struct timeval *tv, long interval);
Arguments:
tv: timeval structure
interval: interval (in milliseconds)
C example:
weechat_timeval_add (&tv, 2000); /* add 2 seconds */
Sorted list functions.
Create a new list.
Prototype:
struct t_weelist *weechat_list_new ();
Return value:
pointer to new list
C example:
struct t_weelist *list = weechat_list_new ();
Script (Python):
# prototype list = weechat.list_new() # example list = weechat.list_new()
Add an item in a list.
Prototype:
struct t_weelist_item *weechat_list_add (struct t_weelist *weelist, const char *data, const char *where, void *user_data);
Arguments:
weelist: list pointer
data: data to insert in list
where: position in list:
WEECHAT_LIST_POS_SORT: add in list, keeping list sorted
WEECHAT_LIST_POS_BEGINNING: add to beginning of list
WEECHAT_LIST_POS_END: add to end of list
user_data: any pointer
Return value:
pointer to new item
C example:
struct t_weelist_item *my_item = weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);
Script (Python):
# prototype item = weechat.list_add(list, data, where, user_data) # example item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")
Search an item in a list.
Prototype:
struct t_weelist_item *weechat_list_search (struct t_weelist *weelist, const char *data);
Arguments:
weelist: list pointer
data: data to search in list
Return value:
pointer to item found, NULL if item was not found
C example:
struct t_weelist_item *item = weechat_list_search (list, "my data");
Script (Python):
# prototype item = weechat.list_search(list, data) # example item = weechat.list_search(list, "my data")
Search an item in a list, ignoring case.
Prototype:
struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist, const char *data);
Arguments:
weelist: list pointer
data: data to search in list
Return value:
pointer to item found, NULL if item was not found
C example:
struct t_weelist_item *item = weechat_list_casesearch (list, "my data");
Script (Python):
# prototype item = weechat.list_casesearch(list, data) # example item = weechat.list_casesearch(list, "my data")
Return an item in a list by position.
Prototype:
struct t_weelist_item *weechat_list_get (struct t_weelist *weelist, int position);
Arguments:
weelist: list pointer
position: position in list (first item is 0)
Return value:
pointer to item found, NULL if item was not found
C example:
struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */
Script (Python):
# prototype item = weechat.list_get(list, position) # example item = weechat.list_get(list, 0)
Set new value for an item.
Prototype:
void weechat_list_set (struct t_weelist_item *item, const char *value);
Arguments:
item: item pointer
value: new value for item
C example:
weechat_list_set (item, "new data");
Script (Python):
# prototype weechat.list_set(item, value) # example weechat.list_set(item, "new data")
Return next item in list.
Prototype:
struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);
Arguments:
item: item pointer
Return value:
pointer to next item, NULL if pointer was last item in list
C example:
struct t_weelist_item *next_item = weechat_list_next (item);
Script (Python):
# prototype item = weechat.list_next(item) # example item = weechat.list_next(item)
Return previous item in list.
Prototype:
struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);
Arguments:
item: item pointer
Return value:
pointer to previous item, NULL if pointer was last item in list
C example:
struct t_weelist_item *prev_item = weechat_list_prev (item);
Script (Python):
# prototype item = weechat.list_prev(item) # example item = weechat.list_prev(item)
Return string value of an item.
Prototype:
const char *weechat_list_string (struct t_weelist_item *item);
Arguments:
item: item pointer
Return value:
string value of item
C example:
weechat_printf (NULL, "value of item: %s", weechat_list_string (item));
Script (Python):
# prototype value = weechat.list_string(item) # example weechat.prnt("", "value of item: %s" % weechat.list_string(item))
Return size of list (number of items).
Prototype:
char *weechat_list_size (struct t_weelist *weelist);
Arguments:
weelist: list pointer
Return value:
size of list (number of items), 0 if list is empty
C example:
weechat_printf (NULL, "size of list: %d", weechat_list_size (list));
Script (Python):
# prototype size = weechat.list_size(list) # example weechat.prnt("", "size of list: %d" % weechat.list_size(list))
Remove an item in a list.
Prototype:
void weechat_list_remove (struct t_weelist *weelist, struct t_weelist_item *item);
Arguments:
weelist: list pointer
item: item pointer
C example:
weechat_list_remove (list, item);
Script (Python):
# prototype weechat.list_remove(list, item) # example weechat.list_remove(list, item)
Remove all items in a list.
Prototype:
void weechat_list_remove_all (struct t_weelist *weelist);
Arguments:
weelist: list pointer
C example:
weechat_list_remove_all (list);
Script (Python):
# prototype weechat.list_remove_all(list) # example weechat.list_remove_all(list)
Free a list.
Prototype:
void weechat_list_free (struct t_weelist *weelist);
Arguments:
weelist: list pointer
C example:
weechat_list_free (list);
Script (Python):
# prototype weechat.list_free(list) # example weechat.list_free(list)
Functions for configuration files.
Create a new configuration file.
Prototype:
struct t_config_file *weechat_config_new (const char *name, int (*callback_reload)(void *data, struct t_config_file *config_file), void *callback_reload_data);
Arguments:
name: name of configuration file (without path or extension)
callback_reload: function called when configuration file is reloaded with /reload (optional, can be NULL), arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
callback_reload_data: pointer given to reload callback when it is called by WeeChat
Return value:
pointer to new configuration file, NULL if an error occured
Note
|
File is NOT created on disk by this function. It will be created by call to function [_weechat_write_config]. You should call this function only after adding some sections (with [_weechat_config_new_section]) and options (with [_weechat_config_new_option]). |
C example:
int my_config_reload_cb (void *data, struct t_config_file *config_file) { /* ... */ return WEECHAT_RC_OK; } struct t_config_file *config_file = weechat_config_new ("test", &my_config_reload_cb, NULL);
Script (Python):
# prototype config_file = weechat.config_new(name, calback_reload, callback_reload_data) # example def my_config_reload_cb(data, config_file): # ... return weechat.WEECHAT_RC_OK config_file = weechat.config_new("test", "my_config_reload_cb", "")
Create a new section in configuration file.
Prototype:
struct t_config_section *weechat_config_new_section ( struct t_config_file *config_file, const char *name, int user_can_add_options, int user_can_delete_options, int (*callback_read)(void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value), void *callback_read_data, int (*callback_write)(void *data, struct t_config_file *config_file, const char *section_name), void *callback_write_data, int (*callback_write_default)(void *data, struct t_config_file *config_file, const char *section_name); void *callback_write_default_data, int (*callback_create_option)(void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value), void *callback_create_option_data, int (*callback_delete_option)(void *data, struct t_config_file *config_file, struct t_config_section *section, struct t_config_option *option), void *callback_delete_option_data);
Arguments:
config_file: configuration file pointer
name: name of section
user_can_add_options: 1 if user can create new options in section, or 0 if it is forbidden
user_can_delete_options: 1 if user can delete options in section, or 0 if it is forbidden
callback_read: function called when an option in section is read from disk (should be NULL in most cases, except if options in section need custom function), arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
struct t_config_section *section: section pointer
const char *option_name: name of option
const char *value: value
callback_read_data: pointer given to callback when it is called by WeeChat
callback_write: function called when section is written in file (should be NULL for most cases, except if section needs to be written by a custom function), arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
struct t_config_section *section: section pointer
const char *option_name: name of option
callback_write_data: pointer given to callback when it is called by WeeChat
callback_write_default: function called when default values for section must be written in file, arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
const char *section_name: name of section
callback_write_default_data: pointer given to callback when it is called by WeeChat
callback_create_option: function called when a new option is created in section (NULL if section does not allow new options to be created), arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
struct t_config_section *section: section pointer
const char *option_name: name of option
const char *value: value
callback_create_option_data: pointer given to callback when it is called by WeeChat
callback_delete_option: function called when an option is deleted in section (NULL if section does not allow options to be deleted), arguments:
void *data: pointer
struct t_config_file *config_file: configuration file pointer
struct t_config_section *section: section pointer
struct t_config_option *option: option pointer
callback_delete_option_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new section in configuration file, NULL if an error occured
C example:
int my_section_read_cb (void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value) { /* ... */ return WEECHAT_RC_OK; } int my_section_write_cb (void *data, struct t_config_file *config_file, const char *section_name) { /* ... */ return WEECHAT_RC_OK; } int my_section_write_default_cb (void *data, struct t_config_file *config_file, const char *section_name) { /* ... */ return WEECHAT_RC_OK; } int my_section_create_option_cb (void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value) { /* ... */ return WEECHAT_RC_OK; } int my_section_delete_option_cb (void *data, struct t_config_file *config_file, struct t_config_section *section, struct t_config_option *option) { /* ... */ return WEECHAT_RC_OK; } /* standard section, user can not add/delete options */ struct t_config_section *new_section1 = weechat_config_new_section (config_file, "section1", 0, 0, NULL, NULL, /* read callback */ NULL, NULL, /* write callback */ NULL, NULL, /* write default callback */ NULL, NULL, /* create option callback */ NULL, NULL); /* delete option callback */ /* special section, user can add/delete options, and options need callback to be read/written */ struct t_config_section *new_section2 = weechat_config_new_section (config_file, "section2", 1, 1, &my_section_read_cb, NULL, &my_section_write_cb, NULL, &my_section_write_default_cb, NULL, &my_section_create_option_cb, NULL, &my_section_delete_option_cb, NULL);
Script (Python):
# prototype section = weechat.config_new_section(config_file, name, user_can_add_options, user_can_delete_options, callback_read, callback_read_data, callback_write, callback_write_data, callback_create_option, callback_create_option_data, callback_delete_option, callback_delete_option_data) # example def my_section_read_cb(data, config_file, section, option_name, value): # ... return weechat.WEECHAT_RC_OK def my_section_write_cb(data, config_file, section_name): # ... return weechat.WEECHAT_RC_OK def my_section_write_default_cb(data, config_file, section_name): # ... return weechat.WEECHAT_RC_OK def my_section_create_option_cb(data, config_file, section, option_name, value): # ... return weechat.WEECHAT_RC_OK def my_section_delete_option_cb(data, config_file, section, option): # ... return weechat.WEECHAT_RC_OK section = weechat.config_new_section(config_file, "section1", 1, 1, "my_section_read_cb", "", "my_section_write_cb", "", "my_section_write_default_cb", "", "my_section_create_option_cb", "", "my_section_delete_option_cb", "")
Search a section in a configuration file.
Prototype:
struct t_config_section *weechat_config_search_section ( struct t_config_file *config_file, const char *section_name);
Arguments:
config_file: configuration file pointer
section_name: name of section to search
Return value:
pointer to section found, NULL if section was not found
C example:
struct t_config_section *section = weechat_config_search_section (config_file, "section");
Script (Python):
# prototype section = weechat.config_search_section(config_file, section_name) # example section = weechat.config_search_section(config_file, "section")
Create a new option in a section of a configuration file.
Prototype:
struct t_config_option *weechat_config_new_option ( struct t_config_file *config_file, struct t_config_section *section, const char *name, const char *type, const char *description, const char *string_values, int min, int max, const char *default_value, const char *value, int null_value_allowed, int (*callback_check_value)(void *data, struct t_config_option *option, const char *value), void *callback_check_value_data, int (*callback_change)(void *data, struct t_config_option *option), void *callback_change_data, int (*callback_delete)(void *data, struct t_config_option *option), void *callback_delete_data);
Arguments:
config_file: configuration file pointer
section: section pointer
name: name of option
type: type of option:
boolean: boolean value (on/off)
integer: integer value (with optional strings for values)
string: string value
color: color
description: description of option
string_values: values as string (separated by "|"), used for type integer (optional)
min: minimum value (for type integer)
max: maximum value (for type integer)
default_value: default value for option (used when option is reset)
value: value for option
null_value_allowed: 1 if null (undefined value) is allowed for option, otherwise 0
callback_check_value: function called to check new value for option (optional), arguments:
void *data: pointer
struct t_config_option *option: option pointer
const char *value: new value for option
callback_check_value_data: pointer given to check_value callback when it is called by WeeChat
callback_change: function called when value of option has changed (optional), arguments:
void *data: pointer
struct t_config_option *option: option pointer
callback_change_data: pointer given to change callback when it is called by WeeChat
callback_delete: function called when option will be deleted (optional), arguments:
void *data: pointer
struct t_config_option *option: option pointer
callback_delete_data: pointer given to delete callback when it is called by WeeChat
Return value:
pointer to new option in section, NULL if an error
C example:
/* boolean */ struct t_config_option *option1 = weechat_config_new_option (config_file, section, "option1", "boolean", "My option, type boolean" NULL, /* string values */ 0, 0, /* min, max */ "on", /* default */ "on", /* value */ 0, /* null value allowed */ NULL, NULL, /* check callback */ NULL, NULL, /* change callback */ NULL, NULL); /* delete callback */ /* integer */ struct t_config_option *option2 = weechat_config_new_option (config_file, section, "option2", "integer", "My option, type integer" NULL, /* string values */ 0, 100, /* min, max */ "15", /* default */ "15", /* value */ 0, /* null value allowed */ NULL, NULL, /* check callback */ NULL, NULL, /* change callback */ NULL, NULL); /* delete callback */ /* integer (with string values) */ struct t_config_option *option3 = weechat_config_new_option (config_file, section, "option3", "integer", "My option, type integer (with string values)" "top|bottom|left|right", /* string values */ 0, 0, /* min, max */ "bottom", /* default */ "bottom", /* value */ 0, /* null value allowed */ NULL, NULL, /* check callback */ NULL, NULL, /* change callback */ NULL, NULL); /* delete callback */ /* string */ struct t_config_option *option4 = weechat_config_new_option (config_file, section, "option4", "string", "My option, type string" NULL, /* string values */ 0, 0, /* min, max */ "test", /* default */ "test", /* value */ 1, /* null value allowed */ NULL, NULL, /* check callback */ NULL, NULL, /* change callback */ NULL, NULL); /* delete callback */ /* color */ struct t_config_option *option5 = weechat_config_new_option (config_file, section, "option5", "color", "My option, type color" NULL, /* string values */ 0, 0, /* min, max */ "lightblue", /* default */ "lightblue", /* value */ 0, /* null value allowed */ NULL, NULL, /* check callback */ NULL, NULL, /* change callback */ NULL, NULL); /* delete callback */
Script (Python):
# prototype option = weechat.config_new_option(config_file, section, name, type, description, string_values, min, max, default_value, value, null_value_allowed, callback_check_value, callback_check_value_data, callback_change, callback_change_data, callback_delete, callback_delete_data) # example def option4_check_value_cb(data, option, value): # ... return weechat.WEECHAT_RC_OK def option4_change_cb(data, option): # ... return weechat.WEECHAT_RC_OK def option4_delete_cb(data, option): # ... return weechat.WEECHAT_RC_OK option1 = weechat.config_new_option(config_file, section, "option1", "boolean", "My option, type boolean", "", 0, 0, "on", "on", 0, "", "", "", "", "", "") option2 = weechat.config_new_option(config_file, section, "option2", "integer", "My option, type integer", "", 0, 100, "15", "15", 0, "", "", "", "", "", "") option3 = weechat.config_new_option(config_file, section, "option3", "integer", "My option, type integer (with string values)", "top|bottom|left|right", 0, 0, "bottom", "bottom", 0, "", "", "", "", "", "") option4 = weechat.config_new_option(config_file, section, "option4", "string", "My option, type string", "", 0, 0, "test", "test", 1, "option4_check_value_cb", "" "option4_change_cb", "", "option4_delete_cb", "") option5 = weechat.config_new_option(config_file, section, "option5", "color", "My option, type color", "", 0, 100, "lightblue", "lightblue", 0, "", "", "", "", "", "")
Search an option in a section of a configuration file.
Prototype:
struct t_config_option *weechat_config_search_option ( struct t_config_file *config_file, struct t_config_section *section, const char *option_name);
Arguments:
config_file: configuration file pointer
section: section pointer
name: name of option to search
Return value:
pointer to option found, NULL if option was not found
C example:
struct t_config_option *option = weechat_config_search_option (config_file, section, "option");
Script (Python):
# prototype option = weechat.config_search_option(config_file, section, option_name) # example option = weechat.config_search_option(config_file, section, "option")
Search an option with full name.
Prototype:
void weechat_config_search_with_string (const char *option_name, struct t_config_file **config_file, struct t_config_section **section, struct t_config_option **option);
Arguments:
option_name: full option name (format: "file.section.option")
config_file: pointer to configuration file pointer, will be set with pointer to configuration file of option found
section: pointer to section pointer, will be set to section of option, if found
option: pointer to an option pointer, will be set to option pointer, if found
C example:
struct t_config_file *ptr_config_file; struct t_config_section *ptr_section; struct t_config_option *ptr_option; weechat_config_search_with_string ("file.section.option", &ptr_config_file, &ptr_section, &ptr_option); if (ptr_option) { /* option found */ } else { /* option not found */ }
Check if a text is "true" or "false", as boolean value.
Prototype:
int weechat_config_string_to_boolean (const char *text);
Arguments:
text: text to analyze
Return value:
1 if text is "true" ("on", "yes", "y", "true", "t", "1")
0 if text is "false" ("off", "no", "n", "false", "f", "0")
C example:
if (weechat_config_string_to_boolean (option_value)) { /* value is "true" */ } else { /* value is "false" */ }
Script (Python):
# prototype value = weechat.config_string_to_boolean(text) # example if weechat.config_string_to_boolean(text): # ...
Reset an option to its default value.
Prototype:
int weechat_config_option_reset (struct t_config_option *option, int run_callback);
Arguments:
option: option pointer
run_callback: 1 for calling callback if value of option is changed, otherwise 0
Return value:
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been reset
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured
C example:
switch (weechat_config_option_reset (option, 1)) { case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_ERROR: /* .... */ break; }
Script (Python):
# prototype rc = weechat.config_option_reset(option, run_callback) # example rc = weechat.config_option_reset(option, 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ...
Set new value for an option.
Prototype:
int weechat_config_option_set (struct t_config_option *option, const char *value, int run_callback);
Arguments:
option: option pointer
value: new value for option
run_callback: 1 for calling chang callback if value of option is changed, otherwise 0
Return value:
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured
C example:
switch (weechat_config_option_set (option, "new_value", 1)) { case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_ERROR: /* .... */ break; }
Script (Python):
# prototype rc = weechat.config_option_set(option, value, run_callback) # example rc = weechat.config_option_set(option, "new_value", 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ...
Set null (undefined value) for an option.
Prototype:
int weechat_config_option_set_null (struct t_config_option *option, int run_callback);
Arguments:
option: option pointer
run_callback: 1 for calling chang callback if value of option is changed (if it was not null), otherwise 0
Note
|
You can set value to null only if it is allowed for option (see [_weechat_config_new_option]). |
Return value:
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured
C example:
switch (weechat_config_option_set_null (option, 1)) { case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: /* .... */ break; case WEECHAT_CONFIG_OPTION_SET_ERROR: /* .... */ break; }
Script (Python):
# prototype rc = weechat.config_option_set_null(option, run_callback) # example rc = weechat.config_option_set_null(option, 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ...
Unset/reset option.
Prototype:
int weechat_config_option_unset (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET if option value has not been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET if option value has been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED if option has been removed
WEECHAT_CONFIG_OPTION_UNSET_ERROR if an error occured
C example:
switch (weechat_config_option_unset (option)) { case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: /* .... */ break; case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: /* .... */ break; case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: /* .... */ break; case WEECHAT_CONFIG_OPTION_UNSET_ERROR: /* .... */ break; }
Script (Python):
# prototype rc = weechat.config_option_unset(option) # example rc = weechat.config_option_unset(option) if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR: # ...
Rename an option.
Prototype:
void weechat_config_option_rename (struct t_config_option *option, const char *new_name);
Arguments:
option: option pointer
new_name: new name for option
C example:
weechat_config_option_rename (option, "new_name");
Script (Python):
# prototype weechat.config_option_rename(option, new_name) # example weechat.config_option_rename(option, "new_name")
Return a pointer on an option property.
Prototype:
void *weechat_config_option_get_pointer (struct t_config_option *option, const char *property);
Arguments:
option: option pointer
property: property name:
config_file: configuration file pointer (struct t_config_file *)
section: section pointer (struct t_config_section *)
name: option name (char *)
type: option type (int *)
description: option description (char *)
string_values: string values (char *)
min: minimum value (int *)
max: maximum value (int *)
default_value: default value (depends on type)
value: current value (depends on type)
prev_option: previous option pointer (struct t_config_option *)
next_option: next option pointer (struct t_config_option *)
Return value:
pointer to property asked
C example:
char *description = weechat_config_option_get_pointer (option, "description");
Check if an option is "null" (undefined value).
Prototype:
int weechat_config_option_is_null (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
1 if value of option is "null"
0 if value of option is not "null"
C example:
if (weechat_config_option_is_null (option)) { /* value is "null" */ } else { /* value is not "null" */ }
Script (Python):
# prototype weechat.config_option_is_null(option) # example if weechat.config_option_is_null(option): # ...
Check if default value for an option is "null" (undefined value).
Prototype:
int weechat_config_option_default_is_null (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
1 if default value of option is "null"
0 if default value of option is not "null"
C example:
if (weechat_config_option_default_is_null (option)) { /* default value is "null" */ } else { /* default value is not "null" */ }
Script (Python):
# prototype weechat.config_option_default_is_null(option) # example if weechat.config_option_default_is_null(option): # ...
Return boolean value of option.
Prototype:
int weechat_config_boolean (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
boolean value of option (0 or 1)
C example:
if (weechat_config_boolean (option)) { /* value is "true" */ } else { /* value is "false" */ }
Script (Python):
# prototype value = weechat.config_option_boolean(option) # example if weechat.config_option_boolean(option): # ...
Return default boolean value of option.
Prototype:
int weechat_config_boolean_default (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
default boolean value of option (0 or 1)
C example:
if (weechat_config_boolean_default (option)) { /* value is "true" */ } else { /* value is "false" */ }
Script (Python):
# prototype value = weechat.config_option_boolean_default(option) # example if weechat.config_option_boolean_default(option): # ...
Return integer value of option.
Prototype:
int weechat_config_integer (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
integer value of option
C example:
int value = weechat_config_integer (option);
Script (Python):
# prototype value = weechat.config_option_integer(option) # example if weechat.config_option_integer(option): # ...
Return default integer value of option.
Prototype:
int weechat_config_integer_default (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
default integer value of option
C example:
int value = weechat_config_integer_default (option);
Script (Python):
# prototype value = weechat.config_option_integer_default(option) # example if weechat.config_option_integer_default(option): # ...
Return string value of option.
Prototype:
const char *weechat_config_string (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
string value of option
C example:
const char *value = weechat_config_string (option);
Script (Python):
# prototype value = weechat.config_option_string(option) # example value = weechat.config_option_string(option):
Return default string value of option.
Prototype:
const char *weechat_config_integer_default (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
default string value of option
C example:
const char *value = weechat_config_string_default (option);
Script (Python):
# prototype value = weechat.config_option_string_default(option) # example value = weechat.config_option_string_default(option):
Return color value of option.
Prototype:
const char *weechat_config_color (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
color value of option (string with name of color)
C example:
const char *color = weechat_config_color (option);
Script (Python):
# prototype value = weechat.config_option_color(option) # example value = weechat.config_option_color(option):
Return default color value of option.
Prototype:
const char *weechat_config_color_default (struct t_config_option *option);
Arguments:
option: option pointer
Return value:
default color value of option (string with name of color)
C example:
const char *color = weechat_config_color_default (option);
Script (Python):
# prototype value = weechat.config_option_color_default(option) # example value = weechat.config_option_color_default(option):
Write a line in a configuration file with option and its value (this function should be called only in "write" or "write_default" callbacks for a section).
Prototype:
void weechat_config_write_option (struct t_config_file *config_file, struct t_config_option *option);
Arguments:
config_file: configuration file pointer
option: option pointer
C example:
int my_section_write_cb (void *data, struct t_config_file *config_file, const char *section_name) { weechat_config_write_line (config_file, "my_section", NULL); weechat_config_write_option (config_file, option); return WEECHAT_RC_OK; }
Script (Python):
# prototype weechat.config_write_option(config_file, option) # example def my_section_write_cb(data, config_file, section_name): weechat.config_write_line(config_file, "my_section", "") weechat.config_write_option(config_file, option) return weechat.WEECHAT_RC_OK
Write a line in a configuration file (this function should be called only in "write" or "write_default" callbacks for a section).
Prototype:
void weechat_config_write_line (struct t_config_file *config_file, const char *option_name, const char *value, ...);
Arguments:
config_file: configuration file pointer
option_name: option name
value: value (if NULL, then line with section name is written, for example: "[section]")
C example:
int my_section_write_cb (void *data, struct t_config_file *config_file, const char *section_name) { weechat_config_write_line (config_file, "my_section", NULL); weechat_config_write_line (config_file, "option", "%s;%d", "value", 123); return WEECHAT_RC_OK; }
Script (Python):
# prototype weechat.config_write_line(config_file, option_name, value) # example def my_section_write_cb(data, config_file, section_name): weechat.config_write_line(config_file, "my_section", "") weechat.config_write_line(config_file, "option", "value") return weechat.WEECHAT_RC_OK
Write configuration file to disk.
Prototype:
int weechat_config_write (struct t_config_file *config_file);
Arguments:
config_file: configuration file pointer
Return value:
WEECHAT_CONFIG_WRITE_OK if configuration was written
WEECHAT_CONFIG_WRITE_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_WRITE_ERROR if another error occured
C example:
switch (weechat_config_write (config_file)) { case WEECHAT_CONFIG_WRITE_OK: /* ... */ break; case WEECHAT_CONFIG_WRITE_MEMORY_ERROR: /* ... */ break; case WEECHAT_CONFIG_WRITE_ERROR: /* ... */ break; }
Script (Python):
# prototype rc = weechat.config_write(config_file) # example rc = weechat.config_write(config_file) if rc == weechat.WEECHAT_CONFIG_WRITE_OK: # ... elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR: # ...
Read configuration file from disk.
Prototype:
int weechat_config_read (struct t_config_file *config_file);
Arguments:
config_file: configuration file pointer
Return value:
WEECHAT_CONFIG_READ_OK if configuration was loaded
WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found
C example:
switch (weechat_config_read (config_file)) { case WEECHAT_CONFIG_READ_OK: /* ... */ break; case WEECHAT_CONFIG_READ_MEMORY_ERROR: /* ... */ break; case WEECHAT_CONFIG_READ_FILE_NOT_FOUND: /* ... */ break; }
Script (Python):
# prototype rc = weechat.config_read(config_file) # example rc = weechat.config_read(config_file) if rc == weechat.WEECHAT_CONFIG_READ_OK: # ... elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND: # ...
Reload configuration file from disk.
Prototype:
int weechat_config_reload (struct t_config_file *config_file);
Arguments:
config_file: configuration file pointer
Return value:
WEECHAT_CONFIG_READ_OK if configuration was reloaded
WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found
C example:
switch (weechat_config_reload (config_file)) { case WEECHAT_CONFIG_READ_OK: /* ... */ break; case WEECHAT_CONFIG_READ_MEMORY_ERROR: /* ... */ break; case WEECHAT_CONFIG_READ_FILE_NOT_FOUND: /* ... */ break; }
Script (Python):
# prototype rc = weechat.config_reload(config_file) # example rc = weechat.config_reload(config_file) if rc == weechat.WEECHAT_CONFIG_READ_OK: # ... elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND: # ...
Free an option.
Prototype:
void weechat_config_option_free (struct t_config_option *option);
Arguments:
option: option pointer
C example:
weechat_config_option_free (option);
Script (Python):
# prototype weechat.config_option_free(option) # example weechat.config_option_free(option)
Free all options in a section.
Prototype:
void weechat_config_section_free_options (struct t_config_section *section);
Arguments:
section: section pointer
C example:
weechat_config_section_free_options (section);
Script (Python):
# prototype weechat.config_section_free_options(section) # example weechat.config_section_free_options(section)
Free a section.
Prototype:
void weechat_config_section_free (struct t_config_option *option);
Arguments:
section: section pointer
C example:
weechat_config_section_free (section);
Script (Python):
# prototype weechat.config_section_free(section) # example weechat.config_section_free(section)
Free a configuration file.
Prototype:
void weechat_config_free (struct t_config_file *config_file);
Arguments:
config_file: configuration file pointer
C example:
weechat_config_free (config_file);
Script (Python):
# prototype weechat.config_free(config_file) # example weechat.config_free(config_file)
Search an option with full name.
Prototype:
struct t_config_option *weechat_config_get (const char *option_name);
Arguments:
option_name: full option name (format: "file.section.option")
Return value:
pointer to option found, NULL if option was not found
C example:
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
Script (Python):
# prototype option = weechat.config_get(option_name) # example option = weechat.config_get("weechat.look.item_time_format")
Search an option in plugins configuration file (plugins.conf).
Prototype:
const char *weechat_config_get_plugin (const char *option_name);
Arguments:
option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)
Return value:
value of option found, NULL if option was not found
C example:
/* if current plugin is "test", then look for value of option "plugins.var.test.option" in file plugins.conf */ char *value = weechat_config_get_plugin ("option");
Script (Python):
# prototype value = weechat.config_get_plugin(option_name) # example value = weechat.config_get_plugin("option")
Check if option is set in plugins configuration file (plugins.conf).
Prototype:
int weechat_config_is_set_plugin (const char *option_name);
Arguments:
option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)
Return value:
1 if option is set, 0 if option does not exist
C example:
if (weechat_config_is_set_plugin ("option")) { /* option is set */ } else { /* option does not exist */ }
Script (Python):
# prototype value = weechat.config_is_set_plugin(option_name) # example if weechat.config_is_set_plugin("option"): # option is set # ... else: # option does not exist # ...
Set new value for option in plugins configuration file (plugins.conf).
Prototype:
int weechat_config_set_plugin (const char *option_name, const char *value);
Arguments:
option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)
value: new value for option
Return value:
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND if option was not found
WEECHAT_CONFIG_OPTION_SET_ERROR if other error occured
C example:
switch (weechat_config_set_plugin ("option", "test_value")) { case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: /* ... */ break; case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: /* ... */ break; case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND: /* ... */ break; case WEECHAT_CONFIG_OPTION_SET_ERROR: /* ... */ break; }
Script (Python):
# prototype rc = weechat.config_set_plugin(option_name, value) # example rc = weechat.config_is_set_plugin("option", "test_value") if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ...
Unset option in plugins configuration file (plugins.conf).
Prototype:
int weechat_config_unset_plugin (const char *option_name);
Arguments:
option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where xxx is current plugin name)
Return value:
WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET if option value has not been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET if option value has been reset
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED if option has been removed
WEECHAT_CONFIG_OPTION_UNSET_ERROR if an error occured
C example:
switch (weechat_config_unset_plugin ("option")) { case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: /* ... */ break; case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: /* ... */ break; case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: /* ... */ break; case WEECHAT_CONFIG_OPTION_UNSET_ERROR: /* ... */ break; }
Script (Python):
# prototype rc = weechat.config_unset_plugin(option_name) # example rc = weechat.config_unset_plugin("option") if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR: # ...
Functions to display text in buffers.
Return a prefix.
Prototype:
const char *weechat_prefix (const char *prefix);
Arguments:
prefix: name of prefix:
Prefix | Value | Color | Description |
---|---|---|---|
error |
=!= |
yellow |
error message |
network |
-- |
magenta |
message from network |
action |
* |
white |
self action |
join |
--> |
lightgreen |
someone joins current chat |
quit |
<-- |
lightred |
someone leaves current chat |
Note
|
Values and colors can be customized with command /set. |
Return value:
prefix value (string with prefix and color codes), empty string if prefix is not found
C example:
weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));
Script (Python):
# prototype value = weechat.prefix(prefix) # example weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))
Return a string color code for display.
Prototype:
const char *weechat_color (const char *color_name);
Arguments:
color_name: name of color, one of:
WeeChat option name (from weechat.color.xxx), for example chat_delimiters
color with optional background, for example yellow or yellow,red
attribute:
bold: set bold
-bold: remove bold
reverse: set reverse
-reverse: remove reverse
italic: set italic
-italic: remove italic
underline: set underline
-underline: remove underline
bar color name:
bar_fg: foreground color for bar
bar_delim: delimiters color for bar
bar_bg: background color for bar
Return value:
string with color code, or a "reset color" code if color is not found
C example:
weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red", weechat_color ("blue"), weechat_color ("chat"), weechat_color ("yellow,red"));
Script (Python):
# prototype value = weechat.color(color_name) # example weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red" % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
Display a message on a buffer.
Prototype:
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
Arguments:
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
message: message to display
C example:
weechat_printf (NULL, "Hello on WeeChat buffer"); weechat_printf (buffer, "Hello on this buffer");
Script (Python):
# prototype weechat.prnt(buffer, message) # example weechat.prnt("", "Hello on WeeChat buffer") weechat.prnt(buffer, "Hello on this buffer")
Note
|
Function is called "print" in scripts ("prnt" in Python). |
Display a message on a buffer, using a custom date.
Prototype:
void weechat_printf_date (struct t_gui_buffer *buffer, time_t date, const char *message, ...);
Arguments:
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message
message: message to display
C example:
weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");
Display a message on a buffer, using a custom tags.
Prototype:
void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags, const char *message, ...);
Arguments:
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
tags: comma separated list of tags
message: message to display
C example:
weechat_printf_tags (NULL, "notify_message", "Message with a tag 'notify_message'");
Display a message on a buffer, using a custom date and tags.
Prototype:
void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date, const char *tags, const char *message, ...);
Arguments:
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message
tags: comma separated list of tags
message: message to display
C example:
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message", "Message 2 minutes ago, with a tag 'notify_message'");
Script (Python):
# prototype weechat.prnt_date_tags(buffer, date, tags, message) # example time = int(time.time()) weechat.prnt_date_tags("", time - 120, "notify_message", "Message 2 minutes ago, with a tag 'notify_message'")
Note
|
Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python). |
Display a message on a line of a buffer with free content.
Prototype:
void weechat_printf_y (struct t_gui_buffer *buffer, int y, const char *message, ...);
Arguments:
buffer: buffer pointer
y: line number (first line is 0)
message: message to display
C example:
weechat_printf_y (buffer, 2, "My message on third line");
Script (Python):
# prototype weechat.prnt_y(buffer, y, message) # example weechat.prnt_y("", 2, "My message on third line")
Note
|
Function is called "print_y" in scripts ("prnt_y" in Python). |
Write a message in WeeChat log file (weechat.log).
Prototype:
void weechat_log_printf (const char *message, ...);
Arguments:
message: message to write
C example:
weechat_log_printf ("My message in log file");
Script (Python):
# prototype weechat.log_print(message) # example weechat.log_print("My message in log file")
Note
|
Function is called "log_print" in scripts. |
Hook a command.
Prototype:
struct t_hook *weechat_hook_command (const char *command, const char *description, const char *args, const char *args_description, const char *completion, int (*callback)(void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol), void *callback_data);
Arguments:
command: command name
description: description for command (displayed with /help command)
args: arguments for command (displayed with /help command)
args_description: description of arguments (displayed with /help command)
completion: completion template for command: list of completions for each argument, separated by space. Many completions are possible for one argument, separated by "|". Many templates are possible for same command, separated by "||".
callback: function called when command is used, arguments:
void *data: pointer
struct t_gui_buffer *buffer: buffer where command is executed
int argc: number of arguments given for command
char **argv: arguments given for command
char **argv_eol: arguments given for command (until end of line for each argument)
callback_data: pointer given to callback when it is called by WeeChat
Default completion codes are:
Plugin | Name | Description |
---|---|---|
alias |
alias |
list of aliases |
aspell |
aspell_langs |
list of supported langs for aspell |
irc |
irc_channel |
current IRC channel |
irc |
irc_channel_nicks_hosts |
nicks and hostnames of current IRC channel |
irc |
irc_channel_topic |
topic of current IRC channel |
irc |
irc_channels |
channels on all IRC servers |
irc |
irc_ignores_numbers |
numbers for defined ignores |
irc |
irc_msg_part |
default part message for IRC channel |
irc |
irc_privates |
privates on all IRC servers |
irc |
irc_server |
current IRC server |
irc |
irc_server_channels |
channels on current IRC server |
irc |
irc_server_nick |
nick on current IRC server |
irc |
irc_server_nicks |
nicks on all channels of current IRC server |
irc |
irc_server_privates |
privates on current IRC server |
irc |
irc_servers |
IRC servers (internal names) |
irc |
nick |
nicks of current IRC channel |
lua |
lua_script |
list of scripts |
perl |
perl_script |
list of scripts |
python |
python_script |
list of scripts |
relay |
relay_free_port |
first free port for relay plugin |
relay |
relay_protocol_name |
all possible protocol.name for relay plugin |
relay |
relay_relays |
protocol.name of current relays for relay plugin |
ruby |
ruby_script |
list of scripts |
tcl |
tcl_script |
list of scripts |
weechat |
bars_names |
names of bars |
weechat |
bars_options |
options for bars |
weechat |
buffers_names |
names of buffers |
weechat |
buffers_numbers |
numbers of buffers |
weechat |
buffers_plugins_names |
names of buffers (including plugins names) |
weechat |
commands |
commands (weechat and plugins) |
weechat |
config_files |
configuration files |
weechat |
config_option_values |
values for a configuration option |
weechat |
config_options |
configuration options |
weechat |
filename |
filename |
weechat |
filters_names |
names of filters |
weechat |
infolists |
names of infolists hooked |
weechat |
infos |
names of infos hooked |
weechat |
keys_codes |
key codes |
weechat |
nicks |
nicks in nicklist of current buffer |
weechat |
plugins_commands |
commands defined by plugins |
weechat |
plugins_names |
names of plugins |
weechat |
proxies_names |
names of proxies |
weechat |
proxies_options |
options for proxies |
weechat |
weechat_commands |
weechat commands |
xfer |
nick |
nicks of DCC chat |
Special codes:
%%command: reuse completion template from command command
%-: stop completion
%*: repeat last completion
Return value:
pointer to new hook, NULL if error occured
C example:
int my_command_cb (void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* ... */ return WEECHAT_RC_OK; } /* this example is inspired by command /filter */ struct t_hook *my_command_hook = weechat_hook_command (/* command name */ "myfilter", /* description */ "description of myfilter", /* args */ "[list] | [enable|disable|toggle [name]] | " "[add name plugin.buffer tags regex] | " "[del name|-all]", /* args description */ "description of arguments...", /* completion */ "list" " || enable %(filters_names)" " || disable %(filters_names)" " || toggle %(filters_names)" " || add %(filters_names) %(buffers_plugins_names)|*" " || del %(filters_names)|-all", /* callback */ &my_command_cb, /* callback_data */ NULL);
For example, if command called is /command abc def ghi, then argv and argv_eol contain following values:
argv:
argv[0] == "abc"
argv[1] == "def"
argv[2] == "ghi"
argv_eol:
argv_eol[0] == "abc def ghi"
argv_eol[1] == "def ghi"
argv_eol[2] == "ghi"
Script (Python):
# prototype hook = weechat.hook_command(command, description, args, args_description, completion, callback, callback_data) # example def my_command_cb(data, buffer, args): # ... return weechat.WEECHAT_RC_OK hook = weechat.hook_command("myfilter", "description of myfilter", "[list] | [enable|disable|toggle [name]] | " "[add name plugin.buffer tags regex] | " "[del name|-all]", "description of arguments...", "list" " || enable %(filters_names)" " || disable %(filters_names)" " || toggle %(filters_names)" " || add %(filters_names) %(buffers_plugins_names)|*" " || del %(filters_names)|-all", "my_command_cb", "")
Hook a command when WeeChat runs it.
Prototype:
struct t_hook *weechat_hook_command_run (const char *command, int (*callback)(void *data, struct t_gui_buffer *buffer, const char *command), void *callback_data);
Arguments:
command: command to hook, may start or end with "*" as joker
callback: function called when command is run, arguments:
void *data: pointer
struct t_gui_buffer *buffer: buffer where command is executed
const char *command: the command executed, with its arguments
callback_data: pointer given to callback when it is called by WeeChat
Note
|
Callback can return WEECHAT_RC_OK or WEECHAT_RC_OK_EAT (command will not be executed by WeeChat after callback). |
Return value:
pointer to new hook, NULL if error occured
C example:
int my_command_run_cb (void *data, struct t_gui_buffer *buffer, const char *command) { weechat_printf (NULL, "You want to complete? I'm eating the completion ahah!"); return WEECHAT_RC_OK_EAT; } struct t_hook *my_command_run_hook = weechat_hook_command_run ("/input complete*", &my_command_run_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_command_run(command, callback, callback_data) # example def my_command_run_cb(data, buffer, command): weechat.prnt("", "You want to complete? I'm eating the completion, ahah!") return weechat.WEECHAT_RC_OK_EAT hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
Hook a timer.
Prototype:
struct t_hook *weechat_hook_timer (long interval, const char *align_second, const char *max_calls, int (*callback)(void *data, int remaining_calls), void *callback_data);
Arguments:
interval: interval between two calls (milliseconds, so 1000 = 1 second)
align_second: alignment on a second. For example, if current time is 09:00, if interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute when second is 00
max_calls: number of calls to timer (if 0, then timer has no end)
callback: function called when time is reached, arguments:
void *data: pointer
int remaining_calls: remaining calls (-1 if timer has no end)
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_timer_cb (void *data, int remaining_calls) { /* ... */ return WEECHAT_RC_OK; } /* timer called each 20 seconds */ struct t_hook *my_timer_hook = weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data) # example def my_timer_cb(data, remaining_calls): # ... return weechat.WEECHAT_RC_OK # timer called each 20 seconds hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
Hook a file descriptor (file or socket).
Prototype:
struct t_hook *weechat_hook_fd (int fd, int flag_read, int flag_write, int flag_exception, int (*callback)(void *data, int fd), void *callback_data);
Arguments:
fd: file descriptor
flag_read: 1 = catch read event, 0 = ignore
flag_write: 1 = catch write event, 0 = ignore
flag_exception: 1 = catch exception event, 0 = ignore
callback: function called a selected event occurs for file (or socket), arguments:
void *data: pointer
int fd: file descriptor
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_fd_cb (void *data, int fd) { /* ... */ return WEECHAT_RC_OK; } int sock = socket (AF_INET, SOCK_STREAM, 0); /* set socket options */ /* ... */ struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data) # example def my_fd_cb(data, fd): # ... return weechat.WEECHAT_RC_OK sock = ... hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
Hook a process (launched with fork), and catch output.
Prototype:
struct t_hook *weechat_hook_process (const char *command, int timeout, int (*callback)(void *data, const char *command, int return_code, const char *out, const char *err), void *callback_data);
Arguments:
command: command to launch in child process
timeout: timeout for command (in milliseconds): after this timeout, child process is killed (0 means no timeout)
callback: function called when data from child is available, or when child has ended, arguments:
void *data: pointer
const char *command: command executed by child
int return_code: return code:
>= 0: child command return code
< 0: WEECHAT_HOOK_PROCESS_OK_RUNNING (data available, but child still running) or WEECHAT_HOOK_PROCESS_ERROR (error when launching command)
out: standard output of command (stdout)
err: error output of command (stderr)
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_process_cb (void *data, const char *command, int return_code, const char *out, const char *err) { if (return_code == WEECHAT_HOOK_PROCESS_ERROR) { weechat_printf (NULL, "Error with command '%s'", command); return WEECHAT_RC_OK; } if (return_code >= 0) { weechat_printf (NULL, "return_code = %d", return_code); } if (out) { weechat_printf (NULL, "stdout: %s", out); } if (err) { weechat_printf (NULL, "stderr: %s", err); } return WEECHAT_RC_OK; } struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000, &my_process_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_process(command, timeout, callback, callback_data) # example def my_process_cb(data, command, return_code, out, err): if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR: weechat.prnt("", "Error with command '%s'" % command) return weechat.WEECHAT_RC_OK if return_code >= 0: weechat.prnt("", "return_code = %d" % return_code) if out != "": weechat.prnt("", "stdout: %s" % out) if err != "": weechat.prnt("", "stderr: %s" % err) return weechat.WEECHAT_RC_OK hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
Hook a connection (background connection to a remote host).
Prototype:
struct t_hook *weechat_hook_connect (const char *proxy, const char *address, int port, int sock, int ipv6, void *gnutls_sess, void *gnutls_cb, int gnutls_dhkey_size, const char *local_hostname, int (*callback)(void *data, int status, int gnutls_rc, const char *errpr, const char *ip_address), void *callback_data);
Arguments:
proxy: name of proxy to use for connection (optional, NULL means connection without proxy)
address: name or IP address to connect to
port: port number
sock: socket used to connect
ipv6: 1 to use IPv6, 0 to use IPv4
gnutls_sess: GnuTLS session (optional)
gnutls_cb: GnuTLS callback (optional)
gnutls_dhkey_size: size of the key used during the Diffie-Hellman Key Exchange (GnuTLS)
callback: function called when connection is ok or failed, arguments:
void *data: pointer
int status: connection status:
WEECHAT_HOOK_CONNECT_OK: connection ok
WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: address not found
WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: IP address not found
WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: connection refused
WEECHAT_HOOK_CONNECT_PROXY_ERROR: error with proxy
WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: error with local hostname
WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: GnuTLS init error
WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: GnuTLS handshake error
WEECHAT_HOOK_CONNECT_MEMORY_ERROR: insufficient memory
gnutls_rc: result value of gnutls_handshake()
const char *error: result value of gnutls_strerror(gnutls_rc)
const char *ip_address: IP address found
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_connect_cb (void *data, int status, int gnutls_rc, const char *error, const char *ip_address) { switch (status) { case WEECHAT_HOOK_CONNECT_OK: /* ... */ break; case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: /* ... */ break; case WEECHAT_HOOK_CONNECT_PROXY_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_MEMORY_ERROR: /* ... */ break; } return WEECHAT_RC_OK; } struct t_hook *my_connect_hook = weechat_hook_connect (NULL, "my.server.org", 1234, sock, 0, NULL, NULL, 0, /* GnuTLS */ NULL, &my_connect_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_connect(proxy, address, port, sock, ipv6, local_hostname, callback, callback_data) # example def my_connect_cb(data, status, gnutls_rc, error, ip_address): if status == WEECHAT_HOOK_CONNECT_OK: # ... elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: # ... elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: # ... elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: # ... elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR: # ... elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: # ... elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: # ... elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: # ... elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR: # ... return weechat.WEECHAT_RC_OK hook = weechat.hook_connect("", "my.server.org", 1234, sock, 0, "", "my_connect_cb", "")
Hook a message printed.
Prototype:
struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer, const char *tags, const char *message, int strip_colors, int (*callback)(void *data, struct t_gui_buffer *buffer, time_t date, int tags_count, const char **tags, int displayed, int highlight, const char *prefix, const char *message), void *callback_data);
Arguments:
buffer: buffer pointer, if NULL, messages from any buffer are caught
tags: only messages with these tags (comma separated list) will be caught (optional)
message: only messages with this string will be caught (optional)
strip_colors: if 1, colors will be stripped from message displayed, before calling callback
callback: function called when a message is printed, arguments:
void *data: pointer
struct t_gui_buffer *buffer: buffer pointer
time_t date: date
int tags_count: number of tags for line
const char **tags: array with tags for line
int displayed: 1 if line is displayed, 0 if it is filtered (hidden)
int highlight: 1 if line has highlight, otherwise 0
const char *prefix: prefix
const char *message: message
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date, int tags_count, const char **tags, int displayed, int highlight, const char *prefix, const char *message) { /* ... */ return WEECHAT_RC_OK; } /* catch all messages, on all buffers, without color */ struct t_hook *my_print_hook = weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data) # example def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message): # ... return weechat.WEECHAT_RC_OK # catch all messages, on all buffers, without color hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
Hook a signal.
Prototype:
struct t_hook *weechat_hook_signal (const char *signal, int (*callback)(void *data, const char *signal, const char *type_data, void *signal_data), void *callback_data);
Arguments:
signal: signal to catch, can begin or end with "*":
Plugin | Signal | Arguments | Description |
---|---|---|---|
irc |
xxx,irc_in_yyy 1 |
string: message |
irc message from server (before irc plugin uses it) |
irc |
xxx,irc_in2_yyy 1 |
string: message |
irc message from server (after irc plugin uses it) |
irc |
xxx,irc_out_yyy 1 |
string: message |
irc message sent to server |
irc |
irc_ctcp |
string: message |
CTCP received |
irc |
irc_dcc |
string: message |
new DCC |
irc |
irc_pv |
string: message |
private message received |
irc |
irc_channel_opened |
pointer: buffer |
channel opened |
irc |
irc_pv_opened |
pointer: buffer |
private opened |
irc |
irc_server_connecting |
string: server name |
connecting to server |
irc |
irc_server_connected |
string: server name |
connected to server |
irc |
irc_server_disconnected |
string: server name |
disconnected from server |
irc |
irc_ignore_removing |
pointer: ignore |
removing ignore |
irc |
irc_ignore_removed |
- |
ignore removed |
logger |
logger_start |
pointer: buffer |
start logging for buffer |
logger |
logger_stop |
pointer: buffer |
stop logging for buffer |
logger |
logger_backlog |
pointer: buffer |
display backlog for buffer |
weechat |
buffer_closing |
pointer: buffer |
closing buffer |
weechat |
buffer_closed |
pointer: buffer |
buffer closed |
weechat |
buffer_lines_hidden |
pointer: buffer |
lines hidden in buffer |
weechat |
buffer_localvar_added |
pointer: buffer |
local variable has been added |
weechat |
buffer_localvar_changed |
pointer: buffer |
local variable has changed |
weechat |
buffer_localvar_removed |
pointer: buffer |
local variable has been removed |
weechat |
buffer_moved |
pointer: buffer |
buffer moved |
weechat |
buffer_opened |
pointer: buffer |
buffer opened |
weechat |
buffer_renamed |
pointer: buffer |
buffer renamed |
weechat |
buffer_switch |
pointer: buffer |
switching buffer |
weechat |
buffer_title_changed |
pointer: buffer |
title of buffer changed |
weechat |
buffer_type_changed |
pointer: buffer |
type of buffer changed |
weechat |
debug_dump |
- |
dump request |
weechat |
filter_added |
pointer: filter |
filter added |
weechat |
filter_removing |
pointer: filter |
removing filter |
weechat |
filter_removed |
- |
filter added |
weechat |
filter_enabled |
- |
filters enabled |
weechat |
filter_disabled |
- |
filters disabled |
weechat |
hotlist_changed |
- |
hotlist changed |
weechat |
input_paste_pending |
- |
paste pending |
weechat |
input_search |
- |
text search in buffer |
weechat |
input_text_changed |
- |
input text changed |
weechat |
input_text_cursor_moved |
- |
input text cursor moved |
weechat |
key_pressed |
string: key pressed |
key pressed |
weechat |
nicklist_changed |
- |
nicklist has changed |
weechat |
partial_completion |
- |
partial completion happened |
weechat |
quit |
string: arguments for /quit |
command /quit issued by user |
weechat |
upgrade |
- |
command /upgrade issued by user |
weechat |
weechat_highlight |
string: message with prefix |
highlight happened |
weechat |
weechat_pv |
string: message with prefix |
private message displayed |
weechat |
window_scrolled |
pointer: window |
scroll in window |
weechat |
window_unzooming |
pointer: current window |
unzooming window |
weechat |
window_unzoomed |
pointer: current window |
window unzoomed |
weechat |
window_zooming |
pointer: current window |
zomming window |
weechat |
window_zoomed |
pointer: current window |
window zoomed |
xfer |
xfer_add |
pointer: infolist with xfer info |
new xfer |
xfer |
xfer_send_ready |
pointer: infolist with xfer info |
xfer ready |
xfer |
xfer_accept_resume |
pointer: infolist with xfer info |
xfer accepts resume (send) |
xfer |
xfer_send_accept_resume |
pointer: infolist with xfer info |
xfer accepts resume (send) |
xfer |
xfer_start_resume |
pointer: infolist with xfer info |
start resume |
xfer |
xfer_resume_ready |
pointer: infolist with xfer info |
xfer resume ready |
Note
|
1 xxx is IRC server name, yyy is IRC command name. |
callback: function called when signal is received, arguments:
void *data: pointer
const char *signal: signal received
const char *type_data: type of data sent with signal:
WEECHAT_HOOK_SIGNAL_STRING: string
WEECHAT_HOOK_SIGNAL_INT: integer number
WEECHAT_HOOK_SIGNAL_POINTER: pointer
void *signal_data: data sent with signal
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_signal_cb (void *data, const char *signal, const char *type_data, void *signal_data) { /* ... */ return WEECHAT_RC_OK; } /* catch signal "quit" */ struct t_hook *my_signal_hook = weechat_hook_signal ("quit", &my_signal_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_signal(signal, callback, callback_data) # example def my_signal_cb(data, signal, type_data, signal_data): # ... return weechat.WEECHAT_RC_OK # catch signal "quit" hook = weechat.hook_signal("quit", "my_signal_cb", "")
Send a signal.
Prototype:
void weechat_hook_signal_send (const char *signal, const char *type_data, void *signal_data);
Arguments:
signal: signal to send
type_data: type of data sent with signal (see [_weechat_hook_signal])
signal_data: data sent with signal
C example:
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
Script (Python):
# prototype weechat.hook_signal_send(signal, type_data, signal_data) # example weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
Hook a configuration option.
Prototype:
struct t_hook *weechat_hook_config (const char *option, int (*callback)(void *data, const char *option, const char *value), void *callback_data);
Arguments:
option: option, format is full name, as used with command /set (for example: weechat.look.item_time_format)
callback: function called when configuration option is changed, arguments:
void *data: pointer
const char *option: name of option
const char *value: new value for option
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
int my_config_cb (void *data, const char *option, const char *value) { /* ... */ return WEECHAT_RC_OK; } /* catch changes to option "weechat.look.item_time_format" */ struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format", &my_config_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_config(option, callback, callback_data) # example def my_config_cb(data, option, value): # ... return weechat.WEECHAT_RC_OK # catch changes to option "weechat.look.item_time_format" hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
Hook a completion.
Prototype:
struct t_hook *weechat_hook_completion (const char *completion_item, int (*callback)(void *data, const char *completion_item, struct t_gui_buffer *buffer, struct t_gui_completion *completion), void *callback_data);
Arguments:
completion_item: name of completion item, after you can use %(name) in a command hooked (argument completion)
callback: function called when completion item is used (user is completing something using this item), artuments:
void *data: pointer
const char *completion_item: name of completion item
struct t_gui_buffer *buffer: buffer where completion is made
struct t_gui_completion *completion: structure used to add words for completion (see [_weechat_hook_completion_list_add])
callback_data: pointer given to callback when it is called by WeeChat
Note
|
Completion names are global (shared accross WeeChat and plugins). So it is recommended to choose a name with a unique prefix, like "plugin_xxx" (where "xxx" is your item name). |
Return value:
pointer to new hook, NULL if error occured
C example:
int my_completion_cb (void *data, const char *completion_item, struct t_gui_buffer *buffer, struct t_gui_completion *completion) { weechat_hook_completion_list_add (completion, "word1", 0, WEECHAT_LIST_POS_SORT); weechat_hook_completion_list_add (completion, "test_word2", 0, WEECHAT_LIST_POS_SORT); return WEECHAT_RC_OK; } struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item", &my_completion_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_completion(completion_item, callback, callback_data) # example def my_completion_cb(data, completion_item, buffer, completion): weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT) weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT) return weechat.WEECHAT_RC_OK hook = weechat.hook_completion("plugin_item", "my_completion_cb", "")
Add a word for a completion.
Prototype:
void weechat_hook_completion_list_add (struct t_gui_completion *completion, const char *word, int nick_completion, const char *where);
Arguments:
completion: completion pointer
word: word to add
nick_completion: 1 if word is a nick, otherwise 0
where: position where word will be inserted in list:
WEECHAT_LIST_POS_SORT: any position, to keep list sorted
WEECHAT_LIST_POS_BEGINNING: beginning of list
WEECHAT_LIST_POS_END: end of list
C example: see [_weechat_hook_completion].
Script (Python):
# prototype weechat.hook_completion_list_add(completion, word, nick_completion, where) # example: see function hook_completion above
Hook a modifier.
Prototype:
struct t_hook *weechat_hook_modifier (const char *modifier, char *(*callback)(void *data, const char *modifier, const char *modifier_data, const char *string), void *callback_data);
Arguments:
modifier: modifier name, list of modifiers used by Weechat or plugins:
Plugin | Modifier | Modifier data | String | Output |
---|---|---|---|---|
charset |
charset_decode |
plugin.buffer_name |
any string |
string decoded from charset found for plugin/buffer to UTF-8 |
charset |
charset_encode |
plugin.buffer_name |
any string |
string encoded from UTF-8 to charset found for plugin/buffer |
irc |
irc_color_decode |
"1" to keep colors, "0" to remove colors |
any string |
string with WeeChat color codes, or without color |
irc |
irc_color_encode |
"1" to keep colors, "0" to remove colors |
any string |
string with IRC color codes, or without color |
irc |
irc_in_xxx 1 |
server name |
content of message received from IRC server |
new content of message |
irc |
irc_out_xxx 1 |
server name |
content of message about to be sent to IRC server |
new content of message |
weechat |
bar_condition_yyy 2 |
string with window pointer ("0x123..") |
empty string |
"1" to display bar, "0" to hide it |
weechat |
input_text_content |
string with buffer pointer ("0x123..") |
input buffer (from user) |
new content of input buffer |
weechat |
input_text_display |
string with buffer pointer ("0x123..") |
input buffer (from user), without cursor tag |
new content of input buffer, for display only (input buffer is not changed) |
weechat |
input_text_display_with_cursor |
string with buffer pointer ("0x123..") |
input buffer (from user), with cursor tag |
new content of input buffer, for display only (input buffer is not changed) |
weechat |
weechat_print |
plugin;buffer_name;tags |
message printed |
new message printed |
Note
|
1 xxx is IRC command name. 2 yyy is bar name. |
callback: function called when modifier is used, arguments:
void *data: pointer
const char *modifier: name of modifier
const char *modifier_data: data for modifier
const char *string: string to modify (function must return copy of this string, no changes are allowed in this string)
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
char * my_modifier_cb (void *data, const char *modifier, const char *modifier_data, const char *string) { char *result; int length; if (!string) return NULL; length = strlen (string) + 5; result = malloc (length); if (result) { /* add "xxx" to any message printed */ snprintf (result, length, "%s xxx", string); } return result; } struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print", &my_modifier_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_modifier(modifier, callback, callback_data) # example def my_modifier_cb(data, modifier, modifier_data, string): return "%s xxx" % string hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
Execute modifier(s).
Prototype:
char *weechat_hook_modifier_exec (const char *modifier, const char *modifier_data, const char *string);
Arguments:
modifier: modifier name
modifier_data: modifier data
string: string to modify
Return value:
string modified, NULL if no changes in string were made by modifier(s)
C example:
char *new_string = weechat_hook_modifier_exec ("my_modifier", my_data, my_string);
Script (Python):
# prototype weechat.hook_modifier_exec(modifier, modifier_data, string) # example weechat.hook_modifier_exec("my_modifier", my_data, my_string)
Hook an information.
Prototype:
struct t_hook *weechat_hook_info (const char *info_name, const char *description, const char *(*callback)(void *data, const char *info_name, const char *arguments), void *callback_data);
Arguments:
info_name: name of info
description: description
callback: function called when info is asked, arguments:
void *data: pointer
const char *info_name: name of info
const char *arguments: additional arguments, depending on info
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
const char * my_info_cb (void *data, const char *info_name, const char *arguments) { /* ... */ return pointer_to_string; } /* add info "my_info" */ struct t_hook *my_info_hook = weechat_hook_info ("my_info", "Some info", &my_info_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_info(info_name, description, callback, callback_data) # example def my_info_cb(data, info_name, arguments): return "some_info" hook = weechat.hook_info("my_info", "Some info", "my_info_cb", "")
Hook an infolist: callback will return pointer to infolist asked.
Prototype:
struct t_hook *weechat_hook_infolist (const char *infolist_name, const char *description, const char *(*callback)(void *data, const char *infolist_name, void *pointer, const char *arguments), void *callback_data);
Arguments:
infolist_name: name of infolist
description: description
callback: function called when infolist is asked, arguments:
void *data: pointer
const char *infolist_name: name of infolist
void *pointer: pointer to an object that infolist must return (to get only one item in infolist)
const char *arguments: additional arguments, depending on infolist
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new hook, NULL if error occured
C example:
struct t_infolist * my_infolist_cb (void *data, const char *infolist_name, void *pointer, const char *arguments) { struct t_infolist *my_infolist; /* build infolist */ /* ... */ return my_infolist; } /* add infolist "my_infolist" */ struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist", "Infolist with some data", &my_infolist_cb, NULL);
Script (Python):
# prototype hook = weechat.hook_infolist(infolist_name, description, callback, callback_data) # example def my_infolist_cb(data, infolist_name, pointer, arguments): # build infolist # ... return my_infolist hook = weechat.hook_infolist("my_infolist", "Infolist with some data", "my_infolist_cb", "")
Unhook something hooked.
Prototype:
void weechat_unhook (struct t_hook *hook);
Arguments:
hook: something hooked with "weechat_hook_xxx()"
C example:
struct t_hook *my_hook = weechat_hook_command ( /* ... */ ); /* ... */ weechat_unhook (my_hook);
Script (Python):
# prototype weechat.unhook(hook) # example weechat.unhook(my_hook)
Unhook everything that has been hooked by current plugin.
Prototype:
void weechat_unhook_all ();
C example:
weechat_unhook_all ();
Script (Python):
# prototype weechat.unhook_all() # example weechat.unhook_all()
Functions to create/query/close buffers.
Open a new buffer.
Prototype:
struct t_gui_buffer *weechat_buffer_new (const char *name, int (*input_callback)(void *data, struct t_gui_buffer *buffer, const char *input_data), void *input_callback_data, int (*close_callback)(void *data, struct t_gui_buffer *buffer), void *close_callback_data);
Arguments:
name: name of buffer (must be unique for plugin)
input_callback: function called when input text is entered on buffer, arguments:
void *data: pointer
struct t_gui_buffer *buffer: buffer pointer
const char *input_data: input data
callback_data: pointer given to callback when it is called by WeeChat
close_callback: function called when buffer is closed, arguments:
void *data: pointer
struct t_gui_buffer *buffer: buffer pointer
callback_data: pointer given to callback when it is called by WeeChat
Return value:
pointer to new buffer, NULL if error occured
C example:
int my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data) { weechat_printf (buffer, "Text: %s", input_data); return WEECHAT_RC_OK; } int my_close_cb (void *data, struct t_gui_buffer *buffer) { weechat_printf (NULL, "Buffer '%s' will be closed!", weechat_buffer_get_string (buffer, "name")); return WEECHAT_RC_OK; } struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer", &my_input_cb, NULL, &my_close_cb, NULL);
Script (Python):
# prototype buffer = weechat.buffer_new(name, input_callback, input_callback_data, close_callback, close_callback_data) # example def my_input_cb(data, buffer, input_data): weechat.prnt(buffer, "Text: %s" % input_data) return weechat.WEECHAT_RC_OK def my_close_cb(data, buffer): weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name")) return weechat.WEECHAT_RC_OK buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
Return pointer to current buffer (buffer displayed by current window).
Prototype:
struct t_gui_buffer *weechat_current_buffer ();
Return value:
pointer to current buffer
C example:
weechat_printf (weechat_current_buffer (), "Text on current buffer");
Script (Python):
# prototype buffer = weechat.current_buffer() # example weechat.prnt(weechat.current_buffer(), "Text on current buffer")
Search a buffer by plugin and/or name.
Prototype:
struct t_gui_buffer *weechat_buffer_search (const char *plugin, const char *name);
Arguments:
plugin: name of plugin
name: name of buffer, if it is NULL or empty string, the current buffer is returned (buffer displayed by current window)
Return value:
pointer to buffer found, NULL if not found
C example:
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin", "my_buffer");
Script (Python):
# prototype buffer = weechat.buffer_search(plugin, name) # example buffer = weechat.buffer_search("my_plugin", "my_buffer")
Search WeeChat main buffer (core buffer, first buffer displayed when WeeChat is starting).
Prototype:
struct t_gui_buffer *weechat_buffer_search_main ();
Return value:
pointer to WeeChat main buffer (core buffer)
C example:
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
Script (Python):
# prototype buffer = weechat.buffer_search_main() # example buffer = weechat.buffer_search_main()
Clear content of a buffer.
Prototype:
void weechat_buffer_clear (struct t_gui_buffer *buffer);
Arguments:
buffer: buffer pointer
C example:
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin", "my_buffer"); if (my_buffer) { weechat_buffer_clear (my_buffer); }
Script (Python):
# prototype weechat.buffer_clear(buffer) # example buffer = weechat.buffer_search("my_plugin", "my_buffer") if buffer != "": weechat.buffer_clear(buffer)
Close a buffer.
Prototype:
void weechat_buffer_close (struct t_gui_buffer *buffer);
Arguments:
buffer: buffer pointer
C example:
struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer", &my_input_cb, NULL, &my_close_cb, NULL); /* ... */ weechat_buffer_close (my_buffer);
Script (Python):
# prototype weechat.buffer_close(buffer) # example buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "") # ... weechat.buffer_close(buffer)
Merge buffer into another buffer: both buffers will still exist separately, but with same number, and WeeChat will display lines from both buffers (mixed lines).
Prototype:
void weechat_buffer_merge (struct t_gui_buffer *buffer, struct t_gui_buffer *target_buffer);
Arguments:
buffer: buffer pointer
target_buffer: target buffer, where buffer will be merged
C example:
/* merge current buffer with weechat "core" buffer */ weechat_buffer_merge (weechat_current_buffer (), weechat_buffer_search_main ());
Script (Python):
# prototype weechat.buffer_merge(buffer, target_buffer) # example # merge current buffer with WeeChat "core" buffer weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
Unmerge buffer from a group of merged buffers.
Prototype:
void weechat_buffer_unmerge (struct t_gui_buffer *buffer, int number);
Arguments:
buffer: buffer pointer
number: target number for detached buffer, if it is < 1, then buffer will be moved to number of buffer + 1
C example:
weechat_buffer_unmerge (weechat_current_buffer (), 1);
Script (Python):
# prototype weechat.buffer_unmerge(buffer, number) # example weechat.buffer_unmerge(weechat.current_buffer(), 1)
Return integer value of a buffer property.
Prototype:
int weechat_buffer_get_integer (struct t_gui_buffer *buffer, const char *property);
Arguments:
buffer: buffer pointer
property: property name:
number: number of buffer (starts with 1)
num_displayed: number of windows displaying buffer
notify: notify level for buffer
lines_hidden: 1 if at least one line is hidden on buffer (filtered), or 0 if all lines are displayed
prefix_max_length: max length for prefix in this buffer
time_for_each_line: 1 if time is displayed for each line in buffer (default), otherwise 0
text_search: text search type:
0: no search at this moment
1: backward search (direction: oldest messages)
2: forward search (direction: newest messages)
text_search_exact: 1 if text search is case sensitive
text_search_found: 1 if text found, otherwise 0
input_pos: cursor position in buffer input
Return value:
integer value of property
C example:
weechat_printf (NULL, "my buffer number is: %d", weechat_buffer_get_integer (my_buffer, "number"));
Script (Python):
# prototype value = weechat.buffer_get_integer(buffer, property) # example weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
Return string value of a buffer property.
Prototype:
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer, const char *property);
Arguments:
buffer: buffer pointer
property: property name:
plugin: name of plugin which created this buffer ("core" for WeeChat main buffer)
name: name of buffer
short_name: short name of buffer
tilte: title of buffer
input: input text
localvar_xxx: get content of local variable "xxx" (replace "xxx" by the name of variable to read)
Return value:
string value of property
C example:
weechat_printf (NULL, "name / short name of buffer are: %s / %s", weechat_buffer_get_string (my_buffer, "name"), weechat_buffer_get_string (my_buffer, "short_name"));
Script (Python):
# prototype value = weechat.buffer_get_string(buffer, property) # example weechat.prnt("", "name / short name of buffer are: %s / %s" % (weechat.buffer_get_string(my_buffer, "name"), weechat.buffer_get_string(my_buffer, "short_name")))
Return pointer value of a buffer property.
Prototype:
const char *weechat_buffer_pointer (struct t_gui_buffer *buffer, const char *property);
Arguments:
buffer: buffer pointer
property: property name:
plugin: pointer to plugin which created this buffer (NULL for WeeChat main buffer)
Return value:
pointer value of property
C example:
weechat_printf (NULL, "plugin pointer of my buffer: %lx", weechat_buffer_get_pointer (my_buffer, "plugin"));
Script (Python):
# prototype value = weechat.buffer_get_pointer(buffer, property) # example weechat.prnt("", "plugin pointer of my buffer: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))
Set string value of a buffer property.
Prototype:
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property, const char *value);
Arguments:
buffer: buffer pointer
property and value: property name, with its value:
Name | Value | Description |
---|---|---|
hotlist |
"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT |
"+": enable hotlist (global setting, buffer pointer is not used) |
unread |
(N/A) |
set unread marker after last line of buffer |
display |
"1", "auto" |
"1": switch to this buffer in current window |
number |
number |
move buffer to this number |
name |
any string |
set new name for buffer |
short_name |
any string |
set new short name for buffer |
type |
"formatted" or "free" |
set type for buffer: "formatted" (for printing chat messages), or "free" (for free content) |
notify |
"0", "1", "2", "3" |
set notify level for buffer: "0" = never add to hotlist, "1" = add for highlights only, "2" = add for highlights and messages, "3" = add for all messages |
title |
any string |
set new title for buffer |
time_for_each_line |
"0" or "1" |
"0" to hide time for all lines in buffer, "1" to see time for all lines (default for a new buffer) |
nicklist |
"0" or "1" |
"0" to remove nicklist for buffer, "1" to add nicklist for buffer |
nicklist_case_sensitive |
"0" or "1" |
"0" to have case insensitive nicklist, "1" to have case sensitive nicklist |
nicklist_display_groups |
"0" or "1" |
"0" to hide nicklist groups, "1" to display nicklist groups |
highlight_words |
"-" or comma separated list of words |
"-" is a special value to disable any highlight on this buffer, or comma separated list of words to highlight in this buffer, for example: "abc,def,ghi" |
highlight_tags |
comma separated list of tags |
comma separated list of tags to highlight in this buffer |
key_bind_xxx |
any string |
bind a new key xxx, specific to this buffer, value is command to execute for this key |
key_unbind_xxx |
(N/A) |
unbind key xxx for this buffer |
input |
any string |
set new value for buffer input |
input_pos |
position |
set cursor position in buffer input |
input_get_unknown_commands |
"0" or "1" |
"0" to disable unknown commands on this buffer (default behaviour), "1" to get unknown commands, for example if user type "/unknowncmd", buffer will receive it (no error about unknown command) |
localvar_set_xxx |
any string |
set new value for local variable xxx (variable is created if it does not exist) |
localvar_del_xxx |
(N/A) |
remove local variable xxx |
C example:
/* disable hotlist (for all buffers) */ weechat_buffer_set (NULL, "hotlist", "-"); /* enable again hotlist */ weechat_buffer_set (NULL, "hotlist", "+"); /* change buffer name */ weechat_buffer_set (my_buffer, "name", "my_new_name"); /* add new local variable "toto" with value "abc" */ weechat_buffer_set (my_buffer, "localvar_set_toto", "abc"); /* remove local variable "toto" */ weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);
Script (Python):
# prototype weechat.buffer_set(buffer, property, value) # examples # disable hotlist (for all buffers) weechat.buffer_set("", "hotlist", "-") # enable again hotlist weechat.buffer_set("", "hotlist", "+") # change buffer name weechat.buffet_set(my_buffer, "name", "my_new_name") # add new local variable "toto" with value "abc" weechat.buffet_set(my_buffer, "localvar_set_toto", "abc") # remove local variable "toto" weechat.buffet_set(my_buffer, "localvar_del_toto", "")
Set pointer value of a buffer property.
Prototype:
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property, void *pointer);
Arguments:
buffer: buffer pointer
property and value: property name, with its value:
close_callback: set close callback function
close_callback_data: set close callback data
input_callback: set input callback function
input_callback_data: set input callback data
C example:
int my_close_cb (void *data, struct t_gui_buffer *buffer) { /* ... */ return WEECHAT_RC_OK; } weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
Replace local variables in a string by their values, using buffer local variables.
Prototype:
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer, const char *string);
Arguments:
buffer: buffer pointer
string: string with text and local variables using format "$var"
Return value:
string with values of local variables
C example:
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc"); char *str = weechat_buffer_string_replace_local_var (my_buffer, "test with $toto"); /* str contains "test with abc" */
Script (Python):
# prototype value = weechat.buffer_string_replace_local_var(buffer, string) # example weechat.buffer_set(my_buffer, "localvar_set_toto", "abc") str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto") # str contains "test with abc"
Functions to query windows.
Return pointer to current window.
Prototype:
struct t_gui_window *weechat_current_window ();
Return value:
pointer to current window
C example:
struct t_gui_window *current_window = weechat_current_window ();
Script (Python):
# prototype window = weechat.current_window() # example current_window = weechat.current_window()
Return integer value of a window property.
Prototype:
int weechat_window_get_integer (struct t_gui_window *window, const char *property);
Arguments:
window: window pointer
property: property name:
win_x: X position of window in terminal (first column is 0)
win_y: Y position of window in terminal (first line is 0)
win_width: width of window, in chars
win_height: height of window, in chars
win_width_pct: percentage size, compared to parent window (for example 50 means half size)
win_height_pct: percentage size, compared to parent window (for example 50 means half size)
win_chat_x: X position of chat window in terminal (first column is 0)
win_chat_y: Y position of chat window in terminal (first line is 0)
win_chat_width: width of chat window, in chars
win_chat_height: height of chat window, in chars
first_line_displayed: 1 if first line of buffer is displayed on screen, otherwise 0
scroll: 1 if scroll is active on window (last line not displayed)
scroll_lines_after: number of lines not displayed after last one displayed (when scrolling)
Return value:
integer value of property
C example:
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)", weechat_window_get_integer (weechat_current_window (), "win_x"), weechat_window_get_integer (weechat_current_window (), "win_y"));
Script (Python):
# prototype value = weechat.window_get_integer(window, property) # example weechat.prnt("", "current window is at position (x,y): (%d,%d)" % (weechat.window_get_integer(weechat.current_window(), "win_x"), weechat.window_get_integer(weechat.current_window(), "win_y")))
Return string value of a window property.
Note
|
This function is not used today, it is reserved for a future version. |
Prototype:
int weechat_window_get_string (struct t_gui_window *window, const char *property);
Arguments:
window: window pointer
property: property name
Return value:
string value of property
Return pointer value of a window property.
Prototype:
void *weechat_window_get_pointer (struct t_gui_window *window, const char *property);
Arguments:
window: window pointer
property: property name:
current: current window pointer
buffer: pointer to buffer displayed by window
Return value:
pointer value of property
C example:
weechat_printf (NULL, "buffer displayed in current window: %lx", weechat_window_get_pointer (weechat_current_window (), "buffer"));
Script (Python):
# prototype value = weechat.window_get_pointer(window, property) # example weechat.prnt("", "buffer displayed in current window: %lx" % weechat.window_get_pointer(weechat.current_window(), "buffer"))
Set title for terminal.
Prototype:
void weechat_window_set_title (const char *title);
Arguments:
title: new title for terminal (NULL to reset title)
C example:
weechat_window_set_title ("new title here");
Script (Python):
# prototype weechat.window_set_title(window, title) # example weechat.window_set_title("new title here")
Functions for buffer nicklist.
Add a group in a nicklist.
Prototype:
struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer, struct t_gui_nick_group *parent_group, const char *name, const char *color, int visible);
Arguments:
buffer: buffer pointer
parent_group: pointer to parent of group, NULL if group has no parent (nicklist root)
name: group name
visible:
1: group and sub-groups/nicks are visible
0: group and sub-groups/nicks are hidden
color: color option name:
WeeChat option name, for example weechat.color.nicklist_group
color with optional background, for example yellow or yellow,red
bar color name:
bar_fg: foreground color for bar
bar_delim: delimiters color for bar
bar_bg: background color for bar
Note
|
The group name can begin with one or more digits, followed by pipe, and then group name. When such string is found at beginning, it’s used to sort groups in nicklist. For example groups "1|test" and "2|abc" will be displayed in that order: first "test" then "abc". |
Return value:
pointer to new group, NULL if an error occured
C example:
struct t_gui_nick_group *my_group = weechat_nicklist_add_group (my_buffer, my_parent_group, "test_group", "weechat.color.nicklist_group", 1);
Script (Python):
# prototype group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible) # example group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group", "weechat.color.nicklist_group", 1)
Search a group in a nicklist.
Prototype:
struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer, struct t_gui_nick_group *from_group, const char *name);
Arguments:
buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: group name to search
Return value:
pointer to group found, NULL if not found
C example:
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer, NULL, "test_group");
Script (Python):
# prototype group = weechat.nicklist_search_group(buffer, from_group, name) # example group = weechat.nicklist_search_group(my_buffer, "", "test_group")
Add a nick in a group.
Prototype:
struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer, struct t_gui_nick_group *group, const char *name, const char *color, const char *prefix, const char *prefix_color, int visible);
Arguments:
buffer: buffer pointer
group: group pointer
name: nick name
color: color option name:
WeeChat option name (from weechat.color.xxx), for example chat_delimiters
color with optional background, for example yellow or yellow,red
bar color name:
bar_fg: foreground color for bar
bar_delim: delimiters color for bar
bar_bg: background color for bar
prefix: prefix displayed before nick
prefix_color: color option name:
WeeChat option name (from weechat.color.xxx), for example chat_delimiters
color with optional background, for example yellow or yellow,red
bar color name:
bar_fg: foreground color for bar
bar_delim: delimiters color for bar
bar_bg: background color for bar
visible:
1: nick is visible
0: nick is hidden
Return value:
pointer to new nick, NULL if an error occured
C example:
struct t_gui_nick *my_nick = weechat_nicklist_add_nick (my_buffer, my_group, "test_nick", (nick_away) ? "weechat.color.nicklist_away" : "bar_fg", "@", "lightgreen", 1);
Script (Python):
# prototype nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible) # example if nick_away: color = "weechat.color.nicklist_away" else: color = "bar_fg" nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
Search a nick in a nicklist.
Prototype:
struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer, struct t_gui_nick_group *from_group, const char *name);
Arguments:
buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: nick name to search
Return value:
pointer to nick found, NULL if not found
C example:
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer, NULL, "test_nick");
Script (Python):
# prototype nick = weechat.nicklist_search_nick(buffer, from_group, name) # example nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
Remove a group from a nicklist.
Prototype:
void weechat_nicklist_remove_group (struct t_gui_buffer *buffer, struct t_gui_nick_group *group);
Arguments:
buffer: buffer pointer
group: group pointer to remove (all sub-groups/nicks will be removed too)
C example:
weechat_nicklist_remove_group (my_buffer, my_group);
Script (Python):
# prototype weechat.nicklist_remove_group(buffer, group) # example weechat.nicklist_remove_group(my_buffer, my_group)
Remove a nick from a nicklist.
Prototype:
void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer, struct t_gui_nick *nick);
Arguments:
buffer: buffer pointer
nick: nick pointer to remove
C example:
weechat_nicklist_remove_nick (my_buffer, my_nick);
Script (Python):
# prototype weechat.nicklist_remove_nick(buffer, nick) # example weechat.nicklist_remove_nick(my_buffer, my_nick)
Remove all groups/nicks from a nicklist.
Prototype:
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
Arguments:
buffer: buffer pointer
C example:
weechat_nicklist_remove_all (my_buffer);
Script (Python):
# prototype weechat.nicklist_remove_all(buffer) # example weechat.nicklist_remove_all(my_buffer)
Functions for bars.
Search a bar item.
Prototype:
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
Arguments:
name: bar item name
Return value:
pointer to bar item found, NULL if bar item was not found
C example:
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
Script (Python):
# prototype bar_item = weechat.bar_item_search(name) # example bar_item = weechat.bar_item_search("myitem")
Create a new bar item.
Prototype:
struct t_gui_bar_item *weechat_bar_item_new (const char *name, char *(build_callback)(void *data, struct t_gui_bar_item *item, struct t_gui_window *window), void *build_callback_data);
Arguments:
name: bar item name
build_callback: function called when bar item is built: it must return content of bar item
build_callback_data: pointer given to build callback, when it is called by WeeChat
Return value:
pointer to new bar item, NULL if an error occured
C example:
char * my_build_callback (void *data, struct t_gui_bar_item *item, struct t_gui_window *window) { return strdup ("my content"); } struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem", &my_build_callback, NULL);
Script (Python):
# prototype bar_item = weechat.bar_item_new(name, build_callback, build_callback_data) # example def my_build_callback(data, item, window): return "my content" bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")
Update content of a bar item, by calling its build callback.
Prototype:
void weechat_bar_item_update (const char *name);
Arguments:
name: bar item name
C example:
weechat_bar_item_update ("myitem");
Script (Python):
# prototype weechat.bar_item_update(name) # example weechat.bar_item_update("myitem")
Remove a bar item.
Prototype:
void weechat_bar_item_remove (struct t_gui_bar_item *item);
Arguments:
item: bar item pointer
C example:
weechat_bar_item_remove (&my_item);
Script (Python):
# prototype weechat.bar_item_remove(item) # example weechat.bar_item_remove(myitem)
Search a bar.
Prototype:
struct t_gui_bar *weechat_bar_search (const char *name);
Arguments:
name: bar name
Return value:
pointer to bar found, NULL if bar was not found
C example:
struct t_gui_bar *bar = weechat_bar_search ("mybar");
Script (Python):
# prototype bar = weechat.bar_search(name) # example bar = weechat.bar_search("mybar")
Create a new bar.
Prototype:
struct t_gui_bar *weechat_bar_new (const char *name, const char *hidden, const char *priority, const char *type, const char *condition, const char *position, const char *filling_top_bottom, const char *filling_left_right, const char *size, const char *size_max, const char *color_fg, const char *color_delim, const char *color_bg, const char *separator, const char *items);
Arguments:
name: bar name
hidden:
on: bar is hidden
off: bar is visible
priority: bar priority (integer)
type:
root: bar displayed once, outside windows
window: bar displayed in each window
condition: condition for displaying bar:
active: bar is displayed in active window only
inactive: bar is displayed in inactive windows only
nicklist: bar is displayed in windows with nicklist
position: top, bottom, left or right
filling_top_bottom:
horizontal: items are filled horizontally (space after each item)
vertical: items are filled vertically (new line after each item)
columns_horizontal: items are filled horizontally, displayed with columns
columns_vertical: items are filled vertically, displayed with columns
filling_left_right:
horizontal: items are filled horitontally (space after each item)
vertical: items are filled verticaly (new line after each item)
columns_horizontal: items are filled horizontally, displayed with columns
columns_vertical: items are filled vertically, displayed with columns
size: bar size in chars (0 means automatic size)
size_max: max size for bar (0 means no max size)
color_fg: color for text in bar
color_delim: color for delimiters in bar
color_bg: background color for bar
separator:
on: bar has separator line with other windows/bars
off: no separator
items: list of items in bar, separated by comma (space between items), or "+" (glued items)
Return value:
pointer to new bar, NULL if an error occured
C example:
struct t_gui_bar *my_bar = weechat_bar_new ("mybar", "off", 100, "window", "", "top", "horizontal", "vertical", "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name");
Script (Python):
# prototype bar = weechat.bar_new(name, hidden, priority, type, condition, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items) # example bar = weechat.bar_new("mybar", "off", 100, "window", "", "top", "horizontal", "vertical", "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
Set a new value for a bar property.
Prototype:
int weechat_bar_set (struct t_gui_bar *bar, const char *property, const char *value);
Arguments:
bar: bar pointer
property: name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items (see [_weechat_bar_new])
value: new value for property
Return value:
1 if new value was set, 0 if an error occured
C example:
weechat_bar_set (mybar, "position", "bottom");
Script (Python):
# prototype weechat.bar_set(bar, property, value) # example weechat.bar_set(my_bar, "position", "bottom")
Refresh content of a bar on screen.
Prototype:
void weechat_bar_update (const char *name);
Arguments:
name: bar name
C example:
weechat_bar_update ("mybar");
Script (Python):
# prototype weechat.bar_update(name) # example weechat.bar_update("mybar")
Remove a bar.
Prototype:
void weechat_bar_remove (struct t_gui_bar *bar);
Arguments:
bar: bar pointer
C example:
weechat_bar_remove (mybar);
Script (Python):
# prototype weechat.bar_remove(bar) # example weechat.bar_remove(my_bar)
Functions for executing WeeChat commands.
Execute a command.
Prototype:
void weechat_command (struct t_gui_buffer *buffer, const char *command);
Arguments:
buffer: buffer pointer (command is executed on this buffer, use NULL for WeeChat core buffer)
command: command to execute (if beginning with a "/"), or text to send to buffer
C example:
weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"), "/whois FlashCode");
Script (Python):
# prototype weechat.command(buffer, command) # example weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
Network functions.
Establish a connection/authentification to a proxy.
Prototype:
int weechat_network_pass_proxy (const char *proxy, int sock, const char *address, int port);
Arguments:
proxy: proxy name to use
sock: socket to use
address: address (hostname or IP address)
port: port
Return value:
1 if connection is ok, 0 if an error occured
C example:
if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667)) { /* OK */ } else { /* error */ }
Establish a connection to a remote host.
Prototype:
int weechat_network_connect_to (const char *proxy, int sock, unsigned long address, int port);
Arguments:
proxy: proxy name to use
sock: socket to use
address: address
port: port
Return value:
1 if connection is ok, 0 if an error occured
C example:
struct sockaddr_in addr; socklen_t length; unsigned long address; memset (&addr, 0, sizeof (struct sockaddr_in)); length = sizeof (addr); getsockname (sock, (struct sockaddr *) &addr, &length); addr.sin_family = AF_INET; address = ntohl (addr.sin_addr.s_addr); if (weechat_network_connect_to (NULL, sock, address, 6667)) { /* OK */ } else { /* error */ }
Functions to get infos.
Return info from WeeChat or a plugin.
Prototype:
const char *weechat_info_get (const char *info_name, const char *arguments);
Arguments:
info_name: name of info to read:
Plugin | Name | Description |
---|---|---|
fifo |
fifo_filename |
name of FIFO pipe |
irc |
irc_buffer |
get buffer pointer for an IRC server/channel |
irc |
irc_is_channel |
1 if string is an IRC channel |
irc |
irc_nick |
get current nick on a server |
irc |
irc_nick_color |
get nick color |
irc |
irc_nick_from_host |
get nick from IRC host |
weechat |
charset_internal |
WeeChat internal charset |
weechat |
charset_terminal |
terminal charset |
weechat |
date |
WeeChat compilation date |
weechat |
dir_separator |
directory separator |
weechat |
filters_enabled |
1 if filters are enabled |
weechat |
inactivity |
keyboard inactivity (seconds) |
weechat |
version |
WeeChat version |
weechat |
weechat_dir |
WeeChat directory |
weechat |
weechat_libdir |
WeeChat "lib" directory |
weechat |
weechat_localedir |
WeeChat "locale" directory |
weechat |
weechat_sharedir |
WeeChat "share" directory |
weechat |
weechat_site |
WeeChat site |
weechat |
weechat_site_download |
WeeChat site, download page |
arguments: arguments for info asked (optional, NULL if no argument is needed)
Return value:
string with info asked, NULL if an error occured
C example:
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)", weechat_info_get ("version", NULL), weechat_info_get ("date", NULL)); weechat_printf (NULL, "WeeChat home is: %s", weechat_info_get ("weechat_dir"));
Script (Python):
# prototype value = weechat.info_get(info_name, arguments) # example weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)" % (weechat.info_get("version", ""), weechat.info_get("date", "")) weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir"))
An infolist is a list of "items". Each item contains variables.
For example, infolist "irc_server" has N items (N is number of IRC servers defined). For each item, there is variables like "name", "buffer", "is_connected", …
Each variable has a type and a value. Possible types are:
integer: any integer value
string: any string value
pointer: any pointer
buffer: buffer with fixed length, containing any data
time: time value
Create a new infolist.
Prototype:
struct t_infolist *weechat_infolist_new ();
Return value:
pointer to new infolist
C example:
struct t_infolist *infolist = weechat_infolist_new ();
Script (Python):
# prototype infolist = weechat.infolist_new() # example infolist = weechat.infolist_new()
Add an item in an infolist.
Prototype:
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
Return value:
pointer to new item
C example:
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
Script (Python):
# prototype item = weechat.infolist_new_item(infolist) # example item = weechat.infolist_new_item(infolist)
Add an integer variable to an infolist item.
Prototype:
struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item, const char *name, int value);
Arguments:
item: infolist item pointer
name: variable name
value: integer value
Return value:
pointer to new variable
C example:
struct t_infolist_var *var = weechat_infolist_new_var_integer (item, "my_integer", 123);
Script (Python):
# prototype var = weechat.infolist_new_var_integer(item, name, value) # example var = weechat.infolist_new_var_integer(item, "my_integer", 123)
Add a string variable to an infolist item.
Prototype:
struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item, const char *name, const char *value);
Arguments:
item: infolist item pointer
name: variable name
value: string value
Return value:
pointer to new variable
C example:
struct t_infolist_var *var = weechat_infolist_new_var_string (item, "my_string", "value");
Script (Python):
# prototype var = weechat.infolist_new_var_string(item, name, value) # example var = weechat.infolist_new_var_string(item, "my_string", "value")
Add a pointer variable to an infolist item.
Prototype:
struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item, const char *name, void *pointer);
Arguments:
item: infolist item pointer
name: variable name
pointer: pointer
Return value:
pointer to new variable
C example:
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item, "my_pointer", &pointer);
Script (Python):
# prototype var = weechat.infolist_new_var_pointer(item, name, pointer) # example var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
Add a buffer variable to an infolist item.
Prototype:
struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item, const char *name, void *pointer, int size);
Arguments:
item: infolist item pointer
name: variable name
pointer: pointer to buffer
size: size of buffer
Return value:
pointer to new variable
C example:
char buffer[256]; /* ... */ struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item, "my_buffer", &buffer, sizeof (buffer));
Add a time variable to an infolist item.
Prototype:
struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item, const char *name, time_t time);
Arguments:
item: infolist item pointer
name: variable name
time: time value
Return value:
pointer to new variable
C example:
struct t_infolist_var *var = weechat_infolist_new_variable_time (item, "my_time", time (NULL));
Script (Python):
# prototype var = weechat.infolist_new_var_time(item, name, time) # example var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
Return infolist from WeeChat or a plugin.
Prototype:
struct t_infolist *weechat_infolist_get (const char *infolist_name, void *pointer, const char *arguments);
Arguments:
infolist_name: name of infolist to read:
Plugin | Name | Description |
---|---|---|
alias |
alias |
list of aliases |
irc |
irc_channel |
list of channels for an IRC server |
irc |
irc_ignore |
list of IRC ignores |
irc |
irc_nick |
list of nicks for an IRC channel |
irc |
irc_server |
list of IRC servers |
logger |
logger_buffer |
list of logger buffers |
lua |
lua_script |
list of scripts |
perl |
perl_script |
list of scripts |
python |
python_script |
list of scripts |
relay |
relay |
list of relay clients |
ruby |
ruby_script |
list of scripts |
tcl |
tcl_script |
list of scripts |
weechat |
bar |
list of bars |
weechat |
bar_item |
list of bar items |
weechat |
bar_window |
list of bar windows |
weechat |
buffer |
list of buffers |
weechat |
buffer_lines |
lines of a buffer |
weechat |
filter |
list of filters |
weechat |
history |
history of commands |
weechat |
hook |
list of hooks |
weechat |
hotlist |
list of buffers in hotlist |
weechat |
key |
list of key bindings |
weechat |
nicklist |
nicks in nicklist for a buffer |
weechat |
option |
list of options |
weechat |
plugin |
list of plugins |
weechat |
window |
list of windows |
xfer |
xfer |
list of xfer |
pointer: pointer to an item, to get only this item in infolist (optional, can be NULL)
arguments: arguments for infolist asked (optional, NULL if no argument is needed)
Return value:
pointer to infolist, NULL if an error occured
C example:
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
Script (Python):
# prototype infolist = weechat.infolist_get(infolist_name, pointer, arguments) # example infolist = weechat.infolist_get("irc_server, "", "")
Move "cursor" to next item in an infolist. The first call to this function for an infolist moves cursor to first item in infolist.
Prototype:
int weechat_infolist_next (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
Return value:
1 if cursor has been moved on next item, 0 if end of list was reached
C example:
if (weechat_infolist_next (infolist)) { /* read variables in item... */ } else { /* no more item available */ }
Script (Python):
# prototype rc = weechat.infolist_next(infolist) # example rc = weechat.infolist_next(infolist) if rc: # read variables in item... else: # no more item available
Move "cursor" to previous item in an infolist. The first call to this function for an infolist moves cursor to last item in infolist.
Prototype:
int weechat_infolist_prev (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
Return value:
1 if cursor has been moved on previous item, 0 if beginning of list was reached
C example:
if (weechat_infolist_prev (infolist)) { /* read variables in item... */ } else { /* no more item available */ }
Script (Python):
# prototype rc = weechat.infolist_prev(infolist) # example rc = weechat.infolist_prev(infolist) if rc: # read variables in item... else: # no more item available
Reset "cursor" for infolist.
Prototype:
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
C example:
weechat_infolist_reset_item_cursor (infolist);
Script (Python):
# prototype weechat.infolist_reset_item_cursor(infolist) # example weechat.infolist_reset_item_cursor(infolist)
Return list of fields for current infolist item.
Prototype:
const char *weechat_infolist_fields (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
Return value:
string with list of fields for current infolist item. List is comma separated, and contains letter for type, followed by variable name. Types are: "i" (integer), "s" (string), "p" (pointer), "b" (buffer), "t" (time).
C example:
const char *fields = weechat_infolist_fields (infolist); /* fields contains something like: "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
Script (Python):
# prototype fields = weechat.infolist_fields(infolist) # example fields = weechat.infolist_fields(infolist) # fields contains something like: # "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
Return value of integer variable in current infolist item.
Prototype:
int weechat_infolist_integer (struct t_infolist *infolist, const char *var);
Arguments:
infolist: infolist pointer
var: variable name (must be type "integer")
Return value:
integer value of variable
C example:
weechat_printf (NULL, "integer = %d", weechat_infolist_integer (infolist, "my_integer"));
Script (Python):
# prototype value = weechat.infolist_integer(infolist, var) # example weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
Return value of string variable in current infolist item.
Prototype:
const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);
Arguments:
infolist: infolist pointer
var: variable name (must be type "string")
Return value:
string value of variable
C example:
weechat_printf (NULL, "string = %s", weechat_infolist_string (infolist, "my_string"));
Script (Python):
# prototype value = weechat.infolist_string(infolist, var) # example weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
Return value of pointer variable in current infolist item.
Prototype:
void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);
Arguments:
infolist: infolist pointer
var: variable name (must be type "pointer")
Return value:
pointer value of variable
C example:
weechat_printf (NULL, "pointer = 0x%lx", weechat_infolist_pointer (infolist, "my_pointer"));
Script (Python):
# prototype value = weechat.infolist_pointer(infolist, var) # example weechat.prnt("", "pointer = 0x%lx" % weechat.infolist_pointer(infolist, "my_pointer"))
Return value of buffer variable in current infolist item.
Prototype:
void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var, int *size);
Arguments:
infolist: infolist pointer
var: variable name (must be type "buffer")
size: pointer to integer variable, will be set with buffer size
Return value:
buffer pointer
C example:
int size; void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size); weechat_printf (NULL, "buffer = 0x%lx, size = %d", pointer, size);
Return value of time variable in current infolist item.
Prototype:
time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);
Arguments:
infolist: infolist pointer
var: variable name (must be type "time")
Return value:
time value of variable
C example:
weechat_printf (NULL, "time = %ld", weechat_infolist_time (infolist, "my_time"));
Script (Python):
# prototype value = weechat.infolist_time(infolist, var) # example weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
Free an infolist.
Prototype:
void weechat_infolist_free (struct t_infolist *infolist);
Arguments:
infolist: infolist pointer
C example:
weechat_infolist_free (infolist);
Script (Python):
# prototype weechat.infolist_free(infolist) # example weechat.infolist_free(infolist)
Functions for upgrading WeeChat (command "/upgrade").
Create or read a file for upgrade.
Prototype:
struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);
Arguments:
filename: name of file (extension ".upgrade" will be added to this name by WeeChat)
write:
1: create file (write mode, before upgrade)
0: read file (after upgrade)
Return value:
pointer to upgrade file
C example:
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);
Script (Python):
# prototype upgrade_file = weechat.upgrade_new(filename, write) # example upgrade_file = weechat.upgrade_new("my_file", 1)
Write an object in upgrade file.
Prototype:
struct t_upgrade_file *weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file, int object_id, struct t_infolist *infolist);
Arguments:
upgrade_file: upgrade file pointer
object_id: id for object
infolist: infolist to write in file
Return value:
1 if ok, 0 if error
C example:
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist)) { /* ok */ } else { /* error */ }
Script (Python):
# prototype weechat.upgrade_write_object(upgrade_file, object_id, infolist) # example weechat.upgrade_write_object(upgrade_file, 1, infolist)
Read an upgrade file.
Prototype:
struct t_upgrade_file *weechat_upgrade_read (struct t_upgrade_file *upgrade_file, int (*callback_read)(void *data, struct t_upgrade_file *upgrade_file, int object_id, struct t_infolist *infolist), void *callback_read_data);
Arguments:
upgrade_file: upgrade file pointer
callback_read: function called for each object read in upgrade file
callback_read_data: pointer given to read callback when it is called by WeeChat
Return value:
1 if ok, 0 if error
C example:
int my_upgrade_read_cb (struct t_upgrade_file *upgrade_file, int object_id, struct t_infolist *infolist) { /* read variables... */ return WEECHAT_RC_OK; } weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
Script (Python):
# prototype weechat.upgrade_read(upgrade_file, callback_read, callback_read_data) # example def my_upgrade_read_cb(upgrade_file, object_id, infolist): # read variables... return weechat.WEECHAT_RC_OK weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
Close an upgrade file.
Prototype:
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
Arguments:
upgrade_file: upgrade file pointer
C example:
weechat_upgrade_close (upgrade_file);
Script (Python):
# prototype weechat.upgrade_close(upgrade_file) # example weechat.upgrade_close(upgrade_file)