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

javascript

4060

15

lua

4050

16

perl

4040

17

php

4030

18

python

4020

19

ruby

4010

20

tcl

4000

21

script

3000

22

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)

asprintf

WeeChat ≥ 4.3.0.

Formater un message dans une chaîne allouée par la fonction.

Cette fonction est définie pour les systèmes où la fonction GNU asprintf() n’est pas disponible.
Le comportement est quasiment le même à l’exception de *result qui est mis à NULL en cas d’erreur.

Prototype :

int weechat_asprintf (char **result, const char *fmt, ...);

Paramètres :

  • result : pointeur vers un pointeur de chaîne

  • fmt : chaîne de formatage

Valeur de retour :

  • nombre d’octets écrits dans *result (en excluant le caractère nul de fin), une valeur négative en cas d’erreur.

Exemple en C :

char *str;

if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
{
    /* *str == "test, 42" */
    /* ... */
    free (str);
}
else
{
    /* erreur : *str == NULL */
}
Cette fonction n’est pas disponible dans l’API script.

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.

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.

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.

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.

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.

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.

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.

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.

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).
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 :

  • 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

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 :

  • 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 :

  1. remplacer le %h du début par un répertoire WeeChat ("data" par défaut),

  2. remplacer le ~ du début par le répertoire maison de l’utilisateur (appel à string_expand_home),

  3. é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 :

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 :

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

Mis à jour dans la 4.3.0.

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 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, "[color]");
/* ... */
free (str);

Script (Python) :

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

# exemple
str = weechat.string_remove_color(ma_chaine, "[color]")

string_base_encode

WeeChat ≥ 2.4, mis à jour dans la 4.3.0.

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

Prototype :

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

Paramètres :

  • base : "16", "32", "64" ou "64url"

  • 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, mis à jour dans la 4.3.0.

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

Prototype :

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

Paramètres :

  • base : "16", "32", "64" ou "64url"

  • 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, 4.3.0, 4.4.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_state_dir}, ${weechat_cache_dir} ou ${weechat_runtime_dir}.

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

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

>> ${weechat_state_dir}
== /home/user/.local/state/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 (1)

(1) 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 (1)

(1) 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 (1)

(1) ( ,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 (1)

>> ${color:*214}texte orange gras
== texte orange gras (2)

(1) En rouge
(2) 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 la fonction util_strftimeval), le format par défaut est %F %T.

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

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

>> ${date:%!.%.3}
== 1435683765.482

${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 (1)

(1) 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

${hdata_count:name[list]}
${hdata_count:name[pointer]}

4.4.0

Nombre d’éléments dans la liste hdata ou en démarrant à pointer.

>> ${hdata_count:buffer[gui_buffers]}
== 15

${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_state_dir}

    • ${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, mis à jour dans la 4.3.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 supplémentaires.

Prototype :

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

Paramètres :

  • string : tampon où stocker la chaîne formaté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

    • %! : horodatage sous forme d’entier, en secondes (valeur de tv→tv_sec)

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 : %p", 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, mis à jour dans la 4.4.0.

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

    • WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)

  • 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

    • WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)

  • 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

      • longlong: entier de type "long long"

    • type_values : type pour les valeurs :

      • integer : entier

      • string : chaîne

      • pointer : pointeur

      • buffer : buffer

      • time : heure

      • longlong: entier de type "long long"

    • 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

javascript.conf

4060

18

lua.conf

4050

19

perl.conf

4040

20

php.conf

4030

21

python.conf

4020

22

ruby.conf

4010

23

tcl.conf

4000

24

script.conf

3000

25

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_boolean_inherited

WeeChat ≥ 4.3.0.

Retourner la valeur booléenne héritée de l’option : la valeur si l’option n’est pas NULL, ou la valeur de l’option parente (si l’option hérite d’une autre option).
Si l’option parente n’est pas trouvée, retourner la valeur par défaut de l’option.
Si la valeur parente est NULL, retourner la valeur par défaut de l’option parente.

Prototype :

int weechat_config_boolean_inherited (struct t_config_option *option);

Paramètres :

  • option : pointeur vers l’option

Valeur de retour : voir les fonctions config_boolean et config_boolean_default.

Exemple en C :

struct t_config_option *option = weechat_config_get ("irc.server.libera.autoconnect");
int autoconnect = weechat_config_boolean_inherited (option);

Script (Python):

# prototype
def config_boolean_inherited(option: str) -> int: ...

# exemple
option = weechat.config_get("irc.server.libera.autoconnect")
autoconnect = weechat.config_boolean_inherited(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_integer_inherited

WeeChat ≥ 4.3.0.

Return inherited integer value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype :

int weechat_config_integer_inherited (struct t_config_option *option);

Paramètres :

  • option : pointeur vers l’option

Valeur de retour : voir les fonctions config_integer et config_integer_default.

Exemple en C :

struct t_config_option *option = weechat_config_get ("irc.server.libera.autojoin_delay");
int delay = weechat_config_integer_inherited (option);

Script (Python):

# prototype
def config_integer_inherited(option: str) -> int: ...

# exemple
option = weechat.config_get("irc.server.libera.autojoin_delay")
delay = weechat.config_integer_inherited(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_string_inherited

WeeChat ≥ 4.3.0.

Return inherited string value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype :

const char *weechat_config_string_inherited (struct t_config_option *option);

Paramètres :

  • option : pointeur vers l’option

Valeur de retour : voir les fonctions config_string et config_string_default.

Exemple en C :

struct t_config_option *option = weechat_config_get ("irc.server.libera.msg_quit");
const char *msg_quit = weechat_config_string_inherited (option);

Script (Python):

# prototype
def config_string_inherited(option: str) -> str: ...

# exemple
option = weechat.config_get("irc.server.libera.msg_quit")
msg_quit = weechat.config_string_inherited(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")
color = 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")
color = weechat.config_color_default(option)

config_color_inherited

WeeChat ≥ 4.3.0.

Return inherited color value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype :

const char *weechat_config_color_inherited (struct t_config_option *option);

Paramètres :

  • option : pointeur vers l’option

Valeur de retour : voir les fonctions config_color et config_color_default.

Exemple en C :

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_inherited (option);

Script (Python):

# prototype
def config_color_inherited(option: str) -> str: ...

# exemple
option = weechat.config_get("plugin.section.option")
color = weechat.config_color_inherited(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: ...

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_enum_default(option)

config_enum_inherited

WeeChat ≥ 4.3.0.

Return inherited enum value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

Prototype :

int weechat_config_enum_inherited (struct t_config_option *option);

Paramètres :

  • option : pointeur vers l’option

Valeur de retour : voir les fonctions config_enum et config_enum_default.

Exemple en C :

struct t_config_option *option = weechat_config_get ("irc.server.libera.sasl_fail");
int sasl_fail = weechat_config_enum_inherited (option);

Script (Python):

# prototype
def config_enum_inherited(option: str) -> int: ...

# exemple
option = weechat.config_get("irc.server.libera.sasl_fail")
sasl_fail = weechat.config_enum_inherited(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é :

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

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 (numéros 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

javascript

javascript_script

liste des scripts

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

relay

relay_remotes

relais distants

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_items

noms des objets de barre

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"