weechat/doc/en/weechat_plugin_api.en.txt

WeeChat Plugin API Reference
============================
Sébastien Helleu <flashcode@flashtux.org>


This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page:
http://www.weechat.org/doc


[[introduction]]
Introduction
------------

WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and
light, designed for many operating systems.

This manual documents WeeChat plugins API, used by C plugins to interact with
WeeChat core.

[[plugins_in_weechat]]
Plugins in WeeChat
------------------

A plugin is a C program which can call WeeChat functions defined in an
interface.

This C program does not need WeeChat sources to compile and can be dynamically
loaded into WeeChat with command `/plugin`.

The plugin has to be a dynamic library, for dynamic loading by operating
system.
Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.

The plugin has to include "weechat-plugin.h" file (available in WeeChat source
code).
This file defines structures and types used to communicate with WeeChat.

[[macros]]
Macros
~~~~~~

The plugin must use some macros (to define some variables):

WEECHAT_PLUGIN_NAME("name")::
    plugin name

WEECHAT_PLUGIN_DESCRIPTION("description")::
    short description of plugin

WEECHAT_PLUGIN_VERSION("1.0")::
    plugin version

WEECHAT_PLUGIN_LICENSE("GPL3")::
    plugin license

[[main_functions]]
Main functions
~~~~~~~~~~~~~~

The plugin must use two functions:

* weechat_plugin_init
* weechat_plugin_end

weechat_plugin_init
^^^^^^^^^^^^^^^^^^^

This function is called when plugin is loaded by WeeChat.

Prototype:

[source,C]
----------------------------------------
int weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[]);
----------------------------------------

Arguments:

* 'plugin': pointer to WeeChat plugin structure
* 'argc': number of arguments for plugin (given on command line by user)
* 'argv': arguments for plugin

Return value:

* 'WEECHAT_RC_OK' if successful (plugin will be loaded)
* 'WEECHAT_RC_ERROR' if error (plugin will NOT be loaded)

weechat_plugin_end
^^^^^^^^^^^^^^^^^^

This function is called when plugin is unloaded by WeeChat.

Prototype:

[source,C]
----------------------------------------
int weechat_plugin_end (struct t_weechat_plugin *plugin);
----------------------------------------

Arguments:

* 'plugin': pointer to WeeChat plugin structure

Return value:

* 'WEECHAT_RC_OK' if successful
* 'WEECHAT_RC_ERROR' if error

[[compile_plugin]]
Compile plugin
~~~~~~~~~~~~~~

Compile does not need WeeChat sources, only file 'weechat-plugin.h' is
required.

To compile a plugin which has one file "toto.c" (under GNU/Linux):

----------------------------------------
$ gcc -fPIC -Wall -c toto.c
$ gcc -shared -fPIC -o libtoto.so toto.o
----------------------------------------

[[load_plugin]]
Load plugin
~~~~~~~~~~~

Copy file 'libtoto.so' into system plugins directory (for example
'/usr/local/lib/weechat/plugins') or into user's plugins directory (for example
'/home/xxx/.weechat/plugins').

Under WeeChat:

----------------------------------------
/plugin load toto
----------------------------------------

[[plugin_example]]
Plugin example
~~~~~~~~~~~~~~

