File: weechat_plugin_api.it.adoc

package info (click to toggle)
weechat 4.7.2-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 29,364 kB
sloc: ansic: 227,998; cpp: 42,983; python: 2,381; sh: 274; php: 223; makefile: 16
file content (20992 lines) | stat: -rw-r--r-- 545,223 bytes
// SPDX-FileCopyrightText: 2003-2025 Sébastien Helleu <flashcode@flashtux.org>
// SPDX-FileCopyrightText: 2010-2012 Marco Paolone <marcopaolone@gmail.com>
//
// SPDX-License-Identifier: GPL-3.0-or-later

= Referenze API per Plugin di WeeChat
:author: Sébastien Helleu
:email: flashcode@flashtux.org
:lang: it
include::includes/attributes-it.adoc[]

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

// TRANSLATION MISSING
Latest version of this document can be found on
https://weechat.org/doc/[this page ^↗^^].

[[introduction]]
== Introduzione

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

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

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

// TRANSLATION MISSING
In order to call WeeChat functions in the format displayed in <<plugin_api>>,
the following global pointer must be declared and initialized in the function
<<_weechat_plugin_init,weechat_plugin_init>>:

[source,c]
----
struct t_weechat_plugin *weechat_plugin;
----

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

// TRANSLATION MISSING
WEECHAT_PLUGIN_AUTHOR("author")::
    the author name

WEECHAT_PLUGIN_VERSION("1.0")::
    versione del plugin

WEECHAT_PLUGIN_LICENSE("GPL3")::
    licenza del plugin

// TRANSLATION MISSING
WEECHAT_PLUGIN_PRIORITY(1000)::
    the plugin priority (optional, see below)

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

// TRANSLATION MISSING
* _plugin_: puntatore alla struttura del plugin di WeeChat, used to initialize
  the convenience global pointer `+weechat_plugin+`
* _argc_: numero di argomenti per il plugin
// TRANSLATION MISSING
* _argv_: argomenti per il plugin (see below)

Valori restituiti:

* _WEECHAT_RC_OK_ se l'operazione ha successo (il plugin
  verrà caricato)
* _WEECHAT_RC_ERROR_ se c'è un errore (il plugin NON
  verrà caricato)

// TRANSLATION MISSING
[[plugin_arguments]]
===== Plugin arguments

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

The arguments can be:

* command line arguments when running the WeeChat binary,
* arguments given to the command `/plugin load xxx`, when the plugin is manually
  loaded by the user.

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

*-a*, *--no-connect*::
    Disabilita la connessione automatica ai server all'avvio di WeeChat.

*-s*, *--no-script*::
    Disabilita il caricamento automatico dei script.

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

// TRANSLATION MISSING
[[plugin_priority]]
===== Plugin priority

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

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

The default WeeChat plugins are initialized in this order:

include::{autogendir}/autogen_api_plugins_priority.it.adoc[tag=plugins_priority]

==== weechat_plugin_end

Questa funzione viene chiamata quando il plugin viene
scaricato 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):

[source,shell]
----
gcc -fPIC -Wall -c tizio.c
gcc -shared -fPIC -o tizio.so tizio.o
----

[[load_plugin]]
=== Caricamento del plugin

Copiare il file _tizio.so_ nella cartella plugin di sistema (ad
esempio _/usr/local/lib/weechat/plugins_) oppure nella cartella
plugin dell'utente (ad esempio _/home/user/.local/share/weechat/plugins_).

In WeeChat:

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

