weechat/doc/it/weechat_plugin_api.it.txt

WeeChat Plugin API Reference
============================
FlashCode <flashcode@flashtux.org>


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

È possibile trovare l'ultima versione di questo documento qui:
http://www.weechat.org/doc


[[introduction]]
Introduzione
------------

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

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

[[plugins_in_weechat]]
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.

[[macros]]
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_VERSION("1.0")::
    versione del plugin

WEECHAT_PLUGIN_LICENSE("GPL3")::
    licenza del plugin

[[main_functions]]
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:

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

Argomenti:

* 'plugin': puntatore alla struttura del plugin di WeeChat
* 'argc': numero di argomenti per il plugin (fornito dalla riga di comando
  dall'utente)
* 'argv': argomenti per il plugin

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)

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

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

Prototipo:

[source,C]
----------------------------------------
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

[[compile_plugin]]
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 libtizio.so tizio.o
----------------------------------------

[[load_plugin]]
Caricamento del plugin
~~~~~~~~~~~~~~~~~~~~~~

Copiare il file 'libtizio.so' nella cartella plugin di sistema (ad
esempio '/usr/local/lib/weechat/plugins') oppure nella cartella
plugin dell'utente (ad esempio '/home/xxx/.weechat/plugins').

In WeeChat:

----------------------------------------
/plugin load tizio
----------------------------------------

[[plugin_example]]
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!):

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

#include "weechat-plugin.h"

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

struct t_weechat_plugin *weechat_plugin = NULL;


/* callback for command "/double" */

int
command_double_cb (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* fa felice il compilatore C */
    (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);
    
    return WEECHAT_RC_OK;
}

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

[[plugin_api]]
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).

[[plugins]]
Plugin
~~~~~~

Funzioni per ottenere informazioni sui plugin.

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

Ottiene il nome del plugin.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

[[strings]]
Stringhe
~~~~~~~~

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

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

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

Argomenti:

* 'charset': nuovo set caratteri da usare

Esempio in C:

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

Script (Python):

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

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Restituisce la stringa tradotta (dipende dalla lingua).

Prototipo:

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

Argomenti:

* 'string': stringa da tradurre

Valore restituito:

* stringa tradotta

Esempio in C:

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

Script (Python):

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

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

* stringa tradotta

Esempio in C:

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

Script (Python):

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

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

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

Restituisce una stringa duplicata, con un massimo di caratteri
impostato su 'chars'.

Prototipo:

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

Argomenti:

* 'string': stringa da duplicare
* 'length': caratteri massimi da duplicare

Valore restituito:

* stringa duplicata (deve essere liberata chiamando "free" dopo
  l'utilizzo)

Esempio in C:

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

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

Converte una stringa UTF-8 in minuscolo.

Prototipo:

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

Argomenti:

* 'string': stringa da convertire

Esempio in C:

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

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

Converte una stringa UTF-8 in maiuscolo.

Prototipo:

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

Argomenti:

* 'string': stringa da convertire

Esempio in C:

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

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

Locale and case independent string comparison.
Confronta stringa di li

Prototipo:

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

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare

Valore restituito:

* differenze tra le due stringhe:
** negativa se stringa1 < stringa2
** zero se stringa1 == stringa1
** positiva se stringa1 > stringa2

Esempio in C:

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

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

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

Prototipo:

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

Argomenti:

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

Valore restituito:

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

Esempio in C:

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

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

Locale and case independent string search.

Prototipo:

[source,C]
----------------------------------------
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

Esempio in C:

[source,C]
----------------------------------------
char *pos = weechat_strcasestr ("aBcDeF", "de"); /* risultato: puntatore a "DeF" */
----------------------------------------

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

Verifica se una stringa coincide ad una mask.

Prototipo:

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

Argomenti:

* 'string': stringa
* 'mask': mask, può iniziare o terminare con "`*`" (nessun altro "`*`"
* consentito all'interno della mask)

Valore restituito:

* 1 se la stringa coincide alla mask, altrimenti 0

Esempio in C:

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

Script (Python):

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

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Rimuove i caratteri all'inizio/fine della stringa.

Prototipo:

[source,C]
----------------------------------------
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:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

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

Prototipo:

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

Argomenti:

* 'string': stringa da dividere
* 'separators': delimitatori usati per dividere
* 'keep_eol': se diversa da 0, allora ogni argomento conterrà tutte le stringhe
  fino a fine riga (consultare l'esempio in basso)
* 'num_items_max': maximum number of items created (0 = no limit)
* 'num_items': pointer to int which will contain number of items created

Valore restituito:

* array di stringhe, NULL se si verifica un problema (deve essere liberata chiamando
  <<_weechat_string_free_split,weechat_string_free_split>> dopo l'uso)

Esempi:

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

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

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

Libera la memoria usata per la divisione di una stringa.

Prototipo:

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

Argomenti:

* 'split_string': stringa divisa dalla funzione
  <<_weechat_string_split,weechat_string_split>>

Esempio in C:

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

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

Compila una stringa con una stringa divisa.

Prototipo:

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

Argomenti:

* 'split_string': stringa divisa dalla funzione
  <<_weechat_string_split,weechat_string_split>>
* 'separator': stringa usata per separare le stringhe

Valore restituito:

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

Esempio in C:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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
  <<_weechat_free_split_command,weechat_free_split_command>> dopo l'uso)

Esempio in C:

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

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

Libera la memoria utilizzata dalla divisione di un comando.

Prototipo:

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

Argomenti:

* 'split_command': comando diviso da
  <<_weechat_string_split_command,weechat_string_split_command>>

Esempio in C:

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

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

Build a string with formatted file size and a unit translated to local
language.
Compila una stringa con un file di dimensione fissa ed una unità
tradotta nella lingua locale.

Prototipo:

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

Argomenti:

* 'size': dimensione (in byte)

Valore restituito:

* stringa formattata (deve essere liberata chiamando "free" dopo l'uso)

C examples:

[source,C]
----------------------------------------
/* esempi in lingua inglese */

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

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

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

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

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

Rimuove i colori di WeeChat da una stringa.

Prototipo:

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

Argomenti:

* 'string': stringa
* 'replacement': se non NULL e non vuota, i codici colore di WeeChat sono
  sostituiti dal primo carattere di questa stringa, altrimenti i codici colori di
  WeeChat ed i caratteri seguenti (se correlate al colore) sono rimossi dalla
  stringa

Valore restituito:

* stringa senza un colore (deve essere liberata chiamando "free" dopo l'uso)

Esempi:

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

Script (Python):

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

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

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

Encode a string in base64.

Prototype:

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

Arguments:

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

C example:

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

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

Decode a base64 string.

Prototype:

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

Arguments:

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

Return value:

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

C example:

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

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

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

Prototype:

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

Arguments:

* 'string': string

Return value:

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

C examples:

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

Script (Python):

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

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

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

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

Prototype:

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

Arguments:

* 'string': string

Return value:

* pointer into "string", or NULL

C examples:

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

Script (Python):

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

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

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

Alcune funzioni stringa UTF-8.

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

Verifica che una stringa abbia caratteri a 8-bit.

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Verifica che una stringa sia valida in UTF-8.

Prototipo:

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

Argomenti:

* 'string': stringa
* '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:

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

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

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

Prototipo:

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

Argomenti:

* 'string': stringa
* 'replacement': carattere sotitutivo per i caratteri non validi

Esempio in C:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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)

Esempio in C:

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

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

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

Prototipo:

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

Argomenti:

* 'string': stringa

Valore restituito:

* puntaotre al carattere UTF-8 successivo, NULL se non trovato
  (raggiunta la fine della stringa)

Esempio in C:

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

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

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

Prototipo:

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

Argomenti:

* 'string': stringa

Valore restituito:

* dimensione carattere UTF-8 (in byte)

Esempio in C:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Confronta due caratteri UTF-8, ignorando maiuscole/minuscole.

Prototipo:

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

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare

Valore restituito:

* differenza tra i primi caratteri di ogni stringa:
** negativa se char1 < char2
** zero se char1 == char2
** positivao se char1 > char2

Esempio in C:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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

Esempio in C:

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

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

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

Prototipo:

[source,C]
----------------------------------------
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)

Esempio in C:

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

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

Restituisce la posizione reale nella stringa UTF-8.

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Restituisce la posizione nella stringa UTF-8.

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Restituisce la stringa duplicata, di lunghezza massima 'lenght'.

Prototipo:

[source,C]
----------------------------------------
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:

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

[[directories]]
Cartelle
~~~~~~~~

Alcune funzioni legate alle cartelle.

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

Crea una cartella nella home di WeeChat.

Prototipo:

[source,C]
----------------------------------------
int weechat_mkdir_home (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 se si è verificato
  un errore

Esempio in C:

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

Script (Python):

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

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

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

Crea una cartella.

Prototipo:

[source,C]
----------------------------------------
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 se si è verificato
  un errore

Esempio in C:

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

Script (Python):

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

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

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

Crea una cartella e le cartelle genitore se necessario.

Prototipo:

[source,C]
----------------------------------------
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 se si è verificato
  un errore

Esempio in C:

[source,C]
----------------------------------------
if (!weechat_mkdir_parents ("/tmp/mia/cartella", 0755))
{
    /* errore */
}
----------------------------------------

Script (Python):

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

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

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

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

Prototipo:

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

Argomenti:

* 'directory': cartella in cui cercare i file
* 'hidden_files': 1 per includere i file nascosti, altrimenti 0
* 'data': puntatore fornito al callback quando chiamato da WeeChat
* 'callback': funzione chiamata per ogni file trovato, argomenti:
** 'void *data': puntatore
** 'const char *filename': nome file trovato

Esempio in C:

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

[[util]]
Util
~~~~

Alcune funzioni utili.

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

Confronta due strutture "timeval".

Prototipo:

[source,C]
----------------------------------------
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:

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

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

Restituisce la differenza (in millisecondi) tra due strutture "timeval".

Prototipo:

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

Argomenti:

* 'tv1': prima struttura "timeval"
* 'tv2': seconda struttura "timeval"

Valore restituito:

* differenza in millisecondi

Esempio in C:

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

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

Aggiungi intervallo (in millisecondi) ad una struttura timeval.

Prototipo:

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

Argomenti:

* 'tv': struttura timeval
* 'interval': intervallo (in millisecondi)

Esempio in C:

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

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

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

Prototype:

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

Arguments:

* 'date': pointer to date

C example:

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

[[sorted_lists]]
Elenchi ordinati
~~~~~~~~~~~~~~~~

Funzioni lista ordinata.

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

Crea una nuova lista.

Prototipo:

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

Valore restituito:

* puntatore alla nuova lista

Esempio in C:

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

Script (Python):

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

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

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

Aggiunge un elemento in una lista.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

# esempio
item = weechat.list_add(list, "miei dati", weechat.WEECHAT_LIST_POS_SORT, "")
----------------------------------------

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

Cerca un elemento nella lista.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

# esempio
item = weechat.list_search(list, "miei dati")
----------------------------------------

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

Cerca un elemento nella lista, ignorando maiuscole/minuscole.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Return an item in a list by position.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Imposta un nuovo valore per un elemento.

Prototipo:

[source,C]
----------------------------------------
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:

[source,C]
----------------------------------------
weechat_list_set (item, "nuovi dati");
----------------------------------------

Script (Python):

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

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

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

Restituisce l'elemento successivo nella lista.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Restituisce l'elemento precedente nella lista.

Prototipo:

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

Argomenti:

* 'item': puntatore all'elemento

Valore restituito:

* puntatore all'elemento precedente, NULL se il puntatore è
  l'ultimo elemento nella lista

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore stringa di un elemento.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Restituisce la dimensione della lista (numero di elementi).

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Rimuove un elemento in una lista.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Rimuove tutti gli elementi in una lista.

Prototipo:

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

Argomenti:

* 'weelist': puntatore alla lista

Esempio in C:

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

Script (Python):

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

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

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

Libera una lista.

Prototipo:

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

Argomenti:

* 'weelist': puntatore alla lista

Esempio in C:

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

Script (Python):

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

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

[[configuration_files]]
File di configurazione
~~~~~~~~~~~~~~~~~~~~~~

Funzioni per i file di configurazione.

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

Crea un nuovo file di configurazione.

Prototipo:

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

Argomenti:

* 'name': nome del file di configurazione (senza percorso o estensione)
* 'callback_reload': funzione chiamata quando il file di configurazione viene
  ricaricato con `/reload` (opzionale, può essere NULL), argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
* 'callback_reload_data': puntatore fornito per ricaricare il callback
  quando richiesto da WeeChat

Valore restituito:

* puntatore al nuovo file di configurazione, NULL se si è verificato
  un errore

[NOTE]
Il file NON viene creato su disco da questa funzione. Verrà creato chiamando
la funzione <<_weechat_write_config,weechat_write_config>>. Si dovrebbe chiamare
questa funzione solo dopo aver aggiunto alcune sezioni (con
<<_weechat_config_new_section,weechat_config_new_section>>) e le opzioni (con
<<_weechat_config_new_option,weechat_config_new_option>>).

Esempio in C:

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

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

Script (Python):

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

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

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

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

Crea una nuova sezione nel file di configurazione.

Prototipo:

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

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:
** '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
* 'callback_read_data': puntatore fornito al callback quando chiamato da WeeChat
* '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:
** '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
* callback_write_data: puntatore fornito al callback quando chiamato da WeeChat
* callback_write_default: funzione chiamata quando i valori predefiniti per la sezione
  devono essere scritti in un file, argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'const char *section_name': nome della sezione
* 'callback_write_default_data': puntatore fornito al callback quando chiamato da
  WeeChat
* 'callback_create_option': funzione chiamata quando viene creata una nuova
  opzione nella sezione (NULL se la sezione non consente di creare nuove
  opzioni), argomenti:
** '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
* 'callback_create_option_data': puntatore fornito al callback quando chiamato
  da WeeChat
* 'callback_delete_option': funzione chiamata quando un'opzione viene eliminata
  nella sezione (NULL se la sezione non consente di eliminare delle opzioni),
  argomenti:
** '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
* 'callback_delete_option_data': puntatore fornito al callback quando chiamato
  da WeeChat

Valore restituito:

* puntatore alla nuova sezione nel file di configurazione, NULL in caso di errore

Esempio in C:

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

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

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

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

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

/* sezione standart, l'utente non può aggiungere/eliminare opzioni */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, /* read callback */
                                NULL, NULL, /* write callback */
                                NULL, NULL, /* write default callback */
                                NULL, NULL, /* create option callback */
                                NULL, NULL); /* delete option callback */

/* 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,
                                &my_section_write_cb, NULL,
                                &my_section_write_default_cb, NULL,
                                &my_section_create_option_cb, NULL,
                                &my_section_delete_option_cb, NULL);
----------------------------------------

Script (Python):

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

# esempio
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_RC_OK

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

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

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

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

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

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

Cerca una sezione in un file di configurazione.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Crea una nuova opzione nella sezione di un file di configurazione.

Prototipo:

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

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'section': puntatore alla sezione
* 'name': nome dell'opzione
* 'type': tipo dell'opzione:
** 'boolean': valore booleano (on/off)
** 'integer': valore intero (con stringhe opzionali per i valori)
** 'string': valore stringa
** 'color': colore
* 'description': descrizione dell'opzione
* 'string_values': valori come stringa (separati da "|"), usato dal tipo 'integer'
  (opzionale)
* '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:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
** 'const char *value': nuovo valore per l'opzione
* 'callback_check_value_data': puntatore fornito alla callback check_value
  quando chiamato da WeeChat
* 'callback_change': funzione chiamata quando il valore dell'opzione è stata
  cambiata (opzionale), argomenti:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
* 'callback_change_data': puntatore fornito per cambiare alla callback quando
  chiamato da WeeChat
* 'callback_delete': funzione chiamata quando l'opzione verrà eliminata
  (opzionale), argomenti:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
* 'callback_delete_data': puntatore fornito per eiliminare alla callback quando
  chiamato da WeeChat

Valore restituito:

 alla nuova opzione nella sezione, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
/* booleano */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "on", /* predefinito */
                               "on", /* valore */
                               0, /* null value allowed */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

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

/* intero (con valori stringa) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)"
                               "top|bottom|left|right", /* string values */
                               0, 0, /* min, max */
                               "bottom", /* predefinito */
                               "bottom", /* valoree */
                               0, /* null value allowed */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* stringa */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "test", /* predefinito */
                               "test", /* valore */
                               1, /* valore null consentito */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* colore */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "lightblue", /* predefinito */
                               "lightblue", /* valore */
                               0, /* valore null consentito */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */
----------------------------------------

Script (Python):

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

# esempio
def option4_check_value_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

def option4_change_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

def option4_delete_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

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

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

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

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

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

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

Cerca un'opzione nella sezione di un file di configurazione.

Prototipo:

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

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:

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

Script (Python):

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

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

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

Cerca un'opzione con il nome completo.

Prototipo:

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

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

Esempio in C:

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

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

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

Verifica se un testo è "vero" o "falso", come valore booleano.

Prototipo:

[source,C]
----------------------------------------
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:

[source,C]
----------------------------------------
if (weechat_config_string_to_boolean (option_value))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

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

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

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

Resetta un'opzione al proprio valore predefinito.

Prototipo:

[source,C]
----------------------------------------
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' se si è verificato un errore

Esempio in C:

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

Script (Python):

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

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

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

Imposta un nuovo valore per l'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione
* 'value': nuovo valore per l'opzione
* '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' se si è verificato un errore

Esempio in C:

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

Script (Python):

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

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

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

Imposta null (valore non definito) per un'opzione.

Prototipo:

[source,C]
----------------------------------------
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

[NOTE]
È possibile impostare il valore a null solo se è consentito per l'opzione
(consultare <<_weechat_config_new_option,weechat_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' se si è verificato un errore

Esempio in C:

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

Script (Python):

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

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

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

Rimuove/resetta un'opzione.

Prototipo:

[source,C]
----------------------------------------
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 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' se si è verificato un errore

Esempio in C:

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

Script (Python):

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

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

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

Rinomina un'opzione.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Restituisce un puntatore alla proprietà di un'opzione.

Prototipo:

[source,C]
----------------------------------------
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 *')
** '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:

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

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

Verifica se un opzione è "null (valore non definito).

Prototipo:

[source,C]
----------------------------------------
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:

[source,C]
----------------------------------------
if (weechat_config_option_is_null (option))
{
    /* il valore è "null" */
}
else
{
    /* il valore non è "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_is_null(option)

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

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

Verifica che il valore predefinito di un'opzione sia "null" (valore non definito).

Prototipo:

[source,C]
----------------------------------------
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:

[source,C]
----------------------------------------
if (weechat_config_option_default_is_null (option))
{
    /* il valore predefinito è "null" */
}
else
{
    /* il valore predefinito non è "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_default_is_null(option)

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

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

Restituisce il valore bool di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore bool di un'opzione (0 o 1)

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_boolean (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

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

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

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

Restituisce il valore bool predefinito di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* il valore bool predefinito di un'opzione (0 o 1)

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_boolean_default (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

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

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

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

Restituisce il valore intero di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore intero di un'opzione

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore intero predefinito di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore intero predefinito di un'opzione

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore stringa di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore stringa di un'opzione

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore stringa predefinito di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore stringa predefinito di un'opzione

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore colore di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore colore dell'opzione (stringa con il nome del colore)

Esempio in C:

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

Script (Python):

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

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

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

Restituisce il valore colore predefinito di un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore colore predefinito di un'opzione (stringa con il nome del colore)

Esempio in C:

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

Script (Python):

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

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

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

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Scrive una riga nel file di configurazione (questa funzione dovrebbe
essere chiamata solo nelle callback "write" o "write_default" per una
sezione).

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Scrive il file di configurazione su disco.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Legge il file di configurazione su disco.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Ricarica il file di configurazione da disco.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Libera un'opzione.

Prototipo:

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

Argomenti:

* 'option': puntatore all'opzione

Esempio in C:

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

Script (Python):

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

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

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

Libera tutte le opzioni in una sessione.

Prototipo:

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

Argomenti:

* 'section': puntatore alla sezione

Esempio in C:

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

Script (Python):

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

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

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

Libera una sezione.

Prototipo:

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

Argomenti:

* 'section': puntatore alla sezione

Esempio in C:

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

Script (Python):

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

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

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

Libera un file di configurazione.

Prototipo:

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

Argomenti:

* 'config_file': puntatore al file di configurazione

Esempio in C:

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

Script (Python):

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

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

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

Cerca un'opzione con il nome completo.

Prototipo:

[source,C]
----------------------------------------
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:

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

Script (Python):

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

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

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

Cerca un'opzione nei file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
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:

[source,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):

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

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

weechat_config_is_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica se un'opzione è impostata nel file di configurazione dei
plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
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:

[source,C]
----------------------------------------
if (weechat_config_is_set_plugin ("option"))
{
    /* l'opzione è impostata */
}
else
{
    /* l'opzione non esiste */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_is_set_plugin(option_name)

# esempio
if weechat.config_is_set_plugin("option"):
    # l'opzione è impostata
    # ...
else:
    # l'opzione non esiste
    # ...
----------------------------------------

weechat_config_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta il nuovo valore per l'opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
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' se si è verificato un errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_set_plugin(option_name, value)

# esempio
rc = weechat.config_is_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_unset_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Disattiva l'opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
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' se si è verificato un errore

Esempio in C:

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

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_unset_plugin(option_name)

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

[[display]]
Display
~~~~~~~

Funzioni per visualizzare il testo nei buffer.

weechat_prefix
^^^^^^^^^^^^^^

Restituisce un prefisso.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_prefix (const char *prefix);
----------------------------------------

Argomenti:

* 'prefix': nome del prefisso:

[width="70%",cols="^2e,^1l,^3,5",options="header"]
|========================================
| Prefisso | Valore | Colore       | Descrizione
| errore   | =!=    | 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
|========================================

[NOTE]
Valori e colori possono essere personalizzati con il comando `/set`.

Valore restituito:

* valore del prefisso (stringa con prefisso e codici colori), stringa vuota
  se il prefisso non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.prefix(prefix)

# esempio
weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))
----------------------------------------

weechat_color
^^^^^^^^^^^^^

Restituisce una codice colore stringa da visualizzare.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_color (const char *color_name);
----------------------------------------

Argomenti:

* 'color_name': nome del colore, uno di:
** nome opzione di WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** attributo:
*** 'bold': imposta grassetto
*** '-bold': rimuove grassetto
*** 'reverse': imposta inverso
*** '-reverse': rimuove inverso
*** 'italic': imposta corsivo
*** '-italic': rimuove corsivo
*** 'underline': imposta sottolineato
*** '-underline': rimuove sottolineato
** 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

Valore restituito:

* stringa con codice colore, o un codice "reset color" se il colore non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.color(color_name)

# esempio
weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
----------------------------------------

weechat_printf
^^^^^^^^^^^^^^

Visualizza un messaggio su un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL il messaggio viene visualizzato sul buffer di WeeChat
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Benvenuto sul buffer di WeeChat");
weechat_printf (buffer, "Benvenuto su questo buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt(buffer, message)

# esempio
weechat.prnt("", "Benvenuto sul buffer di WeeChat")
weechat.prnt(buffer, "Benvenuto su questo buffer")
----------------------------------------

[NOTE]
La funzione è chiamata "print" negli script ("prnt" in Python).

weechat_printf_date
^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, utilizzando una data personalizzata.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL, il messaggio viene visualizzato
  sul buffer di WeeChat
* 'date': data per il messaggio
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_date (NULL, time (NULL) - 120, "Ciao, 2 minuti fa");
----------------------------------------

weechat_printf_tags
^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, utilizzando tag personalizzati.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL il messaggio viene visualizzato
  sul buffer di WeeChat
* 'tags': lista di tag separati da virgole
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_tags (NULL, "notify_message",
                     "Messaggio con tag 'notify_message'");
----------------------------------------

weechat_printf_date_tags
^^^^^^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, usando tag e data personalizzati.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               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
* 'tags': lista di tag separati da virgole
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Messaggio 2 minuti fa, con tag 'notify_message'");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt_date_tags(buffer, date, tags, message)

# esempio
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Messaggio 2 minuti fa, con tag 'notify_message'")
----------------------------------------

[NOTE]
La funzione è chiamata "print_date_tags" negli script ("prnt_date_tags" in Python).

weechat_printf_y
^^^^^^^^^^^^^^^^

Visualizza un messaggio sulla riga di un buffer con contenuto libero.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'y': numero di riga (la prima riga è 0)
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_y (buffer, 2, "Mio messaggio sulla terza riga");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt_y(buffer, y, message)

# esempio
weechat.prnt_y("", 2, "Mio messaggio sulla terza riga")
----------------------------------------

[NOTE]
La funzione è chiamata "print_y" negli script ("prnt_y in Python).

weechat_log_printf
^^^^^^^^^^^^^^^^^^

Scrive un messaggio nel file di log di WeeChat (weechat.log).

Prototipo:

[source,C]
----------------------------------------
void weechat_log_printf (const char *message, ...);
----------------------------------------

Argomenti:

* 'message': messaggio da scrivere

Esempio in C:

[source,C]
----------------------------------------
weechat_log_printf ("Mio messaggio nel file di log");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.log_print(message)

# esempio
weechat.log_print("Mio messaggio nel file di log")
----------------------------------------

[NOTE]
La funzione è chiamata "log_print" negli script.

[[hooks]]
Hook
~~~~

weechat_hook_command
^^^^^^^^^^^^^^^^^^^^

Hook su un comando.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     void *callback_data);
----------------------------------------

Argomenti:

* 'command': nome del comando
* '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:
** '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)
* 'callback_data': puntatore fornito dalla callback quando chiamata da WeeChat

I codici predefiniti per il completamento sono:
include::autogen/plugin_api/completions.txt[]

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:

[source,C]
----------------------------------------
int
my_command_cb (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 (/* nome comando */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);
----------------------------------------

Ad esempio, se il comando chiamato è `/comando abc def ghi`, allora
argv e argv_eol contengono i seguenti valori:

* 'argv':
** 'argv[0]' == "abc"
** 'argv[1]' == "def"
** 'argv[2]' == "ghi"
* 'argv_eol':
** 'argv_eol[0]' == "abc def ghi"
** 'argv_eol[1]' == "def ghi"
** 'argv_eol[2]' == "ghi"

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# esempio
def my_command_cb(data, buffer, args):
    # ...
    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", "")
----------------------------------------

weechat_hook_command_run
^^^^^^^^^^^^^^^^^^^^^^^^

Hook su un comando quando eseguito da WeeChat.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);
----------------------------------------

Argomenti:

* 'command': comando su cui eseguire l'hook, può iniziare o terminare con "*"
* 'callback': funzione chiamata quando il comando è in esecuzione, argomenti:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': buffer dove viene eseguito il comando
** 'const char *command': il comando eseguito, con i propri argomenti
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

[NOTE]
La callback può restituire 'WEECHAT_RC_OK' o 'WEECHAT_RC_OK_EAT' (il comando
non verrà eseguito da WeeChat dopo la callback).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
		    "Vuoi completare? Sto mangiando il completamento, ahah!);
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_command_run(command, callback, callback_data)

# esempio
def my_command_run_cb(data, buffer, command):
    weechat.prnt("". "Vuoi completare? Sto mangiando il completamento, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
----------------------------------------

weechat_hook_timer
^^^^^^^^^^^^^^^^^^

Hook sul timer.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_timer (long interval,
                                   const char *align_second,
                                   const char *max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'interval': intervallo tra due chiamate (millisecondi, 1000 = 1 secondo)
* 'align_second': allineamento su un secondo. Per esempio, rrent time is 09:00,
  if interval = 60000 (60 seconds), and align_second = 60, then timer is
  called each minute when second is 00
* 'max_calls': number of calls to timer (if 0, then timer has no end)
* 'callback': function called when time is reached, arguments:
** 'void *data': pointer
** 'int remaining_calls': remaining calls (-1 if timer has no end)
* 'callback_data': pointer given to callback when it is called by WeeChat

Valore restituito:

* pointer to new hook, NULL if error occured

Esempio in C:

[source,C]
----------------------------------------
int
my_timer_cb (void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* timer chiamato ogni 20 secondi */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# esempio
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each 20 seconds
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
----------------------------------------

weechat_hook_fd
^^^^^^^^^^^^^^^

Hook su un descrittore file (file oppure socket).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);
----------------------------------------

Argomenti:

* 'fd': descrittore file
* 'flag_read': 1 = cattura l'evento lettura (read), 0 = ignora
* 'flag_write': 1 = cattura l'evento scrittura (write), 0 = ignora
* 'flag_exception': 1 = cattura l'eccezione evento (event), 0 = ignora
* 'callback': funzione che chiama un evento selezionato che si verifica
  per un file (o un socket), argomenti:
** 'void *data': puntatore
** 'int fd': descrittore file
* 'callback_data': puntatore fornito alla calback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_fd_cb (void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# esempio
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
----------------------------------------

weechat_hook_process
^^^^^^^^^^^^^^^^^^^^

Hook su un processo (lanciato con un fork), e cattura l'output.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);
----------------------------------------


Argomenti:

* 'command': comando da avviare nel processo figlio
* 'timeout': timeout per il comando (in millisecondi): dopo questo timeout,
  il processo figlio viene terminato (0 vuol dire nessun timeout)
* 'callback': funzione chiamata quando i dati dal processo figlio sono disponibili,
  oppure quando è terminato, argomenti:
** 'void *data': puntatore
** 'const char *command': comando eseguito dal processo figlio
** 'int return_code': codice restituito:
*** '>= 0': codice restituito dal comando figlio
*** '< 0': 'WEECHAT_HOOK_PROCESS_OK_RUNNING' (dati disponibili, ma figlio
    ancora in esecuzione) o 'WEECHAT_HOOK_PROCESS_ERROR' (errore nella
    esecuzione del comando)
** 'out': output standard del comando (stdout)
** 'err': output di errore del comando (stderr)
* 'callback_data': puntatore fornito alla callback quando fornita da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }
    
    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }
    
    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }
    
    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }
    
    return WEECHAT_RC_OK;
}

struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_process(command, timeout, callback, callback_data)

# esempio
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout: %s" % out)
    if err != "":
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
----------------------------------------

weechat_hook_connect
^^^^^^^^^^^^^^^^^^^^

Hook su una connessione (connessione in secondo piano ad un host remoto).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int sock,
                                     int ipv6,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);
----------------------------------------

Argomenti:

* 'proxy': name of proxy to use for connection (optional, NULL means connection
  without proxy)
* 'address': nome o indirizzo IP al quale connettersi
* 'port': numero della porta
* 'sock': socket utilizzato per la connessione
* 'ipv6': 1 per usare IPv6, 0 per usare IPv4
* 'gnutls_sess': sessione GnuTLS (opzionale)
* 'gnutls_cb': GnuTLS callback (optional)
* 'gnutls_dhkey_size': size of the key used during the Diffie-Hellman Key
  Exchange (GnuTLS)
* 'local_hostname': local hostname to use for connection (opzionale)
* 'callback': funzione chiamata quando la connessione è avvenuta con
  successo oppure no, argomenti:
** 'void *data': puntatore
** 'int status': stato della connessione:
*** 'WEECHAT_HOOK_CONNECT_OK': connessione avvenuta con successo
*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND': indirizzo non trovato
*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND': indirizzo IP non trovato
*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED': connessione rifiutata
*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR': errore con il proxy
*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR': errore con il nome host locale
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR': errore inizializzazione GnuTLS
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR': errore di handshake GnuTLS
*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR': memoria insufficiente
** 'gnutls_rc': result value of 'gnutls_handshake()'
** 'const char *error': result value of 'gnutls_strerror(gnutls_rc)'
** 'const char *ip_address': indirizzo IP trovato
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_connect_cb (void *data, int status, int gnutls_rc, const char *error,
               const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       sock, 0,
                                                       NULL, NULL, 0, /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_connect(proxy, address, port, sock, ipv6, local_hostname,
    callback, callback_data)

# esempio
def my_connect_cb(data, status, gnutls_rc, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, sock, 0, "",
                            "my_connect_cb", "")
----------------------------------------

weechat_hook_print
^^^^^^^^^^^^^^^^^^

Hook su un messaggio stampato.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL, verranno catturati i messaggi da qualsiasi
  buffer
* 'tags': verranno catturati solo messaggi con queste tag (elenco separato da virgole)
  (opzionale)
* 'message': verranno catturati solo i messaggi con questa stringa (opzionale)
* 'strip_colors': se 1, i colori verranno estratti dal messaggio visualizzato, prima
  di chiamare la callback
* 'callback': funzione chiamata quando viene stampato un messaggio, argomenti:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': puntatore al buffer
** 'time_t date': data
** 'int tags_count': numero di tag per riga
** 'const char **tags': array con tag per riga
** 'int displayed': 1 se la riga è visualizzata, 0 se filtrata (nascosta)
** 'int highlight': 1 se la riga viene evidenziata, altrimenti 0
** 'const char *prefix': prefisso
** 'const char *message': messaggio
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cattura tutti i messaggi, su tutti i buffer, senza colore */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# esempio
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    # ...
    return weechat.WEECHAT_RC_OK

# catch all messages, on all buffers, without color
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----------------------------------------

weechat_hook_signal
^^^^^^^^^^^^^^^^^^^

Hook su un segnale.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);
----------------------------------------

Argomenti:

* 'signal': segnale da catturare, può iniziare o terminare con "*":

[width="100%",cols="^1,^3,^4,5",options="header"]
|========================================
| Plugin | Segnale | Argomenti | Descrizione

| irc | xxx,irc_in_yyy ^(1)^ | string: message |
  irc message from server (before irc plugin uses it,
  signal sent only if message is *not* ignored)

| irc | xxx,irc_in2_yyy ^(1)^ | string: message |
  irc message from server (after irc plugin uses it,
  signal sent only if message is *not* ignored)

| irc | xxx,irc_raw_in_yyy ^(1)^ | string: message |
  irc message from server (before irc plugin uses it,
  signal sent even if message is ignored)

| irc | xxx,irc_raw_in2_yyy ^(1)^ | string: message |
  irc message from server (after irc plugin uses it,
  signal sent even if message is ignored)

| irc | xxx,irc_out_yyy ^1^ | string: message |
  irc message sent to server

| irc | irc_ctcp | string: message |
  CTCP received

| irc | irc_dcc | string: message |
  new DCC

| irc | irc_pv | string: message |
  private message received

| irc | irc_channel_opened | pointer: buffer |
  channel opened

| irc | irc_pv_opened | pointer: buffer |
  private opened

| irc | irc_server_connecting | string: server name |
  connecting to server

| irc | irc_server_connected | string: server name |
  connected to server

| irc | irc_server_disconnected | string: server name |
  disconnected from server

| irc | irc_ignore_removing | pointer: ignore |
  removing ignore

| irc | irc_ignore_removed | - |
  ignore removed

| logger | logger_start | pointer: buffer |
  start logging for buffer

| logger | logger_stop | pointer: buffer |
  stop logging for buffer

| logger | logger_backlog | pointer: buffer |
  display backlog for buffer

| weechat | buffer_closing | pointer: buffer |
  closing buffer

| weechat | buffer_closed | pointer: buffer |
  buffer closed

| weechat | buffer_lines_hidden | pointer: buffer |
  lines hidden in buffer

| weechat | buffer_localvar_added | pointer: buffer |
  local variable has been added

| weechat | buffer_localvar_changed | pointer: buffer |
  local variable has changed

| weechat | buffer_localvar_removed | pointer: buffer |
  local variable has been removed

| weechat | buffer_moved | pointer: buffer |
  buffer moved

| weechat | buffer_opened | pointer: buffer |
  buffer opened

| weechat | buffer_renamed | pointer: buffer |
  buffer renamed

| weechat | buffer_switch | pointer: buffer |
  switching buffer

| weechat | buffer_title_changed | pointer: buffer |
  title of buffer changed

| weechat | buffer_type_changed | pointer: buffer |
  type of buffer changed

| weechat | day_changed | string: new date, format: "2010-01-31" |
  day of system date has changed

| weechat | debug_dump | - |
  dump request

| weechat | filter_added | pointer: filter |
  filter added

| weechat | filter_removing | pointer: filter |
  removing filter

| weechat | filter_removed | - |
  filter added

| weechat | filter_enabled | - |
  filters enabled

| weechat | filter_disabled | - |
  filters disabled

| weechat | hotlist_changed | - |
  hotlist changed

| weechat | input_paste_pending | - |
  paste pending

| weechat | input_search | - |
  text search in buffer

| weechat | input_text_changed | - |
  input text changed

| weechat | input_text_cursor_moved | - |
  input text cursor moved

| weechat | key_pressed | string: key pressed |
  key pressed

| weechat | nicklist_group_added | string: buffer pointer + "," + group name |
  group added in nicklist

| weechat | nicklist_group_removed | string: buffer pointer + "," + group name |
  group removed from nicklist

| weechat | nicklist_nick_added | string: buffer pointer + "," + nick name |
  nick added in nicklist

| weechat | nicklist_nick_removed | string: buffer pointer + "," + nick name |
  nick removed from nicklist

| weechat | partial_completion | - |
  partial completion happened

| weechat | quit | string: arguments for /quit |
  command `/quit` issued by user

| weechat | upgrade | - |
  command `/upgrade` issued by user

| weechat | weechat_highlight | string: message with prefix |
  highlight happened

| weechat | weechat_pv | string: message with prefix |
  private message displayed

| weechat | window_scrolled | pointer: window |
  scroll in window

| weechat | window_unzooming | pointer: current window |
  unzooming window

| weechat | window_unzoomed | pointer: current window |
  window unzoomed

| weechat | window_zooming | pointer: current window |
  zomming window

| weechat | window_zoomed | pointer: current window |
  window zoomed

| xfer | xfer_add | pointer: infolist with xfer info |
  new xfer

| xfer | xfer_send_ready | pointer: infolist with xfer info |
  xfer ready

| xfer | xfer_accept_resume | pointer: infolist with xfer info |
  xfer accepts resume (send)

| xfer | xfer_send_accept_resume | pointer: infolist with xfer info |
  xfer accepts resume (send)

| xfer | xfer_start_resume | pointer: infolist with xfer info |
  start resume

| xfer | xfer_resume_ready | pointer: infolist with xfer info |
  xfer resume ready

| xfer | xfer_ended | pointer: infolist with xfer info |
  xfer has ended
|========================================

[NOTE]
^(1)^ 'xxx' è il nome del server IRC, 'yyy' è il nome del comando IRC.

* 'callback': funzione chiamata a segnale ricevuto, argomenti:
** 'void *data': puntatore
** 'const char *signal': segnale ricevuto
** 'const char *type_data': tipo di dati inviati con il segnale:
*** 'WEECHAT_HOOK_SIGNAL_STRING': stringa
*** 'WEECHAT_HOOK_SIGNAL_INT': numero intero
*** 'WEECHAT_HOOK_SIGNAL_POINTER': puntatore
** 'void *signal_data': dati inviati con il segnale
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_signal(signal, callback, callback_data)

# esempio
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# catch signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")
----------------------------------------

weechat_hook_signal_send
^^^^^^^^^^^^^^^^^^^^^^^^

Invia un segnale.

Prototipo:

[source,C]
----------------------------------------
void weechat_hook_signal_send (const char *signal, const char *type_data,
                               void *signal_data);
----------------------------------------

Argomenti:

* 'signal': segnale da inviare
* 'type_data': tipo di dati inviati con il segnale (consultare
  <<_weechat_hook_signal,weechat_hook_signal>>)
* 'signal_data': dati inviati con il segnale

Esempio in C:

[source,C]
----------------------------------------
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_signal_send(signal, type_data, signal_data)

# esempio
weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
----------------------------------------

weechat_hook_config
^^^^^^^^^^^^^^^^^^^

Hook su un'opzione di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);
----------------------------------------

Argomenti:

* 'option': opzione, il formato è il nome completo, come usato con il comando
  `/set` (ad esempio: `weechat.look.item_time_format`)
* 'callback': function called when configuration option is changed, arguments:
** 'void *data': pointer
** 'const char *option': name of option
** 'const char *value': new value for option
* 'callback_data': pointer given to callback when it is called by WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cattura le modifiche dell'opzione "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_config(option, callback, callback_data)

# esempio
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# cattura le modifiche dell'opzione "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
----------------------------------------

weechat_hook_completion
^^^^^^^^^^^^^^^^^^^^^^^

Hook su un completamento.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);
----------------------------------------

Argomenti:

* 'completion_item': nome dell'elemento del completamento, è possibile usare
  in seguito '%(name)' in un comando con un hook (argomento 'completion')
* 'description': descrizione di completamento
* 'callback': funzione chiamata quando viene usato l'elemento completamento
  (l'utente sta completando qualcosa usando questo elemento), argomenti:
** '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
   <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>)
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

[NOTE]
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).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_word2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# esempio
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")
----------------------------------------