Full example of plugin, which adds a command '/double': displays two times
arguments on current buffer, or execute two times a command (ok that's not
very useful, but that's just an example!):

[source,C]
----------------------------------------
#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
WEECHAT_PLUGIN_AUTHOR("Sebastien Helleu <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


/* callback for command "/double" */

int
command_double_cb (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* make C compiler happy */
    (void) data;
    (void) buffer;
    (void) argv;
    
    if (argc > 1)
    {
        weechat_command (NULL, argv_eol[1]);
        weechat_command (NULL, argv_eol[1]);
    }
    
    return WEECHAT_RC_OK;
}

int
weechat_plugin_init (struct t_weechat_plugin *plugin,
                     int argc, char *argv[])
{
    weechat_plugin = plugin;
    
    weechat_hook_command ("double",
                          "Display two times a message "
                          "or execute two times a command",
                          "message | command",
                          "message: message to display two times\n"
                          "command: command to execute two times",
                          NULL,
                          &command_double_cb, NULL);
    
    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* make C compiler happy */
    (void) plugin;
    
    return WEECHAT_RC_OK;
}
----------------------------------------

[[plugin_api]]
Plugin API
----------

Following chapters describe functions in API, sorted by category.

For each function, we give:

* description of function,
* C prototype,
* detail of arguments,
* return value,
* C example,
* example in Python script (syntax for other scripting languages is similar).

[[plugins]]
Plugins
~~~~~~~

Functions to get infos about plugins.

weechat_plugin_get_name
^^^^^^^^^^^^^^^^^^^^^^^

Get plugin name.

Prototype:

[source,C]
----------------------------------------
const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);
----------------------------------------

Arguments:

* 'plugin': pointer to WeeChat plugin structure (can be NULL)

Return value:

* name of plugin, "core" for WeeChat core (if plugin pointer is NULL)

C example:

[source,C]
----------------------------------------
const char *name = weechat_plugin_get_name (plugin);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
name = weechat.plugin_get_name(plugin)

# example
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
name = weechat.plugin_get_name(plugin)
----------------------------------------

[[strings]]
Strings
~~~~~~~

Many string functions below are already available thru standard C functions,
but it's recommended to use functions in this API because they are ok with
UTF-8 and locale.

weechat_charset_set
^^^^^^^^^^^^^^^^^^^

Set new plugin charset (default charset is 'UTF-8', so if your plugin uses
'UTF-8', you don't need to call this function).

Prototype:

[source,C]
----------------------------------------
void weechat_charset_set (const char *charset);
----------------------------------------

Arguments:

* 'charset': new charset to use

C example:

[source,C]
----------------------------------------
weechat_charset_set (plugin, "iso-8859-1");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.charset_set(charset)

# example
weechat.charset_set("iso-8859-1")
----------------------------------------

weechat_iconv_to_internal
^^^^^^^^^^^^^^^^^^^^^^^^^

Convert string to WeeChat internal charset (UTF-8).

Prototype:

[source,C]
----------------------------------------
char *weechat_iconv_to_internal (const char *charset, const char *string);
----------------------------------------

Arguments:

* 'charset': charset to convert
* 'string': string to convert

Return value:

* converted string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.iconv_to_internal(charset, string)

# example
str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")
----------------------------------------

weechat_iconv_from_internal
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Convert string from internal WeeChat charset (UTF-8) to another.

Prototype:

[source,C]
----------------------------------------
char *weechat_iconv_from_internal (const char *charset, const char *string);
----------------------------------------

Arguments:

* 'charset': target charset
* 'string': string to convert

Return value:

* converted string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.iconv_from_internal(charset, string)

# example
str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")
----------------------------------------

weechat_gettext
^^^^^^^^^^^^^^^

Return translated string (depends on local language).

Prototype:

[source,C]
----------------------------------------
const char *weechat_gettext (const char *string);
----------------------------------------

Arguments:

* 'string': string to translate

Return value:

* translated string

C example:

[source,C]
----------------------------------------
char *str = weechat_gettext ("hello");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.gettext(string)

# example
str = weechat.gettext("hello")
----------------------------------------

weechat_ngettext
^^^^^^^^^^^^^^^^

Return translated string, using single or plural form, according to 'count'
argument.

Prototype:

[source,C]
----------------------------------------
const char *weechat_ngettext (const char *string, const char *plural,
                              int count);
----------------------------------------

Arguments:

* 'string': string to translate, single form
* 'plural': string to translate, plural form
* 'count': used to choose between single and plural form (choice is made
  according to local language)

Return value:

* translated string

C example:

[source,C]
----------------------------------------
char *str = weechat_ngettext ("file", "files", num_files);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.ngettext(string, plural, count)

# example
num_files = 2
str = weechat.ngettext("file", "files", num_files)
----------------------------------------

weechat_strndup
^^^^^^^^^^^^^^^

Return duplicated string, with 'length' chars max.

Prototype:

[source,C]
----------------------------------------
char *weechat_strndup (const char *string, int length);
----------------------------------------

Arguments:

* 'string': string to duplicate
* 'length': max chars to duplicate

Return value:

* duplicated string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_tolower
^^^^^^^^^^^^^^^^^^^^^^

Convert UTF-8 string to lower case.

Prototype:

[source,C]
----------------------------------------
void weechat_string_tolower (const char *string);
----------------------------------------

Arguments:

* 'string': string to convert

C example:

[source,C]
----------------------------------------
char *str = "AbCdé";
weechat_string_tolower (str); /* str is now: "abcdé" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_toupper
^^^^^^^^^^^^^^^^^^^^^^

Convert UTF-8 string to upper case.

Prototype:

[source,C]
----------------------------------------
void weechat_string_toupper (const char *string);
----------------------------------------

Arguments:

* 'string': string to convert

C example:

[source,C]
----------------------------------------
char *str = "AbCdé";
weechat_string_tolower (str); /* str is now: "ABCDé" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_strcasecmp
^^^^^^^^^^^^^^^^^^

Locale and case independent string comparison.

Prototype:

[source,C]
----------------------------------------
int weechat_strcasecmp (const char *string1, const char *string2);
----------------------------------------

Arguments:

* 'string1': first string for comparison
* 'string2': second string for comparison

Return value:

* difference between two strings:
** negative if string1 < string2
** zero if string1 == string2
** positive if string1 > string2

C example:

[source,C]
----------------------------------------
int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_strncasecmp
^^^^^^^^^^^^^^^^^^^

Locale and case independent string comparison, for 'max' chars.

Prototype:

[source,C]
----------------------------------------
int weechat_strncasecmp (const char *string1, const char *string2, int max);
----------------------------------------

Arguments:

* 'string1': first string for comparison
* 'string2': second string for comparison
* 'max': max chars to compare

Return value:

* difference between two strings:
** negative if string1 < string2
** zero if string1 == string2
** positive if string1 > string2

C example:

[source,C]
----------------------------------------
int diff = weechat_strncasecmp ("aabb", "aacc", 2); /* == 0 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_strcmp_ignore_chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Locale (and optionally case independent) string comparison, ignoring some
chars.

Prototype:

[source,C]
----------------------------------------
int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);
----------------------------------------

Arguments:

* 'string1': first string for comparison
* 'string2': second string for comparison
* 'chars_ignored': string with chars to ignored
* 'case_sensitive': 1 for case sensitive comparison, otherwise 0

Return value:

* difference between two strings:
** negative if string1 < string2
** zero if string1 == string2
** positive if string1 > string2

C example:

[source,C]
----------------------------------------
int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_strcasestr
^^^^^^^^^^^^^^^^^^

Locale and case independent string search.

Prototype:

[source,C]
----------------------------------------
char *weechat_strcasestr (const char *string, const char *search);
----------------------------------------

Arguments:

* 'string': string
* 'search': string to search in 'string'

Return value:

* pointer to string found, or NULL if not found

C example:

[source,C]
----------------------------------------
char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_match
^^^^^^^^^^^^^^^^^^^^

Check if a string matches a mask.

Prototype:

[source,C]
----------------------------------------
int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);
----------------------------------------

Arguments:

* 'string': string
* 'mask': mask, can begin or end with "`*`" (no other "`*`" are allowed inside
  mask)

Return value:

* 1 if string matches mask, otherwise 0

C example:

[source,C]
----------------------------------------
int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */
int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */
int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */
int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
match = weechat.string_match(string, mask, case_sensitive)

# examples
match1 = weechat.string_match("abcdef", "abc*", 0) # 1
match2 = weechat.string_match("abcdef", "*dd*", 0) # 0
match3 = weechat.string_match("abcdef", "*def", 0) # 1
match4 = weechat.string_match("abcdef", "*de*", 0) # 1
----------------------------------------

weechat_string_replace
^^^^^^^^^^^^^^^^^^^^^^

Replace all occurrences of a string by another string.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);
----------------------------------------

Arguments:

* 'string': string
* 'search': string to replace
* 'replace': replacement for string 'search'

Return value:

* string with 'search' replaced by 'replace' (must be freed by calling "free"
  after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_expand_home
^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Replace leading `~` by string with home directory. If string does not start
with `~`, then same string is returned.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_expand_home (const char *path);
----------------------------------------

Arguments:

* 'path': path

Return value:

* path with leading `~` replaced by home directory (must be freed by calling
  "free" after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/xxx/file.txt" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_remove_quotes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove quotes at beginning and end of string (ignore spaces if there are before
first quote or after last quote).

Prototype:

[source,C]
----------------------------------------
char *weechat_string_remove_quotes (const char *string, const char *quotes);
----------------------------------------

Arguments:

* 'string': string
* 'quotes': string with list of quotes

Return value:

* string without quotes at beginning/end (must be freed by calling "free"
  after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'");
/* result: "I can't" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_strip
^^^^^^^^^^^^^^^^^^^^

Strip chars at beginning and/or end of string.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);
----------------------------------------

Arguments:

* 'string': string
* 'left': strip left chars if different from 0
* 'right': strip right chars if different from 0
* 'chars': string with chars to strip

Return value:

* stripped string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* result: ".abc" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_has_highlight
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check if a string has one or more highlights, using list of highlight words.

Prototype:

[source,C]
----------------------------------------
int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);
----------------------------------------

Arguments:

* 'string': string
* 'highlight_words': list of highlight words, separated by comma

Return value:

* 1 if string has one or more highlights, otherwise 0

C example:

[source,C]
----------------------------------------
int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
highlight = weechat.string_has_highlight(string, highlight_words)

# example
highlight = weechat.string_has_highlight("my test string", "test,word2") # 1
----------------------------------------

weechat_string_has_highlight_regex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Check if a string has one or more highlights, using a regular expression.
For at least one match of regular expression on string, it must be surrounded
by word chars (alphanumeric character, "-", "_" or "|").

Prototype:

[source,C]
----------------------------------------
int weechat_string_has_highlight_regex (const char *string, const char *regex);
----------------------------------------

Arguments:

* 'string': string
* 'regex': regular expression

Return value:

* 1 if string has one or more highlights, otherwise 0

C example:

[source,C]
----------------------------------------
int hl = weechat_string_has_highlight_regex ("my test string", "test|word2"); /* == 1 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
highlight = weechat.string_has_highlight_regex(string, regex)

# example
highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1
----------------------------------------

weechat_string_mask_to_regex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return a regex, built with a mask, where only special char is "`*`". All other
special chars for regex are escaped.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_mask_to_regex (const char *mask);
----------------------------------------

Arguments:

* 'mask': mask

Return value:

* regular expression, as string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
regex = weechat.string_mask_to_regex(mask)

# example
regex = weechat.string_mask_to_regex("test*mask") # "test.*mask"
----------------------------------------

weechat_string_split
^^^^^^^^^^^^^^^^^^^^

Split a string according to one or more delimiter(s).

Prototype:

[source,C]
----------------------------------------
char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);
----------------------------------------

Arguments:

* 'string': string to split
* 'separators': delimiters used for split
* 'keep_eol': if different from 0, then each argument will contain all string
  until end of line (see example below)
* 'num_items_max': maximum number of items created (0 = no limit)
* 'num_items': pointer to int which will contain number of items created

Return value:

* array of strings, NULL if problem (must be freed by calling
  <<_weechat_string_free_split,weechat_string_free_split>> after use)

C examples:

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("abc de  fghi", " ", 0, 0, &argc);
/* result: argv[0] == "abc"
           argv[1] == "de"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi", " ", 1, 0, &argc);
/* result: argv[0] == "abc de  fghi"
           argv[1] == "de  fghi"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_free_split
^^^^^^^^^^^^^^^^^^^^^^^^^

Free memory used by a split string.

Prototype:

[source,C]
----------------------------------------
void weechat_string_free_split (char **split_string);
----------------------------------------

Arguments:

* 'split_string': string split by function
  <<_weechat_string_split,weechat_string_split>>

C example:

[source,C]
----------------------------------------
char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_build_with_split_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Build a string with a split string.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);
----------------------------------------

Arguments:

* 'split_string': string split by function
  <<_weechat_string_split,weechat_string_split>>
* 'separator': string used to separate strings

Return value:

* string built with split string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (argv, ";");
/* str == "abc;def;ghi" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_split_command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Split a list of commands separated by 'separator' (which can be escaped by "\"
in string).

Prototype:

[source,C]
----------------------------------------
char **weechat_string_split_command (const char *command, char separator);
----------------------------------------

Arguments:

* 'command': command to split
* 'separator': separator

Return value:

* array of strings, NULL if problem (must be freed by calling
  <<_weechat_free_split_command,weechat_free_split_command>> after use)

C example:

[source,C]
----------------------------------------
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
*/
weechat_free_split_command (argv);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_free_split_command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free memory used by a split command.

Prototype:

[source,C]
----------------------------------------
void weechat_string_free_split_command (char **split_command);
----------------------------------------

Arguments:

* 'split_command': command split by
  <<_weechat_string_split_command,weechat_string_split_command>>

C example:

[source,C]
----------------------------------------
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_format_size
^^^^^^^^^^^^^^^^^^^^^^^^^^

Build a string with formatted file size and a unit translated to local
language.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_format_size (unsigned long long size);
----------------------------------------

Arguments:

* 'size': size (in bytes)

Return value:

* formatted string (must be freed by calling "free" after use)

C examples:

[source,C]
----------------------------------------
/* examples with english locale */

char *str = weechat_string_format_size (0); /* str == "0 byte" */
/* ... */
free (str);

char *str = weechat_string_format_size (200); /* str == "200 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (1536); /* str == "1.5 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152); /* str == "2 MB" */
/* ... */
free (str);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_remove_color
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove WeeChat colors from a string.

Prototype:

[source,C]
----------------------------------------
char *weechat_string_remove_color (const char *string,
                                   const char *replacement);
----------------------------------------

Arguments:

* 'string': string
* 'replacement': if not NULL and not empty, WeeChat color codes are replaced by
  first char of this string, otherwise WeeChat color codes and following chars
  (if related to color) are removed from string

Return value:

* string without color (must be freed by calling "free" after use)

C examples:

[source,C]
----------------------------------------
/* remove color codes */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* replace color codes by "?" */
char *str = weechat_string_remove_color (my_string2, "?");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.string_remove_color(string, replacement)

# example
str = weechat.string_remove_color(my_string, "?")
----------------------------------------

weechat_string_encode_base64
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.2._

Encode a string in base64.

Prototype:

[source,C]
----------------------------------------
void weechat_string_encode_base64 (const char *from, int length, char *to);
----------------------------------------

Arguments:

* 'from': string to encode
* 'length': length of string to encode (for example `strlen(from)`)
* 'to': pointer to string to store result (must be long enough, result is
  longer than initial string)

C example:

[source,C]
----------------------------------------
char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_decode_base64
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.2._

Decode a base64 string.

Prototype:

[source,C]
----------------------------------------
int weechat_string_decode_base64 (const char *from, char *to);
----------------------------------------

Arguments:

* 'from': string to decode
* 'to': pointer to string to store result (must be long enough, result is
  shorter than initial string)

Return value:

* length of string stored in *to (does not count final '\0')

C example:

[source,C]
----------------------------------------
char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_string_is_command_char
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.2._

Check if first char of string is a command char (default command char is '/').

Prototype:

[source,C]
----------------------------------------
int weechat_string_is_command_char (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* 1 if first char of string is a command char, otherwise 0

C examples:

[source,C]
----------------------------------------
int command_char1 = weechat_string_is_command_char ("/test"); /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");  /* == 0 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
is_cmdchar = weechat.string_is_command_char(string)

# examples
command_char1 = weechat.string_is_command_char("/test") # == 1
command_char2 = weechat.string_is_command_char("test")  # == 0
----------------------------------------

weechat_string_input_for_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.2._

Return pointer to input text for buffer (pointer inside "string" argument), or
NULL if it's a command.

Prototype:

[source,C]
----------------------------------------
const char *weechat_string_input_for_buffer (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* pointer into "string", or NULL

C examples:

[source,C]
----------------------------------------
const char *str1 = weechat_string_input_for_buffer ("test");   /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");  /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test"); /* "/test" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.string_input_for_buffer(string)

# examples
str1 = weechat.string_input_for_buffer("test")   # "test"
str2 = weechat.string_input_for_buffer("/test")  # ""
str3 = weechat.string_input_for_buffer("//test") # "/test"
----------------------------------------

[[utf-8]]
UTF-8
~~~~~

Some UTF-8 string functions.

weechat_utf8_has_8bits
^^^^^^^^^^^^^^^^^^^^^^

Check if a string has 8-bits chars.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_has_8bits (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* 1 if string has 8-bits chars, 0 if only 7-bits chars

C example:

[source,C]
----------------------------------------
if (weechat_utf8_has_8bits (string))
{
    /* ... */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_is_valid
^^^^^^^^^^^^^^^^^^^^^

Check if a string is UTF-8 valid.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_is_valid (const char *string, char **error);
----------------------------------------

Arguments:

* 'string': string
* 'error': if not NULL, '*error*' is set with pointer to first non valid UTF-8
  char in string, if any

Return value:

* 1 if UTF-8 string is valid, otherwise 0

C example:

[source,C]
----------------------------------------
char *error;
if (weechat_utf8_is_valid (string, &error))
{
    /* ... */
}
else
{
    /* "error" points to first invalid char */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_normalize
^^^^^^^^^^^^^^^^^^^^^^

Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char.

Prototype:

[source,C]
----------------------------------------
void weechat_utf8_normalize (const char *string, char replacement);
----------------------------------------

Arguments:

* 'string': string
* 'replacement': replacement char for invalid chars

C example:

[source,C]
----------------------------------------
weechat_utf8_normalize (string, '?');
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_prev_char
^^^^^^^^^^^^^^^^^^^^^^

Return pointer to previous UTF-8 char in a string.

Prototype:

[source,C]
----------------------------------------
char *weechat_utf8_prev_char (const char *string_start, const char *string);
----------------------------------------

Arguments:

* 'string_start': start of string (function will not return a char before this
  pointer)
* 'string': pointer to string (must be > = 'string_start')

Return value:

* pointer to previous UTF-8 char, NULL if not found (start of string reached)

C example:

[source,C]
----------------------------------------
char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_next_char
^^^^^^^^^^^^^^^^^^^^^^

Return pointer to next UTF-8 char in a string.

Prototype:

[source,C]
----------------------------------------
char *weechat_utf8_next_char (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* pointer to next UTF-8 char, NULL if not found (end of string reached)

C example:

[source,C]
----------------------------------------
char *next_char = weechat_utf8_next_char (string);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_char_int
^^^^^^^^^^^^^^^^^^^^^

Return UTF-8 char as integer.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_char_int (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* UTF-8 char as integer

C example:

[source,C]
----------------------------------------
int char_int = weechat_utf8_char_int ("être"); /* "ê" as integer */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_char_size
^^^^^^^^^^^^^^^^^^^^^^

Return UTF-8 char size (in bytes).

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_char_size (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* UTF-8 char size (in bytes)

C example:

[source,C]
----------------------------------------
int char_size = weechat_utf8_char_size ("être"); /* == 2 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_strlen
^^^^^^^^^^^^^^^^^^^

Return UTF-8 string length (in UTF-8 chars).

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_strlen (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* UTF-8 string length (number of UTF-8 chars)

C example:

[source,C]
----------------------------------------
int length = weechat_utf8_strlen ("chêne"); /* == 5 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_strnlen
^^^^^^^^^^^^^^^^^^^^

Return UTF-8 string length (in UTF-8 chars), for max 'bytes' in string.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_strnlen (const char *string, int bytes);
----------------------------------------

Arguments:

* 'string': string
* 'bytes': max bytes

Return value:

* UTF-8 string length (number of UTF-8 chars)

C example:

[source,C]
----------------------------------------
int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_strlen_screen
^^^^^^^^^^^^^^^^^^^^^^^^^^

Return number of chars needed on screen to display UTF-8 string.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_strlen_screen (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* number of chars needed on screen to display UTF-8 string

C example:

[source,C]
----------------------------------------
int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_charcmp
^^^^^^^^^^^^^^^^^^^^

Compare two UTF-8 chars.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_charcmp (const char *string1, const char *string2);
----------------------------------------

Arguments:

* 'string1': first string for comparison
* 'string2': second string for comparison

Return value:

* difference between first char of each string:
** negative if char1 < char2
** zero if char1 == char2
** positive if char1 > char2

C example:

[source,C]
----------------------------------------
int diff = weechat_utf8_charcmp ("aaa", "ccc"); /* == -2 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_charcasecmp
^^^^^^^^^^^^^^^^^^^^^^^^

Compare two UTF-8 chars, ignoring case.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_charcasecmp (const char *string1, const char *string2);
----------------------------------------

Arguments:

* 'string1': first string for comparison
* 'string2': second string for comparison

Return value:

* difference between first char of each string:
** negative if char1 < char2
** zero if char1 == char2
** positive if char1 > char2

C example:

[source,C]
----------------------------------------
int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_char_size_screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return number of chars needed on screen to display UTF-8 char.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_char_size_screen (const char *string);
----------------------------------------

Arguments:

* 'string': string

Return value:

* number of chars needed on screen to display UTF-8 char

C example:

[source,C]
----------------------------------------
int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_add_offset
^^^^^^^^^^^^^^^^^^^^^^^

Move forward N chars in an UTF-8 string.

Prototype:

[source,C]
----------------------------------------
char *weechat_utf8_add_offset (const char *string, int offset);
----------------------------------------

Arguments:

* 'string': string
* 'offset': number of chars

Return value:

* pointer to string, N chars after (NULL if it's not reachable)

C example:

[source,C]
----------------------------------------
char *str = "chêne";
char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_real_pos
^^^^^^^^^^^^^^^^^^^^^

Return real position in UTF-8 string.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_real_pos (const char *string, int pos);
----------------------------------------

Arguments:

* 'string': string
* 'pos': position (number of chars)

Return value:

* real potision (in bytes)

C example:

[source,C]
----------------------------------------
int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_pos
^^^^^^^^^^^^^^^^

Return position in UTF-8 string.

Prototype:

[source,C]
----------------------------------------
int weechat_utf8_pos (const char *string, int real_pos);
----------------------------------------

Arguments:

* 'string': string
* 'real_pos': position (bytes)

Return value:

* position (number of chars)

C example:

[source,C]
----------------------------------------
int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_utf8_strndup
^^^^^^^^^^^^^^^^^^^^

Return duplicate string, with 'length' chars max.

Prototype:

[source,C]
----------------------------------------
char *weechat_utf8_strndup (const char *string, int length);
----------------------------------------

Arguments:

* 'string': string
* 'length': max chars to duplicate

Return value:

* duplicated string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *string = weechat_utf8_strndup ("chêne", 3); /* returns "chê" */
/* ... */
free (string);
----------------------------------------

[NOTE]
This function is not available in scripting API.

[[directories]]
Directories
~~~~~~~~~~~

Some functions related to directories.

weechat_mkdir_home
^^^^^^^^^^^^^^^^^^

Create a directory in WeeChat home.

Prototype:

[source,C]
----------------------------------------
int weechat_mkdir_home (char *directory, int mode);
----------------------------------------

Arguments:

* 'directory': name of directory to create
* 'mode': mode for directory

Return value:

* 1 if directory was successfully created, 0 if an error occured

C example:

[source,C]
----------------------------------------
if (!weechat_mkdir_home ("temp", 0755))
{
    /* error */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.mkdir_home(directory, mode)

# example
weechat.mkdir_home("temp", 0755)
----------------------------------------

weechat_mkdir
^^^^^^^^^^^^^

Create a directory.

Prototype:

[source,C]
----------------------------------------
int weechat_mkdir (char *directory, int mode);
----------------------------------------

Arguments:

* 'directory': name of directory to create
* 'mode': mode for directory

Return value:

* 1 if directory was successfully created, 0 if an error occured

C example:

[source,C]
----------------------------------------
if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* error */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.mkdir(directory, mode)

# example
weechat.mkdir("/tmp/mydir", 0755)
----------------------------------------

weechat_mkdir_parents
^^^^^^^^^^^^^^^^^^^^^

Create a directory and make parent directories as needed.

Prototype:

[source,C]
----------------------------------------
int weechat_mkdir_parents (char *directory, int mode);
----------------------------------------

Arguments:

* 'directory': name of directory to create
* 'mode': mode for directory

Return value:

* 1 if directory was successfully created, 0 if an error occured

C example:

[source,C]
----------------------------------------
if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* error */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.mkdir_parents(directory, mode)

# example
weechat.mkdir_parents("/tmp/my/dir", 0755)
----------------------------------------

weechat_exec_on_files
^^^^^^^^^^^^^^^^^^^^^

Find files in a directory and execute a callback on each file.

Prototype:

[source,C]
----------------------------------------
void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void *data,
                            void (*callback)(void *data,
                                             const char *filename));
----------------------------------------

Arguments:

* 'directory': directory for searching files
* 'hidden_files': 1 to include hidden files, otherwise 0
* 'data': pointer given to callback when it is called by WeeChat
* 'callback': function called for each file found, arguments:
** 'void *data': pointer
** 'const char *filename': filename found

C example:

[source,C]
----------------------------------------
void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, NULL, &callback);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_file_get_content
^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.1._

Get content of text file in a string.

Prototype:

[source,C]
----------------------------------------
char *weechat_file_get_content (const char *filename);
----------------------------------------

Arguments:

* 'filename': path and file name

Return value:

* content of file as string (must be freed by calling "free" after use)

C example:

[source,C]
----------------------------------------
char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);
----------------------------------------

[NOTE]
This function is not available in scripting API.

[[util]]
Util
~~~~

Some useful functions.

weechat_util_timeval_cmp
^^^^^^^^^^^^^^^^^^^^^^^^

Compare two "timeval" structures.

Prototype:

[source,C]
----------------------------------------
int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);
----------------------------------------

Arguments:

* 'tv1': first "timeval" structure
* 'tv2': second "timeval" structure

Return value:

* -1 if tv1 < tv2
* zero if tv1 == tv2
* +1 if tv1 > tv2

C example:

[source,C]
----------------------------------------
if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_util_timeval_diff
^^^^^^^^^^^^^^^^^^^^^^^^^

Return difference (in milliseconds) between two "timeval" structures.

Prototype:

[source,C]
----------------------------------------
long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);
----------------------------------------

Arguments:

* 'tv1': first "timeval" structure
* 'tv2': second "timeval" structure

Return value:

* difference in milliseconds

C example:

[source,C]
----------------------------------------
long diff = weechat_util_timeval_diff (&tv1, &tv2);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_util_timeval_add
^^^^^^^^^^^^^^^^^^^^^^^^

Add interval (in milliseconds) to a timeval structure.

Prototype:

[source,C]
----------------------------------------
void weechat_util_timeval_add (struct timeval *tv, long interval);
----------------------------------------

Arguments:

* 'tv': timeval structure
* 'interval': interval (in milliseconds)

C example:

[source,C]
----------------------------------------
weechat_util_timeval_add (&tv, 2000); /* add 2 seconds */
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_util_get_time_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.2._

Get date/time as a string built with "strftime".

Prototype:

[source,C]
----------------------------------------
char *weechat_util_get_time_string (const time_t *date);
----------------------------------------

Arguments:

* 'date': pointer to date

C example:

[source,C]
----------------------------------------
time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));
----------------------------------------

[NOTE]
This function is not available in scripting API.

[[sorted_lists]]
Sorted lists
~~~~~~~~~~~~

Sorted list functions.

weechat_list_new
^^^^^^^^^^^^^^^^

Create a new list.

Prototype:

[source,C]
----------------------------------------
struct t_weelist *weechat_list_new ();
----------------------------------------

Return value:

* pointer to new list

C example:

[source,C]
----------------------------------------
struct t_weelist *list = weechat_list_new ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
list = weechat.list_new()

# example
list = weechat.list_new()
----------------------------------------

weechat_list_add
^^^^^^^^^^^^^^^^

Add an item in a list.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'data': data to insert in list
* 'where': position in list:
** 'WEECHAT_LIST_POS_SORT': add in list, keeping list sorted
** 'WEECHAT_LIST_POS_BEGINNING': add to beginning of list
** 'WEECHAT_LIST_POS_END': add to end of list
* 'user_data': any pointer

Return value:

* pointer to new item

C example:

[source,C]
----------------------------------------
struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_add(list, data, where, user_data)

# example
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")
----------------------------------------

weechat_list_search
^^^^^^^^^^^^^^^^^^^

Search an item in a list.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'data': data to search in list

Return value:

* pointer to item found, NULL if item was not found

C example:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_search (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_search(list, data)

# example
item = weechat.list_search(list, "my data")
----------------------------------------

weechat_list_search_pos
^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Search an item position in a list.

Prototype:

[source,C]
----------------------------------------
int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'data': data to search in list

Return value:

* position of item found, -1 if item was not found

C example:

[source,C]
----------------------------------------
int pos_item = weechat_list_search_pos (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
pos_item = weechat.list_search_pos(list, data)

# example
pos_item = weechat.list_search_pos(list, "my data")
----------------------------------------

weechat_list_casesearch
^^^^^^^^^^^^^^^^^^^^^^^

Search an item in a list, ignoring case.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'data': data to search in list

Return value:

* pointer to item found, NULL if item was not found

C example:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_casesearch (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_casesearch(list, data)

# example
item = weechat.list_casesearch(list, "my data")
----------------------------------------

weechat_list_casesearch_pos
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Search an item position in a list, ignoring case.

Prototype:

[source,C]
----------------------------------------
int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'data': data to search in list

Return value:

* position of item found, -1 if item was not found

C example:

[source,C]
----------------------------------------
int pos_item = weechat_list_casesearch_pos (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
pos_item = weechat.list_casesearch_pos(list, data)

# example
pos_item = weechat.list_casesearch_pos(list, "my data")
----------------------------------------

weechat_list_get
^^^^^^^^^^^^^^^^

Return an item in a list by position.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'position': position in list (first item is 0)

Return value:

* pointer to item found, NULL if item was not found

C example:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_get(list, position)

# example
item = weechat.list_get(list, 0)
----------------------------------------

weechat_list_set
^^^^^^^^^^^^^^^^

Set new value for an item.

Prototype:

[source,C]
----------------------------------------
void weechat_list_set (struct t_weelist_item *item, const char *value);
----------------------------------------

Arguments:

* 'item': item pointer
* 'value': new value for item

C example:

[source,C]
----------------------------------------
weechat_list_set (item, "new data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.list_set(item, value)

# example
weechat.list_set(item, "new data")
----------------------------------------

weechat_list_next
^^^^^^^^^^^^^^^^^

Return next item in list.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);
----------------------------------------

Arguments:

* 'item': item pointer

Return value:

* pointer to next item, NULL if pointer was last item in list

C example:

[source,C]
----------------------------------------
struct t_weelist_item *next_item = weechat_list_next (item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_next(item)

# example
item = weechat.list_next(item)
----------------------------------------

weechat_list_prev
^^^^^^^^^^^^^^^^^

Return previous item in list.

Prototype:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);
----------------------------------------

Arguments:

* 'item': item pointer

Return value:

* pointer to previous item, NULL if pointer was last item in list

C example:

[source,C]
----------------------------------------
struct t_weelist_item *prev_item = weechat_list_prev (item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.list_prev(item)

# example
item = weechat.list_prev(item)
----------------------------------------

weechat_list_string
^^^^^^^^^^^^^^^^^^^

Return string value of an item.

Prototype:

[source,C]
----------------------------------------
const char *weechat_list_string (struct t_weelist_item *item);
----------------------------------------

Arguments:

* 'item': item pointer

Return value:

* string value of item

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "value of item: %s", weechat_list_string (item));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.list_string(item)

# example
weechat.prnt("", "value of item: %s" % weechat.list_string(item))
----------------------------------------

weechat_list_size
^^^^^^^^^^^^^^^^^

Return size of list (number of items).

Prototype:

[source,C]
----------------------------------------
char *weechat_list_size (struct t_weelist *weelist);
----------------------------------------

Arguments:

* 'weelist': list pointer

Return value:

* size of list (number of items), 0 if list is empty

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "size of list: %d", weechat_list_size (list));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
size = weechat.list_size(list)

# example
weechat.prnt("", "size of list: %d" % weechat.list_size(list))
----------------------------------------

weechat_list_remove
^^^^^^^^^^^^^^^^^^^

Remove an item in a list.

Prototype:

[source,C]
----------------------------------------
void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);
----------------------------------------

Arguments:

* 'weelist': list pointer
* 'item': item pointer

C example:

[source,C]
----------------------------------------
weechat_list_remove (list, item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.list_remove(list, item)

# example
weechat.list_remove(list, item)
----------------------------------------

weechat_list_remove_all
^^^^^^^^^^^^^^^^^^^^^^^

Remove all items in a list.

Prototype:

[source,C]
----------------------------------------
void weechat_list_remove_all (struct t_weelist *weelist);
----------------------------------------

Arguments:

* 'weelist': list pointer

C example:

[source,C]
----------------------------------------
weechat_list_remove_all (list);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.list_remove_all(list)

# example
weechat.list_remove_all(list)
----------------------------------------

weechat_list_free
^^^^^^^^^^^^^^^^^

Free a list.

Prototype:

[source,C]
----------------------------------------
void weechat_list_free (struct t_weelist *weelist);
----------------------------------------

Arguments:

* 'weelist': list pointer

C example:

[source,C]
----------------------------------------
weechat_list_free (list);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.list_free(list)

# example
weechat.list_free(list)
----------------------------------------

[[hashtables]]
Hashtables
~~~~~~~~~~

Hashtable functions.

weechat_hashtable_new
^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Create a new hashtable.

Prototype:

[source,C]
----------------------------------------
struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned int (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                             const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));
----------------------------------------

Arguments:

* 'size': size of internal array to store hashed keys, a high value uses more
  memory, but has better performance (this is *not* a limit for number of items
  in hashtable)
* 'type_keys': type for keys in hashtable:
** 'WEECHAT_HASHTABLE_INTEGER'
** 'WEECHAT_HASHTABLE_STRING'
** 'WEECHAT_HASHTABLE_POINTER'
** 'WEECHAT_HASHTABLE_BUFFER'
** 'WEECHAT_HASHTABLE_TIME'
* 'type_values': type for values in hashtable:
** 'WEECHAT_HASHTABLE_INTEGER'
** 'WEECHAT_HASHTABLE_STRING'
** 'WEECHAT_HASHTABLE_POINTER'
** 'WEECHAT_HASHTABLE_BUFFER'
** 'WEECHAT_HASHTABLE_TIME'
* 'callback_hash_key': callback used to "hash" a key (key as integer value), can
  be NULL if key type is "string" (a default function is used for strings, and
  only for strings)
* 'callback_keycmp': callback used to compare two keys, can be NULL if value
  type is "string" (a default comparison function is used for strings, and only
  for strings)

Return value:

* pointer to new hashtable, NULL if an error occured

C example:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_set_with_size
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Add or update item in a hashtable with size for key and value.

Prototype:

[source,C]
----------------------------------------
int weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                     const void *key, int key_size,
                                     const void *value, int value_size);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'key': key pointer
* 'key_size': size of key (in bytes), used only if type of keys in hashtable
  is "buffer"
* 'value': value pointer
* 'value_size': size of value (in bytes), used only if type of values in
  hashtable is "buffer"

Return value:

* 1 if ok, 0 if error

C example:

[source,C]
----------------------------------------
weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_set
^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Add or update item in a hashtable.

Prototype:

[source,C]
----------------------------------------
int weechat_hashtable_set (struct t_hashtable *hashtable,
                           const void *key, const void *value);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'key': key pointer
* 'value': value pointer

Return value:

* 1 if ok, 0 if error

C example:

[source,C]
----------------------------------------
weechat_hashtable_set (hashtable, "my_key", "my_value");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_get
^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Get value associated with a key in a hashtable.

Prototype:

[source,C]
----------------------------------------
void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'key': key pointer

Return value:

* value for key, NULL if key is not found

C example:

[source,C]
----------------------------------------
void *value = weechat_hashtable_get (hashtable, "my_key");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_has_key
^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return 1 if hashtable has key, otherwise 0.

Prototype:

[source,C]
----------------------------------------
int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'key': key pointer

Return value:

* 1 if key is in hashtable, 0 if key is not in hashtable

C example:

[source,C]
----------------------------------------
if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* key is in hashtable */
    /* ... */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_map
^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Call a function on all hashtable entries.

Prototype:

[source,C]
----------------------------------------
void hashtable_map (struct t_hashlist *hashlist,
                    int (*callback_map)(void *data,
                                        struct t_hashtable *hashtable,
                                        const void *key,
                                        const void *value),
                    void *callback_map_data);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'callback_map': function called for each entry in hashtable
* 'callback_map_data': pointer given to map callback when it is called

C example:

[source,C]
----------------------------------------
void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* display key and value (they are both strings here) */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Return integer value of a hashtable property.

Prototype:

[source,C]
----------------------------------------
int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'property': property name:
** 'size': size of internal array "htable" in hashtable
** 'items_count': number of items in hashtable

Return value:

* integer value of property

C example:

[source,C]
----------------------------------------
int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return string value of a hashtable property.

Prototype:

[source,C]
----------------------------------------
const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          void *property);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'property': property name:
** 'type_keys': type for keys:
*** 'integer': integer
*** 'string': string
*** 'pointer': pointer
*** 'buffer': buffer
*** 'time': time
** 'type_values': type for values:
*** 'integer': integer
*** 'string': string
*** 'pointer': pointer
*** 'buffer': buffer
*** 'time': time
** 'keys': string with list of keys (format: "key1,key2,key3")
** '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")

Return value:

* string value of property

C examples:

[source,C]
----------------------------------------
weechat_printf (NULL, "keys are type: %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "list of keys: %s",
                weechat_hashtable_get_string (hashtable, "keys"));
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_add_to_infolist
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Add hashtable items to an infolist item.

Prototype:

[source,C]
----------------------------------------
int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'infolist_item': infolist item pointer
* 'prefix': string used as prefix for names in infolist

Return value:

* 1 if ok, 0 if error

C example:

[source,C]
----------------------------------------
weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* if hashtable contains:
     "key1" => "value 1"
     "key2" => "value 2"
   then following variables will be added to infolist item:
     "testhash_name_00001"  = "key1"
     "testhash_value_00001" = "value 1"
     "testhash_name_00002"  = "key2"
     "testhash_value_00002" = "value 2"
*/
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_remove
^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Remove an item in a hashtable.

Prototype:

[source,C]
----------------------------------------
void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer
* 'key': key pointer

C example:

[source,C]
----------------------------------------
weechat_hashtable_remove (hashtable, "my_key");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Remove all items in a hashtable.

Prototype:

[source,C]
----------------------------------------
void weechat_hashtable_remove_all (struct t_hashtable *hashtable);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer

C example:

[source,C]
----------------------------------------
weechat_hashtable_remove_all (hashtable);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_hashtable_free
^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.3._

Free a hashtable.

Prototype:

[source,C]
----------------------------------------
void weechat_hashtable_free (struct t_hashtable *hashtable);
----------------------------------------

Arguments:

* 'hashtable': hashtable pointer

C example:

[source,C]
----------------------------------------
weechat_hashtable_free (hashtable);
----------------------------------------

[NOTE]
This function is not available in scripting API.

[[configuration_files]]
Configuration files
~~~~~~~~~~~~~~~~~~~

Functions for configuration files.

weechat_config_new
^^^^^^^^^^^^^^^^^^

Create a new configuration file.

Prototype:

[source,C]
----------------------------------------
struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(void *data,
                                                                 struct t_config_file *config_file),
                                          void *callback_reload_data);
----------------------------------------

Arguments:

* 'name': name of configuration file (without path or extension)
* 'callback_reload': function called when configuration file is reloaded with
  `/reload` (optional, can be NULL), arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
* 'callback_reload_data': pointer given to reload callback when it is called
  by WeeChat

Return value:

* pointer to new configuration file, NULL if an error occured

[NOTE]
File is NOT created on disk by this function. It will be created by call to
function <<_weechat_write_config,weechat_write_config>>.
You should call this function only after adding some sections (with
<<_weechat_config_new_section,weechat_config_new_section>>) and options (with
<<_weechat_config_new_option,weechat_config_new_option>>).

C example:

[source,C]
----------------------------------------
int
my_config_reload_cb (void *data, struct t_config_file *config_file)
{
    /* ... */
    
    return WEECHAT_RC_OK;
}

struct t_config_file *config_file = weechat_config_new ("test",
                                                        &my_config_reload_cb,
                                                        NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
config_file = weechat.config_new(name, calback_reload, callback_reload_data)

# example
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")
----------------------------------------

weechat_config_new_section
^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a new section in configuration file.

Prototype:

[source,C]
----------------------------------------
struct t_config_section *weechat_config_new_section (
    struct t_config_file *config_file,
    const char *name,
    int user_can_add_options,
    int user_can_delete_options,
    int (*callback_read)(void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    void *callback_read_data,
    int (*callback_write)(void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    void *callback_write_data,
    int (*callback_write_default)(void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name);
    void *callback_write_default_data,
    int (*callback_create_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    void *callback_create_option_data,
    int (*callback_delete_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    void *callback_delete_option_data);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'name': name of section
* 'user_can_add_options': 1 if user can create new options in section, or 0 if
  it is forbidden
* 'user_can_delete_options': 1 if user can delete options in section, or 0 if
  it is forbidden
* 'callback_read': function called when an option in section is read from disk
  (should be NULL in most cases, except if options in section need custom
  function), arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
** 'struct t_config_section *section': section pointer
** 'const char *option_name': name of option
** 'const char *value': value
* 'callback_read_data': pointer given to callback when it is called by WeeChat
* 'callback_write': function called when section is written in file (should be
  NULL for most cases, except if section needs to be written by a custom
  function), arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
** 'struct t_config_section *section': section pointer
** 'const char *option_name': name of option
* callback_write_data: pointer given to callback when it is called by WeeChat
* callback_write_default: function called when default values for section must
  be written in file, arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
** 'const char *section_name': name of section
* 'callback_write_default_data': pointer given to callback when it is called by
  WeeChat
* 'callback_create_option': function called when a new option is created in
  section (NULL if section does not allow new options to be created),
  arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
** 'struct t_config_section *section': section pointer
** 'const char *option_name': name of option
** 'const char *value': value
* 'callback_create_option_data': pointer given to callback when it is called by
  WeeChat
* 'callback_delete_option': function called when an option is deleted in
  section (NULL if section does not allow options to be deleted),
  arguments:
** 'void *data': pointer
** 'struct t_config_file *config_file': configuration file pointer
** 'struct t_config_section *section': section pointer
** 'struct t_config_option *option': option pointer
* 'callback_delete_option_data': pointer given to callback when it is called by
  WeeChat

Return value:

* pointer to new section in configuration file, NULL if an error occured

C example:

[source,C]
----------------------------------------
int
my_section_read_cb (void *data, struct t_config_file *config_file,
                    struct t_config_section *section, const char *option_name,
                    const char *value)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */
    
    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_write_default_cb (void *data, struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */
    
    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_create_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name, const char *value)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE;
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_delete_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* standard section, user can not add/delete options */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, /* read callback */
                                NULL, NULL, /* write callback */
                                NULL, NULL, /* write default callback */
                                NULL, NULL, /* create option callback */
                                NULL, NULL); /* delete option callback */

/* special section, user can add/delete options, and options need
   callback to be read/written */
struct t_config_section *new_section2 =
    weechat_config_new_section (config_file, "section2", 1, 1,
                                &my_section_read_cb, NULL,
                                &my_section_write_cb, NULL,
                                &my_section_write_default_cb, NULL,
                                &my_section_create_option_cb, NULL,
                                &my_section_delete_option_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

# example
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

section = weechat.config_new_section(config_file, "section1", 1, 1,
    "my_section_read_cb", "",
    "my_section_write_cb", "",
    "my_section_write_default_cb", "",
    "my_section_create_option_cb", "",
    "my_section_delete_option_cb", "")
----------------------------------------

weechat_config_search_section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search a section in a configuration file.

Prototype:

[source,C]
----------------------------------------
struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'section_name': name of section to search

Return value:

* pointer to section found, NULL if section was not found

C example:

[source,C]
----------------------------------------
struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
section = weechat.config_search_section(config_file, section_name)

# example
section = weechat.config_search_section(config_file, "section")
----------------------------------------

weechat_config_new_option
^^^^^^^^^^^^^^^^^^^^^^^^^

Create a new option in a section of a configuration file.

Prototype:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_new_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *name,
    const char *type,
    const char *description,
    const char *string_values,
    int min,
    int max,
    const char *default_value,
    const char *value,
    int null_value_allowed,
    int (*callback_check_value)(void *data,
                                struct t_config_option *option,
                                const char *value),
    void *callback_check_value_data,
    int (*callback_change)(void *data,
                           struct t_config_option *option),
    void *callback_change_data,
    int (*callback_delete)(void *data,
                           struct t_config_option *option),
    void *callback_delete_data);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'section': section pointer
* 'name': name of option
* 'type': type of option:
** 'boolean': boolean value (on/off)
** 'integer': integer value (with optional strings for values)
** 'string': string value
** 'color': color
* 'description': description of option
* 'string_values': values as string (separated by "|"), used for type 'integer'
  (optional)
* 'min': minimum value (for type 'integer')
* 'max': maximum value (for type 'integer')
* 'default_value': default value for option (used when option is reset)
* 'value': value for option
* 'null_value_allowed': 1 if 'null' (undefined value) is allowed for option,
  otherwise 0
* 'callback_check_value': function called to check new value for option
  (optional), arguments:
** 'void *data': pointer
** 'struct t_config_option *option': option pointer
** 'const char *value': new value for option
* 'callback_check_value_data': pointer given to check_value callback when it
  is called by WeeChat
* 'callback_change': function called when value of option has changed
  (optional), arguments:
** 'void *data': pointer
** 'struct t_config_option *option': option pointer
* 'callback_change_data': pointer given to change callback when it is called
  by WeeChat
* 'callback_delete': function called when option will be deleted (optional),
  arguments:
** 'void *data': pointer
** 'struct t_config_option *option': option pointer
* 'callback_delete_data': pointer given to delete callback when it is called
  by WeeChat

Return value:

* pointer to new option in section, NULL if an error

C example:

[source,C]
----------------------------------------
/* boolean */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "on", /* default */
                               "on", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer"
                               NULL, /* string values */
                               0, 100, /* min, max */
                               "15", /* default */
                               "15", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer (with string values) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)"
                               "top|bottom|left|right", /* string values */
                               0, 0, /* min, max */
                               "bottom", /* default */
                               "bottom", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* string */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "test", /* default */
                               "test", /* value */
                               1, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* color */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "lightblue", /* default */
                               "lightblue", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

# example
def option4_check_value_cb(data, option, value):
    # ...
    return 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "My option, type integer",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "My option, type integer (with string values)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", ""
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "My option, type color",
    "", 0, 100, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")
----------------------------------------

weechat_config_search_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search an option in a section of a configuration file.

Prototype:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'section': section pointer
* 'name': name of option to search

Return value:

* pointer to option found, NULL if option was not found

C example:

[source,C]
----------------------------------------
struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
option = weechat.config_search_option(config_file, section, option_name)

# example
option = weechat.config_search_option(config_file, section, "option")
----------------------------------------

weechat_config_search_section_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search a section and an option in a configuration file or section.

Prototype:

[source,C]
----------------------------------------
void weechat_config_search_section_option (struct t_config_file *config_file,
                                           struct t_config_section *section,
                                           const char *option_name,
                                           struct t_config_section **section_found,
                                           struct t_config_option **option_found);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'section': section pointer
* 'option_name': option name
* 'section_found': pointer to section pointer, will be set to section of option,
  if found
* 'option_found': pointer to an option pointer, will be set to option pointer,
  if found

C example:

[source,C]
----------------------------------------
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_section_option(config_file,
                                     section,
                                     "option",
                                     &ptr_section,
                                     &ptr_option);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_config_search_with_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search an option with full name.

Prototype:

[source,C]
----------------------------------------
void weechat_config_search_with_string (const char *option_name,
                                        struct t_config_file **config_file,
                                        struct t_config_section **section,
                                        struct t_config_option **option);
----------------------------------------

Arguments:

* 'option_name': full option name (format: "file.section.option")
* 'config_file': pointer to configuration file pointer, will be set with
  pointer to configuration file of option found
* 'section': pointer to section pointer, will be set to section of option, if
  found
* 'option': pointer to an option pointer, will be set to option pointer, if
  found

C example:

[source,C]
----------------------------------------
struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_config_string_to_boolean
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check if a text is "true" or "false", as boolean value.

Prototype:

[source,C]
----------------------------------------
int weechat_config_string_to_boolean (const char *text);
----------------------------------------

Arguments:

* 'text': text to analyze

Return value:

* 1 if text is "true" ("on", "yes", "y", "true", "t", "1")
* 0 if text is "false" ("off", "no", "n", "false", "f", "0")

C example:

[source,C]
----------------------------------------
if (weechat_config_string_to_boolean (option_value))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_string_to_boolean(text)

# example
if weechat.config_string_to_boolean(text):
    # ...
----------------------------------------

weechat_config_option_reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Reset an option to its default value.

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);
----------------------------------------

Arguments:

* 'option': option pointer
* 'run_callback': 1 for calling callback if value of option is changed,
  otherwise 0

Return value:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been reset
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_option_reset (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_option_reset(option, run_callback)

# example
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_set
^^^^^^^^^^^^^^^^^^^^^^^^^

Set new value for an option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);
----------------------------------------

Arguments:

* 'option': option pointer
* 'value': new value for option
* 'run_callback': 1 for calling chang callback if value of option is changed,
  otherwise 0

Return value:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_option_set (option, "new_value", 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_option_set(option, value, run_callback)

# example
rc = weechat.config_option_set(option, "new_value", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_set_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set null (undefined value) for an option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);
----------------------------------------

Arguments:

* 'option': option pointer
* 'run_callback': 1 for calling chang callback if value of option is changed
  (if it was not null), otherwise 0

[NOTE]
You can set value to null only if it is allowed for option (see
<<_weechat_config_new_option,weechat_config_new_option>>).

Return value:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_option_set_null (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_option_set_null(option, run_callback)

# example
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_unset
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Unset/reset option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_unset (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' if option value has not been reset
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' if option value has been reset
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_option_unset (option))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_option_unset(option)

# example
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----------------------------------------

weechat_config_option_rename
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rename an option.

Prototype:

[source,C]
----------------------------------------
void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);
----------------------------------------

Arguments:

* 'option': option pointer
* 'new_name': new name for option

C example:

[source,C]
----------------------------------------
weechat_config_option_rename (option, "new_name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_option_rename(option, new_name)

# example
weechat.config_option_rename(option, "new_name")
----------------------------------------

weechat_config_option_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return a pointer on an option property.

Prototype:

[source,C]
----------------------------------------
void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);
----------------------------------------

Arguments:

* 'option': option pointer
* 'property': property name:
** 'config_file': configuration file pointer ('struct t_config_file *')
** 'section': section pointer ('struct t_config_section *')
** 'name': option name ('char *')
** 'type': option type ('int *')
** 'description': option description ('char *')
** 'string_values': string values ('char *')
** 'min': minimum value ('int *')
** 'max': maximum value ('int *')
** 'default_value': default value (depends on type)
** 'value': current value (depends on type)
** 'prev_option': previous option pointer ('struct t_config_option *')
** 'next_option': next option pointer ('struct t_config_option *')

Return value:

* pointer to property asked

C example:

[source,C]
----------------------------------------
char *description = weechat_config_option_get_pointer (option, "description");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_config_option_is_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check if an option is "null" (undefined value).

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_is_null (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* 1 if value of option is "null"
* 0 if value of option is not "null"

C example:

[source,C]
----------------------------------------
if (weechat_config_option_is_null (option))
{
    /* value is "null" */
}
else
{
    /* value is not "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
is_null = weechat.config_option_is_null(option)

# example
if weechat.config_option_is_null(option):
    # ...
----------------------------------------

weechat_config_option_default_is_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check if default value for an option is "null" (undefined value).

Prototype:

[source,C]
----------------------------------------
int weechat_config_option_default_is_null (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* 1 if default value of option is "null"
* 0 if default value of option is not "null"

C example:

[source,C]
----------------------------------------
if (weechat_config_option_default_is_null (option))
{
    /* default value is "null" */
}
else
{
    /* default value is not "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
is_null = weechat.config_option_default_is_null(option)

# example
if weechat.config_option_default_is_null(option):
    # ...
----------------------------------------

weechat_config_boolean
^^^^^^^^^^^^^^^^^^^^^^

Return boolean value of option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_boolean (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* boolean value of option (0 or 1)

C example:

[source,C]
----------------------------------------
if (weechat_config_boolean (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_boolean(option)

# example
if weechat.config_option_boolean(option):
    # ...
----------------------------------------

weechat_config_boolean_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return default boolean value of option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_boolean_default (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* default boolean value of option (0 or 1)

C example:

[source,C]
----------------------------------------
if (weechat_config_boolean_default (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_boolean_default(option)

# example
if weechat.config_option_boolean_default(option):
    # ...
----------------------------------------

weechat_config_integer
^^^^^^^^^^^^^^^^^^^^^^

Return integer value of option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_integer (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* integer value of option

C example:

[source,C]
----------------------------------------
int value = weechat_config_integer (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_integer(option)

# example
if weechat.config_option_integer(option):
    # ...
----------------------------------------

weechat_config_integer_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return default integer value of option.

Prototype:

[source,C]
----------------------------------------
int weechat_config_integer_default (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* default integer value of option

C example:

[source,C]
----------------------------------------
int value = weechat_config_integer_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_integer_default(option)

# example
if weechat.config_option_integer_default(option):
    # ...
----------------------------------------

weechat_config_string
^^^^^^^^^^^^^^^^^^^^^

Return string value of option.

Prototype:

[source,C]
----------------------------------------
const char *weechat_config_string (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* string value of option

C example:

[source,C]
----------------------------------------
const char *value = weechat_config_string (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_string(option)

# example
value = weechat.config_option_string(option):
----------------------------------------

weechat_config_string_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return default string value of option.

Prototype:

[source,C]
----------------------------------------
const char *weechat_config_integer_default (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* default string value of option

C example:

[source,C]
----------------------------------------
const char *value = weechat_config_string_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_string_default(option)

# example
value = weechat.config_option_string_default(option):
----------------------------------------

weechat_config_color
^^^^^^^^^^^^^^^^^^^^

Return color value of option.

Prototype:

[source,C]
----------------------------------------
const char *weechat_config_color (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* color value of option (string with name of color)

C example:

[source,C]
----------------------------------------
const char *color = weechat_config_color (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_color(option)

# example
value = weechat.config_option_color(option):
----------------------------------------

weechat_config_color_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Return default color value of option.

Prototype:

[source,C]
----------------------------------------
const char *weechat_config_color_default (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

Return value:

* default color value of option (string with name of color)

C example:

[source,C]
----------------------------------------
const char *color = weechat_config_color_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_option_color_default(option)

# example
value = weechat.config_option_color_default(option):
----------------------------------------

weechat_config_write_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Write a line in a configuration file with option and its value (this function
should be called only in "write" or "write_default" callbacks for a section).

Prototype:

[source,C]
----------------------------------------
void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'option': option pointer

C example:

[source,C]
----------------------------------------
int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);
    
    weechat_config_write_option (config_file, option);
    
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_write_option(config_file, option)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_config_write_line
^^^^^^^^^^^^^^^^^^^^^^^^^

Write a line in a configuration file (this function should be called only in
"write" or "write_default" callbacks for a section).

Prototype:

[source,C]
----------------------------------------
void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer
* 'option_name': option name
* 'value': value (if NULL, then line with section name is written, for
  example: "[section]")

C example:

[source,C]
----------------------------------------
int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);
    
    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);
                               
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_write_line(config_file, option_name, value)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_line(config_file, "option", "value")
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_config_write
^^^^^^^^^^^^^^^^^^^^

Write configuration file to disk.

Prototype:

[source,C]
----------------------------------------
int weechat_config_write (struct t_config_file *config_file);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer

Return value:

* 'WEECHAT_CONFIG_WRITE_OK' if configuration was written
* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_WRITE_ERROR' if another error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_write (config_file))
{
    case WEECHAT_CONFIG_WRITE_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_write(config_file)

# example
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...
----------------------------------------

weechat_config_read
^^^^^^^^^^^^^^^^^^^

Read configuration file from disk.

Prototype:

[source,C]
----------------------------------------
int weechat_config_read (struct t_config_file *config_file);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer

Return value:

* 'WEECHAT_CONFIG_READ_OK' if configuration was loaded
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' if file was not found

C example:

[source,C]
----------------------------------------
switch (weechat_config_read (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_read(config_file)

# example
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----------------------------------------

weechat_config_reload
^^^^^^^^^^^^^^^^^^^^^

Reload configuration file from disk.

Prototype:

[source,C]
----------------------------------------
int weechat_config_reload (struct t_config_file *config_file);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer

Return value:

* 'WEECHAT_CONFIG_READ_OK' if configuration was reloaded
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' if file was not found

C example:

[source,C]
----------------------------------------
switch (weechat_config_reload (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_reload(config_file)

# example
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----------------------------------------

weechat_config_option_free
^^^^^^^^^^^^^^^^^^^^^^^^^^

Free an option.

Prototype:

[source,C]
----------------------------------------
void weechat_config_option_free (struct t_config_option *option);
----------------------------------------

Arguments:

* 'option': option pointer

C example:

[source,C]
----------------------------------------
weechat_config_option_free (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_option_free(option)

# example
weechat.config_option_free(option)
----------------------------------------

weechat_config_section_free_options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free all options in a section.

Prototype:

[source,C]
----------------------------------------
void weechat_config_section_free_options (struct t_config_section *section);
----------------------------------------

Arguments:

* 'section': section pointer

C example:

[source,C]
----------------------------------------
weechat_config_section_free_options (section);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_section_free_options(section)

# example
weechat.config_section_free_options(section)
----------------------------------------

weechat_config_section_free
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free a section.

Prototype:

[source,C]
----------------------------------------
void weechat_config_section_free (struct t_config_option *option);
----------------------------------------

Arguments:

* 'section': section pointer

C example:

[source,C]
----------------------------------------
weechat_config_section_free (section);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_section_free(section)

# example
weechat.config_section_free(section)
----------------------------------------

weechat_config_free
^^^^^^^^^^^^^^^^^^^

Free a configuration file.

Prototype:

[source,C]
----------------------------------------
void weechat_config_free (struct t_config_file *config_file);
----------------------------------------

Arguments:

* 'config_file': configuration file pointer

C example:

[source,C]
----------------------------------------
weechat_config_free (config_file);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.config_free(config_file)

# example
weechat.config_free(config_file)
----------------------------------------

weechat_config_get
^^^^^^^^^^^^^^^^^^

Search an option with full name.

Prototype:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_get (const char *option_name);
----------------------------------------

Arguments:

* 'option_name': full option name (format: "file.section.option")

Return value:

* pointer to option found, NULL if option was not found

C example:

[source,C]
----------------------------------------
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
option = weechat.config_get(option_name)

# example
option = weechat.config_get("weechat.look.item_time_format")
----------------------------------------

weechat_config_get_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^

Search an option in plugins configuration file (plugins.conf).

Prototype:

[source,C]
----------------------------------------
const char *weechat_config_get_plugin (const char *option_name);
----------------------------------------

Arguments:

* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx."
  (where "xxx" is current plugin name)

Return value:

* value of option found, NULL if option was not found

C example:

[source,C]
----------------------------------------
/* if current plugin is "test", then look for value of option
   "plugins.var.test.option" in file plugins.conf */
char *value = weechat_config_get_plugin ("option");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_get_plugin(option_name)

# example
value = weechat.config_get_plugin("option")
----------------------------------------

weechat_config_is_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check if option is set in plugins configuration file (plugins.conf).

Prototype:

[source,C]
----------------------------------------
int weechat_config_is_set_plugin (const char *option_name);
----------------------------------------

Arguments:

* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx."
  (where "xxx" is current plugin name)

Return value:

* 1 if option is set, 0 if option does not exist

C example:

[source,C]
----------------------------------------
if (weechat_config_is_set_plugin ("option"))
{
    /* option is set */
}
else
{
    /* option does not exist */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.config_is_set_plugin(option_name)

# example
if weechat.config_is_set_plugin("option"):
    # option is set
    # ...
else:
    # option does not exist
    # ...
----------------------------------------

weechat_config_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^

Set new value for option in plugins configuration file (plugins.conf).

Prototype:

[source,C]
----------------------------------------
int weechat_config_set_plugin (const char *option_name, const char *value);
----------------------------------------

Arguments:

* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx."
  (where "xxx" is current plugin name)
* 'value': new value for option

Return value:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' if option value has been changed
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' if option was not found
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if other error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_set_plugin(option_name, value)

# example
rc = weechat.config_is_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_unset_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Unset option in plugins configuration file (plugins.conf).

Prototype:

[source,C]
----------------------------------------
int weechat_config_unset_plugin (const char *option_name);
----------------------------------------

Arguments:

* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx."
  (where xxx is current plugin name)

Return value:

* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' if option value has not been reset
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' if option value has been reset
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occured

C example:

[source,C]
----------------------------------------
switch (weechat_config_unset_plugin ("option"))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.config_unset_plugin(option_name)

# example
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----------------------------------------

[[display]]
Display
~~~~~~~

Functions to display text in buffers.

weechat_prefix
^^^^^^^^^^^^^^

Return a prefix.

Prototype:

[source,C]
----------------------------------------
const char *weechat_prefix (const char *prefix);
----------------------------------------

Arguments:

* 'prefix': name of prefix:

[width="70%",cols="^2e,^1l,^3,5",options="header"]
|========================================
| Prefix  | Value | Color      | Description
| error   | =!=   | yellow     | error message
| network | --    | magenta    | message from network
| action  | *     | white      | self action
| join    | -->   | lightgreen | someone joins current chat
| quit    | <--   | lightred   | someone leaves current chat
|========================================

[NOTE]
Values and colors can be customized with command `/set`.

Return value:

* prefix value (string with prefix and color codes), empty string if prefix is
  not found

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.prefix(prefix)

# example
weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))
----------------------------------------

weechat_color
^^^^^^^^^^^^^

Return a string color code for display.

Prototype:

[source,C]
----------------------------------------
const char *weechat_color (const char *color_name);
----------------------------------------

Arguments:

* 'color_name': name of color, one of:
** WeeChat option name (from weechat.color.xxx), for example 'chat_delimiters'
** color with optional background, for example 'yellow' or 'yellow,red'
** attribute:
*** 'bold': set bold
*** '-bold': remove bold
*** 'reverse': set reverse
*** '-reverse': remove reverse
*** 'italic': set italic
*** '-italic': remove italic
*** 'underline': set underline
*** '-underline': remove underline
** bar color name:
*** 'bar_fg': foreground color for bar
*** 'bar_delim': delimiters color for bar
*** 'bar_bg': background color for bar

Return value:

* string with color code, or a "reset color" code if color is not found

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.color(color_name)

# example
weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
----------------------------------------

weechat_printf
^^^^^^^^^^^^^^

Display a message on a buffer.

Prototype:

[source,C]
----------------------------------------
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
----------------------------------------

Arguments:

* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer
* 'message': message to display

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.prnt(buffer, message)

# example
weechat.prnt("", "Hello on WeeChat buffer")
weechat.prnt(buffer, "Hello on this buffer")
----------------------------------------

[NOTE]
Function is called "print" in scripts ("prnt" in Python).

weechat_printf_date
^^^^^^^^^^^^^^^^^^^

Display a message on a buffer, using a custom date.

Prototype:

[source,C]
----------------------------------------
void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);
----------------------------------------

Arguments:

* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer
* 'date': date for message
* 'message': message to display

C example:

[source,C]
----------------------------------------
weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_printf_tags
^^^^^^^^^^^^^^^^^^^

Display a message on a buffer, using a custom tags.

Prototype:

[source,C]
----------------------------------------
void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);
----------------------------------------

Arguments:

* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer
* 'tags': comma separated list of tags
* 'message': message to display

C example:

[source,C]
----------------------------------------
weechat_printf_tags (NULL, "notify_message",
                     "Message with a tag 'notify_message'");
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_printf_date_tags
^^^^^^^^^^^^^^^^^^^^^^^^

Display a message on a buffer, using a custom date and tags.

Prototype:

[source,C]
----------------------------------------
void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);
----------------------------------------

Arguments:

* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer
* 'date': date for message
* 'tags': comma separated list of tags
* 'message': message to display

C example:

[source,C]
----------------------------------------
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message 2 minutes ago, with a tag 'notify_message'");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.prnt_date_tags(buffer, date, tags, message)

# example
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message 2 minutes ago, with a tag 'notify_message'")
----------------------------------------

[NOTE]
Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python).

weechat_printf_y
^^^^^^^^^^^^^^^^

Display a message on a line of a buffer with free content.

Prototype:

[source,C]
----------------------------------------
void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *message, ...);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'y': line number (first line is 0)
* 'message': message to display

