Translators:

Questo manuale documenta il client di chat WeeChat, ed è parte del programma stesso.

Latest version of this document can be found on this page ↗.

1. Introduzione

WeeChat (Wee Enhanced Environment for Chat) è un client di chat libero, veloce e leggero, realizzato per molti sistemi operativi.

Questo manuale documenta le API per i plugin di WeeChat, utilizzate dai plugin C per interagire con il core di WeeChat.

2. Plugin in WeeChat

Un plugin è un programma C che può richiamare le funzioni di WeeChat definite in un’interfaccia.

Questo programma C non richiede i sorgenti di WeeChat per essere compilato e può essere caricato dinamicamente in WeeChat con il comano /plugin.

Il plugin deve essere una libreria dinamica, per essere caricato dinamicamente dal del sistema operativo. In GNU/Linux, il file ha estensione ".so", ".dll" in Windows.

Il plugin deve includere il file "weechat-plugin.h" (disponibile nel codice sorgente di WeeChat). Il file definisce strutture e tipi utilizzati per comunicare con WeeChat.

In order to call WeeChat functions in the format displayed in Plugin API, the following global pointer must be declared and initialized in the function weechat_plugin_init:

struct t_weechat_plugin *weechat_plugin;

2.1. Macro

Il plugin deve utilizzare alcune macro (per definire alcune variabili):

WEECHAT_PLUGIN_NAME("nome")

nome del plugin

WEECHAT_PLUGIN_DESCRIPTION("descrizione")

breve descrizione del plugin

WEECHAT_PLUGIN_AUTHOR("author")

the author name

WEECHAT_PLUGIN_VERSION("1.0")

versione del plugin

WEECHAT_PLUGIN_LICENSE("GPL3")

licenza del plugin

WEECHAT_PLUGIN_PRIORITY(1000)

the plugin priority (optional, see below)

2.2. Funzioni principali

Il plugin deve usare due funzioni:

  • weechat_plugin_init

  • weechat_plugin_end

weechat_plugin_init

Questa funzione viene chiamata quando il plugin è caricato. da WeeChat.

Prototipo:

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

Argomenti:

  • plugin: puntatore alla struttura del plugin di WeeChat, used to initialize the convenience global pointer weechat_plugin

  • argc: numero di argomenti per il plugin

  • argv: argomenti per il plugin (see below)

Valori restituiti:

  • WEECHAT_RC_OK se l’operazione ha successo (il plugin verrà caricato)

  • WEECHAT_RC_ERROR se c’è un errore (il plugin NON verrà caricato)

Plugin arguments

When the plugin is loaded by WeeChat, it receives the list of arguments in parameter argv and the number of arguments in argc.

The arguments can be:

  • command line arguments when running the WeeChat binary,

  • arguments given to the command /plugin load xxx, when the plugin is manually loaded by the user.

When the arguments come from the command line, only these arguments are sent to the plugin:

-a, --no-connect

Disabilita la connessione automatica ai server all’avvio di WeeChat.

-s, --no-script

Disabilita il caricamento automatico dei script.

plugin:option

Option for a plugin: only the plugin-related options are sent, for example only the options starting with irc: are sent to the plugin called "irc".

Plugin priority

When plugins are auto-loaded (for example on startup), WeeChat first loads all plugins, and then calls the init functions, using the priority defined in each plugin. A high priority means that the init function is called first.

Default priority is 1000 (with such priority, the plugin is loaded after all default plugins).

The default WeeChat plugins are initialized in this order:

Rank Plugin Priority

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

Questa funzione viene chiamata quando il plugin viene scaricato da WeeChat.

Prototipo:

int weechat_plugin_end (struct t_weechat_plugin *plugin);

Argomenti:

  • plugin: puntatore alla struttura plugin di WeeChat

Valori restituiti:

  • WEECHAT_RC_OK se l’operazione ha successo

  • WEECHAT_RC_ERROR se c’è un errore

2.3. Compilazione del plugin

La compilazione non richiede i sorgenti di WeeChat, è richiesto solo il file weechat-plugin.h.

Per compilare un plugin che ha un file "tizio.c" (in GNU/Linux):

gcc -fPIC -Wall -c tizio.c
gcc -shared -fPIC -o tizio.so tizio.o

2.4. Caricamento del plugin

Copiare il file tizio.so nella cartella plugin di sistema (ad esempio /usr/local/lib/weechat/plugins) oppure nella cartella plugin dell’utente (ad esempio /home/user/.local/share/weechat/plugins).

In WeeChat:

/plugin load tizio

2.5. Plugin di esempio

Un esempio completo di plugin, che aggiunge un comando /double: visualizza due volte gli argomenti nel buffer corrente, oppure esegue un comando due volte (ok, non sarà molto utile, ma è solo un esempio!):

#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for 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;


/* callback per il comando "/double" */

int
command_double_cb (const void *pointer, void *data,
                   struct t_gui_buffer *buffer,
                   int argc, char **argv, char **argv_eol)
{
    /* fa felice il compilatore C */
    (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",
                          "Visualizza due volte un messaggio "
                          "oppure esegue un comando due volte",
                          "messaggio | comando",
                          "messaggio: messaggio da visualizzare due volte\n"
                          "comando: comando da eseguire due volte",
                          NULL,
                          &command_double_cb, NULL, NULL);

    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* fa felice il compilatore C */
    (void) plugin;

    return WEECHAT_RC_OK;
}

3. Plugin API

I capitoli seguenti descrivono le funzioni nelle API, organizzate in categorie.

Per ogni funzione, viene fornita:

  • descrizione della funzione,

  • prototipo C,

  • dettaglio degli argomenti,

  • valore restituito,

  • esempio C,

  • esempio nello script Python (la sintassi è simile per gli altri linguaggi di scripting).

3.1. Registering

Functions to register a script: used only by scripting API, not the C API.

register

Register the script.

For more information, see the WeeChat scripting guide ↗.

Script (Python):

# prototipo
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...
Nota
 This function is not available in the C API.

3.2. Plugin

Funzioni per ottenere informazioni sui plugin.

plugin_get_name

Ottiene il nome del plugin.

Prototipo:

const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

Argomenti:

  • plugin: puntatore alla struttura plugin di WeeChat (può essere NULL)

Valore restituito:

  • nome del plugin, "core" per il core di WeeChat (se il puntatore al plugin è NULL)

Esempio in C:

const char *name = weechat_plugin_get_name (plugin);

Script (Python):

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

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

3.3. Stringhe

Molte delle funzioni stringa che seguono sono già disponibili tramite funzioni standard in C, ma si raccomanda di utilizzare le funzioni in questa API perché compatibili con UTF-8 e il locale.

charset_set

Imposta il nuovo set caratteri del nuovo plugin (il set caratteri predefinito è UTF-8, così se il plugin usa UTF-8 non è necessario chiamare questa funzione).

Prototipo:

void weechat_charset_set (const char *charset);

Argomenti:

  • charset: nuovo set caratteri da usare

Esempio in C:

weechat_charset_set ("iso-8859-1");

Script (Python):

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

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

iconv_to_internal

Converte le stringhe per il set caratteri interno di WeeChat (UTF-8).

Prototipo:

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

Argomenti:

  • charset: set caratteri da convertire

  • string: stringa da convertire

Valore restituito:

  • la stringa convertita (deve essere liberata richiamando "free" dopo l’utilizzo)

Esempio in C:

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

Script (Python):

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

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

iconv_from_internal

Converte la stringa dal set caratteri interno di WeeChat (UTF-8) in un’altra.

Prototipo:

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

Argomenti:

  • charset: set caratteri in uscita

  • string: stringa da convertire

Valore restituito:

  • la stringa convertita (deve essere liberata richiamando "free" dopo l’utilizzo

Esempio in C:

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

Script (Python):

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

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

gettext

Restituisce la stringa tradotta (dipende dalla lingua).

Prototipo:

const char *weechat_gettext (const char *string);

Argomenti:

  • string: stringa da tradurre

Valore restituito:

  • translated string or string if there is no translation available in local language

Esempio in C:

char *str = weechat_gettext ("hello");

Script (Python):

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

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

ngettext

Restituisce la stringa tradotta, utilizzando il singolare o il plurale, in base all’argomento count (contatore).

Prototipo:

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

Argomenti:

  • string: stringa da tradurre, singolare

  • plural: stringa da tradurre, plurale

  • count: utilizzato per scegliere tra singolare e plurale (la scelta viene fatta in base alla lingua locale)

Valore restituito:

  • translated string or string / plural if there is no translation available in local language

Esempio in C:

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

Script (Python):

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

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

asprintf

WeeChat ≥ 4.3.0.

Format a message in a string allocated by the function.

Nota
 This function is defined for systems where the GNU function asprintf() is not available.
The behavior is almost the same except that *result is set to NULL on error.

Prototipo:

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

Argomenti:

  • result: pointer to a string pointer

  • fmt: format string

Valore restituito:

  • number of bytes written in *result (excluding the final null byte), a negative value in case of error.

Esempio in C:

char *str;

if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
{
    /* *str == "test, 42" */
    /* ... */
    free (str);
}
else
{
    /* error: *str == NULL */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strndup

Return duplicated string, with a max number of bytes.

Prototipo:

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

Argomenti:

  • string: stringa da duplicare

  • bytes: max bytes to duplicate

Valore restituito:

  • stringa duplicata (deve essere liberata chiamando "free" dopo l’utilizzo)

Esempio in C:

char *str = weechat_strndup ("abcdef", 3);  /* result: "abc" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_cut

WeeChat ≥ 3.3.

Cut a string after a given number of chars, add an optional suffix after the string if it is cut.

Prototipo:

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

Argomenti:

  • string: string to cut

  • length: max chars

  • count_suffix: if 1, the length of suffix is counted in the max length

  • screen: if 1, the cut is based on width of chars displayed

  • cut_suffix: the suffix added after the string if it is cut

Valore restituito:

  • cut string (must be freed by calling "free" after use)

Esempio in C:

char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_tolower

Updated in 3.8.

Return a string with uppercase letters converted to lowercase.

Nota
 Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.
Moreover, a newly allocated string is returned and must be freed after use.

Prototipo:

char *weechat_string_tolower (const char *string);

Argomenti:

  • string: stringa da convertire

Valore restituito:

  • string with lowercase letters (must be freed by calling "free" after use)

Esempio in C:

char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_é" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_toupper

Updated in 3.8.

Return a string with lowercase letters converted to uppercase.

Nota
 Behavior has changed in version 3.8: now all lowercase letters are properly converted to uppercase (by calling function towupper), in addition to the range a to z.
Moreover, a newly allocated string is returned and must be freed after use.

Prototipo:

char *weechat_string_toupper (const char *string);

Argomenti:

  • string: stringa da convertire

Valore restituito:

  • string with uppercase letters (must be freed by calling "free" after use)

Esempio in C:

char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_É" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_charcmp

Updated in 1.0, 3.8.

Confronta due caratteri.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

Return value:

  • arithmetic result of subtracting the first UTF-8 char in string2 from the first UTF-8 char in string1:

    • < 0 if char1 < char2

    • 0 if char1 == char2

    • > 0 if char1 > char2

Esempio in C:

int diff = weechat_string_charcmp ("aaa", "ccc");  /* == -2 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_charcasecmp

Updated in 1.0, 3.8.

Confronta due caratteri, ignorando la sensibilità alle maiuscole.

Nota
 Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

Return value:

  • arithmetic result of subtracting the first UTF-8 char in string2 (converted to lowercase) from the first UTF-8 char in string1 (converted to lowercase):

    • < 0 if char1 < char2

    • 0 if char1 == char2

    • > 0 if char1 > char2

Esempio in C:

int diff = weechat_string_charcasecmp ("aaa", "CCC");  /* == -2 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strcmp

WeeChat ≥ 3.8.

Case-sensitive string comparison.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strcmp ("aaa", "ccc");  /* == -2 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strncmp

WeeChat ≥ 3.8.

Case-sensitive string comparison, for max chars.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

  • max: numero massimo di caratteri da comparare

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strncmp ("aabb", "aacc", 2);  /* == 0 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strcasecmp

Updated in 1.0, 3.8.

Case-insensitive string comparison.

Nota
 Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff;
diff = weechat_strcasecmp ("aaa", "CCC");    /* == -2 */
diff = weechat_strcasecmp ("noël", "NOËL");  /* == 0  */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strcasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0, 3.8.

Confronta stringa non sensibile alle maiuscole e alla localizzazione, usando una serie per il confronto.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

  • range: numero di caratteri nel confronto maiuscole/minuscole, ad esempio:

    • 26: A-Z vengono ridotti ad a-z

    • 29: A-Z [ \ ] vengono ridotti ad a-z { | }

    • 30: A-Z [ \ ] ^ vengono ridotti ad a-z { | } ~

Nota
 I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strncasecmp

Updated in 1.0, 3.8.

Case-insensitive string comparison, for max chars.

Nota
 Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

  • max: numero massimo di caratteri da comparare

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strncasecmp ("aabb", "AACC", 2);  /* == 0 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strncasecmp_range

WeeChat ≥ 0.3.7, updated in 1.0, 3.8.

Confronta una stringa non sensibile alle maiuscole e alla localizzazione, per un numero max di caratteri, usando una serie per il confronto.

Prototipo:

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

Argomenti:

  • string1: prima stringa da comparare

  • string2: seconda stringa da comparare

  • max: numero massimo di caratteri da comparare

  • range: numero di caratteri nel confronto maiuscole/minuscole, ad esempio:

    • 26: A-Z vengono ridotti ad a-z

    • 29: A-Z [ \ ] vengono ridotti ad a-z { | }

    • 30: A-Z [ \ ] ^ vengono ridotti ad a-z { | } ~

Nota
 I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strcmp_ignore_chars

Updated in 1.0, 3.8.

String comparison ignoring some chars.

Prototipo:

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

Argomenti:

  • string1: prima stringa per il confronto

  • string2: seconda stringa per il confronto

  • chars_ignored: stringa con caratteri da ignorare

  • case_sensitive: 1 per il confronto sensibile alle maiuscole, altrimenti 0

Nota
 Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Return value:

  • arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase if case_sensitive is set to 0) from the last compared UTF-8 char in string1 (converted to lowercase if case_sensitive is set to 0):

    • < 0 if string1 < string2

    • 0 if string1 == string2

    • > 0 if string1 > string2

Esempio in C:

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strcasestr

Updated in 1.3, 3.8.

Case-insensitive string search.

Nota
 Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Prototipo:

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

Argomenti:

  • string: stringa

  • search: stringa da cercare in string

Valore restituito:

  • puntatore alla stringa trovata, o NULL se non trovata (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

Esempio in C:

const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* risultato: puntatore a "DeF" */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

strlen_screen

WeeChat ≥ 0.4.2, updated in 3.8.

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

WeeChat color codes are skipped and don’t count in the result (this is the only difference with the function utf8_strlen_screen).

Prototipo:

int weechat_strlen_screen (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • numero di caratteri necessari per visualizzare la stringa UTF-8 su schermo

Esempio in C:

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

Script (Python):

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

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

string_match

Updated in 1.0, 3.8.

Verifica se una stringa coincide ad una mask.

Prototipo:

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

Argomenti:

  • string: stringa

  • mask: mask with wildcards (*), each wildcard matches 0 or more chars in the string

  • case_sensitive: 1 per il confronto sensibile alle maiuscole, altrimenti 0

Nota
 Since version 1.0, wildcards are allowed inside the mask (not only beginning/end of mask).
Nota
 Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Valore restituito:

  • 1 se la stringa coincide alla mask, altrimenti 0

Esempio in 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):

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

# esempio
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, updated in 3.8.

Check if a string matches a list of masks where negative mask is allowed with the format "!word". A negative mask has higher priority than a standard mask.

Prototipo:

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

Argomenti:

  • string: string

  • masks: list of masks, with a NULL after the last mask in list; each mask is compared to the string with the function string_match

  • case_sensitive: 1 for case-sensitive comparison, otherwise 0

Nota
 Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function towlower), in addition to the range A to Z.

Valore restituito:

  • 1 if string matches list of masks (at least one mask matches and no negative mask matches), otherwise 0

Esempio in 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):

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

# esempio
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.

Sostituisce la ~ iniziale con la stringa con la cartella home. Se la stringa non inizia con ~, viene restituita la stessa stringa.

Prototipo:

char *weechat_string_expand_home (const char *path);

Argomenti:

  • path: percorso