[[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("Sébastien Helleu <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


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

int
command_double_cb (const void *pointer, void *data,
                   struct t_gui_buffer *buffer,
                   int argc, char **argv, char **argv_eol)
{
    /* fa felice il compilatore C */
    (void) pointer;
    (void) data;
    (void) buffer;
    (void) argv;

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

    return WEECHAT_RC_OK;
}

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

    weechat_hook_command ("double",
                          "Visualizza due volte un messaggio "
                          "oppure esegue un comando due volte",
                          "messaggio | comando",
                          "messaggio: messaggio da visualizzare due volte\n"
                          "comando: comando da eseguire due volte",
                          NULL,
                          &command_double_cb, NULL, NULL);

    return WEECHAT_RC_OK;
}

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

    return WEECHAT_RC_OK;
}
----

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

// TRANSLATION MISSING
[[registering]]
=== Registering

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

==== register

Register the script.

For more information, see the
link:weechat_scripting.it.html#register_function[WeeChat scripting guide ^↗^^].

Script (Python):

[source,python]
----
# prototipo
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...
----

[NOTE]
This function is not available in the C API.

[[plugins]]
=== Plugin

Funzioni per ottenere informazioni sui plugin.

==== 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
def plugin_get_name(plugin: str) -> str: ...

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

[[strings]]
=== Stringhe

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

==== charset_set

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

Prototipo:

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

Argomenti:

* _charset_: nuovo set caratteri da usare

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def charset_set(charset: str) -> int: ...

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

==== iconv_to_internal

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

Prototipo:

[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 ("iso-8859-1", "iso string: é à");
/* ... */
free (str);
----

Script (Python):

[source,python]
----
# prototipo
def iconv_to_internal(charset: str, string: str) -> str: ...

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

==== iconv_from_internal

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

Prototipo:

[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
def iconv_from_internal(charset: str, string: str) -> str: ...

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

==== gettext

Restituisce la stringa tradotta (dipende dalla lingua).

Prototipo:

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

Argomenti:

* _string_: stringa da tradurre

Valore restituito:

// TRANSLATION MISSING
* translated string or _string_ if there is no translation available in local language

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def gettext(string: str) -> str: ...

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

==== ngettext

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

Prototipo:

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

// TRANSLATION MISSING
* translated string or _string_ / _plural_ if there is no translation available
  in local language

Esempio in C:

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

Script (Python):

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

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

==== asprintf

_WeeChat ≥ 4.3.0._

// TRANSLATION MISSING
Format a message in a string allocated by the function.

// TRANSLATION MISSING
[NOTE]
This function is defined for systems where the GNU function `asprintf()`
is not available. +
The behavior is almost the same except that `*result` is set to NULL on error.

Prototipo:

[source,c]
----
int weechat_asprintf (char **result, const char *fmt, ...);
----

Argomenti:

// TRANSLATION MISSING
* _result_: pointer to a string pointer
// TRANSLATION MISSING
* _fmt_: format string

Valore restituito:

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

Esempio in C:

[source,c]
----
char *str;

if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
{
    /* *str == "test, 42" */
    /* ... */
    free (str);
}
else
{
    /* error: *str == NULL */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strndup

// TRANSLATION MISSING
Return duplicated string, with a max number of bytes.

Prototipo:

[source,c]
----
char *weechat_strndup (const char *string, int bytes);
----

Argomenti:

* _string_: stringa da duplicare
// TRANSLATION MISSING
* _bytes_: max bytes to duplicate

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== string_cut

_WeeChat ≥ 3.3._

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

Prototipo:

[source,c]
----
char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
----

Argomenti:

* _string_: string to cut
* _length_: max chars
* _count_suffix_: if 1, the length of suffix is counted in the max length
* _screen_: if 1, the cut is based on width of chars displayed
* _cut_suffix_: the suffix added after the string if it is cut

Valore restituito:

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

Esempio in C:

[source,c]
----
char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
/* ... */
free (str);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_tolower

// TRANSLATION MISSING
_Updated in 3.8._

// TRANSLATION MISSING
Return a string with uppercase letters converted to lowercase.

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

Prototipo:

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

Argomenti:

* _string_: stringa da convertire

Valore restituito:

// TRANSLATION MISSING
* string with lowercase letters (must be freed by calling "free" after use)

Esempio in C:

[source,c]
----
char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_é" */
/* ... */
free (str);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_toupper

// TRANSLATION MISSING
_Updated in 3.8._

// TRANSLATION MISSING
Return a string with lowercase letters converted to uppercase.

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

Prototipo:

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

Argomenti:

* _string_: stringa da convertire

Valore restituito:

// TRANSLATION MISSING
* string with uppercase letters (must be freed by calling "free" after use)

Esempio in C:

[source,c]
----
char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_É" */
/* ... */
free (str);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_charcmp

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

Confronta due caratteri.

Prototipo:

[source,c]
----
int weechat_string_charcmp (const char *string1, const char *string2);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the first UTF-8 char in _string2_
  from the first UTF-8 char in _string1_:
// TRANSLATION MISSING
** < 0 if char1 < char2
** 0 if char1 == char2
** > 0 if char1 > char2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_charcasecmp

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

Confronta due caratteri, ignorando la sensibilità alle maiuscole.

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8: now all uppercase letters are properly
converted to lowercase (by calling function `towlower`), in addition to the
range `A` to `Z`.

Prototipo:

[source,c]
----
int weechat_string_charcasecmp (const char *string1, const char *string2);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the first UTF-8 char in _string2_
  (converted to lowercase) from the first UTF-8 char in _string1_ (converted to
  lowercase):
// TRANSLATION MISSING
** < 0 if char1 < char2
** 0 if char1 == char2
** > 0 if char1 > char2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strcmp

// TRANSLATION MISSING
_WeeChat ≥ 3.8._

// TRANSLATION MISSING
Case-sensitive string comparison.

Prototipo:

[source,c]
----
int weechat_strcmp (const char *string1, const char *string2);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ from the last compared UTF-8 char in _string1_:
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strncmp

// TRANSLATION MISSING
_WeeChat ≥ 3.8._

// TRANSLATION MISSING
Case-sensitive string comparison, for _max_ chars.

Prototipo:

[source,c]
----
int weechat_strncmp (const char *string1, const char *string2, int max);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare
* _max_: numero massimo di caratteri da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ from the last compared UTF-8 char in _string1_:
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strcasecmp

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

// TRANSLATION MISSING
Case-insensitive string comparison.

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8: now all uppercase letters are properly
converted to lowercase (by calling function `towlower`), in addition to the
range `A` to `Z`.

Prototipo:

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

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ (converted to lowercase) from the last compared UTF-8 char in _string1_
  (converted to lowercase):
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strcasecmp_range

// TRANSLATION MISSING
_WeeChat ≥ 0.3.7, updated in 1.0, 3.8._

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

Prototipo:

[source,c]
----
int weechat_strcasecmp_range (const char *string1, const char *string2, int range);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare
* _range_: numero di caratteri nel confronto maiuscole/minuscole, ad esempio:
** 26: `+A-Z+` vengono ridotti ad `+a-z+`
** 29: `+A-Z [ \ ]+` vengono ridotti ad `+a-z { | }+`
** 30: `+A-Z [ \ ] ^+` vengono ridotti ad `+a-z { | } ~+`

[NOTE]
I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ (converted to lowercase) from the last compared UTF-8 char in _string1_
  (converted to lowercase):
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strncasecmp

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

// TRANSLATION MISSING
Case-insensitive string comparison, for _max_ chars.

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8: now all uppercase letters are properly
converted to lowercase (by calling function `towlower`), in addition to the
range `A` to `Z`.

Prototipo:

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

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare
* _max_: numero massimo di caratteri da comparare

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ (converted to lowercase) from the last compared UTF-8 char in _string1_
  (converted to lowercase):
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strncasecmp_range

// TRANSLATION MISSING
_WeeChat ≥ 0.3.7, updated in 1.0, 3.8._

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

Prototipo:

[source,c]
----
int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);
----

Argomenti:

* _string1_: prima stringa da comparare
* _string2_: seconda stringa da comparare
* _max_: numero massimo di caratteri da comparare
* _range_: numero di caratteri nel confronto maiuscole/minuscole, ad esempio:
** 26: `+A-Z+` vengono ridotti ad `+a-z+`
** 29: `+A-Z [ \ ]+` vengono ridotti ad `+a-z { | }+`
** 30: `+A-Z [ \ ] ^+` vengono ridotti ad `+a-z { | } ~+`

[NOTE]
I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ (converted to lowercase) from the last compared UTF-8 char in _string1_
  (converted to lowercase):
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strcmp_ignore_chars

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

// TRANSLATION MISSING
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_: prima stringa per il confronto
* _string2_: seconda stringa per il confronto
* _chars_ignored_: stringa con caratteri da ignorare
* _case_sensitive_: 1 per il confronto sensibile alle maiuscole, altrimenti 0

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8 when _case_sensitive_ is set to 0: now all
uppercase letters are properly converted to lowercase (by calling function
`towlower`), in addition to the range `A` to `Z`.

// TRANSLATION MISSING
Return value:

* arithmetic result of subtracting the last compared UTF-8 char in
  _string2_ (converted to lowercase if _case_sensitive_ is set to 0) from the last
  compared UTF-8 char in _string1_ (converted to lowercase if _case_sensitive_ is
  set to 0):
// TRANSLATION MISSING
** < 0 if string1 < string2
** 0 if string1 == string2
** > 0 if string1 > string2

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strcasestr

// TRANSLATION MISSING
_Updated in 1.3, 3.8._

// TRANSLATION MISSING
Case-insensitive string search.

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8: now all uppercase letters are properly
converted to lowercase (by calling function `towlower`), in addition to the
range `A` to `Z`.

Prototipo:

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

Argomenti:

* _string_: stringa
* _search_: stringa da cercare in _string_

Valore restituito:

// TRANSLATION MISSING
* puntatore alla stringa trovata, o NULL se non trovata
  (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== strlen_screen

// TRANSLATION MISSING
_WeeChat ≥ 0.4.2, updated in 3.8._

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

// TRANSLATION MISSING
WeeChat color codes are skipped and don't count in the result (this is the only
difference with the function <<_utf8_strlen_screen,utf8_strlen_screen>>).

Prototipo:

[source,c]
----
int weechat_strlen_screen (const char *string);
----

Argomenti:

* _string_: stringa

Valore restituito:

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

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def strlen_screen(string: str) -> int: ...

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

==== string_match

// TRANSLATION MISSING
_Updated in 1.0, 3.8._

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
// TRANSLATION MISSING
* _mask_: mask with wildcards (`+*+`), each wildcard matches 0 or more chars in
  the string
* _case_sensitive_: 1 per il confronto sensibile alle maiuscole, altrimenti 0

// TRANSLATION MISSING
[NOTE]
Since version 1.0, wildcards are allowed inside the mask
(not only beginning/end of mask).

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8 when _case_sensitive_ is set to 0: now all
uppercase letters are properly converted to lowercase (by calling function
`towlower`), in addition to the range `A` to `Z`.

Valore restituito:

* 1 se la stringa coincide alla mask, altrimenti 0

Esempio in C:

[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 */
int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */
----

Script (Python):

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

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

==== string_match_list

// TRANSLATION MISSING
_WeeChat ≥ 2.5, updated in 3.8._

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

Prototipo:

[source,c]
----
int weechat_string_match_list (const char *string, const char **masks,
                               int case_sensitive);
----

Argomenti:

// TRANSLATION MISSING
* _string_: string
* _masks_: list of masks, with a NULL after the last mask in list; each mask
  is compared to the string with the function <<_string_match,string_match>>
* _case_sensitive_: 1 for case-sensitive comparison, otherwise 0

// TRANSLATION MISSING
[NOTE]
Behavior has changed in version 3.8 when _case_sensitive_ is set to 0: now all
uppercase letters are properly converted to lowercase (by calling function
`towlower`), in addition to the range `A` to `Z`.

Valore restituito:

// TRANSLATION MISSING
* 1 if string matches list of masks (at least one mask matches and no negative
  mask matches), otherwise 0

Esempio in C:

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

Script (Python):

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

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

==== string_expand_home

_WeeChat ≥ 0.3.3._

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

Prototipo:

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

Argomenti:

* _path_: percorso

Valore restituito:

* percorso con la `+~+` iniziale sostituita dalla cartella home (deve essere
  liberata chiamando "free" dopo l'uso)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_eval_path_home

_WeeChat ≥ 1.3, updated in 3.2._

// TRANSLATION MISSING
Evaluate a path in 3 steps:

. replace leading `%h` by a WeeChat directory (data by default),
. replace leading `+~+` by user home directory (call to
  <<_string_expand_home,string_expand_home>>),
. evaluate variables (see <<_string_eval_expression,string_eval_expression>>).

Prototipo:

[source,c]
----
char *weechat_string_eval_path_home (const char *path,
                                     struct t_hashtable *pointers,
                                     struct t_hashtable *extra_vars,
                                     struct t_hashtable *options);
----

// TRANSLATION MISSING
Argomenti:

* _path_: path
* _pointers_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>
* _extra_vars_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>
* _options_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>, with one extra key
  supported:
** _directory_: WeeChat directory to use when replacing `%h`, one of:
*** _config_
*** _data_ (default)
*** _cache_
*** _runtime_

// TRANSLATION MISSING
Valore restituito:

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

Esempio in C:

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

Script (Python):

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

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

==== string_remove_quotes

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

Prototipo:

[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, " 'Non posso' ", "'");
/* risultato: "Non posso" */
/* ... */
free (str);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_strip

Rimuove i caratteri ad 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);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_convert_escaped_chars

_WeeChat ≥ 1.0._

// TRANSLATION MISSING
Convert escaped chars to their value:

* `+\"+`: double quote
* `+\\+`: backslash
* `+\a+`: alert (BEL)
* `+\b+`: backspace
* `+\e+`: escape
* `+\f+`: form feed
* `+\n+`: new line
* `+\r+`: carriage return
* `+\t+`: horizontal tab
* `+\v+`: vertical tab
* `+\0ooo+`: char as octal value (`ooo` is 0 to 3 digits)
* `+\xhh+`: char as hexadecimal value (`hh` is 1 to 2 digits)
* `+\uhhhh+`: unicode char as hexadecimal value (`hhhh` is 1 to 4 digits)
* `+\Uhhhhhhhh+`: unicode char as hexadecimal value (`hhhhhhhh` is 1 to 8 digits)

Prototipo:

[source,c]
----
char *weechat_string_convert_escaped_chars (const char *string);
----

Argomenti:

* _string_: stringa

Valore restituito:

// TRANSLATION MISSING
* string with escaped chars replaced by their value (deve essere liberata
  chiamando "free" dopo l'uso)

Esempio in C:

[source,c]
----
char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
/* str == "snowman: ☃" */
/* ... */
free (str);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_mask_to_regex

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

Prototipo:

[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
def string_mask_to_regex(mask: str) -> str: ...

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

==== string_regex_flags

_WeeChat ≥ 0.3.7._

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

Prototipo:

[source,c]
----
const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)
----

Argomenti:

// TRANSLATION MISSING
* _regex_: POSIX extended regular expression
* _default_flags_: combinazione dei seguenti valori (consultare `man regcomp`):
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB
// TRANSLATION MISSING
* _flags_: pointer value is set with flags used in regular expression (default
  flags + flags set in regular expression)

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

// TRANSLATION MISSING
Allowed flags are:

// TRANSLATION MISSING
* _e_: POSIX extended regular expression (_REG_EXTENDED_)
* _i_: case-insensitive (_REG_ICASE_)
* _n_: match-any-character operators don_t match a newline (_REG_NEWLINE_)
* _s_: support for substring addressing of matches is not required (_REG_NOSUB_)

Valore restituito:

// TRANSLATION MISSING
* pointer in _regex_, after flags

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_regcomp

_WeeChat ≥ 0.3.7._

// TRANSLATION MISSING
Compile a POSIX extended regular expression using optional flags at beginning
of string (for format of flags, see
<<_string_regex_flags,string_regex_flags>>).

Prototipo:

[source,c]
----
int weechat_string_regcomp (void *preg, const char *regex, int default_flags)
----

Argomenti:

// TRANSLATION MISSING
* _preg_: pointer to _regex_t_ structure
* _regex_: POSIX extended regular expression
* _default_flags_: combination of following values (see `man regcomp`):
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB

Valore restituito:

// TRANSLATION MISSING
* same return code as function `regcomp` (0 if ok, other value for error,
  see `man regcomp`)

[NOTE]
// TRANSLATION MISSING
Regular expression _preg_ must be cleaned by calling "regfree" after use,
if the function returned 0 (OK).

Esempio in C:

[source,c]
----
regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
{
    /* OK */
    /* ... */
    regfree (&my_regex);
}
else
{
    /* error */
    /* ... */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_has_highlight

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

Prototipo:

[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
def string_has_highlight(string: str, highlight_words: str) -> int: ...

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

==== string_has_highlight_regex

_WeeChat ≥ 0.3.4._

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

Prototipo:

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

Argomenti:

* _string_: stringa
// TRANSLATION MISSING
* _regex_: POSIX extended regular expression

Valore restituito:

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

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def string_has_highlight_regex(string: str, regex: str) -> int: ...

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

==== string_replace

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

Prototipo:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_replace_regex

_WeeChat ≥ 1.0._

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

Prototipo:

[source,c]
----
char *weechat_string_replace_regex (const char *string, void *regex,
                                    const char *replace, const char reference_char,
                                    char *(*callback)(void *data, const char *text),
                                    void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _string_: string
* _regex_: pointer to a regular expression (_regex_t_ structure) compiled with
  WeeChat function <<_string_regcomp,string_regcomp>> or regcomp
  (see `man regcomp`)
* _replace_: replacement text, where following references are allowed:
** `+$0+` to `+$99+`: match 0 to 99 in regular expression (0 is the whole match,
   1 to 99 are groups captured between parentheses)
** `+$++`: the last match (with highest number)
** `+$.*N+`: match `+N+` (can be `+++` or `+0+` to `+99+`), with all chars
   replaced by `+*+` (the `+*+` char can be any char between space (32) and
   `+~+` (126))
* _reference_char_: the char used for reference to match (commonly `+$+`)
* _callback_: an optional callback called for each reference in _replace_
  (except for matches replaced by a char); the callback must return:
** newly allocated string: it is used as replacement text (it is freed after
   use)
** NULL: the text received in callback is used as replacement text (without
   changes)
* _callback_data_: pointer given to callback when it is called

Valore restituito:

// TRANSLATION MISSING
* string with text replaced, NULL if problem (must be freed by calling "free"
  after use)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_translate_chars

_WeeChat ≥ 3.8._

// TRANSLATION MISSING
Translate chars in a string.

Prototipo:

[source,c]
----
char *string_translate_chars (const char *string, const char *chars1, const char *chars2);
----

Argomenti:

// TRANSLATION MISSING
* _string_: string
* _chars1_: string with chars to translate
* _chars2_: string with replacement chars; it must contain the same number of
  UTF-8 chars than _chars1_

Valore restituito:

// TRANSLATION MISSING
* string with translated chars, NULL if problem (must be freed by calling "free"
  after use)

Esempi in C:

[source,c]
----
/* "test" => "tEst" */
char *str = weechat_string_translate_chars ("test", "abcdef", "ABCDEF");

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_split

// TRANSLATION MISSING
_Updated in 2.5, 2.6._

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

Prototipo:

[source,c]
----
char **weechat_string_split (const char *string, const char *separators,
                             const char *strip_items, int flags,
                             int num_items_max, int *num_items);
----

Argomenti:

* _string_: stringa da dividere
* _separators_: delimitatori usati per dividere
// TRANSLATION MISSING
* _strip_items_: chars to strip from returned items (left/right);
  optional, can be NULL
* _flags_: combination values to change the default behavior; if the value is 0,
  the default behavior is used (no strip of separators at beginning/end of string,
  multiple separators are kept as-is so empty strings can be returned);
  the following flags are accepted:
** WEECHAT_STRING_SPLIT_STRIP_LEFT: strip separators on the left
   (beginning of string)
** WEECHAT_STRING_SPLIT_STRIP_RIGHT: strip separators on the right
   (end of string)
** WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: collapse multiple consecutive separators
   into a single one
** WEECHAT_STRING_SPLIT_KEEP_EOL: keep end of line for each value
* _num_items_max_: numero massimo di elementi creati (0 = nessun limite)
* _num_items_: puntatore ad int che conterrà il numero di elementi creati

// TRANSLATION MISSING
[NOTE]
With WeeChat ≤ 2.4, the _flags_ argument was called _keep_eol_ and took other
values, which must be converted like that:
[width="100%",cols="1,10",options="header"]
|===
| keep_eol | flags
| 0        | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
| 1        | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
| 2        | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
|===

Valore restituito:

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

Esempi:

[source,c]
----
char **argv;
int argc;

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

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

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

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

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_split_shell

_WeeChat ≥ 1.0._

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

// TRANSLATION MISSING
This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in
Python repository), see
https://docs.python.org/3/library/shlex.html[this page ^↗^^].

Prototipo:

[source,c]
----
char **weechat_string_split_shell (const char *string, int *num_items);
----

Argomenti:

* _string_: stringa da dividere
* _num_items_: puntatore ad int che conterrà il numero di elementi creati

Valore restituito:

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

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 <<_string_split,string_split>>

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_rebuild_split_string

// TRANSLATION MISSING
_Updated in 3.7._

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

Prototipo:

[source,c]
----
char *weechat_string_rebuild_split_string (char **split_string,
                                           const char *separator,
                                           int index_start, int index_end);
----

Argomenti:

* _split_string_: stringa divisa dalla funzione <<_string_split,string_split>>
// TRANSLATION MISSING
* _separator_: string used to separate strings (can be NULL or empty string)
// TRANSLATION MISSING
* _index_start_: index of first string to use (≥ 0)
// TRANSLATION MISSING
* _index_end_: index of last string to use
  (must be ≥ _index_start_; special value -1 can be used to use all arguments
  until NULL is found)

Valore restituito:

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

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_split_command

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

Prototipo:

[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
  <<_string_free_split_command,string_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"
           argv[2] == NULL
*/
weechat_free_split_command (argv);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 <<_string_split_command,string_split_command>>

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_format_size

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

Prototipo:

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

Argomenti:

* _size_: dimensione (in byte)

Valore restituito:

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

Esempi in C:

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

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

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

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

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

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

Script (Python), _WeeChat ≥ 2.2_:

[source,python]
----
# prototipo
def string_format_size(size: int) -> str: ...

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

// TRANSLATION MISSING
==== string_parse_size

_WeeChat ≥ 3.7._

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

Prototipo:

[source,c]
----
unsigned long long weechat_string_parse_size (const char *size);
----

Argomenti:

* _size_: the size as string: positive integer number followed by optional
  spaces and optional unit (lower or upper case), which is one of:
** _b_: bytes
** _k_: kilobytes (1k = 1000 bytes)
** _m_: megabytes (1m = 1000k = 1,000,000 bytes)
** _g_: gigabytes (1g = 1000m = 1,000,000,000 bytes)
** _t_: terabytes (1t = 1000g = 1,000,000,000,000 bytes)

Valore restituito:

* size in bytes, 0 if error

Esempio in C:

[source,c]
----
unsigned long long size = weechat_parse_size ("1.34m");  /* size == 1340000 */
----

Script (Python):

[source,python]
----
# prototipo
def string_parse_size(size: str) -> int: ...

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

==== string_color_code_size

_WeeChat ≥ 3.0._

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

Prototipo:

[source,c]
----
int weechat_string_color_code_size (const char *string);
----

Argomenti:

* _string_: stringa

Valore restituito:

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

Esempi:

[source,c]
----
int size;

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

Script (Python):

[source,python]
----
# prototipo
def string_color_code_size(string: str) -> int: ...

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

==== string_remove_color

// TRANSLATION MISSING
_Updated in 4.3.0._

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
// TRANSLATION MISSING
* _replacement_: if not NULL and not empty, WeeChat color codes are replaced by
  this string, otherwise WeeChat color codes and following chars (if related
  to color) are removed from string

Valore restituito:

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

Esempi:

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

Script (Python):

[source,python]
----
# prototipo
def string_remove_color(string: str, replacement: str) -> str: ...

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

==== string_base_encode

_WeeChat ≥ 2.4, updated in 4.3.0._

// TRANSLATION MISSING
Encode a string in base 16, 32, or 64.

Prototipo:

[source,c]
----
int weechat_string_base_encode (const char *base, const char *from, int length, char *to);
----

Argomenti:

// TRANSLATION MISSING
* _base_: "16", "32", "64", or "64url"
* _from_: stringa da codificare
* _length_: lunghezza della stringa da codificare (ad esempio `strlen(from)`)
* _to_: puntatore alla stringa per memorizzare il risultato (deve essere
  sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Valore restituito:

// TRANSLATION MISSING
* lunghezza della stringa memorizzata in _*to_ (lo `\0` finale non conta),
  -1 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_base_decode

_WeeChat ≥ 2.4, updated in 4.3.0._

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

Prototipo:

[source,c]
----
int weechat_string_base_decode (const char *base, const char *from, char *to);
----

Argomenti:

// TRANSLATION MISSING
* _base_: "16", "32", "64" or "64url"
* _from_: stringa da decodificare
* _to_: puntatore alla stringa per memorizzare il risultato (deve essere
  sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Valore restituito:

// TRANSLATION MISSING
* lunghezza della stringa memorizzata in _*to_ (lo `\0` finale non conta),
  -1 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_hex_dump

_WeeChat ≥ 1.4._

// TRANSLATION MISSING
Display a dump of data as hexadecimal and ascii bytes.

Prototipo:

[source,c]
----
char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                       const char *prefix, const char *suffix);
----

Argomenti:

// TRANSLATION MISSING
* _data_: the data to dump
* _data_size_: number of bytes to dump in _data_
* _bytes_per_line_: number of bytes to display in each line
* _prefix_: the prefix to display at the beginning of each line
  (optional, can be NULL)
* _suffix_: the suffix to display at the end of each line
  (optional, can be NULL)

Valore restituito:

// TRANSLATION MISSING
* string with dump of data (must be freed by calling "free" after use)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_is_command_char

_WeeChat ≥ 0.3.2._

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

Prototipo:

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

Argomenti:

* _string_: stringa

Valore restituito:

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

Esempi in C:

[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]
----
# prototipo
def string_is_command_char(string: str) -> int: ...

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

==== string_input_for_buffer

_WeeChat ≥ 0.3.2._

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

Prototipo:

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

Argomenti:

* _string_: stringa

Valore restituito:

* puntatore all'interno di "string", oppure NULL

Esempi in C:

[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]
----
# prototipo
def string_input_for_buffer(string: str) -> str: ...

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

// TRANSLATION MISSING
==== string_eval_expression

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

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

[NOTE]
Since version 1.0, nested variables are supported, for example:
`+${color:${variable}}+`.

Prototipo:

[source,c]
----
char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);
----

Argomenti:

* _expr_: the expression to evaluate (see <<eval_conditions,conditions>> and
  <<eval_variables,variables>>)
* _pointers_: hashtable with pointers (keys must be string, values must be
  pointer); pointers "window" and "buffer" are automatically added if they are
  not in hashtable (with pointer to current window/buffer) (can be NULL):
** _regex_: pointer to a regular expression (_regex_t_ structure) compiled with
   WeeChat function <<_string_regcomp,string_regcomp>> or regcomp (see `man regcomp`);
   this option is similar to _regex_ in hashtable _options_ (below),
   but is used for better performance
* _extra_vars_: extra variables that will be expanded (can be NULL)
* _options_: a hashtable with some options (keys and values must be string)
  (can be NULL):
** _type_: default behavior is just to replace values in expression, other
   types can be selected:
*** _condition_: the expression is evaluated as a condition: operators and
    parentheses are used, result is a boolean ("0" or "1")
** _prefix_: prefix before variables to replace (default: `+${+`)
** _suffix_: suffix after variables to replace (default: `+}+`)
** _extra_: default behavior is to just replace extra variables (_extra_vars_),
   other behavior can be selected:
*** _eval_: extra variables (_extra_vars_) are evaluated themselves before
    replacing _(WeeChat ≥ 1.6)_
** _regex_: a regex used to replace text in _expr_ (which is then not
   evaluated)
** _regex_replace_: the replacement text to use with _regex_, to replace
   text in _expr_ (the _regex_replace_ is evaluated on each match of _regex_
   against _expr_, until no match is found)
** _debug_: debug level (string with integer number ≥ 1), if enabled, a key
   "debug_output" is added in hashtable _options_:
*** _1_: enable debug
*** _2_: enable more verbose debug

Valore restituito:

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

Esempi in C:

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

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

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

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

Script (Python):

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

# esempi

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

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

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

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

[[eval_conditions]]
===== Conditions

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

[width="100%",cols="2,1,5,5",options="header"]
|===
| Operator | Min WeeChat | Description | Examples

| `+&&+` |
| Logical "and"
| >> `+25 && 77+` +
  == `+1+` +
  +
  >> `+25 && 0+` +
  == `+0+`

| `+\|\|+` |
| Logical "or"
| >> `+25 \|\| 0+` +
  == `+1+` +
  +
  >> `+0 \|\| 0+` +
  == `+0+`
|===

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

[width="100%",cols="2,1,5,5",options="header"]
|===
| Operator | Min WeeChat | Description | Examples

| `+=~+` |
| Is matching POSIX extended regex (optional flags are allowed, see function <<_string_regcomp,string_regcomp>>)
| >> `+abc def =~ ab.*ef+` +
  == `+1+` +
  +
  >> `+abc def =~ y.*z+` +
  == `+0+`

| `+!~+` |
| Is NOT matching POSIX extended regex (optional flags are allowed, see function <<_string_regcomp,string_regcomp>>)
| >> `+abc def !~ ab.*ef+` +
  == `+0+` +
  +
  >> `+abc def !~ y.*z+` +
  == `+1+`

| `+==*+` | 2.9
| Is matching mask where "*" is allowed, case-sensitive (see function <<_string_match,string_match>>)
| >> `+abc def ==* a*f+` +
  == `+1+` +
  +
  >> `+abc def ==* y*z+` +
  == `+0+`

| `+!!*+` | 2.9
| Is NOT wildcard mask where "*" is allowed, case-sensitive (see function <<_string_match,string_match>>)
| >> `+abc def !!* a*f+` +
  == `+0+` +
  +
  >> `+abc def !!* y*z+` +
  == `+1+`

| `+=*+` | 1.8
| Is matching mask where "*" is allowed, case-insensitive (see function <<_string_match,string_match>>)
| >> `+abc def =* A*F+` +
  == `+1+` +
  +
  >> `+abc def =* Y*Z+` +
  == `+0+`

| `+!*+` | 1.8
| Is NOT wildcard mask where "*" is allowed, case-insensitive (see function <<_string_match,string_match>>)
| >> `+abc def !* A*F+` +
  == `+0+` +
  +
  >> `+abc def !* Y*Z+` +
  == `+1+`

| `+==-+` | 2.9
| Is included, case-sensitive
| >> `+abc def ==- bc+` +
  == `+1+` +
  +
  >> `+abc def ==- xyz+` +
  == `+0+`

| `+!!-+` | 2.9
| Is NOT included, case-sensitive
| >> `+abc def !!- bc+` +
  == `+0+` +
  +
  >> `+abc def !!- xyz+` +
  == `+1+`

| `+=-+` | 2.9
| Is included, case-insensitive
| >> `+abc def =- BC+` +
  == `+1+` +
  +
  >> `+abc def =- XYZ+` +
  == `+0+`

| `+!-+` | 2.9
| Is NOT included, case-insensitive
| >> `+abc def !- BC+` +
  == `+0+` +
  +
  >> `+abc def !- XYZ+` +
  == `+1+`

| `+==+` |
| Equal
| >> `+test == test+` +
  == `+1+` +
  +
  >> `+test == string+` +
  == `+0+`

| `+!=+` |
| Not equal
| >> `+test != test+` +
  == `+0+` +
  +
  >> `+test != string+` +
  == `+1+`

| `+<=+` |
| Less or equal
| >> `+abc <= defghi+` +
  == `+1+` +
  +
  >> `+abc <= abc+` +
  == `+1+` +
  +
  >> `+defghi <= abc+` +
  == `+0+` +
  +
  >> `+15 <= 2+` +
  == `+0+`

| `+<+` |
| Less
| >> `+abc < defghi+` +
  == `+1+` +
  +
  >> `+abc < abc+` +
  == `+0+` +
  +
  >> `+defghi < abc+` +
  == `+0+` +
  +
  >> `+15 < 2+` +
  == `+0+`

| `+>=+` |
| Greater or equal
| >> `+defghi >= abc+` +
  == `+1+` +
  +
  >> `+abc >= abc+` +
  == `+1+` +
  +
  >> `+abc >= defghi+` +
  == `+0+` +
  +
  >> `+15 >= 2+` +
  == `+1+`

| `+>+` |
| Greater
| >> `+defghi > abc+` +
  == `+1+` +
  +
  >> `+abc > abc+` +
  == `+0+` +
  +
  >> `+abc > defghi+` +
  == `+0+` +
  +
  >> `+15 > 2+` +
  == `+1+`
|===

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

* integer (examples: 5, -7)
* floating point number (examples: 5.2, -7.5, 2.83e-2) _(WeeChat ≥ 2.0)_
* hexadecimal number (examples: 0xA3, -0xA3) _(WeeChat ≥ 2.0)_

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

* `50 > 100` returns 0 (number comparison)
* `"50" > "100"` returns 1 (string comparison)

[[eval_variables]]
===== Variables

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

[width="100%",cols="2,1,5,5",options="header"]
|===
| Format | Min WeeChat | Description | Examples

| `+${raw_hl:xxx}+` | 4.2.0
| Raw string (not evaluated), with syntax highlighting (using colors).
| >> `+${raw_hl:${cut:1,,${rev:hello}}}+` +
  == `+${cut:1,,${rev:hello}}+` (with colors)

| `+${raw:xxx}+` | 3.1
| Raw string (not evaluated).
| >> `+${raw:${info:version}}+` +
  == `+${info:version}+`

| `+${hl:xxx}+` | 4.2.0
| String with syntax highlighting (using colors).
| >> `+${hl:${file.section.option}}+` +
  == `+test ${variable}+` (with colors)

| `+${name}+` | 3.4
| User variable (defined with `+${define:name,value}+`).
| >> `+${name}+` +
  == `+value+`

| `+${name}+` |
| Variable `name` from hashtable _extra_vars_.
| >> `+${name}+` +
  == `+value+`

| `+${weechat_xxx_dir}+` | 3.2
| A WeeChat directory: `+${weechat_config_dir}+`, `+${weechat_data_dir}+`,
  `+${weechat_state_dir}+`, `+${weechat_cache_dir}+` or `+${weechat_runtime_dir}+`.
| >> `+${weechat_config_dir}+` +
  == `+/home/user/.config/weechat+` +
  +
  >> `+${weechat_data_dir}+` +
  == `+/home/user/.local/share/weechat+` +
  +
  >> `+${weechat_state_dir}+` +
  == `+/home/user/.local/state/weechat+` +
  +
  >> `+${weechat_cache_dir}+` +
  == `+/home/user/.cache/weechat+` +
  +
  >> `+${weechat_runtime_dir}+` +
  == `+/run/user/1000/weechat+`

| `+${eval:xxx}+` | 1.3
| String to evaluate.
| >> `+${eval:${date:${weechat.look.buffer_time_format}}}+` +
  == `+19:02:45+` ^(1)^ +
  +
  ^(1)^ With colors if there are color codes in the option
  weechat.look.buffer_time_format

| `+${eval_cond:xxx}+` | 3.1
| String to evaluate as condition.
| >> `+${eval_cond:${window.win_width} > 100}+` +
  == `+1+`

| `+${esc:xxx}+` +
  `+${\xxx}+` | 1.0
| String with escaped chars.
| >> `+${esc:prefix\tmessage}+` +
  == `+prefix<TAB>message+` +
  +
  >> `+${\ua9}+` +
  == `+©+`

| `+${chars:range}+` | 3.8
| String with a range of chars, where `range` is one of: +
  - `digit` (`0123456789`) +
  - `xdigit` (`0123456789abcdefABCDEF`) +
  - `lower` (all lower case letters) +
  - `upper` (all upper case letters) +
  - `alpha` (all letters) +
  - `alnum` (all letters and digits) +
  - a range of chars with format `c1-c2` (`c1` code point must be lower or equal to `c2`)
| >> `+${chars:digit}+` +
  == `+0123456789+` +
  +
  >> `+${chars:xdigit}+` +
  == `+0123456789abcdefABCDEF+` +
  +
  >> `+${chars:lower}+` +
  == `+abcdefghijklmnopqrstuvwxyz+` +
  +
  >> `+${chars:J-V}+` +
  == `+JKLMNOPQRSTUV+` +
  +
  >> `+${chars:←-↓}+` +
  == `+←↑→↓+`

| `+${lower:string}+` | 3.6
| String converted to lower case.
| >> `+${lower:TEST}+` +
  == `+test+`

| `+${upper:string}+` | 3.6
| String converted to upper case.
| >> `+${upper:test}+` +
  == `+TEST+`

| `+${hide:x,string}+` | 1.1
| String with hidden chars (all chars in `string` replaced `x`).
| >> `+${hide:*,password}+` +
  == `+********+`

| `+${cut:max,suffix,string}+` +
  `+${cut:+max,suffix,string}+` | 1.8
| String with `max` chars, and optional `suffix` if string is cut. +
  With the format `+max`, the suffix is counted in max length.
| >> `+${cut:4,…,this is a test}+` +
  == `+this…+` +
  +
  >> `+${cut:+4,…,this is a test}+` +
  == `+t…+` +
  +
  >> `+${cut:2,>>,こんにちは世界}+` +
  == `+こん>>+`

| `+${cutscr:max,suffix,string}+` +
  `+${cutscr:+max,suffix,string}+` | 1.8
| String with `max` chars displayed on screen, and optional `suffix` if string is cut. +
  With the format `+max`, the suffix is counted in max length.
| >> `+${cutscr:4,…,this is a test}+` +
  == `+this…+` +
  +
  >> `+${cutscr:+4,…,this is a test}+` +
  == `+thi…+` +
  +
  >> `+${cutscr:2,>>,こんにちは世界}+` +
  == `+こ>>+`

| `+${rev:xxx}+` | 2.2
| Reversed string (color codes are reversed, so the string should not contain
  color codes).
| >> `+${rev:Hello, world!}+` +
  == `+!dlrow ,olleH+` +
  +
  >> `+${rev:Hello, ${color:red}world!}+` +
  == `+!dlrow30F ,olleH+` ^(1)^ +
  +
  ^(1)^ No color, the color code is reversed

| `+${revscr:xxx}+` | 2.7
| Reversed string for screen, color codes are not reversed.
| >> `+${revscr:Hello, world!}+` +
  == `+!dlrow ,olleH+` +
  +
  >> `+${revscr:Hello, ${color:red}world!}+` +
  == `+!dlrow ,olleH+` ^(1)^ +
  +
  ^(1)^ `pass:[ ,olleH]` in red

| `+${repeat:count,string}+` | 2.3
| Repeated string.
| >> `+${repeat:5,-}+` +
  == `+-----+`

| `+${length:xxx}+` | 2.7
| Length of string (number of UTF-8 chars), color codes are ignored.
| >> `+${length:test}+` +
  == `+4+` +
  +
  >> `+${length:こんにちは世界}+` +
  == `+7+`

| `+${lengthscr:xxx}+` | 2.7
| Length of string displayed on screen, color codes are ignored.
| >> `+${lengthscr:test}+` +
  == `+4+` +
  +
  >> `+${lengthscr:こんにちは世界}+` +
  == `+14+`

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

| `+${split_shell:number,xxx}+` | 3.3
| Split shell arguments, and return, according to `number`: +
  - `count`: the number of arguments after split +
  - `random`: a random argument +
  - integer ≥ 1: the argument by index (1 = first argument) +
  - integer ≤ -1: the argument by index from the end (-1 = last argument, -2 = penultimate argument, etc.)
| >> `+${split_shell:1,"first arg" arg2}+` +
  == `+first arg+` +
  +
  >> `+${split_shell:-1,"first arg" arg2}+` +
  == `+arg2+` +
  +
  >> `+${split_shell:count,"first arg" arg2}+` +
  == `+2+` +
  +
  >> `+${split_shell:random,"first arg" arg2}+` +
  == `+arg2+`

| `+${re:xxx}+` | 1.1
| Regex data: +
  `0` = whole string matching, +
  `1` to `99` = group captured, +
  `+++` = last group captured, +
  `#` = index of last group captured _(WeeChat ≥ 1.8)_, +
  `repl_index` = index of replacement being done (starts to 1) _(WeeChat ≥ 3.3)_.
| >> `+${re:0}+` +
  == `+test1 test2+` +
  +
  >> `+${re:1}+` +
  == `+test1+` +
  +
  >> `+${re:2}+` +
  == `+test2+` +
  +
  >> `pass:[${re:+}]` +
  == `+test2+` +
  +
  >> `+${re:#}+` +
  == `+2+` +
  +
  >> `+${re:repl_index}+` +
  == `+1+`

| `+${color:name}+` | 0.4.2
| WeeChat color code (the name of color has optional attributes),
  see function <<_color,color>> for supported formats.
| >> `+${color:red}red text+` +
  == `+red text+` ^(1)^ +
  +
  >> `+${color:*214}bold orange text+` +
  == `+bold orange text+` ^(2)^ +
  +
  ^(1)^ In red +
  ^(2)^ In bold orange

| `+${modifier:name,data,string}+` | 2.7
| Result of a modifier, see function
  <<_hook_modifier_exec,hook_modifier_exec>>.
| >> `+${modifier:eval_path_home,,~}+` +
  == `+/home/user+` +
  +
  >> `+${modifier:eval_path_home,directory=config,%h/irc.conf}+` +
  == `+/home/user/.config/weechat/irc.conf+`

| `+${info:name}+` +
  `+${info:name,arguments}+` | 0.4.3
| Info from WeeChat or a plugin, see function <<_info_get,info_get>>.
| >> `+${info:version}+` +
  == `+1.0+` +
  +
  >> `+${info:nick_color_name,foo}+` +
  == `+lightblue+`

| `+${base_encode:base,xxx}+` | 2.9
| String encoded in base 16, 32 or 64.
| >> `+${base_encode:16,test string}+` +
  == `+7465737420737472696E67+` +
  +
  >> `+${base_encode:32,test string}+` +
  == `+ORSXG5BAON2HE2LOM4======+` +
  +
  >> `+${base_encode:64,test string}+` +
  == `+dGVzdCBzdHJpbmc=+`

| `+${base_decode:base,xxx}+` | 2.9
| String decoded from base 16, 32 or 64.
| >> `+${base_decode:16,7465737420737472696E67}+` +
  == `+test string+` +
  +
  >> `+${base_decode:32,ORSXG5BAON2HE2LOM4======}+` +
  == `+test string+` +
  +
  >> `+${base_decode:64,dGVzdCBzdHJpbmc=}+` +
  == `+test string+`

| `+${date}+` +
  `+${date:xxx}+` | 1.3
| Current date/time, with custom format (see function <<_util_strftimeval,util_strftimeval>>),
  default format is `%F %T`.
| >> `+${date}+` +
  == `+2015-06-30 19:02:45+` +
  +
  >> `+${date:%H:%M:%S}+` +
  == `+19:02:45+` +
  +
  >> `+${date:%!.%.3}+` +
  == `+1435683765.482+`

| `+${env:NAME}+` | 1.2
| Value of the environment variable `NAME`.
| >> `+${env:HOME}+` +
  == `+/home/user+`

| `+${if:condition}+` +
  `+${if:condition?true}+`
  `+${if:condition?true:false}+` | 1.8
| Ternary operator with a condition, a value if the condition is true (optional)
  and another value if the condition is false (optional). If values are not
  given, "1" or "0" are returned, according to the result of the condition.
| >> `+${if:${info:term_width}>80?big:small}+` +
  == `+big+`

| `+${calc:xxx}+` | 2.7
| Result of expression, where parentheses and the following operators are
  supported: +
  `+++`: addition +
  `+-+`: subtraction +
  `+*+`: multiplication +
  `+/+`: division +
  `+//+`: result of division without fractional part +
  `+%+`: remainder of division +
  `+**+`: power.
| >> `+${calc:5+2*3}+` +
  == `+11+` +
  +
  >> `+${calc:(5+2)*3}+` +
  == `+21+` +
  +
  >> `+${calc:10/4}+` +
  == `+2.5+` +
  +
  >> `+${calc:10//4}+` +
  == `+2+` +
  +
  >> `+${calc:9.2%3}+` +
  == `+0.2+` +
  +
  >> `+${calc:2**16}+` +
  == `+65536+`

| `+${random:min,max}+` | 3.3
| Random integer number in the range from `min` to `max` (inclusive).
| >> `+${random:0,10}+` +
  == `+3+`

| `+${translate:xxx}+` | 3.2
| Translated string (depends on the language used by WeeChat to display messages).
| >> `+${translate:Plugin}+` +
  == `+Extension+` ^(1)^ +
  +
  ^(1)^ Example in French

| `+${define:name,value}+` | 3.4
| Define a variable `name` set to `value`, which can then be used in the same
  evaluated expression with `+${name}+`.
| >> `+${define:len,${calc:5+3}}${len}x${len}+` +
  == `+8x8+`

| `+${hdata_count:name[list]}+` +
  `+${hdata_count:name[pointer]}+` | 4.4.0
| Number of items in a hdata list or starting at `pointer`.
| >> `+${hdata_count:buffer[gui_buffers]}+` +
  == `+15+`

| `+${sec.data.name}+` |
| Value of the secured data `name`.
| >> `+${sec.data.libera_pass}+` +
  == `+my_password+`

| `+${file.section.option}+` |
| Value of the option.
| >> `+${weechat.look.buffer_time_format}+` +
  == `+%H:%M:%S+`

| `+${name}+` |
| Value of local variable `name` in buffer.
| >> `+${nick}+` +
  == `+FlashCode+`

| `+${pointer}+` |
| Variable `pointer` from hashtable _pointers_.
| >> `+${buffer}+` +
  == `+0x1234abcd+`

| `+${hdata.var1.var2...}+` +
  `+${hdata[list].var1.var2...}+` |
| Hdata value (pointers `window` and `buffer` are set by default with current
  window/buffer), `list` can be a list name (example: "gui_buffers"), a pointer
  (example: "0x1234abcd") or a pointer name (example: "my_pointer"). +
  When `var1` is a hashtable, methods `keys()`, `values()`, `keys_sorted()`,
  `keys_values()` and `keys_values_sorted()` can be called.
| >> `+${buffer[gui_buffers].full_name}+` +
  == `+core.weechat+` +
  +
  >> `+${buffer[my_buffer_pointer].full_name}+` +
  == `+core.weechat+` +
  +
  >> `+${window.buffer.number}+` +
  == `+1+` +
  +
  >> `+${buffer.local_variables.keys_values()}+` +
  == `+plugin:core,name:weechat+` +
  +
  >> `+${buffer.local_variables.plugin}+` +
  == `+core+`
|===

==== string_dyn_alloc

_WeeChat ≥ 1.8._

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

// TRANSLATION MISSING
Only the pointer to string pointer (_**string_) is used in all the
_pass:[string_dyn_*]_ functions.

Prototipo:

[source,c]
----
char **weechat_string_dyn_alloc (int size_alloc);
----

Argomenti:

// TRANSLATION MISSING
* _size_alloc_: the initial allocated size (must be greater than zero)

Valore restituito:

// TRANSLATION MISSING
* pointer to the dynamic string

Esempio in C:

[source,c]
----
char **string = weechat_string_dyn_alloc (256);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_dyn_copy

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Copy a string in a dynamic string.

// TRANSLATION MISSING
The pointer _*string_ can change if the string is reallocated (if there is
not enough space to copy the string).

Prototipo:

[source,c]
----
int weechat_string_dyn_copy (char **string, const char *new_string);
----

Argomenti:

// TRANSLATION MISSING
* _string_: pointer to dynamic string
* _new_string_: the string to copy

Valore restituito:

// TRANSLATION MISSING
* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_dyn_concat

// TRANSLATION MISSING
_WeeChat ≥ 1.8, updated in 3.0._

// TRANSLATION MISSING
Concatenate a string to a dynamic string.

// TRANSLATION MISSING
The pointer _*string_ can change if the string is reallocated (if there is
not enough space to concatenate the string).

Prototipo:

[source,c]
----
int weechat_string_dyn_concat (char **string, const char *add, int bytes);
----

Argomenti:

// TRANSLATION MISSING
* _string_: pointer to dynamic string
* _add_: the string to add
* _bytes_: max number of bytes in _add_ to concatenate, must be lower or equal
  to length of _add_ (-1 = automatic: concatenate whole string _add_)
  _(WeeChat ≥ 3.0)_

Valore restituito:

// TRANSLATION MISSING
* 1 if OK, 0 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_dyn_free

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Free a dynamic string.

Prototipo:

[source,c]
----
char *weechat_string_dyn_free (char **string, int free_string);
----

Argomenti:

// TRANSLATION MISSING
* _string_: pointer to dynamic string
* _free_string_: free the string itself; if 0, the content of _*string_ remains
  valid after the call to this function

Valore restituito:

// TRANSLATION MISSING
* string pointer if _free_string_ is 0, otherwise NULL

Esempio in C:

[source,c]
----
char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_concat (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
/* ... */
weechat_string_dyn_free (string, 1);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== string_concat

_WeeChat ≥ 4.2.0._

// TRANSLATION MISSING
Concatenate multiple strings using a separator.

Prototipo:

[source,c]
----
const char *weechat_string_concat (const char *separator, ...);
----

Argomenti:

// TRANSLATION MISSING
* _separator_: the separator string which is inserted between concatenated
  strings (can be NULL or empty string)

// TRANSLATION MISSING
[NOTE]
Last argument *MUST* always be NULL. +
A macro called `WEECHAT_STR_CONCAT` can be used, where the final NULL value is
not needed (usage of this macro is recommended).

Valore restituito:

// TRANSLATION MISSING
* concatenated string

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
const char *result = weechat_string_concat (" / ", "abc", "def", "ghi", NULL);  /* result == "abc / def / ghi" */

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[utf-8]]
=== UTF-8

Alcune funzioni stringa UTF-8.

==== 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))
{
    /* ... */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_is_valid

// TRANSLATION MISSING
_Updated in 1.4._

Verifica che una stringa sia valida in UTF-8.

Prototipo:

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

Argomenti:

* _string_: stringa
// TRANSLATION MISSING
* _length_: max number of UTF-8 chars to check; if ≤ 0, the whole string is
  checked _(WeeChat ≥ 1.4)_
* _error_: se non NULL, _*error_ è impostato con il puntatore al primo
  carattere UTF-8 non valido nella stringa, se esiste

Valore restituito:

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

Esempio in C:

[source,c]
----
char *error;
if (weechat_utf8_is_valid (string, -1, &error))
{
    /* ... */
}
else
{
    /* "error" punta al primo carattere non valido */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_normalize

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

Prototipo:

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

Argomenti:

* _string_: stringa
* _replacement_: carattere sotitutivo per i caratteri non validi

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_prev_char

// TRANSLATION MISSING
_Updated in 1.3._

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

Prototipo:

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

Argomenti:

* _string_start_: inizio della stringa (la funzione non restituirà un carattere prima
  di questo puntatore)
* _string_: puntatore alla stringa (deve essere ≥ _string_start_)

Valore restituito:

// TRANSLATION MISSING
* puntatore al precedente carattere UTF-8, NULL se non trovata (raggiunta
  l'inizio della stringa)
  (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_next_char

// TRANSLATION MISSING
_Updated in 1.3._

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

Prototipo:

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

Argomenti:

* _string_: stringa

Valore restituito:

// TRANSLATION MISSING
* puntatore al carattere UTF-8 successivo, NULL se non trovato
  (raggiunta la fine della stringa)
  (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_char_int

Restituisce un carattere UTF-8 come intero.

Prototipo:

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

Argomenti:

* _string_: stringa

Valore restituito:

* carattere UTF-8 come intero

Esempio in C:

[source,c]
----
int char_int = weechat_utf8_char_int ("être");  /* "ê" come intero */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_strnlen

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

Prototipo:

[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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_strlen_screen

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

Prototipo:

[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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_char_size_screen

// TRANSLATION MISSING
_Updated in 3.8._

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:
// TRANSLATION MISSING
** -1: non printable char
// TRANSLATION MISSING
** ≥ 0: printable char

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

// TRANSLATION MISSING
* U+0009 (Tabulation): value of option
  link:weechat_user.it.html#option_weechat.look.tab_width[weechat.look.tab_width ^↗^^]
* U+0001 (1) to U+001F (31), except U+0009 (Tabulation): 1
* U+00AD (173, soft hyphen): -1
* U+200B (8203, zero width space): -1

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_add_offset

// TRANSLATION MISSING
_Updated in 1.3._

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

Prototipo:

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

Argomenti:

* _string_: stringa
* _offset_: numero di caratteri

Valore restituito:

// TRANSLATION MISSING
* puntatore alla stringa, N caratteri dopo (NULL se non raggiungibile)
  (_WeeChat ≥ 1.3_: pointer returned is a _const char *_ instead of _char *_)

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_strndup

Restituisce la stringa duplicata, di lunghezza massima _length_.

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);  /* restituisce "chê" */
/* ... */
free (string);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== utf8_strncpy

_WeeChat ≥ 3.8._

// TRANSLATION MISSING
Copy _length_ chars max in another string and add null byte at the end.

Prototipo:

[source,c]
----
void weechat_utf8_strncpy (char *dest, const char *string, int length);
----

Argomenti:

// TRANSLATION MISSING
* _dest_: destination string (must be long enough)
* _string_: stringa
// TRANSLATION MISSING
* _length_: max chars to copy

Esempio in C:

[source,c]
----
char dest[256];

weechat_utf8_strncpy (dest, "chêne", 3);  /* copies "chê" to dest */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
[[crypto]]
=== Cryptography

Some cryptographic functions.

// TRANSLATION MISSING
==== crypto_hash

_WeeChat ≥ 2.8._

Compute hash of data.

Prototipo:

[source,c]
----
int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo,
                         void *hash, int *hash_size);
----

Argomenti:

* _data_: the data to hash
* _data_size_: number of bytes to hash in _data_
* _hash_algo_: the hash algorithm, see table below
* _hash_: pointer to the hash variable, which is used to store the resulting hash
  (the buffer must be large enough, according to the algorithm, see table below)
* _hash_size_: pointer to a variable used to store the length of the hash computed
  (in bytes) (can be NULL)

[[crypto_hash_algorithms]]
Supported hash algorithms:

[width="100%",cols="2,2,3,6",options="header"]
|===
| Value           | Algorithm   | Hash size           | Notes
| `+crc32+`       | CRC32       | 4 bytes (32 bits)   | Not a hash algorithm in the cryptographic sense.
| `+md5+`         | MD5         | 16 bytes (128 bits) | *Weak*, not recommended for cryptography usage.
| `+sha1+`        | SHA-1       | 20 bytes (160 bits) | *Weak*, not recommended for cryptography usage.
| `+sha224+`      | SHA-224     | 28 bytes (224 bits) |
| `+sha256+`      | SHA-256     | 32 bytes (256 bits) |
| `+sha384+`      | SHA-384     | 48 bytes (384 bits) |
| `+sha512+`      | SHA-512     | 64 bytes (512 bits) |
| `+sha512-224+`  | SHA-512/224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.9.4.
| `+sha512-256+`  | SHA-512/256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.9.4.
| `+sha3-224+`    | SHA3-224    | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
| `+sha3-256+`    | SHA3-256    | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
| `+sha3-384+`    | SHA3-384    | 48 bytes (384 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
| `+sha3-512+`    | SHA3-512    | 64 bytes (512 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
| `+blake2b-160+` | BLAKE2B-160 | 20 bytes (160 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2b-256+` | BLAKE2B-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2b-384+` | BLAKE2B-384 | 48 bytes (384 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2b-512+` | BLAKE2B-512 | 64 bytes (512 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2s-128+` | BLAKE2S-128 | 16 bytes (128 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2s-160+` | BLAKE2S-160 | 20 bytes (160 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2s-224+` | BLAKE2S-224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
| `+blake2s-256+` | BLAKE2S-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
|===

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== crypto_hash_file

_WeeChat ≥ 3.7._

Compute hash of a file.

Prototipo:

[source,c]
----
int weechat_crypto_hash_file (const char *filename, const char *hash_algo,
                              void *hash, int *hash_size);
----

Argomenti:

* _filename_: percorso e nome file
* _hash_algo_: the hash algorithm, see table in function
  <<crypto_hash_algorithms,crypto_hash>>
* _hash_: pointer to the hash variable, which is used to store the resulting hash
  (the buffer must be large enough, according to the algorithm, see table in
  function <<crypto_hash_algorithms,crypto_hash>>)
* _hash_size_: pointer to a variable used to store the length of the hash computed
  (in bytes) (can be NULL)

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== crypto_hash_pbkdf2

_WeeChat ≥ 2.8._

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

Prototipo:

[source,c]
----
int weechat_crypto_hash_pbkdf2 (const void *data, int data_size,
                                const char *hash_algo,
                                const void *salt, int salt_size,
                                int iterations,
                                void *hash, int *hash_size);
----

Argomenti:

* _data_: the data to hash
* _data_size_: number of bytes to hash in _data_
* _hash_algo_: hash algorithm used by the key derivation function, see table
  in function <<crypto_hash_algorithms,crypto_hash>>
* _salt_: the salt
* _salt_size_: number of bytes in _salt_
* _iterations_: number of iterations
* _hash_: pointer to the hash variable, which is used to store the resulting hash
  (the buffer must be large enough, according to the algorithm, see table in
  function <<crypto_hash_algorithms,crypto_hash>>)
* _hash_size_: pointer to a variable used to store the size of the hash computed
  (in bytes) (can be NULL)

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[directories]]
=== Cartelle

Alcune funzioni legate alle cartelle.

// TRANSLATION MISSING
==== crypto_hmac

_WeeChat ≥ 3.2._

Compute keyed-hash message authentication code (HMAC).

Prototipo:

[source,c]
----
int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size,
                         int hash_algo, void *hash, int *hash_size);
----

Argomenti:

* _key_: the key
* _key_size_: number of bytes in _key_
* _message_: the message
* _message_size_: number of bytes in _message_
* _hash_algo_: the hash algorithm, see table in function
  <<crypto_hash_algorithms,crypto_hash>>
* _hash_: pointer to the hash variable, which is used to store the resulting hash
  (the buffer must be large enough, according to the algorithm, see table
  in function <<crypto_hash_algorithms,crypto_hash>>)
* _hash_size_: pointer to a variable used to store the size of the hash computed
  (in bytes) (can be NULL)

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== mkdir_home

// TRANSLATION MISSING
_Updated in 3.2._

Crea una cartella nella home di WeeChat.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _directory_: name of directory to create; it can start with one of these
  strings to force a specific WeeChat directory (WeeChat ≥ 3.2):
** `${weechat_config_dir}`
** `${weechat_data_dir}` (default)
** `${weechat_state_dir}`
** `${weechat_cache_dir}`
** `${weechat_runtime_dir}`
* _mode_: modalità per la cartella

Valore restituito:

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

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def mkdir_home(directory: str, mode: int) -> int: ...

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

==== 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 in caso di errore

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def mkdir(directory: str, mode: int) -> int: ...

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

==== mkdir_parents

Crea una cartella e le cartelle genitore se necessario.

Prototipo:

[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 in caso di errore

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def mkdir_parents(directory: str, mode: int) -> int: ...

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

==== exec_on_files

// TRANSLATION MISSING
_Updated in 1.5, 2.0._

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

Prototipo:

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

Argomenti:

* _directory_: cartella in cui cercare i file
// TRANSLATION MISSING
* _recurse_subdirs_: 1 to recurse into sub-directories _(WeeChat ≥ 2.0)_
* _hidden_files_: 1 per includere i file nascosti, altrimenti 0
* _callback_: funzione chiamata per ogni file trovato, argomenti:
** _void *data_: puntatore
** _const char *filename_: nome file trovato
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== file_get_content

_WeeChat ≥ 0.3.1._

Ottiene il contenuto del file di testo in una stringa.

Prototipo:

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

Argomenti:

* _filename_: percorso e nome file

Valore restituito:

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

Esempio in C:

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

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== file_copy

_WeeChat ≥ 3.3._

Copy a file to another location.

Prototipo:

[source,c]
----
int weechat_file_copy (const char *from, const char *to);
----

Argomenti:

* _from_: source file
* _to_: destination file

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
{
    /* OK */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== file_compress

_WeeChat ≥ 3.7._

Compress a file with gzip or zstd.

Prototipo:

[source,c]
----
int weechat_file_compress (const char *from, const char *to,
                           const char *compressor, int compression_level);
----

Argomenti:

* _from_: source file
* _to_: destination file
* _compressor_: the compressor to use, one of:
** _gzip_: gzip compression
** _zstd_: zstandard compression (available only if zstd was enabled when
   WeeChat was compiled)
* _compression_level_: compression level, between 1 (fast, low compression) to
  100 (slow, best compression)

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
{
    /* OK */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== file_compare

_WeeChat ≥ 4.7.0._

Compare the content of two files.

Prototipo:

[source,c]
----
int weechat_file_compare (const char *filename1, const char *filename2);
----

Argomenti:

* _filename1_: first file to compare
* _filename2_: second file to compare

Valore restituito:

* 0: both files have same content
* 1: content is different
* 2: error (file not found or read error)

Esempio in C:

[source,c]
----
if (weechat_file_compare ("/tmp/test.txt", "/tmp/test2.txt") == 0)
{
    /* same content */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[util]]
=== Utilità

Alcune funzioni utili.

==== 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 */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== util_timeval_diff

// TRANSLATION MISSING
_Updated in 1.1._

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

Prototipo:

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

Argomenti:

* _tv1_: prima struttura "timeval"
* _tv2_: seconda struttura "timeval"

Valore restituito:

// TRANSLATION MISSING
* difference in microseconds

// TRANSLATION MISSING
[NOTE]
With WeeChat ≤ 1.0, the returned value was in milliseconds.

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== util_timeval_add

// TRANSLATION MISSING
_Updated in 1.1._

// TRANSLATION MISSING
Add interval (in microseconds) to a timeval structure.

Prototipo:

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

Argomenti:

* _tv_: struttura timeval
// TRANSLATION MISSING
* _interval_: interval (in microseconds)

// TRANSLATION MISSING
[NOTE]
With WeeChat ≤ 1.0, the interval was expressed in milliseconds.

Esempio in C:

[source,c]
----
weechat_util_timeval_add (&tv, 2000000);  /* aggiunge 2 secondi */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== util_get_time_string

// TRANSLATION MISSING
_WeeChat ≥ 0.3.2, updated in 1.3._

// TRANSLATION MISSING
Get date/time as a string built with "strftime" and the format defined in
option _weechat.look.time_format_.

Prototipo:

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

Argomenti:

* _date_: puntatore alla data

Valore restituito:

// TRANSLATION MISSING
* pointer to a string with date/time

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== util_strftimeval

_WeeChat ≥ 4.2.0, updated in 4.3.0, 4.7.0._

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

Prototype:

[source,c]
----
int weechat_util_strftimeval (char *string, int max, const char *format, struct timeval *tv);
----

Arguments:

* _string_: buffer where the formatted string is stored
* _max_: string size
* _format_: format, the same as _strftime_ function, with these extra specifiers:
** `%@`: return the date expressed in Coordinated Universal Time (UTC)
   instead of date relative to the user's specified timezone _(WeeChat ≥ 4.7.0)_
** `%.N` where `N` is between 1 and 6: zero-padded microseconds on N digits
   (for example `%.3` for milliseconds)
** `%f`: alias of `%.6`
** `%!`: timestamp as integer, in seconds (value of tv->tv_sec)

Return value:

* number of bytes put in _string_ (value returned from _strftime_ function)

C example:

[source,c]
----
char time[256];
struct timeval tv;
gettimeofday (&tv, NULL);
weechat_util_strftimeval (time, sizeof (time), "%@%FT%T.%fZ", &tv);
/* result: 2023-12-26T18:10:04.460509Z */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== util_parse_time

_WeeChat ≥ 4.2.0._

Parse date/time with support of microseconds.

Prototype:

[source,c]
----
int util_parse_time (const char *datetime, struct timeval *tv);
----

Arguments:

* _date_: date/time
* _tv_: parsed date/time ("timeval" structure)

Return value:

* 1 if OK, 0 if error

C example:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== util_version_number

// TRANSLATION MISSING
_WeeChat ≥ 0.3.9, updated in 4.7.0._

// TRANSLATION MISSING
Convert a string with WeeChat version to a number.

Prototipo:

[source,c]
----
unsigned long weechat_util_version_number (const char *version);
----

Argomenti:

// TRANSLATION MISSING
* _version_: WeeChat version as string (example: "0.3.9" or "0.3.9-dev")

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[sorted_lists]]
=== Elenchi ordinati

Funzioni lista ordinata.

==== 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
def list_new() -> str: ...

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

==== 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
def list_add(list: str, data: str, where: str, user_data: str) -> str: ...

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

==== list_search

Cerca un elemento nella lista.

Prototipo:

[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
def list_search(list: str, data: str) -> str: ...

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

==== list_search_pos

_WeeChat ≥ 0.3.4._

Cerca la posizione di un elemento nella lista.

Prototipo:

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

Argomenti:

* _weelist_: puntatore alla lista
* _data_: dati da cercare nella lista

Valore restituito:

* posizione dell'elemento trovato, -1 se non trovato

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def list_search_pos(list: str, data: str) -> int: ...

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

==== list_casesearch

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

Prototipo:

[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
def list_casesearch(list: str, data: str) -> str: ...

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

==== list_casesearch_pos

_WeeChat ≥ 0.3.4._

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

Prototipo:

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

Argomenti:

* _weelist_: puntatore alla lista
* _data_: dati da cercare nella lista

Valore restituito:

* posizione dell'elemento trovato, -1 se non trovato

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def list_casesearch_pos(list: str, data: str) -> int: ...

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

==== list_get

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

Prototipo:

[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);  /* primo elemento */
----

Script (Python):

[source,python]
----
# prototipo
def list_get(list: str, position: int) -> str: ...

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

==== list_set

Imposta un nuovo valore per un elemento.

Prototipo:

[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
def list_set(item: str, value: str) -> int: ...

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

==== 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
def list_next(item: str) -> str: ...

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

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

// TRANSLATION MISSING
* pointer to previous item, NULL if pointer was first item in list

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def list_prev(item: str) -> str: ...

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

==== 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, "valore dell'elemento: %s", weechat_list_string (item));
----

Script (Python):

[source,python]
----
# prototipo
def list_string(item: str) -> str: ...

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

==== list_user_data

_WeeChat ≥ 2.6._

// TRANSLATION MISSING
Return pointer to the user data of an item.

Prototipo:

[source,c]
----
void *weechat_list_user_data (struct t_weelist_item *item);
----

Argomenti:

* _item_: puntatore all'elemento

Valore restituito:

// TRANSLATION MISSING
* pointer to the user data of item

Esempio in C:

[source,c]
----
weechat_printf (NULL, "user data of item: %p", weechat_list_user_data (item));
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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, "dimensione della lista: %d", weechat_list_size (list));
----

Script (Python):

[source,python]
----
# prototipo
def list_size(list: str) -> int: ...

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

==== list_remove

Rimuove un elemento in una lista.

Prototipo:

[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
def list_remove(list: str, item: str) -> int: ...

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

==== list_remove_all

Rimuove tutti gli elementi in una lista.

Prototipo:

[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
def list_remove_all(list: str) -> int: ...

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

==== 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
def list_free(list: str) -> int: ...

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

[[array_lists]]
=== Array lists

// TRANSLATION MISSING
Array list functions.

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

==== arraylist_new

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Create a new array list.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _initial_size_: initial size of the array list (not the number of items)
* _sorted_: 1 to sort the array list, 0 for no sort
* _allow_duplicates_: 1 to allow duplicate entries, 0 to prevent a same entry
  to be added again
* _callback_cmp_: callback used to compare two items (optional), arguments and
  return value:
** _void *data_: pointer
** _struct t_arraylist *arraylist_: array list pointer
** _void *pointer1_: pointer to first item
** _void *pointer2_: pointer to second item
** return value:
*** negative number if first item is less than second item
*** 0 if first item equals second item
*** positive number if first item is greater than second item
* _callback_cmp_data_: pointer given to callback when it is called by WeeChat
* _callback_free_: callback used to free an item (optional), arguments:
** _void *data_: pointer
** _struct t_arraylist *arraylist_: array list pointer
** _void *pointer_: pointer to item
* _callback_free_data_: pointer given to callback when it is called by WeeChat

Valore restituito:

// TRANSLATION MISSING
* pointer to new array list

Esempio in C:

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

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_size

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Return size of array list (number of item pointers).

Prototipo:

[source,c]
----
int weechat_list_size (struct t_arraylist *arraylist);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer

Valore restituito:

// TRANSLATION MISSING
* size of array list (number of items), 0 if array list is empty

Esempio in C:

[source,c]
----
weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_get

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Return an item pointer by position.

Prototipo:

[source,c]
----
void *weechat_arraylist_get (struct t_arraylist *arraylist, int index);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer
* _index_: index in list (first pointer is 0)

Valore restituito:

// TRANSLATION MISSING
* pointer found, NULL if pointer was not found

Esempio in C:

[source,c]
----
void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_search

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Search an item in an array list.

Prototipo:

[source,c]
----
void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer,
                                int *index, int *index_insert);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer
* _pointer_: pointer to the item to search in array list
* _index_: pointer to integer that will be set to the index found, or -1 if not found
  (optional)
* _index_insert_: pointer to integer that will be set with the index that must be
  used to insert the element in the arraylist (to keep arraylist sorted) (optional)

Valore restituito:

// TRANSLATION MISSING
* pointer to item found, NULL if item was not found

Esempio in C:

[source,c]
----
int index, index_insert;
void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_insert

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Insert an item in an array list.

Prototipo:

[source,c]
----
int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer
* _index_: position of the item in array list or -1 to add at the end
  (this argument is used only if the array list is not sorted, it is ignored if
  the array list is sorted)
* _pointer_: pointer to the item to insert

Valore restituito:

// TRANSLATION MISSING
* index of new item (≥ 0), -1 if error.

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_add

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Add an item in an array list.

Prototipo:

[source,c]
----
int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer
* _pointer_: pointer to the item to add

Valore restituito:

// TRANSLATION MISSING
* index of new item (≥ 0), -1 if error.

Esempio in C:

[source,c]
----
int index = weechat_arraylist_add (arraylist, pointer);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_remove

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Remove an item from an array list.

Prototipo:

[source,c]
----
int weechat_arraylist_remove (struct t_arraylist *arraylist, int index);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer
* _index_: index of the item to remove

Valore restituito:

// TRANSLATION MISSING
* index of item removed, -1 if error.

Esempio in C:

[source,c]
----
int index_removed = weechat_arraylist_remove (arraylist, index);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_clear

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Remove all items from an array list.

Prototipo:

[source,c]
----
int weechat_arraylist_clear (struct t_arraylist *arraylist);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer

Valore restituito:

// TRANSLATION MISSING
* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
if (weechat_arraylist_clear (arraylist))
{
    /* OK */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== arraylist_free

_WeeChat ≥ 1.8._

// TRANSLATION MISSING
Free an array list.

Prototipo:

[source,c]
----
void weechat_arraylist_free (struct t_arraylist *arraylist);
----

Argomenti:

// TRANSLATION MISSING
* _arraylist_: array list pointer

Esempio in C:

[source,c]
----
weechat_arraylist_free (arraylist);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[hashtables]]
=== Tabelle hash

Funzioni per le tabelle hash.

==== hashtable_new

// TRANSLATION MISSING
_WeeChat ≥ 0.3.3, updated in 4.4.0._

Crea una nuova tabella hash.

Prototipo:

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

Argomenti:

* _size_: dimensione dell'array interno per memorizzare le chiavi con hash, un
  valore più alto usa più memoria, ma ha migliori performance. (questo *non* è
  un limite per il numero di elementi nella tabella hash)
* _type_keys_: tipo per le chiavi nella tabella hash:
** _WEECHAT_HASHTABLE_INTEGER_
** _WEECHAT_HASHTABLE_STRING_
** _WEECHAT_HASHTABLE_POINTER_
** _WEECHAT_HASHTABLE_BUFFER_
** _WEECHAT_HASHTABLE_TIME_
** _WEECHAT_HASHTABLE_LONGLONG_ _(WeeChat ≥ 4.4.0)_
* _type_values_: tipo per i valori nella tabella hash:
** _WEECHAT_HASHTABLE_INTEGER_
** _WEECHAT_HASHTABLE_STRING_
** _WEECHAT_HASHTABLE_POINTER_
** _WEECHAT_HASHTABLE_BUFFER_
** _WEECHAT_HASHTABLE_TIME_
** _WEECHAT_HASHTABLE_LONGLONG_ _(WeeChat ≥ 4.4.0)_
// TRANSLATION MISSING
* _callback_hash_key_: callback used to "hash" a key (key as integer value), can
  be NULL if key type is not "buffer" (a default hash function is used),
  arguments and return value:
** _struct t_hashtable *hashtable_: puntatore alla tabella hash
** _const void *key_: chiave
** return value: hash della chiave
// TRANSLATION MISSING
* _callback_keycmp_: callback used to compare two keys, can be NULL if key type
  is not "buffer" (a default comparison function is used), arguments and return
  value:
** _struct t_hashtable *hashtable_: puntatore alla tabella hash
** _const void *key1_: prima chiave
** _const void *key2_: seconda chiave
** valore restituito:
*** numero negativo se _key1_ è minore di _key2_
*** 0 se _key1_ è uguale a _key2_
*** numero positivo se _key1_ è maggiore di _key2_

Valore restituito:

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

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_set_with_size

// TRANSLATION MISSING
_WeeChat ≥ 0.3.3, updated in 0.4.2._

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

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _key_: puntatore alla chiave
* _key_size_: dimensione della chiave (in byte), usata solo se il tipo delle
   chiavi nella tabella hash è "buffer"
* _value_: puntatore al valore
* _value_size_: dimensione del valore (in byte), utilizzata solo se il tipo dei
   valori nella tabella è "buffer"

Valore restituito:

// TRANSLATION MISSING
* pointer to item created/updated, NULL if error

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_set

// TRANSLATION MISSING
_WeeChat ≥ 0.3.3, updated in 0.4.2._

Aggiunge o aggiorna un elemento nella tabella hash.

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _key_: puntatore alla chiave
* _value_: puntatore al valore

Valore restituito:

// TRANSLATION MISSING
* pointer to item created/updated, NULL if error

Esempio in C:

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

==== hashtable_get

_WeeChat ≥ 0.3.3._

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

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _key_: puntatore alla chiave

Valore restituito:

* valore per la chiave, NULL se non trovata

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_has_key

_WeeChat ≥ 0.3.4._

// TRANSLATION MISSING
Check if a key is in the hashtable.

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _key_: puntatore alla chiave

Valore restituito:

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

Esempio in C:

[source,c]
----
if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* la chiave è nella tabella hash */
    /* ... */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_map

_WeeChat ≥ 0.3.3._

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

Prototipo:

[source,c]
----
void weechat_hashtable_map (struct t_hashtable *hashtable,
                            void (*callback_map)(void *data,
                                                 struct t_hashtable *hashtable,
                                                 const void *key,
                                                 const void *value),
                            void *callback_map_data);
----

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _callback_map_: funzione chiamata per ogni voce nella tabella hash
* _callback_map_data_: puntatore fornito alla mappa di callback quando chiamata

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_map_string

_WeeChat ≥ 0.3.7._

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

Prototipo:

[source,c]
----
void weechat_hashtable_map_string (struct t_hashtable *hashtable,
                                   void (*callback_map)(void *data,
                                                        struct t_hashtable *hashtable,
                                                        const char *key,
                                                        const char *value),
                                   void *callback_map_data);
----

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _callback_map_: funzione chiamata per ogni voce nella tabella hash
* _callback_map_data_: puntatore fornito alla mappa di callback quando chiamata

[NOTE]
Le stringhe _key_ e _value_ inviate alla callback sono temporanee, vengono
eliminate dopo la chiamata alla callback.

Esempio in C:

[source,c]
----
void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* display key and value */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_dup

_WeeChat ≥ 1.0._

// TRANSLATION MISSING
Duplicate a hashtable.

Prototipo:

[source,c]
----
struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);
----

Argomenti:

* _hashtable_: puntatore alla tabella hash

Valore restituito:

// TRANSLATION MISSING
* duplicated hashtable

Esempio in C:

[source,c]
----
struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_get_integer

_WeeChat ≥ 0.3.3._

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

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _property_: nome della proprietà:
** _size_: dimensione dell'array interno "htable" nella tabella hash
** _items_count_: numero di elementi nella tabella hash

Valore restituito:

* valore intero della proprietà

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_get_string

_WeeChat ≥ 0.3.4._

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

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _property_: nome della proprietà:
** _type_keys_: tipo per le chiavi:
*** _integer_: intero
*** _string_: stringa
*** _pointer_: puntatore
*** _buffer_: buffer
*** _time_: tempo
// TRANSLATION MISSING
*** _longlong_: long long integer
** _type_values_: tipo per i valori:
*** _integer_: intero
*** _string_: stringa
*** _pointer_: puntatore
*** _buffer_: buffer
*** _time_: tempo
// TRANSLATION MISSING
*** _longlong_: long long integer
** _keys_: stringa con la lista di chiavi (formato: "chiave1,chiave2,chiave3")
** _keys_sorted_: stringa con l'elenco di chiavi ordinate (formato: "chiave1,chiave2,chiave3")
** _values_: stringa  con la lista di valori (formato: "valore1,valore2,valore3")
** _keys_values_: stringa con la lista di valori e chiavi
   (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")
** _keys_values_sorted_: stringa con la lista di chiavi e valori (ordinata per chiavi)
   (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")

Valore restituito:

* valore stringa della proprietà

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_set_pointer

_WeeChat ≥ 0.3.4._

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

Prototipo:

[source,c]
----
void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);
----

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _property_: nome della proprietà:
// TRANSLATION MISSING
** _callback_free_key_: set callback function used to free keys in hashtable
   _(WeeChat ≥ 0.4.2)_
** _callback_free_value_: imposta la funzione callback usata per
   liberare i valori nella tabella hash
// TRANSLATION MISSING
* _pointer_: new pointer value for property

Esempio in C:

[source,c]
----
void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

void
my_free_key_cb (struct t_hashtable *hashtable, void *key)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_add_to_infolist

_WeeChat ≥ 0.3.3._

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

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _infolist_item_: puntatore all'elemento della lista info
* _prefix_: stringa usata come prefisso per i nomi nella lista info

Valore restituito:

* 1 se ok, 0 in caso di errore

Esempio in C:

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

/* se la tabella hash contiene:
     "key1" => "value 1"
     "key2" => "value 2"
   allora le seguenti variabili verranno aggiunti all'elemento  della lista info:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
*/
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_add_from_infolist

_WeeChat ≥ 2.2._

// TRANSLATION MISSING
Add infolist items in a hashtable.

Prototipo:

[source,c]
----
int weechat_hashtable_add_from_infolist (struct t_hashtable *hashtable,
                                         struct t_infolist *infolist,
                                         const char *prefix);
----

Argomenti:

* _hashtable_: puntatore alla tabella hash
// TRANSLATION MISSING
* _infolist_: infolist pointer
* _prefix_: stringa usata come prefisso per i nomi nella lista info

Valore restituito:

* 1 se ok, 0 in caso di errore

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
weechat_hashtable_add_from_infolist (hashtable, infolist, "testhash");

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_remove

_WeeChat ≥ 0.3.3._

Rimuove un elemento in una tabella hash.

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash
* _key_: puntatore alla chiave

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_remove_all

_WeeChat ≥ 0.3.3._

Rimuove tutti gli elementi in una tabella hash.

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hashtable_free

_WeeChat ≥ 0.3.3._

Libera una tabella hash.

Prototipo:

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

Argomenti:

* _hashtable_: puntatore alla tabella hash

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[configuration_files]]
=== File di configurazione

Funzioni per i file di configurazione.

==== config_new

// TRANSLATION MISSING
_Updated in 1.5, 4.0.0._

Crea un nuovo file di configurazione.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _name_: nome del file di configurazione (senza percorso o estensione); a priority
  is allowed before the name, with format `nnn|name` where `nnn` is non-negative
  integer with priority; default priority is 1000; files are sorted by priority
  from higher to lower when running command `/reload`
  (see priority of configuration files below)
// TRANSLATION MISSING
* _callback_reload_: funzione chiamata quando il file di configurazione viene
  ricaricato con `/reload` (opzionale, può essere NULL, see below), argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** valore restituito:
*** _WEECHAT_CONFIG_READ_OK_
*** _WEECHAT_CONFIG_READ_MEMORY_ERROR_
*** _WEECHAT_CONFIG_READ_FILE_NOT_FOUND_
* _callback_reload_pointer_: puntatore fornito per ricaricare il callback
  quando richiesto da WeeChat
// TRANSLATION MISSING
* _callback_reload_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the configuration file is
  freed

// TRANSLATION MISSING
Reload callback:

* The callback must only call the function <<_config_reload,config_reload>>,
  it must not remove the configuration file.
* A callback is needed only if it does some things before and/or after the
  call to the function <<_config_reload,config_reload>>. +
  If no callback is given, WeeChat will call its internal reload function,
  so the configuration file will be reloaded in all cases.

Valore restituito:

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

[NOTE]
Il file NON viene creato su disco da questa funzione. Verrà creato chiamando
la funzione <<_config_write,config_write>>.
Si dovrebbe chiamare questa funzione solo dopo aver aggiunto alcune sezioni
(con <<_config_new_section,config_new_section>>) e le
opzioni (con <<_config_new_option,config_new_option>>).

// TRANSLATION MISSING
Priority of default configuration files:

include::{autogendir}/autogen_api_config_priority.it.adoc[tag=config_priority]

Esempio in C:

[source,c]
----
int
my_config_reload_cb (const void *pointer, void *data,
                     struct t_config_file *config_file)
{
    /* ... */

    return WEECHAT_RC_OK;
}

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

Script (Python):

[source,python]
----
# prototipo
def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ...

# esempio
def my_config_reload_cb(data: str, config_file: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

// TRANSLATION MISSING
==== config_set_version

_WeeChat ≥ 4.0.0._

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

Prototipo:

[source,c]
----
int config_file_set_version (struct t_config_file *config_file,
                             int version,
                             struct t_hashtable *(*callback_update)(const void *pointer,
                                                                    void *data,
                                                                    struct t_config_file *config_file,
                                                                    int version_read,
                                                                    struct t_hashtable *data_read),
                             const void *callback_update_pointer,
                             void *callback_update_data);
----

Argomenti:

* _config_file_: configuration file pointer
* _version_: version, must be ≥ 2
* _callback_update_: function called when configuration file is read, for each
  section and each option, if the version read is less than the expected version,
  (optional, can be NULL, see below), arguments and return value:
** _const void *pointer_: pointer
** _void *data_: pointer
** _struct t_config_file *config_file_: configuration file pointer
** _int version_read_: version read in configuration file (1 by default)
** _struct t_hashtable *data_read_: hashtable with data read from configuration file
   (see below)
** return value:
*** either "data_read" pointer (hashtable completed), or pointer to a new
    hashtable (created by callback, with keys and values of type "string")
* _callback_update_pointer_: pointer given to callback when it is called by
  WeeChat
* _callback_update_data_: pointer given to callback when it is called by
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the configuration file is freed

Update callback:

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

[width="100%",cols="1m,2,8",options="header"]
|===
| Key        | Availability    | Value
| config     | Always set      | Name of configuration file, without extension (eg: `weechat`)
| section    | Always set      | Name of section being read
| option     | For option only | Name of the option
| value      | For option only | Value of the option (if not NULL)
| value_null | For option only | Option as NULL value (value is always `1`)
|===

* The callback can update "section" for a line with a section and "option", "value"
  and "value_null" for a line with an option.
* If "option" is set to empty string by the callback, the line read in
  configuration file is ignored.
* Field "value_null" is set to force a NULL value for the option.

Valore restituito:

* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
struct t_hashtable *
my_config_update_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     int version_read,
                     struct t_hashtable *data_read)
{
    const char *ptr_section, *ptr_option;

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

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

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

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

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

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

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

    /* no changes */
    return NULL;
}

struct t_config_file *config_file = weechat_config_new ("test", NULL, NULL, NULL);
weechat_config_set_version (config_file, 2, &my_config_update_cb, NULL, NULL);
weechat_config_read (config_file);
----

Script (Python):

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

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

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

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

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

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

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

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

    # no changes
    return {}

config_file = weechat.config_new("test", "", "")
weechat.config_set_version(config_file, 2, "my_config_update_cb", "")
weechat.config_read(config_file)
----

==== config_new_section

// TRANSLATION MISSING
_Updated in 1.5._

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)(const void *pointer,
                         void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    const void *callback_read_pointer,
    void *callback_read_data,
    int (*callback_write)(const void *pointer,
                          void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    const void *callback_write_pointer,
    void *callback_write_data,
    int (*callback_write_default)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name),
    const void *callback_write_default_pointer,
    void *callback_write_default_data,
    int (*callback_create_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    const void *callback_create_option_pointer,
    void *callback_create_option_data,
    int (*callback_delete_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    const void *callback_delete_option_pointer,
    void *callback_delete_option_data);
----

Argomenti:

* _config_file_: puntatore al file di configurazione
* _name_: nome della sezione
* _user_can_add_options_: 1 se l'utente può creare nuove opzioni nella sezione,
  oppure 0 se non gli è consentito
* _user_can_delete_options_: 1 se l'utente può eliminare le opzioni nella sezione,
  oppure 0 se non gli è consentito
* _callback_read_: funzione chiamata quando un'opzione nella sezione viene letta
  da disco (dovrebbe essere NULL in molti casi, tranne se l'opzione nella sezione
  necessita di una funzione personalizza), argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** _struct t_config_section *section_: puntatore alla sezione
** _const char *option_name_: nome dell'opzione
** _const char *value_: valore
** valore restituito:
*** _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_
*** _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_
*** _WEECHAT_CONFIG_OPTION_SET_ERROR_
*** _WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND_
* _callback_read_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _callback_read_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the section is freed
* _callback_write_: funzione chiamata quando la sezione è scritta nel file (dovrebbe
  essere NULL in molti casi, tranne se la sezione necessita di una funzione
  personalizzata), argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** _const char *section_name_: nome della sezione
** valore restituito:
*** _WEECHAT_CONFIG_WRITE_OK_
*** _WEECHAT_CONFIG_WRITE_ERROR_
*** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_
* _callback_write_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _callback_write_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the section is freed
* _callback_write_default_: funzione chiamata quando i valori predefiniti per
  la sezione devono essere scritti in un file, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** _const char *section_name_: nome della sezione
** valore restituito:
*** _WEECHAT_CONFIG_WRITE_OK_
*** _WEECHAT_CONFIG_WRITE_ERROR_
*** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_
* _callback_write_default_pointer_: puntatore fornito alla callback quando
  chiamata da WeeChat
// TRANSLATION MISSING
* _callback_write_default_data_: puntatore fornito dalla callback quando
  chiamata da WeeChat; if not NULL, it must have been allocated with malloc
  (or similar function) and it is automatically freed when the section is freed
* _callback_create_option_: funzione chiamata quando viene creata una nuova
  opzione nella sezione (NULL se la sezione non consente di creare nuove
  opzioni), argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** _struct t_config_section *section_: puntatore alla sezione
** _const char *option_name_: nome dell'opzione
** _const char *value_: valore
** valore restituito:
*** _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_
*** _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_
*** _WEECHAT_CONFIG_OPTION_SET_ERROR_
*** _WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND_
* _callback_create_option_pointer_: puntatore fornito alla callback quando
  chiamata da WeeChat
// TRANSLATION MISSING
* _callback_create_option_data_: puntatore fornito dalla callback quando
  chiamata da WeeChat; if not NULL, it must have been allocated with malloc
  (or similar function) and it is automatically freed when the section is freed
* _callback_delete_option_: funzione chiamata quando un'opzione viene eliminata
  nella sezione (NULL se la sezione non consente di eliminare delle opzioni),
  argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_file *config_file_: puntatore al file di configurazione
** _struct t_config_section *section_: puntatore alla sezione
** _struct t_config_option *option_: puntatore all'opzione
** valore restituito:
*** _WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET_
*** _WEECHAT_CONFIG_OPTION_UNSET_OK_RESET_
*** _WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED_
*** _WEECHAT_CONFIG_OPTION_UNSET_ERROR_
* _callback_delete_option_pointer_: puntatore fornito alla callback quando
  chiamata da WeeChat
// TRANSLATION MISSING
* _callback_delete_option_data_: puntatore fornito dalla callback quando
  chiamata da WeeChat; if not NULL, it must have been allocated with malloc
  (or similar function) and it is automatically freed when the section is freed

Valore restituito:

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

Esempio in C:

[source,c]
----
int
my_section_read_cb (const void *pointer, void *data,
                    struct t_config_file *config_file,
                    struct t_config_section *section,
                    const char *option_name,
                    const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_write_default_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_create_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name,
                             const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_delete_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* sezione standard, l'utente non può aggiungere/rimuovere opzioni */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL);

/* sezione speciale, l'utente può aggiungere/eliminare opzioni, e le
   opzioni necessitano di un callback per essere lette/scritte */
struct t_config_section *new_section2 =
    weechat_config_new_section (config_file, "section2", 1, 1,
                                &my_section_read_cb, NULL, NULL,
                                &my_section_write_cb, NULL, NULL,
                                &my_section_write_default_cb, NULL, NULL,
                                &my_section_create_option_cb, NULL, NULL,
                                &my_section_delete_option_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def config_new_section(config_file: str, name: str,
                       user_can_add_options: int, user_can_delete_options: int,
                       callback_read: str, callback_read_data: str,
                       callback_write: str, callback_write_data: str,
                       callback_write_default: str, callback_write_default_data: str,
                       callback_create_option: str, callback_create_option_data: str,
                       callback_delete_option: str, callback_delete_option_data: str) -> str: ...

# esempio
def my_section_read_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_write_default_cb(data: str, config_file: str, section_name: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK
    # return weechat.WEECHAT_CONFIG_WRITE_ERROR
    # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

def my_section_create_option_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

def my_section_delete_option_cb(data: str, config_file: str, section: str, option: str) -> int:
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
    # return weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR

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

==== config_search_section

Cerca una sezione in un file di configurazione.

Prototipo:

[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
def config_search_section(config_file: str, section_name: str) -> str: ...

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

==== config_new_option

// TRANSLATION MISSING
_Updated in 1.5, 4.1.0._

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)(const void *pointer,
                                void *data,
                                struct t_config_option *option,
                                const char *value),
    const void *callback_check_value_pointer,
    void *callback_check_value_data,
    void (*callback_change)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_change_pointer,
    void *callback_change_data,
    void (*callback_delete)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_delete_pointer,
    void *callback_delete_data);
----

Argomenti:

* _config_file_: puntatore al file di configurazione
* _section_: puntatore alla sezione
// TRANSLATION MISSING
* _name_: nome dell'opzione; with WeeChat ≥ 1.4, the name can include a parent
  option name (the value of parent option will be displayed in `/set` command
  output if this option is "null"), the syntax is then:
  "name << file.section.option"
* _type_: tipo dell'opzione:
** _boolean_: valore booleano (on/off)
** _integer_: valore intero
** _string_: valore stringa
** _color_: colore
// TRANSLATION MISSING
** _enum_: list of string values (stored as integer internally)
* _description_: descrizione dell'opzione
// TRANSLATION MISSING
* _string_values_: valori come stringa (separati da `+|+`) (optional, required
  for type _enum_)
* _min_: valore minimo (per il tipo _integer_)
* _max_: valore massimo (per il tipo _integer_)
* _default_value_: valore predefinito per l'opzione (usato per il reset dell'opzione)
* _value_: valore per l'opzione
* _null_value_allowed_: 1 se _null_ (valore non definito) è consentito per l'opzione,
  altrimenti 0
* _callback_check_value_: funzione chiamata per verificare il nuovo valore per
  l'opzione (ozionale), argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_option *option_: puntatore all'opzione
** _const char *value_: nuovo valore per l'opzione
** valore restituito:
*** 1 se il valore è corretto
*** 0 se il valore non è valido
* _callback_check_value_pointer_: puntatore fornito alla callback check_value
  quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_check_value_data_: puntatore fornito dalla callback quando chiamata
  da WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the option is freed
* _callback_change_: funzione chiamata quando il valore dell'opzione è stata
  cambiata (opzionale), argomenti:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_option *option_: puntatore all'opzione
* _callback_change_pointer_: puntatore fornito per cambiare alla callback
  quando chiamato da WeeChat
// TRANSLATION MISSING
* _callback_change_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the option is freed
* _callback_delete_: funzione chiamata quando l'opzione verrà eliminata
  (opzionale), argomenti:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_config_option *option_: puntatore all'opzione
* _callback_delete_pointer_: puntatore fornito per eiliminare alla callback
  quando chiamato da WeeChat
// TRANSLATION MISSING
* _callback_delete_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the option is freed

Valore restituito:

 alla nuova opzione nella sezione, NULL in caso di errore

Esempio in C:

[source,c]
----
/* booleano */
struct t_config_option *option_bool =
    weechat_config_new_option (config_file, section, "option_bool", "boolean",
                               "My option, type boolean",
                               NULL,
                               0, 0,
                               "on",
                               "on",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* intero */
struct t_config_option *option_int =
    weechat_config_new_option (config_file, section, "option_int", "integer",
                               "My option, type integer",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* stringa */
struct t_config_option *option_str =
    weechat_config_new_option (config_file, section, "option_str", "string",
                               "My option, type string",
                               NULL,
                               0, 0,
                               "test",
                               "test",
                               1,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* colore */
struct t_config_option *option_col =
    weechat_config_new_option (config_file, section, "option_col", "color",
                               "My option, type color",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* enum */
struct t_config_option *option_enum =
    weechat_config_new_option (config_file, section, "option_enum", "enum",
                               "My option, type enum",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def config_new_option(config_file: str, section: str, name: str, type: str, description: str,
                      string_values: str, min: int, max: int,
                      default_value: Union[str, None], value: Union[str, None], null_value_allowed: int,
                      callback_check_value: str, callback_check_value_data: str,
                      callback_change: str, callback_change_data: str,
                      callback_delete: str, callback_delete_data: str) -> str: ...

# esempio
def option_str_check_value_cb(data: str, option: str, value: str) -> int:
    # ...
    return 1
    # return 0

def option_str_change_cb(data: str, option: str) -> None:
    # ...

def option_str_delete_cb(data: str, option: str) -> None:
    # ...

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

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

option_str = weechat.config_new_option(config_file, section, "option_str", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option_str_check_value_cb", "",
    "option_str_change_cb", "",
    "option_str_delete_cb", "")

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

option_enum = weechat.config_new_option(config_file, section, "option_enum", "enum",
    "My option, type enum",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")
----

// TRANSLATION MISSING
[NOTE]
In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6
strings (due to a Ruby limitation of 15 arguments by function), see the
link:++weechat_scripting.it.html#_ruby++[WeeChat Scripting Guide ^↗^^]
for more info _(fixed in version 0.4.1)_.

==== config_search_option

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

Prototipo:

[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
def config_search_option(config_file: str, section: str, option_name: str) -> str: ...

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

==== config_search_section_option

Cerca una sezione ed un'opzione in un file di configurazione o sezione.

Prototipo:

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

Argomenti:

* _config_file_: puntatore al file di configurazione
* _section_: puntatore alla sezione
* _option_name_: nome dell'opzione
* _section_found_: puntatore al puntatore della sezione, sarà impostato alla
  sezione dell'opzione, se viene trovata
* _option_found_: puntatore al puntatore dell'opzione, sarà impostato al
  puntatore di un'opzione, se viene trovata

Esempio in C:

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

weechat_config_search_section_option(config_file,
                                     section,
                                     "option",
                                     &ptr_section,
                                     &ptr_option);
if (ptr_option)
{
    /* opzione trovata */
}
else
{
    /* opzione non trovata */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== config_search_with_string

// TRANSLATION MISSING
Get file/section/option info about an option with full name.

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,
                                        char **pos_option_name);
----

Argomenti:

* _option_name_: nome completo dell'opzione (formato: "file.section.option")
* _config_file_: puntatore al puntatore del file di configurazione, sarà impostato
  al puntatore al file di configurazione se l'opzione viene trovata
* _section_: puntatore al puntatore della sezione, sarà impostato alla sezione
  dell'opzione, se viene trovata
* _option_: puntatore al puntatore dell'opzione, sarà impostato al puntatore di
  un'opzione, se viene trovata
// TRANSLATION MISSING
* _pos_option_name_: pointer to a string pointer, will be set to pointer to
  name of option, if found

Esempio in C:

[source,c]
----
struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;
char *option_name;

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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
def config_string_to_boolean(text: str) -> int: ...

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

==== config_option_reset

Resetta un'opzione al proprio valore predefinito.

Prototipo:

[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_ in caso di 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
def config_option_reset(option: str, run_callback: int) -> int: ...

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

==== config_option_set

Imposta un nuovo valore per l'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione
// TRANSLATION MISSING
* _value_: new value for option, special values are possible according to the
  type of option:
// TRANSLATION MISSING
** _boolean_:
// TRANSLATION MISSING
*** `toggle`: toggle the current value
// TRANSLATION MISSING
** _integer_, _color_ or _enum_:
// TRANSLATION MISSING
*** `++N`: add `N` (any integer) to the current value
// TRANSLATION MISSING
*** `--N`: subtract `N` (any integer) from the current value
* _run_callback_: 1 per la chiamata alla callback chang se il valore dell'opzione
  è cambiato, altrimenti 0

Valore restituito:

* _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_ se il valore dell'opzione è
  cambiato
* _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_ se il valore non è cambiato
* _WEECHAT_CONFIG_OPTION_SET_ERROR_ in caso di errore

Esempio in C:

[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
def config_option_set(option: str, value: str, run_callback: int) -> int: ...

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

==== config_option_set_null

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

Prototipo:

[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 <<_config_new_option,config_new_option>>).

Valore restituito:

* _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_ se il valore dell'opzione è
  cambiato
* _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_ se il valore non è cambiato
* _WEECHAT_CONFIG_OPTION_SET_ERROR_ in caso di errore

Esempio in C:

[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
def config_option_set_null(option: str, run_callback: int) -> int: ...

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

==== config_option_unset

Rimuove/ripristina un'opzione.

Prototipo:

[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 ripristinato
* _WEECHAT_CONFIG_OPTION_UNSET_OK_RESET_ se il valore dell'opzione è stato
  ripristinato
* _WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED_ se l'opzione è stata rimossa
* _WEECHAT_CONFIG_OPTION_UNSET_ERROR_ in caso di errore

Esempio in C:

[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
def config_option_unset(option: str) -> int: ...

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

==== config_option_rename

Rinomina un'opzione.

Prototipo:

[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
def config_option_rename(option: str, new_name: str) -> int: ...

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

==== config_option_get_string

_WeeChat ≥ 1.9._

// TRANSLATION MISSING
Return string value of an option property.

Prototipo:

[source,c]
----
const char *weechat_config_option_get_string (struct t_config_option *option,
                                              const char *property);
----

Argomenti:

// TRANSLATION MISSING
* _option_: puntatore all'opzione
* _property_: nome della proprietà:
** _config_name_: file name
** _section_name_: section name
** _name_: option name
** _parent_name_: name of parent option
** _type_: option type, one of:
*** _boolean_
*** _integer_
*** _string_
*** _color_
*** _enum_
** _description_: option description

Valore restituito:

// TRANSLATION MISSING
* string value of property

Esempio in C:

[source,c]
----
const char *type = weechat_config_option_get_string (option, "type");
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 *_)
// TRANSLATION MISSING
** _parent_name_: name of parent option (_char *_) _(WeeChat ≥ 1.4)_
** _type_: tipo dell'opzione (_int *_)
** _description_: descrizione dell'opzione (_char *_)
** _string_values_: valori stringa (_char *_)
** _min_: valore minimo (_int *_)
** _max_: valore massimo (_int *_)
** _default_value_: valore predefinito (dipende dal tipo)
** _value_: valore corrente (dipende dal tipo)
** _prev_option_: puntatore all'opzione precedente (_struct t_config_option *_)
** _next_option_: puntatore all'opzione successiva (_struct t_config_option *_)

Valore restituito:

* puntatore alla proprietà richiesta

Esempio in C:

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

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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
def config_option_is_null(option: str) -> int: ...

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

==== config_option_default_is_null

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

Prototipo:

[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
def config_option_default_is_null(option: str) -> int: ...

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

==== config_boolean

Restituisce il valore bool di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: boolean value of option (0 or 1)
* _integer_: 0
* _string_: 0
* _color_: 0
* _enum_: 0

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----

Script (Python):

[source,python]
----
# prototipo
def config_boolean(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...
----

==== config_boolean_default

Restituisce il valore bool predefinito di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: default boolean value of option (0 or 1)
* _integer_: 0
* _string_: 0
* _color_: 0
* _enum_: 0

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----

Script (Python):

[source,python]
----
# prototipo
def config_boolean_default(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...
----

// TRANSLATION MISSING
==== config_boolean_inherited

_WeeChat ≥ 4.3.0._

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

Prototipo:

[source,c]
----
int weechat_config_boolean_inherited (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

Return value: see functions <<_config_boolean,config_boolean>> and
<<_config_boolean_default,config_boolean_default>>.

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("irc.server.libera.autoconnect");
int autoconnect = weechat_config_boolean_inherited (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_boolean_inherited(option: str) -> int: ...

# esempio
option = weechat.config_get("irc.server.libera.autoconnect")
autoconnect = weechat.config_boolean_inherited(option)
----

==== config_integer

Restituisce il valore intero di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: boolean value of option (0 or 1)
* _integer_: integer value of option
* _string_: 0
* _color_: color index
* _enum_: integer value of option (index of enum value)

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_integer(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)
----

==== config_integer_default

Restituisce il valore intero predefinito di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: default boolean value of option (0 or 1)
* _integer_: default integer value of option
* _string_: 0
* _color_: default color index
* _enum_: default integer value of option (index of enum value)

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_integer_default(option: str) -> int: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)
----

// TRANSLATION MISSING
==== config_integer_inherited

_WeeChat ≥ 4.3.0._

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

Prototipo:

[source,c]
----
int weechat_config_integer_inherited (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

Return value: see functions <<_config_integer,config_integer>> and
<<_config_integer_default,config_integer_default>>.

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("irc.server.libera.autojoin_delay");
int delay = weechat_config_integer_inherited (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_integer_inherited(option: str) -> int: ...

# esempio
option = weechat.config_get("irc.server.libera.autojoin_delay")
delay = weechat.config_integer_inherited(option)
----

==== config_string

Restituisce il valore stringa di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: "on" if value is true, otherwise "off"
* _integer_: NULL
* _string_: string value of option
* _color_: name of color
* _enum_: string value of option

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_string(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)
----

==== config_string_default

Restituisce il valore stringa predefinito di un'opzione.

Prototipo:

[source,c]
----
const char *weechat_config_string_default (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: "on" if default value is true, otherwise "off"
* _integer_: NULL
* _string_: default string value of option
* _color_: name of default color
* _enum_: default string value of option

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_string_default(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)
----

// TRANSLATION MISSING
==== config_string_inherited

_WeeChat ≥ 4.3.0._

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

Prototipo:

[source,c]
----
const char *weechat_config_string_inherited (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

Return value: see functions <<_config_string,config_string>> and
<<_config_string_default,config_string_default>>.

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("irc.server.libera.msg_quit");
const char *msg_quit = weechat_config_string_inherited (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_string_inherited(option: str) -> str: ...

# esempio
option = weechat.config_get("irc.server.libera.msg_quit")
msg_quit = weechat.config_string_inherited(option)
----

==== config_color

Restituisce il valore colore di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: NULL
* _integer_: NULL
* _string_: NULL
* _color_: name of color
* _enum_: NULL

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_color(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
color = weechat.config_color(option)
----

==== config_color_default

Restituisce il valore colore predefinito di un'opzione.

Prototipo:

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

Argomenti:

* _option_: puntatore all'opzione

// TRANSLATION MISSING
Return value, depending on the option type:

* _boolean_: NULL
* _integer_: NULL
* _string_: NULL
* _color_: name of default color
* _enum_:  NULL

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_color_default(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
color = weechat.config_color_default(option)
----

// TRANSLATION MISSING
==== config_color_inherited

_WeeChat ≥ 4.3.0._

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

Prototipo:

[source,c]
----
const char *weechat_config_color_inherited (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

Return value: see functions <<_config_color,config_color>> and
<<_config_color_default,config_color_default>>.

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_inherited (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_color_inherited(option: str) -> str: ...

# esempio
option = weechat.config_get("plugin.section.option")
color = weechat.config_color_inherited(option)
----

// TRANSLATION MISSING
==== config_enum

_WeeChat ≥ 4.1.0._

Return enum value of option, as integer.

Prototype:

[source,c]
----
int weechat_config_enum (struct t_config_option *option);
----

Arguments:

* _option_: option pointer

Return value, depending on the option type:

* _boolean_: boolean value of option (0 or 1)
* _integer_: integer value of option
* _string_: 0
* _color_: color index
* _enum_: integer value of option (index of enum value)

C example:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_enum (option);
----

Script (Python):

[source,python]
----
# prototype
def config_enum(option: str) -> int: ...

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_enum(option)
----

// TRANSLATION MISSING
==== config_enum_default

_WeeChat ≥ 4.1.0._

Return default enum value of option, as integer.

Prototype:

[source,c]
----
int weechat_config_enum_default (struct t_config_option *option);
----

Arguments:

* _option_: option pointer

Return value, depending on the option type:

* _boolean_: default boolean value of option (0 or 1)
* _integer_: default integer value of option
* _string_: 0
* _color_: default color index
* _enum_: integer value of option (index of enum value)

C example:

[source,c]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_enum_default (option);
----

Script (Python):

[source,python]
----
# prototype
def config_enum_default(option: str) -> int: ...

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

// TRANSLATION MISSING
==== config_enum_inherited

_WeeChat ≥ 4.3.0._

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

Prototipo:

[source,c]
----
int weechat_config_enum_inherited (struct t_config_option *option);
----

Argomenti:

* _option_: puntatore all'opzione

Return value: see functions <<_config_enum,config_enum>> and
<<_config_enum_default,config_enum_default>>.

Esempio in C:

[source,c]
----
struct t_config_option *option = weechat_config_get ("irc.server.libera.sasl_fail");
int sasl_fail = weechat_config_enum_inherited (option);
----

Script (Python):

[source,python]
----
# prototipo
def config_enum_inherited(option: str) -> int: ...

# esempio
option = weechat.config_get("irc.server.libera.sasl_fail")
sasl_fail = weechat.config_enum_inherited(option)
----

==== config_write_option

Scrive una riga nel file di configurazione con l'opzione ed il suo valore
(questa funzione dovrebbe essere chiamata solo nelle callback "write"
o "write_default" per una sezione).

Prototipo:

[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 (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_option (config_file, option);

    return WEECHAT_RC_OK;
}
----

Script (Python):

[source,python]
----
# prototipo
def config_write_option(config_file: str, option: str) -> int: ...

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

==== config_write_line

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

Prototipo:

[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 (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);

    return WEECHAT_RC_OK;
}
----

Script (Python):

[source,python]
----
# prototipo
def config_write_line(config_file: str, option_name: str, value: str) -> int: ...

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

==== config_write

Scrive il file di configurazione su disco.

Prototipo:

[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
def config_write(config_file: str) -> int: ...

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

==== config_read

Legge il file di configurazione da disco.

Prototipo:

[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
def config_read(config_file: str) -> int: ...

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

==== config_reload

Ricarica il file di configurazione da disco.

Prototipo:

[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
def config_reload(config_file: str) -> int: ...

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

==== config_option_free

Libera un'opzione.

Prototipo:

[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
def config_option_free(option: str) -> int: ...

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

==== config_section_free_options

Libera tutte le opzioni in una sessione.

Prototipo:

[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
def config_section_free_options(section: str) -> int: ...

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

==== config_section_free

Libera una sezione.

Prototipo:

[source,c]
----
void weechat_config_section_free (struct t_config_section *section);
----

Argomenti:

* _section_: puntatore alla sezione

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def config_section_free(section: str) -> int: ...

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

==== 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
def config_free(config_file: str) -> int: ...

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

==== 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
def config_get(option_name: str) -> str: ...

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

==== config_get_plugin

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

Prototipo:

[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
def config_get_plugin(option_name: str) -> str: ...

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

==== config_is_set_plugin

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

Prototipo:

[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
def config_is_set_plugin(option_name: str) -> int: ...

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

==== config_set_plugin

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

Prototipo:

[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_ in caso di 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
def config_set_plugin(option_name: str, value: str) -> int: ...

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

==== config_set_desc_plugin

_WeeChat ≥ 0.3.5._

Imposta la descrizione per l'opzione nel file di configurazione dei plugin
(plugins.conf).

Prototipo:

[source,c]
----
void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);
----

Argomenti:

* _option_name_: nome dell'opzione, WeeChat aggiungerà il prefisso "plugins.desc.xxx."
  (dove "xxx" è il nome del plugin corrente)
* _description_: descrizione per l'opzione

[NOTE]
Non è un problema se l'opzione (plugins.var.xx.option_name) non esiste.
Una futura creazione dell'opzione con questo nome userà questa descrizione.

Esempio in C:

[source,c]
----
weechat_config_set_desc_plugin ("option", "description of option");
----

Script (Python):

[source,python]
----
# prototipo
def config_set_desc_plugin(option_name: str, description: str) -> int: ...

# esempio
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")
----

==== config_unset_plugin

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

Prototipo:

[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_ in caso di 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
def config_unset_plugin(option_name: str) -> int: ...

# esempio
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----

[[key_bindings]]
=== Combinazione tasti

Funzioni per le combinazioni dei tasti.

==== key_bind

// TRANSLATION MISSING
_WeeChat ≥ 0.3.6, updated in 1.8._

Aggiunge una nuova combinazione tasto.

[NOTE]
A differenza del comando `/key bind`, questa funzione non cambia mai una
combinazione tasti esistente, ma ne vengono create di nuove. Per rimuovere
una combinazione tasti, usare <<_key_unbind,key_unbind>>.

Prototipo:

[source,c]
----
int weechat_key_bind (const char *context, struct t_hashtable *keys);
----

:key_bind_quiet: __quiet

Argomenti:

* _context_: contesto per i tasti:
** _default_: contesto default (azioni comuni)
** _search_: contesto search (quando si cerca testo nel buffer)
** _cursor_: movimento libero del cursore sullo schermo
** _mouse_: tasti per gli eventi del mouse
// TRANSLATION MISSING
* _keys_: hashtable with key bindings; it can contain following special keys:
** _{key_bind_quiet}_: do not display the keys added in _core_ buffer
   _(WeeChat ≥ 1.8)_

Valore restituito:

* numero delle combinazioni tasti aggiunte

Esempio in C:

[source,c]
----
struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}
----

Script (Python):

[source,python]
----
# prototipo
def key_bind(context: str, keys: Dict[str, str]) -> int: ...

# esempio
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)
----

==== key_unbind

_WeeChat ≥ 0.3.6, updated in 2.0._

Rimuove una o più associazioni tasti.

[CAUTION]
Alla chiamata di questa funzione, assicurarsi che non venga rimossa una
combinazione tasti definita dall'utente.

Prototipo:

[source,c]
----
int weechat_key_unbind (const char *context, const char *key);
----

Argomenti:

* _context_: contesto per i tasti (consultare <<_key_bind,key_bind>>)
// TRANSLATION MISSING
* _key_: tasto da rimuovere o un valore speciale "area:XXX" per rimuovere tutti
  i tasti che hanno _XXX_ come prima o seconda area; if the key starts with
  "quiet:", the keys removed are not displayed in _core_ buffer _(WeeChat ≥ 2.0)_.

Valore restituito:

* numero di combinazioni tasti rimosse

Esempio in C:

[source,c]
----
/* rimuove un singolo tasto */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* rimuove tutti i tasti con la zona "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");
----

Script (Python):

[source,python]
----
# prototipo
def key_unbind(context: str, key: str) -> int: ...

# esempi

# rimuove un singolo tasto
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# rimuove tutti i tasti con la zona "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")
----

[[display]]
=== Visualizzazione

Funzioni per visualizzare il testo nei buffer.

==== prefix

Restituisce un prefisso.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _prefix_: nome del prefisso, see table below

Valore restituito:

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

// TRANSLATION MISSING
List of prefixes:

[width="100%",cols="^2m,^1,^3,5",options="header"]
|===
| Prefisso | Valore   | Colore       | Descrizione
| error    | `+=!=+`  | giallo       | Messaggio di errore.
| network  | `+--+`   | magenta      | Messaggio dalla rete.
| action   | `+*+`    | bianco       | Azione automatica.
| join     | `+-->+`  | verde chiaro | Qualcuno entra nella chat corrente.
| quit     | `+<--+`  | rosso chiaro | Qualcuno lascia la chat corrente.
|===

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

Esempio in C:

[source,c]
----
weechat_printf (NULL, "%sQuesto è un errore...", weechat_prefix ("error"));
----

Script (Python):

[source,python]
----
# prototipo
def prefix(prefix: str) -> str: ...

# esempio
weechat.prnt("", "%sQuesto è un errore..." % weechat.prefix("error"))
----

==== color

Restituisce una codice colore stringa da visualizzare.

Prototipo:

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

Argomenti:

* _color_name_: nome del colore, uno di:
// TRANSLATION MISSING
** WeeChat color option name (from weechat.color.xxx), for example
   _chat_delimiters_
// TRANSLATION MISSING
** option name (format: file.section.option), for example
   _irc.color.message_quit_ _(WeeChat ≥ 1.2)_
** colore con attributi/sfondo opzionali (vedi sotto)
** attributo:
// TRANSLATION MISSING
*** _blink_: set blink
// TRANSLATION MISSING
*** _-blink_: remove blink
// TRANSLATION MISSING
*** _dim_: set "dim" (half bright)
// TRANSLATION MISSING
*** _-dim_: remove "dim" (half bright)
*** _bold_: imposta grassetto
*** _-bold_: rimuove grassetto
*** _reverse_: imposta inverso
*** _-reverse_: rimuove inverso
*** _italic_: imposta corsivo
*** _-italic_: rimuove corsivo
*** _underline_: imposta sottolineato
*** _-underline_: rimuove sottolineato
// TRANSLATION MISSING
*** _emphasis_: toggle the emphasis for text (note: this should be used only in
    bars, because WeeChat uses text emphasis when searching text in buffer)
    _(WeeChat ≥ 0.4.2)_
** nome colore della barra:
*** _bar_fg_: colore di primo piano della barra
*** _bar_delim_: colore dei delimitatori della barra
*** _bar_bg_: colore di sfondo della barra
** reset:
*** _reset_: ripristina colore ed attributi
*** _resetcolor_: ripristina colore (mantiene attributi) _(WeeChat ≥ 0.3.6)_

Il formato del colore è: attributi (opzionale) + nome colore +",sfondo"
(opzionale). Gli attributi possibili sono:

// TRANSLATION MISSING
* `+%+`: blink
// TRANSLATION MISSING
* `+.+`: "dim" (half bright)
* `+*+` : testo in grassetto
* `+!+` : video inverso
* `+/+` : corsivo
* `+_+` : testo sottolineato
* `+|+` : mantiene attributi: non ripristina
  grassetto/inverso/corsivo/sottolineato al cambio di colore _(WeeChat ≥ 0.3.6)_

Esempi:

* `+yellow+` : giallo
* `+_green+` : verde sottolineato
* `+*214+` : arancione grassetto
* `+yellow,red+` : giallo su rosso
* `+|cyan+` : ciano (e mantiene qualsiasi attributo impostato in precedenza)

Valore restituito:

* stringa con il codice colore, o una stringa vuota se non trovata

Esempio in C:

[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
def color(color_name: str) -> str: ...

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

==== printf

Visualizza un messaggio su un buffer.

Prototipo:

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

// TRANSLATION MISSING
This function is a shortcut for function printf_datetime_tags. +
These two calls give exactly same result:

[source,c]
----
weechat_printf (buffer, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");
----

Argomenti:

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

[NOTE]
La prima tabulazione nel messaggio ("\t") è usata per separare il prefisso dal messaggio. +
Se il proprio messaggio ha alcune tabulazioni e non si vuole il prefisso, allora
bisogna utilizzare uno spazio, una tabulazione, poi il messaggio (consultare
l'esempio successivo): ciò disabilita il prefisso (lo spazio prima della
tabulazione non verrà mostrato).

// TRANSLATION MISSING
[NOTE]
With two tabs ("\t") at beginning of message, time will not be displayed and
message will have no alignment at all. Moreover, the date in message will be
set to 0.

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
weechat_printf (NULL, "Benvenuto sul buffer di WeeChat");
weechat_printf (buffer, "Benvenuto su questo buffer");
weechat_printf (buffer, "%sQuesto è un errore!", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni");
weechat_printf (buffer, "\t\tMessage without time/alignment");
weechat_printf (buffer, "\t\t");  /* empty line (without time) */
----

Script (Python):

// TRANSLATION MISSING
[source,python]
----
# prototipo
def prnt(buffer: str, message: str) -> int: ...

# esempio
weechat.prnt("", "Benvenuto sul buffer di WeeChat")
weechat.prnt(buffer, "Benvenuto su questo buffer")
weechat.prnt(buffer, "%sQuesto è un errore!" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni")
weechat.prnt(buffer, "\t\tMessage without time/alignment")
weechat.prnt(buffer, "\t\t")  # empty line (without time)
----

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

==== 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, ...);
----

// TRANSLATION MISSING
This function is a shortcut for function printf_datetime_tags. +
These two calls give exactly same result:

[source,c]
----
weechat_printf_date_tags (buffer, 0, NULL, "message");
weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");
----

Argomenti:

* _buffer_: puntatore al buffer, se NULL il messaggio viene visualizzato
  sul buffer di WeeChat
* _date_: data per il messaggio (0 indica data/ora corrente)
// TRANSLATION MISSING
* _tags_: lista di tag separati da virgole (NULL means no tags)
* _message_: messaggio da visualizzare

// TRANSLATION MISSING
See the link:weechat_user.it.html#lines_tags[WeeChat user's guide / Lines tags ^↗^^]
for a list of commonly used tags in WeeChat.

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
def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ...

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

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

==== printf_datetime_tags

_WeeChat ≥ 4.2.0._

// TRANSLATION MISSING
Display a message on a buffer, using a custom date/time (with microseconds)
and tags.

Prototipo:

[source,c]
----
void weechat_printf_datetime_tags (struct t_gui_buffer *buffer, time_t date,
                                   int date_usec, const char *tags, const char *message, ...);
----

Argomenti:

* _buffer_: puntatore al buffer, se NULL il messaggio viene visualizzato
  sul buffer di WeeChat
* _date_: data per il messaggio (0 indica data/ora corrente)
// TRANSLATION MISSING
* _date_usec_: microseconds of date (between 0 and 999999)
// TRANSLATION MISSING
* _tags_: lista di tag separati da virgole (NULL means no tags)
* _message_: messaggio da visualizzare

// TRANSLATION MISSING
See the link:weechat_user.it.html#lines_tags[WeeChat user's guide / Lines tags ^↗^^]
for a list of commonly used tags in WeeChat.

Esempio in C:

[source,c]
----
struct timeval tv_now;

gettimeofday (&tv_now, NULL);
weechat_printf_datetime_tags (NULL, tv_now.tv_sec - 120, tv_now.tv_usec,
                              "notify_message",
                              "Messaggio 2 minuti fa, con tag 'notify_message'");
----

Script (Python):

[source,python]
----
# prototipo
def prnt_datetime_tags(buffer: str, date: int, date_usec: int, tags: str, message: str) -> int: ...

# esempio
now = time.time()
time_sec = int(now)
time_usec = int((now * 1000000) % 1000000)
weechat.prnt_datetime_tags("", time_sec - 120, time_usec, "notify_message",
                           "Messaggio 2 minuti fa, con tag 'notify_message'")
----

[NOTE]
La funzione è chiamata "print_datetime_tags" negli script ("prnt_datetime_tags" in Python).

==== printf_y

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

Prototipo:

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

// TRANSLATION MISSING
This function is a shortcut for function printf_y_datetime_tags. +
These two calls give exactly same result:

[source,c]
----
weechat_printf_y (buffer, 0, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");
----

Argomenti:

* _buffer_: puntatore al buffer
// TRANSLATION MISSING
* _y_: numero di riga (la prima riga è 0); a negative value adds a line after
  last line displayed: absolute value of _y_ is the number of lines after last
  line (for example -1 is immediately after last line, -2 is 2 lines after last
  line) _(WeeChat ≥ 1.0)_
* _message_: messaggio da visualizzare

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def prnt_y(buffer: str, y: int, message: str) -> int: ...

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

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

==== printf_y_date_tags

_WeeChat ≥ 3.5._

// TRANSLATION MISSING
Display a message on a line of a buffer with free content, using a custom
date and tags.

Prototipo:

[source,c]
----
void weechat_printf_y_date_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                 const char *tags, const char *message, ...);
----

// TRANSLATION MISSING
This function is a shortcut for function printf_y_datetime_tags. +
These two calls give exactly same result:

[source,c]
----
weechat_printf_y_date_tags (buffer, 0, 0, NULL, "message");
weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");
----

Argomenti:

* _buffer_: puntatore al buffer
// TRANSLATION MISSING
* _y_: numero di riga (la prima riga è 0); a negative value adds a line after
  last line displayed: absolute value of _y_ is the number of lines after last
  line (for example -1 is immediately after last line, -2 is 2 lines after last
  line)
* _date_: data per il messaggio (0 indica data/ora corrente)
// TRANSLATION MISSING
* _tags_: lista di tag separati da virgole (NULL means no tags)
* _message_: messaggio da visualizzare

Esempio in C:

[source,c]
----
weechat_printf_y_date_tags (buffer, 2, 0, "my_tag", "My message on third line with a tag");
----

Script (Python):

[source,python]
----
# prototipo
def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ...

# esempio
weechat.prnt_y_date_tags("", 2, 0, "my_tag", "My message on third line with a tag")
----

[NOTE]
La funzione è chiamata "print_y_date_tags" negli script ("prnt_y_date_tags in Python).

==== printf_y_datetime_tags

_WeeChat ≥ 4.2.0._

// TRANSLATION MISSING
Display a message on a line of a buffer with free content, using a custom
date/time (with microseconds) and tags.

Prototipo:

[source,c]
----
void weechat_printf_y_datetime_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                     int date_usec, const char *tags, const char *message, ...);
----

Argomenti:

* _buffer_: puntatore al buffer
// TRANSLATION MISSING
* _y_: numero di riga (la prima riga è 0); a negative value adds a line after
  last line displayed: absolute value of _y_ is the number of lines after last
  line (for example -1 is immediately after last line, -2 is 2 lines after last
  line)
* _date_: data per il messaggio (0 indica data/ora corrente)
// TRANSLATION MISSING
* _date_usec_: microseconds of date (between 0 and 999999)
// TRANSLATION MISSING
* _tags_: lista di tag separati da virgole (NULL means no tags)
* _message_: messaggio da visualizzare

Esempio in C:

[source,c]
----
weechat_printf_y_datetime_tags (buffer, 2, 0, 0, "my_tag", "My message on third line with a tag");
----

Script (Python):

[source,python]
----
# prototipo
def prnt_y_datetime_tags(buffer: str, y: int, date: int, date_usec: int, tags: str, message: str) -> int: ...

# esempio
weechat.prnt_y_datetime_tags("", 2, 0, 0, "my_tag", "My message on third line with a tag")
----

[NOTE]
La funzione è chiamata "print_y_datetime_tags" negli script ("prnt_y_datetime_tags in Python).

==== log_printf

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

Prototipo:

[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
def log_print(message: str) -> int: ...

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

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

[[hooks]]
=== Hook

[[hook_priority]]
[float]
==== Priorità degli hook

_WeeChat ≥ 0.3.4._

In alcuni hook è possibile impostare una priorità. Un hook con priorità
maggiore si trova all'inizio della lista, in modo da poter essere eseguita
prima di altri. Può risultare utile per i modificatori, data l'importanza
nell'ordine di esecuzione.

Per impostare la priorità, è necessario usare questa sintassi per gli
argomenti dove è consentita la priorità: `nnn|nome` dove `nnn` è un intero non
negativo con la priorità e `nome` è il nome per l'argomenti (la priorità non
compare nel nome, viene rimossa automaticamente dalla stringa). +
// TRANSLATION MISSING
Only a single priority per hook is allowed.

La priorità predefinita è 1000.

// TRANSLATION MISSING
C examples:

// TRANSLATION MISSING
[source,c]
----
/* hook per il modificatore con priorità = 2000 */
/* high priority: called before other modifier callbacks */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

/* hook two signals with priority = 3000 */
/* high priority: called before other signal callbacks */
weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL);

/* hook lines printed in formatted buffers with priority = 500 */
/* low priority: called after other line callbacks */
weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL);
----

I tipi di hook che seguono consentono la priorità:

* <<_hook_command,command>>
* <<_hook_completion,completion>>
* <<_hook_command_run,command_run>>
* <<_hook_line,line>>
* <<_hook_signal,signal>>
* <<_hook_hsignal,hsignal>>
* <<_hook_config,config>>
* <<_hook_modifier,modifier>>
* <<_hook_info,info>>
* <<_hook_info_hashtable,info_hashtable>>
* <<_hook_infolist,infolist>>
* <<_hook_hdata,hdata>>
* <<_hook_focus,focus>>

==== hook_command

// TRANSLATION MISSING
_Updated in 1.5._

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)(const void *pointer,
                                                     void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _command_: nome del comando
  (a priority is allowed before the command, see note about <<hook_priority,priority>>)
* _description_: descrizione per il comando (visualizzata con `/help comando`)
* _args_: argomenti per il comando (visualizzati con `/help command`)
* _args_description_: descrizione degli argomenti (visualizzata con `/help command`)
* _completion_: modello di completamento per il comando:: elenco di completamenti
  per ogni argomento, separati da spazio. Sono possibili più  completamenti sono
  possibili per un singolo argomento, separati da `+|+`. Più modelli sono possibili per
  lo stesso comando, separati da `+||+`.
* _callback_: funzione chiamata quando viene utilizzato il comando, argomenti e
  valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: buffer quando il comando viene eseguito
** _int argc_: numero di argomenti forniti per un comando
** _char **argv_: argomenti forniti per un comando
** _char **argv_eol_: argomenti forniti per un comando (fino a fine riga per ogni
   argomento)
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito dalla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

I codici predefiniti per il completamento sono:

include::{autogendir}/autogen_api_completions.it.adoc[tag=completions]

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 (const void *pointer, void *data, struct t_gui_buffer *buffer,
               int argc, char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* questo esempio si ispira al comando /filter */
struct t_hook *my_command_hook =
    weechat_hook_command ("myfilter",
                          "description of myfilter",
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          "description of arguments...",
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          &my_command_cb, NULL, NULL);
----

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

* _argv_:
** _argv[0]_ == "/command"
** _argv[1]_ == "abc"
** _argv[2]_ == "def"
** _argv[3]_ == "ghi"
* _argv_eol_:
** _argv_eol[0]_ == "/command abc def ghi"
** _argv_eol[1]_ == "abc def ghi"
** _argv_eol[2]_ == "def ghi"
** _argv_eol[3]_ == "ghi"

Per gli script, _args_ ha valore "abc def ghi".

Script (Python):

[source,python]
----
# prototipo
def hook_command(command: str, description: str, args: str, args_description: str,
                 completion: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_command_cb(data: str, buffer: str, args: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "descrizione di myfilter",
    "[list] | [enable|disable|toggle [name]] | "
    "[add name plugin.buffer tags regex] | "
    "[del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")
----

==== hook_completion

// TRANSLATION MISSING
_Updated in 1.5._

Hook su un completamento.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _completion_item_: nome dell'elemento del completamento, è possibile usare
  in seguito _%(name)_ in un comando con un hook (argomento _completion_)
  (a priority is allowed before the completion item, see note about <<hook_priority,priority>>)
* _callback_: funzione chiamata quando viene usato l'elemento completamento
  (l'utente sta completando qualcosa usando questo elemento), argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *completion_item_: nome dell'elemento del completamento
** _struct t_gui_buffer *buffer_: buffer dove viene eseguito il completamento
** _struct t_gui_completion *completion_: struttura usata per aggiungere
   parole per il completamento (consultare <<_completion_list_add,completion_list_add>>)
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

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

// TRANSLATION MISSING
[IMPORTANT]
The callback must only call completion functions like
<<_completion_list_add,completion_list_add>> and must *NOT* update the command line. +
To update the command line when kbd:[Tab] is pressed, you can use the function
<<_hook_command_run,hook_command_run>> with command:
`+/input complete_next+` (and you must return _WEECHAT_RC_OK_EAT_ if your callback
has updated the command line, so that WeeChat will not perform the completion).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

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

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

Script (Python):

[source,python]
----
# prototipo
def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    weechat.completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

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

// TRANSLATION MISSING
==== hook_completion_get_string

_Novità nella versioe 0.3.4._

*Deprecated since WeeChat 2.9* (still there for compatibility). +
This function has been replaced by <<_completion_get_string,completion_get_string>>.

// TRANSLATION MISSING
==== hook_completion_list_add

*Deprecated since WeeChat 2.9* (still there for compatibility). +
This function has been replaced by <<_completion_list_add,completion_list_add>>.

==== hook_command_run

// TRANSLATION MISSING
_Updated in 1.5._

Hook su un comando quando eseguito da WeeChat.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _command_: comando su cui eseguire l'hook (wildcard `+*+` is allowed)
  (a priority is allowed before the command, see note about <<hook_priority,priority>>)
* _callback_: funzione chiamata quando il comando è in esecuzione, argomenti e
  valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: buffer dove viene eseguito il comando
** _const char *command_: il comando eseguito, con i propri argomenti
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_OK_EAT_: il comando non verrà eseguito da WeeChat dopo la callback
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

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

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

Script (Python):

[source,python]
----
# prototipo
def hook_command_run(command: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_command_run_cb(data: str, buffer: str, command: str) -> int:
    weechat.prnt("", "Sto mangiando il completamento!")
    return weechat.WEECHAT_RC_OK_EAT

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

==== hook_timer

// TRANSLATION MISSING
_Updated in 1.5._

Hook sul timer.

Prototipo:

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

Argomenti:

* _interval_: intervallo tra due chiamate (millisecondi, 1000 = 1 secondo)
// TRANSLATION MISSING
* _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 0
// TRANSLATION MISSING
* _max_calls_: number of calls to timer (if 0, then timer has no end)
// TRANSLATION MISSING
* _callback_: function called when time is reached, argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _int remaining_calls_: remaining calls (-1 if timer has no end)
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
int
my_timer_cb (const void *pointer, 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, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_timer(interval: int, align_second: int, max_calls: int, callback: str, callback_data: str) -> str: ...

# esempio
def my_timer_cb(data: str, remaining_calls: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# timer chiamato ogni 20 secondi
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
----

==== hook_fd

// TRANSLATION MISSING
_Updated in 1.3, 1.5, 2.0._

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)(const void *pointer,
                                                void *data,
                                                int fd),
                                const void *callback_pointer,
                                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
// TRANSLATION MISSING
* _flag_exception_: 1 = cattura l'eccezione evento (event), 0 = ignora
  (_WeeChat ≥ 1.3_: this argument is ignored and not used anymore)
* _callback_: funzione che chiama un evento selezionato che si verifica
  per un file (o un socket), argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _int fd_: descrittore file
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

// TRANSLATION MISSING
[IMPORTANT]
In scripts, with WeeChat ≥ 2.0, the callback argument _fd_ is an integer
(with WeeChat ≤ 1.9, it was a string). +
To be compatible with all versions, it is recommended to convert the argument
to integer before using it, for example in Python: `int(fd)`.

Esempio in C:

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

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* imposta le opzioni del socket */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_fd(fd: int, flag_read: int, flag_write: int, flag_exception: int, callback: str, callback_data: str) -> str: ...

# esempio
def my_fd_cb(data: str, fd: int) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

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

==== hook_process

// TRANSLATION MISSING
_Updated in 1.5._

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

[NOTE]
// TRANSLATION MISSING
Since version 0.3.9.2, the shell is not used anymore to execute the command.
WeeChat makes an automatic split of command and arguments (like the shell does).
If the split is not correct (according to quotes in your command), or if you
want to use shell, you can use function
<<_hook_process_hashtable,hook_process_hashtable>> with
arguments in the hashtable _options_ _(WeeChat ≥ 0.4.0)_.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _command_: command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or
  function _(WeeChat ≥ 1.5)_ (see below)
* _timeout_: timeout per il comando (in millisecondi): dopo questo timeout,
  il processo figlio viene terminato (0 indica nessun timeout)
* _callback_: funzione chiamata quando i dati dal processo figlio sono disponibili,
  oppure quando è terminato, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *command_: comando eseguito dal processo figlio
** _int return_code_: codice restituito:
*** _≥ 0_: codice ritorno figlio per un comando, e per un URL i valori
    possibili sono:
**** _0_: trasferimento riuscito
**** _1_: URL non valido
**** _2_: errore di trasferimento
**** _3_: memoria non sufficiente
**** _4_: errore con un file
*** _< 0_:
**** _WEECHAT_HOOK_PROCESS_RUNNING_ (-1): dati disponibili, ma figlio ancora in
     esecuzione
**** _WEECHAT_HOOK_PROCESS_ERROR_ (-2): errore nella esecuzione del comando
// TRANSLATION MISSING
**** _WEECHAT_HOOK_PROCESS_CHILD_ (-3): callback is called in the child process
     (used only in C API, not scripting API)
** _out_: output standard del comando (stdout)
** _err_: output di errore del comando (stderr)
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
// TRANSLATION MISSING
*** child process return code (in case of function with "func:" in command)
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Quando il comando ha terminato, o se viene raggiunto il timeout, WeeChat
effettua automaticamente l'unhook (e termina il processo se ancora in esecuzione).

Il comando può essere un URL con il formato: "url:https://www.example.com", per
scaricare il contenuto dell'URL _(WeeChat ≥ 0.3.7)_. Le opzioni per
un URL sono disponibili con la funzione
<<_hook_process_hashtable,hook_process_hashtable>>.

// TRANSLATION MISSING
The command can also be a function name with format: "func:name", to execute
the function "name" _(WeeChat ≥ 1.5)_. This function receives a single argument
(_data_) and must return a string, which is sent to the callback. +
In C API, the callback is called with the return code set to
_WEECHAT_HOOK_PROCESS_CHILD_, which means the callback is running in the child
process (after fork). +
In scripting API, the function _name_ is called directly and its result
(string) is sent to the callback (like the output of an external command).

[TIP]
// TRANSLATION MISSING
If you want to retrieve infos about WeeChat (like current stable version,
latest git commit, etc.), you can use URLs on
https://weechat.org/dev/info/[this page ^↗^^].

[NOTE]
La dimensione del buffer per l'invio dei dati alla callback è di 64KB (ci sono
2 buffer: uno per stdout ed uno per stderr).
Se l'output che viene da un processo figlio (stdout o stderr) è più lungo di
64KB, la callback verrà chiamata più di una volta.

[IMPORTANT]
Anche se la maggior parte delle volte la callback viene chiamata una sola volta,
ci si deve assicurare che più chiamate alla callback siano corrette nel codice:
bisogna concatenare i dati forniti da più chiamate ed utilizzarli quando il
codice restituito è non-negativo.

Esempio in C:

[source,c]
----
/* example with an external command */
int
my_process_cb (const void *pointer, void *data, const char *command,
               int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Errore con il comando '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

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

/* example with the callback called in the child process */
int
my_process_func_cb (const void *pointer, void *data, const char *command,
                    int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
    {
        /* do something blocking... */
        /* ... */

        /* the stdout will be sent as "out" in the parent callback */
        printf ("this is the result");

        /* return code of the process */
        return 0;
    }
    else
    {
        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 ("func:get_status", 5000,
                                                       &my_process_func_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_process(command: str, timeout: int, callback: str, callback_data: str) -> str: ...

# example with an external command
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "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", "")

# example with a script function
def get_status(data: str) -> str:
    # do something blocking...
    # ...
    return "this is the result"

def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "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("func:get_status", 5000, "my_process_cb", "")
----

==== hook_process_hashtable

// TRANSLATION MISSING
_WeeChat ≥ 0.3.7, updated in 1.5._

Hook su un processo (avviato con un fork) usando le opzioni nella tabella hash,
e cattura dell'output.

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(const void *pointer,
                                                               void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               const void *callback_pointer,
                                               void *callback_data);
----

Gli argomenti sono gli stessi della funzione
<<_hook_process,hook_process>>, con un argomento aggiuntivo:

* _options_: le opzioni per il comando eseguito; la tabella hash è duplicata
  nella funzione, per cui è possibile liberarla dopo questa chiamata

// TRANSLATION MISSING
For a standard command (not beginning with "url:"), following options are
available:

// TRANSLATION MISSING
[width="100%",cols="^1,^1,1,1,5",options="header"]
|===
| Option | Min WeeChat | Value | Default | Description

// TRANSLATION MISSING
| argN (N ≥ 1) | 0.4.0 | any string | no arguments
| Arguments for command; if no argument is given with these options,
  the command is automatically split like the shell does (and then command
  arguments are read in the _command_ argument).

// TRANSLATION MISSING
| stdin | 0.4.3 | (not used) | no stdin
| Create a pipe for writing data on standard input (stdin) of child process
  (see function <<_hook_set,hook_set>>).

// TRANSLATION MISSING
| buffer_flush | 1.0 | number of bytes | 65536
| Minimum number of bytes to flush stdout/stderr (to send output to callback),
  between 1 and 65536. With the value 1, the output is sent immediately to the
  callback.

// TRANSLATION MISSING
| detached | 1.0 | (not used) | not detached
| Run the process in a detached mode: stdout and stderr are redirected to
  _/dev/null_.
|===

// TRANSLATION MISSING
For command "url:...", see available options in function <<_hook_url,hook_url>>.

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
int
my_process_cb (const void *pointer, void *data, const char *command,
               int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "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;
}

/* example 1: download URL */
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                     options_url1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* example 2: open URL with custom HTTP headers */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: value1\n"
                           "Header2: value2");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://localhost:8080/",
                                                                     options_url2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}

/* example 3: execute a notify program with a message from someone */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message);  /* unsafe argument */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* example 4: call shell to execute a command (command must be SAFE) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd2);
}
----

Script (Python):

[source,python]
----
# prototipo
def hook_process_hashtable(command: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# esempio
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "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

# example 1: download URL
hook1 = weechat.hook_process_hashtable("url:https://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# example 2: open URL with custom HTTP headers
options = {
    "httpheader": "\n".join([
        "Header1: value1",
        "Header2: value2",
    ]),
}
hook2 = weechat.hook_process_hashtable("url:http://localhost:8080/",
                                       options,
                                       20000, "my_process_cb", "")

# example 3: execute a notify program with a message from someone
hook3 = weechat.hook_process_hashtable("my-notify-command",
                                       {"arg1": "-from",
                                        "arg2": nick,
                                        "arg3": "-msg",
                                        "arg4": message},  # unsafe argument
                                       20000, "my_process_cb", "")

# example 4: call shell to execute a command (command must be SAFE)
hook4 = weechat.hook_process_hashtable("sh",
                                       {"arg1": "-c",
                                        "arg2": "ls -l /tmp | grep something"},
                                       20000, "my_process_cb", "")
----

// TRANSLATION MISSING
==== hook_url

_WeeChat ≥ 4.1.0._

URL transfer.

This function is similar to <<_hook_process,hook_process>> and
<<_hook_process_hashtable,hook_process_hashtable>> with command "url:..."
but it uses a thread instead of a new process, making it more lightweight
and thus recommended for this usage.

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_url (const char *url,
                                 struct t_hashtable *options,
                                 int timeout,
                                 int (*callback)(const void *pointer,
                                                 void *data,
                                                 const char *url,
                                                 struct t_hashtable *options,
                                                 struct t_hashtable *output),
                                 const void *callback_pointer,
                                 void *callback_data);
----

Argomenti:

* _url_: URL
* _options_: options for URL transfer (see below); la tabella hash è duplicata
  nella funzione, per cui è possibile liberarla dopo questa chiamata
* _timeout_: timeout for URL transfer (in milliseconds): after this timeout,
  the transfer is stopped (0 means no timeout)
* _callback_: function called when the transfer has ended, arguments and return
  value:
** _const void *pointer_: pointer
** _void *data_: pointer
** _const char *url_: URL
** _struct t_hashtable *options_: options
** _struct t_hashtable *output_: result (keys and values are strings), which may
   contain the following keys:
*** _response_code_: HTTP response code
*** _headers_: HTTP headers in response
*** _output_: standard output (set only if _file_out_ was not set in options)
*** _error_: error message (set only in case of error)
*** _error_code_: error code (integer, set only in case of error):
**** `1`: invalid URL
**** `2`: transfer error (Curl error)
**** `3`: not enough memory
**** `4`: file error
**** `5`: transfer stopped (hook removed during the transfer)
**** `6`: transfer timeout
**** `100`: thread creation error
*** _error_code_pthread_: return code of function _pthread_create_
    (integer, set only if _error_code_ is `100`)
** return value:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

The following Curl options are available (see `+man curl_easy_setopt+` for
a description of each option):

include::{autogendir}/autogen_api_url_options.it.adoc[tag=url_options]

// TRANSLATION MISSING
[NOTE]
^(1)^ Per le opzioni con il tipo "mask" il formato è: "value1+value2+value3";
for options with type "list", the list items must be separated by a newline
(`\n`). +
^(2)^ Quando sono disponibili le costanti, esse vanno usate come valore per
l'opzione.

These two extra options (strings) are allowed for input/output file:

[width="100%",cols="2,^1,7",options="header"]
|===
| Option   | Type   | Description
| file_in  | string | file da leggere e inviare con gli URL (invio del file "post")
| file_out | string | scrive URL scaricato/file in questo file (invece dello standard output)
|===

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
int
my_url_cb (const void *pointer, void *data, const char *url,
           struct t_hashtable *options, struct t_hashtable *output)
{
    weechat_printf (NULL, "response_code: %s", weechat_hashtable_get (output, "response_code"));
    weechat_printf (NULL, "headers: %s", weechat_hashtable_get (output, "headers"));
    weechat_printf (NULL, "output: %s", weechat_hashtable_get (output, "output"));
    weechat_printf (NULL, "error: %s", weechat_hashtable_get (output, "error"));
    return WEECHAT_RC_OK;
}

/* example 1: output to a file */
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url1)
{
    weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_url_hook = weechat_hook_url ("https://weechat.org/",
                                                   options_url1,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url1);
}

/* example 2: custom HTTP headers, output sent to callback */
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_url2)
{
    weechat_hashtable_set (options_url2, "httpheader",
                           "Header1: value1\n"
                           "Header2: value2");
    struct t_hook *my_url_hook = weechat_hook_url ("http://localhost:8080/",
                                                   options_url2,
                                                   20000,
                                                   &my_url_cb, NULL, NULL);
    weechat_hashtable_free (options_url2);
}
----

Script (Python):

[source,python]
----
# prototipo
def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

# esempio
def my_url_cb(data: str, url: str, options: Dict[str, str], output: Dict[str, str]) -> int:
    weechat.prnt("", "output: %s" % output)
    return weechat.WEECHAT_RC_OK

# example 1: output to a file
hook1 = weechat.hook_url("https://weechat.org/",
                         {"file_out": "/tmp/weechat.org.html"},
                         20000, "my_url_cb", "")

# example 2: custom HTTP headers, output sent to callback
options = {
    "httpheader": "\n".join([
        "Header1: value1",
        "Header2: value2",
    ]),
}
hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "")
----

==== hook_connect

// TRANSLATION MISSING
_Updated in 1.5, 2.0, 4.4.0._

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 ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Argomenti:

* _proxy_: nome del proxy da utilizzare per la connessione (opzionale,
  NULL significa connessione senza proxy)
* _address_: nome o indirizzo IP al quale connettersi
* _port_: numero della porta
// TRANSLATION MISSING
* _ipv6_:
// TRANSLATION MISSING
** `WEECHAT_HOOK_CONNECT_IPV6_DISABLE` ^(1)^: disable IPv6 (use only IPv4)
// TRANSLATION MISSING
** `WEECHAT_HOOK_CONNECT_IPV6_AUTO` ^(1)^: use IPv6 with fallback to IPv4
// TRANSLATION MISSING
** `WEECHAT_HOOK_CONNECT_IPV6_FORCE` ^(1)^: force IPv6 (do not use IPv4) _(WeeChat ≥ 4.4.0)_
// TRANSLATION MISSING
* _retry_: retry count, used to fallback to IPv4 hosts if IPv6 hosts connect
  but then fail to accept the client
* _gnutls_sess_: sessione GnuTLS (opzionale)
* _gnutls_cb_ callback GnuTLS (opzionale)
* _gnutls_dhkey_size_: dimensione della chiave utilizzata nello Scambio
  Chiavi Diffie-Hellman (GnuTLS)
* _gnutls_priorities_: priorità per gnutls (per la sintassi, consultare la
  documentazione della funzione _gnutls_priority_init_ nel manuale di gnutls), i
  valori di base sono:
** _PERFORMANCE_
** _NORMAL_ (predefinito)
** _SECURE128_
** _SECURE256_
** _EXPORT_
** _NONE_
* _local_hostname_: nome host locale da utilizzare per la connessione
  (opzionale)
* _callback_: funzione chiamata quando la connessione è avvenuta con
  successo oppure no, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _int status_: stato della connessione ^(2)^:
*** _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
*** _WEECHAT_HOOK_CONNECT_TIMEOUT_: timeout
*** _WEECHAT_HOOK_CONNECT_SOCKET_ERROR_: errore nella creazione socket
** _gnutls_rc_: valore del risultato di _gnutls_handshake()_ ^(2)^
** _sock_: socket utilizzato per la connessione ^(2)^
** _const char *error_: valore del risultato di _gnutls_strerror(gnutls_rc)_
** _const char *ip_address_: indirizzo IP trovato
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

// TRANSLATION MISSING
[NOTE]
^(1)^ Constants for parameter _ipv6_ are available since WeeChat 4.4.0. +
For older releases, allowed values are `1` (use IPv6 with fallback to IPv4) and
`0` (disable IPv6, use only IPv4). +
^(2)^ In scripts, with WeeChat ≥ 2.0, the callback arguments _status_, _gnutls_rc_
and _sock_ are integers (with WeeChat ≤ 1.9, they were strings). +
To be compatible with all versions, it is recommended to convert the argument
to integer before using it, for example in Python: `int(sock)`.

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

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

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

Script (Python):

[source,python]
----
# prototipo
def hook_connect(proxy: str, address: str, port: int, ipv6: int, retry: int, local_hostname: str,
                 callback: str, callback_data: str) -> str: ...

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

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

// TRANSLATION MISSING
==== hook_line

_WeeChat ≥ 2.3, updated in 4.2.0._

Hook a line to be printed in a buffer.

When a line is printed in a buffer, hooks are called in this order:

* <<_hook_line,hook line>> (this hook): it can change the buffer, prefix,
  message, tags, notify level, … (see below)
* <<_hook_modifier,hook modifier>> "<<hook_modifier_weechat_print,weechat_print>>":
  it can change the prefix and message on a buffer with formatted content
* <<_hook_print,hook print>>: called when the line has been added in a buffer
  with formatted content (nothing can be changed directly with this hook).

[NOTE]
The "line" hook is the only one among these three hooks that can work on
buffers with free content.

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_line (const char *buffer_type,
                                  const char *buffer_name,
                                  const char *tags,
                                  struct t_hashtable *(*callback)(const void *pointer,
                                                                  void *data,
                                                                  struct t_hashtable *line),
                                  const void *callback_pointer,
                                  void *callback_data);
----

Argomenti:

* _buffer_type_: catch lines on the given buffer type (if NULL or empty string,
  _formatted_ is the default)
  (_WeeChat ≥ 3.7_: a priority is allowed before the buffer type,
  see note about <<hook_priority,priority>>):
** _formatted_: catch lines on formatted buffers only (default)
** _free_: catch lines on buffers with free content only
** _*_: catch lines on all buffer types
* _buffer_name_: comma-separated list of buffer masks
  (see <<_buffer_match_list,buffer_match_list>>); NULL, empty string or "*"
  matches any buffer
* _tags_: catch only messages with these tags (optional): comma-separated list
   of tags that must be in message (logical "or"); it is possible to combine
   many tags as a logical "and" with separator `+++`; wildcard `+*+` is allowed
   in tags
* _callback_: function called when a line is added in a buffer, arguments and
  return value:
** _const void *pointer_: pointer
** _void *data_: pointer
** _struct t_hashtable *line_: hashtable with the line info, keys and values are
   strings (see table below)
** return value: hashtable with new values (see table below)
* _callback_pointer_: pointer given to callback when it is called by WeeChat
* _callback_data_: pointer given to callback when it is called by WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Line data sent to the callback is a hashtable, with following values
(keys and values are strings):

[width="100%",cols="^1,3,3,2",options="header"]
|===
| Key | Value (formatted buffer) | Value (free buffer) | Examples

| buffer
| Buffer pointer.
| Buffer pointer.
| `+0x1234abcd+`

| buffer_name
| Buffer name.
| Buffer name.
| `+core.weechat+` +
  `+irc.server.libera+` +
  `+irc.libera.#weechat+`

| buffer_type
| "formatted"
| "free"
| `+formatted+` +
  `+free+`

| y
| N/A ("-1").
| Line number (≥ "0").
| `+-1+` +
  `+8+`

| date
| Line date (timestamp).
| N/A ("0").
| `+1533792000+`

| date_usec
| Microseconds of line date (between 0 and 999999).
| N/A ("0").
| `+123456+`

| date_printed
| Date when line was displayed (timestamp).
| N/A ("0").
| `+1533792012+`

| date_usec_printed
| Microseconds of date when line was displayed (between 0 and 999999).
| N/A ("0").
| `+654321+`

| str_time
| Date for display (possible color codes inside).
| N/A (empty string).
| `+09:07:20+`

| tags_count
| Number of tags in the line (≥ "0").
| N/A ("0").
| `+2+`

| tags
| Comma-separated list of tags.
| N/A (empty string).
| `+irc_join,nick_test+`

| displayed
| "0" = line is filtered (hidden) +
  "1" = line is not filtered (displayed).
| "0" = line is filtered (hidden) +
  "1" = line is not filtered (displayed).
| `+0+` +
  `+1+`

| notify_level
| "-1" = no notify +
  "0" = low level +
  "1" = message +
  "2" = private message +
  "3" = highlight
| N/A ("0").
| `+2+`

| highlight
| "0" = no highlight +
  "1" = line has highlight.
| N/A ("0").
| `+0+` +
  `+1+`

| prefix
| Prefix of the line.
| N/A (empty string).
| `+-->+`

| message
| Message of the line.
| Message of the line.
| `+test (~test@example.com) has joined #channel+`
|===

The callback can return a hashtable with some fields to update the line.
Any invalid value in a field is silently ignored by WeeChat.

The following keys can be set in the hashtable (keys and values are strings
in this hashtable):

[width="100%",cols="^1,2,2,5",options="header"]
|===
| Key | Allowed value (formatted buffer) | Allowed value (free buffer) | Result

| buffer
| Pointer of a buffer with formatted content.
| Pointer of a buffer with free content.
| The line is displayed on this buffer. +
  If the value is empty, the line is deleted (anything else in the hashtable
  is then ignored); the next hooks of type "line" are not called.

| buffer_name
| Name of a buffer with formatted content.
| Name of a buffer with free content.
| The line is displayed on this buffer. +
  If `buffer` is also set, the value of `+buffer_name+` has higher priority and is used. +
  If the value is empty, the line is deleted (anything else in the hashtable
  is then ignored); the next hooks of type "line" are not called.

| y
| N/A.
| Integer (≥ "0").
| The line number is set to this value.

| date
| Timestamp.
| N/A.
| The date is set to this value. +
  The value of `+str_time+` is updated accordingly.

| date_usec
| Integer ("0" to "999999").
| N/A.
| The microseconds of line date is set to this value. +
  The value of `+str_time+` is updated accordingly.

| date_printed
| Timestamp.
| N/A.
| The printed date is set to this timestamp (not displayed).

| date_usec_printed
| Integer ("0" to "999999").
| N/A.
| The microseconds of printed date is set to this value.

| str_time
| String.
| N/A.
| This string is used to display the date line. +
  If `date` is also set, the value of `+str_time+` has higher priority and is used.

| tags
| String.
| N/A.
| The line tags are replaced with this comma-separated list of tags. +
  The values of `+notify_level+` and `highlight` are updated accordingly.

| notify_level
| Integer ("-1" to "3").
| N/A.
| The notify level is set to this value. The hotlist will be updated
  accordingly once the line is added in the buffer. +
  The value of `highlight` is updated accordingly. +
  If `tags` is also set, the value of `+notify_level+` has higher priority and is used.

| highlight
| Integer ("0" or "1").
| N/A.
| "0" disables highlight on the line, "1" forces a highlight on the line. +
  If `tags` or `+notify_level+` are set, the value of `highlight` has higher
  priority and is used.

| prefix
| String.
| N/A.
| The line prefix is set to this value.

| message
| String.
| String.
| The line message is set to this value.
|===

Esempio in C:

[source,c]
----
int
my_line_cb (const void *pointer, void *data, struct t_hashtable *line)
{
    struct t_hashtable *hashtable;

    hashtable = weechat_hashtable_new (8,
                                       WEECHAT_HASHTABLE_STRING,
                                       WEECHAT_HASHTABLE_STRING,
                                       NULL,
                                       NULL);
    /* force a highlight on the line */
    weechat_hashtable_set (hashtable, "highlight", "1");
    return hashtable;
}

/* catch lines with tag "irc_join" */
struct t_hook *my_line_hook =
    weechat_hook_line ("", "", "irc_join", &my_line_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_line(buffer_type: str, buffer_name: str, tags: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_line_cb(data: str, line: Dict[str, str]) -> Dict[str, str]:
    # force a highlight on the line
    return {"highlight": "1"}

# catch lines with tag "irc_join"
hook = weechat.hook_line("", "", "irc_join", "my_line_cb", "")
----

==== hook_print

// TRANSLATION MISSING
_Updated in 0.4.3, 1.0, 1.5, 4.2.0._

// TRANSLATION MISSING
Hook su un messaggio stampato. It is called when a line has been added in
a buffer with formatted content.

// TRANSLATION MISSING
For more information on the hooks called when a line is printed, see
<<_hook_line,hook_line>>.

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)(const void *pointer,
                                                   void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int date_usec,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Argomenti:

* _buffer_: puntatore al buffer, se NULL, verranno catturati i messaggi da qualsiasi
  buffer
// TRANSLATION MISSING
* _tags_: catch only messages with these tags (optional):
// TRANSLATION MISSING
** with WeeChat ≥ 0.4.3: comma-separated list of tags that must be in message
   (logical "or"); it is possible to combine many tags as a logical "and" with
   separator `+++`; wildcard `+*+` is allowed in tags
// TRANSLATION MISSING
** with WeeChat ≤ 0.4.2: comma-separated list of tags that must all be in
   message (logical "and")
* _message_: verranno catturati solo i messaggi con questa stringa (opzionale,
  non sensibile alle maiuscole)
* _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 e
  valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: puntatore al buffer
** _time_t date_: data
// TRANSLATION MISSING
** _int date_usec_: microseconds of date
** _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
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

// TRANSLATION MISSING
[IMPORTANT]
In scripts, with WeeChat ≥ 1.0, the callback arguments _displayed_ and
_highlight_ are integers (with WeeChat ≤ 0.4.3, they were strings). +
To be compatible with all versions, it is recommended to convert the argument
to integer before testing it, for example in Python: `if int(highlight):`.

Esempio in C:

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

/* 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, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_print(buffer: str, tags: str, message: str, strip_colors: int, callback: str, callback_data: str) -> str: ...

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

# cattura tutti i messaggi, su tutti i buffer, senza colore
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----

==== hook_signal

// TRANSLATION MISSING
_Updated in 1.5, 3.6._

Hook su un segnale.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _signal_: segnale da catturare, wildcard `+*+` is allowed, multiple signals
  can be separated by semi-colons
  (a priority is allowed before one or more signals, see note about <<hook_priority,priority>>)
  (see table below)
* _callback_: funzione chiamata a segnale ricevuto, argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _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
** valore restituito:
*** _WEECHAT_RC_OK_
// TRANSLATION MISSING
*** _WEECHAT_RC_OK_EAT_ (stop sending the signal immediately)
    _(WeeChat ≥ 0.4.0)_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

// TRANSLATION MISSING
List of signals sent by WeeChat and plugins:

[width="100%",cols="^2,^4,^1,6,9",options="header"]
|===
// TRANSLATION MISSING
| Plugin | Segnale | Min WeeChat | Argomenti | Descrizione

// TRANSLATION MISSING
| guile | [[hook_signal_guile_script_loaded]] guile_script_loaded | 0.3.9
| String: path to script.
| Scheme script loaded.

// TRANSLATION MISSING
| guile | [[hook_signal_guile_script_unloaded]] guile_script_unloaded | 0.3.9
| String: path to script.
| Scheme script unloaded.

// TRANSLATION MISSING
| guile | [[hook_signal_guile_script_installed]] guile_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Scheme script(s) installed.

// TRANSLATION MISSING
| guile | [[hook_signal_guile_script_removed]] guile_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Scheme script(s) removed.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_in_yyy]] xxx,irc_in_yyy ^(1)^ |
| String: messaggio.
| Messaggio IRC dal server (prima di essere utilizzato
  dal plugin irc, il segnale viene inviato solo se il
  messaggio *non* viene ignorato). +
  Since version 2.2, the whole IRC message is sent, including tags. +
  If the return code of a callback is _WEECHAT_RC_OK_EAT_, then the IRC message
  is immediately destroyed and not processed _(WeeChat ≥ 3.3)_.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_in2_yyy]] xxx,irc_in2_yyy ^(1)^ |
| String: messaggio.
| Messaggio IRC dal server (dopo essere stato
  utilizzato dal plugin irc, il segnale viene inviato
  solo se il messaggio *non* viene ignorato). +
  Since version 2.2, the whole IRC message is sent, including tags.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_raw_in_yyy]] xxx,irc_raw_in_yyy ^(1)^ | 0.3.2
| String: messaggio.
| Messaggio IRC dal server (prima di essere utilizzato
  dal plugin irc, il segnale viene inviato anche se il
  messaggio è stato ignorato). +
  Since version 2.2, the whole IRC message is sent, including tags. +
  If the return code of a callback is _WEECHAT_RC_OK_EAT_, then the IRC message
  is immediately destroyed and not processed _(WeeChat ≥ 3.3)_.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_raw_in2_yyy]] xxx,irc_raw_in2_yyy ^(1)^ | 0.3.2
| String: messaggio.
| Messaggio IRC dal server (dopo essere stato
  utilizzato dal plugin irc, il segnale viene inviato
  anche se il messaggio è stato ignorato). +
  Since version 2.2, the whole IRC message is sent, including tags.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_out1_yyy]] xxx,irc_out1_yyy ^(1)^ | 0.3.7
| String: messaggio.
| IRC message sent to server before automatic split
  (to fit in 512 bytes by default).

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_out_yyy]] xxx,irc_out_yyy ^(1)^ |
| String: messaggio.
| IRC message sent to server after automatic split
  (to fit in 512 bytes by default). +
  *Warning:* the string may contain invalid UTF-8 data.
  Signal "xxx,irc_out1_yyy" is recommended instead.

// TRANSLATION MISSING
| irc | [[hook_signal_xxx_irc_outtags_yyy]] xxx,irc_outtags_yyy ^(1)^ | 0.3.4
| Stringa: tag + ";" + messaggio.
| Tag + messaggio IRC inviato al server. +
  *Warning:* the string may contain invalid UTF-8 data.
  Signal "xxx,irc_out1_yyy" is recommended instead.

| irc | [[hook_signal_irc_ctcp]] irc_ctcp |
| String: messaggio.
| CTCP ricevuto.

| irc | [[hook_signal_irc_dcc]] irc_dcc |
| String: messaggio.
| Nuova DCC.

| irc | [[hook_signal_irc_pv]] irc_pv |
| String: messaggio.
| Messaggio privato ricevuto.

| irc | [[hook_signal_irc_channel_opened]] irc_channel_opened |
| Puntatore: buffer.
| Canale aperto.

| irc | [[hook_signal_irc_pv_opened]] irc_pv_opened |
| Puntatore: buffer.
| Chat privata aperta.

| irc | [[hook_signal_irc_server_opened]] irc_server_opened | 0.3.7
| Puntatore: buffer.
| Server del buffer aperto.

| irc | [[hook_signal_irc_server_connecting]] irc_server_connecting |
| String: nome server.
| Connessione al server.

| irc | [[hook_signal_irc_server_connected]] irc_server_connected |
| String: nome server.
| Connesso al server.

| irc | [[hook_signal_irc_server_disconnected]] irc_server_disconnected |
| String: nome server.
| Disconnesso dal server.

// TRANSLATION MISSING
| irc | [[hook_signal_irc_server_lag_changed]] irc_server_lag_changed | 1.8
| String: server name.
| Lag changed on the server.

| irc | [[hook_signal_irc_ignore_removing]] irc_ignore_removing |
| Puntatore: ignore.
| Rimozione dell'ignore.

| irc | [[hook_signal_irc_ignore_removed]] irc_ignore_removed |
| -
| Ignore rimosso.

| irc | [[hook_signal_irc_notify_join]] irc_notify_join | 0.3.8
| String: nome server + "," + nick.
| Un nick nella lista notifiche è entrato sul server.

| irc | [[hook_signal_irc_notify_quit]] irc_notify_quit | 0.3.8
| String: nome server + "," + nick.
| Un nick nella lista notifiche è uscito dal server.

| irc | [[hook_signal_irc_notify_away]] irc_notify_away | 0.3.8
| String: nome server + "," + nick + "," + messaggio di assenza.
| Un nick nella lista notifiche è ora assente sul server.

| irc | [[hook_signal_irc_notify_still_away]] irc_notify_still_away | 0.3.8
| String: nome server + "," + nick + "," + messaggio di assenza.
| Un nick nella lista notifiche è ancora assente sul server (messaggio di assenza cambiato).

| irc | [[hook_signal_irc_notify_back]] irc_notify_back | 0.3.8
| String: nome server + "," + nick.
| Un nick nella lista notifiche è tornato (messaggio di assenza rimosso).

// TRANSLATION MISSING
| javascript | [[hook_signal_javascript_script_loaded]] javascript_script_loaded | 1.2
| String: path to script.
| JavaScript script loaded.

// TRANSLATION MISSING
| javascript | [[hook_signal_javascript_script_unloaded]] javascript_script_unloaded | 1.2
| String: path to script.
| JavaScript script unloaded.

// TRANSLATION MISSING
| javascript | [[hook_signal_javascript_script_installed]] javascript_script_installed | 1.2
| String: comma-separated list of paths to scripts installed.
| JavaScript script(s) installed.

// TRANSLATION MISSING
| javascript | [[hook_signal_javascript_script_removed]] javascript_script_removed | 1.2
| String: comma-separated list of scripts removed.
| JavaScript script(s) removed.

| logger | [[hook_signal_logger_start]] logger_start |
| Puntatore: buffer.
| Avvia il logging per il buffer.

| logger | [[hook_signal_logger_stop]] logger_stop |
| Puntatore: buffer.
| Ferma il logging per il buffer.

| logger | [[hook_signal_logger_backlog]] logger_backlog |
| Puntatore: buffer.
| Visualizza log precedenti per il buffer.

// TRANSLATION MISSING
| lua | [[hook_signal_lua_script_loaded]] lua_script_loaded | 0.3.9
| String: path to script.
| Lua script loaded.

// TRANSLATION MISSING
| lua | [[hook_signal_lua_script_unloaded]] lua_script_unloaded | 0.3.9
| String: path to script.
| Lua script unloaded.

// TRANSLATION MISSING
| lua | [[hook_signal_lua_script_installed]] lua_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Lua script(s) installed.

// TRANSLATION MISSING
| lua | [[hook_signal_lua_script_removed]] lua_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Lua script(s) removed.

// TRANSLATION MISSING
| perl | [[hook_signal_perl_script_loaded]] perl_script_loaded | 0.3.9
| String: path to script.
| Perl script loaded.

// TRANSLATION MISSING
| perl | [[hook_signal_perl_script_unloaded]] perl_script_unloaded | 0.3.9
| String: path to script.
| Perl script unloaded.

// TRANSLATION MISSING
| perl | [[hook_signal_perl_script_installed]] perl_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Perl script(s) installed.

// TRANSLATION MISSING
| perl | [[hook_signal_perl_script_removed]] perl_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Perl script(s) removed.

// TRANSLATION MISSING
| php | [[hook_signal_php_script_loaded]] php_script_loaded | 2.0
| String: path to script.
| PHP script loaded.

// TRANSLATION MISSING
| php | [[hook_signal_php_script_unloaded]] php_script_unloaded | 2.0
| String: path to script.
| PHP script unloaded.

// TRANSLATION MISSING
| php | [[hook_signal_php_script_installed]] php_script_installed | 2.0
| String: comma-separated list of paths to scripts installed.
| PHP script(s) installed.

// TRANSLATION MISSING
| php | [[hook_signal_php_script_removed]] php_script_removed | 2.0
| String: comma-separated list of scripts removed.
| PHP script(s) removed.

// TRANSLATION MISSING
| python | [[hook_signal_python_script_loaded]] python_script_loaded | 0.3.9
| String: path to script.
| Python script loaded.

// TRANSLATION MISSING
| python | [[hook_signal_python_script_unloaded]] python_script_unloaded | 0.3.9
| String: path to script.
| Python script unloaded.

// TRANSLATION MISSING
| python | [[hook_signal_python_script_installed]] python_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Python script(s) installed.

// TRANSLATION MISSING
| python | [[hook_signal_python_script_removed]] python_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Python script(s) removed.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_connecting]] relay_client_connecting | 1.0
| Pointer: relay client.
| A relay client is connecting.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_waiting_auth]] relay_client_waiting_auth | 1.0
| Pointer: relay client.
| Waiting for authentication from a relay client.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_auth_ok]] relay_client_auth_ok | 1.0
| Pointer: relay client.
| Successful authentication from a relay client.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_connected]] relay_client_connected | 1.0
| Pointer: relay client.
| A relay client is connected.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_auth_failed]] relay_client_auth_failed | 1.0
| Pointer: relay client.
| Authentication of a relay client has failed.

// TRANSLATION MISSING
| relay | [[hook_signal_relay_client_disconnected]] relay_client_disconnected | 1.0
| Pointer: relay client.
| A relay client is disconnected.

// TRANSLATION MISSING
| ruby | [[hook_signal_ruby_script_loaded]] ruby_script_loaded | 0.3.9
| String: path to script.
| Ruby script loaded.

// TRANSLATION MISSING
| ruby | [[hook_signal_ruby_script_unloaded]] ruby_script_unloaded | 0.3.9
| String: path to script.
| Ruby script unloaded.

// TRANSLATION MISSING
| ruby | [[hook_signal_ruby_script_installed]] ruby_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Ruby script(s) installed.

// TRANSLATION MISSING
| ruby | [[hook_signal_ruby_script_removed]] ruby_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Ruby script(s) removed.

// TRANSLATION MISSING
| spell | [[hook_signal_spell_suggest]] spell_suggest | 2.4
| Pointer: buffer.
| New suggestions for a misspelled word.

// TRANSLATION MISSING
| tcl | [[hook_signal_tcl_script_loaded]] tcl_script_loaded | 0.3.9
| String: path to script.
| Tcl script loaded.

// TRANSLATION MISSING
| tcl | [[hook_signal_tcl_script_unloaded]] tcl_script_unloaded | 0.3.9
| String: path to script.
| Tcl script unloaded.

// TRANSLATION MISSING
| tcl | [[hook_signal_tcl_script_installed]] tcl_script_installed | 0.3.9
| String: comma-separated list of paths to scripts installed.
| Tcl script(s) installed.

// TRANSLATION MISSING
| tcl | [[hook_signal_tcl_script_removed]] tcl_script_removed | 0.3.9
| String: comma-separated list of scripts removed.
| Tcl script(s) removed.

// TRANSLATION MISSING
| typing | [[hook_signal_typing_self_typing]] typing_self_typing | 3.3
| Pointer: buffer.
| User is typing a message (sent by typing plugin, used by irc plugin).

// TRANSLATION MISSING
| typing | [[hook_signal_typing_self_paused]] typing_self_paused | 3.3
| Pointer: buffer.
| User paused during typing (sent by typing plugin, used by irc plugin).

// TRANSLATION MISSING
| typing | [[hook_signal_typing_self_cleared]] typing_self_cleared | 3.3
| Pointer: buffer.
| User cleared the input without sending the message (sent by typing plugin, used by irc plugin).

// TRANSLATION MISSING
| typing | [[hook_signal_typing_self_sent]] typing_self_sent | 3.3
| Pointer: buffer.
| Message (not a command) sent to the buffer (sent by typing plugin, used by irc plugin).

// TRANSLATION MISSING
| typing | [[hook_signal_typing_set_nick]] typing_set_nick | 3.3
| String: buffer pointer + ";" + state (one of: "off", "typing", "paused",
  "cleared") + ";" + nick.
| Set typing state for a nick on a buffer (sent by irc plugin, handled by typing plugin).

// TRANSLATION MISSING
| typing | [[hook_signal_typing_reset_buffer]] typing_reset_buffer | 3.3
| Pointer: buffer.
| Remove typing state for all nicks on a buffer (sent by irc plugin, handled by typing plugin).

| weechat | [[hook_signal_buffer_opened]] buffer_opened |
| Puntatore: buffer.
| Buffer aperto.

| weechat | [[hook_signal_buffer_closing]] buffer_closing |
| Puntatore: buffer.
| Chiusura del buffer.

| weechat | [[hook_signal_buffer_closed]] buffer_closed |
| Puntatore: buffer.
| Buffer chiuso.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_cleared]] buffer_cleared |
| Puntatore: buffer.
| Buffer cleared.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_filters_enabled]] buffer_filters_enabled | 2.0
| Pointer: buffer.
| Filters enabled in buffer.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_filters_disabled]] buffer_filters_disabled | 2.0
| Pointer: buffer.
| Filters disabled in buffer.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_hidden]] buffer_hidden |
| Pointer: buffer.
| Buffer hidden.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_unhidden]] buffer_unhidden |
| Pointer: buffer.
| Buffer unhidden.

| weechat | [[hook_signal_buffer_line_added]] buffer_line_added | 0.3.7
| Puntatore: riga.
| Riga aggiunta in un buffer.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_line_data_changed]] buffer_line_data_changed | 4.4.0
| Pointer: line data.
| Line data has been updated in a buffer.

| weechat | [[hook_signal_buffer_lines_hidden]] buffer_lines_hidden |
| Puntatore: buffer.
| Righe nascoste nel buffer.

| weechat | [[hook_signal_buffer_localvar_added]] buffer_localvar_added |
| Puntatore: buffer.
| Variabili locali aggiunte.

| weechat | [[hook_signal_buffer_localvar_changed]] buffer_localvar_changed |
| Puntatore: buffer.
| Variabili locali modificate.

| weechat | [[hook_signal_buffer_localvar_removed]] buffer_localvar_removed |
| Puntatore: buffer.
| Variabili locali rimosse.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_merged]] buffer_merged |
| Puntatore: buffer.
| Buffer merged.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_unmerged]] buffer_unmerged |
| Puntatore: buffer.
| Buffer unmerged.

| weechat | [[hook_signal_buffer_moved]] buffer_moved |
| Puntatore: buffer.
| Buffer spostato.

| weechat | [[hook_signal_buffer_renamed]] buffer_renamed |
| Puntatore: buffer.
| Buffer rinominato.

| weechat | [[hook_signal_buffer_switch]] buffer_switch |
| Puntatore: buffer.
| Passaggio tra buffer.

| weechat | [[hook_signal_buffer_title_changed]] buffer_title_changed |
| Puntatore: buffer.
| Titolo del buffer modificato.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_modes_changed]] buffer_modes_changed | 4.3.0
| Pointer: buffer.
| Modes of buffer changed.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_time_for_each_line_changed]] buffer_time_for_each_line_changed | 4.4.0
| Pointer: buffer.
| Display time for each line changed.

| weechat | [[hook_signal_buffer_type_changed]] buffer_type_changed |
| Puntatore: buffer.
| Tipo di buffer modificato.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_zoomed]] buffer_zoomed | 0.4.3
| Puntatore: buffer.
| Merged buffer zoomed.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_unzoomed]] buffer_unzoomed | 0.4.3
| Puntatore: buffer.
| Merged buffer unzoomed.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_user_input_xxx]] buffer_user_input_xxx ^(2)^ | 3.8
| String: text sent to buffer.
| Text sent to a user buffer as input (sent only for buffers created with `/buffer add`). +
  If the return code of a callback is _WEECHAT_RC_OK_EAT_, then the string "q"
  cannot be used anymore to close the buffer.

// TRANSLATION MISSING
| weechat | [[hook_signal_buffer_user_closing_xxx]] buffer_user_closing_xxx ^(2)^ | 3.8
| -
| User buffer is closing (sent only for buffers created with `/buffer add`).

// TRANSLATION MISSING
| weechat | [[hook_signal_cursor_start]] cursor_start | 3.2
| -
| Start cursor mode.

// TRANSLATION MISSING
| weechat | [[hook_signal_cursor_end]] cursor_end | 3.2
| -
| End cursor mode.

| weechat | [[hook_signal_day_changed]] day_changed | 0.3.2
| String: nuova data, formato: "2010-01-31".
| Data di sistema modificata.

| weechat | [[hook_signal_debug_dump]] debug_dump |
| Stringa: nome plugin.
| Richiesta di dump.

// TRANSLATION MISSING
| weechat | [[hook_signal_debug_libs]] debug_libs |
| -
| Display external libraries used.

| weechat | [[hook_signal_filter_added]] filter_added |
| Puntatore: filtro.
| Filtro aggiunto.

| weechat | [[hook_signal_filter_removing]] filter_removing |
| Puntatore: filtro.
| Rimozione del filtro.

| weechat | [[hook_signal_filter_removed]] filter_removed |
| -
| Filtro rimosso.

| weechat | [[hook_signal_filters_enabled]] filters_enabled |
| -
| Filtri abilitati.

| weechat | [[hook_signal_filters_disabled]] filters_disabled |
| -
| Filtri disabilitati.

// TRANSLATION MISSING
| weechat | [[hook_signal_hotlist_changed]] hotlist_changed |
| Pointer: buffer (can be NULL).
| Hotlist modificata.

| weechat | [[hook_signal_input_paste_pending]] input_paste_pending |
| -
| Incolla testo in attesa.

| weechat | [[hook_signal_input_search]] input_search |
| Puntatore: buffer.
| Ricerca testo nel buffer.

// TRANSLATION MISSING
| weechat | [[hook_signal_input_prompt_changed]] input_prompt_changed | 4.3.0
| Pointer: buffer.
| Input prompt changed.

| weechat | [[hook_signal_input_text_changed]] input_text_changed |
| Puntatore: buffer.
| Testo in input modificato.

| weechat | [[hook_signal_input_text_cursor_moved]] input_text_cursor_moved |
| Puntatore: buffer.
| Cursore del testo di input spostato.

// TRANSLATION MISSING
| weechat | [[hook_signal_key_bind]] key_bind |
| String: key.
| Key added.

// TRANSLATION MISSING
| weechat | [[hook_signal_key_unbind]] key_unbind |
| String: key.
| Key removed.

| weechat | [[hook_signal_key_pressed]] key_pressed |
| String: tasto digitato.
| Tasto digitato.

// TRANSLATION MISSING
| weechat | [[hook_signal_key_combo_default]] key_combo_default | 1.0
| String: key combo.
| Key combo in _default_ context.

// TRANSLATION MISSING
| weechat | [[hook_signal_key_combo_search]] key_combo_search | 1.0
| String: key combo.
| Key combo in _search_ context.

// TRANSLATION MISSING
| weechat | [[hook_signal_key_combo_cursor]] key_combo_cursor | 1.0
| String: key combo.
| Key combo in _cursor_ context.

// TRANSLATION MISSING
| weechat | [[hook_signal_layout_buffers_applied]] layout_buffers_applied | 4.4.0
| String: layout name.
| Layout applied for buffers.

// TRANSLATION MISSING
| weechat | [[hook_signal_layout_windows_applied]] layout_windows_applied | 4.4.0
| String: layout name.
| Layout applied for windows.

// TRANSLATION MISSING
| weechat | [[hook_signal_mouse_enabled]] mouse_enabled | 1.1
| -
| Mouse enabled.

// TRANSLATION MISSING
| weechat | [[hook_signal_mouse_disabled]] mouse_disabled | 1.1
| -
| Mouse disabled.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_group_added]] nicklist_group_added | 0.3.2
| String: buffer pointer + "," + group name.
| Group added in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_group_changed]] nicklist_group_changed | 0.3.4
| String: buffer pointer + "," + group name.
| Group changed in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_group_removing]] nicklist_group_removing | 0.4.1
| String: buffer pointer + "," + group name.
| Removing group from nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_group_removed]] nicklist_group_removed | 0.3.2
| String: buffer pointer + "," + group name.
| Group removed from nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_nick_added]] nicklist_nick_added | 0.3.2
| String: buffer pointer + "," + nick name.
| Nick added in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_nick_changed]] nicklist_nick_changed | 0.3.4
| String: buffer pointer + "," + nick name.
| Nick changed in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_nick_removing]] nicklist_nick_removing | 0.4.1
| String: buffer pointer + "," + nick name.
| Removing nick from nicklist.

// TRANSLATION MISSING
| weechat | [[hook_signal_nicklist_nick_removed]] nicklist_nick_removed | 0.3.2
| String: buffer pointer + "," + nick name.
| Nick removed from nicklist.

| weechat | [[hook_signal_partial_completion]] partial_completion |
| -
| Completamento parziale avvenuto.

// TRANSLATION MISSING
| weechat | [[hook_signal_plugin_loaded]] plugin_loaded | 0.3.9
| String: path to plugin loaded.
| Plugin loaded.

// TRANSLATION MISSING
| weechat | [[hook_signal_plugin_unloaded]] plugin_unloaded | 0.3.9
| String: name of plugin unloaded (example: "irc").
| Plugin unloaded.

| weechat | [[hook_signal_quit]] quit |
| String: argomenti per /quit.
| Comando `/quit` digitato dall'utente.

// TRANSLATION MISSING
| weechat | [[hook_signal_signal_sighup]] signal_sighup | 1.3
| -
| Signal SIGHUP received.

// TRANSLATION MISSING
| weechat | [[hook_signal_signal_sigquit]] signal_sigquit | 1.2
| -
| Signal SIGQUIT received (quit request with core dump).

// TRANSLATION MISSING
| weechat | [[hook_signal_signal_sigterm]] signal_sigterm | 1.2
| -
| Signal SIGTERM received (graceful termination of WeeChat process).

// TRANSLATION MISSING
| weechat | [[hook_signal_signal_sigwinch]] signal_sigwinch | 0.4.3
| -
| Signal SIGWINCH received (terminal was resized).

// TRANSLATION MISSING
| weechat | [[hook_signal_upgrade]] upgrade |
| String: "quit" if "-quit" argument was given for /upgrade, "save" if "-save"
  if "-save" argument was given for /upgrade, otherwise NULL.
| Comando `/upgrade` digitato dall'utente.

| weechat | [[hook_signal_upgrade_ended]] upgrade_ended | 0.3.4
| -
| Fine del processo di aggiornamento (comando `/upgrade`).

| weechat | [[hook_signal_weechat_highlight]] weechat_highlight |
| String: messaggio con prefisso.
| Evento accaduto.

| weechat | [[hook_signal_weechat_pv]] weechat_pv |
| String: messaggio con prefisso.
| Messaggio privato visualizzato.

// TRANSLATION MISSING
| weechat | [[hook_signal_window_closing]] window_closing | 0.3.6
| Puntatore: finestra.
| Closing window.

// TRANSLATION MISSING
| weechat | [[hook_signal_window_closed]] window_closed | 0.3.6
| Puntatore: finestra.
| Window closed.

// TRANSLATION MISSING
| weechat | [[hook_signal_window_opened]] window_opened | 0.4.1
| Puntatore: finestra.
| Window opened.

| weechat | [[hook_signal_window_scrolled]] window_scrolled |
| Puntatore: finestra.
| Scroll nella finestra.

| weechat | [[hook_signal_window_switch]] window_switch | 0.3.7
| Puntatore: finestra.
| Passaggio alla finestra.

| weechat | [[hook_signal_window_zoom]] window_zoom |
| Puntatore: finestra corrente.
| Massimizzazione della finestra.

| weechat | [[hook_signal_window_zoomed]] window_zoomed |
| Puntatore: finestra corrente.
| Finestra massimizzata.

| weechat | [[hook_signal_window_unzoom]] window_unzoom |
| Puntatore: finestra corrente.
| Minimizzazione della finestra.

| weechat | [[hook_signal_window_unzoomed]] window_unzoomed |
| Puntatore: finestra corrente.
| Finestra minimizzata.

| xfer | [[hook_signal_xfer_add]] xfer_add |
| Puntatore: lista info con info per xfe.r|
  Nuovo xfer.

| xfer | [[hook_signal_xfer_send_ready]] xfer_send_ready |
| Puntatore: lista info xon info per xfer.
| Xfer pronto.

// TRANSLATION MISSING
| xfer | [[hook_signal_xfer_accept_resume]] xfer_accept_resume |
| Puntatore: lista info con info per xfer.
| Accept xfer resume.

// TRANSLATION MISSING
| xfer | [[hook_signal_xfer_send_accept_resume]] xfer_send_accept_resume |
| Puntatore: lista info con info per xfer.
| Xfer resumed.

| xfer | [[hook_signal_xfer_start_resume]] xfer_start_resume |
| Puntatore: lista info con info per xfer.
| Avvia ripresa.

| xfer | [[hook_signal_xfer_resume_ready]] xfer_resume_ready |
| Puntatore: lista info con info per xfer.
| Ripresa xfer pronta.

| xfer | [[hook_signal_xfer_ended]] xfer_ended | 0.3.2
| Puntatore: lista info con info per xfer.
| Xfer terminato.
|===

[NOTE]
^(1)^ _xxx_ è il nome del server IRC, _yyy_ è il nome del comando IRC. +
// TRANSLATION MISSING
^(2)^ _xxx_ is buffer name.

Esempio in C:

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

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

Script (Python):

// TRANLSATION MISSING
[source,python]
----
# prototipo
def hook_signal(signal: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_signal_cb(data: str, signal: str, signal_data: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

# catch signals "quit" and "upgrade"
hook = weechat.hook_signal("quit;upgrade", "my_signal_cb", "")
----

==== hook_signal_send

// TRANSLATION MISSING
_Updated in 1.0, 4.5.0._

Invia un segnale.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _signal_: segnale da inviare; flags are allowed before the signal name (see below)
  _(WeeChat ≥ 4.5.0)_
* _type_data_: tipo di dati inviati con il segnale (consultare <<_hook_signal,hook_signal>>)
* _signal_data_: dati inviati con il segnale

// TRANSLATION MISSING
The signal name can contain flags with the following format: `[flags:xxx,yyy]signal`
where `xxx` and `yyy` are names of flags, and `signal` the signal name. +
The following flags are supported:

* _stop_on_error_: exit immediately if a callback returns WEECHAT_RC_ERROR
  (remaining callbacks are then NOT executed) _(WeeChat ≥ 4.5.0)_
* _ignore_eat_: consider any callback returning WEECHAT_RC_OK_EAT is in fact
  WEECHAT_RC_OK and execute remaining callbacks _(WeeChat ≥ 4.5.0)_

// TRANSLATION MISSING
Return value _(WeeChat ≥ 1.0)_:

// TRANSLATION MISSING
* return code of last callback executed (_WEECHAT_RC_OK_ if no callback was
  executed):
** _WEECHAT_RC_OK_
** _WEECHAT_RC_OK_EAT_
** _WEECHAT_RC_ERROR_

Esempio in C:

[source,c]
----
int rc = weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
int rc2 = weechat_hook_signal_send ("[flags:stop_on_error,ignore_eat]my_signal2",
                                    WEECHAT_HOOK_SIGNAL_STRING, my_string);
----

Script (Python):

[source,python]
----
# prototipo
def hook_signal_send(signal: str, type_data: str, signal_data: str) -> int: ...

# esempio
rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
rc2 = weechat.hook_signal_send("[flags:stop_on_error,ignore_eat]my_signal2",
                               weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
----

[[signal_logger_backlog]]
===== Signal logger_backlog

Il segnale "logger_backlog" può essere inviato per visualizzare il backlog
(cronologia di chat) nel buffer (ad esempio se il proprio buffer viene aperto
in un plugin/script).

L'argomento è un puntatore al buffer.

Esempio in C:

[source,c]
----
weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);
----

Script (Python):

[source,python]
----
weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
----

[[signals_xxx_script_install]]
===== Signals xxx_script_install

Cinque segnali che possono essere inviati per installare uno script, a seconda
del linguaggio:

* _perl_script_install_
* _python_script_install_
* _ruby_script_install_
* _lua_script_install_
* _tcl_script_install_
* _guile_script_install_
* _javascript_script_install_
* _php_script_install_

La callback compirà le seguenti azioni alla ricezione del segnale:

. Scarica e rimuove lo script installato.
. Sposta il nuovo script nella cartella _~/.local/share/weechat/xxx/_ (dove _xxx_ è il
  linguaggio).
// TRANSLATION MISSING
. Crea un link al nuovo script nella cartella _~/.local/share/weechat/xxx/autoload/_
  (only if the script was already auto-loaded, or if the option
  _script.scripts.autoload_ is enabled for a new script).
// TRANSLATION MISSING
. Carica il nuovo script (if the script was loaded).

// TRANSLATION MISSING
These signals are used by _script_ plugin to install scripts.

L'argomento è una stringa con il percorso dello script da installare.

Esempio in C:

[source,c]
----
weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py");
----

Script (Python):

[source,python]
----
weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py")
----

[[signals_xxx_script_remove]]
===== Signals xxx_script_remove

Cinque segnali che possono essere inviati per rimuovere un elenco di script, a
seconda del linguaggio:

* _perl_script_remove_
* _python_script_remove_
* _ruby_script_remove_
* _lua_script_remove_
* _tcl_script_remove_
* _guile_script_remove_
* _javascript_script_remove_
* _php_script_remove_

Per ogni script nella lista, la callback scaricherà e rimuoverà lo script.

// TRANSLATION MISSING
These signals are used by _script_ plugin to remove scripts.

L'argomento è una stringa con una lista separata da virgole di script da
rimuovere (script è il nome senza percorso, ad esempio _script.py_).

Esempio in C:

[source,c]
----
/* scarica e rimuove gli script test.py e script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----

Script (Python):

[source,python]
----
# scarica e rimuove gli script test.py e script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----

[[signal_irc_input_send]]
===== Signal irc_input_send

// TRANSLATION MISSING
_WeeChat ≥ 0.3.4, updated in 1.5._

Il segnale "irc_input_send" può essere inviato per simulare input in un buffer
irc (server, canale o privato).

L'argomento è una stringa con il seguente formato:

* nome interno del server (richiesto)
* punto e virgola
* nome canale (opzionale)
* punto e virgola
// TRANSLATION MISSING
* comma-separated list of options (optional):
** _priority_high_: queue with high priority (like user messages); this is the
   default priority
** _priority_low_: queue with low priority (like messages automatically sent by
   WeeChat)
** _user_message_: force user message (don't execute a command)
* punto e virgola
* elenco separato da virgole di tag usate per l'invio di un messaggio
  (opzionale)
* punto e virgola
* testo o comando (richiesto)

Esempi in C:

[source,c]
----
/* dice "Hello!" sul server libera, canale #weechat */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "libera;#weechat;priority_high,user_message;;Hello!");

/* invia il comando "/whois FlashCode" sul server libera, con priorità minore */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "libera;;priority_low;;/whois FlashCode");
----

Script (Python):

[source,python]
----
# dice "Hello!" sul server libera server, canale #weechat
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;#weechat;priority_high,user_message;;Hello!")

# invia il comando "/whois FlashCode" sul server libera, con priorità minore
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;;priority_low;;/whois FlashCode")
----

==== hook_hsignal

_WeeChat ≥ 0.3.4, updated in 1.5, 3.6._

Hook su hsignal (segnale con tabella hash).

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _signal_: segnale da catturare, wildcard `+*+` is allowed, multiple signals can
  be separated by semi-colons
  (a priority is allowed before one or more signals, see note about <<hook_priority,priority>>)
  (see table below)
* _callback_: funzione chiamata a segnale ricevuto, argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *signal_: segnale ricevuto
** _struct t_hashtable *hashtable_: tabella hash
** valore restituito:
*** _WEECHAT_RC_OK_
// TRANSLATION MISSING
*** _WEECHAT_RC_OK_EAT_ (stop sending the signal immediately)
    _(WeeChat ≥ 0.4.0)_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

// TRANSLATION MISSING
List of hsignals sent by WeeChat and plugins:

[width="100%",cols="^1,^3,^1,5,5",options="header"]
|===
// TRANSLATION MISSING
| Plugin | Segnale | Min WeeChat | Argomenti | Descrizione

| irc | [[hook_hsignal_irc_redirection_xxx_yyy]] irc_redirection_xxx_yyy ^(1)^ | 0.3.4
| Consultare <<hsignal_irc_redirect_command,hsignal_irc_redirect_command>>
| Redirection output.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_group_added]] nicklist_group_added | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _group_ (_struct t_gui_nick_group *_): group
| Group added in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_nick_added]] nicklist_nick_added | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _nick_ (_struct t_gui_nick *_): nick
| Nick added in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_group_removing]] nicklist_group_removing | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _group_ (_struct t_gui_nick_group *_): group
| Removing group from nicklist.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_nick_removing]] nicklist_nick_removing | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _nick_ (_struct t_gui_nick *_): nick
| Removing nick from nicklist.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_group_changed]] nicklist_group_changed | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _group_ (_struct t_gui_nick_group *_): group
| Group changed in nicklist.

// TRANSLATION MISSING
| weechat | [[hook_hsignal_nicklist_nick_changed]] nicklist_nick_changed | 0.4.1
| _buffer_ (_struct t_gui_buffer *_): buffer +
  _parent_group_ (_struct t_gui_nick_group *_): parent group +
  _nick_ (_struct t_gui_nick *_): nick
| Nick changed in nicklist.
|===

[NOTE]
^(1)^ _xxx_ è l'argomento del segnale usato nella redirezione, _yyy_ è lo schema
di redirezione.

Esempio in C:

[source,c]
----
int
my_hsignal_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_hsignal(signal: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_hsignal_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")
----

==== hook_hsignal_send

// TRANSLATION MISSING
_WeeChat ≥ 0.3.4, updated in 1.0, 4.5.0._

Invia un hsignal (segnale con tabella hash).

Prototipo:

[source,c]
----
int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);
----

Argomenti:

// TRANSLATION MISSING
* _signal_: segnale da inviare; flags are allowed before the signal name
  (see function <<_hook_signal_send,hook_signal_send>>) _(WeeChat ≥ 4.5.0)_
* _hashtable_: tabella hash

// TRANSLATION MISSING
Return value _(WeeChat ≥ 1.0)_:

// TRANSLATION MISSING
* return code of last callback executed (_WEECHAT_RC_OK_ if no callback was
  executed):
** _WEECHAT_RC_OK_
** _WEECHAT_RC_OK_EAT_
** _WEECHAT_RC_ERROR_

Esempio in C:

[source,c]
----
int rc, rc2;
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
    rc2 = weechat_hook_hsignal_send ("[flags:stop_on_error,ignore_eat]my_hsignal2", hashtable);
    weechat_hashtable_free (hashtable);
}
----

Script (Python):

[source,python]
----
# prototipo
def hook_hsignal_send(signal: str, hashtable: Dict[str, str]) -> int: ...

# esempio
rc = weechat.hook_hsignal_send("my_hsignal", {"key": "value"})
rc2 = weechat.hook_hsignal_send("[flags:stop_on_error,ignore_eat]my_hsignal2", {"key": "value"})
----

[[hsignal_irc_redirect_command]]
===== Hsignal irc_redirect_command

_WeeChat ≥ 0.3.4._

L'hsignal "irc_redirect_command" può essere inviato per redirigere l'output
di un comando irc ad una callback.

L'argomento è una tabella hash con le seguenti componenti (chiavi e valori
sono stringhe):

* _server_: nome interno del server (richiesto)
* _pattern_: schema di redirezione da usare (richiesto), sia uno di default
  (definito dal plugin irc), oppure definito dall'utente (consultare
  <<hsignal_irc_redirect_pattern>>), gli schemi predefiniti sono:
** _ison_
** _list_
** _mode_channel_
** _mode_channel_ban_ ("mode #channel b")
** _mode_channel_ban_exception_ ("mode #channel e")
** _mode_channel_invite_ ("mode #channel I")
** _mode_user_
** _monitor_
** _names_
** _ping_
** _time_
** _topic_
** _userhost_
** _who_
** _whois_
** _whowas_
* _signal_: nome segnale (richiesto)
* _count_: numero di volte in  cui verrà utilizzata la redirezione (opzionale, predefinito è 1)
* _string_: stringa che deve essere presente nei messaggi irc ricevuti (opzionale, ma
  raccomandata, se una stringa può essere usata per identificare i messaggi)
* _timeout_: timeout per la redirezione, in secondi (opzionale, predefiniti sono)
* _cmd_filter_: elenco separato da virgole di comandi irc da filtrare (solo questi
  comandi verranno inviati alle callback, altri ignorati) (opzionale)

Subito dopo aver inviato questo hsignal, è necessario inviare il comando al
server irc, e la redirezione verrà usata per questo comando.

Quando è stata ricevuta la risposta completa dal proprio comando, verrà
inviato un hsignal. Questo hsignal ha il nome _irc_redirection_xxx_yyy_ dove
_xxx_ è il segnale e _yyy_ lo _schema_ usato.

La tabella hash inviata in hsignal ha il seguente contenuto (chiavi e valori
sono stringhe):

* _output_: output del comando (i messaggi vengono separati da "\n")
* _output_size_: numero di byte in _output_ (come stringa)
* _error_: stringa di errore (in caso di errore):
** _timeout_: redirezione fermata dopo il timeout
* _server_: nome interno del server
* _pattern_: schema di redirezione
* _signal_: nome del segnale
* _command_: comando rediretto

Esempio in C:

[source,c]
----
int
test_whois_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "libera");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "libera;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}
----

Script (Python):

[source,python]
----
def test_whois_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          {"server": "libera", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "libera;;2;;/whois FlashCode")
----

[[hsignal_irc_redirect_pattern]]
===== Hsignal irc_redirect_pattern

_WeeChat ≥ 0.3.4._

L'hsignal "irc_redirect_pattern" può essere inviato per creare uno schema
per la redirezione irc (consultare <<hsignal_irc_redirect_command>>).

L'argomento è una tabella hash con le seguenti voci (chiavi e valori sono stringa):

* _pattern_: nome dello schema (richiesto)
* _timeout_: timeout predefinito per lo schema, in secondi (opzionale, predefinito è 60)
* _cmd_start_: elenco separato da virgole di comandi che avviano la redirezione (opzionale)
* _cmd_stop_: elenco separato da virgole di comandi che fermano la redirezione (richiesto)
* _cmd_extra_: elenco separato da virgole di comandi che possono essere ricevuti dopo aver
  fermato i comandi (opzionale)

Per ogni comando in _cmd_start_, _cmd_stop_ e _cmd_extra_, è possibile fornire
un intero con la posizione di "string" che va trovato nel messaggio ricevuto,
ad esempio:

----
352:1,354,401:1
----

Per i comandi 352 e 401, "string" deve essere trovata nel messaggio ricevuto,
come primo argomento.

[IMPORTANT]
Lo schema viene rimosso quando usato da una redirezione. Se uno schema si
rivelasse necessario per diverse redirezioni, è necessario crearne uno prima
di ogni redirezione.

Esempio in C:

[source,c]
----
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}
----

Script (Python):

[source,python]
----
weechat.hook_hsignal_send("irc_redirect_pattern",
                          {"pattern": "my_whois", "timeout": "30",
                           "cmd_start": "311:1",
                           "cmd_stop": "318:1,401:1,402:1,431:1,461",
                           "cmd_extra": "318:1"})
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...
----

==== hook_config

// TRANSLATION MISSING
_Updated in 1.5._

Hook su un'opzione di configurazione.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _option_: opzione, il formato è il nome completo, come usato con il comando
  `/set` (ad esempio: `+weechat.look.item_time_format+`), wildcard `+*+` is allowed
  (a priority is allowed before the option, see note about <<hook_priority,priority>>)
* _callback_: funzione chiamata quando l'opzione di configurazione è cambiata,
  argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *option_: nome dell'opzione
** _const char *value_: nuovo valore per l'opzione
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
int
my_config_cb (const void *pointer, 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, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_config(option: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_config_cb(data: str, option: str, value: str) -> int:
    # ...
    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", "")
----

==== hook_modifier

// TRANSLATION MISSING
_Updated in 1.5._

Hook su un modificatore.

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _modifier_: nome modificatore
  (a priority is allowed before the modifier, see note about <<hook_priority,priority>>)
  (see table below)
* _callback_: funzione chiamata quando viene usato il modificatore,
  argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *modifier_: nome del modificatore
** _const char *modifier_data_: dati per il modificatore
** _const char *string_: stringa da modificare
** valore restituito: nuova stringa
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

List of modifiers used by WeeChat and plugins:

[width="100%",cols="^2,^1,3,4,4",options="header"]
|===
// TRANSLATION MISSING
| Modificatore | Min WeeChat | Dati modificatore | Stringa | Output

// TRANSLATION MISSING
| [[hook_modifier_irc_batch]] irc_batch | 4.0.0
| Server name + "," + batch type + "," + batch parameters
| Content of multiple messages, separated by a newline char ("\n").
| New content of messages (number can be different), an empty string discards
  all messages in the batch.

// TRANSLATION MISSING
| [[hook_modifier_irc_cap_sync_req]] irc_cap_sync_req | 4.0.0
| Server name + "," + supported capabilities on server (separated by spaces)
| Capabilities to request (separated by spaces).
| New content of capabilities to request (separated by spaces).

// TRANSLATION MISSING
| [[hook_modifier_irc_in_xxx]] irc_in_xxx ^(1)^ |
| Nome server
| Contenuto del messaggio ricevuto dal server IRC (prima della codifica del set caratteri). +
  *Warning:* the string may contain invalid UTF-8 data; use only for raw
  operations on a message.
  Modifier <<hook_modifier_irc_in2_xxx,irc_in2_xxx>> is recommended instead.
| Nuovo contenuto del messaggio.

| [[hook_modifier_irc_in2_xxx]] irc_in2_xxx ^(1)^ | 0.3.5
| Nome server
| Contenuto del messaggio ricevuto dal server IRC (dopo la codifica del set caratteri).
| Nuovo contenuto del messaggio.

// TRANSLATION MISSING
| [[hook_modifier_irc_out1_xxx]] irc_out1_xxx ^(1)^ | 0.3.7
| Nome server
| Content of message about to be sent to IRC server before automatic split
  (to fit in 512 bytes by default).
| Nuovo contenuto del messaggio.

// TRANSLATION MISSING
| [[hook_modifier_irc_out_xxx]] irc_out_xxx ^(1)^ |
| Nome server
| Content of message about to be sent to IRC server after automatic split
  (to fit in 512 bytes by default).
| Nuovo contenuto del messaggio.

// TRANSLATION MISSING
| [[hook_modifier_relay_client_irc_in]] relay_client_irc_in | 4.0.0
| String with relay client pointer (eg: "0x1234abcd")
| Content of message received from relay IRC client.
| New content of message.

// TRANSLATION MISSING
| [[hook_modifier_relay_client_irc_out1]] relay_client_irc_out1 | 4.0.0
| String with relay client pointer (eg: "0x1234abcd")
| Content of message about to be sent to relay IRC client before automatic split
  (to fit in 512 bytes by default).
| New content of message.

// TRANSLATION MISSING
| [[hook_modifier_relay_client_irc_out]] relay_client_irc_out | 4.0.0
| String with relay client pointer (eg: "0x1234abcd")
| Content of message about to be sent to relay IRC client after automatic split
  (to fit in 512 bytes by default).
| New content of message.

// TRANSLATION MISSING
| [[hook_modifier_bar_condition_yyy]] bar_condition_yyy ^(2)^ |
| Stringa con puntatore alla finestra (eg: "0x1234abcd")
| Stringa vuota.
| "1" per visualizzare la barra, "0" per nasconderla.

// TRANSLATION MISSING
| [[hook_modifier_history_add]] history_add | 0.3.2
| Stringa con puntatore al buffer (eg: "0x1234abcd")
| Contenuto della riga di comando da aggiungere nella cronologia comandi (buffer e globale).
| Stringa aggiunta alla cronologia comandi.

// TRANSLATION MISSING
| [[hook_modifier_input_text_content]] input_text_content |
| Stringa con puntatore al buffer (eg: "0x1234abcd")
| Contenuto della riga di comando.
| Nuovo contenuto della riga di comando.

// TRANSLATION MISSING
| [[hook_modifier_input_text_display]] input_text_display |
| Stringa con puntatore al buffer (eg: "0x1234abcd")
| Contenuto della riga di comando, senza tag al cursore.
| Nuova stringa, solo da mostrare (la riga di comando non viene modificata).

// TRANSLATION MISSING
| [[hook_modifier_input_text_display_with_cursor]] input_text_display_with_cursor |
| Stringa con puntatore al buffer (eg: "0x1234abcd")
| Contenuto della riga di comando, con tag al cursore.
| Nuova stringa, solo da mostrare (la riga di comando non viene modificata).

// TRANSLATION MISSING
| [[hook_modifier_input_text_for_buffer]] input_text_for_buffer | 0.3.7
| Stringa con puntatore al buffer (eg: "0x1234abcd")
| Contenuto della riga di comando inviata al buffer (testo o comando).
| Nuovo contenuto della riga di comando inviata al buffer.

// TRANSLATION MISSING
| [[hook_modifier_weechat_print]] weechat_print |
| buffer pointer (eg: "0x1234abcd") + ";" + tags ^(3)^
| Messaggio stampato.
| Nuovo messaggio stampato. +
  For more information on the hooks called when a line is printed, see
  <<_hook_line,hook_line>>.
|===

[NOTE]
^(1)^ _xxx_ è il nome del comando IRC. +
^(2)^ _yyy_ è il nome della barra. +
^(3)^ With WeeChat ≤ 2.8, the format was: plugin + ";" + buffer_name + ";" + tags.

Esempio in C:

[source,c]
----
char *
my_modifier_cb (const void *pointer, void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;

    if (!string)
        return NULL;

    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* 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, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_modifier(modifier: str, callback: str, callback_data: str) -> str: ...

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

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

==== hook_modifier_exec

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 in caso di errore

// TRANSLATION MISSING
List of modifiers defined by WeeChat and plugins that can be used:

[width="100%",cols="^2,^1,3,4,4",options="header"]
|===
// TRANSLATION MISSING
| Modificatore | Min WeeChat | Dati modificatore | Stringa | Output

| [[hook_modifier_charset_decode]] charset_decode |
| plugin.buffer_name
| Qualsiasi stringa.
| Stringa codificata dal set caratteri trovato per plugin/buffer in UTF-8.

| [[hook_modifier_charset_encode]] charset_encode |
| plugin.buffer_name
| Qualsiasi stringa.
| Stringa codificata da UTF-8 al set caratteri trovato per il plugin/buffer.

// TRANSLATION MISSING
| [[hook_modifier_irc_color_decode]] irc_color_decode |
| "1" per mantenere i colori, "0" per rimuovere i colori
| Qualsiasi stringa.
| String with IRC colors converted to WeeChat colors (or IRC colors removed).

// TRANSLATION MISSING
| [[hook_modifier_irc_color_encode]] irc_color_encode |
| "1" per mantenere i colori, "0" per rimuovere i colori
| Qualsiasi stringa.
| String with IRC colors (or IRC colors removed).

// TRANSLATION MISSING
| [[hook_modifier_irc_color_decode_ansi]] irc_color_decode_ansi | 1.0
| "1" per mantenere i colori, "0" per rimuovere i colori
| Qualsiasi stringa.
| String with ANSI colors converted to IRC colors (or ANSI colors removed).

// TRANSLATION MISSING
| [[hook_modifier_irc_command_auth]] irc_command_auth | 0.4.1
| Nome server
| Authentication command (for example: `+/msg nickserv identify password+`).
| Command with hidden password (for example: `+/msg nickserv identify ********+`).

// TRANSLATION MISSING
| [[hook_modifier_irc_message_auth]] irc_message_auth | 0.4.1
| Nome server
| Message displayed after `/msg` sent to nickserv.
| Message with hidden password.

// TRANSLATION MISSING
| [[hook_modifier_irc_tag_escape_value]] irc_tag_escape_value | 3.3
| -
| Any string.
| String with IRC tag value escaped,
  see https://ircv3.net/specs/extensions/message-tags#escaping-values[this page ^↗^^].

// TRANSLATION MISSING
| [[hook_modifier_irc_tag_unescape_value]] irc_tag_unescape_value | 3.3
| -
| Any string.
| String with IRC tag value unescaped,
  see https://ircv3.net/specs/extensions/message-tags#escaping-values[this page ^↗^^].

// TRANSLATION MISSING
| [[hook_modifier_color_decode]] color_decode | 4.3.0
| Replacement string for colors removed
| Any string.
| String with WeeChat colors converted to a replacement string
  (colors stripped if the replacement string is empty).

// TRANSLATION MISSING
| [[hook_modifier_color_decode_ansi]] color_decode_ansi | 1.0
| "1" per mantenere i colori, "0" per rimuovere i colori
| Qualsiasi stringa.
| String with ANSI colors converted to WeeChat colors (or ANSI colors removed).

// TRANSLATION MISSING
| [[hook_modifier_color_encode_ansi]] color_encode_ansi | 2.7
| -
| Any string.
| String with WeeChat colors converted to ANSI colors.

// TRANSLATION MISSING
| [[hook_modifier_eval_path_home]] eval_path_home | 2.7
| Optional: `directory=xxx` where `xxx` can be: `config`, `data`, `cache`, `runtime`
| Any string.
| Evaluated path, result of the function
  <<_string_eval_path_home,string_eval_path_home>>.
|===

Esempio in C:

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

Script (Python):

[source,python]
----
# prototipo
def hook_modifier_exec(modifier: str, modifier_data: str, string: str) -> str: ...

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

==== hook_info

// TRANSLATION MISSING
_Updated in 1.5, 2.5._

Hook su una informazione (la callback prende e restituisce una stringa).

Prototipo:

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

Argomenti:

// TRANSLATION MISSING
* _info_name_: nome della info
  (a priority is allowed before the info name, see note about <<hook_priority,priority>>)
* _description_: descrizione
* _args_description_: descrizione degli argomenti
* _callback_: funzione chiamata alla richiesta di una info, argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *info_name_: nome della info
** _const char *arguments_: argomenti addizionali, dipendono dalle info
** valore restituito: valore dell'info richiesta
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

// TRANSLATION MISSING
[NOTE]
With WeeChat ≥ 2.5, the callback returns an allocated string
(with WeeChat ≤ 2.4, it was a pointer to a static string).

Esempio in C:

[source,c]
----
char *
my_info_cb (const void *pointer, void *data, const char *info_name,
            const char *arguments)
{
    /* ... */
    return strdup ("some_info");
}

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

Script (Python):

[source,python]
----
# prototipo
def hook_info(info_name: str, description: str, args_description: str,
              callback: str, callback_data: str) -> str: ...

# esempio
def my_info_cb(data: str, info_name: str, arguments: str) -> str:
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")
----

==== hook_info_hashtable

// TRANSLATION MISSING
_WeeChat ≥ 0.3.4, updated in 1.5._

Hook su una informazione (la callback prende e restituisce una tabella hash).

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(const void *pointer,
                                                                            void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            const void *callback_pointer,
                                            void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _info_name_: nome della info
  (a priority is allowed before the info name, see note about <<hook_priority,priority>>)
* _description_: descrizione
* _args_description_: descrizione della tabella hash attesa (opzionale, può
  essere NULL)
* _output_description_: descrizione della tabella hash restituita dalla
  callback (opzionale, può essere NULL)
* _callback_: funzione chiamata alla richiesta della info, argomenti e valore
  restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *info_name_: nome della info
** _struct t_hashtable *hashtable_: tabella hash, in base alla info
** valore restituito: tabella hash richiesta
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hashtable *
my_info_hashtable_cb (const void *pointer, void *data, const char *info_name,
                      struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_info_hashtable(info_name: str, description: str, args_description: str,
                        output_description: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_info_hashtable_cb(data: str, info_name: str, hashtable: Dict[str, str]) -> Dict[str, str]:
    return {"test_key": "test_value"}

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")
----

==== hook_infolist

// TRANSLATION MISSING
_Updated in 1.5._

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,
                                      struct t_infolist *(*callback)(const void *pointer,
                                                                     void *data,
                                                                     const char *infolist_name,
                                                                     void *obj_pointer,
                                                                     const char *arguments),
                                      const void *callback_pointer,
                                      void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _infolist_name_: nome della lista info
  (a priority is allowed before the infolist name, see note about <<hook_priority,priority>>)
* _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 e
  valore restituito:
** _const void *pointer_: puntatore
** _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
** valore restituito: lista info richiesta
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_infolist *
my_infolist_cb (const void *pointer, void *data, const char *infolist_name,
                void *obj_pointer, const char *arguments)
{
    struct t_infolist *my_infolist;

    /* compila lista info */
    /* ... */

    return my_infolist;
}

/* aggiunge lista info "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, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_infolist(infolist_name: str, description: str, pointer_description: str,
                  args_description: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_infolist_cb(data: str, infolist_name: str, pointer: str, arguments: str) -> str:
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")
----

==== hook_hdata

// TRANSLATION MISSING
_Updated in 1.5._

Hook di un hdata: la callback restituisce il puntatore all'hdata richiesto.

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(const void *pointer,
                                                               void *data,
                                                               const char *hdata_name),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _hdata_name_: nome dell'hdata
  (a priority is allowed before the hdata name, see note about <<hook_priority,priority>>)
* _description_: descrizione
* _callback_: funzione chiamata alla richiesta di hdata, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _const char *hdata_name_: nome dell'hdata
** return value: hdata richiesto
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hdata *
my_hdata_cb (const void *pointer, void *data, const char *hdata_name)
{
    struct t_hdata *my_hdata;

    /* build hdata */
    /* ... */

    return my_hdata;
}

/* add hdata "my_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                              "Hdata for my structure",
                                              &my_hdata_cb, NULL, NULL);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hook_focus

// TRANSLATION MISSING
_Updated in 1.5, 4.0.0, 4.1.0._

Hook sul foucus: evento del mouse o tasto premuto nella modalità cursore
(movimento libero del cursore).

Prototipo:

[source,c]
----
struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(const void *pointer,
                                                                   void *data,
                                                                   struct t_hashtable *info),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Argomenti:

// TRANSLATION MISSING
* _area_: "chat" per la zona di chat, o il nome di un elemento barra
  (a priority is allowed before the area, see note about <<hook_priority,priority>>)
* _callback_: funzione chiamata al momento del focus, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_hashtable *info_: tabella hash con informazioni sul focus e
   stringhe restituite da altre chiamate alle callback sul focus (con la
   priorità più alta) (consultare la tabella in basso)
** valore restituito: sia il puntatore "info" tabella hash completa), o il
   puntatore ad una nuova tabella hash (creata dalla callback, con chiavi e
   valori di tipo "string), questa nuovo contenuto della tabella hash verrà
   aggiunto ad _info_ per le altre chiamate alle callback del focus
* _callback_pointer_: puntatore fornito alla callback quando chiamata da WeeChat
// TRANSLATION MISSING
* _callback_data_: puntatore fornito alla callback quando chiamata da WeeChat;
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

[IMPORTANT]
Per l'azione di un mouse, la callback verrà chiamata due volte: la prima quando
il pulsante viene premuto (qui la zona corrisponde sempre alla propria area), la
seconda quando il pulsante viene rilasciato, e allora la zona potrà non
corrispondere con la propria: per cui bisogna *sempre* verificare nella propria
callback se l'area corrisponde prima di usare le informazioni nella tabella hash.

Contenuto della tabella hash inviata alla callback (tasti e valori sono di tipo
"string"):

[width="100%",cols="5,5,8,3",options="header"]
|===
| Key ^(1)^ | Descrizione | Valori di esempio | Valore se N/D

| _x | Colonna sullo schermo.
| "0" ... "n" |

| _y | Riga sullo schermo.
| "0" ... "n" |

| _key | Evento tasto o mouse.
| "button1", "button2-gesture-left", ... |

| _window | Puntatore alla finestra.
| "0x1234abcd" | ""

| _window_number | Numero della finestra.
| "1" ... "n" | "*"

| _buffer | Puntatore al buffer.
| "0x1234abcd" | ""

| _buffer_number | Numero del buffer.
| "1" ... "n" | "-1"

| _buffer_plugin | Nome plugin del buffer.
| "core", "irc", ... | ""

| _buffer_name | Nome del buffer.
| "weechat", "libera.#weechat", ... | ""

| _buffer_full_name | Nome completo del buffer.
| "core.weechat", "irc.libera.#weechat", ... | ""

| _buffer_localvar_XXX ^(2)^ | Variabili locali del buffer.
| qualsiasi valore | non impostato

| _chat | Indicatore area di chat.
| "0" o "1" | "0"

// TRANSLATION MISSING
| _chat_line | Pointer to line _(WeeChat ≥ 1.2)_.
| "0x1234abcd" | ""

| _chat_line_x | Colonna nella riga ^(3)^.
| "0" ... "n" | "-1"

| _chat_line_y | Numero della riga ^(3)^.
| "0" ... "n" | "-1"

| _chat_line_date | Riga con data/ora.
| "1313237175" | "0"

// TRANSLATION MISSING
| _chat_line_date_usec | Microseconds of line date/time.
| "123456" | "0"

| _chat_line_date_printed | Riga con data/ora ^(4)^.
| "1313237175" | "0"

// TRANSLATION MISSING
| _chat_line_date_usec_printed | Microseconds of line printed date/time ^(4)^.
| "123456" | "0"

| _chat_line_time | Ora visualizzata.
| "14:06:15" | ""

| _chat_line_tags | Tag della riga.
| "irc_privmsg,nick_flashy,log1" | ""

| _chat_line_nick | Nick della riga.
| "FlashCode" | ""

| _chat_line_prefix | Prefisso della riga.
| "@FlashCode" | ""

| _chat_line_message | Messaggio della riga.
| "Hello world!" | ""

// TRANSLATION MISSING
| _chat_focused_line | Line at (x, y) _(WeeChat ≥ 4.0.0)_.
| "Hello world!" | ""

// TRANSLATION MISSING
| _chat_focused_line_bol | Text from beginning of line to (x-1, y) _(WeeChat ≥ 4.1.0)_.
| "Hello" | ""

// TRANSLATION MISSING
| _chat_focused_line_eol | Text from (x, y) to end of line _(WeeChat ≥ 4.1.0)_.
| "llo world!" | ""

| _chat_word | Parola a (x,y).
| "Hello" | ""

// TRANSLATION MISSING
| _chat_bol | Text from beginning of message to (x-1, y).
| "He" | ""

// TRANSLATION MISSING
| _chat_eol | Text from (x, y) to the end of message.
| "llo world!" | ""

| _bar_name | Nome della barra.
| "title", "nicklist", ... | ""

| _bar_filling | Riempimento della barra.
| "horizontal", "vertical", ... | ""

| _bar_item_name | Nome dell'elemento barra.
| "buffer_nicklist", "hotlist", ... | ""

| _bar_item_line | Riga nell'elemento barra.
| "0" ... "n" | "-1"

| _bar_item_col | Colonna nell'elemento barra.
| "0" ... "n" | "-1"

// TRANSLATION MISSING
| _bar_window | Pointer to bar window _(WeeChat ≥ 2.9)_.
| "0x1234abcd" | ""
|===

[NOTE]
^(1)^ Ci sono alcune chiavi con il suffisso "2" (es: "_x2", "_y2", "_window2",
...) con informazioni sul secondo punto (utile solo per le azioni del mouse,
per sapere dove il pulsante del mouse è stato rilasciato). +
^(2)^ `XXX` è il nome della variabile locale nel buffer. +
^(3)^ È impostato solo per l buffer con contenuto libero. +
^(4)^ Data/ora in cui WeeChat aggiunge una riga nel buffer (maggiore o uguale a
"chat_line_date").

Informazioni aggiuntive per l'elemento barra "buffer_nicklist":

[width="100%",cols="^1,^1,5",options="header"]
|===
| Plugin ^(1)^ | Chiave   | Descrizione
// TRANSLATION MISSING
| irc          | irc_nick | Pointer to IRC nick _(WeeChat ≥ 3.0)_.
| irc          | irc_host | Host per il nick (se conosciuto).
| weechat      | nick     | Nick.
| weechat      | prefix   | Prefisso per il nick.
| weechat      | group    | Nome gruppo.
|===

[NOTE]
^(1)^ Il nome del plugin che definisce un hook_focus per restituire
informazioni su questo elemento della barra (ad esempio se il plugin è "irc",
tale informazione sarà disponibile solo sui buffer irc).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hashtable *
my_focus_nicklist_cb (const void *pointer, void *data, struct t_hashtable *info)
{
    /* add strings in hashtable */
    /* ... */

    return info;
}

/* add focus on nicklist */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def hook_focus(area: str, callback: str, callback_data: str) -> str: ...

# esempio
def my_focus_nicklist_cb(data: str, info: Dict[str, str]) -> Dict[str, str]:
    # build dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")
----

==== hook_set

_WeeChat ≥ 0.3.9 (script: WeeChat ≥ 0.4.3)._

// TRANSLATION MISSING
Set string value of a hook property.

Prototipo:

[source,c]
----
void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);
----

Argomenti:

* _hook_: qualcosa su cui è presente un hook con "weechat_hook_xxx()"
// TRANSLATION MISSING
* _property_: nome della proprietà (see table below)
// TRANSLATION MISSING
* _value_: new value for property

// TRANSLATION MISSING
Properties:

// TRANSLATION MISSING
[width="100%",cols="^1,^1,2,2,5",options="header"]
|===
// TRANSLATION MISSING
| Nome | Min WeeChat | Hook type | Valore | Descrizione

// TRANSLATION MISSING
| subplugin | | any type

| qualsiasi stringa |
// TRANSLATION MISSING
  Name of sub plugin (commonly script name, which is displayed in
  `/help command` for a hook of type _command_).

// TRANSLATION MISSING
| keep_spaces_right | 4.6.0 | _command_, _command_run_
| "0" or "1"
| Keep trailing spaces in command arguments when it is executed.

| stdin | 0.4.3 | _process_, _process_hashtable_ | qualsiasi stringa |
// TRANSLATION MISSING
  Send data on standard input (_stdin_) of child process.

// TRANSLATION MISSING
| stdin_close | 0.4.3 | _process_, _process_hashtable_ | (not used) |
// TRANSLATION MISSING
  Close pipe used to send data on standard input (_stdin_) of child process.

| signal | 1.0 | _process_, _process_hashtable_ |
// TRANSLATION MISSING
  signal number or one of these names: `hup`, `int`, `quit`, `kill`, `term`,
  `usr1`, `usr2` |
// TRANSLATION MISSING
  Send a signal to the child process.
|===

Esempio in C:

[source,c]
----
struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");
----

Script (Python):

[source,python]
----
# prototipo
def hook_set(hook: str, property: str, value: str) -> int: ...

# esempio
def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process_hashtable("/path/to/command", {"stdin": "1"},
                                      20000, "my_process_cb", "")
weechat.hook_set(hook, "stdin", "data sent to stdin of child process")
weechat.hook_set(hook, "stdin_close", "")  # optional
----

==== unhook

Rimuove un 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
def unhook(hook: str) -> int: ...

# esempio
weechat.unhook(my_hook)
----

==== unhook_all

// TRANSLATION MISSING
_Updated in 1.5._

Rimuove l'hook in qualsiasi punto in cui è stato attivato dal
plugin corrente.

Prototipo:

[source,c]
----
void weechat_unhook_all (const char *subplugin);
----

Argomenti:

// TRANSLATION MISSING
* _subplugin_: if not NULL, unhook only hooks with this "subplugin" set
  (this argument is not available in scripting API)

Esempio in C:

[source,c]
----
weechat_unhook_all (NULL);
----

Script (Python):

[source,python]
----
# prototipo
def unhook_all() -> int: ...

# esempio
weechat.unhook_all()
----

[[buffers]]
=== Buffer

Funzioni per creare/richiedere/chiudere buffer.

==== buffer_new

// TRANSLATION MISSING
_Updated in 1.5._

Apre un nuovo buffer.

// TRANSLATION MISSING
[NOTE]
If you want to immediately set buffer properties (buffer type, local variables,
key bindings, etc.), then better use the function <<_buffer_new_props,buffer_new_props>>
which sets these properties during the buffer creation, before sending signal
<<hook_signal_buffer_opened,buffer_opened>>.

Prototipo:

[source,c]
----
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         const void *input_callback_pointer,
                                         void *input_callback_data,
                                         int (*close_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer),
                                         const void *close_callback_pointer,
                                         void *close_callback_data);
----

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 e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: puntatore al buffer
** _const char *input_data_: dati in input
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _input_callback_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _input_callback_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the buffer is closed
* _close_callback_: funzione chiamata alla chiusura del buffer, argomenti e
  valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: puntatore al buffer
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _close_callback_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _close_callback_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the buffer is closed

Valore restituito:

* puntatore al nuovo buffer, NULL in caso di errore

Esempio in C:

[source,c]
----
int
my_input_cb (const void *pointer, void *data,
             struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Testo: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Il buffer '%s' verrà chiuso!",
                    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, NULL,
                                                     &my_close_cb, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def buffer_new(name: str, input_callback: str, input_callback_data: str,
               close_callback: str, close_callback_data: str) -> str: ...

# esempio
def my_input_cb(data: str, buffer: str, input_data: str) -> int:
    weechat.prnt(buffer, "Testo: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data: str, buffer: str) -> int:
    weechat.prnt("", "Il buffer '%s' verrà chiuso!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
----

==== buffer_new_props

_WeeChat ≥ 3.5._

// TRANSLATION MISSING
Open a new buffer and apply properties.

Prototipo:

[source,c]
----
struct t_gui_buffer *weechat_buffer_new_props (const char *name,
                                               struct t_hashtable *properties,
                                               int (*input_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer,
                                                                     const char *input_data),
                                               const void *input_callback_pointer,
                                               void *input_callback_data,
                                               int (*close_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_buffer *buffer),
                                               const void *close_callback_pointer,
                                               void *close_callback_data);
----

Argomenti:

* _name_: nome del buffer (deve essere unico per il plugin)
// TRANSLATION MISSING
* _properties_: properties to apply
  (see function <<_buffer_set,buffer_set>> for the allowed properties)
* _input_callback_: funzione chiamata quando il testo in input è stato
  inserito nel buffer, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: puntatore al buffer
** _const char *input_data_: dati in input
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _input_callback_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _input_callback_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the buffer is closed
* _close_callback_: funzione chiamata alla chiusura del buffer, argomenti e
  valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_buffer *buffer_: puntatore al buffer
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _close_callback_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _close_callback_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the buffer is closed

Valore restituito:

* puntatore al nuovo buffer, NULL in caso di errore

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
int
my_input_cb (const void *pointer, void *data,
             struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Testo: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Il buffer '%s' verrà chiuso!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_hashtable *properties = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);
/* buffer with free content */
weechat_hashtable_set (properties, "type", "free");
/* no logging on this buffer */
weechat_hashtable_set (properties, "localvar_set_no_log", "1");
/* bind key alt-c on this buffer */
weechat_hashtable_set (properties, "key_bind_meta-c", "/my_command");

struct t_gui_buffer *my_buffer = weechat_buffer_new_props ("my_buffer",
                                                           properties,
                                                           &my_input_cb, NULL, NULL,
                                                           &my_close_cb, NULL, NULL);
----

Script (Python):

// TRANSLATION MISSING
[source,python]
----
# prototipo
def buffer_new_props(name: str, properties: Dict[str, str],
                     input_callback: str, input_callback_data: str,
                     close_callback: str, close_callback_data: str) -> str: ...

# esempio
def my_input_cb(data: str, buffer: str, input_data: str) -> int:
    weechat.prnt(buffer, "Testo: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data: str, buffer: str) -> int:
    weechat.prnt("", "Il buffer '%s' verrà chiuso!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

properties = {
    "type": "free",                    # buffer with free content
    "localvar_set_no_log": "1",        # no logging on this buffer
    "key_bind_meta-c": "/my_command",  # bind key alt-c on this buffer
}
buffer = weechat.buffer_new_props("my_buffer", properties, "my_input_cb", "", "my_close_cb", "")
----

==== 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
def current_buffer() -> str: ...

# esempio
weechat.prnt(weechat.current_buffer(), "Testo sul buffer corrente")
----

==== buffer_search

// TRANSLATION MISSING
_Updated in 1.0, 4.3.0._

// TRANSLATION MISSING
Search a buffer by plugin/name, full name or unique identifier (`id`).

Prototipo:

[source,c]
----
struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);
----

Argomenti:

// TRANSLATION MISSING
* _plugin_: name of plugin, following special values are allowed:
** `+==+`: the name used is the buffer full name (for example:
   `irc.libera.#weechat` instead of `libera.#weechat`)
   _(WeeChat ≥ 1.0)_
// TRANSLATION MISSING
** `+==id+`: the name used is the buffer unique identifier (`id`) _(WeeChat ≥ 4.3.0)_
// TRANSLATION MISSING
* _name_: name of buffer, if it is NULL or empty string, the current buffer is
  returned (buffer displayed by current window); if the name starts with
  `(?i)`, the search is case-insensitive _(WeeChat ≥ 1.0)_

Valore restituito:

* puntatore al buffer trovato, NULL in caso contrario

Esempio in C:

[source,c]
----
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.libera.#test");  /* WeeChat ≥ 1.0 */
struct t_gui_buffer *buffer3 = weechat_buffer_search ("==id", "1709797810942688");  /* WeeChat ≥ 4.3.0 */
----

Script (Python):

[source,python]
----
# prototipo
def buffer_search(plugin: str, name: str) -> str: ...

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
----

==== 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
def buffer_search_main() -> str: ...

# esempio
buffer = weechat.buffer_search_main()
----

==== 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
def buffer_clear(buffer: str) -> int: ...

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer:
    weechat.buffer_clear(buffer)
----

==== 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
def buffer_close(buffer: str) -> int: ...

# esempio
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----

==== 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
def buffer_merge(buffer: str, target_buffer: str) -> int: ...

# esempio
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----

==== 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
def buffer_unmerge(buffer: str, number: int) -> int: ...

# esempio
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----

==== 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à:
// TRANSLATION MISSING
** _opening_: 1 if buffer is opening, otherwise 0 _(WeeChat ≥ 4.2.0)_
** _number_: numero del buffer (inizia da 1)
** _layout_number_: numero del buffer salvato nel layout
** _layout_number_merge_order_: ordine di unione per i layout
** _type_: tipo dibuffer (0: formattato, 1: contenuto libero)
** _notify_: livello di notifica per il buffer
** _num_displayed_: numero delle finestre che visualizzano il buffer
// TRANSLATION MISSING
** _active_: 2 if buffer is the only active (merged), 1 se il buffer è attivo, 0 se il buffer è unito e non selezionato
// TRANSLATION MISSING
** _hidden_: 1 if buffer is hidden, otherwise 0 _(WeeChat ≥ 1.0)_
// TRANSLATION MISSING
** _zoomed_: 1 if buffer is merged and zoomed, otherwise 0 _(WeeChat ≥ 1.0)_
** _print_hooks_enabled_: 1 se gli hook sulla stampa sono abilitati, altrimenti 0
// TRANSLATION MISSING
** _day_change_: 1 if messages for the day change are displayed, otherwise 0 _(WeeChat ≥ 0.4.3)_
// TRANSLATION MISSING
** _clear_: 1 if buffer can be cleared with command `/buffer clear`, otherwise 0 _(WeeChat ≥ 1.0)_
// TRANSLATION MISSING
** _filter_: 1 if filters are enabled on buffer, otherwise 0 _(WeeChat ≥ 1.0)_
// TRANSLATION MISSING
** _closing_: 1 if buffer is closing, otherwise 0 _(WeeChat ≥ 1.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
// TRANSLATION MISSING
** _next_line_id_: next line id in buffer _(WeeChat ≥ 3.8)_
** _time_for_each_line_: 1 se l'ora è visualizzata per ogni riga nel buffer (predefinito), altrimenti 0
** _nicklist_: 1 se la lista nick è abilitata, altrimenti 0
** _nicklist_case_sensitive_: 1 se i nick sono sensibili alle maiuscole, altrimenti 0
** _nicklist_max_length_: lunghezza massima per un nick
** _nicklist_display_groups_: 1 se i gruppi vengono visualizzati, altrimenti 0
// TRANSLATION MISSING
** _nicklist_count_: number of nicks and groups in nicklist
// TRANSLATION MISSING
** _nicklist_visible_count_: numero di nick/gruppi visualizzati
** _nicklist_groups_count_: number of groups in nicklist
// TRANSLATION MISSING
** _nicklist_groups_visible_count_: number of groups displayed
// TRANSLATION MISSING
** _nicklist_nicks_count_: number of nicks in nicklist
// TRANSLATION MISSING
** _nicklist_nicks_visible_count_: number of nicks displayed
** _input_: 1 se l'input è abilitato, altrimenti 0
// TRANSLATION MISSING
** _input_get_any_user_data_: 1 if any user data, including commands, are sent to input callback, otherwise 0
** _input_get_unknown_commands_: 1 se i comandi sconosciuti vengono inviati alla callback di input, altrimenti 0
// TRANSLATION MISSING
** _input_get_empty_: 1 if empty input is sent to input callback, otherwise 0
// TRANSLATION MISSING
** _input_multiline_: 1 if multiple lines are sent as one message to input callback, otherwise 0
** _input_size_: dimensione per l'input (in byte)
** _input_length_: lunghezza dell'input (numero di caratteri)
** _input_pos_: posizione del cursore nell'input del buffer
** _input_1st_display_: primo carattere visualizzato su schermo
** _num_history_: numero di comandi nella cronologia
** _text_search_: tipo di ricerca nel testo:
*** 0: nessuna ricerca in questo momento
// TRANSLATION MISSING
*** 1: search in buffer lines
// TRANSLATION MISSING
*** 2: search in commands history
// TRANSLATION MISSING
** _text_search_direction_: direction for search:
// TRANSLATION MISSING
*** 0: backward search (direction: oldest messages/commands)
// TRANSLATION MISSING
*** 1: forward search (direction: newest messages/commands)
** _text_search_exact_: 1 se la ricerca testo è esatta
// TRANSLATION MISSING
** _text_search_regex_: 1 if searching with a regular expression
** _text_search_where_:
*** 0: nessuna ricerca in questo momento
// TRANSLATION MISSING
*** 1: search in message
// TRANSLATION MISSING
*** 2: search in prefix
// TRANSLATION MISSING
*** 3: search in prefix and message
** _text_search_history_:
*** 0: nessuna ricerca in questo momento
// TRANSLATION MISSING
*** 1: search in buffer local history
// TRANSLATION MISSING
*** 2: search in global history
** _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
def buffer_get_integer(buffer: str, property: str) -> int: ...

# esempio
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
----

==== 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à:
// TRANSLATION MISSING
** _id_: unique identifier _(WeeChat ≥ 4.3.0)_
** _plugin_: nome del plugin che ha creato questo buffer ("core" per il buffer principale di WeeChat)
** _name_: nome del buffer
** _full_name_: nome completo del buffer ("plugin.nome") _(WeeChat ≥ 0.3.7)_
// TRANSLATION MISSING
** _old_full_name_: old full name of buffer ("plugin.name"), set before the buffer is renamed _(WeeChat ≥ 2.8)_
** _short_name_: nome breve del buffer (nota: usato solo per il display e può essere cambiato dall'utente, questo nome non va usato per trovare il nome del buffer, utilizzare invece _name_, _fullname_ o la variabile locale _channel_)
// TRANSLATION MISSING
** _type_: type of buffer: "formatted" or "free" _(WeeChat ≥ 4.2.0)_
** _title_: titolo del buffer
// TRANSLATION MISSING
** _modes_: modes _(WeeChat ≥ 4.3.0)_
// TRANSLATION MISSING
** _nicklist_last_id_assigned_: last unique identifier used in this buffer for a group or nick _(WeeChat ≥ 4.3.0)_
// TRANSLATION MISSING
** _input_prompt_: input prompt _(WeeChat ≥ 4.3.0)_
** _input_: testo in ingresso
** _text_search_input_: input salvato prima della ricerca nel testo
** _highlight_words_: elenco di parole da evidenziare
// TRANSLATION MISSING
** _highlight_disable_regex_: POSIX extended regular expression for disabling highlight
// TRANSLATION MISSING
** _highlight_regex_: POSIX extended regular expression for highlight
// TRANSLATION MISSING
** _highlight_tags_restrict_: restrict highlights to messages with these tags
// TRANSLATION MISSING
** _highlight_tags_: force highlight on messages with these tags
** _hotlist_max_level_nicks_: livello massimo della hotlist per alcuni nick
** _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
def buffer_get_string(buffer: str, property: str) -> str: ...

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

==== buffer_get_pointer

Restituisce il valore puntatore della proprietà di un buffer.

Prototipo:

[source,c]
----
void *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)
// TRANSLATION MISSING
** _text_search_regex_compiled_: compiled regular expression
// TRANSLATION MISSING
** _text_search_ptr_history_: history found
** _highlight_disable_regex_compiled_: espressione regolare _highlight_disable_regex_ compilata
** _highlight_regex_compiled_: espressione regolare _highlight_regex_ compilata

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,c]
----
weechat_printf (NULL, "plugin pointer of my buffer: %p",
                weechat_buffer_get_pointer (my_buffer, "plugin"));
----

Script (Python):

[source,python]
----
# prototipo
def buffer_get_pointer(buffer: str, property: str) -> str: ...

# esempio
weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----

==== 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
// TRANSLATION MISSING
* _property_: nome della proprietà (see table below)
// TRANSLATION MISSING
* _value_: new value for property

// TRANSLATION MISSING
Properties:

[width="100%",cols="^2,^1,4,8",options="header"]
|===
// TRANSLATION MISSING
| Nome | Min WeeChat | Valore | Descrizione

// TRANSLATION MISSING
| hotlist | | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1"
// TRANSLATION MISSING
| "+": 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à
  (conditions defined in option _weechat.look.hotlist_add_conditions_
  are *NOT* checked) +
  "-1": remove buffer from hotlist _(WeeChat ≥ 1.0)_.

// TRANSLATION MISSING
| hotlist_conditions | 4.5.0 | WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT
| priority: add buffer to hotlist with this priority
  (conditions defined in option _weechat.look.hotlist_add_conditions_
  are checked).

// TRANSLATION MISSING
| completion_freeze | | "0" oppure "1"
| "0": no freeze of completion (default value)
  (impostazione globale, il puntatore al buffer non è utilizzato) +
  "1": do not stop completion when command line is updated
  (impostazione globale, il puntatore al buffer non è utilizzato).

// TRANSLATION MISSING
| unread | | empty string, "0", "+N", "-N" or "N" (N is integer)
| empty string: set unread marker after last line of buffer +
  "0": remove unread marker from buffer +
  "N": move the unread marker N lines from the end towards the first line of buffer +
  "-N": move the unread marker N lines towards the first line of buffer +
  "+N": move the unread marker N lines towards the last line of buffer.

| display | | "1" oppure "auto"
| "1": passa a questo buffer nella finestra corrente +
  "auto": passa a questo buffer nella finestra corrente, l'evidenziatore di
  lettura non viene resettato.

// TRANSLATION MISSING
| hidden | 1.0 | "0" oppure "1"
| "0": unhide the buffer +
  "1": hide the buffer.

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

// TRANSLATION MISSING
| type | | "formatted" oppure "free"
| Imposta tipo per il: "formatted" (per stampare i messaggi di chat),
  oppure "free" (per contenuto libero); when the value is "free", the property
  _clear_ is forced to "0" _(WeeChat ≥ 1.0)_.

| notify | | "0", "1", "2", "3"
| Imposta il livello di notifica per il buffer: "0" = non aggiungere alla hotlist,
  "1" = aggiungere solo per gli eventi, "2" = aggiungere per eventi e
  messaggi, "3" = aggiungere per tutti i messaggi.

// TRANSLATION MISSING
| print_hooks_enabled | | "0" oppure "1"
| "0" to disable print hooks, "1" to enable them (default for a new buffer).

// TRANSLATION MISSING
| day_change | 0.4.3 | "0" oppure "1"
| "0" to hide messages for the day change, "1" to see them
  (default for a new buffer).

// TRANSLATION MISSING
| clear | 1.0 | "0" or "1"
| "0" to prevent user from clearing buffer with the command `/buffer clear`,
  "1" to let user clear the buffer (default for a new buffer)
   (note: even when it is set to "0", the buffer can still be cleared with
   the function <<_buffer_clear,buffer_clear>>).

// TRANSLATION MISSING
| filter | 1.0 | "0" or "1"
| "0": disable filters on buffer +
  "1": enable filters on buffer.

| title | | qualsiasi stringa
| Imposta nuovo titolo per il buffer.

// TRANSLATION MISSING
| modes | 4.3.0 | any string
| Set new modes for buffer.

| time_for_each_line | | "0" oppure "1"
| "0" per nascondere l'orario in tutte le righe del buffer, "1" per
  visualizzarlo su tutte le righe (predefinito per un nuovo buffer).

| nicklist | | "0" oppure "1"
| "0" per rimuovere la lista nick per il buffer, "1" per aggiungere
  la lista nick per il buffer.

| nicklist_case_sensitive | | "0" oppure "1"
| "0" per avere una lista nick non sensibile alle maiuscole, "1" per
  una lista nick sensibile alle maiuscole.

| nicklist_display_groups | | "0" oppure "1"
| "0" per nascondere i gruppi nella lista nick, "1" per visualizzare
  i gruppi della lista nick.

| highlight_words | | "-" oppure elenco di parole separato da virgole
| "-" è un valore speciale per disabilitare qualsiasi evento su questo
  buffer, o un elenco di parole separate da virgole da evidenziare in
  questo buffer, ad esempio: "abc,def,ghi".

| highlight_words_add | | elenco di parole separate da virgole
| Elenco di parole separate da virgole da evidenziare in questo buffer,
  queste parole vengono aggiunte alle parole evidenziate esistenti nel
  buffer.

| highlight_words_del | | elenco di parole separate da virgole
| Elenco di parole separate da virgole da rimuovere dalle
  parole evidenziate nel buffer.

// TRANSLATION MISSING
| highlight_disable_regex | | any string
| POSIX extended regular expression for disabling highlight.

// TRANSLATION MISSING
| highlight_regex | | qualsiasi stringa
| POSIX extended regular expression for highlight.

// TRANSLATION MISSING
| highlight_tags_restrict | | elenco separato da virgole di tag
| Restrict highlights to messages with these tags in this buffer
  (it is possible to combine many tags as a logical "and" with separator "+",
  for example: "nick_toto+irc_action").

// TRANSLATION MISSING
| highlight_tags | | elenco separato da virgole di tag
| Force highlight on messages with these tags in this buffer
  (it is possible to combine many tags as a logical "and" with separator "+",
  for example: "nick_toto+irc_action").

| hotlist_max_level_nicks | | elenco separado da virgole di "nick:livello"
| Elenco separato da virgole di nick con il livello massimo per la hotlist
  su questo buffer (il livello può essere: -1: mai nella hotlist, 0: basso,
  1: messaggio, 2: privato, 3: evento), ad esempio: "joe:2,mike:-1,robert:-1"
  (joe non produce eventi sul buffer, mike e robert non modificano la hotlist).

| hotlist_max_level_nicks_add | | elenco separato da virgole di "nick:livello"
| Elenco separato da virgole di nick con il livello per la hotlist, questi
  nick vengono aggiunti a quelli esistenti nel buffer.

| hotlist_max_level_nicks_del | | elenco separato da virgole di nick
| Elenco separato da virgole di nick da rimuovere dai livelli massimi della
  hotlist.

| key_bind_xxx | | qualsiasi stringa
| Assegna un nuovo tasto _xxx_, specifico per questo buffer, il valore è il
  comando da eseguire per questo tasto.

| key_unbind_xxx | | -
| Rimuove l'assegnazione del tasto _xxx_ per questo buffer.

// TRANSLATION MISSING
| input_prompt | 4.3.0 | any string
| Set new value for input prompt.

| input | | qualsiasi stringa
| Imposta un nuovo valore per l'input del buffer.

| input_pos | | posizione
| Imposta la posizione del cursore per l'input del buffer.

// TRANSLATION MISSING
| input_get_any_user_data | 4.3.0 | "0" or "1"
| "0" to get only user messages (default behavior), "1" to get everything,
  including commands.

| input_get_unknown_commands | | "0" oppure "1"
| "0" per disabilitare i comandi sconosciuti per questo buffer (comportamento
  predefinito), "1" per ricevere i comandi sconosciuti, ad esempio se l'utente
  digita "/unknowncmd", verrà ricevuto dal buffer (nessun errore riguardo il
  comando sconosciuto).

// TRANSLATION MISSING
| input_get_empty | | "0" oppure "1"
| "0" to disable empty input on this buffer (default behavior), "1" to get empty input.

// TRANSLATION MISSING
| input_multiline | | "0" or "1"
| "0" to send each line separately to this buffer (default behavior), "1" to
  send multiple lines as a single message.

| localvar_set_xxx | | qualsiasi stringa
| Imposta il nuovo valore per la variabile locale _xxx_ (la variabile verrà
  creata se non esiste).

| localvar_del_xxx | | -
| Rimuove la variabile locale _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", "");
----

Script (Python):

[source,python]
----
# prototipo
def buffer_set(buffer: str, property: str, value: str) -> int: ...

# esempi

# disabilita hotlist (per tutti i buffer)
weechat.buffer_set("", "hotlist", "-")

# abilita nuovamente hotlist
weechat.buffer_set("", "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", "")
----

==== 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_: nome della proprietà:
** _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
// TRANSLATION MISSING
** _nickcmp_callback_: set nick comparison callback function (this callback is
   called when searching nick in nicklist) _(WeeChat ≥ 0.3.9)_
// TRANSLATION MISSING
** _nickcmp_callback_data_: set nick comparison callback data
   _(WeeChat ≥ 0.3.9)_
// TRANSLATION MISSING
* _pointer_: new pointer value for property

// TRANSLATION MISSING
Prototypes for callbacks:

[source,c]
----
int close_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer);

int input_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (const void *pointer, void *data,
                      struct t_gui_buffer *buffer,
                      const char *nick1, const char *nick2);
----

Esempio in C:

[source,c]
----
int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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 contiene "test with abc" */
----

Script (Python):

[source,python]
----
# prototipo
def buffer_string_replace_local_var(buffer: str, string: str) -> str: ...

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

==== buffer_match_list

// TRANSLATION MISSING
_WeeChat ≥ 0.3.5, updated in 4.0.0._

Verifica se il buffer corrisponde ad una lista di buffer.

Prototipo:

[source,c]
----
int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);
----

Argomenti:

* _buffer_: puntatore al buffer
* _string_: elenco separato da virgole di buffer:
** `+*+` indica tutti i buffer
** il nome preceduto da `+!+` viene escluso
// TRANSLATION MISSING
** wildcard `+*+` is allowed in name

// TRANSLATION MISSING
[NOTE]
Since version 4.0.0, comparison of buffer names is case-sensitive.

Valore restituito:

* 1 se il buffer coincide con la lista, altrimenti 0

Esempio in C:

[source,c]
----
struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "libera.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.libera.*"));         /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
}
----

Script (Python):

[source,python]
----
# prototipo
def buffer_match_list(buffer: str, string: str) -> int: ...

# esempio
buffer = weechat.buffer_search("irc", "libera.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.libera.*"))         # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0
----

// TRANSLATION MISSING
[[buffer_lines]]
=== Buffer lines

// TRANSLATION MISSING
Functions for buffer lines.

==== line_search_by_id

_WeeChat ≥ 4.4.0._

// TRANSLATION MISSING
Search line in buffer by identifier.

Prototipo:

[source,c]
----
struct t_gui_line *weechat_line_search_by_id (struct t_gui_buffer *buffer, int id);
----

Valore restituito:

// TRANSLATION MISSING
* pointer to line found, NULL if not found

Esempio in C:

[source,c]
----
struct t_gui_line *line = weechat_line_search_by_id (buffer, 123);
----

Script (Python):

[source,python]
----
# prototipo
def line_search_by_id(buffer: str, line_id: int) -> str: ...

# esempio
line = weechat.line_search_by_id(buffer, 123)
----

[[windows]]
=== Finestre

Funzioni per richiedere finestre.

==== 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
def current_window() -> str: ...

# esempio
current_window = weechat.current_window()
----

==== window_search_with_buffer

_WeeChat ≥ 0.3.5._

Restituisce il puntatore alla finestra che mostra il buffer.

Prototipo:

[source,c]
----
struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);
----

Argomenti:

* _buffer_: puntatore al buffer

Valore restituito:

* puntatore alla finestra che mostra il buffer (NULL se nessuna finestra sta
  mostrando il buffer)

Esempio in C:

[source,c]
----
weechat_printf (NULL,
                "window displaying core buffer: %p",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));
----

Script (Python):

[source,python]
----
# prototipo
def window_search_with_buffer(buffer: str) -> str: ...

# esempio
weechat.prnt("", "window displaying core buffer: %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))
----

==== window_get_integer

Restituisce 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à:
** _number_: numero della finestra (inizia da 1)
** _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 indica metà grandezza)
** _win_height_pct_: misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 indica 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
** _scrolling_: 1 se lo scorrimento è attivo sulla finestra (ultima riga non
   visualizzata)
** _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
def window_get_integer(window: str, property: str) -> int: ...

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

==== 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]
----
const char *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à

Script (Python):

[source,python]
----
# prototipo
def window_get_string(window: str, property: str) -> str: ...
----

==== 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: %p",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----

Script (Python):

[source,python]
----
# prototipo
def window_get_pointer(window: str, property: str) -> str: ...

# esempio
weechat.prnt("", "buffer displayed in current window: %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----

==== window_set_title

Imposta il titolo per il terminale.

Prototipo:

[source,c]
----
void weechat_window_set_title (const char *title);
----

Argomenti:

// TRANSLATION MISSING
* _title_: nuovo titolo per il terminale; string is evaluated, so variables
  like `${info:version}` can be used
  (see <<_string_eval_expression,string_eval_expression>>)

Esempio in C:

[source,c]
----
weechat_window_set_title ("nuovo titolo qui");
----

Script (Python):

[source,python]
----
# prototipo
def window_set_title(title: str) -> int: ...

# esempio
weechat.window_set_title("nuovo titolo qui")
----

[[nicklist]]
=== Lista nick

Funzioni per il buffer nicklist.

==== nicklist_add_group

Aggiunge un gruppo in una lista nick.

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
  (lista nick radice)
* _name_: nome del gruppo
* _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
* _visible_:
** _1_: gruppi e sottogruppi/nick sono visibili
** _0_: gruppi e sottogruppi/nick sono nascosti

[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
def nicklist_add_group(buffer: str, parent_group: str, name: str, color: str, visible: int) -> str: ...

# esempio
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)
----

==== nicklist_search_group

// TRANSLATION MISSING
_Updated in 4.3.0._

// TRANSLATION MISSING
Search a group in a nicklist by name or unique identifier (`id`).

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
// TRANSLATION MISSING
* _name_: group name to search; with WeeChat ≥ 4.3.0, a unique identifier can
  be given with the format: `==id:xxx` (where `xxx` is the identifier)

Valore restituito:

* puntatore al gruppo trovato, NULL se non trovato

Esempio in C:

[source,c]
----
struct t_gui_nick_group *ptr_group1 = weechat_nicklist_search_group (my_buffer,
                                                                     NULL, "test_group");
struct t_gui_nick_group *ptr_group2 = weechat_nicklist_search_group (my_buffer,
                                                                     NULL, "==id:1714382231198764");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_search_group(buffer: str, from_group: str, name: str) -> str: ...

# esempio
group1 = weechat.nicklist_search_group(my_buffer, "", "test_group")
group2 = weechat.nicklist_search_group(my_buffer, "", "==id:1714382231198764")
----

==== nicklist_add_nick

Aggiunge un nick in un gruppo.

Prototipo:

[source,c]
----
struct t_gui_nick *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
def nicklist_add_nick(buffer: str, group: str, name: str, color: str, prefix: str, prefix_color: str, visible: int) -> str: ...

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

==== nicklist_search_nick

// TRANSLATION MISSING
_Updated in 4.3.0._

// TRANSLATION MISSING
Search a nick in a nicklist by name or unique identifier (`id`).

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
// TRANSLATION MISSING
* _name_: nick name to search; with WeeChat ≥ 4.3.0, a unique identifier can
  be given with the format: `==id:xxx` (where `xxx` is the identifier)

Valore restituito:

* puntatore al nuovo nick, NULL se non trovato

Esempio in C:

[source,c]
----
struct t_gui_nick *ptr_nick1 = weechat_nicklist_search_nick (my_buffer,
                                                             NULL, "test_nick");
struct t_gui_nick *ptr_nick2 = weechat_nicklist_search_nick (my_buffer,
                                                             NULL, "==id:1714382252187496");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_search_nick(buffer: str, from_group: str, name: str) -> str: ...

# esempio
nick1 = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
nick2 = weechat.nicklist_search_nick(my_buffer, "", "==id:1714382252187496")
----

==== 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
def nicklist_remove_group(buffer: str, group: str) -> int: ...

# esempio
weechat.nicklist_remove_group(my_buffer, my_group)
----

==== 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
def nicklist_remove_nick(buffer: str, nick: str) -> int: ...

# esempio
weechat.nicklist_remove_nick(my_buffer, my_nick)
----

==== 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
def nicklist_remove_all(buffer: str) -> int: ...

# esempio
weechat.nicklist_remove_all(my_buffer)
----

==== nicklist_get_next_item

_WeeChat ≥ 0.3.7._

Ottiene il prossimo gruppo oppure il nick dalla lista nick (usato principalmente
per mostrare la lista nick).

Prototipo:

[source,c]
----
void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);
----

Argomenti:

* _buffer_: puntatore al buffer
* _group_: puntatore sul puntatore al gruppo
* _nick_: puntatore sul puntatore al nick

Esempio in C:

[source,c]
----
struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* nick */
        /* ... */
    }
    else
    {
        /* gruppo */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== nicklist_group_get_integer

_WeeChat ≥ 0.3.4._

Restituisce un valore intero della proprietà di un gruppo.

Prototipo:

[source,c]
----
int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _group_: puntatore al gruppo
* _property_: nome della proprietà:
** _visible_: 1 se il gruppo è visibile, altrimenti 0
** _level_: livello del gruppo (root è 0)

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,c]
----
int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_group_get_integer(buffer: str, group: str, property: str) -> int: ...

# esempio
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")
----

==== nicklist_group_get_string

_WeeChat ≥ 0.3.4._

Restituisce il valore stringa della proprietà di un gruppo.

Prototipo:

[source,c]
----
const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _group_: puntatore al gruppo
* _property_: nome della proprietà:
// TRANSLATION MISSING
** _id_: unique identifier _(WeeChat ≥ 4.3.0)_
** _name_: nome del gruppo
** _color_: colore del gruppo nella lista nick

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,c]
----
const char *color = weechat_nicklist_group_get_string (buffer, group, "color");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_group_get_string(buffer: str, group: str, property: str) -> str: ...

# esempio
color = weechat.nicklist_group_get_string(buffer, group, "color")
----

==== nicklist_group_get_pointer

_WeeChat ≥ 0.3.4._

Restituisce il valore puntatore della proprietà di un gruppo.

Prototipo:

[source,c]
----
void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _group_: puntatore al gruppo
* _property_: nome della proprietà:
** _parent_: puntatore al gruppo genitore

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,c]
----
struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_group_get_pointer(buffer: str, group: str, property: str) -> str: ...

# esempio
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")
----

==== nicklist_group_set

// TRANSLATION MISSING
_WeeChat ≥ 0.3.4, updated in 4.3.0._

Imposta il valore stringa della proprietà di un gruppo.

Prototipo:

[source,c]
----
void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);
----

Argomenti:

* _buffer_: puntatore al buffer
* _group_: puntatore al gruppo
// TRANSLATION MISSING
* _property_: nome della proprietà (see table below)
// TRANSLATION MISSING
* _value_: new value for property

// TRANSLATION MISSING
Properties:

[width="100%",cols="^2,^1,4,8",options="header"]
|===
// TRANSLATION MISSING
| Nome | Min WeeChat | Valore | Descrizione

// TRANSLATION MISSING
| id | 4.3.0 | long long integer ≥ 0
| New id for the group (it must be unique in the buffer). +
  Note: it is not recommended to change this identifier.

| color | | nome per l'opzione del colore per WeeChat
| Consultare l'argomento "color" della funzione
  <<_nicklist_add_group,nicklist_add_group>>.

| visible | | "0", "1"
| "0" = gruppo nascosto, "1" = gruppo visibile.
|===

Esempio in C:

[source,c]
----
/* cambia colore del gruppo a "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* cambia il colore del gruppo a giallo */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* nasconde gruppo nella lista nick */
weechat_nicklist_group_set (buffer, group, "visible", "0");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_group_set(buffer: str, group: str, property: str, value: str) -> int: ...

# esempi

# cambia colore del gruppo a "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# cambia colore del gruppo a giallo
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# nasconde gruppo nella lista nick
weechat.nicklist_group_set(buffer, group, "visible", "0")
----

==== nicklist_nick_get_integer

_WeeChat ≥ 0.3.4._

Restituisce il valore intero della proprietà di un nick.

Prototipo:

[source,c]
----
int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _nick_: puntatore al nick
* _property_: nome della proprietà:
** _visible_: 1 se il nick è visibile, altrimenti 0

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,c]
----
int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_nick_get_integer(buffer: str, nick: str, property: str) -> int: ...

# esempio
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")
----

==== nicklist_nick_get_string

_WeeChat ≥ 0.3.4._

Restituisce il valore stringa della proprietà di un nick.

Prototipo:

[source,c]
----
const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _nick_: puntatore al nick
* _property_: nome della proprietà:
// TRANSLATION MISSING
** _id_: unique identifier _(WeeChat ≥ 4.3.0)_
** _name_: nome del nick
** _color_: colore del nick nella lista nick
** _prefix_: prefisso del nick
** _prefix_color_: colore del prefisso nella lista nick

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,c]
----
const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_nick_get_string(buffer: str, nick: str, property: str) -> str: ...

# esempio
color = weechat.nicklist_nick_get_string(buffer, nick, "color")
----

==== nicklist_nick_get_pointer

_WeeChat ≥ 0.3.4._

Restituisce il valore puntatore della proprietà di un nick.

Prototipo:

[source,c]
----
void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);
----

Argomenti:

* _buffer_: puntatore al buffer
* _nick_: puntatore al nick
* _property_: nome proprietà:
** _group_: puntatore al gruppo che contiene questo nick

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,c]
----
struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_nick_get_pointer(buffer: str, nick: str, property: str) -> str: ...

# esempio
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")
----

==== nicklist_nick_set

// TRANSLATION MISSING
_WeeChat ≥ 0.3.4, updated in 4.3.0._

Imposta il valore stringa della proprietà di un nick.

Prototipo:

[source,c]
----
void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);
----

Argomenti:

* _buffer_: puntatore al buffer
* _nick_: puntatore al nick
// TRANSLATION MISSING
* _property_: nome della proprietà (see table below)
// TRANSLATION MISSING
* _value_: new value for property

// TRANSLATION MISSING
Properties:

[width="100%",cols="^2,^1,4,8",options="header"]
|===
// TRANSLATION MISSING
| Nome | Min WeeChat | Valore | Descrizione

// TRANSLATION MISSING
| id | 4.3.0 | long long integer ≥ 0
| New id for the nick (it must be unique in the buffer). +
  Note: it is not recommended to change this identifier.

| color | | nome per l'opzione del colore di WeeChat
| Consultare l'argomento "color" della funzione
  <<_nicklist_add_nick,nicklist_add_nick>>.

| prefix | | qualsiasi stringa
| Prefisso del nick.

| prefix_color | | nome per l'opzione del colore di WeeChat
| Consultare l'argomento "prefix_color" della funzione
  <<_nicklist_add_nick,nicklist_add_nick>>.

| visible | | "0", "1"
| "0" = nick nascosto, "1" = nick visibile.
|===

Esempi in C:

[source,c]
----
/* cambia colore del nick in azzurro */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* cambia prefisso in "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* cambia colore del prefisso in giallo */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* nascondi nick nella lista nick */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");
----

Script (Python):

[source,python]
----
# prototipo
def nicklist_nick_set(buffer: str, nick: str, property: str, value: str) -> int: ...

# esempi

# cambia colore del nick in azzurro
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# cambia prefisso in "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# cambia colore del prefisso in giallo
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# nascondi nick nella lista nick
weechat.nicklist_nick_set(buffer, nick, "visible", "0")
----

[[bars]]
=== Barre

Funzioni per le barre.

==== 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
def bar_item_search(name: str) -> str: ...

# esempio
bar_item = weechat.bar_item_search("myitem")
----

==== bar_item_new

// TRANSLATION MISSING
_Updated in 0.4.2, 1.5._

Crea un nuovo elemento barra.

Prototipo:

[source,c]
----
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             const void *build_callback_pointer,
                                             void *build_callback_data);
----

Argomenti:

* _name_: nome dell'elemento barra
* _build_callback_: funzione chiamata quando l'elemento barra viene
  compilato, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_gui_bar_item *item_: puntatore all'elemento barra
// TRANSLATION MISSING
** _struct t_gui_window *window_: puntatore alla finestra (NULL when called for
   a root bar)
// TRANSLATION MISSING
** _struct t_gui_buffer *buffer_: buffer displayed in window (if window is NULL,
   then it is current buffer) or buffer given in bar item with syntax:
   "@buffer:item" _(WeeChat ≥ 0.4.2)_
// TRANSLATION MISSING
** _struct t_hashtable *extra_info_: always NULL (argument is reserved for a
   future version) _(WeeChat ≥ 0.4.2)_
** valore restituito: contenuto dell'elemento barra
* _build_callback_pointer_: puntatore fornito alla callback quando
  chiamata da WeeChat
// TRANSLATION MISSING
* _build_callback_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the bar item is removed

Valore restituito:

* puntatore al nuovo elemento barra, NULL se non trovato

Esempio in C:

[source,c]
----
char *
my_build_callback (const void *pointer, void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL, NULL);
----

Script (Python):

// TRANSLATION MISSING
[IMPORTANT]
For compatibility with versions ≤ 0.4.1, the default callback has only 3
arguments: _data_, _item_ and _window_ (no _buffer_ and _extra_info_). +
To use a callback with all arguments, you must add "(extra)" before the name,
see example below (supported only in WeeChat ≥ 0.4.2).

// TRANSLATION MISSING
[source,python]
----
# prototipo
def bar_item_new(name: str, build_callback: str, build_callback_data: str) -> str: ...

# esempio (callback without "buffer" and "extra_info")
def my_build_callback(data: str, item: str, window: str) -> str:
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# example (callback with all arguments, for WeeChat ≥ 0.4.2)
def my_build_callback2(data: str, item: str, window: str, buffer: str, extra_info: Dict[str, str]) -> str:
    return "my content"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat ≥ 0.4.2
----

==== 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
def bar_item_update(name: str) -> int: ...

# esempio
weechat.bar_item_update("myitem")
----

==== 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
def bar_item_remove(item: str) -> int: ...

# esempio
weechat.bar_item_remove(myitem)
----

==== 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
def bar_search(name: str) -> str: ...

# esempio
bar = weechat.bar_search("mybar")
----

==== bar_new

// TRANSLATION MISSING
_Updated in 2.9, 4.0.0._

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 *color_bg_inactive,
                                   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
// TRANSLATION MISSING
** evaluated expression: see the
   link:weechat_user.it.html#bar_conditions[WeeChat user's guide / Bar conditions ^↗^^]
* _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
// TRANSLATION MISSING
* _color_bg_inactive_: background color for window bar which is not displayed
  in active window
* _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

// TRANSLATION MISSING
[NOTE]
Since version 4.0.0, if the bar already exists, WeeChat sets the values received
as default values for bar options and returns the bar pointer instead of NULL.

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", "darkgray", "off",
    "time,buffer_number+buffer_name");
----

Script (Python):

[source,python]
----
# prototipo
def bar_new(name: str, hidden: str, priority: str, type: str, condition: str, position: str,
            filling_top_bottom: str, filling_left_right: str, size: str, size_max: str,
            color_fg: str, color_delim: str, color_bg: str, color_bg_inactive: str,
            separator: str, items: str) -> str: ...

# esempio
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "darkgray", "off", "time,buffer_number+buffer_name")
----

// TRANSLATION MISSING
[NOTE]
With WeeChat ≥ 2.9, in Ruby, the 4 colors (color_fg, color_delim, color_bg,
color_bg_inactive) must be given in an array of 4 strings (due to a Ruby
limitation of 15 arguments by function), see the
link:++weechat_scripting.it.html#_ruby++[WeeChat scripting guide ^↗^^]
for more info.

==== 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 <<_bar_new,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
def bar_set(bar: str, property: str, value: str) -> int: ...

# esempio
weechat.bar_set(my_bar, "position", "bottom")
----

==== 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
def bar_update(name: str) -> int: ...

# esempio
weechat.bar_update("mybar")
----

==== 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
def bar_remove(bar: str) -> int: ...

# esempio
weechat.bar_remove(my_bar)
----

[[commands]]
=== Comandi

Funzioni per eseguire comandi di WeeChat.

==== command

// TRANSLATION MISSING
_Updated in 1.1, 4.0.0._

// TRANSLATION MISSING
Execute a command or send text to buffer.

Prototipo:

[source,c]
----
int 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 corrente)
* _command_: comando da eseguire (se preceduto da "/"), oppure il testo
  viene inviato sul buffer

// TRANSLATION MISSING
[NOTE]
On buffer with `input_multiline` set to `0` (default), only the first command
is executed (before the first newline char: `\n`).

Valori restituiti _(WeeChat ≥ 1.1)_:

* _WEECHAT_RC_OK_ se l'operazione ha successo
* _WEECHAT_RC_ERROR_ se c'è un errore

Esempio in C:

[source,c]
----
int rc;
rc = weechat_command (weechat_buffer_search ("irc", "libera.#weechat"),
                      "/whois FlashCode");
----

Script (Python):

[source,python]
----
# prototipo
def command(buffer: str, command: str) -> int: ...

# esempio
rc = weechat.command(weechat.buffer_search("irc", "libera.#weechat"), "/whois FlashCode")
----

==== command_options

// TRANSLATION MISSING
_WeeChat ≥ 2.5, updated in 4.0.0, 4.5.0._

// TRANSLATION MISSING
Execute a command or send text to buffer with options.

Prototipo:

[source,c]
----
int weechat_command_options (struct t_gui_buffer *buffer, const char *command,
                             struct t_hashtable *options);
----

Argomenti:

* _buffer_: puntatore al buffer (il comando viene eseguito su questo buffer,
  utilizzare NULL per il buffer corrente)
// TRANSLATION MISSING
* _command_: comando da eseguire (if beginning with a `/` or a command char),
   oppure il testo viene inviato sul buffer
// TRANSLATION MISSING
* _options_: a hashtable with some options (keys and values must be string)
  (can be NULL):
// TRANSLATION MISSING
** _commands_: a comma-separated list of commands allowed to be executed during
   this call (see function <<_string_match_list,string_match_list>> for the
   format); the special value `-` (hyphen-minus) disables the execution of commands
   and the string in _command_ is sent as-is to the buffer (_WeeChat ≥ 4.5.0_)
** _delay_: delay to execute command, in milliseconds
// TRANSLATION MISSING
** _split_newline_: `1` to split commands on newline char (`\n`) (_WeeChat ≥ 4.0.0_)

Valori restituiti:

* _WEECHAT_RC_OK_ se l'operazione ha successo
* _WEECHAT_RC_ERROR_ se c'è un errore

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
/* allow any command except /exec, run command in 2 seconds */
int rc;
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
weechat_hashtable_set (options, "commands", "*,!exec");
weechat_hashtable_set (options, "delay", "2000");
rc = weechat_command_options (NULL, "/some_command arguments", options);
----

Script (Python):

// TRANSLATION MISSING
[source,python]
----
# prototipo
def command_options(buffer: str, command: str, options: Dict[str, str]) -> int: ...

# example: allow any command except /exec
rc = weechat.command_options("", "/some_command arguments", {"commands": "*,!exec", "delay": "2000"})
----

// TRANSLATION MISSING
[[completion]]
=== Completion

Functions to complete a command line.

// TRANSLATION MISSING
==== completion_new

_WeeChat ≥ 2.9._

Create a new completion.

Prototipo:

[source,c]
----
struct t_gui_completion *weechat_completion_new (struct t_gui_buffer *buffer);
----

Argomenti:

* _buffer_: buffer pointer

Valori restituiti:

* pointer to new completion

Esempio in C:

[source,c]
----
struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());
----

Script (Python):

[source,python]
----
# prototipo
def completion_new(buffer: str) -> str: ...

# esempio
completion = weechat.completion_new(weechat.buffer_search_main())
----

// TRANSLATION MISSING
==== completion_search

_WeeChat ≥ 2.9._

Search possible words at a given position of a string, in the completion
context.

Prototipo:

[source,c]
----
int weechat_completion_search (struct t_gui_completion *completion, const char *data,
                               int position, int direction);
----

Argomenti:

* _completion_: completion pointer
* _data_: the string to complete
* _position_: index of the char in string to complete (starts to 0)
* _direction_: 1 for next completion, -1 for previous completion

Valore restituito:

// TRANSLATION MISSING
* 1 if OK, 0 if error

Esempio in C:

[source,c]
----
struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());
if (weechat_completion_search (completion, "/help filt", 10, 1))
{
    /* ... */
}
----

Script (Python):

[source,python]
----
# prototipo
def completion_search(completion: str, data: str, position: int, direction: int) -> int: ...

# esempio
completion = weechat.completion_new(weechat.buffer_search_main())
if weechat.completion_search(completion, "/help filt", 10, 1):
    # ...
----

==== completion_get_string

_Novità nella versioe 2.9._

Ottiene il completamento di una proprietà come stringa.

Prototipo:

[source,c]
----
const char *weechat_completion_get_string (struct t_gui_completion *completion,
                                           const char *property);
----

Argomenti:

* _completion_: puntatore al completamento
* _property_: nome della proprietà:
** _base_command_: comando usato per il completamento
** _base_word_: parola che viene completata
** _args_: argomenti del comando (inclusa la parola base)

Esempio in C:

[source,c]
----
int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* ottiene l'argomento del comando */
    const char *args = weechat_completion_get_string (completion, "args");

    /* completamento che dipende dagli argomenti */
    /* ... */

    return WEECHAT_RC_OK;
}
----

Script (Python):

[source,python]
----
# prototipo
def completion_get_string(completion: str, property: str) -> str: ...

# esempio
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    # ottiene l'argomento del comando
    args = weechat.completion_get_string(completion, "args")
    # completamento che dipende dagli argomenti
    # ...
    return weechat.WEECHAT_RC_OK
----

==== completion_set

_Novità nella versioe 4.6.0._

// TRANSLATION MISSING
Set a completion property.

Prototipo:

[source,c]
----
void weechat_completion_get_string (struct t_gui_completion *completion,
                                    const char *property,
                                    const char *value);
----

Argomenti:

* _completion_: puntatore al completamento
// TRANSLATION MISSING
* _property_: nome della proprietà (see table below)
// TRANSLATION MISSING
* _value_: new value for property

// TRANSLATION MISSING
Properties:

[width="100%",cols="^2,^1,4,8",options="header"]
|===
// TRANSLATION MISSING
| Name | Min WeeChat | Value | Description

// TRANSLATION MISSING
| add_space | 4.6.0 | "0" or "1"
| "0": do not add space after completion +
  "1": add space after completion (default).
|===

Esempio in C:

[source,c]
----
int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* do not add space after completion */
    weechat_completion_set (completion, "add_space", "0");

    /* ... */

    return WEECHAT_RC_OK;
}
----

Script (Python):

[source,python]
----
# prototipo
def completion_set(completion: str, property: str, value: str) -> int: ...

# esempio
def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
    # do not add space after completion
    weechat.completion_set(completion, "add_space", "0")
    # ...
    return weechat.WEECHAT_RC_OK
----

==== completion_list_add

_Novità nella versioe 2.9._

Aggiunge una parola per il completamento.

Prototipo:

[source,c]
----
void weechat_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 <<_hook_completion,hook_completion>>.

Script (Python):

[source,python]
----
# prototipo
def completion_list_add(completion: str, word: str, nick_completion: int, where: str) -> int: ...

# esempio: consultare function hook_completion
----

// TRANSLATION MISSING
==== completion_free

_WeeChat ≥ 2.9._

Free a completion.

Prototipo:

[source,c]
----
void weechat_completion_free (struct t_gui_completion *completion);
----

Argomenti:

* _completion_: completion pointer

Esempio in C:

[source,c]
----
weechat_completion_free (completion);
----

Script (Python):

[source,python]
----
# prototipo
def completion_free(completion: str) -> int: ...

# esempio
weechat.completion_free(completion)
----

[[network]]
=== Network

Funzioni di rete.

==== network_pass_proxy

Stabilisce una connessione/autenticazione con un proxy.

[IMPORTANT]
// TRANSLATION MISSING
This function is blocking on call to connect(), so it must be called in a forked
process only, to not block WeeChat.

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.libera.chat", 6667))
{
    /* OK */
}
else
{
    /* errore */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== network_connect_to

// TRANSLATION MISSING
_Updated in 0.4.3._

Stabilisce una connessione con un host remoto.

[IMPORTANT]
// TRANSLATION MISSING
This function is blocking on call to connect(), so it must be called in a forked
process only, to not block WeeChat.

Prototipo:

[source,c]
----
int weechat_network_connect_to (const char *proxy,
                                struct sockaddr *address,
                                socklen_t address_length);
----

Argomenti:

* _proxy_: nome del proxy da utilizzare
// TRANSLATION MISSING
* _address_: address to connect to (with port)
// TRANSLATION MISSING
* _address_length_: length of argument _address_

Valore restituito:

// TRANSLATION MISSING
* socket number (≥ 0) if connection is OK, -1 if an error occurred

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
struct sockaddr *addr;
socklen_t length;
int sock;

/* allocate/set address and port in 'addr', set 'length' */
/* ... */

sock = weechat_network_connect_to (NULL, addr, length);
if (sock >= 0)
{
    /* OK */
}
else
{
    /* errore */
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[infos]]
=== Info

Funzioni per ottenere info.

==== info_get

// TRANSLATION MISSING
_Updated in 2.5._

Restituisce la info, come stringa, da WeeChat o da un plugin.

Prototipo:

[source,c]
----
char *weechat_info_get (const char *info_name, const char *arguments);
----

Argomenti:

// TRANSLATION MISSING
* _info_name_: nome delle informazioni da leggere (see table below)
* _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
  (deve essere liberata richiamando "free" dopo l'utilizzo)

// TRANSLATION MISSING
[NOTE]
With WeeChat ≥ 2.5, the value returned is an allocated string
(with WeeChat ≤ 2.4, it was a pointer to a static string).

// TRANSLATION MISSING
Infos:

include::{autogendir}/autogen_api_infos.it.adoc[tag=infos]

Esempio in C:

[source,c]
----
char *version = weechat_info_get ("version", NULL);
char *date = weechat_info_get ("date", NULL);
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                version, date);
if (version)
    free (version);
if (date)
    free (date);

char *weechat_config_dir = weechat_info_get ("weechat_config_dir", NULL);
weechat_printf (NULL, "WeeChat config directory is: %s", weechat_config_dir);
if (weechat_config_dir)
    free (weechat_config_dir);
----

Script (Python):

[source,python]
----
# prototipo
def info_get(info_name: str, arguments: str) -> str: ...

# esempio
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat config directory is: %s" % weechat.info_get("weechat_config_dir"))
----

==== info_get_hashtable

_WeeChat ≥ 0.3.4._

Restituisce una info, come tabella hash, da WeeChat o da un plugin.

Prototipo:

[source,c]
----
struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);
----

Argomenti:

// TRANSLATION MISSING
* _info_name_: nome della info da leggere (see table below)
* _hashtable_: tabella hash con argomenti (dipende dalla info richiesta)
* (opzionale, NULL se l'argomento non viene richiesto)

Valore restituito:

// TRANSLATION MISSING
* tabella hash con la info richiesta, NULL in caso di errore (must be
  freed by calling <<_hashtable_free,hashtable_free>> after use)

// TRANSLATION MISSING
Infos:

include::{autogendir}/autogen_api_infos_hashtable.it.adoc[tag=infos_hashtable]

Esempio in C:

[source,c]
----
struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (
        hashtable_in,
        "message",
        "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :Hello world!");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "tags"                : "time=2015-06-27T16:40:35.000Z;tag2=value\\sspace"
     *   "tag_time"            : "2015-06-27T16:40:35.000Z"
     *   "tag_tag2"            : "value space"
     *   "message_without_tags": ":nick!user@host PRIVMSG #weechat :Hello world!"
     *   "nick"                : "nick"
     *   "user"                : "user"
     *   "host"                : "nick!user@host"
     *   "command"             : "PRIVMSG"
     *   "channel"             : "#weechat"
     *   "arguments"           : "#weechat :Hello world!"
     *   "text"                : "Hello world!"
     *   "param1"              : "#weechat"
     *   "param2"              : "Hello world!"
     *   "num_params"          : "2"
     *   "pos_command"         : "65"
     *   "pos_arguments"       : "73"
     *   "pos_channel"         : "73"
     *   "pos_text"            : "83"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}
----

// TRANSLATION MISSING
[NOTE]
See the link:weechat_scripting.it.html#irc_message_parse[Guida allo Scripting di WeeChat / Verifica messaggio ^↗^^]
for more info about "irc_message_parse" output.

Script (Python):

[source,python]
----
# prototipo
def info_get_hashtable(info_name: str, dict_in: Dict[str, str]) -> Dict[str, str]: ...

# esempio
dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message here"}
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))
----

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

==== 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
def infolist_new() -> str: ...

# esempio
infolist = weechat.infolist_new()
----

==== 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
def infolist_new_item(infolist: str) -> str: ...

# esempio
item = weechat.infolist_new_item(infolist)
----

==== 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
def infolist_new_var_integer(item: str, name: str, value: int) -> str: ...

# esempio
var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----

==== 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
def infolist_new_var_string(item: str, name: str, value: str) -> str: ...

# esempio
var = weechat.infolist_new_var_string(item, "my_string", "value")
----

==== 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
def infolist_new_var_pointer(item: str, name: str, pointer: str) -> str: ...

# esempio
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----

==== 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_var_buffer (item,
                                                              "my_buffer",
                                                              &buffer,
                                                              sizeof (buffer));
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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_var_time (item,
                                                            "my_time",
                                                            time (NULL));
----

Script (Python):

[source,python]
----
# prototipo
def infolist_new_var_time(item: str, name: str, time: int) -> str: ...

# esempio
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
----

==== infolist_get

Restituisce una lista info da WeeChat o da un plugin.

[IMPORTANT]
Il contenuto della lista info è un duplicato dei dati attuali. Se si sta
richiedendo una lista info con molti dati (come "buffer_lines"), WeeChat
allocherà memoria per duplicare tutti i dati, e potrebbe essere necessario un
po' di tempo. +
Invece di usare liste info più grandi, è preferibilie usare hdata (ma le liste
info potrebbero avere più info di hdata, che sono dati raw), consultare <<hdata,hdata>>.

Prototipo:

[source,c]
----
struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);
----

Argomenti:

// TRANSLATION MISSING
* _infolist_name_: nome della lista info da leggere (see table below)
* _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

// TRANSLATION MISSING
Infolists:

include::{autogendir}/autogen_api_infolists.it.adoc[tag=infolists]

Esempio in C:

[source,c]
----
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def infolist_get(infolist_name: str, pointer: str, arguments: str) -> str: ...

# esempio
infolist = weechat.infolist_get("irc_server", "", "")
----

==== 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
def infolist_next(infolist: str) -> int: ...

# esempio
rc = weechat.infolist_next(infolist)
if rc:
    # legge variabili nell'elemento...
else:
    # nessun altro elemento disponibile
----

==== 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
def infolist_prev(infolist: str) -> int: ...

# esempio
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----

==== 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
def infolist_reset_item_cursor(infolist: str) -> int: ...

# esempio
weechat.infolist_reset_item_cursor(infolist)
----

==== infolist_search_var

_WeeChat ≥ 0.4.3._

// TRANSLATION MISSING
Search a variable in the current infolist item.

Prototipo:

[source,c]
----
struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                    const char *name);
----

Argomenti:

* _infolist_: puntatore alla lista info
* _name_: nome della variabile

Valore restituito:

// TRANSLATION MISSING
* pointer to variable found, NULL if the variable was not found

Esempio in C:

// TRANSLATION MISSING
[source,c]
----
if (weechat_infolist_search_var (infolist, "name"))
{
    /* variable "name" exists */
    /* ... */
}
----

Script (Python):

// TRANSLATION MISSING
[source,python]
----
# prototipo
def infolist_search_var(infolist: str, name: str) -> str: ...

# esempio
if weechat.infolist_search_var(infolist, "name"):
    # variable "name" exists
    # ...
----

==== 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
def infolist_fields(infolist: str) -> str: ...

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

==== 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, "my_integer"));
----

Script (Python):

[source,python]
----
# prototipo
def infolist_integer(infolist: str, var: str) -> int: ...

# esempio
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
----

==== 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, "my_string"));
----

Script (Python):

[source,python]
----
# prototipo
def infolist_string(infolist: str, var: str) -> str: ...

# esempio
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
----

==== 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 = %p", weechat_infolist_pointer (infolist, "my_pointer"));
----

Script (Python):

[source,python]
----
# prototipo
def infolist_pointer(infolist: str, var: str) -> str: ...

# esempio
weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer"))
----

==== 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 = %p, size = %d", pointer, size);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== 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
def infolist_time(infolist: str, var: str) -> int: ...

# esempio
weechat.prnt("", "time = %d" % weechat.infolist_time(infolist, "my_time"))
----

==== 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
def infolist_free(infolist: str) -> int: ...

# esempio
weechat.infolist_free(infolist)
----

[[hdata]]
=== Hdata

Funzioni per hdata (accesso raw a WeeChat o ai dati dei plugin).

// TRANSLATION MISSING
[IMPORTANT]
Hdata fornisce un accesso in sola lettura ai dati. È *SEVERAMENTE VIETATO*
scrivere qualcosa in memoria puntato dalle variabili in hdata. +
The only way to update data is to call function <<_hdata_update,hdata_update>>.

==== hdata_new

// TRANSLATION MISSING
_WeeChat ≥ 0.3.6, updated in 0.3.9, 0.4.0._

Crea un nuovo hdata.

[NOTE]
.hdata vs infolist
====
Hdata è un metodo veloce per leggere i dati di WeeChat o dei plugin. È simile
alle liste info, ma ci sono alcune differenze:

* è più veloce ed usa meno memoria: lettura diretta dei dati senza duplicazione
* può contenere informazioni differenti rispetto alle liste info: esso contiene
  solo dati raw in strutture (le liste info possono aggiungere alcuni dati extra
  per convenienza)
====

Prototipo:

[source,c]
----
struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);
----

Argomenti:

* _hdata_name_: nome di un hdata
* _var_prev_: nome della variabile nella struttura che è puntatore all'elemento
  precedente nella lista (può essere NULL se non è disponibile tale variabile)
* _var_next_: nome della variabile nella struttura che è puntatore all'elemento
  successivo nella lista (può essere NULL se non è disponibile tale variabile)
// TRANSLATION MISSING
* _create_allowed_: 1 if create of structure is allowed, otherwise 0
  _(WeeChat ≥ 0.4.0)_
// TRANSLATION MISSING
* _delete_allowed_: 1 if delete of structure is allowed, otherwise 0
  _(WeeChat ≥ 0.3.9)_
// TRANSLATION MISSING
* _callback_update_: callback to update data in hdata, can be NULL if no update
  is allowed _(WeeChat ≥ 0.3.9)_, arguments and return value:
** _void *data_: pointer
** _struct t_hdata *hdata_: pointer to hdata
** _struct t_hashtable *hashtable_: hashtable with variables to update
   (see <<_hdata_update,hdata_update>>)
** return value: number of variables updated
// TRANSLATION MISSING
* _callback_update_data_: pointer given to update callback when it is called by
  WeeChat _(WeeChat ≥ 0.3.9)_

Valore restituito:

* puntatore al nuovo hdata

Esempio in C:
source,c]
----
struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_new_var

// TRANSLATION MISSING
_WeeChat ≥ 0.3.6, updated in 0.3.7, 0.3.9, 0.4.3, 3.4, 4.3.0_

Crea una nuova variabile in hdata.

Prototipo:

[source,c]
----
void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);
----

Argomenti:

* _hdata_: puntatore ad hdata
* _name_: nome della variabile
* _offset_: offset della variabile nella struttura
* _type_: tipo variabile, una di:
** _WEECHAT_HDATA_CHAR_
** _WEECHAT_HDATA_INTEGER_
** _WEECHAT_HDATA_LONG_
** _WEECHAT_HDATA_LONGLONG_ (_WeeChat ≥ 4.3.0_)
** _WEECHAT_HDATA_STRING_
** _WEECHAT_HDATA_SHARED_STRING_ (_WeeChat ≥ 0.4.3_)
** _WEECHAT_HDATA_POINTER_
** _WEECHAT_HDATA_TIME_
** _WEECHAT_HDATA_HASHTABLE_ (_WeeChat ≥ 0.3.7_)
** _WEECHAT_HDATA_OTHER_
// TRANSLATION MISSING
* _update_allowed_: 1 if update of variable is allowed, otherwise 0
  _(WeeChat ≥ 0.3.9)_
// TRANSLATION MISSING
* _array_size_: not NULL only if a variable is an array, and it can be:
  _(WeeChat ≥ 0.3.9)_
** name of variable in hdata: this variable will be used as size of array
   (dynamic size for array)
** integer (as string): fixed size for array
** _*_: automatic size: the size of array is computed by looking at values, when
   the first NULL is found (only for type string, pointer or hashtable)
* _hdata_name_: nome di un hdata (se è un puntatore ad una struttura con dati)

// TRANSLATION MISSING
With WeeChat ≥ 3.4, the _array_size_ parameter can be prefixed with `*,` for
pointer to dynamically allocated array (without this prefix, the array is
considered static).

// TRANSLATION MISSING
Examples of variables and the corresponding array size (_WeeChat ≥ 3.4_):

// TRANSLATION MISSING
[width="100%",cols="3,3m,2,7",options="header"]
|===
| Variable declaration in C | Hdata type | Array size | Description

| `+int *numbers;+` | WEECHAT_HDATA_INTEGER | `+*,2+`
| Allocated array of 2 integers.

| `+int *numbers;+` | WEECHAT_HDATA_INTEGER | `+*,array_size+`
| Allocated array of integers, the size is stored in another variable called
  "array_size".

| `+int numbers[3];+` | WEECHAT_HDATA_INTEGER | `+3+`
| Static array of 3 integers.

| `+char **words;+` | WEECHAT_HDATA_STRING | `+*,*+`
| Allocated array of strings, dynamic size (NULL pointer must be present after
  last word).

| `+char **words;+` | WEECHAT_HDATA_STRING | `+*,count_words+`
| Allocated array of strings, the size is stored in another variable called
  "count_words".
|===

Esempio in C:

[source,c]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int numbers[3];
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "numbers", offsetof (struct t_myplugin_list, numbers), WEECHAT_HDATA_INTEGER, 0, "3", NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "*,tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*,*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
----

La macro "WEECHAT_HDATA_VAR" può essere usata per accorciare il codice:

[source,c]
----
WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, numbers, INTEGER, 0, "3", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "*,tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*,*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_new_list

// TRANSLATION MISSING
_WeeChat ≥ 0.3.6, updated in 1.0._

Crea una nuovo puntatore alla lista in hdata.

Prototipo:

[source,c]
----
void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome delal variabile
* _pointer_: puntatore alla lista
// TRANSLATION MISSING
* _flags_: combination of following values: _(WeeChat ≥ 1.0)_
** _WEECHAT_HDATA_LIST_CHECK_POINTERS_: list used to check pointers

Esempio in C:

[source,c]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);
----

La macro "WEECHAT_HDATA_LIST" può essere usata per accorciare il codice:

[source,c]
----
WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
WEECHAT_HDATA_LIST(last_buffer, 0);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_get

_WeeChat ≥ 0.3.6._

Restituisce hdata per una struttura di WeeChat o di un plugin.

[NOTE]
Hdata non contiene dati, è una tabella hash con la posizione delle variabili
nella struttura. Ciò indica che è necessario questo hdata ed un puntatore ad
un oggetto di WeeChat/plugin per leggere dei dati.

Prototipo:

[source,c]
----
struct t_hdata *weechat_hdata_get (const char *hdata_name);
----

Argomenti:

// TRANSLATION MISSING
* _hdata_name_: nome di un hdata (see list below)

Valore restituito:

* puntatore ad un hdata, NULL in caso di errore

// TRANSLATION MISSING
List of hdata:

include::{autogendir}/autogen_api_hdata.it.adoc[tag=hdata]

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get(hdata_name: str) -> str: ...

# esempio
hdata = weechat.hdata_get("irc_server")
----

==== hdata_get_var_offset

_WeeChat ≥ 0.3.6._

Restituisce l'offset della variabile in hdata.

Prototipo:

[source,c]
----
int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome della variabile

Valore restituito:

* offset della variabile, -1 in caso di errore

Esempio in C:

[source,c]
----
int offset = weechat_hdata_get_var_offset (hdata, "name");
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_var_offset(hdata: str, name: str) -> int: ...

# esempio
offset = weechat.hdata_get_var_offset(hdata, "name")
----

==== hdata_get_var_type

_WeeChat ≥ 0.3.6._

Restituisce il tipo di variabile in hdata (come intero).

Prototipo:

[source,c]
----
int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome della variabile

Valore restituito:

* tipo della variabile, -1 in caso di errore

Esempio in C:

[source,c]
----
int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_LONGLONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_SHARED_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable not found */
        break;
}
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_get_var_type_string

_WeeChat ≥ 0.3.6._

Restituisce il tipo di variabile in hdata (come stringa).

Prototipo:

[source,c]
----
const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome della variabile

Valore restituito:

* tipo della variabile, NULL in caso di errore

Esempio in C:

[source,c]
----
weechat_printf (NULL, "type = %s",
                weechat_hdata_get_var_type_string (hdata, "name"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_var_type_string(hdata: str, name: str) -> str: ...

# esempio
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string(hdata, "name"))
----

==== hdata_get_var_array_size

_WeeChat ≥ 0.3.9._

// TRANSLATION MISSING
Return array size for variable in hdata.

Prototipo:

[source,c]
----
int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntarore all'oggetto di WeeChat/plugin
* _name_: nome della variabile

Valore restituito:

// TRANSLATION MISSING
* array size for variable, -1 if variable is not an array or if an error occurred

Esempio in C:

[source,c]
----
int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_var_array_size(hdata: str, pointer: str, name: str) -> int: ...

# esempio
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")
----

==== hdata_get_var_array_size_string

_WeeChat ≥ 0.3.9._

// TRANSLATION MISSING
Return array size for variable in hdata (as string).

Prototipo:

[source,c]
----
const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer,
                                                     const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntarore all'oggetto di WeeChat/plugin
* _name_: nome della variabile

Valore restituito:

// TRANSLATION MISSING
* array size for variable as string, NULL if variable is not an array or if an
  error occurred

Esempio in C:

[source,c]
----
const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_var_array_size_string(hdata: str, pointer: str, name: str) -> str: ...

# esempio
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")
----

==== hdata_get_var_hdata

_WeeChat ≥ 0.3.6._

Restituisce hdata per la variabile in hdata.

Prototipo:

[source,c]
----
const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome della variabile

Valore restituito:

* hdata per la variabile, NULL in caso di nessun hdata presente o di errore

Esempio in C:

[source,c]
----
weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_var_hdata(hdata: str, name: str) -> str: ...

# esempio
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))
----

==== hdata_get_var

_WeeChat ≥ 0.3.6._

Restituisce il puntatore al contenuto della variabile in hdata.

Prototipo:

[source,c]
----
void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntarore all'oggetto di WeeChat/plugin
* _name_: nome della variabile

Valore restituito:

* puntatore al contenuto della variabile, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_get_var_at_offset

_WeeChat ≥ 0.3.6._

Restituisce il puntatore al contenuto della variabile in hdata, usando un offset.

Prototipo:

[source,c]
----
void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore ad un oggetto di WeeChat/plugin
* _offset_: offset della variabile

Valore restituito:

* puntatore al contenuto della variabile, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

==== hdata_get_list

_WeeChat ≥ 0.3.6._

Restituisce il puntatore alla lista da hdata.

Prototipo:

[source,c]
----
void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _name_: nome della lista

Valore restituito:

* puntatore alla lista, NULL in caso di errore

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_list(hdata: str, name: str) -> str: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")
----

==== hdata_check_pointer

// TRANSLATION MISSING
_WeeChat ≥ 0.3.7, updated in 1.0._

Verifica se un puntatore è valido per un hdata e un puntatore della lista.

Prototipo:

[source,c]
----
int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);
----

Argomenti:

* _hdata_: puntatore hdata
// TRANSLATION MISSING
* _list_: puntatore alla lista; if NULL _(WeeChat ≥ 1.0)_, the pointer is
  checked with the lists in hdata that have flag "check pointers" (see
  <<_hdata_new_list,hdata_new_list>>), and if no such list exists,
  the pointer is considered as valid
* _pointer_: puntatore da verificare

Valore restituito:

* 1 se il puntatore è in lista, 0 in caso contrario

Esempio in C:

[source,c]
----
/* check if a buffer pointer is valid */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* valid pointer */
}
else
{
    /* invalid pointer */
}
----

Script (Python):

[source,python]
----
# prototipo
def hdata_check_pointer(hdata: str, list: str, pointer: str) -> int: ...

# esempio
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # valid pointer
    # ...
else:
    # invalid pointer
    # ...
----

==== hdata_move

_WeeChat ≥ 0.3.6._

Sposta il puntatore ad un altro elemento nella lista.

Prototipo:

[source,c]
----
void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore ad un oggetto di WeeChat/plugin
* _count_: numero di salto(i) da eseguire (intero positivo o negativo, diverso
  da 0)

Valore restituito:

// TRANSLATION MISSING
* pointer to element reached, NULL if element is not found (for example end
  of list), or if an error occurred

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* passa al buffer successivo, 2 volte */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* passa al buffer precedente */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);
----