C example:

[source,C]
----------------------------------------
weechat_printf_y (buffer, 2, "My message on third line");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.prnt_y(buffer, y, message)

# example
weechat.prnt_y("", 2, "My message on third line")
----------------------------------------

[NOTE]
Function is called "print_y" in scripts ("prnt_y" in Python).

weechat_log_printf
^^^^^^^^^^^^^^^^^^

Write a message in WeeChat log file (weechat.log).

Prototype:

[source,C]
----------------------------------------
void weechat_log_printf (const char *message, ...);
----------------------------------------

Arguments:

* 'message': message to write

C example:

[source,C]
----------------------------------------
weechat_log_printf ("My message in log file");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.log_print(message)

# example
weechat.log_print("My message in log file")
----------------------------------------

[NOTE]
Function is called "log_print" in scripts.

[[hooks]]
Hooks
~~~~~

[[hook_priority]]
[float]
Hook priority
^^^^^^^^^^^^^

_New in version 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 nonnegative integer with priority and "name"
the name for argument (priority does not appear in name, it is automatically
removed from string).

Default priority is 1000.

C example:

[source,C]
----------------------------------------
/* hook modifier with priority = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL);
----------------------------------------

Following hook types allow priority: command, command_run, signal, hsignal,
config, completion, modifier, info, infolist.

weechat_hook_command
^^^^^^^^^^^^^^^^^^^^

Hook a command.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     void *callback_data);
----------------------------------------

Arguments:

* 'command': command name
  (priority allowed, see note about <<hook_priority,priority>>)
* 'description': description for command (displayed with `/help command`)
* 'args': arguments for command (displayed with `/help command`)
* 'args_description': description of arguments (displayed with `/help command`)
* 'completion': completion template for command: list of completions for each
  argument, separated by space. Many completions are possible for one
  argument, separated by "|". Many templates are possible for same command,
  separated by "||".
* 'callback': function called when command is used, arguments:
** 'void *data': pointer
** 'struct t_gui_buffer *buffer': buffer where command is executed
** 'int argc': number of arguments given for command
** 'char **argv': arguments given for command
** 'char **argv_eol': arguments given for command (until end of line for each
   argument)
* 'callback_data': pointer given to callback when it is called by WeeChat

Default completion codes are:
include::autogen/plugin_api/completions.txt[]

Special codes:

* '%%command': reuse completion template from command 'command'
* '%-': stop completion
* '%*': repeat last completion

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_command_cb (void *data, struct t_gui_buffer *buffer, int argc,
               char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* this example is inspired by command /filter */