Valore restituito:

  • percorso con la ~ iniziale sostituita dalla cartella home (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/user/file.txt" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_eval_path_home

WeeChat ≥ 1.3, updated in 3.2.

Evaluate a path in 3 steps:

  1. replace leading %h by a WeeChat directory (data by default),

  2. replace leading ~ by user home directory (call to string_expand_home),

  3. evaluate variables (see string_eval_expression).

Prototipo:

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

Argomenti:

  • path: path

  • pointers: hashtable for call to function string_eval_expression

  • extra_vars: hashtable for call to function string_eval_expression

  • options: hashtable for call to function string_eval_expression, with one extra key supported:

    • directory: WeeChat directory to use when replacing %h, one of:

      • config

      • data (default)

      • cache

      • runtime

Valore restituito:

  • evaluated path (must be freed by calling "free" after use)

Esempio in C:

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

Script (Python):

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

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

string_remove_quotes

Rimuove le virgolette all’inizio e alla fine della stringa (ignora gli spazi se presenti prima delle prime virgolette o dopo le ultime virgolette).

Prototipo:

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

Argomenti:

  • string: stringa

  • quotes: stringa con elenco di virgolette

Valore restituito:

  • stringa senza virgolette all’inizio/fine (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str = weechat_string_remove_quotes (string, " 'Non posso' ", "'");
/* risultato: "Non posso" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_strip

Rimuove i caratteri ad inizio/fine della stringa.

Prototipo:

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

Argomenti:

  • string: stringa

  • left: rimuove i caratteri a sinistra se diversi da 0

  • right: rimuove i caratteri a destra se diversi da 0

  • chars: stringa con i caratteri da rimuovere

Valore restituito:

  • stringa corretta (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str = weechat_string_strip (".abc -", 0, 1, "- .");  /* risultato: ".abc" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_convert_escaped_chars

WeeChat ≥ 1.0.

Convert escaped chars to their value:

  • \": double quote

  • \\: backslash

  • \a: alert (BEL)

  • \b: backspace

  • \e: escape

  • \f: form feed

  • \n: new line

  • \r: carriage return

  • \t: horizontal tab

  • \v: vertical tab

  • \0ooo: char as octal value (ooo is 0 to 3 digits)

  • \xhh: char as hexadecimal value (hh is 1 to 2 digits)

  • \uhhhh: unicode char as hexadecimal value (hhhh is 1 to 4 digits)

  • \Uhhhhhhhh: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)

Prototipo:

char *weechat_string_convert_escaped_chars (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • string with escaped chars replaced by their value (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
/* str == "snowman: ☃" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_mask_to_regex

Restituisce una espressione regolare con una mask, dove l’unico carattere speciale è *. Tutti gli altri caratteri speciali per le espressioni regolari non vengono riconosciuti.

Prototipo:

char *weechat_string_mask_to_regex (const char *mask);

Argomenti:

  • mask: mask

Valore restituito:

  • espressione regolare, come stringa (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);

Script (Python):

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

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

string_regex_flags

WeeChat ≥ 0.3.7.

Restituisce sia il puntatore sulla stringa dopo le flag che la mask con le flag per compilare l’espressione regolare.

Prototipo:

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

Argomenti:

  • regex: POSIX extended regular expression

  • default_flags: combinazione dei seguenti valori (consultare man regcomp):

    • REG_EXTENDED

    • REG_ICASE

    • REG_NEWLINE

    • REG_NOSUB

  • flags: pointer value is set with flags used in regular expression (default flags + flags set in regular expression)

Flags must be at beginning of regular expression. Format is: "(?eins-eins)string".

Allowed flags are:

  • e: POSIX extended regular expression (REG_EXTENDED)

  • i: case-insensitive (REG_ICASE)

  • n: match-any-character operators don_t match a newline (REG_NEWLINE)

  • s: support for substring addressing of matches is not required (REG_NOSUB)

Valore restituito:

  • pointer in regex, after flags

Esempio in 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 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_regcomp

WeeChat ≥ 0.3.7.

Compile a POSIX extended regular expression using optional flags at beginning of string (for format of flags, see string_regex_flags).

Prototipo:

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

Argomenti:

  • preg: pointer to regex_t structure

  • regex: POSIX extended regular expression

  • default_flags: combination of following values (see man regcomp):

    • REG_EXTENDED

    • REG_ICASE

    • REG_NEWLINE

    • REG_NOSUB

Valore restituito:

  • same return code as function regcomp (0 if ok, other value for error, see man regcomp)

Nota
 Regular expression preg must be cleaned by calling "regfree" after use, if the function returned 0 (OK).

Esempio in C:

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
{
    /* OK */
    /* ... */
    regfree (&my_regex);
}
else
{
    /* error */
    /* ... */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_has_highlight

Controlla se una stringa ha uno o più eventi, usando la lista di parole per gli eventi.

Prototipo:

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

Argomenti:

  • string: stringa

  • highlight_words: lista di parole per gli eventi, separate da virgole

Valore restituito:

  • 1 se la stringa ha uno o più eventi, altrimenti 0

Esempio in C:

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

Script (Python):

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

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

string_has_highlight_regex

WeeChat ≥ 0.3.4.

Check if a string has one or more highlights, using a POSIX extended regular expression.
For at least one match of regular expression on string, it must be surrounded by delimiters (chars different from: alphanumeric, -, _ and |).

Prototipo:

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

Argomenti:

  • string: stringa

  • regex: POSIX extended regular expression

Valore restituito:

  • 1 se la stringa ha uno o più eventi, altrimenti 0

Esempio in C:

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

Script (Python):

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

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

string_replace

Sostituisce tutte le ricorrenze di una stringa con un’altra.

Prototipo:

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

Argomenti:

  • string: stringa

  • search: stringa da sostituire

  • replace: sostituzione per la stringa search

Valore restituito:

  • la stringa dopo search sostituita da replace (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *str = weechat_string_replace ("test", "s", "x");  /* result: "text" */
/* ... */
free (str);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_replace_regex

WeeChat ≥ 1.0.

Replace text in a string using a regular expression, replacement text and optional callback.

Prototipo:

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);

Argomenti:

  • string: string

  • regex: pointer to a regular expression (regex_t structure) compiled with WeeChat function string_regcomp or regcomp (see man regcomp)

  • replace: replacement text, where following references are allowed:

    • $0 to $99: match 0 to 99 in regular expression (0 is the whole match, 1 to 99 are groups captured between parentheses)

    • $+: the last match (with highest number)

    • $.*N: match N (can be + or 0 to 99), with all chars replaced by * (the * char can be any char between space (32) and ~ (126))

  • reference_char: the char used for reference to match (commonly $)

  • callback: an optional callback called for each reference in replace (except for matches replaced by a char); the callback must return:

    • newly allocated string: it is used as replacement text (it is freed after use)

    • NULL: the text received in callback is used as replacement text (without changes)

  • callback_data: pointer given to callback when it is called

Valore restituito:

  • string with text replaced, NULL if problem (must be freed by calling "free" after use)

Esempio in 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);
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_translate_chars

WeeChat ≥ 3.8.

Translate chars in a string.

Prototipo:

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

Argomenti:

  • string: string

  • chars1: string with chars to translate

  • chars2: string with replacement chars; it must contain the same number of UTF-8 chars than chars1

Valore restituito:

  • string with translated chars, NULL if problem (must be freed by calling "free" after use)

Esempi in 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");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_split

Updated in 2.5, 2.6.

Divide una stringa in base a uno o più delimitatori.

Prototipo:

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

Argomenti:

  • string: stringa da dividere

  • separators: delimitatori usati per dividere

  • strip_items: chars to strip from returned items (left/right); optional, can be NULL

  • flags: combination values to change the default behavior; if the value is 0, the default behavior is used (no strip of separators at beginning/end of string, multiple separators are kept as-is so empty strings can be returned); the following flags are accepted:

    • WEECHAT_STRING_SPLIT_STRIP_LEFT: strip separators on the left (beginning of string)

    • WEECHAT_STRING_SPLIT_STRIP_RIGHT: strip separators on the right (end of string)

    • WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: collapse multiple consecutive separators into a single one

    • WEECHAT_STRING_SPLIT_KEEP_EOL: keep end of line for each value

  • num_items_max: numero massimo di elementi creati (0 = nessun limite)

  • num_items: puntatore ad int che conterrà il numero di elementi creati

Nota
 With WeeChat ≤ 2.4, the flags argument was called keep_eol and took other values, which must be converted like that:
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

Valore restituito:

  • array di stringhe, NULL se si verifica un problema (deve essere liberata chiamando string_free_split dopo l’uso)

Esempi:

char **argv;
int argc;

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

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

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

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

argv = weechat_string_split (" abc, de,, fghi ", ",", " ",
                             WEECHAT_STRING_SPLIT_STRIP_LEFT
                             | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                             | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                             0, &argc);
/* result: argv[0] == "abc"
           argv[1] == "de"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_split_shell

WeeChat ≥ 1.0.

Split a string like the shell does for a command with arguments.

This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in Python repository), see this page ↗.

Prototipo:

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

Argomenti:

  • string: stringa da dividere

  • num_items: puntatore ad int che conterrà il numero di elementi creati

Valore restituito:

  • array di stringhe, NULL se si verifica un problema (deve essere liberata chiamando string_free_split dopo l’uso)

Esempio in C:

char **argv;
int argc;
argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
/* result: argv[0] == "test"
           argv[1] == "first arg"
           argv[2] == "second arg"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_free_split

Libera la memoria usata per la divisione di una stringa.

Prototipo:

void weechat_string_free_split (char **split_string);

Argomenti:

Esempio in C:

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_rebuild_split_string

Updated in 3.7.

Rebuild a string with a split string, using optional separator and index of first/last string to use.

Prototipo:

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

Argomenti:

  • split_string: stringa divisa dalla funzione string_split

  • separator: string used to separate strings (can be NULL or empty string)

  • index_start: index of first string to use (≥ 0)

  • index_end: index of last string to use (must be ≥ index_start; special value -1 can be used to use all arguments until NULL is found)

Valore restituito:

  • stringa compilata con la stringa divisa (deve essere liberata chiamando "free" dopo l’uso)

Esempio in 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);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_split_command

Divide una lista di comandi separata da separator (che può essere omesso aggiungendo \ nella stringa).

Prototipo:

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

Argomenti:

  • command: comando da dividere

  • separator: separatore

Valore restituito:

  • array di stringhe, NULL in caso di problemi (deve essere liberata chiamando free_split_command dopo l’uso)

Esempio in C:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
           argv[2] == NULL
*/
weechat_free_split_command (argv);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_free_split_command

Libera la memoria utilizzata dalla divisione di un comando.

Prototipo:

void weechat_string_free_split_command (char **split_command);

Argomenti:

Esempio in C:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_format_size

Compila una stringa con un file di dimensione fissa ed una unità tradotta nella lingua locale.

Prototipo:

char *weechat_string_format_size (unsigned long long size);

Argomenti:

  • size: dimensione (in byte)

Valore restituito:

  • stringa formattata (deve essere liberata chiamando "free" dopo l’uso)

Esempi in C:

/* esempi in lingua inglese */

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

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

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

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

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

Script (Python), WeeChat ≥ 2.2:

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

# esempio
str = weechat.string_format_size(15200)  # == "15.2 KB"

string_parse_size

WeeChat ≥ 3.7.

Parse a string with a size and optional unit and return the size in bytes.

Prototipo:

unsigned long long weechat_string_parse_size (const char *size);

Argomenti:

  • size: the size as string: positive integer number followed by optional spaces and optional unit (lower or upper case), which is one of:

    • b: bytes

    • k: kilobytes (1k = 1000 bytes)

    • m: megabytes (1m = 1000k = 1,000,000 bytes)

    • g: gigabytes (1g = 1000m = 1,000,000,000 bytes)

    • t: terabytes (1t = 1000g = 1,000,000,000,000 bytes)

Valore restituito:

  • size in bytes, 0 if error

Esempio in C:

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

Script (Python):

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

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

string_color_code_size

WeeChat ≥ 3.0.

Return the size (in bytes) of the WeeChat color code at the beginning of the string.

Prototipo:

int weechat_string_color_code_size (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • size (in bytes) of the WeeChat color code at the beginning of the string; if the string is NULL, empty or does not start with a color code, 0 is returned; if the string begins with multiple color codes, only the size of the first one is returned

Esempi:

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

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

# esempio
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

Updated in 4.3.0.

Rimuove i colori di WeeChat da una stringa.

Prototipo:

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

Argomenti:

  • string: stringa

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

Valore restituito:

  • stringa senza un colore (deve essere liberata chiamando "free" dopo l’uso)

Esempi:

/* rimuove i codici colore */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* sostituisce i codici colore con "?" */
char *str = weechat_string_remove_color (my_string2, "[color]");
/* ... */
free (str);

Script (Python):

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

# esempio
str = weechat.string_remove_color(my_string, "[color]")

string_base_encode

WeeChat ≥ 2.4, updated in 4.3.0.

Encode a string in base 16, 32, or 64.

Prototipo:

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

Argomenti:

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

  • from: stringa da codificare

  • length: lunghezza della stringa da codificare (ad esempio strlen(from))

  • to: puntatore alla stringa per memorizzare il risultato (deve essere sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Valore restituito:

  • lunghezza della stringa memorizzata in *to (lo \0 finale non conta), -1 if error

Esempio in 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=" */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_base_decode

WeeChat ≥ 2.4, updated in 4.3.0.

Decode a string encoded in base 16, 32, or 64.

Prototipo:

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

Argomenti:

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

  • from: stringa da decodificare

  • to: puntatore alla stringa per memorizzare il risultato (deve essere sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Valore restituito:

  • lunghezza della stringa memorizzata in *to (lo \0 finale non conta), -1 if error

Esempio in 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" */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_hex_dump

WeeChat ≥ 1.4.

Display a dump of data as hexadecimal and ascii bytes.

Prototipo:

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

Argomenti:

  • data: the data to dump

  • data_size: number of bytes to dump in data

  • bytes_per_line: number of bytes to display in each line

  • prefix: the prefix to display at the beginning of each line (optional, can be NULL)

  • suffix: the suffix to display at the end of each line (optional, can be NULL)

Valore restituito:

  • string with dump of data (must be freed by calling "free" after use)

Esempio in 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           "  */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_is_command_char

WeeChat ≥ 0.3.2.

Verifica che il primo carattere della stringa sia un carattere comando (il comando carattere predefinito è /).

Prototipo:

int weechat_string_is_command_char (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • 1 se il primo carattere della stringa è un comando carattere, altrimenti 0

Esempi in C:

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

Script (Python):

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

# esempi
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.

Restituisce il puntatore al testo in input per il buffer (puntatore all’interno dell’argomento "string"), oppure NULL se è un comando.

Prototipo:

const char *weechat_string_input_for_buffer (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • puntatore all’interno di "string", oppure NULL

Esempi in 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):

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

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

string_eval_expression

WeeChat ≥ 0.4.0, updated in 0.4.2, 0.4.3, 1.0, 1.1, 1.2, 1.3, 1.6, 1.8, 2.0, 2.2, 2.3, 2.7, 2.9, 3.1, 3.2, 3.3, 3.4, 3.6, 3.8, 4.0.0, 4.2.0, 4.3.0, 4.4.0.

Evaluate an expression and return result as a string. Special variables with format ${variable} are expanded (see table below).

Nota
 Since version 1.0, nested variables are supported, for example: ${color:${variable}}.

Prototipo:

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

Argomenti:

  • expr: the expression to evaluate (see conditions and variables)

  • pointers: hashtable with pointers (keys must be string, values must be pointer); pointers "window" and "buffer" are automatically added if they are not in hashtable (with pointer to current window/buffer) (can be NULL):

    • regex: pointer to a regular expression (regex_t structure) compiled with WeeChat function string_regcomp or regcomp (see man regcomp); this option is similar to regex in hashtable options (below), but is used for better performance

  • extra_vars: extra variables that will be expanded (can be NULL)

  • options: a hashtable with some options (keys and values must be string) (can be NULL):

    • type: default behavior is just to replace values in expression, other types can be selected:

      • condition: the expression is evaluated as a condition: operators and parentheses are used, result is a boolean ("0" or "1")

    • prefix: prefix before variables to replace (default: ${)

    • suffix: suffix after variables to replace (default: })

    • extra: default behavior is to just replace extra variables (extra_vars), other behavior can be selected:

      • eval: extra variables (extra_vars) are evaluated themselves before replacing (WeeChat ≥ 1.6)

    • regex: a regex used to replace text in expr (which is then not evaluated)

    • regex_replace: the replacement text to use with regex, to replace text in expr (the regex_replace is evaluated on each match of regex against expr, until no match is found)

    • debug: debug level (string with integer number ≥ 1), if enabled, a key "debug_output" is added in hashtable options:

      • 1: enable debug

      • 2: enable more verbose debug

Valore restituito:

  • evaluated expression (must be freed by calling "free" after use), or NULL if problem (invalid expression or not enough memory)

Esempi in C:

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

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

/* replace with regex */
struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
/* add brackets around URLs */
weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+");
weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
char *str4 = weechat_string_eval_expression ("test: https://weechat.org", NULL, NULL, NULL);  /* "test: [ https://weechat.org ]" */

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

Script (Python):

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

# esempi

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

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

# replace with regex: add brackets around URLs
options = {
    "regex": "[a-zA-Z0-9_]+://[^ ]+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options)  # "test: [ https://weechat.org ]"

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

List of logical operators that can be used in conditions (by order of priority, from first used to last):

Operator Min WeeChat Description Examples

&&

Logical "and"

>> 25 && 77
== 1

>> 25 && 0
== 0

||

Logical "or"

>> 25 || 0
== 1

>> 0 || 0
== 0

List of comparison operators that can be used in conditions (by order of priority, from first used to last):

Operator Min WeeChat Description Examples

=~

Is matching POSIX extended regex (optional flags are allowed, see function string_regcomp)

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

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

!~

Is NOT matching POSIX extended regex (optional flags are allowed, see function string_regcomp)

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

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

==*

2.9

Is matching mask where "*" is allowed, case-sensitive (see function string_match)

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

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

!!*

2.9

Is NOT wildcard mask where "*" is allowed, case-sensitive (see function string_match)

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

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

=*

1.8

Is matching mask where "*" is allowed, case-insensitive (see function string_match)

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

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

!*

1.8

Is NOT wildcard mask where "*" is allowed, case-insensitive (see function string_match)

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

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

==-

2.9

Is included, case-sensitive

>> abc def ==- bc
== 1

>> abc def ==- xyz
== 0

!!-

2.9

Is NOT included, case-sensitive

>> abc def !!- bc
== 0

>> abc def !!- xyz
== 1

=-

2.9

Is included, case-insensitive

>> abc def =- BC
== 1

>> abc def =- XYZ
== 0

!-

2.9

Is NOT included, case-insensitive

>> abc def !- BC
== 0

>> abc def !- XYZ
== 1

==

Equal

>> test == test
== 1

>> test == string
== 0

!=

Not equal

>> test != test
== 0

>> test != string
== 1

<=

Less or equal

>> abc <= defghi
== 1

>> abc <= abc
== 1

>> defghi <= abc
== 0

>> 15 <= 2
== 0

<

Less

>> abc < defghi
== 1

>> abc < abc
== 0

>> defghi < abc
== 0

>> 15 < 2
== 0

>=

Greater or equal

>> defghi >= abc
== 1

>> abc >= abc
== 1

>> abc >= defghi
== 0

>> 15 >= 2
== 1

>

Greater

>> defghi > abc
== 1

>> abc > abc
== 0

>> abc > defghi
== 0

>> 15 > 2
== 1

The comparison is made using floating point numbers if the two expressions are valid numbers, with one of the following formats:

  • integer (examples: 5, -7)

  • floating point number (examples: 5.2, -7.5, 2.83e-2) (WeeChat ≥ 2.0)

  • hexadecimal number (examples: 0xA3, -0xA3) (WeeChat ≥ 2.0)

To force a string comparison, you can add double quotes around each expression, for example:

  • 50 > 100 returns 0 (number comparison)

  • "50" > "100" returns 1 (string comparison)

Variables

List of variables expanded in expression (by order of priority, from first expanded to last):

Format Min WeeChat Description Examples

${raw_hl:xxx}

4.2.0

Raw string (not evaluated), with syntax highlighting (using colors).

>> ${raw_hl:${cut:1,,${rev:hello}}}
== ${cut:1,,${rev:hello}} (with colors)

${raw:xxx}

3.1

Raw string (not evaluated).

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

${hl:xxx}

4.2.0

String with syntax highlighting (using colors).

>> ${hl:${file.section.option}}
== test ${variable} (with colors)

${name}

3.4

User variable (defined with ${define:name,value}).

>> ${name}
== value

${name}

Variable name from hashtable extra_vars.

>> ${name}
== value

${weechat_xxx_dir}

3.2

A WeeChat directory: ${weechat_config_dir}, ${weechat_data_dir}, ${weechat_state_dir}, ${weechat_cache_dir} or ${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

String to evaluate.

>> ${eval:${date:${weechat.look.buffer_time_format}}}
== 19:02:45 (1)

(1) With colors if there are color codes in the option weechat.look.buffer_time_format

${eval_cond:xxx}

3.1

String to evaluate as condition.

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

${esc:xxx}
${\xxx}

1.0

String with escaped chars.

>> ${esc:prefix\tmessage}
== prefix<TAB>message

>> ${\ua9}
== ©

${chars:range}

3.8

String with a range of chars, where range is one of:
- digit (0123456789)
- xdigit (0123456789abcdefABCDEF)
- lower (all lower case letters)
- upper (all upper case letters)
- alpha (all letters)
- alnum (all letters and digits)
- a range of chars with format c1-c2 (c1 code point must be lower or equal to c2)

>> ${chars:digit}
== 0123456789

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

>> ${chars:lower}
== abcdefghijklmnopqrstuvwxyz

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

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

${lower:string}

3.6

String converted to lower case.

>> ${lower:TEST}
== test

${upper:string}

3.6

String converted to upper case.

>> ${upper:test}
== TEST

${hide:x,string}

1.1

String with hidden chars (all chars in string replaced x).

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

${cut:max,suffix,string}
${cut:+max,suffix,string}

1.8

String with max chars, and optional suffix if string is cut.
With the format +max, the suffix is counted in max length.

>> ${cut:4,…,this is a test}
== this…

>> ${cut:+4,…,this is a test}
== t…

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

${cutscr:max,suffix,string}
${cutscr:+max,suffix,string}

1.8

String with max chars displayed on screen, and optional suffix if string is cut.
With the format +max, the suffix is counted in max length.

>> ${cutscr:4,…,this is a test}
== this…

>> ${cutscr:+4,…,this is a test}
== thi…

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

${rev:xxx}

2.2

Reversed string (color codes are reversed, so the string should not contain color codes).

>> ${rev:Hello, world!}
== !dlrow ,olleH

>> ${rev:Hello, ${color:red}world!}
== !dlrow30F ,olleH (1)

(1) No color, the color code is reversed

${revscr:xxx}

2.7

Reversed string for screen, color codes are not reversed.

>> ${revscr:Hello, world!}
== !dlrow ,olleH

>> ${revscr:Hello, ${color:red}world!}
== !dlrow ,olleH (1)

(1) ,olleH in red

${repeat:count,string}

2.3

Repeated string.

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

${length:xxx}

2.7

Length of string (number of UTF-8 chars), color codes are ignored.

>> ${length:test}
== 4

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

${lengthscr:xxx}

2.7

Length of string displayed on screen, color codes are ignored.

>> ${lengthscr:test}
== 4

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

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

3.3

Split string, and return, according to number:
- count: the number of items after split
- random: a random item
- integer ≥ 1: the item by index (1 = first item)
- integer ≤ -1: the item by index from the end (-1 = last item, -2 = penultimate item, etc.),
seps is a list of chars that are used as separators (if empty, a comma is used),
flags is a list of flags separated by +:
- strip_left: strip separators on the left (beginning of string)
- strip_right: strip separators on the right (end of string)
- collapse_seps: collapse multiple consecutive separators into a single one
- keep_eol: keep end of line for each value
- strip_items=xyz: strip chars x, y and z from beginning/end of items
- max_items=N: return max N items

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

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

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

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

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

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

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

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

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

${split_shell:number,xxx}

3.3

Split shell arguments, and return, according to number:
- count: the number of arguments after split
- random: a random argument
- integer ≥ 1: the argument by index (1 = first argument)
- integer ≤ -1: the argument by index from the end (-1 = last argument, -2 = penultimate argument, etc.)

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

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

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

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

${re:xxx}

1.1

Regex data:
0 = whole string matching,
1 to 99 = group captured,
+ = last group captured,
# = index of last group captured (WeeChat ≥ 1.8),
repl_index = index of replacement being done (starts to 1) (WeeChat ≥ 3.3).

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

>> ${re:1}
== test1

>> ${re:2}
== test2

>> ${re:+}
== test2

>> ${re:#}
== 2

>> ${re:repl_index}
== 1

${color:name}

0.4.2

WeeChat color code (the name of color has optional attributes), see function color for supported formats.

>> ${color:red}red text
== red text (1)

>> ${color:*214}bold orange text
== bold orange text (2)

(1) In red
(2) In bold orange

${modifier:name,data,string}

2.7

Result of a modifier, see function hook_modifier_exec.

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

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

${info:name}
${info:name,arguments}

0.4.3

Info from WeeChat or a plugin, see function info_get.

>> ${info:version}
== 1.0

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

${base_encode:base,xxx}

2.9

String encoded in base 16, 32 or 64.

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

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

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

${base_decode:base,xxx}

2.9

String decoded from base 16, 32 or 64.

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

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

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

${date}
${date:xxx}

1.3

Current date/time, with custom format (see function util_strftimeval), default format is %F %T.

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

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

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

${env:NAME}

1.2

Value of the environment variable NAME.

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

${if:condition}
${if:condition?true} ${if:condition?true:false}

1.8

Ternary operator with a condition, a value if the condition is true (optional) and another value if the condition is false (optional). If values are not given, "1" or "0" are returned, according to the result of the condition.

>> ${if:${info:term_width}>80?big:small}
== big

${calc:xxx}

2.7

Result of expression, where parentheses and the following operators are supported:
+: addition
-: subtraction
*: multiplication
/: division
//: result of division without fractional part
%: remainder of division
**: power.

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

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

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

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

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

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

${random:min,max}

3.3

Random integer number in the range from min to max (inclusive).

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

${translate:xxx}

3.2

Translated string (depends on the language used by WeeChat to display messages).

>> ${translate:Plugin}
== Extension (1)

(1) Example in French

${define:name,value}

3.4

Define a variable name set to value, which can then be used in the same evaluated expression with ${name}.

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

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

4.4.0

Number of items in a hdata list or starting at pointer.

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

${sec.data.name}

Value of the secured data name.

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

${file.section.option}

Value of the option.

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

${name}

Value of local variable name in buffer.

>> ${nick}
== FlashCode

${pointer}

Variable pointer from hashtable pointers.

>> ${buffer}
== 0x1234abcd

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

Hdata value (pointers window and buffer are set by default with current window/buffer), list can be a list name (example: "gui_buffers"), a pointer (example: "0x1234abcd") or a pointer name (example: "my_pointer").
When var1 is a hashtable, methods keys(), values(), keys_sorted(), keys_values() and keys_values_sorted() can be called.

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

>> ${buffer[my_buffer_pointer].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.

Allocate a dynamic string, with a variable length.
Internally, a structure is allocated with the string pointer, the allocated size and current length of string.

Only the pointer to string pointer (**string) is used in all the string_dyn_* functions.

Prototipo:

char **weechat_string_dyn_alloc (int size_alloc);

Argomenti:

  • size_alloc: the initial allocated size (must be greater than zero)

Valore restituito:

  • pointer to the dynamic string

Esempio in C:

char **string = weechat_string_dyn_alloc (256);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_dyn_copy

WeeChat ≥ 1.8.

Copy a string in a dynamic string.

The pointer *string can change if the string is reallocated (if there is not enough space to copy the string).

Prototipo:

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

Argomenti:

  • string: pointer to dynamic string

  • new_string: the string to copy

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_dyn_concat

WeeChat ≥ 1.8, updated in 3.0.

Concatenate a string to a dynamic string.

The pointer *string can change if the string is reallocated (if there is not enough space to concatenate the string).

Prototipo:

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

Argomenti:

  • string: pointer to dynamic string

  • add: the string to add

  • bytes: max number of bytes in add to concatenate, must be lower or equal to length of add (-1 = automatic: concatenate whole string add) (WeeChat ≥ 3.0)

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    if (weechat_string_dyn_concat (string, "abc", -1))
    {
        /* ... */
    }
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_dyn_free

WeeChat ≥ 1.8.

Free a dynamic string.

Prototipo:

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

Argomenti:

  • string: pointer to dynamic string

  • free_string: free the string itself; if 0, the content of *string remains valid after the call to this function

Valore restituito:

  • string pointer if free_string is 0, otherwise NULL

Esempio in C:

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_concat (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
/* ... */
weechat_string_dyn_free (string, 1);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

string_concat

WeeChat ≥ 4.2.0.

Concatenate multiple strings using a separator.

Prototipo:

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

Argomenti:

  • separator: the separator string which is inserted between concatenated strings (can be NULL or empty string)

Nota
 Last argument MUST always be NULL.
A macro called WEECHAT_STR_CONCAT can be used, where the final NULL value is not needed (usage of this macro is recommended).

Valore restituito:

  • concatenated string

Esempio in 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" */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.4. UTF-8

Alcune funzioni stringa UTF-8.

utf8_has_8bits

Verifica che una stringa abbia caratteri a 8-bit.

Prototipo:

int weechat_utf8_has_8bits (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • 1 se la stringa ha caratteri a 8-bit, 0 se solo a 7-bit

Esempio in C:

if (weechat_utf8_has_8bits (string))
{
    /* ... */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_is_valid

Updated in 1.4.

Verifica che una stringa sia valida in UTF-8.

Prototipo:

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

Argomenti:

  • string: stringa

  • length: max number of UTF-8 chars to check; if ≤ 0, the whole string is checked (WeeChat ≥ 1.4)

  • error: se non NULL, *error è impostato con il puntatore al primo carattere UTF-8 non valido nella stringa, se esiste

Valore restituito:

  • 1 se la stringa UTF-8 è valida, altrimenti 0

Esempio in C:

char *error;
if (weechat_utf8_is_valid (string, -1, &error))
{
    /* ... */
}
else
{
    /* "error" punta al primo carattere non valido */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_normalize

Normalizza le stringhe UTF-8: rimuove i caratteri non UTF-8 e li sostituisce con un carattere.

Prototipo:

void weechat_utf8_normalize (char *string, char replacement);

Argomenti:

  • string: stringa

  • replacement: carattere sotitutivo per i caratteri non validi

Esempio in C:

weechat_utf8_normalize (string, '?');
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_prev_char

Updated in 1.3.

Restituisce il puntatore al carattere UTF-8 precedente in una stringa.

Prototipo:

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

Argomenti:

  • string_start: inizio della stringa (la funzione non restituirà un carattere prima di questo puntatore)

  • string: puntatore alla stringa (deve essere ≥ string_start)

Valore restituito:

  • puntatore al precedente carattere UTF-8, NULL se non trovata (raggiunta l’inizio della stringa) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

Esempio in C:

const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_next_char

Updated in 1.3.

Restituisce il puntatore al successivo carattere UTF-8 in una stringa.

Prototipo:

const char *weechat_utf8_next_char (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • puntatore al carattere UTF-8 successivo, NULL se non trovato (raggiunta la fine della stringa) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

Esempio in C:

const char *next_char = weechat_utf8_next_char (string);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_char_int

Restituisce un carattere UTF-8 come intero.

Prototipo:

int weechat_utf8_char_int (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • carattere UTF-8 come intero

Esempio in C:

int char_int = weechat_utf8_char_int ("être");  /* "ê" come intero */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_char_size

Restituisce la dimensione di un carattere UTF-8 (in byte).

Prototipo:

int weechat_utf8_char_size (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • dimensione carattere UTF-8 (in byte)

Esempio in C:

int char_size = weechat_utf8_char_size ("être");  /* == 2 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_strlen

Restituisce la lunghezza della stringa UTF-8 (nei caratteri UTF-8).

Prototipo:

int weechat_utf8_strlen (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • lunghezza della stringa UTF-8 (numero di caratteri UTF-8)

Esempio in C:

int length = weechat_utf8_strlen ("chêne");  /* == 5 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_strnlen

Restituisce la lunghezza della stringa UTF-8 (in caratteri UTF-8), per un massimo di bytes nella stringa.

Prototipo:

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

Argomenti:

  • string: stringa

  • bytes: massimo di byte

Valore restituito:

  • lunghezza della stringa UTF-8 (numero di caratteri UTF-8)

Esempio in C:

int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_strlen_screen

Restituisce il numero di caratteri necessari per visualizzare la stringa UTF-8 su schermo.

Prototipo:

int weechat_utf8_strlen_screen (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • numero di caratteri necessari per visualizzare la stringa UTF-8 su schermo

Esempio in C:

int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_char_size_screen

Updated in 3.8.

Restituisce il numero di caratteri necessari per visualizzare il carattere UTF-8 sullo schermo.

Prototipo:

int weechat_utf8_char_size_screen (const char *string);

Argomenti:

  • string: stringa

Valore restituito:

  • numero di caratteri necessario per visualizzare il carattere UTF-8 su schermo:

    • -1: non printable char

    • ≥ 0: printable char

The result is the return value of function wcwidth (see man wcwidth), with exception for the following chars, that have a specific behavior in WeeChat:

  • U+0009 (Tabulation): value of option weechat.look.tab_width ↗

  • U+0001 (1) to U+001F (31), except U+0009 (Tabulation): 1

  • U+00AD (173, soft hyphen): -1

  • U+200B (8203, zero width space): -1

Esempio in C:

int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_add_offset

Updated in 1.3.

Si sposta in avanti di N caratteri in una stringa UTF-8.

Prototipo:

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

Argomenti:

  • string: stringa

  • offset: numero di caratteri

Valore restituito:

  • puntatore alla stringa, N caratteri dopo (NULL se non raggiungibile) (WeeChat ≥ 1.3: pointer returned is a const char * instead of char *)

Esempio in C:

const char *str = "chêne";
const char *str2 = weechat_utf8_add_offset (str, 3);  /* points to "ne" */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_real_pos

Restituisce la posizione reale nella stringa UTF-8.

Prototipo:

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

Argomenti:

  • string: stringa

  • pos: posizione (numero di caratteri)

Valore restituito:

  • pozisione reale (in byte)

Esempio in C:

int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_pos

Restituisce la posizione nella stringa UTF-8.

Prototipo:

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

Argomenti:

  • string: stringa

  • real_pos: posizione (byte)

Valore restituito:

  • posizione (numero di caratteri)

Esempio in C:

int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_strndup

Restituisce la stringa duplicata, di lunghezza massima length.

Prototipo:

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

Argomenti:

  • string: stringa

  • length: caratteri massimi da duplicare

Valore restituito:

  • stringa duplicata (deve essere liberata chiamando "free" dopo l’uso)

Esempio in C:

char *string = weechat_utf8_strndup ("chêne", 3);  /* restituisce "chê" */
/* ... */
free (string);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

utf8_strncpy

WeeChat ≥ 3.8.

Copy length chars max in another string and add null byte at the end.

Prototipo:

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

Argomenti:

  • dest: destination string (must be long enough)

  • string: stringa

  • length: max chars to copy

Esempio in C:

char dest[256];

weechat_utf8_strncpy (dest, "chêne", 3);  /* copies "chê" to dest */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.5. Cryptography

Some cryptographic functions.

crypto_hash

WeeChat ≥ 2.8.

Compute hash of data.

Prototipo:

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

Argomenti:

  • data: the data to hash

  • data_size: number of bytes to hash in data

  • hash_algo: the hash algorithm, see table below

  • hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table below)

  • hash_size: pointer to a variable used to store the length of the hash computed (in bytes) (can be NULL)

Supported hash algorithms:

Value Algorithm Hash size Notes

crc32

CRC32

4 bytes (32 bits)

Not a hash algorithm in the cryptographic sense.

md5

MD5

16 bytes (128 bits)

Weak, not recommended for cryptography usage.

sha1

SHA-1

20 bytes (160 bits)

Weak, not recommended for cryptography usage.

sha224

SHA-224

28 bytes (224 bits)

sha256

SHA-256

32 bytes (256 bits)

sha384

SHA-384

48 bytes (384 bits)

sha512

SHA-512

64 bytes (512 bits)

sha512-224

SHA-512/224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.9.4.

sha512-256

SHA-512/256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.9.4.

sha3-224

SHA3-224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-256

SHA3-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-384

SHA3-384

48 bytes (384 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

sha3-512

SHA3-512

64 bytes (512 bits)

Algorithm available with libgcrypt ≥ 1.7.0.

blake2b-160

BLAKE2B-160

20 bytes (160 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-256

BLAKE2B-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-384

BLAKE2B-384

48 bytes (384 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2b-512

BLAKE2B-512

64 bytes (512 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-128

BLAKE2S-128

16 bytes (128 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-160

BLAKE2S-160

20 bytes (160 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-224

BLAKE2S-224

28 bytes (224 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

blake2s-256

BLAKE2S-256

32 bytes (256 bits)

Algorithm available with libgcrypt ≥ 1.8.0.

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

const char *data = "abcdefghijklmnopqrstuvwxyz";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

crypto_hash_file

WeeChat ≥ 3.7.

Compute hash of a file.

Prototipo:

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

Argomenti:

  • filename: percorso e nome file

  • hash_algo: the hash algorithm, see table in function crypto_hash

  • hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

  • hash_size: pointer to a variable used to store the length of the hash computed (in bytes) (can be NULL)

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_file ("/path/to/file", "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

crypto_hash_pbkdf2

WeeChat ≥ 2.8.

Compute PKCS#5 Passphrase Based Key Derivation Function number 2 (PBKDF2) hash of data.

Prototipo:

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);

Argomenti:

  • data: the data to hash

  • data_size: number of bytes to hash in data

  • hash_algo: hash algorithm used by the key derivation function, see table in function crypto_hash

  • salt: the salt

  • salt_size: number of bytes in salt

  • iterations: number of iterations

  • hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

  • hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

const char *data = "abcdefghijklmnopqrstuvwxyz";
const char *salt = "12345678901234567890123456789012";  /* 32 bytes */
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000,
                                 hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.6. Cartelle

Alcune funzioni legate alle cartelle.

crypto_hmac

WeeChat ≥ 3.2.

Compute keyed-hash message authentication code (HMAC).

Prototipo:

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

Argomenti:

  • key: the key

  • key_size: number of bytes in key

  • message: the message

  • message_size: number of bytes in message

  • hash_algo: the hash algorithm, see table in function crypto_hash

  • hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

  • hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

const char *key = "the key";
const char *message = "the message";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

mkdir_home

Updated in 3.2.

Crea una cartella nella home di WeeChat.

Prototipo:

int weechat_mkdir_home (char *directory, int mode);

Argomenti:

  • directory: name of directory to create; it can start with one of these strings to force a specific WeeChat directory (WeeChat ≥ 3.2):

    • ${weechat_config_dir}

    • ${weechat_data_dir} (default)

    • ${weechat_state_dir}

    • ${weechat_cache_dir}

    • ${weechat_runtime_dir}

  • mode: modalità per la cartella

Valore restituito:

  • 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

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

Script (Python):

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

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

mkdir

Crea una cartella.

Prototipo:

int weechat_mkdir (char *directory, int mode);

Argomenti:

  • directory: nome della cartella da creare

  • mode: modalità per la cartella

Valore restituito:

  • 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

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

Script (Python):

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

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

mkdir_parents

Crea una cartella e le cartelle genitore se necessario.

Prototipo:

int weechat_mkdir_parents (char *directory, int mode);

Argomenti:

  • directory: nome della cartella da creare

  • mode: modalità per la cartella

Valore restituito:

  • 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

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

Script (Python):

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

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

exec_on_files

Updated in 1.5, 2.0.

Cerca i file in una cartella ed esegue una callback su ogni file.

Prototipo:

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

Argomenti:

  • directory: cartella in cui cercare i file

  • recurse_subdirs: 1 to recurse into sub-directories (WeeChat ≥ 2.0)

  • hidden_files: 1 per includere i file nascosti, altrimenti 0

  • callback: funzione chiamata per ogni file trovato, argomenti:

    • void *data: puntatore

    • const char *filename: nome file trovato

  • callback_data: puntatore fornito alla callback quando chiamata da WeeChat

Esempio in C:

void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, 0, &callback, NULL);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

file_get_content

WeeChat ≥ 0.3.1.

Ottiene il contenuto del file di testo in una stringa.

Prototipo:

char *weechat_file_get_content (const char *filename);

Argomenti:

  • filename: percorso e nome file

Valore restituito:

  • contenuto del file come stringa (deve essere liberata chiamando "free dopo l’uso)

Esempio in C:

char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

file_copy

WeeChat ≥ 3.3.

Copy a file to another location.

Prototipo:

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

Argomenti:

  • from: source file

  • to: destination file

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
{
    /* OK */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

file_compress

WeeChat ≥ 3.7.

Compress a file with gzip or zstd.

Prototipo:

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

Argomenti:

  • from: source file

  • to: destination file

  • compressor: the compressor to use, one of:

    • gzip: gzip compression

    • zstd: zstandard compression (available only if zstd was enabled when WeeChat was compiled)

  • compression_level: compression level, between 1 (fast, low compression) to 100 (slow, best compression)

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
{
    /* OK */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.7. Utilità

Alcune funzioni utili.

util_timeval_cmp

Confronta due strutture "timeval".

Prototipo:

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

Argomenti:

  • tv1: prima struttura "timeval"

  • tv2: seconda struttura "timeval"

Valore restituito:

  • -1 se tv1 < tv2

  • zero se tv1 == tv2

  • +1 se tv1 > tv2

Esempio in C:

if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_timeval_diff

Updated in 1.1.

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

Prototipo:

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

Argomenti:

  • tv1: prima struttura "timeval"

  • tv2: seconda struttura "timeval"

Valore restituito:

  • difference in microseconds

Nota
 With WeeChat ≤ 1.0, the returned value was in milliseconds.

Esempio in C:

long long diff = weechat_util_timeval_diff (&tv1, &tv2);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_timeval_add

Updated in 1.1.

Add interval (in microseconds) to a timeval structure.

Prototipo:

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

Argomenti:

  • tv: struttura timeval

  • interval: interval (in microseconds)

Nota
 With WeeChat ≤ 1.0, the interval was expressed in milliseconds.

Esempio in C:

weechat_util_timeval_add (&tv, 2000000);  /* aggiunge 2 secondi */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_get_time_string

WeeChat ≥ 0.3.2, updated in 1.3.

Get date/time as a string built with "strftime" and the format defined in option weechat.look.time_format.

Prototipo:

const char *weechat_util_get_time_string (const time_t *date);

Argomenti:

  • date: puntatore alla data

Valore restituito:

  • pointer to a string with date/time

Esempio in C:

time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_strftimeval

WeeChat ≥ 4.2.0, updated in 4.3.0.

Format date and time like function strftime in C library, using struct timeval as input, and supporting extra specifiers.

Prototype:

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

Arguments:

  • string: buffer where the formatted string is stored

  • max: string size

  • format: format, the same as strftime function, with these extra specifiers:

    • %.N where N is between 1 and 6: zero-padded microseconds on N digits (for example %.3 for milliseconds)

    • %f: alias of %.6

    • %!: timestamp as integer, in seconds (value of tv→tv_sec)

Return value:

  • number of bytes put in string (value returned from strftime function)

C example:

char time[256];
struct timeval tv;
gettimeofday (&tv, NULL);
weechat_util_strftimeval (time, sizeof (time), "%FT%T.%f", &tv);
/* result: 2023-12-26T18:10:04.460509 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_parse_time

WeeChat ≥ 4.2.0.

Parse date/time with support of microseconds.

Prototype:

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

Arguments:

  • date: date/time

  • tv: parsed date/time ("timeval" structure)

Return value:

  • 1 if OK, 0 if error

C example:

struct timeval tv;
weechat_util_parse_time ("2023-12-25T10:29:09.456789Z", &tv);  /* == 1 */
/* result: tv.tv_sec == 1703500149, tv.tv_usec = 456789 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

util_version_number

WeeChat ≥ 0.3.9.

Convert a string with WeeChat version to a number.

Prototipo:

int weechat_util_version_number (const char *version);

Argomenti:

  • version: WeeChat version as string (example: "0.3.9" or "0.3.9-dev")

Esempio in 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 */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.8. Elenchi ordinati

Funzioni lista ordinata.

list_new

Crea una nuova lista.

Prototipo:

struct t_weelist *weechat_list_new ();

Valore restituito:

  • puntatore alla nuova lista

Esempio in C:

struct t_weelist *list = weechat_list_new ();

Script (Python):

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

# esempio
list = weechat.list_new()

list_add

Aggiunge un elemento in una lista.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • data: dati da inserire nella lista

  • where: posizione nella lista:

    • WEECHAT_LIST_POS_SORT: aggiunge alla lista, mantenendola ordinata

    • WEECHAT_LIST_POS_BEGINNING: aggiunge all’inizio della lista

    • WEECHAT_LIST_POS_END: aggiunge alla fine della lista

  • user_data: qualsiasi puntatore

Valore restituito:

  • puntatore al nuovo elemento

Esempio in C:

struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);

Script (Python):

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

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

list_search

Cerca un elemento nella lista.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • data: dati da cercare nella lista

Valore restituito:

  • puntatore all’elemento trovato, NULL se non trovato

Esempio in C:

struct t_weelist_item *item = weechat_list_search (list, "my data");

Script (Python):

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

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

list_search_pos

WeeChat ≥ 0.3.4.

Cerca la posizione di un elemento nella lista.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • data: dati da cercare nella lista

Valore restituito:

  • posizione dell’elemento trovato, -1 se non trovato

Esempio in C:

int pos_item = weechat_list_search_pos (list, "my data");

Script (Python):

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

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

list_casesearch

Cerca un elemento nella lista, senza effettuare una ricerca esatta.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • data: dati da cercare nella lista

Valore restituito:

  • puntatore all’elemento trovato, NULL se non trovato

Esempio in C:

struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

Script (Python):

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

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

list_casesearch_pos

WeeChat ≥ 0.3.4.

Cerca la posizione di un elemento in una lista, ricerca normale.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • data: dati da cercare nella lista

Valore restituito:

  • posizione dell’elemento trovato, -1 se non trovato

Esempio in C:

int pos_item = weechat_list_casesearch_pos (list, "my data");

Script (Python):

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

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

list_get

Restituisce un elemento in una lista in base alla sua posizione.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • position: posizione nella lista (il primo elemento è 0)

Valore restituito:

  • puntatore all’elemento trovato, NULL se non trovato

Esempio in C:

struct t_weelist_item *item = weechat_list_get (list, 0);  /* primo elemento */

Script (Python):

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

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

list_set

Imposta un nuovo valore per un elemento.

Prototipo:

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

Argomenti:

  • item: puntatore all’elemento

  • value: nuovo valore per l’elemento

Esempio in C:

weechat_list_set (item, "nuovi dati");

Script (Python):

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

# esempio
weechat.list_set(item, "nuovi dati")

list_next

Restituisce l’elemento successivo nella lista.

Prototipo:

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

Argomenti:

  • item: puntatore all’elemento

Valore restituito:

  • puntatore all’elemento successivo, NULL se il puntatore è l’ultimo oggetto nella lista

Esempio in C:

struct t_weelist_item *next_item = weechat_list_next (item);

Script (Python):

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

# esempio
item = weechat.list_next(item)

list_prev

Restituisce l’elemento precedente nella lista.

Prototipo:

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

Argomenti:

  • item: puntatore all’elemento

Valore restituito:

  • pointer to previous item, NULL if pointer was first item in list

Esempio in C:

struct t_weelist_item *prev_item = weechat_list_prev (item);

Script (Python):

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

# esempio
item = weechat.list_prev(item)

list_string

Restituisce il valore stringa di un elemento.

Prototipo:

const char *weechat_list_string (struct t_weelist_item *item);

Argomenti:

  • item: puntatore all’elemento

Valore restituito:

  • valore stringa di un elemento

Esempio in C:

weechat_printf (NULL, "valore dell'elemento: %s", weechat_list_string (item));

Script (Python):

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

# esempio
weechat.prnt("", "valore dell'elemento: %s" % weechat.list_string(item))

list_user_data

WeeChat ≥ 2.6.

Return pointer to the user data of an item.

Prototipo:

void *weechat_list_user_data (struct t_weelist_item *item);

Argomenti:

  • item: puntatore all’elemento

Valore restituito:

  • pointer to the user data of item

Esempio in C:

weechat_printf (NULL, "user data of item: %p", weechat_list_user_data (item));
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

list_size

Restituisce la dimensione della lista (numero di elementi).

Prototipo:

char *weechat_list_size (struct t_weelist *weelist);

Argomenti:

  • weelist: puntatore alla lista

Valore restituito:

  • dimensione della lista (numero di elementi), 0 se la lista è vuota

Esempio in C:

weechat_printf (NULL, "dimensione della lista: %d", weechat_list_size (list));

Script (Python):

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

# esempio
weechat.prnt("", "dimensione della lista: %d" % weechat.list_size(list))

list_remove

Rimuove un elemento in una lista.

Prototipo:

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

Argomenti:

  • weelist: puntatore alla lista

  • item: puntatore all’elemento

Esempio in C:

weechat_list_remove (list, item);

Script (Python):

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

# esempio
weechat.list_remove(list, item)

list_remove_all

Rimuove tutti gli elementi in una lista.

Prototipo:

void weechat_list_remove_all (struct t_weelist *weelist);

Argomenti:

  • weelist: puntatore alla lista

Esempio in C:

weechat_list_remove_all (list);

Script (Python):

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

# esempio
weechat.list_remove_all(list)

list_free

Libera una lista.

Prototipo:

void weechat_list_free (struct t_weelist *weelist);

Argomenti:

  • weelist: puntatore alla lista

Esempio in C:

weechat_list_free (list);

Script (Python):

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

# esempio
weechat.list_free(list)

3.9. Array lists

Array list functions.

An array list is a list of pointers with a dynamic size and optional sort.

arraylist_new

WeeChat ≥ 1.8.

Create a new array list.

Prototipo:

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);

Argomenti:

  • initial_size: initial size of the array list (not the number of items)

  • sorted: 1 to sort the array list, 0 for no sort

  • allow_duplicates: 1 to allow duplicate entries, 0 to prevent a same entry to be added again

  • callback_cmp: callback used to compare two items (optional), arguments and return value:

    • void *data: pointer

    • struct t_arraylist *arraylist: array list pointer

    • void *pointer1: pointer to first item

    • void *pointer2: pointer to second item

    • return value:

      • negative number if first item is less than second item

      • 0 if first item equals second item

      • positive number if first item is greater than second item

  • callback_cmp_data: pointer given to callback when it is called by WeeChat

  • callback_free: callback used to free an item (optional), arguments:

    • void *data: pointer

    • struct t_arraylist *arraylist: array list pointer

    • void *pointer: pointer to item

  • callback_free_data: pointer given to callback when it is called by WeeChat

Valore restituito:

  • pointer to new array list

Esempio in 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);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_size

WeeChat ≥ 1.8.

Return size of array list (number of item pointers).

Prototipo:

int weechat_list_size (struct t_arraylist *arraylist);

Argomenti:

  • arraylist: array list pointer

Valore restituito:

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

Esempio in C:

weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_get

WeeChat ≥ 1.8.

Return an item pointer by position.

Prototipo:

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

Argomenti:

  • arraylist: array list pointer

  • index: index in list (first pointer is 0)

Valore restituito:

  • pointer found, NULL if pointer was not found

Esempio in C:

void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_search

WeeChat ≥ 1.8.

Search an item in an array list.

Prototipo:

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

Argomenti:

  • arraylist: array list pointer

  • pointer: pointer to the item to search in array list

  • index: pointer to integer that will be set to the index found, or -1 if not found (optional)

  • index_insert: pointer to integer that will be set with the index that must be used to insert the element in the arraylist (to keep arraylist sorted) (optional)

Valore restituito:

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

Esempio in C:

int index, index_insert;
void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_insert

WeeChat ≥ 1.8.

Insert an item in an array list.

Prototipo:

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

Argomenti:

  • arraylist: array list pointer

  • index: position of the item in array list or -1 to add at the end (this argument is used only if the array list is not sorted, it is ignored if the array list is sorted)

  • pointer: pointer to the item to insert

Valore restituito:

  • index of new item (≥ 0), -1 if error.

Esempio in C:

int index = weechat_arraylist_insert (arraylist, -1, pointer);  /* insert at the end if not sorted */
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_add

WeeChat ≥ 1.8.

Add an item in an array list.

Prototipo:

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

Argomenti:

  • arraylist: array list pointer

  • pointer: pointer to the item to add

Valore restituito:

  • index of new item (≥ 0), -1 if error.

Esempio in C:

int index = weechat_arraylist_add (arraylist, pointer);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_remove

WeeChat ≥ 1.8.

Remove an item from an array list.

Prototipo:

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

Argomenti:

  • arraylist: array list pointer

  • index: index of the item to remove

Valore restituito:

  • index of item removed, -1 if error.

Esempio in C:

int index_removed = weechat_arraylist_remove (arraylist, index);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_clear

WeeChat ≥ 1.8.

Remove all items from an array list.

Prototipo:

int weechat_arraylist_clear (struct t_arraylist *arraylist);

Argomenti:

  • arraylist: array list pointer

Valore restituito:

  • 1 if OK, 0 if error

Esempio in C:

if (weechat_arraylist_clear (arraylist))
{
    /* OK */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

arraylist_free

WeeChat ≥ 1.8.

Free an array list.

Prototipo:

void weechat_arraylist_free (struct t_arraylist *arraylist);

Argomenti:

  • arraylist: array list pointer

Esempio in C:

weechat_arraylist_free (arraylist);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.10. Tabelle hash

Funzioni per le tabelle hash.

hashtable_new

WeeChat ≥ 0.3.3, updated in 4.4.0.

Crea una nuova tabella hash.

Prototipo:

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));

Argomenti:

  • size: dimensione dell’array interno per memorizzare le chiavi con hash, un valore più alto usa più memoria, ma ha migliori performance. (questo non è un limite per il numero di elementi nella tabella hash)

  • type_keys: tipo per le chiavi nella tabella hash:

    • WEECHAT_HASHTABLE_INTEGER

    • WEECHAT_HASHTABLE_STRING

    • WEECHAT_HASHTABLE_POINTER

    • WEECHAT_HASHTABLE_BUFFER

    • WEECHAT_HASHTABLE_TIME

    • WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)

  • type_values: tipo per i valori nella tabella hash:

    • 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: callback used to "hash" a key (key as integer value), can be NULL if key type is not "buffer" (a default hash function is used), arguments and return value:

    • struct t_hashtable *hashtable: puntatore alla tabella hash

    • const void *key: chiave

    • return value: hash della chiave

  • callback_keycmp: callback used to compare two keys, can be NULL if key type is not "buffer" (a default comparison function is used), arguments and return value:

    • struct t_hashtable *hashtable: puntatore alla tabella hash

    • const void *key1: prima chiave

    • const void *key2: seconda chiave

    • valore restituito:

      • numero negativo se key1 è minore di key2

      • 0 se key1 è uguale a key2

      • numero positivo se key1 è maggiore di key2

Valore restituito:

  • puntatore alla nuova tabella hash, NULL in caso di errore

Esempio in C:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_set_with_size

WeeChat ≥ 0.3.3, updated in 0.4.2.

Aggiunge o aggiorna un elemento nella tabella hash con la dimensione per la chiave ed il valore.

Prototipo:

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);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • key: puntatore alla chiave

  • key_size: dimensione della chiave (in byte), usata solo se il tipo delle chiavi nella tabella hash è "buffer"

  • value: puntatore al valore

  • value_size: dimensione del valore (in byte), utilizzata solo se il tipo dei valori nella tabella è "buffer"

Valore restituito:

  • pointer to item created/updated, NULL if error

Esempio in C:

weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_set

WeeChat ≥ 0.3.3, updated in 0.4.2.

Aggiunge o aggiorna un elemento nella tabella hash.

Prototipo:

struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • key: puntatore alla chiave

  • value: puntatore al valore

Valore restituito:

  • pointer to item created/updated, NULL if error

Esempio in C:

weechat_hashtable_set (hashtable, "my_key", "my_value");

hashtable_get

WeeChat ≥ 0.3.3.

Ottiene il valore associato ad una chiave in una tabella hash.

Prototipo:

void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • key: puntatore alla chiave

Valore restituito:

  • valore per la chiave, NULL se non trovata

Esempio in C:

void *value = weechat_hashtable_get (hashtable, "my_key");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_has_key

WeeChat ≥ 0.3.4.

Check if a key is in the hashtable.

Prototipo:

int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • key: puntatore alla chiave

Valore restituito:

  • 1 se la chiave si trova nella tabella hash, 0 in caso contrario

Esempio in C:

if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* la chiave è nella tabella hash */
    /* ... */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_map

WeeChat ≥ 0.3.3.

Chiama una funzione su tutte le voci della tabella hash, by insertion order in the hashtable (from oldest to newest one).

Prototipo:

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);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • callback_map: funzione chiamata per ogni voce nella tabella hash

  • callback_map_data: puntatore fornito alla mappa di callback quando chiamata

Esempio in C:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* display key and value (they are both strings here) */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_map_string

WeeChat ≥ 0.3.7.

Chiama una funzione su tutte le voci della tabella hash, by insertion order in the hashtable (from oldest to newest one), inviando chiavi e valori come stringhe.

Prototipo:

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);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • callback_map: funzione chiamata per ogni voce nella tabella hash

  • callback_map_data: puntatore fornito alla mappa di callback quando chiamata

Nota
 Le stringhe key e value inviate alla callback sono temporanee, vengono eliminate dopo la chiamata alla callback.

Esempio in C:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* display key and value */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_dup

WeeChat ≥ 1.0.

Duplicate a hashtable.

Prototipo:

struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);

Argomenti:

  • hashtable: puntatore alla tabella hash

Valore restituito:

  • duplicated hashtable

Esempio in C:

struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_get_integer

WeeChat ≥ 0.3.3.

Restituisce un valore intero per la proprietà di una tabella hash.

Prototipo:

int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • property: nome della proprietà:

    • size: dimensione dell’array interno "htable" nella tabella hash

    • items_count: numero di elementi nella tabella hash

Valore restituito:

  • valore intero della proprietà

Esempio in C:

int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_get_string

WeeChat ≥ 0.3.4.

Restituisce il valore stringa della proprietà di una tabella hash.

Prototipo:

const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *property);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • property: nome della proprietà:

    • type_keys: tipo per le chiavi:

      • integer: intero

      • string: stringa

      • pointer: puntatore

      • buffer: buffer

      • time: tempo

      • longlong: long long integer

    • type_values: tipo per i valori:

      • integer: intero

      • string: stringa

      • pointer: puntatore

      • buffer: buffer

      • time: tempo

      • longlong: long long integer

    • keys: stringa con la lista di chiavi (formato: "chiave1,chiave2,chiave3")

    • keys_sorted: stringa con l’elenco di chiavi ordinate (formato: "chiave1,chiave2,chiave3")

    • values: stringa con la lista di valori (formato: "valore1,valore2,valore3")

    • keys_values: stringa con la lista di valori e chiavi (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")

    • keys_values_sorted: stringa con la lista di chiavi e valori (ordinata per chiavi) (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")

Valore restituito:

  • valore stringa della proprietà

Esempio in C:

weechat_printf (NULL, "keys are type: %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "list of keys: %s",
                weechat_hashtable_get_string (hashtable, "keys"));
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_set_pointer

WeeChat ≥ 0.3.4.

Imposta il valore puntatore della proprietà di una tabella hash.

Prototipo:

void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • property: nome della proprietà:

    • callback_free_key: set callback function used to free keys in hashtable (WeeChat ≥ 0.4.2)

    • callback_free_value: imposta la funzione callback usata per liberare i valori nella tabella hash

  • pointer: new pointer value for property

Esempio in 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);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_add_to_infolist

WeeChat ≥ 0.3.3.

Aggiunge elementi della tabella hash ad un elemento della lista info, by insertion order in the hashtable (from oldest to newest one).

Prototipo:

int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • infolist_item: puntatore all’elemento della lista info

  • prefix: stringa usata come prefisso per i nomi nella lista info

Valore restituito:

  • 1 se ok, 0 in caso di errore

Esempio in C:

weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* se la tabella hash contiene:
     "key1" => "value 1"
     "key2" => "value 2"
   allora le seguenti variabili verranno aggiunti all'elemento  della lista info:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
*/
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_add_from_infolist

WeeChat ≥ 2.2.

Add infolist items in a hashtable.

Prototipo:

int weechat_hashtable_add_from_infolist (struct t_hashtable *hashtable,
                                         struct t_infolist *infolist,
                                         const char *prefix);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • infolist: infolist pointer

  • prefix: stringa usata come prefisso per i nomi nella lista info

Valore restituito:

  • 1 se ok, 0 in caso di errore

Esempio in C:

weechat_hashtable_add_from_infolist (hashtable, infolist, "testhash");

/* if infolist contains:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
   then following variables will be added to hashtable:
     "key1" => "value 1"
     "key2" => "value 2"
*/
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_remove

WeeChat ≥ 0.3.3.

Rimuove un elemento in una tabella hash.

Prototipo:

void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);

Argomenti:

  • hashtable: puntatore alla tabella hash

  • key: puntatore alla chiave

Esempio in C:

weechat_hashtable_remove (hashtable, "my_key");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_remove_all

WeeChat ≥ 0.3.3.

Rimuove tutti gli elementi in una tabella hash.

Prototipo:

void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

Argomenti:

  • hashtable: puntatore alla tabella hash

Esempio in C:

weechat_hashtable_remove_all (hashtable);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

hashtable_free

WeeChat ≥ 0.3.3.

Libera una tabella hash.

Prototipo:

void weechat_hashtable_free (struct t_hashtable *hashtable);

Argomenti:

  • hashtable: puntatore alla tabella hash

Esempio in C:

weechat_hashtable_free (hashtable);
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

3.11. File di configurazione

Funzioni per i file di configurazione.

config_new

Updated in 1.5, 4.0.0.

Crea un nuovo file di configurazione.

Prototipo:

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);

Argomenti:

  • name: nome del file di configurazione (senza percorso o estensione); a priority is allowed before the name, with format nnn|name where nnn is non-negative integer with priority; default priority is 1000; files are sorted by priority from higher to lower when running command /reload (see priority of configuration files below)

  • callback_reload: funzione chiamata quando il file di configurazione viene ricaricato con /reload (opzionale, può essere NULL, see below), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • valore restituito:

      • WEECHAT_CONFIG_READ_OK

      • WEECHAT_CONFIG_READ_MEMORY_ERROR

      • WEECHAT_CONFIG_READ_FILE_NOT_FOUND

  • callback_reload_pointer: puntatore fornito per ricaricare il callback quando richiesto da WeeChat

  • callback_reload_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed

Reload callback:

  • The callback must only call the function config_reload, it must not remove the configuration file.

  • A callback is needed only if it does some things before and/or after the call to the function config_reload.
    If no callback is given, WeeChat will call its internal reload function, so the configuration file will be reloaded in all cases.

Valore restituito:

  • puntatore al nuovo file di configurazione, NULL in caso di errore

Nota
 Il file NON viene creato su disco da questa funzione. Verrà creato chiamando la funzione config_write. Si dovrebbe chiamare questa funzione solo dopo aver aggiunto alcune sezioni (con config_new_section) e le opzioni (con config_new_option).

Priority of default configuration files:

Rank File Priority

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

Esempio in 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):

# prototipo
def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ...

# esempio
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.

Set configuration file version and a callback to update config sections/options on-the-fly when the config is read.

Prototipo:

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);

Argomenti:

  • config_file: configuration file pointer

  • version: version, must be ≥ 2

  • callback_update: function called when configuration file is read, for each section and each option, if the version read is less than the expected version, (optional, can be NULL, see below), arguments and return value:

    • const void *pointer: pointer

    • void *data: pointer

    • struct t_config_file *config_file: configuration file pointer

    • int version_read: version read in configuration file (1 by default)

    • struct t_hashtable *data_read: hashtable with data read from configuration file (see below)

    • return value:

      • either "data_read" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string")

  • callback_update_pointer: pointer given to callback when it is called by WeeChat

  • callback_update_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed

Update callback:

  • The callback receives a hashtable with data read from configuration file:

Key Availability Value

config

Always set

Name of configuration file, without extension (eg: weechat)

section

Always set

Name of section being read

option

For option only

Name of the option

value

For option only

Value of the option (if not NULL)

value_null

For option only

Option as NULL value (value is always 1)

  • The callback can update "section" for a line with a section and "option", "value" and "value_null" for a line with an option.

  • If "option" is set to empty string by the callback, the line read in configuration file is ignored.

  • Field "value_null" is set to force a NULL value for the option.

Valore restituito:

  • 1 if OK, 0 if error

Esempio in 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;

    /* return now if version is already up-to-date */
    if (version_read >= 2)
        return NULL;

    ptr_section = hashtable_get (data_read, "section");
    ptr_option = hashtable_get (data_read, "option");

    /* rename section "abc" to "def" */
    if (ptr_section && !ptr_option && (strcmp (ptr_section, "abc") == 0))
    {
        hashtable_set (data_read, "section", "def");
        return data_read;
    }

    /* limit other changes to section "test" */
    if (!ptr_section || !ptr_option || (strcmp (ptr_section, "test") != 0))
        return NULL;

    /* rename option "test1" to "test2" */
    if (strcmp (ptr_option, "test1") == 0)
    {
        hashtable_set (data_read, "option", "test2");
        return data_read;
    }

    /* set value to "xxx" for option "test" */
    if (strcmp (ptr_option, "test") == 0)
    {
        hashtable_set (data_read, "value", "xxx");
        return data_read;
    }

    /* set value to NULL for option "test_null" */
    if (strcmp (ptr_option, "test_null") == 0)
    {
        hashtable_set (data_read, "value_null", "1");
        return data_read;
    }

    /* no changes */
    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):

# prototipo
def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int: ...

# esempio
def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]:
    # return now if version is already up-to-date
    if version_read >= 2:
        return {}

    section = data_read.get("section")
    option = data_read.get("option")

    # rename section "abc" to "def"
    if section and not option and section == "abc":
        data_read["section"] = "def"
        return data_read

    # limit other changes to section "test"
    if not section or not option or section != "test":
        return {}

    # rename option "test1" to "test2"
    if option == "test1":
        data_read["option"] = "test2"
        return data_read

    # set value to "xxx" for option "test"
    if option == "test":
        data_read["value"] = "xxx"
        return data_read

    # set value to NULL for option "test_null"
    if option == "test_null":
        data_read["value_null"] = "1"
        return data_read

    # no changes
    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

Updated in 1.5.

Crea una nuova sezione nel file di configurazione.

Prototipo:

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);

Argomenti:

  • config_file: puntatore al file di configurazione

  • name: nome della sezione

  • user_can_add_options: 1 se l’utente può creare nuove opzioni nella sezione, oppure 0 se non gli è consentito

  • user_can_delete_options: 1 se l’utente può eliminare le opzioni nella sezione, oppure 0 se non gli è consentito

  • callback_read: funzione chiamata quando un’opzione nella sezione viene letta da disco (dovrebbe essere NULL in molti casi, tranne se l’opzione nella sezione necessita di una funzione personalizza), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • struct t_config_section *section: puntatore alla sezione

    • const char *option_name: nome dell’opzione

    • const char *value: valore

    • valore restituito:

      • 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: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_read_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

  • callback_write: funzione chiamata quando la sezione è scritta nel file (dovrebbe essere NULL in molti casi, tranne se la sezione necessita di una funzione personalizzata), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • const char *section_name: nome della sezione

    • valore restituito:

      • WEECHAT_CONFIG_WRITE_OK

      • WEECHAT_CONFIG_WRITE_ERROR

      • WEECHAT_CONFIG_WRITE_MEMORY_ERROR

  • callback_write_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_write_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

  • callback_write_default: funzione chiamata quando i valori predefiniti per la sezione devono essere scritti in un file, argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • const char *section_name: nome della sezione

    • valore restituito:

      • WEECHAT_CONFIG_WRITE_OK

      • WEECHAT_CONFIG_WRITE_ERROR

      • WEECHAT_CONFIG_WRITE_MEMORY_ERROR

  • callback_write_default_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_write_default_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

  • callback_create_option: funzione chiamata quando viene creata una nuova opzione nella sezione (NULL se la sezione non consente di creare nuove opzioni), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • struct t_config_section *section: puntatore alla sezione

    • const char *option_name: nome dell’opzione

    • const char *value: valore

    • valore restituito:

      • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

      • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

      • WEECHAT_CONFIG_OPTION_SET_ERROR

      • WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

  • callback_create_option_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_create_option_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

  • callback_delete_option: funzione chiamata quando un’opzione viene eliminata nella sezione (NULL se la sezione non consente di eliminare delle opzioni), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_file *config_file: puntatore al file di configurazione

    • struct t_config_section *section: puntatore alla sezione

    • struct t_config_option *option: puntatore all’opzione

    • valore restituito:

      • WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET

      • WEECHAT_CONFIG_OPTION_UNSET_OK_RESET

      • WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

      • WEECHAT_CONFIG_OPTION_UNSET_ERROR

  • callback_delete_option_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_delete_option_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the section is freed

Valore restituito:

  • puntatore alla nuova sezione nel file di configurazione, NULL in caso di errore

Esempio in 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; */
}

/* sezione standard, l'utente non può aggiungere/rimuovere opzioni */
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);

/* sezione speciale, l'utente può aggiungere/eliminare opzioni, e le
   opzioni necessitano di un callback per essere lette/scritte */
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):

# prototipo
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: ...

# esempio
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

Cerca una sezione in un file di configurazione.

Prototipo:

struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);

Argomenti:

  • config_file: puntatore al file di configurazione

  • section_name: nome della sezione da cercare

Valore restituito:

  • puntatore alla sezione trovata, NULL se non trovata

Esempio in C:

struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");

Script (Python):

# prototipo
def config_search_section(config_file: str, section_name: str) -> str: ...

# esempio
section = weechat.config_search_section(config_file, "section")

config_new_option

Updated in 1.5, 4.1.0.

Crea una nuova opzione nella sezione di un file di configurazione.

Prototipo:

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);

Argomenti:

  • config_file: puntatore al file di configurazione

  • section: puntatore alla sezione

  • name: nome dell’opzione; with WeeChat ≥ 1.4, the name can include a parent option name (the value of parent option will be displayed in /set command output if this option is "null"), the syntax is then: "name << file.section.option"

  • type: tipo dell’opzione:

    • boolean: valore booleano (on/off)

    • integer: valore intero

    • string: valore stringa

    • color: colore

    • enum: list of string values (stored as integer internally)

  • description: descrizione dell’opzione

  • string_values: valori come stringa (separati da |) (optional, required for type enum)

  • min: valore minimo (per il tipo integer)

  • max: valore massimo (per il tipo integer)

  • default_value: valore predefinito per l’opzione (usato per il reset dell’opzione)

  • value: valore per l’opzione

  • null_value_allowed: 1 se null (valore non definito) è consentito per l’opzione, altrimenti 0

  • callback_check_value: funzione chiamata per verificare il nuovo valore per l’opzione (ozionale), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_option *option: puntatore all’opzione

    • const char *value: nuovo valore per l’opzione

    • valore restituito:

      • 1 se il valore è corretto

      • 0 se il valore non è valido

  • callback_check_value_pointer: puntatore fornito alla callback check_value quando chiamata da WeeChat

  • callback_check_value_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed

  • callback_change: funzione chiamata quando il valore dell’opzione è stata cambiata (opzionale), argomenti:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_option *option: puntatore all’opzione

  • callback_change_pointer: puntatore fornito per cambiare alla callback quando chiamato da WeeChat

  • callback_change_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed

  • callback_delete: funzione chiamata quando l’opzione verrà eliminata (opzionale), argomenti:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_config_option *option: puntatore all’opzione

  • callback_delete_pointer: puntatore fornito per eiliminare alla callback quando chiamato da WeeChat

  • callback_delete_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the option is freed

Valore restituito:

alla nuova opzione nella sezione, NULL in caso di errore

Esempio in C:

/* booleano */
struct t_config_option *option_bool =
    weechat_config_new_option (config_file, section, "option_bool", "boolean",
                               "My option, type boolean",
                               NULL,
                               0, 0,
                               "on",
                               "on",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* intero */
struct t_config_option *option_int =
    weechat_config_new_option (config_file, section, "option_int", "integer",
                               "My option, type integer",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* stringa */
struct t_config_option *option_str =
    weechat_config_new_option (config_file, section, "option_str", "string",
                               "My option, type string",
                               NULL,
                               0, 0,
                               "test",
                               "test",
                               1,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* colore */
struct t_config_option *option_col =
    weechat_config_new_option (config_file, section, "option_col", "color",
                               "My option, type color",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* enum */
struct t_config_option *option_enum =
    weechat_config_new_option (config_file, section, "option_enum", "enum",
                               "My option, type enum",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

Script (Python):

# prototipo
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: ...

# esempio
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",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

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

option_str = weechat.config_new_option(config_file, section, "option_str", "string",
    "My option, type string",
    "", 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",
    "My option, type color",
    "", 0, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")

option_enum = weechat.config_new_option(config_file, section, "option_enum", "enum",
    "My option, type enum",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")
Nota
 In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat Scripting Guide ↗ for more info (fixed in version 0.4.1).

config_search_option

Cerca un’opzione nella sezione di un file di configurazione.

Prototipo:

struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);

Argomenti:

  • config_file: puntatore al file di configurazione

  • section: puntatore alla sezione

  • name: nome dell’opzione da cercare

Valore restituito:

  • puntatore all’opzione trovata, NULL se non trovata

Esempio in C:

struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");

Script (Python):

# prototipo
def config_search_option(config_file: str, section: str, option_name: str) -> str: ...

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

config_search_section_option

Cerca una sezione ed un’opzione in un file di configurazione o sezione.

Prototipo:

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);

Argomenti:

  • config_file: puntatore al file di configurazione

  • section: puntatore alla sezione

  • option_name: nome dell’opzione

  • section_found: puntatore al puntatore della sezione, sarà impostato alla sezione dell’opzione, se viene trovata

  • option_found: puntatore al puntatore dell’opzione, sarà impostato al puntatore di un’opzione, se viene trovata

Esempio in 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)
{
    /* opzione trovata */
}
else
{
    /* opzione non trovata */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

config_search_with_string

Get file/section/option info about an option with full name.

Prototipo:

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);

Argomenti:

  • option_name: nome completo dell’opzione (formato: "file.section.option")

  • config_file: puntatore al puntatore del file di configurazione, sarà impostato al puntatore al file di configurazione se l’opzione viene trovata

  • section: puntatore al puntatore della sezione, sarà impostato alla sezione dell’opzione, se viene trovata

  • option: puntatore al puntatore dell’opzione, sarà impostato al puntatore di un’opzione, se viene trovata

  • pos_option_name: pointer to a string pointer, will be set to pointer to name of option, if found

Esempio in C:

struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;
char *option_name;

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option,
                                   &option_name);
if (ptr_option)
{
    /* opzione trovata */
}
else
{
    /* opzione non trovata */
}
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

config_string_to_boolean

Verifica se un testo è "vero" o "falso", come valore booleano.

Prototipo:

int weechat_config_string_to_boolean (const char *text);

Argomenti:

  • text: testo da analizzare

Valore restituito:

  • 1 se il testo è "true" ("on", "yes", "y", "true", "t", "1")

  • 0 se il testo è "false" ("off", "no", "n", "false", "f", "0")

Esempio in C:

if (weechat_config_string_to_boolean (option_value))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}

Script (Python):

# prototipo
def config_string_to_boolean(text: str) -> int: ...

# esempio
if weechat.config_string_to_boolean(text):
    # ...

config_option_reset

Resetta un’opzione al proprio valore predefinito.

Prototipo:

int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);

Argomenti:

  • option: puntatore all’opzione

  • run_callback: 1 per la chiamata alla callbackse il valore dell’opzione è cambiato, altrimenti 0

Valore restituito:

  • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED se il valore dell’opzione è stato resettato

  • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE se il valore non è stato modificato

  • WEECHAT_CONFIG_OPTION_SET_ERROR in caso di errore

Esempio in 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):

# prototipo
def config_option_reset(option: str, run_callback: int) -> int: ...

# esempio
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

Imposta un nuovo valore per l’opzione.

Prototipo:

int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);

Argomenti:

  • option: puntatore all’opzione

  • value: new value for option, special values are possible according to the type of option:

    • boolean:

      • toggle: toggle the current value

    • integer, color or enum:

      • ++N: add N (any integer) to the current value

      • --N: subtract N (any integer) from the current value

  • run_callback: 1 per la chiamata alla callback chang se il valore dell’opzione è cambiato, altrimenti 0

Valore restituito:

  • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED se il valore dell’opzione è cambiato

  • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE se il valore non è cambiato

  • WEECHAT_CONFIG_OPTION_SET_ERROR in caso di errore

Esempio in C:

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

Script (Python):

# prototipo
def config_option_set(option: str, value: str, run_callback: int) -> int: ...

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

config_option_set_null

Imposta null (valore non definito) per un’opzione.

Prototipo:

int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);

Argomenti:

  • option: puntatore all’opzione

  • run_callback: 1 per la chiamata alla callback chang se il valore dell’opzione è cambiato (se non è null), altrimenti 0

Nota
 È possibile impostare il valore a null solo se è consentito per l’opzione (consultare config_new_option).

Valore restituito:

  • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED se il valore dell’opzione è cambiato

  • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE se il valore non è cambiato

  • WEECHAT_CONFIG_OPTION_SET_ERROR in caso di errore

Esempio in 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):

# prototipo
def config_option_set_null(option: str, run_callback: int) -> int: ...

# esempio
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

Rimuove/ripristina un’opzione.

Prototipo:

int weechat_config_option_unset (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Valore restituito:

  • WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET se il valore dell’opzione non è stato ripristinato

  • WEECHAT_CONFIG_OPTION_UNSET_OK_RESET se il valore dell’opzione è stato ripristinato

  • WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED se l’opzione è stata rimossa

  • WEECHAT_CONFIG_OPTION_UNSET_ERROR in caso di errore

Esempio in 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):

# prototipo
def config_option_unset(option: str) -> int: ...

# esempio
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

Rinomina un’opzione.

Prototipo:

void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);