Script (Python):

[source,python]
----
# prototipo
def hdata_move(hdata: str, pointer: str, count: int) -> str: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# passa al buffer successivo, 2 volte
buffer = weechat.hdata_move(hdata, buffer, 2)

# passa al buffer precedente
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)
----

==== hdata_search

// TRANSLATION MISSING
_WeeChat ≥ 0.4.1, updated in 3.4._

// TRANSLATION MISSING
Search element in a list: the expression _search_ is evaluated for each element
in list, until element is found (or end of list).

Prototipo:

[source,c]
----
void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search,
                            struct t_hashtable *pointers, struct t_hashtable *extra_vars,
                            struct t_hashtable *options, int move);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore ad un oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _search_: expression to evaluate, default pointer in expression is the name of
  hdata (and this pointer changes for each element in list); for help on
  expression, see the
  link:weechat_user.it.html#command_weechat_eval[WeeChat user's guide / Command /eval ^↗^^]
// TRANSLATION MISSING
* _pointers_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>
// TRANSLATION MISSING
* _extra_vars_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>
// TRANSLATION MISSING
* _options_: hashtable for call to function
  <<_string_eval_expression,string_eval_expression>>
// TRANSLATION MISSING
* _move_: number of jump(s) to execute after unsuccessful search (negative or
  positive integer, different from 0)

