diff options
Diffstat (limited to 'doc/en/weechat_plugin_api.en.asciidoc')
| -rw-r--r-- | doc/en/weechat_plugin_api.en.asciidoc | 14936 |
1 files changed, 14936 insertions, 0 deletions
diff --git a/doc/en/weechat_plugin_api.en.asciidoc b/doc/en/weechat_plugin_api.en.asciidoc new file mode 100644 index 000000000..51dd0b2c9 --- /dev/null +++ b/doc/en/weechat_plugin_api.en.asciidoc @@ -0,0 +1,14936 @@ += WeeChat plugin API reference +:author: Sébastien Helleu +:email: flashcode@flashtux.org +:lang: en +:toc: +:toclevels: 4 + + +This manual documents WeeChat chat client, it is part of WeeChat. + +Latest version of this document can be found on this page: +http://weechat.org/doc + + +[[introduction]] +== Introduction + +WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and +light, designed for many operating systems. + +This manual documents WeeChat plugins API, used by C plugins to interact with +WeeChat core. + +[[plugins_in_weechat]] +== Plugins in WeeChat + +A plugin is a C program which can call WeeChat functions defined in an +interface. + +This C program does not need WeeChat sources to compile and can be dynamically +loaded into WeeChat with command `/plugin`. + +The plugin has to be a dynamic library, for dynamic loading by operating +system. +Under GNU/Linux, the file has ".so" extension, ".dll" under Windows. + +The plugin has to include "weechat-plugin.h" file (available in WeeChat source +code). +This file defines structures and types used to communicate with WeeChat. + +[[macros]] +=== Macros + +The plugin must use some macros (to define some variables): + +WEECHAT_PLUGIN_NAME("name"):: + plugin name + +WEECHAT_PLUGIN_DESCRIPTION("description"):: + short description of plugin + +WEECHAT_PLUGIN_VERSION("1.0"):: + plugin version + +WEECHAT_PLUGIN_LICENSE("GPL3"):: + plugin license + +[[main_functions]] +=== Main functions + +The plugin must use two functions: + +* weechat_plugin_init +* weechat_plugin_end + +==== weechat_plugin_init + +This function is called when plugin is loaded by WeeChat. + +Prototype: + +[source,C] +---- +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) + +==== weechat_plugin_end + +This function is called when plugin is unloaded by WeeChat. + +Prototype: + +[source,C] +---- +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_plugin]] +=== Compile plugin + +Compile does not need WeeChat sources, only file 'weechat-plugin.h' is +required. + +To compile a plugin which has one file "toto.c" (under GNU/Linux): + +---- +$ gcc -fPIC -Wall -c toto.c +$ gcc -shared -fPIC -o libtoto.so toto.o +---- + +[[load_plugin]] +=== Load plugin + +Copy file 'libtoto.so' into system plugins directory (for example +'/usr/local/lib/weechat/plugins') or into user's plugins directory (for example +'/home/xxx/.weechat/plugins'). + +Under WeeChat: + +---- +/plugin load toto +---- + +[[plugin_example]] +=== Plugin example + +Full example of plugin, which adds a command '/double': displays two times +arguments on current buffer, or execute two times a command (OK that's not +very useful, but that's just an example!): + +[source,C] +---- +#include <stdlib.h> + +#include "weechat-plugin.h" + +WEECHAT_PLUGIN_NAME("double"); +WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); +WEECHAT_PLUGIN_AUTHOR("Sébastien Helleu <flashcode@flashtux.org>"); +WEECHAT_PLUGIN_VERSION("0.1"); +WEECHAT_PLUGIN_LICENSE("GPL3"); + +struct t_weechat_plugin *weechat_plugin = NULL; + + +/* callback for command "/double" */ + +int +command_double_cb (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* make C compiler happy */ + (void) data; + (void) buffer; + (void) argv; + + if (argc > 1) + { + weechat_command (NULL, argv_eol[1]); + weechat_command (NULL, argv_eol[1]); + } + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_init (struct t_weechat_plugin *plugin, + int argc, char *argv[]) +{ + weechat_plugin = plugin; + + weechat_hook_command ("double", + "Display two times a message " + "or execute two times a command", + "message | command", + "message: message to display two times\n" + "command: command to execute two times", + NULL, + &command_double_cb, NULL); + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_end (struct t_weechat_plugin *plugin) +{ + /* make C compiler happy */ + (void) plugin; + + return WEECHAT_RC_OK; +} +---- + +[[plugin_api]] +== Plugin API + +Following chapters describe functions in API, sorted by category. + +For each function, we give: + +* description of function, +* C prototype, +* detail of arguments, +* return value, +* C example, +* example in Python script (syntax for other scripting languages is similar). + +[[plugins]] +=== Plugins + +Functions to get infos about plugins. + +==== weechat_plugin_get_name + +Get plugin name. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +const char *name = weechat_plugin_get_name (plugin); +---- + +Script (Python): + +[source,python] +---- +# prototype +name = weechat.plugin_get_name(plugin) + +# example +plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin") +name = weechat.plugin_get_name(plugin) +---- + +[[strings]] +=== Strings + +Many string functions below are already available thru standard C functions, +but it's recommended to use functions in this API because they are OK with +UTF-8 and locale. + +==== weechat_charset_set + +Set new plugin charset (default charset is 'UTF-8', so if your plugin uses +'UTF-8', you don't need to call this function). + +Prototype: + +[source,C] +---- +void weechat_charset_set (const char *charset); +---- + +Arguments: + +* 'charset': new charset to use + +C example: + +[source,C] +---- +weechat_charset_set ("iso-8859-1"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.charset_set(charset) + +# example +weechat.charset_set("iso-8859-1") +---- + +==== weechat_iconv_to_internal + +Convert string to WeeChat internal charset (UTF-8). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_iconv_to_internal ("iso-8859-1", "iso string: é à"); +/* ... */ +free (str); +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.iconv_to_internal(charset, string) + +# example +str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à") +---- + +==== weechat_iconv_from_internal + +Convert string from internal WeeChat charset (UTF-8) to another. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à"); +/* ... */ +free (str); +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.iconv_from_internal(charset, string) + +# example +str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à") +---- + +==== weechat_gettext + +Return translated string (depends on local language). + +Prototype: + +[source,C] +---- +const char *weechat_gettext (const char *string); +---- + +Arguments: + +* 'string': string to translate + +Return value: + +* translated string + +C example: + +[source,C] +---- +char *str = weechat_gettext ("hello"); +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.gettext(string) + +# example +str = weechat.gettext("hello") +---- + +==== weechat_ngettext + +Return translated string, using single or plural form, according to 'count' +argument. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_ngettext ("file", "files", num_files); +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.ngettext(string, plural, count) + +# example +num_files = 2 +str = weechat.ngettext("file", "files", num_files) +---- + +==== weechat_strndup + +Return duplicated string, with 'length' chars max. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_tolower + +Convert UTF-8 string to lower case. + +Prototype: + +[source,C] +---- +void weechat_string_tolower (char *string); +---- + +Arguments: + +* 'string': string to convert + +C example: + +[source,C] +---- +char str[] = "AbCdé"; +weechat_string_tolower (str); /* str is now: "abcdé" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_toupper + +Convert UTF-8 string to upper case. + +Prototype: + +[source,C] +---- +void weechat_string_toupper (char *string); +---- + +Arguments: + +* 'string': string to convert + +C example: + +[source,C] +---- +char str[] = "AbCdé"; +weechat_string_toupper (str); /* str is now: "ABCDé" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strcasecmp + +Locale and case independent string comparison. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strcasecmp_range + +_WeeChat ≥ 0.3.7._ + +Locale and case independent string comparison, using a range for case +comparison. + +Prototype: + +[source,C] +---- +int weechat_strcasecmp_range (const char *string1, const char *string2, int range); +---- + +Arguments: + +* 'string1': first string for comparison +* 'string2': second string for comparison +* 'range': number of chars in case comparison, for example: +** 26: "A-Z" are lowered to "a-z" +** 29: "A-Z [ \ ]" are lowered to "a-z { | }" +** 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~" + +[NOTE] +Values 29 and 30 are used by some protocols like IRC. + +Return value: + +* difference between two strings: +** negative if string1 < string2 +** zero if string1 == string2 +** positive if string1 > string2 + +C example: + +[source,C] +---- +int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29); /* == 0 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strncasecmp + +Locale and case independent string comparison, for 'max' chars. + +Prototype: + +[source,C] +---- +int weechat_strncasecmp (const char *string1, const char *string2, int max); +---- + +Arguments: + +* 'string1': first string for comparison +* 'string2': second string for comparison +* 'max': max chars to compare + +Return value: + +* difference between two strings: +** negative if string1 < string2 +** zero if string1 == string2 +** positive if string1 > string2 + +C example: + +[source,C] +---- +int diff = weechat_strncasecmp ("aabb", "aacc", 2); /* == 0 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strncasecmp_range + +_WeeChat ≥ 0.3.7._ + +Locale and case independent string comparison, for 'max' chars, using a range +for case comparison. + +Prototype: + +[source,C] +---- +int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range); +---- + +Arguments: + +* 'string1': first string for comparison +* 'string2': second string for comparison +* 'max': max chars to compare +* 'range': number of chars in case comparison, for example: +** 26: "A-Z" are lowered to "a-z" +** 29: "A-Z [ \ ]" are lowered to "a-z { | }" +** 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~" + +[NOTE] +Values 29 and 30 are used by some protocols like IRC. + +Return value: + +* difference between two strings: +** negative if string1 < string2 +** zero if string1 == string2 +** positive if string1 > string2 + +C example: + +[source,C] +---- +int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29); /* == 0 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strcmp_ignore_chars + +Locale (and optionally case independent) string comparison, ignoring some +chars. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strcasestr + +Locale and case independent string search. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_strlen_screen + +_WeeChat ≥ 0.4.2._ + +Return number of chars needed on screen to display UTF-8 string. +Non-printable chars have a width of 1 (this is the difference with the function +<<_weechat_utf8_strlen_screen,weechat_utf8_strlen_screen>>). + +Prototype: + +[source,C] +---- +int weechat_strlen_screen (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* number of chars needed on screen to display UTF-8 string + +C example: + +[source,C] +---- +int length_on_screen = weechat_strlen_screen ("é"); /* == 1 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +length = weechat.strlen_screen(string) + +# example +length = weechat.strlen_screen("é") # 1 +---- + +==== weechat_string_match + +_Updated in 1.0._ + +Check if a string matches a mask. + +Prototype: + +[source,C] +---- +int weechat_string_match (const char *string, const char *mask, + int case_sensitive); +---- + +Arguments: + +* 'string': string +* 'mask': mask with wildcards ("*"), each wildcard matches 0 or more chars in + the string +* 'case_sensitive': 1 for case sensitive comparison, otherwise 0 + +[NOTE] +Since version 1.0, wildcards are allowed inside the mask +(not only beginning/end of mask). + +Return value: + +* 1 if string matches mask, otherwise 0 + +C example: + +[source,C] +---- +int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ +int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ +int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ +int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */ +int match5 = weechat_string_match ("abcdef", "*b*d*", 0); /* == 1 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +match = weechat.string_match(string, mask, case_sensitive) + +# examples +match1 = weechat.string_match("abcdef", "abc*", 0) # 1 +match2 = weechat.string_match("abcdef", "*dd*", 0) # 0 +match3 = weechat.string_match("abcdef", "*def", 0) # 1 +match4 = weechat.string_match("abcdef", "*de*", 0) # 1 +match5 = weechat.string_match("abcdef", "*b*d*", 0) # 1 +---- + +==== weechat_string_expand_home + +_WeeChat ≥ 0.3.3._ + +Replace leading `~` by string with home directory. If string does not start +with `~`, then same string is returned. + +Prototype: + +[source,C] +---- +char *weechat_string_expand_home (const char *path); +---- + +Arguments: + +* 'path': path + +Return value: + +* path with leading `~` replaced by home directory (must be freed by calling + "free" after use) + +C example: + +[source,C] +---- +char *str = weechat_string_expand_home ("~/file.txt"); +/* result: "/home/xxx/file.txt" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_remove_quotes + +Remove quotes at beginning and end of string (ignore spaces if there are before +first quote or after last quote). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'"); +/* result: "I can't" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_strip + +Strip chars at beginning and/or end of string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* result: ".abc" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_convert_escaped_chars + +_WeeChat ≥ 1.0._ + +Convert escaped chars to their value: + +* `\"`: double quote +* `\\`: backslash +* `\a`: alert (BEL) +* `\b`: backspace +* `\e`: escape +* `\f`: form feed +* `\n`: new line +* `\r`: carriage return +* `\t`: horizontal tab +* `\v`: vertical tab +* `\0ooo`: char as octal value (ooo is 0 to 3 digits) +* `\xhh`: char as hexadecimal value (hh is 1 to 2 digits) +* `\uhhhh`: unicode char as hexadecimal value (hhhh is 1 to 4 digits) +* `\Uhhhhhhhh`: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits) + +Prototype: + +[source,C] +---- +char *weechat_string_convert_escaped_chars (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* string with escaped chars replaced by their value (must be freed by calling + "free" after use) + +C example: + +[source,C] +---- +char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603"); +/* str == "snowman: ☃" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_mask_to_regex + +Return a regex, built with a mask, where only special char is "`*`". All other +special chars for regex are escaped. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str_regex = weechat_string_mask_to_regex ("test*mask"); +/* result: "test.*mask" */ +/* ... */ +free (str_regex); +---- + +Script (Python): + +[source,python] +---- +# prototype +regex = weechat.string_mask_to_regex(mask) + +# example +regex = weechat.string_mask_to_regex("test*mask") # "test.*mask" +---- + +==== weechat_string_regex_flags + +_WeeChat ≥ 0.3.7._ + +Get pointer on string after flags and mask with flags to compile regular +expression. + +Prototype: + +[source,C] +---- +const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags) +---- + +Arguments: + +* 'regex': POSIX extended regular expression +* 'default_flags': combination of following values (see `man regcomp`): +** REG_EXTENDED +** REG_ICASE +** REG_NEWLINE +** REG_NOSUB +* 'flags': pointer value is set with flags used in regular expression (default + flags + flags set in regular expression) + +Flags must be at beginning of regular expression. Format is: +"(?eins-eins)string". + +Allowed flags are: + +* 'e': POSIX extended regular expression ('REG_EXTENDED') +* 'i': case insensitive ('REG_ICASE') +* 'n': match-any-character operators don't match a newline ('REG_NEWLINE') +* 's': support for substring addressing of matches is not required ('REG_NOSUB') + +Return value: + +* pointer in 'regex', after flags + +C example: + +[source,C] +---- +const char *regex = "(?i)test"; +int flags; +const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags); +/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_regcomp + +_WeeChat ≥ 0.3.7._ + +Compile a POSIX extended regular expression using optional flags at beginning +of string (for format of flags, see +<<_weechat_string_regex_flags,weechat_string_regex_flags>>). + +Prototype: + +[source,C] +---- +int weechat_string_regcomp (void *preg, const char *regex, int default_flags) +---- + +Arguments: + +* 'preg': pointer to 'regex_t' structure +* 'regex': POSIX extended regular expression +* 'default_flags': combination of following values (see `man regcomp`): +** REG_EXTENDED +** REG_ICASE +** REG_NEWLINE +** REG_NOSUB + +Return value: + +* same return code as function `regcomp` (0 if OK, other value for error, + see `man regcomp`) + +C example: + +[source,C] +---- +regex_t my_regex; +if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0) +{ + /* error */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_has_highlight + +Check if a string has one or more highlights, using list of highlight words. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +highlight = weechat.string_has_highlight(string, highlight_words) + +# example +highlight = weechat.string_has_highlight("my test string", "test,word2") # 1 +---- + +==== weechat_string_has_highlight_regex + +_WeeChat ≥ 0.3.4._ + +Check if a string has one or more highlights, using a POSIX extended regular +expression. + +For at least one match of regular expression on string, it must be surrounded +by delimiters (chars different from: alphanumeric, "-", "_" and "|"). + +Prototype: + +[source,C] +---- +int weechat_string_has_highlight_regex (const char *string, const char *regex); +---- + +Arguments: + +* 'string': string +* 'regex': POSIX extended regular expression + +Return value: + +* 1 if string has one or more highlights, otherwise 0 + +C example: + +[source,C] +---- +int hl = weechat_string_has_highlight_regex ("my test string", "test|word2"); /* == 1 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +highlight = weechat.string_has_highlight_regex(string, regex) + +# example +highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1 +---- + +==== weechat_string_replace + +Replace all occurrences of a string by another string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_replace_regex + +_WeeChat ≥ 1.0._ + +Replace text in a string using a regular expression, replacement text and +optional callback. + +Prototype: + +[source,C] +---- +char *weechat_string_replace_regex (const char *string, void *regex, + const char *replace, const char reference_char, + char *(*callback)(void *data, const char *text), + void *callback_data); +---- + +Arguments: + +* 'string': string +* 'regex': pointer to a regular expression ('regex_t' structure) compiled with + WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or regcomp + (see `man regcomp`) +* 'replace': replacement text, where following references are allowed: +** `$0` to `$99`: match 0 to 99 in regular expression (0 is the whole match, + 1 to 99 are groups captured between parentheses) +** `$+`: the last match (with highest number) +** `$.*N`: match `N` (can be `+` or `0` to `99`), with all chars replaced by `*` + (the `*` char can be any char between space (32) and `~` (126)) +* 'reference_char': the char used for reference to match (commonly '$') +* 'callback': an optional callback called for each reference in 'replace' + (except for matches replaced by a char); the callback must return: +** newly allocated string: it is used as replacement text (it is freed after + use) +** NULL: the text received in callback is used as replacement text (without + changes) +* 'callback_data': pointer given to callback when it is called + +Return value: + +* string with text replaced, NULL if problem (must be freed by calling "free" + after use) + +C example: + +[source,C] +---- +regex_t my_regex; +char *string; +if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})", + REG_EXTENDED) == 0) +{ + string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex, + "$3/$2/$1", '$', NULL, NULL); + /* string == "date: 14/02/2014" */ + if (string) + free (string); + regfree (&my_regex); +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_split + +Split a string according to one or more delimiter(s). + +Prototype: + +[source,C] +---- +char **weechat_string_split (const char *string, const char *separators, + int keep_eol, int num_items_max, + int *num_items); +---- + +Arguments: + +* 'string': string to split +* 'separators': delimiters used for split +* 'keep_eol': +** 0: each string will contain one word +** 1: each string will contain all string until end of line (see example below) +** 2: same as 1, but do not remove separators at end of string before split + _(WeeChat ≥ 0.3.6)_ +* 'num_items_max': maximum number of items created (0 = no limit) +* 'num_items': pointer to int which will contain number of items created + +Return value: + +* array of strings, NULL if problem (must be freed by calling + <<_weechat_string_free_split,weechat_string_free_split>> after use) + +C example: + +[source,C] +---- +char **argv; +int argc; +argv = weechat_string_split ("abc de fghi", " ", 0, 0, &argc); +/* result: argv[0] == "abc" + argv[1] == "de" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_split (argv); + +argv = weechat_string_split ("abc de fghi", " ", 1, 0, &argc); +/* result: argv[0] == "abc de fghi" + argv[1] == "de fghi" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_split (argv); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_split_shell + +_WeeChat ≥ 1.0._ + +Split a string like the shell does for a command with arguments. + +This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in +Python repository), see: http://docs.python.org/3/library/shlex.html. + +Prototype: + +[source,C] +---- +char **weechat_string_split_shell (const char *string, int *num_items); +---- + +Arguments: + +* 'string': string to split +* 'num_items': pointer to int which will contain number of items created + +Return value: + +* array of strings, NULL if problem (must be freed by calling + <<_weechat_string_free_split,weechat_string_free_split>> after use) + +C example: + +[source,C] +---- +char **argv; +int argc; +argv = weechat_string_split_shell ("test 'first arg' \"second arg\"", &argc); +/* result: argv[0] == "test" + argv[1] == "first arg" + argv[2] == "second arg" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_split (argv); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_free_split + +Free memory used by a split string. + +Prototype: + +[source,C] +---- +void weechat_string_free_split (char **split_string); +---- + +Arguments: + +* 'split_string': string split by function + <<_weechat_string_split,weechat_string_split>> + +C example: + +[source,C] +---- +char *argv; +int argc; +argv = weechat_string_split (string, " ", 0, 0, &argc); +/* ... */ +weechat_string_free_split (argv); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_build_with_split_string + +Build a string with a split string. + +Prototype: + +[source,C] +---- +char *weechat_string_build_with_split_string (char **split_string, + const char *separator); +---- + +Arguments: + +* 'split_string': string split by function + <<_weechat_string_split,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: + +[source,C] +---- +char **argv; +int argc; +argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc); +char *str = weechat_string_build_with_split_string (argv, ";"); +/* str == "abc;def;ghi" */ +/* ... */ +free (str); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_split_command + +Split a list of commands separated by 'separator' (which can be escaped by "\" +in string). + +Prototype: + +[source,C] +---- +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,weechat_free_split_command>> after use) + +C example: + +[source,C] +---- +char **argv = weechat_string_split_command ("/command1 arg;/command2", ';'); +/* result: argv[0] == "/command1 arg" + argv[1] == "/command2" +*/ +weechat_free_split_command (argv); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_free_split_command + +Free memory used by a split command. + +Prototype: + +[source,C] +---- +void weechat_string_free_split_command (char **split_command); +---- + +Arguments: + +* 'split_command': command split by + <<_weechat_string_split_command,weechat_string_split_command>> + +C example: + +[source,C] +---- +char **argv = weechat_string_split_command ("/command1 arg;/command2", ';'); +/* ... */ +weechat_free_split_command (argv); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_format_size + +Build a string with formatted file size and a unit translated to local +language. + +Prototype: + +[source,C] +---- +char *weechat_string_format_size (unsigned long long size); +---- + +Arguments: + +* 'size': size (in bytes) + +Return value: + +* formatted string (must be freed by calling "free" after use) + +C examples: + +[source,C] +---- +/* 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); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_remove_color + +Remove WeeChat colors from a string. + +Prototype: + +[source,C] +---- +char *weechat_string_remove_color (const char *string, + const char *replacement); +---- + +Arguments: + +* 'string': string +* 'replacement': if not NULL and not empty, WeeChat color codes are replaced by + first char of this string, otherwise WeeChat color codes and following chars + (if related to color) are removed from string + +Return value: + +* string without color (must be freed by calling "free" after use) + +C examples: + +[source,C] +---- +/* 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): + +[source,python] +---- +# prototype +str = weechat.string_remove_color(string, replacement) + +# example +str = weechat.string_remove_color(my_string, "?") +---- + +==== weechat_string_encode_base64 + +_WeeChat ≥ 0.3.2._ + +Encode a string in base64. + +Prototype: + +[source,C] +---- +void weechat_string_encode_base64 (const char *from, int length, char *to); +---- + +Arguments: + +* 'from': string to encode +* 'length': length of string to encode (for example `strlen(from)`) +* 'to': pointer to string to store result (must be long enough, result is + longer than initial string) + +C example: + +[source,C] +---- +char *string = "abcdefgh", result[128]; +weechat_string_encode_base64 (string, strlen (string), result); +/* result == "YWJjZGVmZ2g=" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_decode_base64 + +_WeeChat ≥ 0.3.2._ + +Decode a base64 string. + +Prototype: + +[source,C] +---- +int weechat_string_decode_base64 (const char *from, char *to); +---- + +Arguments: + +* 'from': string to decode +* 'to': pointer to string to store result (must be long enough, result is + shorter than initial string) + +Return value: + +* length of string stored in *to (does not count final '\0') + +C example: + +[source,C] +---- +char *string = "YWJjZGVmZ2g=", result[128]; +int length; +length = weechat_string_decode_base64 (string, result); +/* length == 8, result == "abcdefgh" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_string_is_command_char + +_WeeChat ≥ 0.3.2._ + +Check if first char of string is a command char (default command char is '/'). + +Prototype: + +[source,C] +---- +int weechat_string_is_command_char (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* 1 if first char of string is a command char, otherwise 0 + +C examples: + +[source,C] +---- +int command_char1 = weechat_string_is_command_char ("/test"); /* == 1 */ +int command_char2 = weechat_string_is_command_char ("test"); /* == 0 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +is_cmdchar = weechat.string_is_command_char(string) + +# examples +command_char1 = weechat.string_is_command_char("/test") # == 1 +command_char2 = weechat.string_is_command_char("test") # == 0 +---- + +==== weechat_string_input_for_buffer + +_WeeChat ≥ 0.3.2._ + +Return pointer to input text for buffer (pointer inside "string" argument), or +NULL if it's a command. + +Prototype: + +[source,C] +---- +const char *weechat_string_input_for_buffer (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* pointer into "string", or NULL + +C examples: + +[source,C] +---- +const char *str1 = weechat_string_input_for_buffer ("test"); /* "test" */ +const char *str2 = weechat_string_input_for_buffer ("/test"); /* NULL */ +const char *str3 = weechat_string_input_for_buffer ("//test"); /* "/test" */ +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.string_input_for_buffer(string) + +# examples +str1 = weechat.string_input_for_buffer("test") # "test" +str2 = weechat.string_input_for_buffer("/test") # "" +str3 = weechat.string_input_for_buffer("//test") # "/test" +---- + +==== weechat_string_eval_expression + +_WeeChat ≥ 0.4.0, updated in 0.4.2._ + +Evaluate an expression and return result as a string. +Special variables with format `${variable}` are expanded (see command `/eval` in +'WeeChat User's guide'). + +[NOTE] +Since version 1.0, nested variables are supported, for example: +`${color:${variable}}`. + +Prototype: + +[source,C] +---- +char *weechat_string_eval_expression (const char *expr, + struct t_hashtable *pointers, + struct t_hashtable *extra_vars, + struct t_hashtable *options); +---- + +Arguments: + +* 'expr': the expression to evaluate +* 'pointers': hashtable with pointers (keys must be string, values must be + pointer); pointers "window" and "buffer" are automatically added if they are + not in hashtable (with pointer to current window/buffer) (can be NULL) +* 'extra_vars': extra variables that will be expanded (can be NULL) +* 'options': a hashtable with some options (keys and values must be string) + (can be NULL): +** 'type': default behavior is just to replace values in expression, other + types can be selected: +*** 'condition': the expression is evaluated as a condition: operators and + parentheses are used, result is a boolean ("0" or "1") +** 'prefix': prefix before variables to replace (default: "${") +** 'suffix': suffix after variables to replace (default: "}") + +Return value: + +* evaluated expression (must be freed by calling "free" after use), or NULL + if problem (invalid expression or not enough memory) + +C examples: + +[source,C] +---- +struct t_hashtable *options = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (options) + weechat_hashtable_set (options, "type", "condition"); +char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL); /* "core.weechat" */ +char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options); /* "1" */ +char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options); /* "0" */ +---- + +Script (Python): + +[source,python] +---- +# prototype +str = weechat.string_eval_expression(expr, pointers, extra_vars, options) + +# examples +str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat" +str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"}) # "1" +str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"}) # "0" +---- + +[[utf-8]] +=== UTF-8 + +Some UTF-8 string functions. + +==== weechat_utf8_has_8bits + +Check if a string has 8-bits chars. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_utf8_has_8bits (string)) +{ + /* ... */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_is_valid + +Check if a string is UTF-8 valid. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *error; +if (weechat_utf8_is_valid (string, &error)) +{ + /* ... */ +} +else +{ + /* "error" points to first invalid char */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_normalize + +Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char. + +Prototype: + +[source,C] +---- +void weechat_utf8_normalize (char *string, char replacement); +---- + +Arguments: + +* 'string': string +* 'replacement': replacement char for invalid chars + +C example: + +[source,C] +---- +weechat_utf8_normalize (string, '?'); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_prev_char + +Return pointer to previous UTF-8 char in a string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *prev_char = weechat_utf8_prev_char (string, ptr_in_string); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_next_char + +Return pointer to next UTF-8 char in a string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *next_char = weechat_utf8_next_char (string); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_char_int + +Return UTF-8 char as integer. + +Prototype: + +[source,C] +---- +int weechat_utf8_char_int (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* UTF-8 char as integer + +C example: + +[source,C] +---- +int char_int = weechat_utf8_char_int ("être"); /* "ê" as integer */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_char_size + +Return UTF-8 char size (in bytes). + +Prototype: + +[source,C] +---- +int weechat_utf8_char_size (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* UTF-8 char size (in bytes) + +C example: + +[source,C] +---- +int char_size = weechat_utf8_char_size ("être"); /* == 2 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_strlen + +Return UTF-8 string length (in UTF-8 chars). + +Prototype: + +[source,C] +---- +int weechat_utf8_strlen (const char *string); +---- + +Arguments: + +* 'string': string + +Return value: + +* UTF-8 string length (number of UTF-8 chars) + +C example: + +[source,C] +---- +int length = weechat_utf8_strlen ("chêne"); /* == 5 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_strnlen + +Return UTF-8 string length (in UTF-8 chars), for max 'bytes' in string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_strlen_screen + +Return number of chars needed on screen to display UTF-8 string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_charcmp + +Compare two UTF-8 chars. + +Prototype: + +[source,C] +---- +int weechat_utf8_charcmp (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: + +[source,C] +---- +int diff = weechat_utf8_charcmp ("aaa", "ccc"); /* == -2 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_charcasecmp + +Compare two UTF-8 chars, ignoring case. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_char_size_screen + +Return number of chars needed on screen to display UTF-8 char. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_add_offset + +Move forward N chars in an UTF-8 string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *str = "chêne"; +char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_real_pos + +Return real position in UTF-8 string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_pos + +Return position in UTF-8 string. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_utf8_strndup + +Return duplicate string, with 'length' chars max. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *string = weechat_utf8_strndup ("chêne", 3); /* returns "chê" */ +/* ... */ +free (string); +---- + +[NOTE] +This function is not available in scripting API. + +[[directories]] +=== Directories + +Some functions related to directories. + +==== weechat_mkdir_home + +Create a directory in WeeChat home. + +Prototype: + +[source,C] +---- +int weechat_mkdir_home (char *directory, int mode); +---- + +Arguments: + +* 'directory': name of directory to create +* 'mode': mode for directory + +Return value: + +* 1 if directory was successfully created, 0 if an error occurred + +C example: + +[source,C] +---- +if (!weechat_mkdir_home ("temp", 0755)) +{ + /* error */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.mkdir_home(directory, mode) + +# example +weechat.mkdir_home("temp", 0755) +---- + +==== weechat_mkdir + +Create a directory. + +Prototype: + +[source,C] +---- +int weechat_mkdir (char *directory, int mode); +---- + +Arguments: + +* 'directory': name of directory to create +* 'mode': mode for directory + +Return value: + +* 1 if directory was successfully created, 0 if an error occurred + +C example: + +[source,C] +---- +if (!weechat_mkdir ("/tmp/mydir", 0755)) +{ + /* error */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.mkdir(directory, mode) + +# example +weechat.mkdir("/tmp/mydir", 0755) +---- + +==== weechat_mkdir_parents + +Create a directory and make parent directories as needed. + +Prototype: + +[source,C] +---- +int weechat_mkdir_parents (char *directory, int mode); +---- + +Arguments: + +* 'directory': name of directory to create +* 'mode': mode for directory + +Return value: + +* 1 if directory was successfully created, 0 if an error occurred + +C example: + +[source,C] +---- +if (!weechat_mkdir_parents ("/tmp/my/dir", 0755)) +{ + /* error */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.mkdir_parents(directory, mode) + +# example +weechat.mkdir_parents("/tmp/my/dir", 0755) +---- + +==== weechat_exec_on_files + +Find files in a directory and execute a callback on each file. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +void callback (void *data, const char *filename) +{ + /* ... */ +} +... +weechat_exec_on_files ("/tmp", 0, NULL, &callback); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_file_get_content + +_WeeChat ≥ 0.3.1._ + +Get content of text file in a string. + +Prototype: + +[source,C] +---- +char *weechat_file_get_content (const char *filename); +---- + +Arguments: + +* 'filename': path and file name + +Return value: + +* content of file as string (must be freed by calling "free" after use) + +C example: + +[source,C] +---- +char *content; + +content = weechat_file_get_content ("/tmp/test.txt"); +/* ... */ +free (content); +---- + +[NOTE] +This function is not available in scripting API. + +[[util]] +=== Util + +Some useful functions. + +==== weechat_util_timeval_cmp + +Compare two "timeval" structures. + +Prototype: + +[source,C] +---- +int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2); +---- + +Arguments: + +* 'tv1': first "timeval" structure +* 'tv2': second "timeval" structure + +Return value: + +* -1 if tv1 < tv2 +* zero if tv1 == tv2 +* +1 if tv1 > tv2 + +C example: + +[source,C] +---- +if (weechat_util_timeval_cmp (&tv1, &tv2) > 0) +{ + /* tv1 > tv2 */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_util_timeval_diff + +Return difference (in milliseconds) between two "timeval" structures. + +Prototype: + +[source,C] +---- +long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2); +---- + +Arguments: + +* 'tv1': first "timeval" structure +* 'tv2': second "timeval" structure + +Return value: + +* difference in milliseconds + +C example: + +[source,C] +---- +long diff = weechat_util_timeval_diff (&tv1, &tv2); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_util_timeval_add + +Add interval (in milliseconds) to a timeval structure. + +Prototype: + +[source,C] +---- +void weechat_util_timeval_add (struct timeval *tv, long interval); +---- + +Arguments: + +* 'tv': timeval structure +* 'interval': interval (in milliseconds) + +C example: + +[source,C] +---- +weechat_util_timeval_add (&tv, 2000); /* add 2 seconds */ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_util_get_time_string + +_WeeChat ≥ 0.3.2._ + +Get date/time as a string built with "strftime". + +Prototype: + +[source,C] +---- +char *weechat_util_get_time_string (const time_t *date); +---- + +Arguments: + +* 'date': pointer to date + +C example: + +[source,C] +---- +time_t date = time (NULL); +weechat_printf (NULL, "date: %s", + weechat_util_get_time_string (&date)); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_util_version_number + +_WeeChat ≥ 0.3.9._ + +Convert a string with WeeChat version to a number. + +Prototype: + +[source,C] +---- +int weechat_util_version_number (const char *version); +---- + +Arguments: + +* 'version': WeeChat version as string (example: "0.3.9" or "0.3.9-dev") + +C example: + +[source,C] +---- +version_number = weechat_util_version_number ("0.3.8"); /* == 0x00030800 */ +version_number = weechat_util_version_number ("0.3.9-dev"); /* == 0x00030900 */ +version_number = weechat_util_version_number ("0.3.9-rc1"); /* == 0x00030900 */ +version_number = weechat_util_version_number ("0.3.9"); /* == 0x00030900 */ +---- + +[NOTE] +This function is not available in scripting API. + +[[sorted_lists]] +=== Sorted lists + +Sorted list functions. + +==== weechat_list_new + +Create a new list. + +Prototype: + +[source,C] +---- +struct t_weelist *weechat_list_new (); +---- + +Return value: + +* pointer to new list + +C example: + +[source,C] +---- +struct t_weelist *list = weechat_list_new (); +---- + +Script (Python): + +[source,python] +---- +# prototype +list = weechat.list_new() + +# example +list = weechat.list_new() +---- + +==== weechat_list_add + +Add an item in a list. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_weelist_item *my_item = + weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_add(list, data, where, user_data) + +# example +item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "") +---- + +==== weechat_list_search + +Search an item in a list. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_weelist_item *item = weechat_list_search (list, "my data"); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_search(list, data) + +# example +item = weechat.list_search(list, "my data") +---- + +==== weechat_list_search_pos + +_WeeChat ≥ 0.3.4._ + +Search an item position in a list. + +Prototype: + +[source,C] +---- +int weechat_list_search_pos (struct t_weelist *weelist, + const char *data); +---- + +Arguments: + +* 'weelist': list pointer +* 'data': data to search in list + +Return value: + +* position of item found, -1 if item was not found + +C example: + +[source,C] +---- +int pos_item = weechat_list_search_pos (list, "my data"); +---- + +Script (Python): + +[source,python] +---- +# prototype +pos_item = weechat.list_search_pos(list, data) + +# example +pos_item = weechat.list_search_pos(list, "my data") +---- + +==== weechat_list_casesearch + +Search an item in a list, ignoring case. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_weelist_item *item = weechat_list_casesearch (list, "my data"); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_casesearch(list, data) + +# example +item = weechat.list_casesearch(list, "my data") +---- + +==== weechat_list_casesearch_pos + +_WeeChat ≥ 0.3.4._ + +Search an item position in a list, ignoring case. + +Prototype: + +[source,C] +---- +int weechat_list_casesearch_pos (struct t_weelist *weelist, + const char *data); +---- + +Arguments: + +* 'weelist': list pointer +* 'data': data to search in list + +Return value: + +* position of item found, -1 if item was not found + +C example: + +[source,C] +---- +int pos_item = weechat_list_casesearch_pos (list, "my data"); +---- + +Script (Python): + +[source,python] +---- +# prototype +pos_item = weechat.list_casesearch_pos(list, data) + +# example +pos_item = weechat.list_casesearch_pos(list, "my data") +---- + +==== weechat_list_get + +Return an item in a list by position. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */ +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_get(list, position) + +# example +item = weechat.list_get(list, 0) +---- + +==== weechat_list_set + +Set new value for an item. + +Prototype: + +[source,C] +---- +void weechat_list_set (struct t_weelist_item *item, const char *value); +---- + +Arguments: + +* 'item': item pointer +* 'value': new value for item + +C example: + +[source,C] +---- +weechat_list_set (item, "new data"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.list_set(item, value) + +# example +weechat.list_set(item, "new data") +---- + +==== weechat_list_next + +Return next item in list. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_weelist_item *next_item = weechat_list_next (item); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_next(item) + +# example +item = weechat.list_next(item) +---- + +==== weechat_list_prev + +Return previous item in list. + +Prototype: + +[source,C] +---- +struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item); +---- + +Arguments: + +* 'item': item pointer + +Return value: + +* pointer to previous item, NULL if pointer was first item in list + +C example: + +[source,C] +---- +struct t_weelist_item *prev_item = weechat_list_prev (item); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.list_prev(item) + +# example +item = weechat.list_prev(item) +---- + +==== weechat_list_string + +Return string value of an item. + +Prototype: + +[source,C] +---- +const char *weechat_list_string (struct t_weelist_item *item); +---- + +Arguments: + +* 'item': item pointer + +Return value: + +* string value of item + +C example: + +[source,C] +---- +weechat_printf (NULL, "value of item: %s", weechat_list_string (item)); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.list_string(item) + +# example +weechat.prnt("", "value of item: %s" % weechat.list_string(item)) +---- + +==== weechat_list_size + +Return size of list (number of items). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, "size of list: %d", weechat_list_size (list)); +---- + +Script (Python): + +[source,python] +---- +# prototype +size = weechat.list_size(list) + +# example +weechat.prnt("", "size of list: %d" % weechat.list_size(list)) +---- + +==== weechat_list_remove + +Remove an item in a list. + +Prototype: + +[source,C] +---- +void weechat_list_remove (struct t_weelist *weelist, + struct t_weelist_item *item); +---- + +Arguments: + +* 'weelist': list pointer +* 'item': item pointer + +C example: + +[source,C] +---- +weechat_list_remove (list, item); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.list_remove(list, item) + +# example +weechat.list_remove(list, item) +---- + +==== weechat_list_remove_all + +Remove all items in a list. + +Prototype: + +[source,C] +---- +void weechat_list_remove_all (struct t_weelist *weelist); +---- + +Arguments: + +* 'weelist': list pointer + +C example: + +[source,C] +---- +weechat_list_remove_all (list); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.list_remove_all(list) + +# example +weechat.list_remove_all(list) +---- + +==== weechat_list_free + +Free a list. + +Prototype: + +[source,C] +---- +void weechat_list_free (struct t_weelist *weelist); +---- + +Arguments: + +* 'weelist': list pointer + +C example: + +[source,C] +---- +weechat_list_free (list); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.list_free(list) + +# example +weechat.list_free(list) +---- + +[[hashtables]] +=== Hashtables + +Hashtable functions. + +==== weechat_hashtable_new + +_WeeChat ≥ 0.3.3._ + +Create a new hashtable. + +Prototype: + +[source,C] +---- +struct t_hashtable *weechat_hashtable_new (int size, + const char *type_keys, + const char *type_values, + unsigned long (*callback_hash_key)(struct t_hashtable *hashtable, + const void *key), + int (*callback_keycmp)(struct t_hashtable *hashtable, + const void *key1, + const void *key2)); +---- + +Arguments: + +* 'size': size of internal array to store hashed keys, a high value uses more + memory, but has better performance (this is *not* a limit for number of items + in hashtable) +* 'type_keys': type for keys in hashtable: +** 'WEECHAT_HASHTABLE_INTEGER' +** 'WEECHAT_HASHTABLE_STRING' +** 'WEECHAT_HASHTABLE_POINTER' +** 'WEECHAT_HASHTABLE_BUFFER' +** 'WEECHAT_HASHTABLE_TIME' +* 'type_values': type for values in hashtable: +** 'WEECHAT_HASHTABLE_INTEGER' +** 'WEECHAT_HASHTABLE_STRING' +** 'WEECHAT_HASHTABLE_POINTER' +** 'WEECHAT_HASHTABLE_BUFFER' +** 'WEECHAT_HASHTABLE_TIME' +* 'callback_hash_key': callback used to "hash" a key (key as integer value), can + be NULL if key type is not "buffer" (a default hash function is used), + arguments and return value: +** 'struct t_hashtable *hashtable': hashtable pointer +** 'const void *key': key +** return value: hash of the key +* 'callback_keycmp': callback used to compare two keys, can be NULL if key type + is not "buffer" (a default comparison function is used), arguments and return + value: +** 'struct t_hashtable *hashtable': hashtable pointer +** 'const void *key1': first key +** 'const void *key2': second key +** return value: +*** negative number if 'key1' is less than 'key2' +*** 0 if 'key1' equals 'key2' +*** positive number if 'key1' is greater than 'key2' + +Return value: + +* pointer to new hashtable, NULL if an error occurred + +C example: + +[source,C] +---- +struct t_hashtable *hashtable = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_set_with_size + +_WeeChat ≥ 0.3.3, updated in 0.4.2._ + +Add or update item in a hashtable with size for key and value. + +Prototype: + +[source,C] +---- +struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable, + const void *key, int key_size, + const void *value, int value_size); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'key': key pointer +* 'key_size': size of key (in bytes), used only if type of keys in hashtable + is "buffer" +* 'value': value pointer +* 'value_size': size of value (in bytes), used only if type of values in + hashtable is "buffer" + +Return value: + +* pointer to item created/updated, NULL if error + +C example: + +[source,C] +---- +weechat_hashtable_set_with_size (hashtable, "my_key", 0, + my_buffer, sizeof (my_buffer_struct)); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_set + +_WeeChat ≥ 0.3.3, updated in 0.4.2._ + +Add or update item in a hashtable. + +Prototype: + +[source,C] +---- +struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable, + const void *key, const void *value); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'key': key pointer +* 'value': value pointer + +Return value: + +* pointer to item created/updated, NULL if error + +C example: + +[source,C] +---- +weechat_hashtable_set (hashtable, "my_key", "my_value"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_get + +_WeeChat ≥ 0.3.3._ + +Get value associated with a key in a hashtable. + +Prototype: + +[source,C] +---- +void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'key': key pointer + +Return value: + +* value for key, NULL if key is not found + +C example: + +[source,C] +---- +void *value = weechat_hashtable_get (hashtable, "my_key"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_has_key + +_WeeChat ≥ 0.3.4._ + +Check if a key is in the hashtable. + +Prototype: + +[source,C] +---- +int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'key': key pointer + +Return value: + +* 1 if key is in hashtable, 0 if key is not in hashtable + +C example: + +[source,C] +---- +if (weechat_hashtable_has_key (hashtable, "my_key")) +{ + /* key is in hashtable */ + /* ... */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_map + +_WeeChat ≥ 0.3.3._ + +Call a function on all hashtable entries. + +Prototype: + +[source,C] +---- +void weechat_hashtable_map (struct t_hashtable *hashtable, + void (*callback_map)(void *data, + struct t_hashtable *hashtable, + const void *key, + const void *value), + void *callback_map_data); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'callback_map': function called for each entry in hashtable +* 'callback_map_data': pointer given to map callback when it is called + +C example: + +[source,C] +---- +void +map_cb (void *data, struct t_hashtable *hashtable, + const void *key, const void *value) +{ + /* display key and value (they are both strings here) */ + weechat_printf (NULL, "key: '%s', value: '%s'", + (const char *)key, + (const char *)value); +} +/* ... */ +weechat_hashtable_map (hashtable, &map_cb, NULL); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_map_string + +_WeeChat ≥ 0.3.7._ + +Call a function on all hashtable entries, sending keys and values as strings. + +Prototype: + +[source,C] +---- +void weechat_hashtable_map_string (struct t_hashtable *hashtable, + void (*callback_map)(void *data, + struct t_hashtable *hashtable, + const char *key, + const char *value), + void *callback_map_data); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'callback_map': function called for each entry in hashtable +* 'callback_map_data': pointer given to map callback when it is called + +[NOTE] +The strings 'key' and 'value' sent to callback are temporary strings, they +are deleted after call to callback. + +C example: + +[source,C] +---- +void +map_cb (void *data, struct t_hashtable *hashtable, + const char *key, const char *value) +{ + /* display key and value */ + weechat_printf (NULL, "key: '%s', value: '%s'", + key, value); +} +/* ... */ +weechat_hashtable_map_string (hashtable, &map_cb, NULL); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_dup + +_WeeChat ≥ 1.0._ + +Duplicate a hashtable. + +Prototype: + +[source,C] +---- +struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable); +---- + +Arguments: + +* 'hashtable': hashtable pointer + +Return value: + +* duplicated hashtable + +C example: + +[source,C] +---- +struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_get_integer + +_WeeChat ≥ 0.3.3._ + +Return integer value of a hashtable property. + +Prototype: + +[source,C] +---- +int weechat_hashtable_get_integer (struct t_hashtable *hashtable, + void *property); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'property': property name: +** 'size': size of internal array "htable" in hashtable +** 'items_count': number of items in hashtable + +Return value: + +* integer value of property + +C example: + +[source,C] +---- +int items_count = weechat_hashtable_get_integer (hashtable, "items_count"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_get_string + +_WeeChat ≥ 0.3.4._ + +Return string value of a hashtable property. + +Prototype: + +[source,C] +---- +const char *weechat_hashtable_get_string (struct t_hashtable *hashtable, + const char *property); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'property': property name: +** 'type_keys': type for keys: +*** 'integer': integer +*** 'string': string +*** 'pointer': pointer +*** 'buffer': buffer +*** 'time': time +** 'type_values': type for values: +*** 'integer': integer +*** 'string': string +*** 'pointer': pointer +*** 'buffer': buffer +*** 'time': time +** 'keys': string with list of keys (format: "key1,key2,key3") +** 'keys_sorted': string with list of sorted keys (format: "key1,key2,key3") +** 'values': string with list of values (format: "value1,value2,value3") +** 'keys_values': string with list of keys and values + (format: "key1:value1,key2:value2,key3:value3") +** 'keys_values_sorted': string with list of keys and values (sorted by keys) + (format: "key1:value1,key2:value2,key3:value3") + +Return value: + +* string value of property + +C examples: + +[source,C] +---- +weechat_printf (NULL, "keys are type: %s", + weechat_hashtable_get_string (hashtable, "type_keys")); +weechat_printf (NULL, "list of keys: %s", + weechat_hashtable_get_string (hashtable, "keys")); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_set_pointer + +_WeeChat ≥ 0.3.4._ + +Set pointer value of a hashtable property. + +Prototype: + +[source,C] +---- +void weechat_hashtable_set_pointer (struct t_hashtable *hashtable, + const char *property, void *pointer); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'property': property name: +** 'callback_free_key': set callback function used to free keys in hashtable + _(WeeChat ≥ 0.4.2)_ +** 'callback_free_value': set callback function used to free values in hashtable +* 'pointer': new pointer value for property + +C example: + +[source,C] +---- +void +my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value) +{ + /* ... */ +} + +weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_add_to_infolist + +_WeeChat ≥ 0.3.3._ + +Add hashtable items to an infolist item. + +Prototype: + +[source,C] +---- +int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable, + struct t_infolist_item *infolist_item, + const char *prefix); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'infolist_item': infolist item pointer +* 'prefix': string used as prefix for names in infolist + +Return value: + +* 1 if OK, 0 if error + +C example: + +[source,C] +---- +weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash"); + +/* if hashtable contains: + "key1" => "value 1" + "key2" => "value 2" + then following variables will be added to infolist item: + "testhash_name_00000" = "key1" + "testhash_value_00000" = "value 1" + "testhash_name_00001" = "key2" + "testhash_value_00001" = "value 2" +*/ +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_remove + +_WeeChat ≥ 0.3.3._ + +Remove an item in a hashtable. + +Prototype: + +[source,C] +---- +void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key); +---- + +Arguments: + +* 'hashtable': hashtable pointer +* 'key': key pointer + +C example: + +[source,C] +---- +weechat_hashtable_remove (hashtable, "my_key"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_remove_all + +_WeeChat ≥ 0.3.3._ + +Remove all items in a hashtable. + +Prototype: + +[source,C] +---- +void weechat_hashtable_remove_all (struct t_hashtable *hashtable); +---- + +Arguments: + +* 'hashtable': hashtable pointer + +C example: + +[source,C] +---- +weechat_hashtable_remove_all (hashtable); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hashtable_free + +_WeeChat ≥ 0.3.3._ + +Free a hashtable. + +Prototype: + +[source,C] +---- +void weechat_hashtable_free (struct t_hashtable *hashtable); +---- + +Arguments: + +* 'hashtable': hashtable pointer + +C example: + +[source,C] +---- +weechat_hashtable_free (hashtable); +---- + +[NOTE] +This function is not available in scripting API. + +[[configuration_files]] +=== Configuration files + +Functions for configuration files. + +==== weechat_config_new + +Create a new configuration file. + +Prototype: + +[source,C] +---- +struct t_config_file *weechat_config_new (const char *name, + int (*callback_reload)(void *data, + struct t_config_file *config_file), + void *callback_reload_data); +---- + +Arguments: + +* 'name': name of configuration file (without path or extension) +* 'callback_reload': function called when configuration file is reloaded with + `/reload` (optional, can be NULL), arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** return value: +*** 'WEECHAT_CONFIG_READ_OK' +*** 'WEECHAT_CONFIG_READ_MEMORY_ERROR' +*** 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' +* 'callback_reload_data': pointer given to reload callback when it is called + by WeeChat + +Return value: + +* pointer to new configuration file, NULL if an error occurred + +[NOTE] +File is NOT created on disk by this function. It will be created by call to +function <<_weechat_config_write,weechat_config_write>>. +You should call this function only after adding some sections (with +<<_weechat_config_new_section,weechat_config_new_section>>) and options (with +<<_weechat_config_new_option,weechat_config_new_option>>). + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_config_new_section + +Create a new section in configuration file. + +Prototype: + +[source,C] +---- +struct t_config_section *weechat_config_new_section ( + struct t_config_file *config_file, + const char *name, + int user_can_add_options, + int user_can_delete_options, + int (*callback_read)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_read_data, + int (*callback_write)(void *data, + struct t_config_file *config_file, + const char *section_name), + void *callback_write_data, + int (*callback_write_default)(void *data, + struct t_config_file *config_file, + const char *section_name); + void *callback_write_default_data, + int (*callback_create_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_create_option_data, + int (*callback_delete_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option), + void *callback_delete_option_data); +---- + +Arguments: + +* 'config_file': configuration file pointer +* 'name': name of section +* 'user_can_add_options': 1 if user can create new options in section, or 0 if + it is forbidden +* 'user_can_delete_options': 1 if user can delete options in section, or 0 if + it is forbidden +* 'callback_read': function called when an option in section is read from disk + (should be NULL in most cases, except if options in section need custom + function), arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** 'struct t_config_section *section': section pointer +** 'const char *option_name': name of option +** 'const char *value': value +** return value: +*** 'WEECHAT_CONFIG_READ_OK' +*** 'WEECHAT_CONFIG_READ_MEMORY_ERROR' +*** 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' +* 'callback_read_data': pointer given to callback when it is called by WeeChat +* 'callback_write': function called when section is written in file (should be + NULL for most cases, except if section needs to be written by a custom + function), arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** 'struct t_config_section *section': section pointer +** 'const char *option_name': name of option +** return value: +*** 'WEECHAT_CONFIG_WRITE_OK' +*** 'WEECHAT_CONFIG_WRITE_ERROR' +*** 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' +* callback_write_data: pointer given to callback when it is called by WeeChat +* callback_write_default: function called when default values for section must + be written in file, arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** 'const char *section_name': name of section +** return value: +*** 'WEECHAT_CONFIG_WRITE_OK' +*** 'WEECHAT_CONFIG_WRITE_ERROR' +*** 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' +* 'callback_write_default_data': pointer given to callback when it is called by + WeeChat +* 'callback_create_option': function called when a new option is created in + section (NULL if section does not allow new options to be created), + arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** 'struct t_config_section *section': section pointer +** 'const char *option_name': name of option +** 'const char *value': value +** return value: +*** 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' +*** 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' +*** 'WEECHAT_CONFIG_OPTION_SET_ERROR' +*** 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' +* 'callback_create_option_data': pointer given to callback when it is called by + WeeChat +* 'callback_delete_option': function called when an option is deleted in + section (NULL if section does not allow options to be deleted), + arguments and return value: +** 'void *data': pointer +** 'struct t_config_file *config_file': configuration file pointer +** 'struct t_config_section *section': section pointer +** 'struct t_config_option *option': option pointer +** return value: +*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' +*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' +*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' +*** 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' +* 'callback_delete_option_data': pointer given to callback when it is called by + WeeChat + +Return value: + +* pointer to new section in configuration file, NULL if an error occurred + +C example: + +[source,C] +---- +int +my_section_read_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, const char *option_name, + const char *value) +{ + /* ... */ + + return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED; + /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */ + /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */ + /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */ +} + +int +my_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_CONFIG_WRITE_OK; + /* return WEECHAT_CONFIG_WRITE_ERROR; */ +} + +int +my_section_write_default_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_CONFIG_WRITE_OK; + /* return WEECHAT_CONFIG_WRITE_ERROR; */ +} + +int +my_section_create_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, const char *value) +{ + /* ... */ + + return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; + /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */ +} + +int +my_section_delete_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option) +{ + /* ... */ + + return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED; + /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */ +} + +/* standard section, user can not add/delete options */ +struct t_config_section *new_section1 = + weechat_config_new_section (config_file, "section1", 0, 0, + NULL, NULL, /* read callback */ + NULL, NULL, /* write callback */ + NULL, NULL, /* write default callback */ + NULL, NULL, /* create option callback */ + NULL, NULL); /* delete option callback */ + +/* special section, user can add/delete options, and options need + callback to be read/written */ +struct t_config_section *new_section2 = + weechat_config_new_section (config_file, "section2", 1, 1, + &my_section_read_cb, NULL, + &my_section_write_cb, NULL, + &my_section_write_default_cb, NULL, + &my_section_create_option_cb, NULL, + &my_section_delete_option_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +section = weechat.config_new_section(config_file, name, + user_can_add_options, user_can_delete_options, + callback_read, callback_read_data, + callback_write, callback_write_data, + callback_create_option, callback_create_option_data, + callback_delete_option, callback_delete_option_data) + +# example +def my_section_read_cb(data, config_file, section, option_name, value): + # ... + return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED + # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE + # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND + # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR + +def my_section_write_cb(data, config_file, section_name): + # ... + return weechat.WEECHAT_CONFIG_WRITE_OK + +def my_section_write_default_cb(data, config_file, section_name): + # ... + return weechat.WEECHAT_CONFIG_WRITE_OK + +def my_section_create_option_cb(data, config_file, section, option_name, value): + # ... + return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE + +def my_section_delete_option_cb(data, config_file, section, option): + # ... + return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED + +section = weechat.config_new_section(config_file, "section1", 1, 1, + "my_section_read_cb", "", + "my_section_write_cb", "", + "my_section_write_default_cb", "", + "my_section_create_option_cb", "", + "my_section_delete_option_cb", "") +---- + +==== weechat_config_search_section + +Search a section in a configuration file. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_section *section = weechat_config_search_section (config_file, + "section"); +---- + +Script (Python): + +[source,python] +---- +# prototype +section = weechat.config_search_section(config_file, section_name) + +# example +section = weechat.config_search_section(config_file, "section") +---- + +==== weechat_config_new_option + +Create a new option in a section of a configuration file. + +Prototype: + +[source,C] +---- +struct t_config_option *weechat_config_new_option ( + struct t_config_file *config_file, + struct t_config_section *section, + const char *name, + const char *type, + const char *description, + const char *string_values, + int min, + int max, + const char *default_value, + const char *value, + int null_value_allowed, + int (*callback_check_value)(void *data, + struct t_config_option *option, + const char *value), + void *callback_check_value_data, + void (*callback_change)(void *data, + struct t_config_option *option), + void *callback_change_data, + void (*callback_delete)(void *data, + struct t_config_option *option), + void *callback_delete_data); +---- + +Arguments: + +* 'config_file': configuration file pointer +* 'section': section pointer +* 'name': name of option +* 'type': type of option: +** 'boolean': boolean value (on/off) +** 'integer': integer value (with optional strings for values) +** 'string': string value +** 'color': color +* 'description': description of option +* 'string_values': values as string (separated by "|"), used for type 'integer' + (optional) +* 'min': minimum value (for type 'integer') +* 'max': maximum value (for type 'integer') +* 'default_value': default value for option (used when option is reset) +* 'value': value for option +* 'null_value_allowed': 1 if 'null' (undefined value) is allowed for option, + otherwise 0 +* 'callback_check_value': function called to check new value for option + (optional), arguments and return value: +** 'void *data': pointer +** 'struct t_config_option *option': option pointer +** 'const char *value': new value for option +** return value: +*** 1 if value is OK +*** 0 if value is invalid +* 'callback_check_value_data': pointer given to check_value callback when it + is called by WeeChat +* 'callback_change': function called when value of option has changed + (optional), arguments: +** 'void *data': pointer +** 'struct t_config_option *option': option pointer +* 'callback_change_data': pointer given to change callback when it is called + by WeeChat +* 'callback_delete': function called when option will be deleted (optional), + arguments: +** 'void *data': pointer +** 'struct t_config_option *option': option pointer +* 'callback_delete_data': pointer given to delete callback when it is called + by WeeChat + +Return value: + +* pointer to new option in section, NULL if an error + +C example: + +[source,C] +---- +/* 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): + +[source,python] +---- +# prototype +option = weechat.config_new_option(config_file, section, name, type, description, + string_values, min, max, default_value, value, null_value_allowed, + callback_check_value, callback_check_value_data, + callback_change, callback_change_data, + callback_delete, callback_delete_data) + +# example +def option4_check_value_cb(data, option, value): + # ... + return 1 + # return 0 + +def option4_change_cb(data, option): + # ... + +def option4_delete_cb(data, option): + # ... + +option1 = weechat.config_new_option(config_file, section, "option1", "boolean", + "My option, type boolean", + "", 0, 0, "on", "on", 0, + "", "", + "", "", + "", "") + +option2 = weechat.config_new_option(config_file, section, "option2", "integer", + "My option, type integer", + "", 0, 100, "15", "15", 0, + "", "", + "", "", + "", "") + +option3 = weechat.config_new_option(config_file, section, "option3", "integer", + "My option, type integer (with string values)", + "top|bottom|left|right", + 0, 0, "bottom", "bottom", 0, + "", "", + "", "", + "", "") + +option4 = weechat.config_new_option(config_file, section, "option4", "string", + "My option, type string", + "", 0, 0, "test", "test", 1, + "option4_check_value_cb", "" + "option4_change_cb", "", + "option4_delete_cb", "") + +option5 = weechat.config_new_option(config_file, section, "option5", "color", + "My option, type color", + "", 0, 0, "lightblue", "lightblue", 0, + "", "", + "", "", + "", "") +---- + +[NOTE] +In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6 +strings (due to a Ruby limitation of 15 arguments by function), see the +'WeeChat Scripting Guide' for more info _(fixed in version 0.4.1)_. + +==== weechat_config_search_option + +Search an option in a section of a configuration file. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_option *option = + weechat_config_search_option (config_file, section, "option"); +---- + +Script (Python): + +[source,python] +---- +# prototype +option = weechat.config_search_option(config_file, section, option_name) + +# example +option = weechat.config_search_option(config_file, section, "option") +---- + +==== weechat_config_search_section_option + +Search a section and an option in a configuration file or section. + +Prototype: + +[source,C] +---- +void weechat_config_search_section_option (struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + struct t_config_section **section_found, + struct t_config_option **option_found); +---- + +Arguments: + +* 'config_file': configuration file pointer +* 'section': section pointer +* 'option_name': option name +* 'section_found': pointer to section pointer, will be set to section of option, + if found +* 'option_found': pointer to an option pointer, will be set to option pointer, + if found + +C example: + +[source,C] +---- +struct t_config_section *ptr_section; +struct t_config_option *ptr_option; + +weechat_config_search_section_option(config_file, + section, + "option", + &ptr_section, + &ptr_option); +if (ptr_option) +{ + /* option found */ +} +else +{ + /* option not found */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_config_search_with_string + +Get file/section/option info about an option with full name. + +Prototype: + +[source,C] +---- +void weechat_config_search_with_string (const char *option_name, + struct t_config_file **config_file, + struct t_config_section **section, + struct t_config_option **option, + char **pos_option_name); +---- + +Arguments: + +* 'option_name': full option name (format: "file.section.option") +* 'config_file': pointer to configuration file pointer, will be set with + pointer to configuration file of option found +* 'section': pointer to section pointer, will be set to section of option, if + found +* 'option': pointer to an option pointer, will be set to option pointer, if + found +* 'pos_option_name': pointer to a string pointer, will be set to pointer to + name of option, if found + +C example: + +[source,C] +---- +struct t_config_file *ptr_config_file; +struct t_config_section *ptr_section; +struct t_config_option *ptr_option; +char *option_name; + +weechat_config_search_with_string ("file.section.option", + &ptr_config_file, + &ptr_section, + &ptr_option, + &option_name); +if (ptr_option) +{ + /* option found */ +} +else +{ + /* option not found */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_config_string_to_boolean + +Check if a text is "true" or "false", as boolean value. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_config_string_to_boolean (option_value)) +{ + /* value is "true" */ +} +else +{ + /* value is "false" */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_string_to_boolean(text) + +# example +if weechat.config_string_to_boolean(text): + # ... +---- + +==== weechat_config_option_reset + +Reset an option to its default value. + +Prototype: + +[source,C] +---- +int weechat_config_option_reset (struct t_config_option *option, + int run_callback); +---- + +Arguments: + +* 'option': option pointer +* 'run_callback': 1 for calling callback if value of option is changed, + otherwise 0 + +Return value: + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been reset +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_option_set + +Set new value for an option. + +Prototype: + +[source,C] +---- +int weechat_config_option_set (struct t_config_option *option, + const char *value, int run_callback); +---- + +Arguments: + +* 'option': option pointer +* 'value': new value for option +* 'run_callback': 1 for calling change callback if value of option is changed, + otherwise 0 + +Return value: + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_option_set_null + +Set null (undefined value) for an option. + +Prototype: + +[source,C] +---- +int weechat_config_option_set_null (struct t_config_option *option, + int run_callback); +---- + +Arguments: + +* 'option': option pointer +* 'run_callback': 1 for calling change callback if value of option is changed + (if it was not null), otherwise 0 + +[NOTE] +You can set value to null only if it is allowed for option (see +<<_weechat_config_new_option,weechat_config_new_option>>). + +Return value: + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_option_unset + +Unset/reset option. + +Prototype: + +[source,C] +---- +int weechat_config_option_unset (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' if option value has not been reset +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' if option value has been reset +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed +* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_option_rename + +Rename an option. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_config_option_rename (option, "new_name"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_option_rename(option, new_name) + +# example +weechat.config_option_rename(option, "new_name") +---- + +==== weechat_config_option_get_pointer + +Return a pointer on an option property. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char *description = weechat_config_option_get_pointer (option, "description"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_config_option_is_null + +Check if an option is "null" (undefined value). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_config_option_is_null (option)) +{ + /* value is "null" */ +} +else +{ + /* value is not "null" */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +is_null = weechat.config_option_is_null(option) + +# example +if weechat.config_option_is_null(option): + # ... +---- + +==== weechat_config_option_default_is_null + +Check if default value for an option is "null" (undefined value). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_config_option_default_is_null (option)) +{ + /* default value is "null" */ +} +else +{ + /* default value is not "null" */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +is_null = weechat.config_option_default_is_null(option) + +# example +if weechat.config_option_default_is_null(option): + # ... +---- + +==== weechat_config_boolean + +Return boolean value of option. + +Prototype: + +[source,C] +---- +int weechat_config_boolean (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* boolean value of option (0 or 1) + +C example: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +if (weechat_config_boolean (option)) +{ + /* value is "true" */ +} +else +{ + /* value is "false" */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_boolean(option) + +# example +option = weechat.config_get("plugin.section.option") +if weechat.config_boolean(option): + # ... +---- + +==== weechat_config_boolean_default + +Return default boolean value of option. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +if (weechat_config_boolean_default (option)) +{ + /* value is "true" */ +} +else +{ + /* value is "false" */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_boolean_default(option) + +# example +option = weechat.config_get("plugin.section.option") +if weechat.config_boolean_default(option): + # ... +---- + +==== weechat_config_integer + +Return integer value of option. + +Prototype: + +[source,C] +---- +int weechat_config_integer (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* integer value of option + +C example: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +int value = weechat_config_integer (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_integer(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_integer(option) +---- + +==== weechat_config_integer_default + +Return default integer value of option. + +Prototype: + +[source,C] +---- +int weechat_config_integer_default (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* default integer value of option + +C example: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +int value = weechat_config_integer_default (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_integer_default(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_integer_default(option) +---- + +==== weechat_config_string + +Return string value of option. + +Prototype: + +[source,C] +---- +const char *weechat_config_string (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* string value of option + +C example: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +const char *value = weechat_config_string (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_string(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_string(option) +---- + +==== weechat_config_string_default + +Return default string value of option. + +Prototype: + +[source,C] +---- +const char *weechat_config_string_default (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +Return value: + +* default string value of option + +C example: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +const char *value = weechat_config_string_default (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_string_default(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_string_default(option) +---- + +==== weechat_config_color + +Return color value of option. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +const char *color = weechat_config_color (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_color(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_color(option) +---- + +==== weechat_config_color_default + +Return default color value of option. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("plugin.section.option"); +const char *color = weechat_config_color_default (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.config_color_default(option) + +# example +option = weechat.config_get("plugin.section.option") +value = weechat.config_color_default(option) +---- + +==== weechat_config_write_option + +Write a line in a configuration file with option and its value (this function +should be called only in "write" or "write_default" callbacks for a section). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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 +---- + +==== weechat_config_write_line + +Write a line in a configuration file (this function should be called only in +"write" or "write_default" callbacks for a section). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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 +---- + +==== weechat_config_write + +Write configuration file to disk. + +Prototype: + +[source,C] +---- +int weechat_config_write (struct t_config_file *config_file); +---- + +Arguments: + +* 'config_file': configuration file pointer + +Return value: + +* 'WEECHAT_CONFIG_WRITE_OK' if configuration was written +* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' if there was not enough memory +* 'WEECHAT_CONFIG_WRITE_ERROR' if another error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_read + +Read configuration file from disk. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_reload + +Reload configuration file from disk. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +==== weechat_config_option_free + +Free an option. + +Prototype: + +[source,C] +---- +void weechat_config_option_free (struct t_config_option *option); +---- + +Arguments: + +* 'option': option pointer + +C example: + +[source,C] +---- +weechat_config_option_free (option); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_option_free(option) + +# example +weechat.config_option_free(option) +---- + +==== weechat_config_section_free_options + +Free all options in a section. + +Prototype: + +[source,C] +---- +void weechat_config_section_free_options (struct t_config_section *section); +---- + +Arguments: + +* 'section': section pointer + +C example: + +[source,C] +---- +weechat_config_section_free_options (section); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_section_free_options(section) + +# example +weechat.config_section_free_options(section) +---- + +==== weechat_config_section_free + +Free a section. + +Prototype: + +[source,C] +---- +void weechat_config_section_free (struct t_config_section *section); +---- + +Arguments: + +* 'section': section pointer + +C example: + +[source,C] +---- +weechat_config_section_free (section); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_section_free(section) + +# example +weechat.config_section_free(section) +---- + +==== weechat_config_free + +Free a configuration file. + +Prototype: + +[source,C] +---- +void weechat_config_free (struct t_config_file *config_file); +---- + +Arguments: + +* 'config_file': configuration file pointer + +C example: + +[source,C] +---- +weechat_config_free (config_file); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_free(config_file) + +# example +weechat.config_free(config_file) +---- + +==== weechat_config_get + +Search an option with full name. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format"); +---- + +Script (Python): + +[source,python] +---- +# prototype +option = weechat.config_get(option_name) + +# example +option = weechat.config_get("weechat.look.item_time_format") +---- + +==== weechat_config_get_plugin + +Search an option in plugins configuration file (plugins.conf). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +/* 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): + +[source,python] +---- +# prototype +value = weechat.config_get_plugin(option_name) + +# example +value = weechat.config_get_plugin("option") +---- + +==== weechat_config_is_set_plugin + +Check if option is set in plugins configuration file (plugins.conf). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_config_is_set_plugin ("option")) +{ + /* option is set */ +} +else +{ + /* option does not exist */ +} +---- + +Script (Python): + +[source,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 + # ... +---- + +==== weechat_config_set_plugin + +Set new value for option in plugins configuration file (plugins.conf). + +Prototype: + +[source,C] +---- +int weechat_config_set_plugin (const char *option_name, const char *value); +---- + +Arguments: + +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where "xxx" is current plugin name) +* 'value': new value for option + +Return value: + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed +* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' if option was not found +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if other error occurred + +C example: + +[source,C] +---- +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): + +[source,python] +---- +# prototype +rc = weechat.config_set_plugin(option_name, value) + +# example +rc = weechat.config_set_plugin("option", "test_value") +if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: + # ... +elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: + # ... +elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND: + # ... +elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: + # ... +---- + +==== weechat_config_set_desc_plugin + +_WeeChat ≥ 0.3.5._ + +Set description for option in plugins configuration file (plugins.conf). + +Prototype: + +[source,C] +---- +void weechat_config_set_desc_plugin (const char *option_name, + const char *description); +---- + +Arguments: + +* 'option_name': option name, WeeChat will add prefix "plugins.desc.xxx." + (where "xxx" is current plugin name) +* 'description': description for option + +[NOTE] +It is not a problem if option (plugins.var.xxx.option_name) does not exist. +A future creation of option with this name will use this description. + +C example: + +[source,C] +---- +weechat_config_set_desc_plugin ("option", "description of option"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.config_set_desc_plugin(option_name, description) + +# example +version = weechat.info_get("version_number", "") or 0 +if int(version) >= 0x00030500: + weechat.config_set_desc_plugin("option", "description of option") +---- + +==== weechat_config_unset_plugin + +Unset option in plugins configuration file (plugins.conf). + +Prototype: + +[source,C] +---- +int weechat_config_unset_plugin (const char *option_name); +---- + +Arguments: + +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where xxx is current plugin name) + +Return value: + +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' if option value has not been reset +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' if option value has been reset +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed +* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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: + # ... +---- + +[[key_bindings]] +=== Key bindings + +Functions for key bindings. + +==== weechat_key_bind + +_WeeChat ≥ 0.3.6._ + +Add new key bindings. + +[NOTE] +Unlike command `/key bind`, this function will never change an existing key +binding, only new keys are created. To remove a key binding, use +<<_weechat_key_unbind,weechat_key_unbind>>. + +Prototype: + +[source,C] +---- +int weechat_key_bind (const char *context, struct t_hashtable *keys); +---- + +Arguments: + +* 'context': context for keys: +** 'default': default context (common actions) +** 'search': search context (when searching text in buffer) +** 'cursor': free movement of cursor on screen +** 'mouse': keys for mouse events +* 'keys': hashtable with key bindings + +Return value: + +* number of key bindings added + +C example: + +[source,C] +---- +struct t_hashtable *keys = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (keys) +{ + weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse"); + weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up"); + weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down"); + weechat_key_bind ("mouse", keys); + weechat_hashtable_free (keys); +} +---- + +Script (Python): + +[source,python] +---- +# prototype +num_keys = weechat.key_bind(context, keys) + +# example +keys = { "@chat(python.test):button1": "hsignal:test_mouse", + "@chat(python.test):wheelup": "/mycommand up", + "@chat(python.test):wheeldown": "/mycommand down" } +weechat.key_bind("mouse", keys) +---- + +==== weechat_key_unbind + +_WeeChat ≥ 0.3.6._ + +Remove key binding(s). + +[WARNING] +When calling this function, ensure that you will not remove a user key binding. + +Prototype: + +[source,C] +---- +int weechat_key_unbind (const char *context, const char *key); +---- + +Arguments: + +* 'context': context for keys (see <<_weechat_key_bind,weechat_key_bind>>) +* 'key': key to remove or a special value "area:XXX" to remove all keys having + 'XXX' as first or second area + +Return value: + +* number of key bindings removed + +C examples: + +[source,C] +---- +/* remove a single key */ +weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1"); + +/* remove all keys with area "chat(plugin.buffer)" */ +weechat_key_unbind ("mouse", "area:chat(plugin.buffer)"); +---- + +Script (Python): + +[source,python] +---- +# prototype +num_keys = weechat.key_unbind(context, key) + +# examples + +# remove a single key +weechat.key_unbind("mouse", "@chat(plugin.buffer):button1") + +# remove all keys with area "chat(python.test)" +weechat.key_unbind("mouse", "area:chat(python.test)") +---- + +[[display]] +=== Display + +Functions to display text in buffers. + +==== weechat_prefix + +Return a prefix. + +Prototype: + +[source,C] +---- +const char *weechat_prefix (const char *prefix); +---- + +Arguments: + +* 'prefix': name of prefix (see table below) + +Return value: + +* prefix value (string with prefix and color codes), empty string if prefix is + not found + +List of prefixes: + +[width="70%",cols="^2e,^1,^3,5",options="header"] +|=== +| Prefix | Value | Color | Description +| error | `=!=` | yellow | Error message +| network | `--` | magenta | Message from network +| action | `*` | white | Self action +| join | `-->` | lightgreen | Someone joins current chat +| quit | `<--` | lightred | Someone leaves current chat +|=== + +[NOTE] +Values and colors can be customized with command `/set`. + +C example: + +[source,C] +---- +weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.prefix(prefix) + +# example +weechat.prnt("", "%sThis is an error..." % weechat.prefix("error")) +---- + +==== weechat_color + +Return a string color code for display. + +Prototype: + +[source,C] +---- +const char *weechat_color (const char *color_name); +---- + +Arguments: + +* 'color_name': name of color, one of: +** WeeChat option name (from weechat.color.xxx), for example 'chat_delimiters' +** color with optional attributes/background (see below) +** attribute: +*** 'bold': set bold +*** '-bold': remove bold +*** 'reverse': set reverse +*** '-reverse': remove reverse +*** 'italic': set italic +*** '-italic': remove italic +*** 'underline': set underline +*** '-underline': remove underline +*** 'emphasis': toggle the emphasis for text (note: this should be used only in + bars, because WeeChat uses text emphasis when searching text in buffer) + _(WeeChat ≥ 0.4.2)_ +** bar color name: +*** 'bar_fg': foreground color for bar +*** 'bar_delim': delimiters color for bar +*** 'bar_bg': background color for bar +** reset: +*** 'reset': reset color and attributes +*** 'resetcolor': reset color (keep attributes) _(WeeChat ≥ 0.3.6)_ + +Format of color is: attributes (optional) + color name + ",background" +(optional). Possible attributes are: + +* `*` : bold text +* `!` : reverse video +* `/` : italic +* `_` : underlined text +* `|` : keep attributes: do not reset bold/reverse/italic/underlined when + changing color _(WeeChat ≥ 0.3.6)_ + +Examples: + +* `yellow` : yellow +* `_green` : underlined green +* `*214` : bold orange +* `yellow,red` : yellow on red +* `|cyan` : cyan (and keep any attribute which was set previously) + +Return value: + +* string with color code, or an empty string if color is not found + +C example: + +[source,C] +---- +weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red", + weechat_color ("blue"), + weechat_color ("chat"), + weechat_color ("yellow,red")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.color(color_name) + +# example +weechat.prnt("", "Color: %sblue %sdefault color %syellow on red" + % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red"))) +---- + +==== weechat_printf + +Display a message on a buffer. + +Prototype: + +[source,C] +---- +void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...); +---- + +Arguments: + +* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer +* 'message': message to display + +[NOTE] +The first tabulation in message ("\t") is used to separate prefix from message. + +If your message has some tabs and if you don't want prefix, then use a space, +a tab, then message (see example below): this will disable prefix (the space +before tab will not be displayed). + +[NOTE] +With two tabs ("\t") at beginning of message, time will not be displayed and +message will have no alignment at all. Moreover, the date in message will be +set to 0. + +C example: + +[source,C] +---- +weechat_printf (NULL, "Hello on WeeChat buffer"); +weechat_printf (buffer, "Hello on this buffer"); +weechat_printf (buffer, "%sThis is an error!", weechat_prefix ("error")); +weechat_printf (buffer, " \tMessage without prefix but with \t some \t tabs"); +weechat_printf (buffer, "\t\tMessage without time/alignment"); +weechat_printf (buffer, "\t\t"); /* empty line (without time) */ +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.prnt(buffer, message) + +# example +weechat.prnt("", "Hello on WeeChat buffer") +weechat.prnt(buffer, "Hello on this buffer") +weechat.prnt(buffer, "%sThis is an error!" % weechat.prefix("error")) +weechat.prnt(buffer, " \tMessage without prefix but with \t some \t tabs") +weechat.prnt(buffer, "\t\tMessage without time/alignment") +weechat.prnt(buffer, "\t\t") # empty line (without time) +---- + +[NOTE] +Function is called "print" in scripts ("prnt" in Python). + +==== weechat_printf_date + +Display a message on a buffer, using a custom date. + +Prototype: + +[source,C] +---- +void weechat_printf_date (struct t_gui_buffer *buffer, time_t date, + const char *message, ...); +---- + +Arguments: + +* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer +* 'date': date for message (0 means current date/time) +* 'message': message to display + +C example: + +[source,C] +---- +weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_printf_tags + +Display a message on a buffer, using a custom tags. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf_tags (NULL, "notify_message", + "Message with a tag 'notify_message'"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_printf_date_tags + +Display a message on a buffer, using a custom date and tags. + +Prototype: + +[source,C] +---- +void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date, + const char *tags, const char *message, ...); +---- + +Arguments: + +* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer +* 'date': date for message (0 means current date/time) +* 'tags': comma separated list of tags +* 'message': message to display + +Tags commonly used (non-exhaustive list): + +[width="70%",cols="1m,4",options="header"] +|=== +| Tag | Description +| no_filter | Line can not be filtered +| no_highlight | No highlight is possible on line +| no_log | Line is not written in log file +| log0 ... log9 | Level of log for line (see `/help logger`) +| notify_none | Buffer with line is not added to hotlist +| notify_message | Buffer with line is added to hotlist with level "message" +| notify_private | Buffer with line is added to hotlist with level "private" +| notify_highlight | Buffer with line is added to hotlist with level "highlight" +| nick_xxx | Message is from nick "xxx" +| prefix_nick_ccc | Prefix is a nick with color "ccc" +| irc_xxx | IRC message "xxx" (can be a command or a 3-digits number) +| irc_numeric | IRC numeric message +| irc_error | Error from IRC server +| irc_action | Action from a nick (command `/me`) +| irc_ctcp | CTCP message +| irc_ctcp_reply | Reply to CTCP message +| irc_smart_filter | IRC message that can be filtered with the "smart filter" +| away_info | Message with away info +|=== + +C example: + +[source,C] +---- +weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message", + "Message 2 minutes ago, with a tag 'notify_message'"); +---- + +Script (Python): + +[source,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). + +==== weechat_printf_y + +Display a message on a line of a buffer with free content. + +Prototype: + +[source,C] +---- +void weechat_printf_y (struct t_gui_buffer *buffer, int y, + const char *message, ...); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'y': line number (first line is 0); a negative value adds a line after last + line displayed: absolute value of 'y' is the number of lines after last line + (for example -1 is immediately after last line, -2 is 2 lines after last line) + _(WeeChat ≥ 1.0)_ +* 'message': message to display + +C example: + +[source,C] +---- +weechat_printf_y (buffer, 2, "My message on third line"); +---- + +Script (Python): + +[source,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). + +==== weechat_log_printf + +Write a message in WeeChat log file (weechat.log). + +Prototype: + +[source,C] +---- +void weechat_log_printf (const char *message, ...); +---- + +Arguments: + +* 'message': message to write + +C example: + +[source,C] +---- +weechat_log_printf ("My message in log file"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.log_print(message) + +# example +weechat.log_print("My message in log file") +---- + +[NOTE] +Function is called "log_print" in scripts. + +[[hooks]] +=== Hooks + +[[hook_priority]] +[float] +==== Hook priority + +_WeeChat ≥ 0.3.4._ + +In some hooks, you can set a priority. A hook with higher priority is at the +beginning of hooks list, so it will be found and executed before other hooks. +It's useful for modifiers, because execution order is important. + +To set a priority, you must use this syntax, for argument where priority is +allowed: "nnn|name" where "nnn" is non-negative integer with priority and "name" +the name for argument (priority does not appear in name, it is automatically +removed from string). + +Default priority is 1000. + +C example: + +[source,C] +---- +/* hook modifier with priority = 2000 */ +weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL); +---- + +Following hook types allow priority: command, command_run, signal, hsignal, +config, completion, modifier, info, info_hashtable, infolist, hdata, focus. + +==== weechat_hook_command + +Hook a command. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_command (const char *command, + const char *description, + const char *args, + const char *args_description, + const char *completion, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + int argc, + char **argv, + char **argv_eol), + void *callback_data); +---- + +Arguments: + +* 'command': command name + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description for command (displayed with `/help command`) +* 'args': arguments for command (displayed with `/help command`) +* 'args_description': description of arguments (displayed with `/help command`) +* 'completion': completion template for command: list of completions for each + argument, separated by space. Many completions are possible for one + argument, separated by "|". Many templates are possible for same command, + separated by "||". +* 'callback': function called when command is used, arguments and return value: +** 'void *data': pointer +** 'struct t_gui_buffer *buffer': buffer where command is executed +** 'int argc': number of arguments given for command +** 'char **argv': arguments given for command +** 'char **argv_eol': arguments given for command (until end of line for each + argument) +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Default completion codes are: + +include::autogen/plugin_api/completions.asciidoc[] + +Special codes: + +* '%%command': reuse completion template from command 'command' +* '%-': stop completion +* '%*': repeat last completion + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +int +my_command_cb (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* this example is inspired by command /filter */ +struct t_hook *my_command_hook = + weechat_hook_command (/* command name */ + "myfilter", + /* description */ + "description of myfilter", + /* args */ + "[list] | [enable|disable|toggle [name]] | " + "[add name plugin.buffer tags regex] | " + "[del name|-all]", + /* args description */ + "description of arguments...", + /* completion */ + "list" + " || enable %(filters_names)" + " || disable %(filters_names)" + " || toggle %(filters_names)" + " || add %(filters_names) %(buffers_plugins_names)|*" + " || del %(filters_names)|-all", + /* callback */ + &my_command_cb, + /* callback_data */ + NULL); +---- + +For example, if command called is `/command abc def ghi`, then 'argv' and +'argv_eol' have following values: + +* 'argv': +** 'argv[0]' == "/command" +** 'argv[1]' == "abc" +** 'argv[2]' == "def" +** 'argv[3]' == "ghi" +* 'argv_eol': +** 'argv_eol[0]' == "/command abc def ghi" +** 'argv_eol[1]' == "abc def ghi" +** 'argv_eol[2]' == "def ghi" +** 'argv_eol[3]' == "ghi" + +For scripts, 'args' has value "abc def ghi". + +Script (Python): + +[source,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", "") +---- + +==== weechat_hook_command_run + +Hook a command when WeeChat runs it. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_command_run (const char *command, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + const char *command), + void *callback_data); +---- + +Arguments: + +* 'command': command to hook (wildcard "*" is allowed) + (priority allowed, see note about <<hook_priority,priority>>) +* 'callback': function called when command is run, arguments and return value: +** 'void *data': pointer +** 'struct t_gui_buffer *buffer': buffer where command is executed +** 'const char *command': the command executed, with its arguments +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_OK_EAT' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +[NOTE] +Callback can return 'WEECHAT_RC_OK' or 'WEECHAT_RC_OK_EAT' (command will not +be executed by WeeChat after callback). + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_timer + +Hook a timer. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_timer (long interval, + int align_second, + int max_calls, + int (*callback)(void *data, + int remaining_calls), + void *callback_data); +---- + +Arguments: + +* 'interval': interval between two calls (milliseconds, so 1000 = 1 second) +* 'align_second': alignment on a second. For example, if current time is 09:00, + if interval = 60000 (60 seconds), and align_second = 60, then timer is + called each minute when second is 0 +* 'max_calls': number of calls to timer (if 0, then timer has no end) +* 'callback': function called when time is reached, arguments and return value: +** 'void *data': pointer +** 'int remaining_calls': remaining calls (-1 if timer has no end) +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_fd + +Hook a file descriptor (file or socket). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_fd (int fd, + int flag_read, + int flag_write, + int flag_exception, + int (*callback)(void *data, + int fd), + void *callback_data); +---- + +Arguments: + +* 'fd': file descriptor +* 'flag_read': 1 = catch read event, 0 = ignore +* 'flag_write': 1 = catch write event, 0 = ignore +* 'flag_exception': 1 = catch exception event, 0 = ignore +* 'callback': function called a selected event occurs for file (or socket), + arguments and return value: +** 'void *data': pointer +** 'int fd': file descriptor +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_process + +Hook a process (launched with fork), and catch output. + +[NOTE] +Since version 0.3.9.2, the shell is not used any more to execute the command. +WeeChat makes an automatic split of the command and its arguments (like the +shell does). + +If the split is not correct (according to quotes in your command), or if you +want to use shell, you can use function +<<_weechat_hook_process_hashtable,weechat_hook_process_hashtable>> with +arguments in the hashtable 'options' _(WeeChat ≥ 0.4.0)_. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_process (const char *command, + int timeout, + int (*callback)(void *data, + const char *command, + int return_code, + const char *out, + const char *err), + void *callback_data); +---- + + +Arguments: + +* 'command': command to launch in child process or URL _(WeeChat ≥ 0.3.7)_ + (see below) +* 'timeout': timeout for command (in milliseconds): after this timeout, child + process is killed (0 means no timeout) +* 'callback': function called when data from child is available, or when child + has ended, arguments and return value: +** 'void *data': pointer +** 'const char *command': command executed by child +** 'int return_code': return code: +*** '>= 0': child return code for a command, and for URL possible values are: +**** '0': transfer OK +**** '1': invalid URL +**** '2': transfer error +**** '3': not enough memory +**** '4': error with a file +*** '< 0': 'WEECHAT_HOOK_PROCESS_RUNNING' (data available, but child still + running) or 'WEECHAT_HOOK_PROCESS_ERROR' (error when launching command) +** 'out': standard output of command (stdout) +** 'err': error output of command (stderr) +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +When command has ended, or if timeout is reached, WeeChat will automatically +unhook (and kill process if it is still running). + +The command can be an URL with format: "url:http://www.example.com", to download +content of URL _(WeeChat ≥ 0.3.7)_. Options are possible for URL with +function <<_weechat_hook_process_hashtable,weechat_hook_process_hashtable>>. + +[TIP] +If you want to retrieve infos about WeeChat (like current stable version, +latest git commit, ...), you can use URLs on page http://weechat.org/dev/info + +[NOTE] +Buffer size for sending data to callback is 64KB (there are 2 buffers: one for +stdout and one for stderr). +If output from child process (stdout or stderr) is longer than 64KB, callback +will be called more than one time. + +[IMPORTANT] +Even if most of times your callback is called only once, you must ensure that +many calls to callback are OK in your code: you must concatenate data issued by +many calls and use data only when return code is non-negative. + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_process_hashtable + +_WeeChat ≥ 0.3.7._ + +Hook a process (launched with fork) using options in a hashtable, and catch +output. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_process_hashtable (const char *command, + struct t_hashtable *options, + int timeout, + int (*callback)(void *data, + const char *command, + int return_code, + const char *out, + const char *err), + void *callback_data); +---- + +Arguments are the same as function <<_weechat_hook_process,weechat_hook_process>>, +with an extra argument: + +* 'options': options for command executed; the hashtable is duplicated in + function, so it's safe to free it after this call + +For a standard command (not beginning with "url:"), following options are +available: + +[width="100%",cols="^1,1,3",options="header"] +|=== +| Option | Value | Description + +| argN (N ≥ 1) + + _(WeeChat ≥ 0.4.0)_ | + any string | + Arguments for command; if no argument is given with these options, + the command is automatically split like the shell does (and then command + arguments are read in the 'command' argument) + +| stdin + + _(WeeChat ≥ 0.4.3)_ | + (not used) | + Create a pipe for writing data on standard input (stdin) of child process + (see function <<_weechat_hook_set,weechat_hook_set>>) + +| buffer_flush + + _(WeeChat ≥ 1.0)_ | + number of bytes | + Minimum number of bytes to flush stdout/stderr (to send output to callback), + between 1 and 65536 (default); 1 = send any output immediately to the callback + +| detached + + _(WeeChat ≥ 1.0)_ | + (not used) | + Run the process in a detached mode: stdout and stderr are redirected to + '/dev/null' +|=== + +For command "url:...", following options are available (see +`man curl_easy_setopt` for a description of each option): + +include::autogen/plugin_api/url_options.asciidoc[] + +[NOTE] +^(1)^ When constants are available they must be used as value for option. For +options with type "mask", format is: "value1+value2+value3". + +For URL, two extra options (strings) are allowed for input/output file: + +* 'file_in': file to read and send with URLs (post file) +* 'file_out': write downloaded URL/file in this file (instead of standard + output) + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +int +my_process_cb (void *data, const char *command, int return_code, + const char *out, const char *err) +{ + if (return_code == WEECHAT_HOOK_PROCESS_ERROR) + { + weechat_printf (NULL, "Error with command '%s'", command); + return WEECHAT_RC_OK; + } + + if (return_code >= 0) + { + weechat_printf (NULL, "return_code = %d", return_code); + } + + if (out) + { + weechat_printf (NULL, "stdout: %s", out); + } + + if (err) + { + weechat_printf (NULL, "stderr: %s", err); + } + + return WEECHAT_RC_OK; +} + +/* example 1: download URL */ +struct t_hashtable *options = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (options) +{ + weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html"); + struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://www.weechat.org/", + options, + 20000, + &my_process_cb, NULL); + weechat_hashtable_free (options); +} + +/* example 2: execute a notify program with a message from someone */ +struct t_hashtable *options_cmd1 = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (options_cmd1) +{ + weechat_hashtable_set (options_cmd1, "arg1", "-from"); + weechat_hashtable_set (options_cmd1, "arg2", nick); + weechat_hashtable_set (options_cmd1, "arg3", "-msg"); + weechat_hashtable_set (options_cmd1, "arg4", message); /* untrusted argument */ + struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command", + options_cmd1, + 20000, + &my_process_cb, NULL); + weechat_hashtable_free (options_cmd1); +} + +/* example 3: call shell to execute a command (command must be SAFE) */ +struct t_hashtable *options_cmd2 = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (options_cmd2) +{ + weechat_hashtable_set (options_cmd2, "arg1", "-c"); + weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something"); + struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh", + options_cmd2, + 20000, + &my_process_cb, NULL); + weechat_hashtable_free (options_cmd2); +} +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_process_hashtable(command, options, timeout, callback, callback_data) + +# example +def my_process_cb(data, command, return_code, out, err): + if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR: + weechat.prnt("", "Error with command '%s'" % command) + return weechat.WEECHAT_RC_OK + if return_code >= 0: + weechat.prnt("", "return_code = %d" % return_code) + if out != "": + weechat.prnt("", "stdout: %s" % out) + if err != "": + weechat.prnt("", "stderr: %s" % err) + return weechat.WEECHAT_RC_OK + +# example 1: download URL +hook1 = weechat.hook_process_hashtable("url:http://www.weechat.org/", + { "file_out": "/tmp/weechat.org.html" }, + 20000, "my_process_cb", "") + +# example 2: execute a notify program with a message from someone +hook2 = weechat.hook_process_hashtable("my-notify-command", + { "arg1": "-from", + "arg2": nick, + "arg3": "-msg", + "arg4": message }, # untrusted argument + 20000, "my_process_cb", "") + +# example 3: call shell to execute a command (command must be SAFE) +hook3 = weechat.hook_process_hashtable("sh", + { "arg1": "-c", + "arg2": "ls -l /tmp | grep something" }, + 20000, "my_process_cb", "") +---- + +==== weechat_hook_connect + +Hook a connection (background connection to a remote host). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_connect (const char *proxy, + const char *address, + int port, + int ipv6, + int retry, + void *gnutls_sess, + void *gnutls_cb, + int gnutls_dhkey_size, + const char *gnutls_priorities, + const char *local_hostname, + int (*callback)(void *data, + int status, + int gnutls_rc, + int sock, + const char *error, + const char *ip_address), + void *callback_data); +---- + +Arguments: + +* 'proxy': name of proxy to use for connection (optional, NULL means connection + without proxy) +* 'address': name or IP address to connect to +* 'port': port number +* 'ipv6': 1 to use IPv6 (with fallback to IPv4), 0 to use only IPv4 +* 'retry': retry count, used to fallback to IPv4 hosts if IPv6 hosts connect + but then fail to accept the client +* 'gnutls_sess': GnuTLS session (optional) +* 'gnutls_cb': GnuTLS callback (optional) +* 'gnutls_dhkey_size': size of the key used during the Diffie-Hellman Key + Exchange (GnuTLS) +* 'gnutls_priorities': priorities for gnutls (for syntax, see documentation of + function 'gnutls_priority_init' in gnutls manual), basic values are: +** 'PERFORMANCE' +** 'NORMAL' (default) +** 'SECURE128' +** 'SECURE256' +** 'EXPORT' +** 'NONE' +* 'local_hostname': local hostname to use for connection (optional) +* 'callback': function called when connection is OK or failed, arguments and + return value: +** 'void *data': pointer +** 'int status': connection status: +*** 'WEECHAT_HOOK_CONNECT_OK': connection OK +*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND': address not found +*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND': IP address not found +*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED': connection refused +*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR': error with proxy +*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR': error with local hostname +*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR': GnuTLS init error +*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR': GnuTLS handshake error +*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR': insufficient memory +*** 'WEECHAT_HOOK_CONNECT_TIMEOUT': timeout +*** 'WEECHAT_HOOK_CONNECT_SOCKET_ERROR': unable to create socket +** 'gnutls_rc': return value of 'gnutls_handshake()' +** 'sock': socket used to connect +** 'const char *error': return value of 'gnutls_strerror(gnutls_rc)' +** 'const char *ip_address': IP address found +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +int +my_connect_cb (void *data, int status, int gnutls_rc, int sock, + const char *error, const char *ip_address) +{ + switch (status) + { + case WEECHAT_HOOK_CONNECT_OK: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_PROXY_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_MEMORY_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_TIMEOUT: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_SOCKET_ERROR: + /* ... */ + break; + } + return WEECHAT_RC_OK; +} + +struct t_hook *my_connect_hook = weechat_hook_connect (NULL, + "my.server.org", 1234, + 1, 0, + NULL, NULL, 0, /* GnuTLS */ + NULL, + &my_connect_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_connect(proxy, address, port, ipv6, retry, local_hostname, + callback, callback_data) + +# example +def my_connect_cb(data, status, gnutls_rc, sock, error, ip_address): + if status == WEECHAT_HOOK_CONNECT_OK: + # ... + elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: + # ... + elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: + # ... + elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: + # ... + elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR: + # ... + elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: + # ... + elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: + # ... + elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: + # ... + elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR: + # ... + elif status == WEECHAT_HOOK_CONNECT_TIMEOUT: + # ... + elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR: + # ... + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_connect("", "my.server.org", 1234, 1, 0, "", + "my_connect_cb", "") +---- + +==== weechat_hook_print + +_Updated in 0.4.3 and 1.0._ + +Hook a message printed. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer, + const char *tags, + const char *message, + int strip_colors, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + time_t date, + int tags_count, + const char **tags, + int displayed, + int highlight, + const char *prefix, + const char *message), + void *callback_data); +---- + +Arguments: + +* 'buffer': buffer pointer, if NULL, messages from any buffer are caught +* 'tags': catch only messages with these tags (optional): +** with WeeChat ≥ 0.4.3: comma-separated list of tags that must be in message + (logical "or"); it is possible to combine many tags as a logical "and" with + separator "+"; wildcard "*" is allowed in tags +** with WeeChat ≤ 0.4.2: comma-separated list of tags that must all be in + message (logical "and") +* 'message': only messages with this string will be caught (optional, case + insensitive) +* 'strip_colors': if 1, colors will be stripped from message displayed, before + calling callback +* 'callback': function called when a message is printed, arguments and return + value: +** 'void *data': pointer +** 'struct t_gui_buffer *buffer': buffer pointer +** 'time_t date': date +** 'int tags_count': number of tags for line +** 'const char **tags': array with tags for line +** 'int displayed': 1 if line is displayed, 0 if it is filtered (hidden) +** 'int highlight': 1 if line has highlight, otherwise 0 +** 'const char *prefix': prefix +** 'const char *message': message +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +[IMPORTANT] +In scripts, with WeeChat ≥ 1.0, the callback arguments 'displayed' and +'highlight' are integers (with WeeChat ≤ 0.4.3, they were strings). + +To be compatible with all versions, it is recommended to convert the argument +to integer before testing it, for example in Python: "`if int(highlight):`". + +C example: + +[source,C] +---- +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): + +[source,python] +---- +# prototype +hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data) + +# example +def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message): + if int(highlight): + # ... + return weechat.WEECHAT_RC_OK + +# catch all messages, on all buffers, without color +hook = weechat.hook_print("", "", "", 1, "my_print_cb", "") +---- + +==== weechat_hook_signal + +Hook a signal. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_signal (const char *signal, + int (*callback)(void *data, + const char *signal, + const char *type_data, + void *signal_data), + void *callback_data); +---- + +Arguments: + +* 'signal': signal to catch, wildcard "*" is allowed + (priority allowed, see note about <<hook_priority,priority>>) + (see table below) +* 'callback': function called when signal is received, arguments and return + value: +** 'void *data': pointer +** 'const char *signal': signal received +** 'const char *type_data': type of data sent with signal: +*** 'WEECHAT_HOOK_SIGNAL_STRING': string +*** 'WEECHAT_HOOK_SIGNAL_INT': integer number +*** 'WEECHAT_HOOK_SIGNAL_POINTER': pointer +** 'void *signal_data': data sent with signal +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_OK_EAT' (stop sending the signal immediately) + _(WeeChat ≥ 0.4.0)_ +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +List of signals sent by WeeChat and plugins: + +[width="100%",cols="^1,^3,4,5",options="header"] +|=== +| Plugin | Signal | Arguments | Description + +| aspell | aspell_suggest + + _(WeeChat ≥ 0.4.0)_ | + Pointer: buffer | + New suggestions for a misspelled word + +| guile | guile_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Scheme script loaded + +| guile | guile_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Scheme script unloaded + +| guile | guile_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Scheme script(s) installed + +| guile | guile_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Scheme script(s) removed + +| irc | xxx,irc_in_yyy ^(1)^ | + String: message | + IRC message from server (before irc plugin uses it, + signal sent only if message is *not* ignored) + +| irc | xxx,irc_in2_yyy ^(1)^ | + String: message | + IRC message from server (after irc plugin uses it, + signal sent only if message is *not* ignored) + +| irc | xxx,irc_raw_in_yyy ^(1)^ + + _(WeeChat ≥ 0.3.2)_ | + String: message | + IRC message from server (before irc plugin uses it, + signal sent even if message is ignored) + +| irc | xxx,irc_raw_in2_yyy ^(1)^ + + _(WeeChat ≥ 0.3.2)_ | + String: message | + IRC message from server (after irc plugin uses it, + signal sent even if message is ignored) + +| irc | xxx,irc_out1_yyy ^(1)^ + + _(WeeChat ≥ 0.3.7)_ | + String: message | + IRC message sent to server (before automatic split to fit in 512 bytes) + +| irc | xxx,irc_out_yyy ^(1)^ | + String: message | + IRC message sent to server (after automatic split to fit in 512 bytes) + +| irc | xxx,irc_outtags_yyy ^(1)^ + + _(WeeChat ≥ 0.3.4)_ | + String: tags + ";" + message | + Tags + IRC message sent to server + +| irc | irc_ctcp | + String: message | + CTCP received + +| irc | irc_dcc | + String: message | + New DCC + +| irc | irc_pv | + String: message | + Private message received + +| irc | irc_channel_opened | + Pointer: buffer | + Channel opened + +| irc | irc_pv_opened | + Pointer: buffer | + Private opened + +| irc | irc_server_opened + + _(WeeChat ≥ 0.3.7)_ | + Pointer: buffer | + Server buffer opened + +| irc | irc_server_connecting | + String: server name | + Connecting to server + +| irc | irc_server_connected | + String: server name | + Connected to server + +| irc | irc_server_disconnected | + String: server name | + Disconnected from server + +| irc | irc_ignore_removing | + Pointer: ignore | + Removing ignore + +| irc | irc_ignore_removed | + - | + Ignore removed + +| irc | irc_notify_join + + _(WeeChat ≥ 0.3.8)_ | + String: server name + "," + nick | + A nick in notify list has joined server + +| irc | irc_notify_quit + + _(WeeChat ≥ 0.3.8)_ | + String: server name + "," + nick | + A nick in notify list has quit server + +| irc | irc_notify_away + + _(WeeChat ≥ 0.3.8)_ | + String: server name + "," + nick + "," + away message | + A nick in notify list is now away on server + +| irc | irc_notify_still_away + + _(WeeChat ≥ 0.3.8)_ | + String: server name + "," + nick + "," + away message | + A nick in notify list is still away on server (away message has changed) + +| irc | irc_notify_back + + _(WeeChat ≥ 0.3.8)_ | + String: server name + "," + nick | + A nick in notify list is back (away status removed) + +| logger | logger_start | + Pointer: buffer | + Start logging for buffer + +| logger | logger_stop | + Pointer: buffer | + Stop logging for buffer + +| logger | logger_backlog | + Pointer: buffer | + Display backlog for buffer + +| lua | lua_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Lua script loaded + +| lua | lua_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Lua script unloaded + +| lua | lua_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Lua script(s) installed + +| lua | lua_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Lua script(s) removed + +| perl | perl_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Perl script loaded + +| perl | perl_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Perl script unloaded + +| perl | perl_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Perl script(s) installed + +| perl | perl_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Perl script(s) removed + +| python | python_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Python script loaded + +| python | python_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Python script unloaded + +| python | python_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Python script(s) installed + +| python | python_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Python script(s) removed + +| relay | relay_client_connecting + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + A relay client is connecting + +| relay | relay_client_waiting_auth + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + Waiting for authentication from a relay client + +| relay | relay_client_auth_ok + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + Successful authentication from a relay client + +| relay | relay_client_connected + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + A relay client is connected + +| relay | relay_client_auth_failed + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + Authentication of a relay client has failed + +| relay | relay_client_disconnected + + _(WeeChat ≥ 1.0)_ | + Pointer: relay client | + A relay client is disconnected + +| ruby | ruby_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Ruby script loaded + +| ruby | ruby_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Ruby script unloaded + +| ruby | ruby_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Ruby script(s) installed + +| ruby | ruby_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Ruby script(s) removed + +| tcl | tcl_script_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Tcl script loaded + +| tcl | tcl_script_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to script | + Tcl script unloaded + +| tcl | tcl_script_installed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of paths to scripts installed | + Tcl script(s) installed + +| tcl | tcl_script_removed + + _(WeeChat ≥ 0.3.9)_ | + String: comma-separated list of scripts removed | + Tcl script(s) removed + +| weechat | buffer_opened | + Pointer: buffer | + Buffer opened + +| weechat | buffer_closing | + Pointer: buffer | + Closing buffer + +| weechat | buffer_closed | + Pointer: buffer | + Buffer closed + +| weechat | buffer_cleared | + Pointer: buffer | + Buffer cleared + +| weechat | buffer_hidden | + Pointer: buffer | + Buffer hidden + +| weechat | buffer_unhidden | + Pointer: buffer | + Buffer unhidden + +| weechat | buffer_line_added + + _(WeeChat ≥ 0.3.7)_ | + Pointer: line | + Line added in a buffer + +| weechat | buffer_lines_hidden | + Pointer: buffer | + Lines hidden in buffer + +| weechat | buffer_localvar_added | + Pointer: buffer | + Local variable has been added + +| weechat | buffer_localvar_changed | + Pointer: buffer | + Local variable has changed + +| weechat | buffer_localvar_removed | + Pointer: buffer | + Local variable has been removed + +| weechat | buffer_merged | + Pointer: buffer | + Buffer merged + +| weechat | buffer_unmerged | + Pointer: buffer | + Buffer unmerged + +| weechat | buffer_moved | + Pointer: buffer | + Buffer moved + +| weechat | buffer_renamed | + Pointer: buffer | + Buffer renamed + +| weechat | buffer_switch | + Pointer: buffer | + Switching buffer + +| weechat | buffer_title_changed | + Pointer: buffer | + Title of buffer changed + +| weechat | buffer_type_changed | + Pointer: buffer | + Type of buffer changed + +| weechat | buffer_zoomed + + _(WeeChat ≥ 0.4.3)_ | + Pointer: buffer | + Merged buffer zoomed + +| weechat | buffer_unzoomed + + _(WeeChat ≥ 0.4.3)_ | + Pointer: buffer | + Merged buffer unzoomed + +| weechat | day_changed + + _(WeeChat ≥ 0.3.2)_ | + String: new date, format: "2010-01-31" | + Day of system date has changed + +| weechat | debug_dump | + String: plugin name | + Dump request + +| weechat | debug_libs | + - | + Display external libraries used + +| weechat | filter_added | + Pointer: filter | + Filter added + +| weechat | filter_removing | + Pointer: filter | + Removing filter + +| weechat | filter_removed | + - | + Filter removed + +| weechat | filters_enabled | + - | + Filters enabled + +| weechat | filters_disabled | + - | + Filters disabled + +| weechat | hotlist_changed | + - | + Hotlist changed + +| weechat | input_paste_pending | + - | + Paste pending + +| weechat | input_search | + Pointer: buffer | + Text search in buffer + +| weechat | input_text_changed | + Pointer: buffer | + Input text changed + +| weechat | input_text_cursor_moved | + Pointer: buffer | + Input text cursor moved + +| weechat | key_bind | + String: key | + Key added + +| weechat | key_unbind | + String: key | + Key removed + +| weechat | key_pressed | + String: key pressed | + Key pressed + +| weechat | key_combo_default + + _(WeeChat ≥ 1.0)_ | + String: key combo | + Key combo in 'default' context + +| weechat | key_combo_search + + _(WeeChat ≥ 1.0)_ | + String: key combo | + Key combo in 'search' context + +| weechat | key_combo_cursor + + _(WeeChat ≥ 1.0)_ | + String: key combo | + Key combo in 'cursor' context + +| weechat | nicklist_group_added + + _(WeeChat ≥ 0.3.2)_ | + String: buffer pointer + "," + group name | + Group added in nicklist + +| weechat | nicklist_group_changed + + _(WeeChat ≥ 0.3.4)_ | + String: buffer pointer + "," + group name | + Group changed in nicklist + +| weechat | nicklist_group_removing + + _(WeeChat ≥ 0.4.1)_ | + String: buffer pointer + "," + group name | + Removing group from nicklist + +| weechat | nicklist_group_removed + + _(WeeChat ≥ 0.3.2)_ | + String: buffer pointer + "," + group name | + Group removed from nicklist + +| weechat | nicklist_nick_added + + _(WeeChat ≥ 0.3.2)_ | + String: buffer pointer + "," + nick name | + Nick added in nicklist + +| weechat | nicklist_nick_changed + + _(WeeChat ≥ 0.3.4)_ | + String: buffer pointer + "," + nick name | + Nick changed in nicklist + +| weechat | nicklist_nick_removing + + _(WeeChat ≥ 0.4.1)_ | + String: buffer pointer + "," + nick name | + Removing nick from nicklist + +| weechat | nicklist_nick_removed + + _(WeeChat ≥ 0.3.2)_ | + String: buffer pointer + "," + nick name | + Nick removed from nicklist + +| weechat | partial_completion | + - | + Partial completion happened + +| weechat | plugin_loaded + + _(WeeChat ≥ 0.3.9)_ | + String: path to plugin loaded | + Plugin loaded + +| weechat | plugin_unloaded + + _(WeeChat ≥ 0.3.9)_ | + String: name of plugin unloaded (example: "irc") | + Plugin unloaded + +| weechat | quit | + String: arguments for /quit | + Command `/quit` issued by user + +| weechat | signal_sigwinch + + _(WeeChat ≥ 0.4.3)_ | + - | + Signal SIGWINCH received (terminal was resized) + +| weechat | upgrade | + String: "quit" if "-quit" argument was given for /upgrade, otherwise NULL | + Command `/upgrade` issued by user + +| weechat | upgrade_ended + + _(WeeChat ≥ 0.3.4)_ | + - | + End of upgrade process (command `/upgrade`) + +| weechat | weechat_highlight | + String: message with prefix | + Highlight happened + +| weechat | weechat_pv | + String: message with prefix | + Private message displayed + +| weechat | window_closing + + _(WeeChat ≥ 0.3.6)_ | + Pointer: window | + Closing window + +| weechat | window_closed + + _(WeeChat ≥ 0.3.6)_ | + Pointer: window | + Window closed + +| weechat | window_opened + + _(WeeChat ≥ 0.4.1)_ | + Pointer: window | + Window opened + +| weechat | window_scrolled | + Pointer: window | + Scroll in window + +| weechat | window_switch + + _(WeeChat ≥ 0.3.7)_ | + Pointer: window | + Switching window + +| weechat | window_zoom | + Pointer: current window | + Zomming window + +| weechat | window_zoomed | + Pointer: current window | + Window zoomed + +| weechat | window_unzoom | + Pointer: current window | + Unzooming window + +| weechat | window_unzoomed | + Pointer: current window | + Window unzoomed + +| xfer | xfer_add | + Pointer: infolist with xfer info | + New xfer + +| xfer | xfer_send_ready | + Pointer: infolist with xfer info | + Xfer ready + +| xfer | xfer_accept_resume | + Pointer: infolist with xfer info | + Accept xfer resume + +| xfer | xfer_send_accept_resume | + Pointer: infolist with xfer info | + Xfer resumed + +| xfer | xfer_start_resume | + Pointer: infolist with xfer info | + Start resume + +| xfer | xfer_resume_ready | + Pointer: infolist with xfer info | + Xfer resume ready + +| xfer | xfer_ended + + _(WeeChat ≥ 0.3.2)_ | + Pointer: infolist with xfer info | + Xfer has ended +|=== + +[NOTE] +^(1)^ 'xxx' is IRC server name, 'yyy' is IRC command name. + +C example: + +[source,C] +---- +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): + +[source,python] +---- +# prototype +hook = weechat.hook_signal(signal, callback, callback_data) + +# example +def my_signal_cb(data, signal, signal_data): + # ... + return weechat.WEECHAT_RC_OK + +# catch signal "quit" +hook = weechat.hook_signal("quit", "my_signal_cb", "") +---- + +==== weechat_hook_signal_send + +_Updated in 1.0._ + +Send a signal. + +Prototype: + +[source,C] +---- +int weechat_hook_signal_send (const char *signal, const char *type_data, + void *signal_data); +---- + +Arguments: + +* 'signal': signal to send +* 'type_data': type of data sent with signal (see + <<_weechat_hook_signal,weechat_hook_signal>>) +* 'signal_data': data sent with signal + +Return value _(WeeChat ≥ 1.0)_: + +* return code of last callback executed ('WEECHAT_RC_OK' if no callback was + executed): +** 'WEECHAT_RC_OK' +** 'WEECHAT_RC_OK_EAT' +** 'WEECHAT_RC_ERROR' + +C example: + +[source,C] +---- +int rc = weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string); +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.hook_signal_send(signal, type_data, signal_data) + +# example +rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string) +---- + +[[signal_logger_backlog]] +===== Signal logger_backlog + +The signal "logger_backlog" can be sent to display backlog (chat history) in +buffer (for example if you open your own buffer in your plugin/script). + +Argument is a pointer to buffer. + +C example: + +[source,C] +---- +weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer); +---- + +Script (Python): + +[source,python] +---- +weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer) +---- + +[[signals_xxx_script_install]] +===== Signals xxx_script_install + +Five signals can be sent to install a script, according to language: + +* 'perl_script_install' +* 'python_script_install' +* 'ruby_script_install' +* 'lua_script_install' +* 'tcl_script_install' + +The callback will do following actions when receiving signal: + +. unload and remove installed script +. move new script to directory '~/.weechat/xxx/' (where 'xxx' is language) +. create link to new script in directory '~/.weechat/xxx/autoload/' +. load new script + +These signals are used by 'script' plugin to install scripts. + +Argument is a string with path to script to install. + +C example: + +[source,C] +---- +weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, + "/home/xxx/.weechat/test.py"); +---- + +Script (Python): + +[source,python] +---- +weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, + "/home/xxx/.weechat/test.py") +---- + +[[signals_xxx_script_remove]] +===== Signals xxx_script_remove + +Five signals can be sent to remove list of scripts, according to language: + +* 'perl_script_remove' +* 'python_script_remove' +* 'ruby_script_remove' +* 'lua_script_remove' +* 'tcl_script_remove' + +For each script in list, the callback will unload then remove script. + +These signals are used by 'script' plugin to remove scripts. + +Argument is a string with comma-separated list of script to remove (script +is name without path, for example 'script.py'). + +C example: + +[source,C] +---- +/* unload and remove scripts test.py and script.py */ +weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING, + "test.py,script.py"); +---- + +Script (Python): + +[source,python] +---- +# unload and remove scripts test.py and script.py +weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING, + "test.py,script.py") +---- + +[[signal_irc_input_send]] +===== Signal irc_input_send + +_WeeChat ≥ 0.3.4._ + +The signal "irc_input_send" can be sent to simulate input in an irc buffer +(server, channel or private). + +Argument is a string with following format: + +* internal server name (required) +* semicolon +* channel name (optional) +* semicolon +* flags used when sending message (optional, default is 1): +** '1': queue with high priority (like user messages) +** '2': queue with low priority (like messages automatically sent by WeeChat) +* semicolon +* comma-separated list of tags used when sending message (optional) +* semicolon +* text or command (required) + +C examples: + +[source,C] +---- +/* say "Hello!" on freenode server, #weechat channel */ +weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, + "freenode;#weechat;1;;Hello!"); + +/* send command "/whois FlashCode" on freenode server, with low priority */ +weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, + "freenode;;2;;/whois FlashCode"); +---- + +Script (Python): + +[source,python] +---- +# say "Hello!" on freenode server, #weechat channel +weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, + "freenode;#weechat;1;;Hello!") + +# send command "/whois FlashCode" on freenode server, with low priority +weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, + "freenode;;2;;/whois FlashCode") +---- + +==== weechat_hook_hsignal + +_WeeChat ≥ 0.3.4._ + +Hook a hsignal (signal with hashtable). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_hsignal (const char *signal, + int (*callback)(void *data, + const char *signal, + struct t_hashtable *hashtable), + void *callback_data); +---- + +Arguments: + +* 'signal': signal to catch, wildcard "*" is allowed + (priority allowed, see note about <<hook_priority,priority>>) + (see table below) +* 'callback': function called when signal is received, arguments and return + value: +** 'void *data': pointer +** 'const char *signal': signal received +** 'struct t_hashtable *hashtable': hashtable +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_OK_EAT' (stop sending the signal immediately) + _(WeeChat ≥ 0.4.0)_ +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +List of hsignals: + +[width="100%",cols="^1,^3,5,5",options="header"] +|=== +| Plugin | Signal | Arguments | Description + +| irc | irc_redirection_xxx_yyy ^(1)^ + + _(WeeChat ≥ 0.3.4)_ | + See <<hsignal_irc_redirect_command,hsignal_irc_redirect_command>> | + Redirection output + +| weechat | nicklist_group_added + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'group' ('struct t_gui_nick_group *'): group | + Group added in nicklist + +| weechat | nicklist_nick_added + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'nick' ('struct t_gui_nick *'): nick | + Nick added in nicklist + +| weechat | nicklist_group_removing + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'group' ('struct t_gui_nick_group *'): group | + Removing group from nicklist + +| weechat | nicklist_nick_removing + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'nick' ('struct t_gui_nick *'): nick | + Removing nick from nicklist + +| weechat | nicklist_group_changed + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'group' ('struct t_gui_nick_group *'): group | + Group changed in nicklist + +| weechat | nicklist_nick_changed + + _(WeeChat ≥ 0.4.1)_ | + 'buffer' ('struct t_gui_buffer *'): buffer + + 'parent_group' ('struct t_gui_nick_group *'): parent group + + 'nick' ('struct t_gui_nick *'): nick | + Nick changed in nicklist +|=== + +[NOTE] +^(1)^ 'xxx' is signal argument used in redirection, 'yyy' is redirection +pattern. + +C example: + +[source,C] +---- +int +my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test", + &my_hsignal_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_hsignal(signal, callback, callback_data) + +# example +def my_hsignal_cb(data, signal, hashtable): + # ... + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_hsignal("test", "my_hsignal_cb", "") +---- + +==== weechat_hook_hsignal_send + +_WeeChat ≥ 0.3.4, updated in 1.0._ + +Send a hsignal (signal with hashtable). + +Prototype: + +[source,C] +---- +int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable); +---- + +Arguments: + +* 'signal': signal to send +* 'hashtable': hashtable + +Return value _(WeeChat ≥ 1.0)_: + +* return code of last callback executed ('WEECHAT_RC_OK' if no callback was + executed): +** 'WEECHAT_RC_OK' +** 'WEECHAT_RC_OK_EAT' +** 'WEECHAT_RC_ERROR' + +C example: + +[source,C] +---- +int rc; +struct t_hashtable *hashtable = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (hashtable) +{ + weechat_hashtable_set (hashtable, "key", "value"); + rc = weechat_hook_hsignal_send ("my_hsignal", hashtable); + weechat_hashtable_free (hashtable); +} +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.hook_hsignal_send(signal, hashtable) + +# example +rc = weechat.hook_hsignal_send("my_hsignal", { "key": "value" }) +---- + +[[hsignal_irc_redirect_command]] +===== Hsignal irc_redirect_command + +_WeeChat ≥ 0.3.4._ + +The hsignal "irc_redirect_command" can be sent to redirect output of irc +command to a callback. + +Argument is a hashtable with following entries (keys and values are string): + +* 'server': internal server name (required) +* 'pattern': redirect pattern to use (required), either a default one (defined + by irc plugin), or a user pattern (see <<hsignal_irc_redirect_pattern>>), + default patterns are: +** 'ison' +** 'list' +** 'mode_channel' +** 'mode_channel_ban' ("mode #channel b") +** 'mode_channel_ban_exception' ("mode #channel e") +** 'mode_channel_invite' ("mode #channel I") +** 'mode_user' +** 'monitor' +** 'names' +** 'ping' +** 'time' +** 'topic' +** 'userhost' +** 'who' +** 'whois' +** 'whowas' +* 'signal': signal name (required) +* 'count': number of times redirection will work (optional, 1 by default) +* 'string': string that must be in irc messages received (optional, but + recommended, if a string can be used to identify messages) +* 'timeout': timeout for redirect, in seconds (optional, 60 by default) +* 'cmd_filter': comma-separated list of irc commands to filter (only these + commands will be sent to callbacks, other will be ignored) (optional) + +Immediately after sending this hsignal, you must send command to irc server, +and redirection will be used for this command. + +When complete answer to your command has been be received, a hsignal will be +send. This hsignal has name 'irc_redirection_xxx_yyy' where 'xxx' is the +'signal' and 'yyy' the 'pattern' used. + +Hashtable sent in hsignal has following content (key and values are strings): + +* 'output': output of command (messages are separated by "\n") +* 'output_size': number of bytes in 'output' (as string) +* 'error': error string (if an error occurred): +** 'timeout': redirection stopped after timeout +* 'server': internal server name +* 'pattern': redirect pattern +* 'signal': signal name +* 'command': redirected command + +C example: + +[source,C] +---- +int +test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable) +{ + weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error")); + weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output")); + return WEECHAT_RC_OK; +} + +weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL); +struct t_hashtable *hashtable = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (hashtable) +{ + weechat_hashtable_set (hashtable, "server", "freenode"); + weechat_hashtable_set (hashtable, "pattern", "whois"); + weechat_hashtable_set (hashtable, "signal", "test"); + weechat_hashtable_set (hashtable, "string", "FlashCode"); + weechat_hook_hsignal_send ("irc_redirect_command", hashtable); + weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, + "freenode;;2;;/whois FlashCode"); + weechat_hashtable_free (hashtable); +} +---- + +Script (Python): + +[source,python] +---- +def test_whois_cb(data, signal, hashtable): + weechat.prnt("", "error = %s" % hashtable["error"]) + weechat.prnt("", "output = %s" % hashtable["output"]) + return weechat.WEECHAT_RC_OK + +weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "") +weechat.hook_hsignal_send("irc_redirect_command", + { "server": "freenode", "pattern": "whois", "signal": "test", + "string": "FlashCode" }) +weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, + "freenode;;2;;/whois FlashCode") +---- + +[[hsignal_irc_redirect_pattern]] +===== Hsignal irc_redirect_pattern + +_WeeChat ≥ 0.3.4._ + +The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc +redirect (see <<hsignal_irc_redirect_command>>). + +Argument is a hashtable with following entries (keys and values are string): + +* 'pattern': name of pattern (required) +* 'timeout': default timeout for pattern, in seconds (optional, 60 by default) +* 'cmd_start': comma-separated list of commands starting redirect (optional) +* 'cmd_stop': comma-separated list of commands stopping redirect (required) +* 'cmd_extra': comma-separated list of commands that may be received + after stop commands (optional) + +For each command in 'cmd_start', 'cmd_stop' and 'cmd_extra', it is possible to +give integer with position of "string" that must be found in received message, +for example: + +---- +352:1,354,401:1 +---- + +For commands 352 and 401, "string" must be found in received message, +as first argument. + +[IMPORTANT] +The pattern is destroyed when it is used by a redirection. If you need pattern +for many redirections, you must create pattern before each redirect. + +C example: + +[source,C] +---- +struct t_hashtable *hashtable = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (hashtable) +{ + weechat_hashtable_set (hashtable, "pattern", "my_whois"); + weechat_hashtable_set (hashtable, "timeout", "30"); + weechat_hashtable_set (hashtable, "cmd_start", "311:1"); + weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461"); + weechat_hashtable_set (hashtable, "cmd_extra", "318:1"); + weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable); + /* + * now redirect irc whois command with hsignal irc_redirect_command, + * using pattern "my_whois" + */ + /* ... */ + weechat_hashtable_free (hashtable); +} +---- + +Script (Python): + +[source,python] +---- +weechat.hook_hsignal_send("irc_redirect_pattern", + { "pattern": "my_whois", "timeout": "30", + "cmd_start": "311:1", + "cmd_stop": "318:1,401:1,402:1,431:1,461", + "cmd_extra": "318:1" }) +# now redirect irc whois command with hsignal irc_redirect_command +# using pattern "my_whois" +# ... +---- + +==== weechat_hook_config + +Hook a configuration option. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_config (const char *option, + int (*callback)(void *data, + const char *option, + const char *value), + void *callback_data); +---- + +Arguments: + +* 'option': option, format is full name, as used with command `/set` (for + example: `weechat.look.item_time_format`), wildcard "*" is allowed + (priority allowed, see note about <<hook_priority,priority>>) +* 'callback': function called when configuration option is changed, arguments + and return value: +** 'void *data': pointer +** 'const char *option': name of option +** 'const char *value': new value for option +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_completion + +Hook a completion. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_completion (const char *completion_item, + const char *description, + int (*callback)(void *data, + const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion), + void *callback_data); +---- + +Arguments: + +* 'completion_item': name of completion item, after you can use '%(name)' in + a command hooked (argument 'completion') + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description of completion +* 'callback': function called when completion item is used (user is completing + something using this item), arguments and return value: +** 'void *data': pointer +** 'const char *completion_item': name of completion item +** 'struct t_gui_buffer *buffer': buffer where completion is made +** 'struct t_gui_completion *completion': structure used to add words for + completion (see + <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>) +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +[NOTE] +Completion names are global (shared across WeeChat and plugins). So it is +recommended to choose a name with a unique prefix, like "plugin_xxx" (where +"xxx" is your item name). + +[IMPORTANT] +The callback must only call function +<<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>> +and must *NOT* update the command line. + +To update the command line when key[Tab] is pressed, you can use the function +<<_weechat_hook_command_run,weechat_hook_command_run>> with command: +"/input complete_next" (and you must return 'WEECHAT_RC_OK_EAT' if your callback +has updated the command line, so that WeeChat will not perform the completion). + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +int +my_completion_cb (void *data, const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion) +{ + weechat_hook_completion_list_add (completion, "word1", + 0, WEECHAT_LIST_POS_SORT); + weechat_hook_completion_list_add (completion, "test_word2", + 0, WEECHAT_LIST_POS_SORT); + return WEECHAT_RC_OK; +} + +struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item", + "my custom completion!", + &my_completion_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_completion(completion_item, description, callback, callback_data) + +# example +def my_completion_cb(data, completion_item, buffer, completion): + weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT) + weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT) + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_completion("plugin_item", "my custom completion!", + "my_completion_cb", "") +---- + +==== weechat_hook_completion_get_string + +_WeeChat ≥ 0.3.4._ + +Get a completion property as string. + +Prototype: + +[source,C] +---- +const char *weechat_hook_completion_get_string (struct t_gui_completion *completion, + const char *property); +---- + +Arguments: + +* 'completion': completion pointer +* 'property': property name: +** 'base_command': command used for completion +** 'base_word': word being completed +** 'args': command arguments (including base word) + +C example: + +[source,C] +---- +int +my_completion_cb (void *data, const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion) +{ + /* get arguments of command */ + const char *args = weechat_hook_completion_get_string (completion, "args"); + + /* completion depending on args */ + /* ... */ + + return WEECHAT_RC_OK; +} +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hook_completion_get_string(completion, property) + +# example +def my_completion_cb(data, completion_item, buffer, completion): + # get arguments of command + args = weechat.hook_completion_get_string(completion, "args") + # completion depending on args + # ... + return weechat.WEECHAT_RC_OK +---- + +==== weechat_hook_completion_list_add + +Add a word for a completion. + +Prototype: + +[source,C] +---- +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,weechat_hook_completion>>. + +Script (Python): + +[source,python] +---- +# prototype +weechat.hook_completion_list_add(completion, word, nick_completion, where) + +# example: see function hook_completion above +---- + +==== weechat_hook_modifier + +Hook a modifier. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_modifier (const char *modifier, + char *(*callback)(void *data, + const char *modifier, + const char *modifier_data, + const char *string), + void *callback_data); +---- + +Arguments: + +* 'modifier': modifier name, list of modifiers used by Weechat or plugins + (priority allowed, see note about <<hook_priority,priority>>) + (see table below) +* 'callback': function called when modifier is used, arguments and return value: +** 'void *data': pointer +** 'const char *modifier': name of modifier +** 'const char *modifier_data': data for modifier +** 'const char *string': string to modify +** return value: new string +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +List of modifiers used by WeeChat and plugins: + +[width="100%",cols="^2,3,4,4",options="header"] +|=== +| Modifier | Modifier data | String | Output + +| charset_decode | + plugin.buffer_name | + Any string | + String decoded from charset found for plugin/buffer to UTF-8 + +| charset_encode | + plugin.buffer_name | + Any string | + String encoded from UTF-8 to charset found for plugin/buffer + +| irc_color_decode | + "1" to keep colors, "0" to remove colors | + Any string | + String with IRC colors converted to WeeChat colors (or IRC colors removed) + +| irc_color_encode | + "1" to keep colors, "0" to remove colors | + Any string | + String with IRC colors (or IRC colors removed) + +| irc_color_decode_ansi + + _(WeeChat ≥ 1.0)_ | + "1" to keep colors, "0" to remove colors | + Any string | + String with ANSI colors converted to IRC colors (or ANSI colors removed) + +| irc_command_auth + + _(WeeChat ≥ 0.4.1)_ | + Server name | + Authentication command (for example: `/msg nickserv identify password`) | + command with hidden password (for example: `/msg nickserv identify ********`) + +| irc_message_auth + + _(WeeChat ≥ 0.4.1)_ | + Server name | + Message displayed after `/msg` sent to nickserv | + Message with hidden password + +| irc_in_xxx ^(1)^ | + Server name | + Content of message received from IRC server (before charset decoding) | + New content of message + +| irc_in2_xxx ^(1)^ + + _(WeeChat ≥ 0.3.5)_ | + Server name | + Content of message received from IRC server (after charset decoding) | + New content of message + +| irc_out1_xxx ^(1)^ + + _(WeeChat ≥ 0.3.7)_ | + Server name | + Content of message about to be sent to IRC server (before automatic split to + fit in 512 bytes) | + New content of message + +| irc_out_xxx ^(1)^ | + Server name | + Content of message about to be sent to IRC server (after automatic split to + fit in 512 bytes) | + New content of message + +| color_decode_ansi + + _(WeeChat ≥ 1.0)_ | + "1" to keep colors, "0" to remove colors | + Any string | + String with ANSI colors converted to WeeChat colors (or ANSI colors removed) + +| bar_condition_yyy ^(2)^ | + String with window pointer ("0x123..") | + Empty string | + "1" to display bar, "0" to hide it + +| history_add + + _(WeeChat ≥ 0.3.2)_ | + String with buffer pointer ("0x123..") | + Content of command line to add in command history (buffer and global) | + String added to command history + +| input_text_content | + String with buffer pointer ("0x123..") | + Content of command line | + New content of command line + +| input_text_display | + String with buffer pointer ("0x123..") | + Content of command line, without cursor tag | + New string, for display only (command line is not changed) + +| input_text_display_with_cursor | + String with buffer pointer ("0x123..") | + Content of command line, with cursor tag | + New string, for display only (command line is not changed) + +| input_text_for_buffer + + _(WeeChat ≥ 0.3.7)_ | + String with buffer pointer ("0x123..") | + Content of command line sent to buffer (text or command) | + New content of command line sent to buffer + +| weechat_print | + plugin + ";" + buffer_name + ";" + tags | + Message printed | + New message printed +|=== + +[NOTE] +^(1)^ 'xxx' is IRC command name. + +^(2)^ 'yyy' is bar name. + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_hook_modifier_exec + +Execute modifier(s). + +Prototype: + +[source,C] +---- +char *weechat_hook_modifier_exec (const char *modifier, + const char *modifier_data, + const char *string); +---- + +Arguments: + +* 'modifier': modifier name +* 'modifier_data': modifier data +* 'string': string to modify + +Return value: + +* string modified, NULL if error occurred + +C example: + +[source,C] +---- +char *new_string = weechat_hook_modifier_exec ("my_modifier", + my_data, my_string); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.hook_modifier_exec(modifier, modifier_data, string) + +# example +weechat.hook_modifier_exec("my_modifier", my_data, my_string) +---- + +==== weechat_hook_info + +Hook an information (callback takes and returns a string). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_info (const char *info_name, + const char *description, + const char *args_description, + const char *(*callback)(void *data, + const char *info_name, + const char *arguments), + void *callback_data); +---- + +Arguments: + +* 'info_name': name of info + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description +* 'args_description': description of arguments (optional, can be NULL) +* 'callback': function called when info is asked, arguments and return value: +** 'void *data': pointer +** 'const char *info_name': name of info +** 'const char *arguments': additional arguments, depending on info +** return value: value of info asked +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +const char * +my_info_cb (void *data, const char *info_name, const char *arguments) +{ + /* ... */ + return pointer_to_string; +} + +/* add info "my_info" */ +struct t_hook *my_info_hook = weechat_hook_info ("my_info", + "Some info", + "Info about arguments", + &my_info_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_info(info_name, description, args_description, callback, callback_data) + +# example +def my_info_cb(data, info_name, arguments): + return "some_info" + +hook = weechat.hook_info("my_info", "Some info", "Info about arguments", + "my_info_cb", "") +---- + +==== weechat_hook_info_hashtable + +_WeeChat ≥ 0.3.4._ + +Hook an information (callback takes and returns a hashtable). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_info_hashtable (const char *info_name, + const char *description, + const char *args_description, + const char *output_description, + struct t_hashtable *(*callback)(void *data, + const char *info_name, + struct t_hashtable *hashtable), + void *callback_data); +---- + +Arguments: + +* 'info_name': name of info + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description +* 'args_description': description of expected hashtable (optional, can be NULL) +* 'output_description': description of hashtable returned by callback + (optional, can be NULL) +* 'callback': function called when info is asked, arguments and return value: +** 'void *data': pointer +** 'const char *info_name': name of info +** 'struct t_hashtable *hashtable': hashtable, depending on info +** return value: hashtable asked +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +struct t_hashtable * +my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable) +{ + /* ... */ + return pointer_to_new_hashtable; +} + +/* add info "my_info_hashtable" */ +struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable", + "Some info", + "Info about input hashtable", + "Info about output hashtable", + &my_info_hashtable_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_info_hashtable(info_name, description, args_description, + output_description, callback, callback_data) + +# example +def my_info_hashtable_cb(data, info_name, hashtable): + return { "test_key": "test_value" } + +hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info", + "Info about input hashtable", + "Info about output hashtable", + "my_info_hashtable_cb", "") +---- + +==== weechat_hook_infolist + +Hook an infolist: callback will return pointer to infolist asked. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_infolist (const char *infolist_name, + const char *description, + const char *pointer_description, + const char *args_description, + struct t_infolist *(*callback)(void *data, + const char *infolist_name, + void *pointer, + const char *arguments), + void *callback_data); +---- + +Arguments: + +* 'infolist_name': name of infolist + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description +* 'pointer_description': description of pointer (optional, can be NULL) +* 'args_description': description of arguments (optional, can be NULL) +* 'callback': function called when infolist is asked, arguments and return + value: +** 'void *data': pointer +** 'const char *infolist_name': name of infolist +** 'void *pointer': pointer to an object that infolist must return (to get only + one item in infolist) +** 'const char *arguments': additional arguments, depending on infolist +** return value: infolist asked +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +struct t_infolist * +my_infolist_cb (void *data, const char *infolist_name, void *pointer, + const char *arguments) +{ + struct t_infolist *my_infolist; + + /* build infolist */ + /* ... */ + + return my_infolist; +} + +/* add infolist "my_infolist" */ +struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist", + "Infolist with some data", + "Info about pointer", + "Info about arguments", + &my_infolist_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_infolist(infolist_name, description, pointer_description, + args_description, callback, callback_data) + +# example +def my_infolist_cb(data, infolist_name, pointer, arguments): + # build infolist + # ... + return my_infolist + +hook = weechat.hook_infolist("my_infolist", "Infolist with some data", + "Info about pointer", "Info about arguments", + "my_infolist_cb", "") +---- + +==== weechat_hook_hdata + +Hook a hdata: callback will return pointer to hdata asked. + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_hdata (const char *hdata_name, + const char *description, + struct t_hdata *(*callback)(void *data, + const char *hdata_name), + void *callback_data); +---- + +Arguments: + +* 'hdata_name': name of hdata + (priority allowed, see note about <<hook_priority,priority>>) +* 'description': description +* 'callback': function called when hdata is asked, arguments and return + value: +** 'void *data': pointer +** 'const char *hdata_name': name of hdata +** return value: hdata asked +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +struct t_hdata * +my_hdata_cb (void *data, const char *hdata_name) +{ + struct t_hdata *my_hdata; + + /* build hdata */ + /* ... */ + + return my_hdata; +} + +/* add hdata "my_hdata" */ +struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata", + "Hdata for my structure", + &my_hdata_cb, NULL); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hook_focus + +Hook a focus: mouse event or key pressed in cursor mode (free movement of +cursor). + +Prototype: + +[source,C] +---- +struct t_hook *weechat_hook_focus (const char *area, + struct t_hashtable *(*callback)(void *data, + struct t_hashtable *info), + void *callback_data); +---- + +Arguments: + +* 'area': "chat" for chat area, or name of bar item + (priority allowed, see note about <<hook_priority,priority>>) +* 'callback': function called when focus is made, arguments and return + value: +** 'void *data': pointer +** 'struct t_hashtable *info': hashtable with info on focus and strings returned + by other calls to focus callbacks (with higher priority) (see table below) +** return value: either "info" pointer (hashtable completed), or pointer to a + new hashtable (created by callback, with keys and values of type "string"), + this new hashtable content will be added to 'info' for other calls to focus + callbacks +* 'callback_data': pointer given to callback when it is called by WeeChat + +[IMPORTANT] +For a mouse gesture, your callback will be called two times: first time when +button is pressed (here the area always matches your area), second time when +button is released, and then the area may not match your area: so you must +*always* test in your callback if area is matching before using info in +hashtable. + +Content of hashtable sent to callback (keys and values are of type "string"): + +[width="100%",cols="5m,5,8,3",options="header"] +|=== +| Key ^(1)^ | Description | Value examples | Value if N/A +| _x | Column on screen 2+| "0" ... "n" +| _y | Line on screen 2+| "0" ... "n" +| _key | Key or mouse event 2+| "button1", "button2-gesture-left", ... +| _window | Pointer to window | "0x12345678" | "" +| _window_number | Number of window | "1" ... "n" | "*" +| _buffer | Pointer to buffer | "0x12345678" | "" +| _buffer_number | Number of buffer | "1" ... "n" | "-1" +| _buffer_plugin | Plugin name of buffer | "core", "irc", ... | "" +| _buffer_name | Name of buffer | "weechat", "freenode.#weechat", ... | "" +| _buffer_full_name | Full name of buffer | "core.weechat", "irc.freenode.#weechat", ... | "" +| _buffer_localvar_XXX ^(2)^ | Local variables of buffer | any value | not set +| _chat | Chat area indicator | "0" or "1" | "0" +| _chat_line_x | Column in line ^(3)^ | "0" ... "n" | "-1" +| _chat_line_y | Line number ^(3)^ | "0" ... "n" | "-1" +| _chat_line_date | Line date/time | "1313237175" | "0" +| _chat_line_date_printed | Line date/time ^(4)^ | "1313237175" | "0" +| _chat_line_time | Time displayed | "14:06:15" | "" +| _chat_line_tags | Tags of line | "irc_privmsg,nick_flashy,log1" | "" +| _chat_line_nick | Nick of line | "FlashCode" | "" +| _chat_line_prefix | Prefix of line | "@FlashCode" | "" +| _chat_line_message | Message of line | "Hello world!" | "" +| _chat_word | Word at (x,y) | "Hello" | "" +| _chat_bol | Beginning of line ⇒ (x-1,y) | "He" | "" +| _chat_eol | (x,y) ⇒ end of line | "llo world!" | "" +| _bar_name | Name of bar | "title", "nicklist", ... | "" +| _bar_filling | Filling of bar | "horizontal", "vertical", ... | "" +| _bar_item_name | Name of bar item | "buffer_nicklist", "hotlist", ... | "" +| _bar_item_line | Line in bar item | "0" ... "n" | "-1" +| _bar_item_col | Column in bar item | "0" ... "n" | "-1" +|=== + +[NOTE] +^(1)^ There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", ...) +with info on second point (useful only for mouse gestures, to know where mouse +button has been released). + +^(2)^ `XXX` is name of local variable in buffer. + +^(3)^ It is set only for buffers with free content. + +^(4)^ It is date when WeeChat adds line in buffer (greater or equal to +"_chat_line_date"). + +Extra info for bar item "buffer_nicklist": + +[width="70%",cols="3m,3,8",options="header"] +|=== +| Key | Plugin ^(1)^ | Description +| nick | core | Nick name +| prefix | core | Prefix for nick +| group | core | Group name +| irc_host | irc | Host for nick (if known) +|=== + +[NOTE] +^(1)^ The name of plugin which defines a hook_focus to return info for this bar +item (so for example if plugin is "irc", such info will be available only on +irc buffers). + +Return value: + +* pointer to new hook, NULL if error occurred + +C example: + +[source,C] +---- +struct t_hashtable * +my_focus_nicklist_cb (void *data, struct t_hashtable *info) +{ + /* add strings in hashtable */ + /* ... */ + + return info; +} + +/* add focus on nicklist */ +struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist", + &my_focus_nicklist_cb, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +hook = weechat.hook_focus(area, callback, callback_data) + +# example +def my_focus_nicklist_cb(data, info): + # build dict + # ... + return my_dict + +hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "") +---- + +==== weechat_hook_set + +_WeeChat ≥ 0.3.9 (script: WeeChat ≥ 0.4.3)._ + +Set string value of a hook property. + +Prototype: + +[source,C] +---- +void weechat_hook_set (struct t_hook *hook, const char *property, + const char *value); +---- + +Arguments: + +* 'hook': something hooked with "weechat_hook_xxx()" +* 'property': property name (see table below) +* 'value': new value for property + +Properties: + +[width="100%",cols="^2,2,2,5",options="header"] +|=== +| Name | Hook type | Value | Description + +| subplugin | any type | any string | + Name of sub plugin (commonly script name, which is displayed in + `/help command` for a hook of type 'command') + +| stdin + + _(WeeChat ≥ 0.4.3)_ | + 'process', 'process_hashtable' | any string | + Send data on standard input ('stdin') of child process + +| stdin_close + + _(WeeChat ≥ 0.4.3)_ | + 'process', 'process_hashtable' | (not used) | + Close pipe used to send data on standard input ('stdin') of child process + +| signal + + _(WeeChat ≥ 1.0)_ | + 'process', 'process_hashtable' | + signal number or one of these names: `hup`, `int`, `quit`, `kill`, `term`, + `usr1`, `usr2` | + Send a signal to the child process +|=== + +C example: + +[source,C] +---- +struct t_hook *my_command_hook = + weechat_hook_command ("abcd", "description", + "args", "description args", + "", &my_command_cb, NULL); +weechat_hook_set (my_command_hook, "subplugin", "test"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.hook_set(hook, property, value) + +# example +def my_process_cb(data, command, return_code, out, err): + # ... + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_process_hashtable("/path/to/command", { "stdin": "1" }, + 20000, "my_process_cb", "") +weechat.hook_set(hook, "stdin", "data sent to stdin of child process") +weechat.hook_set(hook, "stdin_close", "") # optional +---- + +==== weechat_unhook + +Unhook something hooked. + +Prototype: + +[source,C] +---- +void weechat_unhook (struct t_hook *hook); +---- + +Arguments: + +* 'hook': something hooked with "weechat_hook_xxx()" + +C example: + +[source,C] +---- +struct t_hook *my_hook = weechat_hook_command ( /* ... */ ); +/* ... */ +weechat_unhook (my_hook); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.unhook(hook) + +# example +weechat.unhook(my_hook) +---- + +==== weechat_unhook_all + +Unhook everything that has been hooked by current plugin. + +Prototype: + +[source,C] +---- +void weechat_unhook_all (); +---- + +C example: + +[source,C] +---- +weechat_unhook_all (); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.unhook_all() + +# example +weechat.unhook_all() +---- + +[[buffers]] +=== Buffers + +Functions to create/query/close buffers. + +==== weechat_buffer_new + +Open a new buffer. + +Prototype: + +[source,C] +---- +struct t_gui_buffer *weechat_buffer_new (const char *name, + int (*input_callback)(void *data, + struct t_gui_buffer *buffer, + const char *input_data), + void *input_callback_data, + int (*close_callback)(void *data, + struct t_gui_buffer *buffer), + void *close_callback_data); +---- + +Arguments: + +* 'name': name of buffer (must be unique for plugin) +* 'input_callback': function called when input text is entered on buffer, + arguments and return value: +** 'void *data': pointer +** 'struct t_gui_buffer *buffer': buffer pointer +** 'const char *input_data': input data +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat +* 'close_callback': function called when buffer is closed, arguments and return + value: +** 'void *data': pointer +** 'struct t_gui_buffer *buffer': buffer pointer +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_data': pointer given to callback when it is called by WeeChat + +Return value: + +* pointer to new buffer, NULL if error occurred + +C example: + +[source,C] +---- +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): + +[source,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", "") +---- + +==== weechat_current_buffer + +Return pointer to current buffer (buffer displayed by current window). + +Prototype: + +[source,C] +---- +struct t_gui_buffer *weechat_current_buffer (); +---- + +Return value: + +* pointer to current buffer + +C example: + +[source,C] +---- +weechat_printf (weechat_current_buffer (), "Text on current buffer"); +---- + +Script (Python): + +[source,python] +---- +# prototype +buffer = weechat.current_buffer() + +# example +weechat.prnt(weechat.current_buffer(), "Text on current buffer") +---- + +==== weechat_buffer_search + +_Updated in 1.0._ + +Search a buffer by plugin and/or name. + +Prototype: + +[source,C] +---- +struct t_gui_buffer *weechat_buffer_search (const char *plugin, + const char *name); +---- + +Arguments: + +* 'plugin': name of plugin, following special value is allowed: +** `==`: the name used is the buffer full name (for example: + `irc.freenode.#weechat` instead of `freenode.#weechat`) + _(WeeChat ≥ 1.0)_ +* 'name': name of buffer, if it is NULL or empty string, the current buffer is + returned (buffer displayed by current window); if the name starts with + `(?i)`, the search is case insensitive _(WeeChat ≥ 1.0)_ + +Return value: + +* pointer to buffer found, NULL if not found + +C examples: + +[source,C] +---- +struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "freenode.#weechat"); +struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.freenode.#test"); /* WeeChat ≥ 1.0 */ +---- + +Script (Python): + +[source,python] +---- +# prototype +buffer = weechat.buffer_search(plugin, name) + +# example +buffer = weechat.buffer_search("my_plugin", "my_buffer") +---- + +==== weechat_buffer_search_main + +Search WeeChat main buffer ('core' buffer, first buffer displayed when WeeChat +is starting). + +Prototype: + +[source,C] +---- +struct t_gui_buffer *weechat_buffer_search_main (); +---- + +Return value: + +* pointer to WeeChat main buffer ('core' buffer) + +C example: + +[source,C] +---- +struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main (); +---- + +Script (Python): + +[source,python] +---- +# prototype +buffer = weechat.buffer_search_main() + +# example +buffer = weechat.buffer_search_main() +---- + +==== weechat_buffer_clear + +Clear content of a buffer. + +Prototype: + +[source,C] +---- +void weechat_buffer_clear (struct t_gui_buffer *buffer); +---- + +Arguments: + +* 'buffer': buffer pointer + +C example: + +[source,C] +---- +struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin", + "my_buffer"); +if (my_buffer) +{ + weechat_buffer_clear (my_buffer); +} +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.buffer_clear(buffer) + +# example +buffer = weechat.buffer_search("my_plugin", "my_buffer") +if buffer != "": + weechat.buffer_clear(buffer) +---- + +==== weechat_buffer_close + +Close a buffer. + +Prototype: + +[source,C] +---- +void weechat_buffer_close (struct t_gui_buffer *buffer); +---- + +Arguments: + +* 'buffer': buffer pointer + +C example: + +[source,C] +---- +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): + +[source,python] +---- +# prototype +weechat.buffer_close(buffer) + +# example +buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "") +# ... +weechat.buffer_close(buffer) +---- + +==== weechat_buffer_merge + +Merge buffer into another buffer: both buffers will still exist separately, but +with same number, and WeeChat will display lines from both buffers (mixed +lines). + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +/* merge current buffer with weechat "core" buffer */ +weechat_buffer_merge (weechat_current_buffer (), + weechat_buffer_search_main ()); +---- + +Script (Python): + +[source,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()) +---- + +==== weechat_buffer_unmerge + +Unmerge buffer from a group of merged buffers. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_buffer_unmerge (weechat_current_buffer (), 1); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.buffer_unmerge(buffer, number) + +# example +weechat.buffer_unmerge(weechat.current_buffer(), 1) +---- + +==== weechat_buffer_get_integer + +Return integer value of a buffer property. + +Prototype: + +[source,C] +---- +int weechat_buffer_get_integer (struct t_gui_buffer *buffer, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'property': property name: +** 'number': number of buffer (starts to 1) +** 'layout_number': number of buffer saved in layout +** 'layout_number_merge_order': order in merge for layout +** 'short_name_is_set': 1 if short name is set, 0 if not set +** 'type': buffer type (0: formatted, 1: free content) +** 'notify': notify level for buffer +** 'num_displayed': number of windows displaying buffer +** 'active': 2 if buffer is the only active (merged), 1 if buffer is active, + 0 if buffer is merged and not selected +** 'hidden': 1 if buffer is hidden, otherwise 0 + _(WeeChat ≥ 1.0)_ +** 'zoomed': 1 if buffer is merged and zoomed, otherwise 0 + _(WeeChat ≥ 1.0)_ +** 'print_hooks_enabled': 1 if print hooks are enabled, otherwise 0 +** 'day_change': 1 if messages for the day change are displayed, otherwise 0 + _(WeeChat ≥ 0.4.3)_ +** 'clear': 1 if buffer can be cleared with command `/buffer clear`, otherwise 0 + _(WeeChat ≥ 1.0)_ +** 'filter': 1 if filters are enabled on buffer, otherwise 0 + _(WeeChat ≥ 1.0)_ +** 'lines_hidden': 1 if at least one line is hidden on buffer (filtered), or 0 + if all lines are displayed +** 'prefix_max_length': max length for prefix in this buffer +** 'time_for_each_line': 1 if time is displayed for each line in buffer + (default), otherwise 0 +** 'nicklist': 1 if nicklist is enabled, otherwise 0 +** 'nicklist_case_sensitive': 1 if nicks are case sensitive, otherwise 0 +** 'nicklist_max_length': max length for a nick +** 'nicklist_display_groups': 1 if groups are displayed, otherwise 0 +** 'nicklist_count': number of nicks and groups in nicklist +** 'nicklist_groups_count': number of groups in nicklist +** 'nicklist_nicks_count': number of nicks in nicklist +** 'nicklist_visible_count': number of nicks/groups displayed +** 'input': 1 if input is enabled, otherwise 0 +** 'input_get_unknown_commands': 1 if unknown commands are sent to input + callback, otherwise 0 +** 'input_size': input size (in bytes) +** 'input_length': input length (number of chars) +** 'input_pos': cursor position in buffer input +** 'input_1st_display': first char displayed on screen +** 'num_history': number of commands in history +** 'text_search': text search type: +*** 0: no search at this moment +*** 1: backward search (direction: oldest messages) +*** 2: forward search (direction: newest messages) +** 'text_search_exact': 1 if text search is case sensitive +** 'text_search_found': 1 if text found, otherwise 0 + +Return value: + +* integer value of property + +C example: + +[source,C] +---- +weechat_printf (NULL, "my buffer number is: %d", + weechat_buffer_get_integer (my_buffer, "number")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.buffer_get_integer(buffer, property) + +# example +weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number")) +---- + +==== weechat_buffer_get_string + +Return string value of a buffer property. + +Prototype: + +[source,C] +---- +const char *weechat_buffer_get_string (struct t_gui_buffer *buffer, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'property': property name: +** 'plugin': name of plugin which created this buffer ("core" for WeeChat main + buffer) +** 'name': name of buffer +** 'full_name': full name of buffer ("plugin.name") _(WeeChat ≥ 0.3.7)_ +** 'short_name': short name of buffer (note: used for display only and can be + changed by user, this must not be used to find name of buffer, use instead + 'name', 'full_name' or local variable 'channel') +** 'title': title of buffer +** 'input': input text +** 'text_search_input': input saved before text search +** 'highlight_words': list of words to highlight +** 'highlight_regex': POSIX extended regular expression for highlight +** 'highlight_tags_restrict': restrict highlights to messages with these tags +** 'highlight_tags': force highlight on messages with these tags +** 'hotlist_max_level_nicks': max hotlist level for some nicks +** 'localvar_xxx': get content of local variable "xxx" (replace "xxx" by the + name of variable to read) + +Return value: + +* string value of property + +C example: + +[source,C] +---- +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): + +[source,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"))) +---- + +==== weechat_buffer_get_pointer + +Return pointer value of a buffer property. + +Prototype: + +[source,C] +---- +void *weechat_buffer_pointer (struct t_gui_buffer *buffer, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'property': property name: +** 'plugin': pointer to plugin which created this buffer (NULL for WeeChat main + buffer) +** 'highlight_regex_compiled': regular expression 'highlight_regex' compiled + +Return value: + +* pointer value of property + +C example: + +[source,C] +---- +weechat_printf (NULL, "plugin pointer of my buffer: %lx", + weechat_buffer_get_pointer (my_buffer, "plugin")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.buffer_get_pointer(buffer, property) + +# example +weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin")) +---- + +==== weechat_buffer_set + +Set string value of a buffer property. + +Prototype: + +[source,C] +---- +void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property, + const char *value); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'property': property name (see table below) +* 'value': new value for property + +Properties: + +[width="100%",cols="^2,4,8",options="header"] +|=== +| Name | Value | Description + +| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, + WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" | + "+": enable hotlist (global setting, buffer pointer is not used) + + "-": disable hotlist (global setting, buffer pointer is not used) + + priority: add buffer to hotlist with this priority + + "-1": remove buffer from hotlist _(WeeChat ≥ 1.0)_ + +| completion_freeze | "0" or "1" | + "0": no freeze of completion (default value) + (global setting, buffer pointer is not used) + + "1": do not stop completion when command line is updated + (global setting, buffer pointer is not used) + +| unread | - | + Set unread marker after last line of buffer + +| display | "1" or "auto" | + "1": switch to this buffer in current window + + "auto": switch to this buffer in current window, read marker is not reset + +| hidden + + _(WeeChat ≥ 1.0)_ | "0" or "1" | + "0": unhide the buffer + + "1": hide the buffer + +| 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); when the value is "free", the property 'clear' is forced to "0" + _(WeeChat ≥ 1.0)_ + +| notify | "0", "1", "2", "3" | + Set notify level for buffer: "0" = never add to hotlist, "1" = add for + highlights only, "2" = add for highlights and messages, "3" = add for all + messages + +| print_hooks_enabled | "0" or "1" | + "0" to disable print hooks, "1" to enable them (default for a new buffer) + +| day_change + + _(WeeChat ≥ 0.4.3)_ | "0" or "1" | + "0" to hide messages for the day change, "1" to see them + (default for a new buffer) + +| clear + + _(WeeChat ≥ 1.0)_ | "0" or "1" | + "0" to prevent user from clearing buffer with the command `/buffer clear`, + "1" to let user clear the buffer (default for a new buffer) + (note: even when it is set to "0", the buffer can still be cleared with + the function <<_weechat_buffer_clear,weechat_buffer_clear>>) + +| filter + + _(WeeChat ≥ 1.0)_ | "0" or "1" | + "0": disable filters on buffer + + "1": enable filters on buffer + +| 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_words_add | comma separated list of words | + Comma separated list of words to highlight in this buffer, these words are + added to existing highlighted words in buffer + +| highlight_words_del | comma separated list of words | + Comma separated list of words to remove from highlighted words on buffer + +| highlight_regex | any string | + POSIX extended regular expression for highlight + +| highlight_tags_restrict | comma separated list of tags | + Restrict highlights to messages with these tags in this buffer + (it is possible to combine many tags as a logical "and" with separator "+", + for example: "nick_toto+irc_action") + +| highlight_tags | comma separated list of tags | + Force highlight on messages with these tags in this buffer + (it is possible to combine many tags as a logical "and" with separator "+", + for example: "nick_toto+irc_action") + +| hotlist_max_level_nicks | comma separated list of "nick:level" | + Comma separated list of nicks with max level for hotlist on this buffer + (level can be: -1: never in hotlist, 0: low, 1: message, 2: private, + 3: highlight), for example: "joe:2,mike:-1,robert:-1" (joe will never produce + highlight on buffer, mike and robert will never change hotlist) + +| hotlist_max_level_nicks_add | comma separated list of "nick:level" | + Comma separated list of nicks with level for hotlist, these nicks are + added to existing nicks in buffer + +| hotlist_max_level_nicks_del | comma separated list of nicks | + Comma separated list of nicks to remove from hotlist max levels + +| key_bind_xxx | any string | + Bind a new key 'xxx', specific to this buffer, value is command to execute + for this key + +| key_unbind_xxx | - | + Unbind key 'xxx' for this buffer + +| input | 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 behavior), "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 | - | + Remove local variable 'xxx' +|=== + +C example: + +[source,C] +---- +/* 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): + +[source,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.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", "") +---- + +==== weechat_buffer_set_pointer + +Set pointer value of a buffer property. + +Prototype: + +[source,C] +---- +void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property, + void *pointer); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'property': property name: +** 'close_callback': set close callback function +** 'close_callback_data': set close callback data +** 'input_callback': set input callback function +** 'input_callback_data': set input callback data +** 'nickcmp_callback': set nick comparison callback function (this callback is + called when searching nick in nicklist) _(WeeChat ≥ 0.3.9)_ +** 'nickcmp_callback_data': set nick comparison callback data + _(WeeChat ≥ 0.3.9)_ +* 'pointer': new pointer value for property + +Prototypes for callbacks: + +[source,C] +---- +int close_callback (void *data, struct t_gui_buffer *buffer); + +int input_callback (void *data, struct t_gui_buffer *buffer, const char *input_data); + +int nickcmp_callback (void *data, struct t_gui_buffer *buffer, const char *nick1, const char *nick2); +---- + +C example: + +[source,C] +---- +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); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_buffer_string_replace_local_var + +Replace local variables in a string by their values, using buffer local +variables. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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" +---- + +==== weechat_buffer_match_list + +_WeeChat ≥ 0.3.5._ + +Check if buffer matches a list of buffers. + +Prototype: + +[source,C] +---- +int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'string': comma-separated list of buffers: +** "*" means all buffers +** name beginning with "!" is excluded +** wildcard "*" is allowed in name + +Return value: + +* 1 if buffer matches list of buffers, 0 otherwise + +C example: + +[source,C] +---- +struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "freenode.#weechat"); +if (buffer) +{ + weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*")); /* 1 */ + weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*")); /* 0 */ + weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.freenode.*")); /* 1 */ + weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*")); /* 0 */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +match = weechat.buffer_match_list(buffer, string) + +# example +buffer = weechat.buffer_search("irc", "freenode.#weechat") +if buffer: + weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*")) # 1 + weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*")) # 0 + weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.freenode.*")) # 1 + weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*")) # 0 +---- + +[[windows]] +=== Windows + +Functions to query windows. + +==== weechat_current_window + +Return pointer to current window. + +Prototype: + +[source,C] +---- +struct t_gui_window *weechat_current_window (); +---- + +Return value: + +* pointer to current window + +C example: + +[source,C] +---- +struct t_gui_window *current_window = weechat_current_window (); +---- + +Script (Python): + +[source,python] +---- +# prototype +window = weechat.current_window() + +# example +current_window = weechat.current_window() +---- + +==== weechat_window_search_with_buffer + +_WeeChat ≥ 0.3.5._ + +Return pointer to window displaying buffer. + +Prototype: + +[source,C] +---- +struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer); +---- + +Arguments: + +* 'buffer': buffer pointer + +Return value: + +* pointer to window displaying buffer (NULL if no window is displaying buffer) + +C example: + +[source,C] +---- +weechat_printf (NULL, + "window displaying core buffer: %lx", + weechat_window_search_with_buffer (weechat_buffer_search_main ())); +---- + +Script (Python): + +[source,python] +---- +# prototype +window = weechat.window_search_with_buffer(buffer) + +# example +weechat.prnt("", "window displaying core buffer: %s" + % weechat.window_search_with_buffer(weechat.buffer_search_main())) +---- + +==== weechat_window_get_integer + +Return integer value of a window property. + +Prototype: + +[source,C] +---- +int weechat_window_get_integer (struct t_gui_window *window, + const char *property); +---- + +Arguments: + +* 'window': window pointer +* 'property': property name: +** 'number': number of window (starts to 1) +** 'win_x': X position of window in terminal (first column is 0) +** 'win_y': Y position of window in terminal (first line is 0) +** 'win_width': width of window, in chars +** 'win_height': height of window, in chars +** 'win_width_pct': percentage size, compared to parent window (for example 50 + means half size) +** 'win_height_pct': percentage size, compared to parent window (for example 50 + means half size) +** 'win_chat_x': X position of chat window in terminal (first column is 0) +** 'win_chat_y': Y position of chat window in terminal (first line is 0) +** 'win_chat_width': width of chat window, in chars +** 'win_chat_height': height of chat window, in chars +** 'first_line_displayed': 1 if first line of buffer is displayed on screen, + otherwise 0 +** 'scrolling': 1 if scroll is active on window (last line not displayed) +** 'lines_after': number of lines not displayed after last one displayed + (when scrolling) + +Return value: + +* integer value of property + +C example: + +[source,C] +---- +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): + +[source,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"))) +---- + +==== weechat_window_get_string + +Return string value of a window property. + +[NOTE] +This function is not used today, it is reserved for a future version. + +Prototype: + +[source,C] +---- +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 + +==== weechat_window_get_pointer + +Return pointer value of a window property. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, + "buffer displayed in current window: %lx", + weechat_window_get_pointer (weechat_current_window (), "buffer")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.window_get_pointer(window, property) + +# example +weechat.prnt("", "buffer displayed in current window: %s" + % weechat.window_get_pointer(weechat.current_window(), "buffer")) +---- + +==== weechat_window_set_title + +Set title for terminal. + +Prototype: + +[source,C] +---- +void weechat_window_set_title (const char *title); +---- + +Arguments: + +* 'title': new title for terminal (NULL to reset title) + +C example: + +[source,C] +---- +weechat_window_set_title ("new title here"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.window_set_title(window, title) + +# example +weechat.window_set_title("new title here") +---- + +[[nicklist]] +=== Nicklist + +Functions for buffer nicklist. + +==== weechat_nicklist_add_group + +Add a group in a nicklist. + +Prototype: + +[source,C] +---- +struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer, + struct t_gui_nick_group *parent_group, + const char *name, + const char *color, + int visible); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'parent_group': pointer to parent of group, NULL if group has no parent + (nicklist root) +* 'name': group name +* 'color': color option name: +** WeeChat option name, for example 'weechat.color.nicklist_group' +** color with optional background, for example 'yellow' or 'yellow,red' +** bar color name: +*** 'bar_fg': foreground color for bar +*** 'bar_delim': delimiters color for bar +*** 'bar_bg': background color for bar +* 'visible': +** '1': group and sub-groups/nicks are visible +** '0': group and sub-groups/nicks are hidden + +[NOTE] +The group name can begin with one or more digits, followed by pipe, and then +group name. When such string is found at beginning, it's used to sort groups +in nicklist. For example groups "1|test" and "2|abc" will be displayed in that +order: first "test" then "abc". + +Return value: + +* pointer to new group, NULL if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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) +---- + +==== weechat_nicklist_search_group + +Search a group in a nicklist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer, + NULL, "test_group"); +---- + +Script (Python): + +[source,python] +---- +# prototype +group = weechat.nicklist_search_group(buffer, from_group, name) + +# example +group = weechat.nicklist_search_group(my_buffer, "", "test_group") +---- + +==== weechat_nicklist_add_nick + +Add a nick in a group. + +Prototype: + +[source,C] +---- +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 occurred + +C example: + +[source,C] +---- +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): + +[source,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) +---- + +==== weechat_nicklist_search_nick + +Search a nick in a nicklist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer, + NULL, "test_nick"); +---- + +Script (Python): + +[source,python] +---- +# prototype +nick = weechat.nicklist_search_nick(buffer, from_group, name) + +# example +nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick") +---- + +==== weechat_nicklist_remove_group + +Remove a group from a nicklist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_nicklist_remove_group (my_buffer, my_group); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.nicklist_remove_group(buffer, group) + +# example +weechat.nicklist_remove_group(my_buffer, my_group) +---- + +==== weechat_nicklist_remove_nick + +Remove a nick from a nicklist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_nicklist_remove_nick (my_buffer, my_nick); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.nicklist_remove_nick(buffer, nick) + +# example +weechat.nicklist_remove_nick(my_buffer, my_nick) +---- + +==== weechat_nicklist_remove_all + +Remove all groups/nicks from a nicklist. + +Prototype: + +[source,C] +---- +void weechat_nicklist_remove_all (struct t_gui_buffer *buffer); +---- + +Arguments: + +* 'buffer': buffer pointer + +C example: + +[source,C] +---- +weechat_nicklist_remove_all (my_buffer); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.nicklist_remove_all(buffer) + +# example +weechat.nicklist_remove_all(my_buffer) +---- + +==== weechat_nicklist_get_next_item + +_WeeChat ≥ 0.3.7._ + +Get next group or nick from nicklist (mainly used to display nicklist). + +Prototype: + +[source,C] +---- +void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer, + struct t_gui_nick_group **group, + struct t_gui_nick **nick); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'group': pointer on pointer to group +* 'nick': pointer on pointer to nick + +C example: + +[source,C] +---- +struct t_gui_nick_group *ptr_group; +struct t_gui_nick *ptr_nick; + +ptr_group = NULL; +ptr_nick = NULL; +weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick); +while (ptr_group || ptr_nick) +{ + if (ptr_nick) + { + /* nick */ + /* ... */ + } + else + { + /* group */ + /* ... */ + } + weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick); +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_nicklist_group_get_integer + +_WeeChat ≥ 0.3.4._ + +Return integer value of a group property. + +Prototype: + +[source,C] +---- +int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'group': group pointer +* 'property': property name: +** 'visible': 1 if group is visible, otherwise 0 +** 'level': group level (root is 0) + +Return value: + +* integer value of property + +C example: + +[source,C] +---- +int visible = weechat_nicklist_group_get_integer (buffer, group, "visible"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_group_get_integer(buffer, group, property) + +# example +visible = weechat.nicklist_group_get_integer(buffer, group, "visible") +---- + +==== weechat_nicklist_group_get_string + +_WeeChat ≥ 0.3.4._ + +Return string value of a group property. + +Prototype: + +[source,C] +---- +const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'group': group pointer +* 'property': property name: +** 'name': name of group +** 'color': group color in nicklist + +Return value: + +* string value of property + +C example: + +[source,C] +---- +const char *color = weechat_nicklist_group_get_string (buffer, group, "color"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_group_get_string(buffer, group, property) + +# example +color = weechat.nicklist_group_get_string(buffer, group, "color") +---- + +==== weechat_nicklist_group_get_pointer + +_WeeChat ≥ 0.3.4._ + +Return pointer value of a group property. + +Prototype: + +[source,C] +---- +void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'group': group pointer +* 'property': property name: +** 'parent': pointer to parent group + +Return value: + +* pointer value of property + +C example: + +[source,C] +---- +struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_group_get_pointer(buffer, group, property) + +# example +parent = weechat.nicklist_group_get_pointer(buffer, group, "parent") +---- + +==== weechat_nicklist_group_set + +_WeeChat ≥ 0.3.4._ + +Set string value of a group property. + +Prototype: + +[source,C] +---- +void weechat_nicklist_group_set (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group, + const char *property, + const char *value); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'group': group pointer +* 'property': property name (see table below) +* 'value': new value for property + +Properties: + +[width="100%",cols="^2,4,8",options="header"] +|=== +| Name | Value | Description + +| color | WeeChat color option name | + See argument "color" of function + <<_weechat_nicklist_add_group,weechat_nicklist_add_group>> + +| visible | "0", "1" | + "0" = hidden group, "1" = visible group +|=== + +C examples: + +[source,C] +---- +/* change group color to "bar_fg" */ +weechat_nicklist_group_set (buffer, group, "color", "bar_fg"); + +/* change group color to yellow */ +weechat_nicklist_group_set (buffer, group, "color", "yellow"); + +/* hide group in nicklist */ +weechat_nicklist_group_set (buffer, group, "visible", "0"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.nicklist_group_set(buffer, group, property, value) + +# examples + +# change group color to "bar_fg" +weechat.nicklist_group_set(buffer, group, "color", "bar_fg") + +# change group color to yellow +weechat.nicklist_group_set(buffer, group, "color", "yellow") + +# hide group in nicklist +weechat.nicklist_group_set(buffer, group, "visible", "0") +---- + +==== weechat_nicklist_nick_get_integer + +_WeeChat ≥ 0.3.4._ + +Return integer value of a nick property. + +Prototype: + +[source,C] +---- +int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer, + struct t_gui_nick *nick, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'nick': nick pointer +* 'property': property name: +** 'visible': 1 if nick is visible, otherwise 0 + +Return value: + +* integer value of property + +C example: + +[source,C] +---- +int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_nick_get_integer(buffer, nick, property) + +# example +visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible") +---- + +==== weechat_nicklist_nick_get_string + +_WeeChat ≥ 0.3.4._ + +Return string value of a nick property. + +Prototype: + +[source,C] +---- +const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer, + struct t_gui_nick *nick, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'nick': nick pointer +* 'property': property name: +** 'name': name of nick +** 'color': nick color in nicklist +** 'prefix': prefix of nick +** 'prefix_color': prefix color in nicklist + +Return value: + +* string value of property + +C example: + +[source,C] +---- +const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_nick_get_string(buffer, nick, property) + +# example +color = weechat.nicklist_nick_get_string(buffer, nick, "color") +---- + +==== weechat_nicklist_nick_get_pointer + +_WeeChat ≥ 0.3.4._ + +Return pointer value of a nick property. + +Prototype: + +[source,C] +---- +void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer, + struct t_gui_nick *nick, + const char *property); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'nick': nick pointer +* 'property': property name: +** 'group': pointer to group containing this nick + +Return value: + +* pointer value of property + +C example: + +[source,C] +---- +struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group"); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.nicklist_nick_get_pointer(buffer, nick, property) + +# example +group = weechat.nicklist_nick_get_pointer(buffer, nick, "group") +---- + +==== weechat_nicklist_nick_set + +_WeeChat ≥ 0.3.4._ + +Set string value of a nick property. + +Prototype: + +[source,C] +---- +void weechat_nicklist_nick_set (struct t_gui_buffer *buffer, + struct t_gui_nick *nick, + const char *property, + const char *value); +---- + +Arguments: + +* 'buffer': buffer pointer +* 'nick': nick pointer +* 'property': property name (see table below) +* 'value': new value for property + +Properties: + +[width="100%",cols="^2,4,8",options="header"] +|=== +| Name | Value | Description + +| color | WeeChat color option name | + See argument "color" of function + <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>> + +| prefix | any string | + Prefix of nick + +| prefix_color | WeeChat color option name | + See argument "prefix_color" of function + <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>> + +| visible | "0", "1" | + "0" = hidden nick, "1" = visible nick +|=== + +C examples: + +[source,C] +---- +/* change nick color to cyan */ +weechat_nicklist_nick_set (buffer, nick, "color", "cyan"); + +/* change prefix to "+" */ +weechat_nicklist_nick_set (buffer, nick, "prefix", "+"); + +/* change prefix color to yellow */ +weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow"); + +/* hide nick in nicklist */ +weechat_nicklist_nick_set (buffer, nick, "visible", "0"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.nicklist_nick_set(buffer, nick, property, value) + +# examples + +# change nick color to cyan +weechat.nicklist_nick_set(buffer, nick, "color", "cyan") + +# change prefix to "+" +weechat.nicklist_nick_set(buffer, nick, "prefix", "+") + +# change prefix color to yellow +weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow") + +# hide nick in nicklist +weechat.nicklist_nick_set(buffer, nick, "visible", "0") +---- + +[[bars]] +=== Bars + +Functions for bars. + +==== weechat_bar_item_search + +Search a bar item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem"); +---- + +Script (Python): + +[source,python] +---- +# prototype +bar_item = weechat.bar_item_search(name) + +# example +bar_item = weechat.bar_item_search("myitem") +---- + +==== weechat_bar_item_new + +_Updated in 0.4.2._ + +Create a new bar item. + +Prototype: + +[source,C] +---- +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, + struct t_gui_buffer *buffer, + struct t_hashtable *extra_info), + void *build_callback_data); +---- + +Arguments: + +* 'name': bar item name +* 'build_callback': function called when bar item is built, arguments and + return value: +** 'void *data': pointer +** 'struct t_gui_bar_item *item': item pointer +** 'struct t_gui_window *window': window pointer (NULL when called for a root + bar) +** 'struct t_gui_buffer *buffer': buffer displayed in window (if window is NULL, + then it is current buffer) or buffer given in bar item with syntax: + "@buffer:item" _(WeeChat ≥ 0.4.2)_ +** 'struct t_hashtable *extra_info': always NULL (argument is reserved for a + future version) _(WeeChat ≥ 0.4.2)_ +** return value: content of bar item +* 'build_callback_data': pointer given to build callback, when it is called by + WeeChat + +Return value: + +* pointer to new bar item, NULL if an error occurred + +C example: + +[source,C] +---- +char * +my_build_callback (void *data, + struct t_gui_bar_item *item, + struct t_gui_window *window, + struct t_gui_buffer *buffer, + struct t_hashtable *extra_info) +{ + return strdup ("my content"); +} + +struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem", + &my_build_callback, + NULL); +---- + +Script (Python): + +[IMPORTANT] +For compatibility with versions ≤ 0.4.1, the default callback has only 3 +arguments: 'data', 'item' and 'window' (no 'buffer' and 'extra_info'). + +To use a callback with all arguments, you must add "(extra)" before the name, +see example below (supported only in WeeChat ≥ 0.4.2). + +[source,python] +---- +# prototype +bar_item = weechat.bar_item_new(name, build_callback, build_callback_data) + +# example (callback without "buffer" and "extra_info") +def my_build_callback(data, item, window): + return "my content" + +bar_item = weechat.bar_item_new("myitem", "my_build_callback", "") + +# example (callback with all arguments, for WeeChat ≥ 0.4.2) +def my_build_callback2(data, item, window, buffer, extra_info): + return "my content" + +bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "") # WeeChat ≥ 0.4.2 +---- + +==== weechat_bar_item_update + +Update content of a bar item, by calling its build callback. + +Prototype: + +[source,C] +---- +void weechat_bar_item_update (const char *name); +---- + +Arguments: + +* 'name': bar item name + +C example: + +[source,C] +---- +weechat_bar_item_update ("myitem"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.bar_item_update(name) + +# example +weechat.bar_item_update("myitem") +---- + +==== weechat_bar_item_remove + +Remove a bar item. + +Prototype: + +[source,C] +---- +void weechat_bar_item_remove (struct t_gui_bar_item *item); +---- + +Arguments: + +* 'item': bar item pointer + +C example: + +[source,C] +---- +weechat_bar_item_remove (&my_item); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.bar_item_remove(item) + +# example +weechat.bar_item_remove(myitem) +---- + +==== weechat_bar_search + +Search a bar. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_gui_bar *bar = weechat_bar_search ("mybar"); +---- + +Script (Python): + +[source,python] +---- +# prototype +bar = weechat.bar_search(name) + +# example +bar = weechat.bar_search("mybar") +---- + +==== weechat_bar_new + +Create a new bar. + +Prototype: + +[source,C] +---- +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 horizontally (space after each item) +** 'vertical': items are filled vertically (new line after each item) +** 'columns_horizontal': items are filled horizontally, displayed with columns +** 'columns_vertical': items are filled vertically, displayed with columns +* 'size': bar size in chars (0 means automatic size) +* 'size_max': max size for bar (0 means no max size) +* 'color_fg': color for text in bar +* 'color_delim': color for delimiters in bar +* 'color_bg': background color for bar +* 'separator': +** 'on': bar has separator line with other windows/bars +** 'off': no separator +* 'items': list of items in bar, separated by comma (space between items), or + "+" (glued items) + +Return value: + +* pointer to new bar, NULL if an error occurred + +C example: + +[source,C] +---- +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): + +[source,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") +---- + +==== weechat_bar_set + +Set a new value for a bar property. + +Prototype: + +[source,C] +---- +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,weechat_bar_new>>) +* 'value': new value for property + +Return value: + +* 1 if new value was set, 0 if an error occurred + +C example: + +[source,C] +---- +weechat_bar_set (mybar, "position", "bottom"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.bar_set(bar, property, value) + +# example +weechat.bar_set(my_bar, "position", "bottom") +---- + +==== weechat_bar_update + +Refresh content of a bar on screen. + +Prototype: + +[source,C] +---- +void weechat_bar_update (const char *name); +---- + +Arguments: + +* 'name': bar name + +C example: + +[source,C] +---- +weechat_bar_update ("mybar"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.bar_update(name) + +# example +weechat.bar_update("mybar") +---- + +==== weechat_bar_remove + +Remove a bar. + +Prototype: + +[source,C] +---- +void weechat_bar_remove (struct t_gui_bar *bar); +---- + +Arguments: + +* 'bar': bar pointer + +C example: + +[source,C] +---- +weechat_bar_remove (mybar); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.bar_remove(bar) + +# example +weechat.bar_remove(my_bar) +---- + +[[commands]] +=== Commands + +Functions for executing WeeChat commands. + +==== weechat_command + +Execute a command. + +Prototype: + +[source,C] +---- +void weechat_command (struct t_gui_buffer *buffer, const char *command); +---- + +Arguments: + +* 'buffer': buffer pointer (command is executed on this buffer, use NULL for + current buffer) +* 'command': command to execute (if beginning with a "/"), or text to send to + buffer + +C example: + +[source,C] +---- +weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"), + "/whois FlashCode"); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.command(buffer, command) + +# example +weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode") +---- + +[[network]] +=== Network + +Network functions. + +==== weechat_network_pass_proxy + +Establish a connection/authentication to a proxy. + +[IMPORTANT] +This function is blocking on call to connect(), so it must be called in a forked +process only, to not block WeeChat. + +Prototype: + +[source,C] +---- +int weechat_network_pass_proxy (const char *proxy, + int sock, + const char *address, + int port); +---- + +Arguments: + +* 'proxy': proxy name to use +* 'sock': socket to use +* 'address': address (hostname or IP address) +* 'port': port + +Return value: + +* 1 if connection is OK, 0 if an error occurred + +C example: + +[source,C] +---- +if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667)) +{ + /* OK */ +} +else +{ + /* error */ +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_network_connect_to + +_Updated in 0.4.3._ + +Establish a connection to a remote host. + +[IMPORTANT] +This function is blocking on call to connect(), so it must be called in a forked +process only, to not block WeeChat. + +Prototype: + +[source,C] +---- +int weechat_network_connect_to (const char *proxy, + struct sockaddr *address, + socklen_t address_length); +---- + +Arguments: + +* 'proxy': proxy name to use +* 'address': address to connect to (with port) +* 'address_length': length of argument 'address' + +Return value: + +* socket number (>= 0) if connection is OK, -1 if an error occurred + +C example: + +[source,C] +---- +struct sockaddr *addr; +socklen_t length; +int sock; + +/* allocate/set address and port in 'addr', set 'length' */ +/* ... */ + +sock = weechat_network_connect_to (NULL, addr, length); +if (sock >= 0) +{ + /* OK */ +} +else +{ + /* error */ +} +---- + +[NOTE] +This function is not available in scripting API. + +[[infos]] +=== Infos + +Functions to get infos. + +==== weechat_info_get + +Return info, as string, from WeeChat or a plugin. + +Prototype: + +[source,C] +---- +const char *weechat_info_get (const char *info_name, const char *arguments); +---- + +Arguments: + +* 'info_name': name of info to read (see table below) +* 'arguments': arguments for info asked (optional, NULL if no argument is + needed) + +Return value: + +* string with info asked, NULL if an error occurred + +Infos: + +include::autogen/plugin_api/infos.asciidoc[] + +C example: + +[source,C] +---- +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", NULL)); +---- + +Script (Python): + +[source,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", "")) +---- + +==== weechat_info_get_hashtable + +_WeeChat ≥ 0.3.4._ + +Return info, as hashtable, from WeeChat or a plugin. + +Prototype: + +[source,C] +---- +struct t_hashtable *weechat_info_get_hashtable (const char *info_name, + struct t_hashtable *hashtable); +---- + +Arguments: + +* 'info_name': name of info to read (see table below) +* 'hashtable': hashtable with arguments (depends on info asked) (optional, NULL + if no argument is needed) + +Return value: + +* hashtable with info asked, NULL if an error occurred + +Infos: + +include::autogen/plugin_api/infos_hashtable.asciidoc[] + +C example: + +[source,C] +---- +struct t_hashtable *hashtable_in, *hashtable_out; + +hashtable_in = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); +if (hashtable_in) +{ + weechat_hashtable_set (hashtable_in, "message", + ":nick!user@host PRIVMSG #weechat :message here"); + hashtable_out = weechat_info_get_hashtable ("irc_message_parse", + hashtable_in); + /* + * now hashtable_out has following keys/values: + * "nick" : "nick" + * "host" : "nick!user@host" + * "command" : "PRIVMSG" + * "channel" : "#weechat" + * "arguments": "#weechat :message here" + */ + weechat_hashtable_free (hashtable_in); + weechat_hashtable_free (hashtable_out); +} +---- + +Script (Python): + +[source,python] +---- +# prototype +dict = weechat.info_get_hashtable(info_name, dict_in) + +# example +dict_in = { "message": ":nick!user@host PRIVMSG #weechat :message here" } +weechat.prnt("", "message parsed: %s" + % weechat.info_get_hashtable("irc_message_parse", dict_in)) +---- + +[[infolists]] +=== Infolists + +An infolist is a list of "items". Each item contains variables. + +For example, infolist "irc_server" has N items (N is number of IRC servers +defined). For each item, there is variables like "name", "buffer", +"is_connected", ... + +Each variable has a type and a value. Possible types are: + +* 'integer': any integer value +* 'string': any string value +* 'pointer': any pointer +* 'buffer': buffer with fixed length, containing any data +* 'time': time value + +==== weechat_infolist_new + +Create a new infolist. + +Prototype: + +[source,C] +---- +struct t_infolist *weechat_infolist_new (); +---- + +Return value: + +* pointer to new infolist + +C example: + +[source,C] +---- +struct t_infolist *infolist = weechat_infolist_new (); +---- + +Script (Python): + +[source,python] +---- +# prototype +infolist = weechat.infolist_new() + +# example +infolist = weechat.infolist_new() +---- + +==== weechat_infolist_new_item + +Add an item in an infolist. + +Prototype: + +[source,C] +---- +struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist); +---- + +Arguments: + +* 'infolist': infolist pointer + +Return value: + +* pointer to new item + +C example: + +[source,C] +---- +struct t_infolist_item *item = weechat_infolist_new_item (infolist); +---- + +Script (Python): + +[source,python] +---- +# prototype +item = weechat.infolist_new_item(infolist) + +# example +item = weechat.infolist_new_item(infolist) +---- + +==== weechat_infolist_new_var_integer + +Add an integer variable to an infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_infolist_var *var = weechat_infolist_new_var_integer (item, + "my_integer", + 123); +---- + +Script (Python): + +[source,python] +---- +# prototype +var = weechat.infolist_new_var_integer(item, name, value) + +# example +var = weechat.infolist_new_var_integer(item, "my_integer", 123) +---- + +==== weechat_infolist_new_var_string + +Add a string variable to an infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_infolist_var *var = weechat_infolist_new_var_string (item, + "my_string", + "value"); +---- + +Script (Python): + +[source,python] +---- +# prototype +var = weechat.infolist_new_var_string(item, name, value) + +# example +var = weechat.infolist_new_var_string(item, "my_string", "value") +---- + +==== weechat_infolist_new_var_pointer + +Add a pointer variable to an infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_infolist_var *var = weechat_infolist_new_var_pointer (item, + "my_pointer", + &pointer); +---- + +Script (Python): + +[source,python] +---- +# prototype +var = weechat.infolist_new_var_pointer(item, name, pointer) + +# example +var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer) +---- + +==== weechat_infolist_new_var_buffer + +Add a buffer variable to an infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +char buffer[256]; +/* ... */ +struct t_infolist_var *var = weechat_infolist_new_var_buffer (item, + "my_buffer", + &buffer, + sizeof (buffer)); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_infolist_new_var_time + +Add a time variable to an infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_infolist_var *var = weechat_infolist_new_var_time (item, + "my_time", + time (NULL)); +---- + +Script (Python): + +[source,python] +---- +# prototype +var = weechat.infolist_new_var_time(item, name, time) + +# example +var = weechat.infolist_new_var_time(item, "my_time", int(time.time())) +---- + +==== weechat_infolist_get + +Return infolist from WeeChat or a plugin. + +[IMPORTANT] +Content of infolist is a duplication of actual data. So if you are asking +infolist with lot of data (like "buffer_lines"), WeeChat will allocate memory +to duplicate all data, and this can take some time. + +Instead of using big infolist, it is preferable to use hdata (but infolist may +have more info than hdata, which is raw data), see <<hdata,hdata>>. + +Prototype: + +[source,C] +---- +struct t_infolist *weechat_infolist_get (const char *infolist_name, + void *pointer, + const char *arguments); +---- + +Arguments: + +* 'infolist_name': name of infolist to read (see table below) +* 'pointer': pointer to an item, to get only this item in infolist (optional, + can be NULL) +* 'arguments': arguments for infolist asked (optional, NULL if no argument is + needed) + +Return value: + +* pointer to infolist, NULL if an error occurred + +Infolists: + +include::autogen/plugin_api/infolists.asciidoc[] + +C example: + +[source,C] +---- +struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL); +---- + +Script (Python): + +[source,python] +---- +# prototype +infolist = weechat.infolist_get(infolist_name, pointer, arguments) + +# example +infolist = weechat.infolist_get("irc_server", "", "") +---- + +==== weechat_infolist_next + +Move "cursor" to next item in an infolist. The first call to this function for +an infolist moves cursor to first item in infolist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_infolist_next (infolist)) +{ + /* read variables in item... */ +} +else +{ + /* no more item available */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.infolist_next(infolist) + +# example +rc = weechat.infolist_next(infolist) +if rc: + # read variables in item... +else: + # no more item available +---- + +==== weechat_infolist_prev + +Move "cursor" to previous item in an infolist. The first call to this function +for an infolist moves cursor to last item in infolist. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +if (weechat_infolist_prev (infolist)) +{ + /* read variables in item... */ +} +else +{ + /* no more item available */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.infolist_prev(infolist) + +# example +rc = weechat.infolist_prev(infolist) +if rc: + # read variables in item... +else: + # no more item available +---- + +==== weechat_infolist_reset_item_cursor + +Reset "cursor" for infolist. + +Prototype: + +[source,C] +---- +void weechat_infolist_reset_item_cursor (struct t_infolist *infolist); +---- + +Arguments: + +* 'infolist': infolist pointer + +C example: + +[source,C] +---- +weechat_infolist_reset_item_cursor (infolist); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.infolist_reset_item_cursor(infolist) + +# example +weechat.infolist_reset_item_cursor(infolist) +---- + +==== weechat_infolist_search_var + +_WeeChat ≥ 0.4.3._ + +Search a variable in the current infolist item. + +Prototype: + +[source,C] +---- +struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist, + const char *name); +---- + +Arguments: + +* 'infolist': infolist pointer +* 'name': variable name + +Return value: + +* pointer to variable found, NULL if the variable was not found + +C example: + +[source,C] +---- +if (weechat_infolist_search_var (infolist, "name")) +{ + /* variable "name" exists */ + /* ... */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +var = weechat.infolist_search_var(infolist, name) + +# example +if weechat.infolist_search_var(infolist, "name"): + # variable "name" exists + # ... +---- + +==== weechat_infolist_fields + +Return list of fields for current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +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): + +[source,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" +---- + +==== weechat_infolist_integer + +Return value of integer variable in current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, "integer = %d", + weechat_infolist_integer (infolist, "my_integer")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.infolist_integer(infolist, var) + +# example +weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer")) +---- + +==== weechat_infolist_string + +Return value of string variable in current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, "string = %s", + weechat_infolist_string (infolist, "my_string")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.infolist_string(infolist, var) + +# example +weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string")) +---- + +==== weechat_infolist_pointer + +Return value of pointer variable in current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, "pointer = 0x%lx", + weechat_infolist_pointer (infolist, "my_pointer")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.infolist_pointer(infolist, var) + +# example +weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer")) +---- + +==== weechat_infolist_buffer + +Return value of buffer variable in current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +int size; +void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size); +weechat_printf (NULL, "buffer = 0x%lx, size = %d", + pointer, size); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_infolist_time + +Return value of time variable in current infolist item. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +weechat_printf (NULL, "time = %ld", + weechat_infolist_time (infolist, "my_time")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.infolist_time(infolist, var) + +# example +weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time")) +---- + +==== weechat_infolist_free + +Free an infolist. + +Prototype: + +[source,C] +---- +void weechat_infolist_free (struct t_infolist *infolist); +---- + +Arguments: + +* 'infolist': infolist pointer + +C example: + +[source,C] +---- +weechat_infolist_free (infolist); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.infolist_free(infolist) + +# example +weechat.infolist_free(infolist) +---- + +[[hdata]] +=== Hdata + +Functions for hdata (raw access to WeeChat or plugins data). + +[IMPORTANT] +Hdata provides read-only access to data. It is *STRICTLY FORBIDDEN* to write +something in memory pointed by hdata variables. + +The only way to update data is to call function +<<_weechat_hdata_update,weechat_hdata_update>>. + +==== weechat_hdata_new + +_WeeChat ≥ 0.3.6, updated in 0.3.9 and 0.4.0._ + +Create a new hdata. + +[NOTE] +.hdata vs infolist +==== +Hdata is a fast way to read WeeChat or plugins data. It is similar to +infolist, but there are some differences: + +* it is faster and uses less memory: direct read of data without duplication +* it may have different info than infolist: it contains only raw data in + structures (infolist may add some extra data for convenience) +==== + +Prototype: + +[source,C] +---- +struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next, + int create_allowed, int delete_allowed, + int (*callback_update)(void *data, + struct t_hdata *hdata, + void *pointer, + struct t_hashtable *hashtable), + void *callback_update_data); +---- + +Arguments: + +* 'hdata_name': name of hdata +* 'var_prev': name of variable in structure which is a pointer to previous + element in list (may be NULL if no such variable is available) +* 'var_next': name of variable in structure which is a pointer to next + element in list (may be NULL if no such variable is available) +* 'create_allowed': 1 if create of structure is allowed, otherwise 0 + _(WeeChat ≥ 0.4.0)_ +* 'delete_allowed': 1 if delete of structure is allowed, otherwise 0 + _(WeeChat ≥ 0.3.9)_ +* 'callback_update': callback to update data in hdata, can be NULL if no update + is allowed _(WeeChat ≥ 0.3.9)_, arguments and return value: +** 'void *data': pointer +** 'struct t_hdata *hdata': pointer to hdata +** 'struct t_hashtable *hashtable': hashtable with variables to update + (see <<_weechat_hdata_update,weechat_hdata_update>>) +** return value: number of variables updated +* 'callback_update_data': pointer given to update callback when it is called by + WeeChat _(WeeChat ≥ 0.3.9)_ + +Return value: + +* pointer to new hdata + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_new_var + +_WeeChat ≥ 0.3.6, updated in 0.3.9._ + +Create a new variable in hdata. + +Prototype: + +[source,C] +---- +void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type, + int update_allowed, const char *array_size, const char *hdata_name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name +* 'offset': offset of variable in structure +* 'type': variable type, one of: +** WEECHAT_HDATA_CHAR +** WEECHAT_HDATA_INTEGER +** WEECHAT_HDATA_LONG +** WEECHAT_HDATA_STRING +** WEECHAT_HDATA_SHARED_STRING +** WEECHAT_HDATA_POINTER +** WEECHAT_HDATA_TIME +** WEECHAT_HDATA_HASHTABLE +** WEECHAT_HDATA_OTHER +* 'update_allowed': 1 if update of variable is allowed, otherwise 0 + _(WeeChat ≥ 0.3.9)_ +* 'array_size': not NULL only if a variable is an array, and it can be: + _(WeeChat ≥ 0.3.9)_ +** name of variable in hdata: this variable will be used as size of array + (dynamic size for array) +** integer (as string): fixed size for array +** '*': automatic size: the size of array is computed by looking at values, when + the first NULL is found (only for type string, pointer or hashtable) +* 'hdata_name': name of a hdata (if it's a pointer to a structure with hdata) + +C example: + +[source,C] +---- +struct t_myplugin_list +{ + char *name; + struct t_gui_buffer *buffer; + int tags_count; + char **tags_array; + char **string_split; + struct t_myplugin_list *prev; + struct t_myplugin_list *next; +}; + +/* ... */ + +struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next"); +weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL); +weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL); +weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL); +weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "tags_count", NULL); +weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*", NULL); +weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list"); +weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list"); +---- + +The macro "WEECHAT_HDATA_VAR" can be used to shorten code: + +[source,C] +---- +WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL); +WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL); +WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL); +WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "tags_count", NULL); +WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*", NULL); +WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list"); +WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_new_list + +_WeeChat ≥ 0.3.6, updated in 1.0._ + +Create a new list pointer in hdata. + +Prototype: + +[source,C] +---- +void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name +* 'pointer': list pointer +* 'flags': combination of following values: _(WeeChat ≥ 1.0)_ +** 'WEECHAT_HDATA_LIST_CHECK_POINTERS': list used to check pointers + +C example: + +[source,C] +---- +struct t_myplugin_list +{ + char *name; + struct t_gui_buffer *buffer; + int tags_count; + char **tags_array; + char **string_split; + struct t_myplugin_list *prev; + struct t_myplugin_list *next; +}; + +/* ... */ + +struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next"); +weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL); +weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL); +weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL); +weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL); +weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL); +weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list"); +weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list"); + +weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS); +weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0); +---- + +The macro "WEECHAT_HDATA_LIST" can be used to shorten code: + +[source,C] +---- +WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS); +WEECHAT_HDATA_LIST(last_buffer, 0); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_get + +_WeeChat ≥ 0.3.6._ + +Return hdata for a WeeChat or plugin structure. + +[NOTE] +Hdata does not contain data, it's only a hashtable with position of variables +in structure. That means you will need this hdata and a pointer to a +WeeChat/plugin object to read some data. + +Prototype: + +[source,C] +---- +struct t_hdata *weechat_hdata_get (const char *hdata_name); +---- + +Arguments: + +* 'hdata_name': name of hdata (see list below) + +Return value: + +* pointer to hdata, NULL if an error occurred + +List of hdata: + +include::autogen/plugin_api/hdata.asciidoc[] + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("irc_server"); +---- + +Script (Python): + +[source,python] +---- +# prototype +hdata = weechat.hdata_get(hdata_name) + +# example +hdata = weechat.hdata_get("irc_server") +---- + +==== weechat_hdata_get_var_offset + +_WeeChat ≥ 0.3.6._ + +Return offset of variable in hdata. + +Prototype: + +[source,C] +---- +int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name + +Return value: + +* variable offset, 0 if an error occurred + +C example: + +[source,C] +---- +int offset = weechat_hdata_get_var_offset (hdata, "name"); +---- + +Script (Python): + +[source,python] +---- +# prototype +offset = weechat.hdata_get_var_offset(hdata, name) + +# example +offset = weechat.hdata_get_var_offset(hdata, "name") +---- + +==== weechat_hdata_get_var_type + +_WeeChat ≥ 0.3.6._ + +Return type of variable in hdata (as integer). + +Prototype: + +[source,C] +---- +int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name + +Return value: + +* variable type, -1 if an error occurred + +C example: + +[source,C] +---- +int type = weechat_hdata_get_var_type (hdata, "name"); +switch (type) +{ + case WEECHAT_HDATA_CHAR: + /* ... */ + break; + case WEECHAT_HDATA_INTEGER: + /* ... */ + break; + case WEECHAT_HDATA_LONG: + /* ... */ + break; + case WEECHAT_HDATA_STRING: + /* ... */ + break; + case WEECHAT_HDATA_SHARED_STRING: + /* ... */ + break; + case WEECHAT_HDATA_POINTER: + /* ... */ + break; + case WEECHAT_HDATA_TIME: + /* ... */ + break; + case WEECHAT_HDATA_HASHTABLE: + /* ... */ + break; + case WEECHAT_HDATA_OTHER: + /* ... */ + break; + default: + /* variable not found */ + break; +} +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_get_var_type_string + +_WeeChat ≥ 0.3.6._ + +Return type of variable in hdata (as string). + +Prototype: + +[source,C] +---- +const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name + +Return value: + +* variable type, NULL if an error occurred + +C example: + +[source,C] +---- +weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name")); +---- + +Script (Python): + +[source,python] +---- +# prototype +type = weechat.hdata_get_var_type_string(hdata, name) + +# example +weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name")) +---- + +==== weechat_hdata_get_var_array_size + +_WeeChat ≥ 0.3.9._ + +Return array size for variable in hdata. + +Prototype: + +[source,C] +---- +int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name + +Return value: + +* array size for variable, -1 if variable is not an array or if an error occurred + +C example: + +[source,C] +---- +int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name"); +---- + +Script (Python): + +[source,python] +---- +# prototype +array_size = weechat.hdata_get_var_array_size(hdata, pointer, name) + +# example +array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name") +---- + +==== weechat_hdata_get_var_array_size_string + +_WeeChat ≥ 0.3.9._ + +Return array size for variable in hdata (as string). + +Prototype: + +[source,C] +---- +const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer, + const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name + +Return value: + +* array size for variable as string, NULL if variable is not an array or if an + error occurred + +C example: + +[source,C] +---- +const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name"); +---- + +Script (Python): + +[source,python] +---- +# prototype +array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, name) + +# example +array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name") +---- + +==== weechat_hdata_get_var_hdata + +_WeeChat ≥ 0.3.6._ + +Return hdata for a variable in hdata. + +Prototype: + +[source,C] +---- +const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': variable name + +Return value: + +* hdata for variable, NULL if no hdata or if an error occurred + +C example: + +[source,C] +---- +weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name")); +---- + +Script (Python): + +[source,python] +---- +# prototype +hdata_name = weechat.hdata_get_var_hdata(hdata, name) + +# example +weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name")) +---- + +==== weechat_hdata_get_var + +_WeeChat ≥ 0.3.6._ + +Return pointer to content of variable in hdata. + +Prototype: + +[source,C] +---- +void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name + +Return value: + +* pointer to content of variable, NULL if an error occurred + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +void *pointer = weechat_hdata_get_var (hdata, buffer, "name"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_get_var_at_offset + +_WeeChat ≥ 0.3.6._ + +Return pointer to content of variable in hdata, using offset. + +Prototype: + +[source,C] +---- +void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'offset': offset of variable + +Return value: + +* pointer to content of variable, NULL if an error occurred + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +int offset = weechat_hdata_get_var_offset (hdata, "name"); +void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_get_list + +_WeeChat ≥ 0.3.6._ + +Return list pointer from hdata. + +Prototype: + +[source,C] +---- +void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'name': list name + +Return value: + +* list pointer, NULL if an error occurred + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers"); +---- + +Script (Python): + +[source,python] +---- +# prototype +list = weechat.hdata_get_list(hdata, name) + +# example +hdata = weechat.hdata_get("buffer") +buffers = weechat.hdata_get_list(hdata, "gui_buffers") +---- + +==== weechat_hdata_check_pointer + +_WeeChat ≥ 0.3.7, updated in 1.0._ + +Check if a pointer is valid for a hdata and a list pointer. + +Prototype: + +[source,C] +---- +int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'list': list pointer; if NULL _(WeeChat ≥ 1.0)_, the pointer is checked with + the lists in hdata that have flag "check pointers" (see + <<_weechat_hdata_new_list,weechat_hdata_new_list>>), and if no such list + exists, the pointer is considered as valid +* 'pointer': pointer to check + +Return value: + +* 1 if pointer is in list, 0 if not found + +C example: + +[source,C] +---- +/* check if a buffer pointer is valid */ +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +if (weechat_hdata_check_pointer (hdata, + weechat_hdata_get_list (hdata, "gui_buffers"), + ptr_buffer)) +{ + /* valid pointer */ +} +else +{ + /* invalid pointer */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.hdata_check_pointer(hdata, list, pointer) + +# example +hdata = weechat.hdata_get("buffer") +if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer): + # valid pointer + # ... +else: + # invalid pointer + # ... +---- + +==== weechat_hdata_move + +_WeeChat ≥ 0.3.6._ + +Move pointer to another element in list. + +Prototype: + +[source,C] +---- +void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to a WeeChat/plugin object +* 'count': number of jump(s) to execute (negative or positive integer, different + from 0) + +Return value: + +* pointer to element reached, NULL if an error occurred + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); + +/* move to next buffer, 2 times */ +buffer = weechat_hdata_move (hdata, buffer, 2); + +/* move to previous buffer */ +if (buffer) + buffer = weechat_hdata_move (hdata, buffer, -1); +---- + +Script (Python): + +[source,python] +---- +# prototype +pointer = weechat.hdata_move(hdata, pointer, count) + +# example +hdata = weechat.hdata_get("buffer") +buffer = weechat.buffer_search_main() + +# move to next buffer, 2 times +buffer = weechat.hdata_move(hdata, buffer, 2) + +# move to previous buffer +if buffer: + buffer = weechat.hdata_move(hdata, buffer, -1) +---- + +==== weechat_hdata_search + +_WeeChat ≥ 0.4.1._ + +Search element in a list: the expression 'search' is evaluated for each element +in list, until element is found (or end of list). + +Prototype: + +[source,C] +---- +void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, int move); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to a WeeChat/plugin object +* 'search': expression to evaluate, default pointer in expression is the name of + hdata (and this pointer changes for each element in list); for help on + expression, see command `/eval` in 'WeeChat User's guide' +* 'move': number of jump(s) to execute after unsuccessful search (negative or + positive integer, different from 0) + +Return value: + +* pointer to element found, NULL if not found + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("irc_server"); +void *servers = weechat_hdata_get (hdata, "irc_servers"); + +/* search irc server with name "freenode" */ +void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == freenode", 1); +if (server) +{ + /* ... */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +pointer = weechat.hdata_search(hdata, pointer, search, count) + +# example +hdata = weechat.hdata_get("irc_server") +servers = weechat.hdata_get_list(hdata, "irc_servers") + +# search irc server with name "freenode" +server = weechat.hdata_search(hdata, servers, "${irc_server.name} == freenode", 1) +if server: + # ... +---- + +==== weechat_hdata_char + +_WeeChat ≥ 0.3.7._ + +Return value of char variable in structure using hdata. + +Prototype: + +[source,C] +---- +char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "char"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* char value of variable + +C example: + +[source,C] +---- +weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_char(hdata, pointer, name) + +# example +weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter")) +---- + +==== weechat_hdata_integer + +_WeeChat ≥ 0.3.6._ + +Return value of integer variable in structure using hdata. + +Prototype: + +[source,C] +---- +int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "integer"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* integer value of variable + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_integer(hdata, pointer, name) + +# example +hdata = weechat.hdata_get("buffer") +buffer = weechat.buffer_search_main() +weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number")) +---- + +==== weechat_hdata_long + +_WeeChat ≥ 0.3.6._ + +Return value of long variable in structure using hdata. + +Prototype: + +[source,C] +---- +long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "long"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* long value of variable + +C example: + +[source,C] +---- +weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_long(hdata, pointer, name) + +# example +weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar")) +---- + +==== weechat_hdata_string + +_WeeChat ≥ 0.3.6._ + +Return value of string variable in structure using hdata. + +Prototype: + +[source,C] +---- +const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "string"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* string value of variable + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_string(hdata, pointer, name) + +# example +hdata = weechat.hdata_get("buffer") +buffer = weechat.buffer_search_main() +weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name")) +---- + +==== weechat_hdata_pointer + +_WeeChat ≥ 0.3.6._ + +Return value of pointer variable in structure using hdata. + +Prototype: + +[source,C] +---- +void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "pointer"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* pointer value of variable + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_pointer(hdata, pointer, name) + +# example +hdata = weechat.hdata_get("buffer") +buffer = weechat.buffer_search_main() +weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines")) +---- + +==== weechat_hdata_time + +_WeeChat ≥ 0.3.6._ + +Return value of time variable in structure using hdata. + +Prototype: + +[source,C] +---- +time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "time"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* time value of variable + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *ptr = weechat_buffer_search_main (); +ptr = weechat_hdata_pointer (hdata, ptr, "lines"); +if (ptr) +{ + hdata = weechat_hdata_get ("lines"); + ptr = weechat_hdata_pointer (hdata, ptr, "first_line"); + if (ptr) + { + hdata = weechat_hdata_get ("line"); + ptr = weechat_hdata_pointer (hdata, ptr, "data"); + if (ptr) + { + hdata = weechat_hdata_get ("line_data"); + time_t date = weechat_hdata_time (hdata, hdata, "date"); + weechat_printf (NULL, "time of last line displayed = %s", ctime (&date)); + } + } +} +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_time(hdata, pointer, name) + +# example +buf = weechat.buffer_search_main() +ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines") +if ptr: + ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line") + if ptr: + ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data") + if ptr: + date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date") + weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date)))) +---- + +==== weechat_hdata_hashtable + +_WeeChat ≥ 0.3.7._ + +Return value of hashtable variable in structure using hdata. + +Prototype: + +[source,C] +---- +struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (must be type "hashtable"); for arrays, the name can be + "N|name" where N is the index in array (starting at 0), for example: "2|name" + +Return value: + +* hashtable value of variable (pointer to hashtable) + +C example: + +[source,C] +---- +struct t_hdata *hdata = weechat_hdata_get ("buffer"); +struct t_gui_buffer *buffer = weechat_buffer_search_main (); +struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables"); +weechat_printf (NULL, "%d local variables in core buffer", + weechat_hashtable_get_integer (hashtable, "items_count")); +---- + +Script (Python): + +[source,python] +---- +# prototype +hashtable = weechat.hdata_hashtable(hdata, pointer, name) + +# example +hdata = weechat.hdata_get("buffer") +buffer = weechat.buffer_search_main() +hash = weechat.hdata_hashtable(hdata, buffer, "local_variables") +weechat.prnt("", "local variables in core buffer:") +for key in hash: + weechat.prnt("", " %s == %s" % (key, hash[key])) +---- + +==== weechat_hdata_set + +_WeeChat ≥ 0.3.9._ + +Set new value for variable in a hdata. + +[NOTE] +This function can be called only in an update callback +(see <<_weechat_hdata_new,weechat_hdata_new>> and +<<_weechat_hdata_update,weechat_hdata_update>>), if the variable can be updated. + +Prototype: + +[source,C] +---- +int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'name': variable name (types allowed: char, integer, long, string, pointer, + time) +* 'value': new value for variable + +Return value: + +* 1 if OK, 0 if error + +C example: + +[source,C] +---- +weechat_hdata_set (hdata, pointer, "message", "test"); +---- + +[NOTE] +This function is not available in scripting API. + +==== weechat_hdata_update + +_WeeChat ≥ 0.3.9._ + +Update data in a hdata. + +Prototype: + +[source,C] +---- +int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'pointer': pointer to WeeChat/plugin object +* 'hashtable': variables to update: keys are name of variables, values are new + values for variables (keys and values are string), some special keys are + allowed: +** key `__create_allowed` (with any value): return 1 if create is allowed for + structure, otherwise 0 _(WeeChat ≥ 0.4.0)_ +** key `__delete_allowed` (with any value): return 1 if delete is allowed for + structure, otherwise 0 +** key `__update_allowed`, value is name of a variable: return 1 if update is + allowed for this variable, otherwise 0 +** key `__delete` (with any value): delete structure (if allowed) + +Return value: + +* number of variables updated + +C example: + +[source,C] +---- +/* subtract one hour on last message displayed in current buffer */ + +struct t_gui_lines *own_lines; +struct t_gui_line *line; +struct t_gui_line_data *line_data; +struct t_hdata *hdata; +struct t_hashtable *hashtable; +char str_date[64]; + +own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines"); +if (own_lines) +{ + line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line"); + if (line) + { + line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data"); + hdata = weechat_hdata_get ("line_data"); + hashtable = weechat_hashtable_new (8, + WEECHAT_HASHTABLE_STRING, + WEECHAT_HASHTABLE_STRING, + NULL, + NULL); + if (hashtable) + { + snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600); + weechat_hashtable_set (hashtable, "date", str_date); + weechat_hdata_update (hdata, line_data, hashtable); + weechat_hashtable_free (hashtable); + } + } +} +---- + +Script (Python): + +[source,python] +---- +# prototype +count = weechat.hdata_update(hdata, pointer, hashtable) + +# example: subtract one hour on last message displayed in current buffer +own_lines = weechat.hdata_pointer(weechat.hdata_get('buffer'), weechat.current_buffer(), 'own_lines') +if own_lines: + line = weechat.hdata_pointer(weechat.hdata_get('lines'), own_lines, 'last_line') + if line: + line_data = weechat.hdata_pointer(weechat.hdata_get('line'), line, 'data') + hdata = weechat.hdata_get('line_data') + weechat.hdata_update(hdata, line_data, { 'date': str(weechat.hdata_time(hdata, line_data, 'date') - 3600) }) +---- + +==== weechat_hdata_get_string + +_WeeChat ≥ 0.3.6._ + +Return string value of a hdata property. + +Prototype: + +[source,C] +---- +const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property); +---- + +Arguments: + +* 'hdata': hdata pointer +* 'property': property name: +** 'var_keys': string with list of keys for variables in hdata + (format: "key1,key2,key3") +** 'var_values': string with list of values for variables in hdata + (format: "value1,value2,value3") +** 'var_keys_values': string with list of keys and values for variables in hdata + (format: "key1:value1,key2:value2,key3:value3") +** 'var_prev': name of variable in structure which is a pointer to previous + element in list +** 'var_next': name of variable in structure which is a pointer to next + element in list +** 'list_keys': string with list of keys for lists in hdata + (format: "key1,key2,key3") +** 'list_values': string with list of values for lists in hdata + (format: "value1,value2,value3") +** 'list_keys_values': string with list of keys and values for lists in hdata + (format: "key1:value1,key2:value2,key3:value3") + +Return value: + +* string value of property + +C example: + +[source,C] +---- +weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys")); +weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys")); +---- + +Script (Python): + +[source,python] +---- +# prototype +value = weechat.hdata_get_string(hdata, property) + +# example +weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys")) +weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys")) +---- + +[[upgrade]] +=== Upgrade + +Functions for upgrading WeeChat (command "/upgrade"). + +==== weechat_upgrade_new + +Create or read a file for upgrade. + +Prototype: + +[source,C] +---- +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: + +[source,C] +---- +struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1); +---- + +Script (Python): + +[source,python] +---- +# prototype +upgrade_file = weechat.upgrade_new(filename, write) + +# example +upgrade_file = weechat.upgrade_new("my_file", 1) +---- + +==== weechat_upgrade_write_object + +Write an object in upgrade file. + +Prototype: + +[source,C] +---- +int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file, + int object_id, + struct t_infolist *infolist); +---- + +Arguments: + +* 'upgrade_file': upgrade file pointer +* 'object_id': id for object +* 'infolist': infolist to write in file + +Return value: + +* 1 if OK, 0 if error + +C example: + +[source,C] +---- +if (weechat_upgrade_write_object (upgrade_file, 1, &infolist)) +{ + /* OK */ +} +else +{ + /* error */ +} +---- + +Script (Python): + +[source,python] +---- +# prototype +rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist) + +# example +weechat.upgrade_write_object(upgrade_file, 1, infolist) +---- + +==== weechat_upgrade_read + +Read an upgrade file. + +Prototype: + +[source,C] +---- +int 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, + arguments and return value: +** 'void *data': pointer +** 'struct t_upgrade_file *upgrade_file': pointer to upgrade file +** 'int object_id': object id +** 'struct t_infolist *infolist': infolist with content of object +** return value: +*** 'WEECHAT_RC_OK' +*** 'WEECHAT_RC_ERROR' +* 'callback_read_data': pointer given to read callback when it is called by + WeeChat + +Return value: + +* 1 if OK, 0 if error + +C example: + +[source,C] +---- +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): + +[source,python] +---- +# prototype +rc = 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", "")) +---- + +==== weechat_upgrade_close + +Close an upgrade file. + +Prototype: + +[source,C] +---- +void weechat_upgrade_close (struct t_upgrade_file *upgrade_file); +---- + +Arguments: + +* 'upgrade_file': upgrade file pointer + +C example: + +[source,C] +---- +weechat_upgrade_close (upgrade_file); +---- + +Script (Python): + +[source,python] +---- +# prototype +weechat.upgrade_close(upgrade_file) + +# example +weechat.upgrade_close(upgrade_file) +---- |