Argomenti:

  • option: puntatore all’opzione

  • new_name: nuovo nome per l’opzione

Esempio in C:

weechat_config_option_rename (option, "new_name");

Script (Python):

# prototipo
def config_option_rename(option: str, new_name: str) -> int: ...

# esempio
weechat.config_option_rename(option, "new_name")

config_option_get_string

WeeChat ≥ 1.9.

Return string value of an option property.

Prototipo:

const char *weechat_config_option_get_string (struct t_config_option *option,
                                              const char *property);

Argomenti:

  • option: puntatore all’opzione

  • property: nome della proprietà:

    • config_name: file name

    • section_name: section name

    • name: option name

    • parent_name: name of parent option

    • type: option type, one of:

      • boolean

      • integer

      • string

      • color

      • enum

    • description: option description

Valore restituito:

  • string value of property

Esempio in C:

const char *type = weechat_config_option_get_string (option, "type");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

config_option_get_pointer

Restituisce un puntatore alla proprietà di un’opzione.

Prototipo:

void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);

Argomenti:

  • option: puntatore all’opzione

  • property: nome della proprietà:

    • config_file: puntatore al file di configurazione (struct t_config_file *)

    • section: puntatore alla sezione (struct t_config_section *)

    • name: nome dell’opzione (char *)

    • parent_name: name of parent option (char *) (WeeChat ≥ 1.4)

    • type: tipo dell’opzione (int *)

    • description: descrizione dell’opzione (char *)

    • string_values: valori stringa (char *)

    • min: valore minimo (int *)

    • max: valore massimo (int *)

    • default_value: valore predefinito (dipende dal tipo)

    • value: valore corrente (dipende dal tipo)

    • prev_option: puntatore all’opzione precedente (struct t_config_option *)

    • next_option: puntatore all’opzione successiva (struct t_config_option *)