// TRANSLATION MISSING
[IMPORTANT]
You must ensure the _search_ expression is safe and does not include any
user data. Such unsafe data must be given in the hashtable _extra_vars_ and
referenced by `${xxx}` in the _search_ expression (see the example below).

Valore restituito:

// TRANSLATION MISSING
* pointer to element found, NULL if not found

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get_list (hdata, "irc_servers");
struct t_hashtable *extra_vars = weechat_hashtable_new (8,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        WEECHAT_HASHTABLE_STRING,
                                                        NULL,
                                                        NULL);

/* search irc server with name "libera" */
weechat_hashtable_set (extra_vars, "server_name", "libera");
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${server_name}",
                                     NULL, extra_vars, NULL, 1);
if (server)
{
    /* ... */
}
weechat_hashtable_free (extra_vars);
----

Script (Python):

// TRANSLATION MISSING
[source,python]
----
# prototipo
def hdata_search(hdata: str, pointer: str, search: str,
                 pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str],
                 count: int) -> str: ...

# esempio
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# search irc server with name "libera"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${server_name}",
                              {}, {"server_name": "libera"}, {}, 1)
if server:
    # ...
----

==== hdata_char

_WeeChat ≥ 0.3.7._

Restituisce il valore di una variabile char in una struttura dati usando hdata.

