Référence API extension WeeChat

Ce manuel documente le client de messagerie instantanée WeeChat, il fait partie de WeeChat.

La dernière version de ce document peut être téléchargée sur cette page ^↗.

1. Introduction

WeeChat (Wee Enhanced Environment for Chat) est un client de discussion libre, rapide et léger, conçu pour différents systèmes d’exploitation.

Ce manuel documente l’API WeeChat des extensions, utilisée par les extensions en C pour interagir avec le cœur de WeeChat.

2. Extensions dans WeeChat

Une extension est un programme C qui peut appeler des fonctions WeeChat définies dans une interface.

Ce programme C n’a pas besoin des sources WeeChat pour être compilé et peut être dynamiquement chargé dans WeeChat avec la commande /plugin.

Cette extension doit être une bibliothèque dynamique, pour un chargement dynamique par le système d’exploitation. Sous GNU/Linux, le fichier a une extension ".so" et ".dll" sous Windows.

L’extension doit inclure le fichier "weechat-plugin.h" (disponible dans le code source WeeChat). Ce fichier définit les structures et types utilisés pour communiquer avec WeeChat.

Pour appeler les fonctions de WeeChat dans le format affiché dans API extension, le pointeur global suivant doit être déclaré et initialisé dans la fonction weechat_plugin_init :

struct t_weechat_plugin *weechat_plugin;

2.1. Macros

L’extension doit utiliser des macros (pour définir quelques variables) :

WEECHAT_PLUGIN_NAME("name"): nom de l’extension
WEECHAT_PLUGIN_DESCRIPTION("description"): description courte de l’extension
WEECHAT_PLUGIN_AUTHOR("author"): nom de l’auteur
WEECHAT_PLUGIN_VERSION("1.0"): version de l’extension
WEECHAT_PLUGIN_LICENSE("GPL3"): licence de l’extension
WEECHAT_PLUGIN_PRIORITY(1000): priorité de l’extension (facultatif, voir ci-dessous)

2.2. Fonctions principales

L’extension doit utiliser deux fonctions :

weechat_plugin_init
weechat_plugin_end

weechat_plugin_init

Cette fonction est appelée quand l’extension est chargée par WeeChat.

Prototype :

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

Paramètres :

plugin : pointeur vers la structure d’extension WeeChat, utilisé pour initialiser le pointeur global weechat_plugin
argc : nombre de paramètres pour l’extension
argv : paramètres pour l’extension (voir ci-dessous)

Valeur de retour :

WEECHAT_RC_OK si ok (l’extension sera chargée)
WEECHAT_RC_ERROR si erreur (l’extension ne sera PAS chargée)

Paramètres de l’extension

Lorsque l’extension est chargée par WeeChat, elle reçoit la liste des paramètres dans argv et le nombre de paramètres dans argc.

Les paramètres peuvent être :

les paramètres de ligne de commande lors du lancement du binaire WeeChat,
les paramètres donnés à la commande /plugin load xxx, lorsque l’extension est chargée manuellement par l’utilisateur.

Lorsque les paramètres proviennent de la ligne de commande, seulement ces paramètres sont envoyés à l’extension :

-a, --no-connect: Supprimer la connexion automatique aux serveurs lors du démarrage.
-s, --no-script: Supprimer le chargement automatique des scripts au démarrage.
extension:option: Option pour une extension : seulement les options liées à l’extension sont envoyées, par exemple seulement les options démarrant par irc: sont envoyées à l’extension "irc".

Priorité de l’extension

Lorsque les extensions sont automatiquement chargées (par exemple au démarrage), WeeChat charge d’abord toutes les extensions, puis appelle les fonctions init, en utilisant la priorité définie dans chaque extension. Une grande priorité signifie que la fonction init est appelée en premier.

La priorité par défaut est 1000 (avec une telle priorité, l’extension est chargée après toutes les extensions par défaut).

Les extensions par défaut de WeeChat sont initialisées dans cet ordre :

Rang	Extension	Priorité
1	charset	16000
2	logger	15000
3	exec	14000
4	trigger	13000
5	spell	12000
6	alias	11000
7	buflist	10000
8	fifo	9000
9	typing	8000
10	xfer	7000
11	irc	6000
12	relay	5000
13	guile	4070
14	lua	4050
15	perl	4040
16	php	4030
17	python	4020
18	ruby	4010
19	tcl	4000
20	script	3000
21	fset	2000

weechat_plugin_end

Cette fonction est appelée quand l’extension est déchargée par WeeChat.

Prototype :

int weechat_plugin_end (struct t_weechat_plugin *plugin);

Paramètres :

plugin : pointeur vers la structure d’extension WeeChat

Valeur de retour :

WEECHAT_RC_OK si ok
WEECHAT_RC_ERROR si erreur

2.3. Compilation de l’extension

La compilation ne nécessite pas les sources de WeeChat, seul le fichier weechat-plugin.h est requis.

Pour compiler l’extension qui n’a qu’un fichier "toto.c" (sous GNU/Linux) :

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

2.4. Chargement de l’extension

Copiez le fichier toto.so dans le répertoire système des extensions (par exemple /usr/local/lib/weechat/plugins) ou dans le répertoire utilisateur des extensions (par exemple /home/user/.local/share/weechat/plugins).

Sous WeeChat :

/plugin load toto

2.5. Exemple d’extension

Exemple complet d’extension, qui ajoute une commande /double : affiche deux fois les paramètres sur le tampon courant, ou exécute deux fois une commande (ok ce n’est pas très utile, mais c’est juste un exemple !) :

#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Extension de test pour WeeChat");
WEECHAT_PLUGIN_AUTHOR("Sébastien Helleu <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


/* fonction de rappel pour la commande "/double" */

int
commande_double_cb (const void *pointer, void *data,
                    struct t_gui_buffer *buffer,
                    int argc, char **argv, char **argv_eol)
{
    /* pour que le compilateur C soit content */
    (void) pointer;
    (void) data;
    (void) buffer;
    (void) argv;

    if (argc > 1)
    {
        weechat_command (NULL, argv_eol[1]);
        weechat_command (NULL, argv_eol[1]);
    }

    return WEECHAT_RC_OK;
}

int
weechat_plugin_init (struct t_weechat_plugin *plugin,
                     int argc, char *argv[])
{
    weechat_plugin = plugin;

    weechat_hook_command ("double",
                          "Affiche deux fois un message "
                          "ou exécute deux fois une commande",
                          "message | commande",
                          "message : message à afficher deux fois\n"
                          "commande : commande à exécuter deux fois",
                          NULL,
                          &commande_double_cb, NULL, NULL);

    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* pour que le compilateur C soit content */
    (void) plugin;

    return WEECHAT_RC_OK;
}

3. API extension

Les chapitres ci-dessous décrivent les fonctions de l’API, classées par catégorie.

Pour chaque fonction, on donne :

une description de la fonction,
le prototype en C,
le détail des paramètres,
la valeur de retour,
un exemple en C,
un exemple en script Python (la syntaxe pour les autres langages de script est similaire).

3.1. Enregistrement

Functions pour enregistrer un script : utilisées seulement par l’API script, pas l’API C.

register

Enregistrer le script.

Pour plus d’informations, voir le Guide pour scripts WeeChat ^↗.

Script (Python) :

# prototype
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...

Cette fonction n’est pas disponible dans l’API C.

3.2. Extensions

Fonctions pour obtenir des informations sur les extensions.

plugin_get_name

Retourner le nom d’une extension.

Prototype :

const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

Paramètres :

plugin : pointeur vers la structure d’extension WeeChat (peut être NULL)

Valeur de retour :

nom de l’extension, "core" pour le cœur de WeeChat (si le pointeur vers l’extension est NULL)

Exemple en C :

const char *name = weechat_plugin_get_name (plugin);

Script (Python) :

# prototype
def plugin_get_name(plugin: str) -> str: ...

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

3.3. Chaînes de caractères

Plusieurs fonctions sur les chaînes de caractères sont déjà disponibles via les fonctions standard du C, mais il est recommandé d’utiliser celles de l’API car elles sont ok avec UTF-8 et la locale.

charset_set

Définir le nouveau jeu de caractères (le jeu de caractères par défaut est UTF-8, donc si votre extension utilise UTF-8, vous n’avez pas besoin d’appeler cette fonction).

Prototype :

void weechat_charset_set (const char *charset);

Paramètres :

charset : nouveau jeu de caractères à utiliser

Exemple en C :

weechat_charset_set ("iso-8859-1");

Script (Python) :

# prototype
def charset_set(charset: str) -> int: ...

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

iconv_to_internal

Convertir une chaîne vers le jeu de caractères interne (UTF-8).

Prototype :

char *weechat_iconv_to_internal (const char *charset, const char *string);

Paramètres :

charset : jeu de caractères à convertir
string : chaîne à convertir

Valeur de retour :

chaîne convertie (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_iconv_to_internal ("iso-8859-1", "chaîne iso : é à");
/* ... */
free (str);

Script (Python) :

# prototype
def iconv_to_internal(charset: str, string: str) -> str: ...

# exemple
str = weechat.iconv_to_internal("iso-8859-1", "chaîne iso : é à")

iconv_from_internal

Convertir une chaîne du jeu de caractères interne (UTF-8) vers un autre.

Prototype :

char *weechat_iconv_from_internal (const char *charset, const char *string);

Paramètres :

charset : jeu de caractères cible
string : chaîne à convertir

Valeur de retour :

chaîne convertie (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_iconv_from_internal ("iso-8859-1", "chaîne utf-8 : é à");
/* ... */
free (str);

Script (Python) :

# prototype
def iconv_from_internal(charset: str, string: str) -> str: ...

# exemple
str = weechat.iconv_from_internal("iso-8859-1", "chaîne utf-8 : é à")

gettext

Retourner la chaîne traduite (dépend de la langue locale).

Prototype :

const char *weechat_gettext (const char *string);

Paramètres :

string : chaîne à traduire

Valeur de retour :

chaîne traduite ou string s’il n’y a pas de traduction disponible dans la langue locale

Exemple en C :

char *str = weechat_gettext ("hello");

Script (Python) :

# prototype
def gettext(string: str) -> str: ...

# exemple
str = weechat.gettext("hello")

ngettext

Retourner la chaîne traduite, en utilisant le singulier ou le pluriel, selon le paramètre count.

Prototype :

const char *weechat_ngettext (const char *string, const char *plural,
                              int count);

Paramètres :

string : chaîne à traduire, au singulier
plural : chaîne à traduire, au pluriel
count : utilisé pour choisir entre le singulier et le pluriel (le choix est fonction de la langue utilisée)

Valeur de retour :

chaîne traduite ou string / plural s’il n’y a pas de traduction disponible dans la langue locale

Exemple en C :

char *str = weechat_ngettext ("file", "files", num_files);

Script (Python) :

# prototype
def ngettext(string: str, plural: str, count: int) -> str: ...

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

strndup

Retourner la chaîne dupliquée, avec un nombre maximum d’octets.

Prototype :

char *weechat_strndup (const char *string, int bytes);

Paramètres :

string : chaîne à dupliquer
bytes : nombre maximum d’octets à dupliquer

Valeur de retour :

chaîne dupliquée (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_strndup ("abcdef", 3);  /* résultat : "abc" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_cut

WeeChat ≥ 3.3.

Couper une chaîne après un nombre donné de caractères, ajouter un suffixe facultatif après la chaîne si elle est coupée.

Prototype :

char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);

Paramètres :

string : chaîne à couper
length : nombre maximum de caractères
count_suffix : si 1, la longueur du suffixe est comptée dans la longueur maximale
screen : si 1, le découpage est basé sur la largeur des caractères affichés
cut_suffix : le suffixe ajouté à la fin de la chaîne si elle est découpée

Valeur de retour :

chaîne coupée (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_cut ("ceci est un test", 5, 1, 1, "…");  /* résultat : "ceci…" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_tolower

Mis à jour dans la 3.8.

Retourner une chaîne avec les lettres majuscules converties en minuscules.

Le comportement a changé dans la version 3.8 : désormais toutes les lettres en majuscules sont correctement converties en minuscules (par appel à la fonction towlower), en plus de l’intervalle de A à Z.
De plus, une chaîne nouvellement allouée est retournée et doit être libérée après utilisation.

Prototype :

char *weechat_string_tolower (const char *string);

Paramètres :

string : chaîne à convertir

Valeur de retour :

chaîne avec les lettres en minuscules (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_tolower ("ABCD_É");  /* résultat : "abcd_é" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_toupper

Mis à jour dans la 3.8.

Retourner une chaîne avec les lettres minuscules converties en majuscules.

Le comportement a changé dans la version 3.8 : désormais toutes les lettres en minuscules sont correctement converties en majuscules (par appel à la fonction towupper), en plus de l’intervalle de a à z.
De plus, une chaîne nouvellement allouée est retournée et doit être libérée après utilisation.

Prototype :

char *weechat_string_toupper (const char *string);

Paramètres :

string : chaîne à convertir

Valeur de retour :

chaîne avec les lettres en majuscules (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_toupper ("abcd_é");  /* résultat : "ABCD_É" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_charcmp

Mis à jour dans la 1.0, 3.8.

Comparer deux caractères.

Prototype :

int weechat_string_charcmp (const char *string1, const char *string2);

Paramètres :

string1 : première chaîne pour la comparaison
string2 : seconde chaîne pour la comparaison

Valeur de retour :

résultat de la soustraction du premier caractère UTF-8 dans string2 du premier caractère UTF-8 dans string1 :
- < 0 si char1 < char2
- 0 si char1 == char2
- > 0 si char1 > char2

Exemple en C :

int diff = weechat_string_charcmp ("aaa", "ccc");  /* == -2 */

Cette fonction n’est pas disponible dans l’API script.

string_charcasecmp

Mis à jour dans la 1.0, 3.8.

Comparer deux caractères en ignorant la casse.

Prototype :

int weechat_string_charcasecmp (const char *string1, const char *string2);

Paramètres :

string1 : première chaîne pour la comparaison
string2 : seconde chaîne pour la comparaison

Valeur de retour :

résultat de la soustraction du premier caractère UTF-8 dans string2 (converti en minuscule) du premier caractère UTF-8 dans string1 (converti en minuscule) :
- < 0 si char1 < char2
- 0 si char1 == char2
- > 0 si char1 > char2

Exemple en C :

int diff = weechat_string_charcasecmp ("aaa", "CCC");  /* == -2 */

Cette fonction n’est pas disponible dans l’API script.

strcmp

WeeChat ≥ 3.8.

Comparer deux chaînes.

Prototype :

int weechat_strcmp (const char *string1, const char *string2);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 du dernier caractère UTF-8 comparé dans string1 :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff = weechat_strcmp ("aaa", "ccc");  /* == -2 */

Cette fonction n’est pas disponible dans l’API script.

strncmp

WeeChat ≥ 3.8.

Comparer deux chaînes, pour max caractères.

Prototype :

int weechat_strncmp (const char *string1, const char *string2, int max);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer
max : nombre maximum de caractères à comparer

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 du dernier caractère UTF-8 comparé dans string1 :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff = weechat_strncmp ("aabb", "aacc", 2);  /* == 0 */

Cette fonction n’est pas disponible dans l’API script.

strcasecmp

Mis à jour dans la 1.0, 3.8.

Comparer deux chaînes indépendemment de la casse.

Prototype :

int weechat_strcasecmp (const char *string1, const char *string2);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 (converti en minuscule) du dernier caractère UTF-8 comparé dans string1 (converti en minuscule) :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff;
diff = weechat_strcasecmp ("aaa", "CCC");    /* == -2 */
diff = weechat_strcasecmp ("noël", "NOËL");  /* == 0  */

Cette fonction n’est pas disponible dans l’API script.

strcasecmp_range

WeeChat ≥ 0.3.7, mis à jour dans la 1.0, 3.8.

Comparer deux chaînes indépendemment de la locale et de la casse, avec un intervalle pour comparer la casse.

Prototype :

int weechat_strcasecmp_range (const char *string1, const char *string2, int range);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer
range : nombre de caractères pour la comparaison de casse, par exemple :
- 26 : A-Z deviennent en minuscules a-z
- 29 : A-Z [ \ ] deviennent minuscules a-z { | }
- 30 : A-Z [ \ ] ^ deviennent minuscules a-z { | } ~

Les valeurs 29 et 30 sont utilisés par quelques protocoles comme IRC.

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 (converti en minuscule) du dernier caractère UTF-8 comparé dans string1 (converti en minuscule) :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */

Cette fonction n’est pas disponible dans l’API script.

strncasecmp

Mis à jour dans la 1.0, 3.8.

Comparer deux chaînes indépendemment de la casse, pour max caractères.

Prototype :

int weechat_strncasecmp (const char *string1, const char *string2, int max);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer
max : nombre maximum de caractères à comparer

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 (converti en minuscule) du dernier caractère UTF-8 comparé dans string1 (converti en minuscule) :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff = weechat_strncasecmp ("aabb", "AACC", 2);  /* == 0 */

Cette fonction n’est pas disponible dans l’API script.

strncasecmp_range

WeeChat ≥ 0.3.7, mis à jour dans la 1.0, 3.8.

Comparer deux chaînes indépendemment de la locale et de la casse, pour max caractères, avec un intervalle pour comparer la casse.

Prototype :

int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer
max : nombre maximum de caractères à comparer
range : nombre de caractères pour la comparaison de casse, par exemple :
- 26 : A-Z deviennent en minuscules a-z
- 29 : A-Z [ \ ] deviennent minuscules a-z { | }
- 30 : A-Z [ \ ] ^ deviennent minuscules a-z { | } ~

Les valeurs 29 et 30 sont utilisés par quelques protocoles comme IRC.

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 (converti en minuscule) du dernier caractère UTF-8 comparé dans string1 (converti en minuscule) :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */

Cette fonction n’est pas disponible dans l’API script.

strcmp_ignore_chars

Mis à jour dans la 1.0, 3.8.

Comparer deux chaînes en ignorant des caractères.

Prototype :

int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);

Paramètres :

string1 : première chaîne à comparer
string2 : seconde chaîne à comparer
chars_ignored : chaîne avec les caractères à ignorer
case_sensitive : 1 pour une comparaison tenant compte de la casse, sinon 0

Le comportement a changé dans la version 3.8 lorsque case_sensitive est positionné à 0 : désormais toutes les lettres en majuscules sont correctement converties en minuscules (par appel à la fonction towlower), en plus de l’intervalle de A à Z.

Valeur de retour :

résultat de la soustraction du dernier caractère UTF-8 comparé dans string2 (converti en minuscule si case_sensitive est positionné à 0) du dernier caractère UTF-8 comparé dans string1 (converti en minuscule si case_sensitive est positionné à 0) :
- < 0 si string1 < string2
- 0 si string1 == string2
- > 0 si string1 > string2

Exemple en C :

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

Cette fonction n’est pas disponible dans l’API script.

strcasestr

Mis à jour dans la 1.3, 3.8.

Rechercher une chaîne indépendemment de la casse.

Prototype :

const char *weechat_strcasestr (const char *string, const char *search);

Paramètres :

string : chaîne
search : chaîne à rechercher dans string

Valeur de retour :

pointeur vers la chaîne trouvée, ou NULL si non trouvée (WeeChat ≥ 1.3 : le pointeur retourné est un const char * au lieu d’un char *)

Exemple en C :

const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* résultat : pointeur vers "DeF" */

Cette fonction n’est pas disponible dans l’API script.

strlen_screen

WeeChat ≥ 0.4.2, mis à jour dans la 3.8.

Retourner le nombre de caractères nécessaires pour afficher la chaîne UTF-8 sur l’écran.

Les codes couleur de WeeChat sont sautés et ne comptent pas dans le résultat (ceci est la seule différence avec la fonction utf8_strlen_screen).

Prototype :

int weechat_strlen_screen (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

nombre de caractères nécessaires pour afficher la chaîne UTF-8 sur l’écran

Exemple en C :

int length_on_screen = weechat_strlen_screen ("é");  /* == 1 */

Script (Python) :

# prototype
def strlen_screen(string: str) -> int: ...

# exemple
length = weechat.strlen_screen("é")  # 1

string_match

Mis à jour dans la 1.0, 3.8.

Vérifier si une chaîne correspond à un masque.

Prototype :

int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);

Paramètres :

string : chaîne
mask : masque avec des caractères joker (*), chaque joker correspond à 0 ou plusieurs caractères dans la chaîne
case_sensitive : 1 pour une comparaison tenant compte de la casse, sinon 0

Depuis la version 1.0, les caractères joker sont autorisés à l’intérieur du masque (pas seulement au début et à la fin du masque).

Valeur de retour :

1 si la chaîne correspond au masque, sinon 0

Exemple en C :

int match1 = weechat_string_match ("abcdef", "abc*", 0);   /* == 1 */
int match2 = weechat_string_match ("abcdef", "*dd*", 0);   /* == 0 */
int match3 = weechat_string_match ("abcdef", "*def", 0);   /* == 1 */
int match4 = weechat_string_match ("abcdef", "*de*", 0);   /* == 1 */
int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */

Script (Python) :

# prototype
def string_match(string: str, mask: str, case_sensitive: int) -> int: ...

# exemples
match1 = weechat.string_match("abcdef", "abc*", 0)   # == 1
match2 = weechat.string_match("abcdef", "*dd*", 0)   # == 0
match3 = weechat.string_match("abcdef", "*def", 0)   # == 1
match4 = weechat.string_match("abcdef", "*de*", 0)   # == 1
match5 = weechat.string_match("abcdef", "*b*d*", 0)  # == 1

string_match_list

WeeChat ≥ 2.5, mis à jour dans la 3.8.

Vérifier si une chaîne correspond à une liste de masques. Des masques négatifs sont autorisés avec le format "!mot". Un masque négatif a une priorité plus haute qu’un masque standard.

Prototype :

int weechat_string_match_list (const char *string, const char **masks,
                               int case_sensitive);

Paramètres :

string : chaîne
masks : liste de masques avec un NULL après le dernier masque de la liste ; chaque masque est comparé à la chaîne avec la fonction string_match
case_sensitive : 1 pour une comparaison tenant compte de la casse, sinon 0

Valeur de retour :

1 si la chaîne correspond à la liste de masques (au moins un masque correspond et aucun masque négatif ne correspond), sinon 0

Exemple en C :

const char *masks[3] = { "*", "!abc*", NULL };
int match1 = weechat_string_match_list ("abc", masks, 0);     /* == 0 */
int match2 = weechat_string_match_list ("abcdef", masks, 0);  /* == 0 */
int match3 = weechat_string_match_list ("def", masks, 0);     /* == 1 */

Script (Python) :

# prototype
def string_match_list(string: str, masks: str, case_sensitive: int) -> int: ...

# exemples
match1 = weechat.string_match("abc", "*,!abc*", 0)     # == 0
match2 = weechat.string_match("abcdef", "*,!abc*", 0)  # == 0
match3 = weechat.string_match("def", "*,!abc*", 0)     # == 1

string_expand_home

WeeChat ≥ 0.3.3.

Remplacer le ~ en début de chaîne par le répertoire "home". Si la chaîne ne débute pas par ~, alors une chaîne identique est retournée.

Prototype :

char *weechat_string_expand_home (const char *path);

Paramètres :

path : chemin

Valeur de retour :

chemin avec le ~ en début remplacé par le répertoire "home" (doit être supprimé par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_expand_home ("~/fichier.txt");
/* résultat : "/home/user/fichier.txt" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_eval_path_home

WeeChat ≥ 1.3, mis à jour dans la 3.2.

Évaluer un chemin en 3 étapes :

remplacer le %h du début par un répertoire WeeChat ("data" par défaut),
remplacer le ~ du début par le répertoire maison de l’utilisateur (appel à string_expand_home),
évaluer les variables (voir string_eval_expression).

Prototype :

char *weechat_string_eval_path_home (const char *path,
                                     struct t_hashtable *pointers,
                                     struct t_hashtable *extra_vars,
                                     struct t_hashtable *options);

Paramètres :

path : chemin
pointers : table de hachage pour l’appel à la fonction string_eval_expression
extra_vars : table de hachage pour l’appel à la fonction string_eval_expression
options : table de hachage pour l’appel à la fonction string_eval_expression, avec une clé supplémentaire supportée :
- directory: répertoire WeeChat à utiliser pour remplacer %h, un parmi ceux-ci :
  - config
  - data (par défaut)
  - cache
  - runtime

Valeur de retour :

chemin évalué (doit être supprimé par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_eval_path_home ("${weechat_config_dir}/test.conf", NULL, NULL, NULL);
/* résultat : "/home/user/.config/weechat/test.conf" */
/* ... */
free (str);

Script (Python) :

# prototype
def string_eval_path_home(path: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# exemple
path = weechat.string_eval_path_home("${weechat_config_dir}/test.conf", {}, {}, {})
# path == "/home/user/.config/weechat/test.conf"

string_remove_quotes

Supprimer les apostrophes/guillemets au début et à la fin d’une chaîne (les espaces avant la première apostrophe ou après la dernière sont ignorés).

Prototype :

char *weechat_string_remove_quotes (const char *string, const char *quotes);

Paramètres :

string : chaîne
quotes : chaîne avec la liste des apostrophes/guillemets à supprimer

Valeur de retour :

chaîne sans les apostrophes/guillemets au début et à la fin (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_remove_quotes (string, " 'aujourd'hui' ", "'");
/* résultat : "aujourd'hui" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_strip

Supprimer des caractères au début et/ou à la fin d’une chaîne.

Prototype :

char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);

Paramètres :

string : chaîne
left : supprime les caractères en début de chaîne si différent de 0
right : supprime les caractères en fin de chaîne si différent de 0
chars : chaîne avec les caractères à supprimer

Valeur de retour :

chaîne avec les caractères supprimés (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_strip (".abc -", 0, 1, "- .");  /* résultat : ".abc" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_convert_escaped_chars

WeeChat ≥ 1.0.

Convertir les caractères échappés par leur valeur :

\" : double guillemet droit
\\ : barre oblique inversée
\a : alerte (BEL)
\b : retour arrière
\e : échappement
\f : saut de page
\n : nouvelle ligne
\r : retour chariot
\t : tabulation horizontale
\v : tabulation verticale
\0ooo : caractère sous forme de valeur octale (ooo a 0 à 3 chiffres)
\xhh : caractère sous forme de valeur hexadécimale (hh a 1 à 2 chiffres)
\uhhhh : caractère unicode sous forme de valeur hexadécimale (hhhh a 1 à 4 chiffres)
\Uhhhhhhhh : caractère unicode sous forme de valeur hexadécimale (hhhhhhhh a 1 à 8 chiffres)

Prototype :

char *weechat_string_convert_escaped_chars (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

chaîne avec les caractères échappés remplacés par leur valeur (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_convert_escaped_chars ("snowman : \\u2603");
/* str == "snowman : ☃" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_mask_to_regex

Retourner une expression régulière ("regex"), construite avec un masque où le seul caractère spécial est *. Tous les autres caractères spéciaux d’expression régulière sont échappés.

Prototype :

char *weechat_string_mask_to_regex (const char *mask);

Paramètres :

mask : masque

Valeur de retour :

expression régulière, sous forme de chaîne (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* résultat : "test.*mask" */
/* ... */
free (str_regex);

Script (Python) :

# prototype
def string_mask_to_regex(mask: str) -> str: ...

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

string_regex_flags

WeeChat ≥ 0.3.7.

Retourner un pointeur dans la chaîne après les "flags" et le masque avec les "flags" pour compiler l’expression régulière.

Prototype :

const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)

Paramètres :

regex : expression régulière POSIX étendue
default_flags : combinaison des valeurs suivantes (voir man regcomp) :
- REG_EXTENDED
- REG_ICASE
- REG_NEWLINE
- REG_NOSUB
flags : la valeur du pointeur est alimentée avec les "flags" utilisés dans l’expression régulière ("flags" par défaut + "flags" définis dans l’expression régulière)

Les "flags" doivent être au début de l’expression régulière. Le format est : "(?eins-eins)chaîne".

Les "flags" autorisés sont :

e : expression régulière POSIX étendue (REG_EXTENDED)
i : insensible à la casse (REG_ICASE)
n : les opérateurs qui cherchent n’importe quel caractère ne trouvent pas les nouvelles lignes (REG_NEWLINE)
s : le support d’adressage des sous-chaînes de correspondance n’est pas requis (REG_NOSUB)

Valeur de retour :

pointeur dans la regex, après les "flags"

Exemple en C :

const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */

Cette fonction n’est pas disponible dans l’API script.

string_regcomp

WeeChat ≥ 0.3.7.

Compiler une expression régulière avec des "flags" optionnels en début de chaîne (pour le format des "flags", voir string_regex_flags).

Prototype :

int weechat_string_regcomp (void *preg, const char *regex, int default_flags)

Paramètres :

preg : pointeur vers la structure regex_t
regex : expression régulière POSIX étendue
default_flags : combinaison des valeurs suivantes (voir man regcomp) :
- REG_EXTENDED
- REG_ICASE
- REG_NEWLINE
- REG_NOSUB

Valeur de retour :

même code retour que la fonction regcomp (0 si ok, autre valeur pour une erreur, voir man regcomp)

L’expression régulière preg doit être nettoyée par un appel à "regfree" après utilisation, si la fonction a retourné 0 (OK).

Exemple en C :

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
{
    /* OK */
    /* ... */
    regfree (&my_regex);
}
else
{
    /* erreur */
    /* ... */
}

Cette fonction n’est pas disponible dans l’API script.

string_has_highlight

Vérifier si une chaîne a un ou plusieurs "highlights", en utilisant une liste de mots "highlight".

Prototype :

int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);

Paramètres :

string : chaîne
highlight_words : liste de mots "highlight", séparés par des virgules

Valeur de retour :

1 si la chaîne a un ou plusieurs "highlights", sinon 0

Exemple en C :

int hl = weechat_string_has_highlight ("my test string", "test,word2");  /* == 1 */

Script (Python) :

# prototype
def string_has_highlight(string: str, highlight_words: str) -> int: ...

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

string_has_highlight_regex

WeeChat ≥ 0.3.4.

Vérifier si une chaîne a un ou plusieurs "highlights", en utilisant une expression régulière POSIX étendue.
Pour au moins une correspondance dans la chaîne, elle doit être entourée de délimiteurs (caractères différents de : alphanumérique, -, _ et |).

Prototype :

int weechat_string_has_highlight_regex (const char *string, const char *regex);

Paramètres :

string : chaîne
regex : expression régulière POSIX étendue

Valeur de retour :

1 si la chaîne a un ou plusieurs "highlights", sinon 0

Exemple en C :

int hl = weechat_string_has_highlight_regex ("my test string", "test|word2");  /* == 1 */

Script (Python) :

# prototype
def string_has_highlight_regex(string: str, regex: str) -> int: ...

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

string_replace

Remplacer toutes les occurrences d’une chaîne par une autre chaîne.

Prototype :

char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);

Paramètres :

string : chaîne
search : chaîne à remplacer
replace : remplacement pour la chaîne search

Valeur de retour :

chaîne avec search remplacée par replace (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *str = weechat_string_replace ("test, test", "s", "x");  /* résultat : "text" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_replace_regex

WeeChat ≥ 1.0.

Remplacer du texte dans une chaîne en utilisant une expression régulière, du texte de remplacement et une fonction de rappel optionnelle.

Prototype :

char *weechat_string_replace_regex (const char *string, void *regex,
                                    const char *replace, const char reference_char,
                                    char *(*callback)(void *data, const char *text),
                                    void *callback_data);

Paramètres :

string : chaîne
regex : pointeur vers une expression régulière (structure regex_t) compilée avec la fonction WeeChat string_regcomp ou regcomp (voir man regcomp)
replace : texte de remplacement, où les références suivantes sont autorisées :
- $0 à $99 : correspondance 0 à 99 dans l’expression régulière (0 est la correspondance entière, 1 à 99 sont les groupes capturés entre parenthèses)
- $+ : la dernière correspondance (avec le numéro le plus élevé)
- $.*N : correspondance N (peut être + ou de 0 à 99), avec tous les caractères remplacés par * (le caractère * peut être n’importe quel caractère entre l’espace (32) et ~ (126))
reference_char : le caractère utilisé pour les références aux correspondances (en général $)
callback : une fonction de rappel optionnelle appelé pour chaque référence dans replace (sauf pour les correspondances remplacées par un caractère) ; la fonction de rappel doit retourner :
- une chaîne nouvellement allouée : elle est utilisée en texte de remplacement (elle est libérée après utilisation)
- NULL : le texte reçu dans la fonction de rappel est utilisé comme texte de remplacement (sans changement)
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée

Valeur de retour :

chaîne avec le texte remplacé, NULL en cas de problème (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

regex_t my_regex;
char *string;
if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
                            REG_EXTENDED) == 0)
{
    string = weechat_string_replace_regex ("date : 2014-02-14", &my_regex,
                                           "$3/$2/$1", '$', NULL, NULL);
    /* string == "date : 14/02/2014" */
    if (string)
        free (string);
    regfree (&my_regex);
}

Cette fonction n’est pas disponible dans l’API script.

string_translate_chars

WeeChat ≥ 3.8.

Traduire des caractères dans une chaîne.

Prototype :

char *string_translate_chars (const char *string, const char *chars1, const char *chars2);

Paramètres :

string : chaîne
chars1 : chaîne avec des caractères à traduire
chars2 : chaîne avec les caractères de remplacement ; elle doit contenir le même nombre de caractères UTF-8 que chars1

Valeur de retour :

chaîne avec les caractères traduits, NULL en cas de problème (doit être supprimée par un appel à "free" après utilisation)

Exemples en C :

/* "test" => "tEst" */
char *str = weechat_string_translate_chars ("test", "abcdef", "ABCDEF");

/* "clean the boat" => "CleAn the BoAt" */
char *str = weechat_string_translate_chars ("clean the boat", "abc", "ABC");

Cette fonction n’est pas disponible dans l’API script.

string_split

Mis à jour dans la 2.5, 2.6.

Découper une chaîne à l’aide de délimiteur(s).

Prototype :

char **weechat_string_split (const char *string, const char *separators,
                             const char *strip_items, int flags,
                             int num_items_max, int *num_items);

Paramètres :

string : chaîne à découper
separators : délimiteurs utilisés pour le découpage
strip_items : caractères à supprimer des chaînes retournées (gauche/droite) ; optionnel, peut être NULL
flags : combinaison de valeurs pour changer le comportement par défaut ; si la valeur est 0, le comportement par défaut est utilisé (pas de suppression des séparateurs en début/fin de chaîne, plusieurs séparateurs consécutifs sont utilisés tels quels donc des chaînes vides peuvent être retournées) ; les "flags" suivants sont acceptés :
- WEECHAT_STRING_SPLIT_STRIP_LEFT : supprimer les séparateurs sur la gauche (début de la chaîne)
- WEECHAT_STRING_SPLIT_STRIP_RIGHT : supprimer les séparateurs sur la droite (fin de la chaîne)
- WEECHAT_STRING_SPLIT_COLLAPSE_SEPS : regrouper plusieurs séparateurs consécutifs en un seul
- WEECHAT_STRING_SPLIT_KEEP_EOL : garder la fin de la ligne pour chaque valeur
num_items_max : nombre maximum de chaînes à créer (0 = pas de limite)
num_items : pointeur vers un entier qui contiendra le nombre de chaînes créées

Avec WeeChat ≤ 2.4, le paramètre flags s’appelait keep_eol et prenait d’autres valeurs, qui doivent être converties comme ceci ;

keep_eol	flags
0	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
1	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
2	WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL

Valeur de retour :

tableau de chaînes, NULL en cas de problème (doit être supprimé par un appel à string_free_split après utilisation)

Exemples en C :

char **argv;
int argc;

argv = weechat_string_split ("abc de  fghi ", " ", NULL, 0, 0, &argc);
/* résultat :  argv[0] == "abc"
               argv[1] == "de"
               argv[2] == ""
               argv[3] == "fghi"
               argv[4] == ""
               argv[5] == NULL
               argc == 5
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                             0, &argc);
/* résultat :  argv[0] == "abc"
               argv[1] == "de"
               argv[2] == "fghi"
               argv[3] == NULL
               argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                             | WEECHAT_STRING_SPLIT_KEEP_EOL,
                             0, &argc);
/* résultat : argv[0] == "abc de  fghi"
              argv[1] == "de  fghi"
              argv[2] == "fghi"
              argv[3] == NULL
              argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                             | WEECHAT_STRING_SPLIT_KEEP_EOL,
                             0, &argc);
/* résultat : argv[0] == "abc de  fghi "
              argv[1] == "de  fghi "
              argv[2] == "fghi "
              argv[3] == NULL
              argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split (" abc, de,, fghi ", ",", " ",
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                             0, &argc);
/* résultat : argv[0] == "abc"
              argv[1] == "de"
              argv[2] == "fghi"
              argv[3] == NULL
              argc == 3
*/
weechat_string_free_split (argv);

Cette fonction n’est pas disponible dans l’API script.

string_split_shell

WeeChat ≥ 1.0.

Découper une chaîne comme le shell le fait pour une commande avec ses paramètres.

Cette fonction est une conversion en C de la classe Python "shlex" (fichier : Lib/shlex.py dans le dépôt Python), voir cette page ^↗.

Prototype :

char **weechat_string_split_shell (const char *string, int *num_items);

Paramètres :

string : chaîne à découper
num_items : pointeur vers un entier qui contiendra le nombre de chaînes créées

Valeur de retour :

tableau de chaînes, NULL en cas de problème (doit être supprimé par un appel à string_free_split après utilisation)

Exemple en C :

char **argv;
int argc;
argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
/* résultat : argv[0] == "test"
              argv[1] == "first arg"
              argv[2] == "second arg"
              argv[3] == NULL
              argc == 3
*/
weechat_string_free_split (argv);

Cette fonction n’est pas disponible dans l’API script.

string_free_split

Supprimer une chaîne découpée.

Prototype :

void weechat_string_free_split (char **split_string);

Paramètres :

split_string : chaîne découpée par string_split

Exemple en C :

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);

Cette fonction n’est pas disponible dans l’API script.

string_rebuild_split_string

Mis à jour dans la 3.7.

Reconstruire une chaîne à partir d’une chaîne découpée, d’un séparateur facultatif et d’un index de première/dernière chaîne à utiliser.

Prototype :

char *weechat_string_rebuild_split_string (char **split_string,
                                           const char *separator,
                                           int index_start, int index_end);

Paramètres :

split_string : chaîne découpée par la fonction string_split
separator : chaîne utilisée pour séparer les différentes chaînes (peut être NULL ou une chaîne vide)
index_start : index de la première chaîne à utiliser (≥ 0)
index_end : index de la dernière chaîne à utiliser (doit être ≥ index_start ; la valeur spéciale -1 peut être utilisée pour utiliser toutes les chaînes jusqu’à ce que NULL soit trouvé)

Valeur de retour :

chaîne reconstruite avec la chaîne découpée (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_rebuild_split_string (argv, ";", 0, -1);
/* str == "abc;def;ghi" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

string_split_command

Découper une liste de commandes séparées par separator (qui peut être échappé par \ dans la chaîne).

Prototype :

char **weechat_string_split_command (const char *command, char separator);

Paramètres :

command : commande à découper
separator : séparateur

Valeur de retour :

tableau de chaînes, NULL en cas de problème (doit être supprimé par un appel à free_split_command après utilisation)

Exemple en C :

char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';');
/* résultat : argv[0] == "/commande1 arg"
              argv[1] == "/commande2"
              argv[2] == NULL
*/
weechat_free_split_command (argv);

Cette fonction n’est pas disponible dans l’API script.

string_free_split_command

Supprimer une commande découpée.

Prototype :

void weechat_string_free_split_command (char **split_command);

Paramètres :

split_command : commande découpée par string_split_command

Exemple en C :

char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';');
/* ... */
weechat_free_split_command (argv);

Cette fonction n’est pas disponible dans l’API script.

string_format_size

Construire une chaîne avec une taille de fichier formatée et une unité traduite dans la langue locale.

Prototype :

char *weechat_string_format_size (unsigned long long size);

Paramètres :

size : taille (en octets)

Valeur de retour :

chaîne formatée (doit être supprimée par un appel à "free" après utilisation)

Exemples en C :

/* exemples avec la langue française */

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

char *str = weechat_string_format_size (1);  /* str == "1 octet" */
/* ... */
free (str);

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

char *str = weechat_string_format_size (15200);  /* str == "15.2 Ko" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152);  /* str == "2.10 Mo" */
/* ... */
free (str);

Script (Python), WeeChat ≥ 2.2 :

# prototype
def string_format_size(size: int) -> str: ...

# exemple
str = weechat.string_format_size(15200)  # == "15.2 Ko"

string_parse_size

WeeChat ≥ 3.7.

Analyser une chaîne avec une taille et une unité optionnelle et retourner la taille en octets.

Prototype :

unsigned long long weechat_string_parse_size (const char *size);

Paramètres :

size : la taille sous forme de chaîne : nombre entier positif suivi par des espaces optionnels et une unité optionnelle (en minuscules ou majuscules), qui est une des suivantes :
- b : octets
- k : kilo-octets (1k = 1000 octets)
- m : méga-octets (1m = 1000k = 1 000 000 octets)
- g : giga-octets (1g = 1000m = 1 000 000 000 octets)
- t : tera-octets (1t = 1000g = 1 000 000 000 000 octets)

Valeur de retour :

taille en octets, 0 si erreur

Exemple en C :

unsigned long long size = weechat_parse_size ("1.34m");  /* size == 1340000 */

Script (Python) :

# prototype
def string_parse_size(size: str) -> int: ...

# exemple
size = weechat.string_parse_size("1.34m")  # 1340000

string_color_code_size

WeeChat ≥ 3.0.

Retourner la taille (en octets) du code couleur WeeChat au début de la chaîne.

Prototype :

int weechat_string_color_code_size (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

taille (en octets) du code couleur WeeChat au début de la chaîne ; si la chaîne est NULL, vide ou ne commence pas avec un code couleur, 0 est retourné ; si la chaîne commence par plusieurs codes couleur, seule la taille du premier est retournée

Exemples en C :

int size;

size = weechat_string_color_code_size ("test");  /* size == 0 */
size = weechat_string_color_code_size (weechat_color ("bold"));  /* size == 2 */
size = weechat_string_color_code_size (weechat_color ("yellow,red"));  /* size == 7 */

Script (Python) :

# prototype
def string_color_code_size(string: str) -> int: ...

# exemples
size = weechat.string_color_code_size("test")  # size == 0
size = weechat.string_color_code_size(weechat.color("bold"))  # size == 2
size = weechat.string_color_code_size(weechat.color("yellow,red"))  # size == 7

string_remove_color

Supprimer les couleurs WeeChat dans une chaîne.

Prototype :

char *weechat_string_remove_color (const char *string,
                                   const char *replacement);

Paramètres :

string : chaîne
replacement : si non NULL et non vide, les couleurs WeeChat sont remplacées par le premier caractère de cette chaîne, sinon les codes couleurs WeeChat et les caractères suivants (rattachés à la couleur) sont supprimés de la chaîne

Valeur de retour :

chaîne sans couleur (doit être supprimée par un appel à "free" après utilisation)

Exemples en C :

/* supprime les codes couleur */
char *str = weechat_string_remove_color (ma_chaine1, NULL);
/* ... */
free (str);

/* remplace les codes couleur par "?" */
char *str = weechat_string_remove_color (ma_chaine2, "?");
/* ... */
free (str);

Script (Python) :

# prototype
def string_remove_color(string: str, replacement: str) -> str: ...

# exemple
str = weechat.string_remove_color(ma_chaine, "?")

string_base_encode

WeeChat ≥ 2.4.

Encoder une chaîne en base 16, 32 ou 64.

Prototype :

int weechat_string_base_encode (int base, const char *from, int length, char *to);

Paramètres :

base : 16, 32 ou 64
from : chaîne à encoder
length : longueur de chaîne à encoder (par exemple strlen(from))
to : pointeur vers la chaîne pour stocker le résultat (doit être suffisamment long, le résultat est plus long que la chaîne initiale)

Valeur de retour :

longueur de la chaîne stockée dans *to (ne compte pas le \0 final), -1 en cas d’erreur

Exemple en C :

char *string = "abcdefgh", result[128];
int length;
length = weechat_string_base_encode (16, string, strlen (string), result);
/* length == 16, result == "6162636465666768" */
length = weechat_string_base_encode (32, string, strlen (string), result);
/* length == 16, result == "MFRGGZDFMZTWQ===" */
length = weechat_string_base_encode (64, string, strlen (string), result);
/* length == 12, result == "YWJjZGVmZ2g=" */

Cette fonction n’est pas disponible dans l’API script.

string_base_decode

WeeChat ≥ 2.4.

Décoder une chaîne encodée en base 16, 32 ou 64.

Prototype :

int weechat_string_base_decode (int base, const char *from, char *to);

Paramètres :

base : 16, 32 ou 64
from : chaîne à décoder
to : pointeur vers la chaîne pour stocker le résultat (doit être suffisamment long, le résultat est plus court que la chaîne initiale)

Valeur de retour :

longueur de la chaîne stockée dans *to (ne compte pas le \0 final), -1 en cas d’erreur

Exemple en C :

char result[128];
int length;
length = weechat_string_base_decode (16, "6162636465666768", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode (32, "MFRGGZDFMZTWQ===", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode (64, "YWJjZGVmZ2g=", result);
/* length == 8, result == "abcdefgh" */

Cette fonction n’est pas disponible dans l’API script.

string_hex_dump

WeeChat ≥ 1.4.

Afficher les données sous forme d’octets en hexadécimal et ascii.

Prototype :

char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                       const char *prefix, const char *suffix);

Paramètres :

data : les données à afficher
data_size : nombre d’octets à afficher dans data
bytes_per_line : nombre d’octets à afficher sur chaque ligne
prefix : le préfixe à afficher au début de chaque ligne (optionnel, peut être NULL)
suffix : le suffixe à afficher à la fin de chaque ligne (optionnel, peut être NULL)

Valeur de retour :

chaîne avec les données (doit être supprimée par un appel à "free" après utilisation)

Exemple en C :

char *string = "abc def-ghi";
char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL);
/* dump == " >> 61 62 63 20 64 65 66 2D   a b c   d e f - \n"
           " >> 67 68 69                  g h i           "  */

Cette fonction n’est pas disponible dans l’API script.

string_is_command_char

WeeChat ≥ 0.3.2.

Vérifier si le premier caractère de la chaîne est un caractère de commande (le caractère par défaut de commande est /).

Prototype :

int weechat_string_is_command_char (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

1 si le premier caractère de la chaîne est un caractère de commande, sinon 0

Exemples en C :

int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */

Script (Python) :

# prototype
def string_is_command_char(string: str) -> int: ...

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

string_input_for_buffer

WeeChat ≥ 0.3.2.

Retourner un pointeur vers le texte envoyé vers le tampon (pointeur à l’intérieur du paramètre "string"), ou NULL si c’est une commande.

Prototype :

const char *weechat_string_input_for_buffer (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

pointeur vers "string", ou NULL

Exemples en 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) :

# prototype
def string_input_for_buffer(string: str) -> str: ...

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

string_eval_expression

WeeChat ≥ 0.4.0, mis à jour dans la 0.4.2, 0.4.3, 1.0, 1.1, 1.2, 1.3, 1.6, 1.8, 2.0, 2.2, 2.3, 2.7, 2.9, 3.1, 3.2, 3.3, 3.4, 3.6, 3.8, 4.0.0, 4.2.0.

Évaluer l’expression et retourner le résultat sous forme de chaîne. Les variables spéciales avec le format ${variable} sont étendues (voir le tableau ci-dessous).

Depuis la version 1.0, les variables imbriquées sont supportées, par exemple : ${color:${variable}}.

Prototype :

char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);

Paramètres :

expr : l’expression à évaluer (voir les conditions et variables)
pointers : table de hachage avec les pointeurs (les clés doivent être des chaînes, les valeurs doivent être des pointeurs) ; les pointeurs "window" et "buffer" sont automatiquement ajoutés s’ils ne sont pas dans la table de hachage (avec le pointeur vers fenêtre/tampon courants) (peut être NULL) :
- regex : pointeur vers une expression régulière (structure regex_t) compilée avec la fonction WeeChat string_regcomp ou regcomp (voir man regcomp) ; cette option est similaire à regex dans la table de hachage options (ci-dessous), mais est utilisée pour de meilleures performances
extra_vars : variables additionnelles qui seront étendues (peut être NULL)
options : table de hachage avec des options (les clés et valeurs doivent être des chaînes) (peut être NULL) :
- type : le comportement par défaut est de juste remplacer les valeurs dans l’expression, d’autres types peuvent être choisis :
  - condition : l’expression est évaluée comme une condition : les opérateurs et parenthèses sont utilisés, le résultat est un booléen ("0" ou "1")
- prefix : préfixe avant les variables à remplacer (par défaut : ${)
- suffix : suffixe après les variables à remplacer (par défaut : })
- extra : le comportement par défaut est juste de remplacer les variables additionnelles (extra_vars), un autre comportement peut être sélectionné :
  - eval : les variables additionnelles (extra_vars) sont évaluées elles-mêmes avant remplacement (WeeChat ≥ 1.6)
- regex : une expression regulière pour remplacer du texte dans expr (qui n’est alors pas évalué)
- regex_replace : le texte de remplacement à utiliser avec regex, pour remplacer du texte dans expr (regex_replace est évalué sur chaque correspondance de regex sur expr, jusqu’à ce que plus aucune correspondance ne soit trouvée)
- debug : niveau de debug (chaîne avec un nombre entier ≥ 1), si activé, une clé "debug_output" est ajoutée dans la table de hachage options :
  - 1 : activer le debug
  - 2 : activer le debug plus verbeux

Valeur de retour :

expression évaluée (doit être supprimée après un appel à "free" après utilisation), ou NULL si problème (expression invalide ou pas assez de mémoire)

Exemples en C :

/* conditions */
struct t_hashtable *options1 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
weechat_hashtable_set (options1, "type", "condition");
char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */

/* expression simple */
char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */

/* remplacement avec regex */
struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
/* ajout de crochets autour des URLs */
weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+");
weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
char *str4 = weechat_string_eval_expression ("test : https://weechat.org", NULL, NULL, NULL);  /* "test : [ https://weechat.org ]" */

/* masquage des mots de passe */
weechat_hashtable_set (options2, "regex", "(password=)([^ ]+)");
weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */

Script (Python) :

# prototype
def string_eval_expression(expr: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# exemples

# conditions
str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"

# expression simple
str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"

# remplacement avec regex : ajout de crochets autour des URLs
options = {
    "regex": "[a-zA-Z0-9_]+://[^ ]+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test : https://weechat.org", {}, {}, options)  # "test : [ https://weechat.org ]"

# replace with regex : masquage des mots de passe
options = {
    "regex": "(password=)([^ ]+)",
    "regex_replace": "${re:1}${hide:*,${re:2}}",
}
str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"

Conditions

Liste des opérateurs logiques qui peuvent être utilisés dans les conditions (par ordre de priorité, du premier utilisé au dernier) :

Opérateur WeeChat mini Description Exemples

&&

"Et" logique

>> 25 && 77
== 1

>> 25 && 0
== 0

||

"Ou" logique

>> 25 || 0
== 1

>> 0 || 0
== 0

Liste des opérateurs de comparaison qui peuvent être utilisés dans les conditions (par ordre de priorité, du premier utilisé au dernier) :

Opérateur WeeChat mini Description Exemples

=~

Correspond à l’expression régulière POSIX étendue (des "flags" facultatifs sont autorisés, voir la fonction string_regcomp)

>> abc def =~ ab.*ef
== 1

>> abc def =~ y.*z
== 0

!~

Ne correspond PAS à l’expression régulière POSIX étendue (des "flags" facultatifs sont autorisés, voir la fonction string_regcomp)

>> abc def !~ ab.*ef
== 0

>> abc def !~ y.*z
== 1

==*

2.9

Correspond au masque où le caractère joker "*" est autorisé, sensible à la casse (voir la fonction string_match)

>> abc def ==* a*f
== 1

>> abc def ==* y*z
== 0

!!*

2.9

Ne correspond PAS au masque où le caractère joker "*" est autorisé, sensible à la casse (voir la fonction string_match)

>> abc def !!* a*f
== 0

>> abc def !!* y*z
== 1

=*

1.8

Correspond au masque où le caractère joker "*" est autorisé, insensible à la casse (voir la fonction string_match)

>> abc def =* A*F
== 1

>> abc def =* Y*Z
== 0

!*

1.8

Ne correspond PAS au masque où le caractère joker "*" est autorisé, insensible à la casse (voir la fonction string_match)

>> abc def !* A*F
== 0

>> abc def !* Y*Z
== 1

==-

2.9

Est inclus, sensible à la casse

>> abc def ==- bc
== 1

>> abc def ==- xyz
== 0

!!-

2.9

N’est PAS inclus, sensible à la casse

>> abc def !!- bc
== 0

>> abc def !!- xyz
== 1

=-

2.9

Est inclus, insensible à la casse

>> abc def =- BC
== 1

>> abc def =- XYZ
== 0

!-

2.9

N’est PAS inclus, insensible à la casse

>> abc def !- BC
== 0

>> abc def !- XYZ
== 1

==

Égal

>> test == test
== 1

>> test == string
== 0

!=

Non égal

>> test != test
== 0

>> test != string
== 1

<=

Plus petit ou égal

>> abc <= defghi
== 1

>> abc <= abc
== 1

>> defghi <= abc
== 0

>> 15 <= 2
== 0

<

Plus petit

>> abc < defghi
== 1

>> abc < abc
== 0

>> defghi < abc
== 0

>> 15 < 2
== 0

>=

Plus grand ou égal

>> defghi >= abc
== 1

>> abc >= abc
== 1

>> abc >= defghi
== 0

>> 15 >= 2
== 1

>

Plus grand

>> defghi > abc
== 1

>> abc > abc
== 0

>> abc > defghi
== 0

>> 15 > 2
== 1

La comparaison est faite en utilisant des nombres à virgule si les deux expressions sont des nombres valides, avec l’un de ces formats :

entier (exemples : 5, -7)
nombre à virgule (exemples : 5.2, -7.5, 2.83e-2) (WeeChat ≥ 2.0)
nombre hexadécimal (exemples : 0xA3, -0xA3) (WeeChat ≥ 2.0)

Pour forcer une comparaison de chaînes, vous pouvez ajouter des guillemets autour de chaque expression, par exemple :

50 > 100 retourne 0 (comparaison de nombres)
"50" > "100" retourne 1 (comparaison de chaînes)

Variables

Liste des variables étendues dans l’expression (par ordre de priorité, de la première étendue à la dernière) :

Format WeeChat mini Description Exemples

${raw_hl:xxx}

4.2.0

Chaîne brute (non évaluée), avec mise en évidence de la syntaxe (en utilisant des couleurs).

>> ${raw_hl:${cut:1,,${rev:hello}}}
== ${cut:1,,${rev:hello}} (avec des couleurs)

${raw:xxx}

3.1

Chaîne brute (non évaluée).

>> ${raw:${info:version}}
== ${info:version}

${hl:xxx}

4.2.0

Chaîne avec mise en évidence de la syntaxe (en utilisant des couleurs).

>> ${hl:${fichier.section.option}}
== test ${variable} (avec des couleurs)

${nom}

3.4

Variable définie par l’utilisateur (avec ${define:nom,valeur}).

>> ${nom}
== valeur

${nom}

Variable nom de la table de hachage extra_vars.

>> ${nom}
== valeur

${weechat_xxx_dir}

3.2

Un répertoire WeeChat : ${weechat_config_dir}, ${weechat_data_dir}, ${weechat_cache_dir} ou ${weechat_runtime_dir}.

>> ${weechat_config_dir}
== /home/user/.config/weechat

>> ${weechat_data_dir}
== /home/user/.local/share/weechat

>> ${weechat_cache_dir}
== /home/user/.cache/weechat

>> ${weechat_runtime_dir}
== /run/user/1000/weechat

${eval:xxx}

1.3

Chaîne à évaluer.

>> ${eval:${date:${weechat.look.buffer_time_format}}}
== 19:02:45 ⁽¹⁾

⁽¹⁾ Avec des couleurs s’il y a des codes couleur dans l’option weechat.look.buffer_time_format

${eval_cond:xxx}

3.1

Chaîne à évaluer comme condition.

>> ${eval_cond:${window.win_width} > 100}
== 1

${esc:xxx}
${\xxx}

1.0

Chaîne avec caractères échappés.

>> ${esc:préfixe\tmessage}
== préfixe<TAB>message

>> ${\ua9}
== ©

${chars:range}

3.8

Chaîne avec un intervalle de caractères, où range est parmi :
- digit (0123456789)
- xdigit (0123456789abcdefABCDEF)
- lower (toutes les lettres en minuscules)
- upper (toutes les lettres en majuscules)
- alpha (toutes les lettres)
- alnum (toutes les lettres et chiffres)
- un intervalle de caractères avec le format c1-c2 (le code de c1 doit être inférieur ou égal à celui de c2)

>> ${chars:digit}
== 0123456789

>> ${chars:xdigit}
== 0123456789abcdefABCDEF

>> ${chars:lower}
== abcdefghijklmnopqrstuvwxyz

>> ${chars:J-V}
== JKLMNOPQRSTUV

>> ${chars:←-↓}
== ←↑→↓

${lower:string}

3.6

Chaîne convertie en minuscules.

>> ${lower:TEST}
== test

${upper:string}

3.6

Chaîne convertie en majuscules.

>> ${upper:test}
== TEST

${hide:x,chaîne}

1.1

Chaîne avec les caractères masqués (tous les caractères dans chaîne remplacés par x).

>> ${hide:*,mot_de_passe}
== ************

${cut:max,suffixe,chaîne}
${cut:+max,suffixe,chaîne}

1.8

Chaîne avec max caractères, et un suffixe facultatif si la chaîne est coupée.
Avec le format +max, le suffixe est compté dans la longueur maximale.

>> ${cut:4,…,ceci est un test}
== ceci…

>> ${cut:+4,…,ceci est un test}
== c…

>> ${cut:2,>>,こんにちは世界}
== こん>>

${cutscr:max,suffixe,chaîne}
${cutscr:+max,suffixe,chaîne}

1.8

Chaîne avec max caractères affichés à l’écran, et un suffixe facultatif si la chaîne est coupée.
Avec le format +max, le suffixe est compté dans la longueur maximale.

>> ${cutscr:4,…,ceci est un test}
== ceci…

>> ${cutscr:+4,…,ceci est un test}
== cec…

>> ${cutscr:2,>>,こんにちは世界}
== こ>>

${rev:xxx}

2.2

Chaîne inversée (les codes couleurs sont inversés, donc la chaîne ne devrait pas contenir de codes couleurs).

>> ${rev:Bonjour, le monde !}
== ! ednom el ,ruojnoB

>> ${rev:Bonjour, ${color:red}le monde !}
== ! ednom el30F ,ruojnoB ⁽¹⁾

⁽¹⁾ Pas de couleur, le code couleur est inversé

${revscr:xxx}

2.7

Chaîne inversée pour l’écran : les codes couleurs ne sont pas inversés.

>> ${revscr:Bonjour, le monde !}
== ! ednom el ,ruojnoB

>> ${revscr:Bonjour, ${color:red}le monde !}
== ! ednom el ,ruojnoB ⁽¹⁾

⁽¹⁾ ( ,ruojnoB en rouge

${repeat:nombre,chaîne}

2.3

Chaîne répétée.

>> ${repeat:5,-}
== -----

${length:xxx}

2.7

Longueur de la chaîne (nombre de caractères UTF-8), les codes couleurs sont ignorés.

>> ${length:test}
== 4

>> ${length:こんにちは世界}
== 7

${lengthscr:xxx}

2.7

Longueur de la chaîne affichée à l’écran, les codes couleurs sont ignorés.

>> ${lengthscr:test}
== 4

>> ${lengthscr:こんにちは世界}
== 14

${split:number,seps,flags,xxx}

3.3

Chaîne découpée, et retour, selon number :
- count : nombre d’éléments après le découpage
- random : un élément au hasard
- entier ≥ 1 : l’élément par son index (1 = premier élément)
- entier ≤ -1 : l’élément par son index en partant de la fin (-1 = dernier élément, -2 = avant-dernier élément, etc.),
seps est une liste de caractères qui sont utilisés comme séparateurs (si vide, une virgule est utilisé),
flags est une liste de drapeaux séparés par +:
- strip_left : supprimer les séparateurs sur la gauche (début de chaîne)
- strip_right : supprimer les séparateurs sur la droite (fin de chaîne)
- collapse_seps : regrouper de multiples séparateurs consécutifs en un seul
- keep_eol : garder jusqu’à la fin de la ligne pour chaque valeur
- strip_items=xyz : supprimer les caractères x, y et z au début/fin des éléments
- max_items=N : retourner au plus N éléments

>> ${split:1,,,abc,def,ghi}
== abc

>> ${split:-1,,,abc,def,ghi}
== ghi

>> ${split:count,,,abc,def,ghi}
== 3

>> ${split:random,,,abc,def,ghi}
== def

>> ${split:3,,collapse_seps,abc,,,def,,,ghi}
== ghi

>> ${split:3,,strip_items=-_,_-abc-_,_-def-_,_-ghi-_}
== ghi

>> ${split:2, ,,this is a test}
== is

>> ${split:2, ,strip_left+strip_right, this is a test }
== is

>> ${split:2, ,keep_eol,this is a test}
== is a test

${split_shell:number,xxx}

3.3

Paramètres shells découpés, et retour, selon number :
- count : le nombre de paramètres après découpage
- random : un paramètre au hasard
- entier ≥ 1 : le paramètre par son index (1 = premier paramètre)
- entier ≤ -1 : le paramètre par son index en partant de la fin (-1 = dernier paramètre, -2 = avant-dernier paramètre, etc.)

>> ${split_shell:1,"first arg" arg2}
== first arg

>> ${split_shell:-1,"first arg" arg2}
== arg2

>> ${split_shell:count,"first arg" arg2}
== 2

>> ${split_shell:random,"first arg" arg2}
== arg2

${re:xxx}

1.1

Données sur l’expression régulière :
0 = toute la chaîne correspondante,
1 à 99 = groupe capturé,
+ = dernier groupe capturé,
# = index du dernier groupe capturé (WeeChat ≥ 1.8)
repl_index = index du remplacement en cours (démarre à 1) (WeeChat ≥ 3.3).

>> ${re:0}
== test1 test2

>> ${re:1}
== test1

>> ${re:2}
== test2

>> ${re:+}
== test2

>> ${re:#}
== 2

>> ${re:repl_index}
== 1

${color:nom}

0.4.2

Code couleur WeeChat (le nom de couleur a des attributs facultatifs), voir la fonction color pour les formats supportés.

>> ${color:red}texte rouge
== texte rouge ⁽¹⁾

>> ${color:*214}texte orange gras
== texte orange gras ⁽²⁾

⁽¹⁾ En rouge
⁽²⁾ En orange gras

${modifier:name,data,string}

2.7

Résultat d’un modificateur, voir la fonction hook_modifier_exec.

>> ${modifier:eval_path_home,,~}
== /home/user

>> ${modifier:eval_path_home,directory=config,%h/irc.conf}
== /home/user/.config/weechat/irc.conf

${info:nom}
${info:nom,paramètres}

0.4.3

Info de WeeChat ou d’une extension, voir la fonction info_get.

>> ${info:version}
== 1.0

>> ${info:nick_color_name,foo}
== lightblue

${base_encode:base,xxx}

2.9

Chaîne encodée en base 16, 32 ou 64.

>> ${base_encode:16,test string}
== 7465737420737472696E67

>> ${base_encode:32,test string}
== ORSXG5BAON2HE2LOM4======

>> ${base_encode:64,test string}
== dGVzdCBzdHJpbmc=

${base_decode:base,xxx}

2.9

Chaîne décodée depuis base 16, 32 ou 64.

>> ${base_decode:16,7465737420737472696E67}
== test string

>> ${base_decode:32,ORSXG5BAON2HE2LOM4======}
== test string

>> ${base_decode:64,dGVzdCBzdHJpbmc=}
== test string

${date}
${date:xxx}

1.3

La date/heure courante, avec un format personnalisé (voir man strftime), le format par défaut est %F %T.

>> ${date}
== 2015-06-30 19:02:45

>> ${date:%H:%M:%S}
== 19:02:45

${env:NOM}

1.2

Valeur de la variable d’environnement NOM.

>> ${env:HOME}
== /home/user

${if:condition}
${if:condition?vrai} ${if:condition?vrai:faux}

1.8

Opérateur ternaire avec une condition, une valeur si la condition est vraie (optionnelle) et une autre valeur si la condition est fausse (optionnelle). Si les valeurs ne sont pas données, "1" ou "0" est retourné, selon le résultat de la condition.

>> ${if:${info:term_width}>80?grand:petit}
== grand

${calc:xxx}

2.7

Résultat de l’expression, où les parenthèses et les opérateurs suivants sont supportés :
+ : addition
- : soustraction
* : multiplication
/ : division
// : résultat de la division sans la partie décimale
% : reste de la division
**: puissance.

>> ${calc:5+2*3}
== 11

>> ${calc:(5+2)*3}
== 21

>> ${calc:10/4}
== 2.5

>> ${calc:10//4}
== 2

>> ${calc:9.2%3}
== 0.2

>> ${calc:2**16}
== 65536

${random:min,max}

3.3

Nombre entier aléatoire dans l’intervalle de min à max (inclus).

>> ${random:0,10}
== 3

${translate:xxx}

3.2

Chaîne traduite (dépend de la langue utilisée par WeeChat pour afficher les messages).

>> ${translate:Plugin}
== Extension ⁽¹⁾

⁽¹⁾ Exemple en Français

${define:nom,valeur}

3.4

Définir une variable nom à valeur, qui peut être utilisée dans la même expression évaluée avec ${nom}.

>> ${define:len,${calc:5+3}}${len}x${len}
== 8x8

${sec.data.nom}

Valeur de la donnée sécurisée nom.

>> ${sec.data.libera_pass}
== mon_mot_de_passe

${fichier.section.option}

Valeur de l’option.

>> ${weechat.look.buffer_time_format}
== %H:%M:%S

${nom}

Valeur de la variable locale nom dans le tampon.

>> ${nick}
== FlashCode

${pointeur}

Variable pointeur de la table de hachage pointers.

>> ${buffer}
== 0x1234abcd

${hdata.var1.var2...}
${hdata[list].var1.var2...}

Valeur d’un hdata (les pointeurs window et buffer sont définis par défaut avec la fenêtre et tampon courants), list peut être le nom d’une liste (exemple : "gui_buffers"), un pointeur (exemple : "0x1234abcd") ou un nom de pointeur (exemple : "mon_pointeur").
Lorsque var1 est une table de hachage, les méthodes keys(), values(), keys_sorted(), keys_values() et keys_values_sorted() peuvent être appelées.

>> ${buffer[gui_buffers].full_name}
== core.weechat

>> ${buffer[mon_pointeur_buffer].full_name}
== core.weechat

>> ${window.buffer.number}
== 1

>> ${buffer.local_variables.keys_values()}
== plugin:core,name:weechat

>> ${buffer.local_variables.plugin}
== core

string_dyn_alloc

WeeChat ≥ 1.8.

Allouer une chaîne dynamique, avec une longueur variable.
De manière interne, une structure est allouée avec le pointeur vers la chaîne, la taille allouée et la longueur courante de la chaîne.

Seul le pointeur de pointeur de chaîne (**string) est utilisé dans toutes les fonctions string_dyn_*.

Prototype :

char **weechat_string_dyn_alloc (int size_alloc);

Paramètres :

size_alloc : la taille initialement allouée (doit être supérieure à zéro)

Valeur de retour :

pointeur vers la chaîne dynamique

Exemple en C :

char **string = weechat_string_dyn_alloc (256);

Cette fonction n’est pas disponible dans l’API script.

string_dyn_copy

WeeChat ≥ 1.8.

Copier une chaîne dans une chaîne dynamique.

Le pointeur *string peut changer si la chaîne est réallouée (s’il n’y a pas assez de place pour copier la chaîne).

Prototype :

int weechat_string_dyn_copy (char **string, const char *new_string);

Paramètres :

string : pointeur vers la chaîne dynamique
new_string : la chaîne à copier

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    /* OK */
}
else
{
    /* erreur */
}

Cette fonction n’est pas disponible dans l’API script.

string_dyn_concat

WeeChat ≥ 1.8, mis à jour en 3.0.

Concaténer une chaîne dans une chaîne dynamique.

Le pointeur *string peut changer si la chaîne est réallouée (s’il n’y a pas assez de place pour concaténer la chaîne).

Prototype :

int weechat_string_dyn_concat (char **string, const char *add, int bytes);

Paramètres :

string : pointeur vers la chaîne dynamique
add : la chaîne à ajouter
bytes : nombre maximum d’octets de add à concaténer, doit être inférieur ou égal à la longueur de add (-1 = automatique : concaténer la totalité de la chaîne add) (WeeChat ≥ 3.0)

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    if (weechat_string_dyn_concat (string, "abc", -1))
    {
        /* ... */
    }
}

Cette fonction n’est pas disponible dans l’API script.

string_dyn_free

WeeChat ≥ 1.8.

Libérer une chaîne dynamique.

Prototype :

char *weechat_string_dyn_free (char **string, int free_string);

Paramètres :

string : pointeur vers la chaîne dynamique
free_string : libérer la chaîne elle-même ; si 0, le contenu de *string reste valide après l’appel à cette fonction

Valeur de retour :

pointeur vers la chaîne si free_string vaut 0, sinon NULL

Exemple en C :

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_concat (string, "test"))
{
    /* OK */
}
else
{
    /* erreur */
}
/* ... */
weechat_string_dyn_free (string, 1);

Cette fonction n’est pas disponible dans l’API script.

string_concat

WeeChat ≥ 4.2.0.

Concaténer plusieurs chaînes de caractères en utilisant un séparateur.

Prototype :

const char *weechat_string_concat (const char *separator, ...);

Paramètres :

separator : la chaîne de séparation qui est insérée entre les chaînes concaténées (peut être NULL ou une chaîne vide)

Le dernier paramètre DOIT toujours être NULL.
Une macro nommée WEECHAT_STR_CONCAT peut être utilisée, où la valeur finale NULL n’est pas nécessaire (l’utilisation de cette macro est recommandée).

Valeur de retour :

chaîne concaténée

Exemple en C :

const char *result = weechat_string_concat (" / ", "abc", "def", "ghi", NULL);  /* result == "abc / def / ghi" */

/* with macro */
const char *result = WEECHAT_STR_CONCAT(" / ", "abc", "def", "ghi");  /* result == "abc / def / ghi" */

Cette fonction n’est pas disponible dans l’API script.

3.4. UTF-8

Fonctions pour les chaînes UTF-8.

utf8_has_8bits

Vérifier si une chaîne a des caractères 8-bits.

Prototype :

int weechat_utf8_has_8bits (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

1 si la chaîne a des caractères 8-bits, 0 s’il y a seulement des caractères 7-bits

Exemple en C :

if (weechat_utf8_has_8bits (string))
{
    /* ... */
}

Cette fonction n’est pas disponible dans l’API script.

utf8_is_valid

Mis à jour dans la 1.4.

Vérifier si une chaîne est valide UTF-8.

Prototype :

int weechat_utf8_is_valid (const char *string, int length, char **error);

Paramètres :

string : chaîne
length : nombre maximum de caractères UTF-8 à vérifier ; si ≤ 0, la chaîne complète est vérifiée (WeeChat ≥ 1.4)
error : si non NULL, *error est alimenté avec le pointeur vers le premier caractère non valide dans la chaîne, s’il y en a

Valeur de retour :

1 si la chaîne UTF-8 est valide, sinon 0

Exemple en C :

char *error;
if (weechat_utf8_is_valid (string, -1, &error))
{
    /* ... */
}
else
{
    /* "error" pointe vers le premier caractère invalide */
}

Cette fonction n’est pas disponible dans l’API script.

utf8_normalize

Normaliser une chaîne UTF-8 : supprimer tous les caractères non valides UTF-8 en les remplaçant par un caractère.

Prototype :

void weechat_utf8_normalize (char *string, char replacement);

Paramètres :

string : chaîne
replacement : caractère de remplacement pour les caractères non valides

Exemple en C :

weechat_utf8_normalize (string, '?');

Cette fonction n’est pas disponible dans l’API script.

utf8_prev_char

Mis à jour dans la 1.3.

Retourner un pointeur vers le caractère UTF-8 précédent dans une chaîne.

Prototype :

const char *weechat_utf8_prev_char (const char *string_start,
                                    const char *string);

Paramètres :

string_start : début de la chaîne (la fonction ne retournera pas un caractère situé avant ce pointeur)
string : pointeur vers la chaîne (doit être ≥ string_start)

Valeur de retour :

pointeur vers le caractère UTF-8 précédent, NULL si non trouvé (début de chaîne atteint) (WeeChat ≥ 1.3 : le pointeur retourné est un const char * au lieu d’un char *)

Exemple en C :

const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

Cette fonction n’est pas disponible dans l’API script.

utf8_next_char

Mis à jour dans la 1.3.

Retourner un pointeur vers le caractère UTF-8 suivant dans une chaîne.

Prototype :

const char *weechat_utf8_next_char (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

pointeur vers le caractère UTF-8 suivant, NULL si non trouvé (fin de la chaîne atteinte) (WeeChat ≥ 1.3 : le pointeur retourné est un const char * au lieu d’un char *)

Exemple en C :

const char *next_char = weechat_utf8_next_char (string);

Cette fonction n’est pas disponible dans l’API script.

utf8_char_int

Retourner un caractère UTF-8 sous forme d’entier.

Prototype :

int weechat_utf8_char_int (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

caractère UTF-8 sous forme d’entier

Exemple en C :

int char_int = weechat_utf8_char_int ("être");  /* "ê" comme entier */

Cette fonction n’est pas disponible dans l’API script.

utf8_char_size

Retourner la taille d’un caractère UTF-8 (en octets).

Prototype :

int weechat_utf8_char_size (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

taille du caractère UTF-8 (en octets)

Exemple en C :

int char_size = weechat_utf8_char_size ("être");  /* == 2 */

Cette fonction n’est pas disponible dans l’API script.

utf8_strlen

Retourner la taille d’une chaîne UTF-8 (en nombre de caractères UTF-8).

Prototype :

int weechat_utf8_strlen (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

longueur de la chaîne UTF-8 (nombre de caractères UTF-8)

Exemple en C :

int length = weechat_utf8_strlen ("chêne");  /* == 5 */

Cette fonction n’est pas disponible dans l’API script.

utf8_strnlen

Retourner la taille d’une chaîne UTF-8 (en nombre de caractères UTF-8), pour au maximum bytes octets dans la chaîne.

Prototype :

int weechat_utf8_strnlen (const char *string, int bytes);

Paramètres :

string : chaîne
bytes : nombre maximum d’octets

Valeur de retour :

longueur de la chaîne UTF-8 (nombre de caractères UTF-8)

Exemple en C :

int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */

Cette fonction n’est pas disponible dans l’API script.

utf8_strlen_screen

Retourner le nombre de caractères nécessaires pour afficher la chaîne UTF-8 sur l’écran.

Prototype :

int weechat_utf8_strlen_screen (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

nombre de caractères nécessaires pour afficher la chaîne UTF-8 sur l’écran

Exemple en C :

int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */

Cette fonction n’est pas disponible dans l’API script.

utf8_char_size_screen

Mis à jour dans la 3.8.

Retourner le nombre de caractères nécessaires pour afficher le caractère UTF-8 sur l’écran.

Prototype :

int weechat_utf8_char_size_screen (const char *string);

Paramètres :

string : chaîne

Valeur de retour :

nombre de caractères nécessaires pour afficher le caractère UTF-8 sur l’écran :
- -1 : caractère non affichable
- ≥ 0 : caractère affichable

Le résultat est la valeur de retour de la fonction wcwidth (voir man wcwidth), avec une exception pour les caractères suivants, qui ont un comportement spécifique dans WeeChat :

U+0009 (Tabulation) : valeur de l’option weechat.look.tab_width ^↗
U+0001 (1) to U+001F (31), sauf U+0009 (Tabulation) : 1
U+00AD (173, trait d’union conditionnel) : -1
U+200B (8203, espace sans chasse) : -1

Exemple en C :

int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */

Cette fonction n’est pas disponible dans l’API script.

utf8_add_offset

Mis à jour dans la 1.3.

Avancer de N caractères dans une chaîne UTF-8.

Prototype :

const char *weechat_utf8_add_offset (const char *string, int offset);

Paramètres :

string : chaîne
offset : nombre de caractères

Valeur de retour :

pointeur vers la chaîne, N caractères après (NULL s’il est impossible d’atteindre cette position dans la chaîne) (WeeChat ≥ 1.3 : le pointeur retourné est un const char * au lieu d’un char *)

Exemple en C :

const char *str = "chêne";
const char *str2 = weechat_utf8_add_offset (str, 3);  /* pointe vers "ne" */

Cette fonction n’est pas disponible dans l’API script.

utf8_real_pos

Retourner la position réelle dans une chaîne UTF-8.

Prototype :

int weechat_utf8_real_pos (const char *string, int pos);

Paramètres :

string : chaîne
pos : position (en nombre de caractères)

Valeur de retour :

position réelle (en octets)

Exemple en C :

int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */

Cette fonction n’est pas disponible dans l’API script.

utf8_pos

Retourner la position dans une chaîne UTF-8.

Prototype :

int weechat_utf8_pos (const char *string, int real_pos);

Paramètres :

string : chaîne
real_pos : position (en octets)

Valeur de retour :

position (en nombre de caractères)

Exemple en C :

int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */

Cette fonction n’est pas disponible dans l’API script.

utf8_strndup

Retourner une chaîne dupliquée, avec au plus length caractères.

Prototype :

char *weechat_utf8_strndup (const char *string, int length);

Paramètres :

string : chaîne
length : nombre maximum de caractères à dupliquer

Valeur de retour :

chaîne dupliquée (doit être supprimée avec un appel à "free" après utilisation)

Exemple en C :

char *string = weechat_utf8_strndup ("chêne", 3);  /* retourne "chê" */
/* ... */
free (str);

Cette fonction n’est pas disponible dans l’API script.

utf8_strncpy

WeeChat ≥ 3.8.

Copier au plus length caractères dans une autre chaîne et ajouter l’octet nul à la fin.

Prototype :

void weechat_utf8_strncpy (char *dest, const char *string, int length);

Paramètres :

dest : chaîne de destination (doit être suffisamment grande)
string : chaîne
length : nombre maximum de caractères à copier

Exemple en C :

char dest[256];

weechat_utf8_strncpy (dest, "chêne", 3);  /* copie "chê" dans dest */

Cette fonction n’est pas disponible dans l’API script.

3.5. Cryptographie

Fonctions de cryptographie.

crypto_hash

WeeChat ≥ 2.8.

Calculer le hachage des données.

Prototype :

int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo,
                         void *hash, int *hash_size);

Paramètres :

data : les données à hacher
data_size : nombre d’octets à hacher dans data
hash_algo : l’algorithme de hachage, voir le tableau ci-dessous
hash : pointeur vers la variable de hachage, qui est utilisée pour stocker le résultat du hachage (le tampon doit être suffisamment grand, selon l’algorithme, voir le tableau ci-dessous)
hash_size : pointeur vers une variable utiliser pour stocker la longueur du résultat du hachage (en octets) (peut être NULL)

Algorithmes de hachage supportés :

Valeur Algorithme Taille du haché Notes

crc32

CRC32

4 octets (32 bits)

Pas un algorithme de hachage au sens cryptographique.

md5

MD5

16 octets (128 bits)

Faible, non recommandé pour un usage cryptographique.

sha1

SHA-1

20 octets (160 bits)

Faible, non recommandé pour un usage cryptographique.

sha224

SHA-224

28 octets (224 bits)

sha256

SHA-256

32 octets (256 bits)

sha384

SHA-384

48 octets (384 bits)

sha512

SHA-512

64 octets (512 bits)

sha512-224

SHA-512/224

28 octets (224 bits)

Algorithme disponible avec libgcrypt ≥ 1.9.4.

sha512-256

SHA-512/256

32 octets (256 bits)

Algorithme disponible avec libgcrypt ≥ 1.9.4.

sha3-224

SHA3-224

28 octets (224 bits)

Algorithme disponible avec libgcrypt ≥ 1.7.0.

sha3-256

SHA3-256

32 octets (256 bits)

Algorithme disponible avec libgcrypt ≥ 1.7.0.

sha3-384

SHA3-384

48 octets (384 bits)

Algorithme disponible avec libgcrypt ≥ 1.7.0.

sha3-512

SHA3-512

64 octets (512 bits)

Algorithme disponible avec libgcrypt ≥ 1.7.0.

blake2b-160

BLAKE2B-160

20 octets (160 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2b-256

BLAKE2B-256

32 octets (256 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2b-384

BLAKE2B-384

48 octets (384 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2b-512

BLAKE2B-512

64 octets (512 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2s-128

BLAKE2S-128

16 octets (128 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2s-160

BLAKE2S-160

20 octets (160 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2s-224

BLAKE2S-224

28 octets (224 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

blake2s-256

BLAKE2S-256

32 octets (256 bits)

Algorithme disponible avec libgcrypt ≥ 1.8.0.

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

const char *data = "abcdefghijklmnopqrstuvwxyz";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 et hash est un tampon avec :
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

Cette fonction n’est pas disponible dans l’API script.

crypto_hash_file

WeeChat ≥ 3.7.

Calculer le hachage d’un fichier.

Prototype :

int weechat_crypto_hash_file (const char *filename, const char *hash_algo,
                              void *hash, int *hash_size);

Paramètres :

filename : chemin et nom du fichier
hash_algo : l’algorithme de hachage, voir le tableau de la fonction crypto_hash
hash : pointeur vers la variable de hachage, qui est utilisée pour stocker le résultat du hachage (le tampon doit être suffisamment grand, selon l’algorithme, voir le tableau de la fonction crypto_hash)
hash_size : pointeur vers une variable utiliser pour stocker la longueur du résultat du hachage (en octets) (peut être NULL)

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_file ("/chemin/vers/fichier", "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 et hash est un tampon avec :
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

Cette fonction n’est pas disponible dans l’API script.

crypto_hash_pbkdf2

WeeChat ≥ 2.8.

Calculer le hachage PBKDF2 (PKCS#5 Passphrase Based Key Derivation Function number 2) des données.

Prototype :

int weechat_crypto_hash_pbkdf2 (const void *data, int data_size,
                                const char *hash_algo,
                                const void *salt, int salt_size,
                                int iterations,
                                void *hash, int *hash_size);

Paramètres :

data : les données à hacher
data_size : nombre d’octets à hacher dans data
hash_algo : algorithme de hachage utilisé dans la fonction de dérivation de clé, voir le tableau dans la fonction crypto_hash
salt : le sel
salt_size : nombre d’octets dans salt
iterations : nombre d’itérations
hash : pointeur vers la variable de hachage, qui est utilisée pour stocker le résultat du hachage (le tampon doit être suffisamment grand, selon l’algorithme, voir le tableau dans la fonction crypto_hash)
hash_size : pointeur vers une variable utiliser pour stocker la longueur du résultat du hachage (en octets) (peut être NULL)

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

const char *data = "abcdefghijklmnopqrstuvwxyz";
const char *salt = "12345678901234567890123456789012";  /* 32 octets */
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000,
                                 hash, &hash_size);
/* rc == 1, hash_size == 32 et hash est un tampon avec :
   99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */

Cette fonction n’est pas disponible dans l’API script.

crypto_hmac

WeeChat ≥ 3.2.

Calculer le code d’authentification d’une empreinte cryptographique de message avec clé (HMAC).

Prototype :

int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size,
                         int hash_algo, void *hash, int *hash_size);

Paramètres :

key : la clé
key_size : nombre d’octets dans key
message : le message
message_size : nombre d’octets dans message
hash_algo : l’algorithme de hachage, voir le tableau dans la fonction crypto_hash
hash : pointeur vers la variable de hachage, qui est utilisée pour stocker le résultat du hachage (le tampon doit être suffisamment grand, selon l’algorithme, voir le tableau dans la fonction crypto_hash)
hash_size : pointeur vers une variable utiliser pour stocker la longueur du résultat du hachage (en octets) (peut être NULL)

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

const char *key = "the key";
const char *message = "the message";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 et hash est un tampon avec :
   47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */

Cette fonction n’est pas disponible dans l’API script.

3.6. Répertoires

Fonctions liées aux répertoires.

mkdir_home

Mis à jour dans la 3.2.

Créer un répertoire dans le répertoire de WeeChat.

Prototype :

int weechat_mkdir_home (char *directory, int mode);

Paramètres :

directory : nom du répertoire à créer ; il peut commencer par une de ces chaînes pour forcer un répertoire spécifique de WeeChat (WeeChat ≥ 3.2) :
- ${weechat_config_dir}
- ${weechat_data_dir} (par défaut)
- ${weechat_cache_dir}
- ${weechat_runtime_dir}
mode : mode pour le répertoire

Valeur de retour :

1 si le répertoire est créé, 0 en cas d’erreur

Exemple en C :

if (!weechat_mkdir_home ("${weechat_cache_dir}/temp", 0755))
{
    /* erreur */
}

Script (Python) :

# prototype
def mkdir_home(directory: str, mode: int) -> int: ...

# exemple
weechat.mkdir_home("${weechat_cache_dir}/temp", 0755)

mkdir

Créer un répertoire.

Prototype :

int weechat_mkdir (char *directory, int mode);

Paramètres :

directory : nom du répertoire à créer
mode : mode pour le répertoire

Valeur de retour :

1 si le répertoire est créé, 0 en cas d’erreur

Exemple en C :

if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* erreur */
}

Script (Python) :

# prototype
def mkdir(directory: str, mode: int) -> int: ...

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

mkdir_parents

Créer un répertoire et ses parents si besoin.

Prototype :

int weechat_mkdir_parents (char *directory, int mode);

Paramètres :

directory : nom du répertoire à créer
mode : mode pour le répertoire

Valeur de retour :

1 si le répertoire est créé, 0 en cas d’erreur

Exemple en C :

if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* erreur */
}

Script (Python) :

# prototype
def mkdir_parents(directory: str, mode: int) -> int: ...

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

exec_on_files

Mis à jour dans la 1.5, 2.0.

Balayer les fichiers dans un répertoire et exécuter une fonction de rappel pour chaque fichier.

Prototype :

void weechat_exec_on_files (const char *directory,
                            int recurse_subdirs,
                            int hidden_files,
                            void (*callback)(void *data,
                                             const char *filename),
                            void *callback_data);

Paramètres :

directory : répertoire où chercher les fichiers
recurse_subdirs : 1 pour entrer dans les sous-répertoires (WeeChat ≥ 2.0)
hidden_files : 1 pour inclure les fichiers cachés, sinon 0
callback : fonction appelée pour chaque fichier trouvé, paramètres :
- void *data : pointeur
- const char *filename : nom de fichier trouvé
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat

Exemple en C :

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

Cette fonction n’est pas disponible dans l’API script.

file_get_content

WeeChat ≥ 0.3.1.

Lire le contenu d’un fichier texte dans une chaîne de caractères.

Prototype :

char *weechat_file_get_content (const char *filename);

Paramètres :

filename : chemin et nom du fichier

Valeur de retour :

contenu du fichier sous forme de chaîne (doit être supprimé par un appel à "free" après utilisation)

Exemple en C :

char *contenu;

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

Cette fonction n’est pas disponible dans l’API script.

file_copy

WeeChat ≥ 3.3.

Copier un fichier vers une autre destination.

Prototype :

int weechat_file_copy (const char *from, const char *to);

Paramètres :

from : fichier source
to : fichier cible

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
{
    /* OK */
}

Cette fonction n’est pas disponible dans l’API script.

file_compress

WeeChat ≥ 3.7.

Compresser un fichier avec gzip ou zstd.

Prototype :

int weechat_file_compress (const char *from, const char *to,
                           const char *compressor, int compression_level);

Paramètres :

from : fichier source
to : fichier cible
compressor : le compresseur à utiliser, un parmi :
- gzip : compression gzip
- zstd : compression zstandard (disponible seulement si zstd a été activé lors de la compilation de WeeChat)
compression_level : niveau de compression, entre 1 (rapide, peu de compression) à 100 (lent, meilleure compression)

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
{
    /* OK */
}

Cette fonction n’est pas disponible dans l’API script.

3.7. Util

Quelques fonctions utiles.

util_timeval_cmp

Comparer deux structures "timeval".

Prototype :

int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);

Paramètres :

tv1 : première structure "timeval"
tv2 : seconde structure "timeval"

Valeur de retour :

-1 si tv1 < tv2
zéro si tv1 == tv2
+1 si tv1 > tv2

Exemple en C :

if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}

Cette fonction n’est pas disponible dans l’API script.

util_timeval_diff

Mis à jour dans la 1.1.

Retourner la différence (en microsecondes) entre deux structures "timeval".

Prototype :

long long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);

Paramètres :

tv1 : première structure "timeval"
tv2 : seconde structure "timeval"

Valeur de retour :

différence en microsecondes

Avec WeeChat ≤ 1.0, la valeur retournée était en millisecondes.

Exemple en C :

long long diff = weechat_util_timeval_diff (&tv1, &tv2);

Cette fonction n’est pas disponible dans l’API script.

util_timeval_add

Mis à jour dans la 1.1.

Ajouter un intervalle (en microsecondes) à une structure "timeval".

Prototype :

void weechat_util_timeval_add (struct timeval *tv, long long interval);

Paramètres :

tv : structure "timeval"
interval : intervalle (en microsecondes)

Avec WeeChat ≤ 1.0, l’intervalle était exprimé en millisecondes.

Exemple en C :

weechat_util_timeval_add (&tv, 2000000);  /* ajouter 2 secondes */

Cette fonction n’est pas disponible dans l’API script.

util_get_time_string

WeeChat ≥ 0.3.2, mise à jour dans la 1.3.

Retourner la date/heure sous forme de chaîne construite avec "strftime" et le format défini dans l’option weechat.look.time_format.

Prototype :

const char *weechat_util_get_time_string (const time_t *date);

Paramètres :

date : pointeur vers la date

Valeur de retour :

pointeur vers une chaîne contenant la date/heure

Exemple en C :

time_t date = time (NULL);
weechat_printf (NULL, "date : %s",
                weechat_util_get_time_string (&date));

Cette fonction n’est pas disponible dans l’API script.

util_strftimeval

WeeChat ≥ 4.2.0.

Formatter la date et l’heure comme la fonction strftime de la bibliothèque C, en utilisant un struct timeval en entrée et en supportant des caractères de conversion pour les microsecondes.

Prototype :

int weechat_util_strftimeval (char *string, int max, const char *format, struct timeval *tv);

Paramètres :

string : tampon où stocker la chaîne formattée
max : taille de la chaîne
format : format, le même que celui de la fonction strftime, avec des caractères de conversion supplémentaires :
- %.N où N est entre 1 and 6: microsecondes remplies avec des zéros sur N chiffres (par exemple %.3 pour les millisecondes)
- %f : alias de %.6

Valeur de retour :

nombre d’octets placés dans string (valeur retournée par la fonction strftime).

Exemple en C :

char time[256];
struct timeval tv;
gettimeofday (&tv, NULL);
weechat_util_strftimeval (time, sizeof (time), "%FT%T.%f", &tv);
/* résultat : 2023-12-26T18:10:04.460509 */

Cette fonction n’est pas disponible dans l’API script.

util_parse_time

WeeChat ≥ 4.2.0.

Analyser la date/heure avec le support des microsecondes.

Prototype :

int util_parse_time (const char *datetime, struct timeval *tv);

Paramètres :

date : date/heure
tv: date/heure analysée (structure "timeval")

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

struct timeval tv;
weechat_util_parse_time ("2023-12-25T10:29:09.456789Z", &tv);  /* == 1 */
/* result: tv.tv_sec == 1703500149, tv.tv_usec = 456789 */

Cette fonction n’est pas disponible dans l’API script.

util_version_number

WeeChat ≥ 0.3.9.

Convertir une chaîne avec la version WeeChat en nombre.

Prototype :

int weechat_util_version_number (const char *version);

Paramètres :

version : version WeeChat sous forme de chaîne (exemple : "0.3.9" ou "0.3.9-dev")

Exemple en C :

version_number = weechat_util_version_number ("0.3.8");      /* == 0x00030800 */
version_number = weechat_util_version_number ("0.3.9-dev");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9-rc1");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9");      /* == 0x00030900 */
version_number = weechat_util_version_number ("1.0");        /* == 0x01000000 */
version_number = weechat_util_version_number ("4.0.0");      /* == 0x04000000 */

Cette fonction n’est pas disponible dans l’API script.

3.8. Listes triées

Fonctions pour les listes triées.

list_new

Créer une nouvelle liste.

Prototype :

struct t_weelist *weechat_list_new ();

Valeur de retour :

pointeur vers la nouvelle liste

Exemple en C :

struct t_weelist *list = weechat_list_new ();

Script (Python) :

# prototype
def list_new() -> str: ...

# exemple
list = weechat.list_new()

list_add

Ajouter un élément dans une liste.

Prototype :

struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);

Paramètres :

weelist : pointeur vers la liste
data : donnée à insérer dans la liste
where : position dans la liste :
- WEECHAT_LIST_POS_SORT : ajout dans la liste, en gardant la liste triée
- WEECHAT_LIST_POS_BEGINNING : ajout en début de liste
- WEECHAT_LIST_POS_END : ajout en fin de liste
user_data : un pointeur quelconque

Valeur de retour :

pointeur vers le nouvel élément

Exemple en C :

struct t_weelist_item *my_item =
    weechat_list_add (list, "ma donnée", WEECHAT_LIST_POS_SORT, NULL);

Script (Python) :

# prototype
def list_add(list: str, data: str, where: str, user_data: str) -> str: ...

# exemple
item = weechat.list_add(list, "ma donnée", weechat.WEECHAT_LIST_POS_SORT, "")

list_search

Rechercher un élément dans une liste.

Prototype :

struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);

Paramètres :

weelist : pointeur vers la liste
data : donnée à chercher dans la liste

Valeur de retour :

pointeur vers l’élément trouvé, NULL si aucun élément n’a été trouvé

Exemple en C :

struct t_weelist_item *item = weechat_list_search (list, "ma donnée");

Script (Python) :

# prototype
def list_search(list: str, data: str) -> str: ...

# exemple
item = weechat.list_search(list, "ma donnée")

list_search_pos

WeeChat ≥ 0.3.4.

Rechercher la position d’un élément dans une liste.

Prototype :

int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);

Paramètres :

weelist : pointeur vers la liste
data : donnée à chercher dans la liste

Valeur de retour :

position de l’élément trouvé, -1 si aucun élément n’a été trouvé

Exemple en C :

int pos_item = weechat_list_search_pos (list, "ma donnée");

Script (Python) :

# prototype
def list_search_pos(list: str, data: str) -> int: ...

# exemple
pos_item = weechat.list_search_pos(list, "ma donnée")

list_casesearch

Rechercher un élément dans la liste, sans tenir compte de la casse.

Prototype :

struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);

Paramètres :

weelist : pointeur vers la liste
data : données à chercher dans la liste

Valeur de retour :

pointeur vers l’élément trouvé, NULL si aucun élément n’a été trouvé

Exemple en C :

struct t_weelist_item *item = weechat_list_casesearch (list, "ma donnée");

Script (Python) :

# prototype
def list_casesearch(list: str, data: str) -> str: ...

# exemple
item = weechat.list_casesearch(list, "ma donnée")

list_casesearch_pos

WeeChat ≥ 0.3.4.

Rechercher la position d’un élément dans la liste, sans tenir compte de la casse.

Prototype :

int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);

Paramètres :

weelist : pointeur vers la liste
data : données à chercher dans la liste

Valeur de retour :

position l’élément trouvé, -1 si aucun élément n’a été trouvé

Exemple en C :

int pos_item = weechat_list_casesearch_pos (list, "ma donnée");

Script (Python) :

# prototype
def list_casesearch_pos(list: str, data: str) -> int: ...

# exemple
pos_item = weechat.list_casesearch_pos(list, "ma donnée")

list_get

Retourner un élément de la liste par sa position.

Prototype :

struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);

Paramètres :

weelist : pointeur vers la liste
position : position dans la liste (le premier élément est 0)

Valeur de retour :

pointeur vers l’élément trouvé, NULL si aucun élément n’a été trouvé

Exemple en C :

struct t_weelist_item *item = weechat_list_get (list, 0);  /* premier élément */

Script (Python) :

# prototype
def list_get(list: str, position: int) -> str: ...

# exemple
item = weechat.list_get(list, 0)

list_set

Affecter une nouvelle valeur pour un élément.

Prototype :

void weechat_list_set (struct t_weelist_item *item, const char *value);

Paramètres :

item : pointeur vers l’élément
value : nouvelle valeur pour l’élément

Exemple en C :

weechat_list_set (item, "nouvelle donnée");

Script (Python) :

# prototype
def list_set(item: str, value: str) -> int: ...

# exemple
weechat.list_set(item, "nouvelle donnée")

list_next

Retourner l’élément suivant dans la liste.

Prototype :

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

Paramètres :

item : pointeur vers l’élément

Valeur de retour :

pointeur vers l’élément suivant, NULL si le pointeur était sur le dernier élément de la liste

Exemple en C :

struct t_weelist_item *next_item = weechat_list_next (item);

Script (Python) :

# prototype
def list_next(item: str) -> str: ...

# exemple
item = weechat.list_next(item)

list_prev

Retourner l’élément précédent dans la liste.

Prototype :

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

Paramètres :

item : pointeur vers l’élément

Valeur de retour :

pointeur vers l’élément précédent, NULL si le pointeur était sur le premier élément de la liste

Exemple en C :

struct t_weelist_item *prev_item = weechat_list_prev (item);

Script (Python) :

# prototype
def list_prev(item: str) -> str: ...

# exemple
item = weechat.list_prev(item)

list_string

Retourner la valeur de l’élément sous forme de chaîne.

Prototype :

const char *weechat_list_string (struct t_weelist_item *item);

Paramètres :

item : pointeur vers l’élément

Valeur de retour :

valeur de l’élément

Exemple en C :

weechat_printf (NULL, "valeur de l'élément : %s", weechat_list_string (item));

Script (Python) :

# prototype
def list_string(item: str) -> str: ...

# exemple
weechat.prnt("", "valeur de l'élément : %s" % weechat.list_string(item))

list_user_data

WeeChat ≥ 2.6.

Retourner le pointeur vers les données utilisateur de l’élément.

Prototype :

void *weechat_list_user_data (struct t_weelist_item *item);

Paramètres :

item : pointeur vers l’élément

Valeur de retour :

pointeur vers les données utilisateur de l’élément

Exemple en C :

weechat_printf (NULL, "données utilisateur de l'élément : 0x%lx", weechat_list_user_data (item));

Cette fonction n’est pas disponible dans l’API script.

list_size

Retourner la taille de la liste (nombre d’éléments).

Prototype :

char *weechat_list_size (struct t_weelist *weelist);

Paramètres :

weelist : pointeur vers la liste

Valeur de retour :

taille de la liste (nombre d’éléments), 0 si la liste est vide

Exemple en C :

weechat_printf (NULL, "taille de la liste : %d", weechat_list_size (list));

Script (Python) :

# prototype
def list_size(list: str) -> int: ...

# exemple
weechat.prnt("", "taille de la liste : %d" % weechat.list_size(list))

list_remove

Supprimer un élément de la liste.

Prototype :

void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);

Paramètres :

weelist : pointeur vers la liste
item : pointeur vers l’élément

Exemple en C :

weechat_list_remove (list, item);

Script (Python) :

# prototype
def list_remove(list: str, item: str) -> int: ...

# exemple
weechat.list_remove(list, item)

list_remove_all

Supprimer tous les éléments de la liste.

Prototype :

void weechat_list_remove_all (struct t_weelist *weelist);

Paramètres :

weelist : pointeur vers la liste

Exemple en C :

weechat_list_remove_all (list);

Script (Python) :

# prototype
def list_remove_all(list: str) -> int: ...

# exemple
weechat.list_remove_all(list)

list_free

Supprimer une liste.

Prototype :

void weechat_list_free (struct t_weelist *weelist);

Paramètres :

weelist : pointeur vers la liste

Exemple en C :

weechat_list_free (list);

Script (Python) :

# prototype
def list_free(list: str) -> int: ...

# exemple
weechat.list_free(list)

3.9. Listes avec tableau

Fonctions pour les listes avec tableau.

Une liste avec tableau est une liste de pointeurs avec une taille dynamique et un tri optionnel.

arraylist_new

WeeChat ≥ 1.8.

Créer une nouvelle liste avec tableau.

Prototype :

struct t_arraylist *weechat_arraylist_new (int initial_size,
                                           int sorted,
                                           int allow_duplicates,
                                           int (*callback_cmp)(void *data,
                                                               struct t_arraylist *arraylist,
                                                               void *pointer1,
                                                               void *pointer2),
                                           void *callback_cmp_data,
                                           void (*callback_free)(void *data,
                                                                 struct t_arraylist *arraylist,
                                                                 void *pointer),
                                           void *callback_free_data);

Paramètres :

initial_size : taille initiale de la liste avec tableau (ce n’est pas le nombre d’éléments)
sorted : 1 pour trier la liste avec tableau, 0 pour ne pas trier
allow_duplicates : 1 pour autoriser les entrées dupliquées, 0 pour empêcher une même entrée d’être ajoutée à nouveau
callback_cmp : fonction appelée pour comparer deux éléments (optionnelle), paramètres et valeur de retour :
- void *data : pointeur
- struct t_arraylist *arraylist : pointeur vers la liste avec tableau
- void *pointer1 : pointeur vers le premier élément
- void *pointer2 : pointeur vers le second élément
- valeur de retour :
  - nombre négatif si le premier élément est inférieur au second élément
  - 0 si le premier élément est égal au second élément
  - nombre positif si le premier élément est supérieur au second élément
callback_cmp_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_free : fonction utilisée pour libérer les éléments (optionnelle), paramètres :
- void *data : pointeur
- struct t_arraylist *arraylist : pointeur vers la liste avec tableau
- void *pointer : pointeur vers l’élément
callback_free_data : pointeur donné à la fonction de rappelle lorsqu’elle est appelée par WeeChat

Valeur de retour :

pointeur vers la nouvelle liste avec tableau

Exemple en C :

int
cmp_cb (void *data, struct t_arraylist *arraylist,
        void *pointer1, void *pointer2)
{
    if (...)
        return -1;
    else if (...)
        return 1;
    else
        return 0;
}

struct t_arraylist *list = weechat_arraylist_new (32, 1, 1,
                                                  &cmp_cb, NULL, NULL, NULL);

Cette fonction n’est pas disponible dans l’API script.

arraylist_size

WeeChat ≥ 1.8.

Retourner la taille de la liste (nombre de pointeurs vers des éléments).

Prototype :

int weechat_list_size (struct t_arraylist *arraylist);

Paramètres :

arraylist : pointeur vers la liste avec tableau

Valeur de retour :

taille de la liste avec tableau (nombre d’éléments), 0 si la liste avec tableau est vide

Exemple en C :

weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));

Cette fonction n’est pas disponible dans l’API script.

arraylist_get

WeeChat ≥ 1.8.

Retourner un pointeur avec un élément par sa position.

Prototype :

void *weechat_arraylist_get (struct t_arraylist *arraylist, int index);

Paramètres :

arraylist : pointeur vers la liste avec tableau
index : index dans la liste (le premier pointeur est 0)

Valeur de retour :

pointeur trouvé, NULL si le pointeur n’est pas trouvé

Exemple en C :

void *pointer = weechat_arraylist_get (arraylist, 0);  /* premier élément */

Cette fonction n’est pas disponible dans l’API script.

arraylist_search

WeeChat ≥ 1.8.

Chercher un élément dans une liste avec tableau.

Prototype :

void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer,
                                int *index, int *index_insert);

Paramètres :

arraylist : pointeur vers la liste avec tableau
pointer : pointeur vers l’élément à chercher dans la liste avec tableau
index : pointeur vers un entier qui sera défini avec l’index trouvé, ou -1 si non trouvé (optionnel)
index_insert : pointeur vers un entier qui sera défini avec l’index qui doit être utilisé pour insérer un élément dans la liste avec tableau (pour garder la liste avec tableau triée) (optionnel)

Valeur de retour :

pointeur vers l’élément trouvé, NULL si l’élément n’est pas trouvé

Exemple en C :

int index, index_insert;
void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);

Cette fonction n’est pas disponible dans l’API script.

arraylist_insert

WeeChat ≥ 1.8.

Insérer un élément dans une liste avec tableau.

Prototype :

int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer);

Paramètres :

arraylist : pointeur vers la liste avec tableau
index : position de l’élément dans la liste avec tableau ou -1 pour ajouter l’élément à la fin (ce paramètre est utilisé seulement si la liste avec tableau n’est pas triée, il est ignoré si la liste avec tableau est triée)
pointeur : pointeur vers l’élément à insérer

Valeur de retour :

index du nouvel élément (≥ 0), -1 si erreur.

Exemple en C :

int index = weechat_arraylist_insert (arraylist, -1, pointer);  /* insert at the end if not sorted */

Cette fonction n’est pas disponible dans l’API script.

arraylist_add

WeeChat ≥ 1.8.

Ajouter un élément dans une liste avec tableau.

Prototype :

int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer);

Paramètres :

arraylist : pointeur vers la liste avec tableau
pointer : pointeur vers l’élément à ajouter

Valeur de retour :

index du nouvel élément (≥ 0), -1 si erreur.

Exemple en C :

int index = weechat_arraylist_add (arraylist, pointer);

Cette fonction n’est pas disponible dans l’API script.

arraylist_remove

WeeChat ≥ 1.8.

Supprimer un élément d’une liste avec tableau.

Prototype :

int weechat_arraylist_remove (struct t_arraylist *arraylist, int index);

Paramètres :

arraylist : pointeur vers la liste avec tableau
index : index de l’élément à supprimer

Valeur de retour :

index de l’élément supprimé, -1 si erreur.

Exemple en C :

int index_removed = weechat_arraylist_remove (arraylist, index);

Cette fonction n’est pas disponible dans l’API script.

arraylist_clear

WeeChat ≥ 1.8.

Supprimer tous les éléments d’une liste avec tableau.

Prototype :

int weechat_arraylist_clear (struct t_arraylist *arraylist);

Paramètres :

arraylist : pointeur vers la liste avec tableau

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

if (weechat_arraylist_clear (arraylist))
{
    /* OK */
}

Cette fonction n’est pas disponible dans l’API script.

arraylist_free

WeeChat ≥ 1.8.

Supprimer une liste avec tableau.

Prototype :

void weechat_arraylist_free (struct t_arraylist *arraylist);

Paramètres :

arraylist : pointeur vers la liste avec tableau

Exemple en C :

weechat_arraylist_free (arraylist);

Cette fonction n’est pas disponible dans l’API script.

3.10. Tables de hachage

Fonctions pour les tables de hachage.

hashtable_new

WeeChat ≥ 0.3.3.

Créer une nouvelle table de hachage.

Prototype :

struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned long long (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                                   const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));

Paramètres :

size : taille du tableau interne pour stocker les clés sous forme de hachage, une grande valeur utilise plus de mémoire mais présente une meilleure performance (cela n’est pas une limite sur le nombre d’entrées de la table de hachage)
type_keys : type pour les clés dans la table de hachage :
- WEECHAT_HASHTABLE_INTEGER
- WEECHAT_HASHTABLE_STRING
- WEECHAT_HASHTABLE_POINTER
- WEECHAT_HASHTABLE_BUFFER
- WEECHAT_HASHTABLE_TIME
type_values : type pour les valeurs dans la table de hachage :
- WEECHAT_HASHTABLE_INTEGER
- WEECHAT_HASHTABLE_STRING
- WEECHAT_HASHTABLE_POINTER
- WEECHAT_HASHTABLE_BUFFER
- WEECHAT_HASHTABLE_TIME
callback_hash_key : fonction appelée pour rendre le hachage d’une clé (la clé sous forme de nombre entier), peut être NULL si le type de clé n’est pas "buffer" (une fonction de hachage par défaut est utilisée), paramètres et valeur de retour :
- struct t_hashtable *hashtable : pointeur vers la table de hachage
- const void *key : clé
- valeur de retour : hachage de la clé
callback_keycmp : fonction appelée pour comparer deux clés, peut être NULL si le type de clé n’est pas "buffer" (une fonction de comparaison par défaut est utilisée), paramètres et valeur de retour :
- struct t_hashtable *hashtable : pointeur vers la table de hachage
- const void *key1 : première clé
- const void *key2 : seconde clé
- valeur de retour :
  - nombre négatif si key1 est inférieur à key2
  - 0 si key1 est égal à key2
  - nombre positif si key1 est supérieur à key2

Valeur de retour :

pointeur vers la nouvelle table de hachage, NULL en cas d’erreur

Exemple en C :

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);

Cette fonction n’est pas disponible dans l’API script.

hashtable_set_with_size

WeeChat ≥ 0.3.3, mis à jour dans la 0.4.2.

Ajouter ou mettre à jour une entrée dans une table de hachage avec une taille pour la clé et la valeur.

Prototype :

struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                                          const void *key, int key_size,
                                                          const void *value, int value_size);

Paramètres :

hashtable : pointeur vers la table de hachage
key : pointeur vers la clé
key_size : taille de la clé (en octets), utilisée seulement si le type de clés dans la table de hachage est "buffer"
value : pointeur vers la valeur
value_size : taille de la valeur (en octets), utilisée seulement si le type de valeurs dans la table de hachage est "buffer"

Valeur de retour :

pointeur vers l’item créé/mis à jour, NULL en cas d’erreur

Exemple en C :

weechat_hashtable_set_with_size (hashtable, "ma_cle", 0,
                                 my_buffer, sizeof (my_buffer_struct));

Cette fonction n’est pas disponible dans l’API script.

hashtable_set

WeeChat ≥ 0.3.3, mis à jour dans la 0.4.2.

Ajouter ou mettre à jour une entrée dans la table de hachage.

Prototype :

struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);

Paramètres :

hashtable : pointeur vers la table de hachage
key : pointeur vers la clé
value : pointeur vers la valeur

Valeur de retour :

pointeur vers l’entrée créée/mise à jour, NULL en cas d’erreur

Exemple en C :

weechat_hashtable_set (hashtable, "ma_cle", "ma_valeur");

Cette fonction n’est pas disponible dans l’API script.

hashtable_get

WeeChat ≥ 0.3.3.

Retourner la valeur associée à une clé dans une table de hachage.

Prototype :

void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);

Paramètres :

hashtable : pointeur vers la table de hachage
key : pointeur vers la clé

Valeur de retour :

valeur pour la clé, NULL si la clé n’est pas trouvée

Exemple en C :

void *value = weechat_hashtable_get (hashtable, "ma_cle");

Cette fonction n’est pas disponible dans l’API script.

hashtable_has_key

WeeChat ≥ 0.3.4.

Vérifier si une clé est présente dans la table de hachage.

Prototype :

int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);

Paramètres :

hashtable : pointeur vers la table de hachage
key : pointeur vers la clé

Valeur de retour :

1 si la clé est dans la table de hachage, 0 si la clé n’est pas dans la table de hachage

Exemple en C :

if (weechat_hashtable_has_key (hashtable, "ma_cle"))
{
    /* la clé est dans la table de hachage */
    /* ... */
}

Cette fonction n’est pas disponible dans l’API script.

hashtable_map

WeeChat ≥ 0.3.3.

Appeller une fonction pour chaque entrée d’une table de hachage, par ordre d’insertion dans la table de hachage (de la plus ancienne à la plus récente).

Prototype :

void weechat_hashtable_map (struct t_hashtable *hashtable,
                            void (*callback_map)(void *data,
                                                 struct t_hashtable *hashtable,
                                                 const void *key,
                                                 const void *value),
                            void *callback_map_data);

Paramètres :

hashtable : pointeur vers la table de hachage
callback_map : fonction appelée pour chaque entrée de la table de hachage
callback_map_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée

Exemple en C :

void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* afficher la clé et la valeur (elles sont des chaînes ici) */
    weechat_printf (NULL, "clé : '%s', valeur : '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);

Cette fonction n’est pas disponible dans l’API script.

hashtable_map_string

WeeChat ≥ 0.3.7.

Appeller une fonction pour chaque entrée d’une table de hachage, par ordre d’insertion dans la table de hachage (de la plus ancienne à la plus récente), en envoyant les clés et valeurs sous forme de chaînes.

Prototype :

void weechat_hashtable_map_string (struct t_hashtable *hashtable,
                                   void (*callback_map)(void *data,
                                                        struct t_hashtable *hashtable,
                                                        const char *key,
                                                        const char *value),
                                   void *callback_map_data);

Paramètres :

hashtable : pointeur vers la table de hachage
callback_map : fonction appelée pour chaque entrée de la table de hachage
callback_map_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée

Les chaînes key et value envoyées à la fonction de rappel sont des chaînes temporaires, elles sont supprimées après l’appel à cette fonction.

Exemple en C :

void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* afficher la clé et la valeur */
    weechat_printf (NULL, "clé : '%s', valeur : '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);

Cette fonction n’est pas disponible dans l’API script.

hashtable_dup

WeeChat ≥ 1.0.

Dupliquer une table de hachage.

Prototype :

struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);

Paramètres :

hashtable : pointeur vers la table de hachage

Valeur de retour :

table de hachage dupliquée

Exemple en C :

struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);

Cette fonction n’est pas disponible dans l’API script.

hashtable_get_integer

WeeChat ≥ 0.3.3.

Retourner une valeur entière pour une propriété d’une table de hachage.

Prototype :

int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);

Paramètres :

hashtable : pointeur vers la table de hachage
property : nom de propriété :
- size : taille du tableau interne "htable" dans la table de hachage
- items_count : nombre d’éléments dans la table de hachage

Valeur de retour :

valeur de la propriété sous forme d’entier

Exemple en C :

int items_count = weechat_hashtable_get_integer (hashtable, "items_count");

Cette fonction n’est pas disponible dans l’API script.

hashtable_get_string

WeeChat ≥ 0.3.4.

Retourner une valeur pour une propriété d’une table de hachage sous forme de chaîne.

Prototype :

const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *property);

Paramètres :

hashtable : pointeur vers la table de hachage
property : nom de la propriété :
- type_keys : type pour les clés :
  - integer : entier
  - string : chaîne
  - pointer : pointeur
  - buffer : buffer
  - time : heure
- type_values : type pour les valeurs :
  - integer : entier
  - string : chaîne
  - pointer : pointeur
  - buffer : buffer
  - time : heure
- keys : chaîne avec la liste des clés (format : "clé1,clé2,clé3")
- keys_sorted : chaîne avec la liste triée des clés (format : "clé1,clé2,clé3")
- values : chaîne avec la liste des valeurs (format : "valeur1,valeur2,valeur3")
- keys_values : chaîne avec la liste des clés et valeurs (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")
- keys_values_sorted : chaîne avec la liste des clés et valeurs (triée sur les clés) (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")

Valeur de retour :

valeur de la propriété sous forme de chaîne

Exemples en C :

weechat_printf (NULL, "les clés sont de type : %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "liste des clés : %s",
                weechat_hashtable_get_string (hashtable, "keys"));

Cette fonction n’est pas disponible dans l’API script.

hashtable_set_pointer

WeeChat ≥ 0.3.4.

Affecter un pointeur à une propriété d’une table de hachage.

Prototype :

void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);

Paramètres :

hashtable : pointeur vers la table de hachage
property : nom de la propriété :
- callback_free_key : définit la fonction de rappel pour supprimer les clés de la table de hachage (WeeChat ≥ 0.4.2)
- callback_free_value : définit la fonction de rappel pour supprimer les valeurs de la table de hachage
pointer : nouvelle valeur de pointeur pour la propriété

Exemple en C :

void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

void
my_free_key_cb (struct t_hashtable *hashtable, void *key)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb);

Cette fonction n’est pas disponible dans l’API script.

hashtable_add_to_infolist

WeeChat ≥ 0.3.3.

Ajouter les éléments d’une table de hachage dans un objet infolist, par ordre d’insertion dans la table de hachage (de la plus ancienne à la plus récente).

Prototype :

int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);

Paramètres :

hashtable : pointeur vers la table de hachage
infolist_item : pointeur vers l’objet de l’infolist
prefix : chaîne utilisée comme préfixe pour les noms dans l’infolist

Valeur de retour :

1 si ok, 0 en cas d’erreur

Exemple en C :

weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* si la table de hachage contient :
     "cle1" => "valeur 1"
     "cle2" => "valeur 2"
   alors les variables suivantes seront ajoutées dans l'objet de l'infolist :
     "testhash_name_00000"  = "cle1"
     "testhash_value_00000" = "valeur 1"
     "testhash_name_00001"  = "cle2"
     "testhash_value_00001" = "valeur 2"
*/

Cette fonction n’est pas disponible dans l’API script.

hashtable_add_from_infolist

WeeChat ≥ 2.2.

Ajouter les éléments d’une infolist dans une table de hachage.

Prototype:

int weechat_hashtable_add_from_infolist (struct t_hashtable *hashtable,
                                         struct t_infolist *infolist,
                                         const char *prefix);

Paramètres :

hashtable : pointeur vers la table de hachage
infolist : pointeur vers l’infolist
prefix : chaîne utilisée comme préfixe pour les noms dans l’infolist

Valeur de retour :

1 si ok, 0 en cas d’erreur

Exemple en C :

weechat_hashtable_add_from_infolist (hashtable, infolist, "testhash");

/* si l'infolist contient :
     "testhash_name_00000"  = "cle1"
     "testhash_value_00000" = "valeur 1"
     "testhash_name_00001"  = "cle2"
     "testhash_value_00001" = "valeur 2"
   alors les variables suivantes seront ajoutées dans la table de hachage :
     "cle1" => "valeur 1"
     "cle2" => "valeur 2"
*/

Cette fonction n’est pas disponible dans l’API script.

hashtable_remove

WeeChat ≥ 0.3.3.

Supprimer un élément d’une table de hachage.

Prototype :

void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);

Paramètres :

hashtable : pointeur vers la table de hachage
key : pointeur vers la clé

Exemple en C :

weechat_hashtable_remove (hashtable, "ma_cle");

Cette fonction n’est pas disponible dans l’API script.

hashtable_remove_all

WeeChat ≥ 0.3.3.

Supprimer tous les éléments d’une table de hachage.

Prototype :

void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

Paramètres :

hashtable : pointeur vers la table de hachage

Exemple en C :

weechat_hashtable_remove_all (hashtable);

Cette fonction n’est pas disponible dans l’API script.

hashtable_free

WeeChat ≥ 0.3.3.

Supprimer une table de hachage.

Prototype :

void weechat_hashtable_free (struct t_hashtable *hashtable);

Paramètres :

hashtable : pointeur vers la table de hachage

Exemple en C :

weechat_hashtable_free (hashtable);

Cette fonction n’est pas disponible dans l’API script.

3.11. Fichiers de configuration

Fonctions pour les fichiers de configuration.

config_new

Mis à jour dans la 1.5, 4.0.0.

Créer un nouveau fichier de configuration.

Prototype :

struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(const void *pointer,
                                                                 void *data,
                                                                 struct t_config_file *config_file),
                                          const void *callback_reload_pointer,
                                          void *callback_reload_data);

Paramètres :

name : nom du nouveau fichier de configuration (sans chemin ou extension) ; une priorité est autorisée avant le nom, avec le format nnn|nom où nnn est un entier positif avec la priorité ; la priorité par défaut est 1000 ; les fichiers de configuration sont triés par priorité de la plus haute à la plus basse lorsque la commande /reload est exécutée (voir la priorité des fichiers de configuration ci-dessous)
callback_reload : fonction appelée quand le fichier de configuration est rechargé avec /reload (optionnel, peut être NULL, voir ci-dessous), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- valeur de retour :
  - WEECHAT_CONFIG_READ_OK
  - WEECHAT_CONFIG_READ_MEMORY_ERROR
  - WEECHAT_CONFIG_READ_FILE_NOT_FOUND
callback_reload_pointer : pointeur donné à la fonction de rappel de rechargement lorsqu’elle est appelée par WeeChat
callback_reload_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le fichier de configuration est libéré

Fonction de rechargement :

La fonction de rappel doit appeler seulement la fonction config_reload, elle ne doit pas supprimer le fichier de configuration.
Une fonction de rappel est nécessaire seulement si des choses sont faites avant ou après l’appel à la fonction config_reload.
Si aucune fonction de rappel n’est donnée, WeeChat appellera sa fonction interne de rechargement, donc le fichier de configuration sera rechargé dans tous les cas.

Valeur de retour :

pointeur vers le nouveau fichier de configuration, NULL en cas d’erreur

Le fichier n’est PAS créé sur le disque par cette fonction. Il sera créé par l’appel à la fonction config_write. Vous ne devriez appeler cette fonction qu’après avoir créé les sections (avec config_new_section) et les options (avec config_new_option).

Priorité des fichiers de configuration par défaut :

Rang	Fichier	Priorité
1	sec.conf	120000
2	weechat.conf	110000
3	plugins.conf	100000
4	charset.conf	16000
5	logger.conf	15000
6	exec.conf	14000
7	trigger.conf	13000
8	spell.conf	12000
9	alias.conf	11000
10	buflist.conf	10000
11	fifo.conf	9000
12	typing.conf	8000
13	xfer.conf	7000
14	irc.conf	6000
15	relay.conf	5000
16	guile.conf	4070
17	lua.conf	4050
18	perl.conf	4040
19	php.conf	4030
20	python.conf	4020
21	ruby.conf	4010
22	tcl.conf	4000
23	script.conf	3000
24	fset.conf	2000

Exemple en C :

int
my_config_reload_cb (const void *pointer, void *data,
                     struct t_config_file *config_file)
{
    /* ... */

    return WEECHAT_RC_OK;
}

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

Script (Python) :

# prototype
def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ...

# exemple
def my_config_reload_cb(data: str, config_file: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

config_set_version

WeeChat ≥ 4.0.0.

Définir la version du fichier de configuration et une fonction de rappel pour la mise à jour des sections/options à la volée lorsque la configuration est lue.

Prototype :

int config_file_set_version (struct t_config_file *config_file,
                             int version,
                             struct t_hashtable *(*callback_update)(const void *pointer,
                                                                    void *data,
                                                                    struct t_config_file *config_file,
                                                                    int version_read,
                                                                    struct t_hashtable *data_read),
                             const void *callback_update_pointer,
                             void *callback_update_data);

Paramètres :

config_file : pointeur vers le fichier de configuration
version : version, doit être ≥ 2
callback_update : fonction appelée lorsque le fichier de configuration est lu, pour chaque section et option, si la version lue est inférieure à la version attendue (optionnelle, peut être NULL, voir ci-dessous), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- int version_read : version lue dans le fichier de configuration (1 par défaut)
- struct t_hashtable *data_read : table de hachage avec les données lues du fichier de configuration (voir ci-dessous)
- valeur de retour :
  - soit le pointeur vers la table de hachage "data_read" (avec la table de hachage complétée), ou un pointeur vers une nouvelle table de hachage (créée par la fonction de rappel, avec clés et valeurs de type "string")
callback_update_pointer: pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_update_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le fichier de configuration est libéré

Fonction de rappel de mise à jour :

La fonction de rappel reçoit une table de hachage avec les données lues du fichier de configuration :

Clé Disponibilité Valeur

config

Toujours définie

Nom du fichier de configuration sans l’extension (par exemple : weechat)

section

Toujours définie

Nom de la section lue

option

Pour une option seulement

Nom de l’option

value

Pour une option seulement

Valeur de l’option (si non NULL)

value_null

Pour une option seulement

L’option a une valeur NULL (la valeur est toujours 1)

La fonction de rappel peut mettre à jour la "section" pour une ligne avec une section et "option", "value" et "value_null" pour une ligne avec une option.
Si "option" est changée en chaîne vide par la fonction de rappel, la ligne lue dans le fichier de configuration est ignorée.
Le champ "value_null" peut être positionné pour forcer une valeur NULL dans l’option.

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

struct t_hashtable *
my_config_update_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     int version_read,
                     struct t_hashtable *data_read)
{
    const char *ptr_section, *ptr_option;

    /* retourner maintenant si la version est déjà la dernière */
    if (version_read >= 2)
        return NULL;

    ptr_section = hashtable_get (data_read, "section");
    ptr_option = hashtable_get (data_read, "option");

    /* renommer la section "abc" en "def" */
    if (ptr_section && !ptr_option && (strcmp (ptr_section, "abc") == 0))
    {
        hashtable_set (data_read, "section", "def");
        return data_read;
    }

    /* limiter les autres changements à la section "test" */
    if (!ptr_section || !ptr_option || (strcmp (ptr_section, "test") != 0))
        return NULL;

    /* renommer l'option "test1" en "test2" */
    if (strcmp (ptr_option, "test1") == 0)
    {
        hashtable_set (data_read, "option", "test2");
        return data_read;
    }

    /* définir la valeur à "xxx" pour l'option "test" */
    if (strcmp (ptr_option, "test") == 0)
    {
        hashtable_set (data_read, "value", "xxx");
        return data_read;
    }

    /* définir la valeur à NULL pour l'option "test_null" */
    if (strcmp (ptr_option, "test_null") == 0)
    {
        hashtable_set (data_read, "value_null", "1");
        return data_read;
    }

    /* aucun changement */
    return NULL;
}

struct t_config_file *config_file = weechat_config_new ("test", NULL, NULL, NULL);
weechat_config_set_version (config_file, 2, &my_config_update_cb, NULL, NULL);
weechat_config_read (config_file);

Script (Python) :

# prototype
def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int: ...

# exemple
def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]:
    # retourner maintenant si la version est déjà la dernière
    if version_read >= 2:
        return {}

    section = data_read.get("section")
    option = data_read.get("option")

    # renommer la section "abc" en "def"
    if section and not option and section == "abc":
        data_read["section"] = "def"
        return data_read

    # limiter les autres changements à la section "test"
    if not section or not option or section != "test":
        return {}

    # renommer l'option "test1" en "test2"
    if option == "test1":
        data_read["option"] = "test2"
        return data_read

    # définir la valeur à "xxx" pour l'option "test"
    if option == "test":
        data_read["value"] = "xxx"
        return data_read

    # définir la valeur à NULL pour l'option "test_null"
    if option == "test_null":
        data_read["value_null"] = "1"
        return data_read

    # aucun changement
    return {}

config_file = weechat.config_new("test", "", "")
weechat.config_set_version(config_file, 2, "my_config_update_cb", "")
weechat.config_read(config_file)

config_new_section

Mis à jour dans la 1.5.

Créer une nouvelle section dans un fichier de configuration.

Prototype :

struct t_config_section *weechat_config_new_section (
    struct t_config_file *config_file,
    const char *name,
    int user_can_add_options,
    int user_can_delete_options,
    int (*callback_read)(const void *pointer,
                         void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    const void *callback_read_pointer,
    void *callback_read_data,
    int (*callback_write)(const void *pointer,
                          void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    const void *callback_write_pointer,
    void *callback_write_data,
    int (*callback_write_default)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name),
    const void *callback_write_default_pointer,
    void *callback_write_default_data,
    int (*callback_create_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    const void *callback_create_option_pointer,
    void *callback_create_option_data,
    int (*callback_delete_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    const void *callback_delete_option_pointer,
    void *callback_delete_option_data);

Paramètres :

config_file : pointeur vers le fichier de configuration
name : nom de la section
user_can_add_options : 1 si l’utilisateur peut créer de nouvelles options dans la section, ou 0 si c’est interdit
user_can_delete_options : 1 si l’utilisateur peut supprimer des options dans la section, ou 0 si c’est interdit
callback_read : fonction appelée quand une option de la section est lue depuis le disque (devrait être NULL dans la plupart des cas, sauf si des options de la section nécessitent une fonction personnalisée), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- struct t_config_section *section : pointeur vers la section
- const char *option_name : nom de l’option
- const char *value : valeur
- valeur de retour :
  - WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
  - WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
  - WEECHAT_CONFIG_OPTION_SET_ERROR
  - WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
callback_read_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_read_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque la section est libérée
callback_write : fonction appelée lorsque la section est écrite dans le fichier (devrait être NULL dans la plupart des cas, sauf si la section nécessite d’être écrite par une fonction personnalisée), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- const char *section_name : nom de la section
- valeur de retour :
  - WEECHAT_CONFIG_WRITE_OK
  - WEECHAT_CONFIG_WRITE_ERROR
  - WEECHAT_CONFIG_WRITE_MEMORY_ERROR
callback_write_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_write_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque la section est libérée
callback_write_default : fonction appelée lorsque les valeurs par défaut doivent être écrites dans le fichier, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- const char *section_name : nom de la section
- valeur de retour :
  - WEECHAT_CONFIG_WRITE_OK
  - WEECHAT_CONFIG_WRITE_ERROR
  - WEECHAT_CONFIG_WRITE_MEMORY_ERROR
callback_write_default_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelé par WeeChat
callback_write_default_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque la section est libérée
callback_create_option : fonction appelée lorsqu’une nouvelle option est créée dans la section (NULL si la section n’autorise pas la création de nouvelles options), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- struct t_config_section *section : pointeur vers la section
- const char *option_name : nom de l’option
- const char *value : valeur
callback_create_option_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_create_option_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque la section est libérée
callback_delete_option : fonction appelée lorsqu’une option est supprimée de la section (NULL si la section n’autorise pas la suppression d’options), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_file *config_file : pointeur vers le fichier de configuration
- struct t_config_section *section : pointeur vers la section
- struct t_config_option *option : pointeur vers l’option
- valeur de retour :
  - WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
  - WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
  - WEECHAT_CONFIG_OPTION_SET_ERROR
  - WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
callback_delete_option_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_delete_option_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque la section est libérée

Valeur de retour :

pointeur vers la nouvelle section du fichier de configuration, NULL en cas d’erreur

Exemple en C :

int
my_section_read_cb (const void *pointer, void *data,
                    struct t_config_file *config_file,
                    struct t_config_section *section,
                    const char *option_name,
                    const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_write_default_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_create_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name,
                             const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_delete_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* section standard, l'utilisateur ne peut pas ajouter/supprimer des options */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL);

/* section spéciale, l'utilisateur peut ajouter/supprimer des options, et les
   options nécessitent une fonction de rappel pour la lecture/écriture */
struct t_config_section *new_section2 =
    weechat_config_new_section (config_file, "section2", 1, 1,
                                &my_section_read_cb, NULL, NULL,
                                &my_section_write_cb, NULL, NULL,
                                &my_section_write_default_cb, NULL, NULL,
                                &my_section_create_option_cb, NULL, NULL,
                                &my_section_delete_option_cb, NULL, NULL);

Script (Python) :

# prototype
def config_new_section(config_file: str, name: str,
                       user_can_add_options: int, user_can_delete_options: int,
                       callback_read: str, callback_read_data: str,
                       callback_write: str, callback_write_data: str,
                       callback_write_default: str, callback_write_default_data: str,
                       callback_create_option: str, callback_create_option_data: str,
                       callback_delete_option: str, callback_delete_option_data: str) -> str: ...

# exemple
def my_section_read_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_write_default_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_create_option_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_delete_option_cb(data: str, config_file: str, section: str, option: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR

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

config_search_section

Rechercher une section dans un fichier de configuration.

Prototype :

struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);

Paramètres :

config_file : pointeur vers le fichier de configuration
section_name : nom de la section à chercher

Valeur de retour :

pointeur vers la section trouvée, ou NULL si la section n’a pas été trouvée

Exemple en C :

struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");

Script (Python) :

# prototype
def config_search_section(config_file: str, section_name: str) -> str: ...

# exemple
section = weechat.config_search_section(config_file, "section")

config_new_option

Mis à jour dans la 1.5, 4.1.0.

Créer une nouvelle option dans une section d’un fichier de configuration.

Prototype :

struct t_config_option *weechat_config_new_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *name,
    const char *type,
    const char *description,
    const char *string_values,
    int min,
    int max,
    const char *default_value,
    const char *value,
    int null_value_allowed,
    int (*callback_check_value)(const void *pointer,
                                void *data,
                                struct t_config_option *option,
                                const char *value),
    const void *callback_check_value_pointer,
    void *callback_check_value_data,
    void (*callback_change)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_change_pointer,
    void *callback_change_data,
    void (*callback_delete)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_delete_pointer,
    void *callback_delete_data);

Paramètres :

config_file : pointeur vers le fichier de configuration
section : pointeur vers la section
name : nom de l’option ; avec WeeChat ≥ 1.4, le nom peut inclure le nom d’une option parente (la valeur de l’option parente sera affichée dans la sortie de /set si cette option est "null"), la syntaxe est alors : "name << file.section.option"
type : type de l’option :
- boolean : valeur booléenne (on/off)
- integer : valeur entière
- string : une chaîne de caractères
- color : une couleur
- enum : liste de valeurs sous forme de chaînes (stocké comme nombre entier en interne)
description : description de l’option
string_values : valeurs sous forme de chaîne (séparées par |) (optionnel, requis pour le type enum)
min : valeur minimum (pour le type integer)
max : valeur maximum (pour le type integer)
default_value : valeur par défaut de l’option (utilisée quand l’option est réinitialisée)
value : valeur de l’option
null_value_allowed : 1 si null (valeur non définie) est autorisé pour l’option, sinon 0
callback_check_value : fonction appelée pour vérifier la nouvelle valeur de l’option (optionnel), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_option *option : pointeur vers l’option
- const char *value : nouvelle valeur pour l’option
- valeur de retour :
  - 1 si la valeur est ok
  - 0 si la valeur est invalide
callback_check_value_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_check_value_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque l’option est libérée
callback_change : fonction appelée lorsque la valeur de l’option a changé (optionnel), paramètres :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_option *option : pointeur vers l’option
callback_change_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_change_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque l’option est libérée
callback_delete : fonction appelée lorsque l’option est supprimée (optionnel), paramètres :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_config_option *option : pointeur vers l’option
callback_delete_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_delete_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque l’option est libérée

Valeur de retour :

pointeur vers la nouvelle option de la section, NULL en cas d’erreur

Exemple en C :

/* booléen */
struct t_config_option *option1_bool =
    weechat_config_new_option (config_file, section, "option_bool", "boolean",
                               "Mon option, type booléen",
                               NULL,
                               0, 0,
                               "on",
                               "on",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* entier */
struct t_config_option *option_int =
    weechat_config_new_option (config_file, section, "option_int", "integer",
                               "Mon option, type entier",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* chaîne */
struct t_config_option *option_str =
    weechat_config_new_option (config_file, section, "option_str", "string",
                               "Mon option, type chaîne",
                               NULL,
                               0, 0,
                               "test",
                               "test",
                               1,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* couleur */
struct t_config_option *option_col =
    weechat_config_new_option (config_file, section, "option_col", "color",
                               "Mon option, type couleur",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* énuméré */
struct t_config_option *option_enum =
    weechat_config_new_option (config_file, section, "option_enum", "enum",
                               "Mon option, type énuméré",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

Script (Python) :

# prototype
def config_new_option(config_file: str, section: str, name: str, type: str, description: str,
                      string_values: str, min: int, max: int,
                      default_value: Union[str, None], value: Union[str, None], null_value_allowed: int,
                      callback_check_value: str, callback_check_value_data: str,
                      callback_change: str, callback_change_data: str,
                      callback_delete: str, callback_delete_data: str) -> str: ...

# exemple
def option_str_check_value_cb(data: str, option: str, value: str) -> int:
    # ...
    return 1
    # return 0

def option_str_change_cb(data: str, option: str) -> None:
    # ...

def option_str_delete_cb(data: str, option: str) -> None:
    # ...

option_bool = weechat.config_new_option(config_file, section, "option_bool", "boolean",
    "Mon option, type booléen",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option_int = weechat.config_new_option(config_file, section, "option_int", "integer",
    "Mon option, type entier",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option_str = weechat.config_new_option(config_file, section, "option_str", "string",
    "Mon option, type chaîne",
    "", 0, 0, "test", "test", 1,
    "option_str_check_value_cb", "",
    "option_str_change_cb", "",
    "option_str_delete_cb", "")

option_col = weechat.config_new_option(config_file, section, "option_col", "color",
    "Mon option, type couleur",
    "", 0, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")

option_enum = weechat.config_new_option(config_file, section, "option_enum", "enum",
    "Mon option, type énuméré",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

En Ruby, les 3 fonctions de rappel + "data" (6 chaînes) doivent être données dans un tableau de 6 chaînes de caractères (en raison d’une limitation de Ruby à 15 paramètres par fonction), voir le Guide pour scripts WeeChat ^↗ pour plus d’infos (corrigé dans la version 0.4.1).

config_search_option

Rechercher une option dans une section d’un fichier de configuration.

Prototype :

struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);

Paramètres :

config_file : pointeur vers le fichier de configuration
section : pointeur vers la section
name : nom de l’option à rechercher

Valeur de retour :

pointeur vers l’option trouvée, NULL si l’option n’a pas été trouvée

Exemple en C :

struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");

Script (Python) :

# prototype
def config_search_option(config_file: str, section: str, option_name: str) -> str: ...

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

config_search_section_option

Rechercher une section et une option dans un fichier de configuration ou une section.

Prototype :

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);

Paramètres :

config_file : pointeur vers le fichier de configuration
section : pointeur vers la section
option_name : nom de l’option
section : pointeur vers un pointeur sur une section, sera alimenté avec le pointeur vers la section de l’option trouvée
option : pointeur vers un pointeur sur une option, sera alimenté avec le pointeur vers l’option trouvée

Exemple en 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 trouvée */
}
else
{
    /* option non trouvée */
}

Cette fonction n’est pas disponible dans l’API script.

config_search_with_string

Retourner des infos sur fichier/section/option pour une option avec le nom complet.

Prototype :

void weechat_config_search_with_string (const char *option_name,
                                        struct t_config_file **config_file,
                                        struct t_config_section **section,
                                        struct t_config_option **option,
                                        char **pos_option_name);

Paramètres :

option_name : nom complet de l’option (format : "fichier.section.option")
config_file : pointeur vers un pointeur sur un fichier de configuration, sera alimenté avec le pointeur vers le fichier de configuration de l’option trouvée
section : pointeur vers un pointeur sur une section, sera alimenté avec le pointeur vers la section de l’option trouvée
option : pointeur vers un pointeur sur une option, sera alimenté avec le pointeur vers l’option trouvée
pos_option_name : pointeur vers un pointeur sur une chaîne, sera alimenté avec le pointeur vers le nom de l’option trouvée

Exemple en C :

struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;
char *option_name;

weechat_config_search_with_string ("fichier.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option,
                                   &option_name);
if (ptr_option)
{
    /* option trouvée */
}
else
{
    /* option non trouvée */
}

Cette fonction n’est pas disponible dans l’API script.

config_string_to_boolean

Vérifier si un texte est "vrai" ou "faux", au sens booléen.

Prototype :

int weechat_config_string_to_boolean (const char *text);

Paramètres :

text : texte à analyser

Valeur de retour :

1 si le texte est "vrai" ("on", "yes", "y", "true", "t", "1")
0 si le texte est "faux" ("off", "no", "n", "false", "f", "0")

Exemple en C :

if (weechat_config_string_to_boolean (option_value))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}

Script (Python) :

# prototype
def config_string_to_boolean(text: str) -> int: ...

# exemple
if weechat.config_string_to_boolean(text):
    # ...

config_option_reset

Réinitialiser une option à sa valeur par défaut.

Prototype :

int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);

Paramètres :

option : pointeur vers l’option
run_callback : 1 pour appeler la fonction de rappel si la valeur de l’option est changée, sinon 0

Valeur de retour :

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED si la valeur de l’option a été réinitialisée
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE si la valeur n’a pas changé
WEECHAT_CONFIG_OPTION_SET_ERROR en cas d’erreur

Exemple en 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) :

# prototype
def config_option_reset(option: str, run_callback: int) -> int: ...

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

config_option_set

Affecter une nouvelle valeur pour une option.

Prototype :

int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);

Paramètres :

option : pointeur vers l’option
value : nouvelle valeur pour l’option, des valeurs spéciales sont possibles selon le type de l’option :
- boolean :
  - toggle : basculer la valeur courante
- integer, color ou enum :
  - ++N : ajouter N (un entier) à la valeur courante
  - --N : soustraire N (un entier) de la valeur courante
run_callback : 1 pour appeler la fonction de rappel si la valeur de l’option est changée, sinon 0

Valeur de retour :

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED si la valeur de l’option a été changée
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE si la valeur n’a pas changé
WEECHAT_CONFIG_OPTION_SET_ERROR en cas d’erreur

Exemple en C :

switch (weechat_config_option_set (option, "nouvelle_valeur", 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}

Script (Python) :

# prototype
def config_option_set(option: str, value: str, run_callback: int) -> int: ...

# exemple
rc = weechat.config_option_set(option, "nouvelle_valeur", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

config_option_set_null

Affecter "null" (valeur indéfinie) à une option.

Prototype :

int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);

Paramètres :

option : pointeur vers l’option
run_callback : 1 pour appeler la fonction de rappel si la valeur de l’option est changée (elle n’était pas "null"), sinon 0

Vous pouvez affecter "null" à une option seulement si c’est autorisé pour l’option (voir config_new_option).

Valeur de retour :

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED si la valeur de l’option a été changée
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE si la valeur n’a pas changé
WEECHAT_CONFIG_OPTION_SET_ERROR en cas d’erreur

Exemple en 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) :

# prototype
def config_option_set_null(option: str, run_callback: int) -> int: ...

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

config_option_unset

Réinitialiser ou supprimer une option.

Prototype :

int weechat_config_option_unset (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour :

WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET si la valeur de l’option n’a pas été réinitialisée
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET si la valeur de l’option a été réinitialisée
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED si l’option a été supprimée
WEECHAT_CONFIG_OPTION_UNSET_ERROR en cas d’erreur

Exemple en 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) :

# prototype
def config_option_unset(option: str) -> int: ...

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

config_option_rename

Renommer une option.

Prototype :

void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);

Paramètres :

option : pointeur vers l’option
new_name : nouveau nom pour l’option

Exemple en C :

weechat_config_option_rename (option, "nouveau_nom");

Script (Python) :

# prototype
def config_option_rename(option: str, new_name: str) -> int: ...

# exemple
weechat.config_option_rename(option, "nouveau_nom")

config_option_get_string

WeeChat ≥ 1.9.

Retourner la valeur d’une propriété de l’option sous forme de chaîne.

Prototype :

const char *weechat_config_option_get_string (struct t_config_option *option,
                                              const char *property);

Paramètres :

option : pointeur vers l’option
property : nom de la propriété :
- config_name : nom du fichier
- section_name : nom de la section
- name : nom de l’option
- parent_name : nom de l’option parente
- type : type de l’option, un parmi ceux-ci :
  - boolean
  - integer
  - string
  - color
  - enum
- description : description de l’option

Valeur de retour :

valeur de la propriété, sous forme de chaîne

Exemple en C :

const char *type = weechat_config_option_get_string (option, "type");

Cette fonction n’est pas disponible dans l’API script.

config_option_get_pointer

Retourner un pointeur vers une propriété de l’option.

Prototype :

void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);

Paramètres :

option : pointeur vers l’option
property : nom de la propriété :
- config_file : pointeur vers le fichier de configuration (struct t_config_file *)
- section : pointeur vers la section (struct t_config_section *)
- name : nom de l’option (char *)
- parent_name : nom de l’option parente (char *) (WeeChat ≥ 1.4)
- type : type de l’option (int *)
- description : description de l’option (char *)
- string_values : valeurs sous forme de chaîne (char *)
- min : valeur minimum (int *)
- max : valeur maximum (int *)
- default_value : valeur par défaut (dépend du type)
- value : valeur courante (dépend du type)
- prev_option : pointeur vers l’option précédente (struct t_config_option *)
- next_option : pointeur vers l’option suivante (struct t_config_option *)

Valeur de retour :

pointeur vers la propriété demandée

Exemple en C :

char *description = weechat_config_option_get_pointer (option, "description");

Cette fonction n’est pas disponible dans l’API script.

config_option_is_null

Vérifier si une option est "null" (valeur non définie).

Prototype :

int weechat_config_option_is_null (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour :

1 si la valeur de l’option est "null"
0 si la valeur de l’option n’est pas "null"

Exemple en C :

if (weechat_config_option_is_null (option))
{
    /* la valeur est "null" */
}
else
{
    /* la valeur n'est pas "null" */
}

Script (Python) :

# prototype
def config_option_is_null(option: str) -> int: ...

# exemple
if weechat.config_option_is_null(option):
    # ...

config_option_default_is_null

Vérifier si la valeur par défaut d’une option est "null" (valeur non définie).

Prototype :

int weechat_config_option_default_is_null (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour :

1 si la valeur par défaut de l’option est "null"
0 si la valeur par défaut de l’option n’est pas "null"

Exemple en C :

if (weechat_config_option_default_is_null (option))
{
    /* la valeur par défaut est "null" */
}
else
{
    /* la valeur par défaut n'est pas "null" */
}

Script (Python) :

# prototype
def config_option_default_is_null(option: str) -> int: ...

# exemple
if weechat.config_option_default_is_null(option):
    # ...

config_boolean

Retourner la valeur booléenne de l’option.

Prototype :

int weechat_config_boolean (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne de l’option (0 ou 1)
integer : 0
string : 0
color : 0
enum : 0

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}

Script (Python) :

# prototype
def config_boolean(option: str) -> int: ...

# exemple
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...

config_boolean_default

Retourner la valeur booléenne par défaut de l’option.

Prototype :

int weechat_config_boolean_default (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne par défaut de l’option (0 ou 1)
integer : 0
string : 0
color : 0
enum : 0

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}

Script (Python) :

# prototype
def config_boolean_default(option: str) -> int: ...

# exemple
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...

config_integer

Retourner la valeur entière de l’option.

Prototype :

int weechat_config_integer (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne de l’option (0 ou 1)
integer : valeur entière de l’option
string : 0
color : index de la couleur
enum : valeur entière de l’option (index de la valeur de l’énuméré)

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);

Script (Python) :

# prototype
def config_integer(option: str) -> int: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)

config_integer_default

Retourner la valeur entière par défaut de l’option.

Prototype :

int weechat_config_integer_default (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne par défaut de l’option (0 ou 1)
integer : valeur entière par défaut de l’option
string : 0
color : index de la couleur par défaut
enum : valeur entière par défaut de l’option (index de la valeur de l’énuméré)

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);

Script (Python) :

# prototype
def config_integer_default(option: str) -> int: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)

config_string

Retourner la valeur de l’option, sous forme de chaîne.

Prototype :

const char *weechat_config_string (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : "on" si la valeur est vraie, sinon "off"
integer : NULL
string : valeur de l’option sous forme de chaîne
color : nom de la couleur
enum : valeur de l’option sous forme de chaîne

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);

Script (Python) :

# prototype
def config_string(option: str) -> str: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)

config_string_default

Retourner la valeur par défaut de l’option, sous forme de chaîne.

Prototype :

const char *weechat_config_string_default (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : "on" si la valeur par défaut est vraie, sinon "off"
integer : NULL
string : valeur par défaut de l’option sous forme de chaîne
color : nom de la couleur par défaut
enum : valeur par défaut de l’option sous forme de chaîne

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);

Script (Python) :

# prototype
def config_string_default(option: str) -> str: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)

config_color

Retourner la valeur de l’option, sous forme de couleur.

Prototype :

const char *weechat_config_color (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : NULL
integer : NULL
string : NULL
color : nom de la couleur
enum : NULL

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);

Script (Python) :

# prototype
def config_color(option: str) -> str: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_color(option)

config_color_default

Retourner la valeur par défaut de l’option, sous forme de couleur.

Prototype :

const char *weechat_config_color_default (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : NULL
integer : NULL
string : NULL
color : nom de la couleur par défaut
enum : NULL

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);

Script (Python) :

# prototype
def config_color_default(option: str) -> str: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_color_default(option)

config_enum

WeeChat ≥ 4.1.0.

Retourner la valeur de l’option, sous forme d’entier.

Prototype :

int weechat_config_enum (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne de l’option (0 ou 1)
integer : valeur entière de l’option
string : 0
color : index de la couleur
enum : valeur entière de l’option (index de la valeur de l’énuméré)

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_enum (option);

Script (Python) :

# prototype
def config_enum(option: str) -> int: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_enum(option)

config_enum_default

WeeChat ≥ 4.1.0.

Retourner la valeur par défaut de l’option, sous forme d’entier.

Prototype :

int weechat_config_enum_default (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Valeur de retour, selon le type de l’option :

boolean : valeur booléenne par défaut de l’option (0 ou 1)
integer : valeur entière par défaut de l’option
string : 0
color : index de la couleur par défaut
enum : valeur entière par défaut de l’option (index de la valeur de l’énuméré)

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_enum_default (option);

Script (Python) :

# prototype
def config_enum_default(option: str) -> int: ...

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_enum_default(option)

config_write_option

Écrire une ligne dans le fichier de configuration avec l’option et sa valeur (cette fonction doit être appelée uniquement dans une fonction de rappel "write" ou "write_default" pour une section).

Prototype :

void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);

Paramètres :

config_file : pointeur vers le fichier de configuration
option : pointeur vers l’option

Exemple en C :

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "ma_section", NULL);

    weechat_config_write_option (config_file, option);

    return WEECHAT_RC_OK;
}

Script (Python) :

# prototype
def config_write_option(config_file: str, option: str) -> int: ...

# exemple
def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
    weechat.config_write_line(config_file, "ma_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK

config_write_line

Écrire une ligne dans un fichier de configuration (cette fonction doit être appelée uniquement dans une fonction de rappel "write" ou "write_default" pour une section).

Prototype :

void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);

Paramètres :

config_file : pointeur vers le fichier de configuration
option_name : nom de l’option
value : valeur (si NULL, alors la ligne est écrite avec le nom de la section, par exemple : "[section]")

Exemple en C :

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "ma_section", NULL);

    weechat_config_write_line (config_file, "option", "%s;%d",
                               "valeur", 123);

    return WEECHAT_RC_OK;
}

Script (Python) :

# prototype
def config_write_line(config_file: str, option_name: str, value: str) -> int: ...

# exemple
def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
    weechat.config_write_line(config_file, "ma_section", "")
    weechat.config_write_line(config_file, "option", "valeur")
    return weechat.WEECHAT_RC_OK

config_write

Écrire un fichier de configuration sur le disque.

Prototype :

int weechat_config_write (struct t_config_file *config_file);

Paramètres :

config_file : pointeur vers le fichier de configuration.

Valeur de retour :

WEECHAT_CONFIG_WRITE_OK si la configuration a été écrite
WEECHAT_CONFIG_WRITE_MEMORY_ERROR s’il n’y a pas eu suffisamment de mémoire
WEECHAT_CONFIG_WRITE_ERROR si une autre erreur s’est produite

Exemple en 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) :

# prototype
def config_write(config_file: str) -> int: ...

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

config_read

Lire un fichier de configuration depuis le disque.

Prototype :

int weechat_config_read (struct t_config_file *config_file);

Paramètres :

config_file : pointeur vers le fichier de configuration

Valeur de retour :

WEECHAT_CONFIG_READ_OK si la configuration a été chargée
WEECHAT_CONFIG_READ_MEMORY_ERROR s’il n’y a pas eu suffisamment de mémoire
WEECHAT_CONFIG_READ_FILE_NOT_FOUND si le fichier n’a pas été trouvé

Exemple en 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) :

# prototype
def config_read(config_file: str) -> int: ...

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

config_reload

Relire un fichier de configuration depuis le disque.

Prototype :

int weechat_config_reload (struct t_config_file *config_file);

Paramètres :

config_file : pointeur vers le fichier de configuration

Valeur de retour :

WEECHAT_CONFIG_READ_OK si la configuration a été rechargée
WEECHAT_CONFIG_READ_MEMORY_ERROR s’il n’y a pas eu suffisamment de mémoire
WEECHAT_CONFIG_READ_FILE_NOT_FOUND si le fichier n’a pas été trouvé

Exemple en 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) :

# prototype
def config_reload(config_file: str) -> int: ...

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

config_option_free

Supprimer une option.

Prototype :

void weechat_config_option_free (struct t_config_option *option);

Paramètres :

option : pointeur vers l’option

Exemple en C :

weechat_config_option_free (option);

Script (Python) :

# prototype
def config_option_free(option: str) -> int: ...

# exemple
weechat.config_option_free(option)

config_section_free_options

Supprimer toutes les options dans une section.

Prototype :

void weechat_config_section_free_options (struct t_config_section *section);

Paramètres :

section : pointeur vers la section

Exemple en C :

weechat_config_section_free_options (section);

Script (Python) :

# prototype
def config_section_free_options(section: str) -> int: ...

# exemple
weechat.config_section_free_options(section)

config_section_free

Supprimer une section.

Prototype :

void weechat_config_section_free (struct t_config_section *section);

Paramètres :

section : pointeur vers la section

Exemple en C :

weechat_config_section_free (section);

Script (Python) :

# prototype
def config_section_free(section: str) -> int: ...

# exemple
weechat.config_section_free(section)

config_free

Supprimer un fichier de configuration.

Prototype :

void weechat_config_free (struct t_config_file *config_file);

Paramètres :

config_file : pointeur vers le fichier de configuration

Exemple en C :

weechat_config_free (config_file);

Script (Python) :

# prototype
def config_free(config_file: str) -> int: ...

# exemple
weechat.config_free(config_file)

config_get

Rechercher une option avec le nom complet.

Prototype :

struct t_config_option *weechat_config_get (const char *option_name);

Paramètres :

option_name : nom complet de l’option (format : "fichier.section.option")

Valeur de retour :

pointeur vers l’option trouvée, NULL si l’option n’a pas été trouvée

Exemple en C :

struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

Script (Python) :

# prototype
def config_get(option_name: str) -> str: ...

# exemple
option = weechat.config_get("weechat.look.item_time_format")

config_get_plugin

Rechercher une option dans le fichier de configuration des extensions (plugins.conf).

Prototype :

const char *weechat_config_get_plugin (const char *option_name);

Paramètres :

option_name : nom de l’option, WeeChat ajoutera le préfixe "plugins.var.xxx." (où "xxx" est le nom de l’extension courante)

Valeur de retour :

valeur de l’option trouvée, NULL si l’option n’a pas été trouvée

Exemple en C :

/* si l'extension courante est "test", alors on cherche la valeur de l'option
   "plugins.var.test.option" dans le fichier plugins.conf */
char *value = weechat_config_get_plugin ("option");

Script (Python) :

# prototype
def config_get_plugin(option_name: str) -> str: ...

# exemple
value = weechat.config_get_plugin("option")

config_is_set_plugin

Vérifier si une option existe dans le fichier de configuration des extensions (plugins.conf).

Prototype :

int weechat_config_is_set_plugin (const char *option_name);

Paramètres :

option_name : nom de l’option, WeeChat ajoutera le préfixe "plugins.var.xxx." (où "xxx" est le nom de l’extension courante)

Valeur de retour :

1 si l’option est définie, 0 si l’option n’existe pas

Exemple en C :

if (weechat_config_is_set_plugin ("option"))
{
    /* l'option existe */
}
else
{
    /* l'option n'existe pas */
}

Script (Python) :

# prototype
def config_is_set_plugin(option_name: str) -> int: ...

# exemple
if weechat.config_is_set_plugin("option"):
    # l'option existe
    # ...
else:
    # l'option n'existe pas
    # ...

config_set_plugin

Affecter une nouvelle valeur pour une option dans le fichier de configuration des extensions (plugins.conf).

Prototype :

int weechat_config_set_plugin (const char *option_name, const char *value);

Paramètres :

option_name : nom de l’option, WeeChat ajoutera le préfixe "plugins.var.xxx." (où "xxx" est le nom de l’extension courante)
value : nouvelle valeur pour l’option

Valeur de retour :

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED si la valeur de l’option a été changée
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE si la valeur n’a pas changé
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND si l’option n’a pas été trouvée
WEECHAT_CONFIG_OPTION_SET_ERROR en cas d’erreur

Exemple en C :

switch (weechat_config_set_plugin ("option", "valeur_test"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}

Script (Python) :

# prototype
def config_set_plugin(option_name: str, value: str) -> int: ...

# exemple
rc = weechat.config_set_plugin("option", "valeur_test")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

config_set_desc_plugin

WeeChat ≥ 0.3.5.

Affecter une description pour une option dans le fichier de configuration des extensions (plugins.conf).

Prototype :

void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);

Paramètres :

option_name : nom de l’option, WeeChat ajoutera le préfixe "plugins.desc.xxx." (où "xxx" est le nom de l’extension courante)
description : description pour l’option

Ce n’est pas un problème si l’option (plugins.var.xxx.option_name) n’existe pas. Une création future de cette option utilisera cette description.

Exemple en C :

weechat_config_set_desc_plugin ("option", "description de l'option");

Script (Python) :

# prototype
def config_set_desc_plugin(option_name: str, description: str) -> int: ...

# exemple
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description de l'option")

config_unset_plugin

Supprimer une option du fichier de configuration des extensions (plugins.conf).

Prototype :

int weechat_config_unset_plugin (const char *option_name);

Paramètres :

option_name : nom de l’option, WeeChat ajoutera le préfixe "plugins.var.xxx." (où "xxx" est le nom de l’extension courante)

Valeur de retour :

WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET si la valeur de l’option n’a pas été réinitialisée
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET si la valeur de l’option a été réinitialisée
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED si l’option a été supprimée
WEECHAT_CONFIG_OPTION_UNSET_ERROR en cas d’erreur

Exemple en 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) :

# prototype
def config_unset_plugin(option_name: str) -> int: ...

# exemple
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:
    # ...

3.12. Associations de touches

Fonctions pour les associations de touches.

key_bind

WeeChat ≥ 0.3.6, mis à jour dans la 1.8.

Ajouter de nouvelles associations de touches.

Contrairement à la commande /key bind, cette fonction ne changera jamais une association de touche existante, seulement des nouvelles touches seront créées. Pour supprimer une association de touche, utilisez key_unbind.

Prototype :

int weechat_key_bind (const char *context, struct t_hashtable *keys);

Paramètres :

context : contexte pour les touches :
- default : contexte par défaut (actions courantes)
- search : contexte de recherche (lors de la recherche de texte dans le tampon)
- cursor : mouvement libre du curseur à l’écran
- mouse : touches pour les évènements de souris
keys : table de hachage avec les associations de touches ; elle peut contenir les clés spéciales suivantes :
- __quiet: ne pas afficher les touches ajoutées dans le tampon core (WeeChat ≥ 1.8)

Valeur de retour :

nombre d’associations de touches ajoutées

Exemple en C :

struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}

Script (Python) :

# prototype
def key_bind(context: str, keys: Dict[str, str]) -> int: ...

# exemple
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)

key_unbind

WeeChat ≥ 0.3.6, mis à jour dans la 2.0.

Supprimer une/des association(s) de touche(s).

Lors de l’appel à cette fonction, assurez-vous que vous n’allez pas supprimer une touche définie par l’utilisateur.

Prototype :

int weechat_key_unbind (const char *context, const char *key);

Paramètres :

context : contexte pour les touches (voir key_bind)
key : touche à supprimer ou la valeur spéciale "area:XXX" pour supprimer toutes les touches ayant XXX comme première ou deuxième zone; si la touche commence par "quiet:", les touches supprimées ne sont pas affichées dans le tampon core (WeeChat ≥ 2.0).

Valeur de retour :

nombre d’associations de touches supprimées

Exemples en C :

/* supprimer une seule touche */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* supprimer toutes les touches avec la zone "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");

Script (Python) :

# prototype
def key_unbind(context: str, key: str) -> int: ...

# exemples

# supprimer une seule touche
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# supprimer toutes les touches avec la zone "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")

3.13. Affichage

Fonctions pour afficher du texte dans les tampons.

prefix

Retourner un préfixe.

Prototype :

const char *weechat_prefix (const char *prefix);

Paramètres :

prefix : nom du préfixe (voir le tableau ci-dessous)

Valeur de retour :

valeur du préfixe (chaîne avec le préfixe et des codes couleur), chaîne vide si le préfixe n’a pas été trouvé

Liste des préfixes :

Préfixe Valeur Couleur Description

error

=!=

jaune ("yellow")

Message d’erreur.

network

--

violet ("magenta")

Message du réseau.

action

*

blanc ("white")

Action personnelle.

join

-->

vert clair ("lightgreen")

Quelqu’un a rejoint la discussion.

quit

<--

rouge clair ("lightred")

Quelqu’un a quitté la discussion.

Les valeurs et couleurs peuvent être configurées avec la commande /set.

Exemple en C :

weechat_printf (NULL, "%sCeci est une erreur...", weechat_prefix ("error"));

Script (Python) :

# prototype
def prefix(prefix: str) -> str: ...

# exemple
weechat.prnt("", "%sCeci est une erreur..." % weechat.prefix("error"))

color

Retourner une chaîne avec un code couleur pour affichage.

Prototype :

const char *weechat_color (const char *color_name);

Paramètres :

color_name : nom de la couleur, parmi :
- le nom d’une option de couleur WeeChat (de weechat.color.xxx), par exemple chat_delimiters
- le nom d’une option (format : fichier.section.option), par exemple irc.color.message_quit (WeeChat ≥ 1.2)
- une couleur avec des attributs/fond optionnels (voir ci-dessous)
- un attribut :
  - blink : activer le clignotement
  - -blink : désactiver le clignotement
  - dim : activer le "dim" (demi-intensité)
  - -dim : désactiver le "dim" (demi-intensité)
  - bold : activer le gras
  - -bold : désactiver le gras
  - reverse : activer la vidéo inverse
  - -reverse : désactiver la vidéo inverse
  - italic : activer l’italique
  - -italic : désactiver l’italique
  - underline : activer le souligné
  - -underline : désactiver le souligné
  - emphasis : activer/désactiver la mise en valeur du texte (note : cela ne devrait être utilisé que dans les barres, car WeeChat utilise la mise en valeur du texte lors de la recherche de texte dans le tampon) (WeeChat ≥ 0.4.2)
- nom d’une couleur de barre :
  - bar_fg : couleur de texte pour la barre
  - bar_delim : couleur des délimiteurs pour la barre
  - bar_bg : couleur de fond pour la barre
- réinitialisation :
  - reset : réinitialiser la couleur et les attributs
  - resetcolor : réinitialiser la couleur (garder les attributs) (WeeChat ≥ 0.3.6)

Le format de la couleur est : attributs (optionnel) + nom de couleur + ",fond" (optionnel). Les attributs possibles sont :

% : clignotement
. : "dim" (demi-intensité)
* : texte gras
! : mode vidéo inverse
/ : italique
_ : texte souligné
| : garder les attributs : ne pas réinitialiser gras/inverse/italique/souligné lors du changement de couleur (WeeChat ≥ 0.3.6)

Exemples :

yellow : jaune
_green : vert souligné
*214 : orange gras
yellow,red : jaune sur rouge
|cyan : cyan (et garder tout attribut définit précédemment)

Valeur de retour :

chaîne avec le code couleur, ou une chaîne vide si la couleur n’a pas été trouvée

Exemple en C :

weechat_printf (NULL, "Couleur : %sbleu %scouleur par défaut %sjaune sur rouge",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));

Script (Python) :

# prototype
def color(color_name: str) -> str: ...

# exemple
weechat.prnt("", "Couleur : %sbleu %scouleur par défaut %sjaune sur rouge"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

printf

Afficher un message sur un tampon.

Prototype :

void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

Cette fonction est un raccourci vers la fonction printf_datetime_tags.
Ces deux appels donnent exactement le même résultat :

weechat_printf (buffer, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

Paramètres :

buffer : pointeur vers le tampon, si NULL, le message est affiché sur le tampon WeeChat
message : message à afficher

La première tabulation dans le message ("\t") est utilisée pour séparer le préfixe du message.
Si votre message contient des tabulations et si vous ne voulez pas de préfixe, utilisez un espace, une tabulation, puis le message : cela désactivera le préfixe (l’espace avant la tabulation ne sera pas affiché).

Avec deux tabulations ("\t") au début du message, l’heure ne sera pas affichée et le message n’aura pas d’alignement. De plus, la date dans le message sera positionnée à 0.

Exemple en C :

weechat_printf (NULL, "Bonjour sur le tampon WeeChat");
weechat_printf (buffer, "Bonjour sur ce tampon");
weechat_printf (buffer, "%sCeci est une erreur !", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessage sans préfixe mais avec \t quelques \t tabulations");
weechat_printf (buffer, "\t\tMessage sans heure/alignement");
weechat_printf (buffer, "\t\t");  /* ligne vide (sans heure) */

Script (Python) :

# prototype
def prnt(buffer: str, message: str) -> int: ...

# exemple
weechat.prnt("", "Bonjour sur le tampon WeeChat")
weechat.prnt(buffer, "Bonjour sur ce tampon")
weechat.prnt(buffer, "%sCeci est une erreur !" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessage sans préfixe mais avec \t quelques \t tabulations")
weechat.prnt(buffer, "\t\tMessage sans heure/alignement")
weechat.prnt(buffer, "\t\t")  # ligne vide (sans heure)

La fonction s’appelle "print" dans les scripts ("prnt" en Python).

printf_date_tags

Afficher un message sur un tampon, en utilisant une date et des étiquettes personnalisées.

Prototype :

void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);

Cette fonction est un raccourci vers la fonction printf_datetime_tags.
Ces deux appels donnent exactement le même résultat :

weechat_printf_date_tags (buffer, 0, NULL, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

Paramètres :

buffer : pointeur vers le tampon, si NULL, le message est affiché sur le tampon WeeChat
date : date pour le message (0 signifie la date/heure courante)
tags : liste d’étiquettes séparées par des virgules (NULL signifie aucune étiquette)
message : message à afficher

Voir le Guide utilisateur WeeChat / Étiquettes des lignes ^↗ pour une liste des étiquettes couramment utilisées dans WeeChat.

Exemple en C :

weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message il y a 2 minutes avec une étiquette 'notify_message'");

Script (Python) :

# prototype
def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ...

# exemple
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message il y a 2 minutes avec une étiquette 'notify_message'")

La fonction s’appelle "print_date_tags" dans les scripts ("prnt_date_tags" en Python).

printf_datetime_tags

WeeChat ≥ 4.2.0.

Afficher un message sur un tampon, en utilisant une date/heure (avec microsecondes) et des étiquettes personnalisées.

Prototype :

void weechat_printf_datetime_tags (struct t_gui_buffer *buffer, time_t date,
                                   int date_usec, const char *tags, const char *message, ...);

Paramètres :

buffer : pointeur vers le tampon, si NULL, le message est affiché sur le tampon WeeChat
date : date pour le message (0 signifie la date/heure courante)
date_usec : microsecondes de la date (entre 0 et 999999)
tags : liste d’étiquettes séparées par des virgules (NULL signifie aucune étiquette)
message : message à afficher

Voir le Guide utilisateur WeeChat / Étiquettes des lignes ^↗ pour une liste des étiquettes couramment utilisées dans WeeChat.

Exemple en C :

struct timeval tv_now;

gettimeofday (&tv_now, NULL);
weechat_printf_datetime_tags (NULL, tv_now.tv_sec - 120, tv_now.tv_usec,
                              "notify_message",
                              "Message il y a 2 minutes avec une étiquette 'notify_message'");

Script (Python) :

# prototype
def prnt_datetime_tags(buffer: str, date: int, date_usec: int, tags: str, message: str) -> int: ...

# exemple
now = time.time()
time_sec = int(now)
time_usec = int((now * 1000000) % 1000000)
weechat.prnt_datetime_tags("", time_sec - 120, time_usec, "notify_message",
                           "Message il y a 2 minutes avec une étiquette 'notify_message'")

La fonction s’appelle "print_datetime_tags" dans les scripts ("prnt_datetime_tags" en Python).

printf_y

Afficher un message sur une ligne d’un tampon avec contenu libre.

Prototype :

void weechat_printf_y (struct t_gui_buffer *buffer, int y, const char *message, ...);

Cette fonction est un raccourci vers la fonction printf_y_datetime_tags.
Ces deux appels donnent exactement le même résultat :

weechat_printf_y (buffer, 0, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

Paramètres :

buffer : pointeur vers le tampon
y : numéro de ligne (la première ligne est 0); une valeur négative affiche une ligne après la dernière ligne affichée : la valeur absolue de y est le nombre de lignes après la dernière ligne (par exemple -1 est immédiatement après la dernière ligne, -2 est 2 lignes après la dernière ligne) (WeeChat ≥ 1.0)
message : message à afficher

Exemple en C :

weechat_printf_y (buffer, 2, "Mon message sur la 3ème ligne");

Script (Python) :

# prototype
def prnt_y(buffer: str, y: int, message: str) -> int: ...

# exemple
weechat.prnt_y("", 2, "Mon message sur la 3ème ligne")

La fonction s’appelle "print_y" dans les scripts ("prnt_y" en Python).

printf_y_date_tags

WeeChat ≥ 3.5.

Afficher un message sur une ligne d’un tampon avec contenu libre, en utilisant une date et des étiquettes personnalisées.

Prototype :

void weechat_printf_y_date_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                 const char *tags, const char *message, ...);

Cette fonction est un raccourci vers la fonction printf_y_datetime_tags.
Ces deux appels donnent exactement le même résultat :

weechat_printf_y_date_tags (buffer, 0, 0, NULL, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

Paramètres :

buffer : pointeur vers le tampon
y : numéro de ligne (la première ligne est 0); une valeur négative affiche une ligne après la dernière ligne affichée : la valeur absolue de y est le nombre de lignes après la dernière ligne (par exemple -1 est immédiatement après la dernière ligne, -2 est 2 lignes après la dernière ligne)
date : date pour le message (0 signifie la date/heure courante)
tags : liste d’étiquettes séparées par des virgules (NULL signifie aucune étiquette)
message : message à afficher

Exemple en C :

weechat_printf_y_date_tags (buffer, 2, 0, "mon_etiquette", "Mon message sur la 3ème ligne avec une étiquette");

Script (Python) :

# prototype
def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ...

# exemple
weechat.prnt_y_date_tags("", 2, 0, "mon_etiquette", "Mon message sur la 3ème ligne avec une étiquette")

La fonction s’appelle "print_y_date_tags" dans les scripts ("prnt_y_date_tags" en Python).

printf_y_datetime_tags

WeeChat ≥ 4.2.0.

Afficher un message sur une ligne d’un tampon avec contenu libre, en utilisant une date/heure (avec microsecondes) et des étiquettes personnalisées.

Prototype :

void weechat_printf_y_datetime_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                     int date_usec, const char *tags, const char *message, ...);

Paramètres :

buffer : pointeur vers le tampon
y : numéro de ligne (la première ligne est 0); une valeur négative affiche une ligne après la dernière ligne affichée : la valeur absolue de y est le nombre de lignes après la dernière ligne (par exemple -1 est immédiatement après la dernière ligne, -2 est 2 lignes après la dernière ligne)
date : date pour le message (0 signifie la date/heure courante)
date_usec : microsecondes de la date (entre 0 et 999999)
tags : liste d’étiquettes séparées par des virgules (NULL signifie aucune étiquette)
message : message à afficher

Exemple en C :

weechat_printf_y_datetime_tags (buffer, 2, 0, 0, "mon_etiquette", "Mon message sur la 3ème ligne avec une étiquette");

Script (Python) :

# prototype
def prnt_y_datetime_tags(buffer: str, y: int, date: int, date_usec: int, tags: str, message: str) -> int: ...

# exemple
weechat.prnt_y_datetime_tags("", 2, 0, 0, "mon_etiquette", "Mon message sur la 3ème ligne avec une étiquette")

La fonction s’appelle "print_y_datetime_tags" dans les scripts ("prnt_y_datetime_tags" en Python).

log_printf

Écrire un message dans le fichier de log WeeChat (weechat.log).

Prototype :

void weechat_log_printf (const char *message, ...);

Paramètres :

message : message à écrire

Exemple en C :

weechat_log_printf ("Mon message dans le fichier log");

Script (Python) :

# prototype
def log_print(message: str) -> int: ...

# exemple
weechat.log_print("Mon message dans le fichier log")

La fonction s’appelle "log_print" dans les scripts.

3.14. Hooks

Priorité de hook

WeeChat ≥ 0.3.4.

Pour certains "hooks", vous pouvez définir une priorité. Un "hook" avec une priorité plus élevée sera au début de la liste des "hooks", et donc il sera trouvé et exécuté avant les autres "hooks". Cela est pratique pour les modificateurs, car l’ordre d’exécution est important.

Pour définir une priorité, vous devez utiliser cette syntaxe, pour un paramètre où la priorité est autorisée : nnn|nom où nnn est un entier positif ou nul avec la priorité et nom le nom pour le paramètre (la priorité n’apparaît pas dans le nom, elle est automatiquement retirée de la chaîne).
Une seule priorité par "hook" est autorisée.

La priorité par défaut est 1000.

Exemples en C :

/* accrocher un modificateur avec priorité = 2000 */
/* haute priorité : appelé avant les autres fonctions de rappel "modifier" */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

/* accrocher deux signaux avec priorité = 3000 */
/* haute priorité : appelé avant les autres fonctions de rappel "signal" */
weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL);

/* accrocher les lignes affichées dans les tampons formatés avec priorité = 500 */
/* basse priorité : appelé après les autres fonctions de rappel "line" */
weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL);

Les types de "hooks" suivants autorisent une priorité :

command
completion
command_run
line
signal
hsignal
config
modifier
info
info_hashtable
infolist
hdata
focus

hook_command

Mis à jour dans la 1.5, 1.7.

Accrocher une commande.

Prototype :

struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     const void *callback_pointer,
                                     void *callback_data);

Paramètres :

command : nom de la commande (une priorité est autorisée avant la commande, voir la note sur la priorité)
description : description de la commande (affiché avec /help command)
args : paramètres pour la commande (affichés avec /help command)
args_description : description des paramètres (affichée avec /help command)
completion : modèle pour la complétion de la commande (voir le format ci-dessous)
callback : fonction appelée lorsque la commande est utilisée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : tampon où la commande est exécutée
- int argc : nombre de paramètres passés à la commande
- char **argv : paramètres pour la commande
- char **argv_eol : paramètres pour la commande (jusqu’à fin de ligne pour chaque paramètre)
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Le modèle de complétion est une liste de complétions pour chaque paramètre, séparés par des espaces. Plusieurs complétions sont possibles pour un paramètre, séparées par |. Plusieurs modèles de complétions sont possibles pour une même commande, séparés par ||.

Le format de la complétion peut être :

%(nom) : la complétion nom
%(nom:paramètres) : la complétion nom avec des paramètres envoyés à la fonction de rappel (WeeChat ≥ 1.7)
toute chaîne : elle est utilisée telle quelle dans la complétion

Par exemple le modèle list || add %(filters_names) || del %(filters_names)|-all complètera avec les valeurs suivantes dans les paramètres de commande :

premier paramètre : list, add et del
second paramètre, cela dépend du premier paramètre :
- list : rien
- add : noms des filtres
- del : noms des filtres et -all

Les codes complétions par défaut sont :

Extension

Nom

Description

alias

liste des alias

alias

alias_value

valeur de l’alias

buflist

buflist_items

objets de barre de buflist

buflist

buflist_items_used

objets de barre buflist utilisés (selon l’option buflist.look.use_items)

exec

exec_commands_ids

ids (nombres et noms) des commandes exécutées

fset

fset_options

fichiers de configuration, section, options et mots des options

guile

guile_script

liste des scripts

irc

irc_channel

canal IRC courant

irc

irc_channel_nicks_hosts

pseudos et noms d’hôtes du canal IRC courant

irc

irc_channel_topic

titre du canal IRC courant

irc

irc_channels

canaux sur tous les serveurs IRC

irc

irc_channels_autojoin

canaux automatiquement rejoints sur le serveur courant (option "autojoin")

irc

irc_ignores_numbers

numéros pour les ignores définis

irc

irc_modelist_masks

masques de la liste de modes du canal IRC courant ; argument obligatoire : mode de la liste de modes

irc

irc_modelist_numbers

nombres de la liste de modes du canal IRC courant ; argument obligatoire : mode de la liste de modes

irc

irc_msg_kick

message d’éjection par défaut

irc

irc_msg_part

message de fin par défaut pour le canal IRC

irc

irc_notify_nicks

pseudos dans la liste de notifications

irc

irc_privates

privés sur tous les serveurs IRC

irc

irc_raw_filters

filtres pour le tampon de données brutes irc

irc

irc_server

serveur IRC courant

irc

irc_server_channels

canaux sur le serveur IRC courant

irc

irc_server_nick

pseudo sur le serveur IRC courant

irc

irc_server_nicks

pseudos sur tous les canaux du serveur IRC courant

irc

irc_server_prefix_modes_filter

paramètres pour filtrer par préfixe de mode (par exemple : "-o", "-h", "-v", "-*")

irc

irc_server_privates

privés sur le serveur IRC courant

irc

irc_servers

serveurs IRC (noms internes)

irc

nick

pseudos du canal IRC courant

lua

lua_script

liste des scripts

perl

perl_script

liste des scripts

php

php_script

liste des scripts

python

python_script

liste des scripts

relay

relay_free_port

premier port libre pour l’extension relay

relay

relay_protocol_name

tous les protocole.nom possible pour l’extension relay

relay

relay_relays

protocole.nom des relais courants pour l’extension relay

ruby

ruby_script

liste des scripts

script

script_extensions

liste des extensions de script

script

script_files

fichiers dans les répertoires de script

script

script_languages

liste des langages de script

script

script_scripts

liste des scripts du dépôt

script

script_scripts_installed

liste des scripts installés (du dépôt)

script

script_tags

étiquettes des scripts dans le dépôt

spell

spell_dicts

liste des dictionnaires installés

spell

spell_langs

liste de toutes les langues supportées

tcl

tcl_script

liste des scripts

trigger

trigger_add_arguments

paramètres pour la commande qui ajoute un trigger : nom du trigger, hooks, paramètres du hook, conditions du hook, regex du hook, commande du hook, code retour du hook, actions "post"

trigger

trigger_hook_arguments

paramètres par défaut pour un hook

trigger

trigger_hook_command

commande par défaut pour un hook

trigger

trigger_hook_conditions

conditions par défaut pour un hook

trigger

trigger_hook_rc

code retour par défaut pour une fonction de rappel de hook

trigger

trigger_hook_regex

expression régulière par défaut pour le hook

trigger

trigger_hooks

hooks pour les triggers

trigger

trigger_hooks_filter

hooks pour les triggers (pour filtrer dans le tampon moniteur)

trigger

trigger_names

triggers

trigger

trigger_names_default

triggers par défaut

trigger

trigger_names_disabled

triggers désactivés

trigger

trigger_names_enabled

triggers activés

trigger

trigger_option_value

valeur d’une option de trigger

trigger

trigger_options

options pour les triggers

trigger

trigger_post_action

actions "post" pour les triggers

weechat

bars_names

noms des barres

weechat

bars_options

options pour les barres

weechat

buffer_local_variable_value

valeur d’une variable locale du tampon

weechat

buffer_local_variables

variables locales du tampon

weechat

buffer_properties_get

propriétés qui peuvent être lues sur un tampon

weechat

buffer_properties_set

propriétés qui peuvent être changées sur un tampon

weechat

buffer_properties_setauto

propriétés qui peuvent être automatiquement changées sur un tampon

weechat

buffers_names

noms des tampons

weechat

buffers_numbers

numéros des tampons

weechat

buffers_plugins_names

noms des tampons (incluant les noms d’extensions)

weechat

colors

noms des couleurs

weechat

commands

commandes (weechat et extensions) ; paramètre optionnel : préfixe à ajouter avant les commandes

weechat

config_files

fichiers de configuration

weechat

config_option_values

valeurs pour une option de configuration

weechat

config_options

options de configuration

weechat

cursor_areas

zones ("chat" ou un nom de barre) pour le mouvement libre du curseur

weechat

custom_bar_item_add_arguments

paramètres pour la commande qui ajoute un objet de barre personnalisé : nom de l’objet, conditions, contenu

weechat

custom_bar_item_conditions

conditions pour l’objet de barre personnalisé

weechat

custom_bar_item_contents

contenus pour l’objet de barre personnalisé

weechat

custom_bar_items_names

noms des objets de barre personnalisés

weechat

env_value

valeur d’une variable d’environnement

weechat

env_vars

variables d’environnement

weechat

eval_variables

variables qui peuvent être utilisées dans la commande /eval

weechat

filename

nom de fichier ; paramètre optionnel : chemin par défaut (évalué, voir /help eval)

weechat

filters_names

noms des filtres

weechat

filters_names_disabled

noms des filtres désactivés

weechat

filters_names_enabled

noms des filtres activés

weechat

infolists

noms des infolistes accrochées

weechat

infos

noms des infos accrochées

weechat

keys_codes

codes des touches

weechat

keys_codes_for_reset

codes des touches pouvant être réinitialisées (touches ajoutées, redéfinies ou supprimées)

weechat

keys_contexts

contextes de touches

weechat

layouts_names

noms des dispositions

weechat

nicks

pseudos dans la liste des pseudos du tampon courant

weechat

palette_colors

couleurs de la palette

weechat

plugins_commands

commandes définies par les extensions ; paramètre optionnel : préfixe à ajouter avant les commandes

weechat

plugins_installed

noms des extensions installées

weechat

plugins_names

noms des extensions

weechat

proxies_names

noms des proxies

weechat

proxies_options

options pour les proxies

weechat

secured_data

noms de données sécurisées (fichier sec.conf, section data)

weechat

weechat_commands

commandes weechat ; paramètre optionnel : préfixe à ajouter avant les commandes

weechat

windows_numbers

numéros des fenêtres

xfer

nick

pseudos de la discussion DCC

Codes spéciaux :

%%command : réutiliser le modèle de complétion de la commande command
%- : arrêter la complétion
%* : répéter la dernière complétion

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_command_cb (const void *pointer, void *data, struct t_gui_buffer *buffer,
               int argc, char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cet exemple s'inspire de la commande /filter */
struct t_hook *my_command_hook =
    weechat_hook_command ("monfiltre",
                          "description de monfiltre",
                          "[list] | [enable|disable|toggle [nom]] | "
                          "[add nom extension.tampon tags regex] | "
                          "[del nom|-all]",
                          "description des paramètres...",
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          &my_command_cb, NULL, NULL);

Par exemple, si la commande appelée est /command abc def ghi, alors argv et argv_eol ont les valeurs suivantes :

argv :
- argv[0] == "/command"
- argv[1] == "abc"
- argv[2] == "def"
- argv[3] == "ghi"
argv_eol :
- argv_eol[0] == "/command abc def ghi"
- argv_eol[1] == "abc def ghi"
- argv_eol[2] == "def ghi"
- argv_eol[3] == "ghi"

Pour les scripts, args a la valeur "abc def ghi".

Script (Python) :

# prototype
def hook_command(command: str, description: str, args: str, args_description: str,
                 completion: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_command_cb(data: str, buffer: str, args: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("monfiltre", "description de monfiltre",
    "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
    "description des paramètres...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")

hook_completion

Mis à jour dans la 1.5, 1.7.

Accrocher une complétion.

Prototype :

struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(const void *pointer,
                                                        void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        const void *callback_pointer,
                                        void *callback_data);

Paramètres :

completion_item : nom de l’objet de complétion, après vous pouvez utiliser %(nom) (ou %(nom:paramètres) avec WeeChat ≥ 1.7) dans une commande (paramètre completion) (une priorité est autorisée avant le nom de l’objet de complétion, voir la note sur la priorité)
description : description de la complétion
callback : fonction appelée lorsque la complétion est utilisée (l’utilisateur est en train de compléter quelque chose qui fait appel à cette complétion), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *completion_item : nom de la complétion (avec WeeChat ≥ 1.7 il peut inclure des paramètres, avec le format : nom:paramètres)
- struct t_gui_buffer *buffer : tampon où la complétion est effectuée
- struct t_gui_completion *completion : structure utilisée pour ajouter les mots pour la complétion (voir completion_list_add)
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Les noms de complétion sont globaux (partagés entre WeeChat et les extensions). Il est donc recommandé de choisir un nom avec un préfixe unique, comme "monextension_xxx" (où "xxx" est le nom de votre complétion).

La fonction de rappel doit seulement appeler des fonction de complétion comme completion_list_add et ne doit PAS mettre à jour la ligne de commande.
Pour mettre à jour la ligne de commande quand Tab est pressé, vous pouvez utiliser la fonction hook_command_run avec la commande : /input complete_next (et vous devez retourner WEECHAT_RC_OK_EAT si votre fonction de rappel a mis à jour la ligne de commande, de sorte que WeeChat n’exécute pas la complétion).

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_completion_list_add (completion, "mot1", 0, WEECHAT_LIST_POS_SORT);
    weechat_completion_list_add (completion, "test_mot2", 0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("extension_item",
                                                             "ma complétion !",
                                                             &my_completion_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    weechat.completion_list_add(completion, "mot1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.completion_list_add(completion, "test_mot2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("extension_item", "ma complétion !",
                               "my_completion_cb", "")

hook_completion_get_string

WeeChat ≥ 0.3.4.

Obsolète depuis WeeChat 2.9 (toujours là pour des raisons de compatibilité).
Cette fonction a été remplacée par completion_get_string.

hook_completion_list_add

Obsolète depuis WeeChat 2.9 (toujours là pour des raisons de compatibilité).
Cette fonction a été remplacée par completion_list_add.

hook_command_run

Mis à jour dans la 1.5.

Intercepter une commande lorsqu’elle est exécutée par WeeChat.

Prototype :

struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         const void *callback_pointer,
                                         void *callback_data);

Paramètres :

command : commande à intercepter (le caractère joker * est autorisé) (une priorité est autorisée avant la commande, voir la note sur la priorité)
callback : fonction appelée lorsque la commande est exécutée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : tampon où la commande est exécutée
- const char *command : la commande exécutée, avec ses paramètres
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT : la commande ne sera pas exécutée par WeeChat après la fonction de rappel
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_command_run_cb (const void *pointer, void *data,
                   struct t_gui_buffer *buffer, const char *command)
{
    weechat_printf (NULL, "Je mange la complétion !");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_command_run(command: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_command_run_cb(data: str, buffer: str, command: str) -> int:
    weechat.prnt("", "Je mange la complétion !")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")

hook_timer

Mis à jour dans la 1.5.

Accrocher un minuteur (fonction appelée à intervalles réguliers).

Prototype :

struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int max_calls,
                                   int (*callback)(const void *pointer,
                                                   void *data,
                                                   int remaining_calls),
                                   const void *callback_pointer,
                                   void *callback_data);

Paramètres :

interval : intervalle entre deux appels (en millisecondes, donc 1000 = 1 seconde)
align_second : alignement sur la seconde. Par exemple, si la date courante est 09:00, si l’intervalle est 60000 (60 secondes), et que align_second = 60, alors le minuteur sera appelé chaque minute quand la seconde sera 0
max_calls : nombre maximum d’appels au minuteur (si 0, le minuteur n’a pas de fin)
callback : fonction appelée quand le délai est atteint, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- int remaining_calls : nombre d’appels restants (-1 si le minuteur n’a pas de fin)
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_timer_cb (const void *pointer, void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* minuteur appelé toutes les 20 secondes */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_timer(interval: int, align_second: int, max_calls: int, callback: str, callback_data: str) -> str: ...

# exemple
def my_timer_cb(data: str, remaining_calls: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# minuteur appelé toutes les 20 secondes
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")

hook_fd

Mis à jour dans la 1.3, 1.5, 2.0.

Accrocher un descripteur de fichier (fichier ou socket).

Prototype :

struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(const void *pointer,
                                                void *data,
                                                int fd),
                                const void *callback_pointer,
                                void *callback_data);

Paramètres :

fd : descripteur de fichier
flag_read : 1 = intercepter un évènement de lecture, 0 = ignorer
flag_write : 1 = intercepter un évènement d’écriture, 0 = ignorer
flag_exception : 1 = intercepter un évènement d’exception, 0 = ignorer (WeeChat ≥ 1.3 : ce paramètre est ignoré et n’est plus utilisé)
callback : fonction appelée lorsqu’un des évènements sélectionnés se produit pour le fichier (ou le socket), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- int fd : descripteur de fichier
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Dans les scripts, avec WeeChat ≥ 2.0, le paramètre de la fonction de rappel fd est un entier (avec WeeChat ≤ 1.9, il était une chaîne).
Pour être compatible avec toutes les versions, il est recommandé de convertir le paramètre en entier avant de l’utiliser, par exemple en Python : int(fd).

Exemple en C :

int
my_fd_cb (const void *pointer, void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* définir les options du socket */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_fd(fd: int, flag_read: int, flag_write: int, flag_exception: int, callback: str, callback_data: str) -> str: ...

# exemple
def my_fd_cb(data: str, fd: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")

hook_process

Mis à jour dans la 1.5.

Accrocher un processus (lancé par un fork), et intercepter sa sortie.

Depuis la version 0.3.9.2, le shell n’est plus utilisé pour exécuter la commande. WeeChat effectue un découpage automatique de la commande et de ses paramètres (comme le fait le shell).
Si le découpage n’est pas correct (selon les guillemets utilisés dans votre commande), ou si vous souhaitez utiliser le shell, vous pouvez utiliser la fonction hook_process_hashtable avec les paramètres dans la table de hachage options (WeeChat ≥ 0.4.0).

Prototype :

struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     const void *callback_pointer,
                                     void *callback_data);

Paramètres :

command : commande à lancer dans le processus fils, URL (WeeChat ≥ 0.3.7) ou fonction (WeeChat ≥ 1.5) (voir ci-dessous)
timeout : timeout pour la commande (en millisecondes) : après ce délai, le processus fils est tué (0 signifie pas de limite)
callback : fonction appelée quand des données du fils sont disponibles, or ou quand le fils s’est terminé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *command : commande exécutée par le fils
- int return_code : code retour :
  - ≥ 0 : code retour du fils pour une commande, et pour l’URL, les valeurs possibles sont :
    
    0 : transfert ok
    
    1 : URL invalide
    
    2 : erreur de transfert
    
    3 : pas assez de mémoire
    
    4 : erreur avec un fichier
  - < 0 :
    
    WEECHAT_HOOK_PROCESS_RUNNING (-1) : données disponibles, mais le fils tourne toujours
    
    WEECHAT_HOOK_PROCESS_ERROR (-2) : erreur en lançant la commande
    
    WEECHAT_HOOK_PROCESS_CHILD (-3) : la fonction de rappel est appelée dans le processus fils (utilisé seulement dans l’API C, pas l’API script)
- out : sortie standard de la commande (stdout)
- err : erreurs de la commande (stderr)
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
  - code retour du processus fils (dans le cas d’une fonction avec "func:" dans la commande)
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Lorsque la commande est terminée, ou si le timeout est atteint, WeeChat supprimera automatiquement le "hook" (et tuera le processus s’il tourne toujours).

La commande peut être une URL avec le format : "url:https://www.example.com", pour télécharger le contenu de l’URL (WeeChat ≥ 0.3.7). Des options pour l’URL sont possibles avec la fonction hook_process_hashtable.

La commande peut aussi être le nom d’une fonction avec le format : "func:nom", pour exécuter la fonction "nom" (WeeChat ≥ 1.5). Cette fonction reçoit un paramètre (data) et doit retourner une chaîne de caractères, qui sera envoyée à la fonction de rappel.
Dans l’API C, la fonction de rappel est appelée avec le code retour qui vaut WEECHAT_HOOK_PROCESS_CHILD, cela signifie que la fonction de rappel tourne dans le processus fils (après le fork).
Dans l’API script, la fonction nom est appelée directement et le résultat (chaîne de caractères) est envoyé à la fonction de rappel (comme la sortie d’une commande externe).

Si vous souhaitez récupérer des infos à propos de WeeChat (comme la version stable actuelle, le dernier commit git, etc.), vous pouvez utiliser les URLs sur cette page ^↗.

La taille du tampon pour l’envoi des données à la fonction de rappel est de 64 Ko (il y a 2 tampons : un pour stdout et un pour stderr). Si la sortie du processus fils (stdout ou stderr) est plus longue que 64 Ko, la fonction de rappel sera appelée plusieurs fois.

Même si la plupart du temps la fonction de rappel n’est appelée qu’une seule fois, vous devez vous assurer que plusieurs appels à la fonction de rappel sont OK dans votre code : vous devez concaténer les données issues de plusieurs appels et n’utiliser les données que lorsque le code retour est positif ou nul.

Exemple en C :

/* exemple avec une commande externe */
int
my_process_cb (const void *pointer, void *data, const char *command,
               int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Erreur avec la commande '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout : %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr : %s", err);
    }

    return WEECHAT_RC_OK;
}

struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL, NULL);

/* exemple avec la fonction de rappel appelée dans le processus fils */
int
my_process_func_cb (const void *pointer, void *data, const char *command,
                    int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
    {
        /* faire quelque chose de bloquant... */
        /* ... */

        /* la sortie "stdout" sera envoyée comme "out" à la fonction de rappel parente */
        printf ("ceci est le résultat");

        /* code retour du processus */
        return 0;
    }
    else
    {
        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
        {
            weechat_printf (NULL, "Erreur avec la commande '%s'", command);
            return WEECHAT_RC_OK;
        }

        if (return_code >= 0)
        {
            weechat_printf (NULL, "return_code = %d", return_code);
        }

        if (out)
        {
            weechat_printf (NULL, "stdout : %s", out);
        }

        if (err)
        {
            weechat_printf (NULL, "stderr : %s", err);
        }

        return WEECHAT_RC_OK;
    }
}

struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
                                                       &my_process_func_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_process(command: str, timeout: int, callback: str, callback_data: str) -> str: ...

# exemple avec une commande externe
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%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", "")

# exemple avec une fonction du script
def get_status(data: str) -> str:
    # faire quelque chose de bloquant...
    # ...
    return "ceci est le résultat"

def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out:
        weechat.prnt("", "stdout : %s" % out)
    if err:
        weechat.prnt("", "stderr : %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")

hook_process_hashtable

WeeChat ≥ 0.3.7, mis à jour dans la 1.5.

Accrocher un processus (lancé par un fork) en utilisant des options dans une table de hachage, et intercepter sa sortie.

Prototype :

struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(const void *pointer,
                                                               void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               const void *callback_pointer,
                                               void *callback_data);

Les paramètres sont les mêmes que ceux de la fonction hook_process, avec un paramètre supplémentaire :

options : options pour la commande exécutée ; la table de hachage est dupliquée dans la fonction, donc il est possible de la supprimer après cet appel

Pour une commande standard (ne commençant pas par "url:"), les options suivantes sont disponibles :

Option

WeeChat mini

Valeur

Défaut

Description

argN (N ≥ 1)

0.4.0

toute chaîne

pas de paramètres

Paramètres pour la commande ; si aucun paramètre n’est donné avec ces options, la commande sera automatiquement découpée comme le fait le shell (et donc les paramètres de la commande sont lus dans le paramètre command).

stdin

0.4.3

(non utilisée)

pas de stdin

Créer un tuyau pour écrire sur l’entrée standard (stdin) du processus fils (voir la fonction hook_set).

buffer_flush

1.0

nombre d’octets

65536

Nombre minimum d’octets pour vider stdout/stderr (pour envoyer la sortie à la fonction de rappel), entre 1 et 65536. Avec la valeur 1, la sortie est envoyée immédiatement à la fonction de rappel.

detached

1.0

(non utilisée)

non détaché

Lancer le process dans un mode détaché : stdout et stderr sont redirigés vers /dev/null.

Pour la commande "url:…", voir les options disponibles dans la fonction hook_url.

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_process_cb (const void *pointer, void *data, const char *command,
               int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Erreur avec la commande '%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;
}

/* exemple 1 : téléchargement d'une URL */
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                     options_url1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* exemple 2 : ouverture d'une URL avec des en-têtes HTTP personnalisés */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: valeur1\n"
                           "Header2: valeur2");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://localhost:8080/",
                                                                     options_url2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}

/* exemple 3 : exécution d'un programme de notification avec le message de quelqu'un */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message);  /* paramètre non sûr */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* exemple 4 : appeler le shell pour exécuter la commande (la commande doit être SURE) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd2);
}

Script (Python) :

# prototype
def hook_process_hashtable(command: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# exemple
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%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

# exemple 1 : téléchargement d'une URL
hook1 = weechat.hook_process_hashtable("url:https://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# exemple 2 : ouverture d'une URL avec des en-têtes HTTP personnalisés
options = {
    "httpheader": "\n".join([
        "Header1: valeur1",
        "Header2: valeur2",
    ]),
}
hook2 = weechat.hook_process_hashtable("url:http://localhost:8080/",
                                       options,
                                       20000, "my_process_cb", "")

# exemple 3 : exécution d'un programme de notification avec le message de quelqu'un
hook3 = weechat.hook_process_hashtable("my-notify-command",
                                       {"arg1": "-from",
                                        "arg2": nick,
                                        "arg3": "-msg",
                                        "arg4": message},  # paramètre non sûr
                                       20000, "my_process_cb", "")

# exemple 4 : appeler le shell pour exécuter la commande (la commande doit être SURE)
hook4 = weechat.hook_process_hashtable("sh",
                                       {"arg1": "-c",
                                        "arg2": "ls -l /tmp | grep something"},
                                       20000, "my_process_cb", "")

hook_url

WeeChat ≥ 4.1.0.

Transfert d’URL.

Prototype :

struct t_hook *weechat_hook_url (const char *url,
                                 struct t_hashtable *options,
                                 int timeout,
                                 int (*callback)(const void *pointer,
                                                 void *data,
                                                 const char *url,
                                                 struct t_hashtable *options,
                                                 struct t_hashtable *output),
                                 const void *callback_pointer,
                                 void *callback_data);

Paramètres :

url : URL
options : options pour le transfert d’URL (voir ci-dessous) ; la table de hachage est dupliquée dans la fonction, donc il est possible de la supprimer après cet appel
timeout : timeout pour le transfert d’URL (en millisecondes) : après de délai, le transfert est stoppé (0 signifie pas de limite)
callback : fonction appelée lorsque le transfert est terminé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *url : URL
- struct t_hashtable *options : options
- struct t_hashtable *output : résultat (les clés et valeurs sont des chaînes), qui peut contenir les clés suivantes :
  - response_code : code réponse HTTP
  - headers : en-têtes HTTP dans la réponse
  - output : sortie standard (défini seulement si file_out n’était pas défini dans les options)
  - error : message d’erreur (défini seulement en cas d’erreur)
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Les options Curl suivantes sont disponibles (voir man curl_easy_setopt pour une description de chaque option) :

Option

Type ⁽¹⁾

Constantes ⁽²⁾

verbose

long

header

long

noprogress

long

nosignal

long

wildcardmatch

long

failonerror

long

keep_sending_on_error

long

proxy

string

proxyport

long

port

long

pre_proxy

string

httpproxytunnel

long

interface

string

dns_cache_timeout

long

proxytype

long

http, socks4, socks5, socks4a, socks5_hostname, http_1_0, https

buffersize

long

tcp_nodelay

long

localport

long

localportrange

long

address_scope

long

noproxy

string

socks5_gssapi_nec

long

tcp_keepalive

long

tcp_keepidle

long

tcp_keepintvl

long

unix_socket_path

string

abstract_unix_socket

string

path_as_is

long

proxy_service_name

string

service_name

string

default_protocol

string

tcp_fastopen

long

socks5_auth

long

haproxyprotocol

long

doh_url

string

protocols_str

string

redir_protocols_str

string

netrc

long

ignored, optional, required

userpwd

string

proxyuserpwd

string

httpauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate, gssapi, bearer, aws_sigv4

proxyauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate, gssapi, bearer, aws_sigv4

netrc_file

string

username

string

password

string

proxyusername

string

proxypassword

string

tlsauth_type

mask

none, srp

tlsauth_username

string

tlsauth_password

string

sasl_authzid

string

sasl_ir

long

xoauth2_bearer

string

login_options

string

disallow_username_in_url

long

autoreferer

long

followlocation

long

post

long

postfields

string

referer

string

useragent

string

httpheader

list

string

cookiefile

string

postfieldsize

long

maxredirs

long

httpget

long

cookiejar

string

http_version

long

none, 1_0, 1_1, 2_0, 2, 2tls, 2_prior_knowledge, 3

cookiesession

long

http200aliases

list

unrestricted_auth

long

postfieldsize_large

long long

cookielist

string

ignore_content_length

long

accept_encoding

string

transfer_encoding

long

http_content_decoding

long

http_transfer_decoding

long

copypostfields

string

postredir

mask

post_301, post_302

expect_100_timeout_ms

long

headeropt

mask

unified, separate

proxyheader

list

pipewait

long

stream_weight

long

request_target

string

http09_allowed

long

hsts

string

hsts_ctrl

mask

enable, readonlyfile

mail_from

string

mail_rcpt

list

mail_auth

string

mail_rcpt_alllowfails

long

tftp_blksize

long

tftp_no_options

long

ftpport

string

quote

list

postquote

list

ftp_use_epsv

long

prequote

list

ftp_use_eprt

long

ftp_create_missing_dirs

long

ftpsslauth

long

default, ssl, tls

ftp_account

string

ftp_skip_pasv_ip

long

ftp_filemethod

long

multicwd, nocwd, singlecwd

ftp_alternative_to_user

string

ftp_ssl_ccc

long

ccc_none, ccc_active, ccc_passive

dirlistonly

long

append

long

ftp_use_pret

long

rtsp_request

long

options, describe, announce, setup, play, pause, teardown, get_parameter, set_parameter, record, receive

rtsp_session_id

string

rtsp_stream_uri

string

rtsp_transport

string

rtsp_client_cseq

long

rtsp_server_cseq

long

aws_sigv4

string

crlf

long

range

string

resume_from

long

customrequest

string

nobody

long

infilesize

long

upload

long

timecondition

long

none, ifmodsince, ifunmodsince, lastmod

timevalue

long

transfertext

long

filetime

long

maxfilesize

long

proxy_transfer_mode

long

resume_from_large

long long

infilesize_large

long long

maxfilesize_large

long long

timevalue_large

long long

upload_buffersize

long

mime_options

mask

formescape

timeout

long

low_speed_limit

long

low_speed_time

long

fresh_connect

long

forbid_reuse

long

connecttimeout

long

ipresolve

long

whatever, v4, v6

connect_only

long

max_send_speed_large

long long

max_recv_speed_large

long long

timeout_ms

long

connecttimeout_ms

long

maxage_conn

long

maxconnects

long

use_ssl

long

none, try, control, all

resolve

list

dns_servers

string

accepttimeout_ms

long

dns_interface

string

dns_local_ip4

string

dns_local_ip6

string

connect_to

list

happy_eyeballs_timeout_ms

long

dns_shuffle_addresses

long

upkeep_interval_ms

long

maxlifetime_conn

long

sslcert

string

sslversion

long

default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3

ssl_verifypeer

long

cainfo

string

ssl_verifyhost

long

ssl_cipher_list

string

sslcerttype

string

sslkey

string

sslkeytype

string

sslengine

string

sslengine_default

long

capath

string

ssl_sessionid_cache

long

krblevel

string

keypasswd

string

issuercert

string

crlfile

string

certinfo

long

gssapi_delegation

long

none, policy_flag, flag

ssl_options

long

allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert

ssl_enable_alpn

long

pinnedpublickey

string

ssl_verifystatus

long

ssl_falsestart

long

proxy_cainfo

string

proxy_capath

string

proxy_crlfile

string

proxy_keypasswd

string

proxy_pinnedpublickey

string

proxy_sslcert

string

proxy_sslcerttype

string

proxy_sslkey

string

proxy_sslkeytype

string

proxy_sslversion

long

default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3

proxy_ssl_cipher_list

list

proxy_ssl_options

long

allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert

proxy_ssl_verifyhost

long

proxy_ssl_verifypeer

long

proxy_tlsauth_password

string

proxy_tlsauth_type

string

proxy_tlsauth_username

string

tls13_ciphers

list

proxy_tls13_ciphers

list

proxy_issuercert

string

ssl_ec_curves

string

doh_ssl_verifyhost

long

doh_ssl_verifypeer

long

doh_ssl_verifystatus

long

ca_cache_timeout

long

ssh_auth_types

mask

none, policy_flag, flag

ssh_public_keyfile

string

ssh_private_keyfile

string

ssh_host_public_key_md5

string

ssh_knownhosts

string

ssh_compression

long

ssh_host_public_key_sha256

string

telnetoptions

list

ws_options

mask

binary, close, cont, offset, ping, pong, raw_mode, text

new_file_perms

long

new_directory_perms

long

quick_exit

long

⁽¹⁾ Pour les options avec le type "mask", le format est : "value1+value2+value3" ; pour les options avec le type "list", les éléments de la liste doivent être séparés par un retour à la ligne (\n).
⁽²⁾ Lorsque des constantes sont disponibles, elles doivent être utilisées comme valeur pour l’option.

Ces deux options supplémentaires (chaînes) sont autorisées, pour le fichier en entrée/sortie :

Option

Type

Description

file_in

string

fichier à lire pour envoyer avec l’URL (envoi de fichier "post")

file_out

string

écrire l’URL/fichier dans ce fichier (au lieu de la sortie standard)

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_url_cb (const void *pointer, void *data, const char *url,
           struct t_hashtable *options, struct t_hashtable *output)
{
    weechat_printf (NULL, "response_code : %s", weechat_hashtable_get (output, "response_code"));
    weechat_printf (NULL, "headers : %s", weechat_hashtable_get (output, "headers"));
    weechat_printf (NULL, "output : %s", weechat_hashtable_get (output, "output"));
    weechat_printf (NULL, "error : %s", weechat_hashtable_get (output, "error"));
    return WEECHAT_RC_OK;
}

/* example 1: sortie dans un fichier */
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_url_hook = weechat_hook_url ("https://weechat.org/",
                                                   options_url1,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* example 2: en-têtes HTTP personnalisés, sortie envoyée à la fonction de rappel */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: valeur1\n"
                           "Header2: valeur2");
    struct t_hook *my_url_hook = weechat_hook_url ("http://localhost:8080/",
                                                   options_url2,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}

Script (Python) :

# prototype
def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# exemple
def my_url_cb(data: str, url: str, options: Dict[str, str], output: Dict[str, str]) -> int:
    weechat.prnt("", "output: %s" % output)
    return weechat.WEECHAT_RC_OK

# exemple 1 : sortie dans un fichier
hook1 = weechat.hook_url("https://weechat.org/",
                         {"file_out": "/tmp/weechat.org.html"},
                         20000, "my_url_cb", "")

# exemple 2 : en-têtes HTTP personnalisés, sortie envoyée à la fonction de rappel
options = {
    "httpheader": "\n".join([
        "Header1: valeur1",
        "Header2: valeur2",
    ]),
}
hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "")

hook_connect

Mis à jour dans la 1.5, 2.0.

Accrocher une connexion (connexion à une machine distante en tâche de fond).

Prototype :

struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     const void *callback_pointer,
                                     void *callback_data);

Paramètres :

proxy : nom du proxy à utiliser pour la connexion (optionnel, NULL signifie une connexion sans proxy)
address : nom ou adresse IP de la machine à laquelle se connecter
port : numéro de port
ipv6 : 1 pour utiliser IPv6 (avec repli sur IPv4), 0 pour utiliser seulement IPv4
retry : numéro de nouvelle tentative, utilisé pour se rabattre sur les adresses IPv4 si la connexion IPv6 échoue
gnutls_sess : session GnuTLS (optionnel)
gnutls_cb : fonction de rappel pour GnuTLS (optionnelle)
gnutls_dhkey_size : taille de clé utilisée pour l’échange de clé Diffie-Hellman (GnuTLS)
gnutls_priorities : priorités pour gnutls (pour la syntaxe, voir la documentation de la fonction gnutls_priority_init dans le manuel gnutls), les valeurs de base sont :
- PERFORMANCE
- NORMAL (défaut)
- SECURE128
- SECURE256
- EXPORT
- NONE
local_hostname : nom de machine local à utiliser pour la connexion (optionnel)
callback : fonction appelée lorsque la connexion est OK ou a échoué, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- int status : statut de connexion :
  - WEECHAT_HOOK_CONNECT_OK : connexion ok
  - WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND : adresse non trouvée
  - WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND : adresse IP non trouvée
  - WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED : connexion refusée
  - WEECHAT_HOOK_CONNECT_PROXY_ERROR : erreur avec le proxy
  - WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR : erreur avec le nom local
  - WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR : erreur d’initialisation GnuTLS
  - WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR : erreur avec la "poignée de main" GnuTLS
  - WEECHAT_HOOK_CONNECT_MEMORY_ERROR : mémoire insuffisante
  - WEECHAT_HOOK_CONNECT_TIMEOUT : temps maximum dépassé
  - WEECHAT_HOOK_CONNECT_SOCKET_ERROR : erreur de création socket
- gnutls_rc : valeur retour de gnutls_handshake()
- sock : socket utilisé pour la connexion
- const char *error : valeur retour de gnutls_strerror(gnutls_rc)
- const char *ip_address : adresse IP trouvée
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Dans les scripts, avec WeeChat ≥ 2.0, les paramètres de la fonction de rappel status, gnutls_rc et sock sont des entiers (avec WeeChat ≤ 1.9, ils étaient des chaînes).
Pour être compatible avec toutes les versions, il est recommandé de convertir le paramètre avant de l’utiliser, par exemple en Python: int(sock).

Exemple en C :

int
my_connect_cb (const void *pointer, void *data, int status, int gnutls_rc,
               int sock, const char *error, const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       1, 0,
                                                       NULL, NULL, 0,  /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_connect(proxy: str, address: str, port: int, ipv6: int, retry: int, local_hostname: str,
                 callback: str, callback_data: str) -> str: ...

# exemple
def my_connect_cb(data: str, status: int, gnutls_rc: int, sock: int, error: str, ip_address: str) -> int:
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, 1, 0, "",
                            "my_connect_cb", "")

hook_line

WeeChat ≥ 2.3, mis à jour dans la 4.2.0.

Intercepter une ligne sur le point d’être affichée dans un tampon.

Lorsqu’une ligne est affichée dans un tampon, les "hooks" suivants sont appelés dans cet ordre :

hook line (ce "hook") : il peut changer le tampon, préfixe, message, étiquettes, niveau de notification, … (voir ci-dessous)
hook modifier "weechat_print" : il peut changer le préfixe et le message sur un tampon avec contenu formaté
hook print : appelé quand une ligne a été ajoutée dans un tampon avec contenu formaté (rien ne peut être changé directement avec ce "hook").

Le "hook" "line" est le seul parmi ces trois "hooks" qui peut fonctionner sur un tampon avec contenu libre.

Prototype :

struct t_hook *weechat_hook_line (const char *buffer_type,
                                  const char *buffer_name,
                                  const char *tags,
                                  struct t_hashtable *(*callback)(const void *pointer,
                                                                  void *data,
                                                                  struct t_hashtable *line),
                                  const void *callback_pointer,
                                  void *callback_data);

Paramètres :

buffer_type : intercepter les lignes affichées sur ce type de tampon (si NULL ou chaîne vide, formatted est utilisé par défaut) (WeeChat ≥ 3.7 : une priorité est autorisée avant le type de tampon, voir la note sur la priorité) :
- formatted : intercepter les lignes sur un tampon avec contenu formaté seulement (par défaut)
- free : intercepter les lignes sur un tampon avec contenu libre seulement
- * : intercepter les lignes sur tous les types de tampons
buffer_name : liste de masques de tampons séparés par des virgules (voir buffer_match_list); NULL, chaîne vide ou "*" correspondent à n’importe quel tampon
tags : intercepter seulement les messages avec ces étiquettes (optionnel) : liste d’étiquettes (séparées par des virgules) qui doivent être dans le message ("ou" logique); il est possible de combiner plusieurs étiquettes sous forme d’un "et" logique avec le séparateur +; le caractère joker * est autorisé dans les étiquettes
callback : fonction appelée lorsqu’une ligne est ajoutée dans un tampon, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_hashtable *line : table de hachage avec les informations sur la ligne, les clés et valeurs sont des chaînes (voir le tableau ci-dessous)
- valeur de retour : table de hachage avec les nouvelles valeurs (voir le tableau ci-dessous)
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Les données de la ligne envoyées à la fonction de rappel sont dans une table de hachage, avec les valeurs suivantes (les clés et valeurs sont des chaînes) :

Clé Valeur (tampon formaté) Valeur (tampon libre) Exemples

buffer

Pointeur vers le tampon.

0x1234abcd

buffer_name

Nom du tampon.

core.weechat
irc.server.libera
irc.libera.#weechat

buffer_type

"formatted"

"free"

formatted
free

N/A ("-1").

Numéro de ligne (≥ "0").

-1
8

date

Date de la ligne (horodatage).

N/A ("0").

1533792000

date_usec

Microsecondes de la date de la ligne (entre 0 et 999999).

N/A ("0").

123456

date_printed

Date d’affichage de la ligne (horodatage).

N/A ("0").

1533792012

date_usec_printed

Microsecondes de la date d’affichage de la ligne (entre 0 et 999999).

N/A ("0").

654321

str_time

Date pour l’affichage (elle peut contenir des codes couleur).

N/A (chaîne vide).

09:07:20

tags_count

Nombre d’étiquettes dans la ligne (≥ "0").

N/A ("0").

2

hook_print

Mis à jour dans la 0.4.3, 1.0, 1.5, 4.2.0.

Intercepter un message affiché. Il est appelée quand une ligne a été ajoutée dans un tampon avec contenu formaté.

Pour plus d’informations sur les "hooks" appelés lorsqu’une ligne est affichée, voir hook_line.

Prototype :

struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(const void *pointer,
                                                   void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int date_usec,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   const void *callback_pointer,
                                   void *callback_data);

Paramètres :

buffer : pointeur vers le tampon, si NULL, les messages de tous les tampons sont interceptés
tags : intercepter seulement les messages avec ces étiquettes (optionnel) :
- avec WeeChat ≥ 0.4.3 : liste d’étiquettes (séparées par des virgules) qui doivent être dans le message ("ou" logique); il est possible de combiner plusieurs étiquettes sous forme d’un "et" logique avec le séparateur +; le caractère joker * est autorisé dans les étiquettes
- avec WeeChat ≤ 0.4.2 : liste d’étiquettes (séparées par des virgules) qui doivent toutes être dans le message ("et" logique)
message : seulement les messages contenant cette chaîne seront interceptés (optionnel, insensible à la casse)
strip_colors : si 1, les couleurs seront supprimées du message affiché, avant d’appeler la fonction de rappel
callback : fonction appelée lorsqu’un message est affiché, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : pointeur vers le tampon
- time_t date : date
- int date_usec : microsecondes de la date
- int tags_count : nombre d’étiquettes de la ligne
- const char **tags : tableau avec les étiquettes de la ligne
- int displayed : 1 si la ligne est affichée, 0 si elle est filtrée (cachée)
- int highlight : 1 si la ligne contient un highlight, sinon 0
- const char *prefix : préfixe
- const char *message : message
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Dans les scripts, avec WeeChat ≥ 1.0, les paramètres de la fonction de rappel displayed et highlight sont des entiers (avec WeeChat ≤ 0.4.3, ils étaient des chaînes).
Pour être compatible avec toutes les versions, il est recommandé de convertir le paramètre en entier avant de le tester, par exemple en Python : if int(highlight):.

Exemple en C :

int
my_print_cb (const void *pointer, void *data, struct t_gui_buffer *buffer,
             time_t date, int date_usec, int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* intercepter tous les messages, de tous les tampons, sans couleur */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_print(buffer: str, tags: str, message: str, strip_colors: int, callback: str, callback_data: str) -> str: ...

# exemple
def my_print_cb(data: str, buffer: str, date: str, tags: str, displayed: int, highlight: int, prefix: str, message: str) -> int:
    if highlight:
        # ...
    return weechat.WEECHAT_RC_OK

# intercepter tous les messages, de tous les tampons, sans couleur
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")

hook_signal

Mis à jour dans la 1.5, 3.6.

S’accrocher à un signal.

Prototype :

struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    const void *callback_pointer,
                                    void *callback_data);

Paramètres :

signal : signal à intercepter, le caractère joker * est autorisé, plusieurs signaux peuvent être séparés par des point-virgules (une priorité est autorisée avant le ou les signaux, voir la note sur la priorité) (voir le tableau ci-dessous)
callback : fonction appelée quand le signal est reçu, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *signal : signal reçu
- const char *type_data : type de donnée reçu avec le signal :
  - WEECHAT_HOOK_SIGNAL_STRING : chaîne de caractères
  - WEECHAT_HOOK_SIGNAL_INT : nombre entier
  - WEECHAT_HOOK_SIGNAL_POINTER : pointeur
- void *signal_data : données envoyées avec le signal
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT (arrêter l’envoi du signal immédiatement) (WeeChat ≥ 0.4.0)
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Liste des signaux envoyés par WeeChat et les extensions :

Extension Signal WeeChat mini Paramètres Description

guile

guile_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script scheme chargé.

guile

guile_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script scheme déchargé.

guile

guile_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) scheme installé(s).

guile

guile_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) scheme supprimé(s).

irc

xxx,irc_in_yyy ⁽¹⁾

Chaîne : message.

Message IRC du serveur (avant utilisation par l’extension irc, signal envoyé uniquement si le message n’est pas ignoré).
Depuis la version 2.2, le message IRC entier est envoyé, en incluant les étiquettes.
Si le code retour d’une fonction de rappel est WEECHAT_RC_OK_EAT, alors le message IRC est immédiatement détruit et non traité (WeeChat ≥ 3.3).

irc

xxx,irc_in2_yyy ⁽¹⁾

Chaîne : message.

Message IRC du serveur (après utilisation par l’extension irc, signal envoyé uniquement si le message n’est pas ignoré).
Depuis la version 2.2, le message IRC entier est envoyé, en incluant les étiquettes.

irc

xxx,irc_raw_in_yyy ⁽¹⁾

0.3.2

Chaîne : message.

Message IRC du serveur (avant utilisation par l’extension irc, signal envoyé même si le message est ignoré).
Depuis la version 2.2, le message IRC entier est envoyé, en incluant les étiquettes.
Si le code retour d’une fonction de rappel est WEECHAT_RC_OK_EAT, alors le message IRC est immédiatement détruit et non traité (WeeChat ≥ 3.3).

irc

xxx,irc_raw_in2_yyy ⁽¹⁾

0.3.2

Chaîne : message.

Message IRC du serveur (après utilisation par l’extension irc, signal envoyé même si le message est ignoré).
Depuis la version 2.2, le message IRC entier est envoyé, en incluant les étiquettes.

irc

xxx,irc_out1_yyy ⁽¹⁾

0.3.7

Chaîne : message.

Message IRC envoyé au serveur avant découpage automatique (pour tenir dans les 512 octets par défaut).
Attention : la chaîne peut contenir des données invalides UTF-8. Le signal "xxx,irc_out1_yyy" est recommandé à la place de celui-ci.

irc

xxx,irc_out_yyy ⁽¹⁾

Chaîne : message.

Message IRC envoyé au serveur après découpage automatique (pour tenir dans les 512 octets par défaut).
Attention : la chaîne peut contenir des données invalides UTF-8. Le signal "xxx,irc_out1_yyy" est recommandé à la place de celui-ci.

irc

xxx,irc_outtags_yyy ⁽¹⁾

0.3.4

Chaîne : étiquettes + ";" + message.

Étiquettes + message IRC envoyé au serveur.

irc

irc_ctcp

Chaîne : message.

CTCP reçu.

irc

irc_dcc

Chaîne : message.

Nouveau DCC.

irc

irc_pv

Chaîne : message.

Message privé reçu.

irc

irc_channel_opened

Pointeur : tampon.

Canal ouvert.

irc

irc_pv_opened

Pointeur : tampon.

Discussion privée ouverte.

irc

irc_server_opened

0.3.7

Pointeur : tampon.

Tampon du serveur ouvert.

irc

irc_server_connecting

Chaîne : nom du serveur.

Connexion en cours au serveur.

irc

irc_server_connected

Chaîne : nom du serveur.

Connecté au serveur.

irc

irc_server_disconnected

Chaîne : nom du serveur.

Déconnecté du serveur.

irc

irc_server_lag_changed

1.8

Chaîne : nom du serveur.

Le lag a changé sur le serveur.

irc

irc_ignore_removing

Pointeur : ignore.

Suppression d’un ignore en cours.

irc

irc_ignore_removed

Ignore supprimé.

irc

irc_notify_join

0.3.8

Chaîne : nom du serveur + "," + pseudo.

Un pseudo dans la liste de notifications a rejoint le serveur.

irc

irc_notify_quit

0.3.8

Chaîne : nom du serveur + "," + pseudo.

Un pseudo dans la liste de notifications a quitté le serveur.

irc

irc_notify_away

0.3.8

Chaîne : nom du serveur + "," + pseudo + "," + message d’absence.

Un pseudo dans la liste de notifications est maintenant absent sur le serveur.

irc

irc_notify_still_away

0.3.8

Chaîne : nom du serveur + "," + pseudo + "," + message d’absence.

Un pseudo dans la liste de notifications est toujours absent sur le serveur (le message d’absence a changé).

irc

irc_notify_back

0.3.8

Chaîne : nom du serveur + "," + pseudo.

Un pseudo dans la liste de notifications est de retour (statut d’absence supprimé).

javascript

javascript_script_loaded

1.2

Chaîne : chemin vers le script.

Script JavaScript chargé.

javascript

javascript_script_unloaded

1.2

Chaîne : chemin vers le script.

Script JavaScript déchargé.

javascript

javascript_script_installed

1.2

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) JavaScript installé(s).

javascript

javascript_script_removed

1.2

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) JavaScript supprimé(s).

logger

logger_start

Pointeur : tampon.

Démarrage de l’enregistrement sur disque pour le tampon.

logger

logger_stop

Pointeur : tampon.

Fin de l’enregistrement sur disque pour le tampon.

logger

logger_backlog

Pointeur : tampon.

Affichage du backlog pour le tampon.

lua

lua_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script lua chargé.

lua

lua_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script lua déchargé.

lua

lua_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) lua installé(s).

lua

lua_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) lua supprimé(s).

perl

perl_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script perl chargé.

perl

perl_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script perl déchargé.

perl

perl_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) perl installé(s).

perl

perl_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) perl supprimé(s).

php

php_script_loaded

2.0

Chaîne : chemin vers le script.

Script PHP chargé.

php

php_script_unloaded

2.0

Chaîne : chemin vers le script.

Script PHP déchargé.

php

php_script_installed

2.0

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) PHP installé(s).

php

php_script_removed

2.0

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) PHP supprimé(s).

python

python_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script python chargé.

python

python_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script python déchargé.

python

python_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) python installé(s).

python

python_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) python supprimé(s).

relay

relay_client_connecting

1.0

Pointeur : client relay.

Un client relay est en train de se connecter.

relay

relay_client_waiting_auth

1.0

Pointeur : client relay.

Attente de l’authentification d’un client relay.

relay

relay_client_auth_ok

1.0

Pointeur : client relay.

Authentification réussie d’un client relay.

relay

relay_client_connected

1.0

Pointeur : client relay.

Un client relay est connecté.

relay

relay_client_auth_failed

1.0

Pointeur : client relay.

L’authentification d’un client relay a échoué.

relay

relay_client_disconnected

1.0

Pointeur : client relay.

Un client relay est déconnecté.

ruby

ruby_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script ruby chargé.

ruby

ruby_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script ruby déchargé.

ruby

ruby_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) ruby installé(s).

ruby

ruby_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) ruby supprimé(s).

spell

spell_suggest

2.4

Pointeur : tampon.

Nouvelles suggestions pour un mot mal orthographié.

tcl

tcl_script_loaded

0.3.9

Chaîne : chemin vers le script.

Script tcl chargé.

tcl

tcl_script_unloaded

0.3.9

Chaîne : chemin vers le script.

Script tcl déchargé.

tcl

tcl_script_installed

0.3.9

Chaîne : liste de chemins vers scripts installés (séparés par des virgules).

Script(s) tcl installé(s).

tcl

tcl_script_removed

0.3.9

Chaîne : liste de scripts supprimés (séparés par des virgules).

Script(s) tcl supprimé(s).

typing

typing_self_typing

3.3

Pointeur : tampon.

L’utilisateur est en train de taper un message (envoyé par l’extension typing, utilisé par l’extension irc).

typing

typing_self_paused

3.3

Pointeur : tampon.

L’utilisateur a fait une pause pendant la saisie du message (envoyé par l’extension typing, utilisé par l’extension irc).

typing

typing_self_cleared

3.3

Pointeur : tampon.

L’utilisateur a effacé la ligne de commande sans envoyer le message (envoyé par l’extension typing, utilisé par l’extension irc).

typing

typing_self_sent

3.3

Pointeur : tampon.

Message (pas une commande) envoyé au tampon (envoyé par l’extension typing, utilisé par l’extension irc).

typing

typing_set_nick

3.3

Chaîne : pointeur tampon + ";" + état (un parmi ceux-ci : "off", "typing", "paused", "cleared") + ";" + pseudo.

Définir l’état de la saisie du pseudo sur le tampon (envoyé par l’extension irc, géré par l’extension typing).

typing

typing_reset_buffer

3.3

Pointeur : tampon.

Supprimer l’état de saisir pour tous les pseudos d’un tampon (envoyé par l’extension irc, géré par l’extension typing).

weechat

buffer_opened

Pointeur : tampon.

Tampon ouvert.

weechat

buffer_closing

Pointeur : tampon.

Fermeture du tampon en cours.

weechat

buffer_closed

Pointeur : tampon.

Tampon fermé.

weechat

buffer_cleared

Pointeur : tampon.

Tampon vidé.

weechat

buffer_filters_enabled

2.0

Pointeur : tampon.

Filtres activés dans le tampon.

weechat

buffer_filters_disabled

2.0

Pointeur : tampon.

Filtres désactivés dans le tampon.

weechat

buffer_hidden

Pointeur : tampon.

Tampon masqué.

weechat

buffer_unhidden

Pointeur : tampon.

Tampon démasqué.

weechat

buffer_line_added

0.3.7

Pointeur : ligne.

Ligne ajoutée dans un tampon.

weechat

buffer_lines_hidden

Pointeur : tampon.

Lignes cachées dans le tampon.

weechat

buffer_localvar_added

Pointeur : tampon.

Variable locale ajoutée.

weechat

buffer_localvar_changed

Pointeur : tampon.

Variable locale modifiée.

weechat

buffer_localvar_removed

Pointeur : tampon.

Variable locale supprimée.

weechat

buffer_merged

Pointeur : tampon.

Tampon mélangé.

weechat

buffer_unmerged

Pointeur : tampon.

Le tampon n’est plus mélangé.

weechat

buffer_moved

Pointeur : tampon.

Tampon déplacé.

weechat

buffer_renamed

Pointeur : tampon.

Tampon renommé.

weechat

buffer_switch

Pointeur : tampon.

Basculement vers un autre tampon.

weechat

buffer_title_changed

Pointeur : tampon.

Titre du tampon changé.

weechat

buffer_type_changed

Pointeur : tampon.

Type de tampon changé.

weechat

buffer_zoomed

0.4.3

Pointeur : tampon.

Zoom sur un tampon mélangé.

weechat

buffer_unzoomed

0.4.3

Pointeur : tampon.

Fin du zoom sur un tampon mélangé.

weechat

buffer_user_input_xxx ⁽²⁾

3.8

Chaîne : texte envoyé au tampon.

Texte envoyé au tampon utilisateur (envoyé seulement sur les tampons créés avec /buffer add).
Si le code retour d’une fonction de rappel est WEECHAT_RC_OK_EAT, alors la chaîne "q" ne peut plus être utilisée pour fermer le tampon.

weechat

buffer_user_closing_xxx ⁽²⁾

3.8

Fermeture du tampon utilisateur en cours (envoyé seulement sur les tampons créés avec /buffer add).

weechat

cursor_start

3.2

Début du mode curseur.

weechat

cursor_end

3.2

Fin du mode curseur.

weechat

day_changed

0.3.2

Chaîne : nouvelle date, format : "2010-01-31".

Le jour de la date système a changé.

weechat

debug_dump

Chaîne : nom d’extension.

Requête de "dump".

weechat

debug_libs

Affichage des bibliothèques externes utilisées.

weechat

filter_added

Pointeur : filtre.

Filtre ajouté.

weechat

filter_removing

Pointeur : filtre.

Suppression de filtre en cours.

weechat

filter_removed

Filtre supprimé.

weechat

filters_enabled

Filtres activés.

weechat

filters_disabled

Filtres désactivés.

weechat

hotlist_changed

Pointeur : tampon (peut être NULL).

La hotlist a changé.

weechat

input_paste_pending

Coller de lignes en cours.

weechat

input_search

Pointeur : tampon.

Recherche de texte dans le tampon.

weechat

input_text_changed

Pointeur : tampon.

Texte modifié dans la barre "input".

weechat

input_text_cursor_moved

Pointeur : tampon.

Curseur déplacé dans la barre "input".

weechat

key_bind

Chaîne : touche.

Touche ajoutée.

weechat

key_unbind

Chaîne : touche.

Touche supprimée.

weechat

key_pressed

Chaîne : touche appuyée.

Touche appuyée.

weechat

key_combo_default

1.0

Chaîne : combinaison de touches.

Combinaison de touches dans le contexte default.

weechat

key_combo_search

1.0

Chaîne : combinaison de touches.

Combinaison de touches dans le contexte search.

weechat

key_combo_cursor

1.0

Chaîne : combinaison de touches.

Combinaison de touches dans le contexte cursor.

weechat

mouse_enabled

1.1

Souris activée.

weechat

mouse_disabled

1.1

Souris désactivée.

weechat

nicklist_group_added

0.3.2

Chaîne : pointeur tampon + "," + nom du groupe.

Groupe ajouté dans la liste des pseudos.

weechat

nicklist_group_changed

0.3.4

Chaîne : pointeur tampon + "," + nom du groupe.

Groupe modifié dans la liste des pseudos.

weechat

nicklist_group_removing

0.4.1

Chaîne : pointeur tampon + "," + nom du groupe.

Suppression du groupe de la liste des pseudos.

weechat

nicklist_group_removed

0.3.2

Chaîne : pointeur tampon + "," + nom du groupe.

Groupe supprimé de la liste des pseudos.

weechat

nicklist_nick_added

0.3.2

Chaîne : pointeur tampon + "," + pseudo.

Pseudo ajouté dans la liste des pseudos.

weechat

nicklist_nick_changed

0.3.4

Chaîne : pointeur tampon + "," + pseudo.

Pseudo modifié dans la liste des pseudos.

weechat

nicklist_nick_removing

0.4.1

Chaîne : pointeur tampon + "," + pseudo.

Suppression du pseudo de la liste des pseudos.

weechat

nicklist_nick_removed

0.3.2

Chaîne : pointeur tampon + "," + pseudo.

Pseudo supprimé de la liste des pseudos.

weechat

partial_completion

Une complétion partielle a été faite.

weechat

plugin_loaded

0.3.9

Chaîne : chemin vers l’extension chargée.

Extension chargée.

weechat

plugin_unloaded

0.3.9

Chaîne : nom de l’extension déchargée (exemple : "irc").

Extension déchargée.

weechat

quit

Chaîne : paramètres pour le /quit.

La commande /quit a été exécutée par l’utilisateur.

weechat

signal_sighup

1.3

Signal SIGHUP reçu.

weechat

signal_sigquit

1.2

Signal SIGQUIT reçu (requête pour quitter avec une copie de la mémoire).

weechat

signal_sigterm

1.2

Signal SIGTERM reçu (arrêt propre du processus WeeChat).

weechat

signal_sigwinch

0.4.3

Signal SIGWINCH reçu (le terminal a été redimensionné).

weechat

upgrade

Chaîne : "quit" si le paramètre "-quit" a été donné pour /upgrade, "-save" si le paramètre "-save" a été donné pour /upgrade, sinon NULL.

La commande /upgrade a été exécutée par l’utilisateur.

weechat

upgrade_ended

0.3.4

Fin du processus de mise à jour (commande /upgrade).

weechat

weechat_highlight

Chaîne : message avec le préfixe.

Un highlight est survenu.

weechat

weechat_pv

Chaîne : message avec le préfixe.

Un message privé a été affiché.

weechat

window_closing

0.3.6

Pointeur : fenêtre.

Fermeture de la fenêtre en cours.

weechat

window_closed

0.3.6

Pointeur : fenêtre.

Fenêtre fermée.

weechat

window_opened

0.4.1

Pointeur : fenêtre.

Fenêtre ouverte.

weechat

window_scrolled

Pointeur : fenêtre.

Défilement dans la fenêtre.

weechat

window_switch

0.3.7

Pointeur : fenêtre.

Basculement vers une autre fenêtre.

weechat

window_zoom

Pointeur : fenêtre courante.

Zoom en cours sur la fenêtre.

weechat

window_zoomed

Pointeur : fenêtre courante.

Zoom effectué sur la fenêtre.

weechat

window_unzoom

Pointeur : fenêtre courante.

Fin du zoom en cours sur la fenêtre.

weechat

window_unzoomed

Pointeur : fenêtre courante.

Fin du zoom effectué sur la fenêtre.

xfer

xfer_add

Pointeur : infolist avec l’info xfer.

Nouveau xfer.

xfer

xfer_send_ready

Pointeur : infolist avec l’info xfer.

Xfer prêt.

xfer

xfer_accept_resume

Pointeur : infolist avec l’info xfer.

Accepter la reprise xfer.

xfer

xfer_send_accept_resume

Pointeur : infolist avec l’info xfer.

Reprise xfer acceptée.

xfer

xfer_start_resume

Pointeur : infolist avec l’info xfer.

Redémarrage.

xfer

xfer_resume_ready

Pointeur : infolist avec l’info xfer.

Redémarrage prêt.

xfer

xfer_ended

0.3.2

Pointeur : infolist avec l’info xfer.

Le xfer s’est terminé.

⁽¹⁾ xxx est le nom du serveur IRC, yyy est le nom d’une commande IRC.
⁽²⁾ xxx est le nom du tampon.

Exemple en C :

int
my_signal_cb (const void *pointer, void *data, const char *signal,
              const char *type_data, void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* intercepter les signaux "quit" et "upgrade" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit;upgrade",
                                                     &my_signal_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_signal(signal: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_signal_cb(data: str, signal: str, signal_data: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# intercepter les signaux "quit" et "upgrade"
hook = weechat.hook_signal("quit;upgrade", "my_signal_cb", "")

hook_signal_send

Mis à jour dans la 1.0.

Envoyer un signal.

Prototype :

int weechat_hook_signal_send (const char *signal, const char *type_data,
                              void *signal_data);

Paramètres :

signal : signal à envoyer
type_data : type de données à envoyer avec le signal (voir hook_signal)
signal_data : données envoyées avec le signal

Valeur de retour (WeeChat ≥ 1.0) :

code retour de la dernière fonction de rappel exécutée (WEECHAT_RC_OK si aucune fonction de rappel n’a été exécuté) :
- WEECHAT_RC_OK
- WEECHAT_RC_OK_EAT
- WEECHAT_RC_ERROR

Exemple en C :

int rc = weechat_hook_signal_send ("mon_signal", WEECHAT_HOOK_SIGNAL_STRING, ma_chaine);

Script (Python) :

# prototype
def hook_signal_send(signal: str, type_data: str, signal_data: str) -> int: ...

# exemple
rc = weechat.hook_signal_send("mon_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, ma_chaine)

Signal logger_backlog

Le signal "logger_backlog" peut être envoyé pour afficher l’historique de discussion dans le tampon (par exemple si vous ouvrez votre propre tampon dans votre extension/script).

Le paramètre est un pointeur vers le tampon.

Exemple en C :

weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);

Script (Python) :

weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)

Signaux xxx_script_install

Cinq signaux peuvent être envoyés pour installer un script, selon le langage :

perl_script_install
python_script_install
ruby_script_install
lua_script_install
tcl_script_install
guile_script_install
javascript_script_install
php_script_install

La fonction de rappel effectuera les actions suivantes lorsqu’elle recevra le signal :

Déchargement et suppression du script installé.
Déplacement du nouveau script vers le répertoire ~/.local/share/weechat/xxx/ (où xxx est le langage).
Création d’un lien vers le nouveau script dans le répertoire ~/.local/share/weechat/xxx/autoload/ (seulement si le script était déjà automatiquement chargé ou si l’option script.scripts.autoload est activée pour un nouveau script).
Chargement du nouveau script (si le script était chargé).

Ces signaux sont utilisés par l’extension script pour installer des scripts.

Le paramètre est une chaîne avec le chemin vers le script à installer.

Exemple en C :

weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py");

Script (Python) :

weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py")

Signaux xxx_script_remove

Cinq signaux peuvent être envoyés pour supprimer une liste de scripts, selon le langage :

perl_script_remove
python_script_remove
ruby_script_remove
lua_script_remove
tcl_script_remove
guile_script_remove
javascript_script_remove
php_script_remove

Pour chaque script dans la liste, la fonction de rappel déchargera et supprimera le script.

Ces signaux sont utilisés par l’extension script pour supprimer des scripts.

Le paramètre est une chaîne avec une liste de scripts à supprimer (séparés par des virgules, nom du script sans le chemin, par exemple script.py).

Exemple en C :

/* décharge et supprime les scripts test.py et script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");

Script (Python) :

# décharge et supprime les scripts test.py et script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")

Signal irc_input_send

WeeChat ≥ 0.3.4, mis à jour dans la 1.5.

Le signal "irc_input_send" peut être envoyé pour simuler une entrée de texte dans un tampon irc (serveur, canal ou privé).

Le paramètre est une chaîne avec le format suivant :

nom interne du serveur (requis)
point-virgule
nom de canal (optionnel)
point-virgule
liste d’options séparées par des virgules (optionnel) :
- priority_high : file d’attente avec haute priorité (comme les messages utilisateur) ; c’est la priorité par défaut
- priority_low : file d’attente avec basse priorité (comme les messages envoyés automatiquement par WeeChat)
- user_message : forcer un message utilisateur (ne pas exécuter de commande)
point-virgule
liste d’étiquettes (séparées par des virgules) utilisées lors de l’envoi du message (optionnel)
point-virgule
texte ou commande (requis)

Exemples en C :

/* dis "Bonjour !" sur le serveur libera, canal #weechat */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "libera;#weechat;priority_high,user_message;;Bonjour !");

/* envoie la commande "/whois FlashCode" sur le canal libera, en basse priorité */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "libera;;priority_low;;/whois FlashCode");

Script (Python) :

# dis "Bonjour !" sur le serveur libera, canal #weechat
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;#weechat;priority_high,user_message;;Bonjour !")

# envoie la commande "/whois FlashCode" sur le canal libera, en basse priorité
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;;priority_low;;/whois FlashCode")

hook_hsignal

WeeChat ≥ 0.3.4, mis à jour dans la 1.5, 3.6.

S’accrocher à un hsignal (signal avec une table de hachage).

Prototype :

struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     const void *callback_pointer,
                                     void *callback_data);

Paramètres :

signal : signal à intercepter, le caractère joker * est autorisé, plusieurs signaux peuvent être séparés par des point-virgules (une priorité est autorisée avant le ou les signaux, voir la note sur la priorité) (voir le tableau ci-dessous)
callback : fonction appelée quand le signal est reçu, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *signal : signal reçu
- struct t_hashtable *hashtable : table de hachage
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT (arrêter l’envoi du signal immédiatement) (WeeChat ≥ 0.4.0)
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Liste des hsignaux envoyés par WeeChat et les extensions :

Extension

Signal

WeeChat mini

Paramètres

Description

irc

irc_redirection_xxx_yyy ⁽¹⁾

0.3.4

Voir hsignal_irc_redirect_command

Sortie de la redirection.

weechat

nicklist_group_added

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : groupe parent
group (struct t_gui_nick_group *) : groupe

Groupe ajouté dans la liste de pseudos.

weechat

nicklist_nick_added

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : groupe parent
nick (struct t_gui_nick *) : pseudo

Pseudo ajouté dans la liste de pseudos.

weechat

nicklist_group_removing

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : groupe parent
group (struct t_gui_nick_group *) : groupe

Suppression d’un groupe de la liste de pseudos.

weechat

nicklist_nick_removing

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : groupe parent
nick (struct t_gui_nick *) : pseudo

Suppression d’un pseudo de la liste de pseudos.

weechat

nicklist_group_changed

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : groupe parent
group (struct t_gui_nick_group *) : groupe

Groupe changé dans la liste de pseudos.

weechat

nicklist_nick_changed

0.4.1

buffer (struct t_gui_buffer *) : tampon
parent_group (struct t_gui_nick_group *) : parent
nick (struct t_gui_nick *) : pseudo

Pseudo changé dans la liste de pseudos.

⁽¹⁾ xxx est l’argument "signal" utilisé dans la redirection, yyy est le modèle de redirection ("pattern").

Exemple en C :

int
my_hsignal_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_hsignal(signal: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_hsignal_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")

hook_hsignal_send

WeeChat ≥ 0.3.4, mis à jour dans la 1.0.

Envoyer un hsignal (signal avec table de hachage).

Prototype :

int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);

Paramètres :

signal : signal à envoyer
hashtable : table de hachage

Valeur de retour (WeeChat ≥ 1.0) :

code retour de la dernière fonction de rappel exécutée (WEECHAT_RC_OK si aucune fonction de rappel n’a été exécutée) :
- WEECHAT_RC_OK
- WEECHAT_RC_OK_EAT
- WEECHAT_RC_ERROR

Exemple en C :

int rc;
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "clé", "valeur");
    rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}

Script (Python) :

# prototype
def hook_hsignal_send(signal: str, hashtable: Dict[str, str]) -> int: ...

# exemple
rc = weechat.hook_hsignal_send("my_hsignal", {"clé": "valeur"})

Hsignal irc_redirect_command

WeeChat ≥ 0.3.4.

Le hsignal "irc_redirect_command" peut être envoyé pour rediriger la sortie d’une commande irc vers une fonction de rappel.

Le paramètre est une table de hachage avec les entrées suivantes (les clés et valeurs sont des chaînes) :

server : nom interne du serveur (requis)
pattern : modèle de redirection à utiliser (requis), soit un par défaut (défini par l’extension irc), ou un modèle utilisateur (voir Hsignal irc_redirect_pattern), les modèles par défaut sont :
- ison
- list
- mode_channel
- mode_channel_ban ("mode #channel b")
- mode_channel_ban_exception ("mode #channel e")
- mode_channel_invite ("mode #channel I")
- mode_user
- monitor
- names
- ping
- time
- topic
- userhost
- who
- whois
- whowas
signal : nom du signal (requis)
count : nombre de fois que la redirection sera exécutée (optionnel, 1 par défaut)
string : chaîne qui doit être dans les messages irc reçus (optionnel, mais recommandé, si une chaîne peut être utilisée pour identifier les messages)
timeout : temps d’attente maximum pour la redirection, en secondes (optionnel, 60 par défaut)
cmd_filter : liste de commandes irc (séparées par des virgules) à filtrer (seules ces commandes seront transmises à la fonction de rappel, les autres seront ignorées) (optionnel)

Immédiatement après l’envoi de ce hsignal, vous devez envoyer la commande au serveur irc, et la redirection sera utilisée pour cette commande.

Lorsque la réponse complète à votre commande a été reçue, un hsignal est envoyé. Ce hsignal a le nom irc_redirection_xxx_yyy où xxx est le signal et yyy le pattern utilisé.

La table de hachage envoyée dans le hsignal a le contenu suivant (les clés et valeurs sont des chaînes) :

output : sortie de la commande (les messages sont séparés par "\n")
output_size : nombre d’octets dans output (sous forme de chaîne)
error : chaîne d’erreur (si une erreur s’est produite) :
- timeout : redirection stoppée après le délai maximum dépassé
server : nom interne du serveur
pattern : modèle de redirection
signal : nom du signal
command : commande redirigée

Exemple en C :

int
test_whois_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "erreur = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "sortie = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "libera");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "libera;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}

Script (Python) :

def test_whois_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    weechat.prnt("", "erreur = %s" % hashtable["error"])
    weechat.prnt("", "sortie = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          {"server": "libera", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;;2;;/whois FlashCode")

Hsignal irc_redirect_pattern

WeeChat ≥ 0.3.4.

Le hsignal "irc_redirect_pattern" peut être envoyé pour créer un modèle de redirection irc (voir Hsignal irc_redirect_command).

Le paramètre est une table de hachage avec les entrées suivantes (les clés et valeurs sont des chaînes) :

pattern : nom du modèle (requis)
timeout : temps d’attente maximum pour le modèle, en secondes (optionnel, 60 par défaut)
cmd_start : liste de commandes (séparées par des virgules) démarrant la redirection (optionnel)
cmd_stop : liste de commandes (séparées par des virgules) stoppant la redirection (requis)
cmd_extra : liste de commandes (séparées par des virgules) pouvant être reçues après les commandes de stop (optionnel)

Pour chaque commande dans cmd_start, cmd_stop et cmd_extra, il est possible de donner un entier avec la position de la chaîne "string" qui doit être trouvée dans le message reçu, par exemple :

352:1,354,401:1

Pour les commandes 352 et 401, la chaîne "string" doit être trouvée dans le message reçu, comme premier paramètre.

Le modèle est détruit dès qu’il est utilisé dans une redirection. Si vous avez besoin du modèle pour plusieurs redirections, vous devez créer un modèle pour chaque redirection.

Exemple en C :

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * rediriger maintenant la commande irc whois avec le hsignal irc_redirect_command,
     * en utilisant le modèle "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}

Script (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"})
# rediriger maintenant la commande irc whois avec le hsignal irc_redirect_command,
# en utilisant le modèle "my_whois"
# ...

hook_config

Mis à jour dans la 1.5.

S’accrocher à une option de configuration.

Prototype :

struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    const char *option,
                                                    const char *value),
                                    const void *callback_pointer,
                                    void *callback_data);

Paramètres :

option : option, le format est le nom complet, celui utilisé avec la commande /set (par exemple : weechat.look.item_time_format), le caractère joker * est autorisé (une priorité est autorisée avant l’option, voir la note sur la priorité)
callback : fonction appelée lorsque l’option de configuration est modifiée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *option : nom de l’option
- const char *value : nouvelle valeur pour l’option
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelé par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

int
my_config_cb (const void *pointer, void *data, const char *option,
              const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* intercepter les changements de l'option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_config(option: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_config_cb(data: str, option: str, value: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# intercepter les changements de l'option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")

hook_modifier

Mis à jour dans la 1.5.

Accrocher un modificateur.

Prototype :

struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(const void *pointer,
                                                        void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      const void *callback_pointer,
                                      void *callback_data);

Paramètres :

modifier : nom du modificateur (une priorité est autorisée avant le modificateur, voir la note sur la priorité) (voir le tableau ci-dessous)
callback : fonction appelée lorsque le modificateur est utilisé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *modifier : nom du modificateur
- const char *modifier_data : données pour le modificateur
- const char *string : chaîne à modifier
- valeur de retour : nouvelle chaîne
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Liste des modificateurs utilisés par WeeChat et les extensions :

Modificateur

WeeChat mini

Données du modificateur

Chaîne

Sortie

irc_batch

4.0.0

Nom de serveur + "," + type de batch + "," + paramètres du batch

Contenu de plusieurs messages, séparés par un caractère de retour chariot ("\n").

Nouveau contenu des messages (le nombre peut être différent), une chaîne vide annule tous les messages du batch.

irc_cap_sync_req

4.0.0

Nom de serveur + "," + capacités supportées par le serveur (séparées par des espaces)

Capacités à demander (séparées par des espaces).

Nouveau contenu des capacités à demander (séparées par des espaces).

irc_in_xxx ⁽¹⁾

Nom de serveur

Contenu du message reçu du serveur IRC (avant décodage du jeu de caractères).
Attention : la chaîne peut contenir des données invalides UTF-8 ; à utiliser seulement pour les opérations de bas niveau sur le message. Le modificateur irc_in2_xxx est recommandé à la place de celui-ci.

Nouveau contenu du message.

irc_in2_xxx ⁽¹⁾

0.3.5

Nom de serveur

Contenu du message reçu du serveur IRC (après décodage du jeu de caractères).

Nouveau contenu du message.

irc_out1_xxx ⁽¹⁾

0.3.7

Nom de serveur

Contenu du message qui va être envoyé au serveur IRC avant découpage automatique (pour tenir dans les 512 octets par défaut).

Nouveau contenu du message.

irc_out_xxx ⁽¹⁾

Nom de serveur

Contenu du message qui va être envoyé au serveur IRC après découpage automatique (pour tenir dans les 512 octets par défaut).

Nouveau contenu du message.

relay_client_irc_in

4.0.0

Chaîne avec un pointeur vers le client relay (par exemple : "0x1234abcd")

Contenu du message reçu du client relay IRC.

Nouveau contenu du message.

relay_client_irc_out1

4.0.0

Chaîne avec un pointeur vers le client relay (par exemple : "0x1234abcd")

Contenu du message qui va être envoyé au client relay IRC avant découpage automatique (pour tenir dans les 512 octets par défaut).

Nouveau contenu du message.

relay_client_irc_out

4.0.0

Chaîne avec un pointeur vers le client relay (par exemple : "0x1234abcd")

Contenu du message qui va être envoyé au client relay IRC après découpage automatique (pour tenir dans les 512 octets par défaut).

Nouveau contenu du message.

bar_condition_yyy ⁽²⁾

Chaîne avec un pointeur vers la fenêtre (par exemple : "0x1234abcd")

Chaîne vide.

"1" pour afficher la barre, "0" pour la cacher.

history_add

0.3.2

Chaîne avec un pointeur vers le tampon (par exemple : "0x1234abcd")

Contenu de la ligne de commande à ajouter à l’historique des commandes (tampon et global).

Chaîne ajoutée à l’historique des commandes.

input_text_content

Chaîne avec un pointeur vers le tampon (par exemple : "0x1234abcd")

Contenu de la ligne de commande.

Nouvelle chaîne pour la ligne de commande.

input_text_display

Chaîne avec un pointeur vers le tampon (par exemple : "0x1234abcd")

Contenu de la ligne de commande, sans le code du curseur dedans.

Nouvelle chaîne, pour affichage seulement (la ligne de commande n’est pas modifiée).

input_text_display_with_cursor

Chaîne avec un pointeur vers le tampon (par exemple : "0x1234abcd")

Contenu de la ligne de commande, avec le code du curseur dedans.

Nouvelle chaîne, pour affichage seulement (la ligne de commande n’est pas modifiée).

input_text_for_buffer

0.3.7

Chaîne avec un pointeur vers le tampon (par exemple : "0x1234abcd")

Contenu de la ligne de commande envoyée au tampon (texte ou commande).

Nouveau contenu de la ligne de commande envoyée au tampon.

weechat_print

pointeur vers le tampon (par exemple : "0x1234abcd") + ";" + étiquettes ⁽³⁾

Message affiché.

Nouveau message affiché.
Pour plus d’informations sur les "hooks" appelés lorsqu’une ligne est affichée, voir hook_line.

⁽¹⁾ xxx est un nom de commande IRC.
⁽²⁾ yyy est le nom de la barre.
⁽³⁾ Avec WeeChat ≤ 2.8, le format était : extension + ";" + nom_tampon + ";" + étiquettes.

Exemple en C :

char *
my_modifier_cb (const void *pointer, void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;

    if (!string)
        return NULL;

    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* ajouter "xxx" à chaque message affiché */
        snprintf (result, length, "%s xxx", string);
    }

    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_modifier(modifier: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_modifier_cb(data: str, modifier: str, modifier_data: str, string: str) -> str:
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")

hook_modifier_exec

Exécuter un ou plusieurs modificateurs.

Prototype :

char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);

Paramètres :

modifier : nom du modificateur
modifier_data : données du modificateur
string : chaîne à modifier

Valeur de retour :

chaîne modifiée, NULL en cas d’erreur

Liste des modificateurs définis par WeeChat et les extensions qui peuvent être utilisés :

Modificateur WeeChat mini Données du modificateur Chaîne Sortie

charset_decode

extension.nom_tampon

Toute chaîne.

Chaîne décodée depuis le jeu de caractères trouvé pour l’extension/tampon vers UTF-8.

charset_encode

extension.nom_tampon

Toute chaîne.

Chaîne encodée depuis UTF-8 vers le jeu de caractères trouvé pour l’extension/tampon.

irc_color_decode

"1" pour garder les couleurs, "0" pour les supprimer

Toute chaîne.

Chaîne avec les couleurs IRC converties en couleurs WeeChat (ou avec les couleurs IRC supprimées).

irc_color_encode

"1" pour garder les couleurs, "0" pour les supprimer

Toute chaîne.

Chaîne avec les couleurs IRC (ou avec les couleurs IRC supprimées).

irc_color_decode_ansi

1.0

"1" pour garder les couleurs, "0" pour les supprimer

Toute chaîne.

Chaîne avec les couleurs ANSI converties en couleurs IRC (ou avec les couleurs ANSI supprimées).

irc_command_auth

0.4.1

Nom du serveur

Commande d’authentification (par exemple : /msg nickserv identify password).

Commande avec le mot de passe caché (par exemple : /msg nickserv identify ********).

irc_message_auth

0.4.1

Nom du serveur

Message affiché après msg envoyé à nickserv.

Message avec le mot de passe caché.

irc_tag_escape_value

3.3

Toute chaîne.

Chaîne avec la valeur de l’étiquette IRC échappée, voir cette page ^↗.

irc_tag_unescape_value

3.3

Toute chaîne.

Chaîne avec la valeur de l’étiquette IRC sans échappements, voir cette page ^↗.

color_decode_ansi

1.0

"1" pour garder les couleurs, "0" pour les supprimer

Toute chaîne.

Chaîne avec les couleurs ANSI converties en couleurs WeeChat (ou avec les couleurs ANSI supprimées).

color_encode_ansi

2.7

Toute chaîne.

Chaîne avec les couleurs WeeChat converties en couleurs ANSI.

eval_path_home

2.7

Facultatif : directory=xxx où xxx peut être : config, data, cache, runtime

Toute chaîne.

Chemin évalué, résultat de la fonction string_eval_path_home.

Exemple en C :

char *new_string = weechat_hook_modifier_exec ("mon_modifier",
                                               mes_donnees, ma_chaine);

Script (Python) :

# prototype
def hook_modifier_exec(modifier: str, modifier_data: str, string: str) -> str: ...

# exemple
weechat.hook_modifier_exec("mon_modifier", mes_donnees, ma_chaine)

hook_info

Mis à jour dans la 1.5, 2.5.

Accrocher une information (la fonction de rappel prend et retourne une chaîne).

Prototype :

struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  char *(*callback)(const void *pointer,
                                                    void *data,
                                                    const char *info_name,
                                                    const char *arguments),
                                  const void *callback_pointer,
                                  void *callback_data);

Paramètres :

info_name : nom de l’information (une priorité est autorisée avant le nom de l’information, voir la note sur la priorité)
description : description
args_description : description des paramètres (optionnel, peut être NULL)
callback : fonction appelée quand l’information est demandée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *info_name : nom de l’information
- const char *arguments : paramètres additionnels, dépendant de l’information
- valeur de retour : valeur de l’information demandée
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Avec WeeChat ≥ 2.5, la fonction de rappel renvoie une chaîne allouée (avec WeeChat ≤ 2.4, il s’agissait d’un pointeur vers une chaîne statique).

Exemple en C :

char *
my_info_cb (const void *pointer, void *data, const char *info_name,
            const char *arguments)
{
    /* ... */
    return strdup ("some_info");
}

/* ajoute l'information "mon_info" */
struct t_hook *my_info_hook = weechat_hook_info ("mon_info",
                                                 "Une information",
                                                 "Info sur les paramètres",
                                                 &my_info_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_info(info_name: str, description: str, args_description: str,
              callback: str, callback_data: str) -> str: ...

# exemple
def my_info_cb(data: str, info_name: str, arguments: str) -> str:
    return "some_info"

hook = weechat.hook_info("mon_info", "Une information", "Info sur les paramètres",
                         "my_info_cb", "")

hook_info_hashtable

WeeChat ≥ 0.3.4, mis à jour dans la 1.5.

Accrocher une information (la fonction de rappel prend et retourne une table de hachage).

Prototype :

struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(const void *pointer,
                                                                            void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            const void *callback_pointer,
                                            void *callback_data);

Paramètres :

info_name : nom de l’information (une priorité est autorisée avant le nom de l’information, voir la note sur la priorité)
description : description
args_description : description de la table de hachage attendue (optionnel, peut être NULL)
output_description : description de la table de hachage retournée par la fonction de rappel (optionnel, peut être NULL)
callback : fonction appelée quand l’information est demandée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *info_name : nom de l’information
- struct t_hashtable *hashtable : table de hachage, dépendant de l’information
- valeur de retour : table de hachage demandée
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

struct t_hashtable *
my_info_hashtable_cb (const void *pointer, void *data, const char *info_name,
                      struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_vers_nouvelle_table_de_hachage;
}

/* ajoute l'information "mon_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("mon_info_hashtable",
                                                           "Une information",
                                                           "Info sur la table de hachage en entrée",
                                                           "Info sur la table de hachage en sortie",
                                                           &my_info_hashtable_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_info_hashtable(info_name: str, description: str, args_description: str,
                        output_description: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_info_hashtable_cb(data: str, info_name: str, hashtable: Dict[str, str]) -> Dict[str, str]:
    return {"test_cle": "test_valeur"}

hook = weechat.hook_info_hashtable("mon_info_hashtable", "Une information",
                                   "Info sur la table de hachage en entrée",
                                   "Info sur la table de hachage en sortie",
                                   "my_info_hashtable_cb", "")

hook_infolist

Mis à jour dans la 1.5.

Accrocher une infolist : la fonction de rappel retournera un pointeur vers l’infolist demandée.

Prototype :

struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      struct t_infolist *(*callback)(const void *pointer,
                                                                     void *data,
                                                                     const char *infolist_name,
                                                                     void *obj_pointer,
                                                                     const char *arguments),
                                      const void *callback_pointer,
                                      void *callback_data);

Paramètres :

infolist_name : nom de l’infolist (une priorité est autorisée avant le nom de l’infolist, voir la note sur la priorité)
description : description
pointer_description : description du pointeur (optionnel, peut être NULL)
args_description : description des paramètres (optionnel, peut être NULL)
callback : fonction appelée quand l’infolist est demandée, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *infolist_name : nom de l’infolist
- void *pointer : pointeur vers un objet que l’infolist doit retourner (pour obtenir uniquement cet objet dans l’infolist)
- const char *arguments : paramètres additionnels, dépendant de l’infolist
- valeur de retour : infolist demandée
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

struct t_infolist *
my_infolist_cb (const void *pointer, void *data, const char *infolist_name,
                void *obj_pointer, const char *arguments)
{
    struct t_infolist *mon_infolist;

    /* construction de l'infolist */
    /* ... */

    return mon_infolist;
}

/* ajoute l'infolist "mon_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("mon_infolist",
                                                    "Mon infolist",
                                                    "Info sur le pointeur",
                                                    "Info sur les paramètres",
                                                    &my_infolist_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_infolist(infolist_name: str, description: str, pointer_description: str,
                  args_description: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_infolist_cb(data: str, infolist_name: str, pointer: str, arguments: str) -> str:
    # construction de l'infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("mon_infolist", "Mon infolist",
                             "Info sur le pointeur", "Info sur les paramètres",
                             "my_infolist_cb", "")

hook_hdata

Mis à jour dans la 1.5.

Accrocher un hdata : la fonction de rappel retournera un pointeur vers le hdata demandé.

Prototype :

struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(const void *pointer,
                                                               void *data,
                                                               const char *hdata_name),
                                   const void *callback_pointer,
                                   void *callback_data);

Paramètres :

hdata_name : nom du hdata (une priorité est autorisée avant le nom du hdata, voir la note sur la priorité)
description : description
callback : fonction appelée quand le hdata est demandé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- const char *hdata_name : nom du hdata
- valeur de retour : hdata demandé
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

struct t_hdata *
my_hdata_cb (const void *pointer, void *data, const char *hdata_name)
{
    struct t_hdata *mon_hdata;

    /* construction du hdata */
    /* ... */

    return mon_hdata;
}

/* ajoute le hdata "mon_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("mon_hdata",
                                              "Hdata pour ma structure",
                                              &my_hdata_cb, NULL, NULL);

Cette fonction n’est pas disponible dans l’API script.

hook_focus

Mis à jour dans la 1.5, 4.0.0, 4.1.0.

Accrocher un focus : évènement souris ou touche du clavier pressée dans le mode "curseur" (mouvement libre du curseur).

Prototype :

struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(const void *pointer,
                                                                   void *data,
                                                                   struct t_hashtable *info),
                                   const void *callback_pointer,
                                   void *callback_data);

Paramètres :

area : "chat" pour la zone de discussion, ou un nom d’objet de barre (une priorité est autorisée avant la zone, voir la note sur la priorité)
callback : fonction appelée quand le focus est fait, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_hashtable *info : table de hachage avec les informations sur le focus et les chaînes retournées par les autres appels aux fonctions de rappel de focus (avec plus haute priorité) (voir le tableau ci-dessous)
- valeur de retour : soit le pointeur vers la table de hachage "info" (avec la table de hachage complétée), ou un pointeur vers une nouvelle table de hachage (créée par la fonction de rappel, avec clés et valeurs de type "string"), le contenu de cette nouvelle table de hachage sera ajouté à info pour les autres appels aux fonctions de rappel focus
callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le "hook" est supprimé

Pour un geste de souris, votre fonction de rappel sera appelée deux fois : la première lorsque le bouton est pressé (ici la zone correspond à vôtre zone), la seconde fois lorsque le bouton est relâché, et la zone peut ne pas correspondre à la vôtre : donc vous devez toujours tester dans la fonction de rappel si la zone correspond avant d’utiliser les informations de la table de hachage.

Contenu de la table de hachage envoyée à la fonction de rappel (les clés et valeurs sont de type "string") :

Clé ⁽¹⁾

Description

Exemples de valeur

Valeur si non applicable

Colonne sur l’écran.

"0" … "n"

Ligne sur l’écran.

"0" … "n"

_key

Touche ou évènement souris.

"button1", "button2-gesture-left", …

_window

Pointeur vers la fenêtre.

"0x1234abcd"

_window_number

Numéro de la fenêtre.

"1" … "n"

"*"

_buffer

Pointeur vers le tampon.

"0x1234abcd"

_buffer_number

Numéro du tampon.

"1" … "n"

"-1"

_buffer_plugin

Nom d’extension du tampon.

"core", "irc", …

_buffer_name

Nom du tampon.

"weechat", "libera.#weechat", …

_buffer_full_name

Nom complet du tampon.

"core.weechat", "irc.libera.#weechat", …

_buffer_localvar_XXX ⁽²⁾

Variables locales du tampon.

toute chaîne

non défini

_chat

Indicateur zone "chat".

"0" ou "1"

"0"

_chat_line

Pointeur vers la ligne (WeeChat ≥ 1.2).

"0x1234abcd"

_chat_line_x

Colonne de la ligne ⁽³⁾.

"0" … "n"

"-1"

_chat_line_y

Numéro de ligne ⁽³⁾.

"0" … "n"

"-1"

_chat_line_date

Date/heure de la ligne.

"1313237175"

"0"

_chat_line_date_usec

Microsecondes de la date/heure de la ligne.

"123456"

"0"

_chat_line_date_printed

Date/heure de la ligne ⁽⁴⁾.

"1313237175"

"0"

_chat_line_date_usec_printed

Microsecondes de la date/heure de la ligne ⁽⁴⁾.

"123456"

"0"

_chat_line_time

Heure affichée.

"14:06:15"

_chat_line_tags

Étiquettes de la ligne.

"irc_privmsg,nick_flashy,log1"

_chat_line_nick

Pseudo de la ligne.

"FlashCode"

_chat_line_prefix

Préfixe de la ligne.

"@FlashCode"

_chat_line_message

Message de la ligne.

"Hello world!"

_chat_focused_line

Ligne à la position (x, y) (WeeChat ≥ 4.0.0).

"Hello world!"

_chat_focused_line_bol

Texte du début de la ligne jusqu’à (x-1, y) (WeeChat ≥ 4.1.0).

"Hello"

_chat_focused_line_eol

Texte de (x, y) jusqu’à la fin de la ligne (WeeChat ≥ 4.1.0).

"llo world!"

_chat_word

Mot à la position (x,y).

"Hello"

_chat_bol

Texte du début du message jusqu’à (x-1, y).

"He"

_chat_eol

Texte de (x, y) jusqu’à la fin du message.

"llo world!"

_bar_name

Nom de la barre.

"title", "nicklist", …

_bar_filling

Remplissage de la barre.

"horizontal", "vertical", …

_bar_item_name

Nom de l’objet de barre.

"buffer_nicklist", "hotlist", …

_bar_item_line

Ligne dans l’objet de barre.

"0" … "n"

"-1"

_bar_item_col

Colonne dans l’objet de barre.

"0" … "n"

"-1"

_bar_window

Pointeur vers la fenêtre de barre (WeeChat ≥ 2.9).

"0x1234abcd"

⁽¹⁾ Il y a les mêmes clés suffixées par "2" (c’est-à-dire : "_x2", "_y2", "_window2", …) avec l’information sur le second point (pratique seulement pour les gestes de souris, pour savoir où le bouton de la souris a été relâché).
⁽²⁾ XXX est le nom d’une variable locale du tampon.
⁽³⁾ Renseigné seulement pour les tampons avec contenu libre.
⁽⁴⁾ Il s’agit de la date lorsque WeeChat ajoute la ligne dans le tampon (supérieure ou égale à "_chat_line_date").

Informations additionnelles pour l’objet de barre "buffer_nicklist" :

Extension ⁽¹⁾

Clé

Description

irc

irc_nick

Pointeur vers le pseudo IRC (WeeChat ≥ 3.0).

irc

irc_host

Nom d’hôte pour le pseudonyme (si connu).

weechat

nick

Pseudonyme.

weechat

prefix

Préfixe du pseudonyme.

weechat

group

Nom du groupe.

⁽¹⁾ Le nom de l’extension qui définit un hook_focus pour retourner des infos pour cet objet de barre (donc par exemple si l’extension est "irc", ces infos ne seront disponibles que sur les tampons irc).

Valeur de retour :

pointeur vers le nouveau "hook", NULL en cas d’erreur

Exemple en C :

struct t_hashtable *
my_focus_nicklist_cb (const void *pointer, void *data, struct t_hashtable *info)
{
    /* ajout de chaînes dans la table de hachage */
    /* ... */

    return info;
}

/* ajoute le focus sur la liste des pseudos */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL, NULL);

Script (Python) :

# prototype
def hook_focus(area: str, callback: str, callback_data: str) -> str: ...

# exemple
def my_focus_nicklist_cb(data: str, info: Dict[str, str]) -> Dict[str, str]:
    # construction du dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")

hook_set

WeeChat ≥ 0.3.9 (script : WeeChat ≥ 0.4.3).

Affecter une valeur à une propriété d’un hook.

Prototype :

void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);

Paramètres :

hook : quelque chose d’accroché avec "weechat_hook_xxx()"
property : nom de la propriété (voir le tableau ci-dessous)
value : nouvelle valeur pour la propriété

Propriétés :

Nom WeeChat mini Type de hook Valeur Description

subplugin

tout type

toute chaîne

Nom de la sous-extension (couramment un nom de script, qui est affiché dans /help commande pour un hook de type command).

stdin

0.4.3

process, process_hashtable

toute chaîne

Envoyer les données sur l’entrée standard (stdin) du processus fils.

stdin_close

0.4.3

process, process_hashtable

(non utilisée)

Fermer le tuyau utilisé pour envoyer les données sur l’entrée standard (stdin) du processus fils.

signal

1.0

process, process_hashtable

numéro de signal ou un de ces noms : hup, int, quit, kill, term, usr1, usr2

Envoyer un signal au proces.sus fils

Exemple en C :

struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");

Script (Python) :

# prototype
def hook_set(hook: str, property: str, value: str) -> int: ...

# exemple
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process_hashtable("/chemin/vers/commande", {"stdin": "1"},
                                      20000, "my_process_cb", "")
weechat.hook_set(hook, "stdin", "données envoyées sur le stdin du processus fils")
weechat.hook_set(hook, "stdin_close", "")  # facultatif

unhook

Décrocher quelque chose qui est a été accroché.

Prototype :

void weechat_unhook (struct t_hook *hook);

Paramètres :

hook : quelque chose accroché avec "weechat_hook_xxx()"

Exemple en C :

struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);

Script (Python) :

# prototype
def unhook(hook: str) -> int: ...

# exemple
weechat.unhook(my_hook)

unhook_all

Mis à jour dans la 1.5.

Décrocher tout ce qui a été accroché par l’extension courante.

Prototype :

void weechat_unhook_all (const char *subplugin);

Paramètres :

subplugin : si non NULL, décrocher uniquement les "hooks" qui ont ce "subplugin" défini (ce paramètre n’est pas disponible dans l’API script)

Exemple en C :

weechat_unhook_all (NULL);

Script (Python) :

# prototype
def unhook_all() -> int: ...

# exemple
weechat.unhook_all()

3.15. Tampons

Fonctions pour créer/interroger/fermer les tampons.

buffer_new

Mis à jour dans la 1.5.

Ouvrir un nouveau tampon.

Si vous souhaitez définir immédiatement des propriétés du tampon (type de tampon, variables locales, touches de raccourci, etc.), alors il vaut mieux utiliser la fonction buffer_new_props qui définit ces propriétés durant la création du tampon, avant d’envoyer le signal buffer_opened.

Prototype :

struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         const void *input_callback_pointer,
                                         void *input_callback_data,
                                         int (*close_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer),
                                         const void *close_callback_pointer,
                                         void *close_callback_data);

Paramètres :

name : nom du tampon (doit être unique pour l’extension)
input_callback : fonction appelée lorsque du texte saisi est envoyé au tampon, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : pointeur vers le tampon
- const char *input_data : données en entrée
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
input_callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
input_callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le tampon est fermé
close_callback : fonction appelée lorsque le tampon est fermé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : pointeur vers le tampon
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
close_callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
close_callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le tampon est fermé

Valeur de retour :

pointeur vers le nouveau tampon, NULL en cas d’erreur

Exemple en C :

int
my_input_cb (const void *pointer, void *data,
             struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Texte : %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Le tampon '%s' va être fermé !",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("mon_buffer",
                                                     &my_input_cb, NULL, NULL,
                                                     &my_close_cb, NULL, NULL);

Script (Python) :

# prototype
def buffer_new(name: str, input_callback: str, input_callback_data: str,
               close_callback: str, close_callback_data: str) -> str: ...

# exemple
def my_input_cb(data: str, buffer: str, input_data: str) -> int:
    weechat.prnt(buffer, "Texte : %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data: str, buffer: str) -> int:
    weechat.prnt("", "Le tampon '%s' va être fermé !" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("mon_buffer", "my_input_cb", "", "my_close_cb", "")

buffer_new_props

WeeChat ≥ 3.5.

Ouvrir un nouveau tampon et appliquer des propriétés.

Prototype :

struct t_gui_buffer *weechat_buffer_new_props (const char *name,
                                               struct t_hashtable *properties,
                                               int (*input_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer,
                                                                     const char *input_data),
                                               const void *input_callback_pointer,
                                               void *input_callback_data,
                                               int (*close_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer),
                                               const void *close_callback_pointer,
                                               void *close_callback_data);

Paramètres :

name : nom du tampon (doit être unique pour l’extension)
properties : propriétés à appliquer (voir la fonction buffer_set pour les propriétés autorisées)
input_callback : fonction appelée lorsque du texte saisi est envoyé au tampon, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : pointeur vers le tampon
- const char *input_data : données en entrée
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
input_callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
input_callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le tampon est fermé
close_callback : fonction appelée lorsque le tampon est fermé, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_buffer *buffer : pointeur vers le tampon
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
close_callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
close_callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le tampon est fermé

Valeur de retour :

pointeur vers le nouveau tampon, NULL en cas d’erreur

Exemple en C :

int
my_input_cb (const void *pointer, void *data,
             struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Texte : %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Le tampon '%s' va être fermé !",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_hashtable *properties = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);
/* tampon avec contenu libre */
weechat_hashtable_set (properties, "type", "free");
/* pas d'enregistrement sur ce tampon */
weechat_hashtable_set (properties, "localvar_set_no_log", "1");
/* associer la touche alt-c sur ce tampon */
weechat_hashtable_set (properties, "key_bind_meta-c", "/ma_commande");

struct t_gui_buffer *my_buffer = weechat_buffer_new_props ("mon_buffer",
                                                           properties,
                                                           &my_input_cb, NULL, NULL,
                                                           &my_close_cb, NULL, NULL);

Script (Python) :

# prototype
def buffer_new_props(name: str, properties: Dict[str, str],
                     input_callback: str, input_callback_data: str,
                     close_callback: str, close_callback_data: str) -> str: ...

# exemple
def my_input_cb(data: str, buffer: str, input_data: str) -> int:
    weechat.prnt(buffer, "Texte : %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data: str, buffer: str) -> int:
    weechat.prnt("", "Le tampon '%s' va être fermé !" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

properties = {
    "type": "free",                     # tampon avec contenu libre
    "localvar_set_no_log": "1",         # pas d'enregistrement sur ce tampon
    "key_bind_meta-c": "/ma_commande",  # associer la touche alt-c sur ce tampon
}
buffer = weechat.buffer_new_props("mon_buffer", properties, "my_input_cb", "", "my_close_cb", "")

current_buffer

Retourner un pointeur vers le tampon courant (le tampon affiché par la fenêtre courante).

Prototype :

struct t_gui_buffer *weechat_current_buffer ();

Valeur de retour :

pointeur vers le tampon courant

Exemple en C :

weechat_printf (weechat_current_buffer (), "Texte sur le tampon courant");

Script (Python) :

# prototype
def current_buffer() -> str: ...

# exemple
weechat.prnt(weechat.current_buffer(), "Texte sur le tampon courant")

buffer_search

Mis à jour dans la 1.0.

Rechercher un tampon par l’extension et/ou le nom.

Prototype :

struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);

Paramètres :

plugin : nom de l’extension, la valeur spéciale suivante est autorisée :
- == : le nom utilisé est le nom complet du tampon (par exemple : irc.libera.#weechat au lieu de libera.#weechat) (WeeChat ≥ 1.0)
name : nom du tampon, si c’est NULL ou une chaîne vide, le tampon courant est retourné (tampon affiché par la fenêtre courante); si le nom commence par (?i), la recherche est insensible à la casse (WeeChat ≥ 1.0)

Valeur de retour :

pointeur vers le tampon trouvé, NULL s’il n’a pas été trouvé

Exemples en C :

struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.libera.#test");  /* WeeChat ≥ 1.0 */

Script (Python) :

# prototype
def buffer_search(plugin: str, name: str) -> str: ...

# exemple
buffer = weechat.buffer_search("mon_extension", "mon_tampon")

buffer_search_main

Rechercher le tampon principal de WeeChat (tampon core, premier tampon affiché lorsque WeeChat démarre).

Prototype :

struct t_gui_buffer *weechat_buffer_search_main ();

Valeur de retour :

pointeur vers le tampon principal WeeChat (tampon core)

Exemple en C :

struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();

Script (Python) :

# prototype
def buffer_search_main() -> str: ...

# exemple
buffer = weechat.buffer_search_main()

buffer_clear

Effacer le contenu d’un tampon.

Prototype :

void weechat_buffer_clear (struct t_gui_buffer *buffer);

Paramètres :

buffer : pointeur vers le tampon

Exemple en C :

struct t_gui_buffer *my_buffer = weechat_buffer_search ("mon_extension",
                                                        "mon_tampon");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}

Script (Python) :

# prototype
def buffer_clear(buffer: str) -> int: ...

# exemple
buffer = weechat.buffer_search("mon_extension", "mon_tampon")
if buffer:
    weechat.buffer_clear(buffer)

buffer_close

Fermer un tampon.

Prototype :

void weechat_buffer_close (struct t_gui_buffer *buffer);

Paramètres :

buffer : pointeur vers le tampon

Exemple en C :

struct t_gui_buffer *my_buffer = weechat_buffer_new ("mon_tampon",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);

Script (Python) :

# prototype
def buffer_close(buffer: str) -> int: ...

# exemple
buffer = weechat.buffer_new("mon_tampon", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)

buffer_merge

Mélanger le tampon avec un autre tampon : les deux tampons continueront d’exister chacun de leur côté, mais avec le même numéro, et WeeChat affichera les lignes des deux tampons (lignes mélangées).

Prototype :

void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);

Paramètres :

buffer : pointeur vers le tampon
target_buffer : tampon cible avec lequel on doit mélanger

Exemple en C :

/* mélanger le tampon courant avec le tampon "core" */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());

Script (Python) :

# prototype
def buffer_merge(buffer: str, target_buffer: str) -> int: ...

# exemple
# mélanger le tampon courant avec le tampon "core"
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())

buffer_unmerge

Supprimer le mélange d’un tampon.

Prototype :

void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);

Paramètres :

buffer : pointeur vers le tampon
number : numéro cible pour le tampon détaché, s’il est < 1, alors le tampon sera déplacé vers le numéro du tampon + 1

Exemple en C :

weechat_buffer_unmerge (weechat_current_buffer (), 1);

Script (Python) :

# prototype
def buffer_unmerge(buffer: str, number: int) -> int: ...

# exemple
weechat.buffer_unmerge(weechat.current_buffer(), 1)

buffer_get_integer

Retourner une valeur entière pour une propriété du tampon.

Prototype :

int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);

Paramètres :

buffer : pointeur vers le tampon
property : nom de la propriété :
- opening : 1 si le tampon est en cours d’ouverture, sinon 0 (WeeChat ≥ 4.2.0)
- number : numéro du tampon (commence à 1)
- layout_number : numéro du tampon sauvegardé dans le "layout"
- layout_number_merge_order : ordre du tampon mélangé pour le "layout"
- short_name_is_set : 1 si le nom court est défini, 0 si non défini
- type : type de tampon (0 : formaté, 1 : contenu libre)
- notify : niveau de notification du tampon
- num_displayed : nombre de fenêtres affichant ce tampon
- active : 2 si le tampon est le seul actif (mélangé), 1 si le tampon est actif, 0 si le tampon est mélangé et n’est pas sélectionné
- hidden : 1 si le tampon est caché, sinon 0 (WeeChat ≥ 1.0)
- zoomed : 1 si le tampon est mélangé et zoomé, sinon 0 (WeeChat ≥ 1.0)
- print_hooks_enabled : 1 si les hooks "print" sont activés, sinon 0
- day_change : 1 si les messages de changement de jour sont affichés, sinon 0 (WeeChat ≥ 0.4.3)
- clear : 1 si le tampon peut être effacé avec la commande /buffer clear, sinon 0 (WeeChat ≥ 1.0)
- filter : 1 si les filtres sont activés sur le tampon, sinon 0 (WeeChat ≥ 1.0)
- closing : 1 si le tampon est en cours de fermeture, sinon 0 (WeeChat ≥ 1.0)
- lines_hidden : 1 si au moins une ligne est cachée dans le tampon (filtrée), ou 0 si toutes les lignes sont affichées
- prefix_max_length : longueur maximale du préfixe dans ce tampon
- next_line_id : prochain identifiant de ligne dans le tampon (WeeChat ≥ 3.8)
- time_for_each_line : 1 si l’heure est affichée pour chaque ligne du tampon (par défaut), sinon 0
- nicklist : 1 si la liste de pseudos est activée, sinon 0
- nicklist_case_sensitive : 1 si les pseudos sont sensibles à la casse, sinon 0
- nicklist_max_length : longueur maximale d’un pseudo
- nicklist_display_groups : 1 si les groupes sont affichés, sinon 0
- nicklist_count : nombre de pseudos et groupes dans la liste de pseudos
- nicklist_visible_count : nombre de pseudos/groupes affichés
- nicklist_groups_count : nombre de groupes dans la liste de pseudos
- nicklist_groups_visible_count : nombre de groupes affichés
- nicklist_nicks_count : nombre de pseudos dans la liste de pseudos
- nicklist_nicks_visible_count : nombre de pseudos affichés
- input : 1 si la zone de saisie est activée, sinon 0
- input_get_unknown_commands : 1 si les commandes inconnues sont envoyées à la fonction de rappel "input", sinon 0
- input_get_empty : 1 si une entrée vide est envoyée à la fonction de rappel "input", sinon 0
- input_multiline : 1 si plusieurs lignes sont envoyées comme un seul message à la fonction de rappel "input", sinon 0
- input_size : taille de la zone de saisie (en octets)
- input_length : longueur de la zone de saisie (nombre de caractères)
- input_pos : position du curseur dans la zone de saisie
- input_1st_display : premier caractère affiché à l’écran
- num_history : nombre de commandes dans l’historique
- text_search : type de recherche de texte :
  - 0 : pas de recherche en cours
  - 1 : recherche dans les lignes du tampon
  - 2 : recherche dans l’historique de commandes
- text_search_direction : direction pour la recherche :
  - 0 : recherche arrière (vers les messages/commandes plus anciens)
  - 1 : recherche avant (vers les messages/commandes plus récents)
- text_search_exact : 1 si la recherche de texte est sensible à la casse
- text_search_regex : 1 si la recherche est avec une expression régulière
- text_search_where :
  - 0 : pas de recherche en cours
  - 1 : recherche dans le message
  - 2 : recherche dans le préfixe
  - 3 : recherche dans le préfixe et le message
- text_search_history:
  - 0 : pas de recherche en cours
  - 1 : recherche dans l’historique local du tampon
  - 2 : recherche dans l’historique global
- text_search_found : 1 si du texte a été trouvé, sinon 0

Valeur de retour :

valeur entière de la propriété

Exemple en C :

weechat_printf (NULL, "mon numéro de tampon est : %d",
                weechat_buffer_get_integer (mon_tampon, "number"));

Script (Python) :

# prototype
def buffer_get_integer(buffer: str, property: str) -> int: ...

# exemple
weechat.prnt("", "mon numéro de tampon est : %d" % weechat.buffer_get_integer(my_buffer, "number"))

buffer_get_string

Retourner la valeur d’une propriété du tampon sous forme de chaîne.

Prototype :

const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);

Paramètres :

buffer : pointeur vers le tampon
property : nom de la propriété :
- plugin : nom de l’extension qui a créé ce tampon ("core" pour le tampon principal WeeChat)
- name : nom du tampon
- full_name : nom complet du tampon ("extension.nom") (WeeChat ≥ 0.3.7)
- old_full_name : ancien nom complet du tampon ("extension.nom"), défini avant que le tampon ne soit renommé (WeeChat ≥ 2.8)
- short_name : nom court du tampon (note : utilisé pour l’affichage seulement et peut être changé par l’utilisateur, il ne doit pas être utilisé pour trouver le nom du tampon, utilisez à la place name, full_name ou bien la variable locale channel)
- type : type de tampon : "formatted" (formaté) ou "free" (contenu libre) (WeeChat ≥ 4.2.0)
- title : titre du tampon
- input : texte saisi
- text_search_input : texte saisi sauvegardé avant la recherche de texte
- highlight_words : liste des mots pour le highlight
- highlight_disable_regex : expression régulière POSIX étendue pour désactiver le highlight
- highlight_regex : expression régulière POSIX étendue pour le highlight
- highlight_tags_restrict : restreindre les highlights aux messages comportant ces étiquettes
- highlight_tags : forcer le highlight pour les messages avec ces étiquettes
- hotlist_max_level_nicks : niveau maximum pour la hotlist pour certains pseudos
- localvar_xxx : contenu de la variable locale "xxx" (remplacer "xxx" par le nom de la variable locale à lire)

Valeur de retour :

valeur de la propriété, sous forme de chaîne

Exemple en C :

weechat_printf (NULL, "nom / nom court du tampon sont : %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));

Script (Python) :

# prototype
def buffer_get_string(buffer: str, property: str) -> str: ...

# exemple
weechat.prnt("", "nom / nom court du tampon sont : %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))

buffer_get_pointer

Retourner la valeur d’une propriété sous forme d’un pointeur.

Prototype :

void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);

Paramètres :

buffer : pointeur vers le tampon
property : nom de la propriété :
- plugin : pointeur vers l’extension qui a créé le tampon (NULL pour le tampon principal WeeChat)
- text_search_regex_compiled : expression régulière compilée
- text_search_ptr_history : entrée d’historique trouvée
- highlight_disable_regex_compiled : expression régulière highlight_disable_regex compilée
- highlight_regex_compiled : expression régulière highlight_regex compilée

Valeur de retour :

valeur de la propriété, sous forme de pointeur

Exemple en C :

weechat_printf (NULL, "pointeur vers l'extension de mon tampon : %lx",
                weechat_buffer_get_pointer (mon_tampon, "plugin"));

Script (Python) :

# prototype
def buffer_get_pointer(buffer: str, property: str) -> str: ...

# exemple
weechat.prnt("", "pointeur vers l'extension de mon tampon : %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))

buffer_set

Affecter une valeur à une propriété d’un tampon.

Prototype :

void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);

Paramètres :

buffer : pointeur vers le tampon
property : nom de la propriété (voir le tableau ci-dessous)
value : nouvelle valeur pour la propriété

Propriétés :

Nom WeeChat mini Valeur Description.

hotlist

"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1"

"+" : active la hotlist (option globale, le pointeur vers le tampon n’est pas utilisé)
"-" : désactive la hotlist (option globale, le pointeur vers le tampon n’est pas utilisé)
priorité : ajouter ce tampon dans la hotlist avec cette priorité (les conditions définies dans l’option weechat.look.hotlist_add_conditions ne sont PAS vérifiées)
"-1" : supprimer ce tampon de la hotlist (WeeChat ≥ 1.0).

completion_freeze

"0" ou "1"

"0" : pas de gel de la complétion (valeur par défaut) (option globale, le pointeur vers le tampon n’est pas utilisé)
"1" : ne pas arrêter la complétion lorsque la ligne de commande est mise à jour (option globale, le pointeur vers le tampon n’est pas utilisé).

unread

chaîne vide, "0", "+N", "-N" ou "N" (N est un entier)

chaîne vide : définir le marqueur de données non lues après la dernière ligne du tampon
"0" : supprimer le marqueur de données non lues du tampon
"N" : déplacer le marqueur de données non lues de N lignes depuis la fin vers la première ligne du tampon
"-N" : déplacer le marqueur de données non lues de N lignes vers la première ligne du tampon
"+N" : déplacer le marqueur de données non lues de N lignes vers la dernière ligne du tampon.

display

"1" ou "auto"

"1" : basculer vers ce tampon dans la fenêtre active
"auto" : basculer vers ce tampon dans la fenêtre active, le marqueur de données non lues n’est pas réinitialisé.

hidden

1.0

"0" ou "1"

"0" : démasquer le tampon
"1" : masquer le tampon.

number

numéro

Déplace le tampon vers ce numéro.

name

toute chaîne

Change le nom du tampon.

short_name

toute chaîne

Change le nom court du tampon.

type

"formatted" ou "free"

Définit le type de tampon : "formatted" (pour afficher les messages d’une discussion), ou "free" (pour du contenu libre); lorsque la valeur est "free", la propriété clear est forcée à "0" (WeeChat ≥ 1.0).

notify

"0", "1", "2", "3"

Définit le niveau de notification du tampon : "0" = ne jamais ajouter à la hotlist, "1" = ajouter pour les highlights seulement, "2" = ajouter pour les highlights et les messages, "3" = ajouter pour tous les messages.

print_hooks_enabled

"0" ou "1"

"0" pour désactiver les hooks "print", "1" pour les activer (par défaut pour un nouveau tampon).

day_change

0.4.3

"0" ou "1"

"0" pour cacher les messages de changement de jour, "1" pour les voir (par défaut pour un nouveau tampon).

clear

1.0

"0" ou "1"

"0" pour empêcher l’utilisateur d’effacer le tampon avec la commande /buffer clear, "1" pour autoriser l’utilisateur à effacer le tampon (par défaut pour un nouveau tampon) (note : même lorsque la valeur est "0", le tampon peut toujours être effacé avec la fonction buffer_clear).

filter

1.0

"0" or "1"

"0" : désactiver les filtres sur le tampon
"1" : activer les filtres sur le tampon.

title

toute chaîne

Change le titre du tampon.

time_for_each_line

"0" ou "1"

"0" pour cacher l’heure sur toutes les lignes du tampon, "1" pour afficher l’heure sur toutes les lignes (par défaut pour un nouveau tampon).

nicklist

"0" ou "1"

"0" pour supprimer la liste des pseudos du tampon, "1" pour ajouter la liste des pseudos du tampon.

nicklist_case_sensitive

"0" ou "1"

"0" pour avoir la liste des pseudos insensible à la casse, "1" pour avoir la liste des pseudos sensible à la casse.

nicklist_display_groups

"0" ou "1"

"0" pour cacher les groupes de la liste des pseudos, "1" pour afficher les groupes de la liste des pseudos.

highlight_words

"-" ou une liste de mots séparés par des virgules

"-" est une valeur spéciale pour désactiver tout highlight sur ce tampon, ou une liste de mots à mettre en valeur dans ce tampon, par exemple : "abc,def,ghi".

highlight_words_add

liste de mots séparés par des virgules

Liste de mots à mettre en valeur dans ce tampon, ces mots sont ajoutés aux mots existants pour le tampon.

highlight_words_del

liste de mots séparés par des virgules

Liste de mots à supprimer de la liste des mots à mettre en valeur dans ce tampon.

highlight_disable_regex

any string

Expression régulière POSIX étendue pour désactiver le highlight.

highlight_regex

toute chaîne

Expression régulière POSIX étendue pour le highlight.

highlight_tags_restrict

liste d’étiquettes séparées par des virgules

Restreindre les highlights aux messages avec ces étiquettes dans ce tampon (il est possible de combiner plusieurs étiquettes sous forme d’un "et" logique avec le séparateur "+", par exemple : "nick_toto+irc_action").

highlight_tags

liste d’étiquettes séparées par des virgules

Forcer le highlight pour les messages avec ces étiquettes dans ce tampon (il est possible de combiner plusieurs étiquettes sous forme d’un "et" logique avec le séparateur "+", par exemple : "nick_toto+irc_action").

hotlist_max_level_nicks

liste de "pseudo:niveau" séparés par des virgules

Liste de pseudos avec niveau max pour la hotlist sur ce tampon (le niveau peut être : -1 : jamais dans la hotlist, 0 : faible, 1 : message, 2 : privé, 3 : highlight), par exemple : "joe:2,mike:-1,robert:-1" (joe ne produira jamais de highlight sur le tampon, mike et robert ne changeront jamais la hotlist).

hotlist_max_level_nicks_add

liste de "pseudo:niveau" séparés par des virgules"

Liste de pseudos avec niveau pour la hotlist, ces pseudos sont ajoutés aux pseudos existant dans le tampon.

hotlist_max_level_nicks_del

liste de pseudos séparés par des virgules

Liste de pseudos à supprimer des niveaux max de hotlist.

key_bind_xxx

toute chaîne

Associe la nouvelle touche xxx, spécifique à ce tampon, la valeur est la commande à exécuter pour cette touche.

key_unbind_xxx

Supprime la touche xxx pour ce tampon.

input

toute chaîne

Change le contenu de la zone de saisie.

input_pos

position

Change la position du curseur dans la zone de saisie.

input_get_unknown_commands

"0" ou "1"

"0" pour désactiver les commandes inconnues sur ce tampon (comportement par défaut), "1" pour recevoir les commandes inconnues, par exemple si l’utilisateur tape "/commandeinconnue", le tampon le recevra (pas d’erreur sur la commande inconnue).

input_get_empty

"0" ou "1"

"0" pour désactiver l’entrée vide sur ce tampon (comportement par défaut), "1" pour recevoir l’entrée vide.

input_multiline

"0" ou "1"

"0" pour envoyer chaque ligne séparément au tampon (comportement par défaut), "1" pour envoyer plusieurs lignes comme un seul message.

localvar_set_xxx

toute chaîne

Change la valeur de la variable locale xxx (la variable est créée si elle n’existe pas).

localvar_del_xxx

Supprime la variable locale xxx.

Exemple en C :

/* désactiver la hotlist (pour tous les tampons) */
weechat_buffer_set (NULL, "hotlist", "-");

/* activer à nouveau la hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* changer le nom du tampon */
weechat_buffer_set (mon_tampon, "name", "nouveau_nom");

/* ajouter une variable locale "toto" avec la valeur "abc" */
weechat_buffer_set (mon_tampon, "localvar_set_toto", "abc");

/* supprimer la variable locale "toto" */
weechat_buffer_set (mon_tampon, "localvar_del_toto", "");

Script (Python) :

# prototype
def buffer_set(buffer: str, property: str, value: str) -> int: ...

# exemples

# désactiver la hotlist (pour tous les tampons)
weechat.buffer_set("", "hotlist", "-")

# activer à nouveau la hotlist
weechat.buffer_set("", "hotlist", "+")

# changer le nom du tampon
weechat.buffer_set(my_buffer, "name", "my_new_name")

# ajouter une variable locale "toto" avec la valeur "abc"
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

# supprimer la variable locale "toto"
weechat.buffer_set(my_buffer, "localvar_del_toto", "")

buffer_set_pointer

Affecter un pointeur à une propriété d’un tampon.

Prototype :

void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);

Paramètres :

buffer : pointeur vers le tampon
property : nom de la propriété :
- close_callback : définit la fonction de rappel de fermeture du tampon
- close_callback_data : définit les données pour la fonction de rappel de fermeture du tampon
- input_callback : définit la fonction de rappel pour les données en entrée
- input_callback_data : définit les données pour la fonction de rappel des données en entrée
- nickcmp_callback : définit la fonction de rappel de comparaison de pseudos (cette fonction de rappel est appelée lors de la recherche d’un pseudo dans la liste des pseudos) (WeeChat ≥ 0.3.9)
- nickcmp_callback_data : définit les données pour la fonction de rappel de comparaison de pseudos (WeeChat ≥ 0.3.9)
pointer : nouvelle valeur de pointeur pour la propriété

Prototypes pour les fonctions de rappel :

int close_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer);

int input_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (const void *pointer, void *data,
                      struct t_gui_buffer *buffer,
                      const char *nick1, const char *nick2);

Exemple en C :

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (mon_tampon, "close_callback", &my_close_cb);

Cette fonction n’est pas disponible dans l’API script.

buffer_string_replace_local_var

Remplacer les variables locales dans une chaîne par leurs valeurs, en utilisant les variables locales du tampon.

Prototype :

char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);

Paramètres :

buffer : pointeur vers le tampon
string : chaîne avec du texte et des variables locales, au format "$var"

Valeur de retour :

chaîne avec les valeurs des variables locales

Exemple en C :

weechat_buffer_set (mon_tampon, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (mon_tampon,
                                                     "test avec $toto");
/* str contient "test avec abc" */

Script (Python) :

# prototype
def buffer_string_replace_local_var(buffer: str, string: str) -> str: ...

# exemple
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test avec $toto")
# str contient "test avec abc"

buffer_match_list

WeeChat ≥ 0.3.5, mis à jour dans la 4.0.0.

Vérifier si le tampon correspond à la liste de tampons.

Prototype :

int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);

Paramètres :

buffer : pointeur vers le tampon
string : liste de tampons, séparés par des virgules :
- * signifie tous les tampons
- un nom commençant par ! est exclu
- le caractère joker * est autorisé dans le nom

Depuis la version 4.0.0, la comparaison des noms de tampons est sensible à la casse.

Valeur de retour :

1 si le tampon correspond à la liste de tampons, 0 sinon

Exemple en C :

struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "libera.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.libera.*"));         /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
}

Script (Python) :

# prototype
def buffer_match_list(buffer: str, string: str) -> int: ...

# exemple
buffer = weechat.buffer_search("irc", "libera.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.libera.*"))         # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0

3.16. Fenêtres

Fonctions pour interroger les fenêtres.

current_window

Retourner le pointeur vers la fenêtre courante.

Prototype :

struct t_gui_window *weechat_current_window ();

Valeur de retour :

pointeur vers la fenêtre courante

Exemple en C :

struct t_gui_window *current_window = weechat_current_window ();

Script (Python) :

# prototype
def current_window() -> str: ...

# exemple
current_window = weechat.current_window()

window_search_with_buffer

WeeChat ≥ 0.3.5.

Retourner le pointeur vers la fenêtre affichant un tampon.

Prototype :

struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);

Paramètre :

buffer : pointeur vers le tampon

Valeur de retour :

pointeur vers la fenêtre affichant un tampon (NULL si aucune fenêtre n’affiche ce tampon)

Exemple en C :

weechat_printf (NULL,
                "fenêtre affichant le tampon core : %lx",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));

Script (Python) :

# prototype
def window_search_with_buffer(buffer: str) -> str: ...

# exemple
weechat.prnt("", "fenêtre affichant le tampon core : %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))

window_get_integer

Retourner la valeur entière d’une propriété de la fenêtre.

Prototype :

int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);

Paramètres :

window : pointeur vers la fenêtre
property : nom de la propriété :
- number : numéro de la fenêtre (commence à 1)
- win_x : position X de la fenêtre dans le terminal (la première colonne est 0)
- win_y : position Y de la fenêtre dans le terminal (la première ligne est 0)
- win_width : largeur de la fenêtre, en caractères
- win_height : hauteur de la fenêtre, en caractères
- win_width_pct : taille en pourcentage, en comparaison avec la fenêtre parente (par exemple 50 indique une largeur de moitié)
- win_height_pct : taille en pourcentage, en comparaison avec la fenêtre parente (par exemple 50 indique une hauteur de moitié)
- win_chat_x : position X de la fenêtre de discussion ("chat") dans le terminal (la première colonne est 0)
- win_chat_y : position Y de la fenêtre de discussion ("chat") dans le terminal (la première ligne est 0)
- win_chat_width : largeur de la fenêtre de discussion ("chat"), en caractères
- win_chat_height : hauteur de la fenêtre de discussion ("chat"), en caractères
- first_line_displayed : 1 si la première du tampon est affichée à l’écran, sinon 0
- scrolling : 1 s’il y a un défilement en cours dans la fenêtre (la dernière ligne n’est pas affichée)
- lines_after : nombre de lignes non affichées après la dernière ligne affichée (lors d’un défilement)

Valeur de retour :

valeur entière de la propriété

Exemple en C :

weechat_printf (NULL, "la fenêtre courante est en position (x,y) : (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));

Script (Python) :

# prototype
def window_get_integer(window: str, property: str) -> int: ...

# exemple
weechat.prnt("", "la fenêtre courante est en position (x,y) : (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))

window_get_string

Retourner la valeur d’une propriété de la fenêtre sous forme d’une chaîne.

Cette fonction n’est pas utilisée aujourd’hui, elle est réservée pour une version future.

Prototype :

const char *weechat_window_get_string (struct t_gui_window *window,
                                       const char *property);

Paramètres :

window : pointeur vers la fenêtre
property : nom de la propriété

Valeur de retour :

valeur de la propriété, sous forme de chaîne

Script (Python) :

# prototype
def window_get_string(window: str, property: str) -> str: ...

window_get_pointer

Retourner la valeur d’une propriété, sous forme d’un pointeur.

Prototype :

void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);

Paramètres :

window : pointeur vers la fenêtre
property : nom de la propriété :
- current : pointeur vers la fenêtre courante
- buffer : pointeur vers le tampon affiché par la fenêtre

Valeur de retour :

valeur de la propriété, sous forme de pointeur

Exemple en C :

weechat_printf (NULL,
                "tampon affiché dans la fenêtre courante : %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));

Script (Python) :

# prototype
def window_get_pointer(window: str, property: str) -> str: ...

# exemple
weechat.prnt("", "tampon affiché dans la fenêtre courante : %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))

window_set_title

Définir le titre du terminal.

Prototype :

void weechat_window_set_title (const char *title);

Paramètres :

title : nouveau titre pour le terminal (NULL pour réinitialiser le titre) ; la chaîne est évaluée, donc les variables comme ${info:version} peuvent être utilisées (voir string_eval_expression)

Exemple en C :

weechat_window_set_title ("nouveau titre ici");

Script (Python) :

# prototype
def window_set_title(title: str) -> int: ...

# exemple
weechat.window_set_title("nouveau titre ici")

3.17. Nicklist

Fonctions pour la liste des pseudos.

nicklist_add_group

Ajouter un groupe dans la liste des pseudos.

Prototype :

struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);

Paramètres :

buffer : pointeur vers le tampon
parent_group : pointeur vers le parent du groupe, NULL si le groupe n’a pas de parent (racine de la liste des pseudos)
name : nom du groupe
color : nom de l’option contenant la couleur :
- une option WeeChat, par exemple weechat.color.nicklist_group
- une couleur avec un fond optionnel, par exemple yellow ou yellow,red
- nom d’une couleur de barre :
  - bar_fg : couleur de texte pour la barre
  - bar_delim : couleur des délimiteurs pour la barre
  - bar_bg : couleur de fond pour la barre
visible :
- 1 : le groupe et ses sous-groupes/pseudos sont visibles
- 0 : le groupe et ses sous-groupes/pseudos sont cachés

Le nom du groupe peut commencer par un ou plusieurs chiffres, suivis d’un pipe ("|"), puis du nom du groupe. Quand une telle chaîne est trouvée au début, elle est utilisée pour trier les groupes dans la liste des pseudos. Par exemple les groupes "1|test" et "2|abc" seront affichés dans cet ordre : "test" en premier, puis "abc" en second.

Valeur de retour :

pointeur vers le nouveau groupe, NULL en cas d’erreur

Exemple en C :

struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "groupe_test",
                                "weechat.color.nicklist_group",
                                1);

Script (Python) :

# prototype
def nicklist_add_group(buffer: str, parent_group: str, name: str, color: str, visible: int) -> str: ...

# exemple
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "groupe_test",
    "weechat.color.nicklist_group", 1)

nicklist_search_group

Rechercher un groupe dans la liste des pseudos.

Prototype :

struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);

Paramètres :

buffer : pointeur vers le tampon
from_group : recherche depuis ce groupe seulement, si NULL, alors recherche dans toute la liste des pseudos
name : nom du groupes à rechercher

Valeur de retour :

pointeur vers le groupe trouvé, NULL s’il n’est pas trouvé

Exemple en C :

struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "groupe_test");

Script (Python) :

# prototype
def nicklist_search_group(buffer: str, from_group: str, name: str) -> str: ...

# exemple
group = weechat.nicklist_search_group(my_buffer, "", "groupe_test")

nicklist_add_nick

Ajouter un pseudo dans un groupe.

Prototype :

struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe
name : nom du pseudo
color : nom de l’option contenant la couleur pour le pseudo :
- une option WeeChat, par exemple weechat.color.nicklist_group
- une couleur avec un fond optionnel, par exemple yellow ou yellow,red
- nom d’une couleur de barre :
  - bar_fg : couleur de texte pour la barre
  - bar_delim : couleur des délimiteurs pour la barre
  - bar_bg : couleur de fond pour la barre
prefix : préfixe affiché avant le pseudo
prefix_color : nom de l’option contenant la couleur pour le préfixe :
- une option WeeChat, par exemple weechat.color.nicklist_group
- une couleur avec un fond optionnel, par exemple yellow ou yellow,red
- nom d’une couleur de barre :
  - bar_fg : couleur de texte pour la barre
  - bar_delim : couleur des délimiteurs pour la barre
  - bar_bg : couleur de fond pour la barre
visible :
- 1 : le pseudo est visible
- 0 : le pseudo est caché

Valeur de retour :

pointeur vers le nouveau pseudo, NULL en cas d’erreur

Exemple en 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) :

# prototype
def nicklist_add_nick(buffer: str, group: str, name: str, color: str, prefix: str, prefix_color: str, visible: int) -> str: ...

# exemple
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)

nicklist_search_nick

Rechercher un pseudo dans la liste des pseudos.

Prototype :

struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);

Paramètres :

buffer : pointeur vers le tampon
from_group : recherche depuis ce groupe seulement, si NULL, alors recherche dans toute la liste des pseudos
name : nom du pseudo à rechercher

Valeur de retour :

pointeur vers le pseudo trouvé, NULL s’il n’est pas trouvé

Exemple en C :

struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");

Script (Python) :

# prototype
def nicklist_search_nick(buffer: str, from_group: str, name: str) -> str: ...

# exemple
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")

nicklist_remove_group

Supprimer un groupe de la liste des pseudos.

Prototype :

void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe à supprimer (tous les sous-groupes/pseudos seront supprimés également)

Exemple en C :

weechat_nicklist_remove_group (my_buffer, my_group);

Script (Python) :

# prototype
def nicklist_remove_group(buffer: str, group: str) -> int: ...

# exemple
weechat.nicklist_remove_group(my_buffer, my_group)

nicklist_remove_nick

Supprimer un pseudo de la liste des pseudos.

Prototype :

void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);

Paramètres :

buffer : pointeur vers le tampon
nick : pointeur vers le pseudo à supprimer

Exemple en C :

weechat_nicklist_remove_nick (my_buffer, my_nick);

Script (Python) :

# prototype
def nicklist_remove_nick(buffer: str, nick: str) -> int: ...

# exemple
weechat.nicklist_remove_nick(my_buffer, my_nick)

nicklist_remove_all

Supprimer tous les groupes/pseudos de la liste des pseudos.

Prototype :

void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);

Paramètres :

buffer : pointeur vers le tampon

Exemple en C :

weechat_nicklist_remove_all (my_buffer);

Script (Python) :

# prototype
def nicklist_remove_all(buffer: str) -> int: ...

# exemple
weechat.nicklist_remove_all(my_buffer)

nicklist_get_next_item

WeeChat ≥ 0.3.7.

Retourner le prochain groupe ou pseudo de la liste des pseudos (utilisé principalement pour afficher la liste des pseudos).

Prototype :

void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers un pointeur sur le groupe
nick : pointeur vers un pointeur sur le pseudo

Exemple en C :

struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* pseudo */
        /* ... */
    }
    else
    {
        /* groupe */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}

Cette fonction n’est pas disponible dans l’API script.

nicklist_group_get_integer

WeeChat ≥ 0.3.4.

Retourner une valeur entière pour une propriété du groupe.

Prototype :

int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe
property : nom de la propriété :
- visible : 1 si le groupe est visible, sinon 0
- level : niveau du groupe (la racine est 0)

Valeur de retour :

valeur entière de la propriété

Exemple en C :

int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");

Script (Python) :

# prototype
def nicklist_group_get_integer(buffer: str, group: str, property: str) -> int: ...

# exemple
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")

nicklist_group_get_string

WeeChat ≥ 0.3.4.

Retourner la valeur d’une propriété du groupe sous forme de chaîne.

Prototype :

const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe
property : nom de la propriété :
- name : nom du groupe
- color : couleur du groupe dans la liste des pseudos

Valeur de retour :

valeur de la propriété, sous forme de chaîne

Exemple en C :

const char *color = weechat_nicklist_group_get_string (buffer, group, "color");

Script (Python) :

# prototype
def nicklist_group_get_string(buffer: str, group: str, property: str) -> str: ...

# exemple
color = weechat.nicklist_group_get_string(buffer, group, "color")

nicklist_group_get_pointer

WeeChat ≥ 0.3.4.

Retourner la valeur d’une propriété du groupe sous forme d’un pointeur.

Prototype :

void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe
property : nom de la propriété :
- parent : pointeur vers le groupe parent

Valeur de retour :

valeur de la propriété, sous forme de pointeur

Exemple en C :

struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");

Script (Python) :

# prototype
def nicklist_group_get_pointer(buffer: str, group: str, property: str) -> str: ...

# exemple
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")

nicklist_group_set

WeeChat ≥ 0.3.4.

Affecter une valeur à une propriété d’un groupe.

Prototype :

void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);

Paramètres :

buffer : pointeur vers le tampon
group : pointeur vers le groupe
property : nom de la propriété (voir le tableau ci-dessous)
value : nouvelle valeur pour la propriété

Propriétés :

Nom

Valeur

Description

color

nom d’option de couleur WeeChat

Voir le paramètre "color" de la fonction nicklist_add_group.

visible

"0", "1"

"0" = groupe caché, "1" = groupe visible.

Exemples en C :

/* changer la couleur du groupe en "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* changer la couleur du groupe en jaune */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* cacher le groupe dans la liste des pseudos */
weechat_nicklist_group_set (buffer, group, "visible", "0");

Script (Python) :

# prototype
def nicklist_group_set(buffer: str, group: str, property: str, value: str) -> int: ...

# exemples

# changer la couleur du groupe en "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# changer la couleur du groupe en jaune
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# cacher le groupe dans la liste des pseudos
weechat.nicklist_group_set(buffer, group, "visible", "0")

nicklist_nick_get_integer

WeeChat ≥ 0.3.4.

Retourner une valeur entière pour une propriété du pseudo.

Prototype :

int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);

Paramètres :

buffer : pointeur vers le tampon
nick : pointeur vers le pseudo
property : nom de la propriété :
- visible : 1 si le pseudo est visible, sinon 0

Valeur de retour :

valeur entière de la propriété

Exemple en C :

int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");

Script (Python) :

# prototype
def nicklist_nick_get_integer(buffer: str, nick: str, property: str) -> int: ...

# exemple
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")

nicklist_nick_get_string

WeeChat ≥ 0.3.4.

Retourner la valeur d’une propriété du pseudo sous forme de chaîne.

Prototype :

const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);

Paramètres :

buffer : pointeur vers le tampon
nick : pointeur vers le pseudo
property : nom de la propriété :
- name : nom du pseudo
- color : couleur du pseudo dans la liste des pseudos
- prefix : préfixe du pseudo
- prefix_color : couleur du préfixe dans la liste des pseudos

Valeur de retour :

valeur de la propriété, sous forme de chaîne

Exemple en C :

const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");

Script (Python) :

# prototype
def nicklist_nick_get_string(buffer: str, nick: str, property: str) -> str: ...

# exemple
color = weechat.nicklist_nick_get_string(buffer, nick, "color")

nicklist_nick_get_pointer

WeeChat ≥ 0.3.4.

Retourner la valeur d’une propriété du pseudo sous forme d’un pointeur.

Prototype :

void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);

Paramètres :

buffer : pointeur vers le tampon
nick : pointeur vers le pseudo
property : nom de la propriété :
- group : pointeur vers le groupe contenant ce pseudo

Valeur de retour :

valeur de la propriété, sous forme de pointeur

Exemple en C :

struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");

Script (Python) :

# prototype
def nicklist_nick_get_pointer(buffer: str, nick: str, property: str) -> str: ...

# exemple
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")

nicklist_nick_set

WeeChat ≥ 0.3.4.

Affecter une valeur à une propriété d’un pseudo.

Prototype :

void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);

Paramètres :

buffer : pointeur vers le tampon
nick : pointeur vers le pseudo
property : nom de la propriété (voir le tableau ci-dessous)
value : nouvelle valeur pour la propriété

Propriétés :

Nom

Valeur

Description

color

nom d’option de couleur WeeChat

Voir le paramètre "color" de la fonction nicklist_add_nick.

prefix

toute chaîne

Préfixe du pseudo.

prefix_color

nom d’option de couleur WeeChat

Voir le paramètre "prefix_color" de la fonction nicklist_add_nick.

visible

"0", "1"

"0" = pseudo caché, "1" = pseudo visible.

Exemples en C :

/* changer la couleur du pseudo en cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* changer le préfixe en "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* changer la couleur du préfixe en jaune */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* cacher le pseudo dans la liste des pseudos */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");

Script (Python) :

# prototype
def nicklist_nick_set(buffer: str, nick: str, property: str, value: str) -> int: ...

# exemples

# changer la couleur du pseudo en cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# changer le préfixe en "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# changer la couleur du préfixe en jaune
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# cacher le pseudo dans la liste des pseudos
weechat.nicklist_nick_set(buffer, nick, "visible", "0")

3.18. Barres

Fonctions pour les barres.

bar_item_search

Rechercher un objet de barre.

Prototype :

struct t_gui_bar_item *weechat_bar_item_search (const char *name);

Paramètres :

name : nom de l’objet de barre

Valeur de retour :

pointeur vers l’objet de barre trouvé, NULL s’il n’a pas été trouvé

Exemple en C :

struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");

Script (Python) :

# prototype
def bar_item_search(name: str) -> str: ...

# exemple
bar_item = weechat.bar_item_search("myitem")

bar_item_new

Mis à jour dans la 0.4.2, 1.5.

Créer un nouvel objet de barre.

Prototype :

struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             const void *build_callback_pointer,
                                             void *build_callback_data);

Paramètres :

name : nom de l’objet de barre
build_callback : fonction appelée lorsque l’objet est construit, paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_gui_bar_item *item : pointeur vers l’objet de barre
- struct t_gui_window *window : pointeur vers la fenêtre (NULL lors d’un appel pour une barre "root")
- struct t_gui_buffer *buffer : tampon affiché dans la fenêtre (si la fenêtre est NULL alors c’est le tampon courant) ou tampon passé dans l’objet de barre avec la syntaxe : "@buffer:item" (WeeChat ≥ 0.4.2)
- struct t_hashtable *extra_info : toujours NULL (le paramètre est réservé pour une version future) (WeeChat ≥ 0.4.2)
- valeur de retour : contenu de l’objet de barre
build_callback_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
build_callback_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque l’objet de barre est supprimé

Valeur de retour :

pointeur vers le nouvel objet de barre, NULL en cas d’erreur

Exemple en C :

char *
my_build_callback (const void *pointer, void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("mon contenu");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL, NULL);

Script (Python) :

Pour la compatibilité avec les versions ≤ 0.4.1, la fonction de rappel par défaut a seulement 3 paramètres : data, item et window (pas de buffer et extra_info).
Pour utiliser la fonction de rappel avec tous les paramètres, vous devez ajouter "(extra)" avant le nom, voir l’exemple ci-dessous (supporté seulement dans WeeChat ≥ 0.4.2).

# prototype
def bar_item_new(name: str, build_callback: str, build_callback_data: str) -> str: ...

# exemple (fonction de rappel sans "buffer" et "extra_info")
def my_build_callback(data: str, item: str, window: str) -> str:
    return "mon contenu"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# exemple (fonction de rappel avec tous les paramètres, pour WeeChat ≥ 0.4.2)
def my_build_callback2(data: str, item: str, window: str, buffer: str, extra_info: Dict[str, str]) -> str:
    return "mon contenu"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat ≥ 0.4.2

bar_item_update

Mettre à jour le contenu d’un objet de barre, en appelant sa fonction de rappel de construction.

Prototype :

void weechat_bar_item_update (const char *name);

Paramètres :

name : nom de l’objet de barre

Exemple en C :

weechat_bar_item_update ("myobjet");

Script (Python) :

# prototype
def bar_item_update(name: str) -> int: ...

# exemple
weechat.bar_item_update("myitem")

bar_item_remove

Supprimer un objet de barre.

Prototype :

void weechat_bar_item_remove (struct t_gui_bar_item *item);

Paramètres :

item : pointeur vers l’objet de barre

Exemple en C :

weechat_bar_item_remove (&my_item);

Script (Python) :

# prototype
def bar_item_remove(item: str) -> int: ...

# exemple
weechat.bar_item_remove(myitem)

bar_search

Rechercher une barre.

Prototype :

struct t_gui_bar *weechat_bar_search (const char *name);

Paramètres :

name : nom de la barre

Valeur de retour :

pointeur vers la barre trouvée, NULL si elle n’est pas trouvée

Exemple en C :

struct t_gui_bar *bar = weechat_bar_search ("my_barre");

Script (Python) :

# prototype
def bar_search(name: str) -> str: ...

# exemple
bar = weechat.bar_search("mybar")

bar_new

Mis à jour dans la 2.9, 4.0.0.

Créer une nouvelle barre.

Prototype :

struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *color_bg_inactive,
                                   const char *separator,
                                   const char *items);

Paramètres :

name : nom de la barre
hidden :
- on : la barre est cachée
- off : la barre est visible
priority : priorité de la barre (nombre entier)
type :
- root : la barre est affichée une seule fois, hors des fenêtres
- window : la barre est affichée dans chaque fenêtre
condition : condition pour afficher la barre :
- active : la barre est affichée dans la fenêtre active seulement
- inactive : la barre est affichée dans les fenêtres inactives seulement
- nicklist : la barre est affichée dans les fenêtres possédant une liste des pseudos
- expression évaluée : voir le Guide utilisateur WeeChat / Conditions de barres ^↗
position : top (en haut), bottom (en bas), left (à gauche) ou right (à droite)
filling_top_bottom :
- horizontal : les objets sont remplis horizontalement (avec un espace entre chaque objet)
- vertical : les objets sont remplis verticalement (avec une nouvelle ligne entre chaque objet)
- columns_horizontal : les objets sont remplis horizontalement, affichés sous forme de colonnes
- columns_vertical : les objets sont remplis verticalement, affichés sous forme de colonnes
filling_left_right :
- horizontal : les objets sont remplis horizontalement (avec un espace entre chaque objet)
- vertical : les objets sont remplis verticalement (avec une nouvelle ligne entre chaque objet)
- columns_horizontal : les objets sont remplis horizontalement, affichés sous forme de colonnes
- columns_vertical : les objets sont remplis verticalement, affichés sous forme de colonnes
size : taille de la barre en caractères (0 indique une taille automatique)
size_max : taille maximum de la barre (0 pour pas de maximum)
color_fg : couleur du texte dans la barre
color_delim : couleur pour les délimiteurs dans la barre
color_bg : couleur de fond pour la barre
color_bg_inactive : couleur de fond pour une barre de type "window" qui n’est pas affichée dans la fenêtre active
separator :
- on : la barre a un séparateur avec les autres fenêtres/barres
- off : pas de séparateur
items : liste des objets dans la barre, séparés par une virgule (espace entre les objets), ou "+" (objets collés)

Valeur de retour :

pointeur vers la nouvelle barre, NULL en cas d’erreur

Depuis la version 4.0.0, si la barre existe déjà, WeeChat définit les valeurs reçues comme valeurs par défaut des options de la barre et retourne le pointeur vers la barre au lieu de NULL.

Exemple en C :

struct t_gui_bar *my_bar = weechat_bar_new (
    "mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "darkgray", "off",
    "time,buffer_number+buffer_name");

Script (Python) :

# prototype
def bar_new(name: str, hidden: str, priority: str, type: str, condition: str, position: str,
            filling_top_bottom: str, filling_left_right: str, size: str, size_max: str,
            color_fg: str, color_delim: str, color_bg: str, color_bg_inactive: str,
            separator: str, items: str) -> str: ...

# exemple
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "darkgray", "off", "time,buffer_number+buffer_name")

Avec WeeChat ≥ 2.9, en Ruby, les 4 couleurs (color_fg, color_delim, color_bg, color_bg_inactive) doivent être données dans un tableau de 4 chaînes de caractères (en raison d’une limitation de Ruby à 15 paramètres par fonction), voir le Guide pour scripts WeeChat ^↗ pour plus d’infos.

bar_set

Affecter une nouvelle valeur pour une propriété de la barre.

Prototype :

int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);

Paramètres :

bar : pointeur vers la barre
property : name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items (voir bar_new)
value : nouvelle valeur pour la propriété

Valeur de retour :

1 si la valeur a été affectée, 0 en cas d’erreur

Exemple en C :

weechat_bar_set (my_bar, "position", "bottom");

Script (Python) :

# prototype
def bar_set(bar: str, property: str, value: str) -> int: ...

# exemple
weechat.bar_set(my_bar, "position", "bottom")

bar_update

Mettre à jour le contenu d’une barre à l’écran.

Prototype :

void weechat_bar_update (const char *name);

Paramètres :

name : nom de la barre

Exemple en C :

weechat_bar_update ("mybar");

Script (Python) :

# prototype
def bar_update(name: str) -> int: ...

# exemple
weechat.bar_update("mybar")

bar_remove

Supprimer une barre.

Prototype :

void weechat_bar_remove (struct t_gui_bar *bar);

Paramètres :

bar : pointeur vers la barre

Exemple en C :

weechat_bar_remove (my_bar);

Script (Python) :

# prototype
def bar_remove(bar: str) -> int: ...

# exemple
weechat.bar_remove(my_bar)

3.19. Commandes

Fonctions pour exécuter des commandes WeeChat.

command

Mis à jour dans la 1.1.

Exécuter une commande ou envoyer du texte au tampon.

Prototype :

int weechat_command (struct t_gui_buffer *buffer, const char *command);

Paramètres :

buffer : pointeur vers le tampon (la commande est exécutée sur ce tampon, NULL pour le tampon courant)
command : commande à exécuter (si elle commence par "/"), ou texte à envoyer au tampon

Valeur de retour (WeeChat ≥ 1.1) :

WEECHAT_RC_OK si ok
WEECHAT_RC_ERROR si erreur

Exemple en C :

int rc;
rc = weechat_command (weechat_buffer_search ("irc", "libera.#weechat"),
                      "/whois FlashCode");

Script (Python) :

# prototype
def command(buffer: str, command: str) -> int: ...

# exemple
rc = weechat.command(weechat.buffer_search("irc", "libera.#weechat"), "/whois FlashCode")

command_options

WeeChat ≥ 2.5.

Exécuter une commande ou envoyer du texte au tampon avec des options.

Prototype :

int weechat_command_options (struct t_gui_buffer *buffer, const char *command,
                             struct t_hashtable *options);

Paramètres :

buffer : pointeur vers le tampon (la commande est exécutée sur ce tampon, NULL pour le tampon courant)
command : commande à exécuter (si elle commence par "/"), ou texte à envoyer au tampon
options : table de hachage avec des options (les clés et valeurs doivent être des chaînes) (peut être NULL) :
- commands : une liste de commandes autorisées pendant l’appel, séparées par des virgules ; voir la fonction string_match_list pour le format
- delay : délai pour exécuter la commande, en millisecondes

Valeur de retour :

WEECHAT_RC_OK si ok
WEECHAT_RC_ERROR si erreur

Exemple en C :

/* autoriser toute commande sauf /exec, lancer la commande dans 2 secondes */
int rc;
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
weechat_hashtable_set (options, "commands", "*,!exec");
weechat_hashtable_set (options, "delay", "2000");
rc = weechat_command_options (NULL, "/une_commande paramètres", options);

Script (Python) :

# prototype
def command_options(buffer: str, command: str, options: Dict[str, str]) -> int: ...

# exemple : autoriser toute commande sauf /exec
rc = weechat.command("", "/une_commande paramètres", {"commands": "*,!exec"})

3.20. Completion

Fonctions pour compléter une ligne de commande.

completion_new

WeeChat ≥ 2.9.

Créer une complétion.

Prototype :

struct t_gui_completion *weechat_completion_new (struct t_gui_buffer *buffer);

Paramètres :

buffer : pointeur vers le tampon

Valeur de retour :

pointer to new completion

Exemple en C :

struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());

Script (Python) :

# prototype
def completion_new(buffer: str) -> str: ...

# exemple
completion = weechat.completion_new(weechat.buffer_search_main())

completion_search

WeeChat ≥ 2.9.

Chercher les mots possibles à une position donnée d’une chaîne, dans le contexte de la complétion.

Prototype :

int weechat_completion_search (struct t_gui_completion *completion, const char *data,
                               int position, int direction);

Paramètres :

completion : pointeur vers la complétion
data : la chaîne à compléter
position : index du caractère dans la chaîne à compléter (commence à 0)
direction : 1 pour la complétion suivante, -1 pour la complétion précédente

Valeur de retour :

1 si OK, 0 si erreur

Exemple en C :

struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());
if (weechat_completion_search (completion, "/help filt", 10, 1))
{
    /* ... */
}

Script (Python) :

# prototype
def completion_search(completion: str, data: str, position: int, direction: int) -> int: ...

# exemple
completion = weechat.completion_new(weechat.buffer_search_main())
if weechat.completion_search(completion, "/help filt", 10, 1):
    # ...

completion_get_string

WeeChat ≥ 2.9.

Retourner la valeur d’une propriété de la complétion sous forme de chaîne.

Prototype :

const char *weechat_completion_get_string (struct t_gui_completion *completion,
                                           const char *property);

Paramètres :

completion : pointeur vers la complétion
property : nom de la propriété :
- base_command : commande utilisée pour la complétion
- base_word : le mot qui va être complété
- args : paramètres de la commande (incluant le mot de base "base_word")

Exemple en C :

int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* récupère les paramètres de la commande */
    const char *args = weechat_completion_get_string (completion, "args");

    /* complétion selon les paramètres */
    /* ... */

    return WEECHAT_RC_OK;
}

Script (Python) :

# prototype
def completion_get_string(completion: str, property: str) -> str: ...

# exemple
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    # récupère les paramètres de la commande
    args = weechat.completion_get_string(completion, "args")
    # complétion selon les paramètres
    # ...
    return weechat.WEECHAT_RC_OK

completion_list_add

WeeChat ≥ 2.9.

Ajouter un mot pour une complétion.

Prototype :

void weechat_completion_list_add (struct t_gui_completion *completion,
                                  const char *word,
                                  int nick_completion,
                                  const char *where);

Paramètres :

completion : pointeur vers la complétion
word : mot à ajouter
nick_completion : 1 si le mot est un pseudo, sinon 0
where : position où sera inséré le mot dans la liste :
- WEECHAT_LIST_POS_SORT : n’importe où, pour maintenir la liste triée
- WEECHAT_LIST_POS_BEGINNING : au début de la liste
- WEECHAT_LIST_POS_END : à la fin de la liste

Exemple en C : voir hook_completion.

Script (Python) :

# prototype
def completion_list_add(completion: str, word: str, nick_completion: int, where: str) -> int: ...

# exemple : voir la fonction hook_completion

completion_free

WeeChat ≥ 2.9.

Supprimer une complétion.

Prototype :

void weechat_completion_free (struct t_gui_completion *completion);

Paramètres :

completion : pointeur vers la complétion

Exemple en C :

weechat_completion_free (completion);

Script (Python) :

# prototype
def completion_free(completion: str) -> int: ...

# exemple
weechat.completion_free(completion)

3.21. Réseau

Fonctions pour le réseau.

network_pass_proxy

Établir une connexion/authentification avec un proxy.

Cette fonction est bloquante sur l’appel à connect(), donc elle doit être appelée sans un processus issu d’un "fork", pour ne pas bloquer WeeChat.

Prototype :

int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);

Paramètres :

proxy : nom du proxy à utiliser
sock : socket à utiliser
address : adresse (nom de machine ou adresse IP)
port : port

Valeur de retour :

1 si la connexion est ok, 0 en cas d’erreur

Exemple en C :

if (weechat_network_pass_proxy ("mon_proxy", sock, "irc.libera.chat", 6667))
{
    /* OK */
}
else
{
    /* erreur */
}

Cette fonction n’est pas disponible dans l’API script.

network_connect_to

Mis à jour dans la 0.4.3.

Établir une connexion à une machine distante.

Cette fonction est bloquante sur l’appel à connect(), donc elle doit être appelée sans un processus issu d’un "fork", pour ne pas bloquer WeeChat.

Prototype :

int weechat_network_connect_to (const char *proxy,
                                struct sockaddr *address,
                                socklen_t address_length);

Paramètres :

proxy : nom du proxy à utiliser
address : adresse où se connecter (avec le port)
address_length : longueur du paramètre address

Valeur de retour :

numéro de socket (≥ 0) si la connexion est OK, -1 en cas d’erreur

Exemple en C :

struct sockaddr *addr;
socklen_t length;
int sock;

/* allouer/définir l'adresse et le port dans 'addr', définir 'length' */
/* ... */

sock = weechat_network_connect_to (NULL, addr, length);
if (sock >= 0)
{
    /* OK */
}
else
{
    /* erreur */
}

Cette fonction n’est pas disponible dans l’API script.

3.22. Infos

Fonctions pour obtenir des informations.

info_get

Mis à jour dans la 2.5.

Retourner une information, sous forme de chaîne, de WeeChat ou d’une extension.

Prototype :

char *weechat_info_get (const char *info_name, const char *arguments);

Paramètres :

info_name : nom de l’information à lire (voir le tableau ci-dessous)
arguments : paramètres pour l’information demandée (optionnels, NULL si aucun paramètre n’est nécessaire)

Valeur de retour :

chaîne avec l’information demandée, NULL en cas d’erreur (doit être supprimée par un appel à "free" après utilisation)

Avec WeeChat ≥ 2.5, la valeur retournée est une chaîne allouée (avec WeeChat ≤ 2.4, il s’agissait d’un pointeur vers une chaîne statique).

Infos :

Extension Nom Description Paramètres

fifo

fifo_filename

nom du tube FIFO

guile

guile_eval

évaluation de code source

code source à exécuter

guile

guile_interpreter

nom de l’interpréteur utilisé

guile

guile_version

version de l’interpréteur utilisé

irc

irc_buffer

retourne le pointeur vers le tampon pour un serveur/canal/pseudo IRC

serveur,canal,pseudo (canal et pseudo sont optionnels)

irc

irc_is_channel

1 si la chaîne est un nom de canal IRC valide pour le serveur

serveur,canal (le serveur est optionnel)

irc

irc_is_message_ignored

1 si le pseudo est ignoré (le message n’est pas affiché)

serveur,message (message est le message brut IRC)

irc

irc_is_nick

1 si la chaîne est un pseudo IRC valide

serveur,pseudo (le serveur est optionnel)

irc

irc_nick

retourne le pseudo utilisé actuellement sur un serveur

nom de serveur

irc

irc_nick_color

retourne le code couleur du pseudo (obsolète depuis la version 1.5, remplacé par "nick_color")

pseudo

irc

irc_nick_color_name

retourne le nom de la couleur du pseudo (obsolète depuis la version 1.5, remplacé par "nick_color_name")

pseudo

irc

irc_nick_from_host

retourne le pseudo à partir d’un host IRC

host IRC (comme :pseudo!nom@serveur.com)

irc

irc_server_cap

1 si la capacité est activée dans le serveur

serveur,capacité

irc

irc_server_cap_value

valeur de la capacité, si activée dans le serveur

serveur,capacité

irc

irc_server_isupport

1 si le serveur supporte cette fonctionnalité (du message IRC 005)

serveur,fonctionnalité

irc

irc_server_isupport_value

valeur de la fonctionnalité, si supportée par le serveur (du message IRC 005)

serveur,fonctionnalité

logger

logger_log_file

chemin vers le fichier de log pour le tampon

pointeur vers un tampon ("0x12345678") ou nom complet de tampon ("irc.libera.#weechat")

lua

lua_eval

évaluation de code source

code source à exécuter

lua

lua_interpreter

nom de l’interpréteur utilisé

lua

lua_version

version de l’interpréteur utilisé

perl

perl_eval

évaluation de code source

code source à exécuter

perl

perl_interpreter

nom de l’interpréteur utilisé

perl

perl_version

version de l’interpréteur utilisé

php

php_eval

évaluation de code source

code source à exécuter

php

php_interpreter

nom de l’interpréteur utilisé

php

php_version

version de l’interpréteur utilisé

python

python_eval

évaluation de code source

code source à exécuter

python

python_interpreter

nom de l’interpréteur utilisé

python

python_version

version de l’interpréteur utilisé

relay

relay_client_count

nombre de clients pour le relai

protocole,statut (les deux sont optionnels, pour chaque paramètre "*" signifie tous ; protocoles : irc, weechat ; statuts : connecting, waiting_auth, connected, auth_failed, disconnected)

ruby

ruby_eval

évaluation de code source

code source à exécuter

ruby

ruby_interpreter

nom de l’interpréteur utilisé

ruby

ruby_version

version de l’interpréteur utilisé

spell

spell_dict

liste de dictionnaires (séparés par des virgules) utilisés sur le tampon

pointeur vers un tampon ("0x12345678") ou nom complet de tampon ("irc.libera.#weechat")

tcl

tcl_eval

évaluation de code source

code source à exécuter

tcl

tcl_interpreter

nom de l’interpréteur utilisé

tcl

tcl_version

version de l’interpréteur utilisé

weechat

auto_connect

1 si la connexion automatique aux serveurs est activée, 0 si elle a été désactivée par l’utilisateur (option "-a" ou "--no-connect")

weechat

auto_load_scripts

1 si la les scripts sont automatiquement charés, 0 si l’auto-chargement a été désactivé par l’utilisateur (option "-s" ou "--no-script")

weechat

buffer

pointeur vers le tampon

nom complet du tampon

weechat

charset_internal

charset interne à WeeChat

weechat

charset_terminal

charset du terminal

weechat

color_ansi_regex

expression régulière POSIX étendue pour chercher les codes ANSI échappés

weechat

color_rgb2term

couleur RGB convertie en couleur du terminal (0-255)

rgb,limite (la limite est optionnelle et vaut 256 par défaut)

weechat

color_term2rgb

couleur du terminal (0-255) convertie en couleur RGB

couleur (couleur du terminal : 0-255)

weechat

cursor_mode

1 si le mode curseur est activé

weechat

date

date/heure de compilation de WeeChat

weechat

dir_separator

séparateur de répertoire

weechat

filters_enabled

1 si les filtres sont activés

weechat

inactivity

inactivité du clavier (secondes)

weechat

locale

locale utilisée pour la traduction des messages

weechat

mouse

1 si la souris est activée

weechat

nick_color

retourne le code couleur du pseudo

pseudo;couleurs (couleurs est une liste de couleurs facultative, séparée par des virgules ; un fond est autorisé pour la couleur avec le format texte:fond ; si couleurs est présent, les options WeeChat avec les couleurs de pseudos et couleurs forcées de pseudos sons ignorées)

weechat

nick_color_ignore_case

retourne le code couleur du pseudo, en ignorant la casse

pseudo;intervalle;couleurs (l’intervalle est un nombre de caractères (voir la fonction strcasecmp_range, 0 = convertir en minuscules sans utiliser d’intervalle), couleurs est une liste de couleurs facultative, séparée par des virgules ; un fond est autorisé pour la couleur avec le format texte:fond ; si couleurs est présent, les options WeeChat avec les couleurs de pseudos et couleurs forcées de pseudos sons ignorées)

weechat

nick_color_name

retourne le nom de la couleur du pseudo

weechat

nick_color_name_ignore_case

retourne le nom de la couleur du pseudo, en ignorant la casse

weechat

pid

PID (ID de processus) de WeeChat

weechat

term_color_pairs

nombre de paires de couleurs supportées dans le terminal

weechat

term_colors

nombre de couleurs supportées dans le terminal

weechat

term_height

hauteur du terminal

weechat

term_width

largeur du terminal

weechat

totp_generate

générer un mot de passe à usage unique basé sur le temps (TOTP)

secret (en base32), horodatage (optionnel, heure courante par défaut), nombre de chiffres (optionnel, entre 4 et 10, 6 par défaut)

weechat

totp_validate

valider un mot de passe à usage unique basé sur le temps (TOTP) : 1 si le TOTP est correct, sinon 0

secret (en base32), mot de passe à usage unique, horodatage (optionnel, heure courante par défaut), nombre de mots de passe avant/après à tester (optionnel, 0 par défaut)

weechat

uptime

Durée de fonctionnement de WeeChat (format : "jours:hh:mm:ss")

"days" (nombre de jours) ou "seconds" (nombre de secondes) (optionnel)

weechat

uptime_current

Durée de fonctionnement de WeeChat pour le processus actuel seulement (les mises à jour par la commande /upgrade sont ignorées) (format : "jours:hh:mm:ss")

"days" (nombre de jours) ou "seconds" (nombre de secondes) (optionnel)

weechat

version

version de WeeChat

weechat

version_git

version git de WeeChat (sortie de la commande "git describe" pour une version de développement seulement, vide pour une version stable)

weechat

version_number

version de WeeChat (sous forme de nombre)

version (optionnelle, par défaut la version du WeeChat en cours d’exécution est retournée)

weechat

weechat_cache_dir

répertoire du cache WeeChat

weechat

weechat_config_dir

répertoire de la configuration WeeChat

weechat

weechat_daemon

1 si WeeChat tourne en mode démon (sans interface, en tâche de fond)

weechat

weechat_data_dir

répertoire des données WeeChat

weechat

weechat_dir

répertoire de WeeChat (*obsolète depuis la version 3.2, remplacé par "weechat_config_dir", "weechat_data_dir", "weechat_cache_dir" et "weechat_runtime_dir")

weechat

weechat_headless

1 si WeeChat tourne sans interface

weechat

weechat_libdir

répertoire "lib" de WeeChat

weechat

weechat_localedir

répertoire "locale" de WeeChat

weechat

weechat_runtime_dir

répertoire de "runtime" WeeChat

weechat

weechat_sharedir

répertoire "share" de WeeChat

weechat

weechat_site

site WeeChat

weechat

weechat_site_download

site WeeChat, page de téléchargement

weechat

weechat_upgrading

1 si WeeChat est en cours de mise à jour (commande /upgrade)

Exemple en C :

char *version = weechat_info_get ("version", NULL);
char *date = weechat_info_get ("date", NULL);
weechat_printf (NULL, "La version de WeeChat est : %s (compilée le %s)",
                version, date);
if (version)
    free (version);
if (date)
    free (date);

weechat_config_dir = weechat_info_get ("weechat_config_dir", NULL);
weechat_printf (NULL, "Le répertoire de config WeeChat est : %s", weechat_config_dir);
if (weechat_config_dir)
    free (weechat_config_dir);

Script (Python) :

# prototype
def info_get(info_name: str, arguments: str) -> str: ...

# exemple
weechat.prnt("", "La version de WeeChat est : %s (compilée le %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "Le répertoire de config WeeChat est : %s" % weechat.info_get("weechat_config_dir", ""))

info_get_hashtable

WeeChat ≥ 0.3.4.

Retourner une information, sous forme de table de hachage, de WeeChat ou d’une extension.

Prototype :

struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);

Paramètres :

info_name : nom de l’information à lire (voir le tableau ci-dessous)
hashtable : table de hachage avec les paramètres (dépendant de l’information demandée) (optionnel, NULL si aucun paramètre n’est nécessaire)

Valeur de retour :

table de hachage avec l’information demandée, NULL en cas d’erreur (doit être supprimée par un appel à hashtable_free après utilisation)

Infos :

Extension

Nom

Description

Table de hachage (entrée)

Table de hachage (sortie)

irc

irc_message_parse

analyse un message IRC

"message" : message IRC, "server" : nom du serveur (optionnel)

"tags" : étiquettes, "tag_xxx" : valeur de l’étiquette "xxx" sans échappements (une clé par étiquette), "message_without_tags" : message sans les étiquettes, "nick" : pseudo, "user" : nom d’utilisateur, "host" : nom d’hôte, "command" : commande, "channel" : canal, "arguments" : paramètres (inclut le canal), "text" : texte (par exemple message utilisateur), "param1" … "paramN" : paramètres de la commande, "num_params" : nombre de paramètres dans la commande, "pos_command" : index de "command" dans le message ("-1" si "command" n’a pas été trouvé), "pos_arguments" : index de "arguments" dans le message ("-1" si "arguments" n’a pas été trouvé), "pos_channel" : index de "channel" dans le message ("-1" si "channel" n’a pas été trouvé), "pos_text" : index de "text" dans le message ("-1" si "text" n’a pas été trouvé)

irc

irc_message_split

découper un message IRC (pour tenir dans les 512 octets par défaut)

"message" : message IRC, "server" : nom du serveur (optionnel)

"msg1" … "msgN" : messages à envoyer (sans le "\r\n" final), "args1" … "argsN" : paramètres des messages, "count" : nombre de messages

weechat

focus_info

obtenir l’information de focus

"x" : coordonnée x (chaîne avec un entier >= 0), "y" : coordonnée y (chaîne avec un entier >= 0)

voir la fonction hook_focus dans la Référence API extension

weechat

secured_data

données sécurisées

données sécurisées : noms et valeurs (attention : les valeurs sont des données sensibles : il ne faut PAS les afficher/logger)

Exemple en C :

struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (
        hashtable_in,
        "message",
        "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :Hello world!");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * maintenant hashtable_out a les clés/valeurs suivantes :
     *   "tags"                : "time=2015-06-27T16:40:35.000Z;tag2=value\\sspace"
     *   "tag_time"            : "2015-06-27T16:40:35.000Z"
     *   "tag_tag2"            : "value space"
     *   "message_without_tags": ":nick!user@host PRIVMSG #weechat :Hello world!"
     *   "nick"                : "nick"
     "   "user"                : "user"
     *   "host"                : "nick!user@host"
     *   "command"             : "PRIVMSG"
     *   "channel"             : "#weechat"
     *   "arguments"           : "#weechat :Hello world!"
     *   "text"                : "Hello world!"
     *   "param1"              : "#weechat"
     *   "param2"              : "Hello world!"
     *   "num_params"          : "2"
     *   "pos_command"         : "65"
     *   "pos_arguments"       : "73"
     *   "pos_channel"         : "73"
     *   "pos_text"            : "83"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}

Voir le Guide pour scripts WeeChat / Analyser un message ^↗ pour plus d’infos sur la sortie de "irc_message_parse".

Script (Python) :

# prototype
def info_get_hashtable(info_name: str, dict_in: Dict[str, str]) -> Dict[str, str]: ...

# exemple
dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message ici"}
weechat.prnt("", "message analysé : %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))

3.23. Infolists

Une "infolist" est une liste composée d’objets ("items"). Chaque objet contient des variables.

Par exemple, l’infolist "irc_server" a N objets (N est le nombre de serveurs IRC définis). Pour chaque objet, il y a des variables, comme "name", "buffer", "is_connected", …

Chaque variable a un type et une valeur. Les types possibles sont :

integer : nombre entier
string : chaîne de caractères
pointer : pointeur
buffer : tampon avec une taille fixe, peut contenir n’importe quel type de données
time : date/heure

infolist_new

Créer une "infolist".

Prototype :

struct t_infolist *weechat_infolist_new ();

Valeur de retour :

pointeur vers la nouvelle "infolist"

Exemple en C :

struct t_infolist *infolist = weechat_infolist_new ();

Script (Python) :

# prototype
def infolist_new() -> str: ...

# exemple
infolist = weechat.infolist_new()

infolist_new_item

Ajouter un objet dans l’infolist.

Prototype :

struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Valeur de retour :

pointeur vers le nouvel objet

Exemple en C :

struct t_infolist_item *item = weechat_infolist_new_item (infolist);

Script (Python) :

# prototype
def infolist_new_item(infolist: str) -> str: ...

# exemple
item = weechat.infolist_new_item(infolist)

infolist_new_var_integer

Ajouter une variable de type "integer" dans l’objet de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);

Paramètres :

item : pointeur vers l’objet de l’infolist
name : nom de la variable
value : valeur

Valeur de retour :

pointeur vers la nouvelle variable

Exemple en C :

struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "mon_entier",
                                                               123);

Script (Python) :

# prototype
def infolist_new_var_integer(item: str, name: str, value: int) -> str: ...

# exemple
var = weechat.infolist_new_var_integer(item, "mon_entier", 123)

infolist_new_var_string

Ajouter une variable de type "string" dans l’objet de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);

Paramètres :

item : pointeur vers l’objet de l’infolist
name : nom de la variable
value : valeur

Valeur de retour :

pointeur vers la nouvelle variable

Exemple en C :

struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "ma_chaine",
                                                              "valeur");

Script (Python) :

# prototype
def infolist_new_var_string(item: str, name: str, value: str) -> str: ...

# exemple
var = weechat.infolist_new_var_string(item, "ma_chaine", "valeur")

infolist_new_var_pointer

Ajouter une variable de type "pointer" dans l’objet de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);

Paramètres :

item : pointeur vers l’objet de l’infolist
name : nom de la variable
pointer : pointeur

Valeur de retour :

pointeur vers la nouvelle variable

Exemple en C :

struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "mon_pointeur",
                                                               &pointer);

Script (Python) :

# prototype
def infolist_new_var_pointer(item: str, name: str, pointer: str) -> str: ...

# exemple
var = weechat.infolist_new_var_pointer(item, "mon_pointeur", pointer)

infolist_new_var_buffer

Ajouter une variable de type "buffer" dans l’objet de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);

Paramètres :

item : pointeur vers l’objet de l’infolist
name : nom de la variable
pointer : pointeur
size : taille du tampon

Valeur de retour :

pointeur vers la nouvelle variable

Exemple en C :

char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                              "mon_buffer",
                                                              buffer,
                                                              sizeof (buffer));

Cette fonction n’est pas disponible dans l’API script.

infolist_new_var_time

Ajouter une variable de type "time" dans l’objet de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);

Paramètres :

item : pointeur vers l’objet de l’infolist
name : nom de la variable
time : valeur

Valeur de retour :

pointeur vers la nouvelle variable

Exemple en C :

struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                            "mon_time",
                                                            time (NULL));

Script (Python) :

# prototype
def infolist_new_var_time(item: str, name: str, time: int) -> str: ...

# exemple
var = weechat.infolist_new_var_time(item, "mon_time", int(time.time()))

infolist_get

Retourner une "infolist" de WeeChat ou d’une extension.

Le contenu d’une infolist est une duplication des données réelles. Donc si vous demandez une infolist avec beaucoup de données (comme "buffer_lines"), WeeChat allouera de la mémoire pour dupliquer toutes les données, et cela peut prendre du temps.
Au lieu d’utiliser une grosse infolist, il est préférable d’utiliser un hdata (mais l’infolist peut contenir plus de données que le hdata, qui contient des données brutes), voir hdata.

Prototype :

struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);

Paramètres :

infolist_name : nom de l’infolist à lire (voir le tableau ci-dessous)
pointer : pointeur vers un objet, pour n’obtenir que celui-ci dans l’infolist (optionnel, peut être NULL)
arguments : paramètres pour l’infolist demandée (optionnels, NULL si aucun paramètre n’est nécessaire)

Valeur de retour :

pointeur vers l’infolist, NULL en cas d’erreur

Infolists :

Extension

Nom

Description

Pointeur

Paramètres

alias

liste des alias

pointeur vers l’alias (optionnel)

nom d’alias (le caractère joker "*" est autorisé) (optionnel)

alias

alias_default

liste des alias par défaut

buflist

liste des tampons dans un objet de barre buflist

nom d’objet de barre buflist (optionnel)

fset

fset_option

liste des options fset

pointeur vers l’option fset (optionnel)

nom d’option (le caractère joker "*" est autorisé) (optionnel)

guile

guile_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

irc

irc_channel

liste des canaux pour un serveur IRC

pointeur vers le canal (optionnel)

serveur,canal (le canal est optionnel)

irc

irc_color_weechat

correspondance entre les codes couleur IRC et les noms de couleur WeeChat

irc

irc_ignore

liste des ignores IRC

pointeur vers l’ignore (optionnel)

irc

irc_modelist

liste des listes de modes pour un canal IRC

pointeur vers une liste de modes (optionnel)

serveur,canal,type (le type est optionnel)

irc

irc_modelist_item

listes des éléments dans une liste de modes de canal

pointeur vers un élément de liste de modes (optionnel)

serveur,canal,type,nombre (le nombre est optionnel)

irc

irc_nick

liste des pseudos pour un canal IRC

pointeur vers le pseudo (optionnel)

serveur,canal,pseudo (le pseudo est optionnel)

irc

irc_notify

liste des notifications

pointeur vers la notification (optionnel)

nom de serveur (le caractère joker "*" est autorisé) (optionnel)

irc

irc_server

liste des serveurs IRC

pointeur vers le serveur (optionnel)

nom de serveur (le caractère joker "*" est autorisé) (optionnel)

logger

logger_buffer

liste des enregistreurs de tampons (loggers)

pointeur vers le logger (optionnel)

lua

lua_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

perl

perl_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

php

php_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

python

python_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

relay

liste des clients pour le relai

pointeur vers le relay (optionnel)

ruby

ruby_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

script

script_script

liste des scripts

pointeur vers le script (optionnel)

nom du script avec extension (le caractère joker "*" est autorisé) (optionnel)

tcl

tcl_script

liste des scripts

pointeur vers le script (optionnel)

nom de script (le caractère joker "*" est autorisé) (optionnel)

weechat

bar

liste des barres

pointeur vers la barre (optionnel)

nom de barre (le caractère joker "*" est autorisé) (optionnel)

weechat

bar_item

liste des objets de barres

pointeur vers l’objet de barre (optionnel)

nom d’objet de barre (le caractère joker "*" est autorisé) (optionnel)

weechat

bar_window

liste des fenêtres de barre

pointeur vers la fenêtre de barre (optionnel)

weechat

buffer

liste des tampons

pointeur vers le tampon (optionnel)

nom de tampon (le caractère joker "*" est autorisé) (optionnel)

weechat

buffer_lines

lignes d’un tampon

pointeur vers le tampon

weechat

filter

liste des filtres

nom de filtre (le caractère joker "*" est autorisé) (optionnel)

weechat

history

historique des commandes

pointeur vers le tampon (si non défini, retourne l’historique global) (optionnel)

weechat

hook

liste des hooks

pointeur vers le hook (optionnel)

type,paramètres (le type est command/timer/.., paramètres pour avoir seulement quelques hooks (le caractère joker "*" est autorisé), les deux sont optionnels)

weechat

hotlist

liste des tampons dans la hotlist

weechat

key

liste des associations de touches

contexte ("default", "search", "cursor" ou "mouse") (optionnel)

weechat

layout

liste des dispositions

weechat

nicklist

pseudos dans la liste des pseudos pour un tampon

pointeur vers le tampon

nick_xxx ou group_xxx pour avoir seulement le pseudo/groupe xxx (optionnel)

weechat

option

liste des options

nom d’option (le caractère joker "*" est autorisé) (optionnel)

weechat

plugin

liste des extensions

pointeur vers l’extension (optionnel)

nom d’extension (le caractère joker "*" est autorisé) (optionnel)

weechat

proxy

liste des proxies

pointeur vers le proxy (optionnel)

nom de proxy (le caractère joker "*" est autorisé) (optionnel)

weechat

url_options

options pour l’URL

weechat

window

liste des fenêtres

pointeur vers la fenêtre (optionnel)

"current" pour la fenêtre courante ou un numéro de fenêtre (optionnel)

xfer

liste des xfer

pointeur vers le xfer (optionnel)

Exemple en C :

struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);

Script (Python) :

# prototype
def infolist_get(infolist_name: str, pointer: str, arguments: str) -> str: ...

# exemple
infolist = weechat.infolist_get("irc_server", "", "")

infolist_next

Déplacer le "curseur" vers l’objet suivant dans l’infolist. Le premier appel à cette fonction sur une infolist déplace le curseur sur le premier objet de l’infolist.

Prototype :

int weechat_infolist_next (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Valeur de retour :

1 si le curseur a été déplacé sur l’objet suivant, 0 si la fin de la liste a été atteinte

Exemple en C :

if (weechat_infolist_next (infolist))
{
    /* lecture des variables dans l'objet... */
}
else
{
    /* pas d'autre objet disponible */
}

Script (Python) :

# prototype
def infolist_next(infolist: str) -> int: ...

# exemple
rc = weechat.infolist_next(infolist)
if rc:
    # lecture des variables dans l'objet...
else:
    # pas d'autre objet disponible

infolist_prev

Déplacer le "curseur" vers l’objet précédent dans l’infolist. Le premier appel à cette fonction sur une infolist déplace le curseur sur le dernier objet de l’infolist.

Prototype :

int weechat_infolist_prev (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Valeur de retour :

1 si le curseur a été déplacé sur l’objet précédent, 0 si le début de liste a été atteint

Exemple en C :

if (weechat_infolist_prev (infolist))
{
    /* lecture des variables dans l'objet... */
}
else
{
    /* pas d'autre objet disponible */
}

Script (Python) :

# prototype
def infolist_prev(infolist: str) -> int: ...

# exemple
rc = weechat.infolist_prev(infolist)
if rc:
    # lecture des variables dans l'objet
else:
    # pas d'autre objet disponible

infolist_reset_item_cursor

Réinitialiser le "curseur" de l’infolist.

Prototype :

void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Exemple en C :

weechat_infolist_reset_item_cursor (infolist);

Script (Python) :

# prototype
def infolist_reset_item_cursor(infolist: str) -> int: ...

# exemple
weechat.infolist_reset_item_cursor(infolist)

infolist_search_var

WeeChat ≥ 0.4.3.

Chercher une variable dans l’objet courant de l’infolist.

Prototype :

struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                    const char *name);

Paramètres :

infolist : pointeur vers l’infolist
name : nom de la variable

Valeur de retour :

pointeur vers la variable trouvée, NULL si la variable n’est pas trouvée

Exemple en C :

if (weechat_infolist_search_var (infolist, "name"))
{
    /* la variable "name" existe */
    /* ... */
}

Script (Python) :

# prototype
def infolist_search_var(infolist: str, name: str) -> str: ...

# exemple
if weechat.infolist_search_var(infolist, "name"):
    # la variable "name" existe
    # ...

infolist_fields

Retourner la liste des champs pour l’objet courant de l’infolist.

Prototype :

const char *weechat_infolist_fields (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Valeur de retour :

chaîne avec la liste des champs pour l’objet courant de l’infolist. La liste, séparée par des virgules, contient la lettre pour le type, suivi du nom de la variable. Les types sont : "i" (nombre entier), "s" (chaîne), "p" (pointeur), "b" (buffer), "t" (date/heure).

Exemple en C :

const char *fields = weechat_infolist_fields (infolist);
/* fields contient quelque chose comme :
   "i:mon_entier,s:ma_chaine,p:mon_pointeur,b:mon_buffer,t:ma_date" */

Script (Python) :

# prototype
def infolist_fields(infolist: str) -> str: ...

# exemple
fields = weechat.infolist_fields(infolist)
# fields contient quelque chose comme :
# "i:mon_entier,s:ma_chaine,p:mon_pointeur,b:mon_buffer,t:ma_date"

infolist_integer

Retourner la valeur de la variable de l’objet courant de l’infolist, sous forme d’entier.

Prototype :

int weechat_infolist_integer (struct t_infolist *infolist, const char *var);

Paramètres :

infolist : pointeur vers l’infolist
var : nom de la variable (doit être de type "integer")

Valeur de retour :

valeur de la variable, sous forme d’entier

Exemple en C :

weechat_printf (NULL, "entier = %d",
                weechat_infolist_integer (infolist, "mon_entier"));

Script (Python) :

# prototype
def infolist_integer(infolist: str, var: str) -> int: ...

# exemple
weechat.prnt("", "entier = %d" % weechat.infolist_integer(infolist, "mon_entier"))

infolist_string

Retourner la valeur de la variable de l’objet courant de l’infolist, sous forme de chaîne de caractères.

Prototype :

const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);

Paramètres :

infolist : pointeur vers l’infolist
var : nom de la variable (doit être de type "string")

Valeur de retour :

valeur de la variable, sous forme de chaîne

Exemple en C :

weechat_printf (NULL, "chaîne = %s",
                weechat_infolist_string (infolist, "ma_chaine"));

Script (Python) :

# prototype
def infolist_string(infolist: str, var: str) -> str: ...

# exemple
weechat.prnt("", "chaîne = %s" % weechat.infolist_string(infolist, "ma_chaine"))

infolist_pointer

Retourner la valeur de la variable de l’objet courant de l’infolist, sous forme de pointeur.

Prototype :

void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);

Paramètres :

infolist : pointeur vers l’infolist
var : nom de la variable (doit être de type "pointer")

Valeur de retour :

valeur de la variable, sous forme de pointeur

Exemple en C :

weechat_printf (NULL, "pointeur = 0x%lx",
                weechat_infolist_pointer (infolist, "mon_pointeur"));

Script (Python) :

# prototype
def infolist_pointer(infolist: str, var: str) -> str: ...

# exemple
weechat.prnt("", "pointeur = 0x%s" % weechat.infolist_pointer(infolist, "mon_pointeur"))

infolist_buffer

Retourner la valeur de la variable de l’objet courant de l’infolist, sous forme de tampon de données.

Prototype :

void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);

Paramètres :

infolist : pointeur vers l’infolist
var : nom de la variable (doit être de type "buffer")
size : pointeur vers une variable entière, qui sera alimenté avec la taille de la zone

Valeur de retour :

pointeur vers le tampon de données

Exemple en C :

int size;
void *pointer = weechat_infolist_buffer (infolist, "mon_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, taille = %d",
                pointer, size);

Cette fonction n’est pas disponible dans l’API script.

infolist_time

Retourner la valeur de la variable de l’objet courant de l’infolist, sous forme de date/heure.

Prototype :

time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);

Paramètres :

infolist : pointeur vers l’infolist
var : nom de la variable (doit être de type "time")

Valeur de retour :

valeur de la variable, sous forme de date/heure

Exemple en C :

weechat_printf (NULL, "date/heure = %ld",
                weechat_infolist_time (infolist, "mon_time"));

Script (Python) :

# prototype
def infolist_time(infolist: str, var: str) -> int: ...

# exemple
weechat.prnt("", "date/heure = %ld" % weechat.infolist_time(infolist, "mon_time"))

infolist_free

Supprimer une infolist.

Prototype :

void weechat_infolist_free (struct t_infolist *infolist);

Paramètres :

infolist : pointeur vers l’infolist

Exemple en C :

weechat_infolist_free (infolist);

Script (Python) :

# prototype
def infolist_free(infolist: str) -> int: ...

# exemple
weechat.infolist_free(infolist)

3.24. Hdata

Fonctions pour les hdata (accès brut aux données de WeeChat ou des extensions).

Le "hdata" fournit seulement un accès en lecture seule aux données. Il est STRICTEMENT INTERDIT d’écrire quelque chose dans une zone mémoire pointée par les variables du hdata.
Le seul moyen pour mettre à jour des données est d’appeler la fonction hdata_update.

hdata_new

WeeChat ≥ 0.3.6, mis à jour dans la 0.3.9, 0.4.0.

Créer un "hdata".

hdata vs infolist

Le "hdata" est un moyen rapide de lire des données de WeeChat ou des extensions. Il est similaire à l’infolist, mais il y a quelques différences :

Il est plus rapide et utilise moins de mémoire : accès direct aux données sans duplication.
Il peut contenir des informations différentes de l’infolist : il contient seulement les données brutes des structures (l’infolist peut ajouter des données supplémentaires pour plus de commodité).

Prototype :

struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);

Paramètres :

hdata_name : nom du hdata
var_prev : nom de la variable dans la structure qui est un pointeur vers l’élément précédent dans la liste (peut être NULL si une telle variable n’existe pas)
var_next : nom de la variable dans la structure qui est un pointeur vers l’élément suivant dans la liste (peut être NULL si une telle variable n’existe pas)
create_allowed : 1 si la création de structure est autorisée, sinon 0 (WeeChat ≥ 0.4.0)
delete_allowed : 1 si la suppression de structure est autorisée, sinon 0 (WeeChat ≥ 0.3.9)
callback_update : fonction appelée pour mettre à jour des données dans le hdata, peut être NULL si aucune mise à jour n’est autorisée (WeeChat ≥ 0.3.9), paramètres et valeur de retour :
- void *data : pointeur
- struct t_hdata *hdata : pointeur vers le hdata
- struct t_hashtable *hashtable : table de hachage avec les variables à mettre à jour (voir hdata_update)
- valeur de retour : nombre de variables mises à jour
callback_update_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat (WeeChat ≥ 0.3.9)

Valeur de retour :

pointeur vers le nouveau "hdata"

Exemple en C :

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);

Cette fonction n’est pas disponible dans l’API script.

hdata_new_var

WeeChat ≥ 0.3.6, mis à jour dans la 0.3.7, 0.3.9, 0.4.3, 3.4.

Créer une nouvelle variable dans le hdata.

Prototype :

void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable
offset : position (offset) de la variable dans la structure
type : type de la variable, un parmi ceux-ci :
- WEECHAT_HDATA_CHAR
- WEECHAT_HDATA_INTEGER
- WEECHAT_HDATA_LONG
- WEECHAT_HDATA_STRING
- WEECHAT_HDATA_SHARED_STRING (WeeChat ≥ 0.4.3)
- WEECHAT_HDATA_POINTER
- WEECHAT_HDATA_TIME
- WEECHAT_HDATA_HASHTABLE (WeeChat ≥ 0.3.7)
- WEECHAT_HDATA_OTHER
update_allowed : 1 si la mise à jour de la variable est autorisée, sinon 0 (WeeChat ≥ 0.3.9)
array_size : non NULL seulement si la variable est un tableau, et peut être : (WeeChat ≥ 0.3.9)
- nom d’une variable du hdata : cette variable sera utilisée comme taille de tableau (taille dynamique pour le tableau)
- entier (sous forme de chaîne) : taille fixe pour le tableau
- * : taille automatique : la taille est calculée en examinant les valeurs, lorsque le premier NULL est trouvé (seulement pour le type string, pointeur ou hashtable)
hdata_name : nom d’un hdata (si c’est un pointeur vers une structure qui a un hdata)

Avec WeeChat ≥ 3.4, le paramètre array_size peut être préfixé par *, pour un pointeur vers un tableau alloué dynamiquement (sans ce préfixe, le tableau est considéré statique).

Exemples de variables avec la taille de tableau correspondante (WeeChat ≥ 3.4) :

Déclaration de variable en C Type Hdata Taille de tableau Description

int *numbers;

WEECHAT_HDATA_INTEGER

*,2

Tableau alloué de 2 entiers.

int *numbers;

WEECHAT_HDATA_INTEGER

*,array_size

Tableau alloué d’entiers, la taille est stockée dans une autre variable nommée "array_size".

int numbers[3];

WEECHAT_HDATA_INTEGER

3

Tableau statique de 3 entiers.

char **words;

WEECHAT_HDATA_STRING

*,*

Tableau alloué de chaînes, taille dynamique (un pointeur NULL doit être présent après le dernier mot).

char **words;

WEECHAT_HDATA_STRING

*,count_words

Tableau alloué de chaînes, la taille est stockée dans une autre variable nommée "count_words".

Exemple en C :

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int numbers[3];
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "numbers", offsetof (struct t_myplugin_list, numbers), WEECHAT_HDATA_INTEGER, 0, "3", NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "*,tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*,*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");

La macro "WEECHAT_HDATA_VAR" peut être utilisée pour raccourcir le code :

WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, numbers, INTEGER, 0, "3", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "*,tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*,*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");

Cette fonction n’est pas disponible dans l’API script.

hdata_new_list

WeeChat ≥ 0.3.6, mis à jour dans la 1.0.

Créer un nouveau pointeur vers une liste dans le hdata.

Prototype :

void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable
pointer : pointeur vers la liste
flags : combinaison des valeurs suivantes : (WeeChat ≥ 1.0)
- WEECHAT_HDATA_LIST_CHECK_POINTERS : liste utilisée pour vérifier les pointeurs

Exemple en C :

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);

La macro "WEECHAT_HDATA_LIST" peut être utilisée pour raccourcir le code :

WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
WEECHAT_HDATA_LIST(last_buffer, 0);

Cette fonction n’est pas disponible dans l’API script.

hdata_get

WeeChat ≥ 0.3.6.

Retourner un "hdata" pour une structure de WeeChat ou d’une extension.

Le "hdata" ne contient aucune donnée, il s’agit seulement d’une table de hachage avec la position (offset) des variables dans la structure. Cela signifie que vous aurez besoin de ce hdata et d’un pointeur vers un objet WeeChat ou d’une extension pour lire des données.

Prototype :

struct t_hdata *weechat_hdata_get (const char *hdata_name);

Paramètres :

hdata_name : nom du hdata (voir la liste ci-dessous)

Valeur de retour :

pointeur vers le hdata, NULL en cas d’erreur

Liste des hdata :

Extension

Nom

Description

Listes

Variables

fset

fset_option

options fset

index (integer)
file (string)
section (string)
option (string)
name (string)
parent_name (string)
type (integer)
default_value (string)
value (string)
parent_value (string)
min (string)
max (string)
description (string)
string_values (string)
marked (integer)

guile

guile_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "guile_script")
next_script (pointer, hdata: "guile_script")

irc

irc_batch

batch irc

reference (string)
parent_ref (string)
type (string)
parameters (string)
start_time (time)
messages (pointer)
end_received (integer)
messages_processed (integer)
prev_batch (pointer, hdata: "irc_batch")
next_batch (pointer, hdata: "irc_batch")

irc

irc_channel

canal irc

type (integer)
name (string)
topic (string)
modes (string)
limit (integer)
key (string)
join_msg_received (hashtable)
checking_whox (integer)
away_message (string)
has_quit_server (integer)
cycle (integer)
part (integer)
nick_completion_reset (integer)
pv_remote_nick_color (string)
hook_autorejoin (pointer)
nicks_count (integer)
nicks (pointer, hdata: "irc_nick")
last_nick (pointer, hdata: "irc_nick")
nicks_speaking (pointer)
nicks_speaking_time (pointer, hdata: "irc_channel_speaking")
last_nick_speaking_time (pointer, hdata: "irc_channel_speaking")
modelists (pointer, hdata: "irc_modelist")
last_modelist (pointer, hdata: "irc_modelist")
join_smart_filtered (hashtable)
typing_state (integer)
typing_status_sent (time)
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
prev_channel (pointer, hdata: "irc_channel")
next_channel (pointer, hdata: "irc_channel")

irc

irc_channel_speaking

channel_speaking irc

nick (string)
time_last_message (time)
prev_nick (pointer, hdata: "irc_channel_speaking")
next_nick (pointer, hdata: "irc_channel_speaking")

irc

irc_ignore

ignore irc

irc_ignore_list
last_irc_ignore

number (integer)
mask (string)
regex_mask (pointer)
server (string)
channel (string)
prev_ignore (pointer, hdata: "irc_ignore")
next_ignore (pointer, hdata: "irc_ignore")

irc

irc_list

données irc sur le tampon /list

buffer (pointer, hdata: "buffer")
channels (pointer)
filter_channels (pointer)
name_max_length (integer)
filter (string)
sort (string)
sort_fields (pointer)
sort_fields_count (integer)
selected_line (integer)

irc

irc_list_channel

canal irc sur le tampon /list

name (string)
name2 (string)
users (integer)
topic (string)

irc

irc_modelist

liste de modes irc

type (char)
state (integer)
items (pointer, hdata: "irc_modelist_item")
last_item (pointer, hdata: "irc_modelist_item")
prev_modelist (pointer, hdata: "irc_modelist")
next_modelist (pointer, hdata: "irc_modelist")

irc

irc_modelist_item

élément de liste de modes irc

number (integer)
mask (string)
setter (string)
datetime (time)
prev_item (pointer, hdata: "irc_modelist_item")
next_item (pointer, hdata: "irc_modelist_item")

irc

irc_nick

pseudo irc

name (string)
host (string)
prefixes (string)
prefix (string)
away (integer)
account (string)
realname (string)
color (string)
prev_nick (pointer, hdata: "irc_nick")
next_nick (pointer, hdata: "irc_nick")

irc

irc_notify

notify irc

server (pointer, hdata: "irc_server")
nick (string)
check_away (integer)
is_on_server (integer)
away_message (string)
ison_received (integer)
prev_notify (pointer, hdata: "irc_notify")
next_notify (pointer, hdata: "irc_notify")

irc

irc_redirect

redirection irc

server (pointer, hdata: "irc_server")
pattern (string)
signal (string)
count (integer)
current_count (integer)
string (string)
timeout (integer)
command (string)
assigned_to_command (integer)
start_time (time)
cmd_start (hashtable)
cmd_stop (hashtable)
cmd_extra (hashtable)
cmd_start_received (integer)
cmd_stop_received (integer)
cmd_filter (hashtable)
output (string)
output_size (integer)
prev_redirect (pointer, hdata: "irc_redirect")
next_redirect (pointer, hdata: "irc_redirect")

irc

irc_redirect_pattern

modèle pour une redirection irc

irc_redirect_patterns
last_irc_redirect_pattern

name (string)
temp_pattern (integer)
timeout (integer)
cmd_start (string)
cmd_stop (string)
cmd_extra (string)
prev_redirect (pointer, hdata: "irc_redirect_pattern")
next_redirect (pointer, hdata: "irc_redirect_pattern")

irc

irc_server

serveur irc

irc_servers
last_irc_server

name (string)
options (pointer)
temp_server (integer)
fake_server (integer)
reloading_from_config (integer)
reloaded_from_config (integer)
addresses_eval (string)
addresses_count (integer)
addresses_array (string, array_size: "addresses_count")
ports_array (integer, array_size: "addresses_count")
retry_array (integer, array_size: "addresses_count")
index_current_address (integer)
current_address (string)
current_ip (string)
current_port (integer)
current_retry (integer)
sock (integer)
hook_connect (pointer, hdata: "hook")
hook_fd (pointer, hdata: "hook")
hook_timer_connection (pointer, hdata: "hook")
hook_timer_sasl (pointer, hdata: "hook")
hook_timer_anti_flood (pointer, hdata: "hook")
sasl_scram_client_first (string)
sasl_scram_salted_pwd (other)
sasl_scram_salted_pwd_size (integer)
sasl_scram_auth_message (string)
sasl_temp_username (string)
sasl_temp_password (string)
authentication_method (integer)
sasl_mechanism_used (integer)
is_connected (integer)
tls_connected (integer)
disconnected (integer)
gnutls_sess (pointer)
tls_cert (pointer)
tls_cert_key (pointer)
unterminated_message (string)
nicks_count (integer)
nicks_array (string, array_size: "nicks_count")
nick_first_tried (integer)
nick_alternate_number (integer)
nick (string)
nick_modes (string)
host (string)
checking_cap_ls (integer)
cap_ls (hashtable)
checking_cap_list (integer)
cap_list (hashtable)
multiline_max_bytes (integer)
multiline_max_lines (integer)
isupport (string)
prefix_modes (string)
prefix_chars (string)
msg_max_length (integer)
user_max_length (integer)
host_max_length (integer)
casemapping (integer)
utf8mapping (integer)
utf8only (integer)
chantypes (string)
chanmodes (string)
monitor (integer)
monitor_time (time)
clienttagdeny (string)
clienttagdeny_count (integer)
clienttagdeny_array (string, array_size: "clienttagdeny_count")
typing_allowed (integer)
reconnect_delay (integer)
reconnect_start (time)
command_time (time)
autojoin_done (integer)
disable_autojoin (integer)
is_away (integer)
away_message (string)
away_time (time)
lag (integer)
lag_displayed (integer)
lag_check_time (other)
lag_next_check (time)
lag_last_refresh (time)
cmd_list_regexp (pointer)
list (pointer, hdata: "irc_list")
last_away_check (time)
last_data_purge (time)
outqueue (pointer)
last_outqueue (pointer)
redirects (pointer, hdata: "irc_redirect")
last_redirect (pointer, hdata: "irc_redirect")
notify_list (pointer, hdata: "irc_notify")
last_notify (pointer, hdata: "irc_notify")
notify_count (integer)
join_manual (hashtable)
join_channel_key (hashtable)
join_noswitch (hashtable)
echo_msg_recv (hashtable)
names_channel_filter (hashtable)
batches (pointer, hdata: "irc_batch")
last_batch (pointer, hdata: "irc_batch")
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
channels (pointer, hdata: "irc_channel")
last_channel (pointer, hdata: "irc_channel")
prev_server (pointer, hdata: "irc_server")
next_server (pointer, hdata: "irc_server")

lua

lua_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "lua_script")
next_script (pointer, hdata: "lua_script")

perl

perl_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "perl_script")
next_script (pointer, hdata: "perl_script")

php

php_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "php_script")
next_script (pointer, hdata: "php_script")

python

python_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "python_script")
next_script (pointer, hdata: "python_script")

ruby

ruby_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "ruby_script")
next_script (pointer, hdata: "ruby_script")

script

script_script

scripts du dépôt

scripts_repo
last_script_repo

name (string)
name_with_extension (string)
language (integer)
author (string)
mail (string)
version (string)
license (string)
description (string)
tags (string)
requirements (string)
min_weechat (string)
max_weechat (string)
sha512sum (string)
url (string)
popularity (integer)
date_added (time)
date_updated (time)
status (integer)
version_loaded (string)
displayed (integer)
install_order (integer)
prev_script (pointer, hdata: "script_script")
next_script (pointer, hdata: "script_script")

tcl

tcl_script

liste des scripts

scripts
last_script

filename (string)
interpreter (pointer)
name (string)
author (string)
version (string)
license (string)
description (string)
shutdown_func (string)
charset (string)
unloading (integer)
prev_script (pointer, hdata: "tcl_script")
next_script (pointer, hdata: "tcl_script")

weechat

bar

barre

gui_bars
last_gui_bar

name (string)
options (pointer)
items_count (integer)
items_subcount (pointer)
items_array (pointer)
items_buffer (pointer)
items_prefix (pointer)
items_name (pointer)
items_suffix (pointer)
bar_window (pointer, hdata: "bar_window")
bar_refresh_needed (integer)
prev_bar (pointer, hdata: "bar")
next_bar (pointer, hdata: "bar")

weechat

bar_item

objet de barre

gui_bar_items
last_gui_bar_item

plugin (pointer, hdata: "plugin")
name (string)
build_callback (pointer)
build_callback_pointer (pointer)
build_callback_data (pointer)
prev_item (pointer, hdata: "bar_item")
next_item (pointer, hdata: "bar_item")

weechat

bar_window

fenêtre de barre

bar (pointer, hdata: "bar")
x (integer)
y (integer)
width (integer)
height (integer)
scroll_x (integer)
scroll_y (integer)
cursor_x (integer)
cursor_y (integer)
current_size (integer)
items_count (integer)
items_subcount (pointer)
items_content (pointer)
items_num_lines (pointer)
items_refresh_needed (pointer)
screen_col_size (integer)
screen_lines (integer)
coords_count (integer)
coords (pointer)
gui_objects (pointer)
prev_bar_window (pointer, hdata: "bar_window")
next_bar_window (pointer, hdata: "bar_window")

Mise à jour autorisée :
scroll_x (integer)
scroll_y (integer)

weechat

buffer

tampon

gui_buffer_last_displayed
gui_buffers
last_gui_buffer

opening (integer)
plugin (pointer, hdata: "plugin")
plugin_name_for_upgrade (string)
number (integer)
layout_number (integer)
layout_number_merge_order (integer)
name (string)
full_name (string)
old_full_name (string)
short_name (string)
type (integer)
notify (integer)
num_displayed (integer)
active (integer)
hidden (integer)
zoomed (integer)
print_hooks_enabled (integer)
day_change (integer)
clear (integer)
filter (integer)
close_callback (pointer)
close_callback_pointer (pointer)
close_callback_data (pointer)
closing (integer)
title (string)
own_lines (pointer, hdata: "lines")
mixed_lines (pointer, hdata: "lines")
lines (pointer, hdata: "lines")
next_line_id (integer)
time_for_each_line (integer)
chat_refresh_needed (integer)
nicklist (integer)
nicklist_case_sensitive (integer)
nicklist_root (pointer, hdata: "nick_group")
nicklist_max_length (integer)
nicklist_display_groups (integer)
nicklist_count (integer)
nicklist_visible_count (integer)
nicklist_groups_count (integer)
nicklist_groups_visible_count (integer)
nicklist_nicks_count (integer)
nicklist_nicks_visible_count (integer)
nickcmp_callback (pointer)
nickcmp_callback_pointer (pointer)
nickcmp_callback_data (pointer)
input (integer)
input_callback (pointer)
input_callback_pointer (pointer)
input_callback_data (pointer)
input_get_unknown_commands (integer)
input_get_empty (integer)
input_multiline (integer)
input_buffer (string)
input_buffer_alloc (integer)
input_buffer_size (integer)
input_buffer_length (integer)
input_buffer_pos (integer)
input_buffer_1st_display (integer)
input_undo_snap (pointer, hdata: "input_undo")
input_undo (pointer, hdata: "input_undo")
last_input_undo (pointer, hdata: "input_undo")
ptr_input_undo (pointer, hdata: "input_undo")
input_undo_count (integer)
completion (pointer, hdata: "completion")
history (pointer, hdata: "history")
last_history (pointer, hdata: "history")
ptr_history (pointer, hdata: "history")
num_history (integer)
text_search (integer)
text_search_direction (integer)
text_search_exact (integer)
text_search_regex (integer)
text_search_regex_compiled (pointer)
text_search_where (integer)
text_search_history (integer)
text_search_found (integer)
text_search_ptr_history (pointer, hdata: "history")
text_search_input (string)
highlight_words (string)
highlight_regex (string)
highlight_regex_compiled (pointer)
highlight_disable_regex (string)
highlight_disable_regex_compiled (pointer)
highlight_tags_restrict (string)
highlight_tags_restrict_count (integer)
highlight_tags_restrict_array (pointer, array_size: "highlight_tags_restrict_count")
highlight_tags (string)
highlight_tags_count (integer)
highlight_tags_array (pointer, array_size: "highlight_tags_count")
hotlist (pointer, hdata: "hotlist")
hotlist_max_level_nicks (hashtable)
keys (pointer, hdata: "key")
last_key (pointer, hdata: "key")
keys_count (integer)
local_variables (hashtable)
prev_buffer (pointer, hdata: "buffer")
next_buffer (pointer, hdata: "buffer")

weechat

buffer_visited

tampon visité

gui_buffers_visited
last_gui_buffer_visited

buffer (pointer, hdata: "buffer")
prev_buffer (pointer, hdata: "buffer_visited")
next_buffer (pointer, hdata: "buffer_visited")

weechat

completion

structure avec une complétion

weechat_completions
last_weechat_completion

plugin (pointer, hdata: "plugin")
buffer (pointer, hdata: "buffer")
context (integer)
base_command (string)
base_command_arg_index (integer)
base_word (string)
base_word_pos (integer)
position (integer)
args (string)
direction (integer)
add_space (integer)
force_partial_completion (integer)
reverse_partial_completion (integer)
list (pointer)
word_found (string)
word_found_is_nick (integer)
position_replace (integer)
diff_size (integer)
diff_length (integer)
partial_list (pointer)
prev_completion (pointer, hdata: "completion")
next_completion (pointer, hdata: "completion")

weechat

completion_word

structure avec un mot trouvé pour une complétion

word (string)
nick_completion (char)
count (integer)

weechat

config_file

fichier de configuration

config_files
last_config_file

plugin (pointer, hdata: "plugin")
priority (integer)
name (string)
filename (string)
file (pointer)
version (integer)
callback_reload (pointer)
callback_reload_pointer (pointer)
callback_reload_data (pointer)
sections (pointer, hdata: "config_section")
last_section (pointer, hdata: "config_section")
prev_config (pointer, hdata: "config_file")
next_config (pointer, hdata: "config_file")

weechat

config_option

option de configuration

config_file (pointer, hdata: "config_file")
section (pointer, hdata: "config_section")
name (string)
parent_name (string)
type (integer)
description (string)
string_values (string, array_size: "*")
min (integer)
max (integer)
default_value (pointer)
value (pointer)
null_value_allowed (integer)
callback_check_value (pointer)
callback_check_value_pointer (pointer)
callback_check_value_data (pointer)
callback_change (pointer)
callback_change_pointer (pointer)
callback_change_data (pointer)
callback_delete (pointer)
callback_delete_pointer (pointer)
callback_delete_data (pointer)
loaded (integer)
prev_option (pointer, hdata: "config_option")
next_option (pointer, hdata: "config_option")

weechat

config_section

section de configuration

config_file (pointer, hdata: "config_file")
name (string)
user_can_add_options (integer)
user_can_delete_options (integer)
callback_read (pointer)
callback_read_pointer (pointer)
callback_read_data (pointer)
callback_write (pointer)
callback_write_pointer (pointer)
callback_write_data (pointer)
callback_write_default (pointer)
callback_write_default_pointer (pointer)
callback_write_default_data (pointer)
callback_create_option (pointer)
callback_create_option_pointer (pointer)
callback_create_option_data (pointer)
callback_delete_option (pointer)
callback_delete_option_pointer (pointer)
callback_delete_option_data (pointer)
options (pointer, hdata: "config_option")
last_option (pointer, hdata: "config_option")
prev_section (pointer, hdata: "config_section")
next_section (pointer, hdata: "config_section")

weechat

filter

filtre

gui_filters
last_gui_filter

enabled (integer)
name (string)
buffer_name (string)
num_buffers (integer)
buffers (pointer)
tags (string)
tags_count (integer)
tags_array (pointer, array_size: "tags_count")
regex (string)
regex_prefix (pointer)
regex_message (pointer)
prev_filter (pointer, hdata: "filter")
next_filter (pointer, hdata: "filter")

weechat

history

historique des commandes dans le tampon

gui_history
last_gui_history

text (string)
next_history (pointer, hdata: "history")
prev_history (pointer, hdata: "history")

Mise à jour autorisée :
__create
__delete

weechat

hotlist

gui_hotlist
last_gui_hotlist

priority (integer)
creation_time.tv_sec (time)
creation_time.tv_usec (long)
buffer (pointer)
count (integer, array_size: "4")
prev_hotlist (pointer, hdata: "hotlist")
next_hotlist (pointer, hdata: "hotlist")

weechat

input_undo

structure avec le "undo" pour la ligne de commande

data (string)
pos (integer)
prev_undo (pointer, hdata: "input_undo")
next_undo (pointer, hdata: "input_undo")

weechat

key

une touche (un raccourci clavier)

gui_default_keys
gui_default_keys_cursor
gui_default_keys_histsearch
gui_default_keys_mouse
gui_default_keys_search
gui_keys
gui_keys_cursor
gui_keys_histsearch
gui_keys_mouse
gui_keys_search
last_gui_default_key
last_gui_default_key_cursor
last_gui_default_key_histsearch
last_gui_default_key_mouse
last_gui_default_key_search
last_gui_key
last_gui_key_cursor
last_gui_key_histsearch
last_gui_key_mouse
last_gui_key_search

key (string)
area_type (pointer)
area_name (pointer)
area_key (string)
command (string)
score (integer)
prev_key (pointer, hdata: "key")
next_key (pointer, hdata: "key")

weechat

layout

disposition

gui_layout_current
gui_layouts
last_gui_layout

name (string)
layout_buffers (pointer, hdata: "layout_buffer")
last_layout_buffer (pointer, hdata: "layout_buffer")
layout_windows (pointer, hdata: "layout_window")
internal_id (integer)
internal_id_current_window (integer)
prev_layout (pointer, hdata: "layout")
next_layout (pointer, hdata: "layout")

weechat

layout_buffer

disposition de tampon

plugin_name (string)
buffer_name (string)
number (integer)
prev_layout (pointer, hdata: "layout_buffer")
next_layout (pointer, hdata: "layout_buffer")

weechat

layout_window

disposition de fenêtre

internal_id (integer)
parent_node (pointer, hdata: "layout_window")
split_pct (integer)
split_horiz (integer)
child1 (pointer, hdata: "layout_window")
child2 (pointer, hdata: "layout_window")
plugin_name (string)
buffer_name (string)

weechat

line

structure avec une ligne

data (pointer, hdata: "line_data")
prev_line (pointer, hdata: "line")
next_line (pointer, hdata: "line")

weechat

line_data

structure avec les données d’une ligne

buffer (pointer, hdata: "buffer")
id (integer)
y (integer)
date (time)
date_usec (integer)
date_printed (time)
date_usec_printed (integer)
str_time (string)
tags_count (integer)
tags_array (shared_string, array_size: "tags_count")
displayed (char)
notify_level (char)
highlight (char)
refresh_needed (char)
prefix (shared_string)
prefix_length (integer)
message (string)

Mise à jour autorisée :
    date (time)
    date_usec (integer)
    date_printed (time)
    date_usec_printed (integer)
    tags_array (shared_string)
    prefix (shared_string)
    message (string)

weechat

lines

structure avec des lignes

first_line (pointer, hdata: "line")
last_line (pointer, hdata: "line")
last_read_line (pointer, hdata: "line")
lines_count (integer)
first_line_not_read (integer)
lines_hidden (integer)
buffer_max_length (integer)
buffer_max_length_refresh (integer)
prefix_max_length (integer)
prefix_max_length_refresh (integer)

weechat

nick

pseudo dans la liste de pseudos

group (pointer, hdata: "nick_group")
name (shared_string)
color (shared_string)
prefix (shared_string)
prefix_color (shared_string)
visible (integer)
prev_nick (pointer, hdata: "nick")
next_nick (pointer, hdata: "nick")

weechat

nick_group

groupe dans la liste de pseudos

name (shared_string)
color (shared_string)
visible (integer)
level (integer)
parent (pointer, hdata: "nick_group")
children (pointer, hdata: "nick_group")
last_child (pointer, hdata: "nick_group")
nicks (pointer, hdata: "nick")
last_nick (pointer, hdata: "nick")
prev_group (pointer, hdata: "nick_group")
next_group (pointer, hdata: "nick_group")

weechat

plugin

extension

weechat_plugins
last_weechat_plugin

filename (string)
handle (pointer)
name (string)
description (string)
author (string)
version (string)
license (string)
charset (string)
priority (integer)
initialized (integer)
debug (integer)
upgrading (integer)
variables (hashtable)
prev_plugin (pointer, hdata: "plugin")
next_plugin (pointer, hdata: "plugin")

weechat

proxy

weechat_proxies
last_weechat_proxy

name (string)
options (pointer)
prev_proxy (pointer, hdata: "proxy")
next_proxy (pointer, hdata: "proxy")

weechat

window

fenêtre

gui_current_window
gui_windows
last_gui_window

number (integer)
win_x (integer)
win_y (integer)
win_width (integer)
win_height (integer)
win_width_pct (integer)
win_height_pct (integer)
win_chat_x (integer)
win_chat_y (integer)
win_chat_width (integer)
win_chat_height (integer)
win_chat_cursor_x (integer)
win_chat_cursor_y (integer)
bar_windows (pointer, hdata: "bar_window")
last_bar_window (pointer, hdata: "bar_window")
refresh_needed (integer)
gui_objects (pointer)
buffer (pointer, hdata: "buffer")
layout_plugin_name (string)
layout_buffer_name (string)
scroll (pointer, hdata: "window_scroll")
ptr_tree (pointer, hdata: "window_tree")
prev_window (pointer, hdata: "window")
next_window (pointer, hdata: "window")

weechat

window_scroll

info de défilement dans la fenêtre

buffer (pointer, hdata: "buffer")
first_line_displayed (integer)
start_line (pointer, hdata: "line")
start_line_pos (integer)
scrolling (integer)
start_col (integer)
lines_after (integer)
text_search_start_line (pointer, hdata: "line")
prev_scroll (pointer, hdata: "window_scroll")
next_scroll (pointer, hdata: "window_scroll")

weechat

window_tree

arbre des fenêtres

gui_windows_tree

parent_node (pointer, hdata: "window_tree")
split_pct (integer)
split_horizontal (integer)
child1 (pointer, hdata: "window_tree")
child2 (pointer, hdata: "window_tree")
window (pointer, hdata: "window")

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("irc_server");

Script (Python) :

# prototype
def hdata_get(hdata_name: str) -> str: ...

# exemple
hdata = weechat.hdata_get("irc_server")

hdata_get_var_offset

WeeChat ≥ 0.3.6.

Retourner la position (offset) de la variable dans le hdata.

Prototype :

int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable

Valeur de retour :

position (offset) de la variable, -1 en cas d’erreur

Exemple en C :

int offset = weechat_hdata_get_var_offset (hdata, "name");

Script (Python) :

# prototype
def hdata_get_var_offset(hdata: str, name: str) -> int: ...

# exemple
offset = weechat.hdata_get_var_offset(hdata, "name")

hdata_get_var_type

WeeChat ≥ 0.3.6.

Retourner le type de la variable dans le hdata (sous forme d’entier).

Prototype :

int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable

Valeur de retour :

type de la variable, -1 en cas d’erreur

Exemple en C :

int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_SHARED_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable non trouvée */
        break;
}

Cette fonction n’est pas disponible dans l’API script.

hdata_get_var_type_string

WeeChat ≥ 0.3.6.

Retourner le type de la variable dans le hdata (sous forme de chaîne).

Prototype :

const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable

Valeur de retour :

type de la variable, NULL en cas d’erreur

Exemple en C :

weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));

Script (Python) :

# prototype
def hdata_get_var_type_string(hdata: str, name: str) -> str: ...

# exemple
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string(hdata, "name"))

hdata_get_var_array_size

WeeChat ≥ 0.3.9.

Retourner la taille du tableau pour la variable dans le hdata.

Prototype :

int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable

Valeur de retour :

taille du tableau pour la variable, -1 si la variable n’est pas un tableau ou en cas d’erreur

Exemple en C :

int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");

Script (Python) :

# prototype
def hdata_get_var_array_size(hdata: str, pointer: str, name: str) -> int: ...

# exemple
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")

hdata_get_var_array_size_string

WeeChat ≥ 0.3.9.

Retourner la taille du tableau pour la variable dans le hdata (sous forme de chaîne).

Prototype :

const char *weechat_hdata_get_var_count_array_size (struct t_hdata *hdata, void *pointer,
                                                    const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable

Valeur de retour :

taille du tableau pour la variable sous forme de chaîne, -1 si la variable n’est pas un tableau ou en cas d’erreur

Exemple en C :

const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");

Script (Python) :

# prototype
def hdata_get_var_array_size_string(hdata: str, pointer: str, name: str) -> str: ...

# exemple
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")

hdata_get_var_hdata

WeeChat ≥ 0.3.6.

Retourner le hdata pour la variable dans le hdata.

Prototype :

const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la variable

Valeur de retour :

hdata pour la variable, NULL si pas de hdata ou en cas d’erreur

Exemple en C :

weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));

Script (Python) :

# prototype
def hdata_get_var_hdata(hdata: str, name: str) -> str: ...

# exemple
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))

hdata_get_var

WeeChat ≥ 0.3.6.

Retourner un pointeur vers le contenu de la variable dans le hdata.

Prototype :

void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable

Valeur de retour :

pointeur vers le contenu de la variable, NULL en cas d’erreur

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");

Cette fonction n’est pas disponible dans l’API script.

hdata_get_var_at_offset

WeeChat ≥ 0.3.6.

Retourner un pointeur vers le contenu de la variable dans le hdata, en utilisant une position (offset).

Prototype :

void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
offset : position (offset) de la variable

Valeur de retour :

pointeur vers le contenu de la variable, NULL en cas d’erreur

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);

Cette fonction n’est pas disponible dans l’API script.

hdata_get_list

WeeChat ≥ 0.3.6.

Retourner un pointeur de liste du hdata.

Prototype :

void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);

Paramètres :

hdata : pointeur vers le hdata
name : nom de la liste

Valeur de retour :

pointeur vers la liste, NULL en cas d’erreur

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");

Script (Python) :

# prototype
def hdata_get_list(hdata: str, name: str) -> str: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")

hdata_check_pointer

WeeChat ≥ 0.3.7, mis à jour dans la 1.0.

Vérifier si un pointeur est valide pour un hdata et un pointeur de liste.

Prototype :

int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);

Paramètres :

hdata : pointeur vers le hdata
list : pointeur vers une liste; si NULL (WeeChat ≥ 1.0), le pointeur est vérifié avec les listes dans le hdata qui ont le drapeau "vérifier les pointeurs" (voir hdata_new_list), et s’il n’y a pas de telle liste, le pointeur est considéré comme valide
pointer : pointeur à vérifier

Valeur de retour :

1 si le pointeur est dans la liste, 0 si non trouvé

Exemple en C :

/* vérifie si le pointeur vers le tampon est valide */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* pointeur valide */
}
else
{
    /* pointeur invalide */
}

Script (Python) :

# prototype
def hdata_check_pointer(hdata: str, list: str, pointer: str) -> int: ...

# exemple
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # pointeur valide
    # ...
else:
    # pointeur invalide
    # ...

hdata_move

WeeChat ≥ 0.3.6.

Déplacer le pointeur vers un autre élément dans la liste.

Prototype :

void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
count : nombre de saut(s) à exécuter (entier négatif ou positif, différent de 0)

Valeur de retour :

pointeur vers l’élément atteint, NULL si l’élément n’est pas trouvé (par exemple fin de la liste), ou en cas d’erreur

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* se déplacer au tampon suivant, 2 fois */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* se déplacer au tampon précédent */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);

Script (Python) :

# prototype
def hdata_move(hdata: str, pointer: str, count: int) -> str: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# se déplacer au tampon suivant, 2 fois
buffer = weechat.hdata_move(hdata, buffer, 2)

# se déplacer au tampon précédent
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)

hdata_search

WeeChat ≥ 0.4.1, mis à jour dans la 3.4.

Chercher un élément dans la liste : l’expression search est évaluée pour chaque élément dans la liste, jusqu’à trouver l’élément (ou la fin de la liste).

Prototype :

void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search,
                            struct t_hashtable *pointers, struct t_hashtable *extra_vars,
                            struct t_hashtable *options, int move);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
search : expression à évaluer, le pointeur par défaut dans l’expression est le nom du hdata (et ce pointeur change pour chaque élément dans la liste); pour l’aide sur l’expression, voir le Guide utilisateur WeeChat / Commande /eval ^↗
pointers : table de hachage pour l’appel à la fonction string_eval_expression
extra_vars : table de hachage pour l’appel à la fonction string_eval_expression
options : table de hachage pour l’appel à la fonction string_eval_expression
move : nombre de saut(s) à exécuter après une recherche infructueuse (entier négatif ou positif, différent de 0)

Vous devez vous assurer que l’expression search est sûre et ne contient aucune donnée utilisateur. De telles données non sûres doivent être données dans la table de hachage extra_vars et être référencées par ${xxx} dans l’expression search (voir l’exemple ci-dessous).

Valeur de retour :

pointeur vers l’élément trouvé, ou NULL si non trouvé

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get_list (hdata, "irc_servers");
struct t_hashtable *extra_vars = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);

/* cherche un serveur irc avec le nom "libera" */
weechat_hashtable_set (extra_vars, "server_name", "libera");
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${server_name}",
                                     NULL, extra_vars, NULL, 1);
if (server)
{
    /* ... */
}
weechat_hashtable_free (extra_vars);

Script (Python) :

# prototype
def hdata_search(hdata: str, pointer: str, search: str,
                 pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str],
                 count: int) -> str: ...

# exemple
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# cherche un serveur irc avec le nom "libera"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${server_name}",
                              {}, {"server_name": "libera"}, {}, 1)
if server:
    # ...

hdata_char

WeeChat ≥ 0.3.7.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme de caractère.

Prototype :

char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "char"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme de caractère

Exemple en C :

weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));

Script (Python) :

# prototype
def hdata_char(hdata: str, pointer: str, name: str) -> int: ...

# exemple
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))

hdata_integer

WeeChat ≥ 0.3.6.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme d’entier.

Prototype :

int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "integer"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme d’entier

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));

Script (Python) :

# prototype
def hdata_integer(hdata: str, pointer: str, name: str) -> int: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))

hdata_long

WeeChat ≥ 0.3.6.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme d’entier long.

Prototype :

long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "long"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme d’entier long

Exemple en C :

weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));

Script (Python) :

# prototype
def hdata_long(hdata: str, pointer: str, name: str) -> int: ...

# exemple
weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar"))

hdata_string

WeeChat ≥ 0.3.6.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme de chaîne.

Prototype :

const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "string"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme de chaîne

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));

Script (Python) :

# prototype
def hdata_string(hdata: str, pointer: str, name: str) -> str: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))

hdata_pointer

WeeChat ≥ 0.3.6.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme de pointeur.

Prototype :

void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "pointeur"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme de pointeur

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines"));

Script (Python) :

# prototype
def hdata_pointer(hdata: str, pointer: str, name: str) -> str: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines"))

hdata_time

WeeChat ≥ 0.3.6.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme de date/heure.

Prototype :

time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "time"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme de date/heure

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "heure de la première ligne affichée = %s", ctime (&date));
        }
    }
}

Script (Python) :

# prototype
def hdata_time(hdata: str, pointer: str, name: str) -> int: ...

# exemple
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "heure de la première ligne affichée = %s" % time.strftime("%F %T", time.localtime(int(date))))

hdata_hashtable

WeeChat ≥ 0.3.7.

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous forme de table de hachage.

Prototype :

struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (doit être de type "hashtable"); pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"

Valeur de retour :

valeur de la variable, sous forme de pointeur vers la table de hachage

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d variables locales dans le tampon principal",
                weechat_hashtable_get_integer (hashtable, "items_count"));

Script (Python) :

# prototype
def hdata_hashtable(hdata: str, pointer: str, name: str) -> Dict[str, str]: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "variables locales dans le tampon principal :")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))

hdata_compare

WeeChat ≥ 1.9, mis à jour dans la 4.1.0.

Comparer une variable hdata de deux objets.

Prototype :

int weechat_hdata_compare (struct t_hdata *hdata, void *pointer1, void *pointer2, const char *name, int case_sensitive);

Paramètres :

hdata : pointeur vers le hdata
pointer1 : pointeur vers le premier objet WeeChat ou d’une extension
pointer2 : pointeur vers le second objet WeeChat ou d’une extension
name : nom de la variable ou chemin vers le nom de la variable ; pour les tableaux, le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0), par exemple : "2|name"
case_sensitive : 1 pour une comparaison tenant compte de la casse pour les chaînes, sinon 0

Valeur de retour :

-1 si variable1 < variable2
0 si variable1 == variable2
1 si variable1 > variable2

Exemple en C :

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("irc", "libera.#weechat-fr");
weechat_printf (NULL, "comparaison de numéro de tampon = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "number", 0));
weechat_printf (NULL, "comparaison du nombre de lignes = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "own_lines.lines_count", 0));
weechat_printf (NULL, "comparaison de variable locale = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "local_variables.myvar", 0));

Script (Python) :

# prototype
def hdata_compare(hdata: str, pointer1: str, pointer2: str, name: str, case_sensitive: int) -> int: ...

# exemple
hdata = weechat.hdata_get("buffer")
buffer1 = weechat.buffer_search("irc", "libera.#weechat")
buffer2 = weechat.buffer_search("irc", "libera.#weechat-fr")
weechat.prnt("", "comparaison de numéro de tampon = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "number", 0))
weechat.prnt("", "comparaison du nombre de lignes = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "own_lines.lines_count", 0))
weechat.prnt("", "comparaison de variable locale = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "local_variables.myvar", 0))

hdata_set

WeeChat ≥ 0.3.9.

Définir une nouvelle valeur pour une variable dans un hdata.

Cette fonction ne peut être appelée que dans une fonction de rappel de mise à jour (voir hdata_new et hdata_update), si la variable peut être mise à jour.

Prototype :

int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
name : nom de la variable (types autorisés : char, integer, long, string, pointer, time)
value : nouvelle valeur pour la variable

Valeur de retour :

1 si ok, 0 en cas d’erreur

Exemple en C :

weechat_hdata_set (hdata, pointer, "message", "test");

Cette fonction n’est pas disponible dans l’API script.

hdata_update

WeeChat ≥ 0.3.9.

Mettre à jour des données dans le hdata.

Prototype :

int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);

Paramètres :

hdata : pointeur vers le hdata
pointer : pointeur vers un objet WeeChat ou d’une extension
hashtable : variables à mettre à jour : les clés sont les noms des variables, les valeurs sont les nouvelles valeurs pour les variables (clés et valeurs sont des chaînes de caractères), quelques clés spéciales sont acceptées :
- clé __create_allowed (avec n’importe quelle valeur) : retourne 1 si la création est autorisée pour la structure, sinon 0 (WeeChat ≥ 0.4.0)
- clé __delete_allowed (avec n’importe quelle valeur) : retourne 1 si la suppression est autorisée pour la structure, sinon 0
- clé __update_allowed, la valeur est le nom d’une variable : retourne 1 si la mise à jour est autorisée pour la variable, sinon 0
- clé __delete (avec n’importe quelle valeur) : supprime la structure (si autorisé)

Valeur de retour :

nombre de variables mises à jour

Exemple en C :

/* soustrait une heure sur le dernier message affiché dans le tampon courant */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}

Script (Python) :

# prototype
def hdata_update(hdata: str, pointer: str, hashtable: Dict[str, str]) -> int: ...

# exemple : soustrait une heure sur le dernier message affiché dans le tampon courant
own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
        hdata = weechat.hdata_get("line_data")
        weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})

hdata_get_string

WeeChat ≥ 0.3.6.

Retourner une valeur pour une propriété d’un hdata sous forme de chaîne.

Prototype :

const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);

Paramètres :

hdata : pointeur vers le hdata
property : nom de la propriété :
- var_keys : chaîne avec la liste des clés pour les variables du hdata (format : "key1,key2,key3")
- var_values : chaîne avec la liste des valeurs pour les variables du hdata (format : "value1,value2,value3")
- var_keys_values : chaîne avec la liste des clés et valeurs pour les variables du hdata (format : "key1:value1,key2:value2,key3:value3")
- var_prev : nom de la variable dans la structure qui est un pointeur vers l’élément précédent dans la liste
- var_next : nom de la variable dans la structure qui est un pointeur vers l’élément suivant dans la liste
- list_keys : chaîne avec la liste des clés pour les listes du hdata (format : "key1,key2,key3")
- list_values : chaîne avec la liste des valeurs pour les listes du hdata (format : "value1,value2,value3")
- list_keys_values : chaîne avec la liste des clés et valeurs pour les listes du hdata (format : "key1:value1,key2:value2,key3:value3")

Valeur de retour :

valeur de la propriété sous forme de chaîne

Exemple en C :

weechat_printf (NULL, "variables dans le hdata : %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "listes dans le hdata : %s", weechat_hdata_get_string (hdata, "list_keys"));

Script (Python) :

# prototype
def hdata_get_string(hdata: str, property: str) -> str: ...

# exemple
weechat.prnt("", "variables dans le hdata : %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "listes dans le hdata : %s" % weechat.hdata_get_string(hdata, "list_keys"))

3.25. Mise à jour

Fonctions pour la mise à jour de WeeChat (commande "/upgrade").

upgrade_new

Mis à jour dans la 1.5.

Créer ou lire un fichier pour la mise à jour.

Prototype :

struct t_upgrade_file *upgrade_file_new (const char *filename,
                                         int (*callback_read)(const void *pointer,
                                                              void *data,
                                                              struct t_upgrade_file *upgrade_file,
                                                              int object_id,
                                                              struct t_infolist *infolist),
                                         const void *callback_read_pointer,
                                         void *callback_read_data);

Paramètres :

filename : nom du fichier (l’extension ".upgrade" est ajoutée automatiquement par WeeChat)
callback_read : fonction appelée pour chaque objet lu dans le fichier de mise à jour (si NULL, le fichier pour la mise à jour est ouvert en écriture), paramètres et valeur de retour :
- const void *pointer : pointeur
- void *data : pointeur
- struct t_upgrade_file *upgrade_file : pointeur vers le fichier de mise à jour
- int object_id : identifiant de l’objet
- struct t_infolist *infolist : infolist avec le contenu de l’objet
- valeur de retour :
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_read_pointer : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat
callback_read_data : pointeur donné à la fonction de rappel lorsqu’elle est appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction similaire) et est automatiquement libéré (par free) lorsque le fichier de mise à jour est fermé

Valeur de retour :

pointeur vers le fichier de mise à jour

Exemple en C :

struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("mon_fichier",
                                                           NULL, NULL, NULL);

Script (Python) :

# prototype
def upgrade_new(filename: str, callback_read: str, callback_read_data: str) -> str: ...

# exemple
upgrade_file = weechat.upgrade_new("mon_fichier", "", "")

upgrade_write_object

Écrire un objet dans le fichier de mise à jour.

Prototype :

int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);

Paramètres :

upgrade_file : pointeur vers le fichier de mise à jour
object_id : identifiant de l’objet
infolist : infolist à écrire dans le fichier

Valeur de retour :

1 si ok, 0 en cas d’erreur

Exemple en C :

if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* erreur */
}

Script (Python) :

# prototype
def upgrade_write_object(upgrade_file: str, object_id: int, infolist: str) -> int: ...

# exemple
weechat.upgrade_write_object(upgrade_file, 1, infolist)

upgrade_read

Mis à jour dans la 1.5.

Lire un fichier de mise à jour.

Prototype :

int weechat_upgrade_read (struct t_upgrade_file *upgrade_file);

Paramètres :

upgrade_file : pointeur vers le fichier de mise à jour

Valeur de retour :

1 si ok, 0 en cas d’erreur

Exemple en C :

weechat_upgrade_read (upgrade_file);

Script (Python) :

# prototype
def upgrade_read(upgrade_file: str) -> int: ...

# exemple
weechat.upgrade_read(upgrade_file)

upgrade_close

Fermer un fichier de mise à jour.

Prototype :

void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);

Paramètres :

upgrade_file : pointeur vers le fichier de mise à jour

Exemple en C :

weechat_upgrade_close (upgrade_file);

Script (Python) :

# prototype
def upgrade_close(upgrade_file: str) -> int: ...

# exemple
weechat.upgrade_close(upgrade_file)