Valore restituito:

  • puntatore alla proprietà richiesta

Esempio in C:

char *description = weechat_config_option_get_pointer (option, "description");
Nota
 Questa funzione non è disponibile nelle API per lo scripting.

config_option_is_null

Verifica se un opzione è "null" (valore non definito).

Prototipo:

int weechat_config_option_is_null (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Valore restituito:

  • 1 se il valore dell’opzione è "null"

  • 0 se il valore dell’opzione non è "null"

Esempio in C:

if (weechat_config_option_is_null (option))
{
    /* il valore è "null" */
}
else
{
    /* il valore non è "null" */
}

Script (Python):

# prototipo
def config_option_is_null(option: str) -> int: ...

# esempio
if weechat.config_option_is_null(option):
    # ...

config_option_default_is_null

Verifica che il valore predefinito di un’opzione sia "null" (valore non definito).

Prototipo:

int weechat_config_option_default_is_null (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Valore restituito:

  • 1 se il valore predefinito di un’opzione è "null"

  • 0 se il valore predefinito di un’opzione non è "null"

Esempio in C:

if (weechat_config_option_default_is_null (option))
{
    /* il valore predefinito è "null" */
}
else
{
    /* il valore predefinito non è "null" */
}

Script (Python):

# prototipo
def config_option_default_is_null(option: str) -> int: ...

# esempio
if weechat.config_option_default_is_null(option):
    # ...

config_boolean

Restituisce il valore bool di un’opzione.

Prototipo:

int weechat_config_boolean (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: boolean value of option (0 or 1)

  • integer: 0

  • string: 0

  • color: 0

  • enum: 0

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}

Script (Python):

# prototipo
def config_boolean(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...

config_boolean_default

Restituisce il valore bool predefinito di un’opzione.

Prototipo:

int weechat_config_boolean_default (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: default boolean value of option (0 or 1)

  • integer: 0

  • string: 0

  • color: 0

  • enum: 0

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}

Script (Python):

# prototipo
def config_boolean_default(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...

config_boolean_inherited

WeeChat ≥ 4.3.0.

Return inherited boolean 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.

Prototipo:

int weechat_config_boolean_inherited (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value: see functions config_boolean and config_boolean_default.

Esempio in C:

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

Script (Python):

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

# esempio
option = weechat.config_get("irc.server.libera.autoconnect")
autoconnect = weechat.config_boolean_inherited(option)

config_integer

Restituisce il valore intero di un’opzione.

Prototipo:

int weechat_config_integer (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: boolean value of option (0 or 1)

  • integer: integer value of option

  • string: 0

  • color: color index

  • enum: integer value of option (index of enum value)

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);

Script (Python):

# prototipo
def config_integer(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)

config_integer_default

Restituisce il valore intero predefinito di un’opzione.

Prototipo:

int weechat_config_integer_default (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: default boolean value of option (0 or 1)

  • integer: default integer value of option

  • string: 0

  • color: default color index

  • enum: default integer value of option (index of enum value)

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);

Script (Python):

# prototipo
def config_integer_default(option: str) -> int: ...

# esempio
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.

Prototipo:

int weechat_config_integer_inherited (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value: see functions config_integer and config_integer_default.

Esempio in C:

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

Script (Python):

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

# esempio
option = weechat.config_get("irc.server.libera.autojoin_delay")
delay = weechat.config_integer_inherited(option)

config_string

Restituisce il valore stringa di un’opzione.

Prototipo:

const char *weechat_config_string (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: "on" if value is true, otherwise "off"

  • integer: NULL

  • string: string value of option

  • color: name of color

  • enum: string value of option

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);

Script (Python):

# prototipo
def config_string(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)

config_string_default

Restituisce il valore stringa predefinito di un’opzione.

Prototipo:

const char *weechat_config_string_default (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: "on" if default value is true, otherwise "off"

  • integer: NULL

  • string: default string value of option

  • color: name of default color

  • enum: default string value of option

Esempio in C:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);

Script (Python):

# prototipo
def config_string_default(option: str) -> str: ...

# esempio
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.

Prototipo:

const char *weechat_config_string_inherited (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value: see functions config_string and config_string_default.

Esempio in 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):

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

# esempio
option = weechat.config_get("irc.server.libera.msg_quit")
msg_quit = weechat.config_string_inherited(option)

config_color

Restituisce il valore colore di un’opzione.

Prototipo:

const char *weechat_config_color (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: NULL

  • integer: NULL

  • string: NULL

  • color: name of color

  • enum: NULL

Esempio in C:

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

Script (Python):

# prototipo
def config_color(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
color = weechat.config_color(option)

config_color_default

Restituisce il valore colore predefinito di un’opzione.

Prototipo:

const char *weechat_config_color_default (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value, depending on the option type:

  • boolean: NULL

  • integer: NULL

  • string: NULL

  • color: name of default color

  • enum: NULL

Esempio in C:

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

Script (Python):

# prototipo
def config_color_default(option: str) -> str: ...

# esempio
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.

Prototipo:

const char *weechat_config_color_inherited (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value: see functions config_color and config_color_default.

Esempio in C:

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

Script (Python):

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

# esempio
option = weechat.config_get("plugin.section.option")
color = weechat.config_color_inherited(option)

config_enum

WeeChat ≥ 4.1.0.

Return enum value of option, as integer.

Prototype:

int weechat_config_enum (struct t_config_option *option);

Arguments:

  • option: option pointer

Return value, depending on the option type:

  • boolean: boolean value of option (0 or 1)

  • integer: integer value of option

  • string: 0

  • color: color index

  • enum: integer value of option (index of enum value)

C example:

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

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_enum(option)

config_enum_default

WeeChat ≥ 4.1.0.

Return default enum value of option, as integer.

Prototype:

int weechat_config_enum_default (struct t_config_option *option);

Arguments:

  • option: option pointer

Return value, depending on the option type:

  • boolean: default boolean value of option (0 or 1)

  • integer: default integer value of option

  • string: 0

  • color: default color index

  • enum: integer value of option (index of enum value)

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_enum_default (option);

Script (Python):

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

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

config_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.

Prototipo:

int weechat_config_enum_inherited (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Return value: see functions config_enum and config_enum_default.

Esempio in C:

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

Script (Python):

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

# esempio
option = weechat.config_get("irc.server.libera.sasl_fail")
sasl_fail = weechat.config_enum_inherited(option)

config_write_option

Scrive una riga nel file di configurazione con l’opzione ed il suo valore (questa funzione dovrebbe essere chiamata solo nelle callback "write" o "write_default" per una sezione).

Prototipo:

void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);

Argomenti:

  • config_file: puntatore al file di configurazione

  • option: puntatore all’opzione

Esempio in C:

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_option (config_file, option);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototipo
def config_write_option(config_file: str, option: str) -> int: ...

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

config_write_line

Scrive una riga nel file di configurazione (questa funzione dovrebbe essere chiamata solo nelle callback "write" o "write_default" per una sezione).

Prototipo:

void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);

Argomenti:

  • config_file: puntatore al file di configurazione

  • option_name: nome dell’opzione

  • value: valore (se NULL, allora la riga con il nome della sezione viene scritto, ad esempio: "[section]")

Esempio in C:

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototipo
def config_write_line(config_file: str, option_name: str, value: str) -> int: ...

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

config_write

Scrive il file di configurazione su disco.

Prototipo:

int weechat_config_write (struct t_config_file *config_file);

Argomenti:

  • config_file: puntatore al file di configurazione

Valore restituito:

  • WEECHAT_CONFIG_WRITE_OK se la configurazione è stata scritta

  • WEECHAT_CONFIG_WRITE_MEMORY_ERROR se non c’è memoria sufficiente

  • WEECHAT_CONFIG_WRITE_ERROR se si è verificato un altro errore

Esempio in 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):

# prototipo
def config_write(config_file: str) -> int: ...

# esempio
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

Legge il file di configurazione da disco.

Prototipo:

int weechat_config_read (struct t_config_file *config_file);

Argomenti:

  • config_file: puntatore al file di configurazione

Valore restituito:

  • WEECHAT_CONFIG_READ_OK se la configurazione è stata caricata

  • WEECHAT_CONFIG_READ_MEMORY_ERROR se non c’è memoria sufficiente

  • WEECHAT_CONFIG_READ_FILE_NOT_FOUND se il file non è stato trovato

Esempio in 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):

# prototipo
def config_read(config_file: str) -> int: ...

# esempio
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

Ricarica il file di configurazione da disco.

Prototipo:

int weechat_config_reload (struct t_config_file *config_file);

Argomenti:

  • config_file: configuration file pointer

Valore restituito:

  • WEECHAT_CONFIG_READ_OK se il file di configurazione è stato ricaricato

  • WEECHAT_CONFIG_READ_MEMORY_ERROR se non c’è memoria sufficiente

  • WEECHAT_CONFIG_READ_FILE_NOT_FOUND se il file non è stato trovato

Esempio in 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):

# prototipo
def config_reload(config_file: str) -> int: ...

# esempio
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

Libera un’opzione.

Prototipo:

void weechat_config_option_free (struct t_config_option *option);

Argomenti:

  • option: puntatore all’opzione

Esempio in C:

weechat_config_option_free (option);

Script (Python):

# prototipo
def config_option_free(option: str) -> int: ...

# esempio
weechat.config_option_free(option)

config_section_free_options

Libera tutte le opzioni in una sessione.

Prototipo:

void weechat_config_section_free_options (struct t_config_section *section);

Argomenti:

  • section: puntatore alla sezione

Esempio in C:

weechat_config_section_free_options (section);

Script (Python):

# prototipo
def config_section_free_options(section: str) -> int: ...

# esempio
weechat.config_section_free_options(section)

config_section_free

Libera una sezione.

Prototipo:

void weechat_config_section_free (struct t_config_section *section);

Argomenti:

  • section: puntatore alla sezione

Esempio in C:

weechat_config_section_free (section);

Script (Python):

# prototipo
def config_section_free(section: str) -> int: ...

# esempio
weechat.config_section_free(section)

config_free

Libera un file di configurazione.

Prototipo:

void weechat_config_free (struct t_config_file *config_file);

Argomenti:

  • config_file: puntatore al file di configurazione

Esempio in C:

weechat_config_free (config_file);

Script (Python):

# prototipo
def config_free(config_file: str) -> int: ...

# esempio
weechat.config_free(config_file)

config_get

Cerca un’opzione con il nome completo.

Prototipo:

struct t_config_option *weechat_config_get (const char *option_name);

Argomenti:

  • option_name: nome completo dell’opzione (formato: "file.section.option")

Valore restituito:

  • puntatore all’opzione trovata, NULL se non trovata

Esempio in C:

struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

Script (Python):

# prototipo
def config_get(option_name: str) -> str: ...

# esempio
option = weechat.config_get("weechat.look.item_time_format")

config_get_plugin

Cerca un’opzione nei file di configurazione dei plugin (plugins.conf).

Prototipo:

const char *weechat_config_get_plugin (const char *option_name);

Argomenti:

  • option_name: nome dell’opzione, WeeChat aggiungerà il prefisso "plugins.var.xxx." (dove "xxx" è il nome del plugin corrente)

Valore restituito:

  • valore dell’opzione trovata, NULL se non trovata

Esempio in C:

/* se il plugin corrente è "test", allora cerca il valore
   dell'opzione "plugins.var.test.option" nel file plugins.conf */
char *value = weechat_config_get_plugin ("option");

Script (Python):

# prototipo
def config_get_plugin(option_name: str) -> str: ...

# esempio
value = weechat.config_get_plugin("option")

config_is_set_plugin

Verifica se un’opzione è impostata nel file di configurazione dei plugin (plugins.conf).

Prototipo:

int weechat_config_is_set_plugin (const char *option_name);

Argomenti:

  • option_name: nome dell’opzione, WeeChat aggiunge il prefisso "plugins.var.xxx." (dove "xxx" è il nome del plugin corrente)

Valore restituito:

  • 1 se l’opzione è impostata, 0 se l’opzione non esiste

Esempio in C:

if (weechat_config_is_set_plugin ("option"))
{
    /* l'opzione è impostata */
}
else
{
    /* l'opzione non esiste */
}

Script (Python):

# prototipo
def config_is_set_plugin(option_name: str) -> int: ...

# esempio
if weechat.config_is_set_plugin("option"):
    # l'opzione è impostata
    # ...
else:
    # l'opzione non esiste
    # ...

config_set_plugin

Imposta il nuovo valore per l’opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

int weechat_config_set_plugin (const char *option_name, const char *value);

Argomenti:

  • option_name: nome dell’opzione, WeeChat aggiunge il prefisso "plugins.var.xxx." (dove "xxx" è il nome del plugin corrente)

  • value: new value for option

Valore restituito:

  • WEECHAT_CONFIG_OPTION_SET_OK_CHANGED se il valore dell’opzione è stato modificato

  • WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE se il valore non è cambiato

  • WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND se l’opzione non è stata trovata

  • WEECHAT_CONFIG_OPTION_SET_ERROR in caso di errore

Esempio in C:

switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototipo
def config_set_plugin(option_name: str, value: str) -> int: ...

# esempio
rc = weechat.config_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

config_set_desc_plugin

WeeChat ≥ 0.3.5.

Imposta la descrizione per l’opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);

Argomenti:

  • option_name: nome dell’opzione, WeeChat aggiungerà il prefisso "plugins.desc.xxx." (dove "xxx" è il nome del plugin corrente)

  • description: descrizione per l’opzione

Nota
 Non è un problema se l’opzione (plugins.var.xx.option_name) non esiste. Una futura creazione dell’opzione con questo nome userà questa descrizione.

Esempio in C:

weechat_config_set_desc_plugin ("option", "description of option");

Script (Python):

# prototipo
def config_set_desc_plugin(option_name: str, description: str) -> int: ...

# esempio
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")

config_unset_plugin

Disattiva l’opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

int weechat_config_unset_plugin (const char *option_name);

Argomenti:

  • option_name: nome dell’opzione, WeeChat aggiunge il prefisso "plugins.var.xxx." (dove xxx è il nome del plugin corrente)

Valore restituito:

  • WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET se il valore dell’opzione non è stato resettato

  • WEECHAT_CONFIG_OPTION_UNSET_OK_RESET se il valore dell’opzione è stato resettato

  • WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED se l’opzione è stata rimossa

  • WEECHAT_CONFIG_OPTION_UNSET_ERROR in caso di errore

Esempio in 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):

# prototipo
def config_unset_plugin(option_name: str) -> int: ...

# esempio
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. Combinazione tasti

Funzioni per le combinazioni dei tasti.

key_bind

WeeChat ≥ 0.3.6, updated in 1.8.

Aggiunge una nuova combinazione tasto.

Nota
 A differenza del comando /key bind, questa funzione non cambia mai una combinazione tasti esistente, ma ne vengono create di nuove. Per rimuovere una combinazione tasti, usare key_unbind.

Prototipo:

int weechat_key_bind (const char *context, struct t_hashtable *keys);

Argomenti:

  • context: contesto per i tasti:

    • default: contesto default (azioni comuni)

    • search: contesto search (quando si cerca testo nel buffer)

    • cursor: movimento libero del cursore sullo schermo

    • mouse: tasti per gli eventi del mouse

  • keys: hashtable with key bindings; it can contain following special keys:

    • __quiet: do not display the keys added in core buffer (WeeChat ≥ 1.8)

Valore restituito:

  • numero delle combinazioni tasti aggiunte

Esempio in 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):

# prototipo
def key_bind(context: str, keys: Dict[str, str]) -> int: ...

# esempio
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)

key_unbind

WeeChat ≥ 0.3.6, updated in 2.0.

Rimuove una o più associazioni tasti.

Attenzione
 Alla chiamata di questa funzione, assicurarsi che non venga rimossa una combinazione tasti definita dall’utente.

Prototipo:

int weechat_key_unbind (const char *context, const char *key);

Argomenti:

  • context: contesto per i tasti (consultare key_bind)

  • key: tasto da rimuovere o un valore speciale "area:XXX" per rimuovere tutti i tasti che hanno XXX come prima o seconda area; if the key starts with "quiet:", the keys removed are not displayed in core buffer (WeeChat ≥ 2.0).

Valore restituito:

  • numero di combinazioni tasti rimosse

Esempio in C:

/* rimuove un singolo tasto */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* rimuove tutti i tasti con la zona "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");

Script (Python):

# prototipo
def key_unbind(context: str, key: str) -> int: ...

# esempi

# rimuove un singolo tasto
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# rimuove tutti i tasti con la zona "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")

3.13. Visualizzazione

Funzioni per visualizzare il testo nei buffer.

prefix

Restituisce un prefisso.

Prototipo:

const char *weechat_prefix (const char *prefix);

Argomenti:

  • prefix: nome del prefisso, see table below

Valore restituito:

  • valore del prefisso (stringa con prefisso e codici colori), stringa vuota se il prefisso non è stato trovato

List of prefixes:

Prefisso Valore Colore Descrizione

error

=!=

giallo

Messaggio di errore.

network

--

magenta

Messaggio dalla rete.

action

*

bianco

Azione automatica.

join

-->

verde chiaro

Qualcuno entra nella chat corrente.

quit

<--

rosso chiaro

Qualcuno lascia la chat corrente.
Nota
 Valori e colori possono essere personalizzati con il comando /set.

Esempio in C:

weechat_printf (NULL, "%sQuesto è un errore...", weechat_prefix ("error"));

Script (Python):

# prototipo
def prefix(prefix: str) -> str: ...

# esempio
weechat.prnt("", "%sQuesto è un errore..." % weechat.prefix("error"))

color

Restituisce una codice colore stringa da visualizzare.

Prototipo:

const char *weechat_color (const char *color_name);

Argomenti:

  • color_name: nome del colore, uno di:

    • WeeChat color option name (from weechat.color.xxx), for example chat_delimiters

    • option name (format: file.section.option), for example irc.color.message_quit (WeeChat ≥ 1.2)

    • colore con attributi/sfondo opzionali (vedi sotto)

    • attributo:

      • blink: set blink

      • -blink: remove blink

      • dim: set "dim" (half bright)

      • -dim: remove "dim" (half bright)

      • bold: imposta grassetto

      • -bold: rimuove grassetto

      • reverse: imposta inverso

      • -reverse: rimuove inverso

      • italic: imposta corsivo

      • -italic: rimuove corsivo

      • underline: imposta sottolineato

      • -underline: rimuove sottolineato

      • emphasis: toggle the emphasis for text (note: this should be used only in bars, because WeeChat uses text emphasis when searching text in buffer) (WeeChat ≥ 0.4.2)

    • nome colore della barra:

      • bar_fg: colore di primo piano della barra

      • bar_delim: colore dei delimitatori della barra

      • bar_bg: colore di sfondo della barra

    • reset:

      • reset: ripristina colore ed attributi

      • resetcolor: ripristina colore (mantiene attributi) (WeeChat ≥ 0.3.6)

Il formato del colore è: attributi (opzionale) + nome colore +",sfondo" (opzionale). Gli attributi possibili sono:

  • %: blink

  • .: "dim" (half bright)

  • * : testo in grassetto

  • ! : video inverso

  • / : corsivo

  • _ : testo sottolineato

  • | : mantiene attributi: non ripristina grassetto/inverso/corsivo/sottolineato al cambio di colore (WeeChat ≥ 0.3.6)

Esempi:

  • yellow : giallo

  • _green : verde sottolineato

  • *214 : arancione grassetto

  • yellow,red : giallo su rosso

  • |cyan : ciano (e mantiene qualsiasi attributo impostato in precedenza)

Valore restituito:

  • stringa con il codice colore, o una stringa vuota se non trovata

Esempio in C:

weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));