struct t_hook *my_command_hook =
    weechat_hook_command (/* command name */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);
----------------------------------------

For example, if command called is `/command abc def ghi`, then argv and
argv_eol contain following values:

* 'argv':
** 'argv[0]' == "abc"
** 'argv[1]' == "def"
** 'argv[2]' == "ghi"
* 'argv_eol':
** 'argv_eol[0]' == "abc def ghi"
** 'argv_eol[1]' == "def ghi"
** 'argv_eol[2]' == "ghi"

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# example
def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "description of myfilter",
    "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")
----------------------------------------

weechat_hook_command_run
^^^^^^^^^^^^^^^^^^^^^^^^

Hook a command when WeeChat runs it.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);
----------------------------------------

Arguments:

* 'command': command to hook, can start or end with "*" as wildcard
  (priority allowed, see note about <<hook_priority,priority>>)
* 'callback': function called when command is run, arguments:
** 'void *data': pointer
** 'struct t_gui_buffer *buffer': buffer where command is executed
** 'const char *command': the command executed, with its arguments
* 'callback_data': pointer given to callback when it is called by WeeChat

[NOTE]
Callback can return 'WEECHAT_RC_OK' or 'WEECHAT_RC_OK_EAT' (command will not
be executed by WeeChat after callback).

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
                    "You want to complete? I'm eating the completion ahah!");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_command_run(command, callback, callback_data)