Prototipo:

[source,c]
----
char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "char"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore char della variabile

Esempio in C:

[source,c]
----
weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_char(hdata: str, pointer: str, name: str) -> int: ...

# esempio
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))
----

==== hdata_integer

_WeeChat ≥ 0.3.6._

Restituisce il valore di una variabile integer in una struttura dati usando hdata.

Prototipo:

[source,c]
----
int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "integer"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore intero della variabile

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_integer(hdata: str, pointer: str, name: str) -> int: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))
----

==== hdata_long

_WeeChat ≥ 0.3.6._

Restituisce il valore della variabile "long" della struttura usando hdata.

Prototipo:

[source,c]
----
long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "long"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore long della variabile

Esempio in C:

[source,c]
----
weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_long(hdata: str, pointer: str, name: str) -> int: ...

# esempio
weechat.prnt("", "longvar = %d" % weechat.hdata_long(hdata, pointer, "longvar"))
----

==== hdata_longlong

_WeeChat ≥ 4.3.0._

// TRANSLATION MISSING
Return value of "long long" variable in structure using hdata.

Prototipo:

[source,c]
----
long long weechat_hdata_longlong (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "long long"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

// TRANSLATION MISSING
* "long long" value of variable

Esempio in C:

[source,c]
----
weechat_printf (NULL, "longlongvar = %lld", weechat_hdata_longlong (hdata, pointer, "longlongvar"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_longlong(hdata: str, pointer: str, name: str) -> int: ...

# esempio
weechat.prnt("", "longlongvar = %d" % weechat.hdata_longlong(hdata, pointer, "longlongvar"))
----

==== hdata_string

_WeeChat ≥ 0.3.6._

Restituisce il valore della variabile string nella struttura usando hdata.

Prototipo:

[source,c]
----
const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "string"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore stringa della variabile

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_string(hdata: str, pointer: str, name: str) -> str: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))
----

==== hdata_pointer

_WeeChat ≥ 0.3.6._

Restituisce il valore della variabile puntatore nella struttura usando hdata.

Prototipo:

[source,c]
----
void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: hdata hdata
* _pointer_: pointer all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "pointer"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore puntatore della variabile

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %p", weechat_hdata_pointer (hdata, buffer, "lines"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_pointer(hdata: str, pointer: str, name: str) -> str: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %x" % weechat.hdata_pointer(hdata, buffer, "lines"))
----

==== hdata_time

_WeeChat ≥ 0.3.6._

Restituisce il valore della variabile time nella struttura usando hdata.

Prototipo:

[source,c]
----
time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "time"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore time della variabile

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
        }
    }
}
----

Script (Python):

[source,python]
----
# prototipo
def hdata_time(hdata: str, pointer: str, name: str) -> int: ...

# esempio
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date))))
----

==== hdata_hashtable

_WeeChat ≥ 0.3.7._

Restituisce il valore di una variabile nella tabella hash nella struttura usando
hdata.

Prototipo:

[source,c]
----
struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);
----

Argomenti:

* _hdata_: puntatore hdata
* _pointer_: puntatore all'oggetto di WeeChat/plugin
// TRANSLATION MISSING
* _name_: nome della variabile (deve essere di tipo "hashtable"); for arrays,
  the name can be "N|name" where N is the index in array (starting at 0),
  for example: "2|name"

Valore restituito:

* valore della tabella hash della variabile (puntatore alla tabella hash)

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d local variables in core buffer",
                weechat_hashtable_get_integer (hashtable, "items_count"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_hashtable(hdata: str, pointer: str, name: str) -> Dict[str, str]: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "local variables in core buffer:")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))
----

// TRANSLATION MISSING
==== hdata_compare

_WeeChat ≥ 1.9, updated in 4.1.0._

Compare a hdata variable of two objects.

Prototipo:

[source,c]
----
int weechat_hdata_compare (struct t_hdata *hdata, void *pointer1, void *pointer2, const char *name, int case_sensitive);
----

Argomenti:

* _hdata_: hdata pointer
* _pointer1_: pointer to first WeeChat/plugin object
* _pointer2_: pointer to second WeeChat/plugin object
* _name_: variable name or path to a variable name; for arrays, the name can be
  "N|name" where N is the index in array (starting at 0), for example: "2|name"
* _case_sensitive_: 1 for case-sensitive comparison of strings, otherwise 0

Valore restituito:

* -1 if variable1 < variable2
* 0 if variable1 == variable2
* 1 if variable1 > variable2

Esempio in C:

[source,c]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("irc", "libera.#weechat-fr");
weechat_printf (NULL, "comparison of buffer number = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "number", 0));
weechat_printf (NULL, "comparison of number of lines = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "own_lines.lines_count", 0));
weechat_printf (NULL, "comparison of local variable = %d",
                weechat_hdata_compare (hdata, buffer1, buffer2, "local_variables.myvar", 0));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_compare(hdata: str, pointer1: str, pointer2: str, name: str, case_sensitive: int) -> int: ...

# esempio
hdata = weechat.hdata_get("buffer")
buffer1 = weechat.buffer_search("irc", "libera.#weechat")
buffer2 = weechat.buffer_search("irc", "libera.#weechat-fr")
weechat.prnt("", "comparison of buffer number = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "number", 0))
weechat.prnt("", "comparison of number of lines = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "own_lines.lines_count", 0))
weechat.prnt("", "comparison of local variable = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "local_variables.myvar", 0))
----

// TRANSLATION MISSING
==== hdata_set

_WeeChat ≥ 0.3.9._

Set new value for variable in a hdata.

[NOTE]
This function can be called only in an update callback
(see <<_hdata_new,hdata_new>> and <<_hdata_update,hdata_update>>),
if the variable can be updated.

Prototipo:

[source,c]
----
int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);
----

Argomenti:

* _hdata_: hdata pointer
* _pointer_: pointer to WeeChat/plugin object
* _name_: variable name (types allowed: char, integer, long, string, pointer,
  time)
* _value_: new value for variable

Valore restituito:

* 1 if ok, 0 if error

Esempio in C:

[source,c]
----
weechat_hdata_set (hdata, pointer, "message", "test");
----

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

// TRANSLATION MISSING
==== hdata_update

_WeeChat ≥ 0.3.9._

Update data in a hdata.

Prototipo:

[source,c]
----
int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);
----

Argomenti:

* _hdata_: hdata pointer
* _pointer_: pointer to WeeChat/plugin object
* _hashtable_: variables to update: keys are name of variables, values are new
  values for variables (keys and values are string), some special keys are
  allowed:
// TRANSLATION MISSING
** key `+__create_allowed+` (with any value): return 1 if create is allowed for
   structure, otherwise 0 _(WeeChat ≥ 0.4.0)_
** key `+__delete_allowed+` (with any value): return 1 if delete is allowed for
   structure, otherwise 0
** key `+__update_allowed+`, value is name of a variable: return 1 if update is
   allowed for this variable, otherwise 0
** key `+__delete+` (with any value): delete structure (if allowed)

Valore restituito:

* number of variables updated

Esempio in C:

[source,c]
----
/* subtract one hour on last message displayed in current buffer */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}
----

Script (Python):

[source,python]
----
# prototipo
def hdata_update(hdata: str, pointer: str, hashtable: Dict[str, str]) -> int: ...

# example: subtract one hour on last message displayed in current buffer
own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
        hdata = weechat.hdata_get("line_data")
        weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})
----

==== hdata_get_string

_WeeChat ≥ 0.3.6._

Restituisce il valore stringa di una proprietà di hdata.

Prototipo:

[source,c]
----
const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);
----

Argomenti:

* _hdata_: puntatore hdata
* _property_: nome della proprietà:
** _var_keys_: stringa con la lista di chiavi per le variabili in hdata
   (formato: "key1,key2,key3")
** _var_values_: stringa con la lista di valori per le variabili in hdata
   (formato: "value1,value2,value3")
** _var_keys_values_: stringa cona la lista di chiavi e valori per le variabili in hdata
   (formato: "key1:value1,key2:value2,key3:value3")
** _var_prev_: nome della variabile nella struttura che fa da puntatore al
   precedente elemento nella lista
** _var_next_: nome della variabile nella struttura che fa da puntatore al
   successivo elemento nella lista
** _list_keys_: stringa con la lista di chiavi per le liste in hdata
   (formato: "key1,key2,key3")
** _list_values_: stringa con la lista di valori per le liste in hdata
   (formato: "value1,value2,value3")
** _list_keys_values_: stringa con la lista di chiavi e valori per le liste in hdata
   (formato: "key1:value1,key2:value2,key3:value3")

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,c]
----
weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys"));
----

Script (Python):

[source,python]
----
# prototipo
def hdata_get_string(hdata: str, property: str) -> str: ...

# esempio
weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))
----

[[upgrade]]
=== Aggiornamento

Funzioni per l'aggiornamento di WeeChat (comando "/upgrade").

==== upgrade_new

// TRANSLATION MISSING
_Updated in 1.5._

Crea o legge un file per l'aggiornamento.

Prototipo:

[source,c]
----
struct t_upgrade_file *upgrade_file_new (const char *filename,
                                         int (*callback_read)(const void *pointer,
                                                              void *data,
                                                              struct t_upgrade_file *upgrade_file,
                                                              int object_id,
                                                              struct t_infolist *infolist),
                                         const void *callback_read_pointer,
                                         void *callback_read_data);
----

Argomenti:

* _filename_: nome del file (l'estensione ".upgrade" verrà aggiunta a questo nome
  da WeeChat)
* _callback_read_: funzione chiamata per ogni oggetto letto nel file
  di aggiornamento, argomenti e valore restituito:
** _const void *pointer_: puntatore
** _void *data_: puntatore
** _struct t_upgrade_file *upgrade_file_: puntatore al file di aggiornamento
** _int object_id_: id dell'oggetto
** _struct t_infolist *infolist_: lista info con il contenuto dell'oggetto
** valore restituito:
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_read_pointer_: puntatore fornito alla callback quando chiamata da
  WeeChat
// TRANSLATION MISSING
* _callback_read_data_: puntatore fornito dalla callback quando chiamata da
  WeeChat; if not NULL, it must have been allocated with malloc (or similar
  function) and it is automatically freed when the upgrade file is closed

Valore restituito:

* puntatore al file di aggiornamento

Esempio in C:

[source,c]
----
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file",
                                                           NULL, NULL, NULL);
----

Script (Python):

[source,python]
----
# prototipo
def upgrade_new(filename: str, callback_read: str, callback_read_data: str) -> str: ...

# esempio
upgrade_file = weechat.upgrade_new("my_file", "", "")
----

==== 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
def upgrade_write_object(upgrade_file: str, object_id: int, infolist: str) -> int: ...

# esempio
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----

==== upgrade_read

// TRANSLATION MISSING
_Updated in 1.5._

Legge un file di aggiornamento.

Prototipo:

[source,c]
----
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file);
----

Argomenti:

* _upgrade_file_: puntatore al file di aggiornamento

Valore restituito:

* 1 se ok, 0 se errore

Esempio in C:

[source,c]
----
weechat_upgrade_read (upgrade_file);
----

Script (Python):

[source,python]
----
# prototipo
def upgrade_read(upgrade_file: str) -> int: ...

# esempio
weechat.upgrade_read(upgrade_file)
----

==== 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
def upgrade_close(upgrade_file: str) -> int: ...

# esempio
weechat.upgrade_close(upgrade_file)
----