= WeeChat plugin API reference :author: Sébastien Helleu :email: flashcode@flashtux.org :lang: en :toc: left :toclevels: 4 :sectnums: :sectnumlevels: 3 :docinfo1: This manual documents WeeChat chat client, it is part of WeeChat. Latest version of this document can be found on https://weechat.org/doc/[this page ^↗^,window=_blank]. [[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. In order to call WeeChat functions in the format displayed in <>, the following global pointer must be declared and initialized in the function <<_weechat_plugin_init,weechat_plugin_init>>: [source,c] ---- struct t_weechat_plugin *weechat_plugin; ---- [[macros]] === Macros The plugin must use some macros (to define some variables): WEECHAT_PLUGIN_NAME("name"):: the plugin name WEECHAT_PLUGIN_DESCRIPTION("description"):: a short description of plugin WEECHAT_PLUGIN_AUTHOR("author"):: the author name WEECHAT_PLUGIN_VERSION("1.0"):: the plugin version WEECHAT_PLUGIN_LICENSE("GPL3"):: the plugin license WEECHAT_PLUGIN_PRIORITY(1000):: the plugin priority (optional, see below) [[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, used to initialize the convenience global pointer `+weechat_plugin+` * _argc_: number of arguments for plugin * _argv_: arguments for plugin (see below) Return value: * _WEECHAT_RC_OK_ if successful (plugin will be loaded) * _WEECHAT_RC_ERROR_ if error (plugin will NOT be loaded) [[plugin_arguments]] ===== Plugin arguments When the plugin is loaded by WeeChat, it receives the list of arguments in parameter `argv` and the number of arguments in `argc`. The arguments can be: * command line arguments when running the WeeChat binary, * arguments given to the command `/plugin load xxx`, when the plugin is manually loaded by the user. When the arguments come from the command line, only these arguments are sent to the plugin: *-a*, *--no-connect*:: Disable auto-connect to servers when WeeChat is starting. *-s*, *--no-script*:: Disable scripts auto-load. *plugin:option*:: Option for a plugin: only the plugin-related options are sent, for example only the options starting with `irc:` are sent to the plugin called "irc". [[plugin_priority]] ===== Plugin priority When plugins are auto-loaded (for example on startup), WeeChat first loads all plugins, and then calls the _init_ functions, using the priority defined in each plugin. A high priority means that the _init_ function is called first. Default priority is 1000 (with such priority, the plugin is loaded after all default plugins). The default WeeChat plugins are initialized in this order: include::includes/autogen_api_plugins_priority.en.adoc[tag=plugins_priority] ==== 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 toto.so toto.o ---- [[load_plugin]] === Load plugin Copy file _toto.so_ into system plugins directory (for example _/usr/local/lib/weechat/plugins_) or into user's plugins directory (for example _/home/user/.local/share/weechat/plugins_). Under WeeChat: ---- /plugin load toto ---- [[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 #include "weechat-plugin.h" WEECHAT_PLUGIN_NAME("double"); WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); WEECHAT_PLUGIN_AUTHOR("Sébastien Helleu "); WEECHAT_PLUGIN_VERSION("0.1"); WEECHAT_PLUGIN_LICENSE("GPL3"); struct t_weechat_plugin *weechat_plugin = NULL; /* callback for command "/double" */ int command_double_cb (const void *pointer, void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* make C compiler happy */ (void) pointer; (void) data; (void) buffer; (void) argv; if (argc > 1) { weechat_command (NULL, argv_eol[1]); weechat_command (NULL, argv_eol[1]); } return WEECHAT_RC_OK; } int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]) { weechat_plugin = plugin; weechat_hook_command ("double", "Display two times a message " "or execute two times a command", "message | command", "message: message to display two times\n" "command: command to execute two times", NULL, &command_double_cb, NULL, NULL); return WEECHAT_RC_OK; } int weechat_plugin_end (struct t_weechat_plugin *plugin) { /* make C compiler happy */ (void) plugin; return WEECHAT_RC_OK; } ---- [[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). [[registering]] === Registering Functions to register a script: used only by scripting API, not the C API. ==== register Register the script. For more information, see the link:weechat_scripting.en.html#register_function[WeeChat scripting guide ^↗^,window=_blank]. Script (Python): [source,python] ---- # prototype def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ... ---- [NOTE] This function is not available in the C API. [[plugins]] === Plugins Functions to get infos about plugins. ==== 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 def plugin_get_name(plugin: str) -> str: ... # 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. ==== 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 def charset_set(charset: str) -> int: ... # example weechat.charset_set("iso-8859-1") ---- ==== iconv_to_internal Convert string to WeeChat internal charset (UTF-8). Prototype: [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 def iconv_to_internal(charset: str, string: str) -> str: ... # example str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à") ---- ==== iconv_from_internal Convert string from internal WeeChat charset (UTF-8) to another. Prototype: [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 def iconv_from_internal(charset: str, string: str) -> str: ... # example str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à") ---- ==== gettext Return translated string (depends on local language). Prototype: [source,c] ---- const char *weechat_gettext (const char *string); ---- Arguments: * _string_: string to translate Return value: * translated string or _string_ if there is no translation available in local language C example: [source,c] ---- char *str = weechat_gettext ("hello"); ---- Script (Python): [source,python] ---- # prototype def gettext(string: str) -> str: ... # example str = weechat.gettext("hello") ---- ==== ngettext Return translated string, using single or plural form, according to _count_ argument. Prototype: [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 or _string_ / _plural_ if there is no translation available in local language C example: [source,c] ---- char *str = weechat_ngettext ("file", "files", num_files); ---- Script (Python): [source,python] ---- # prototype def ngettext(string: str, plural: str, count: int) -> str: ... # example num_files = 2 str = weechat.ngettext("file", "files", num_files) ---- ==== strndup Return duplicated string, with a max number of bytes. Prototype: [source,c] ---- char *weechat_strndup (const char *string, int bytes); ---- Arguments: * _string_: string to duplicate * _bytes_: max bytes to duplicate Return value: * duplicated string (must be freed by calling "free" after use) C example: [source,c] ---- char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */ /* ... */ free (str); ---- [NOTE] This function is not available in scripting API. ==== string_cut _WeeChat ≥ 3.3._ Cut a string after a given number of chars, add an optional suffix after the string if it is cut. Prototype: [source,c] ---- char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix); ---- Arguments: * _string_: string to cut * _length_: max chars * _count_suffix_: if 1, the length of suffix is counter in the max length * _screen_: if 1, the cut is based on width of chars displayed * _cut_suffix_: the suffix added after the string if it is cut Return value: * cut string (must be freed by calling "free" after use) C example: [source,c] ---- char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…"); /* result: "this…" */ /* ... */ free (str); ---- [NOTE] This function is not available in scripting API. ==== string_tolower 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. ==== 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. ==== strcasecmp _Updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 if string1 > string2 C example: [source,c] ---- int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ ---- [NOTE] This function is not available in scripting API. ==== strcasecmp_range _WeeChat ≥ 0.3.7, updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 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. ==== strncasecmp _Updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 if string1 > string2 C example: [source,c] ---- int diff = weechat_strncasecmp ("aabb", "aacc", 2); /* == 0 */ ---- [NOTE] This function is not available in scripting API. ==== strncasecmp_range _WeeChat ≥ 0.3.7, updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 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. ==== strcmp_ignore_chars _Updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 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. ==== strcasestr _Updated in 1.3._ Locale and case independent string search. Prototype: [source,c] ---- const char *weechat_strcasestr (const char *string, const char *search); ---- Arguments: * _string_: string * _search_: string to search in _string_ Return value: * pointer to string found, or NULL if not found (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_) C example: [source,c] ---- const char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */ ---- [NOTE] This function is not available in scripting API. ==== strlen_screen _WeeChat ≥ 0.4.2._ 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 <<_utf8_strlen_screen,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 def strlen_screen(string: str) -> int: ... # example length = weechat.strlen_screen("é") # 1 ---- ==== 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 def string_match(string: str, mask: str, case_sensitive: int) -> int: ... # examples match1 = weechat.string_match("abcdef", "abc*", 0) # == 1 match2 = weechat.string_match("abcdef", "*dd*", 0) # == 0 match3 = weechat.string_match("abcdef", "*def", 0) # == 1 match4 = weechat.string_match("abcdef", "*de*", 0) # == 1 match5 = weechat.string_match("abcdef", "*b*d*", 0) # == 1 ---- ==== string_match_list _WeeChat ≥ 2.5._ Check if a string matches a list of masks where negative mask is allowed with the format "!word". A negative mask has higher priority than a standard mask. Prototype: [source,c] ---- int weechat_string_match_list (const char *string, const char **masks, int case_sensitive); ---- Arguments: * _string_: string * _masks_: list of masks, with a NULL after the last mask in list; each mask is compared to the string with the function <<_string_match,string_match>> * _case_sensitive_: 1 for case sensitive comparison, otherwise 0 Return value: * 1 if string matches list of masks (at least one mask matches and no negative mask matches), otherwise 0 C example: [source,c] ---- const char *masks[3] = { "*", "!abc*", NULL }; int match1 = weechat_string_match_list ("abc", masks, 0); /* == 0 */ int match2 = weechat_string_match_list ("abcdef", masks, 0); /* == 0 */ int match3 = weechat_string_match_list ("def", masks, 0); /* == 1 */ ---- Script (Python): [source,python] ---- # prototype def string_match_list(string: str, masks: str, case_sensitive: int) -> int: ... # examples match1 = weechat.string_match("abc", "*,!abc*", 0) # == 0 match2 = weechat.string_match("abcdef", "*,!abc*", 0) # == 0 match3 = weechat.string_match("def", "*,!abc*", 0) # == 1 ---- ==== string_expand_home _WeeChat ≥ 0.3.3._ Replace leading `+~+` by string with home directory. If string does not start with `+~+`, then same string is returned. Prototype: [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/user/file.txt" */ /* ... */ free (str); ---- [NOTE] This function is not available in scripting API. ==== string_eval_path_home _WeeChat ≥ 1.3, updated in 3.2._ Evaluate a path in 3 steps: . replace leading `%h` by a WeeChat directory (data by default), . replace leading `+~+` by user home directory (call to <<_string_expand_home,string_expand_home>>), . evaluate variables (see <<_string_eval_expression,string_eval_expression>>). Prototype: [source,c] ---- char *weechat_string_eval_path_home (const char *path, struct t_hashtable *pointers, struct t_hashtable *extra_vars, struct t_hashtable *options); ---- Arguments: * _path_: path * _pointers_: hashtable for call to function <<_string_eval_expression,string_eval_expression>> * _extra_vars_: hashtable for call to function <<_string_eval_expression,string_eval_expression>> * _options_: hashtable for call to function <<_string_eval_expression,string_eval_expression>>, with one extra key supported: ** _directory_: WeeChat directory to use when replacing `%h`, one of: *** _config_ *** _data_ (default) *** _cache_ *** _runtime_ Return value: * evaluated path (must be freed by calling "free" after use) C example: [source,c] ---- char *str = weechat_string_eval_path_home ("${weechat_config_dir}/test.conf", NULL, NULL, NULL); /* result: "/home/user/.config/weechat/test.conf" */ /* ... */ free (str); ---- Script (Python): [source,python] ---- # prototype def string_eval_path_home(path: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ... # example path = weechat.string_eval_path_home("${weechat_config_dir}/test.conf", {}, {}, {}) # path == "/home/user/.config/weechat/test.conf" ---- ==== string_remove_quotes Remove quotes at beginning and end of string (ignore spaces if there are before first quote or after last quote). Prototype: [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. ==== 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. ==== 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. ==== 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 def string_mask_to_regex(mask: str) -> str: ... # example regex = weechat.string_mask_to_regex("test*mask") # "test.*mask" ---- ==== string_regex_flags _WeeChat ≥ 0.3.7._ Get pointer on string after flags and mask with flags to compile regular expression. Prototype: [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. ==== string_regcomp _WeeChat ≥ 0.3.7._ Compile a POSIX extended regular expression using optional flags at beginning of string (for format of flags, see <<_string_regex_flags,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`) [NOTE] Regular expression _preg_ must be cleaned by calling "regfree" after use, if the function returned 0 (OK). C example: [source,c] ---- regex_t my_regex; if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0) { /* OK */ /* ... */ regfree (&my_regex); } else { /* error */ /* ... */ } ---- [NOTE] This function is not available in scripting API. ==== string_has_highlight Check if a string has one or more highlights, using list of highlight words. Prototype: [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 def string_has_highlight(string: str, highlight_words: str) -> int: ... # example highlight = weechat.string_has_highlight("my test string", "test,word2") # 1 ---- ==== string_has_highlight_regex _WeeChat ≥ 0.3.4._ Check if a string has one or more highlights, using a POSIX extended regular expression. + For at least one match of regular expression on string, it must be surrounded by delimiters (chars different from: alphanumeric, `+-+`, `+_+` and `+|+`). Prototype: [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 def string_has_highlight_regex(string: str, regex: str) -> int: ... # example highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1 ---- ==== string_replace Replace all occurrences of a string by another string. Prototype: [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. ==== 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 <<_string_regcomp,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. ==== string_split _Updated in 2.5, 2.6._ Split a string according to one or more delimiter(s). Prototype: [source,c] ---- char **weechat_string_split (const char *string, const char *separators, const char *strip_items, int flags, int num_items_max, int *num_items); ---- Arguments: * _string_: string to split * _separators_: delimiters used for split * _strip_items_: chars to strip from returned items (left/right); optional, can be NULL * _flags_: combination values to change the default behavior; if the value is 0, the default behavior is used (no strip of separators at beginning/end of string, multiple separators are kept as-is so empty strings can be returned); the following flags are accepted: ** WEECHAT_STRING_SPLIT_STRIP_LEFT: strip separators on the left (beginning of string) ** WEECHAT_STRING_SPLIT_STRIP_RIGHT: strip separators on the right (end of string) ** WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: collapse multiple consecutive separators into a single one ** WEECHAT_STRING_SPLIT_KEEP_EOL: keep end of line for each value * _num_items_max_: maximum number of items created (0 = no limit) * _num_items_: pointer to int which will contain number of items created [NOTE] With WeeChat ≤ 2.4, the _flags_ argument was called _keep_eol_ and took other values, which must be converted like that: [width="100%",cols="1,10",options="header"] |=== | keep_eol | flags | 0 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS | 1 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL | 2 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL |=== Return value: * array of strings, NULL if problem (must be freed by calling <<_string_free_split,string_free_split>> after use) C example: [source,c] ---- char **argv; int argc; argv = weechat_string_split ("abc de fghi ", " ", NULL, 0, 0, &argc); /* result: argv[0] == "abc" argv[1] == "de" argv[2] == "" argv[3] == "fghi" argv[4] = "" argv[5] == NULL argc == 5 */ weechat_string_free_split (argv); argv = weechat_string_split ("abc de fghi ", " ", NULL, WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_STRIP_RIGHT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS, 0, &argc); /* result: argv[0] == "abc" argv[1] == "de" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_split (argv); argv = weechat_string_split ("abc de fghi ", " ", NULL, WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_STRIP_RIGHT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS | WEECHAT_STRING_SPLIT_KEEP_EOL, 0, &argc); /* result: argv[0] == "abc de fghi" argv[1] == "de fghi" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_split (argv); argv = weechat_string_split ("abc de fghi ", " ", NULL, WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS | WEECHAT_STRING_SPLIT_KEEP_EOL, 0, &argc); /* result: argv[0] == "abc de fghi " argv[1] == "de fghi " argv[2] == "fghi " argv[3] == NULL argc == 3 */ weechat_string_free_split (argv); argv = weechat_string_split (" abc, de,, fghi ", ",", " ", WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_STRIP_RIGHT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS, 0, &argc); /* result: argv[0] == "abc" argv[1] == "de" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_split (argv); ---- [NOTE] This function is not available in scripting API. ==== string_split_shell _WeeChat ≥ 1.0._ Split a string like the shell does for a command with arguments. This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in Python repository), see https://docs.python.org/3/library/shlex.html[this page ^↗^,window=_blank]. 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 <<_string_free_split,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. ==== 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 <<_string_split,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. ==== string_rebuild_split_string _Updated in 3.7._ Rebuild a string with a split string, using optional separator and index of first/last string to use. Prototype: [source,c] ---- char *weechat_string_rebuild_split_string (char **split_string, const char *separator, int index_start, int index_end); ---- Arguments: * _split_string_: string split by function <<_string_split,string_split>> * _separator_: string used to separate strings (can be NULL or empty string) * _index_start_: index of first string to use (≥ 0) * _index_end_: index of last string to use (must be ≥ _index_start_; special value -1 can be used to use all arguments until NULL is found) Return value: * string rebuilt with split string (must be freed by calling "free" after use) C example: [source,c] ---- char **argv; int argc; argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc); char *str = weechat_string_rebuild_split_string (argv, ";", 0, -1); /* str == "abc;def;ghi" */ /* ... */ free (str); ---- [NOTE] This function is not available in scripting API. ==== string_split_command Split a list of commands separated by _separator_ (which can be escaped by `+\+` in string). Prototype: [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 <<_free_split_command,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" argv[2] == NULL */ weechat_free_split_command (argv); ---- [NOTE] This function is not available in scripting API. ==== string_free_split_command Free memory used by a split command. Prototype: [source,c] ---- void weechat_string_free_split_command (char **split_command); ---- Arguments: * _split_command_: command split by <<_string_split_command,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. ==== 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 bytes" */ /* ... */ free (str); char *str = weechat_string_format_size (1); /* str == "1 byte" */ /* ... */ free (str); char *str = weechat_string_format_size (200); /* str == "200 bytes" */ /* ... */ free (str); char *str = weechat_string_format_size (15200); /* str == "15.2 KB" */ /* ... */ free (str); char *str = weechat_string_format_size (2097152); /* str == "2.10 MB" */ /* ... */ free (str); ---- Script (Python), _WeeChat ≥ 2.2_: [source,python] ---- # prototype def string_format_size(size: int) -> str: ... # example str = weechat.string_format_size(15200) # == "15.2 KB" ---- ==== string_parse_size _WeeChat ≥ 3.7._ Parse a string with a size and optional unit and return the size in bytes. Prototype: [source,c] ---- unsigned long long weechat_string_parse_size (const char *size); ---- Arguments: * _size_: the size as string: positive integer number followed by optional spaces and optional unit (lower or upper case), which is one of: ** _b_: bytes ** _k_: kilobytes (1k = 1000 bytes) ** _m_: megabytes (1m = 1000k = 1,000,000 bytes) ** _g_: gigabytes (1g = 1000m = 1,000,000,000 bytes) ** _t_: terabytes (1t = 1000g = 1,000,000,000,000 bytes) Return value: * size in bytes, 0 if error C example: [source,c] ---- unsigned long long size = weechat_parse_size ("1.34m"); /* size == 1340000 */ ---- Script (Python): [source,python] ---- # prototype def string_parse_size(size: str) -> int: ... # example size = weechat.string_parse_size("1.34m") # 1340000 ---- ==== string_color_code_size _WeeChat ≥ 3.0._ Return the size (in bytes) of the WeeChat color code at the beginning of the string. Prototype: [source,c] ---- int weechat_string_color_code_size (const char *string); ---- Arguments: * _string_: string Return value: * size (in bytes) of the WeeChat color code at the beginning of the string; if the string is NULL, empty or does not start with a color code, 0 is returned; if the string begins with multiple color codes, only the size of the first one is returned C examples: [source,c] ---- int size; size = weechat_string_color_code_size ("test"); /* size == 0 */ size = weechat_string_color_code_size (weechat_color ("bold")); /* size == 2 */ size = weechat_string_color_code_size (weechat_color ("yellow,red")); /* size == 7 */ ---- Script (Python): [source,python] ---- # prototype def string_color_code_size(string: str) -> int: ... # examples size = weechat.string_color_code_size("test") # size == 0 size = weechat.string_color_code_size(weechat.color("bold")) # size == 2 size = weechat.string_color_code_size(weechat.color("yellow,red")) # size == 7 ---- ==== string_remove_color 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 def string_remove_color(string: str, replacement: str) -> str: ... # example str = weechat.string_remove_color(my_string, "?") ---- ==== string_base_encode _WeeChat ≥ 2.4._ Encode a string in base 16, 32, or 64. Prototype: [source,c] ---- int weechat_string_base_encode (int base, const char *from, int length, char *to); ---- Arguments: * _base_: 16, 32, or 64 * _from_: string to encode * _length_: length of string to encode (for example `strlen(from)`) * _to_: pointer to string to store result (must be long enough, result is longer than initial string) Return value: * length of string stored in _*to_ (does not count final `\0`), -1 if error C example: [source,c] ---- char *string = "abcdefgh", result[128]; int length; length = weechat_string_base_encode (16, string, strlen (string), result); /* length == 16, result == "6162636465666768" */ length = weechat_string_base_encode (32, string, strlen (string), result); /* length == 16, result == "MFRGGZDFMZTWQ===" */ length = weechat_string_base_encode (64, string, strlen (string), result); /* length == 12, result == "YWJjZGVmZ2g=" */ ---- [NOTE] This function is not available in scripting API. ==== string_base_decode _WeeChat ≥ 2.4._ Decode a string encoded in base 16, 32, or 64. Prototype: [source,c] ---- int weechat_string_base_decode (int base, const char *from, char *to); ---- Arguments: * _base_: 16, 32, or 64 * _from_: string to decode * _to_: pointer to string to store result (must be long enough, result is shorter than initial string) Return value: * length of string stored in _*to_ (does not count final `\0`), -1 if error C example: [source,c] ---- char result[128]; int length; length = weechat_string_base_decode (16, "6162636465666768", result); /* length == 8, result == "abcdefgh" */ length = weechat_string_base_decode (32, "MFRGGZDFMZTWQ===", result); /* length == 8, result == "abcdefgh" */ length = weechat_string_base_decode (64, "YWJjZGVmZ2g=", result); /* length == 8, result == "abcdefgh" */ ---- [NOTE] This function is not available in scripting API. ==== string_hex_dump _WeeChat ≥ 1.4._ Display a dump of data as hexadecimal and ascii bytes. Prototype: [source,c] ---- char *string_hex_dump (const char *data, int data_size, int bytes_per_line, const char *prefix, const char *suffix); ---- Arguments: * _data_: the data to dump * _data_size_: number of bytes to dump in _data_ * _bytes_per_line_: number of bytes to display in each line * _prefix_: the prefix to display at the beginning of each line (optional, can be NULL) * _suffix_: the suffix to display at the end of each line (optional, can be NULL) Return value: * string with dump of data (must be freed by calling "free" after use) C example: [source,c] ---- char *string = "abc def-ghi"; char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL); /* dump == " >> 61 62 63 20 64 65 66 2D a b c d e f - \n" " >> 67 68 69 g h i " */ ---- [NOTE] This function is not available in scripting API. ==== string_is_command_char _WeeChat ≥ 0.3.2._ Check if first char of string is a command char (default command char is `+/+`). Prototype: [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 def string_is_command_char(string: str) -> int: ... # examples command_char1 = weechat.string_is_command_char("/test") # == 1 command_char2 = weechat.string_is_command_char("test") # == 0 ---- ==== string_input_for_buffer _WeeChat ≥ 0.3.2._ Return pointer to input text for buffer (pointer inside "string" argument), or NULL if it's a command. Prototype: [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 def string_input_for_buffer(string: str) -> str: ... # examples str1 = weechat.string_input_for_buffer("test") # "test" str2 = weechat.string_input_for_buffer("/test") # "" str3 = weechat.string_input_for_buffer("//test") # "/test" ---- ==== string_eval_expression _WeeChat ≥ 0.4.0, updated in 0.4.2, 0.4.3, 1.0, 1.1, 1.2, 1.3, 1.6, 1.8, 2.0, 2.2, 2.3, 2.7, 2.9, 3.1, 3.2, 3.3, 3.4, 3.6._ Evaluate an expression and return result as a string. Special variables with format `+${variable}+` are expanded (see table below). [NOTE] Since version 1.0, nested variables are supported, for example: `+${color:${variable}}+`. Prototype: [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 (see <> and <>) * _pointers_: hashtable with pointers (keys must be string, values must be pointer); pointers "window" and "buffer" are automatically added if they are not in hashtable (with pointer to current window/buffer) (can be NULL): ** _regex_: pointer to a regular expression (_regex_t_ structure) compiled with WeeChat function <<_string_regcomp,string_regcomp>> or regcomp (see `man regcomp`); this option is similar to _regex_ in hashtable _options_ (below), but is used for better performance * _extra_vars_: extra variables that will be expanded (can be NULL) * _options_: a hashtable with some options (keys and values must be string) (can be NULL): ** _type_: default behavior is just to replace values in expression, other types can be selected: *** _condition_: the expression is evaluated as a condition: operators and parentheses are used, result is a boolean ("0" or "1") ** _prefix_: prefix before variables to replace (default: `+${+`) ** _suffix_: suffix after variables to replace (default: `+}+`) ** _extra_: default behavior is to just replace extra variables (_extra_vars_), other behavior can be selected: *** _eval_: extra variables (_extra_vars_) are evaluated themselves before replacing _(WeeChat ≥ 1.6)_ ** _regex_: a regex used to replace text in _expr_ (which is then not evaluated) ** _regex_replace_: the replacement text to use with _regex_, to replace text in _expr_ (the _regex_replace_ is evaluated on each match of _regex_ against _expr_, until no match is found) ** _debug_: debug level (string with integer number ≥ 1), if enabled, a key "debug_output" is added in hashtable _options_: *** _1_: enable debug *** _2_: enable more verbose debug Return value: * evaluated expression (must be freed by calling "free" after use), or NULL if problem (invalid expression or not enough memory) C examples: [source,c] ---- /* conditions */ struct t_hashtable *options1 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); weechat_hashtable_set (options1, "type", "condition"); char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1); /* "1" */ char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1); /* "0" */ /* simple expression */ char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL); /* "core.weechat" */ /* replace with regex */ struct t_hashtable *options2 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); /* add brackets around URLs */ weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+"); weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]"); char *str4 = weechat_string_eval_expression ("test: https://weechat.org", NULL, NULL, NULL); /* "test: [ https://weechat.org ]" */ /* hide passwords */ weechat_hashtable_set (options2, "regex", "(password=)([^ ]+)"); weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}"); char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL); /* "password=*** password=***" */ ---- Script (Python): [source,python] ---- # prototype def string_eval_expression(expr: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ... # examples # conditions str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"}) # "1" str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"}) # "0" # simple expression str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat" # replace with regex: add brackets around URLs options = { "regex": "[a-zA-Z0-9_]+://[^ ]+", "regex_replace": "[ ${re:0} ]", } str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options) # "test: [ https://weechat.org ]" # replace with regex: hide passwords options = { "regex": "(password=)([^ ]+)", "regex_replace": "${re:1}${hide:*,${re:2}}", } str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options) # "password=*** password=***" ---- [[eval_conditions]] ===== Conditions List of logical operators that can be used in conditions (by order of priority, from first used to last): [width="100%",cols="2,1,5,5",options="header"] |=== | Operator | Min WeeChat | Description | Examples | `+&&+` | | Logical "and" | >> `+25 && 77+` + == `+1+` + + >> `+25 && 0+` + == `+0+` | `+\|\|+` | | Logical "or" | >> `+25 \|\| 0+` + == `+1+` + + >> `+0 \|\| 0+` + == `+0+` |=== List of comparison operators that can be used in conditions (by order of priority, from first used to last): [width="100%",cols="2,1,5,5",options="header"] |=== | Operator | Min WeeChat | Description | Examples | `+=~+` | | Is matching POSIX extended regex (optional flags are allowed, see function <<_string_regcomp,string_regcomp>>) | >> `+abc def =~ ab.*ef+` + == `+1+` + + >> `+abc def =~ y.*z+` + == `+0+` | `+!~+` | | Is NOT matching POSIX extended regex (optional flags are allowed, see function <<_string_regcomp,string_regcomp>>) | >> `+abc def !~ ab.*ef+` + == `+0+` + + >> `+abc def !~ y.*z+` + == `+1+` | `+==*+` | 2.9 | Is matching mask where "*" is allowed, case sensitive (see function <<_string_match,string_match>>) | >> `+abc def ==* a*f+` + == `+1+` + + >> `+abc def ==* y*z+` + == `+0+` | `+!!*+` | 2.9 | Is NOT wildcard mask where "*" is allowed, case sensitive (see function <<_string_match,string_match>>) | >> `+abc def !!* a*f+` + == `+0+` + + >> `+abc def !!* y*z+` + == `+1+` | `+=*+` | 1.8 | Is matching mask where "*" is allowed, case insensitive (see function <<_string_match,string_match>>) | >> `+abc def =* A*F+` + == `+1+` + + >> `+abc def =* Y*Z+` + == `+0+` | `+!*+` | 1.8 | Is NOT wildcard mask where "*" is allowed, case insensitive (see function <<_string_match,string_match>>) | >> `+abc def !* A*F+` + == `+0+` + + >> `+abc def !* Y*Z+` + == `+1+` | `+==-+` | 2.9 | Is included, case sensitive | >> `+abc def ==- bc+` + == `+1+` + + >> `+abc def ==- xyz+` + == `+0+` | `+!!-+` | 2.9 | Is NOT included, case sensitive | >> `+abc def !!- bc+` + == `+0+` + + >> `+abc def !!- xyz+` + == `+1+` | `+=-+` | 2.9 | Is included, case insensitive | >> `+abc def =- BC+` + == `+1+` + + >> `+abc def =- XYZ+` + == `+0+` | `+!-+` | 2.9 | Is NOT included, case insensitive | >> `+abc def !- BC+` + == `+0+` + + >> `+abc def !- XYZ+` + == `+1+` | `+==+` | | Equal | >> `+test == test+` + == `+1+` + + >> `+test == string+` + == `+0+` | `+!=+` | | Not equal | >> `+test != test+` + == `+0+` + + >> `+test != string+` + == `+1+` | `+<=+` | | Less or equal | >> `+abc <= defghi+` + == `+1+` + + >> `+abc <= abc+` + == `+1+` + + >> `+defghi <= abc+` + == `+0+` + + >> `+15 <= 2+` + == `+0+` | `+<+` | | Less | >> `+abc < defghi+` + == `+1+` + + >> `+abc < abc+` + == `+0+` + + >> `+defghi < abc+` + == `+0+` + + >> `+15 < 2+` + == `+0+` | `+>=+` | | Greater or equal | >> `+defghi >= abc+` + == `+1+` + + >> `+abc >= abc+` + == `+1+` + + >> `+abc >= defghi+` + == `+0+` + + >> `+15 >= 2+` + == `+1+` | `+>+` | | Greater | >> `+defghi > abc+` + == `+1+` + + >> `+abc > abc+` + == `+0+` + + >> `+abc > defghi+` + == `+0+` + + >> `+15 > 2+` + == `+1+` |=== The comparison is made using floating point numbers if the two expressions are valid numbers, with one of the following formats: * integer (examples: 5, -7) * floating point number (examples: 5.2, -7.5, 2.83e-2) _(WeeChat ≥ 2.0)_ * hexadecimal number (examples: 0xA3, -0xA3) _(WeeChat ≥ 2.0)_ To force a string comparison, you can add double quotes around each expression, for example: * `50 > 100` returns 0 (number comparison) * `"50" > "100"` returns 1 (string comparison) [[eval_variables]] ===== Variables List of variables expanded in expression (by order of priority, from first expanded to last): [width="100%",cols="2,1,5,5",options="header"] |=== | Format | Min WeeChat | Description | Examples | `+${raw:xxx}+` | 3.1 | Raw string (not evaluated). | >> `+${raw:${info:version}}+` + == `+${info:version}+` | `+${name}+` | 3.4 | User variable (defined with `+${define:name,value}+`). | >> `+${name}+` + == `+value+` | `+${name}+` | | Variable `name` from hashtable _extra_vars_. | >> `+${name}+` + == `+value+` | `+${weechat_xxx_dir}+` | 3.2 | A WeeChat directory: `+${weechat_config_dir}+`, `+${weechat_data_dir}+`, `+${weechat_cache_dir}+` or `+${weechat_runtime_dir}+`. | >> `+${weechat_config_dir}+` + == `+/home/user/.config/weechat+` + + >> `+${weechat_data_dir}+` + == `+/home/user/.local/share/weechat+` + + >> `+${weechat_cache_dir}+` + == `+/home/user/.cache/weechat+` + + >> `+${weechat_runtime_dir}+` + == `+/run/user/1000/weechat+` | `+${eval:xxx}+` | 1.3 | String to evaluate. | >> `+${eval:${date:${weechat.look.buffer_time_format}}}+` + == `+19:02:45+` ^(1)^ + + ^(1)^ With colors if there are color codes in the option weechat.look.buffer_time_format | `+${eval_cond:xxx}+` | 3.1 | String to evaluate as condition. | >> `+${eval_cond:${window.win_width} > 100}+` + == `+1+` | `+${esc:xxx}+` + `+${\xxx}+` | 1.0 | String with escaped chars. | >> `+${esc:prefix\tmessage}+` + == `+prefixmessage+` + + >> `+${\ua9}+` + == `+©+` | `+${lower:string}+` | 3.6 | String converted to lower case. | >> `+${lower:TEST}+` + >> `+test+` | `+${upper:string}+` | 3.6 | String converted to upper case. | >> `+${upper:test}+` + >> `+TEST+` | `+${hide:x,string}+` | 1.1 | String with hidden chars (all chars in `string` replaced by `x`). | >> `+${hide:*,password}+` + >> `+********+` | `+${cut:max,suffix,string}+` + `+${cut:+max,suffix,string}+` | 1.8 | String with `max` chars, and optional `suffix` if string is cut. + With the format `+max`, the suffix is counted in max length. | >> `+${cut:4,…,this is a test}+` + == `+this…+` + + >> `+${cut:+4,…,this is a test}+` + == `+t…+` + + >> `+${cut:2,>>,こんにちは世界}+` + == `+こん>>+` | `+${cutscr:max,suffix,string}+` + `+${cutscr:+max,suffix,string}+` | 1.8 | String with `max` chars displayed on screen, and optional `suffix` if string is cut. + With the format `+max`, the suffix is counted in max length. | >> `+${cutscr:4,…,this is a test}+` + == `+this…+` + + >> `+${cutscr:+4,…,this is a test}+` + == `+thi…+` + + >> `+${cutscr:2,>>,こんにちは世界}+` + == `+こ>>+` | `+${rev:xxx}+` | 2.2 | Reversed string (color codes are reversed, so the string should not contain color codes). | >> `+${rev:Hello, world!}+` + == `+!dlrow ,olleH+` + + >> `+${rev:Hello, ${color:red}world!}+` + == `+!dlrow30F ,olleH+` ^(1)^ + + ^(1)^ No color, the color code is reversed | `+${revscr:xxx}+` | 2.7 | Reversed string for screen, color codes are not reversed. | >> `+${revscr:Hello, world!}+` + == `+!dlrow ,olleH+` + + >> `+${revscr:Hello, ${color:red}world!}+` + == `+!dlrow ,olleH+` ^(1)^ + + ^(1)^ `pass:[ ,olleH]` in red | `+${repeat:count,string}+` | 2.3 | Repeated string. | >> `+${repeat:5,-}+` + == `+-----+` | `+${length:xxx}+` | 2.7 | Length of string (number of UTF-8 chars), color codes are ignored. | >> `+${length:test}+` + == `+4+` + + >> `+${length:こんにちは世界}+` + == `+7+` | `+${lengthscr:xxx}+` | 2.7 | Length of string displayed on screen, color codes are ignored. | >> `+${lengthscr:test}+` + == `+4+` + + >> `+${lengthscr:こんにちは世界}+` + == `+14+` | `+${split:number,seps,flags,xxx}+` | 3.3 | Split string, and return, according to `number`: + - `count`: the number of items after split + - `random`: a random item + - integer ≥ 1: the item by index (1 = first item) + - integer ≤ -1: the item by index from the end (-1 = last item, -2 = penultimate item, etc.), + `seps` is a list of chars that are used as separators (if empty, a comma is used), + `flags` is a list of flags separated by `+`: + - `strip_left`: strip separators on the left (beginning of string) + - `strip_right`: strip separators on the right (end of string) + - `collapse_seps`: collapse multiple consecutive separators into a single one + - `keep_eol`: keep end of line for each value + - `strip_items=xyz`: strip chars `x`, `y` and `z` from beginning/end of items + - `max_items=N`: return max N items | >> `+${split:1,,,abc,def,ghi}+` + == `+abc+` + + >> `+${split:-1,,,abc,def,ghi}+` + == `+ghi+` + + >> `+${split:count,,,abc,def,ghi}+` + == `+3+` + + >> `+${split:random,,,abc,def,ghi}+` + == `+def+` + + >> `+${split:3,,collapse_seps,abc,,,def,,,ghi}+` + == `+ghi+` + + >> `+${split:3,,strip_items=-_,_-abc-_,_-def-_,_-ghi-_}+` + == `+ghi+` + + >> `+${split:2, ,,this is a test}+` + == `+is+` + + >> `+${split:2, ,strip_left+strip_right, this is a test }+` + == `+is+` + + >> `+${split:2, ,keep_eol,this is a test}+` + == `+is a test+` | `+${split_shell:number,xxx}+` | 3.3 | Split shell arguments, and return, according to `number`: + - `count`: the number of arguments after split + - `random`: a random argument + - integer ≥ 1: the argument by index (1 = first argument) + - integer ≤ -1: the argument by index from the end (-1 = last argument, -2 = penultimate argument, etc.) | >> `+${split_shell:1,"first arg" arg2}+` + == `+first arg+` + + >> `+${split_shell:-1,"first arg" arg2}+` + == `+arg2+` + + >> `+${split_shell:count,"first arg" arg2}+` + == `+2+` + + >> `+${split_shell:random,"first arg" arg2}+` + == `+arg2+` | `+${re:xxx}+` | 1.1 | Regex data: + `0` = whole string matching, + `1` to `99` = group captured, + `+++` = last group captured, + `#` = index of last group captured _(WeeChat ≥ 1.8)_, + `repl_index` = index of replacement being done (starts to 1) _(WeeChat ≥ 3.3)_. | >> `+${re:0}+` + == `+test1 test2+` + + >> `+${re:1}+` + == `+test1+` + + >> `+${re:2}+` + == `+test2+` + + >> `+${re:+}+` + == `+test2+` + + >> `+${re:#}+` + == `+2+` + + >> `+${re:repl_index}+` + == `+1+` | `+${color:name}+` | 0.4.2 | WeeChat color code (the name of color has optional attributes), see function <<_color,color>> for supported formats. | >> `+${color:red}red text+` + == `+red text+` ^(1)^ + + >> `+${color:*214}bold orange text+` + == `+bold orange text+` ^(2)^ + + ^(1)^ In red + ^(2)^ In bold orange | `+${modifier:name,data,string}+` | 2.7 | Result of a modifier, see function <<_hook_modifier_exec,hook_modifier_exec>>. | >> `+${modifier:eval_path_home,,~}+` + == `+/home/user+` + + >> `+${modifier:eval_path_home,directory=config,%h/irc.conf}+` + == `+/home/user/.config/weechat/irc.conf+` | `+${info:name}+` + `+${info:name,arguments}+` | 0.4.3 | Info from WeeChat or a plugin, see function <<_info_get,info_get>>. | >> `+${info:version}+` + == `+1.0+` + + >> `+${info:nick_color_name,foo}+` + == `+lightblue+` | `+${base_encode:base,xxx}+` | 2.9 | String encoded in base 16, 32 or 64. | >> `+${base_encode:16,test string}+` + == `+7465737420737472696E67+` + + >> `+${base_encode:32,test string}+` + == `+ORSXG5BAON2HE2LOM4======+` + + >> `+${base_encode:64,test string}+` + == `+dGVzdCBzdHJpbmc=+` | `+${base_decode:base,xxx}+` | 2.9 | String decoded from base 16, 32 or 64. | >> `+${base_decode:16,7465737420737472696E67}+` + == `+test string+` + + >> `+${base_decode:32,ORSXG5BAON2HE2LOM4======}+` + == `+test string+` + + >> `+${base_decode:64,dGVzdCBzdHJpbmc=}+` + == `+test string+` | `+${date}+` + `+${date:xxx}+` | 1.3 | Current date/time, with custom format (see `man strftime`), default format is `%F %T`. | >> `+${date}+` + == `+2015-06-30 19:02:45+` + + >> `+${date:%H:%M:%S}+` + == `+19:02:45+` | `+${env:NAME}+` | 1.2 | Value of the environment variable `NAME`. | >> `+${env:HOME}+` + == `+/home/user+` | `+${if:condition}+` + `+${if:condition?true}+` `+${if:condition?true:false}+` | 1.8 | Ternary operator with a condition, a value if the condition is true (optional) and another value if the condition is false (optional). If values are not given, "1" or "0" are returned, according to the result of the condition. | >> `+${if:${info:term_width}>80?big:small}+` + == `+big+` | `+${calc:xxx}+` | 2.7 | Result of expression, where parentheses and the following operators are supported: + `+++`: addition + `+-+`: subtraction + `+*+`: multiplication + `+/+`: division + `+//+`: result of division without fractional part + `+%+`: remainder of division + `+**+`: power. | >> `+${calc:5+2*3}+` + == `+11+` + + >> `+${calc:(5+2)*3}+` + == `+21+` + + >> `+${calc:10/4}+` + == `+2.5+` + + >> `+${calc:10//4}+` + == `+2+` + + >> `+${calc:9.2%3}+` + == `+0.2+` + + >> `+${calc:2**16}+` + == `+65536+` | `+${random:min,max}+` | 3.3 | Random integer number in the range from `min` to `max` (inclusive). | >> `+${random:0,10}+` + == `+3+` | `+${translate:xxx}+` | 3.2 | Translated string (depends on the language used by WeeChat to display messages). | >> `+${translate:Plugin}+` + == `+Extension+` ^(1)^ + + ^(1)^ Example in French | `+${define:name,value}+` | 3.4 | Define a variable `name` set to `value`, which can then be used in the same evaluated expression with `+${name}+`. | >> `+${define:len,${calc:5+3}}${len}x${len}+` + == `+8x8+` | `+${sec.data.name}+` | | Value of the secured data `name`. | >> `+${sec.data.libera_pass}+` + == `+my_password+` | `+${file.section.option}+` | | Value of the option. | >> `+${weechat.look.buffer_time_format}+` + == `+%H:%M:%S+` | `+${name}+` | | Value of local variable `name` in buffer. | >> `+${nick}+` + == `+FlashCode+` | `+${pointer}+` | | Variable `pointer` from hashtable _pointers_. | >> `+${buffer}+` + == `+0x1234abcd+` | `+${hdata.var1.var2...}+` + `+${hdata[list].var1.var2...}+` | | Hdata value (pointers `window` and `buffer` are set by default with current window/buffer), `list` can be a list name (example: "gui_buffers"), a pointer (example: "0x1234abcd") or a pointer name (example: "my_pointer"). | >> `+${buffer[gui_buffers].full_name}+` + == `+core.weechat+` + + >> `+${buffer[my_buffer_pointer].full_name}+` + == `+core.weechat+` + + >> `+${window.buffer.number}+` + == `+1+` |=== ==== string_dyn_alloc _WeeChat ≥ 1.8._ Allocate a dynamic string, with a variable length. + Internally, a structure is allocated with the string pointer, the allocated size and current length of string. Only the pointer to string pointer (_**string_) is used in all the _pass:[string_dyn_*]_ functions. Prototype: [source,c] ---- char **weechat_string_dyn_alloc (int size_alloc); ---- Arguments: * _size_alloc_: the initial allocated size (must be greater than zero) Return value: * pointer to the dynamic string C example: [source,c] ---- char **string = weechat_string_dyn_alloc (256); ---- [NOTE] This function is not available in scripting API. ==== string_dyn_copy _WeeChat ≥ 1.8._ Copy a string in a dynamic string. The pointer _*string_ can change if the string is reallocated (if there is not enough space to copy the string). Prototype: [source,c] ---- int weechat_string_dyn_copy (char **string, const char *new_string); ---- Arguments: * _string_: pointer to dynamic string * _new_string_: the string to copy Return value: * 1 if OK, 0 if error C example: [source,c] ---- char **string = weechat_string_dyn_alloc (256); if (weechat_string_dyn_copy (string, "test")) { /* OK */ } else { /* error */ } ---- [NOTE] This function is not available in scripting API. ==== string_dyn_concat _WeeChat ≥ 1.8, updated in 3.0._ Concatenate a string to a dynamic string. The pointer _*string_ can change if the string is reallocated (if there is not enough space to concatenate the string). Prototype: [source,c] ---- int weechat_string_dyn_concat (char **string, const char *add, int bytes); ---- Arguments: * _string_: pointer to dynamic string * _add_: the string to add * _bytes_: max number of bytes in _add_ to concatenate, must be lower or equal to length of _add_ (-1 = automatic: concatenate whole string _add_) _(WeeChat ≥ 3.0)_ Return value: * 1 if OK, 0 if error C example: [source,c] ---- char **string = weechat_string_dyn_alloc (256); if (weechat_string_dyn_copy (string, "test")) { if (weechat_string_dyn_concat (string, "abc", -1)) { /* ... */ } } ---- [NOTE] This function is not available in scripting API. ==== string_dyn_free _WeeChat ≥ 1.8._ Free a dynamic string. Prototype: [source,c] ---- char *weechat_string_dyn_free (char **string, int free_string); ---- Arguments: * _string_: pointer to dynamic string * _free_string_: free the string itself; if 0, the content of _*string_ remains valid after the call to this function Return value: * string pointer if _free_string_ is 0, otherwise NULL C example: [source,c] ---- char **string = weechat_string_dyn_alloc (256); if (weechat_string_dyn_concat (string, "test")) { /* OK */ } else { /* error */ } /* ... */ weechat_string_dyn_free (string, 1); ---- [NOTE] This function is not available in scripting API. [[utf-8]] === UTF-8 Some UTF-8 string functions. ==== 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. ==== utf8_is_valid _Updated in 1.4._ Check if a string is UTF-8 valid. Prototype: [source,c] ---- int weechat_utf8_is_valid (const char *string, int length, char **error); ---- Arguments: * _string_: string * _length_: max number of UTF-8 chars to check; if ≤ 0, the whole string is checked _(WeeChat ≥ 1.4)_ * _error_: if not NULL, _*error_ is set with pointer to first non valid UTF-8 char in string, if any Return value: * 1 if UTF-8 string is valid, otherwise 0 C example: [source,c] ---- char *error; if (weechat_utf8_is_valid (string, -1, &error)) { /* ... */ } else { /* "error" points to first invalid char */ } ---- [NOTE] This function is not available in scripting API. ==== utf8_normalize Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char. Prototype: [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. ==== utf8_prev_char _Updated in 1.3._ Return pointer to previous UTF-8 char in a string. Prototype: [source,c] ---- const char *weechat_utf8_prev_char (const char *string_start, const char *string); ---- Arguments: * _string_start_: start of string (function will not return a char before this pointer) * _string_: pointer to string (must be ≥ _string_start_) Return value: * pointer to previous UTF-8 char, NULL if not found (start of string reached) (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_) C example: [source,c] ---- const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string); ---- [NOTE] This function is not available in scripting API. ==== utf8_next_char _Updated in 1.3._ Return pointer to next UTF-8 char in a string. Prototype: [source,c] ---- const char *weechat_utf8_next_char (const char *string); ---- Arguments: * _string_: string Return value: * pointer to next UTF-8 char, NULL if not found (end of string reached) (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_) C example: [source,c] ---- const char *next_char = weechat_utf8_next_char (string); ---- [NOTE] This function is not available in scripting API. ==== utf8_char_int Return UTF-8 char as integer. Prototype: [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. ==== 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. ==== 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. ==== 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. ==== 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. ==== utf8_charcmp _Updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 if string1 > string2 C example: [source,c] ---- int diff = weechat_utf8_charcmp ("aaa", "ccc"); /* == -2 */ ---- [NOTE] This function is not available in scripting API. ==== utf8_charcasecmp _Updated in 1.0._ 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: * -1 if string1 < string2 * 0 if string1 == string2 * 1 if string1 > string2 C example: [source,c] ---- int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */ ---- [NOTE] This function is not available in scripting API. ==== 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. ==== utf8_add_offset _Updated in 1.3._ Move forward N chars in an UTF-8 string. Prototype: [source,c] ---- const char *weechat_utf8_add_offset (const char *string, int offset); ---- Arguments: * _string_: string * _offset_: number of chars Return value: * pointer to string, N chars after (NULL if it's not reachable) (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_) C example: [source,c] ---- const char *str = "chêne"; const char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */ ---- [NOTE] This function is not available in scripting API. ==== utf8_real_pos Return real position in UTF-8 string. Prototype: [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. ==== 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. ==== 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. [[crypto]] === Cryptography Some cryptographic functions. ==== crypto_hash _WeeChat ≥ 2.8._ Compute hash of data. Prototype: [source,c] ---- int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo, void *hash, int *hash_size); ---- Arguments: * _data_: the data to hash * _data_size_: number of bytes to hash in _data_ * _hash_algo_: the hash algorithm, see table below * _hash_: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table below) * _hash_size_: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL) [[crypto_hash_algorithms]] Supported hash algorithms: [width="100%",cols="2,2,3,6",options="header"] |=== | Value | Algorithm | Hash size | Notes | `+crc32+` | CRC32 | 4 bytes (32 bits) | Not a hash algorithm in the cryptographic sense. | `+md5+` | MD5 | 16 bytes (128 bits) | *Weak*, not recommended for cryptography usage. | `+sha1+` | SHA-1 | 20 bytes (160 bits) | *Weak*, not recommended for cryptography usage. | `+sha224+` | SHA-224 | 28 bytes (224 bits) | | `+sha256+` | SHA-256 | 32 bytes (256 bits) | | `+sha384+` | SHA-384 | 48 bytes (384 bits) | | `+sha512+` | SHA-512 | 64 bytes (512 bits) | | `+sha3-224+` | SHA3-224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.7.0. | `+sha3-256+` | SHA3-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.7.0. | `+sha3-384+` | SHA3-384 | 48 bytes (384 bits) | Algorithm available with libgcrypt ≥ 1.7.0. | `+sha3-512+` | SHA3-512 | 64 bytes (512 bits) | Algorithm available with libgcrypt ≥ 1.7.0. |=== Return value: * 1 if OK, 0 if error C example: [source,c] ---- const char *data = "abcdefghijklmnopqrstuvwxyz"; char hash[256 / 8]; int rc, hash_size; rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size); /* rc == 1, hash_size == 32 and hash is a buffer with: 71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */ ---- [NOTE] This function is not available in scripting API. ==== crypto_hash_file _WeeChat ≥ 3.7._ Compute hash of a file. Prototype: [source,c] ---- int weechat_crypto_hash_file (const char *filename, const char *hash_algo, void *hash, int *hash_size); ---- Arguments: * _filename_: path and file name * _hash_algo_: the hash algorithm, see table in function <> * _hash_: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function <>) * _hash_size_: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL) Return value: * 1 if OK, 0 if error C example: [source,c] ---- char hash[256 / 8]; int rc, hash_size; rc = weechat_crypto_hash_file ("/path/to/file", "sha256", hash, &hash_size); /* rc == 1, hash_size == 32 and hash is a buffer with: 71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */ ---- [NOTE] This function is not available in scripting API. ==== crypto_hash_pbkdf2 _WeeChat ≥ 2.8._ Compute PKCS#5 Passphrase Based Key Derivation Function number 2 (PBKDF2) hash of data. Prototype: [source,c] ---- int weechat_crypto_hash_pbkdf2 (const void *data, int data_size, const char *hash_algo, const void *salt, int salt_size, int iterations, void *hash, int *hash_size); ---- Arguments: * _data_: the data to hash * _data_size_: number of bytes to hash in _data_ * _hash_algo_: hash algorithm used by the key derivation function, see table in function <> * _salt_: the salt * _salt_size_: number of bytes in _salt_ * _iterations_: number of iterations * _hash_: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function <>) * _hash_size_: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL) Return value: * 1 if OK, 0 if error C example: [source,c] ---- const char *data = "abcdefghijklmnopqrstuvwxyz"; const char *salt = "12345678901234567890123456789012"; /* 32 bytes */ char hash[256 / 8]; int rc, hash_size; rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000, hash, &hash_size); /* rc == 1, hash_size == 32 and hash is a buffer with: 99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */ ---- [NOTE] This function is not available in scripting API. ==== crypto_hmac _WeeChat ≥ 3.2._ Compute keyed-hash message authentication code (HMAC). Prototype: [source,c] ---- int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size, int hash_algo, void *hash, int *hash_size); ---- Arguments: * _key_: the key * _key_size_: number of bytes in _key_ * _message_: the message * _message_size_: number of bytes in _message_ * _hash_algo_: the hash algorithm, see table in function <> * _hash_: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function <>) * _hash_size_: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL) Return value: * 1 if OK, 0 if error C example: [source,c] ---- const char *key = "the key"; const char *message = "the message"; char hash[256 / 8]; int rc, hash_size; rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size); /* rc == 1, hash_size == 32 and hash is a buffer with: 47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */ ---- [NOTE] This function is not available in scripting API. [[directories]] === Directories Some functions related to directories. ==== mkdir_home _Updated in 3.2._ Create a directory in WeeChat home. Prototype: [source,c] ---- int weechat_mkdir_home (char *directory, int mode); ---- Arguments: * _directory_: name of directory to create; it can start with one of these strings to force a specific WeeChat directory (WeeChat ≥ 3.2): ** `${weechat_config_dir}` ** `${weechat_data_dir}` (default) ** `${weechat_cache_dir}` ** `${weechat_runtime_dir}` * _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 ("${weechat_cache_dir}/temp", 0755)) { /* error */ } ---- Script (Python): [source,python] ---- # prototype def mkdir_home(directory: str, mode: int) -> int: ... # example weechat.mkdir_home("${weechat_cache_dir}/temp", 0755) ---- ==== 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 def mkdir(directory: str, mode: int) -> int: ... # example weechat.mkdir("/tmp/mydir", 0755) ---- ==== mkdir_parents Create a directory and make parent directories as needed. Prototype: [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 def mkdir_parents(directory: str, mode: int) -> int: ... # example weechat.mkdir_parents("/tmp/my/dir", 0755) ---- ==== exec_on_files _Updated in 1.5, 2.0._ Find files in a directory and execute a callback on each file. Prototype: [source,c] ---- void weechat_exec_on_files (const char *directory, int recurse_subdirs, int hidden_files, void (*callback)(void *data, const char *filename), void *callback_data); ---- Arguments: * _directory_: directory for searching files * _recurse_subdirs_: 1 to recurse into sub-directories _(WeeChat ≥ 2.0)_ * _hidden_files_: 1 to include hidden files, otherwise 0 * _callback_: function called for each file found, arguments: ** _void *data_: pointer ** _const char *filename_: filename found * _callback_data_: pointer given to callback when it is called by WeeChat C example: [source,c] ---- void callback (void *data, const char *filename) { /* ... */ } ... weechat_exec_on_files ("/tmp", 0, 0, &callback, NULL); ---- [NOTE] This function is not available in scripting API. ==== file_get_content _WeeChat ≥ 0.3.1._ Get content of text file in a string. Prototype: [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. ==== file_copy _WeeChat ≥ 3.3._ Copy a file to another location. Prototype: [source,c] ---- int weechat_file_copy (const char *from, const char *to); ---- Arguments: * _from_: source file * _to_: destination file Return value: * 1 if OK, 0 if error C example: [source,c] ---- if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt")) { /* OK */ } ---- [NOTE] This function is not available in scripting API. ==== file_compress _WeeChat ≥ 3.7._ Compress a file with gzip or zstd. Prototype: [source,c] ---- int weechat_file_compress (const char *from, const char *to, const char *compressor, int compression_level); ---- Arguments: * _from_: source file * _to_: destination file * _compressor_: the compressor to use, one of: ** _gzip_: gzip compression ** _zstd_: zstandard compression * _compression_level_: compression level, between 1 (fast, low compression) to 100 (slow, best compression) Return value: * 1 if OK, 0 if error C example: [source,c] ---- if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50)) { /* OK */ } ---- [NOTE] This function is not available in scripting API. [[util]] === Util Some useful functions. ==== 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. ==== util_timeval_diff _Updated in 1.1._ Return difference (in microseconds) between two "timeval" structures. Prototype: [source,c] ---- long long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2); ---- Arguments: * _tv1_: first "timeval" structure * _tv2_: second "timeval" structure Return value: * difference in microseconds [NOTE] With WeeChat ≤ 1.0, the returned value was in milliseconds. C example: [source,c] ---- long long diff = weechat_util_timeval_diff (&tv1, &tv2); ---- [NOTE] This function is not available in scripting API. ==== util_timeval_add _Updated in 1.1._ Add interval (in microseconds) to a timeval structure. Prototype: [source,c] ---- void weechat_util_timeval_add (struct timeval *tv, long long interval); ---- Arguments: * _tv_: timeval structure * _interval_: interval (in microseconds) [NOTE] With WeeChat ≤ 1.0, the interval was expressed in milliseconds. C example: [source,c] ---- weechat_util_timeval_add (&tv, 2000000); /* add 2 seconds */ ---- [NOTE] This function is not available in scripting API. ==== util_get_time_string _WeeChat ≥ 0.3.2, updated in 1.3._ Get date/time as a string built with "strftime" and the format defined in option _weechat.look.time_format_. Prototype: [source,c] ---- const char *weechat_util_get_time_string (const time_t *date); ---- Arguments: * _date_: pointer to date Return value: * pointer to a string with date/time C example: [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. ==== 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. ==== 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 def list_new() -> str: ... # example list = weechat.list_new() ---- ==== 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 def list_add(list: str, data: str, where: str, user_data: str) -> str: ... # example item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "") ---- ==== list_search Search an item in a list. Prototype: [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 def list_search(list: str, data: str) -> str: ... # example item = weechat.list_search(list, "my data") ---- ==== list_search_pos _WeeChat ≥ 0.3.4._ Search an item position in a list. Prototype: [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 def list_search_pos(list: str, data: str) -> int: ... # example pos_item = weechat.list_search_pos(list, "my data") ---- ==== list_casesearch Search an item in a list, ignoring case. Prototype: [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 def list_casesearch(list: str, data: str) -> str: ... # example item = weechat.list_casesearch(list, "my data") ---- ==== list_casesearch_pos _WeeChat ≥ 0.3.4._ Search an item position in a list, ignoring case. Prototype: [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 def list_casesearch_pos(list: str, data: str) -> int: ... # example pos_item = weechat.list_casesearch_pos(list, "my data") ---- ==== list_get Return an item in a list by position. Prototype: [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 def list_get(list: str, position: int) -> str: ... # example item = weechat.list_get(list, 0) ---- ==== 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 def list_set(item: str, value: str) -> int: ... # example weechat.list_set(item, "new data") ---- ==== 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 def list_next(item: str) -> str: ... # example item = weechat.list_next(item) ---- ==== 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 def list_prev(item: str) -> str: ... # example item = weechat.list_prev(item) ---- ==== 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 def list_string(item: str) -> str: ... # example weechat.prnt("", "value of item: %s" % weechat.list_string(item)) ---- ==== list_user_data _WeeChat ≥ 2.6._ Return pointer to the user data of an item. Prototype: [source,c] ---- void *weechat_list_user_data (struct t_weelist_item *item); ---- Arguments: * _item_: item pointer Return value: * pointer to the user data of item C example: [source,c] ---- weechat_printf (NULL, "user data of item: 0x%lx", weechat_list_user_data (item)); ---- [NOTE] This function is not available in scripting API. ==== 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 def list_size(list: str) -> int: ... # example weechat.prnt("", "size of list: %d" % weechat.list_size(list)) ---- ==== list_remove Remove an item in a list. Prototype: [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 def list_remove(list: str, item: str) -> int: ... # example weechat.list_remove(list, item) ---- ==== list_remove_all Remove all items from 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 def list_remove_all(list: str) -> int: ... # example weechat.list_remove_all(list) ---- ==== 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 def list_free(list: str) -> int: ... # example weechat.list_free(list) ---- [[array_lists]] === Array lists Array list functions. An array list is a list of pointers with a dynamic size and optional sort. ==== arraylist_new _WeeChat ≥ 1.8._ Create a new array list. Prototype: [source,c] ---- struct t_arraylist *weechat_arraylist_new (int initial_size, int sorted, int allow_duplicates, int (*callback_cmp)(void *data, struct t_arraylist *arraylist, void *pointer1, void *pointer2), void *callback_cmp_data, void (*callback_free)(void *data, struct t_arraylist *arraylist, void *pointer), void *callback_free_data); ---- Arguments: * _initial_size_: initial size of the array list (not the number of items) * _sorted_: 1 to sort the array list, 0 for no sort * _allow_duplicates_: 1 to allow duplicate entries, 0 to prevent a same entry to be added again * _callback_cmp_: callback used to compare two items (optional), arguments and return value: ** _void *data_: pointer ** _struct t_arraylist *arraylist_: array list pointer ** _void *pointer1_: pointer to first item ** _void *pointer2_: pointer to second item ** return value: *** negative number if first item is less than second item *** 0 if first item equals second item *** positive number if first item is greater than second item * _callback_cmp_data_: pointer given to callback when it is called by WeeChat * _callback_free_: callback used to free an item (optional), arguments: ** _void *data_: pointer ** _struct t_arraylist *arraylist_: array list pointer ** _void *pointer_: pointer to item * _callback_free_data_: pointer given to callback when it is called by WeeChat Return value: * pointer to new array list C example: [source,c] ---- int cmp_cb (void *data, struct t_arraylist *arraylist, void *pointer1, void *pointer2) { if (...) return -1; else if (...) return 1; else return 0; } struct t_arraylist *list = weechat_arraylist_new (32, 1, 1, &cmp_cb, NULL, NULL, NULL); ---- [NOTE] This function is not available in scripting API. ==== arraylist_size _WeeChat ≥ 1.8._ Return size of array list (number of item pointers). Prototype: [source,c] ---- int weechat_list_size (struct t_arraylist *arraylist); ---- Arguments: * _arraylist_: array list pointer Return value: * size of array list (number of items), 0 if array list is empty C example: [source,c] ---- weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist)); ---- [NOTE] This function is not available in scripting API. ==== arraylist_get _WeeChat ≥ 1.8._ Return an item pointer by position. Prototype: [source,c] ---- void *weechat_arraylist_get (struct t_arraylist *arraylist, int index); ---- Arguments: * _arraylist_: array list pointer * _index_: index in list (first pointer is 0) Return value: * pointer found, NULL if pointer was not found C example: [source,c] ---- void *pointer = weechat_arraylist_get (arraylist, 0); /* first item */ ---- [NOTE] This function is not available in scripting API. ==== arraylist_search _WeeChat ≥ 1.8._ Search an item in an array list. Prototype: [source,c] ---- void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer, int *index, int *index_insert); ---- Arguments: * _arraylist_: array list pointer * _pointer_: pointer to the item to search in array list * _index_: pointer to integer that will be set to the index found, or -1 if not found (optional) * _index_insert_: pointer to integer that will be set with the index that must be used to insert the element in the arraylist (to keep arraylist sorted) (optional) Return value: * pointer to item found, NULL if item was not found C example: [source,c] ---- int index, index_insert; void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert); ---- [NOTE] This function is not available in scripting API. ==== arraylist_insert _WeeChat ≥ 1.8._ Insert an item in an array list. Prototype: [source,c] ---- int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer); ---- Arguments: * _arraylist_: array list pointer * _index_: position of the item in array list or -1 to add at the end (this argument is used only if the array list is not sorted, it is ignored if the array list is sorted) * _pointer_: pointer to the item to insert Return value: * index of new item (≥ 0), -1 if error. C example: [source,c] ---- int index = weechat_arraylist_insert (arraylist, -1, pointer); /* insert at the end if not sorted */ ---- [NOTE] This function is not available in scripting API. ==== arraylist_add _WeeChat ≥ 1.8._ Add an item in an array list. Prototype: [source,c] ---- int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer); ---- Arguments: * _arraylist_: array list pointer * _pointer_: pointer to the item to add Return value: * index of new item (≥ 0), -1 if error. C example: [source,c] ---- int index = weechat_arraylist_add (arraylist, pointer); ---- [NOTE] This function is not available in scripting API. ==== arraylist_remove _WeeChat ≥ 1.8._ Remove an item from an array list. Prototype: [source,c] ---- int weechat_arraylist_remove (struct t_arraylist *arraylist, int index); ---- Arguments: * _arraylist_: array list pointer * _index_: index of the item to remove Return value: * index of item removed, -1 if error. C example: [source,c] ---- int index_removed = weechat_arraylist_remove (arraylist, index); ---- [NOTE] This function is not available in scripting API. ==== arraylist_clear _WeeChat ≥ 1.8._ Remove all items from an array list. Prototype: [source,c] ---- int weechat_arraylist_clear (struct t_arraylist *arraylist); ---- Arguments: * _arraylist_: array list pointer Return value: * 1 if OK, 0 if error C example: [source,c] ---- if (weechat_arraylist_clear (arraylist)) { /* OK */ } ---- [NOTE] This function is not available in scripting API. ==== arraylist_free _WeeChat ≥ 1.8._ Free an array list. Prototype: [source,c] ---- void weechat_arraylist_free (struct t_arraylist *arraylist); ---- Arguments: * _arraylist_: array list pointer C example: [source,c] ---- weechat_arraylist_free (arraylist); ---- [NOTE] This function is not available in scripting API. [[hashtables]] === Hashtables Hashtable functions. ==== 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 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. ==== 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. ==== 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. ==== 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. ==== 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. ==== hashtable_map _WeeChat ≥ 0.3.3._ Call a function on all hashtable entries, by insertion order in the hashtable (from oldest to newest one). Prototype: [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. ==== hashtable_map_string _WeeChat ≥ 0.3.7._ Call a function on all hashtable entries, by insertion order in the hashtable (from oldest to newest one), sending keys and values as strings. Prototype: [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. ==== 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. ==== 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. ==== 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. ==== 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) { /* ... */ } void my_free_key_cb (struct t_hashtable *hashtable, void *key) { /* ... */ } weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb); weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb); ---- [NOTE] This function is not available in scripting API. ==== hashtable_add_to_infolist _WeeChat ≥ 0.3.3._ Add hashtable items to an infolist item, by insertion order in the hashtable (from oldest to newest one). Prototype: [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. ==== hashtable_add_from_infolist _WeeChat ≥ 2.2._ Add infolist items in a hashtable. Prototype: [source,c] ---- int weechat_hashtable_add_from_infolist (struct t_hashtable *hashtable, struct t_infolist *infolist, const char *prefix); ---- Arguments: * _hashtable_: hashtable pointer * _infolist_: infolist pointer * _prefix_: string used as prefix for names in infolist Return value: * 1 if OK, 0 if error C example: [source,c] ---- weechat_hashtable_add_from_infolist (hashtable, infolist, "testhash"); /* if infolist contains: "testhash_name_00000" = "key1" "testhash_value_00000" = "value 1" "testhash_name_00001" = "key2" "testhash_value_00001" = "value 2" then following variables will be added to hashtable: "key1" => "value 1" "key2" => "value 2" */ ---- [NOTE] This function is not available in scripting API. ==== hashtable_remove _WeeChat ≥ 0.3.3._ Remove an item from a hashtable. Prototype: [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. ==== hashtable_remove_all _WeeChat ≥ 0.3.3._ Remove all items from 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. ==== 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. ==== config_new _Updated in 1.5._ Create a new configuration file. Prototype: [source,c] ---- struct t_config_file *weechat_config_new (const char *name, int (*callback_reload)(const void *pointer, void *data, struct t_config_file *config_file), const void *callback_reload_pointer, void *callback_reload_data); ---- Arguments: * _name_: name of configuration file (without path or extension) * _callback_reload_: function called when configuration file is reloaded with `/reload` (optional, can be NULL, see below), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** return value: *** _WEECHAT_CONFIG_READ_OK_ *** _WEECHAT_CONFIG_READ_MEMORY_ERROR_ *** _WEECHAT_CONFIG_READ_FILE_NOT_FOUND_ * _callback_reload_pointer_: pointer given to callback when it is called by WeeChat * _callback_reload_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed Reload callback: * The callback must only call the function <<_config_reload,config_reload>>, it must not remove the configuration file. * A callback is needed only if it does some things before and/or after the call to the function <<_config_reload,config_reload>>. + If no callback is given, WeeChat will call its internal reload function, so the configuration file will be reloaded in all cases. Return value: * pointer to new configuration file, NULL if an error occurred [NOTE] File is NOT created on disk by this function. It will be created by call to function <<_config_write,config_write>>. You should call this function only after adding some sections (with <<_config_new_section,config_new_section>>) and options (with <<_config_new_option,config_new_option>>). C example: [source,c] ---- int my_config_reload_cb (const void *pointer, void *data, struct t_config_file *config_file) { /* ... */ return WEECHAT_RC_OK; } struct t_config_file *config_file = weechat_config_new ("test", &my_config_reload_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ... # example def my_config_reload_cb(data, config_file): # ... return weechat.WEECHAT_RC_OK config_file = weechat.config_new("test", "my_config_reload_cb", "") ---- ==== config_new_section _Updated in 1.5._ 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)(const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value), const void *callback_read_pointer, void *callback_read_data, int (*callback_write)(const void *pointer, void *data, struct t_config_file *config_file, const char *section_name), const void *callback_write_pointer, void *callback_write_data, int (*callback_write_default)(const void *pointer, void *data, struct t_config_file *config_file, const char *section_name), const void *callback_write_default_pointer, void *callback_write_default_data, int (*callback_create_option)(const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value), const void *callback_create_option_pointer, void *callback_create_option_data, int (*callback_delete_option)(const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, struct t_config_option *option), const void *callback_delete_option_pointer, void *callback_delete_option_data); ---- Arguments: * _config_file_: configuration file pointer * _name_: name of section * _user_can_add_options_: 1 if user can create new options in section, or 0 if it is forbidden * _user_can_delete_options_: 1 if user can delete options in section, or 0 if it is forbidden * _callback_read_: function called when an option in section is read from disk (should be NULL in most cases, except if options in section need custom function), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** _struct t_config_section *section_: section pointer ** _const char *option_name_: name of option ** _const char *value_: value ** return value: *** _WEECHAT_CONFIG_READ_OK_ *** _WEECHAT_CONFIG_READ_MEMORY_ERROR_ *** _WEECHAT_CONFIG_READ_FILE_NOT_FOUND_ * _callback_read_pointer_: pointer given to callback when it is called by WeeChat * _callback_read_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed * _callback_write_: function called when section is written in file (should be NULL for most cases, except if section needs to be written by a custom function), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** _struct t_config_section *section_: section pointer ** _const char *section_name_: name of section ** return value: *** _WEECHAT_CONFIG_WRITE_OK_ *** _WEECHAT_CONFIG_WRITE_ERROR_ *** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_ * _callback_write_pointer_: pointer given to callback when it is called by WeeChat * _callback_write_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed * _callback_write_default_: function called when default values for section must be written in file, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** _const char *section_name_: name of section ** return value: *** _WEECHAT_CONFIG_WRITE_OK_ *** _WEECHAT_CONFIG_WRITE_ERROR_ *** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_ * _callback_write_default_pointer_: pointer given to callback when it is called by WeeChat * _callback_write_default_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed * _callback_create_option_: function called when a new option is created in section (NULL if section does not allow new options to be created), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** _struct t_config_section *section_: section pointer ** _const char *option_name_: name of option ** _const char *value_: value ** return value: *** _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_ *** _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_ *** _WEECHAT_CONFIG_OPTION_SET_ERROR_ *** _WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND_ * _callback_create_option_pointer_: pointer given to callback when it is called by WeeChat * _callback_create_option_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed * _callback_delete_option_: function called when an option is deleted in section (NULL if section does not allow options to be deleted), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_file *config_file_: configuration file pointer ** _struct t_config_section *section_: section pointer ** _struct t_config_option *option_: option pointer ** return value: *** _WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET_ *** _WEECHAT_CONFIG_OPTION_UNSET_OK_RESET_ *** _WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED_ *** _WEECHAT_CONFIG_OPTION_UNSET_ERROR_ * _callback_delete_option_pointer_: pointer given to callback when it is called by WeeChat * _callback_delete_option_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed Return value: * pointer to new section in configuration file, NULL if an error occurred C example: [source,c] ---- int my_section_read_cb (const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value) { /* ... */ return WEECHAT_CONFIG_READ_OK; /* return WEECHAT_CONFIG_READ_MEMORY_ERROR; */ /* return WEECHAT_CONFIG_READ_FILE_NOT_FOUND; */ } int my_section_write_cb (const void *pointer, void *data, struct t_config_file *config_file, const char *section_name) { /* ... */ return WEECHAT_CONFIG_WRITE_OK; /* return WEECHAT_CONFIG_WRITE_ERROR; */ /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */ } int my_section_write_default_cb (const void *pointer, void *data, struct t_config_file *config_file, const char *section_name) { /* ... */ return WEECHAT_CONFIG_WRITE_OK; /* return WEECHAT_CONFIG_WRITE_ERROR; */ /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */ } int my_section_create_option_cb (const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, const char *option_name, const char *value) { /* ... */ return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED; /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */ /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */ /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */ } int my_section_delete_option_cb (const void *pointer, void *data, struct t_config_file *config_file, struct t_config_section *section, struct t_config_option *option) { /* ... */ return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED; /* return WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET; */ /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */ /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */ } /* standard section, user can not add/delete options */ struct t_config_section *new_section1 = weechat_config_new_section (config_file, "section1", 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); /* special section, user can add/delete options, and options need callback to be read/written */ struct t_config_section *new_section2 = weechat_config_new_section (config_file, "section2", 1, 1, &my_section_read_cb, NULL, NULL, &my_section_write_cb, NULL, NULL, &my_section_write_default_cb, NULL, NULL, &my_section_create_option_cb, NULL, NULL, &my_section_delete_option_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def config_new_section(config_file: str, name: str, user_can_add_options: int, user_can_delete_options: int, callback_read: str, callback_read_data: str, callback_write: str, callback_write_data: str, callback_write_default: str, callback_write_default_data: str, callback_create_option: str, callback_create_option_data: str, callback_delete_option: str, callback_delete_option_data: str) -> str: ... # example def my_section_read_cb(data, 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", "") ---- ==== 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 def config_search_section(config_file: str, section_name: str) -> str: ... # example section = weechat.config_search_section(config_file, "section") ---- ==== config_new_option _Updated in 1.5._ 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)(const void *pointer, void *data, struct t_config_option *option, const char *value), const void *callback_check_value_pointer, void *callback_check_value_data, void (*callback_change)(const void *pointer, void *data, struct t_config_option *option), const void *callback_change_pointer, void *callback_change_data, void (*callback_delete)(const void *pointer, void *data, struct t_config_option *option), const void *callback_delete_pointer, void *callback_delete_data); ---- Arguments: * _config_file_: configuration file pointer * _section_: section pointer * _name_: name of option; with WeeChat ≥ 1.4, the name can include a parent option name (the value of parent option will be displayed in `/set` command output if this option is "null"), the syntax is then: "name << file.section.option" * _type_: type of option: ** _boolean_: boolean value (on/off) ** _integer_: integer value (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: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_option *option_: option pointer ** _const char *value_: new value for option ** return value: *** 1 if value is OK *** 0 if value is invalid * _callback_check_value_pointer_: pointer given to check_value callback when it is called by WeeChat * _callback_check_value_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed * _callback_change_: function called when value of option has changed (optional), arguments: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_option *option_: option pointer * _callback_change_pointer_: pointer given to change callback when it is called by WeeChat * _callback_change_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed * _callback_delete_: function called when option will be deleted (optional), arguments: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_config_option *option_: option pointer * _callback_delete_pointer_: pointer given to delete callback when it is called by WeeChat * _callback_delete_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed Return value: * pointer to new option in section, NULL if an error C example: [source,c] ---- /* boolean */ struct t_config_option *option1 = weechat_config_new_option (config_file, section, "option1", "boolean", "My option, type boolean", NULL, 0, 0, "on", "on", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); /* integer */ struct t_config_option *option2 = weechat_config_new_option (config_file, section, "option2", "integer", "My option, type integer", NULL, 0, 100, "15", "15", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); /* 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", 0, 0, "bottom", "bottom", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); /* string */ struct t_config_option *option4 = weechat_config_new_option (config_file, section, "option4", "string", "My option, type string", NULL, 0, 0, "test", "test", 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); /* color */ struct t_config_option *option5 = weechat_config_new_option (config_file, section, "option5", "color", "My option, type color", NULL, 0, 0, "lightblue", "lightblue", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def config_new_option(config_file: str, section: str, name: str, type: str, description: str, string_values: str, min: int, max: int, default_value: str | None, value: str | None, null_value_allowed: int, callback_check_value: str, callback_check_value_data: str, callback_change: str, callback_change_data: str, callback_delete: str, callback_delete_data: str) -> str: ... # example def 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 link:++weechat_scripting.en.html#_ruby++[WeeChat scripting guide ^↗^,window=_blank] for more info _(fixed in version 0.4.1)_. ==== 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 def config_search_option(config_file: str, section: str, option_name: str) -> str: ... # example option = weechat.config_search_option(config_file, section, "option") ---- ==== config_search_section_option Search a section and an option in a configuration file or section. Prototype: [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. ==== 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. ==== 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 def config_string_to_boolean(text: str) -> int: ... # example if weechat.config_string_to_boolean(text): # ... ---- ==== config_option_reset Reset an option to its default value. Prototype: [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 def config_option_reset(option: str, run_callback: int) -> int: ... # example rc = weechat.config_option_reset(option, 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ... ---- ==== config_option_set Set new value for an option. Prototype: [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, special values are possible according to the type of option: ** _boolean_: *** `toggle`: toggle the current value ** _integer_ or _color_: *** `++N`: add `N` (any integer) to the current value *** `--N`: subtract `N` (any integer) from the current value * _run_callback_: 1 for calling change callback if value of option is changed, otherwise 0 Return value: * _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_ if option value has been changed * _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_ if value was not changed * _WEECHAT_CONFIG_OPTION_SET_ERROR_ if an error occurred C example: [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 def config_option_set(option: str, value: str, run_callback: int) -> int: ... # example rc = weechat.config_option_set(option, "new_value", 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ... ---- ==== config_option_set_null Set null (undefined value) for an option. Prototype: [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 <<_config_new_option,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 def config_option_set_null(option: str, run_callback: int) -> int: ... # example rc = weechat.config_option_set_null(option, 1) if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ... ---- ==== config_option_unset Unset/reset option. Prototype: [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 def config_option_unset(option: str) -> int: ... # example rc = weechat.config_option_unset(option) if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR: # ... ---- ==== config_option_rename Rename an option. Prototype: [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 def config_option_rename(option: str, new_name: str) -> int: ... # example weechat.config_option_rename(option, "new_name") ---- ==== config_option_get_string _WeeChat ≥ 1.9._ Return string value of an option property. Prototype: [source,c] ---- const char *weechat_config_option_get_string (struct t_config_option *option, const char *property); ---- Arguments: * _option_: option pointer * _property_: property name: ** _config_name_: file name ** _section_name_: section name ** _name_: option name ** _parent_name_: name of parent option ** _type_: option type, one of: *** _boolean_ *** _integer_ *** _string_ *** _color_ ** _description_: option description Return value: * string value of property C example: [source,c] ---- const char *type = weechat_config_option_get_string (option, "type"); ---- [NOTE] This function is not available in scripting API. ==== config_option_get_pointer Return a pointer on an option property. Prototype: [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 *_) ** _parent_name_: name of parent option (_char *_) _(WeeChat ≥ 1.4)_ ** _type_: option type (_int *_) ** _description_: option description (_char *_) ** _string_values_: string values (_char *_) ** _min_: minimum value (_int *_) ** _max_: maximum value (_int *_) ** _default_value_: default value (depends on type) ** _value_: current value (depends on type) ** _prev_option_: previous option pointer (_struct t_config_option *_) ** _next_option_: next option pointer (_struct t_config_option *_) Return value: * pointer to property asked C example: [source,c] ---- char *description = weechat_config_option_get_pointer (option, "description"); ---- [NOTE] This function is not available in scripting API. ==== config_option_is_null Check if an option is "null" (undefined value). Prototype: [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 def config_option_is_null(option: str) -> int: ... # example if weechat.config_option_is_null(option): # ... ---- ==== config_option_default_is_null Check if default value for an option is "null" (undefined value). Prototype: [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 def config_option_default_is_null(option: str) -> int: ... # example if weechat.config_option_default_is_null(option): # ... ---- ==== config_boolean Return boolean value of option. Prototype: [source,c] ---- int weechat_config_boolean (struct t_config_option *option); ---- Arguments: * _option_: option pointer Return value, depending on the option type: * _boolean_: boolean value of option (0 or 1) * _integer_: 0 * _string_: 0 * _color_: 0 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 def config_boolean(option: str) -> int: ... # example option = weechat.config_get("plugin.section.option") if weechat.config_boolean(option): # ... ---- ==== config_boolean_default Return default boolean value of option. Prototype: [source,c] ---- int weechat_config_boolean_default (struct t_config_option *option); ---- Arguments: * _option_: option pointer Return value, depending on the option type: * _boolean_: default boolean value of option (0 or 1) * _integer_: 0 * _string_: 0 * _color_: 0 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 def config_boolean_default(option: str) -> int: ... # example option = weechat.config_get("plugin.section.option") if weechat.config_boolean_default(option): # ... ---- ==== 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, depending on the option type: * _boolean_: boolean value of option (0 or 1) * _integer_: integer value of option * _string_: 0 * _color_: color index 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 def config_integer(option: str) -> int: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_integer(option) ---- ==== config_integer_default Return default integer value of option. Prototype: [source,c] ---- int weechat_config_integer_default (struct t_config_option *option); ---- Arguments: * _option_: option pointer Return value, depending on the option type: * _boolean_: default boolean value of option (0 or 1) * _integer_: default integer value of option * _string_: 0 * _color_: default color index 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 def config_integer_default(option: str) -> int: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_integer_default(option) ---- ==== 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, depending on the option type: * _boolean_: "on" if value is true, otherwise "off" * _integer_: string value if the option is an integer with string values, otherwise NULL * _string_: string value of option * _color_: name of color 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 def config_string(option: str) -> str: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_string(option) ---- ==== config_string_default Return default string value of option. Prototype: [source,c] ---- const char *weechat_config_string_default (struct t_config_option *option); ---- Arguments: * _option_: option pointer Return value, depending on the option type: * _boolean_: "on" if default value is true, otherwise "off" * _integer_: default string value if the option is an integer with string values, otherwise NULL * _string_: default string value of option * _color_: name of default color 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 def config_string_default(option: str) -> str: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_string_default(option) ---- ==== 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, depending on the option type: * _boolean_: NULL * _integer_: NULL * _string_: NULL * _color_: 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 def config_color(option: str) -> str: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_color(option) ---- ==== 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, depending on the option type: * _boolean_: NULL * _integer_: NULL * _string_: NULL * _color_: name of default 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 def config_color_default(option: str) -> str: ... # example option = weechat.config_get("plugin.section.option") value = weechat.config_color_default(option) ---- ==== config_write_option Write a line in a configuration file with option and its value (this function should be called only in "write" or "write_default" callbacks for a section). Prototype: [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 (const void *pointer, void *data, struct t_config_file *config_file, const char *section_name) { weechat_config_write_line (config_file, "my_section", NULL); weechat_config_write_option (config_file, option); return WEECHAT_RC_OK; } ---- Script (Python): [source,python] ---- # prototype def config_write_option(config_file: str, option: str) -> int: ... # 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 ---- ==== 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 (const void *pointer, void *data, struct t_config_file *config_file, const char *section_name) { weechat_config_write_line (config_file, "my_section", NULL); weechat_config_write_line (config_file, "option", "%s;%d", "value", 123); return WEECHAT_RC_OK; } ---- Script (Python): [source,python] ---- # prototype def config_write_line(config_file: str, option_name: str, value: str) -> int: ... # 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 ---- ==== 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 def config_write(config_file: str) -> int: ... # example rc = weechat.config_write(config_file) if rc == weechat.WEECHAT_CONFIG_WRITE_OK: # ... elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR: # ... ---- ==== config_read Read configuration file from disk. Prototype: [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 def config_read(config_file: str) -> int: ... # example rc = weechat.config_read(config_file) if rc == weechat.WEECHAT_CONFIG_READ_OK: # ... elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND: # ... ---- ==== config_reload Reload configuration file from disk. Prototype: [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 def config_reload(config_file: str) -> int: ... # example rc = weechat.config_reload(config_file) if rc == weechat.WEECHAT_CONFIG_READ_OK: # ... elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR: # ... elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND: # ... ---- ==== config_option_free Free an option. Prototype: [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 def config_option_free(option: str) -> int: ... # example weechat.config_option_free(option) ---- ==== 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 def config_section_free_options(section: str) -> int: ... # example weechat.config_section_free_options(section) ---- ==== 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 def config_section_free(section: str) -> int: ... # example weechat.config_section_free(section) ---- ==== 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 def config_free(config_file: str) -> int: ... # example weechat.config_free(config_file) ---- ==== 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 def config_get(option_name: str) -> str: ... # example option = weechat.config_get("weechat.look.item_time_format") ---- ==== config_get_plugin Search an option in plugins configuration file (plugins.conf). Prototype: [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 def config_get_plugin(option_name: str) -> str: ... # example value = weechat.config_get_plugin("option") ---- ==== config_is_set_plugin Check if option is set in plugins configuration file (plugins.conf). Prototype: [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 def config_is_set_plugin(option_name: str) -> int: ... # example if weechat.config_is_set_plugin("option"): # option is set # ... else: # option does not exist # ... ---- ==== config_set_plugin Set new value for option in plugins configuration file (plugins.conf). Prototype: [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 def config_set_plugin(option_name: str, value: str) -> int: ... # example rc = weechat.config_set_plugin("option", "test_value") if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR: # ... ---- ==== config_set_desc_plugin _WeeChat ≥ 0.3.5._ Set description for option in plugins configuration file (plugins.conf). Prototype: [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 def config_set_desc_plugin(option_name: str, description: str) -> int: ... # example version = weechat.info_get("version_number", "") or 0 if int(version) >= 0x00030500: weechat.config_set_desc_plugin("option", "description of option") ---- ==== config_unset_plugin Unset option in plugins configuration file (plugins.conf). Prototype: [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 def config_unset_plugin(option_name: str) -> int: ... # example rc = weechat.config_unset_plugin("option") if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: # ... elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR: # ... ---- [[key_bindings]] === Key bindings Functions for key bindings. ==== key_bind _WeeChat ≥ 0.3.6, updated in 1.8._ Add new key bindings. [NOTE] Unlike command `/key bind`, this function will never change an existing key binding, only new keys are created. To remove a key binding, use <<_key_unbind,key_unbind>>. Prototype: [source,c] ---- int weechat_key_bind (const char *context, struct t_hashtable *keys); ---- :key_bind_quiet: __quiet Arguments: * _context_: context for keys: ** _default_: default context (common actions) ** _search_: search context (when searching text in buffer) ** _cursor_: free movement of cursor on screen ** _mouse_: keys for mouse events * _keys_: hashtable with key bindings; it can contain following special keys: ** _{key_bind_quiet}_: do not display the keys added in _core_ buffer _(WeeChat ≥ 1.8)_ 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 def key_bind(context: str, keys: Dict[str, str]) -> int: ... # example keys = {"@chat(python.test):button1": "hsignal:test_mouse", "@chat(python.test):wheelup": "/mycommand up", "@chat(python.test):wheeldown": "/mycommand down"} weechat.key_bind("mouse", keys) ---- ==== key_unbind _WeeChat ≥ 0.3.6, updated in 2.0._ Remove key binding(s). [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 <<_key_bind,key_bind>>) * _key_: key to remove or a special value "area:XXX" to remove all keys having _XXX_ as first or second area; if the key starts with "quiet:", the keys removed are not displayed in _core_ buffer _(WeeChat ≥ 2.0)_. Return value: * number of key bindings removed C examples: [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 def key_unbind(context: str, key: str) -> int: ... # examples # remove a single key weechat.key_unbind("mouse", "@chat(plugin.buffer):button1") # remove all keys with area "chat(python.test)" weechat.key_unbind("mouse", "area:chat(python.test)") ---- [[display]] === Display Functions to display text in buffers. ==== 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="100%",cols="^2m,^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 def prefix(prefix: str) -> str: ... # example weechat.prnt("", "%sThis is an error..." % weechat.prefix("error")) ---- ==== 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 color option name (from weechat.color.xxx), for example _chat_delimiters_ ** option name (format: file.section.option), for example _irc.color.message_quit_ _(WeeChat ≥ 1.2)_ ** color with optional attributes/background (see below) ** attribute: *** _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 def color(color_name: str) -> str: ... # example weechat.prnt("", "Color: %sblue %sdefault color %syellow on red" % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red"))) ---- ==== printf Display a message on a buffer. Prototype: [source,c] ---- void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...); ---- This function is a shortcut for function printf_date_tags. These two calls give exactly same result: [source,c] ---- weechat_printf (buffer, "message"); weechat_printf_date_tags (buffer, 0, NULL, "message"); ---- Arguments: * _buffer_: buffer pointer, if NULL, message is displayed on WeeChat buffer * _message_: message to display [NOTE] The first tabulation in message ("\t") is used to separate prefix from message. + If your message has some tabs and if you don't want prefix, then use a space, a tab, then message (see example below): this will disable prefix (the space before tab will not be displayed). [NOTE] With two tabs ("\t") at beginning of message, time will not be displayed and message will have no alignment at all. Moreover, the date in message will be set to 0. C example: [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 def prnt(buffer: str, message: str) -> int: ... # example weechat.prnt("", "Hello on WeeChat buffer") weechat.prnt(buffer, "Hello on this buffer") weechat.prnt(buffer, "%sThis is an error!" % weechat.prefix("error")) weechat.prnt(buffer, " \tMessage without prefix but with \t some \t tabs") weechat.prnt(buffer, "\t\tMessage without time/alignment") weechat.prnt(buffer, "\t\t") # empty line (without time) ---- [NOTE] Function is called "print" in scripts ("prnt" in Python). ==== printf_date_tags Display a message on a buffer, using a custom date and tags. Prototype: [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 (NULL means no tags) * _message_: message to display See the link:weechat_user.en.html#lines_tags[WeeChat user's guide / Lines tags ^↗^,window=_blank] for a list of commonly used tags in WeeChat. 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 def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ... # example time = int(time.time()) weechat.prnt_date_tags("", time - 120, "notify_message", "Message 2 minutes ago, with a tag 'notify_message'") ---- [NOTE] Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python). ==== printf_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 def prnt_y(buffer: str, y: int, message: str) -> int: ... # example weechat.prnt_y("", 2, "My message on third line") ---- [NOTE] Function is called "print_y" in scripts ("prnt_y" in Python). ==== printf_y_date_tags _WeeChat ≥ 3.5._ Display a message on a line of a buffer with free content, using a custom date and tags. Prototype: [source,c] ---- void weechat_printf_y_date_tags (struct t_gui_buffer *buffer, int y, time_t date, const char *tags, const char *message, ...); ---- Arguments: * _buffer_: buffer pointer * _y_: line number (first line is 0); a negative value adds a line after last line displayed: absolute value of _y_ is the number of lines after last line (for example -1 is immediately after last line, -2 is 2 lines after last line) * _date_: date for message (0 means current date/time) * _tags_: comma separated list of tags (NULL means no tags) * _message_: message to display C example: [source,c] ---- weechat_printf_y_date_tags (buffer, 2, 0, "my_tag", "My message on third line with a tag"); ---- Script (Python): [source,python] ---- # prototype def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ... # example weechat.prnt_y_date_tags("", 2, 0, "my_tag", "My message on third line with a tag") ---- [NOTE] Function is called "print_y_date_tags" in scripts ("prnt_y_date_tags" in Python). ==== 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 def log_print(message: str) -> int: ... # 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). + Only a single priority per hook is allowed. Default priority is 1000. C examples: [source,c] ---- /* hook modifier with priority = 2000 */ /* high priority: called before other modifier calbacks */ weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL); /* hook two signals with priority = 3000 */ /* high priority: called before other signal callbacks */ weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL); /* hook lines printed in formatted buffers with priority = 500 */ /* low priority: called after other line callbacks */ weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL); ---- Following hook types allow priority: * <<_hook_command,command>> * <<_hook_completion,completion>> * <<_hook_command_run,command_run>> * <<_hook_line,line>> * <<_hook_signal,signal>> * <<_hook_hsignal,hsignal>> * <<_hook_config,config>> * <<_hook_modifier,modifier>> * <<_hook_info,info>> * <<_hook_info_hashtable,info_hashtable>> * <<_hook_infolist,infolist>> * <<_hook_hdata,hdata>> * <<_hook_focus,focus>> ==== hook_command _Updated in 1.5, 1.7._ 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)(const void *pointer, void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol), const void *callback_pointer, void *callback_data); ---- Arguments: * _command_: command name (a priority is allowed before the command, see note about <>) * _description_: description for command (displayed with `/help command`) * _args_: arguments for command (displayed with `/help command`) * _args_description_: description of arguments (displayed with `/help command`) * _completion_: completion template for command (see format below) * _callback_: function called when command is used, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer where command is executed ** _int argc_: number of arguments given for command ** _char **argv_: arguments given for command ** _char **argv_eol_: arguments given for command (until end of line for each argument) ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted The _completion_ template is a list of completions for each argument, separated by spaces. Many completions are possible for one argument, separated by `+|+`. Many templates are possible for same command, separated by `+||+`. The format of a completion can be: * _%(name)_: the completion _name_ * _%(name:arguments)_: the completion _name_ with _arguments_ sent to the callback _(WeeChat ≥ 1.7)_ * any string: it is used as-is in completion For example the template `list || add %(filters_names) || del %(filters_names)|-all` will complete with following values in command arguments: * first argument: `list`, `add` and `del` * second argument, depending on first argument: ** `list`: nothing ** `add`: names of filters ** `del`: names of filters and `-all` Default completion codes are: include::includes/autogen_api_completions.en.adoc[tag=completions] 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 (const void *pointer, void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* ... */ return WEECHAT_RC_OK; } /* this example is inspired by command /filter */ struct t_hook *my_command_hook = weechat_hook_command ("myfilter", "description of myfilter", "[list] | [enable|disable|toggle [name]] | " "[add name plugin.buffer tags regex] | " "[del name|-all]", "description of arguments...", "list" " || enable %(filters_names)" " || disable %(filters_names)" " || toggle %(filters_names)" " || add %(filters_names) %(buffers_plugins_names)|*" " || del %(filters_names)|-all", &my_command_cb, NULL, NULL); ---- For example, if command called is `/command abc def ghi`, then _argv_ and _argv_eol_ have following values: * _argv_: ** _argv[0]_ == "/command" ** _argv[1]_ == "abc" ** _argv[2]_ == "def" ** _argv[3]_ == "ghi" * _argv_eol_: ** _argv_eol[0]_ == "/command abc def ghi" ** _argv_eol[1]_ == "abc def ghi" ** _argv_eol[2]_ == "def ghi" ** _argv_eol[3]_ == "ghi" For scripts, _args_ has value "abc def ghi". Script (Python): [source,python] ---- # prototype def hook_command(command: str, description: str, args: str, args_description: str, completion: str, callback: str, callback_data: str) -> str: ... # example def my_command_cb(data, buffer, args): # ... return weechat.WEECHAT_RC_OK hook = weechat.hook_command("myfilter", "description of myfilter", "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]", "description of arguments...", "list" " || enable %(filters_names)" " || disable %(filters_names)" " || toggle %(filters_names)" " || add %(filters_names) %(buffers_plugins_names)|*" " || del %(filters_names)|-all", "my_command_cb", "") ---- ==== hook_completion _Updated in 1.5, 1.7._ Hook a completion. Prototype: [source,c] ---- struct t_hook *weechat_hook_completion (const char *completion_item, const char *description, int (*callback)(const void *pointer, void *data, const char *completion_item, struct t_gui_buffer *buffer, struct t_gui_completion *completion), const void *callback_pointer, void *callback_data); ---- Arguments: * _completion_item_: name of completion item, after you can use _%(name)_ (or _%(name:arguments)_ with WeeChat ≥ 1.7) in a command hooked (argument _completion_) (a priority is allowed before the completion item, see note about <>) * _description_: description of completion * _callback_: function called when completion item is used (user is completing something using this item), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *completion_item_: name of completion item (with WeeChat ≥ 1.7 it can include arguments, with the format: _name:arguments_) ** _struct t_gui_buffer *buffer_: buffer where completion is made ** _struct t_gui_completion *completion_: structure used to add words for completion (see <<_completion_list_add,completion_list_add>>) ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted [NOTE] Completion names are global (shared across WeeChat and plugins). So it is recommended to choose a name with a unique prefix, like "plugin_xxx" (where "xxx" is your item name). [IMPORTANT] The callback must only call completion functions like <<_completion_list_add,completion_list_add>> and must *NOT* update the command line. + To update the command line when kbd:[Tab] is pressed, you can use the function <<_hook_command_run,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 (const void *pointer, void *data, const char *completion_item, struct t_gui_buffer *buffer, struct t_gui_completion *completion) { weechat_completion_list_add (completion, "word1", 0, WEECHAT_LIST_POS_SORT); weechat_completion_list_add (completion, "test_word2", 0, WEECHAT_LIST_POS_SORT); return WEECHAT_RC_OK; } struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item", "my custom completion!", &my_completion_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ... # example def my_completion_cb(data, completion_item, buffer, completion): weechat.completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT) weechat.completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT) return weechat.WEECHAT_RC_OK hook = weechat.hook_completion("plugin_item", "my custom completion!", "my_completion_cb", "") ---- ==== hook_completion_get_string _WeeChat ≥ 0.3.4._ *Deprecated since WeeChat 2.9* (still there for compatibility). + This function has been replaced by <<_completion_get_string,completion_get_string>>. ==== hook_completion_list_add *Deprecated since WeeChat 2.9* (still there for compatibility). + This function has been replaced by <<_completion_list_add,completion_list_add>>. ==== hook_command_run _Updated in 1.5._ Hook a command when WeeChat runs it. Prototype: [source,c] ---- struct t_hook *weechat_hook_command_run (const char *command, int (*callback)(const void *pointer, void *data, struct t_gui_buffer *buffer, const char *command), const void *callback_pointer, void *callback_data); ---- Arguments: * _command_: command to hook (wildcard `+*+` is allowed) (a priority is allowed before the command, see note about <>) * _callback_: function called when command is run, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer where command is executed ** _const char *command_: the command executed, with its arguments ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_OK_EAT_: command will not be executed by WeeChat after callback *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- int my_command_run_cb (const void *pointer, void *data, struct t_gui_buffer *buffer, const char *command) { weechat_printf (NULL, "I'm eating the completion!"); return WEECHAT_RC_OK_EAT; } struct t_hook *my_command_run_hook = weechat_hook_command_run ("/input complete*", &my_command_run_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_command_run(command: str, callback: str, callback_data: str) -> str: ... # example def my_command_run_cb(data, buffer, command): weechat.prnt("", "I'm eating the completion!") return weechat.WEECHAT_RC_OK_EAT hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "") ---- ==== hook_timer _Updated in 1.5._ Hook a timer. Prototype: [source,c] ---- struct t_hook *weechat_hook_timer (long interval, int align_second, int max_calls, int (*callback)(const void *pointer, void *data, int remaining_calls), const void *callback_pointer, void *callback_data); ---- Arguments: * _interval_: interval between two calls (milliseconds, so 1000 = 1 second) * _align_second_: alignment on a second. For example, if current time is 09:00, if interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute when second is 0 * _max_calls_: number of calls to timer (if 0, then timer has no end) * _callback_: function called when time is reached, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _int remaining_calls_: remaining calls (-1 if timer has no end) ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- int my_timer_cb (const void *pointer, void *data, int remaining_calls) { /* ... */ return WEECHAT_RC_OK; } /* timer called each 20 seconds */ struct t_hook *my_timer_hook = weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_timer(interval: int, align_second: int, max_calls: int, callback: str, callback_data: str) -> str: ... # example def my_timer_cb(data, remaining_calls): # ... return weechat.WEECHAT_RC_OK # timer called each 20 seconds hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "") ---- ==== hook_fd _Updated in 1.3, 1.5, 2.0._ Hook a file descriptor (file or socket). Prototype: [source,c] ---- struct t_hook *weechat_hook_fd (int fd, int flag_read, int flag_write, int flag_exception, int (*callback)(const void *pointer, void *data, int fd), const void *callback_pointer, void *callback_data); ---- Arguments: * _fd_: file descriptor * _flag_read_: 1 = catch read event, 0 = ignore * _flag_write_: 1 = catch write event, 0 = ignore * _flag_exception_: 1 = catch exception event, 0 = ignore (_WeeChat ≥ 1.3_: this argument is ignored and not used any more) * _callback_: function called a selected event occurs for file (or socket), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _int fd_: file descriptor ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred [IMPORTANT] In scripts, with WeeChat ≥ 2.0, the callback argument _fd_ is an integer (with WeeChat ≤ 1.9, it was a string). + To be compatible with all versions, it is recommended to convert the argument to integer before using it, for example in Python: `int(fd)`. C example: [source,c] ---- int my_fd_cb (const void *pointer, void *data, int fd) { /* ... */ return WEECHAT_RC_OK; } int sock = socket (AF_INET, SOCK_STREAM, 0); /* set socket options */ /* ... */ struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_fd(fd: int, flag_read: int, flag_write: int, flag_exception: int, callback: str, callback_data: str) -> str: ... # example def my_fd_cb(data, fd): # ... return weechat.WEECHAT_RC_OK sock = ... hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "") ---- ==== hook_process _Updated in 1.5._ Hook a process (launched with fork), and catch output. [NOTE] Since version 0.3.9.2, the shell is not used 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 <<_hook_process_hashtable,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)(const void *pointer, void *data, const char *command, int return_code, const char *out, const char *err), const void *callback_pointer, void *callback_data); ---- Arguments: * _command_: command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or function _(WeeChat ≥ 1.5)_ (see below) * _timeout_: timeout for command (in milliseconds): after this timeout, child process is killed (0 means no timeout) * _callback_: function called when data from child is available, or when child has ended, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *command_: command executed by child ** _int return_code_: return code: *** _≥ 0_: child return code for a command, and for URL possible values are: **** _0_: transfer OK **** _1_: invalid URL **** _2_: transfer error **** _3_: not enough memory **** _4_: error with a file *** _< 0_: **** _WEECHAT_HOOK_PROCESS_RUNNING_ (-1): data available, but child still running **** _WEECHAT_HOOK_PROCESS_ERROR_ (-2): error when launching command **** _WEECHAT_HOOK_PROCESS_CHILD_ (-3): callback is called in the child process (used only in C API, not scripting API) ** _out_: standard output of command (stdout) ** _err_: error output of command (stderr) ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ *** child process return code (in case of function with "func:" in command) * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred When command has ended, or if timeout is reached, WeeChat will automatically unhook (and kill process if it is still running). The command can be an URL with format: "url:https://www.example.com", to download content of URL _(WeeChat ≥ 0.3.7)_. Options are possible for URL with function <<_hook_process_hashtable,hook_process_hashtable>>. The command can also be a function name with format: "func:name", to execute the function "name" _(WeeChat ≥ 1.5)_. This function receives a single argument (_data_) and must return a string, which is sent to the callback. + In C API, the callback is called with the return code set to _WEECHAT_HOOK_PROCESS_CHILD_, which means the callback is running in the child process (after fork). + In scripting API, the function _name_ is called directly and its result (string) is sent to the callback (like the output of an external command). [TIP] If you want to retrieve infos about WeeChat (like current stable version, latest git commit, etc.), you can use URLs on https://weechat.org/dev/info/[this page ^↗^,window=_blank]. [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] ---- /* example with an external command */ int my_process_cb (const void *pointer, void *data, const char *command, int return_code, const char *out, const char *err) { if (return_code == WEECHAT_HOOK_PROCESS_ERROR) { weechat_printf (NULL, "Error with command '%s'", command); return WEECHAT_RC_OK; } if (return_code >= 0) { weechat_printf (NULL, "return_code = %d", return_code); } if (out) { weechat_printf (NULL, "stdout: %s", out); } if (err) { weechat_printf (NULL, "stderr: %s", err); } return WEECHAT_RC_OK; } struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000, &my_process_cb, NULL, NULL); /* example with the callback called in the child process */ int my_process_func_cb (const void *pointer, void *data, const char *command, int return_code, const char *out, const char *err) { if (return_code == WEECHAT_HOOK_PROCESS_CHILD) { /* do something blocking... */ /* ... */ /* the stdout will be sent as "out" in the parent callback */ printf ("this is the result"); /* return code of the process */ return 0; } else { if (return_code == WEECHAT_HOOK_PROCESS_ERROR) { weechat_printf (NULL, "Error with command '%s'", command); return WEECHAT_RC_OK; } if (return_code >= 0) { weechat_printf (NULL, "return_code = %d", return_code); } if (out) { weechat_printf (NULL, "stdout: %s", out); } if (err) { weechat_printf (NULL, "stderr: %s", err); } return WEECHAT_RC_OK; } } struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000, &my_process_func_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_process(command: str, timeout: int, callback: str, callback_data: str) -> str: ... # example with an external command def my_process_cb(data, 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", "") # example with a script function def get_status(data): # do something blocking... # ... return "this is the result" 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("func:get_status", 5000, "my_process_cb", "") ---- ==== hook_process_hashtable _WeeChat ≥ 0.3.7, updated in 1.5._ Hook a process (launched with fork) using options in a hashtable, and catch output. Prototype: [source,c] ---- struct t_hook *weechat_hook_process_hashtable (const char *command, struct t_hashtable *options, int timeout, int (*callback)(const void *pointer, void *data, const char *command, int return_code, const char *out, const char *err), const void *callback_pointer, void *callback_data); ---- Arguments are the same as function <<_hook_process,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,1,1,5",options="header"] |=== | Option | Min WeeChat | Value | Default | Description | argN (N ≥ 1) | 0.4.0 | any string | no arguments | Arguments for command; if no argument is given with these options, the command is automatically split like the shell does (and then command arguments are read in the _command_ argument). | stdin | 0.4.3 | (not used) | no stdin | Create a pipe for writing data on standard input (stdin) of child process (see function <<_hook_set,hook_set>>). | buffer_flush | 1.0 | number of bytes | 65536 | Minimum number of bytes to flush stdout/stderr (to send output to callback), between 1 and 65536. With the value 1, the output is sent immediately to the callback. | detached | 1.0 | (not used) | not detached | Run the process in a detached mode: stdout and stderr are redirected to _/dev/null_. |=== For command "url:...", following options are available (see `+man curl_easy_setopt+` for a description of each option): include::includes/autogen_api_url_options.en.adoc[tag=url_options] [NOTE] ^(1)^ For options with type "mask", format is: "value1+value2+value3"; for options with type "list", the list items must be separated by a newline (`\n`). + ^(2)^ When constants are available they must be used as value for option. 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 (const void *pointer, void *data, const char *command, int return_code, const char *out, const char *err) { if (return_code == WEECHAT_HOOK_PROCESS_ERROR) { weechat_printf (NULL, "Error with command '%s'", command); return WEECHAT_RC_OK; } if (return_code >= 0) { weechat_printf (NULL, "return_code = %d", return_code); } if (out) { weechat_printf (NULL, "stdout: %s", out); } if (err) { weechat_printf (NULL, "stderr: %s", err); } return WEECHAT_RC_OK; } /* example 1: download URL */ struct t_hashtable *options_url1 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); if (options_url1) { weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html"); struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/", options_url1, 20000, &my_process_cb, NULL, NULL); weechat_hashtable_free (options_url1); } /* example 2: open URL with custom HTTP headers */ struct t_hashtable *options_url2 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); if (options_url2) { weechat_hashtable_set (options_url2, "httpheader", "Header1: value1\n" "Header2: value2"); struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://localhost:8080/", options_url2, 20000, &my_process_cb, NULL, NULL); weechat_hashtable_free (options_url2); } /* example 3: execute a notify program with a message from someone */ struct t_hashtable *options_cmd1 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); if (options_cmd1) { weechat_hashtable_set (options_cmd1, "arg1", "-from"); weechat_hashtable_set (options_cmd1, "arg2", nick); weechat_hashtable_set (options_cmd1, "arg3", "-msg"); weechat_hashtable_set (options_cmd1, "arg4", message); /* untrusted argument */ struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command", options_cmd1, 20000, &my_process_cb, NULL, NULL); weechat_hashtable_free (options_cmd1); } /* example 4: call shell to execute a command (command must be SAFE) */ struct t_hashtable *options_cmd2 = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); if (options_cmd2) { weechat_hashtable_set (options_cmd2, "arg1", "-c"); weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something"); struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh", options_cmd2, 20000, &my_process_cb, NULL, NULL); weechat_hashtable_free (options_cmd2); } ---- Script (Python): [source,python] ---- # prototype def hook_process_hashtable(command: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ... # example def my_process_cb(data, 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:https://weechat.org/", {"file_out": "/tmp/weechat.org.html"}, 20000, "my_process_cb", "") # example 2: open URL with custom HTTP headers options = { "httpheader": "\n".join([ "Header1: value1", "Header2: value2", ]), } hook2 = weechat.hook_process_hashtable("url:http://localhost:8080/", options, 20000, "my_process_cb", "") # example 3: execute a notify program with a message from someone hook3 = weechat.hook_process_hashtable("my-notify-command", {"arg1": "-from", "arg2": nick, "arg3": "-msg", "arg4": message}, # untrusted argument 20000, "my_process_cb", "") # example 4: call shell to execute a command (command must be SAFE) hook4 = weechat.hook_process_hashtable("sh", {"arg1": "-c", "arg2": "ls -l /tmp | grep something"}, 20000, "my_process_cb", "") ---- ==== hook_connect _Updated in 1.5, 2.0._ 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)(const void *pointer, void *data, int status, int gnutls_rc, int sock, const char *error, const char *ip_address), const void *callback_pointer, void *callback_data); ---- Arguments: * _proxy_: name of proxy to use for connection (optional, NULL means connection without proxy) * _address_: name or IP address to connect to * _port_: port number * _ipv6_: 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: ** _const void *pointer_: pointer ** _void *data_: pointer ** _int status_: connection status: *** _WEECHAT_HOOK_CONNECT_OK_: connection OK *** _WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND_: address not found *** _WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND_: IP address not found *** _WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED_: connection refused *** _WEECHAT_HOOK_CONNECT_PROXY_ERROR_: error with proxy *** _WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR_: error with local hostname *** _WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR_: GnuTLS init error *** _WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR_: GnuTLS handshake error *** _WEECHAT_HOOK_CONNECT_MEMORY_ERROR_: insufficient memory *** _WEECHAT_HOOK_CONNECT_TIMEOUT_: timeout *** _WEECHAT_HOOK_CONNECT_SOCKET_ERROR_: unable to create socket ** _gnutls_rc_: return value of _gnutls_handshake()_ ** _sock_: socket used to connect ** _const char *error_: return value of _gnutls_strerror(gnutls_rc)_ ** _const char *ip_address_: IP address found ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred [IMPORTANT] In scripts, with WeeChat ≥ 2.0, the callback arguments _status_, _gnutls_rc_ and _sock_ are integers (with WeeChat ≤ 1.9, they were strings). + To be compatible with all versions, it is recommended to convert the argument to integer before using it, for example in Python: `int(sock)`. C example: [source,c] ---- int my_connect_cb (const void *pointer, void *data, int status, int gnutls_rc, int sock, const char *error, const char *ip_address) { switch (status) { case WEECHAT_HOOK_CONNECT_OK: /* ... */ break; case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: /* ... */ break; case WEECHAT_HOOK_CONNECT_PROXY_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_MEMORY_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_TIMEOUT: /* ... */ break; case WEECHAT_HOOK_CONNECT_SOCKET_ERROR: /* ... */ break; } return WEECHAT_RC_OK; } struct t_hook *my_connect_hook = weechat_hook_connect (NULL, "my.server.org", 1234, 1, 0, NULL, NULL, 0, /* GnuTLS */ NULL, &my_connect_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_connect(proxy: str, address: str, port: int, ipv6: int, retry: int, local_hostname: str, callback: str, callback_data: str) -> str: ... # example def my_connect_cb(data, 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", "") ---- ==== hook_line _WeeChat ≥ 2.3, updated in 3.7._ Hook a line to be printed in a buffer. When a line is printed in a buffer, hooks are called in this order: * <<_hook_line,hook line>> (this hook): it can change the buffer, prefix, message, tags, notify level, … (see below) * <<_hook_modifier,hook modifier>> "<>": it can change the prefix and message on a buffer with formatted content * <<_hook_print,hook print>>: called when the line has been added in a buffer with formatted content (nothing can be changed directly with this hook). [NOTE] The "line" hook is the only one among these three hooks that can work on buffers with free content. Prototype: [source,c] ---- struct t_hook *weechat_hook_line (const char *buffer_type, const char *buffer_name, const char *tags, struct t_hashtable *(*callback)(const void *pointer, void *data, struct t_hashtable *line), const void *callback_pointer, void *callback_data); ---- Arguments: * _buffer_type_: catch lines on the given buffer type (if NULL or empty string, _formatted_ is the default) (_WeeChat ≥ 3.7_: a priority is allowed before the buffer type, see note about <>): ** _formatted_: catch lines on formatted buffers only (default) ** _free_: catch lines on buffers with free content only ** _*_: catch lines on all buffer types * _buffer_name_: comma-separated list of buffer masks (see <<_buffer_match_list,buffer_match_list>>); NULL, empty string or "*" matches any buffer * _tags_: catch only messages with these tags (optional): comma-separated list of tags that must be in message (logical "or"); it is possible to combine many tags as a logical "and" with separator `+++`; wildcard `+*+` is allowed in tags * _callback_: function called when a line is added in a buffer, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_hashtable *line_: hashtable with the line info, keys and values are strings (see table below) ** return value: hashtable with new values (see table below) * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred Line data sent to the callback is a hashtable, with following values (keys and values are strings): [width="100%",cols="^1,3,3,2",options="header"] |=== | Key | Value (formatted buffer) | Value (free buffer) | Examples | buffer | Buffer pointer. | Buffer pointer. | `+0x1234abcd+` | buffer_name | Buffer name. | Buffer name. | `+core.weechat+` + `+irc.server.libera+` + `+irc.libera.#weechat+` | buffer_type | "formatted" | "free" | `+formatted+` + `+free+` | y | N/A ("-1"). | Line number (≥ "0"). | `+-1+` + `+8+` | date | Line date (timestamp). | N/A ("0"). | `+1533792000+` | date_printed | Date when line was displayed (timestamp). | N/A ("0"). | `+1533792012+` | str_time | Date for display (possible color codes inside). | N/A (empty string). | `+09:07:20+` | tags_count | Number of tags in the line (≥ "0"). | N/A ("0"). | `+2+` | tags | Comma-separated list of tags. | N/A (empty string). | `+irc_join,nick_test+` | displayed | "0" = line is filtered (hidden) + "1" = line is not filtered (displayed). | "0" = line is filtered (hidden) + "1" = line is not filtered (displayed). | `+0+` + `+1+` | notify_level | "-1" = no notify + "0" = low level + "1" = message + "2" = private message + "3" = highlight | N/A ("0"). | `+2+` | highlight | "0" = no highlight + "1" = line has highlight. | N/A ("0"). | `+0+` + `+1+` | prefix | Prefix of the line. | N/A (empty string). | `+-->+` | message | Message of the line. | Message of the line. | `+test (~test@example.com) has joined #channel+` |=== The callback can return a hashtable with some fields to update the line. Any invalid value in a field is silently ignored by WeeChat. The following keys can be set in the hashtable (keys and values are strings in this hashtable): [width="100%",cols="^1,2,2,5",options="header"] |=== | Key | Allowed value (formatted buffer) | Allowed value (free buffer) | Result | buffer | Pointer of a buffer with formatted content. | Pointer of a buffer with free content. | The line is displayed on this buffer. + If the value is empty, the line is deleted (anything else in the hashtable is then ignored); the next hooks of type "line" are not called. | buffer_name | Name of a buffer with formatted content. | Name of a buffer with free content. | The line is displayed on this buffer. + If `buffer` is also set, the value of `+buffer_name+` has higher priority and is used. + If the value is empty, the line is deleted (anything else in the hashtable is then ignored); the next hooks of type "line" are not called. | y | N/A. | Integer (≥ "0"). | The line number is set to this value. | date | Timestamp. | N/A. | The date is set to this value. + The value of `+str_time+` is updated accordingly. | date_printed | Timestamp. | N/A. | The printed date is set to this timestamp (not displayed). | str_time | String. | N/A. | This string is used to display the date line. + If `date` is also set, the value of `+str_time+` has higher priority and is used. | tags | String. | N/A. | The line tags are replaced with this comma-separated list of tags. + The values of `+notify_level+` and `highlight` are updated accordingly. | notify_level | Integer ("-1" to "3"). | N/A. | The notify level is set to this value. The hotlist will be updated accordingly once the line is added in the buffer. + The value of `highlight` is updated accordingly. + If `tags` is also set, the value of `+notify_level+` has higher priority and is used. | highlight | Integer ("0" or "1"). | N/A. | "0" disables highlight on the line, "1" forces a highlight on the line. + If `tags` or `+notify_level+` are set, the value of `highlight` has higher priority and is used. | prefix | String. | N/A. | The line prefix is set to this value. | message | String. | String. | The line message is set to this value. |=== C example: [source,c] ---- int my_line_cb (const void *pointer, void *data, struct t_hasbtable *line) { struct t_hashtable *hashtable; hashtable = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); /* force a highlight on the line */ weechat_hashtable_set (hashtable, "highlight", "1"); return hashtable; } /* catch lines with tag "irc_join" */ struct t_hook *my_line_hook = weechat_hook_line ("", "", "irc_join", &my_line_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_line(buffer_type: str, buffer_name: str, tags: str, callback: str, callback_data: str) -> str: ... # example def my_line_cb(data, line): # force a highlight on the line return {"highlight": "1"} # catch lines with tag "irc_join" hook = weechat.hook_line("", "", "irc_join", "my_line_cb", "") ---- ==== hook_print _Updated in 0.4.3, 1.0, 1.5._ Hook a message printed. It is called when a line has been added in a buffer with formatted content. For more information on the hooks called when a line is printed, see <<_hook_line,hook_line>>. 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)(const void *pointer, 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), const void *callback_pointer, void *callback_data); ---- Arguments: * _buffer_: buffer pointer, if NULL, messages from any buffer are caught * _tags_: catch only messages with these tags (optional): ** with WeeChat ≥ 0.4.3: comma-separated list of tags that must be in message (logical "or"); it is possible to combine many tags as a logical "and" with separator `+++`; wildcard `+*+` is allowed in tags ** with WeeChat ≤ 0.4.2: comma-separated list of tags that must all be in message (logical "and") * _message_: only messages with this string will be caught (optional, case insensitive) * _strip_colors_: if 1, colors will be stripped from message displayed, before calling callback * _callback_: function called when a message is printed, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer pointer ** _time_t date_: date ** _int tags_count_: number of tags for line ** _const char **tags_: array with tags for line ** _int displayed_: 1 if line is displayed, 0 if it is filtered (hidden) ** _int highlight_: 1 if line has highlight, otherwise 0 ** _const char *prefix_: prefix ** _const char *message_: message ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred [IMPORTANT] In scripts, with WeeChat ≥ 1.0, the callback arguments _displayed_ and _highlight_ are integers (with WeeChat ≤ 0.4.3, they were strings). + To be compatible with all versions, it is recommended to convert the argument to integer before testing it, for example in Python: `if int(highlight):`. C example: [source,c] ---- int my_print_cb (const void *pointer, 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, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_print(buffer: str, tags: str, message: str, strip_colors: int, callback: str, callback_data: str) -> str: ... # example def my_print_cb(data, 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", "") ---- ==== hook_signal _Updated in 1.5, 3.6._ Hook a signal. Prototype: [source,c] ---- struct t_hook *weechat_hook_signal (const char *signal, int (*callback)(const void *pointer, void *data, const char *signal, const char *type_data, void *signal_data), const void *callback_pointer, void *callback_data); ---- Arguments: * _signal_: signal to catch, wildcard `+*+` is allowed; multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about <>) (see table below) * _callback_: function called when signal is received, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *signal_: signal received ** _const char *type_data_: type of data sent with signal: *** _WEECHAT_HOOK_SIGNAL_STRING_: string *** _WEECHAT_HOOK_SIGNAL_INT_: integer number *** _WEECHAT_HOOK_SIGNAL_POINTER_: pointer ** _void *signal_data_: data sent with signal ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_OK_EAT_ (stop sending the signal immediately) _(WeeChat ≥ 0.4.0)_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred List of signals sent by WeeChat and plugins: [width="100%",cols="^2,^4,^1,6,9",options="header"] |=== | Plugin | Signal | Min WeeChat | Arguments | Description | guile | [[hook_signal_guile_script_loaded]] guile_script_loaded | 0.3.9 | String: path to script. | Scheme script loaded. | guile | [[hook_signal_guile_script_unloaded]] guile_script_unloaded | 0.3.9 | String: path to script. | Scheme script unloaded. | guile | [[hook_signal_guile_script_installed]] guile_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Scheme script(s) installed. | guile | [[hook_signal_guile_script_removed]] guile_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Scheme script(s) removed. | irc | [[hook_signal_xxx_irc_in_yyy]] xxx,irc_in_yyy ^(1)^ | | String: message. | IRC message from server (before irc plugin uses it, signal sent only if message is *not* ignored). + Since version 2.2, the whole IRC message is sent, including tags. + If the return code of a callback is _WEECHAT_RC_OK_EAT_, then the IRC message is immediately destroyed and not processed _(WeeChat ≥ 3.3)_. | irc | [[hook_signal_xxx_irc_in2_yyy]] xxx,irc_in2_yyy ^(1)^ | | String: message. | IRC message from server (after irc plugin uses it, signal sent only if message is *not* ignored). + Since version 2.2, the whole IRC message is sent, including tags. | irc | [[hook_signal_xxx_irc_raw_in_yyy]] xxx,irc_raw_in_yyy ^(1)^ | 0.3.2 | String: message. | IRC message from server (before irc plugin uses it, signal sent even if message is ignored). + Since version 2.2, the whole IRC message is sent, including tags. + If the return code of a callback is _WEECHAT_RC_OK_EAT_, then the IRC message is immediately destroyed and not processed _(WeeChat ≥ 3.3)_. | irc | [[hook_signal_xxx_irc_raw_in2_yyy]] xxx,irc_raw_in2_yyy ^(1)^ | 0.3.2 | String: message. | IRC message from server (after irc plugin uses it, signal sent even if message is ignored). + Since version 2.2, the whole IRC message is sent, including tags. | irc | [[hook_signal_xxx_irc_out1_yyy]] xxx,irc_out1_yyy ^(1)^ | 0.3.7 | String: message. | IRC message sent to server before automatic split (to fit in 512 bytes by default). | irc | [[hook_signal_xxx_irc_out_yyy]] xxx,irc_out_yyy ^(1)^ | | String: message. | IRC message sent to server after automatic split (to fit in 512 bytes by default). + *Warning:* the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead. | irc | [[hook_signal_xxx_irc_outtags_yyy]] xxx,irc_outtags_yyy ^(1)^ | 0.3.4 | String: tags + ";" + message. | Tags + IRC message sent to server. + *Warning:* the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead. | irc | [[hook_signal_irc_ctcp]] irc_ctcp | | String: message. | CTCP received. | irc | [[hook_signal_irc_dcc]] irc_dcc | | String: message. | New DCC. | irc | [[hook_signal_irc_pv]] irc_pv | | String: message. | Private message received. | irc | [[hook_signal_irc_channel_opened]] irc_channel_opened | | Pointer: buffer. | Channel opened. | irc | [[hook_signal_irc_pv_opened]] irc_pv_opened | | Pointer: buffer. | Private opened. | irc | [[hook_signal_irc_server_opened]] irc_server_opened | 0.3.7 | Pointer: buffer. | Server buffer opened. | irc | [[hook_signal_irc_server_connecting]] irc_server_connecting | | String: server name. | Connecting to server. | irc | [[hook_signal_irc_server_connected]] irc_server_connected | | String: server name. | Connected to server. | irc | [[hook_signal_irc_server_disconnected]] irc_server_disconnected | | String: server name. | Disconnected from server. | irc | [[hook_signal_irc_server_lag_changed]] irc_server_lag_changed | 1.8 | String: server name. | Lag changed on the server. | irc | [[hook_signal_irc_ignore_removing]] irc_ignore_removing | | Pointer: ignore. | Removing ignore. | irc | [[hook_signal_irc_ignore_removed]] irc_ignore_removed | | - | Ignore removed. | irc | [[hook_signal_irc_notify_join]] irc_notify_join | 0.3.8 | String: server name + "," + nick. | A nick in notify list has joined server. | irc | [[hook_signal_irc_notify_quit]] irc_notify_quit | 0.3.8 | String: server name + "," + nick. | A nick in notify list has quit server. | irc | [[hook_signal_irc_notify_away]] irc_notify_away | 0.3.8 | String: server name + "," + nick + "," + away message. | A nick in notify list is now away on server. | irc | [[hook_signal_irc_notify_still_away]] irc_notify_still_away | 0.3.8 | String: server name + "," + nick + "," + away message. | A nick in notify list is still away on server (away message has changed). | irc | [[hook_signal_irc_notify_back]] irc_notify_back | 0.3.8 | String: server name + "," + nick. | A nick in notify list is back (away status removed). | javascript | [[hook_signal_javascript_script_loaded]] javascript_script_loaded | 1.2 | String: path to script. | JavaScript script loaded. | javascript | [[hook_signal_javascript_script_unloaded]] javascript_script_unloaded | 1.2 | String: path to script. | JavaScript script unloaded. | javascript | [[hook_signal_javascript_script_installed]] javascript_script_installed | 1.2 | String: comma-separated list of paths to scripts installed. | JavaScript script(s) installed. | javascript | [[hook_signal_javascript_script_removed]] javascript_script_removed | 1.2 | String: comma-separated list of scripts removed. | JavaScript script(s) removed. | logger | [[hook_signal_logger_start]] logger_start | | Pointer: buffer. | Start logging for buffer. | logger | [[hook_signal_logger_stop]] logger_stop | | Pointer: buffer. | Stop logging for buffer. | logger | [[hook_signal_logger_backlog]] logger_backlog | | Pointer: buffer. | Display backlog for buffer. | lua | [[hook_signal_lua_script_loaded]] lua_script_loaded | 0.3.9 | String: path to script. | Lua script loaded. | lua | [[hook_signal_lua_script_unloaded]] lua_script_unloaded | 0.3.9 | String: path to script. | Lua script unloaded. | lua | [[hook_signal_lua_script_installed]] lua_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Lua script(s) installed. | lua | [[hook_signal_lua_script_removed]] lua_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Lua script(s) removed. | perl | [[hook_signal_perl_script_loaded]] perl_script_loaded | 0.3.9 | String: path to script. | Perl script loaded. | perl | [[hook_signal_perl_script_unloaded]] perl_script_unloaded | 0.3.9 | String: path to script. | Perl script unloaded. | perl | [[hook_signal_perl_script_installed]] perl_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Perl script(s) installed. | perl | [[hook_signal_perl_script_removed]] perl_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Perl script(s) removed. | php | [[hook_signal_php_script_loaded]] php_script_loaded | 2.0 | String: path to script. | PHP script loaded. | php | [[hook_signal_php_script_unloaded]] php_script_unloaded | 2.0 | String: path to script. | PHP script unloaded. | php | [[hook_signal_php_script_installed]] php_script_installed | 2.0 | String: comma-separated list of paths to scripts installed. | PHP script(s) installed. | php | [[hook_signal_php_script_removed]] php_script_removed | 2.0 | String: comma-separated list of scripts removed. | PHP script(s) removed. | python | [[hook_signal_python_script_loaded]] python_script_loaded | 0.3.9 | String: path to script. | Python script loaded. | python | [[hook_signal_python_script_unloaded]] python_script_unloaded | 0.3.9 | String: path to script. | Python script unloaded. | python | [[hook_signal_python_script_installed]] python_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Python script(s) installed. | python | [[hook_signal_python_script_removed]] python_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Python script(s) removed. | relay | [[hook_signal_relay_client_connecting]] relay_client_connecting | 1.0 | Pointer: relay client. | A relay client is connecting. | relay | [[hook_signal_relay_client_waiting_auth]] relay_client_waiting_auth | 1.0 | Pointer: relay client. | Waiting for authentication from a relay client. | relay | [[hook_signal_relay_client_auth_ok]] relay_client_auth_ok | 1.0 | Pointer: relay client. | Successful authentication from a relay client. | relay | [[hook_signal_relay_client_connected]] relay_client_connected | 1.0 | Pointer: relay client. | A relay client is connected. | relay | [[hook_signal_relay_client_auth_failed]] relay_client_auth_failed | 1.0 | Pointer: relay client. | Authentication of a relay client has failed. | relay | [[hook_signal_relay_client_disconnected]] relay_client_disconnected | 1.0 | Pointer: relay client. | A relay client is disconnected. | ruby | [[hook_signal_ruby_script_loaded]] ruby_script_loaded | 0.3.9 | String: path to script. | Ruby script loaded. | ruby | [[hook_signal_ruby_script_unloaded]] ruby_script_unloaded | 0.3.9 | String: path to script. | Ruby script unloaded. | ruby | [[hook_signal_ruby_script_installed]] ruby_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Ruby script(s) installed. | ruby | [[hook_signal_ruby_script_removed]] ruby_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Ruby script(s) removed. | spell | [[hook_signal_spell_suggest]] spell_suggest | 2.4 | Pointer: buffer. | New suggestions for a misspelled word. | tcl | [[hook_signal_tcl_script_loaded]] tcl_script_loaded | 0.3.9 | String: path to script. | Tcl script loaded. | tcl | [[hook_signal_tcl_script_unloaded]] tcl_script_unloaded | 0.3.9 | String: path to script. | Tcl script unloaded. | tcl | [[hook_signal_tcl_script_installed]] tcl_script_installed | 0.3.9 | String: comma-separated list of paths to scripts installed. | Tcl script(s) installed. | tcl | [[hook_signal_tcl_script_removed]] tcl_script_removed | 0.3.9 | String: comma-separated list of scripts removed. | Tcl script(s) removed. | typing | [[hook_signal_typing_self_typing]] typing_self_typing | 3.3 | Pointer: buffer. | User is typing a message (sent by typing plugin, used by irc plugin). | typing | [[hook_signal_typing_self_paused]] typing_self_paused | 3.3 | Pointer: buffer. | User paused during typing (sent by typing plugin, used by irc plugin). | typing | [[hook_signal_typing_self_cleared]] typing_self_cleared | 3.3 | Pointer: buffer. | User cleared the input without sending the message (sent by typing plugin, used by irc plugin). | typing | [[hook_signal_typing_self_sent]] typing_self_sent | 3.3 | Pointer: buffer. | Message (not a command) sent to the buffer (sent by typing plugin, used by irc plugin). | typing | [[hook_signal_typing_set_nick]] typing_set_nick | 3.3 | String: buffer pointer + ";" + state (one of: "off", "typing", "paused", "cleared") + ";" + nick. | Set typing state for a nick on a buffer (sent by irc plugin, handled by typing plugin). | typing | [[hook_signal_typing_reset_buffer]] typing_reset_buffer | 3.3 | Pointer: buffer. | Remove typing state for all nicks on a buffer (sent by irc plugin, handled by typing plugin). | weechat | [[hook_signal_buffer_opened]] buffer_opened | | Pointer: buffer. | Buffer opened. | weechat | [[hook_signal_buffer_closing]] buffer_closing | | Pointer: buffer. | Closing buffer. | weechat | [[hook_signal_buffer_closed]] buffer_closed | | Pointer: buffer. | Buffer closed. | weechat | [[hook_signal_buffer_cleared]] buffer_cleared | | Pointer: buffer. | Buffer cleared. | weechat | [[hook_signal_buffer_filters_enabled]] buffer_filters_enabled | 2.0 | Pointer: buffer. | Filters enabled in buffer. | weechat | [[hook_signal_buffer_filters_disabled]] buffer_filters_disabled | 2.0 | Pointer: buffer. | Filters disabled in buffer. | weechat | [[hook_signal_buffer_hidden]] buffer_hidden | | Pointer: buffer. | Buffer hidden. | weechat | [[hook_signal_buffer_unhidden]] buffer_unhidden | | Pointer: buffer. | Buffer unhidden. | weechat | [[hook_signal_buffer_line_added]] buffer_line_added | 0.3.7 | Pointer: line. | Line added in a buffer. | weechat | [[hook_signal_buffer_lines_hidden]] buffer_lines_hidden | | Pointer: buffer. | Lines hidden in buffer. | weechat | [[hook_signal_buffer_localvar_added]] buffer_localvar_added | | Pointer: buffer. | Local variable has been added. | weechat | [[hook_signal_buffer_localvar_changed]] buffer_localvar_changed | | Pointer: buffer. | Local variable has changed. | weechat | [[hook_signal_buffer_localvar_removed]] buffer_localvar_removed | | Pointer: buffer. | Local variable has been removed. | weechat | [[hook_signal_buffer_merged]] buffer_merged | | Pointer: buffer. | Buffer merged. | weechat | [[hook_signal_buffer_unmerged]] buffer_unmerged | | Pointer: buffer. | Buffer unmerged. | weechat | [[hook_signal_buffer_moved]] buffer_moved | | Pointer: buffer. | Buffer moved. | weechat | [[hook_signal_buffer_renamed]] buffer_renamed | | Pointer: buffer. | Buffer renamed. | weechat | [[hook_signal_buffer_switch]] buffer_switch | | Pointer: buffer. | Switching buffer. | weechat | [[hook_signal_buffer_title_changed]] buffer_title_changed | | Pointer: buffer. | Title of buffer changed. | weechat | [[hook_signal_buffer_type_changed]] buffer_type_changed | | Pointer: buffer. | Type of buffer changed. | weechat | [[hook_signal_buffer_zoomed]] buffer_zoomed | 0.4.3 | Pointer: buffer. | Merged buffer zoomed. | weechat | [[hook_signal_buffer_unzoomed]] buffer_unzoomed | 0.4.3 | Pointer: buffer. | Merged buffer unzoomed. | weechat | [[hook_signal_cursor_start]] cursor_start | 3.2 | - | Start cursor mode. | weechat | [[hook_signal_cursor_end]] cursor_end | 3.2 | - | End cursor mode. | weechat | [[hook_signal_day_changed]] day_changed | 0.3.2 | String: new date, format: "2010-01-31". | Day of system date has changed. | weechat | [[hook_signal_debug_dump]] debug_dump | | String: plugin name. | Dump request. | weechat | [[hook_signal_debug_libs]] debug_libs | | - | Display external libraries used. | weechat | [[hook_signal_filter_added]] filter_added | | Pointer: filter. | Filter added. | weechat | [[hook_signal_filter_removing]] filter_removing | | Pointer: filter. | Removing filter. | weechat | [[hook_signal_filter_removed]] filter_removed | | - | Filter removed. | weechat | [[hook_signal_filters_enabled]] filters_enabled | | - | Filters enabled. | weechat | [[hook_signal_filters_disabled]] filters_disabled | | - | Filters disabled. | weechat | [[hook_signal_hotlist_changed]] hotlist_changed | | Pointer: buffer (can be NULL). | Hotlist changed. | weechat | [[hook_signal_input_paste_pending]] input_paste_pending | | - | Paste pending. | weechat | [[hook_signal_input_search]] input_search | | Pointer: buffer. | Text search in buffer. | weechat | [[hook_signal_input_text_changed]] input_text_changed | | Pointer: buffer. | Input text changed. | weechat | [[hook_signal_input_text_cursor_moved]] input_text_cursor_moved | | Pointer: buffer. | Input text cursor moved. | weechat | [[hook_signal_key_bind]] key_bind | | String: key. | Key added. | weechat | [[hook_signal_key_unbind]] key_unbind | | String: key. | Key removed. | weechat | [[hook_signal_key_pressed]] key_pressed | | String: key pressed. | Key pressed. | weechat | [[hook_signal_key_combo_default]] key_combo_default | 1.0 | String: key combo. | Key combo in _default_ context. | weechat | [[hook_signal_key_combo_search]] key_combo_search | 1.0 | String: key combo. | Key combo in _search_ context. | weechat | [[hook_signal_key_combo_cursor]] key_combo_cursor | 1.0 | String: key combo. | Key combo in _cursor_ context. | weechat | [[hook_signal_mouse_enabled]] mouse_enabled | 1.1 | - | Mouse enabled. | weechat | [[hook_signal_mouse_disabled]] mouse_disabled | 1.1 | - | Mouse disabled. | weechat | [[hook_signal_nicklist_group_added]] nicklist_group_added | 0.3.2 | String: buffer pointer + "," + group name. | Group added in nicklist. | weechat | [[hook_signal_nicklist_group_changed]] nicklist_group_changed | 0.3.4 | String: buffer pointer + "," + group name. | Group changed in nicklist. | weechat | [[hook_signal_nicklist_group_removing]] nicklist_group_removing | 0.4.1 | String: buffer pointer + "," + group name. | Removing group from nicklist. | weechat | [[hook_signal_nicklist_group_removed]] nicklist_group_removed | 0.3.2 | String: buffer pointer + "," + group name. | Group removed from nicklist. | weechat | [[hook_signal_nicklist_nick_added]] nicklist_nick_added | 0.3.2 | String: buffer pointer + "," + nick name. | Nick added in nicklist. | weechat | [[hook_signal_nicklist_nick_changed]] nicklist_nick_changed | 0.3.4 | String: buffer pointer + "," + nick name. | Nick changed in nicklist. | weechat | [[hook_signal_nicklist_nick_removing]] nicklist_nick_removing | 0.4.1 | String: buffer pointer + "," + nick name. | Removing nick from nicklist. | weechat | [[hook_signal_nicklist_nick_removed]] nicklist_nick_removed | 0.3.2 | String: buffer pointer + "," + nick name. | Nick removed from nicklist. | weechat | [[hook_signal_partial_completion]] partial_completion | | - | Partial completion happened. | weechat | [[hook_signal_plugin_loaded]] plugin_loaded | 0.3.9 | String: path to plugin loaded. | Plugin loaded. | weechat | [[hook_signal_plugin_unloaded]] plugin_unloaded | 0.3.9 | String: name of plugin unloaded (example: "irc"). | Plugin unloaded. | weechat | [[hook_signal_quit]] quit | | String: arguments for /quit. | Command `/quit` issued by user. | weechat | [[hook_signal_signal_sighup]] signal_sighup | 1.3 | - | Signal SIGHUP received. | weechat | [[hook_signal_signal_sigquit]] signal_sigquit | 1.2 | - | Signal SIGQUIT received (quit request with core dump). | weechat | [[hook_signal_signal_sigterm]] signal_sigterm | 1.2 | - | Signal SIGTERM received (graceful termination of WeeChat process). | weechat | [[hook_signal_signal_sigwinch]] signal_sigwinch | 0.4.3 | - | Signal SIGWINCH received (terminal was resized). | weechat | [[hook_signal_upgrade]] upgrade | | String: "quit" if "-quit" argument was given for /upgrade, "save" if "-save" if "-save" argument was given for /upgrade, otherwise NULL. | Command `/upgrade` issued by user. | weechat | [[hook_signal_upgrade_ended]] upgrade_ended | 0.3.4 | - | End of upgrade process (command `/upgrade`). | weechat | [[hook_signal_weechat_highlight]] weechat_highlight | | String: message with prefix. | Highlight happened. | weechat | [[hook_signal_weechat_pv]] weechat_pv | | String: message with prefix. | Private message displayed. | weechat | [[hook_signal_window_closing]] window_closing | 0.3.6 | Pointer: window. | Closing window. | weechat | [[hook_signal_window_closed]] window_closed | 0.3.6 | Pointer: window. | Window closed. | weechat | [[hook_signal_window_opened]] window_opened | 0.4.1 | Pointer: window. | Window opened. | weechat | [[hook_signal_window_scrolled]] window_scrolled | | Pointer: window. | Scroll in window. | weechat | [[hook_signal_window_switch]] window_switch | 0.3.7 | Pointer: window. | Switching window. | weechat | [[hook_signal_window_zoom]] window_zoom | | Pointer: current window. | Zooming window. | weechat | [[hook_signal_window_zoomed]] window_zoomed | | Pointer: current window. | Window zoomed. | weechat | [[hook_signal_window_unzoom]] window_unzoom | | Pointer: current window. | Unzooming window. | weechat | [[hook_signal_window_unzoomed]] window_unzoomed | | Pointer: current window. | Window unzoomed. | xfer | [[hook_signal_xfer_add]] xfer_add | | Pointer: infolist with xfer info. | New xfer. | xfer | [[hook_signal_xfer_send_ready]] xfer_send_ready | | Pointer: infolist with xfer info. | Xfer ready. | xfer | [[hook_signal_xfer_accept_resume]] xfer_accept_resume | | Pointer: infolist with xfer info. | Accept xfer resume. | xfer | [[hook_signal_xfer_send_accept_resume]] xfer_send_accept_resume | | Pointer: infolist with xfer info. | Xfer resumed. | xfer | [[hook_signal_xfer_start_resume]] xfer_start_resume | | Pointer: infolist with xfer info. | Start resume. | xfer | [[hook_signal_xfer_resume_ready]] xfer_resume_ready | | Pointer: infolist with xfer info. | Xfer resume ready. | xfer | [[hook_signal_xfer_ended]] xfer_ended | 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 (const void *pointer, void *data, const char *signal, const char *type_data, void *signal_data) { /* ... */ return WEECHAT_RC_OK; } /* catch signals "quit" and "upgrade" */ struct t_hook *my_signal_hook = weechat_hook_signal ("quit;upgrade", &my_signal_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_signal(signal: str, callback: str, callback_data: str) -> str: ... # example def my_signal_cb(data, signal, signal_data): # ... return weechat.WEECHAT_RC_OK # catch signals "quit" and "upgrade" hook = weechat.hook_signal("quit;upgrade", "my_signal_cb", "") ---- ==== hook_signal_send _Updated in 1.0._ 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 <<_hook_signal,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 def hook_signal_send(signal: str, type_data: str, signal_data: str) -> int: ... # 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_ * _guile_script_install_ * _javascript_script_install_ * _php_script_install_ The callback will do following actions when receiving signal: . Unload and remove installed script. . Move new script to directory _~/.local/share/weechat/xxx/_ (where _xxx_ is language). . Create link to new script in directory _~/.local/share/weechat/xxx/autoload/_ (only if the script was already auto-loaded, or if the option _script.scripts.autoload_ is enabled for a new script). . Load new script (if the script was loaded). These signals are used by _script_ plugin to install scripts. Argument is a string with path to script to install. C example: [source,c] ---- weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py"); ---- Script (Python): [source,python] ---- weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/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_ * _guile_script_remove_ * _javascript_script_remove_ * _php_script_remove_ For each script in list, the callback will unload then remove script. These signals are used by _script_ plugin to remove scripts. Argument is a string with comma-separated list of script to remove (script is name without path, for example _script.py_). C example: [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, updated in 1.5._ The signal "irc_input_send" can be sent to simulate input in an irc buffer (server, channel or private). Argument is a string with following format: * internal server name (required) * semicolon * channel name (optional) * semicolon * comma-separated list of options (optional): ** _priority_high_: queue with high priority (like user messages); this is the default priority ** _priority_low_: queue with low priority (like messages automatically sent by WeeChat) ** _user_message_: force user message (don't execute a command) * semicolon * comma-separated list of tags used when sending message (optional) * semicolon * text or command (required) C examples: [source,c] ---- /* say "Hello!" on libera server, #weechat channel */ weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, "libera;#weechat;priority_high,user_message;;Hello!"); /* send command "/whois FlashCode" on libera server, with low priority */ weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, "libera;;priority_low;;/whois FlashCode"); ---- Script (Python): [source,python] ---- # say "Hello!" on libera server, #weechat channel weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, "libera;#weechat;priority_high,user_message;;Hello!") # send command "/whois FlashCode" on libera server, with low priority weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, "libera;;priority_low;;/whois FlashCode") ---- ==== hook_hsignal _WeeChat ≥ 0.3.4, updated in 1.5, 3.6._ Hook a hsignal (signal with hashtable). Prototype: [source,c] ---- struct t_hook *weechat_hook_hsignal (const char *signal, int (*callback)(const void *pointer, void *data, const char *signal, struct t_hashtable *hashtable), const void *callback_pointer, void *callback_data); ---- Arguments: * _signal_: signal to catch, wildcard `+*+` is allowed; multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about <>) (see table below) * _callback_: function called when signal is received, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *signal_: signal received ** _struct t_hashtable *hashtable_: hashtable ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_OK_EAT_ (stop sending the signal immediately) _(WeeChat ≥ 0.4.0)_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred List of hsignals: [width="100%",cols="^1,^3,^1,5,5",options="header"] |=== | Plugin | Signal | Min WeeChat | Arguments | Description | irc | [[hook_hsignal_irc_redirection_xxx_yyy]] irc_redirection_xxx_yyy ^(1)^ | 0.3.4 | See <> | Redirection output. | weechat | [[hook_hsignal_nicklist_group_added]] nicklist_group_added | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _group_ (_struct t_gui_nick_group *_): group | Group added in nicklist. | weechat | [[hook_hsignal_nicklist_nick_added]] nicklist_nick_added | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _nick_ (_struct t_gui_nick *_): nick | Nick added in nicklist. | weechat | [[hook_hsignal_nicklist_group_removing]] nicklist_group_removing | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _group_ (_struct t_gui_nick_group *_): group | Removing group from nicklist. | weechat | [[hook_hsignal_nicklist_nick_removing]] nicklist_nick_removing | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _nick_ (_struct t_gui_nick *_): nick | Removing nick from nicklist. | weechat | [[hook_hsignal_nicklist_group_changed]] nicklist_group_changed | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _group_ (_struct t_gui_nick_group *_): group | Group changed in nicklist. | weechat | [[hook_hsignal_nicklist_nick_changed]] nicklist_nick_changed | 0.4.1 | _buffer_ (_struct t_gui_buffer *_): buffer + _parent_group_ (_struct t_gui_nick_group *_): parent group + _nick_ (_struct t_gui_nick *_): nick | Nick changed in nicklist. |=== [NOTE] ^(1)^ _xxx_ is signal argument used in redirection, _yyy_ is redirection pattern. C example: [source,c] ---- int my_hsignal_cb (const void *pointer, void *data, const char *signal, struct t_hashtable *hashtable) { /* ... */ return WEECHAT_RC_OK; } struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test", &my_hsignal_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_hsignal(signal: str, callback: str, callback_data: str) -> str: ... # example def my_hsignal_cb(data, signal, hashtable): # ... return weechat.WEECHAT_RC_OK hook = weechat.hook_hsignal("test", "my_hsignal_cb", "") ---- ==== 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 def hook_hsignal_send(signal: str, hashtable: Dict[str, str]) -> int: ... # 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 <>), 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 (const void *pointer, void *data, const char *signal, struct t_hashtable *hashtable) { weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error")); weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output")); return WEECHAT_RC_OK; } weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL, NULL); struct t_hashtable *hashtable = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); if (hashtable) { weechat_hashtable_set (hashtable, "server", "libera"); weechat_hashtable_set (hashtable, "pattern", "whois"); weechat_hashtable_set (hashtable, "signal", "test"); weechat_hashtable_set (hashtable, "string", "FlashCode"); weechat_hook_hsignal_send ("irc_redirect_command", hashtable); weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING, "libera;;2;;/whois FlashCode"); weechat_hashtable_free (hashtable); } ---- Script (Python): [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": "libera", "pattern": "whois", "signal": "test", "string": "FlashCode"}) weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING, "libera;;2;;/whois FlashCode") ---- [[hsignal_irc_redirect_pattern]] ===== Hsignal irc_redirect_pattern _WeeChat ≥ 0.3.4._ The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc redirect (see <>). 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" # ... ---- ==== hook_config _Updated in 1.5._ Hook a configuration option. Prototype: [source,c] ---- struct t_hook *weechat_hook_config (const char *option, int (*callback)(const void *pointer, void *data, const char *option, const char *value), const void *callback_pointer, void *callback_data); ---- Arguments: * _option_: option, format is full name, as used with command `/set` (for example: `+weechat.look.item_time_format+`), wildcard `+*+` is allowed (a priority is allowed before the option, see note about <>) * _callback_: function called when configuration option is changed, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *option_: name of option ** _const char *value_: new value for option ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- int my_config_cb (const void *pointer, void *data, const char *option, const char *value) { /* ... */ return WEECHAT_RC_OK; } /* catch changes to option "weechat.look.item_time_format" */ struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format", &my_config_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_config(option: str, callback: str, callback_data: str) -> str: ... # example def my_config_cb(data, option, value): # ... return weechat.WEECHAT_RC_OK # catch changes to option "weechat.look.item_time_format" hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "") ---- ==== hook_modifier _Updated in 1.5._ Hook a modifier. Prototype: [source,c] ---- struct t_hook *weechat_hook_modifier (const char *modifier, char *(*callback)(const void *pointer, void *data, const char *modifier, const char *modifier_data, const char *string), const void *callback_pointer, void *callback_data); ---- Arguments: * _modifier_: modifier name (a priority is allowed before the modifier, see note about <>) (see table below) * _callback_: function called when modifier is used, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *modifier_: name of modifier ** _const char *modifier_data_: data for modifier ** _const char *string_: string to modify ** return value: new string * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred List of modifiers used by WeeChat and plugins: [width="100%",cols="^2,^1,3,4,4",options="header"] |=== | Modifier | Min WeeChat | Modifier data | String | Output | [[hook_modifier_irc_in_xxx]] irc_in_xxx ^(1)^ | | Server name | Content of message received from IRC server (before charset decoding). + *Warning:* the string may contain invalid UTF-8 data; use only for raw operations on a message. Modifier <> is recommended instead. | New content of message. | [[hook_modifier_irc_in2_xxx]] irc_in2_xxx ^(1)^ | 0.3.5 | Server name | Content of message received from IRC server (after charset decoding). | New content of message. | [[hook_modifier_irc_out1_xxx]] irc_out1_xxx ^(1)^ | 0.3.7 | Server name | Content of message about to be sent to IRC server before automatic split (to fit in 512 bytes by default). | New content of message. | [[hook_modifier_irc_out_xxx]] irc_out_xxx ^(1)^ | | Server name | Content of message about to be sent to IRC server after automatic split (to fit in 512 bytes by default). | New content of message. | [[hook_modifier_bar_condition_yyy]] bar_condition_yyy ^(2)^ | | String with window pointer (eg: "0x1234abcd") | Empty string. | "1" to display bar, "0" to hide it. | [[hook_modifier_history_add]] history_add | 0.3.2 | String with buffer pointer (eg: "0x1234abcd") | Content of command line to add in command history (buffer and global). | String added to command history. | [[hook_modifier_input_text_content]] input_text_content | | String with buffer pointer (eg: "0x1234abcd") | Content of command line. | New content of command line. | [[hook_modifier_input_text_display]] input_text_display | | String with buffer pointer (eg: "0x1234abcd") | Content of command line, without cursor tag. | New string, for display only (command line is not changed). | [[hook_modifier_input_text_display_with_cursor]] input_text_display_with_cursor | | String with buffer pointer (eg: "0x1234abcd") | Content of command line, with cursor tag. | New string, for display only (command line is not changed). | [[hook_modifier_input_text_for_buffer]] input_text_for_buffer | 0.3.7 | String with buffer pointer (eg: "0x1234abcd") | Content of command line sent to buffer (text or command). | New content of command line sent to buffer. | [[hook_modifier_weechat_print]] weechat_print | | buffer pointer (eg: "0x1234abcd") + ";" + tags ^(3)^ | Message printed. | New message printed. + For more information on the hooks called when a line is printed, see <<_hook_line,hook_line>>. |=== [NOTE] ^(1)^ _xxx_ is IRC command name. + ^(2)^ _yyy_ is bar name. + ^(3)^ With WeeChat ≤ 2.8, the format was: plugin + ";" + buffer_name + ";" + tags. C example: [source,c] ---- char * my_modifier_cb (const void *pointer, void *data, const char *modifier, const char *modifier_data, const char *string) { char *result; int length; if (!string) return NULL; length = strlen (string) + 5; result = malloc (length); if (result) { /* add "xxx" to any message printed */ snprintf (result, length, "%s xxx", string); } return result; } struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print", &my_modifier_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_modifier(modifier: str, callback: str, callback_data: str) -> str: ... # example def my_modifier_cb(data, modifier, modifier_data, string): return "%s xxx" % string hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "") ---- ==== 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 List of modifiers defined by WeeChat and plugins that can be used: [width="100%",cols="^2,^1,3,4,4",options="header"] |=== | Modifier | Min WeeChat | Modifier data | String | Output | [[hook_modifier_charset_decode]] charset_decode | | plugin.buffer_name | Any string. | String decoded from charset found for plugin/buffer to UTF-8. | [[hook_modifier_charset_encode]] charset_encode | | plugin.buffer_name | Any string. | String encoded from UTF-8 to charset found for plugin/buffer. | [[hook_modifier_irc_color_decode]] 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). | [[hook_modifier_irc_color_encode]] irc_color_encode | | "1" to keep colors, "0" to remove colors | Any string. | String with IRC colors (or IRC colors removed). | [[hook_modifier_irc_color_decode_ansi]] irc_color_decode_ansi | 1.0 | "1" to keep colors, "0" to remove colors | Any string. | String with ANSI colors converted to IRC colors (or ANSI colors removed). | [[hook_modifier_irc_command_auth]] irc_command_auth | 0.4.1 | Server name | Authentication command (for example: `+/msg nickserv identify password+`). | command with hidden password (for example: `+/msg nickserv identify ********+`). | [[hook_modifier_irc_message_auth]] irc_message_auth | 0.4.1 | Server name | Message displayed after `/msg` sent to nickserv. | Message with hidden password. | [[hook_modifier_irc_tag_escape_value]] irc_tag_escape_value | 3.3 | - | Any string. | String with IRC tag value escaped, see https://ircv3.net/specs/extensions/message-tags#escaping-values[this page ^↗^,window=_blank]. | [[hook_modifier_irc_tag_unescape_value]] irc_tag_unescape_value | 3.3 | - | Any string. | String with IRC tag value unescaped, see https://ircv3.net/specs/extensions/message-tags#escaping-values[this page ^↗^,window=_blank]. | [[hook_modifier_color_decode_ansi]] color_decode_ansi | 1.0 | "1" to keep colors, "0" to remove colors | Any string. | String with ANSI colors converted to WeeChat colors (or ANSI colors removed). | [[hook_modifier_color_encode_ansi]] color_encode_ansi | 2.7 | - | Any string. | String with WeeChat colors converted to ANSI colors. | [[hook_modifier_eval_path_home]] eval_path_home | 2.7 | Optional: `directory=xxx` where `xxx` can be: `config`, `data`, `cache`, `runtime` | Any string. | Evaluated path, result of the function <<_string_eval_path_home,string_eval_path_home>>. |=== C example: [source,c] ---- char *new_string = weechat_hook_modifier_exec ("my_modifier", my_data, my_string); ---- Script (Python): [source,python] ---- # prototype def hook_modifier_exec(modifier: str, modifier_data: str, string: str) -> str: ... # example weechat.hook_modifier_exec("my_modifier", my_data, my_string) ---- ==== hook_info _Updated in 1.5, 2.5._ Hook an information (callback takes and returns a string). Prototype: [source,c] ---- struct t_hook *weechat_hook_info (const char *info_name, const char *description, const char *args_description, char *(*callback)(const void *pointer, void *data, const char *info_name, const char *arguments), const void *callback_pointer, void *callback_data); ---- Arguments: * _info_name_: name of info (a priority is allowed before the info name, see note about <>) * _description_: description * _args_description_: description of arguments (optional, can be NULL) * _callback_: function called when info is asked, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *info_name_: name of info ** _const char *arguments_: additional arguments, depending on info ** return value: value of info asked * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred [NOTE] With WeeChat ≥ 2.5, the callback returns an allocated string (with WeeChat ≤ 2.4, it was a pointer to a static string). C example: [source,c] ---- char * my_info_cb (const void *pointer, void *data, const char *info_name, const char *arguments) { /* ... */ return strdup ("some_info"); } /* add info "my_info" */ struct t_hook *my_info_hook = weechat_hook_info ("my_info", "Some info", "Info about arguments", &my_info_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_info(info_name: str, description: str, args_description: str, callback: str, callback_data: str) -> str: ... # example def my_info_cb(data, info_name, arguments): return "some_info" hook = weechat.hook_info("my_info", "Some info", "Info about arguments", "my_info_cb", "") ---- ==== hook_info_hashtable _WeeChat ≥ 0.3.4, updated in 1.5._ Hook an information (callback takes and returns a hashtable). Prototype: [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)(const void *pointer, void *data, const char *info_name, struct t_hashtable *hashtable), const void *callback_pointer, void *callback_data); ---- Arguments: * _info_name_: name of info (a priority is allowed before the info name, see note about <>) * _description_: description * _args_description_: description of expected hashtable (optional, can be NULL) * _output_description_: description of hashtable returned by callback (optional, can be NULL) * _callback_: function called when info is asked, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *info_name_: name of info ** _struct t_hashtable *hashtable_: hashtable, depending on info ** return value: hashtable asked * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- struct t_hashtable * my_info_hashtable_cb (const void *pointer, void *data, const char *info_name, struct t_hashtable *hashtable) { /* ... */ return pointer_to_new_hashtable; } /* add info "my_info_hashtable" */ struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable", "Some info", "Info about input hashtable", "Info about output hashtable", &my_info_hashtable_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_info_hashtable(info_name: str, description: str, args_description: str, output_description: str, callback: str, callback_data: str) -> str: ... # example def my_info_hashtable_cb(data, 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", "") ---- ==== hook_infolist _Updated in 1.5._ 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)(const void *pointer, void *data, const char *infolist_name, void *obj_pointer, const char *arguments), const void *callback_pointer, void *callback_data); ---- Arguments: * _infolist_name_: name of infolist (a priority is allowed before the infolist name, see note about <>) * _description_: description * _pointer_description_: description of pointer (optional, can be NULL) * _args_description_: description of arguments (optional, can be NULL) * _callback_: function called when infolist is asked, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *infolist_name_: name of infolist ** _void *pointer_: pointer to an object that infolist must return (to get only one item in infolist) ** _const char *arguments_: additional arguments, depending on infolist ** return value: infolist asked * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- struct t_infolist * my_infolist_cb (const void *pointer, void *data, const char *infolist_name, void *obj_pointer, const char *arguments) { struct t_infolist *my_infolist; /* build infolist */ /* ... */ return my_infolist; } /* add infolist "my_infolist" */ struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist", "Infolist with some data", "Info about pointer", "Info about arguments", &my_infolist_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_infolist(infolist_name: str, description: str, pointer_description: str, args_description: str, callback: str, callback_data: str) -> str: ... # example def my_infolist_cb(data, 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", "") ---- ==== hook_hdata _Updated in 1.5._ 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)(const void *pointer, void *data, const char *hdata_name), const void *callback_pointer, void *callback_data); ---- Arguments: * _hdata_name_: name of hdata (a priority is allowed before the hdata name, see note about <>) * _description_: description * _callback_: function called when hdata is asked, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _const char *hdata_name_: name of hdata ** return value: hdata asked * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted Return value: * pointer to new hook, NULL if error occurred C example: [source,c] ---- struct t_hdata * my_hdata_cb (const void *pointer, void *data, const char *hdata_name) { struct t_hdata *my_hdata; /* build hdata */ /* ... */ return my_hdata; } /* add hdata "my_hdata" */ struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata", "Hdata for my structure", &my_hdata_cb, NULL, NULL); ---- [NOTE] This function is not available in scripting API. ==== hook_focus _Updated in 1.5._ 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)(const void *pointer, void *data, struct t_hashtable *info), const void *callback_pointer, void *callback_data); ---- Arguments: * _area_: "chat" for chat area, or name of bar item (a priority is allowed before the area, see note about <>) * _callback_: function called when focus is made, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_hashtable *info_: hashtable with info on focus and strings returned by other calls to focus callbacks (with higher priority) (see table below) ** return value: either "info" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string"), this new hashtable content will be added to _info_ for other calls to focus callbacks * _callback_pointer_: pointer given to callback when it is called by WeeChat * _callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted [IMPORTANT] For a mouse gesture, your callback will be called two times: first time when button is pressed (here the area always matches your area), second time when button is released, and then the area may not match your area: so you must *always* test in your callback if area is matching before using info in hashtable. Content of hashtable sent to callback (keys and values are of type "string"): [width="100%",cols="5,5,8,3",options="header"] |=== | Key ^(1)^ | Description | Value examples | Value if N/A | _x | Column on screen. | "0" ... "n" | | _y | Line on screen. | "0" ... "n" | | _key | Key or mouse event. | "button1", "button2-gesture-left", ... | | _window | Pointer to window. | "0x1234abcd" | "" | _window_number | Number of window . | "1" ... "n" | "*" | _buffer | Pointer to buffer. | "0x1234abcd" | "" | _buffer_number | Number of buffer. | "1" ... "n" | "-1" | _buffer_plugin | Plugin name of buffer. | "core", "irc", ... | "" | _buffer_name | Name of buffer. | "weechat", "libera.#weechat", ... | "" | _buffer_full_name | Full name of buffer. | "core.weechat", "irc.libera.#weechat", ... | "" | _buffer_localvar_XXX ^(2)^ | Local variables of buffer. | any value | not set | _chat | Chat area indicator. | "0" or "1" | "0" | _chat_line | Pointer to line _(WeeChat ≥ 1.2)_. | "0x1234abcd" | "" | _chat_line_x | Column in line ^(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 | Text from beginning of line to (x-1, y). | "He" | "" | _chat_eol | Text from (x, y) to the 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" | _bar_window | Pointer to bar window _(WeeChat ≥ 2.9)_. | "0x1234abcd" | "" |=== [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="100%",cols="^1,^1,5",options="header"] |=== | Plugin ^(1)^ | Key | Description | irc | irc_nick | Pointer to IRC nick _(WeeChat ≥ 3.0)_. | irc | irc_host | Host for nick (if known). | weechat | nick | Nick name. | weechat | prefix | Prefix for nick. | weechat | group | Group name. |=== [NOTE] ^(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 (const void *pointer, void *data, struct t_hashtable *info) { /* add strings in hashtable */ /* ... */ return info; } /* add focus on nicklist */ struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist", &my_focus_nicklist_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def hook_focus(area: str, callback: str, callback_data: str) -> str: ... # example def my_focus_nicklist_cb(data, info): # build dict # ... return my_dict hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "") ---- ==== hook_set _WeeChat ≥ 0.3.9 (script: WeeChat ≥ 0.4.3)._ Set string value of a hook property. Prototype: [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="^1,^1,2,2,5",options="header"] |=== | Name | Min WeeChat | Hook type | Value | Description | subplugin | | any type | any string | Name of sub plugin (commonly script name, which is displayed in `/help command` for a hook of type _command_). | stdin | 0.4.3 | _process_, _process_hashtable_ | any string | Send data on standard input (_stdin_) of child process. | stdin_close | 0.4.3 | _process_, _process_hashtable_ | (not used) | Close pipe used to send data on standard input (_stdin_) of child process. | signal | 1.0 | _process_, _process_hashtable_ | signal number or one of these names: `hup`, `int`, `quit`, `kill`, `term`, `usr1`, `usr2` | Send a signal to the child process. |=== C example: [source,c] ---- struct t_hook *my_command_hook = weechat_hook_command ("abcd", "description", "args", "description args", "", &my_command_cb, NULL, NULL); weechat_hook_set (my_command_hook, "subplugin", "test"); ---- Script (Python): [source,python] ---- # prototype def hook_set(hook: str, property: str, value: str) -> int: ... # 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 ---- ==== 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 def unhook(hook: str) -> int: ... # example weechat.unhook(my_hook) ---- ==== unhook_all _Updated in 1.5._ Unhook everything that has been hooked by current plugin. Prototype: [source,c] ---- void weechat_unhook_all (const char *subplugin); ---- Arguments: * _subplugin_: if not NULL, unhook only hooks with this "subplugin" set (this argument is not available in scripting API) C example: [source,c] ---- weechat_unhook_all (NULL); ---- Script (Python): [source,python] ---- # prototype def unhook_all() -> int: ... # example weechat.unhook_all() ---- [[buffers]] === Buffers Functions to create/query/close buffers. ==== buffer_new _Updated in 1.5._ Open a new buffer. [NOTE] If you want to immediately set buffer properties (buffer type, local variables, key bindings, etc.), then better use the function <<_buffer_new_props,buffer_new_props>> which sets these properties during the buffer creation, before sending signal <>. Prototype: [source,c] ---- struct t_gui_buffer *weechat_buffer_new (const char *name, int (*input_callback)(const void *pointer, void *data, struct t_gui_buffer *buffer, const char *input_data), const void *input_callback_pointer, void *input_callback_data, int (*close_callback)(const void *pointer, void *data, struct t_gui_buffer *buffer), const void *close_callback_pointer, void *close_callback_data); ---- Arguments: * _name_: name of buffer (must be unique for plugin) * _input_callback_: function called when input text is entered on buffer, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer pointer ** _const char *input_data_: input data ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _input_callback_pointer_: pointer given to callback when it is called by WeeChat * _input_callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed * _close_callback_: function called when buffer is closed, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer pointer ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _close_callback_pointer_: pointer given to callback when it is called by WeeChat * _close_callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed Return value: * pointer to new buffer, NULL if error occurred C example: [source,c] ---- int my_input_cb (const void *pointer, void *data, struct t_gui_buffer *buffer, const char *input_data) { weechat_printf (buffer, "Text: %s", input_data); return WEECHAT_RC_OK; } int my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer) { weechat_printf (NULL, "Buffer '%s' will be closed!", weechat_buffer_get_string (buffer, "name")); return WEECHAT_RC_OK; } struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer", &my_input_cb, NULL, NULL, &my_close_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def buffer_new(name: str, input_callback: str, input_callback_data: str, close_callback: str, close_callback_data: str) -> str: ... # example def my_input_cb(data, 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", "") ---- ==== buffer_new_props _WeeChat ≥ 3.5._ Open a new buffer and apply properties. Prototype: [source,c] ---- struct t_gui_buffer *weechat_buffer_new_props (const char *name, struct t_hashtable *properties, int (*input_callback)(const void *pointer, void *data, struct t_gui_buffer *buffer, const char *input_data), const void *input_callback_pointer, void *input_callback_data, int (*close_callback)(const void *pointer, void *data, struct t_gui_buffer *buffer), const void *close_callback_pointer, void *close_callback_data); ---- Arguments: * _name_: name of buffer (must be unique for plugin) * _properties_: properties to apply (see function <<_buffer_set,buffer_set>> for the allowed properties) * _input_callback_: function called when input text is entered on buffer, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer pointer ** _const char *input_data_: input data ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _input_callback_pointer_: pointer given to callback when it is called by WeeChat * _input_callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed * _close_callback_: function called when buffer is closed, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_buffer *buffer_: buffer pointer ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _close_callback_pointer_: pointer given to callback when it is called by WeeChat * _close_callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the buffer is closed Return value: * pointer to new buffer, NULL if error occurred C example: [source,c] ---- int my_input_cb (const void *pointer, void *data, struct t_gui_buffer *buffer, const char *input_data) { weechat_printf (buffer, "Text: %s", input_data); return WEECHAT_RC_OK; } int my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer) { weechat_printf (NULL, "Buffer '%s' will be closed!", weechat_buffer_get_string (buffer, "name")); return WEECHAT_RC_OK; } struct t_hashtable *properties = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); /* buffer with free content */ weechat_hashtable_set (properties, "type", "free"); /* no logging on this buffer */ weechat_hashtable_set (properties, "localvar_set_no_log", "1"); /* bind key alt-c on this buffer */ weechat_hashtable_set (properties, "key_bind_meta-c", "/my_command"); struct t_gui_buffer *my_buffer = weechat_buffer_new_props ("my_buffer", properties, &my_input_cb, NULL, NULL, &my_close_cb, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def buffer_new_props(name: str, properties: Dict[str, str], input_callback: str, input_callback_data: str, close_callback: str, close_callback_data: str) -> str: ... # example def my_input_cb(data, 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 properties = { "type": "free", # buffer with free content "localvar_set_no_log": "1", # no logging on this buffer "key_bind_meta-c": "/my_command", # bind key alt-c on this buffer } buffer = weechat.buffer_new_props("my_buffer", properties, "my_input_cb", "", "my_close_cb", "") ---- ==== current_buffer Return pointer to current buffer (buffer displayed by current window). Prototype: [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 def current_buffer() -> str: ... # example weechat.prnt(weechat.current_buffer(), "Text on current buffer") ---- ==== 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.libera.#weechat` instead of `libera.#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", "libera.#weechat"); struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.libera.#test"); /* WeeChat ≥ 1.0 */ ---- Script (Python): [source,python] ---- # prototype def buffer_search(plugin: str, name: str) -> str: ... # example buffer = weechat.buffer_search("my_plugin", "my_buffer") ---- ==== buffer_search_main Search WeeChat main buffer (_core_ buffer, first buffer displayed when WeeChat is starting). Prototype: [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 def buffer_search_main() -> str: ... # example buffer = weechat.buffer_search_main() ---- ==== 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 def buffer_clear(buffer: str) -> int: ... # example buffer = weechat.buffer_search("my_plugin", "my_buffer") if buffer: weechat.buffer_clear(buffer) ---- ==== buffer_close Close a buffer. Prototype: [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 def buffer_close(buffer: str) -> int: ... # example buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "") # ... weechat.buffer_close(buffer) ---- ==== buffer_merge Merge buffer into another buffer: both buffers will still exist separately, but with same number, and WeeChat will display lines from both buffers (mixed lines). Prototype: [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 def buffer_merge(buffer: str, target_buffer: str) -> int: ... # example # merge current buffer with WeeChat "core" buffer weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main()) ---- ==== buffer_unmerge Unmerge buffer from a group of merged buffers. Prototype: [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 def buffer_unmerge(buffer: str, number: int) -> int: ... # example weechat.buffer_unmerge(weechat.current_buffer(), 1) ---- ==== buffer_get_integer Return integer value of a buffer property. Prototype: [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_visible_count_: number of nicks/groups displayed ** _nicklist_groups_count_: number of groups in nicklist ** _nicklist_visible_groups_count_: number of groups displayed ** _nicklist_nicks_count_: number of nicks in nicklist ** _nicklist_visible_nicks_count_: number of nicks 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_get_empty_: 1 if empty input is sent to input callback, otherwise 0 ** _input_multiline_: 1 if multiple lines are sent as one message to input callback, otherwise 0 ** _input_size_: input size (in bytes) ** _input_length_: input length (number of chars) ** _input_pos_: cursor position in buffer input ** _input_1st_display_: first char displayed on screen ** _num_history_: number of commands in history ** _text_search_: text search type: *** 0: no search at this moment *** 1: 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 def buffer_get_integer(buffer: str, property: str) -> int: ... # example weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number")) ---- ==== buffer_get_string Return string value of a buffer property. Prototype: [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_disable_regex_: POSIX extended regular expression for disabling highlight ** _highlight_regex_: POSIX extended regular expression for highlight ** _highlight_tags_restrict_: restrict highlights to messages with these tags ** _highlight_tags_: force highlight on messages with these tags ** _hotlist_max_level_nicks_: max hotlist level for some nicks ** _localvar_xxx_: get content of local variable "xxx" (replace "xxx" by the name of variable to read) Return value: * string value of property C example: [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 def buffer_get_string(buffer: str, property: str) -> str: ... # example weechat.prnt("", "name / short name of buffer are: %s / %s" % (weechat.buffer_get_string(my_buffer, "name"), weechat.buffer_get_string(my_buffer, "short_name"))) ---- ==== buffer_get_pointer Return pointer value of a buffer property. Prototype: [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_disable_regex_compiled_: regular expression _highlight_disable_regex_ compiled ** _highlight_regex_compiled_: regular expression _highlight_regex_ compiled Return value: * pointer value of property C example: [source,c] ---- weechat_printf (NULL, "plugin pointer of my buffer: %lx", weechat_buffer_get_pointer (my_buffer, "plugin")); ---- Script (Python): [source,python] ---- # prototype def buffer_get_pointer(buffer: str, property: str) -> str: ... # example weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin")) ---- ==== buffer_set Set string value of a buffer property. Prototype: [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,^1,4,8",options="header"] |=== | Name | Min WeeChat | Value | Description | hotlist | | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" | "+": enable hotlist (global setting, buffer pointer is not used) + "-": disable hotlist (global setting, buffer pointer is not used) + priority: add buffer to hotlist with this priority + "-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 | 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 | 0.4.3 | "0" or "1" | "0" to hide messages for the day change, "1" to see them (default for a new buffer). | clear | 1.0 | "0" or "1" | "0" to prevent user from clearing buffer with the command `/buffer clear`, "1" to let user clear the buffer (default for a new buffer) (note: even when it is set to "0", the buffer can still be cleared with the function <<_buffer_clear,buffer_clear>>). | filter | 1.0 | "0" or "1" | "0": disable filters on buffer + "1": enable filters on buffer. | title | | any string | Set new title for buffer. | time_for_each_line | | "0" or "1" | "0" to hide time for all lines in buffer, "1" to see time for all lines (default for a new buffer). | nicklist | | "0" or "1" | "0" to remove nicklist for buffer, "1" to add nicklist for buffer. | nicklist_case_sensitive | | "0" or "1" | "0" to have case insensitive nicklist, "1" to have case sensitive nicklist. | nicklist_display_groups | | "0" or "1" | "0" to hide nicklist groups, "1" to display nicklist groups. | highlight_words | | "-" or comma separated list of words | "-" is a special value to disable any highlight on this buffer, or comma separated list of words to highlight in this buffer, for example: "abc,def,ghi". | highlight_words_add | | comma separated list of words | Comma separated list of words to highlight in this buffer, these words are added to existing highlighted words in buffer. | highlight_words_del | | comma separated list of words | Comma separated list of words to remove from highlighted words on buffer. | highlight_disable_regex | | any string | POSIX extended regular expression for disabling highlight. | highlight_regex | | any string | POSIX extended regular expression for highlight. | highlight_tags_restrict | | comma separated list of tags | Restrict highlights to messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action"). | highlight_tags | | comma separated list of tags | Force highlight on messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action"). | hotlist_max_level_nicks | | comma separated list of "nick:level" | Comma separated list of nicks with max level for hotlist on this buffer (level can be: -1: never in hotlist, 0: low, 1: message, 2: private, 3: highlight), for example: "joe:2,mike:-1,robert:-1" (joe will never produce highlight on buffer, mike and robert will never change hotlist). | hotlist_max_level_nicks_add | | comma separated list of "nick:level" | Comma separated list of nicks with level for hotlist, these nicks are added to existing nicks in buffer. | hotlist_max_level_nicks_del | | comma separated list of nicks | Comma separated list of nicks to remove from hotlist max levels. | key_bind_xxx | | any string | Bind a new key _xxx_, specific to this buffer, value is command to execute for this key. | key_unbind_xxx | | - | Unbind key _xxx_ for this buffer. | input | | 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). | input_get_empty | | "0" or "1" | "0" to disable empty input on this buffer (default behavior), "1" to get empty input. | input_multiline | | "0" or "1" | "0" to send each line separately to this buffer (default behavior), "1" to send multiple lines as a single message. | localvar_set_xxx | | any string | Set new value for local variable _xxx_ (variable is created if it does not exist). | localvar_del_xxx | | - | Remove local variable _xxx_. |=== C example: [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", ""); ---- Script (Python): [source,python] ---- # prototype def buffer_set(buffer: str, property: str, value: str) -> int: ... # examples # disable hotlist (for all buffers) weechat.buffer_set("", "hotlist", "-") # enable again hotlist weechat.buffer_set("", "hotlist", "+") # change buffer name weechat.buffer_set(my_buffer, "name", "my_new_name") # add new local variable "toto" with value "abc" weechat.buffer_set(my_buffer, "localvar_set_toto", "abc") # remove local variable "toto" weechat.buffer_set(my_buffer, "localvar_del_toto", "") ---- ==== buffer_set_pointer Set pointer value of a buffer property. Prototype: [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 (const void *pointer, void *data, struct t_gui_buffer *buffer); int input_callback (const void *pointer, void *data, struct t_gui_buffer *buffer, const char *input_data); int nickcmp_callback (const void *pointer, void *data, struct t_gui_buffer *buffer, const char *nick1, const char *nick2); ---- C example: [source,c] ---- int my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer) { /* ... */ return WEECHAT_RC_OK; } weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb); ---- [NOTE] This function is not available in scripting API. ==== buffer_string_replace_local_var Replace local variables in a string by their values, using buffer local variables. Prototype: [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 def buffer_string_replace_local_var(buffer: str, string: str) -> str: ... # example weechat.buffer_set(my_buffer, "localvar_set_toto", "abc") str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto") # str contains "test with abc" ---- ==== buffer_match_list _WeeChat ≥ 0.3.5._ 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", "libera.#weechat"); if (buffer) { weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*")); /* 1 */ weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*")); /* 0 */ weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.libera.*")); /* 1 */ weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*")); /* 0 */ } ---- Script (Python): [source,python] ---- # prototype def buffer_match_list(buffer: str, string: str) -> int: ... # example buffer = weechat.buffer_search("irc", "libera.#weechat") if buffer: weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*")) # 1 weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*")) # 0 weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.libera.*")) # 1 weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*")) # 0 ---- [[windows]] === Windows Functions to query windows. ==== 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 def current_window() -> str: ... # example current_window = weechat.current_window() ---- ==== window_search_with_buffer _WeeChat ≥ 0.3.5._ Return pointer to window displaying buffer. Prototype: [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 def window_search_with_buffer(buffer: str) -> str: ... # example weechat.prnt("", "window displaying core buffer: %s" % weechat.window_search_with_buffer(weechat.buffer_search_main())) ---- ==== window_get_integer Return integer value of a window property. Prototype: [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 def window_get_integer(window: str, property: str) -> int: ... # example weechat.prnt("", "current window is at position (x,y): (%d,%d)" % (weechat.window_get_integer(weechat.current_window(), "win_x"), weechat.window_get_integer(weechat.current_window(), "win_y"))) ---- ==== window_get_string Return string value of a window property. [NOTE] This function is not used today, it is reserved for a future version. Prototype: [source,c] ---- const char *weechat_window_get_string (struct t_gui_window *window, const char *property); ---- Arguments: * _window_: window pointer * _property_: property name Return value: * string value of property Script (Python): [source,python] ---- # prototype def window_get_string(window: str, property: str) -> str: ... ---- ==== 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 def window_get_pointer(window: str, property: str) -> str: ... # example weechat.prnt("", "buffer displayed in current window: %s" % weechat.window_get_pointer(weechat.current_window(), "buffer")) ---- ==== window_set_title Set title for terminal. Prototype: [source,c] ---- void weechat_window_set_title (const char *title); ---- Arguments: * _title_: new title for terminal (NULL to reset title); string is evaluated, so variables like `${info:version}` can be used (see <<_string_eval_expression,string_eval_expression>>) C example: [source,c] ---- weechat_window_set_title ("new title here"); ---- Script (Python): [source,python] ---- # prototype def window_set_title(title: str) -> int: ... # example weechat.window_set_title("new title here") ---- [[nicklist]] === Nicklist Functions for buffer nicklist. ==== 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 def nicklist_add_group(buffer: str, parent_group: str, name: str, color: str, visible: int) -> str: ... # example group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group", "weechat.color.nicklist_group", 1) ---- ==== nicklist_search_group 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 def nicklist_search_group(buffer: str, from_group: str, name: str) -> str: ... # example group = weechat.nicklist_search_group(my_buffer, "", "test_group") ---- ==== 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 def nicklist_add_nick(buffer: str, group: str, name: str, color: str, prefix: str, prefix_color: str, visible: int) -> str: ... # example if nick_away: color = "weechat.color.nicklist_away" else: color = "bar_fg" nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1) ---- ==== nicklist_search_nick 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 def nicklist_search_nick(buffer: str, from_group: str, name: str) -> str: ... # example nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick") ---- ==== 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 def nicklist_remove_group(buffer: str, group: str) -> int: ... # example weechat.nicklist_remove_group(my_buffer, my_group) ---- ==== nicklist_remove_nick Remove a nick from a nicklist. Prototype: [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 def nicklist_remove_nick(buffer: str, nick: str) -> int: ... # example weechat.nicklist_remove_nick(my_buffer, my_nick) ---- ==== nicklist_remove_all Remove all groups/nicks from a nicklist. Prototype: [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 def nicklist_remove_all(buffer: str) -> int: ... # example weechat.nicklist_remove_all(my_buffer) ---- ==== nicklist_get_next_item _WeeChat ≥ 0.3.7._ Get next group or nick from nicklist (mainly used to display nicklist). Prototype: [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. ==== 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 def nicklist_group_get_integer(buffer: str, group: str, property: str) -> int: ... # example visible = weechat.nicklist_group_get_integer(buffer, group, "visible") ---- ==== nicklist_group_get_string _WeeChat ≥ 0.3.4._ Return string value of a group property. Prototype: [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 def nicklist_group_get_string(buffer: str, group: str, property: str) -> str: ... # example color = weechat.nicklist_group_get_string(buffer, group, "color") ---- ==== nicklist_group_get_pointer _WeeChat ≥ 0.3.4._ Return pointer value of a group property. Prototype: [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 def nicklist_group_get_pointer(buffer: str, group: str, property: str) -> str: ... # example parent = weechat.nicklist_group_get_pointer(buffer, group, "parent") ---- ==== nicklist_group_set _WeeChat ≥ 0.3.4._ 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 <<_nicklist_add_group,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 def nicklist_group_set(buffer: str, group: str, property: str, value: str) -> int: ... # examples # change group color to "bar_fg" weechat.nicklist_group_set(buffer, group, "color", "bar_fg") # change group color to yellow weechat.nicklist_group_set(buffer, group, "color", "yellow") # hide group in nicklist weechat.nicklist_group_set(buffer, group, "visible", "0") ---- ==== nicklist_nick_get_integer _WeeChat ≥ 0.3.4._ Return integer value of a nick property. Prototype: [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 def nicklist_nick_get_integer(buffer: str, nick: str, property: str) -> int: ... # example visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible") ---- ==== nicklist_nick_get_string _WeeChat ≥ 0.3.4._ Return string value of a nick property. Prototype: [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 def nicklist_nick_get_string(buffer: str, nick: str, property: str) -> str: ... # example color = weechat.nicklist_nick_get_string(buffer, nick, "color") ---- ==== nicklist_nick_get_pointer _WeeChat ≥ 0.3.4._ Return pointer value of a nick property. Prototype: [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 def nicklist_nick_get_pointer(buffer: str, nick: str, property: str) -> str: ... # example group = weechat.nicklist_nick_get_pointer(buffer, nick, "group") ---- ==== nicklist_nick_set _WeeChat ≥ 0.3.4._ 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 <<_nicklist_add_nick,nicklist_add_nick>>. | prefix | any string | Prefix of nick. | prefix_color | WeeChat color option name | See argument "prefix_color" of function <<_nicklist_add_nick,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 def nicklist_nick_set(buffer: str, nick: str, property: str, value: str) -> int: ... # examples # change nick color to cyan weechat.nicklist_nick_set(buffer, nick, "color", "cyan") # change prefix to "+" weechat.nicklist_nick_set(buffer, nick, "prefix", "+") # change prefix color to yellow weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow") # hide nick in nicklist weechat.nicklist_nick_set(buffer, nick, "visible", "0") ---- [[bars]] === Bars Functions for bars. ==== 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 def bar_item_search(name: str) -> str: ... # example bar_item = weechat.bar_item_search("myitem") ---- ==== bar_item_new _Updated in 0.4.2, 1.5._ Create a new bar item. Prototype: [source,c] ---- struct t_gui_bar_item *weechat_bar_item_new (const char *name, char *(*build_callback)(const void *pointer, void *data, struct t_gui_bar_item *item, struct t_gui_window *window, struct t_gui_buffer *buffer, struct t_hashtable *extra_info), const void *build_callback_pointer, void *build_callback_data); ---- Arguments: * _name_: bar item name * _build_callback_: function called when bar item is built, arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_gui_bar_item *item_: item pointer ** _struct t_gui_window *window_: window pointer (NULL when called for a root bar) ** _struct t_gui_buffer *buffer_: buffer displayed in window (if window is NULL, then it is current buffer) or buffer given in bar item with syntax: "@buffer:item" _(WeeChat ≥ 0.4.2)_ ** _struct t_hashtable *extra_info_: always NULL (argument is reserved for a future version) _(WeeChat ≥ 0.4.2)_ ** return value: content of bar item * _build_callback_pointer_: pointer given to build callback, when it is called by WeeChat * _build_callback_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the bar item is removed Return value: * pointer to new bar item, NULL if an error occurred C example: [source,c] ---- char * my_build_callback (const void *pointer, void *data, struct t_gui_bar_item *item, struct t_gui_window *window, struct t_gui_buffer *buffer, struct t_hashtable *extra_info) { return strdup ("my content"); } struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem", &my_build_callback, NULL, NULL); ---- Script (Python): [IMPORTANT] For compatibility with versions ≤ 0.4.1, the default callback has only 3 arguments: _data_, _item_ and _window_ (no _buffer_ and _extra_info_). + To use a callback with all arguments, you must add "(extra)" before the name, see example below (supported only in WeeChat ≥ 0.4.2). [source,python] ---- # prototype def bar_item_new(name: str, build_callback: str, build_callback_data: str) -> str: ... # example (callback without "buffer" and "extra_info") def my_build_callback(data, 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 ---- ==== 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 def bar_item_update(name: str) -> int: ... # example weechat.bar_item_update("myitem") ---- ==== 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 def bar_item_remove(item: str) -> int: ... # example weechat.bar_item_remove(myitem) ---- ==== 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 def bar_search(name: str) -> str: ... # example bar = weechat.bar_search("mybar") ---- ==== bar_new _Updated in 2.9._ 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 *color_bg_inactive, const char *separator, const char *items); ---- Arguments: * _name_: bar name * _hidden_: ** _on_: bar is hidden ** _off_: bar is visible * _priority_: bar priority (integer) * _type_: ** _root_: bar displayed once, outside windows ** _window_: bar displayed in each window * _condition_: condition for displaying bar: ** _active_: bar is displayed in active window only ** _inactive_: bar is displayed in inactive windows only ** _nicklist_: bar is displayed in windows with nicklist ** evaluated expression: see the link:weechat_user.en.html#bar_conditions[WeeChat user's guide / Bar conditions ^↗^,window=_blank] * _position_: _top_, _bottom_, _left_ or _right_ * _filling_top_bottom_: ** _horizontal_: items are filled horizontally (space after each item) ** _vertical_: items are filled vertically (new line after each item) ** _columns_horizontal_: items are filled horizontally, displayed with columns ** _columns_vertical_: items are filled vertically, displayed with columns * _filling_left_right_: ** _horizontal_: items are filled horizontally (space after each item) ** _vertical_: items are filled vertically (new line after each item) ** _columns_horizontal_: items are filled horizontally, displayed with columns ** _columns_vertical_: items are filled vertically, displayed with columns * _size_: bar size in chars (0 means automatic size) * _size_max_: max size for bar (0 means no max size) * _color_fg_: color for text in bar * _color_delim_: color for delimiters in bar * _color_bg_: background color for bar * _color_bg_inactive_: background color for window bar which is not displayed in active window * _separator_: ** _on_: bar has separator line with other windows/bars ** _off_: no separator * _items_: list of items in bar, separated by comma (space between items), or "+" (glued items) Return value: * pointer to new bar, NULL if an error occurred 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", "darkgray", "off", "time,buffer_number+buffer_name"); ---- Script (Python): [source,python] ---- # prototype def bar_new(name: str, hidden: str, priority: str, type: str, condition: str, position: str, filling_top_bottom: str, filling_left_right: str, size: str, size_max: str, color_fg: str, color_delim: str, color_bg: str, color_bg_inactive: str, separator: str, items: str) -> str: ... # example bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical", "0", "5", "default", "cyan", "blue", "darkgray", "off", "time,buffer_number+buffer_name") ---- [NOTE] With WeeChat ≥ 2.9, in Ruby, the 4 colors (color_fg, color_delim, color_bg, color_bg_inactive) must be given in an array of 4 strings (due to a Ruby limitation of 15 arguments by function), see the link:++weechat_scripting.en.html#_ruby++[WeeChat scripting guide ^↗^,window=_blank] for more info. ==== 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 <<_bar_new,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 def bar_set(bar: str, property: str, value: str) -> int: ... # example weechat.bar_set(my_bar, "position", "bottom") ---- ==== bar_update Refresh content of a bar on screen. Prototype: [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 def bar_update(name: str) -> int: ... # example weechat.bar_update("mybar") ---- ==== 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 def bar_remove(bar: str) -> int: ... # example weechat.bar_remove(my_bar) ---- [[commands]] === Commands Functions for executing WeeChat commands. ==== command _Updated in 1.1._ Execute a command or send text to buffer. Prototype: [source,c] ---- int weechat_command (struct t_gui_buffer *buffer, const char *command); ---- Arguments: * _buffer_: buffer pointer (command is executed on this buffer, use NULL for current buffer) * _command_: command to execute (if beginning with a "/"), or text to send to buffer Return value _(WeeChat ≥ 1.1)_: * _WEECHAT_RC_OK_ if successful * _WEECHAT_RC_ERROR_ if error C example: [source,c] ---- int rc; rc = weechat_command (weechat_buffer_search ("irc", "libera.#weechat"), "/whois FlashCode"); ---- Script (Python): [source,python] ---- # prototype def command(buffer: str, command: str) -> int: ... # example rc = weechat.command(weechat.buffer_search("irc", "libera.#weechat"), "/whois FlashCode") ---- ==== command_options _WeeChat ≥ 2.5._ Execute a command or send text to buffer with options. Prototype: [source,c] ---- int weechat_command_options (struct t_gui_buffer *buffer, const char *command, struct t_hashtable *options); ---- Arguments: * _buffer_: buffer pointer (command is executed on this buffer, use NULL for current buffer) * _command_: command to execute (if beginning with a "/"), or text to send to buffer * _options_: a hashtable with some options (keys and values must be string) (can be NULL): ** _commands_: a comma-separated list of commands allowed to be executed during this call; see function <<_string_match_list,string_match_list>> for the format ** _delay_: delay to execute command, in milliseconds Return value: * _WEECHAT_RC_OK_ if successful * _WEECHAT_RC_ERROR_ if error C example: [source,c] ---- /* allow any command except /exec, run command in 2 seconds */ int rc; struct t_hashtable *options = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); weechat_hashtable_set (options, "commands", "*,!exec"); weechat_hashtable_set (options, "delay", "2000"); rc = weechat_command_options (NULL, "/some_command arguments", options); ---- Script (Python): [source,python] ---- # prototype def command_options(buffer: str, command: str, options: Dict[str, str]) -> int: ... # example: allow any command except /exec rc = weechat.command("", "/some_command arguments", {"commands": "*,!exec"}) ---- [[completion]] === Completion Functions to complete a command line. ==== completion_new _WeeChat ≥ 2.9._ Create a new completion. Prototype: [source,c] ---- struct t_gui_completion *weechat_completion_new (struct t_gui_buffer *buffer); ---- Arguments: * _buffer_: buffer pointer Return value: * pointer to new completion C example: [source,c] ---- struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ()); ---- Script (Python): [source,python] ---- # prototype def completion_new(buffer: str) -> str: ... # example completion = weechat.completion_new(weechat.buffer_search_main()) ---- ==== completion_search _WeeChat ≥ 2.9._ Search possible words at a given position of a string, in the completion context. Prototype: [source,c] ---- int weechat_completion_search (struct t_gui_completion *completion, const char *data, int position, int direction); ---- Arguments: * _completion_: completion pointer * _data_: the string to complete * _position_: index of the char in string to complete (starts to 0) * _direction_: 1 for next completion, -1 for previous completion Return value: * 1 if OK, 0 if error C example: [source,c] ---- struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ()); if (weechat_completion_search (completion, "/help filt", 10, 1)) { /* ... */ } ---- Script (Python): [source,python] ---- # prototype def completion_search(completion: str, data: str, position: int, direction: int) -> int: ... # example completion = weechat.completion_new(weechat.buffer_search_main()) if weechat.completion_search(completion, "/help filt", 10, 1): # ... ---- ==== completion_get_string _WeeChat ≥ 2.9._ Get a completion property as string. Prototype: [source,c] ---- const char *weechat_completion_get_string (struct t_gui_completion *completion, const char *property); ---- Arguments: * _completion_: completion pointer * _property_: property name: ** _base_command_: command used for completion ** _base_word_: word being completed ** _args_: command arguments (including base word) C example: [source,c] ---- int my_completion_cb (const void *pointer, void *data, const char *completion_item, struct t_gui_buffer *buffer, struct t_gui_completion *completion) { /* get arguments of command */ const char *args = weechat_completion_get_string (completion, "args"); /* completion depending on args */ /* ... */ return WEECHAT_RC_OK; } ---- Script (Python): [source,python] ---- # prototype def completion_get_string(completion: str, property: str) -> str: ... # example def my_completion_cb(data, completion_item, buffer, completion): # get arguments of command args = weechat.completion_get_string(completion, "args") # completion depending on args # ... return weechat.WEECHAT_RC_OK ---- ==== completion_list_add _WeeChat ≥ 2.9._ Add a word for a completion. Prototype: [source,c] ---- void weechat_completion_list_add (struct t_gui_completion *completion, const char *word, int nick_completion, const char *where); ---- Arguments: * _completion_: completion pointer * _word_: word to add * _nick_completion_: 1 if word is a nick, otherwise 0 * _where_: position where word will be inserted in list: ** _WEECHAT_LIST_POS_SORT_: any position, to keep list sorted ** _WEECHAT_LIST_POS_BEGINNING_: beginning of list ** _WEECHAT_LIST_POS_END_: end of list C example: see <<_hook_completion,hook_completion>>. Script (Python): [source,python] ---- # prototype def completion_list_add(completion: str, word: str, nick_completion: int, where: str) -> int: ... # example: see function hook_completion ---- ==== completion_free _WeeChat ≥ 2.9._ Free a completion. Prototype: [source,c] ---- void weechat_completion_free (struct t_gui_completion *completion); ---- Arguments: * _completion_: completion pointer C example: [source,c] ---- weechat_completion_free (completion); ---- Script (Python): [source,python] ---- # prototype def completion_free(completion: str) -> int: ... # example weechat.completion_free(completion) ---- [[network]] === Network Network functions. ==== network_pass_proxy Establish a connection/authentication to a proxy. [IMPORTANT] This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat. Prototype: [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.libera.chat", 6667)) { /* OK */ } else { /* error */ } ---- [NOTE] This function is not available in scripting API. ==== network_connect_to _Updated in 0.4.3._ Establish a connection to a remote host. [IMPORTANT] This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat. Prototype: [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. ==== info_get _Updated in 2.5._ Return info, as string, from WeeChat or a plugin. Prototype: [source,c] ---- char *weechat_info_get (const char *info_name, const char *arguments); ---- Arguments: * _info_name_: name of info to read (see table below) * _arguments_: arguments for info asked (optional, NULL if no argument is needed) Return value: * string with info asked, NULL if an error occurred (must be freed by calling "free" after use) [NOTE] With WeeChat ≥ 2.5, the value returned is an allocated string (with WeeChat ≤ 2.4, it was a pointer to a static string). Infos: include::includes/autogen_api_infos.en.adoc[tag=infos] C example: [source,c] ---- char *version = weechat_info_get ("version", NULL); char *date = weechat_info_get ("date", NULL); weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)", version, date); if (version) free (version); if (date) free (date); char *weechat_config_dir = weechat_info_get ("weechat_config_dir", NULL); weechat_printf (NULL, "WeeChat config directory is: %s", weechat_config_dir); if (weechat_config_dir) free (weechat_config_dir); ---- Script (Python): [source,python] ---- # prototype def info_get(info_name: str, arguments: str) -> str: ... # example weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)" % (weechat.info_get("version", ""), weechat.info_get("date", "")) weechat.prnt("", "WeeChat config directory is: %s" % weechat.info_get("weechat_config_dir", "")) ---- ==== info_get_hashtable _WeeChat ≥ 0.3.4._ Return info, as hashtable, from WeeChat or a plugin. Prototype: [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::includes/autogen_api_infos_hashtable.en.adoc[tag=infos_hashtable] 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", "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :Hello world!"); hashtable_out = weechat_info_get_hashtable ("irc_message_parse", hashtable_in); /* * now hashtable_out has following keys/values: * "tags" : "time=2015-06-27T16:40:35.000Z;tag2=value\\sspace" * "tag_time" : "2015-06-27T16:40:35.000Z" * "tag_tag2" : "value space" * "message_without_tags": ":nick!user@host PRIVMSG #weechat :Hello world!" * "nick" : "nick" * "user" : "user" * "host" : "nick!user@host" * "command" : "PRIVMSG" * "channel" : "#weechat" * "arguments" : "#weechat :Hello world!" * "text" : "Hello world!" * "param1" : "#weechat" * "param2" : "Hello world!" * "num_params" : "2" * "pos_command" : "65" * "pos_arguments" : "73" * "pos_channel" : "73" * "pos_text" : "83" */ weechat_hashtable_free (hashtable_in); weechat_hashtable_free (hashtable_out); } ---- [NOTE] See the link:weechat_scripting.en.html#irc_message_parse[WeeChat scripting guide / Parse message ^↗^,window=_blank] for more info about "irc_message_parse" output. Script (Python): [source,python] ---- # prototype def info_get_hashtable(info_name: str, dict_in: Dict[str, str]) -> Dict[str, str]: ... # example dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message here"} weechat.prnt("", "message parsed: %s" % weechat.info_get_hashtable("irc_message_parse", dict_in)) ---- [[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 ==== 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 def infolist_new() -> str: ... # example infolist = weechat.infolist_new() ---- ==== 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 def infolist_new_item(infolist: str) -> str: ... # example item = weechat.infolist_new_item(infolist) ---- ==== infolist_new_var_integer Add an integer variable to an infolist item. Prototype: [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 def infolist_new_var_integer(item: str, name: str, value: int) -> str: ... # example var = weechat.infolist_new_var_integer(item, "my_integer", 123) ---- ==== infolist_new_var_string Add a string variable to an infolist item. Prototype: [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 def infolist_new_var_string(item: str, name: str, value: str) -> str: ... # example var = weechat.infolist_new_var_string(item, "my_string", "value") ---- ==== infolist_new_var_pointer Add a pointer variable to an infolist item. Prototype: [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 def infolist_new_var_pointer(item: str, name: str, pointer: str) -> str: ... # example var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer) ---- ==== infolist_new_var_buffer Add a buffer variable to an infolist item. Prototype: [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. ==== 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 def infolist_new_var_time(item: str, name: str, time: int) -> str: ... # example var = weechat.infolist_new_var_time(item, "my_time", int(time.time())) ---- ==== infolist_get Return infolist from WeeChat or a plugin. [IMPORTANT] Content of infolist is a duplication of actual data. So if you are asking infolist with lot of data (like "buffer_lines"), WeeChat will allocate memory to duplicate all data, and this can take some time. + Instead of using big infolist, it is preferable to use hdata (but infolist may have more info than hdata, which is raw data), see <>. 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::includes/autogen_api_infolists.en.adoc[tag=infolists] C example: [source,c] ---- struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def infolist_get(infolist_name: str, pointer: str, arguments: str) -> str: ... # example infolist = weechat.infolist_get("irc_server", "", "") ---- ==== infolist_next Move "cursor" to next item in an infolist. The first call to this function for an infolist moves cursor to first item in infolist. Prototype: [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 def infolist_next(infolist: str) -> int: ... # example rc = weechat.infolist_next(infolist) if rc: # read variables in item... else: # no more item available ---- ==== infolist_prev Move "cursor" to previous item in an infolist. The first call to this function for an infolist moves cursor to last item in infolist. Prototype: [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 def infolist_prev(infolist: str) -> int: ... # example rc = weechat.infolist_prev(infolist) if rc: # read variables in item... else: # no more item available ---- ==== infolist_reset_item_cursor Reset "cursor" for infolist. Prototype: [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 def infolist_reset_item_cursor(infolist: str) -> int: ... # example weechat.infolist_reset_item_cursor(infolist) ---- ==== infolist_search_var _WeeChat ≥ 0.4.3._ Search a variable in the current infolist item. Prototype: [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 def infolist_search_var(infolist: str, name: str) -> str: ... # example if weechat.infolist_search_var(infolist, "name"): # variable "name" exists # ... ---- ==== infolist_fields Return list of fields for current infolist item. Prototype: [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 def infolist_fields(infolist: str) -> str: ... # example fields = weechat.infolist_fields(infolist) # fields contains something like: # "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" ---- ==== infolist_integer Return value of integer variable in current infolist item. Prototype: [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 def infolist_integer(infolist: str, var: str) -> int: ... # example weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer")) ---- ==== infolist_string Return value of string variable in current infolist item. Prototype: [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 def infolist_string(infolist: str, var: str) -> str: ... # example weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string")) ---- ==== infolist_pointer Return value of pointer variable in current infolist item. Prototype: [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 def infolist_pointer(infolist: str, var: str) -> str: ... # example weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer")) ---- ==== infolist_buffer Return value of buffer variable in current infolist item. Prototype: [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. ==== 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 def infolist_time(infolist: str, var: str) -> int: ... # example weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time")) ---- ==== 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 def infolist_free(infolist: str) -> int: ... # 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 <<_hdata_update,hdata_update>>. ==== hdata_new _WeeChat ≥ 0.3.6, updated in 0.3.9, 0.4.0._ Create a new hdata. [NOTE] .hdata vs infolist ==== Hdata is a fast way to read WeeChat or plugins data. It is similar to infolist, but there are some differences: * It is faster and uses less memory: direct read of data without duplication. * It may have different info than infolist: it contains only raw data in structures (infolist may add some extra data for convenience). ==== Prototype: [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 <<_hdata_update,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. ==== hdata_new_var _WeeChat ≥ 0.3.6, updated in 0.3.7, 0.3.9, 0.4.3, 3.4._ 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 ≥ 0.4.3_) ** _WEECHAT_HDATA_POINTER_ ** _WEECHAT_HDATA_TIME_ ** _WEECHAT_HDATA_HASHTABLE_ (_WeeChat ≥ 0.3.7_) ** _WEECHAT_HDATA_OTHER_ * _update_allowed_: 1 if update of variable is allowed, otherwise 0 _(WeeChat ≥ 0.3.9)_ * _array_size_: not NULL only if a variable is an array, and it can be: _(WeeChat ≥ 0.3.9)_ ** name of variable in hdata: this variable will be used as size of array (dynamic size for array) ** integer (as string): fixed size for array ** _*_: automatic size: the size of array is computed by looking at values, when the first NULL is found (only for type string, pointer or hashtable) * _hdata_name_: name of a hdata (if it's a pointer to a structure with hdata) With WeeChat ≥ 3.4, the _array_size_ parameter can be prefixed with `*,` for pointer to dynamically allocated array (without this prefix, the array is considered static). Examples of variables and the corresponding array size (_WeeChat ≥ 3.4_): [width="100%",cols="3,3m,2,7",options="header"] |=== | Variable declaration in C | Hdata type | Array size | Description | `+int *numbers;+` | WEECHAT_HDATA_INTEGER | `+*,2+` | Allocated array of 2 integers. | `+int *numbers;+` | WEECHAT_HDATA_INTEGER | `+*,array_size+` | Allocated array of integers, the size is stored in another variable called "array_size". | `+int numbers[3];+` | WEECHAT_HDATA_INTEGER | `+3+` | Static array of 3 integers. | `+char **words;+` | WEECHAT_HDATA_STRING | `+*,*+` | Allocated array of strings, dynamic size (NULL pointer must be present after last word). | `+char **words;+` | WEECHAT_HDATA_STRING | `+*,count_words+` | Allocated array of strings, the size is stored in another variable called "count_words". |=== C example: [source,c] ---- struct t_myplugin_list { char *name; struct t_gui_buffer *buffer; int numbers[3]; int tags_count; char **tags_array; char **string_split; struct t_myplugin_list *prev; struct t_myplugin_list *next; }; /* ... */ struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next"); weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL); weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL); weechat_hdata_new_var (hdata, "numbers", offsetof (struct t_myplugin_list, numbers), WEECHAT_HDATA_INTEGER, 0, "3", NULL); weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL); weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "*,tags_count", NULL); weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*,*", NULL); weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list"); weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list"); ---- The macro "WEECHAT_HDATA_VAR" can be used to shorten code: [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, numbers, INTEGER, 0, "3", NULL); WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL); WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "*,tags_count", NULL); WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*,*", NULL); WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list"); WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list"); ---- [NOTE] This function is not available in scripting API. ==== hdata_new_list _WeeChat ≥ 0.3.6, updated in 1.0._ Create a new list pointer in hdata. Prototype: [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. ==== 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::includes/autogen_api_hdata.en.adoc[tag=hdata] C example: [source,c] ---- struct t_hdata *hdata = weechat_hdata_get ("irc_server"); ---- Script (Python): [source,python] ---- # prototype def hdata_get(hdata_name: str) -> str: ... # example hdata = weechat.hdata_get("irc_server") ---- ==== hdata_get_var_offset _WeeChat ≥ 0.3.6._ Return offset of variable in hdata. Prototype: [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 def hdata_get_var_offset(hdata: str, name: str) -> int: ... # example offset = weechat.hdata_get_var_offset(hdata, "name") ---- ==== hdata_get_var_type _WeeChat ≥ 0.3.6._ Return type of variable in hdata (as integer). Prototype: [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. ==== 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 def hdata_get_var_type_string(hdata: str, name: str) -> str: ... # example weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name")) ---- ==== hdata_get_var_array_size _WeeChat ≥ 0.3.9._ Return array size for variable in hdata. Prototype: [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 def hdata_get_var_array_size(hdata: str, pointer: str, name: str) -> int: ... # example array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name") ---- ==== hdata_get_var_array_size_string _WeeChat ≥ 0.3.9._ Return array size for variable in hdata (as string). Prototype: [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 def hdata_get_var_array_size_string(hdata: str, pointer: str, name: str) -> str: ... # example array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name") ---- ==== hdata_get_var_hdata _WeeChat ≥ 0.3.6._ Return hdata for a variable in hdata. Prototype: [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 def hdata_get_var_hdata(hdata: str, name: str) -> str: ... # example weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name")) ---- ==== hdata_get_var _WeeChat ≥ 0.3.6._ Return pointer to content of variable in hdata. Prototype: [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. ==== 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. ==== 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 def hdata_get_list(hdata: str, name: str) -> str: ... # example hdata = weechat.hdata_get("buffer") buffers = weechat.hdata_get_list(hdata, "gui_buffers") ---- ==== hdata_check_pointer _WeeChat ≥ 0.3.7, updated in 1.0._ Check if a pointer is valid for a hdata and a list pointer. Prototype: [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 <<_hdata_new_list,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 def hdata_check_pointer(hdata: str, list: str, pointer: str) -> int: ... # example hdata = weechat.hdata_get("buffer") if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer): # valid pointer # ... else: # invalid pointer # ... ---- ==== hdata_move _WeeChat ≥ 0.3.6._ Move pointer to another element in list. Prototype: [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 element is not found (for example end of list), or 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 def hdata_move(hdata: str, pointer: str, count: int) -> str: ... # example hdata = weechat.hdata_get("buffer") buffer = weechat.buffer_search_main() # move to next buffer, 2 times buffer = weechat.hdata_move(hdata, buffer, 2) # move to previous buffer if buffer: buffer = weechat.hdata_move(hdata, buffer, -1) ---- ==== hdata_search _WeeChat ≥ 0.4.1, updated in 3.4._ Search element in a list: the expression _search_ is evaluated for each element in list, until element is found (or end of list). Prototype: [source,c] ---- void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, struct t_hashtable *pointers, struct t_hashtable *extra_vars, struct t_hashtable *options, int move); ---- Arguments: * _hdata_: hdata pointer * _pointer_: pointer to a WeeChat/plugin object * _search_: expression to evaluate, default pointer in expression is the name of hdata (and this pointer changes for each element in list); for help on expression, see the link:weechat_user.en.html#command_weechat_eval[WeeChat user's guide / Command /eval ^↗^,window=_blank] * _pointers_: hashtable for call to function <<_string_eval_expression,string_eval_expression>> * _extra_vars_: hashtable for call to function <<_string_eval_expression,string_eval_expression>> * _options_: hashtable for call to function <<_string_eval_expression,string_eval_expression>> * _move_: number of jump(s) to execute after unsuccessful search (negative or positive integer, different from 0) [IMPORTANT] You must ensure the _search_ expression is safe and does not include any user data. Such unsafe data must be given in the hashtable _extra_vars_ and referenced by `${xxx}` in the _search_ expression (see the example below). Return value: * pointer to element found, NULL if not found C example: [source,c] ---- struct t_hdata *hdata = weechat_hdata_get ("irc_server"); void *servers = weechat_hdata_get_list (hdata, "irc_servers"); struct t_hashtable *extra_vars = weechat_hashtable_new (8, WEECHAT_HASHTABLE_STRING, WEECHAT_HASHTABLE_STRING, NULL, NULL); /* search irc server with name "libera" */ weechat_hashtable_set (extra_vars, "server_name", "libera"); void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${server_name}", NULL, extra_vars, NULL, 1); if (server) { /* ... */ } weechat_hashtable_free (extra_vars); ---- Script (Python): [source,python] ---- # prototype def hdata_search(hdata: str, pointer: str, search: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str], count: int) -> str: ... # example hdata = weechat.hdata_get("irc_server") servers = weechat.hdata_get_list(hdata, "irc_servers") # search irc server with name "libera" server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${server_name}", {}, {"server_name": "libera"}, {}, 1) if server: # ... ---- ==== hdata_char _WeeChat ≥ 0.3.7._ Return value of char variable in structure using hdata. Prototype: [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 def hdata_char(hdata: str, pointer: str, name: str) -> int: ... # example weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter")) ---- ==== hdata_integer _WeeChat ≥ 0.3.6._ Return value of integer variable in structure using hdata. Prototype: [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 def hdata_integer(hdata: str, pointer: str, name: str) -> int: ... # example hdata = weechat.hdata_get("buffer") buffer = weechat.buffer_search_main() weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number")) ---- ==== hdata_long _WeeChat ≥ 0.3.6._ Return value of long variable in structure using hdata. Prototype: [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 def hdata_long(hdata: str, pointer: str, name: str) -> int: ... # example weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar")) ---- ==== 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 def hdata_string(hdata: str, pointer: str, name: str) -> str: ... # example hdata = weechat.hdata_get("buffer") buffer = weechat.buffer_search_main() weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name")) ---- ==== hdata_pointer _WeeChat ≥ 0.3.6._ Return value of pointer variable in structure using hdata. Prototype: [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 def hdata_pointer(hdata: str, pointer: str, name: str) -> str: ... # example hdata = weechat.hdata_get("buffer") buffer = weechat.buffer_search_main() weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines")) ---- ==== 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 def hdata_time(hdata: str, pointer: str, name: str) -> int: ... # example buf = weechat.buffer_search_main() ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines") if ptr: ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line") if ptr: ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data") if ptr: date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date") weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date)))) ---- ==== hdata_hashtable _WeeChat ≥ 0.3.7._ Return value of hashtable variable in structure using hdata. Prototype: [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 def hdata_hashtable(hdata: str, pointer: str, name: str) -> Dict[str, str]: ... # example hdata = weechat.hdata_get("buffer") buffer = weechat.buffer_search_main() hash = weechat.hdata_hashtable(hdata, buffer, "local_variables") weechat.prnt("", "local variables in core buffer:") for key in hash: weechat.prnt("", " %s == %s" % (key, hash[key])) ---- ==== hdata_compare _WeeChat ≥ 1.9._ Compare a hdata variable of two objects. Prototype: [source,c] ---- int weechat_hdata_compare (struct t_hdata *hdata, void *pointer1, void *pointer2, const char *name, int case_sensitive); ---- Arguments: * _hdata_: hdata pointer * _pointer1_: pointer to first WeeChat/plugin object * _pointer2_: pointer to second WeeChat/plugin object * _name_: variable name; for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name" * _case_sensitive_: 1 for case sensitive comparison of strings, otherwise 0 Return value: * -1 if variable1 < variable2 * 0 if variable1 == variable2 * 1 if variable1 > variable2 C example: [source,c] ---- struct t_hdata *hdata = weechat_hdata_get ("buffer"); struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat"); struct t_gui_buffer *buffer2 = weechat_buffer_search ("irc", "libera.#weechat-fr"); weechat_printf (NULL, "number comparison = %d", weechat_hdata_compare (hdata, buffer1, buffer2, "number", 0)); ---- Script (Python): [source,python] ---- # prototype def hdata_compare(hdata: str, pointer1: str, pointer2: str, name: str, case_sensitive: int) -> int: ... # example hdata = weechat.hdata_get("buffer") buffer1 = weechat.buffer_search("irc", "libera.#weechat") buffer2 = weechat.buffer_search("irc", "libera.#weechat-fr") weechat.prnt("", "number comparison = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "number", 0)) ---- ==== hdata_set _WeeChat ≥ 0.3.9._ Set new value for variable in a hdata. [NOTE] This function can be called only in an update callback (see <<_hdata_new,hdata_new>> and <<_hdata_update,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. ==== 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 def hdata_update(hdata: str, pointer: str, hashtable: Dict[str, str]) -> int: ... # example: subtract one hour on last message displayed in current buffer own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines") if own_lines: line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line") if line: line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data") hdata = weechat.hdata_get("line_data") weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)}) ---- ==== hdata_get_string _WeeChat ≥ 0.3.6._ Return string value of a hdata property. Prototype: [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 def hdata_get_string(hdata: str, property: str) -> str: ... # example weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys")) weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys")) ---- [[upgrade]] === Upgrade Functions for upgrading WeeChat (command "/upgrade"). ==== upgrade_new _Updated in 1.5._ Create or read a file for upgrade. Prototype: [source,c] ---- struct t_upgrade_file *upgrade_file_new (const char *filename, int (*callback_read)(const void *pointer, void *data, struct t_upgrade_file *upgrade_file, int object_id, struct t_infolist *infolist), const void *callback_read_pointer, void *callback_read_data); ---- Arguments: * _filename_: name of file (extension ".upgrade" is added to this name by WeeChat) * _callback_read_: function called for each object read in upgrade file (if NULL, the upgrade file is opened in write mode), arguments and return value: ** _const void *pointer_: pointer ** _void *data_: pointer ** _struct t_upgrade_file *upgrade_file_: pointer to upgrade file ** _int object_id_: object id ** _struct t_infolist *infolist_: infolist with content of object ** return value: *** _WEECHAT_RC_OK_ *** _WEECHAT_RC_ERROR_ * _callback_read_pointer_: pointer given to callback when it is called by WeeChat * _callback_read_data_: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the upgrade file is closed Return value: * pointer to upgrade file C example: [source,c] ---- struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", NULL, NULL, NULL); ---- Script (Python): [source,python] ---- # prototype def upgrade_new(filename: str, callback_read: str, callback_read_data: str) -> str: ... # example upgrade_file = weechat.upgrade_new("my_file", "", "") ---- ==== upgrade_write_object Write an object in upgrade file. Prototype: [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 def upgrade_write_object(upgrade_file: str, object_id: int, infolist: str) -> int: ... # example weechat.upgrade_write_object(upgrade_file, 1, infolist) ---- ==== upgrade_read _Updated in 1.5._ Read an upgrade file. Prototype: [source,c] ---- int weechat_upgrade_read (struct t_upgrade_file *upgrade_file); ---- Arguments: * _upgrade_file_: upgrade file pointer Return value: * 1 if OK, 0 if error C example: [source,c] ---- weechat_upgrade_read (upgrade_file); ---- Script (Python): [source,python] ---- # prototype def upgrade_read(upgrade_file: str) -> int: ... # example weechat.upgrade_read(upgrade_file) ---- ==== 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 def upgrade_close(upgrade_file: str) -> int: ... # example weechat.upgrade_close(upgrade_file) ----