# example
def my_command_run_cb(data, buffer, command):
    weechat.prnt("", "You want to complete? I'm eating the completion, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
----------------------------------------

weechat_hook_timer
^^^^^^^^^^^^^^^^^^

Hook a timer.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_timer (long interval,
                                   const char *align_second,
                                   const char *max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);
----------------------------------------

Arguments:

* 'interval': interval between two calls (milliseconds, so 1000 = 1 second)
* 'align_second': alignment on a second. For example, if current time is 09:00,
  if interval = 60000 (60 seconds), and align_second = 60, then timer is
  called each minute when second is 00
* 'max_calls': number of calls to timer (if 0, then timer has no end)
* 'callback': function called when time is reached, arguments:
** 'void *data': pointer
** 'int remaining_calls': remaining calls (-1 if timer has no end)
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_timer_cb (void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* timer called each 20 seconds */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# example
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each 20 seconds
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
----------------------------------------

weechat_hook_fd
^^^^^^^^^^^^^^^

Hook a file descriptor (file or socket).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);
----------------------------------------

Arguments:

* 'fd': file descriptor
* 'flag_read': 1 = catch read event, 0 = ignore
* 'flag_write': 1 = catch write event, 0 = ignore
* 'flag_exception': 1 = catch exception event, 0 = ignore
* 'callback': function called a selected event occurs for file (or socket),
  arguments:
** 'void *data': pointer
** 'int fd': file descriptor
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_fd_cb (void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# example
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
----------------------------------------

weechat_hook_process
^^^^^^^^^^^^^^^^^^^^

Hook a process (launched with fork), and catch output.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);
----------------------------------------


Arguments:

* 'command': command to launch in child process
* 'timeout': timeout for command (in milliseconds): after this timeout, child
  process is killed (0 means no timeout)
* 'callback': function called when data from child is available, or when child
  has ended, arguments:
** 'void *data': pointer
** 'const char *command': command executed by child
** 'int return_code': return code:
*** '>= 0': child command return code
*** '< 0': 'WEECHAT_HOOK_PROCESS_OK_RUNNING' (data available, but child still
    running) or 'WEECHAT_HOOK_PROCESS_ERROR' (error when launching command)
** 'out': standard output of command (stdout)
** 'err': error output of command (stderr)
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

When command has ended, or if timeout is reached, WeeChat will automatically
unhook (and kill process if it is still running).

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

C example:

[source,C]
----------------------------------------
int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }
    
    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }
    
    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }
    
    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }
    
    return WEECHAT_RC_OK;
}

struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_process(command, timeout, callback, callback_data)

# example
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout: %s" % out)
    if err != "":
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
----------------------------------------

weechat_hook_connect
^^^^^^^^^^^^^^^^^^^^

Hook a connection (background connection to a remote host).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int sock,
                                     int ipv6,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);
----------------------------------------

Arguments:

* 'proxy': name of proxy to use for connection (optional, NULL means connection
  without proxy)
* 'address': name or IP address to connect to
* 'port': port number
* 'sock': socket used to connect
* 'ipv6': 1 to use IPv6, 0 to use IPv4
* 'gnutls_sess': GnuTLS session (optional)
* 'gnutls_cb': GnuTLS callback (optional)
* 'gnutls_dhkey_size': size of the key used during the Diffie-Hellman Key
  Exchange (GnuTLS)
* 'local_hostname': local hostname to use for connection (optional)
* 'callback': function called when connection is ok or failed, arguments:
** 'void *data': pointer
** 'int status': connection status:
*** 'WEECHAT_HOOK_CONNECT_OK': connection ok
*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND': address not found
*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND': IP address not found
*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED': connection refused
*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR': error with proxy
*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR': error with local hostname
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR': GnuTLS init error
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR': GnuTLS handshake error
*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR': insufficient memory
** 'gnutls_rc': result value of 'gnutls_handshake()'
** 'const char *error': result value of 'gnutls_strerror(gnutls_rc)'
** 'const char *ip_address': IP address found
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_connect_cb (void *data, int status, int gnutls_rc, const char *error,
               const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       sock, 0,
                                                       NULL, NULL, 0, /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_connect(proxy, address, port, sock, ipv6, local_hostname,
    callback, callback_data)

# example
def my_connect_cb(data, status, gnutls_rc, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, sock, 0, "",
                            "my_connect_cb", "")
----------------------------------------

weechat_hook_print
^^^^^^^^^^^^^^^^^^

Hook a message printed.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);
----------------------------------------

Arguments:

* 'buffer': buffer pointer, if NULL, messages from any buffer are caught
* 'tags': only messages with these tags (comma separated list) will be caught
  (optional)
* 'message': only messages with this string will be caught (optional)
* 'strip_colors': if 1, colors will be stripped from message displayed, before
  calling callback
* 'callback': function called when a message is printed, arguments:
** 'void *data': pointer
** 'struct t_gui_buffer *buffer': buffer pointer
** 'time_t date': date
** 'int tags_count': number of tags for line
** 'const char **tags': array with tags for line
** 'int displayed': 1 if line is displayed, 0 if it is filtered (hidden)
** 'int highlight': 1 if line has highlight, otherwise 0
** 'const char *prefix': prefix
** 'const char *message': message
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch all messages, on all buffers, without color */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# example
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    # ...
    return weechat.WEECHAT_RC_OK

# catch all messages, on all buffers, without color
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----------------------------------------

weechat_hook_signal
^^^^^^^^^^^^^^^^^^^

Hook a signal.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);
----------------------------------------

Arguments:

* 'signal': signal to catch, can begin or end with "*"
  (priority allowed, see note about <<hook_priority,priority>>):

[width="100%",cols="^1,^3,^4,5",options="header"]
|========================================
| Plugin | Signal | Arguments | Description

| 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_out_yyy ^(1)^ | string: message |
  irc message sent to server

| 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_connecting | string: server name |
  connecting to server

| irc | irc_server_connected | string: server name |
  connected to server

| irc | irc_server_disconnected | string: server name |
  disconnected from server

| irc | irc_ignore_removing | pointer: ignore |
  removing ignore

| irc | irc_ignore_removed | - |
  ignore removed

| logger | logger_start | pointer: buffer |
  start logging for buffer

| logger | logger_stop | pointer: buffer |
  stop logging for buffer

| logger | logger_backlog | pointer: buffer |
  display backlog for buffer

| weechat | buffer_closing | pointer: buffer |
  closing buffer

| weechat | buffer_closed | pointer: buffer |
  buffer closed

| weechat | buffer_lines_hidden | pointer: buffer |
  lines hidden in buffer

| weechat | buffer_localvar_added | pointer: buffer |
  local variable has been added

| weechat | buffer_localvar_changed | pointer: buffer |
  local variable has changed

| weechat | buffer_localvar_removed | pointer: buffer |
  local variable has been removed

| weechat | buffer_moved | pointer: buffer |
  buffer moved

| weechat | buffer_opened | pointer: buffer |
  buffer opened

| weechat | buffer_renamed | pointer: buffer |
  buffer renamed

| weechat | buffer_switch | pointer: buffer |
  switching buffer

| weechat | buffer_title_changed | pointer: buffer |
  title of buffer changed

| weechat | buffer_type_changed | pointer: buffer |
  type of buffer changed

| weechat | day_changed | string: new date, format: "2010-01-31" |
  day of system date has changed

| weechat | debug_dump | string: plugin name |
  dump request

| weechat | filter_added | pointer: filter |
  filter added

| weechat | filter_removing | pointer: filter |
  removing filter

| weechat | filter_removed | - |
  filter added

| weechat | filter_enabled | - |
  filters enabled

| weechat | filter_disabled | - |
  filters disabled

| weechat | hotlist_changed | - |
  hotlist changed

| weechat | input_paste_pending | - |
  paste pending

| weechat | input_search | - |
  text search in buffer

| weechat | input_text_changed | - |
  input text changed

| weechat | input_text_cursor_moved | - |
  input text cursor moved

| weechat | key_pressed | string: key pressed |
  key pressed

| weechat | nicklist_group_added | string: buffer pointer + "," + group name |
  group added in 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_removed | string: buffer pointer + "," + nick name |
  nick removed from nicklist

| weechat | partial_completion | - |
  partial completion happened

| weechat | quit | string: arguments for /quit |
  command `/quit` issued by user

| weechat | upgrade | - |
  command `/upgrade` issued by user

| weechat | weechat_highlight | string: message with prefix |
  highlight happened

| weechat | weechat_pv | string: message with prefix |
  private message displayed

| weechat | window_scrolled | pointer: window |
  scroll in window

| weechat | window_unzooming | pointer: current window |
  unzooming window

| weechat | window_unzoomed | pointer: current window |
  window unzoomed

| weechat | window_zooming | pointer: current window |
  zomming window

| weechat | window_zoomed | pointer: current window |
  window zoomed

| xfer | xfer_add | pointer: infolist with xfer info |
  new xfer

| xfer | xfer_send_ready | pointer: infolist with xfer info |
  xfer ready

| xfer | xfer_accept_resume | pointer: infolist with xfer info |
  xfer accepts resume (send)

| xfer | xfer_send_accept_resume | pointer: infolist with xfer info |
  xfer accepts resume (send)

| xfer | xfer_start_resume | pointer: infolist with xfer info |
  start resume

| xfer | xfer_resume_ready | pointer: infolist with xfer info |
  xfer resume ready

| xfer | xfer_ended | pointer: infolist with xfer info |
  xfer has ended
|========================================

[NOTE]
^(1)^ 'xxx' is IRC server name, 'yyy' is IRC command name.

* 'callback': function called when signal is received, arguments:
** 'void *data': pointer
** 'const char *signal': signal received
** 'const char *type_data': type of data sent with signal:
*** 'WEECHAT_HOOK_SIGNAL_STRING': string
*** 'WEECHAT_HOOK_SIGNAL_INT': integer number
*** 'WEECHAT_HOOK_SIGNAL_POINTER': pointer
** 'void *signal_data': data sent with signal
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_signal(signal, callback, callback_data)

# example
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# catch signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")
----------------------------------------

weechat_hook_signal_send
^^^^^^^^^^^^^^^^^^^^^^^^

Send a signal.

Prototype:

[source,C]
----------------------------------------
void weechat_hook_signal_send (const char *signal, const char *type_data,
                               void *signal_data);
----------------------------------------

Arguments:

* 'signal': signal to send
* 'type_data': type of data sent with signal (see
  <<_weechat_hook_signal,weechat_hook_signal>>)
* 'signal_data': data sent with signal

C example:

[source,C]
----------------------------------------
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.hook_signal_send(signal, type_data, signal_data)

# example
weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
----------------------------------------

[[signal_logger_backlog]]
Signal logger_backlog
+++++++++++++++++++++

The signal "logger_backlog" can be sent to display backlog (chat history) in
buffer (for example if you open your own buffer in your plugin/script).

Argument is a pointer to buffer.

C example:

[source,C]
----------------------------------------
weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
----------------------------------------

[[signals_xxx_script_install]]
Signals xxx_script_install
++++++++++++++++++++++++++

Five signals can be sent to install a script, according to language:

* 'perl_script_install'
* 'python_script_install'
* 'ruby_script_install'
* 'lua_script_install'
* 'tcl_script_install'

The callback will do following actions when receiving signal:

. unload and remove installed script
. move new script to directory '~/.weechat/xxx/' (where 'xxx' is language) 
. create link to new script in directory '~/.weechat/xxx/autoload/'
. load new script

These signals are used by script 'weeget.py' to install scripts.

Argument is a string with path to script to install.

C example:

[source,C]
----------------------------------------
weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")
----------------------------------------

[[signals_xxx_script_remove]]
Signals xxx_script_remove
+++++++++++++++++++++++++

Five signals can be sent to remove list of scripts, according to language:

* 'perl_script_remove'
* 'python_script_remove'
* 'ruby_script_remove'
* 'lua_script_remove'
* 'tcl_script_remove'

For each script in list, the callback will unload then remove script.

These signals are used by script 'weeget.py' to remove scripts.

Argument is a string with comma-separated list of script to remove (script
is name without path, for example 'script.py').

C example:

[source,C]
----------------------------------------
/* unload and remove scripts test.py and script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# unload and remove scripts test.py and script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----------------------------------------

[[signal_irc_input_send]]
Signal irc_input_send
+++++++++++++++++++++

_New in version 0.3.4._

The signal "irc_input_send" can be sent to simulate input in an irc buffer
(server, channel or private).

Argument is a string with following format:

* internal server name (required)
* semicolon
* channel name (optional)
* semicolon
* flags used when sending message (optional, default is 1):
** '1': queue with high priority (like user messages)
** '2': queue with low priority (like messages automatically sent by WeeChat)
* semicolon
* comma-separated list of tags used when sending message (optional)
* semicolon
* text or command (required)

C examples:

[source,C]
----------------------------------------
/* say "Hello!" on freenode server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* send command "/whois FlashCode" on freenode server, with low priority */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# say "Hello!" on freenode server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# send command "/whois FlashCode" on freenode server, with low priority
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----------------------------------------

weechat_hook_hsignal
^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Hook a hsignal (signal with hashtable).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     void *callback_data);
----------------------------------------

Arguments:

* 'signal': signal to catch, can begin or end with "*"
  (priority allowed, see note about <<hook_priority,priority>>):

[width="100%",cols="^1,^3,5",options="header"]
|========================================
| Plugin | Signal | Arguments

| irc | irc_redirection_xxx_yyy ^(1)^ |
  redirection output (see <<hsignal_irc_redirect_command>>)
|========================================

[NOTE]
^(1)^ 'xxx' is signal argument used in redirection, 'yyy' is redirection
pattern.

* 'callback': function called when signal is received, arguments:
** 'void *data': pointer
** 'const char *signal': signal received
** 'struct t_hashtable *hashtable': hashtable
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_hsignal(signal, callback, callback_data)

# example
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")
----------------------------------------

weechat_hook_hsignal_send
^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Send a hsignal (signal with hashtable).

Prototype:

[source,C]
----------------------------------------
void weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);
----------------------------------------

Arguments:

* 'signal': signal to send
* 'hashtable': hashtable

C example:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.hook_hsignal_send(signal, hashtable)

# example
weechat.hook_hsignal_send("my_hsignal", { "key": "value" })
----------------------------------------

[[hsignal_irc_redirect_command]]
Hsignal irc_redirect_command
++++++++++++++++++++++++++++

_New in version 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'
** '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.

C example:

[source,C]
----------------------------------------
int
test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_INTEGER,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK
}

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          { "server": "freenode", "pattern": "whois", "signal": "test",
                            "string": "FlashCode" })
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----------------------------------------

[[hsignal_irc_redirect_pattern]]
Hsignal irc_redirect_pattern
++++++++++++++++++++++++++++

_New in version 0.3.4._

The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc
redirect (see <<hsignal_irc_redirect_command>>).

Argument is a hashtable with following entries (keys and values are string):

* 'pattern': name of pattern (required)
* 'timeout': default timeout for pattern, in seconds (optional, 60 by default)
* 'cmd_start': comma-separated list of commands starting redirect (optional)
* 'cmd_stop': comma-separated list of commands stopping redirect (required)
* 'cmd_extra': comma-separated list of commands that may be received
  after stop commands (optional)

For each command in 'cmd_start', 'cmd_stop' and 'cmd_extra', it is possible to
give integer with position of "string" that must be found in received message,
for example:

----------------------------------------
352:1,354,401:1
----------------------------------------

For commands 352 and 401, "string" must be found in received message,
as first argument.

[IMPORTANT]
The pattern is destroyed when it is used by a redirection. If you need pattern
for many redirections, you must create pattern before each redirect.

C example:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_INTEGER,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_hsignal_send("irc_redirect_pattern",
                          { "pattern": "my_whois", "timeout": "30",
                            "cmd_start": "311:1",
                            "cmd_stop": "318:1,401:1,402:1,431:1,461",
                            "cmd_extra": "318:1" })
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...
----------------------------------------

weechat_hook_config
^^^^^^^^^^^^^^^^^^^

Hook a configuration option.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);
----------------------------------------

Arguments:

* 'option': option, format is full name, as used with command `/set` (for
  example: `weechat.look.item_time_format`)
  (priority allowed, see note about <<hook_priority,priority>>)
* 'callback': function called when configuration option is changed, arguments:
** 'void *data': pointer
** 'const char *option': name of option
** 'const char *value': new value for option
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch changes to option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_config(option, callback, callback_data)

# example
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# catch changes to option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
----------------------------------------

weechat_hook_completion
^^^^^^^^^^^^^^^^^^^^^^^

Hook a completion.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);
----------------------------------------

Arguments:

* 'completion_item': name of completion item, after you can use '%(name)' in
  a command hooked (argument 'completion')
  (priority allowed, see note about <<hook_priority,priority>>)
* 'description': description of completion
* 'callback': function called when completion item is used (user is completing
  something using this item), arguments:
** 'void *data': pointer
** 'const char *completion_item': name of completion item
** 'struct t_gui_buffer *buffer': buffer where completion is made
** 'struct t_gui_completion *completion': structure used to add words for
   completion (see
   <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>)
* 'callback_data': pointer given to callback when it is called by WeeChat

[NOTE]
Completion names are global (shared accross WeeChat and plugins). So it is
recommended to choose a name with a unique prefix, like "plugin_xxx" (where
"xxx" is your item name).

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_word2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")
----------------------------------------

weechat_hook_completion_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Get a completion property as string.

Prototype:

[source,C]
----------------------------------------
const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);
----------------------------------------

Arguments:

* 'completion': completion pointer
* 'property': property name:
** 'base_command': command used for completion
** 'base_word': word being completed
** 'args': command arguments (including base word)

C example:

[source,C]
----------------------------------------
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_hook_completion_get_string (completion, "args");
    
    /* completion depending on args */
    /* ... */
    
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.hook_completion_get_string(completion, property)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    # get arguments of command
    args = weechat.hook_completion_get_string(completion, "args")
    # completion depending on args
    # ...
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_hook_completion_list_add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a word for a completion.

Prototype:

[source,C]
----------------------------------------
void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);
----------------------------------------

Arguments:

* 'completion': completion pointer
* 'word': word to add
* 'nick_completion': 1 if word is a nick, otherwise 0
* 'where': position where word will be inserted in list:
** 'WEECHAT_LIST_POS_SORT': any position, to keep list sorted
** 'WEECHAT_LIST_POS_BEGINNING': beginning of list
** 'WEECHAT_LIST_POS_END': end of list

C example: see <<_weechat_hook_completion,weechat_hook_completion>>.

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# example: see function hook_completion above
----------------------------------------

weechat_hook_modifier
^^^^^^^^^^^^^^^^^^^^^

Hook a modifier.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);
----------------------------------------

Arguments:

* 'modifier': modifier name, list of modifiers used by Weechat or plugins
  (priority allowed, see note about <<hook_priority,priority>>):

[width="100%",cols="^1,^2,3,4,4",options="header"]
|========================================
| Plugin | Modifier | Modifier data | String | Output

| charset | charset_decode |
  plugin.buffer_name |
  any string |
  string decoded from charset found for plugin/buffer to UTF-8

| charset | charset_encode |
  plugin.buffer_name |
  any string |
  string encoded from UTF-8 to charset found for plugin/buffer

| irc | irc_color_decode |
  "1" to keep colors, "0" to remove colors |
  any string |
  string with WeeChat color codes, or without color

| irc | irc_color_encode |
  "1" to keep colors, "0" to remove colors |
  any string |
  string with IRC color codes, or without color

| irc | irc_in_xxx ^(1)^ |
  server name |
  content of message received from IRC server |
  new content of message

| irc | irc_out_xxx ^(1)^ |
  server name |
  content of message about to be sent to IRC server |
  new content of message

| weechat | bar_condition_yyy ^(2)^ |
  string with window pointer ("0x123..") |
  empty string |
  "1" to display bar, "0" to hide it

| weechat | history_add |
  string with buffer pointer ("0x123..") |
  input buffer (from user) to add in command history (buffer and global) |
  string added to command history

| weechat | input_text_content |
  string with buffer pointer ("0x123..") |
  input buffer (from user) |
  new content of input buffer

| weechat | input_text_display |
  string with buffer pointer ("0x123..") |
  input buffer (from user), without cursor tag |
  new content of input buffer, for display only (input buffer is not changed)

| weechat | input_text_display_with_cursor |
  string with buffer pointer ("0x123..") |
  input buffer (from user), with cursor tag |
  new content of input buffer, for display only (input buffer is not changed)

| weechat | weechat_print |
  plugin;buffer_name;tags |
  message printed |
  new message printed
|========================================

[NOTE]
^(1)^ 'xxx' is IRC command name. +
^(2)^ 'yyy' is bar name.

* 'callback': function called when modifier is used, arguments:
** 'void *data': pointer
** 'const char *modifier': name of modifier
** 'const char *modifier_data': data for modifier
** 'const char *string': string to modify (function must return copy of this
   string, no changes are allowed in this string)
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;
    
    if (!string)
        return NULL;
    
    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* add "xxx" to any message printed */
        snprintf (result, length, "%s xxx", string);
    }
    
    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_modifier(modifier, callback, callback_data)

# example
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
----------------------------------------

weechat_hook_modifier_exec
^^^^^^^^^^^^^^^^^^^^^^^^^^

Execute modifier(s).

Prototype:

[source,C]
----------------------------------------
char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);
----------------------------------------

Arguments:

* 'modifier': modifier name
* 'modifier_data': modifier data
* 'string': string to modify

Return value:

* string modified, NULL if no changes in string were made by modifier(s)

C example:

[source,C]
----------------------------------------
char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.hook_modifier_exec(modifier, modifier_data, string)

# example
weechat.hook_modifier_exec("my_modifier", my_data, my_string)
----------------------------------------

weechat_hook_info
^^^^^^^^^^^^^^^^^

Hook an information (callback takes and returns a string).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);
----------------------------------------

Arguments:

* 'info_name': name of info
  (priority allowed, see note about <<hook_priority,priority>>)
* 'description': description
* 'args_description': description of arguments (optional, can be NULL)
* 'callback': function called when info is asked, arguments:
** 'void *data': pointer
** 'const char *info_name': name of info
** 'const char *arguments': additional arguments, depending on info
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* add info "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# example
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")
----------------------------------------

weechat_hook_info_hashtable
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Hook an information (callback takes and returns a hashtable).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            void *callback_data);
----------------------------------------

Arguments:

* 'info_name': name of info
  (priority allowed, see note about <<hook_priority,priority>>)
* 'description': description
* 'args_description': description of expected hashtable (optional, can be NULL)
* 'output_description': description of hashtable returned by callback
  (optional, can be NULL)
* 'callback': function called when info is asked, arguments:
** 'void *data': pointer
** 'const char *info_name': name of info
** 'struct t_hashtable *hashtable': hashtable, depending on info
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
struct t_hashtable *
my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# example
def my_info_hashtable_cb(data, info_name, hashtable):
    return { "test_key": "test_value" }

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")
----------------------------------------

weechat_hook_infolist
^^^^^^^^^^^^^^^^^^^^^

Hook an infolist: callback will return pointer to infolist asked.

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      const char *(*callback)(void *data,
                                                              const char *infolist_name,
                                                              void *pointer,
                                      const char *arguments),
                                      void *callback_data);
----------------------------------------

Arguments:

* 'infolist_name': name of infolist
  (priority allowed, see note about <<hook_priority,priority>>)
* 'description': description
* 'pointer_description': description of pointer (optional, can be NULL)
* 'args_description': description of arguments (optional, can be NULL)
* 'callback': function called when infolist is asked, arguments:
** 'void *data': pointer
** 'const char *infolist_name': name of infolist
** 'void *pointer': pointer to an object that infolist must return (to get only
   one item in infolist)
** 'const char *arguments': additional arguments, depending on infolist
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new hook, NULL if error occured

C example:

[source,C]
----------------------------------------
struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;
    
    /* build infolist */
    /* ... */
    
    return my_infolist;
}

/* add infolist "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# example
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")
----------------------------------------

weechat_unhook
^^^^^^^^^^^^^^

Unhook something hooked.

Prototype:

[source,C]
----------------------------------------
void weechat_unhook (struct t_hook *hook);
----------------------------------------

Arguments:

* 'hook': something hooked with "weechat_hook_xxx()"

C example:

[source,C]
----------------------------------------
struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.unhook(hook)

# example
weechat.unhook(my_hook)
----------------------------------------

weechat_unhook_all
^^^^^^^^^^^^^^^^^^

Unhook everything that has been hooked by current plugin.

Prototype:

[source,C]
----------------------------------------
void weechat_unhook_all ();
----------------------------------------

C example:

[source,C]
----------------------------------------
weechat_unhook_all ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.unhook_all()

# example
weechat.unhook_all()
----------------------------------------

[[buffers]]
Buffers
~~~~~~~

Functions to create/query/close buffers.

weechat_buffer_new
^^^^^^^^^^^^^^^^^^

Open a new buffer.

Prototype:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);
----------------------------------------

Arguments:

* 'name': name of buffer (must be unique for plugin)
* 'input_callback': function called when input text is entered on buffer,
  arguments:
*** 'void *data': pointer
*** 'struct t_gui_buffer *buffer': buffer pointer
*** 'const char *input_data': input data
* 'callback_data': pointer given to callback when it is called by WeeChat
* 'close_callback': function called when buffer is closed, arguments:
*** 'void *data': pointer
*** 'struct t_gui_buffer *buffer': buffer pointer
* 'callback_data': pointer given to callback when it is called by WeeChat

Return value:

* pointer to new buffer, NULL if error occured

C example:

[source,C]
----------------------------------------
int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Text: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Buffer '%s' will be closed!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# example
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Text: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
----------------------------------------

weechat_current_buffer
^^^^^^^^^^^^^^^^^^^^^^

Return pointer to current buffer (buffer displayed by current window).

Prototype:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_current_buffer ();
----------------------------------------

Return value:

* pointer to current buffer

C example:

[source,C]
----------------------------------------
weechat_printf (weechat_current_buffer (), "Text on current buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
buffer = weechat.current_buffer()

# example
weechat.prnt(weechat.current_buffer(), "Text on current buffer")
----------------------------------------

weechat_buffer_search
^^^^^^^^^^^^^^^^^^^^^

Search a buffer by plugin and/or name.

Prototype:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);
----------------------------------------

Arguments:

* 'plugin': name of plugin
* 'name': name of buffer, if it is NULL or empty string, the current buffer is
  returned (buffer displayed by current window)

Return value:

* pointer to buffer found, NULL if not found

C example:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
buffer = weechat.buffer_search(plugin, name)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")
----------------------------------------

weechat_buffer_search_main
^^^^^^^^^^^^^^^^^^^^^^^^^^

Search WeeChat main buffer ('core' buffer, first buffer displayed when WeeChat
is starting).

Prototype:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search_main ();
----------------------------------------

Return value:

* pointer to WeeChat main buffer ('core' buffer)

C example:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
buffer = weechat.buffer_search_main()

# example
buffer = weechat.buffer_search_main()
----------------------------------------

weechat_buffer_clear
^^^^^^^^^^^^^^^^^^^^

Clear content of a buffer.

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_clear (struct t_gui_buffer *buffer);
----------------------------------------

Arguments:

* 'buffer': buffer pointer

C example:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.buffer_clear(buffer)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)
----------------------------------------

weechat_buffer_close
^^^^^^^^^^^^^^^^^^^^

Close a buffer.

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_close (struct t_gui_buffer *buffer);
----------------------------------------

Arguments:

* 'buffer': buffer pointer

C example:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.buffer_close(buffer)

# example
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----------------------------------------

weechat_buffer_merge
^^^^^^^^^^^^^^^^^^^^

Merge buffer into another buffer: both buffers will still exist separately, but
with same number, and WeeChat will display lines from both buffers (mixed
lines).

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'target_buffer': target buffer, where buffer will be merged

C example:

[source,C]
----------------------------------------
/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.buffer_merge(buffer, target_buffer)

# example
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----------------------------------------

weechat_buffer_unmerge
^^^^^^^^^^^^^^^^^^^^^^

Unmerge buffer from a group of merged buffers.

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'number': target number for detached buffer, if it is < 1, then buffer will
  be moved to number of 'buffer' + 1

C example:

[source,C]
----------------------------------------
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.buffer_unmerge(buffer, number)

# example
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----------------------------------------

weechat_buffer_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Return integer value of a buffer property.

Prototype:

[source,C]
----------------------------------------
int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'property': property name:
** 'number': number of buffer (starts with 1)
** 'layout_number': number of buffer saved in layout
** 'type': buffer type (0: formatted, 1: free content)
** 'notify': notify level for buffer
** 'num_displayed': number of windows displaying buffer
** 'active': 1 if buffer is active, 0 if buffer is merged and not selected
** 'print_hooks_enabled': 1 if print hooks are enabled, otherwise 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_visible_count': number of nicks/groups displayed
** 'input': 1 if input is enabled, otherwise 0
** 'input_get_unknown_commands': 1 if unknown commands are sent to input
   callback, otherwise 0
** 'input_size': input size (in bytes)
** 'input_length': input length (number of chars)
** 'input_pos': cursor position in buffer input
** 'input_1st_display': first char displayed on screen
** 'num_history': number of commands in history
** 'text_search': text search type:
*** 0: no search at this moment
*** 1: backward search (direction: oldest messages)
*** 2: forward search (direction: newest messages)
** 'text_search_exact': 1 if text search is case sensitive
** 'text_search_found': 1 if text found, otherwise 0

Return value:

* integer value of property

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.buffer_get_integer(buffer, property)

# example
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
----------------------------------------

weechat_buffer_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Return string value of a buffer property.

Prototype:

[source,C]
----------------------------------------
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'property': property name:
** 'plugin': name of plugin which created this buffer ("core" for WeeChat main
   buffer)
** 'name': name of buffer
** 'short_name': short name of buffer
** 'title': title of buffer
** 'input': input text
** 'text_search_input': input saved before text search
** 'highlight_words': list of words to highlight
** 'highlight_tags': list of tags to highlight
** 'hotlist_max_level_nicks': max hotlist level for some nicks
** 'localvar_xxx': get content of local variable "xxx" (replace "xxx" by the
   name of variable to read)

Return value:

* string value of property

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.buffer_get_string(buffer, property)

# example
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))
----------------------------------------

weechat_buffer_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Return pointer value of a buffer property.

Prototype:

[source,C]
----------------------------------------
void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'property': property name:
** 'plugin': pointer to plugin which created this buffer (NULL for WeeChat main
   buffer)

Return value:

* pointer value of property

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "plugin pointer of my buffer: %lx",
                weechat_buffer_get_pointer (my_buffer, "plugin"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.buffer_get_pointer(buffer, property)

# example
weechat.prnt("", "plugin pointer of my buffer: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----------------------------------------

weechat_buffer_set
^^^^^^^^^^^^^^^^^^

Set string value of a buffer property.

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'property' and 'value': property name, with its value:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Name | Value | Description

| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT |
  "+": enable hotlist (global setting, buffer pointer is not used) +
  "-": disable hotlist (global setting, buffer pointer is not used) +
  priority: add buffer to hotlist with this priority

| unread | - |
  set unread marker after last line of buffer

| display | "1", "auto" |
  "1": switch to this buffer in current window +
  "auto": switch to this buffer in current window, read marker is not reset

| number | number |
  move buffer to this number

| name | any string |
  set new name for buffer

| short_name | any string |
  set new short name for buffer

| type | "formatted" or "free" |
  set type for buffer: "formatted" (for printing chat messages), or "free" (for
  free content)

| notify | "0", "1", "2", "3" |
  set notify level for buffer: "0" = never add to hotlist, "1" = add for
  highlights only, "2" = add for highlights and messages, "3" = add for all
  messages

| title | any string |
  set new title for buffer

| time_for_each_line | "0" or "1" |
  "0" to hide time for all lines in buffer, "1" to see time for all lines
  (default for a new buffer)

| nicklist | "0" or "1" |
  "0" to remove nicklist for buffer, "1" to add nicklist for buffer

| nicklist_case_sensitive | "0" or "1" |
  "0" to have case insensitive nicklist, "1" to have case sensitive nicklist

| nicklist_display_groups | "0" or "1" |
  "0" to hide nicklist groups, "1" to display nicklist groups

| highlight_words | "-" or comma separated list of words |
  "-" is a special value to disable any highlight on this buffer, or comma
  separated list of words to highlight in this buffer, for example:
  "abc,def,ghi"

| highlight_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_tags | comma separated list of tags |
  comma separated list of tags to highlight in this buffer

| 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 behaviour), "1" to
  get unknown commands, for example if user type "/unknowncmd", buffer will
  receive it (no error about unknown command)

| localvar_set_xxx | any string |
  set new value for local variable 'xxx' (variable is created if it does not
  exist)

| localvar_del_xxx | - |
  remove local variable 'xxx'
|========================================

C example:

[source,C]
----------------------------------------
/* disable hotlist (for all buffers) */
weechat_buffer_set (NULL, "hotlist", "-");

/* enable again hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* change buffer name */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* add new local variable "toto" with value "abc" */
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

/* remove local variable "toto" */
weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.buffer_set(buffer, property, value)

# examples

# disable hotlist (for all buffers)
weechat.buffer_set("", "hotlist", "-")

# enable again hotlist
weechat.buffer_set("", "hotlist", "+")

# change buffer name
weechat.buffet_set(my_buffer, "name", "my_new_name")

# add new local variable "toto" with value "abc"
weechat.buffet_set(my_buffer, "localvar_set_toto", "abc")

# remove local variable "toto"
weechat.buffet_set(my_buffer, "localvar_del_toto", "")
----------------------------------------

weechat_buffer_set_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Set pointer value of a buffer property.

Prototype:

[source,C]
----------------------------------------
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'property' and 'value': property name, with its value:
** 'close_callback': set close callback function
** 'close_callback_data': set close callback data
** 'input_callback': set input callback function
** 'input_callback_data': set input callback data

C example:

[source,C]
----------------------------------------
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_buffer_string_replace_local_var
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Replace local variables in a string by their values, using buffer local
variables.

Prototype:

[source,C]
----------------------------------------
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'string': string with text and local variables using format "$var"

Return value:

* string with values of local variables

C example:

[source,C]
----------------------------------------
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contains "test with abc" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.buffer_string_replace_local_var(buffer, string)

# example
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"
----------------------------------------

[[windows]]
Windows
~~~~~~~

Functions to query windows.

weechat_current_window
^^^^^^^^^^^^^^^^^^^^^^

Return pointer to current window.

Prototype:

[source,C]
----------------------------------------
struct t_gui_window *weechat_current_window ();
----------------------------------------

Return value:

* pointer to current window

C example:

[source,C]
----------------------------------------
struct t_gui_window *current_window = weechat_current_window ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
window = weechat.current_window()

# example
current_window = weechat.current_window()
----------------------------------------

weechat_window_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Return integer value of a window property.

Prototype:

[source,C]
----------------------------------------
int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);
----------------------------------------

Arguments:

* 'window': window pointer
* 'property': property name:
** 'win_x': X position of window in terminal (first column is 0)
** 'win_y': Y position of window in terminal (first line is 0)
** 'win_width': width of window, in chars
** 'win_height': height of window, in chars
** 'win_width_pct': percentage size, compared to parent window (for example 50
   means half size)
** 'win_height_pct': percentage size, compared to parent window (for example 50
   means half size)
** 'win_chat_x': X position of chat window in terminal (first column is 0)
** 'win_chat_y': Y position of chat window in terminal (first line is 0)
** 'win_chat_width': width of chat window, in chars
** 'win_chat_height': height of chat window, in chars
** 'first_line_displayed': 1 if first line of buffer is displayed on screen,
   otherwise 0
** 'scroll': 1 if scroll is active on window (last line not displayed)
** 'scroll_lines_after': number of lines not displayed after last one
   displayed (when scrolling)

Return value:

* integer value of property

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.window_get_integer(window, property)

# example
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))
----------------------------------------

weechat_window_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Return string value of a window property.

[NOTE]
This function is not used today, it is reserved for a future version.

Prototype:

[source,C]
----------------------------------------
int weechat_window_get_string (struct t_gui_window *window,
                               const char *property);
----------------------------------------

Arguments:

* 'window': window pointer
* 'property': property name

Return value:

* string value of property

weechat_window_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Return pointer value of a window property.

Prototype:

[source,C]
----------------------------------------
void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);
----------------------------------------

Arguments:

* 'window': window pointer
* 'property': property name:
** 'current': current window pointer
** 'buffer': pointer to buffer displayed by window

Return value:

* pointer value of property

C example:

[source,C]
----------------------------------------
weechat_printf (NULL,
                "buffer displayed in current window: %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.window_get_pointer(window, property)

# example
weechat.prnt("", "buffer displayed in current window: %lx"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----------------------------------------

weechat_window_set_title
^^^^^^^^^^^^^^^^^^^^^^^^

Set title for terminal.

Prototype:

[source,C]
----------------------------------------
void weechat_window_set_title (const char *title);
----------------------------------------

Arguments:

* 'title': new title for terminal (NULL to reset title)

C example:

[source,C]
----------------------------------------
weechat_window_set_title ("new title here");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.window_set_title(window, title)

# example
weechat.window_set_title("new title here")
----------------------------------------

[[nicklist]]
Nicklist
~~~~~~~~

Functions for buffer nicklist.

weechat_nicklist_add_group
^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a group in a nicklist.

Prototype:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'parent_group': pointer to parent of group, NULL if group has no parent
  (nicklist root)
* 'name': group name
* 'visible':
** '1': group and sub-groups/nicks are visible
** '0': group and sub-groups/nicks are hidden
* 'color': color option name:
** WeeChat option name, for example 'weechat.color.nicklist_group'
** color with optional background, for example 'yellow' or 'yellow,red'
** bar color name:
*** 'bar_fg': foreground color for bar
*** 'bar_delim': delimiters color for bar
*** 'bar_bg': background color for bar

[NOTE]
The group name can begin with one or more digits, followed by pipe, and then
group name. When such string is found at beginning, it's used to sort groups
in nicklist. For example groups "1|test" and "2|abc" will be displayed in that
order: first "test" then "abc".

Return value:

* pointer to new group, NULL if an error occured

C example:

[source,C]
----------------------------------------
struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# example
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)
----------------------------------------

weechat_nicklist_search_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search a group in a nicklist.

Prototype:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'from_group': search from this group only, if NULL, then search in whole
  nicklist
* 'name': group name to search

Return value:

* pointer to group found, NULL if not found

C example:

[source,C]
----------------------------------------
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "test_group");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
group = weechat.nicklist_search_group(buffer, from_group, name)

# example
group = weechat.nicklist_search_group(my_buffer, "", "test_group")
----------------------------------------

weechat_nicklist_add_nick
^^^^^^^^^^^^^^^^^^^^^^^^^

Add a nick in a group.

Prototype:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer
* 'name': nick name
* 'color': color option name:
*** WeeChat option name (from weechat.color.xxx), for example 'chat_delimiters'
*** color with optional background, for example 'yellow' or 'yellow,red'
*** bar color name:
**** 'bar_fg': foreground color for bar
**** 'bar_delim': delimiters color for bar
**** 'bar_bg': background color for bar
* 'prefix': prefix displayed before nick
* 'prefix_color': color option name:
** WeeChat option name (from weechat.color.xxx), for example 'chat_delimiters'
** color with optional background, for example 'yellow' or 'yellow,red'
** bar color name:
*** 'bar_fg': foreground color for bar
*** 'bar_delim': delimiters color for bar
*** 'bar_bg': background color for bar
* 'visible':
** '1': nick is visible
** '0': nick is hidden

Return value:

* pointer to new nick, NULL if an error occured

C example:

[source,C]
----------------------------------------
struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# example
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
----------------------------------------

weechat_nicklist_search_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Search a nick in a nicklist.

Prototype:

[source,C]
----------------------------------------
struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'from_group': search from this group only, if NULL, then search in whole
  nicklist
* 'name': nick name to search

Return value:

* pointer to nick found, NULL if not found

C example:

[source,C]
----------------------------------------
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# example
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
----------------------------------------

weechat_nicklist_remove_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove a group from a nicklist.

Prototype:

[source,C]
----------------------------------------
void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer to remove (all sub-groups/nicks will be removed too)

C example:

[source,C]
----------------------------------------
weechat_nicklist_remove_group (my_buffer, my_group);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.nicklist_remove_group(buffer, group)

# example
weechat.nicklist_remove_group(my_buffer, my_group)
----------------------------------------

weechat_nicklist_remove_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove a nick from a nicklist.

Prototype:

[source,C]
----------------------------------------
void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'nick': nick pointer to remove

C example:

[source,C]
----------------------------------------
weechat_nicklist_remove_nick (my_buffer, my_nick);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.nicklist_remove_nick(buffer, nick)

# example
weechat.nicklist_remove_nick(my_buffer, my_nick)
----------------------------------------

weechat_nicklist_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove all groups/nicks from a nicklist.

Prototype:

[source,C]
----------------------------------------
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
----------------------------------------

Arguments:

* 'buffer': buffer pointer

C example:

[source,C]
----------------------------------------
weechat_nicklist_remove_all (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.nicklist_remove_all(buffer)

# example
weechat.nicklist_remove_all(my_buffer)
----------------------------------------

weechat_nicklist_group_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return integer value of a group property.

Prototype:

[source,C]
----------------------------------------
int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer
* 'property': property name:
** 'visible': 1 if group is visible, otherwise 0
** 'level': group level (root is 0)

Return value:

* integer value of property

C example:

[source,C]
----------------------------------------
int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_group_get_integer(buffer, group, property)

# example
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")
----------------------------------------

weechat_nicklist_group_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return string value of a group property.

Prototype:

[source,C]
----------------------------------------
const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer
* 'property': property name:
** 'name': name of group
** 'color': group color in nicklist

Return value:

* string value of property

C example:

[source,C]
----------------------------------------
const char *color = weechat_nicklist_group_get_string (buffer, group, "color");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_group_get_string(buffer, group, property)

# example
color = weechat.nicklist_group_get_string(buffer, group, "color")
----------------------------------------

weechat_nicklist_group_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return pointer value of a group property.

Prototype:

[source,C]
----------------------------------------
void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer
* 'property': property name:
** 'parent': pointer to parent group

Return value:

* pointer value of property

C example:

[source,C]
----------------------------------------
struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_group_get_pointer(buffer, group, property)

# example
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")
----------------------------------------

weechat_nicklist_group_set
^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Set string value of a group property.

Prototype:

[source,C]
----------------------------------------
void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'group': group pointer
* 'property' and 'value': property name, with its value:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Name | Value | Description

| color | WeeChat color option name |
  see argument "color" of function
  <<_weechat_nicklist_add_group,weechat_nicklist_add_group>>

| visible | "0", "1" |
  "0" = hidden group, "1" = visible group
|========================================

C examples:

[source,C]
----------------------------------------
/* change group color to "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* change group color to yellow */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* hide group in nicklist */
weechat_nicklist_group_set (buffer, group, "visible", "0");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.nicklist_group_set(buffer, group, property, value)

# examples

# change group color to "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# change group color to yellow
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# hide group in nicklist
weechat.nicklist_group_set(buffer, group, "visible", "0")
----------------------------------------

weechat_nicklist_nick_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return integer value of a nick property.

Prototype:

[source,C]
----------------------------------------
int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'nick': nick pointer
* 'property': property name:
** 'visible': 1 if nick is visible, otherwise 0

Return value:

* integer value of property

C example:

[source,C]
----------------------------------------
int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_nick_get_integer(buffer, nick, property)

# example
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")
----------------------------------------

weechat_nicklist_nick_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return string value of a nick property.

Prototype:

[source,C]
----------------------------------------
const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'nick': nick pointer
* 'property': property name:
** 'name': name of nick
** 'color': nick color in nicklist
** 'prefix': prefix of nick
** 'prefix_color': prefix color in nicklist

Return value:

* string value of property

C example:

[source,C]
----------------------------------------
const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_nick_get_string(buffer, nick, property)

# example
color = weechat.nicklist_nick_get_string(buffer, nick, "color")
----------------------------------------

weechat_nicklist_nick_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return pointer value of a nick property.

Prototype:

[source,C]
----------------------------------------
void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'nick': nick pointer
* 'property': property name:
** 'group': pointer to group containing this nick

Return value:

* pointer value of property

C example:

[source,C]
----------------------------------------
struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.nicklist_nick_get_pointer(buffer, nick, property)

# example
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")
----------------------------------------

weechat_nicklist_nick_set
^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Set string value of a nick property.

Prototype:

[source,C]
----------------------------------------
void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);
----------------------------------------

Arguments:

* 'buffer': buffer pointer
* 'nick': nick pointer
* 'property' and 'value': property name, with its value:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Name | Value | Description

| color | WeeChat color option name |
  see argument "color" of function
  <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>>

| prefix | any string |
  prefix of nick

| prefix_color | WeeChat color option name |
  see argument "prefix_color" of function
  <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>>

| visible | "0", "1" |
  "0" = hidden nick, "1" = visible nick
|========================================

C examples:

[source,C]
----------------------------------------
/* change nick color to cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* change prefix to "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* change prefix color to yellow */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* hide nick in nicklist */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.nicklist_nick_set(buffer, nick, property, value)

# examples

# change nick color to cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# change prefix to "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# change prefix color to yellow
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# hide nick in nicklist
weechat.nicklist_nick_set(buffer, nick, "visible", "0")
----------------------------------------

[[bars]]
Bars
~~~~

Functions for bars.

weechat_bar_item_search
^^^^^^^^^^^^^^^^^^^^^^^

Search a bar item.

Prototype:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
----------------------------------------

Arguments:

* 'name': bar item name

Return value:

* pointer to bar item found, NULL if bar item was not found

C example:

[source,C]
----------------------------------------
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
bar_item = weechat.bar_item_search(name)

# example
bar_item = weechat.bar_item_search("myitem")
----------------------------------------

weechat_bar_item_new
^^^^^^^^^^^^^^^^^^^^

Create a new bar item.

Prototype:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(build_callback)(void *data,
                                                                    struct t_gui_bar_item *item,
                                                                    struct t_gui_window *window),
                                             void *build_callback_data);
----------------------------------------

Arguments:

* 'name': bar item name
* 'build_callback': function called when bar item is built: it must return
  content of bar item
* 'build_callback_data': pointer given to build callback, when it is called by
  WeeChat

Return value:

* pointer to new bar item, NULL if an error occured

C example:

[source,C]
----------------------------------------
char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# example
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")
----------------------------------------

weechat_bar_item_update
^^^^^^^^^^^^^^^^^^^^^^^

Update content of a bar item, by calling its build callback.

Prototype:

[source,C]
----------------------------------------
void weechat_bar_item_update (const char *name);
----------------------------------------

Arguments:

* 'name': bar item name

C example:

[source,C]
----------------------------------------
weechat_bar_item_update ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.bar_item_update(name)

# example
weechat.bar_item_update("myitem")
----------------------------------------

weechat_bar_item_remove
^^^^^^^^^^^^^^^^^^^^^^^

Remove a bar item.

Prototype:

[source,C]
----------------------------------------
void weechat_bar_item_remove (struct t_gui_bar_item *item);
----------------------------------------

Arguments:

* 'item': bar item pointer

C example:

[source,C]
----------------------------------------
weechat_bar_item_remove (&my_item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.bar_item_remove(item)

# example
weechat.bar_item_remove(myitem)
----------------------------------------

weechat_bar_search
^^^^^^^^^^^^^^^^^^

Search a bar.

Prototype:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_search (const char *name);
----------------------------------------

Arguments:

* 'name': bar name

Return value:

* pointer to bar found, NULL if bar was not found

C example:

[source,C]
----------------------------------------
struct t_gui_bar *bar = weechat_bar_search ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
bar = weechat.bar_search(name)

# example
bar = weechat.bar_search("mybar")
----------------------------------------

weechat_bar_new
^^^^^^^^^^^^^^^

Create a new bar.

Prototype:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *separator,
                                   const char *items);
----------------------------------------

Arguments:

* 'name': bar name
* 'hidden':
** 'on': bar is hidden
** 'off': bar is visible
* 'priority': bar priority (integer)
* 'type':
** 'root': bar displayed once, outside windows
** 'window': bar displayed in each window
* 'condition': condition for displaying bar:
** 'active': bar is displayed in active window only
** 'inactive': bar is displayed in inactive windows only
** 'nicklist': bar is displayed in windows with nicklist
* 'position': 'top', 'bottom', 'left' or 'right'
* 'filling_top_bottom':
** 'horizontal': items are filled horizontally (space after each item)
** 'vertical': items are filled vertically (new line after each item)
** 'columns_horizontal': items are filled horizontally, displayed with columns
** 'columns_vertical': items are filled vertically, displayed with columns
* 'filling_left_right':
** 'horizontal': items are filled horitontally (space after each item)
** 'vertical': items are filled verticaly (new line after each item)
** 'columns_horizontal': items are filled horizontally, displayed with columns
** 'columns_vertical': items are filled vertically, displayed with columns
* 'size': bar size in chars (0 means automatic size)
* 'size_max': max size for bar (0 means no max size)
* 'color_fg': color for text in bar
* 'color_delim': color for delimiters in bar
* 'color_bg': background color for bar
* 'separator':
** 'on': bar has separator line with other windows/bars
** 'off': no separator
* 'items': list of items in bar, separated by comma (space between items), or
  "+" (glued items)

Return value:

* pointer to new bar, NULL if an error occured

C example:

[source,C]
----------------------------------------
struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
                                            "off",
                                            100,
                                            "window",
                                            "",
                                            "top",
                                            "horizontal",
                                            "vertical",
                                            "0",
                                            "5",
                                            "default",
                                            "cyan",
                                            "blue",
                                            "off",
                                            "time,buffer_number+buffer_name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# example
bar = weechat.bar_new("mybar", "off", 100, "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
----------------------------------------

weechat_bar_set
^^^^^^^^^^^^^^^

Set a new value for a bar property.

Prototype:

[source,C]
----------------------------------------
int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);
----------------------------------------

Arguments:

* 'bar': bar pointer
* 'property': name, hidden, priority, conditions, position, filling_top_bottom,
  filling_left_right, size, size_max, color_fg, color_delim, color_bg,
  separator, items (see <<_weechat_bar_new,weechat_bar_new>>)
* 'value': new value for property

Return value:

* 1 if new value was set, 0 if an error occured

C example:

[source,C]
----------------------------------------
weechat_bar_set (mybar, "position", "bottom");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.bar_set(bar, property, value)

# example
weechat.bar_set(my_bar, "position", "bottom")
----------------------------------------

weechat_bar_update
^^^^^^^^^^^^^^^^^^

Refresh content of a bar on screen.

Prototype:

[source,C]
----------------------------------------
void weechat_bar_update (const char *name);
----------------------------------------

Arguments:

* 'name': bar name

C example:

[source,C]
----------------------------------------
weechat_bar_update ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.bar_update(name)

# example
weechat.bar_update("mybar")
----------------------------------------

weechat_bar_remove
^^^^^^^^^^^^^^^^^^

Remove a bar.

Prototype:

[source,C]
----------------------------------------
void weechat_bar_remove (struct t_gui_bar *bar);
----------------------------------------

Arguments:

* 'bar': bar pointer

C example:

[source,C]
----------------------------------------
weechat_bar_remove (mybar);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.bar_remove(bar)

# example
weechat.bar_remove(my_bar)
----------------------------------------

[[commands]]
Commands
~~~~~~~~

Functions for executing WeeChat commands.

weechat_command
^^^^^^^^^^^^^^^

Execute a command.

Prototype:

[source,C]
----------------------------------------
void weechat_command (struct t_gui_buffer *buffer, const char *command);
----------------------------------------

Arguments:

* 'buffer': buffer pointer (command is executed on this buffer, use NULL for
  WeeChat core buffer)
* 'command': command to execute (if beginning with a "/"), or text to send to
  buffer

C example:

[source,C]
----------------------------------------
weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                 "/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.command(buffer, command)

# example
weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
----------------------------------------

[[network]]
Network
~~~~~~~

Network functions.

weechat_network_pass_proxy
^^^^^^^^^^^^^^^^^^^^^^^^^^

Establish a connection/authentification to a proxy.

Prototype:

[source,C]
----------------------------------------
int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);
----------------------------------------

Arguments:

* 'proxy': proxy name to use
* 'sock': socket to use
* 'address': address (hostname or IP address)
* 'port': port

Return value:

* 1 if connection is ok, 0 if an error occured

C example:

[source,C]
----------------------------------------
if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* error */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_network_connect_to
^^^^^^^^^^^^^^^^^^^^^^^^^^

Establish a connection to a remote host.

Prototype:

[source,C]
----------------------------------------
int weechat_network_connect_to (const char *proxy,
                                int sock,
                                unsigned long address,
                                int port);
----------------------------------------

Arguments:

* 'proxy': proxy name to use
* 'sock': socket to use
* 'address': address
* 'port': port

Return value:

* 1 if connection is ok, 0 if an error occured

C example:

[source,C]
----------------------------------------
struct sockaddr_in addr;
socklen_t length;
unsigned long address;

memset (&addr, 0, sizeof (struct sockaddr_in));
length = sizeof (addr);
getsockname (sock, (struct sockaddr *) &addr, &length);
addr.sin_family = AF_INET;
address = ntohl (addr.sin_addr.s_addr);

if (weechat_network_connect_to (NULL, sock, address, 6667))
{
    /* OK */
}
else
{
    /* error */
}
----------------------------------------

[NOTE]
This function is not available in scripting API.

[[infos]]
Infos
~~~~~

Functions to get infos.

weechat_info_get
^^^^^^^^^^^^^^^^

Return info, as string, from WeeChat or a plugin.

Prototype:

[source,C]
----------------------------------------
const char *weechat_info_get (const char *info_name, const char *arguments);
----------------------------------------

Arguments:

* 'info_name': name of info to read:
include::autogen/plugin_api/infos.txt[]
* 'arguments': arguments for info asked (optional, NULL if no argument is
  needed)

Return value:

* string with info asked, NULL if an error occured

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                weechat_info_get ("version", NULL),
                weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
                weechat_info_get ("weechat_dir", NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.info_get(info_name, arguments)

# example
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir", ""))
----------------------------------------

weechat_info_get_hashtable
^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Return info, as hashtable, from WeeChat or a plugin.

Prototype:

[source,C]
----------------------------------------
struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);
----------------------------------------

Arguments:

* 'info_name': name of info to read:
include::autogen/plugin_api/infos_hashtable.txt[]
* '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 occured

C example:

[source,C]
----------------------------------------
struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (hashtable_in, "message",
                           ":nick!user@host PRIVMSG #weechat :message here");
    hashtable_out = weechat_info_get_hashtable ("irc_parse_message",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "nick"     : "nick"
     *   "host"     : "nick!user@host"
     *   "command"  : "PRIVMSG"
     *   "channel"  : "#weechat"
     *   "arguments": "#weechat :message here"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
dict = weechat.info_get_hashtable(info_name, dict_in)

# example
dict_in = { "message": ":nick!user@host PRIVMSG #weechat :message here" }
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_parse_message", dict_in))
----------------------------------------

[[infolists]]
Infolists
~~~~~~~~~

An infolist is a list of "items". Each item contains variables.

For example, infolist "irc_server" has N items (N is number of IRC servers
defined). For each item, there is variables like "name", "buffer",
"is_connected", ...

Each variable has a type and a value. Possible types are:

* 'integer': any integer value
* 'string': any string value
* 'pointer': any pointer
* 'buffer': buffer with fixed length, containing any data
* 'time': time value

weechat_infolist_new
^^^^^^^^^^^^^^^^^^^^

Create a new infolist.

Prototype:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_new ();
----------------------------------------

Return value:

* pointer to new infolist

C example:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_new ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
infolist = weechat.infolist_new()

# example
infolist = weechat.infolist_new()
----------------------------------------

weechat_infolist_new_item
^^^^^^^^^^^^^^^^^^^^^^^^^

Add an item in an infolist.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

Return value:

* pointer to new item

C example:

[source,C]
----------------------------------------
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
item = weechat.infolist_new_item(infolist)

# example
item = weechat.infolist_new_item(infolist)
----------------------------------------

weechat_infolist_new_var_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add an integer variable to an infolist item.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);
----------------------------------------

Arguments:

* 'item': infolist item pointer
* 'name': variable name
* 'value': integer value

Return value:

* pointer to new variable

C example:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
var = weechat.infolist_new_var_integer(item, name, value)

# example
var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----------------------------------------

weechat_infolist_new_var_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a string variable to an infolist item.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);
----------------------------------------

Arguments:

* 'item': infolist item pointer
* 'name': variable name
* 'value': string value

Return value:

* pointer to new variable

C example:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
var = weechat.infolist_new_var_string(item, name, value)

# example
var = weechat.infolist_new_var_string(item, "my_string", "value")
----------------------------------------

weechat_infolist_new_var_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a pointer variable to an infolist item.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);
----------------------------------------

Arguments:

* 'item': infolist item pointer
* 'name': variable name
* 'pointer': pointer

Return value:

* pointer to new variable

C example:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
var = weechat.infolist_new_var_pointer(item, name, pointer)

# example
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----------------------------------------

weechat_infolist_new_var_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a buffer variable to an infolist item.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);
----------------------------------------

Arguments:

* 'item': infolist item pointer
* 'name': variable name
* 'pointer': pointer to buffer
* 'size': size of buffer

Return value:

* pointer to new variable

C example:

[source,C]
----------------------------------------
char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item,
                                                                   "my_buffer",
                                                                   &buffer,
                                                                   sizeof (buffer));
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_infolist_new_var_time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Add a time variable to an infolist item.

Prototype:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);
----------------------------------------

Arguments:

* 'item': infolist item pointer
* 'name': variable name
* 'time': time value

Return value:

* pointer to new variable

C example:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_variable_time (item,
                                                                 "my_time",
                                                                 time (NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
var = weechat.infolist_new_var_time(item, name, time)

# example
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
----------------------------------------

weechat_infolist_get
^^^^^^^^^^^^^^^^^^^^

Return infolist from WeeChat or a plugin.

Prototype:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);
----------------------------------------

Arguments:

* 'infolist_name': name of infolist to read:
include::autogen/plugin_api/infolists.txt[]
* 'pointer': pointer to an item, to get only this item in infolist (optional,
  can be NULL)
* 'arguments': arguments for infolist asked (optional, NULL if no argument is
  needed)

Return value:

* pointer to infolist, NULL if an error occured

C example:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# example
infolist = weechat.infolist_get("irc_server, "", "")
----------------------------------------

weechat_infolist_next
^^^^^^^^^^^^^^^^^^^^^

Move "cursor" to next item in an infolist. The first call to this function for
an infolist moves cursor to first item in infolist.

Prototype:

[source,C]
----------------------------------------
int weechat_infolist_next (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

Return value:

* 1 if cursor has been moved on next item, 0 if end of list was reached

C example:

[source,C]
----------------------------------------
if (weechat_infolist_next (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.infolist_next(infolist)

# example
rc = weechat.infolist_next(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----------------------------------------

weechat_infolist_prev
^^^^^^^^^^^^^^^^^^^^^

Move "cursor" to previous item in an infolist. The first call to this function
for an infolist moves cursor to last item in infolist.

Prototype:

[source,C]
----------------------------------------
int weechat_infolist_prev (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

Return value:

* 1 if cursor has been moved on previous item, 0 if beginning of list was
  reached

C example:

[source,C]
----------------------------------------
if (weechat_infolist_prev (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.infolist_prev(infolist)

# example
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----------------------------------------

weechat_infolist_reset_item_cursor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Reset "cursor" for infolist.

Prototype:

[source,C]
----------------------------------------
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

C example:

[source,C]
----------------------------------------
weechat_infolist_reset_item_cursor (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.infolist_reset_item_cursor(infolist)

# example
weechat.infolist_reset_item_cursor(infolist)
----------------------------------------

weechat_infolist_fields
^^^^^^^^^^^^^^^^^^^^^^^

Return list of fields for current infolist item.

Prototype:

[source,C]
----------------------------------------
const char *weechat_infolist_fields (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

Return value:

* string with list of fields for current infolist item. List is comma
  separated, and contains letter for type, followed by variable name. Types
  are: "i" (integer), "s" (string), "p" (pointer), "b" (buffer), "t" (time).

C example:

[source,C]
----------------------------------------
const char *fields = weechat_infolist_fields (infolist);
/* fields contains something like:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
fields = weechat.infolist_fields(infolist)

# example
fields = weechat.infolist_fields(infolist)
# fields contains something like:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
----------------------------------------

weechat_infolist_integer
^^^^^^^^^^^^^^^^^^^^^^^^

Return value of integer variable in current infolist item.

Prototype:

[source,C]
----------------------------------------
int weechat_infolist_integer (struct t_infolist *infolist, const char *var);
----------------------------------------

Arguments:

* 'infolist': infolist pointer
* 'var': variable name (must be type "integer")

Return value:

* integer value of variable

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "my_integer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.infolist_integer(infolist, var)

# example
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
----------------------------------------

weechat_infolist_string
^^^^^^^^^^^^^^^^^^^^^^^

Return value of string variable in current infolist item.

Prototype:

[source,C]
----------------------------------------
const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);
----------------------------------------

Arguments:

* 'infolist': infolist pointer
* 'var': variable name (must be type "string")

Return value:

* string value of variable

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "my_string"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.infolist_string(infolist, var)

# example
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
----------------------------------------

weechat_infolist_pointer
^^^^^^^^^^^^^^^^^^^^^^^^

Return value of pointer variable in current infolist item.

Prototype:

[source,C]
----------------------------------------
void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);
----------------------------------------

Arguments:

* 'infolist': infolist pointer
* 'var': variable name (must be type "pointer")

Return value:

* pointer value of variable

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "pointer = 0x%lx",
                weechat_infolist_pointer (infolist, "my_pointer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.infolist_pointer(infolist, var)

# example
weechat.prnt("", "pointer = 0x%lx" % weechat.infolist_pointer(infolist, "my_pointer"))
----------------------------------------

weechat_infolist_buffer
^^^^^^^^^^^^^^^^^^^^^^^

Return value of buffer variable in current infolist item.

Prototype:

[source,C]
----------------------------------------
void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);
----------------------------------------

Arguments:

* 'infolist': infolist pointer
* 'var': variable name (must be type "buffer")
* 'size': pointer to integer variable, will be set with buffer size

Return value:

* buffer pointer

C example:

[source,C]
----------------------------------------
int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);
----------------------------------------

[NOTE]
This function is not available in scripting API.

weechat_infolist_time
^^^^^^^^^^^^^^^^^^^^^

Return value of time variable in current infolist item.

Prototype:

[source,C]
----------------------------------------
time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);
----------------------------------------

Arguments:

* 'infolist': infolist pointer
* 'var': variable name (must be type "time")

Return value:

* time value of variable

C example:

[source,C]
----------------------------------------
weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.infolist_time(infolist, var)

# example
weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
----------------------------------------

weechat_infolist_free
^^^^^^^^^^^^^^^^^^^^^

Free an infolist.

Prototype:

[source,C]
----------------------------------------
void weechat_infolist_free (struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'infolist': infolist pointer

C example:

[source,C]
----------------------------------------
weechat_infolist_free (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.infolist_free(infolist)

# example
weechat.infolist_free(infolist)
----------------------------------------

[[upgrade]]
Upgrade
~~~~~~~

Functions for upgrading WeeChat (command "/upgrade").

weechat_upgrade_new
^^^^^^^^^^^^^^^^^^^

Create or read a file for upgrade.

Prototype:

[source,C]
----------------------------------------
struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);
----------------------------------------

Arguments:

* 'filename': name of file (extension ".upgrade" will be added to this name by
  WeeChat)
* 'write':
** '1': create file (write mode, before upgrade)
** '0': read file (after upgrade)

Return value:

* pointer to upgrade file

C example:

[source,C]
----------------------------------------
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
upgrade_file = weechat.upgrade_new(filename, write)

# example
upgrade_file = weechat.upgrade_new("my_file", 1)
----------------------------------------

weechat_upgrade_write_object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Write an object in upgrade file.

Prototype:

[source,C]
----------------------------------------
int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);
----------------------------------------

Arguments:

* 'upgrade_file': upgrade file pointer
* 'object_id': id for object
* 'infolist': infolist to write in file

Return value:

* 1 if ok, 0 if error

C example:

[source,C]
----------------------------------------
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* error */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# example
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----------------------------------------

weechat_upgrade_read
^^^^^^^^^^^^^^^^^^^^

Read an upgrade file.

Prototype:

[source,C]
----------------------------------------
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file,
                          int (*callback_read)(void *data,
                                               struct t_upgrade_file *upgrade_file,
                                               int object_id,
                                               struct t_infolist *infolist),
                          void *callback_read_data);
----------------------------------------

Arguments:

* 'upgrade_file': upgrade file pointer
* 'callback_read': function called for each object read in upgrade file
* 'callback_read_data': pointer given to read callback when it is called by
  WeeChat

Return value:

* 1 if ok, 0 if error

C example:

[source,C]
----------------------------------------
int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
                    int object_id,
                    struct t_infolist *infolist)
{
    /* read variables... */
    return WEECHAT_RC_OK;
}

weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
rc = weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)

# example
def my_upgrade_read_cb(upgrade_file, object_id, infolist):
    # read variables...
    return weechat.WEECHAT_RC_OK

weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
----------------------------------------

weechat_upgrade_close
^^^^^^^^^^^^^^^^^^^^^

Close an upgrade file.

Prototype:

[source,C]
----------------------------------------
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
----------------------------------------

Arguments:

* 'upgrade_file': upgrade file pointer

C example:

[source,C]
----------------------------------------
weechat_upgrade_close (upgrade_file);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
weechat.upgrade_close(upgrade_file)

# example
weechat.upgrade_close(upgrade_file)
----------------------------------------