weechat_hook_completion_list_add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una parola per il completamento.

Prototipo:

[source,C]
----------------------------------------
void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);
----------------------------------------

Argomenti:

* 'completion': puntatore al completamento
* 'word': parola da aggiungere
* 'nick_completion': 1 se la parola è un nick, altrimenti 0
* 'where': posizione in cui la parola sarà inserita nella lista:
** 'WEECHAT_LIST_POS_SORT': qualunque posizione, per mantenere
   la lista ordinata
** 'WEECHAT_LIST_POS_BEGINNING': inizio della lista
** 'WEECHAT_LIST_POS_END': fine della lista

Esempio in C: consultare <<_weechat_hook_completion,weechat_hook_completion>>.

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# esempio: see function hook_completion above
----------------------------------------

weechat_hook_modifier
^^^^^^^^^^^^^^^^^^^^^

Hook su un modificatore.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);
----------------------------------------

Argomenti:

* 'modifier': nome modificatore, lista di modificatori utilizzati da
  Weechat o dai plugin:

[width="100%",cols="^1,^2,3,4,4",options="header"]
|========================================
| Plugin | Modificatore | Dati modificatore | Stringa | Output

| charset | charset_decode |
  plugin.buffer_name |
  qualsiasi stringa |
  stringa codificata dal set caratteri trovato per plugin/buffer in UTF-8

| charset | charset_encode |
  plugin.buffer_name |
  any string |
  string encoded from UTF-8 to charset found for plugin/buffer

| irc | irc_color_decode |
  "1" to keep colors, "0" to remove colors |
  any string |
  string with WeeChat color codes, or without color

| irc | irc_color_encode |
  "1" to keep colors, "0" to remove colors |
  any string |
  string with IRC color codes, or without color

| irc | irc_in_xxx ^1^ |
  server name |
  content of message received from IRC server |
  new content of message

| irc | irc_out_xxx ^1^ |
  server name |
  content of message about to be sent to IRC server |
  new content of message

| weechat | bar_condition_yyy ^2^ |
  string with window pointer ("0x123..") |
  empty string |
  "1" to display bar, "0" to hide it

| weechat | input_text_content |
  string with buffer pointer ("0x123..") |
  input buffer (from user) |
  new content of input buffer

| weechat | input_text_display |
  string with buffer pointer ("0x123..") |
  input buffer (from user), without cursor tag |
  new content of input buffer, for display only (input buffer is not changed)

| weechat | input_text_display_with_cursor |
  string with buffer pointer ("0x123..") |
  input buffer (from user), with cursor tag |
  new content of input buffer, for display only (input buffer is not changed)

| weechat | weechat_print |
  plugin;buffer_name;tags |
  message printed |
  new message printed
|========================================

[NOTE]
^1^ 'xxx' è il nome del comando IRC. +
^2^ 'yyy' è il nome della barra.

* 'callback': funzione chiamata quando viene usato il modificatore,
  argomenti:
** 'void *data': puntatore
** 'const char *modifier': nome del modificatore
** 'const char *modifier_data': dati per il modificatore
** 'const char *string': stringa da modificare (la funzione deve restituire
   una copia di questa stringa, non è consentito alcun cambiamento in
    questa stringa)
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;
    
    if (!string)
        return NULL;
    
    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* aggiunge "xxx" ad ogni messaggio stampato */
        snprintf (result, length, "%s xxx", string);
    }
    
    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_modifier(modifier, callback, callback_data)

# esempio
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
----------------------------------------

weechat_hook_modifier_exec
^^^^^^^^^^^^^^^^^^^^^^^^^^

Esegue modificatore(i).

Prototipo:

[source,C]
----------------------------------------
char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);
----------------------------------------

Argomenti:

* 'modifier': nome modificatore
* 'modifier_data': dati modificatore
* 'string': stringa da modificare

Valore restituito:

* stringa modificata, NULL se nessun cambiamento nella stringa è
  stato effettuato dal modificatore(i).

Esempio in C:

[source,C]
----------------------------------------
char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_modifier_exec(modifier, modifier_data, string)

# esempio
weechat.hook_modifier_exec("my_modifier", my_data, my_string)
----------------------------------------

weechat_hook_info
^^^^^^^^^^^^^^^^^

Hook su una informazione.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);
----------------------------------------

Argomenti:

* 'info_name': nome della info
* 'description': descrizione
* 'args_description': descrizione degli argomenti
* 'callback': funzione chiamata alla richiesta di una info, argomenti:
** 'void *data': puntatore
** 'const char *info_name': nome della info
** 'const char *arguments': argomenti addizionali, dipendono dalle info
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* add info "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# esempio
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")
----------------------------------------

weechat_hook_infolist
^^^^^^^^^^^^^^^^^^^^^

Hook su una lista info: la callback restituisce il puntatore alla lista info
richiesta.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      const char *(*callback)(void *data,
                                                              const char *infolist_name,
                                                              void *pointer,
                                      const char *arguments),
                                      void *callback_data);
----------------------------------------

Argomenti:

* 'infolist_name': nome della lista info
* 'description': descrizione
* 'pointer_description': descrizione del puntatore (opzionale, può essere NULL)
* 'args_description': descrizione degli argomenti (opzionale, può essere NULL)
* 'callback': funzione chiamata alla richiesta della lista info, argomenti:
** 'void *data': puntatore
** 'const char *infolist_name': nome della lista info
** 'void *pointer': puntatore ad un oggetto che la lista info deve restituire
   (per ricevere un solo elemento della lista info)
** 'const char *arguments': argomento aggiuntivo, dipende dalla lista info
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;
    
    /* build infolist */
    /* ... */
    
    return my_infolist;
}

/* add infolist "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# esempio
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")
----------------------------------------

weechat_unhook
^^^^^^^^^^^^^^

Rimuove l'hook.

Prototipo:

[source,C]
----------------------------------------
void weechat_unhook (struct t_hook *hook);
----------------------------------------

Argomenti:

* 'hook': qualcosa su cui è presente un hook con "weechat_hook_xxx()"

Esempio in C:

[source,C]
----------------------------------------
struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.unhook(hook)

# esempio
weechat.unhook(my_hook)
----------------------------------------

weechat_unhook_all
^^^^^^^^^^^^^^^^^^

Rimuove l'hook in qualsiasi punto in cui è stato attivato dal
plugin corrente.

Prototipo:

[source,C]
----------------------------------------
void weechat_unhook_all ();
----------------------------------------

Esempio in C:

[source,C]
----------------------------------------
weechat_unhook_all ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.unhook_all()

# esempio
weechat.unhook_all()
----------------------------------------

[[buffers]]
Buffers
~~~~~~~

Funzioni per creare/richiedere/chiudere buffer.

weechat_buffer_new
^^^^^^^^^^^^^^^^^^

Apre un nuovo buffer.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);
----------------------------------------

Argomenti:

* 'name': nome del buffer (deve essere unico per il plugin)
* 'input_callback': funzione chiamata quando il testo in input è stato
  inserito nel buffer, argomenti:
*** 'void *data': puntatore
*** 'struct t_gui_buffer *buffer': puntatore al buffer
*** 'const char *input_data': dati in input
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat
* 'close_callback': funzione chiamata alla chiusura del buffer, argomenti:
*** 'void *data': puntatore
*** 'struct t_gui_buffer *buffer': puntatore al buffer
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo buffer, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Text: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Buffer '%s' will be closed!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# esempio
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Text: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
----------------------------------------

weechat_current_buffer
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore al buffer corrente (buffer visualizzato nella
finestra corrente).

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_current_buffer ();
----------------------------------------

Valore restituito:

* puntatore al buffer corrente

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (weechat_current_buffer (), "Testo sul buffer corrente");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.current_buffer()

# esempio
weechat.prnt(weechat.current_buffer(), "Testo sul buffer corrente")
----------------------------------------

weechat_buffer_search
^^^^^^^^^^^^^^^^^^^^^

Cerca un buffer tramite plugin e/o nome.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);
----------------------------------------

Argomenti:

* 'plugin': nome del plugin
* 'name': nome del buffer, se NULL o la stringa è vuota, viene
  restituito il buffer corrente (buffer visualizzato dalla finestra corrente)

Valore restituito:

* puntatore al buffer trovato, NULL in caso contrario

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_search(plugin, name)

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
----------------------------------------

weechat_buffer_search_main
^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca nel buffer principale di WeeChat (per primo nel buffer 'core', il primo
visualizzato all'avvio di WeeChat).

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search_main ();
----------------------------------------

Valore restituito:

* puntatore al buffer principale di WeeChat (buffer 'core')

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_search_main()

# esempio
buffer = weechat.buffer_search_main()
----------------------------------------

weechat_buffer_clear
^^^^^^^^^^^^^^^^^^^^

Pulisce il contenuto del buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_clear (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_clear(buffer)

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)
----------------------------------------

weechat_buffer_close
^^^^^^^^^^^^^^^^^^^^

Chiude un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_close (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_close(buffer)

# esempio
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----------------------------------------

weechat_buffer_merge
^^^^^^^^^^^^^^^^^^^^

Unisce un buffer in un altro: entrambi i buffer esistono separatamente, ma
con lo stesso numero, e WeeChat visualizzerà le righe di entrambi i
buffer (righe mischiate).

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'target_buffer': buffer di destinazione, dove il buffer verrà unito

Esempio in C:

[source,C]
----------------------------------------
/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_merge(buffer, target_buffer)

# esempio
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----------------------------------------

weechat_buffer_unmerge
^^^^^^^^^^^^^^^^^^^^^^

Stacca un buffer da un gruppo di buffer uniti.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'number': numero di destinazione per il buffer staccato,
  se è < 1, allora il buffer verrà spostato al numero di
  'buffer' +1

Esempio in C:

[source,C]
----------------------------------------
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_unmerge(buffer, number)

# esempio
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----------------------------------------

weechat_buffer_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore intero della proprietà di
un buffer.

Prototipo:

[source,C]
----------------------------------------
int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome della proprietà:
** 'number': numero del buffer (inizia da 1)
** 'layout_number': number of buffer saved in layout
** 'type': buffer type (0: formatted, 1: free content)
** 'notify': livello di notifica per il buffer
** 'num_displayed': numero delle finestre che visualizzano il buffer
** 'active': 1 if buffer is active, 0 if buffer is merged and not selected
** 'print_hooks_enabled': 1 if print hooks are enabled, otherwise 0
** 'lines_hidden': 1 se almeno una riga è nascosta sul buffer (filtrata),
   oppure 0 se vengono visualizzate tutte le righe
** 'prefix_max_length': lunghezza massima del prefisso in questo buffer
** 'time_for_each_line': 1 se l'ora è visualizzata per ogni riga nel buffer
   (predefinito), altrimenti 0
** 'nicklist': 1 if nicklist is enabled, otherwise 0
** 'nicklist_case_sensitive': 1 if nicks are case sensitive, otherwise 0
** 'nicklist_max_length': max length for a nick
** 'nicklist_display_groups': 1 if groups are displayed, otherwise 0
** 'nicklist_visible_count': number of nicks/groups displayed
** 'input': 1 if input is enabled, otherwise 0
** 'input_get_unknown_commands': 1 if unknown commands are sent to input
   callback, otherwise 0
** 'input_size': input size (in bytes)
** 'input_length': input length (number of chars)
** 'input_pos': cursor position in buffer input
** 'input_1st_display': first char displayed on screen
** 'num_history': number of commands in history
** 'text_search': tipo di ricerca nel testo:
*** 0: nessuna ricerca in questo momento
*** 1: ricerca all'indietro (direzione: messaggi più vecchi)
*** 2: ricerca in avanti (direzione: messaggi più nuovi)
** 'text_search_exact': 1 se la ricerca testo è esatta
** 'text_search_found': 1 se il testo viene trovato, altrimenti 0

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_integer(buffer, property)

# esempio
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
----------------------------------------

weechat_buffer_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa di una proprietà del buffer.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome proprietà:
** 'plugin': nome del plugin che ha creato questo buffer ("core"
   per il buffer principale di WeeChat)
** 'name': nome del buffer
** 'short_name': nome breve del buffer
** 'tilte': titolo del buffer
** 'input': testo in ingresso
** 'text_search_input': input saved before text search
** 'highlight_words': list of words to highlight
** 'highlight_tags': list of tags to highlight
** 'localvar_xxx': ottiene il contenuto della variabile locale "xxx"
   (sostituire "xxx" con il nome della variabile da leggere)

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_string(buffer, property)

# esempio
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))
----------------------------------------

weechat_buffer_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore puntatore della proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                                    const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome proprietà:
** 'plugin': puntatore al plugin che ha creato questo buffer (NULL
   per il buffer principale di WeeChat)

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "plugin pointer of my buffer: %lx",
                weechat_buffer_get_pointer (my_buffer, "plugin"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_pointer(buffer, property)

# esempio
weechat.prnt("", "plugin pointer of my buffer: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----------------------------------------

weechat_buffer_set
^^^^^^^^^^^^^^^^^^

Imposta il valore stringa della proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property' e 'value': nome della proprietà, con il proprio valore:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Name | Value | Description

| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT |
  "+": abilita hotlist (impostazione globale , il puntatore al buffer pointer non
  è utilizzato) +
  "-": disabilita hotlist (impostazione globale, il puntatore al buffer non è
  utilizzato) +
  priorità: aggiunge il buffer alla hotlist con questa proprietà

| unread | - |
  imposta l'evidenziatore di lettura dopo l'ultima riga del buffer

| display | "1", "auto" |
  "1": passa a questo buffer nella finestra corrente +
  "auto": passa a questo buffer nella finestra corrente, l'evidenziatore di
  lettura non viene resettato

| number | numero |
  sposta buffer a questo numero

| name | qualsiasi stringa |
  imposta nuovo nome per il buffer

| short_name | qualsiasi stringa |
  imposta nuovo nome breve per il buffer

| type | "formatted" o "free" |
  imposta tipo per il: "formatted" (per stampare i messaggi di chat),
  oppure "free" (per contenuto libero)

| notify | "0", "1", "2", "3" |
  set notify level for buffer: "0" = never add to hotlist, "1" = add for
  highlights only, "2" = add for highlights and messages, "3" = add for all
  messages

| title | any string |
  set new title for buffer

| time_for_each_line | "0" or "1" |
  "0" to hide time for all lines in buffer, "1" to see time for all lines
  (default for a new buffer)

| nicklist | "0" or "1" |
  "0" to remove nicklist for buffer, "1" to add nicklist for buffer

| nicklist_case_sensitive | "0" or "1" |
  "0" to have case insensitive nicklist, "1" to have case sensitive nicklist

| nicklist_display_groups | "0" or "1" |
  "0" to hide nicklist groups, "1" to display nicklist groups

| highlight_words | "-" or comma separated list of words |
  "-" is a special value to disable any highlight on this buffer, or comma
  separated list of words to highlight in this buffer, for example:
  "abc,def,ghi"

| highlight_tags | comma separated list of tags |
  comma separated list of tags to highlight in this buffer

| key_bind_xxx | any string |
  bind a new key 'xxx', specific to this buffer, value is command to execute
  for this key

| key_unbind_xxx | - |
  unbind key 'xxx' for this buffer

| input | any string |
  set new value for buffer input

| input_pos | position |
  set cursor position in buffer input

| input_get_unknown_commands | "0" or "1" |
  "0" to disable unknown commands on this buffer (default behaviour), "1" to
  get unknown commands, for example if user type "/unknowncmd", buffer will
  receive it (no error about unknown command)

| localvar_set_xxx | any string |
  set new value for local variable 'xxx' (variable is created if it does not
  exist)

| localvar_del_xxx | - |
  remove local variable 'xxx'
|========================================

Esempio in C:

[source,C]
----------------------------------------
/* disabilita hotlist (per tutti i buffer) */
weechat_buffer_set (NULL, "hotlist", "-");

/* abilita nuovamente hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* cambia il nome buffer */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* aggiunge una nuova variabile locale "tizio" con il valore "abc" */
weechat_buffer_set (my_buffer, "localvar_set_tizio", "abc");

/* rimuove la variabile locale "tizio" */
weechat_buffer_set (my_buffer, "localvar_del_tizio", NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_set(buffer, property, value)

# esempi

# disabilita hotlist (per tutti i buffer)
weechat.buffer_set("", "hotlist", "-")

# abilita nuovamente hotlist
weechat.buffer_set("", "hotlist", "+")

# cambia il nome buffer
weechat.buffet_set(my_buffer, "name", "my_new_name")

# aggiunge una nuova variabile locale "tizio" con il valore "abc"
weechat.buffet_set(my_buffer, "localvar_set_tizio", "abc")

# rimuove la variabile locale "tizio"
weechat.buffet_set(my_buffer, "localvar_del_toto", "")
----------------------------------------

weechat_buffer_set_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta il valore puntatore per la proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property' e 'value': nome della proprietà, con il proprio valore:
** 'close_callback': set close callback function
** 'close_callback_data': set close callback data
** 'input_callback': set input callback function
** 'input_callback_data': set input callback data

Esempio in C:

[source,C]
----------------------------------------
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
----------------------------------------

weechat_buffer_string_replace_local_var
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sostituisce le variabili globali in una stringa con i loro valori, utilizzando
le variabili del buffer locale.

Prototipo:

[source,C]
----------------------------------------
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'string': stringa con testo e variabili locali che utilizzano il formato "$var"

Valore restituito:

* stringa con i valori delle variabili locali

Esempio in C:

[source,C]
----------------------------------------
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contains "test with abc" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_string_replace_local_var(buffer, string)

# esempio
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"
----------------------------------------

[[windows]]
Windows
~~~~~~~

Functions to query windows.

weechat_current_window
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore alla finestra corrente

Prototipo:

[source,C]
----------------------------------------
struct t_gui_window *weechat_current_window ();
----------------------------------------

Valore restituito:

* puntatore alla finestra corrente

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_window *current_window = weechat_current_window ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
window = weechat.current_window()

# esempio
current_window = weechat.current_window()
----------------------------------------

weechat_window_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

 il valore intero della proprietà di una finestra.

Prototipo:

[source,C]
----------------------------------------
int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà:
** 'win_x': posizione X della finestra nel terminale (la prima colonna è 0)
** 'win_y': posizione Y della finestra nel terminale (la prima riga è 0)
** 'win_width': larghezza della finestra, in caratteri
** 'win_height': altezza della finestra, in caratteri
** 'win_width_pct': misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 vuol dire metà grandezza)
** 'win_height_pct': misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 vuol dire metà grandezza)
** 'win_chat_x': posizione X della finestra di chat nel terminale
   (la prima colonna è 0)
** 'win_chat_y': posizione Y della finestra di chat nel terminale
   (la prima riga è 0)
** 'win_chat_width': larghezza della finestra di chat, in caratteri
** 'win_chat_height': altezza della finestra di chat, in caratteri
** 'first_line_displayed': 1 se la prima riga del buffer viene visualizzata
   su schermo, altrimenti 0
** 'scroll': 1 se lo scorrimento è attivo sulla finestra (ultima riga non
   visualizzata)
** 'scroll_lines_after': numero di righe non visualizzate dopo l'ultima
   visualizzata (durante lo scorrimento)

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.window_get_integer(window, property)

# esempio
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))
----------------------------------------

weechat_window_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa della proprietà di una finestra.

[NOTE]
La funzione non è utilizzata oggi, è riservata per una versione futura.

Prototipo:

[source,C]
----------------------------------------
int weechat_window_get_string (struct t_gui_window *window,
                               const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà

Valore restituito:

* valore stringa della proprietà

weechat_window_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore puntatore della proprietà di una finestra.

Prototipo:

[source,C]
----------------------------------------
void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà:
** 'current': puntatore alla finestra corrente
** 'buffer': puntatore al buffer visualizzato dalla finestra

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL,
                "buffer displayed in current window: %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.window_get_pointer(window, property)

# esempio
weechat.prnt("", "buffer displayed in current window: %lx"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----------------------------------------

weechat_window_set_title
^^^^^^^^^^^^^^^^^^^^^^^^

 il titolo per il terminale.

Prototipo:

[source,C]
----------------------------------------
void weechat_window_set_title (const char *title);
----------------------------------------

Argomenti:

* 'title': nuovo titolo per il terminale (NULL per resettarlo)

Esempio in C:

[source,C]
----------------------------------------
weechat_window_set_title ("nuovo titolo qui");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.window_set_title(window, title)

# esempio
weechat.window_set_title("nuovo titolo qui")
----------------------------------------

[[nicklist]]
Nicklist
~~~~~~~~

 per il buffer nicklist.

weechat_nicklist_add_group
^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un gruppo in una nicklist.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'parent_group': puntatore al genitore del gruppo, NULL se il gruppo non ha genitore
  (nicklist radice)
* 'name': nome del gruppo
* 'visible':
** '1': gruppi e sottogruppi/nick sono visibili
** '0': gruppi e sottogruppi/nick sono nascosti
* 'color': nome per l'opzione colore:
** nome opzione per WeeChat, ad esempio 'weechat.color.nicklist_group'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** nome colore per la barra:
*** 'bar_fg': colore di primo piando per la barra
*** 'bar_delim': colore dei delimitatori per la barra
*** 'bar_bg': colore di sfondo per la barra

[NOTE]
Il nome del gruppo può iniziare con uno o più numeri, seguiti da una pipe, e
infine dal nome del gruppo. Quando questa stringa si trova all'inizio, viene
utilizzata per ordinare i gruppi nella lista nick. Ad esempio i gruppi "1|test" e
"2|abc" verranno visualizzati in quest'ordine: prima "test" poi "abc".

Valore restituito:

* puntatore al nuovo gruppo, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# esempio
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)
----------------------------------------

weechat_nicklist_search_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un gruppo in una lista nick.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'from_group': ricerca solo da questo gruppo, se NULL, allora la cerca in
  tutta la lista nick
* 'name': nome gruppo da cercare

Valore restituito:

* puntatore al gruppo trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "test_group");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
group = weechat.nicklist_search_group(buffer, from_group, name)

# esempio
group = weechat.nicklist_search_group(my_buffer, "", "test_group")
----------------------------------------

weechat_nicklist_add_nick
^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un nick in un gruppo.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'name': nome nick
* 'color': nome dell'opzione per il colore:
*** nome opzione per WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
*** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
*** nome colore per la barra:
**** 'bar_fg': colore di primo piano per la barra
**** 'bar_delim': colore dei delimitatori per la barra
**** 'bar_bg': colore di sfondo per la barra
* 'prefix': prefisso visualizzato prima del nick
* 'prefix_color': nome dell'opzione per il colore:
** nome opzione per WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** nome colore per la barra:
*** 'bar_fg': colore di primo piano per la barra
*** 'bar_delim': colore dei delimitatori per la barra
*** 'bar_bg': colore di sfondo per la barra
* 'visible':
** '1': il nick è visibile
** '0': il nick è nascosto

Valore restituito:

* puntatore al nuovo nick, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# esempio
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
----------------------------------------

weechat_nicklist_search_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un nick nella lista nick.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'from_group': cerca solo da questo gruppo, se NULL, allora cerca
  nell'intera lista nick
* 'name': nick da cercare

Valore restituito:

* puntatore al nuovo nick, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# esempio
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
----------------------------------------

weechat_nicklist_remove_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un gruppo da una lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo da rimuovere (verranno rimossi anhe
  i sottogruppi/nick)

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_group (my_buffer, my_group);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_group(buffer, group)

# esempio
weechat.nicklist_remove_group(my_buffer, my_group)
----------------------------------------

weechat_nicklist_remove_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un nick dalla lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick da rimuovere

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_nick (my_buffer, my_nick);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_nick(buffer, nick)

# esempio
weechat.nicklist_remove_nick(my_buffer, my_nick)
----------------------------------------

weechat_nicklist_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove tutti i gruppi/nick da una lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_all (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_all(buffer)

# esempio
weechat.nicklist_remove_all(my_buffer)
----------------------------------------

[[bars]]
Barre
~~~~~

Functions for bars.

weechat_bar_item_search
^^^^^^^^^^^^^^^^^^^^^^^

Cerca un elemento barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra

Valore restituito:

* puntatore all'elemento barra trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar_item = weechat.bar_item_search(name)

# esempio
bar_item = weechat.bar_item_search("myitem")
----------------------------------------

weechat_bar_item_new
^^^^^^^^^^^^^^^^^^^^

Crea un nuovo elemento barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(build_callback)(void *data,
                                                                    struct t_gui_bar_item *item,
                                                                    struct t_gui_window *window),
                                             void *build_callback_data);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra
* 'build_callback': funzione chiamata quando l'elemento barra viene
  compilato; deve restituire il contenuto dell'elemento barra
* 'build_callback_data': puntatore fornito alla callback quando
  chiamata da WeeChat

Valore restituito:

* puntatore al nuovo elemento barra, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# esempio
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")
----------------------------------------

weechat_bar_item_update
^^^^^^^^^^^^^^^^^^^^^^^

Aggiorna il contenuto dell'elemento barra, chiamando la callback
che lo ha compilato.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_item_update (const char *name);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_item_update ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_item_update(name)

# esempio
weechat.bar_item_update("myitem")
----------------------------------------

weechat_bar_item_remove
^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un elemento barra.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_item_remove (struct t_gui_bar_item *item);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_item_remove (&my_item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_item_remove(item)

# esempio
weechat.bar_item_remove(myitem)
----------------------------------------

weechat_bar_search
^^^^^^^^^^^^^^^^^^

Cerca una barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_search (const char *name);
----------------------------------------

Argomenti:

* 'name': nome della barra

Valore restituito:

* puntatore alla barra trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar *bar = weechat_bar_search ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar = weechat.bar_search(name)

# esempio
bar = weechat.bar_search("mybar")
----------------------------------------

weechat_bar_new
^^^^^^^^^^^^^^^

Crea una nuova barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *separator,
                                   const char *items);
----------------------------------------

Argomenti:

* 'name': nome della barra
* 'hidden':
** 'on': la barra è nascosta
** 'off': la barra è visibile
* 'priority': priorità per la barra (intero)
* 'type':
** 'root': barra visualizzata una sola volta, al di fuori delle finestre
** 'window': barra visualizzata in ogni finestra
* 'condition': condizioni per la visualizzazione della barra:
** 'active': la barra viene visualizzata solo nella finestra attiva
** 'inactive': la barra viene visualizzata solo nelle finestre inattive
** 'nicklist': la barra viene visualizzata nelle finestre con liste nick
* 'position': 'top', 'bottom', 'left' o 'right'
* 'filling_top_bottom':
** 'horizontal': gli elementi sono posizionati in orizzontale
   (spazio dopo ogni elemento)
** 'vertical': gli elementi sono posizionati in verticale
   (nuova riga dopo ogni elemento)
** 'columns_horizontal': gli elementi sono posizionati in orizzontale,
   visualizzati su colonne
** 'columns_vertical': gli elementi sono posizionati in verticale,
   visualizzati su colonne
* 'filling_left_right':
** 'horizontal': gli elementi sono posizionati in orizzontale
   (spazio dopo ogni elemento)
** 'vertical': gli elementi sono posizionati in verticale
   (nuova riga dopo ogni elemento)
** 'columns_horizontal': gli elementi sono posizionati in orizzontale,
   visualizzati su colonne
** 'columns_vertical': gli elementi sono posizionati in verticale,
   visualizzati su colonne
* 'size': dimensione della barra in caratteri
  (0 corrisponde a dimensione automatica)
* 'size_max': dimensione massima per la barra
  (0 corrisponde a nessuna dimensione massima)
* 'color_fg': colore per il testo nella barra
* 'color_delim': colore per i delimitatori nella barra
* 'color_bg': colore di sfondo per la barra
* 'separator':
** 'on': la barra ha una riga di separazione con altre finestre/barre
** 'off': nessun separatore
* 'items': elenco di elemento nella barra, separati da virgola (spazio tra
  gli elementi), o "+" (elementi incollati)

Valore restituito:

* puntatore alla nuova barra, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
                                            "off",
                                            100,
                                            "window",
                                            "",
                                            "top",
                                            "horizontal",
                                            "vertical",
                                            "0",
                                            "5",
                                            "default",
                                            "cyan",
                                            "blue",
                                            "off",
                                            "time,buffer_number+buffer_name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# esempio
bar = weechat.bar_new("mybar", "off", 100, "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
----------------------------------------

weechat_bar_set
^^^^^^^^^^^^^^^

Imposta un nuovo valore per la proprietà di una barra.

Prototipo:

[source,C]
----------------------------------------
int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);
----------------------------------------

Argomenti:

* 'bar': puntatore alla barra
* 'property': name, hidden, priority, conditions, position, filling_top_bottom,
  filling_left_right, size, size_max, color_fg, color_delim, color_bg,
  separator, items (consultare <<_weechat_bar_new,weechat_bar_new>>)
* 'value': nuovo valore per la proprietà

Valore restituito:

* 1 se il nuovo valore è stato impostato, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_set (mybar, "position", "bottom");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_set(bar, property, value)

# esempio
weechat.bar_set(my_bar, "position", "bottom")
----------------------------------------

weechat_bar_update
^^^^^^^^^^^^^^^^^^

Aggiorna il contenuto di una barra su schermo.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_update (const char *name);
----------------------------------------

Argomenti:

* 'name': nome della barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_update ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_update(name)

# esempio
weechat.bar_update("mybar")
----------------------------------------

weechat_bar_remove
^^^^^^^^^^^^^^^^^^

Rimuove una barra.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_remove (struct t_gui_bar *bar);
----------------------------------------

Argomenti:

* 'bar': puntatore alla barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_remove (mybar);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_remove(bar)

# esempio
weechat.bar_remove(my_bar)
----------------------------------------

[[commands]]
Comandi
~~~~~~~

Funzioni per eseguire comandi di WeeChat.

weechat_command
^^^^^^^^^^^^^^^

Esegue un comando.

Prototipo:

[source,C]
----------------------------------------
void weechat_command (struct t_gui_buffer *buffer, const char *command);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer (il comando viene eseguito su questo buffer,
  utilizzare NULL per il buffer core di WeeChat)
* 'command': comando da eseguire (se preceduto da "/"), oppure il testo
  viene inviato sul buffer

Esempio in C:

[source,C]
----------------------------------------
weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                 "/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.command(buffer, command)

# esempio
weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
----------------------------------------

[[network]]
Network
~~~~~~~

Funzioni di rete.

weechat_network_pass_proxy
^^^^^^^^^^^^^^^^^^^^^^^^^^

Stabilisce una connessione/autenticazione con un proxy.

Prototipo:

[source,C]
----------------------------------------
int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);
----------------------------------------

Argomenti:

* 'proxy': nome del proxy da utilizzare
* 'sock': socket da utilizzare
* 'address': indirizzo (nome host o indirizzo IP)
* 'port': port

Valore restituito:

* 1 se la connessione è andata a buon fine, 0 in caso di
  errore

Esempio in C:

[source,C]
----------------------------------------
if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* error */
}
----------------------------------------

weechat_network_connect_to
^^^^^^^^^^^^^^^^^^^^^^^^^^

Stabilisce una connessione con un host remoto.

Prototipo:

[source,C]
----------------------------------------
int weechat_network_connect_to (const char *proxy,
                                int sock,
                                unsigned long address,
                                int port);
----------------------------------------

Argomenti:

* 'proxy': nome del proxy da utilizzare
* 'sock': socket da utilizzare
* 'address': indirizzo
* 'port': porta

Valore restituito:

* 1 se la connessione è andata a buon fine, 0 in
  caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct sockaddr_in addr;
socklen_t length;
unsigned long address;

memset (&addr, 0, sizeof (struct sockaddr_in));
length = sizeof (addr);
getsockname (sock, (struct sockaddr *) &addr, &length);
addr.sin_family = AF_INET;
address = ntohl (addr.sin_addr.s_addr);

if (weechat_network_connect_to (NULL, sock, address, 6667))
{
    /* OK */
}
else
{
    /* errore */
}
----------------------------------------

[[infos]]
Info
~~~~

Funzioni per ottenere info.

weechat_info_get
^^^^^^^^^^^^^^^^

Restituisce informazioni da WeeChat o da un plugin.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_info_get (const char *info_name, const char *arguments);
----------------------------------------

Argomenti:

* 'info_name': nome delle informazioni da leggere:
include::autogen/plugin_api/infos.txt[]
* 'arguments': argomenti per l'informazione richiesta (opzionake, NULL se non
  è richiesto alcun argomento)

Valore restituito:

* stringa con l'informazione richiesta, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                weechat_info_get ("version", NULL),
                weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
                weechat_info_get ("weechat_dir", NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.info_get(info_name, arguments)

# esempio
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir"))
----------------------------------------

[[infolists]]
Liste info
~~~~~~~~~~

Una lista info è una lista di "elementi". Ciascun elemento contiene
delle variabili.

Ad esempio, la lista info "irc_server" ha N elementi (N è il numero di
server IRC definiti). Per ogni elemento, esistono variabili come "name",
"buffer", "is connected",...

Ogni variabile ha un tipo e un valore. I tipi possibili sono:

* 'integer': qualunque valore intero
* 'string': qualunque valore stringa
* 'pointer': qualunque puntatore
* 'buffer': buffer di lunghezza fissa, contenente qualunque dato
* 'time': valore tempo

weechat_infolist_new
^^^^^^^^^^^^^^^^^^^^

Crea una nuova lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_new ();
----------------------------------------

Valore restituito:

* puntatore alla nuova lista info

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_new ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
infolist = weechat.infolist_new()

# esempio
infolist = weechat.infolist_new()
----------------------------------------

weechat_infolist_new_item
^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un elemento alla lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* puntatore al nuovo elemento

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.infolist_new_item(infolist)

# esempio
item = weechat.infolist_new_item(infolist)
----------------------------------------

weechat_infolist_new_var_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile intera ad un elemento della
lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'value': valore intero

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_integer(item, name, value)

# esempio
var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----------------------------------------

weechat_infolist_new_var_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile stringa ad un elemento
della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'value': valore stringa

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_string(item, name, value)

# esempio
var = weechat.infolist_new_var_string(item, "my_string", "value")
----------------------------------------

weechat_infolist_new_var_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile puntatore ad un elemento
della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'pointer': puntatore

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_pointer(item, name, pointer)

# esempio
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----------------------------------------

weechat_infolist_new_var_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile puntatore ad un elemento della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome della variabile
* 'pointer': puntatore al buffer
* 'size': dimensione del buffer

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item,
                                                                   "my_buffer",
                                                                   &buffer,
                                                                   sizeof (buffer));
----------------------------------------

weechat_infolist_new_var_time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile tempo ad un elemento della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome della variabile
* 'time': valore tempo

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_variable_time (item,
                                                                 "my_time",
                                                                 time (NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_time(item, name, time)

# esempio
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
----------------------------------------

weechat_infolist_get
^^^^^^^^^^^^^^^^^^^^

Restituisce una lista info da WeeChat o da un plugin.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);
----------------------------------------

Argomenti:

* 'infolist_name': nome della lista info da leggere:
include::autogen/plugin_api/infolists.txt[]
* 'pointer': puntatore ad un elemento, per ricevere solo questo
  elemento nella lista info (opzionale, può essere NULL)
* 'arguments': argomenti per la lista info richiesta (opzionale, NULL se
  non è necessario alcun argomento)

Valore restituito:

* puntatore alla lista info, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# esempio
infolist = weechat.infolist_get("irc_server, "", "")
----------------------------------------

weechat_infolist_next
^^^^^^^^^^^^^^^^^^^^^

Sposta "cursor" all'elemento successivo nella lista info. La prima chiamata
a questa funzione per una lista info sposta il cursore al primo elemento
nella lista info.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_next (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* 1 se il cursore è stato spostato sull'elemento successivo, 0 se è
  stata raggiunta la fine della lista

Esempio in C:

[source,C]
----------------------------------------
if (weechat_infolist_next (infolist))
{
    /* legge variabili nell'elemento... */
}
else
{
    /* nessun altro elemento disponibile */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.infolist_next(infolist)

# esempio
rc = weechat.infolist_next(infolist)
if rc:
    # legge variabili nell'elemento...
else:
    # nessun altro elemento disponibile
----------------------------------------

weechat_infolist_prev
^^^^^^^^^^^^^^^^^^^^^

Sposta "cursor" all'elemento precedente nella lista info. La prima
chiamata a questa funzione per una lista info sposta il cursore
all'ultimo elemento.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_prev (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* 1 se il cursore è stato spostato sull'elemento precedente, 0 se
  è stato raggiunto l'inizio della lista

Esempio in C:

[source,C]
----------------------------------------
if (weechat_infolist_prev (infolist))
{
    /* legge variabili nell'elemento... */
}
else
{
    /* nessun altro elemento disponibile */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.infolist_prev(infolist)

# esempio
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----------------------------------------

weechat_infolist_reset_item_cursor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ripristina "cursor" per la lista info.

Prototipo:

[source,C]
----------------------------------------
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Esempio in C:

[source,C]
----------------------------------------
weechat_infolist_reset_item_cursor (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.infolist_reset_item_cursor(infolist)

# esempio
weechat.infolist_reset_item_cursor(infolist)
----------------------------------------

weechat_infolist_fields
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce una lista di campi per l'elemento della
lista info corrente.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_infolist_fields (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* stringa con una lista di campi per l'elemento della lista info corrente.
  La lista è separata da virgole, e contiene lettere per tipo, seguite dal
  nome della variabile. I tipi sono: "i" (intero), "s" (stringa), "p" (puntatore),
  "b" (buffer), "t" (tempo).

Esempio in C:

[source,C]
----------------------------------------
const char *fields = weechat_infolist_fields (infolist);
/* i campi contengono qualcosa come:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
fields = weechat.infolist_fields(infolist)

# esempio
fields = weechat.infolist_fields(infolist)
# i campi contengono qualcosa come:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
----------------------------------------

weechat_infolist_integer
^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile intera nell'elemento
corrente della lista info.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_integer (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "integer")

Valore restituito:

* valore intero della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "mio_intero"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_integer(infolist, var)

# esempio
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "mio_intero"))
----------------------------------------

weechat_infolist_string
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile stringa nell'elemento
della lista info corrente.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "string")

Valore restituito:

* valore stringa della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "mia_stringa"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_string(infolist, var)

# esempio
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "mia_stringa"))
----------------------------------------

weechat_infolist_pointer
^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile puntatore nell'elemento
della lista info corrente.

Prototipo:

[source,C]
----------------------------------------
void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "pointer")

Valore restituito:

* puntatore al valore della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "pointer = 0x%lx",
                weechat_infolist_pointer (infolist, "mio_puntatore"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_pointer(infolist, var)

# esempio
weechat.prnt("", "pointer = 0x%lx" % weechat.infolist_pointer(infolist, "mio_puntatore"))
----------------------------------------

weechat_infolist_buffer
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile buffer nell'elemento corrente
della lista info.

Prototipo:

[source,C]
----------------------------------------
void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "buffer")
* 'size': puntatore ad una variabile intera, verrà impostata con la
  dimensione del buffer

Valore restituito:

* puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);
----------------------------------------

weechat_infolist_time
^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile data/ora nell'elemento
attivo della lista info.

Prototipo:

[source,C]
----------------------------------------
time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "time")

Valore restituito:

* valore della variabile nel formato data/ora

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_time(infolist, var)

# esempio
weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
----------------------------------------

weechat_infolist_free
^^^^^^^^^^^^^^^^^^^^^

Libera una lista info.

Prototipo:

[source,C]
----------------------------------------
void weechat_infolist_free (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Esempio in C:

[source,C]
----------------------------------------
weechat_infolist_free (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.infolist_free(infolist)

# esempio
weechat.infolist_free(infolist)
----------------------------------------

[[upgrade]]
Upgrade
~~~~~~~

Funzioni per l'aggiornamento di WeeChat (comando "/upgrade").

weechat_upgrade_new
^^^^^^^^^^^^^^^^^^^

Crea o legge un file per l'aggiornamento.

Prototipo:

[source,C]
----------------------------------------
struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);
----------------------------------------

Argomenti:

* 'filename': nome del file (l'estensione ".upgrade" verrà aggiunta a questo nome
  da WeeChat)
* 'write':
** '1': crea il file (in modalità scrittura, prima dell'aggiornamento)
** '0': legge il file (dopo l'aggiornamento)

Valore restituito:

* puntatore al file di aggiornamento

Esempio in C:

[source,C]
----------------------------------------
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("mio_file", 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
upgrade_file = weechat.upgrade_new(filename, write)

# esempio
upgrade_file = weechat.upgrade_new("mio_file", 1)
----------------------------------------

weechat_upgrade_write_object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Scrive un oggetto nel file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento
* 'object_id': id per l'oggetto
* 'infolist': lista info da scrivere nel file

Valore restituito:

* 1 se ok, 0 se errore

Esempio in C:

[source,C]
----------------------------------------
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* errore */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# esempio
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----------------------------------------

weechat_upgrade_read
^^^^^^^^^^^^^^^^^^^^

Legge un file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file,
                          int (*callback_read)(void *data,
                                               struct t_upgrade_file *upgrade_file,
                                               int object_id,
                                               struct t_infolist *infolist),
                          void *callback_read_data);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento
* 'callback_read': funzione chiamata per ogni oggetto letto nel file
  di aggiornamento
* 'callback_read_data': puntatore assegnato per la lettura della chiamata
  quando chiamato da WeeChat

Valore restituito:

* 1 se ok, 0 se errore

Esempio in C:

[source,C]
----------------------------------------
int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
                    int object_id,
                    struct t_infolist *infolist)
{
    /* read variables... */
    return WEECHAT_RC_OK;
}

weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)

# esempio
def my_upgrade_read_cb(upgrade_file, object_id, infolist):
    # read variables...
    return weechat.WEECHAT_RC_OK

weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
----------------------------------------

weechat_upgrade_close
^^^^^^^^^^^^^^^^^^^^^

Chiude un file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento

Esempio in C:

[source,C]
----------------------------------------
weechat_upgrade_close (upgrade_file);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.upgrade_close(upgrade_file)

# esempio
weechat.upgrade_close(upgrade_file)
----------------------------------------