Script (Python):

# prototipo
def color(color_name: str) -> str: ...

# esempio
weechat.prnt("", "Color: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

printf

Visualizza un messaggio su un buffer.

Prototipo:

void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

This function is a shortcut for function printf_datetime_tags.
These two calls give exactly same result:

weechat_printf (buffer, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

Argomenti:

  • buffer: puntatore al buffer, se NULL il messaggio viene visualizzato sul buffer di WeeChat

  • message: messaggio da visualizzare

Nota
 La prima tabulazione nel messaggio ("\t") è usata per separare il prefisso dal messaggio.
Se il proprio messaggio ha alcune tabulazioni e non si vuole il prefisso, allora bisogna utilizzare uno spazio, una tabulazione, poi il messaggio (consultare l’esempio successivo): ciò disabilita il prefisso (lo spazio prima della tabulazione non verrà mostrato).
Nota
 With two tabs ("\t") at beginning of message, time will not be displayed and message will have no alignment at all. Moreover, the date in message will be set to 0.

Esempio in C:

weechat_printf (NULL, "Benvenuto sul buffer di WeeChat");
weechat_printf (buffer, "Benvenuto su questo buffer");
weechat_printf (buffer, "%sQuesto è un errore!", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni");
weechat_printf (buffer, "\t\tMessage without time/alignment");
weechat_printf (buffer, "\t\t");  /* empty line (without time) */

Script (Python):

# prototipo
def prnt(buffer: str, message: str) -> int: ...

# esempio
weechat.prnt("", "Benvenuto sul buffer di WeeChat")
weechat.prnt(buffer, "Benvenuto su questo buffer")
weechat.prnt(buffer, "%sQuesto è un errore!" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni")
weechat.prnt(buffer, "\t\tMessage without time/alignment")
weechat.prnt(buffer, "\t\t")  # empty line (without time)
Nota
 La funzione è chiamata "print" negli script ("prnt" in Python).

printf_date_tags

Visualizza un messaggio sul buffer, usando tag e data personalizzati.

Prototipo:

void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);

This function is a shortcut for function printf_datetime_tags.
These two calls give exactly same result:

weechat_printf_date_tags (buffer, 0, NULL, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

Argomenti:

  • buffer: puntatore al buffer, se NULL il messaggio viene visualizzato sul buffer di WeeChat

  • date: data per il messaggio (0 indica data/ora corrente)

  • tags: lista di tag separati da virgole (NULL means no tags)

  • message: messaggio da visualizzare

See the WeeChat user’s guide / Lines tags ↗ for a list of commonly used tags in WeeChat.

Esempio in C:

weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Messaggio 2 minuti fa, con tag 'notify_message'");

Script (Python):

# prototipo
def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ...

# esempio
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Messaggio 2 minuti fa, con tag 'notify_message'")
Nota
 La funzione è chiamata "print_date_tags" negli script ("prnt_date_tags" in Python).

printf_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a buffer, using a custom date/time (with microseconds) and tags.

Prototipo:

void weechat_printf_datetime_tags (struct t_gui_buffer *buffer, time_t date,
                                   int date_usec, const char *tags, const char *message, ...);

Argomenti:

  • buffer: puntatore al buffer, se NULL il messaggio viene visualizzato sul buffer di WeeChat

  • date: data per il messaggio (0 indica data/ora corrente)

  • date_usec: microseconds of date (between 0 and 999999)

  • tags: lista di tag separati da virgole (NULL means no tags)

  • message: messaggio da visualizzare

See the WeeChat user’s guide / Lines tags ↗ for a list of commonly used tags in WeeChat.

Esempio in 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",
                              "Messaggio 2 minuti fa, con tag 'notify_message'");

Script (Python):

# prototipo
def prnt_datetime_tags(buffer: str, date: int, date_usec: int, tags: str, message: str) -> int: ...

# esempio
now = time.time()
time_sec = int(now)
time_usec = int((now * 1000000) % 1000000)
weechat.prnt_datetime_tags("", time_sec - 120, time_usec, "notify_message",
                           "Messaggio 2 minuti fa, con tag 'notify_message'")
Nota
 La funzione è chiamata "print_datetime_tags" negli script ("prnt_datetime_tags" in Python).

printf_y

Visualizza un messaggio sulla riga di un buffer con contenuto libero.

Prototipo:

void weechat_printf_y (struct t_gui_buffer *buffer, int y, const char *message, ...);

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

weechat_printf_y (buffer, 0, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

Argomenti:

  • buffer: puntatore al buffer

  • y: numero di riga (la prima riga è 0); a negative value adds a line after last line displayed: absolute value of y is the number of lines after last line (for example -1 is immediately after last line, -2 is 2 lines after last line) (WeeChat ≥ 1.0)

  • message: messaggio da visualizzare

Esempio in C:

weechat_printf_y (buffer, 2, "Mio messaggio sulla terza riga");

Script (Python):

# prototipo
def prnt_y(buffer: str, y: int, message: str) -> int: ...

# esempio
weechat.prnt_y("", 2, "Mio messaggio sulla terza riga")
Nota
 La funzione è chiamata "print_y" negli script ("prnt_y in Python).

printf_y_date_tags

WeeChat ≥ 3.5.

Display a message on a line of a buffer with free content, using a custom date and tags.

Prototipo:

void weechat_printf_y_date_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                 const char *tags, const char *message, ...);

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

weechat_printf_y_date_tags (buffer, 0, 0, NULL, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

Argomenti:

  • buffer: puntatore al buffer

  • y: numero di riga (la prima riga è 0); a negative value adds a line after last line displayed: absolute value of y is the number of lines after last line (for example -1 is immediately after last line, -2 is 2 lines after last line)

  • date: data per il messaggio (0 indica data/ora corrente)

  • tags: lista di tag separati da virgole (NULL means no tags)

  • message: messaggio da visualizzare

Esempio in C:

weechat_printf_y_date_tags (buffer, 2, 0, "my_tag", "My message on third line with a tag");

Script (Python):

# prototipo
def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ...

# esempio
weechat.prnt_y_date_tags("", 2, 0, "my_tag", "My message on third line with a tag")
Nota
 La funzione è chiamata "print_y_date_tags" negli script ("prnt_y_date_tags in Python).

printf_y_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a line of a buffer with free content, using a custom date/time (with microseconds) and tags.

Prototipo:

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, ...);

Argomenti:

  • buffer: puntatore al buffer

  • y: numero di riga (la prima riga è 0); a negative value adds a line after last line displayed: absolute value of y is the number of lines after last line (for example -1 is immediately after last line, -2 is 2 lines after last line)

  • date: data per il messaggio (0 indica data/ora corrente)

  • date_usec: microseconds of date (between 0 and 999999)

  • tags: lista di tag separati da virgole (NULL means no tags)

  • message: messaggio da visualizzare

Esempio in C:

weechat_printf_y_datetime_tags (buffer, 2, 0, 0, "my_tag", "My message on third line with a tag");

Script (Python):

# prototipo
def prnt_y_datetime_tags(buffer: str, y: int, date: int, date_usec: int, tags: str, message: str) -> int: ...

# esempio
weechat.prnt_y_datetime_tags("", 2, 0, 0, "my_tag", "My message on third line with a tag")
Nota
 La funzione è chiamata "print_y_datetime_tags" negli script ("prnt_y_datetime_tags in Python).

log_printf

Scrive un messaggio nel file di log di WeeChat (weechat.log).

Prototipo:

void weechat_log_printf (const char *message, ...);

Argomenti:

  • message: messaggio da scrivere

Esempio in C:

weechat_log_printf ("Mio messaggio nel file di log");

Script (Python):

# prototipo
def log_print(message: str) -> int: ...

# esempio
weechat.log_print("Mio messaggio nel file di log")
Nota
 La funzione è chiamata "log_print" negli script.

3.14. Hook

Priorità degli hook

WeeChat ≥ 0.3.4.

In alcuni hook è possibile impostare una priorità. Un hook con priorità maggiore si trova all’inizio della lista, in modo da poter essere eseguita prima di altri. Può risultare utile per i modificatori, data l’importanza nell’ordine di esecuzione.

Per impostare la priorità, è necessario usare questa sintassi per gli argomenti dove è consentita la priorità: nnn|nome dove nnn è un intero non negativo con la priorità e nome è il nome per l’argomenti (la priorità non compare nel nome, viene rimossa automaticamente dalla stringa).
Only a single priority per hook is allowed.

La priorità predefinita è 1000.

C examples:

/* hook per il modificatore con priorità = 2000 */
/* high priority: called before other modifier callbacks */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

/* hook two signals with priority = 3000 */
/* high priority: called before other signal callbacks */
weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL);

/* hook lines printed in formatted buffers with priority = 500 */
/* low priority: called after other line callbacks */
weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL);

I tipi di hook che seguono consentono la priorità:

hook_command

Updated in 1.5.

Hook su un comando.

Prototipo:

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);

Argomenti:

  • command: nome del comando (a priority is allowed before the command, see note about priority)

  • description: descrizione per il comando (visualizzata con /help comando)

  • args: argomenti per il comando (visualizzati con /help command)

  • args_description: descrizione degli argomenti (visualizzata con /help command)

  • completion: modello di completamento per il comando:: elenco di completamenti per ogni argomento, separati da spazio. Sono possibili più completamenti sono possibili per un singolo argomento, separati da |. Più modelli sono possibili per lo stesso comando, separati da ||.

  • callback: funzione chiamata quando viene utilizzato il comando, argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_gui_buffer *buffer: buffer quando il comando viene eseguito

    • int argc: numero di argomenti forniti per un comando

    • char **argv: argomenti forniti per un comando

    • char **argv_eol: argomenti forniti per un comando (fino a fine riga per ogni argomento)

    • valore restituito:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_data: puntatore fornito dalla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

I codici predefiniti per il completamento sono:

Plugin Nome Descrizione

alias

alias

elenco di alias

alias

alias_value

valore dell’alias

buflist

buflist_items

buflist bar items

buflist

buflist_items_used

buflist bar items used (according to option buflist.look.use_items)

exec

exec_commands_ids

ids (numbers and names) of executed commands

fset

fset_options

configuration files, sections, options and words of options

guile

guile_script

elenco degli script

irc

irc_channel

canale IRC corrente

irc

irc_channel_nicks_hosts

nick e host del canale IRC corrente

irc

irc_channel_topic

argomento del canale IRC attivo

irc

irc_channels

canali su tutti i server IRC

irc

irc_channels_autojoin

channels automatically joined on the current server (option "autojoin")

irc

irc_ignores_numbers

numero di ignore definiti

irc

irc_modelist_masks

modelist masks of current IRC channel; required argument: modelist mode

irc

irc_modelist_numbers

modelist numbers of current IRC channel; required argument: modelist mode

irc

irc_msg_kick

default kick message

irc

irc_msg_part

messaggio di uscita predefinito per il canale IRC

irc

irc_notify_nicks

nick nella lista notifiche

irc

irc_privates

privati su tutti i server IRC

irc

irc_raw_filters

filters for irc raw buffer

irc

irc_server

server IRC corrente

irc

irc_server_channels

canali sul server IRC corrente

irc

irc_server_nick

nick sul server IRC corrente

irc

irc_server_nicks

nick su tutti i canali del server IRC corrente

irc

irc_server_prefix_modes_filter

arguments to filter by prefix mode (for example: "-o", "-h", "-v", "-*")

irc

irc_server_privates

privati sul server IRC corrente

irc

irc_servers

server IRC (nomi interni)

irc

nick

nick del canale IRC corrente

javascript

javascript_script

elenco degli script

lua

lua_script

elenco degli script

perl

perl_script

elenco degli script

php

php_script

elenco degli script

python

python_script

elenco degli script

relay

relay_free_port

prima porta libera per il plugin relay

relay

relay_protocol_name

protocollo.nome possibile per il plugin relay

relay

relay_relays

protocollo.nome dei relay correnti per il plugin relay

relay

relay_remotes

relay remotes

ruby

ruby_script

elenco degli script

script

script_extensions

list of script extensions

script

script_files

file nella directory degli script

script

script_languages

list of script languages

script

script_scripts

elenco degli script nel repository

script

script_scripts_installed

elenco degli script installati (dal repository)

script

script_tags

tag degli script nel repository

spell

spell_dicts

list of installed dictionaries

spell

spell_langs

list of all languages supported

tcl

tcl_script

elenco degli script

trigger

trigger_add_arguments

arguments for command that adds a trigger: trigger name, hooks, hook arguments, hook conditions, hook regex, hook command, hook return code, post actions

trigger

trigger_hook_arguments

default arguments for a hook

trigger

trigger_hook_command

default command for a hook

trigger

trigger_hook_conditions

default conditions for a hook

trigger

trigger_hook_rc

default return codes for hook callback

trigger

trigger_hook_regex

default regular expression for a hook

trigger

trigger_hooks

hooks for triggers

trigger

trigger_hooks_filter

hooks for triggers (for filter in monitor buffer)

trigger

trigger_names

triggers

trigger

trigger_names_default

default triggers

trigger

trigger_names_disabled

disabled triggers

trigger

trigger_names_enabled

enabled triggers

trigger

trigger_option_value

value of a trigger option

trigger

trigger_options

options for triggers

trigger

trigger_post_action

trigger post actions

weechat

bars_items

names of bar items

weechat

bars_names

nomi delle barre

weechat

bars_options

opzioni per le barre

weechat

buffer_local_variable_value

value of a buffer local variable

weechat

buffer_local_variables

buffer local variables

weechat

buffer_properties_get

proprietà che possono essere lette su un buffer

weechat

buffer_properties_set

proprietà che possono essere impostate su un buffer

weechat

buffer_properties_setauto

properties that can be automatically set on a buffer

weechat

buffers_names

nomi dei buffer

weechat

buffers_numbers

numeri dei buffer

weechat

buffers_plugins_names

nomi dei buffer (inclusi i nomi dei plugin)

weechat

colors

color names

weechat

commands

commands (weechat and plugins); optional argument: prefix to add before the commands

weechat

config_files

file di configurazione

weechat

config_option_values

valori per una opzione di configurazione

weechat

config_options

opzioni di configurazione

weechat

cursor_areas

aree ("chat" o nome barra) per il movimento libero del cursore

weechat

custom_bar_item_add_arguments

arguments for command that adds a custom bar item: item name, conditions, content

weechat

custom_bar_item_conditions

conditions for custom bar item

weechat

custom_bar_item_contents

contents for custom bar item

weechat

custom_bar_items_names

names of custom bar items

weechat

env_value

value of an environment variable

weechat

env_vars

environment variables

weechat

eval_variables

variables that can be used in /eval command

weechat

filename

filename; optional argument: default path (evaluated, see /help eval)

weechat

filters_names

nomi dei filtri

weechat

filters_names_disabled

names of disabled filters

weechat

filters_names_enabled

names of enabled filters

weechat

hook_types

hook types

weechat

infolists

nomi degli hook liste info

weechat

infos

nomi degli hook sulle info

weechat

keys_codes

codici tasto

weechat

keys_codes_for_reset

codici tasti che possono essere ripristinati (tasti aggiunti, ridefiniti o rimossi)

weechat

keys_contexts

contesti del tasto

weechat

layouts_names

nomi dei layout

weechat

nicks

nick nella lista nick del buffer corrente

weechat

palette_colors

Tavolozza dei colori

weechat

plugins_commands

commands defined by plugins; optional argument: prefix to add before the commands

weechat

plugins_installed

names of plugins installed

weechat

plugins_names

nomi dei plugin

weechat

proxies_names

nomi dei proxy

weechat

proxies_options

opzioni per i proxy

weechat

secured_data

names of secured data (file sec.conf, section data)

weechat

weechat_commands

weechat commands; optional argument: prefix to add before the commands

weechat

windows_numbers

numeri delle finestre

xfer

nick

nick della chat DCC

Codici speciali:

  • %%command: riutilizza il modello di completamento dal comando command

  • %-: ferma completamento

  • %*: ripete l’ultimo completamento

Valore restituito:

  • puntatore al nuovo hook, NULL in caso di errore

Esempio in 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;
}

/* questo esempio si ispira al comando /filter */
struct t_hook *my_command_hook =
    weechat_hook_command ("myfilter",
                          "description of myfilter",
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          "description of arguments...",
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          &my_command_cb, NULL, NULL);

Ad esempio, se il comando chiamato è /comando abc def ghi, allora argv e argv_eol contengono i seguenti valori:

  • argv:

    • argv[0] == "/command"

    • argv[1] == "abc"

    • argv[2] == "def"

    • argv[3] == "ghi"

  • argv_eol:

    • argv_eol[0] == "/command abc def ghi"

    • argv_eol[1] == "abc def ghi"

    • argv_eol[2] == "def ghi"

    • argv_eol[3] == "ghi"

Per gli script, args ha valore "abc def ghi".

Script (Python):

# prototipo
def hook_command(command: str, description: str, args: str, args_description: str,
                 completion: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_command_cb(data: str, buffer: str, args: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "descrizione di myfilter",
    "[list] | [enable|disable|toggle [name]] | "
    "[add name plugin.buffer tags regex] | "
    "[del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")

hook_completion

Updated in 1.5.

Hook su un completamento.

Prototipo:

struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(const void *pointer,
                                                        void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        const void *callback_pointer,
                                        void *callback_data);

Argomenti:

  • completion_item: nome dell’elemento del completamento, è possibile usare in seguito %(name) in un comando con un hook (argomento completion) (a priority is allowed before the completion item, see note about priority)

  • callback: funzione chiamata quando viene usato l’elemento completamento (l’utente sta completando qualcosa usando questo elemento), argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • const char *completion_item: nome dell’elemento del completamento

    • struct t_gui_buffer *buffer: buffer dove viene eseguito il completamento

    • struct t_gui_completion *completion: struttura usata per aggiungere parole per il completamento (consultare completion_list_add)

    • valore restituito:

      • WEECHAT_RC_OK

      • WEECHAT_RC_ERROR

  • callback_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_data: puntatore fornito alla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Nota
 I nomi del completamento sono globali (condivisi tra WeeChat e plugin). Si raccomanda pertanto di scegliere un nome con un prefisso unico, come "plugin_xxx" (dove "xxx" è il nome del proprio elemento).
Importante
 The callback must only call completion functions like completion_list_add and must NOT update the command line.
To update the command line when Tab is pressed, you can use the function hook_command_run with command: /input complete_next (and you must return WEECHAT_RC_OK_EAT if your callback has updated the command line, so that WeeChat will not perform the completion).

Valore restituito:

  • puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_completion_list_add (completion, "word1", 0, WEECHAT_LIST_POS_SORT);
    weechat_completion_list_add (completion, "test_word2", 0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL, NULL);

Script (Python):

# prototipo
def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    weechat.completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")

hook_completion_get_string

Novità nella versioe 0.3.4.

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_get_string.

hook_completion_list_add

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_list_add.

hook_command_run

Updated in 1.5.

Hook su un comando quando eseguito da WeeChat.

Prototipo:

struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         const void *callback_pointer,
                                         void *callback_data);

Argomenti:

  • command: comando su cui eseguire l’hook (wildcard * is allowed) (a priority is allowed before the command, see note about priority)

  • callback: funzione chiamata quando il comando è in esecuzione, argomenti e valore restituito:

    • const void *pointer: puntatore

    • void *data: puntatore

    • struct t_gui_buffer *buffer: buffer dove viene eseguito il comando

    • const char *command: il comando eseguito, con i propri argomenti

    • valore restituito:

      • WEECHAT_RC_OK

      • WEECHAT_RC_OK_EAT: il comando non verrà eseguito da WeeChat dopo la callback

      • WEECHAT_RC_ERROR

  • callback_pointer: puntatore fornito alla callback quando chiamata da WeeChat

  • callback_data: puntatore fornito alla callback quando chiamata da WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the hook is deleted

Valore restituito:

  • puntatore al nuovo hook, NULL in caso di errore

Esempio in C: