This manual documents WeeChat chat client, it is part of WeeChat.
Latest version of this document can be found on this page: https://weechat.org/doc
1. Introduction
WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems.
This manual documents WeeChat plugins API, used by C plugins to interact with WeeChat core.
2. Plugins in WeeChat
A plugin is a C program which can call WeeChat functions defined in an interface.
This C program does not need WeeChat sources to compile and can be dynamically
loaded into WeeChat with command /plugin
.
The plugin has to be a dynamic library, for dynamic loading by operating system. Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.
The plugin has to include "weechat-plugin.h" file (available in WeeChat source code). This file defines structures and types used to communicate with WeeChat.
2.1. Macros
The plugin must use some macros (to define some variables):
- WEECHAT_PLUGIN_NAME("name")
-
plugin name
- WEECHAT_PLUGIN_DESCRIPTION("description")
-
short description of plugin
- WEECHAT_PLUGIN_VERSION("1.0")
-
plugin version
- WEECHAT_PLUGIN_LICENSE("GPL3")
-
plugin license
2.2. Main functions
The plugin must use two functions:
-
weechat_plugin_init
-
weechat_plugin_end
2.2.1. weechat_plugin_init
This function is called when plugin is loaded by WeeChat.
Prototype:
Arguments:
-
plugin: pointer to WeeChat plugin structure
-
argc: number of arguments for plugin (given on command line by user)
-
argv: arguments for plugin
Return value:
-
WEECHAT_RC_OK if successful (plugin will be loaded)
-
WEECHAT_RC_ERROR if error (plugin will NOT be loaded)
2.2.2. weechat_plugin_end
This function is called when plugin is unloaded by WeeChat.
Prototype:
Arguments:
-
plugin: pointer to WeeChat plugin structure
Return value:
-
WEECHAT_RC_OK if successful
-
WEECHAT_RC_ERROR if error
2.3. Compile plugin
Compile does not need WeeChat sources, only file weechat-plugin.h is required.
To compile a plugin which has one file "toto.c" (under GNU/Linux):
$ gcc -fPIC -Wall -c toto.c
$ gcc -shared -fPIC -o libtoto.so toto.o
2.4. Load plugin
Copy file libtoto.so into system plugins directory (for example /usr/local/lib/weechat/plugins) or into user’s plugins directory (for example /home/xxx/.weechat/plugins).
Under WeeChat:
/plugin load toto
2.5. Plugin example
Full example of plugin, which adds a command /double: displays two times arguments on current buffer, or execute two times a command (OK that’s not very useful, but that’s just an example!):
3. Plugin API
Following chapters describe functions in API, sorted by category.
For each function, we give:
-
description of function,
-
C prototype,
-
detail of arguments,
-
return value,
-
C example,
-
example in Python script (syntax for other scripting languages is similar).
3.1. Plugins
Functions to get infos about plugins.
3.1.1. weechat_plugin_get_name
Get plugin name.
Prototype:
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:
Script (Python):
3.2. 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.
3.2.1. weechat_charset_set
Set new plugin charset (default charset is UTF-8, so if your plugin uses UTF-8, you don’t need to call this function).
Prototype:
Arguments:
-
charset: new charset to use
C example:
Script (Python):
3.2.2. weechat_iconv_to_internal
Convert string to WeeChat internal charset (UTF-8).
Prototype:
Arguments:
-
charset: charset to convert
-
string: string to convert
Return value:
-
converted string (must be freed by calling "free" after use)
C example:
Script (Python):
3.2.3. weechat_iconv_from_internal
Convert string from internal WeeChat charset (UTF-8) to another.
Prototype:
Arguments:
-
charset: target charset
-
string: string to convert
Return value:
-
converted string (must be freed by calling "free" after use)
C example:
Script (Python):
3.2.4. weechat_gettext
Return translated string (depends on local language).
Prototype:
Arguments:
-
string: string to translate
Return value:
-
translated string
C example:
Script (Python):
3.2.5. weechat_ngettext
Return translated string, using single or plural form, according to count argument.
Prototype:
Arguments:
-
string: string to translate, single form
-
plural: string to translate, plural form
-
count: used to choose between single and plural form (choice is made according to local language)
Return value:
-
translated string
C example:
Script (Python):
3.2.6. weechat_strndup
Return duplicated string, with length chars max.
Prototype:
Arguments:
-
string: string to duplicate
-
length: max chars to duplicate
Return value:
-
duplicated string (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.7. weechat_string_tolower
Convert UTF-8 string to lower case.
Prototype:
Arguments:
-
string: string to convert
C example:
Note
|
This function is not available in scripting API. |
3.2.8. weechat_string_toupper
Convert UTF-8 string to upper case.
Prototype:
Arguments:
-
string: string to convert
C example:
Note
|
This function is not available in scripting API. |
3.2.9. weechat_strcasecmp
Updated in 1.0.
Locale and case independent string comparison.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.10. weechat_strcasecmp_range
WeeChat ≥ 0.3.7, updated in 1.0.
Locale and case independent string comparison, using a range for case comparison.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.11. weechat_strncasecmp
Updated in 1.0.
Locale and case independent string comparison, for max chars.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.12. weechat_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:
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:
Note
|
This function is not available in scripting API. |
3.2.13. weechat_strcmp_ignore_chars
Updated in 1.0.
Locale (and optionally case independent) string comparison, ignoring some chars.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.14. weechat_strcasestr
Locale and case independent string search.
Prototype:
Arguments:
-
string: string
-
search: string to search in string
Return value:
-
pointer to string found, or NULL if not found
C example:
Note
|
This function is not available in scripting API. |
3.2.15. weechat_strlen_screen
WeeChat ≥ 0.4.2.
Return number of chars needed on screen to display UTF-8 string. Non-printable chars have a width of 1 (this is the difference with the function weechat_utf8_strlen_screen).
Prototype:
Arguments:
-
string: string
Return value:
-
number of chars needed on screen to display UTF-8 string
C example:
Script (Python):
3.2.16. weechat_string_match
Updated in 1.0.
Check if a string matches a mask.
Prototype:
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:
Script (Python):
3.2.17. weechat_string_expand_home
WeeChat ≥ 0.3.3.
Replace leading ~
by string with home directory. If string does not start
with ~
, then same string is returned.
Prototype:
Arguments:
-
path: path
Return value:
-
path with leading
~
replaced by home directory (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.18. weechat_string_remove_quotes
Remove quotes at beginning and end of string (ignore spaces if there are before first quote or after last quote).
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.19. weechat_string_strip
Strip chars at beginning and/or end of string.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.20. weechat_string_convert_escaped_chars
WeeChat ≥ 1.0.
Convert escaped chars to their value:
-
\"
: double quote -
\\
: backslash -
\a
: alert (BEL) -
\b
: backspace -
\e
: escape -
\f
: form feed -
\n
: new line -
\r
: carriage return -
\t
: horizontal tab -
\v
: vertical tab -
\0ooo
: char as octal value (ooo is 0 to 3 digits) -
\xhh
: char as hexadecimal value (hh is 1 to 2 digits) -
\uhhhh
: unicode char as hexadecimal value (hhhh is 1 to 4 digits) -
\Uhhhhhhhh
: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)
Prototype:
Arguments:
-
string: string
Return value:
-
string with escaped chars replaced by their value (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.21. weechat_string_mask_to_regex
Return a regex, built with a mask, where only special char is "*
". All other
special chars for regex are escaped.
Prototype:
Arguments:
-
mask: mask
Return value:
-
regular expression, as string (must be freed by calling "free" after use)
C example:
Script (Python):
3.2.22. weechat_string_regex_flags
WeeChat ≥ 0.3.7.
Get pointer on string after flags and mask with flags to compile regular expression.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.23. weechat_string_regcomp
WeeChat ≥ 0.3.7.
Compile a POSIX extended regular expression using optional flags at beginning of string (for format of flags, see weechat_string_regex_flags).
Prototype:
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, seeman regcomp
)
C example:
Note
|
This function is not available in scripting API. |
3.2.24. weechat_string_has_highlight
Check if a string has one or more highlights, using list of highlight words.
Prototype:
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:
Script (Python):
3.2.25. weechat_string_has_highlight_regex
WeeChat ≥ 0.3.4.
Check if a string has one or more highlights, using a POSIX extended regular
expression.
For at least one match of regular expression on string, it must be surrounded
by delimiters (chars different from: alphanumeric, "-", "_" and "|").
Prototype:
Arguments:
-
string: string
-
regex: POSIX extended regular expression
Return value:
-
1 if string has one or more highlights, otherwise 0
C example:
Script (Python):
3.2.26. weechat_string_replace
Replace all occurrences of a string by another string.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.2.27. weechat_string_replace_regex
WeeChat ≥ 1.0.
Replace text in a string using a regular expression, replacement text and optional callback.
Prototype:
Arguments:
-
string: string
-
regex: pointer to a regular expression (regex_t structure) compiled with WeeChat function weechat_string_regcomp or regcomp (see
man regcomp
) -
replace: replacement text, where following references are allowed:
-
$0
to$99
: match 0 to 99 in regular expression (0 is the whole match, 1 to 99 are groups captured between parentheses) -
$+
: the last match (with highest number) -
$.*N
: matchN
(can be+
or0
to99
), 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:
Note
|
This function is not available in scripting API. |
3.2.28. weechat_string_split
Split a string according to one or more delimiter(s).
Prototype:
Arguments:
-
string: string to split
-
separators: delimiters used for split
-
keep_eol:
-
0: each string will contain one word
-
1: each string will contain all string until end of line (see example below)
-
2: same as 1, but do not remove separators at end of string before split (WeeChat ≥ 0.3.6)
-
-
num_items_max: maximum number of items created (0 = no limit)
-
num_items: pointer to int which will contain number of items created
Return value:
-
array of strings, NULL if problem (must be freed by calling weechat_string_free_split after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.29. weechat_string_split_shell
WeeChat ≥ 1.0.
Split a string like the shell does for a command with arguments.
This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in Python repository), see: http://docs.python.org/3/library/shlex.html.
Prototype:
Arguments:
-
string: string to split
-
num_items: pointer to int which will contain number of items created
Return value:
-
array of strings, NULL if problem (must be freed by calling weechat_string_free_split after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.30. weechat_string_free_split
Free memory used by a split string.
Prototype:
Arguments:
-
split_string: string split by function weechat_string_split
C example:
Note
|
This function is not available in scripting API. |
3.2.31. weechat_string_build_with_split_string
Build a string with a split string.
Prototype:
Arguments:
-
split_string: string split by function weechat_string_split
-
separator: string used to separate strings
Return value:
-
string built with split string (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.32. weechat_string_split_command
Split a list of commands separated by separator (which can be escaped by "\" in string).
Prototype:
Arguments:
-
command: command to split
-
separator: separator
Return value:
-
array of strings, NULL if problem (must be freed by calling weechat_free_split_command after use)
C example:
Note
|
This function is not available in scripting API. |
3.2.33. weechat_string_free_split_command
Free memory used by a split command.
Prototype:
Arguments:
-
split_command: command split by weechat_string_split_command
C example:
Note
|
This function is not available in scripting API. |
3.2.34. weechat_string_format_size
Build a string with formatted file size and a unit translated to local language.
Prototype:
Arguments:
-
size: size (in bytes)
Return value:
-
formatted string (must be freed by calling "free" after use)
C examples:
Note
|
This function is not available in scripting API. |
3.2.35. weechat_string_remove_color
Remove WeeChat colors from a string.
Prototype:
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:
Script (Python):
3.2.36. weechat_string_encode_base64
WeeChat ≥ 0.3.2.
Encode a string in base64.
Prototype:
Arguments:
-
from: string to encode
-
length: length of string to encode (for example
strlen(from)
) -
to: pointer to string to store result (must be long enough, result is longer than initial string)
C example:
Note
|
This function is not available in scripting API. |
3.2.37. weechat_string_decode_base64
WeeChat ≥ 0.3.2.
Decode a base64 string.
Prototype:
Arguments:
-
from: string to decode
-
to: pointer to string to store result (must be long enough, result is shorter than initial string)
Return value:
-
length of string stored in *to (does not count final \0)
C example:
Note
|
This function is not available in scripting API. |
3.2.38. weechat_string_is_command_char
WeeChat ≥ 0.3.2.
Check if first char of string is a command char (default command char is /).
Prototype:
Arguments:
-
string: string
Return value:
-
1 if first char of string is a command char, otherwise 0
C examples:
Script (Python):
3.2.39. weechat_string_input_for_buffer
WeeChat ≥ 0.3.2.
Return pointer to input text for buffer (pointer inside "string" argument), or NULL if it’s a command.
Prototype:
Arguments:
-
string: string
Return value:
-
pointer into "string", or NULL
C examples:
Script (Python):
3.2.40. weechat_string_eval_expression
WeeChat ≥ 0.4.0, updated in 0.4.2 and 1.1.
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:
Arguments:
-
expr: the expression to evaluate (see table below)
-
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 weechat_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: "}")
-
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)
-
Return value:
-
evaluated expression (must be freed by calling "free" after use), or NULL if problem (invalid expression or not enough memory)
List of variables expanded in expression (by order of priority, from first expanded to last):
Format | Description | Examples | Results |
---|---|---|---|
|
Variable |
|
|
|
String with escaped chars |
|
|
|
String with hidden chars (all chars in |
|
|
|
Regex captured group: 0 = whole string matching, 1 to 99 = group captured,
|
|
|
|
WeeChat color code (the name of color has optional attributes) |
|
|
|
Info from WeeChat or a plugin, see function weechat_info_get |
|
|
|
Value of the secured data |
|
|
|
Value of the option |
|
|
|
Value of local variable |
|
|
|
Hdata value (pointers |
|
|
C examples:
Script (Python):
3.3. UTF-8
Some UTF-8 string functions.
3.3.1. weechat_utf8_has_8bits
Check if a string has 8-bits chars.
Prototype:
Arguments:
-
string: string
Return value:
-
1 if string has 8-bits chars, 0 if only 7-bits chars
C example:
Note
|
This function is not available in scripting API. |
3.3.2. weechat_utf8_is_valid
Check if a string is UTF-8 valid.
Prototype:
Arguments:
-
string: string
-
error: if not NULL, error is set with pointer to first non valid UTF-8 char in string, if any
Return value:
-
1 if UTF-8 string is valid, otherwise 0
C example:
Note
|
This function is not available in scripting API. |
3.3.3. weechat_utf8_normalize
Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char.
Prototype:
Arguments:
-
string: string
-
replacement: replacement char for invalid chars
C example:
Note
|
This function is not available in scripting API. |
3.3.4. weechat_utf8_prev_char
Return pointer to previous UTF-8 char in a string.
Prototype:
Arguments:
-
string_start: start of string (function will not return a char before this pointer)
-
string: pointer to string (must be ≥ string_start)
Return value:
-
pointer to previous UTF-8 char, NULL if not found (start of string reached)
C example:
Note
|
This function is not available in scripting API. |
3.3.5. weechat_utf8_next_char
Return pointer to next UTF-8 char in a string.
Prototype:
Arguments:
-
string: string
Return value:
-
pointer to next UTF-8 char, NULL if not found (end of string reached)
C example:
Note
|
This function is not available in scripting API. |
3.3.6. weechat_utf8_char_int
Return UTF-8 char as integer.
Prototype:
Arguments:
-
string: string
Return value:
-
UTF-8 char as integer
C example:
Note
|
This function is not available in scripting API. |
3.3.7. weechat_utf8_char_size
Return UTF-8 char size (in bytes).
Prototype:
Arguments:
-
string: string
Return value:
-
UTF-8 char size (in bytes)
C example:
Note
|
This function is not available in scripting API. |
3.3.8. weechat_utf8_strlen
Return UTF-8 string length (in UTF-8 chars).
Prototype:
Arguments:
-
string: string
Return value:
-
UTF-8 string length (number of UTF-8 chars)
C example:
Note
|
This function is not available in scripting API. |
3.3.9. weechat_utf8_strnlen
Return UTF-8 string length (in UTF-8 chars), for max bytes in string.
Prototype:
Arguments:
-
string: string
-
bytes: max bytes
Return value:
-
UTF-8 string length (number of UTF-8 chars)
C example:
Note
|
This function is not available in scripting API. |
3.3.10. weechat_utf8_strlen_screen
Return number of chars needed on screen to display UTF-8 string.
Prototype:
Arguments:
-
string: string
Return value:
-
number of chars needed on screen to display UTF-8 string
C example:
Note
|
This function is not available in scripting API. |
3.3.11. weechat_utf8_charcmp
Updated in 1.0.
Compare two UTF-8 chars.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.3.12. weechat_utf8_charcasecmp
Updated in 1.0.
Compare two UTF-8 chars, ignoring case.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.3.13. weechat_utf8_char_size_screen
Return number of chars needed on screen to display UTF-8 char.
Prototype:
Arguments:
-
string: string
Return value:
-
number of chars needed on screen to display UTF-8 char
C example:
Note
|
This function is not available in scripting API. |
3.3.14. weechat_utf8_add_offset
Move forward N chars in an UTF-8 string.
Prototype:
Arguments:
-
string: string
-
offset: number of chars
Return value:
-
pointer to string, N chars after (NULL if it’s not reachable)
C example:
Note
|
This function is not available in scripting API. |
3.3.15. weechat_utf8_real_pos
Return real position in UTF-8 string.
Prototype:
Arguments:
-
string: string
-
pos: position (number of chars)
Return value:
-
real potision (in bytes)
C example:
Note
|
This function is not available in scripting API. |
3.3.16. weechat_utf8_pos
Return position in UTF-8 string.
Prototype:
Arguments:
-
string: string
-
real_pos: position (bytes)
Return value:
-
position (number of chars)
C example:
Note
|
This function is not available in scripting API. |
3.3.17. weechat_utf8_strndup
Return duplicate string, with length chars max.
Prototype:
Arguments:
-
string: string
-
length: max chars to duplicate
Return value:
-
duplicated string (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.4. Directories
Some functions related to directories.
3.4.1. weechat_mkdir_home
Create a directory in WeeChat home.
Prototype:
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:
Script (Python):
3.4.2. weechat_mkdir
Create a directory.
Prototype:
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:
Script (Python):
3.4.3. weechat_mkdir_parents
Create a directory and make parent directories as needed.
Prototype:
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:
Script (Python):
3.4.4. weechat_exec_on_files
Find files in a directory and execute a callback on each file.
Prototype:
Arguments:
-
directory: directory for searching files
-
hidden_files: 1 to include hidden files, otherwise 0
-
data: pointer given to callback when it is called by WeeChat
-
callback: function called for each file found, arguments:
-
void *data: pointer
-
const char *filename: filename found
-
C example:
Note
|
This function is not available in scripting API. |
3.4.5. weechat_file_get_content
WeeChat ≥ 0.3.1.
Get content of text file in a string.
Prototype:
Arguments:
-
filename: path and file name
Return value:
-
content of file as string (must be freed by calling "free" after use)
C example:
Note
|
This function is not available in scripting API. |
3.5. Util
Some useful functions.
3.5.1. weechat_util_timeval_cmp
Compare two "timeval" structures.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.5.2. weechat_util_timeval_diff
Updated in 1.1.
Return difference (in microseconds) between two "timeval" structures.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.5.3. weechat_util_timeval_add
Updated in 1.1.
Add interval (in microseconds) to a timeval structure.
Prototype:
Arguments:
-
tv: timeval structure
-
interval: interval (in microseconds)
Note
|
With WeeChat ≤ 1.0, the interval was expressed in milliseconds. |
C example:
Note
|
This function is not available in scripting API. |
3.5.4. weechat_util_get_time_string
WeeChat ≥ 0.3.2.
Get date/time as a string built with "strftime".
Prototype:
Arguments:
-
date: pointer to date
C example:
Note
|
This function is not available in scripting API. |
3.5.5. weechat_util_version_number
WeeChat ≥ 0.3.9.
Convert a string with WeeChat version to a number.
Prototype:
Arguments:
-
version: WeeChat version as string (example: "0.3.9" or "0.3.9-dev")
C example:
Note
|
This function is not available in scripting API. |
3.6. Sorted lists
Sorted list functions.
3.6.1. weechat_list_new
Create a new list.
Prototype:
Return value:
-
pointer to new list
C example:
Script (Python):
3.6.2. weechat_list_add
Add an item in a list.
Prototype:
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:
Script (Python):
3.6.3. weechat_list_search
Search an item in a list.
Prototype:
Arguments:
-
weelist: list pointer
-
data: data to search in list
Return value:
-
pointer to item found, NULL if item was not found
C example:
Script (Python):
3.6.4. weechat_list_search_pos
WeeChat ≥ 0.3.4.
Search an item position in a list.
Prototype:
Arguments:
-
weelist: list pointer
-
data: data to search in list
Return value:
-
position of item found, -1 if item was not found
C example:
Script (Python):
3.6.5. weechat_list_casesearch
Search an item in a list, ignoring case.
Prototype:
Arguments:
-
weelist: list pointer
-
data: data to search in list
Return value:
-
pointer to item found, NULL if item was not found
C example:
Script (Python):
3.6.6. weechat_list_casesearch_pos
WeeChat ≥ 0.3.4.
Search an item position in a list, ignoring case.
Prototype:
Arguments:
-
weelist: list pointer
-
data: data to search in list
Return value:
-
position of item found, -1 if item was not found
C example:
Script (Python):
3.6.7. weechat_list_get
Return an item in a list by position.
Prototype:
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:
Script (Python):
3.6.8. weechat_list_set
Set new value for an item.
Prototype:
Arguments:
-
item: item pointer
-
value: new value for item
C example:
Script (Python):
3.6.9. weechat_list_next
Return next item in list.
Prototype:
Arguments:
-
item: item pointer
Return value:
-
pointer to next item, NULL if pointer was last item in list
C example:
Script (Python):
3.6.10. weechat_list_prev
Return previous item in list.
Prototype:
Arguments:
-
item: item pointer
Return value:
-
pointer to previous item, NULL if pointer was first item in list
C example:
Script (Python):
3.6.11. weechat_list_string
Return string value of an item.
Prototype:
Arguments:
-
item: item pointer
Return value:
-
string value of item
C example:
Script (Python):
3.6.12. weechat_list_size
Return size of list (number of items).
Prototype:
Arguments:
-
weelist: list pointer
Return value:
-
size of list (number of items), 0 if list is empty
C example:
Script (Python):
3.6.13. weechat_list_remove
Remove an item in a list.
Prototype:
Arguments:
-
weelist: list pointer
-
item: item pointer
C example:
Script (Python):
3.6.14. weechat_list_remove_all
Remove all items in a list.
Prototype:
Arguments:
-
weelist: list pointer
C example:
Script (Python):
3.6.15. weechat_list_free
Free a list.
Prototype:
Arguments:
-
weelist: list pointer
C example:
Script (Python):
3.7. Hashtables
Hashtable functions.
3.7.1. weechat_hashtable_new
WeeChat ≥ 0.3.3.
Create a new hashtable.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.2. weechat_hashtable_set_with_size
WeeChat ≥ 0.3.3, updated in 0.4.2.
Add or update item in a hashtable with size for key and value.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.3. weechat_hashtable_set
WeeChat ≥ 0.3.3, updated in 0.4.2.
Add or update item in a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
-
key: key pointer
-
value: value pointer
Return value:
-
pointer to item created/updated, NULL if error
C example:
Note
|
This function is not available in scripting API. |
3.7.4. weechat_hashtable_get
WeeChat ≥ 0.3.3.
Get value associated with a key in a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
-
key: key pointer
Return value:
-
value for key, NULL if key is not found
C example:
Note
|
This function is not available in scripting API. |
3.7.5. weechat_hashtable_has_key
WeeChat ≥ 0.3.4.
Check if a key is in the hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
-
key: key pointer
Return value:
-
1 if key is in hashtable, 0 if key is not in hashtable
C example:
Note
|
This function is not available in scripting API. |
3.7.6. weechat_hashtable_map
WeeChat ≥ 0.3.3.
Call a function on all hashtable entries.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.7. weechat_hashtable_map_string
WeeChat ≥ 0.3.7.
Call a function on all hashtable entries, sending keys and values as strings.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.8. weechat_hashtable_dup
WeeChat ≥ 1.0.
Duplicate a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
Return value:
-
duplicated hashtable
C example:
Note
|
This function is not available in scripting API. |
3.7.9. weechat_hashtable_get_integer
WeeChat ≥ 0.3.3.
Return integer value of a hashtable property.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.10. weechat_hashtable_get_string
WeeChat ≥ 0.3.4.
Return string value of a hashtable property.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.11. weechat_hashtable_set_pointer
WeeChat ≥ 0.3.4.
Set pointer value of a hashtable property.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.12. weechat_hashtable_add_to_infolist
WeeChat ≥ 0.3.3.
Add hashtable items to an infolist item.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.7.13. weechat_hashtable_remove
WeeChat ≥ 0.3.3.
Remove an item in a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
-
key: key pointer
C example:
Note
|
This function is not available in scripting API. |
3.7.14. weechat_hashtable_remove_all
WeeChat ≥ 0.3.3.
Remove all items in a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
C example:
Note
|
This function is not available in scripting API. |
3.7.15. weechat_hashtable_free
WeeChat ≥ 0.3.3.
Free a hashtable.
Prototype:
Arguments:
-
hashtable: hashtable pointer
C example:
Note
|
This function is not available in scripting API. |
3.8. Configuration files
Functions for configuration files.
3.8.1. weechat_config_new
Create a new configuration file.
Prototype:
Arguments:
-
name: name of configuration file (without path or extension)
-
callback_reload: function called when configuration file is reloaded with
/reload
(optional, can be NULL), arguments and return value:-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
return value:
-
WEECHAT_CONFIG_READ_OK
-
WEECHAT_CONFIG_READ_MEMORY_ERROR
-
WEECHAT_CONFIG_READ_FILE_NOT_FOUND
-
-
-
callback_reload_data: pointer given to reload callback when it is called by WeeChat
Return value:
-
pointer to new configuration file, NULL if an error occurred
Note
|
File is NOT created on disk by this function. It will be created by call to function weechat_config_write. You should call this function only after adding some sections (with weechat_config_new_section) and options (with weechat_config_new_option). |
C example:
Script (Python):
3.8.2. weechat_config_new_section
Create a new section in configuration file.
Prototype:
Arguments:
-
config_file: configuration file pointer
-
name: name of section
-
user_can_add_options: 1 if user can create new options in section, or 0 if it is forbidden
-
user_can_delete_options: 1 if user can delete options in section, or 0 if it is forbidden
-
callback_read: function called when an option in section is read from disk (should be NULL in most cases, except if options in section need custom function), arguments and return value:
-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
struct t_config_section *section: section pointer
-
const char *option_name: name of option
-
const char *value: value
-
return value:
-
WEECHAT_CONFIG_READ_OK
-
WEECHAT_CONFIG_READ_MEMORY_ERROR
-
WEECHAT_CONFIG_READ_FILE_NOT_FOUND
-
-
-
callback_read_data: pointer given to callback when it is called by WeeChat
-
callback_write: function called when section is written in file (should be NULL for most cases, except if section needs to be written by a custom function), arguments and return value:
-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
struct t_config_section *section: section pointer
-
const char *option_name: name of option
-
return value:
-
WEECHAT_CONFIG_WRITE_OK
-
WEECHAT_CONFIG_WRITE_ERROR
-
WEECHAT_CONFIG_WRITE_MEMORY_ERROR
-
-
-
callback_write_data: pointer given to callback when it is called by WeeChat
-
callback_write_default: function called when default values for section must be written in file, arguments and return value:
-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
const char *section_name: name of section
-
return value:
-
WEECHAT_CONFIG_WRITE_OK
-
WEECHAT_CONFIG_WRITE_ERROR
-
WEECHAT_CONFIG_WRITE_MEMORY_ERROR
-
-
-
callback_write_default_data: pointer given to callback when it is called by WeeChat
-
callback_create_option: function called when a new option is created in section (NULL if section does not allow new options to be created), arguments and return value:
-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
struct t_config_section *section: section pointer
-
const char *option_name: name of option
-
const char *value: value
-
return value:
-
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
-
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
-
WEECHAT_CONFIG_OPTION_SET_ERROR
-
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
-
-
-
callback_create_option_data: pointer given to callback when it is called by WeeChat
-
callback_delete_option: function called when an option is deleted in section (NULL if section does not allow options to be deleted), arguments and return value:
-
void *data: pointer
-
struct t_config_file *config_file: configuration file pointer
-
struct t_config_section *section: section pointer
-
struct t_config_option *option: option pointer
-
return value:
-
WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
-
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
-
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
-
WEECHAT_CONFIG_OPTION_UNSET_ERROR
-
-
-
callback_delete_option_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new section in configuration file, NULL if an error occurred
C example:
Script (Python):
3.8.3. weechat_config_search_section
Search a section in a configuration file.
Prototype:
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:
Script (Python):
3.8.4. weechat_config_new_option
Create a new option in a section of a configuration file.
Prototype:
Arguments:
-
config_file: configuration file pointer
-
section: section pointer
-
name: name of option
-
type: type of option:
-
boolean: boolean value (on/off)
-
integer: integer value (with optional strings for values)
-
string: string value
-
color: color
-
-
description: description of option
-
string_values: values as string (separated by "|"), used for type integer (optional)
-
min: minimum value (for type integer)
-
max: maximum value (for type integer)
-
default_value: default value for option (used when option is reset)
-
value: value for option
-
null_value_allowed: 1 if null (undefined value) is allowed for option, otherwise 0
-
callback_check_value: function called to check new value for option (optional), arguments and return value:
-
void *data: pointer
-
struct t_config_option *option: option pointer
-
const char *value: new value for option
-
return value:
-
1 if value is OK
-
0 if value is invalid
-
-
-
callback_check_value_data: pointer given to check_value callback when it is called by WeeChat
-
callback_change: function called when value of option has changed (optional), arguments:
-
void *data: pointer
-
struct t_config_option *option: option pointer
-
-
callback_change_data: pointer given to change callback when it is called by WeeChat
-
callback_delete: function called when option will be deleted (optional), arguments:
-
void *data: pointer
-
struct t_config_option *option: option pointer
-
-
callback_delete_data: pointer given to delete callback when it is called by WeeChat
Return value:
-
pointer to new option in section, NULL if an error
C example:
Script (Python):
Note
|
In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat Scripting Guide for more info (fixed in version 0.4.1). |
3.8.5. weechat_config_search_option
Search an option in a section of a configuration file.
Prototype:
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:
Script (Python):
3.8.6. weechat_config_search_section_option
Search a section and an option in a configuration file or section.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.8.7. weechat_config_search_with_string
Get file/section/option info about an option with full name.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.8.8. weechat_config_string_to_boolean
Check if a text is "true" or "false", as boolean value.
Prototype:
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:
Script (Python):
3.8.9. weechat_config_option_reset
Reset an option to its default value.
Prototype:
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:
Script (Python):
3.8.10. weechat_config_option_set
Set new value for an option.
Prototype:
Arguments:
-
option: option pointer
-
value: new value for option
-
run_callback: 1 for calling change callback if value of option is changed, otherwise 0
Return value:
-
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
-
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
-
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occurred
C example:
Script (Python):
3.8.11. weechat_config_option_set_null
Set null (undefined value) for an option.
Prototype:
Arguments:
-
option: option pointer
-
run_callback: 1 for calling change callback if value of option is changed (if it was not null), otherwise 0
Note
|
You can set value to null only if it is allowed for option (see weechat_config_new_option). |
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:
Script (Python):
3.8.12. weechat_config_option_unset
Unset/reset option.
Prototype:
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:
Script (Python):
3.8.13. weechat_config_option_rename
Rename an option.
Prototype:
Arguments:
-
option: option pointer
-
new_name: new name for option
C example:
Script (Python):
3.8.14. weechat_config_option_get_pointer
Return a pointer on an option property.
Prototype:
Arguments:
-
option: option pointer
-
property: property name:
-
config_file: configuration file pointer (struct t_config_file *)
-
section: section pointer (struct t_config_section *)
-
name: option name (char *)
-
type: option type (int *)
-
description: option description (char *)
-
string_values: string values (char *)
-
min: minimum value (int *)
-
max: maximum value (int *)
-
default_value: default value (depends on type)
-
value: current value (depends on type)
-
prev_option: previous option pointer (struct t_config_option *)
-
next_option: next option pointer (struct t_config_option *)
-
Return value:
-
pointer to property asked
C example:
Note
|
This function is not available in scripting API. |
3.8.15. weechat_config_option_is_null
Check if an option is "null" (undefined value).
Prototype:
Arguments:
-
option: option pointer
Return value:
-
1 if value of option is "null"
-
0 if value of option is not "null"
C example:
Script (Python):
3.8.16. weechat_config_option_default_is_null
Check if default value for an option is "null" (undefined value).
Prototype:
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:
Script (Python):
3.8.17. weechat_config_boolean
Return boolean value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
boolean value of option (0 or 1)
C example:
Script (Python):
3.8.18. weechat_config_boolean_default
Return default boolean value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
default boolean value of option (0 or 1)
C example:
Script (Python):
3.8.19. weechat_config_integer
Return integer value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
integer value of option
C example:
Script (Python):
3.8.20. weechat_config_integer_default
Return default integer value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
default integer value of option
C example:
Script (Python):
3.8.21. weechat_config_string
Return string value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
string value of option
C example:
Script (Python):
3.8.22. weechat_config_string_default
Return default string value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
default string value of option
C example:
Script (Python):
3.8.23. weechat_config_color
Return color value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
color value of option (string with name of color)
C example:
Script (Python):
3.8.24. weechat_config_color_default
Return default color value of option.
Prototype:
Arguments:
-
option: option pointer
Return value:
-
default color value of option (string with name of color)
C example:
Script (Python):
3.8.25. weechat_config_write_option
Write a line in a configuration file with option and its value (this function should be called only in "write" or "write_default" callbacks for a section).
Prototype:
Arguments:
-
config_file: configuration file pointer
-
option: option pointer
C example:
Script (Python):
3.8.26. weechat_config_write_line
Write a line in a configuration file (this function should be called only in "write" or "write_default" callbacks for a section).
Prototype:
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:
Script (Python):
3.8.27. weechat_config_write
Write configuration file to disk.
Prototype:
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:
Script (Python):
3.8.28. weechat_config_read
Read configuration file from disk.
Prototype:
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:
Script (Python):
3.8.29. weechat_config_reload
Reload configuration file from disk.
Prototype:
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:
Script (Python):
3.8.30. weechat_config_option_free
Free an option.
Prototype:
Arguments:
-
option: option pointer
C example:
Script (Python):
3.8.31. weechat_config_section_free_options
Free all options in a section.
Prototype:
Arguments:
-
section: section pointer
C example:
Script (Python):
3.8.32. weechat_config_section_free
Free a section.
Prototype:
Arguments:
-
section: section pointer
C example:
Script (Python):
3.8.33. weechat_config_free
Free a configuration file.
Prototype:
Arguments:
-
config_file: configuration file pointer
C example:
Script (Python):
3.8.34. weechat_config_get
Search an option with full name.
Prototype:
Arguments:
-
option_name: full option name (format: "file.section.option")
Return value:
-
pointer to option found, NULL if option was not found
C example:
Script (Python):
3.8.35. weechat_config_get_plugin
Search an option in plugins configuration file (plugins.conf).
Prototype:
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:
Script (Python):
3.8.36. weechat_config_is_set_plugin
Check if option is set in plugins configuration file (plugins.conf).
Prototype:
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:
Script (Python):
3.8.37. weechat_config_set_plugin
Set new value for option in plugins configuration file (plugins.conf).
Prototype:
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:
Script (Python):
3.8.38. weechat_config_set_desc_plugin
WeeChat ≥ 0.3.5.
Set description for option in plugins configuration file (plugins.conf).
Prototype:
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:
Script (Python):
3.8.39. weechat_config_unset_plugin
Unset option in plugins configuration file (plugins.conf).
Prototype:
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:
Script (Python):
3.9. Key bindings
Functions for key bindings.
3.9.1. weechat_key_bind
WeeChat ≥ 0.3.6.
Add new key bindings.
Note
|
Unlike command /key bind , this function will never change an existing key
binding, only new keys are created. To remove a key binding, use
weechat_key_unbind. |
Prototype:
Arguments:
-
context: context for keys:
-
default: default context (common actions)
-
search: search context (when searching text in buffer)
-
cursor: free movement of cursor on screen
-
mouse: keys for mouse events
-
-
keys: hashtable with key bindings
Return value:
-
number of key bindings added
C example:
Script (Python):
3.9.2. weechat_key_unbind
WeeChat ≥ 0.3.6.
Remove key binding(s).
Warning
|
When calling this function, ensure that you will not remove a user key binding. |
Prototype:
Arguments:
-
context: context for keys (see weechat_key_bind)
-
key: key to remove or a special value "area:XXX" to remove all keys having XXX as first or second area
Return value:
-
number of key bindings removed
C examples:
Script (Python):
3.10. Display
Functions to display text in buffers.
3.10.1. weechat_prefix
Return a prefix.
Prototype:
Arguments:
-
prefix: name of prefix (see table below)
Return value:
-
prefix value (string with prefix and color codes), empty string if prefix is not found
List of prefixes:
Prefix | Value | Color | Description |
---|---|---|---|
error |
|
yellow |
Error message |
network |
|
magenta |
Message from network |
action |
|
white |
Self action |
join |
|
lightgreen |
Someone joins current chat |
quit |
|
lightred |
Someone leaves current chat |
Note
|
Values and colors can be customized with command /set . |
C example:
Script (Python):
3.10.2. weechat_color
Return a string color code for display.
Prototype:
Arguments:
-
color_name: name of color, one of:
-
WeeChat option name (from weechat.color.xxx), for example chat_delimiters
-
color with optional attributes/background (see below)
-
attribute:
-
bold: set bold
-
-bold: remove bold
-
reverse: set reverse
-
-reverse: remove reverse
-
italic: set italic
-
-italic: remove italic
-
underline: set underline
-
-underline: remove underline
-
emphasis: toggle the emphasis for text (note: this should be used only in bars, because WeeChat uses text emphasis when searching text in buffer) (WeeChat ≥ 0.4.2)
-
-
bar color name:
-
bar_fg: foreground color for bar
-
bar_delim: delimiters color for bar
-
bar_bg: background color for bar
-
-
reset:
-
reset: reset color and attributes
-
resetcolor: reset color (keep attributes) (WeeChat ≥ 0.3.6)
-
-
Format of color is: attributes (optional) + color name + ",background" (optional). Possible attributes are:
-
*
: bold text -
!
: reverse video -
/
: italic -
_
: underlined text -
|
: keep attributes: do not reset bold/reverse/italic/underlined when changing color (WeeChat ≥ 0.3.6)
Examples:
-
yellow
: yellow -
_green
: underlined green -
*214
: bold orange -
yellow,red
: yellow on red -
|cyan
: cyan (and keep any attribute which was set previously)
Return value:
-
string with color code, or an empty string if color is not found
C example:
Script (Python):
3.10.3. weechat_printf
Display a message on a buffer.
Prototype:
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:
Script (Python):
Note
|
Function is called "print" in scripts ("prnt" in Python). |
3.10.4. weechat_printf_date
Display a message on a buffer, using a custom date.
Prototype:
Arguments:
-
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
-
date: date for message (0 means current date/time)
-
message: message to display
C example:
Note
|
This function is not available in scripting API. |
3.10.5. weechat_printf_tags
Display a message on a buffer, using a custom tags.
Prototype:
Arguments:
-
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
-
tags: comma separated list of tags
-
message: message to display
C example:
Note
|
This function is not available in scripting API. |
3.10.6. weechat_printf_date_tags
Display a message on a buffer, using a custom date and tags.
Prototype:
Arguments:
-
buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
-
date: date for message (0 means current date/time)
-
tags: comma separated list of tags
-
message: message to display
Tags commonly used (non-exhaustive list):
Tag | Description |
---|---|
|
Line can not be filtered |
|
No highlight is possible on line |
|
Line is not written in log file |
|
Level of log for line (see |
|
Buffer with line is not added to hotlist |
|
Buffer with line is added to hotlist with level "message" |
|
Buffer with line is added to hotlist with level "private" |
|
Buffer with line is added to hotlist with level "highlight" |
|
Message is from nick "xxx" |
|
Prefix is a nick with color "ccc" |
|
Username and host in message |
|
IRC message "xxx" (can be a command or a 3-digits number) |
|
IRC numeric message |
|
Error from IRC server |
|
Action from a nick (command |
|
CTCP message |
|
Reply to CTCP message |
|
IRC message that can be filtered with the "smart filter" |
|
Message with away info |
C example:
Script (Python):
Note
|
Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python). |
3.10.7. weechat_printf_y
Display a message on a line of a buffer with free content.
Prototype:
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:
Script (Python):
Note
|
Function is called "print_y" in scripts ("prnt_y" in Python). |
3.10.8. weechat_log_printf
Write a message in WeeChat log file (weechat.log).
Prototype:
Arguments:
-
message: message to write
C example:
Script (Python):
Note
|
Function is called "log_print" in scripts. |
3.11. Hooks
Hook priority
WeeChat ≥ 0.3.4.
In some hooks, you can set a priority. A hook with higher priority is at the beginning of hooks list, so it will be found and executed before other hooks. It’s useful for modifiers, because execution order is important.
To set a priority, you must use this syntax, for argument where priority is allowed: "nnn|name" where "nnn" is non-negative integer with priority and "name" the name for argument (priority does not appear in name, it is automatically removed from string).
Default priority is 1000.
C example:
Following hook types allow priority: command, command_run, signal, hsignal, config, completion, modifier, info, info_hashtable, infolist, hdata, focus.
3.11.1. weechat_hook_command
Hook a command.
Prototype:
Arguments:
-
command: command name (priority allowed, see note about priority)
-
description: description for command (displayed with
/help command
) -
args: arguments for command (displayed with
/help command
) -
args_description: description of arguments (displayed with
/help command
) -
completion: completion template for command: list of completions for each argument, separated by space. Many completions are possible for one argument, separated by "|". Many templates are possible for same command, separated by "||".
-
callback: function called when command is used, arguments and return value:
-
void *data: pointer
-
struct t_gui_buffer *buffer: buffer where command is executed
-
int argc: number of arguments given for command
-
char **argv: arguments given for command
-
char **argv_eol: arguments given for command (until end of line for each argument)
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Default completion codes are:
Plugin | Name | Description |
---|---|---|
alias |
alias |
list of aliases |
alias |
alias_value |
value of alias |
aspell |
aspell_dicts |
list of aspell installed dictionaries |
aspell |
aspell_langs |
list of all languages supported by aspell |
exec |
exec_commands_ids |
ids (numbers and names) of executed commands |
guile |
guile_script |
list of scripts |
irc |
irc_channel |
current IRC channel |
irc |
irc_channel_nicks_hosts |
nicks and hostnames of current IRC channel |
irc |
irc_channel_topic |
topic of current IRC channel |
irc |
irc_channels |
channels on all IRC servers |
irc |
irc_ignores_numbers |
numbers for defined ignores |
irc |
irc_msg_kick |
default kick message |
irc |
irc_msg_part |
default part message for IRC channel |
irc |
irc_notify_nicks |
nicks in notify list |
irc |
irc_privates |
privates on all IRC servers |
irc |
irc_server |
current IRC server |
irc |
irc_server_channels |
channels on current IRC server |
irc |
irc_server_nick |
nick on current IRC server |
irc |
irc_server_nicks |
nicks on all channels of current IRC server |
irc |
irc_server_privates |
privates on current IRC server |
irc |
irc_servers |
IRC servers (internal names) |
irc |
nick |
nicks of current IRC channel |
lua |
lua_script |
list of scripts |
perl |
perl_script |
list of scripts |
python |
python_script |
list of scripts |
relay |
relay_free_port |
first free port for relay plugin |
relay |
relay_protocol_name |
all possible protocol.name for relay plugin |
relay |
relay_relays |
protocol.name of current relays for relay plugin |
ruby |
ruby_script |
list of scripts |
script |
script_files |
files in script directories |
script |
script_scripts |
list of scripts in repository |
script |
script_scripts_installed |
list of scripts installed (from repository) |
script |
script_tags |
tags of scripts in repository |
tcl |
tcl_script |
list of scripts |
trigger |
trigger_hook_arguments |
default arguments for a hook |
trigger |
trigger_hook_command |
default command for a hook |
trigger |
trigger_hook_conditions |
default conditions for a hook |
trigger |
trigger_hook_rc |
default return codes for hook callback |
trigger |
trigger_hook_regex |
default regular expression for a hook |
trigger |
trigger_hooks |
hooks for triggers |
trigger |
trigger_hooks_filter |
hooks for triggers (for filter in monitor buffer) |
trigger |
trigger_names |
triggers |
trigger |
trigger_names_default |
default triggers |
trigger |
trigger_option_value |
value of a trigger option |
trigger |
trigger_options |
options for triggers |
weechat |
bars_names |
names of bars |
weechat |
bars_options |
options for bars |
weechat |
buffer_properties_get |
properties that can be read on a buffer |
weechat |
buffer_properties_set |
properties that can be set on a buffer |
weechat |
buffers_names |
names of buffers |
weechat |
buffers_numbers |
numbers of buffers |
weechat |
buffers_plugins_names |
names of buffers (including plugins names) |
weechat |
commands |
commands (weechat and plugins) |
weechat |
config_files |
configuration files |
weechat |
config_option_values |
values for a configuration option |
weechat |
config_options |
configuration options |
weechat |
cursor_areas |
areas ("chat" or bar name) for free cursor movement |
weechat |
env_value |
value of an environment variable |
weechat |
env_vars |
environment variables |
weechat |
filename |
filename |
weechat |
filters_names |
names of filters |
weechat |
infolists |
names of infolists hooked |
weechat |
infos |
names of infos hooked |
weechat |
keys_codes |
key codes |
weechat |
keys_codes_for_reset |
key codes that can be reset (keys added, redefined or removed) |
weechat |
keys_contexts |
key contexts |
weechat |
layouts_names |
names of layouts |
weechat |
nicks |
nicks in nicklist of current buffer |
weechat |
palette_colors |
palette colors |
weechat |
plugins_commands |
commands defined by plugins |
weechat |
plugins_installed |
names of plugins installed |
weechat |
plugins_names |
names of plugins |
weechat |
proxies_names |
names of proxies |
weechat |
proxies_options |
options for proxies |
weechat |
secured_data |
names of secured data (file sec.conf, section data) |
weechat |
weechat_commands |
weechat commands |
weechat |
windows_numbers |
numbers of windows |
xfer |
nick |
nicks of DCC chat |
Special codes:
-
%%command: reuse completion template from command command
-
%-: stop completion
-
%*: repeat last completion
Return value:
-
pointer to new hook, NULL if error occurred
C example:
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):
3.11.2. weechat_hook_command_run
Hook a command when WeeChat runs it.
Prototype:
Arguments:
-
command: command to hook (wildcard "*" is allowed) (priority allowed, see note about priority)
-
callback: function called when command is run, arguments and return value:
-
void *data: pointer
-
struct t_gui_buffer *buffer: buffer where command is executed
-
const char *command: the command executed, with its arguments
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_OK_EAT
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Note
|
Callback can return WEECHAT_RC_OK or WEECHAT_RC_OK_EAT (command will not be executed by WeeChat after callback). |
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.3. weechat_hook_timer
Hook a timer.
Prototype:
Arguments:
-
interval: interval between two calls (milliseconds, so 1000 = 1 second)
-
align_second: alignment on a second. For example, if current time is 09:00, if interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute when second is 0
-
max_calls: number of calls to timer (if 0, then timer has no end)
-
callback: function called when time is reached, arguments and return value:
-
void *data: pointer
-
int remaining_calls: remaining calls (-1 if timer has no end)
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.4. weechat_hook_fd
Hook a file descriptor (file or socket).
Prototype:
Arguments:
-
fd: file descriptor
-
flag_read: 1 = catch read event, 0 = ignore
-
flag_write: 1 = catch write event, 0 = ignore
-
flag_exception: 1 = catch exception event, 0 = ignore
-
callback: function called a selected event occurs for file (or socket), arguments and return value:
-
void *data: pointer
-
int fd: file descriptor
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.5. weechat_hook_process
Hook a process (launched with fork), and catch output.
Note
|
Since version 0.3.9.2, the shell is not used any more to execute the command.
WeeChat makes an automatic split of the command and its arguments (like the
shell does). If the split is not correct (according to quotes in your command), or if you want to use shell, you can use function weechat_hook_process_hashtable with arguments in the hashtable options (WeeChat ≥ 0.4.0). |
Prototype:
Arguments:
-
command: command to launch in child process or URL (WeeChat ≥ 0.3.7) (see below)
-
timeout: timeout for command (in milliseconds): after this timeout, child process is killed (0 means no timeout)
-
callback: function called when data from child is available, or when child has ended, arguments and return value:
-
void *data: pointer
-
const char *command: command executed by child
-
int return_code: return code:
-
>= 0: child return code for a command, and for URL possible values are:
-
0: transfer OK
-
1: invalid URL
-
2: transfer error
-
3: not enough memory
-
4: error with a file
-
-
< 0: WEECHAT_HOOK_PROCESS_RUNNING (data available, but child still running) or WEECHAT_HOOK_PROCESS_ERROR (error when launching command)
-
-
out: standard output of command (stdout)
-
err: error output of command (stderr)
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
When command has ended, or if timeout is reached, WeeChat will automatically unhook (and kill process if it is still running).
The command can be an URL with format: "url:http://www.example.com", to download content of URL (WeeChat ≥ 0.3.7). Options are possible for URL with function weechat_hook_process_hashtable.
Tip
|
If you want to retrieve infos about WeeChat (like current stable version, latest git commit, …), you can use URLs on page https://weechat.org/dev/info |
Note
|
Buffer size for sending data to callback is 64KB (there are 2 buffers: one for stdout and one for stderr). If output from child process (stdout or stderr) is longer than 64KB, callback will be called more than one time. |
Important
|
Even if most of times your callback is called only once, you must ensure that many calls to callback are OK in your code: you must concatenate data issued by many calls and use data only when return code is non-negative. |
C example:
Script (Python):
3.11.6. weechat_hook_process_hashtable
WeeChat ≥ 0.3.7.
Hook a process (launched with fork) using options in a hashtable, and catch output.
Prototype:
Arguments are the same as function weechat_hook_process, with an extra argument:
-
options: options for command executed; the hashtable is duplicated in function, so it’s safe to free it after this call
For a standard command (not beginning with "url:"), following options are available:
Option | Value | Description |
---|---|---|
argN (N ≥ 1) |
any string |
Arguments for command; if no argument is given with these options, the command is automatically split like the shell does (and then command arguments are read in the command argument) |
stdin |
(not used) |
Create a pipe for writing data on standard input (stdin) of child process (see function weechat_hook_set) |
buffer_flush |
number of bytes |
Minimum number of bytes to flush stdout/stderr (to send output to callback), between 1 and 65536 (default); 1 = send any output immediately to the callback |
detached |
(not used) |
Run the process in a detached mode: stdout and stderr are redirected to /dev/null |
For command "url:…", following options are available (see
man curl_easy_setopt
for a description of each option):
Option | Type | Constants (1) |
---|---|---|
verbose |
long |
|
header |
long |
|
noprogress |
long |
|
nosignal |
long |
|
wildcardmatch |
long |
|
failonerror |
long |
|
proxy |
string |
|
proxyport |
long |
|
port |
long |
|
httpproxytunnel |
long |
|
interface |
string |
|
dns_cache_timeout |
long |
|
proxytype |
long |
http, socks4, socks5, socks4a, socks5_hostname, http_1_0 |
buffersize |
long |
|
tcp_nodelay |
long |
|
localport |
long |
|
localportrange |
long |
|
address_scope |
long |
|
protocols |
mask |
http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, all, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher |
redir_protocols |
mask |
http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, all, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher |
noproxy |
string |
|
socks5_gssapi_service |
string |
|
socks5_gssapi_nec |
long |
|
tcp_keepalive |
long |
|
tcp_keepidle |
long |
|
tcp_keepintvl |
long |
|
netrc |
long |
ignored, optional, required |
userpwd |
string |
|
proxyuserpwd |
string |
|
httpauth |
mask |
none, basic, digest, gssnegotiate, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate |
proxyauth |
mask |
none, basic, digest, gssnegotiate, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate |
netrc_file |
string |
|
username |
string |
|
password |
string |
|
proxyusername |
string |
|
proxypassword |
string |
|
tlsauth_type |
mask |
none, srp |
tlsauth_username |
string |
|
tlsauth_password |
string |
|
sasl_ir |
long |
|
xoauth2_bearer |
string |
|
login_options |
string |
|
autoreferer |
long |
|
followlocation |
long |
|
put |
long |
|
post |
long |
|
postfields |
string |
|
referer |
string |
|
useragent |
string |
|
cookie |
string |
|
cookiefile |
string |
|
postfieldsize |
long |
|
maxredirs |
long |
|
httpget |
long |
|
cookiejar |
string |
|
http_version |
long |
none, 1_0, 1_1 |
cookiesession |
long |
|
unrestricted_auth |
long |
|
postfieldsize_large |
long long |
|
cookielist |
string |
|
ignore_content_length |
long |
|
accept_encoding |
string |
|
transfer_encoding |
long |
|
http_content_decoding |
long |
|
http_transfer_decoding |
long |
|
copypostfields |
string |
|
postredir |
mask |
post_301, post_302 |
expect_100_timeout_ms |
long |
|
headeropt |
mask |
unified, separate |
mail_from |
string |
|
mail_auth |
string |
|
tftp_blksize |
long |
|
ftpport |
string |
|
ftp_use_epsv |
long |
|
ftp_use_eprt |
long |
|
ftp_create_missing_dirs |
long |
|
ftp_response_timeout |
long |
|
ftpsslauth |
long |
default, ssl, tls |
ftp_account |
string |
|
ftp_skip_pasv_ip |
long |
|
ftp_filemethod |
long |
multicwd, nocwd, singlecwd |
ftp_alternative_to_user |
string |
|
ftp_ssl_ccc |
long |
ccc_none, ccc_active, ccc_passive |
dirlistonly |
long |
|
append |
long |
|
ftp_use_pret |
long |
|
rtsp_request |
long |
options, describe, announce, setup, play, pause, teardown, get_parameter, set_parameter, record, receive |
rtsp_session_id |
string |
|
rtsp_stream_uri |
string |
|
rtsp_transport |
string |
|
rtsp_client_cseq |
long |
|
rtsp_server_cseq |
long |
|
crlf |
long |
|
range |
string |
|
resume_from |
long |
|
customrequest |
string |
|
nobody |
long |
|
infilesize |
long |
|
upload |
long |
|
timecondition |
long |
none, ifmodsince, ifunmodsince, lastmod |
timevalue |
long |
|
transfertext |
long |
|
filetime |
long |
|
maxfilesize |
long |
|
proxy_transfer_mode |
long |
|
resume_from_large |
long long |
|
infilesize_large |
long long |
|
maxfilesize_large |
long long |
|
timeout |
long |
|
low_speed_limit |
long |
|
low_speed_time |
long |
|
fresh_connect |
long |
|
forbid_reuse |
long |
|
connecttimeout |
long |
|
ipresolve |
long |
whatever, v4, v6 |
connect_only |
long |
|
max_send_speed_large |
long long |
|
max_recv_speed_large |
long long |
|
timeout_ms |
long |
|
connecttimeout_ms |
long |
|
maxconnects |
long |
|
use_ssl |
long |
none, try, control, all |
dns_servers |
string |
|
accepttimeout_ms |
long |
|
dns_interface |
string |
|
dns_local_ip4 |
string |
|
dns_local_ip6 |
string |
|
sslcert |
string |
|
sslversion |
long |
default, tlsv1, sslv2, sslv3 |
ssl_verifypeer |
long |
|
cainfo |
string |
|
random_file |
string |
|
egdsocket |
string |
|
ssl_verifyhost |
long |
|
ssl_cipher_list |
string |
|
sslcerttype |
string |
|
sslkey |
string |
|
sslkeytype |
string |
|
sslengine |
string |
|
sslengine_default |
long |
|
capath |
string |
|
ssl_sessionid_cache |
long |
|
krblevel |
string |
|
keypasswd |
string |
|
issuercert |
string |
|
crlfile |
string |
|
certinfo |
long |
|
gssapi_delegation |
long |
none, policy_flag, flag |
ssl_options |
long |
allow_beast |
ssl_enable_alpn |
long |
|
ssl_enable_npn |
long |
|
ssh_auth_types |
mask |
none, policy_flag, flag |
ssh_public_keyfile |
string |
|
ssh_private_keyfile |
string |
|
ssh_host_public_key_md5 |
string |
|
ssh_knownhosts |
string |
|
new_file_perms |
long |
|
new_directory_perms |
long |
Note
|
(1) When constants are available they must be used as value for option. For options with type "mask", format is: "value1+value2+value3". |
For URL, two extra options (strings) are allowed for input/output file:
-
file_in: file to read and send with URLs (post file)
-
file_out: write downloaded URL/file in this file (instead of standard output)
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.7. weechat_hook_connect
Hook a connection (background connection to a remote host).
Prototype:
Arguments:
-
proxy: name of proxy to use for connection (optional, NULL means connection without proxy)
-
address: name or IP address to connect to
-
port: port number
-
ipv6: 1 to use IPv6 (with fallback to IPv4), 0 to use only IPv4
-
retry: retry count, used to fallback to IPv4 hosts if IPv6 hosts connect but then fail to accept the client
-
gnutls_sess: GnuTLS session (optional)
-
gnutls_cb: GnuTLS callback (optional)
-
gnutls_dhkey_size: size of the key used during the Diffie-Hellman Key Exchange (GnuTLS)
-
gnutls_priorities: priorities for gnutls (for syntax, see documentation of function gnutls_priority_init in gnutls manual), basic values are:
-
PERFORMANCE
-
NORMAL (default)
-
SECURE128
-
SECURE256
-
EXPORT
-
NONE
-
-
local_hostname: local hostname to use for connection (optional)
-
callback: function called when connection is OK or failed, arguments and return value:
-
void *data: pointer
-
int status: connection status:
-
WEECHAT_HOOK_CONNECT_OK: connection OK
-
WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: address not found
-
WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: IP address not found
-
WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: connection refused
-
WEECHAT_HOOK_CONNECT_PROXY_ERROR: error with proxy
-
WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: error with local hostname
-
WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: GnuTLS init error
-
WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: GnuTLS handshake error
-
WEECHAT_HOOK_CONNECT_MEMORY_ERROR: insufficient memory
-
WEECHAT_HOOK_CONNECT_TIMEOUT: timeout
-
WEECHAT_HOOK_CONNECT_SOCKET_ERROR: unable to create socket
-
-
gnutls_rc: return value of gnutls_handshake()
-
sock: socket used to connect
-
const char *error: return value of gnutls_strerror(gnutls_rc)
-
const char *ip_address: IP address found
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.8. weechat_hook_print
Updated in 0.4.3 and 1.0.
Hook a message printed.
Prototype:
Arguments:
-
buffer: buffer pointer, if NULL, messages from any buffer are caught
-
tags: catch only messages with these tags (optional):
-
with WeeChat ≥ 0.4.3: comma-separated list of tags that must be in message (logical "or"); it is possible to combine many tags as a logical "and" with separator "+"; wildcard "*" is allowed in tags
-
with WeeChat ≤ 0.4.2: comma-separated list of tags that must all be in message (logical "and")
-
-
message: only messages with this string will be caught (optional, case insensitive)
-
strip_colors: if 1, colors will be stripped from message displayed, before calling callback
-
callback: function called when a message is printed, arguments and return value:
-
void *data: pointer
-
struct t_gui_buffer *buffer: buffer pointer
-
time_t date: date
-
int tags_count: number of tags for line
-
const char **tags: array with tags for line
-
int displayed: 1 if line is displayed, 0 if it is filtered (hidden)
-
int highlight: 1 if line has highlight, otherwise 0
-
const char *prefix: prefix
-
const char *message: message
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
Important
|
In scripts, with WeeChat ≥ 1.0, the callback arguments displayed and
highlight are integers (with WeeChat ≤ 0.4.3, they were strings). To be compatible with all versions, it is recommended to convert the argument to integer before testing it, for example in Python: " if int(highlight): ". |
C example:
Script (Python):
3.11.9. weechat_hook_signal
Hook a signal.
Prototype:
Arguments:
-
signal: signal to catch, wildcard "*" is allowed (priority allowed, see note about priority) (see table below)
-
callback: function called when signal is received, arguments and return value:
-
void *data: pointer
-
const char *signal: signal received
-
const char *type_data: type of data sent with signal:
-
WEECHAT_HOOK_SIGNAL_STRING: string
-
WEECHAT_HOOK_SIGNAL_INT: integer number
-
WEECHAT_HOOK_SIGNAL_POINTER: pointer
-
-
void *signal_data: data sent with signal
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_OK_EAT (stop sending the signal immediately) (WeeChat ≥ 0.4.0)
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
List of signals sent by WeeChat and plugins:
Plugin | Signal | Arguments | Description |
---|---|---|---|
aspell |
aspell_suggest |
Pointer: buffer |
New suggestions for a misspelled word |
guile |
guile_script_loaded |
String: path to script |
Scheme script loaded |
guile |
guile_script_unloaded |
String: path to script |
Scheme script unloaded |
guile |
guile_script_installed |
String: comma-separated list of paths to scripts installed |
Scheme script(s) installed |
guile |
guile_script_removed |
String: comma-separated list of scripts removed |
Scheme script(s) removed |
irc |
xxx,irc_in_yyy (1) |
String: message |
IRC message from server (before irc plugin uses it, signal sent only if message is not ignored) |
irc |
xxx,irc_in2_yyy (1) |
String: message |
IRC message from server (after irc plugin uses it, signal sent only if message is not ignored) |
irc |
xxx,irc_raw_in_yyy (1) |
String: message |
IRC message from server (before irc plugin uses it, signal sent even if message is ignored) |
irc |
xxx,irc_raw_in2_yyy (1) |
String: message |
IRC message from server (after irc plugin uses it, signal sent even if message is ignored) |
irc |
xxx,irc_out1_yyy (1) |
String: message |
IRC message sent to server (before automatic split to fit in 512 bytes) |
irc |
xxx,irc_out_yyy (1) |
String: message |
IRC message sent to server (after automatic split to fit in 512 bytes) |
irc |
xxx,irc_outtags_yyy (1) |
String: tags + ";" + message |
Tags + IRC message sent to server |
irc |
irc_ctcp |
String: message |
CTCP received |
irc |
irc_dcc |
String: message |
New DCC |
irc |
irc_pv |
String: message |
Private message received |
irc |
irc_channel_opened |
Pointer: buffer |
Channel opened |
irc |
irc_pv_opened |
Pointer: buffer |
Private opened |
irc |
irc_server_opened |
Pointer: buffer |
Server buffer opened |
irc |
irc_server_connecting |
String: server name |
Connecting to server |
irc |
irc_server_connected |
String: server name |
Connected to server |
irc |
irc_server_disconnected |
String: server name |
Disconnected from server |
irc |
irc_ignore_removing |
Pointer: ignore |
Removing ignore |
irc |
irc_ignore_removed |
- |
Ignore removed |
irc |
irc_notify_join |
String: server name + "," + nick |
A nick in notify list has joined server |
irc |
irc_notify_quit |
String: server name + "," + nick |
A nick in notify list has quit server |
irc |
irc_notify_away |
String: server name + "," + nick + "," + away message |
A nick in notify list is now away on server |
irc |
irc_notify_still_away |
String: server name + "," + nick + "," + away message |
A nick in notify list is still away on server (away message has changed) |
irc |
irc_notify_back |
String: server name + "," + nick |
A nick in notify list is back (away status removed) |
logger |
logger_start |
Pointer: buffer |
Start logging for buffer |
logger |
logger_stop |
Pointer: buffer |
Stop logging for buffer |
logger |
logger_backlog |
Pointer: buffer |
Display backlog for buffer |
lua |
lua_script_loaded |
String: path to script |
Lua script loaded |
lua |
lua_script_unloaded |
String: path to script |
Lua script unloaded |
lua |
lua_script_installed |
String: comma-separated list of paths to scripts installed |
Lua script(s) installed |
lua |
lua_script_removed |
String: comma-separated list of scripts removed |
Lua script(s) removed |
perl |
perl_script_loaded |
String: path to script |
Perl script loaded |
perl |
perl_script_unloaded |
String: path to script |
Perl script unloaded |
perl |
perl_script_installed |
String: comma-separated list of paths to scripts installed |
Perl script(s) installed |
perl |
perl_script_removed |
String: comma-separated list of scripts removed |
Perl script(s) removed |
python |
python_script_loaded |
String: path to script |
Python script loaded |
python |
python_script_unloaded |
String: path to script |
Python script unloaded |
python |
python_script_installed |
String: comma-separated list of paths to scripts installed |
Python script(s) installed |
python |
python_script_removed |
String: comma-separated list of scripts removed |
Python script(s) removed |
relay |
relay_client_connecting |
Pointer: relay client |
A relay client is connecting |
relay |
relay_client_waiting_auth |
Pointer: relay client |
Waiting for authentication from a relay client |
relay |
relay_client_auth_ok |
Pointer: relay client |
Successful authentication from a relay client |
relay |
relay_client_connected |
Pointer: relay client |
A relay client is connected |
relay |
relay_client_auth_failed |
Pointer: relay client |
Authentication of a relay client has failed |
relay |
relay_client_disconnected |
Pointer: relay client |
A relay client is disconnected |
ruby |
ruby_script_loaded |
String: path to script |
Ruby script loaded |
ruby |
ruby_script_unloaded |
String: path to script |
Ruby script unloaded |
ruby |
ruby_script_installed |
String: comma-separated list of paths to scripts installed |
Ruby script(s) installed |
ruby |
ruby_script_removed |
String: comma-separated list of scripts removed |
Ruby script(s) removed |
tcl |
tcl_script_loaded |
String: path to script |
Tcl script loaded |
tcl |
tcl_script_unloaded |
String: path to script |
Tcl script unloaded |
tcl |
tcl_script_installed |
String: comma-separated list of paths to scripts installed |
Tcl script(s) installed |
tcl |
tcl_script_removed |
String: comma-separated list of scripts removed |
Tcl script(s) removed |
weechat |
buffer_opened |
Pointer: buffer |
Buffer opened |
weechat |
buffer_closing |
Pointer: buffer |
Closing buffer |
weechat |
buffer_closed |
Pointer: buffer |
Buffer closed |
weechat |
buffer_cleared |
Pointer: buffer |
Buffer cleared |
weechat |
buffer_hidden |
Pointer: buffer |
Buffer hidden |
weechat |
buffer_unhidden |
Pointer: buffer |
Buffer unhidden |
weechat |
buffer_line_added |
Pointer: line |
Line added in a buffer |
weechat |
buffer_lines_hidden |
Pointer: buffer |
Lines hidden in buffer |
weechat |
buffer_localvar_added |
Pointer: buffer |
Local variable has been added |
weechat |
buffer_localvar_changed |
Pointer: buffer |
Local variable has changed |
weechat |
buffer_localvar_removed |
Pointer: buffer |
Local variable has been removed |
weechat |
buffer_merged |
Pointer: buffer |
Buffer merged |
weechat |
buffer_unmerged |
Pointer: buffer |
Buffer unmerged |
weechat |
buffer_moved |
Pointer: buffer |
Buffer moved |
weechat |
buffer_renamed |
Pointer: buffer |
Buffer renamed |
weechat |
buffer_switch |
Pointer: buffer |
Switching buffer |
weechat |
buffer_title_changed |
Pointer: buffer |
Title of buffer changed |
weechat |
buffer_type_changed |
Pointer: buffer |
Type of buffer changed |
weechat |
buffer_zoomed |
Pointer: buffer |
Merged buffer zoomed |
weechat |
buffer_unzoomed |
Pointer: buffer |
Merged buffer unzoomed |
weechat |
day_changed |
String: new date, format: "2010-01-31" |
Day of system date has changed |
weechat |
debug_dump |
String: plugin name |
Dump request |
weechat |
debug_libs |
- |
Display external libraries used |
weechat |
filter_added |
Pointer: filter |
Filter added |
weechat |
filter_removing |
Pointer: filter |
Removing filter |
weechat |
filter_removed |
- |
Filter removed |
weechat |
filters_enabled |
- |
Filters enabled |
weechat |
filters_disabled |
- |
Filters disabled |
weechat |
hotlist_changed |
- |
Hotlist changed |
weechat |
input_paste_pending |
- |
Paste pending |
weechat |
input_search |
Pointer: buffer |
Text search in buffer |
weechat |
input_text_changed |
Pointer: buffer |
Input text changed |
weechat |
input_text_cursor_moved |
Pointer: buffer |
Input text cursor moved |
weechat |
key_bind |
String: key |
Key added |
weechat |
key_unbind |
String: key |
Key removed |
weechat |
key_pressed |
String: key pressed |
Key pressed |
weechat |
key_combo_default |
String: key combo |
Key combo in default context |
weechat |
key_combo_search |
String: key combo |
Key combo in search context |
weechat |
key_combo_cursor |
String: key combo |
Key combo in cursor context |
weechat |
mouse_enabled |
- |
Mouse enabled |
weechat |
mouse_disabled |
- |
Mouse disabled |
weechat |
nicklist_group_added |
String: buffer pointer + "," + group name |
Group added in nicklist |
weechat |
nicklist_group_changed |
String: buffer pointer + "," + group name |
Group changed in nicklist |
weechat |
nicklist_group_removing |
String: buffer pointer + "," + group name |
Removing group from nicklist |
weechat |
nicklist_group_removed |
String: buffer pointer + "," + group name |
Group removed from nicklist |
weechat |
nicklist_nick_added |
String: buffer pointer + "," + nick name |
Nick added in nicklist |
weechat |
nicklist_nick_changed |
String: buffer pointer + "," + nick name |
Nick changed in nicklist |
weechat |
nicklist_nick_removing |
String: buffer pointer + "," + nick name |
Removing nick from nicklist |
weechat |
nicklist_nick_removed |
String: buffer pointer + "," + nick name |
Nick removed from nicklist |
weechat |
partial_completion |
- |
Partial completion happened |
weechat |
plugin_loaded |
String: path to plugin loaded |
Plugin loaded |
weechat |
plugin_unloaded |
String: name of plugin unloaded (example: "irc") |
Plugin unloaded |
weechat |
quit |
String: arguments for /quit |
Command |
weechat |
signal_sigwinch |
- |
Signal SIGWINCH received (terminal was resized) |
weechat |
upgrade |
String: "quit" if "-quit" argument was given for /upgrade, otherwise NULL |
Command |
weechat |
upgrade_ended |
- |
End of upgrade process (command |
weechat |
weechat_highlight |
String: message with prefix |
Highlight happened |
weechat |
weechat_pv |
String: message with prefix |
Private message displayed |
weechat |
window_closing |
Pointer: window |
Closing window |
weechat |
window_closed |
Pointer: window |
Window closed |
weechat |
window_opened |
Pointer: window |
Window opened |
weechat |
window_scrolled |
Pointer: window |
Scroll in window |
weechat |
window_switch |
Pointer: window |
Switching window |
weechat |
window_zoom |
Pointer: current window |
Zomming window |
weechat |
window_zoomed |
Pointer: current window |
Window zoomed |
weechat |
window_unzoom |
Pointer: current window |
Unzooming window |
weechat |
window_unzoomed |
Pointer: current window |
Window unzoomed |
xfer |
xfer_add |
Pointer: infolist with xfer info |
New xfer |
xfer |
xfer_send_ready |
Pointer: infolist with xfer info |
Xfer ready |
xfer |
xfer_accept_resume |
Pointer: infolist with xfer info |
Accept xfer resume |
xfer |
xfer_send_accept_resume |
Pointer: infolist with xfer info |
Xfer resumed |
xfer |
xfer_start_resume |
Pointer: infolist with xfer info |
Start resume |
xfer |
xfer_resume_ready |
Pointer: infolist with xfer info |
Xfer resume ready |
xfer |
xfer_ended |
Pointer: infolist with xfer info |
Xfer has ended |
Note
|
(1) xxx is IRC server name, yyy is IRC command name. |
C example:
Script (Python):
3.11.10. weechat_hook_signal_send
Updated in 1.0.
Send a signal.
Prototype:
Arguments:
-
signal: signal to send
-
type_data: type of data sent with signal (see weechat_hook_signal)
-
signal_data: data sent with signal
Return value (WeeChat ≥ 1.0):
-
return code of last callback executed (WEECHAT_RC_OK if no callback was executed):
-
WEECHAT_RC_OK
-
WEECHAT_RC_OK_EAT
-
WEECHAT_RC_ERROR
-
C example:
Script (Python):
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:
Script (Python):
Signals xxx_script_install
Five signals can be sent to install a script, according to language:
-
perl_script_install
-
python_script_install
-
ruby_script_install
-
lua_script_install
-
tcl_script_install
The callback will do following actions when receiving signal:
-
unload and remove installed script
-
move new script to directory ~/.weechat/xxx/ (where xxx is language)
-
create link to new script in directory ~/.weechat/xxx/autoload/
-
load new script
These signals are used by script plugin to install scripts.
Argument is a string with path to script to install.
C example:
Script (Python):
Signals xxx_script_remove
Five signals can be sent to remove list of scripts, according to language:
-
perl_script_remove
-
python_script_remove
-
ruby_script_remove
-
lua_script_remove
-
tcl_script_remove
For each script in list, the callback will unload then remove script.
These signals are used by script plugin to remove scripts.
Argument is a string with comma-separated list of script to remove (script is name without path, for example script.py).
C example:
Script (Python):
Signal irc_input_send
WeeChat ≥ 0.3.4.
The signal "irc_input_send" can be sent to simulate input in an irc buffer (server, channel or private).
Argument is a string with following format:
-
internal server name (required)
-
semicolon
-
channel name (optional)
-
semicolon
-
flags used when sending message (optional, default is 1):
-
1: queue with high priority (like user messages)
-
2: queue with low priority (like messages automatically sent by WeeChat)
-
-
semicolon
-
comma-separated list of tags used when sending message (optional)
-
semicolon
-
text or command (required)
C examples:
Script (Python):
3.11.11. weechat_hook_hsignal
WeeChat ≥ 0.3.4.
Hook a hsignal (signal with hashtable).
Prototype:
Arguments:
-
signal: signal to catch, wildcard "*" is allowed (priority allowed, see note about priority) (see table below)
-
callback: function called when signal is received, arguments and return value:
-
void *data: pointer
-
const char *signal: signal received
-
struct t_hashtable *hashtable: hashtable
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_OK_EAT (stop sending the signal immediately) (WeeChat ≥ 0.4.0)
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
List of hsignals:
Plugin | Signal | Arguments | Description |
---|---|---|---|
irc |
irc_redirection_xxx_yyy (1) |
Redirection output |
|
weechat |
nicklist_group_added |
buffer (struct t_gui_buffer *): buffer |
Group added in nicklist |
weechat |
nicklist_nick_added |
buffer (struct t_gui_buffer *): buffer |
Nick added in nicklist |
weechat |
nicklist_group_removing |
buffer (struct t_gui_buffer *): buffer |
Removing group from nicklist |
weechat |
nicklist_nick_removing |
buffer (struct t_gui_buffer *): buffer |
Removing nick from nicklist |
weechat |
nicklist_group_changed |
buffer (struct t_gui_buffer *): buffer |
Group changed in nicklist |
weechat |
nicklist_nick_changed |
buffer (struct t_gui_buffer *): buffer |
Nick changed in nicklist |
Note
|
(1) xxx is signal argument used in redirection, yyy is redirection pattern. |
C example:
Script (Python):
3.11.12. weechat_hook_hsignal_send
WeeChat ≥ 0.3.4, updated in 1.0.
Send a hsignal (signal with hashtable).
Prototype:
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:
Script (Python):
Hsignal irc_redirect_command
WeeChat ≥ 0.3.4.
The hsignal "irc_redirect_command" can be sent to redirect output of irc command to a callback.
Argument is a hashtable with following entries (keys and values are string):
-
server: internal server name (required)
-
pattern: redirect pattern to use (required), either a default one (defined by irc plugin), or a user pattern (see [hsignal_irc_redirect_pattern]), default patterns are:
-
ison
-
list
-
mode_channel
-
mode_channel_ban ("mode #channel b")
-
mode_channel_ban_exception ("mode #channel e")
-
mode_channel_invite ("mode #channel I")
-
mode_user
-
monitor
-
names
-
ping
-
time
-
topic
-
userhost
-
who
-
whois
-
whowas
-
-
signal: signal name (required)
-
count: number of times redirection will work (optional, 1 by default)
-
string: string that must be in irc messages received (optional, but recommended, if a string can be used to identify messages)
-
timeout: timeout for redirect, in seconds (optional, 60 by default)
-
cmd_filter: comma-separated list of irc commands to filter (only these commands will be sent to callbacks, other will be ignored) (optional)
Immediately after sending this hsignal, you must send command to irc server, and redirection will be used for this command.
When complete answer to your command has been be received, a hsignal will be send. This hsignal has name irc_redirection_xxx_yyy where xxx is the signal and yyy the pattern used.
Hashtable sent in hsignal has following content (key and values are strings):
-
output: output of command (messages are separated by "\n")
-
output_size: number of bytes in output (as string)
-
error: error string (if an error occurred):
-
timeout: redirection stopped after timeout
-
-
server: internal server name
-
pattern: redirect pattern
-
signal: signal name
-
command: redirected command
C example:
Script (Python):
Hsignal irc_redirect_pattern
WeeChat ≥ 0.3.4.
The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc redirect (see [hsignal_irc_redirect_command]).
Argument is a hashtable with following entries (keys and values are string):
-
pattern: name of pattern (required)
-
timeout: default timeout for pattern, in seconds (optional, 60 by default)
-
cmd_start: comma-separated list of commands starting redirect (optional)
-
cmd_stop: comma-separated list of commands stopping redirect (required)
-
cmd_extra: comma-separated list of commands that may be received after stop commands (optional)
For each command in cmd_start, cmd_stop and cmd_extra, it is possible to give integer with position of "string" that must be found in received message, for example:
352:1,354,401:1
For commands 352 and 401, "string" must be found in received message, as first argument.
Important
|
The pattern is destroyed when it is used by a redirection. If you need pattern for many redirections, you must create pattern before each redirect. |
C example:
Script (Python):
3.11.13. weechat_hook_config
Hook a configuration option.
Prototype:
Arguments:
-
option: option, format is full name, as used with command
/set
(for example:weechat.look.item_time_format
), wildcard "*" is allowed (priority allowed, see note about priority) -
callback: function called when configuration option is changed, arguments and return value:
-
void *data: pointer
-
const char *option: name of option
-
const char *value: new value for option
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.14. weechat_hook_completion
Hook a completion.
Prototype:
Arguments:
-
completion_item: name of completion item, after you can use %(name) in a command hooked (argument completion) (priority allowed, see note about priority)
-
description: description of completion
-
callback: function called when completion item is used (user is completing something using this item), arguments and return value:
-
void *data: pointer
-
const char *completion_item: name of completion item
-
struct t_gui_buffer *buffer: buffer where completion is made
-
struct t_gui_completion *completion: structure used to add words for completion (see weechat_hook_completion_list_add)
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Note
|
Completion names are global (shared across WeeChat and plugins). So it is recommended to choose a name with a unique prefix, like "plugin_xxx" (where "xxx" is your item name). |
Important
|
The callback must only call function
weechat_hook_completion_list_add
and must NOT update the command line. To update the command line when Tab is pressed, you can use the function weechat_hook_command_run with command: "/input complete_next" (and you must return WEECHAT_RC_OK_EAT if your callback has updated the command line, so that WeeChat will not perform the completion). |
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.15. weechat_hook_completion_get_string
WeeChat ≥ 0.3.4.
Get a completion property as string.
Prototype:
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:
Script (Python):
3.11.16. weechat_hook_completion_list_add
Add a word for a completion.
Prototype:
Arguments:
-
completion: completion pointer
-
word: word to add
-
nick_completion: 1 if word is a nick, otherwise 0
-
where: position where word will be inserted in list:
-
WEECHAT_LIST_POS_SORT: any position, to keep list sorted
-
WEECHAT_LIST_POS_BEGINNING: beginning of list
-
WEECHAT_LIST_POS_END: end of list
-
C example: see weechat_hook_completion.
Script (Python):
3.11.17. weechat_hook_modifier
Hook a modifier.
Prototype:
Arguments:
-
modifier: modifier name, list of modifiers used by Weechat or plugins (priority allowed, see note about priority) (see table below)
-
callback: function called when modifier is used, arguments and return value:
-
void *data: pointer
-
const char *modifier: name of modifier
-
const char *modifier_data: data for modifier
-
const char *string: string to modify
-
return value: new string
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
List of modifiers used by WeeChat and plugins:
Modifier | Modifier data | String | Output |
---|---|---|---|
charset_decode |
plugin.buffer_name |
Any string |
String decoded from charset found for plugin/buffer to UTF-8 |
charset_encode |
plugin.buffer_name |
Any string |
String encoded from UTF-8 to charset found for plugin/buffer |
irc_color_decode |
"1" to keep colors, "0" to remove colors |
Any string |
String with IRC colors converted to WeeChat colors (or IRC colors removed) |
irc_color_encode |
"1" to keep colors, "0" to remove colors |
Any string |
String with IRC colors (or IRC colors removed) |
irc_color_decode_ansi |
"1" to keep colors, "0" to remove colors |
Any string |
String with ANSI colors converted to IRC colors (or ANSI colors removed) |
irc_command_auth |
Server name |
Authentication command (for example: |
command with hidden password (for example: |
irc_message_auth |
Server name |
Message displayed after |
Message with hidden password |
irc_in_xxx (1) |
Server name |
Content of message received from IRC server (before charset decoding) |
New content of message |
irc_in2_xxx (1) |
Server name |
Content of message received from IRC server (after charset decoding) |
New content of message |
irc_out1_xxx (1) |
Server name |
Content of message about to be sent to IRC server (before automatic split to fit in 512 bytes) |
New content of message |
irc_out_xxx (1) |
Server name |
Content of message about to be sent to IRC server (after automatic split to fit in 512 bytes) |
New content of message |
color_decode_ansi |
"1" to keep colors, "0" to remove colors |
Any string |
String with ANSI colors converted to WeeChat colors (or ANSI colors removed) |
bar_condition_yyy (2) |
String with window pointer ("0x123..") |
Empty string |
"1" to display bar, "0" to hide it |
history_add |
String with buffer pointer ("0x123..") |
Content of command line to add in command history (buffer and global) |
String added to command history |
input_text_content |
String with buffer pointer ("0x123..") |
Content of command line |
New content of command line |
input_text_display |
String with buffer pointer ("0x123..") |
Content of command line, without cursor tag |
New string, for display only (command line is not changed) |
input_text_display_with_cursor |
String with buffer pointer ("0x123..") |
Content of command line, with cursor tag |
New string, for display only (command line is not changed) |
input_text_for_buffer |
String with buffer pointer ("0x123..") |
Content of command line sent to buffer (text or command) |
New content of command line sent to buffer |
weechat_print |
plugin + ";" + buffer_name + ";" + tags |
Message printed |
New message printed |
Note
|
(1) xxx is IRC command name. (2) yyy is bar name. |
C example:
Script (Python):
3.11.18. weechat_hook_modifier_exec
Execute modifier(s).
Prototype:
Arguments:
-
modifier: modifier name
-
modifier_data: modifier data
-
string: string to modify
Return value:
-
string modified, NULL if error occurred
C example:
Script (Python):
3.11.19. weechat_hook_info
Hook an information (callback takes and returns a string).
Prototype:
Arguments:
-
info_name: name of info (priority allowed, see note about priority)
-
description: description
-
args_description: description of arguments (optional, can be NULL)
-
callback: function called when info is asked, arguments and return value:
-
void *data: pointer
-
const char *info_name: name of info
-
const char *arguments: additional arguments, depending on info
-
return value: value of info asked
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.20. weechat_hook_info_hashtable
WeeChat ≥ 0.3.4.
Hook an information (callback takes and returns a hashtable).
Prototype:
Arguments:
-
info_name: name of info (priority allowed, see note about priority)
-
description: description
-
args_description: description of expected hashtable (optional, can be NULL)
-
output_description: description of hashtable returned by callback (optional, can be NULL)
-
callback: function called when info is asked, arguments and return value:
-
void *data: pointer
-
const char *info_name: name of info
-
struct t_hashtable *hashtable: hashtable, depending on info
-
return value: hashtable asked
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.21. weechat_hook_infolist
Hook an infolist: callback will return pointer to infolist asked.
Prototype:
Arguments:
-
infolist_name: name of infolist (priority allowed, see note about priority)
-
description: description
-
pointer_description: description of pointer (optional, can be NULL)
-
args_description: description of arguments (optional, can be NULL)
-
callback: function called when infolist is asked, arguments and return value:
-
void *data: pointer
-
const char *infolist_name: name of infolist
-
void *pointer: pointer to an object that infolist must return (to get only one item in infolist)
-
const char *arguments: additional arguments, depending on infolist
-
return value: infolist asked
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.22. weechat_hook_hdata
Hook a hdata: callback will return pointer to hdata asked.
Prototype:
Arguments:
-
hdata_name: name of hdata (priority allowed, see note about priority)
-
description: description
-
callback: function called when hdata is asked, arguments and return value:
-
void *data: pointer
-
const char *hdata_name: name of hdata
-
return value: hdata asked
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Note
|
This function is not available in scripting API. |
3.11.23. weechat_hook_focus
Hook a focus: mouse event or key pressed in cursor mode (free movement of cursor).
Prototype:
Arguments:
-
area: "chat" for chat area, or name of bar item (priority allowed, see note about priority)
-
callback: function called when focus is made, arguments and return value:
-
void *data: pointer
-
struct t_hashtable *info: hashtable with info on focus and strings returned by other calls to focus callbacks (with higher priority) (see table below)
-
return value: either "info" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string"), this new hashtable content will be added to info for other calls to focus callbacks
-
-
callback_data: pointer given to callback when it is called by WeeChat
Important
|
For a mouse gesture, your callback will be called two times: first time when button is pressed (here the area always matches your area), second time when button is released, and then the area may not match your area: so you must always test in your callback if area is matching before using info in hashtable. |
Content of hashtable sent to callback (keys and values are of type "string"):
Key (1) | Description | Value examples | Value if N/A |
---|---|---|---|
|
Column on screen |
"0" … "n" |
|
|
Line on screen |
"0" … "n" |
|
|
Key or mouse event |
"button1", "button2-gesture-left", … |
|
|
Pointer to window |
"0x12345678" |
"" |
|
Number of window |
"1" … "n" |
"*" |
|
Pointer to buffer |
"0x12345678" |
"" |
|
Number of buffer |
"1" … "n" |
"-1" |
|
Plugin name of buffer |
"core", "irc", … |
"" |
|
Name of buffer |
"weechat", "freenode.#weechat", … |
"" |
|
Full name of buffer |
"core.weechat", "irc.freenode.#weechat", … |
"" |
|
Local variables of buffer |
any value |
not set |
|
Chat area indicator |
"0" or "1" |
"0" |
|
Column in line (3) |
"0" … "n" |
"-1" |
|
Line number (3) |
"0" … "n" |
"-1" |
|
Line date/time |
"1313237175" |
"0" |
|
Line date/time (4) |
"1313237175" |
"0" |
|
Time displayed |
"14:06:15" |
"" |
|
Tags of line |
"irc_privmsg,nick_flashy,log1" |
"" |
|
Nick of line |
"FlashCode" |
"" |
|
Prefix of line |
"@FlashCode" |
"" |
|
Message of line |
"Hello world!" |
"" |
|
Word at (x,y) |
"Hello" |
"" |
|
Beginning of line ⇒ (x-1,y) |
"He" |
"" |
|
(x,y) ⇒ end of line |
"llo world!" |
"" |
|
Name of bar |
"title", "nicklist", … |
"" |
|
Filling of bar |
"horizontal", "vertical", … |
"" |
|
Name of bar item |
"buffer_nicklist", "hotlist", … |
"" |
|
Line in bar item |
"0" … "n" |
"-1" |
|
Column in bar item |
"0" … "n" |
"-1" |
Note
|
(1) There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", …)
with info on second point (useful only for mouse gestures, to know where mouse
button has been released). (2) XXX is name of local variable in buffer.(3) It is set only for buffers with free content. (4) It is date when WeeChat adds line in buffer (greater or equal to "_chat_line_date"). |
Extra info for bar item "buffer_nicklist":
Key | Plugin (1) | Description |
---|---|---|
|
core |
Nick name |
|
core |
Prefix for nick |
|
core |
Group name |
|
irc |
Host for nick (if known) |
Note
|
(1) The name of plugin which defines a hook_focus to return info for this bar item (so for example if plugin is "irc", such info will be available only on irc buffers). |
Return value:
-
pointer to new hook, NULL if error occurred
C example:
Script (Python):
3.11.24. weechat_hook_set
WeeChat ≥ 0.3.9 (script: WeeChat ≥ 0.4.3).
Set string value of a hook property.
Prototype:
Arguments:
-
hook: something hooked with "weechat_hook_xxx()"
-
property: property name (see table below)
-
value: new value for property
Properties:
Name | Hook type | Value | Description |
---|---|---|---|
subplugin |
any type |
any string |
Name of sub plugin (commonly script name, which is displayed in
|
stdin |
process, process_hashtable |
any string |
Send data on standard input (stdin) of child process |
stdin_close |
process, process_hashtable |
(not used) |
Close pipe used to send data on standard input (stdin) of child process |
signal |
process, process_hashtable |
signal number or one of these names: |
Send a signal to the child process |
C example:
Script (Python):
3.11.25. weechat_unhook
Unhook something hooked.
Prototype:
Arguments:
-
hook: something hooked with "weechat_hook_xxx()"
C example:
Script (Python):
3.11.26. weechat_unhook_all
Unhook everything that has been hooked by current plugin.
Prototype:
C example:
Script (Python):
3.12. Buffers
Functions to create/query/close buffers.
3.12.1. weechat_buffer_new
Open a new buffer.
Prototype:
Arguments:
-
name: name of buffer (must be unique for plugin)
-
input_callback: function called when input text is entered on buffer, arguments and return value:
-
void *data: pointer
-
struct t_gui_buffer *buffer: buffer pointer
-
const char *input_data: input data
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
-
close_callback: function called when buffer is closed, arguments and return value:
-
void *data: pointer
-
struct t_gui_buffer *buffer: buffer pointer
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_data: pointer given to callback when it is called by WeeChat
Return value:
-
pointer to new buffer, NULL if error occurred
C example:
Script (Python):
3.12.2. weechat_current_buffer
Return pointer to current buffer (buffer displayed by current window).
Prototype:
Return value:
-
pointer to current buffer
C example:
Script (Python):
3.12.3. weechat_buffer_search
Updated in 1.0.
Search a buffer by plugin and/or name.
Prototype:
Arguments:
-
plugin: name of plugin, following special value is allowed:
-
==
: the name used is the buffer full name (for example:irc.freenode.#weechat
instead offreenode.#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:
Script (Python):
3.12.4. weechat_buffer_search_main
Search WeeChat main buffer (core buffer, first buffer displayed when WeeChat is starting).
Prototype:
Return value:
-
pointer to WeeChat main buffer (core buffer)
C example:
Script (Python):
3.12.5. weechat_buffer_clear
Clear content of a buffer.
Prototype:
Arguments:
-
buffer: buffer pointer
C example:
Script (Python):
3.12.6. weechat_buffer_close
Close a buffer.
Prototype:
Arguments:
-
buffer: buffer pointer
C example:
Script (Python):
3.12.7. weechat_buffer_merge
Merge buffer into another buffer: both buffers will still exist separately, but with same number, and WeeChat will display lines from both buffers (mixed lines).
Prototype:
Arguments:
-
buffer: buffer pointer
-
target_buffer: target buffer, where buffer will be merged
C example:
Script (Python):
3.12.8. weechat_buffer_unmerge
Unmerge buffer from a group of merged buffers.
Prototype:
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:
Script (Python):
3.12.9. weechat_buffer_get_integer
Return integer value of a buffer property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
property: property name:
-
number: number of buffer (starts to 1)
-
layout_number: number of buffer saved in layout
-
layout_number_merge_order: order in merge for layout
-
short_name_is_set: 1 if short name is set, 0 if not set
-
type: buffer type (0: formatted, 1: free content)
-
notify: notify level for buffer
-
num_displayed: number of windows displaying buffer
-
active: 2 if buffer is the only active (merged), 1 if buffer is active, 0 if buffer is merged and not selected
-
hidden: 1 if buffer is hidden, otherwise 0 (WeeChat ≥ 1.0)
-
zoomed: 1 if buffer is merged and zoomed, otherwise 0 (WeeChat ≥ 1.0)
-
print_hooks_enabled: 1 if print hooks are enabled, otherwise 0
-
day_change: 1 if messages for the day change are displayed, otherwise 0 (WeeChat ≥ 0.4.3)
-
clear: 1 if buffer can be cleared with command
/buffer clear
, otherwise 0 (WeeChat ≥ 1.0) -
filter: 1 if filters are enabled on buffer, otherwise 0 (WeeChat ≥ 1.0)
-
lines_hidden: 1 if at least one line is hidden on buffer (filtered), or 0 if all lines are displayed
-
prefix_max_length: max length for prefix in this buffer
-
time_for_each_line: 1 if time is displayed for each line in buffer (default), otherwise 0
-
nicklist: 1 if nicklist is enabled, otherwise 0
-
nicklist_case_sensitive: 1 if nicks are case sensitive, otherwise 0
-
nicklist_max_length: max length for a nick
-
nicklist_display_groups: 1 if groups are displayed, otherwise 0
-
nicklist_count: number of nicks and groups in nicklist
-
nicklist_groups_count: number of groups in nicklist
-
nicklist_nicks_count: number of nicks in nicklist
-
nicklist_visible_count: number of nicks/groups displayed
-
input: 1 if input is enabled, otherwise 0
-
input_get_unknown_commands: 1 if unknown commands are sent to input callback, otherwise 0
-
input_size: input size (in bytes)
-
input_length: input length (number of chars)
-
input_pos: cursor position in buffer input
-
input_1st_display: first char displayed on screen
-
num_history: number of commands in history
-
text_search: text search type:
-
0: no search at this moment
-
1: backward search (direction: oldest messages)
-
2: forward search (direction: newest messages)
-
-
text_search_exact: 1 if text search is case sensitive
-
text_search_found: 1 if text found, otherwise 0
-
Return value:
-
integer value of property
C example:
Script (Python):
3.12.10. weechat_buffer_get_string
Return string value of a buffer property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
property: property name:
-
plugin: name of plugin which created this buffer ("core" for WeeChat main buffer)
-
name: name of buffer
-
full_name: full name of buffer ("plugin.name") (WeeChat ≥ 0.3.7)
-
short_name: short name of buffer (note: used for display only and can be changed by user, this must not be used to find name of buffer, use instead name, full_name or local variable channel)
-
title: title of buffer
-
input: input text
-
text_search_input: input saved before text search
-
highlight_words: list of words to highlight
-
highlight_regex: POSIX extended regular expression for highlight
-
highlight_tags_restrict: restrict highlights to messages with these tags
-
highlight_tags: force highlight on messages with these tags
-
hotlist_max_level_nicks: max hotlist level for some nicks
-
localvar_xxx: get content of local variable "xxx" (replace "xxx" by the name of variable to read)
-
Return value:
-
string value of property
C example:
Script (Python):
3.12.11. weechat_buffer_get_pointer
Return pointer value of a buffer property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
property: property name:
-
plugin: pointer to plugin which created this buffer (NULL for WeeChat main buffer)
-
highlight_regex_compiled: regular expression highlight_regex compiled
-
Return value:
-
pointer value of property
C example:
Script (Python):
3.12.12. weechat_buffer_set
Set string value of a buffer property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
property: property name (see table below)
-
value: new value for property
Properties:
Name | Value | Description |
---|---|---|
hotlist |
"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" |
"+": enable hotlist (global setting, buffer pointer is not used) |
completion_freeze |
"0" or "1" |
"0": no freeze of completion (default value)
(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 |
hidden |
"0" or "1" |
"0": unhide 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" or "1" |
"0" to hide messages for the day change, "1" to see them (default for a new buffer) |
clear |
"0" or "1" |
"0" to prevent user from clearing buffer with the command |
filter |
"0" or "1" |
"0": disable filters on buffer |
title |
any string |
Set new title for buffer |
time_for_each_line |
"0" or "1" |
"0" to hide time for all lines in buffer, "1" to see time for all lines (default for a new buffer) |
nicklist |
"0" or "1" |
"0" to remove nicklist for buffer, "1" to add nicklist for buffer |
nicklist_case_sensitive |
"0" or "1" |
"0" to have case insensitive nicklist, "1" to have case sensitive nicklist |
nicklist_display_groups |
"0" or "1" |
"0" to hide nicklist groups, "1" to display nicklist groups |
highlight_words |
"-" or comma separated list of words |
"-" is a special value to disable any highlight on this buffer, or comma separated list of words to highlight in this buffer, for example: "abc,def,ghi" |
highlight_words_add |
comma separated list of words |
Comma separated list of words to highlight in this buffer, these words are added to existing highlighted words in buffer |
highlight_words_del |
comma separated list of words |
Comma separated list of words to remove from highlighted words on buffer |
highlight_regex |
any string |
POSIX extended regular expression for highlight |
highlight_tags_restrict |
comma separated list of tags |
Restrict highlights to messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action") |
highlight_tags |
comma separated list of tags |
Force highlight on messages with these tags in this buffer (it is possible to combine many tags as a logical "and" with separator "+", for example: "nick_toto+irc_action") |
hotlist_max_level_nicks |
comma separated list of "nick:level" |
Comma separated list of nicks with max level for hotlist on this buffer (level can be: -1: never in hotlist, 0: low, 1: message, 2: private, 3: highlight), for example: "joe:2,mike:-1,robert:-1" (joe will never produce highlight on buffer, mike and robert will never change hotlist) |
hotlist_max_level_nicks_add |
comma separated list of "nick:level" |
Comma separated list of nicks with level for hotlist, these nicks are added to existing nicks in buffer |
hotlist_max_level_nicks_del |
comma separated list of nicks |
Comma separated list of nicks to remove from hotlist max levels |
key_bind_xxx |
any string |
Bind a new key xxx, specific to this buffer, value is command to execute for this key |
key_unbind_xxx |
- |
Unbind key xxx for this buffer |
input |
any string |
Set new value for buffer input |
input_pos |
position |
Set cursor position in buffer input |
input_get_unknown_commands |
"0" or "1" |
"0" to disable unknown commands on this buffer (default behavior), "1" to get unknown commands, for example if user type "/unknowncmd", buffer will receive it (no error about unknown command) |
localvar_set_xxx |
any string |
Set new value for local variable xxx (variable is created if it does not exist) |
localvar_del_xxx |
- |
Remove local variable xxx |
C example:
Script (Python):
3.12.13. weechat_buffer_set_pointer
Set pointer value of a buffer property.
Prototype:
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:
C example:
Note
|
This function is not available in scripting API. |
3.12.14. weechat_buffer_string_replace_local_var
Replace local variables in a string by their values, using buffer local variables.
Prototype:
Arguments:
-
buffer: buffer pointer
-
string: string with text and local variables using format "$var"
Return value:
-
string with values of local variables
C example:
Script (Python):
3.12.15. weechat_buffer_match_list
WeeChat ≥ 0.3.5.
Check if buffer matches a list of buffers.
Prototype:
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:
Script (Python):
3.13. Windows
Functions to query windows.
3.13.1. weechat_current_window
Return pointer to current window.
Prototype:
Return value:
-
pointer to current window
C example:
Script (Python):
3.13.2. weechat_window_search_with_buffer
WeeChat ≥ 0.3.5.
Return pointer to window displaying buffer.
Prototype:
Arguments:
-
buffer: buffer pointer
Return value:
-
pointer to window displaying buffer (NULL if no window is displaying buffer)
C example:
Script (Python):
3.13.3. weechat_window_get_integer
Return integer value of a window property.
Prototype:
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:
Script (Python):
3.13.4. weechat_window_get_string
Return string value of a window property.
Note
|
This function is not used today, it is reserved for a future version. |
Prototype:
Arguments:
-
window: window pointer
-
property: property name
Return value:
-
string value of property
3.13.5. weechat_window_get_pointer
Return pointer value of a window property.
Prototype:
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:
Script (Python):
3.13.6. weechat_window_set_title
Set title for terminal.
Prototype:
Arguments:
-
title: new title for terminal (NULL to reset title)
C example:
Script (Python):
3.14. Nicklist
Functions for buffer nicklist.
3.14.1. weechat_nicklist_add_group
Add a group in a nicklist.
Prototype:
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:
Script (Python):
3.14.2. weechat_nicklist_search_group
Search a group in a nicklist.
Prototype:
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:
Script (Python):
3.14.3. weechat_nicklist_add_nick
Add a nick in a group.
Prototype:
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:
Script (Python):
3.14.4. weechat_nicklist_search_nick
Search a nick in a nicklist.
Prototype:
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:
Script (Python):
3.14.5. weechat_nicklist_remove_group
Remove a group from a nicklist.
Prototype:
Arguments:
-
buffer: buffer pointer
-
group: group pointer to remove (all sub-groups/nicks will be removed too)
C example:
Script (Python):
3.14.6. weechat_nicklist_remove_nick
Remove a nick from a nicklist.
Prototype:
Arguments:
-
buffer: buffer pointer
-
nick: nick pointer to remove
C example:
Script (Python):
3.14.7. weechat_nicklist_remove_all
Remove all groups/nicks from a nicklist.
Prototype:
Arguments:
-
buffer: buffer pointer
C example:
Script (Python):
3.14.8. weechat_nicklist_get_next_item
WeeChat ≥ 0.3.7.
Get next group or nick from nicklist (mainly used to display nicklist).
Prototype:
Arguments:
-
buffer: buffer pointer
-
group: pointer on pointer to group
-
nick: pointer on pointer to nick
C example:
Note
|
This function is not available in scripting API. |
3.14.9. weechat_nicklist_group_get_integer
WeeChat ≥ 0.3.4.
Return integer value of a group property.
Prototype:
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:
Script (Python):
3.14.10. weechat_nicklist_group_get_string
WeeChat ≥ 0.3.4.
Return string value of a group property.
Prototype:
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:
Script (Python):
3.14.11. weechat_nicklist_group_get_pointer
WeeChat ≥ 0.3.4.
Return pointer value of a group property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
group: group pointer
-
property: property name:
-
parent: pointer to parent group
-
Return value:
-
pointer value of property
C example:
Script (Python):
3.14.12. weechat_nicklist_group_set
WeeChat ≥ 0.3.4.
Set string value of a group property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
group: group pointer
-
property: property name (see table below)
-
value: new value for property
Properties:
Name | Value | Description |
---|---|---|
color |
WeeChat color option name |
See argument "color" of function weechat_nicklist_add_group |
visible |
"0", "1" |
"0" = hidden group, "1" = visible group |
C examples:
Script (Python):
3.14.13. weechat_nicklist_nick_get_integer
WeeChat ≥ 0.3.4.
Return integer value of a nick property.
Prototype:
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:
Script (Python):
3.14.14. weechat_nicklist_nick_get_string
WeeChat ≥ 0.3.4.
Return string value of a nick property.
Prototype:
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:
Script (Python):
3.14.15. weechat_nicklist_nick_get_pointer
WeeChat ≥ 0.3.4.
Return pointer value of a nick property.
Prototype:
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:
Script (Python):
3.14.16. weechat_nicklist_nick_set
WeeChat ≥ 0.3.4.
Set string value of a nick property.
Prototype:
Arguments:
-
buffer: buffer pointer
-
nick: nick pointer
-
property: property name (see table below)
-
value: new value for property
Properties:
Name | Value | Description |
---|---|---|
color |
WeeChat color option name |
See argument "color" of function weechat_nicklist_add_nick |
prefix |
any string |
Prefix of nick |
prefix_color |
WeeChat color option name |
See argument "prefix_color" of function weechat_nicklist_add_nick |
visible |
"0", "1" |
"0" = hidden nick, "1" = visible nick |
C examples:
Script (Python):
3.15. Bars
Functions for bars.
3.15.1. weechat_bar_item_search
Search a bar item.
Prototype:
Arguments:
-
name: bar item name
Return value:
-
pointer to bar item found, NULL if bar item was not found
C example:
Script (Python):
3.15.2. weechat_bar_item_new
Updated in 0.4.2.
Create a new bar item.
Prototype:
Arguments:
-
name: bar item name
-
build_callback: function called when bar item is built, arguments and return value:
-
void *data: pointer
-
struct t_gui_bar_item *item: item pointer
-
struct t_gui_window *window: window pointer (NULL when called for a root bar)
-
struct t_gui_buffer *buffer: buffer displayed in window (if window is NULL, then it is current buffer) or buffer given in bar item with syntax: "@buffer:item" (WeeChat ≥ 0.4.2)
-
struct t_hashtable *extra_info: always NULL (argument is reserved for a future version) (WeeChat ≥ 0.4.2)
-
return value: content of bar item
-
-
build_callback_data: pointer given to build callback, when it is called by WeeChat
Return value:
-
pointer to new bar item, NULL if an error occurred
C example:
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). |
3.15.3. weechat_bar_item_update
Update content of a bar item, by calling its build callback.
Prototype:
Arguments:
-
name: bar item name
C example:
Script (Python):
3.15.4. weechat_bar_item_remove
Remove a bar item.
Prototype:
Arguments:
-
item: bar item pointer
C example:
Script (Python):
3.15.5. weechat_bar_search
Search a bar.
Prototype:
Arguments:
-
name: bar name
Return value:
-
pointer to bar found, NULL if bar was not found
C example:
Script (Python):
3.15.6. weechat_bar_new
Create a new bar.
Prototype:
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 chapter about bars in WeeChat User’s guide
-
-
position: top, bottom, left or right
-
filling_top_bottom:
-
horizontal: items are filled horizontally (space after each item)
-
vertical: items are filled vertically (new line after each item)
-
columns_horizontal: items are filled horizontally, displayed with columns
-
columns_vertical: items are filled vertically, displayed with columns
-
-
filling_left_right:
-
horizontal: items are filled horizontally (space after each item)
-
vertical: items are filled vertically (new line after each item)
-
columns_horizontal: items are filled horizontally, displayed with columns
-
columns_vertical: items are filled vertically, displayed with columns
-
-
size: bar size in chars (0 means automatic size)
-
size_max: max size for bar (0 means no max size)
-
color_fg: color for text in bar
-
color_delim: color for delimiters in bar
-
color_bg: background color for bar
-
separator:
-
on: bar has separator line with other windows/bars
-
off: no separator
-
-
items: list of items in bar, separated by comma (space between items), or "+" (glued items)
Return value:
-
pointer to new bar, NULL if an error occurred
C example:
Script (Python):
3.15.7. weechat_bar_set
Set a new value for a bar property.
Prototype:
Arguments:
-
bar: bar pointer
-
property: name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items (see weechat_bar_new)
-
value: new value for property
Return value:
-
1 if new value was set, 0 if an error occurred
C example:
Script (Python):
3.15.8. weechat_bar_update
Refresh content of a bar on screen.
Prototype:
Arguments:
-
name: bar name
C example:
Script (Python):
3.15.9. weechat_bar_remove
Remove a bar.
Prototype:
Arguments:
-
bar: bar pointer
C example:
Script (Python):
3.16. Commands
Functions for executing WeeChat commands.
3.16.1. weechat_command
Updated in 1.1.
Execute a command.
Prototype:
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:
Script (Python):
3.17. Network
Network functions.
3.17.1. weechat_network_pass_proxy
Establish a connection/authentication to a proxy.
Important
|
This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat. |
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.17.2. weechat_network_connect_to
Updated in 0.4.3.
Establish a connection to a remote host.
Important
|
This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat. |
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.18. Infos
Functions to get infos.
3.18.1. weechat_info_get
Return info, as string, from WeeChat or a plugin.
Prototype:
Arguments:
-
info_name: name of info to read (see table below)
-
arguments: arguments for info asked (optional, NULL if no argument is needed)
Return value:
-
string with info asked, NULL if an error occurred
Infos:
Plugin | Name | Description | Arguments |
---|---|---|---|
aspell |
aspell_dict |
comma-separated list of dictionaries used in buffer |
buffer pointer ("0x12345678") or buffer full name ("irc.freenode.#weechat") |
fifo |
fifo_filename |
name of FIFO pipe |
- |
irc |
irc_buffer |
get buffer pointer for an IRC server/channel/nick |
server,channel,nick (channel and nicks are optional) |
irc |
irc_is_channel |
1 if string is a valid IRC channel name for server |
server,channel (server is optional) |
irc |
irc_is_nick |
1 if string is a valid IRC nick name |
nickname |
irc |
irc_nick |
get current nick on a server |
server name |
irc |
irc_nick_color |
get nick color code |
nickname |
irc |
irc_nick_color_name |
get nick color name |
nickname |
irc |
irc_nick_from_host |
get nick from IRC host |
IRC host (like |
irc |
irc_server_isupport |
1 if server supports this feature (from IRC message 005) |
server,feature |
irc |
irc_server_isupport_value |
value of feature, if supported by server (from IRC message 005) |
server,feature |
python |
python2_bin |
path to python 2.x interpreter |
- |
relay |
relay_client_count |
number of clients for relay |
status name (optional): connecting, waiting_auth, connected, auth_failed, disconnected |
weechat |
charset_internal |
WeeChat internal charset |
- |
weechat |
charset_terminal |
terminal charset |
- |
weechat |
color_ansi_regex |
POSIX extended regular expression to search ANSI escape codes |
- |
weechat |
color_rgb2term |
RGB color converted to terminal color (0-255) |
rgb,limit (limit is optional and is set to 256 by default) |
weechat |
color_term2rgb |
terminal color (0-255) converted to RGB color |
color (terminal color: 0-255) |
weechat |
cursor_mode |
1 if cursor mode is enabled |
- |
weechat |
date |
WeeChat compilation date |
- |
weechat |
dir_separator |
directory separator |
- |
weechat |
filters_enabled |
1 if filters are enabled |
- |
weechat |
inactivity |
keyboard inactivity (seconds) |
- |
weechat |
locale |
locale used for translating messages |
- |
weechat |
term_height |
height of terminal |
- |
weechat |
term_width |
width of terminal |
- |
weechat |
version |
WeeChat version |
- |
weechat |
version_git |
WeeChat git version (output of command "git describe" for a development version only, empty for a stable release) |
- |
weechat |
version_number |
WeeChat version (as number) |
- |
weechat |
weechat_dir |
WeeChat directory |
- |
weechat |
weechat_libdir |
WeeChat "lib" directory |
- |
weechat |
weechat_localedir |
WeeChat "locale" directory |
- |
weechat |
weechat_sharedir |
WeeChat "share" directory |
- |
weechat |
weechat_site |
WeeChat site |
- |
weechat |
weechat_site_download |
WeeChat site, download page |
- |
weechat |
weechat_upgrading |
1 if WeeChat is upgrading (command |
- |
C example:
Script (Python):
3.18.2. weechat_info_get_hashtable
WeeChat ≥ 0.3.4.
Return info, as hashtable, from WeeChat or a plugin.
Prototype:
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:
Plugin | Name | Description | Hashtable (input) | Hashtable (output) |
---|---|---|---|---|
irc |
irc_message_parse |
parse an IRC message |
"message": IRC message, "server": server name (optional) |
"tags": tags, "message_without_tags": message without the tags, "nick": nick, "host": host, "command": command, "channel": channel, "arguments": arguments (includes channel) |
irc |
irc_message_split |
split an IRC message (to fit in 512 bytes) |
"message": IRC message, "server": server name (optional) |
"msg1" … "msgN": messages to send (without final "\r\n"), "args1" … "argsN": arguments of messages, "count": number of messages |
C example:
Script (Python):
3.19. 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
3.19.1. weechat_infolist_new
Create a new infolist.
Prototype:
Return value:
-
pointer to new infolist
C example:
Script (Python):
3.19.2. weechat_infolist_new_item
Add an item in an infolist.
Prototype:
Arguments:
-
infolist: infolist pointer
Return value:
-
pointer to new item
C example:
Script (Python):
3.19.3. weechat_infolist_new_var_integer
Add an integer variable to an infolist item.
Prototype:
Arguments:
-
item: infolist item pointer
-
name: variable name
-
value: integer value
Return value:
-
pointer to new variable
C example:
Script (Python):
3.19.4. weechat_infolist_new_var_string
Add a string variable to an infolist item.
Prototype:
Arguments:
-
item: infolist item pointer
-
name: variable name
-
value: string value
Return value:
-
pointer to new variable
C example:
Script (Python):
3.19.5. weechat_infolist_new_var_pointer
Add a pointer variable to an infolist item.
Prototype:
Arguments:
-
item: infolist item pointer
-
name: variable name
-
pointer: pointer
Return value:
-
pointer to new variable
C example:
Script (Python):
3.19.6. weechat_infolist_new_var_buffer
Add a buffer variable to an infolist item.
Prototype:
Arguments:
-
item: infolist item pointer
-
name: variable name
-
pointer: pointer to buffer
-
size: size of buffer
Return value:
-
pointer to new variable
C example:
Note
|
This function is not available in scripting API. |
3.19.7. weechat_infolist_new_var_time
Add a time variable to an infolist item.
Prototype:
Arguments:
-
item: infolist item pointer
-
name: variable name
-
time: time value
Return value:
-
pointer to new variable
C example:
Script (Python):
3.19.8. weechat_infolist_get
Return infolist from WeeChat or a plugin.
Important
|
Content of infolist is a duplication of actual data. So if you are asking
infolist with lot of data (like "buffer_lines"), WeeChat will allocate memory
to duplicate all data, and this can take some time. Instead of using big infolist, it is preferable to use hdata (but infolist may have more info than hdata, which is raw data), see hdata. |
Prototype:
Arguments:
-
infolist_name: name of infolist to read (see table below)
-
pointer: pointer to an item, to get only this item in infolist (optional, can be NULL)
-
arguments: arguments for infolist asked (optional, NULL if no argument is needed)
Return value:
-
pointer to infolist, NULL if an error occurred
Infolists:
Plugin | Name | Description | Pointer | Arguments |
---|---|---|---|---|
alias |
alias |
list of aliases |
alias pointer (optional) |
alias name (wildcard "*" is allowed) (optional) |
guile |
guile_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
irc |
irc_channel |
list of channels for an IRC server |
channel pointer (optional) |
server,channel (channel is optional) |
irc |
irc_color_weechat |
mapping between IRC color codes and WeeChat color names |
- |
- |
irc |
irc_ignore |
list of IRC ignores |
ignore pointer (optional) |
- |
irc |
irc_nick |
list of nicks for an IRC channel |
nick pointer (optional) |
server,channel,nick (nick is optional) |
irc |
irc_notify |
list of notify |
notify pointer (optional) |
server name (wildcard "*" is allowed) (optional) |
irc |
irc_server |
list of IRC servers |
server pointer (optional) |
server name (wildcard "*" is allowed) (optional) |
logger |
logger_buffer |
list of logger buffers |
logger pointer (optional) |
- |
lua |
lua_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
perl |
perl_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
python |
python_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
relay |
relay |
list of relay clients |
relay pointer (optional) |
- |
ruby |
ruby_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
script |
script_script |
list of scripts |
script pointer (optional) |
script name with extension (wildcard "*" is allowed) (optional) |
tcl |
tcl_script |
list of scripts |
script pointer (optional) |
script name (wildcard "*" is allowed) (optional) |
weechat |
bar |
list of bars |
bar pointer (optional) |
bar name (wildcard "*" is allowed) (optional) |
weechat |
bar_item |
list of bar items |
bar item pointer (optional) |
bar item name (wildcard "*" is allowed) (optional) |
weechat |
bar_window |
list of bar windows |
bar window pointer (optional) |
- |
weechat |
buffer |
list of buffers |
buffer pointer (optional) |
buffer name (wildcard "*" is allowed) (optional) |
weechat |
buffer_lines |
lines of a buffer |
buffer pointer |
- |
weechat |
filter |
list of filters |
- |
filter name (wildcard "*" is allowed) (optional) |
weechat |
history |
history of commands |
buffer pointer (if not set, return global history) (optional) |
- |
weechat |
hook |
list of hooks |
hook pointer (optional) |
type,arguments (type is command/timer/.., arguments to get only some hooks (wildcard "*" is allowed), both are optional) |
weechat |
hotlist |
list of buffers in hotlist |
- |
- |
weechat |
key |
list of key bindings |
- |
context ("default", "search", "cursor" or "mouse") (optional) |
weechat |
layout |
list of layouts |
- |
- |
weechat |
nicklist |
nicks in nicklist for a buffer |
buffer pointer |
nick_xxx or group_xxx to get only nick/group xxx (optional) |
weechat |
option |
list of options |
- |
option name (wildcard "*" is allowed) (optional) |
weechat |
plugin |
list of plugins |
plugin pointer (optional) |
plugin name (wildcard "*" is allowed) (optional) |
weechat |
proxy |
list of proxies |
proxy pointer (optional) |
proxy name (wildcard "*" is allowed) (optional) |
weechat |
url_options |
options for URL |
- |
- |
weechat |
window |
list of windows |
window pointer (optional) |
"current" for current window or a window number (optional) |
xfer |
xfer |
list of xfer |
xfer pointer (optional) |
- |
C example:
Script (Python):
3.19.9. weechat_infolist_next
Move "cursor" to next item in an infolist. The first call to this function for an infolist moves cursor to first item in infolist.
Prototype:
Arguments:
-
infolist: infolist pointer
Return value:
-
1 if cursor has been moved on next item, 0 if end of list was reached
C example:
Script (Python):
3.19.10. weechat_infolist_prev
Move "cursor" to previous item in an infolist. The first call to this function for an infolist moves cursor to last item in infolist.
Prototype:
Arguments:
-
infolist: infolist pointer
Return value:
-
1 if cursor has been moved on previous item, 0 if beginning of list was reached
C example:
Script (Python):
3.19.11. weechat_infolist_reset_item_cursor
Reset "cursor" for infolist.
Prototype:
Arguments:
-
infolist: infolist pointer
C example:
Script (Python):
3.19.12. weechat_infolist_search_var
WeeChat ≥ 0.4.3.
Search a variable in the current infolist item.
Prototype:
Arguments:
-
infolist: infolist pointer
-
name: variable name
Return value:
-
pointer to variable found, NULL if the variable was not found
C example:
Script (Python):
3.19.13. weechat_infolist_fields
Return list of fields for current infolist item.
Prototype:
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:
Script (Python):
3.19.14. weechat_infolist_integer
Return value of integer variable in current infolist item.
Prototype:
Arguments:
-
infolist: infolist pointer
-
var: variable name (must be type "integer")
Return value:
-
integer value of variable
C example:
Script (Python):
3.19.15. weechat_infolist_string
Return value of string variable in current infolist item.
Prototype:
Arguments:
-
infolist: infolist pointer
-
var: variable name (must be type "string")
Return value:
-
string value of variable
C example:
Script (Python):
3.19.16. weechat_infolist_pointer
Return value of pointer variable in current infolist item.
Prototype:
Arguments:
-
infolist: infolist pointer
-
var: variable name (must be type "pointer")
Return value:
-
pointer value of variable
C example:
Script (Python):
3.19.17. weechat_infolist_buffer
Return value of buffer variable in current infolist item.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.19.18. weechat_infolist_time
Return value of time variable in current infolist item.
Prototype:
Arguments:
-
infolist: infolist pointer
-
var: variable name (must be type "time")
Return value:
-
time value of variable
C example:
Script (Python):
3.19.19. weechat_infolist_free
Free an infolist.
Prototype:
Arguments:
-
infolist: infolist pointer
C example:
Script (Python):
3.20. Hdata
Functions for hdata (raw access to WeeChat or plugins data).
Important
|
Hdata provides read-only access to data. It is STRICTLY FORBIDDEN to write
something in memory pointed by hdata variables. The only way to update data is to call function weechat_hdata_update. |
3.20.1. weechat_hdata_new
WeeChat ≥ 0.3.6, updated in 0.3.9 and 0.4.0.
Create a new hdata.
Note
|
hdata vs infolist
Hdata is a fast way to read WeeChat or plugins data. It is similar to infolist, but there are some differences:
|
Prototype:
Arguments:
-
hdata_name: name of hdata
-
var_prev: name of variable in structure which is a pointer to previous element in list (may be NULL if no such variable is available)
-
var_next: name of variable in structure which is a pointer to next element in list (may be NULL if no such variable is available)
-
create_allowed: 1 if create of structure is allowed, otherwise 0 (WeeChat ≥ 0.4.0)
-
delete_allowed: 1 if delete of structure is allowed, otherwise 0 (WeeChat ≥ 0.3.9)
-
callback_update: callback to update data in hdata, can be NULL if no update is allowed (WeeChat ≥ 0.3.9), arguments and return value:
-
void *data: pointer
-
struct t_hdata *hdata: pointer to hdata
-
struct t_hashtable *hashtable: hashtable with variables to update (see weechat_hdata_update)
-
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:
Note
|
This function is not available in scripting API. |
3.20.2. weechat_hdata_new_var
WeeChat ≥ 0.3.6, updated in 0.3.9.
Create a new variable in hdata.
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: variable name
-
offset: offset of variable in structure
-
type: variable type, one of:
-
WEECHAT_HDATA_CHAR
-
WEECHAT_HDATA_INTEGER
-
WEECHAT_HDATA_LONG
-
WEECHAT_HDATA_STRING
-
WEECHAT_HDATA_SHARED_STRING
-
WEECHAT_HDATA_POINTER
-
WEECHAT_HDATA_TIME
-
WEECHAT_HDATA_HASHTABLE
-
WEECHAT_HDATA_OTHER
-
-
update_allowed: 1 if update of variable is allowed, otherwise 0 (WeeChat ≥ 0.3.9)
-
array_size: not NULL only if a variable is an array, and it can be: (WeeChat ≥ 0.3.9)
-
name of variable in hdata: this variable will be used as size of array (dynamic size for array)
-
integer (as string): fixed size for array
-
*: automatic size: the size of array is computed by looking at values, when the first NULL is found (only for type string, pointer or hashtable)
-
-
hdata_name: name of a hdata (if it’s a pointer to a structure with hdata)
C example:
The macro "WEECHAT_HDATA_VAR" can be used to shorten code:
Note
|
This function is not available in scripting API. |
3.20.3. weechat_hdata_new_list
WeeChat ≥ 0.3.6, updated in 1.0.
Create a new list pointer in hdata.
Prototype:
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:
The macro "WEECHAT_HDATA_LIST" can be used to shorten code:
Note
|
This function is not available in scripting API. |
3.20.4. weechat_hdata_get
WeeChat ≥ 0.3.6.
Return hdata for a WeeChat or plugin structure.
Note
|
Hdata does not contain data, it’s only a hashtable with position of variables in structure. That means you will need this hdata and a pointer to a WeeChat/plugin object to read some data. |
Prototype:
Arguments:
-
hdata_name: name of hdata (see list below)
Return value:
-
pointer to hdata, NULL if an error occurred
List of hdata:
-
guile_callback: callback of a script
-
plugin: guile
-
variables:
-
script (pointer, hdata: "guile_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "guile_callback")
-
next_callback (pointer, hdata: "guile_callback")
-
-
-
guile_script: list of scripts
-
plugin: guile
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "guile_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "guile_script")
-
next_script (pointer, hdata: "guile_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
irc_channel: irc channel
-
plugin: irc
-
variables:
-
type (integer)
-
name (string)
-
topic (string)
-
modes (string)
-
limit (integer)
-
key (string)
-
join_msg_received (hashtable)
-
checking_away (integer)
-
away_message (string)
-
has_quit_server (integer)
-
cycle (integer)
-
part (integer)
-
nick_completion_reset (integer)
-
pv_remote_nick_color (string)
-
hook_autorejoin (pointer)
-
nicks_count (integer)
-
nicks (pointer, hdata: "irc_nick")
-
last_nick (pointer, hdata: "irc_nick")
-
nicks_speaking (pointer)
-
nicks_speaking_time (pointer, hdata: "irc_channel_speaking")
-
last_nick_speaking_time (pointer, hdata: "irc_channel_speaking")
-
join_smart_filtered (hashtable)
-
buffer (pointer, hdata: "buffer")
-
buffer_as_string (string)
-
prev_channel (pointer, hdata: "irc_channel")
-
next_channel (pointer, hdata: "irc_channel")
-
-
-
irc_channel_speaking: irc channel_speaking
-
plugin: irc
-
variables:
-
nick (string)
-
time_last_message (time)
-
prev_nick (pointer, hdata: "irc_channel_speaking")
-
next_nick (pointer, hdata: "irc_channel_speaking")
-
-
-
irc_ignore: irc ignore
-
plugin: irc
-
variables:
-
number (integer)
-
mask (string)
-
regex_mask (pointer)
-
server (string)
-
channel (string)
-
prev_ignore (pointer, hdata: "irc_ignore")
-
next_ignore (pointer, hdata: "irc_ignore")
-
-
lists:
-
irc_ignore_list
-
last_irc_ignore
-
-
-
irc_nick: irc nick
-
plugin: irc
-
variables:
-
name (string)
-
host (string)
-
prefixes (string)
-
prefix (string)
-
away (integer)
-
color (string)
-
prev_nick (pointer, hdata: "irc_nick")
-
next_nick (pointer, hdata: "irc_nick")
-
-
-
irc_notify: irc notify
-
plugin: irc
-
variables:
-
server (pointer, hdata: "irc_server")
-
nick (string)
-
check_away (integer)
-
is_on_server (integer)
-
away_message (string)
-
ison_received (integer)
-
prev_notify (pointer, hdata: "irc_notify")
-
next_notify (pointer, hdata: "irc_notify")
-
-
-
irc_redirect: irc redirect
-
plugin: irc
-
variables:
-
server (pointer, hdata: "irc_server")
-
pattern (string)
-
signal (string)
-
count (integer)
-
current_count (integer)
-
string (string)
-
timeout (integer)
-
command (string)
-
assigned_to_command (integer)
-
start_time (time)
-
cmd_start (hashtable)
-
cmd_stop (hashtable)
-
cmd_extra (hashtable)
-
cmd_start_received (integer)
-
cmd_stop_received (integer)
-
cmd_filter (hashtable)
-
output (string)
-
output_size (integer)
-
prev_redirect (pointer, hdata: "irc_redirect")
-
next_redirect (pointer, hdata: "irc_redirect")
-
-
-
irc_redirect_pattern: pattern for irc redirect
-
plugin: irc
-
variables:
-
name (string)
-
temp_pattern (integer)
-
timeout (integer)
-
cmd_start (string)
-
cmd_stop (string)
-
cmd_extra (string)
-
prev_redirect (pointer, hdata: "irc_redirect_pattern")
-
next_redirect (pointer, hdata: "irc_redirect_pattern")
-
-
lists:
-
irc_redirect_patterns
-
last_irc_redirect_pattern
-
-
-
irc_server: irc server
-
plugin: irc
-
variables:
-
name (string)
-
options (pointer)
-
temp_server (integer)
-
reloading_from_config (integer)
-
reloaded_from_config (integer)
-
addresses_count (integer)
-
addresses_array (string, array_size: "addresses_count")
-
ports_array (integer, array_size: "addresses_count")
-
retry_array (integer, array_size: "addresses_count")
-
index_current_address (integer)
-
current_address (string)
-
current_ip (string)
-
current_port (integer)
-
current_retry (integer)
-
sock (integer)
-
hook_connect (pointer, hdata: "hook")
-
hook_fd (pointer, hdata: "hook")
-
hook_timer_connection (pointer, hdata: "hook")
-
hook_timer_sasl (pointer, hdata: "hook")
-
is_connected (integer)
-
ssl_connected (integer)
-
disconnected (integer)
-
gnutls_sess (other)
-
tls_cert (other)
-
tls_cert_key (other)
-
unterminated_message (string)
-
nicks_count (integer)
-
nicks_array (string, array_size: "nicks_count")
-
nick_first_tried (integer)
-
nick_alternate_number (integer)
-
nick (string)
-
nick_modes (string)
-
cap_away_notify (integer)
-
isupport (string)
-
prefix_modes (string)
-
prefix_chars (string)
-
nick_max_length (integer)
-
casemapping (integer)
-
chantypes (string)
-
chanmodes (string)
-
monitor (integer)
-
monitor_time (time)
-
reconnect_delay (integer)
-
reconnect_start (time)
-
command_time (time)
-
reconnect_join (integer)
-
disable_autojoin (integer)
-
is_away (integer)
-
away_message (string)
-
away_time (time)
-
lag (integer)
-
lag_check_time (other)
-
lag_next_check (time)
-
lag_last_refresh (time)
-
cmd_list_regexp (pointer)
-
last_user_message (time)
-
last_away_check (time)
-
last_data_purge (time)
-
outqueue (pointer)
-
last_outqueue (pointer)
-
redirects (pointer, hdata: "irc_redirect")
-
last_redirect (pointer, hdata: "irc_redirect")
-
notify_list (pointer, hdata: "irc_notify")
-
last_notify (pointer, hdata: "irc_notify")
-
notify_count (integer)
-
join_manual (hashtable)
-
join_channel_key (hashtable)
-
join_noswitch (hashtable)
-
buffer (pointer, hdata: "buffer")
-
buffer_as_string (string)
-
channels (pointer, hdata: "irc_channel")
-
last_channel (pointer, hdata: "irc_channel")
-
prev_server (pointer, hdata: "irc_server")
-
next_server (pointer, hdata: "irc_server")
-
-
lists:
-
irc_servers
-
last_irc_server
-
-
-
lua_callback: callback of a script
-
plugin: lua
-
variables:
-
script (pointer, hdata: "lua_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "lua_callback")
-
next_callback (pointer, hdata: "lua_callback")
-
-
-
lua_script: list of scripts
-
plugin: lua
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "lua_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "lua_script")
-
next_script (pointer, hdata: "lua_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
perl_callback: callback of a script
-
plugin: perl
-
variables:
-
script (pointer, hdata: "perl_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "perl_callback")
-
next_callback (pointer, hdata: "perl_callback")
-
-
-
perl_script: list of scripts
-
plugin: perl
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "perl_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "perl_script")
-
next_script (pointer, hdata: "perl_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
python_callback: callback of a script
-
plugin: python
-
variables:
-
script (pointer, hdata: "python_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "python_callback")
-
next_callback (pointer, hdata: "python_callback")
-
-
-
python_script: list of scripts
-
plugin: python
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "python_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "python_script")
-
next_script (pointer, hdata: "python_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
ruby_callback: callback of a script
-
plugin: ruby
-
variables:
-
script (pointer, hdata: "ruby_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "ruby_callback")
-
next_callback (pointer, hdata: "ruby_callback")
-
-
-
ruby_script: list of scripts
-
plugin: ruby
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "ruby_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "ruby_script")
-
next_script (pointer, hdata: "ruby_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
script_script: scripts from repository
-
plugin: script
-
variables:
-
name (string)
-
name_with_extension (string)
-
language (integer)
-
author (string)
-
mail (string)
-
version (string)
-
license (string)
-
description (string)
-
tags (string)
-
requirements (string)
-
min_weechat (string)
-
max_weechat (string)
-
md5sum (string)
-
url (string)
-
popularity (integer)
-
date_added (time)
-
date_updated (time)
-
status (integer)
-
version_loaded (string)
-
displayed (integer)
-
install_order (integer)
-
prev_script (pointer, hdata: "script_script")
-
next_script (pointer, hdata: "script_script")
-
-
lists:
-
last_script_repo
-
scripts_repo
-
-
-
tcl_callback: callback of a script
-
plugin: tcl
-
variables:
-
script (pointer, hdata: "tcl_script")
-
function (string)
-
data (string)
-
config_file (pointer, hdata: "config_file")
-
config_section (pointer, hdata: "config_section")
-
config_option (pointer, hdata: "config_option")
-
hook (pointer)
-
buffer (pointer, hdata: "buffer")
-
bar_item (pointer, hdata: "bar_item")
-
upgrade_file (pointer)
-
prev_callback (pointer, hdata: "tcl_callback")
-
next_callback (pointer, hdata: "tcl_callback")
-
-
-
tcl_script: list of scripts
-
plugin: tcl
-
variables:
-
filename (string)
-
interpreter (pointer)
-
name (string)
-
author (string)
-
version (string)
-
license (string)
-
description (string)
-
shutdown_func (string)
-
charset (string)
-
callbacks (pointer, hdata: "tcl_callback")
-
unloading (integer)
-
prev_script (pointer, hdata: "tcl_script")
-
next_script (pointer, hdata: "tcl_script")
-
-
lists:
-
last_script
-
scripts
-
-
-
bar: bar
-
plugin: weechat
-
variables:
-
name (string)
-
options (pointer)
-
items_count (integer)
-
items_subcount (pointer)
-
items_array (pointer)
-
items_buffer (pointer)
-
items_prefix (pointer)
-
items_name (pointer)
-
items_suffix (pointer)
-
bar_window (pointer, hdata: "bar_window")
-
bar_refresh_needed (integer)
-
prev_bar (pointer, hdata: "bar")
-
next_bar (pointer, hdata: "bar")
-
-
lists:
-
gui_bars
-
last_gui_bar
-
-
-
bar_item: bar item
-
plugin: weechat
-
variables:
-
plugin (pointer, hdata: "plugin")
-
name (string)
-
build_callback (pointer)
-
build_callback_data (pointer)
-
prev_item (pointer, hdata: "bar_item")
-
next_item (pointer, hdata: "bar_item")
-
-
lists:
-
gui_bar_items
-
last_gui_bar_item
-
-
-
bar_window: bar window
-
plugin: weechat
-
variables:
-
bar (pointer, hdata: "bar")
-
x (integer)
-
y (integer)
-
width (integer)
-
height (integer)
-
scroll_x (integer)
-
scroll_y (integer)
-
cursor_x (integer)
-
cursor_y (integer)
-
current_size (integer)
-
items_count (integer)
-
items_subcount (pointer)
-
items_content (pointer)
-
items_num_lines (pointer)
-
items_refresh_needed (pointer)
-
screen_col_size (integer)
-
screen_lines (integer)
-
coords_count (integer)
-
coords (pointer)
-
gui_objects (pointer)
-
prev_bar_window (pointer, hdata: "bar_window")
-
next_bar_window (pointer, hdata: "bar_window")
-
-
-
buffer: buffer
-
plugin: weechat
-
variables:
-
plugin (pointer, hdata: "plugin")
-
plugin_name_for_upgrade (string)
-
number (integer)
-
layout_number (integer)
-
layout_number_merge_order (integer)
-
name (string)
-
full_name (string)
-
short_name (string)
-
type (integer)
-
notify (integer)
-
num_displayed (integer)
-
active (integer)
-
hidden (integer)
-
zoomed (integer)
-
print_hooks_enabled (integer)
-
day_change (integer)
-
clear (integer)
-
filter (integer)
-
close_callback (pointer)
-
close_callback_data (pointer)
-
closing (integer)
-
title (string)
-
own_lines (pointer, hdata: "lines")
-
mixed_lines (pointer, hdata: "lines")
-
lines (pointer, hdata: "lines")
-
time_for_each_line (integer)
-
chat_refresh_needed (integer)
-
nicklist (integer)
-
nicklist_case_sensitive (integer)
-
nicklist_root (pointer, hdata: "nick_group")
-
nicklist_max_length (integer)
-
nicklist_display_groups (integer)
-
nicklist_count (integer)
-
nicklist_groups_count (integer)
-
nicklist_nicks_count (integer)
-
nicklist_visible_count (integer)
-
nickcmp_callback (pointer)
-
nickcmp_callback_data (pointer)
-
input (integer)
-
input_callback (pointer)
-
input_callback_data (pointer)
-
input_get_unknown_commands (integer)
-
input_buffer (string)
-
input_buffer_alloc (integer)
-
input_buffer_size (integer)
-
input_buffer_length (integer)
-
input_buffer_pos (integer)
-
input_buffer_1st_display (integer)
-
input_undo_snap (pointer, hdata: "input_undo")
-
input_undo (pointer, hdata: "input_undo")
-
last_input_undo (pointer, hdata: "input_undo")
-
ptr_input_undo (pointer, hdata: "input_undo")
-
input_undo_count (integer)
-
completion (pointer, hdata: "completion")
-
history (pointer, hdata: "history")
-
last_history (pointer, hdata: "history")
-
ptr_history (pointer, hdata: "history")
-
num_history (integer)
-
text_search (integer)
-
text_search_exact (integer)
-
text_search_regex (integer)
-
text_search_regex_compiled (pointer)
-
text_search_where (integer)
-
text_search_found (integer)
-
text_search_input (string)
-
highlight_words (string)
-
highlight_regex (string)
-
highlight_regex_compiled (pointer)
-
highlight_tags_restrict (string)
-
highlight_tags_restrict_count (integer)
-
highlight_tags_restrict_array (pointer, array_size: "highlight_tags_restrict_count")
-
highlight_tags (string)
-
highlight_tags_count (integer)
-
highlight_tags_array (pointer, array_size: "highlight_tags_count")
-
hotlist_max_level_nicks (hashtable)
-
keys (pointer, hdata: "key")
-
last_key (pointer, hdata: "key")
-
keys_count (integer)
-
local_variables (hashtable)
-
prev_buffer (pointer, hdata: "buffer")
-
next_buffer (pointer, hdata: "buffer")
-
-
lists:
-
gui_buffer_last_displayed
-
gui_buffers
-
last_gui_buffer
-
-
-
buffer_visited: visited buffer
-
plugin: weechat
-
variables:
-
buffer (pointer, hdata: "buffer")
-
prev_buffer (pointer, hdata: "buffer_visited")
-
next_buffer (pointer, hdata: "buffer_visited")
-
-
lists:
-
gui_buffers_visited
-
last_gui_buffer_visited
-
-
-
completion: structure with completion
-
plugin: weechat
-
variables:
-
buffer (pointer, hdata: "buffer")
-
context (integer)
-
base_command (string)
-
base_command_arg_index (integer)
-
base_word (string)
-
base_word_pos (integer)
-
position (integer)
-
args (string)
-
direction (integer)
-
add_space (integer)
-
force_partial_completion (integer)
-
list (pointer)
-
word_found (string)
-
word_found_is_nick (integer)
-
position_replace (integer)
-
diff_size (integer)
-
diff_length (integer)
-
partial_list (pointer)
-
-
-
config_file: config file
-
plugin: weechat
-
variables:
-
plugin (pointer, hdata: "plugin")
-
name (string)
-
filename (string)
-
file (pointer)
-
callback_reload (pointer)
-
callback_reload_data (pointer)
-
sections (pointer, hdata: "config_section")
-
last_section (pointer, hdata: "config_section")
-
prev_config (pointer, hdata: "config_file")
-
next_config (pointer, hdata: "config_file")
-
-
lists:
-
config_files
-
last_config_file
-
-
-
config_option: config option
-
plugin: weechat
-
variables:
-
config_file (pointer, hdata: "config_file")
-
section (pointer, hdata: "config_section")
-
name (string)
-
type (integer)
-
description (string)
-
string_values (string, array_size: "*")
-
min (integer)
-
max (integer)
-
default_value (pointer)
-
value (pointer)
-
null_value_allowed (integer)
-
callback_check_value (pointer)
-
callback_check_value_data (pointer)
-
callback_change (pointer)
-
callback_change_data (pointer)
-
callback_delete (pointer)
-
callback_delete_data (pointer)
-
loaded (integer)
-
prev_option (pointer, hdata: "config_option")
-
next_option (pointer, hdata: "config_option")
-
-
-
config_section: config section
-
plugin: weechat
-
variables:
-
config_file (pointer, hdata: "config_file")
-
name (string)
-
user_can_add_options (integer)
-
user_can_delete_options (integer)
-
callback_read (pointer)
-
callback_read_data (pointer)
-
callback_write (pointer)
-
callback_write_data (pointer)
-
callback_write_default (pointer)
-
callback_write_default_data (pointer)
-
callback_create_option (pointer)
-
callback_create_option_data (pointer)
-
callback_delete_option (pointer)
-
callback_delete_option_data (pointer)
-
options (pointer, hdata: "config_option")
-
last_option (pointer, hdata: "config_option")
-
prev_section (pointer, hdata: "config_section")
-
next_section (pointer, hdata: "config_section")
-
-
-
filter: filter
-
plugin: weechat
-
variables:
-
enabled (integer)
-
name (string)
-
buffer_name (string)
-
num_buffers (integer)
-
buffers (pointer)
-
tags (string)
-
tags_count (integer)
-
tags_array (pointer, array_size: "tags_count")
-
regex (string)
-
regex_prefix (pointer)
-
regex_message (pointer)
-
prev_filter (pointer, hdata: "filter")
-
next_filter (pointer, hdata: "filter")
-
-
lists:
-
gui_filters
-
last_gui_filter
-
-
-
history: history of commands in buffer
-
plugin: weechat
-
variables:
-
text (string)
-
next_history (pointer, hdata: "history")
-
prev_history (pointer, hdata: "history")
-
-
update allowed:
-
__create
-
__delete
-
-
lists:
-
gui_history
-
last_gui_history
-
-
-
hotlist: hotlist
-
plugin: weechat
-
variables:
-
priority (integer)
-
creation_time.tv_sec (time)
-
creation_time.tv_usec (long)
-
buffer (pointer)
-
count (integer, array_size: "4")
-
prev_hotlist (pointer, hdata: "hotlist")
-
next_hotlist (pointer, hdata: "hotlist")
-
-
lists:
-
gui_hotlist
-
last_gui_hotlist
-
-
-
input_undo: structure with undo for input line
-
plugin: weechat
-
variables:
-
data (string)
-
pos (integer)
-
prev_undo (pointer, hdata: "input_undo")
-
next_undo (pointer, hdata: "input_undo")
-
-
-
key: a key (keyboard shortcut)
-
plugin: weechat
-
variables:
-
key (string)
-
area_type (pointer)
-
area_name (pointer)
-
area_key (string)
-
command (string)
-
score (integer)
-
prev_key (pointer, hdata: "key")
-
next_key (pointer, hdata: "key")
-
-
lists:
-
gui_default_keys
-
gui_default_keys_cursor
-
gui_default_keys_mouse
-
gui_default_keys_search
-
gui_keys
-
gui_keys_cursor
-
gui_keys_mouse
-
gui_keys_search
-
last_gui_default_key
-
last_gui_default_key_cursor
-
last_gui_default_key_mouse
-
last_gui_default_key_search
-
last_gui_key
-
last_gui_key_cursor
-
last_gui_key_mouse
-
last_gui_key_search
-
-
-
layout: layout
-
plugin: weechat
-
variables:
-
name (string)
-
layout_buffers (pointer, hdata: "layout_buffer")
-
last_layout_buffer (pointer, hdata: "layout_buffer")
-
layout_windows (pointer, hdata: "layout_window")
-
internal_id (integer)
-
internal_id_current_window (integer)
-
prev_layout (pointer, hdata: "layout")
-
next_layout (pointer, hdata: "layout")
-
-
lists:
-
gui_layout_current
-
gui_layouts
-
last_gui_layout
-
-
-
layout_buffer: buffer layout
-
plugin: weechat
-
variables:
-
plugin_name (string)
-
buffer_name (string)
-
number (integer)
-
prev_layout (pointer, hdata: "layout_buffer")
-
next_layout (pointer, hdata: "layout_buffer")
-
-
-
layout_window: window layout
-
plugin: weechat
-
variables:
-
internal_id (integer)
-
parent_node (pointer, hdata: "layout_window")
-
split_pct (integer)
-
split_horiz (integer)
-
child1 (pointer, hdata: "layout_window")
-
child2 (pointer, hdata: "layout_window")
-
plugin_name (string)
-
buffer_name (string)
-
-
-
line: structure with one line
-
plugin: weechat
-
variables:
-
data (pointer, hdata: "line_data")
-
prev_line (pointer, hdata: "line")
-
next_line (pointer, hdata: "line")
-
-
-
line_data: structure with one line data
-
plugin: weechat
-
variables:
-
buffer (pointer, hdata: "buffer")
-
y (integer)
-
date (time)
-
date_printed (time)
-
str_time (string)
-
tags_count (integer)
-
tags_array (shared_string, array_size: "tags_count")
-
displayed (char)
-
highlight (char)
-
refresh_needed (char)
-
prefix (shared_string)
-
prefix_length (integer)
-
message (string)
-
-
update allowed:
-
date (time)
-
date_printed (time)
-
tags_array (shared_string)
-
prefix (shared_string)
-
message (string)
-
-
-
lines: structure with lines
-
plugin: weechat
-
variables:
-
first_line (pointer, hdata: "line")
-
last_line (pointer, hdata: "line")
-
last_read_line (pointer, hdata: "line")
-
lines_count (integer)
-
first_line_not_read (integer)
-
lines_hidden (integer)
-
buffer_max_length (integer)
-
buffer_max_length_refresh (integer)
-
prefix_max_length (integer)
-
prefix_max_length_refresh (integer)
-
-
-
nick: nick in nicklist
-
plugin: weechat
-
variables:
-
group (pointer, hdata: "nick_group")
-
name (shared_string)
-
color (shared_string)
-
prefix (shared_string)
-
prefix_color (shared_string)
-
visible (integer)
-
prev_nick (pointer, hdata: "nick")
-
next_nick (pointer, hdata: "nick")
-
-
-
nick_group: group in nicklist
-
plugin: weechat
-
variables:
-
name (shared_string)
-
color (shared_string)
-
visible (integer)
-
level (integer)
-
parent (pointer, hdata: "nick_group")
-
children (pointer, hdata: "nick_group")
-
last_child (pointer, hdata: "nick_group")
-
nicks (pointer, hdata: "nick")
-
last_nick (pointer, hdata: "nick")
-
prev_group (pointer, hdata: "nick_group")
-
next_group (pointer, hdata: "nick_group")
-
-
-
plugin: plugin
-
plugin: weechat
-
variables:
-
filename (string)
-
handle (pointer)
-
name (string)
-
description (string)
-
author (string)
-
version (string)
-
license (string)
-
charset (string)
-
debug (integer)
-
prev_plugin (pointer, hdata: "plugin")
-
next_plugin (pointer, hdata: "plugin")
-
-
lists:
-
last_weechat_plugin
-
weechat_plugins
-
-
-
proxy: proxy
-
plugin: weechat
-
variables:
-
name (string)
-
options (pointer)
-
prev_proxy (pointer, hdata: "proxy")
-
next_proxy (pointer, hdata: "proxy")
-
-
lists:
-
last_weechat_proxy
-
weechat_proxies
-
-
-
window: window
-
plugin: weechat
-
variables:
-
number (integer)
-
win_x (integer)
-
win_y (integer)
-
win_width (integer)
-
win_height (integer)
-
win_width_pct (integer)
-
win_height_pct (integer)
-
win_chat_x (integer)
-
win_chat_y (integer)
-
win_chat_width (integer)
-
win_chat_height (integer)
-
win_chat_cursor_x (integer)
-
win_chat_cursor_y (integer)
-
bar_windows (pointer, hdata: "bar_window")
-
last_bar_window (pointer, hdata: "bar_window")
-
refresh_needed (integer)
-
gui_objects (pointer)
-
buffer (pointer, hdata: "buffer")
-
layout_plugin_name (string)
-
layout_buffer_name (string)
-
scroll (pointer, hdata: "window_scroll")
-
ptr_tree (pointer, hdata: "window_tree")
-
prev_window (pointer, hdata: "window")
-
next_window (pointer, hdata: "window")
-
-
lists:
-
gui_current_window
-
gui_windows
-
last_gui_window
-
-
-
window_scroll: scroll info in window
-
plugin: weechat
-
variables:
-
buffer (pointer, hdata: "buffer")
-
first_line_displayed (integer)
-
start_line (pointer, hdata: "line")
-
start_line_pos (integer)
-
scrolling (integer)
-
start_col (integer)
-
lines_after (integer)
-
prev_scroll (pointer, hdata: "window_scroll")
-
next_scroll (pointer, hdata: "window_scroll")
-
-
-
window_tree: tree of windows
-
plugin: weechat
-
variables:
-
parent_node (pointer, hdata: "window_tree")
-
split_pct (integer)
-
split_horizontal (integer)
-
child1 (pointer, hdata: "window_tree")
-
child2 (pointer, hdata: "window_tree")
-
window (pointer, hdata: "window")
-
-
lists:
-
gui_windows_tree
-
-
C example:
Script (Python):
3.20.5. weechat_hdata_get_var_offset
WeeChat ≥ 0.3.6.
Return offset of variable in hdata.
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: variable name
Return value:
-
variable offset, 0 if an error occurred
C example:
Script (Python):
3.20.6. weechat_hdata_get_var_type
WeeChat ≥ 0.3.6.
Return type of variable in hdata (as integer).
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: variable name
Return value:
-
variable type, -1 if an error occurred
C example:
Note
|
This function is not available in scripting API. |
3.20.7. weechat_hdata_get_var_type_string
WeeChat ≥ 0.3.6.
Return type of variable in hdata (as string).
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: variable name
Return value:
-
variable type, NULL if an error occurred
C example:
Script (Python):
3.20.8. weechat_hdata_get_var_array_size
WeeChat ≥ 0.3.9.
Return array size for variable in hdata.
Prototype:
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:
Script (Python):
3.20.9. weechat_hdata_get_var_array_size_string
WeeChat ≥ 0.3.9.
Return array size for variable in hdata (as string).
Prototype:
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:
Script (Python):
3.20.10. weechat_hdata_get_var_hdata
WeeChat ≥ 0.3.6.
Return hdata for a variable in hdata.
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: variable name
Return value:
-
hdata for variable, NULL if no hdata or if an error occurred
C example:
Script (Python):
3.20.11. weechat_hdata_get_var
WeeChat ≥ 0.3.6.
Return pointer to content of variable in hdata.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.20.12. weechat_hdata_get_var_at_offset
WeeChat ≥ 0.3.6.
Return pointer to content of variable in hdata, using offset.
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.20.13. weechat_hdata_get_list
WeeChat ≥ 0.3.6.
Return list pointer from hdata.
Prototype:
Arguments:
-
hdata: hdata pointer
-
name: list name
Return value:
-
list pointer, NULL if an error occurred
C example:
Script (Python):
3.20.14. weechat_hdata_check_pointer
WeeChat ≥ 0.3.7, updated in 1.0.
Check if a pointer is valid for a hdata and a list pointer.
Prototype:
Arguments:
-
hdata: hdata pointer
-
list: list pointer; if NULL (WeeChat ≥ 1.0), the pointer is checked with the lists in hdata that have flag "check pointers" (see weechat_hdata_new_list), 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:
Script (Python):
3.20.15. weechat_hdata_move
WeeChat ≥ 0.3.6.
Move pointer to another element in list.
Prototype:
Arguments:
-
hdata: hdata pointer
-
pointer: pointer to a WeeChat/plugin object
-
count: number of jump(s) to execute (negative or positive integer, different from 0)
Return value:
-
pointer to element reached, NULL if an error occurred
C example:
Script (Python):
3.20.16. weechat_hdata_search
WeeChat ≥ 0.4.1.
Search element in a list: the expression search is evaluated for each element in list, until element is found (or end of list).
Prototype:
Arguments:
-
hdata: hdata pointer
-
pointer: pointer to a WeeChat/plugin object
-
search: expression to evaluate, default pointer in expression is the name of hdata (and this pointer changes for each element in list); for help on expression, see command
/eval
in WeeChat User’s guide -
move: number of jump(s) to execute after unsuccessful search (negative or positive integer, different from 0)
Return value:
-
pointer to element found, NULL if not found
C example:
Script (Python):
3.20.17. weechat_hdata_char
WeeChat ≥ 0.3.7.
Return value of char variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.18. weechat_hdata_integer
WeeChat ≥ 0.3.6.
Return value of integer variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.19. weechat_hdata_long
WeeChat ≥ 0.3.6.
Return value of long variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.20. weechat_hdata_string
WeeChat ≥ 0.3.6.
Return value of string variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.21. weechat_hdata_pointer
WeeChat ≥ 0.3.6.
Return value of pointer variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.22. weechat_hdata_time
WeeChat ≥ 0.3.6.
Return value of time variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.23. weechat_hdata_hashtable
WeeChat ≥ 0.3.7.
Return value of hashtable variable in structure using hdata.
Prototype:
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:
Script (Python):
3.20.24. weechat_hdata_set
WeeChat ≥ 0.3.9.
Set new value for variable in a hdata.
Note
|
This function can be called only in an update callback (see weechat_hdata_new and weechat_hdata_update), if the variable can be updated. |
Prototype:
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:
Note
|
This function is not available in scripting API. |
3.20.25. weechat_hdata_update
WeeChat ≥ 0.3.9.
Update data in a hdata.
Prototype:
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:
Script (Python):
3.20.26. weechat_hdata_get_string
WeeChat ≥ 0.3.6.
Return string value of a hdata property.
Prototype:
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:
Script (Python):
3.21. Upgrade
Functions for upgrading WeeChat (command "/upgrade").
3.21.1. weechat_upgrade_new
Create or read a file for upgrade.
Prototype:
Arguments:
-
filename: name of file (extension ".upgrade" will be added to this name by WeeChat)
-
write:
-
1: create file (write mode, before upgrade)
-
0: read file (after upgrade)
-
Return value:
-
pointer to upgrade file
C example:
Script (Python):
3.21.2. weechat_upgrade_write_object
Write an object in upgrade file.
Prototype:
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:
Script (Python):
3.21.3. weechat_upgrade_read
Read an upgrade file.
Prototype:
Arguments:
-
upgrade_file: upgrade file pointer
-
callback_read: function called for each object read in upgrade file, arguments and return value:
-
void *data: pointer
-
struct t_upgrade_file *upgrade_file: pointer to upgrade file
-
int object_id: object id
-
struct t_infolist *infolist: infolist with content of object
-
return value:
-
WEECHAT_RC_OK
-
WEECHAT_RC_ERROR
-
-
-
callback_read_data: pointer given to read callback when it is called by WeeChat
Return value:
-
1 if OK, 0 if error
C example:
Script (Python):
3.21.4. weechat_upgrade_close
Close an upgrade file.
Prototype:
Arguments:
-
upgrade_file: upgrade file pointer
C example:
Script (Python):