diff options
author | Sébastien Helleu <flashcode@flashtux.org> | 2014-05-25 12:25:58 +0200 |
---|---|---|
committer | Sébastien Helleu <flashcode@flashtux.org> | 2014-05-25 12:47:24 +0200 |
commit | dc0229617ada67fd02815bbc94b245871248b9db (patch) | |
tree | 0af7418d7f3ebf8082408fa2ee9e73f5a572360f /doc/it/weechat_scripting.it.asciidoc | |
parent | 76a066c9cca620e1204815f63abbfa8b09f162c6 (diff) | |
download | weechat-dc0229617ada67fd02815bbc94b245871248b9db.zip |
doc: use .asciidoc extension instead of .txt for doc files
Diffstat (limited to 'doc/it/weechat_scripting.it.asciidoc')
-rw-r--r-- | doc/it/weechat_scripting.it.asciidoc | 975 |
1 files changed, 975 insertions, 0 deletions
diff --git a/doc/it/weechat_scripting.it.asciidoc b/doc/it/weechat_scripting.it.asciidoc new file mode 100644 index 000000000..594f8b055 --- /dev/null +++ b/doc/it/weechat_scripting.it.asciidoc @@ -0,0 +1,975 @@ += Guida allo Scripting di WeeChat +:author: Sébastien Helleu +:email: flashcode@flashtux.org +:lang: it +:toc: +:toclevels: 3 + + +Questo manuale documenta il client di chat WeeChat, ed è parte +del programma stesso. + +La versione più recente di questo documento si trova qui: +http://weechat.org/doc + + +[[introduction]] +== Introduzione + +WeeChat (Wee Enhanced Environment for Chat) è un client di chat libero, +veloce e leggero, realizzato per molti sistemi operativi. + +Questo manuale documenta come scrivere script per WeeChat, usando uno dei +linguaggi di scripting supportati: + +* python +* perl +* ruby +* lua +* tcl +* guile (scheme) + +[NOTE] +Quasi tutti gli esempi in questo manuale sono scritti in Python, ma l'API +è identica per gli altri linguaggi. + +[[scripts_in_weechat]] +== Script in WeeChat + +[[languages_specificities]] +=== Specifiche per i linguaggi + +==== Python + +* E necessario `import weechat` +* Le funzioni `print*` sono chiamate `prnt*` in python (dato che 'print' + è una parola riservata) +* Le funzioni sono chiamate con `weechat.xxx(arg1, arg2, ...)` + +==== Perl + +* Le funzioni sono chiamate con `weechat::xxx(arg1, arg2, ...);` + +==== Ruby + +* E necessario definire 'weechat_init' e chiamare 'register' all'interno +* Le funzioni sono chiamate con `Weechat.xxx(arg1, arg2, ...)` +* A causa di una limitazione di Ruby (massimo 15 argomenti per funzione), la + funzione `WeeChat.config_new_option` riceve le callback in un array di 6 + stringhe (3 callback + 3 stringhe di dati), così che una chiamata a questa + funzione appare come: + +[source,ruby] +---- +Weechat.config_new_option(config, section, "name", "string", "description of option", "", 0, 0, + "value", "value", 0, ["check_cb", "", "change_cb", "", "delete_cb", ""]) +---- + +==== Lua + +* Le funzioni sono chiamate con `weechat.xxx(arg1, arg2, ...)` + +==== Tcl + +* Le funzioni sono chiamate con `weechat::xxx arg1 arg2 ...` + +==== Guile (scheme) + +* Le funzioni sono chiamate con `(weechat:xxx arg1 arg2 ...)` +* Le seguenti funzioni prendono un elenco di argomenti (invece di più argomenti + come per le altre funzioni), poiché il numero di argomenti eccede il numero + di argomenti consentiti in Guile: +** config_new_section +** config_new_option +** bar_new + +[[register_function]] +=== Registrare una funzione + +Tutti gli script WeeChat devono "registrare" loro stessi in WeeChat, e questo +deve essere la prima funzione chiamata nello script di WeeChat. + +Prototipo: + +[source,python] +---- +weechat.register(name, author, version, license, description, shutdown_function, charset) +---- + +Argomenti: + +* 'name': stringa, nome interno dello script +* 'author': stringa, nome dell'autore +* 'version': stringa, versione dello script +* 'license': stringa, licenza dello script +* 'description': stringa, breve descrizione dello script +* 'shutdown_function': stringa, nome della funzione chiamata quando lo script + viene scaricato (può essere una stringa vuota) +* 'charset': stringa, set caratteri dello script (se il proprio script è in UTF-8, + è possibile utilizzare un valore nullo qui, dato che UTF-8 è il set caratteri predefinito) + +Esempio di script, per ogni linguaggio: + +* python: + +[source,python] +---- +import weechat + +weechat.register("test_python", "FlashCode", "1.0", "GPL3", "Test script", "", "") +weechat.prnt("", "Hello, from python script!") +---- + +* perl: + +[source,perl] +---- +weechat::register("test_perl", "FlashCode", "1.0", "GPL3", "Test script", "", ""); +weechat::print("", "Hello, from perl script!"); +---- + +* ruby: + +[source,ruby] +---- +def weechat_init + Weechat.register("test_ruby", "FlashCode", "1.0", "GPL3", "Test script", "", "") + Weechat.print("", "Hello, from ruby script!") + return Weechat::WEECHAT_RC_OK +end +---- + +* lua: + +[source,lua] +---- +weechat.register("test_lua", "FlashCode", "1.0", "GPL3", "Test script", "", "") +weechat.print("", "Hello, from lua script!") +---- + +* tcl: + +[source,tcl] +---- +weechat::register "test_tcl" "FlashCode" "1.0" "GPL3" "Test script" "" "" +weechat::print "" "Hello, from tcl script!" +---- + +* guile (scheme): + +[source,lisp] +---- +(weechat:register "test_scheme" "FlashCode" "1.0" "GPL3" "Test script" "" "") +(weechat:print "" "Hello, from scheme script!") +---- + +[[load_script]] +=== Caricare uno script + +Si raccomanda di usare il plugin "script" per caricare gli script, ad esempio: + +---- +/script load script.py +/script load script.pl +/script load script.rb +/script load script.lua +/script load script.tcl +/script load script.scm +---- + +Ogni linguaggio ha anche il suo comando specifico: + +---- +/python load python/script.py +/perl load perl/script.pl +/ruby load ruby/script.rb +/lua load lua/script.lua +/tcl load tcl/script.tcl +/guile load guile/script.scm +---- + +È possibile creare un link nella directory 'linguaggio/autoload' per caricare +automaticamente gli script all'avvio di WeeChat. + +Ad esempio con Python: + +---- +$ cd ~/.weechat/python/autoload +$ ln -s ../script.py +---- + +[NOTE] +Quando viene installato un script con il comando `/script install` il link nella +directory 'autoload' viene creato automaticamente'. + +[[differences_with_c_api]] +== Differenze con le API in C + +Le API per gli script sono quasi identiche di quelle per i plugin C. +È possibile consultare '*' per i dettagli su ogni funzione nelle API: +prototipo, argomenti, valori restituiti, esempi. + +È importante fare la differenza tra un 'plugin' ed uno 'script': +un plugin è un file binario compilato e caricato con il comando +`plugin`, mentre uno 'script' è un file di testo caricato tramite +un plugin come 'python' con il comando `python`. + +Quando il proprio script 'test.py' chiama una funzione delle API di +Weechat, il path è simile a questo: + +.... + ┌──────────────────────┐ ╔══════════════════╗ + │ python plugin │ ║ WeeChat "core" ║ + ├────────────┬─────────┤ ╟─────────┐ ║ +test.py ─────► │ script API │ C API │ ─────► ║ C API │ ║ + └────────────┴─────────┘ ╚═════════╧════════╝ +.... + +Quando WeeChat chiama una callback nel proprio script 'test.py', è +l'opposto del path precedente: + +.... +╔══════════════════╗ ┌──────────────────────┐ +║ WeeChat "core" ║ │ python plugin │ +║ ┌─────────╢ ├─────────┬────────────┤ +║ │ C API ║ ─────► │ C API │ script API │ ─────► test.py +╚════════╧═════════╝ └─────────┴────────────┘ +.... + +[[pointers]] +=== Puntatori + +Come è già noto probabilmente, non esistono realmente i "puntatori" +negli script. Quando le funzioni API restituiscono un puntatore, viene +covertito in una stringa per lo script. + +Ad esempio, se la funzione restituisce il puntatore 0x1234ab56, lo +script riceverà la stringa "0x1234ab56". + +E quando una funzione API si aspetta un puntatore nell'argomento, lo script +deve fornire quel valore stringa. Il plugin C lo convertirà in un puntatore reale +prima di chiamare la funzione API in C. + +Sono consentite stringhe vuote oppure "0x0", valgono come NULL in C. +Ad esempio, per stampare dei dati sul buffer core (il buffer principale di +WeeChat), è possibile fare questo: + +[source,python] +---- +weechat.prnt("", "hi!") +---- + +[WARNING] +In molte funzioni, per motivi legati alla velocità, WeeChat non verifica se +il puntatore è corretto oppure no. È il proprio lavoro controllare che si +stia fornendo un puntatore valido, altrimenti potrebbe comparire una +bella segnalazione per un errore ;) + +[[callbacks]] +=== Callback + +Quasi tutte le callback di WeeChat devono restituire WEECHAT_RC_OK +oppure WEECHAT_RC_ERROR (l'eccezione è la callback modifier, che +restituisce una stringa). + +Le callback in C utilizzano un argomento "data", che è un puntatore. +Nelle API per gli script, questo "data" è una stringa con un qualsiasi +valore (non è un puntatore). + +Esempio di callback, per ogni linguaggio: + +* python: + +[source,python] +---- +def timer_cb(data, remaining_calls): + weechat.prnt("", "timer! data=%s" % data) + return weechat.WEECHAT_RC_OK + +weechat.hook_timer(1000, 0, 1, "timer_cb", "test") +---- + +* perl: + +[source,perl] +---- +sub timer_cb { + my ($data, $remaining_calls) = @_; + weechat::print("", "timer! data=$data"); + return weechat::WEECHAT_RC_OK; +} + +weechat::hook_timer(1000, 0, 1, "timer_cb", "test"); +---- + +* ruby: + +[source,ruby] +---- +def timer_cb(data, remaining_calls) + Weechat.print("", "timer! data=#{data}"); + return Weechat::WEECHAT_RC_OK +end + +Weechat.hook_timer(1000, 0, 1, "timer_cb", "test"); +---- + +* lua: + +[source,lua] +---- +function timer_cb(data, remaining_calls) + weechat.print("", "timer! data="..data) + return weechat.WEECHAT_RC_OK +end + +weechat.hook_timer(1000, 0, 1, "timer_cb", "test") +---- + +* tcl: + +[source,tcl] +---- +proc timer_cb { data remaining_calls } { + weechat::print {} "timer! data=$data" + return $::weechat::WEECHAT_RC_OK +} + +weechat::hook_timer 1000 0 1 timer_cb test +---- + +* guile (scheme): + +[source,lisp] +---- +(define (timer_cb data remaining_calls) + (weechat:print "" (string-append "timer! data=" data)) + weechat:WEECHAT_RC_OK +) + +(weechat:hook_timer 1000 0 1 "timer_cb" "test") +---- + +[[script_api]] +== Script API + +Per maggiori informazioni sulle funzioni nelle API, +consultare 'Referenze API per Plugin di WeeChat'. + +[[script_api_functions]] +=== Funzioni + +Elenco di funzioni nelle API per gli script: + +[width="100%",cols="^1,10",options="header"] +|=== +| Categoria | Funzioni +| generale | + register +| plugin | + plugin_get_name +| stringhe | + charset_set, iconv_to_internal, iconv_from_internal, gettext, ngettext, + + strlen_screen, string_match, string_has_highlight, string_has_highlight_regex, + string_mask_to_regex, string_remove_color, string_is_command_char, + string_input_for_buffer, string_eval_expression +| directory | + mkdir_home, mkdir, mkdir_parents +| liste ordinate | + list_new, list_add, list_search, list_search_pos, list_casesearch, + list_casesearch_pos, list_get, list_set, list_next, list_prev, list_string, + list_size, list_remove, list_remove_all, list_free +| file di configurazione | + config_new, config_new_section, config_search_section, config_new_option, + config_search_option, + + config_string_to_boolean, config_option_reset, config_option_set, + config_option_set_null, config_option_unset, config_option_rename, + config_option_is_null, config_option_default_is_null, + + config_boolean, config_boolean_default, config_integer, config_integer_default, + config_string, config_string_default, config_color, config_color_default, + + config_write_option, config_write_line, config_write, config_read, + config_reload, + + config_option_free, config_section_free_options, config_section_free, + config_free, + + config_get, config_get_plugin, config_is_set_plugin, config_set_plugin, + config_set_desc_plugin, config_unset_plugin +| combinazione tasti | + key_bind, key_unbind +| visualizzazione | + prefix, color, print (for python: prnt), print_date_tags (for python: + prnt_date_tags), print_y (for python: prnt_y), log_print +| hook | + hook_command, hook_command_run, hook_timer, hook_fd, hook_process, + hook_process_hashtable, hook_connect, hook_print, hook_signal, + hook_signal_send, hook_hsignal, hook_hsignal_send, hook_config, + hook_completion, hook_completion_list_add, hook_modifier, hook_modifier_exec, + hook_info, hook_info_hashtable, hook_infolist, hook_focus, hook_set, unhook, + unhook_all +| buffer | + buffer_new, current_buffer, buffer_search, buffer_search_main, buffer_clear, + buffer_close, buffer_merge, buffer_unmerge, buffer_get_integer, + buffer_get_string, buffer_get_pointer, buffer_set, + buffer_string_replace_local_var, buffer_match_list +| finestre | + current_window, window_search_with_buffer, window_get_integer, + window_get_string, window_get_pointer, window_set_title +| lista nick | + nicklist_add_group, nicklist_search_group, nicklist_add_nick, + nicklist_search_nick, nicklist_remove_group, nicklist_remove_nick, + nicklist_remove_all, nicklist_group_get_integer, nicklist_group_get_string, + nicklist_group_get_pointer, nicklist_group_set, nicklist_nick_get_integer, + nicklist_nick_get_string, nicklist_nick_get_pointer, nicklist_nick_set +| barre | + bar_item_search, bar_item_new, bar_item_update, bar_item_remove, bar_search, + bar_new, bar_set, bar_update, bar_remove +| comandi | + comando +| info | + info_get, info_get_hashtable +| liste info | + infolist_new, infolist_new_item, infolist_new_var_integer, + infolist_new_var_string, infolist_new_var_pointer, infolist_new_var_time, + + infolist_get, infolist_next, infolist_prev, infolist_reset_item_cursor, + + infolist_fields, infolist_integer, infolist_string, infolist_pointer, + + infolist_time, infolist_free +| hdata | + hdata_get, hdata_get_var_offset, hdata_get_var_type_string, + hdata_get_var_array_size, hdata_get_var_array_size_string, + hdata_get_var_hdata, hdata_get_list, hdata_check_pointer, hdata_move, + hdata_search, hdata_char, hdata_integer, hdata_long, hdata_string, + hdata_pointer, hdata_time, hdata_hashtable, hdata_update, hdata_get_string +| aggiornamento | + upgrade_new, upgrade_write_object, upgrade_read, upgrade_close +|=== + +[[script_api_constants]] +=== Costanti + +Elenco di costanti nelle API per gli script: + +[width="100%",cols="^1,10",options="header"] +|=== +| Categoria | Costanti +| codici restituiti | + WEECHAT_RC_OK, WEECHAT_RC_OK_EAT, WEECHAT_RC_ERROR +| file di configurazione | + WEECHAT_CONFIG_READ_OK, WEECHAT_CONFIG_READ_MEMORY_ERROR, + WEECHAT_CONFIG_READ_FILE_NOT_FOUND, WEECHAT_CONFIG_WRITE_OK, + WEECHAT_CONFIG_WRITE_ERROR, WEECHAT_CONFIG_WRITE_MEMORY_ERROR, + + 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, + WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET, WEECHAT_CONFIG_OPTION_UNSET_OK_RESET, + WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED, WEECHAT_CONFIG_OPTION_UNSET_ERROR +| liste ordinate | + WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING, WEECHAT_LIST_POS_END +| hotlist | + WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, + WEECHAT_HOTLIST_HIGHLIGHT +| hook su processo | + WEECHAT_HOOK_PROCESS_RUNNING, WEECHAT_HOOK_PROCESS_ERROR +| hook su connessione | + WEECHAT_HOOK_CONNECT_OK, WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND, + WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND, WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED, + WEECHAT_HOOK_CONNECT_PROXY_ERROR, WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR, + WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR, WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR, + WEECHAT_HOOK_CONNECT_MEMORY_ERROR, WEECHAT_HOOK_CONNECT_TIMEOUT, + WEECHAT_HOOK_CONNECT_SOCKET_ERROR +| hook su segnale | + WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT, WEECHAT_HOOK_SIGNAL_POINTER +|=== + +[[common_tasks]] +== Compiti comuni + +Questo capitolo spiega alcuni compiti comuni, con degli esempi. +Verranno utilizzati soltanto degli elementi parziali contenuti +nelle API, per un riferimento completo consultare +'Referenze API per Plugin di WeeChat'. + +[[buffers]] +=== Buffer + +[[buffers_display_messages]] +==== Visualizzare messaggi + +Una stringa vuota è utilizzata spesso per lavorare con il buffer core di +WeeChat. Per gli altri buffer, è necessario fornire un puntatore (come +stringa, consultare <<pointers,pointers>>). + +Esempi: + +[source,python] +---- +# visualizza "hello" sul buffer core +weechat.prnt("", "hello") + +# visualizza "hello" sul buffer core, ma non salva sul file di log +# (solo versioni >= 0.3.3) +weechat.prnt_date_tags("", 0, "no_log", "hello") + +# visualizza il prefisso "==>" ed il messaggio "hello" sul buffer corrente +# (prefisso e messaggio vanno separati da una tabulazione) +weechat.prnt(weechat.current_buffer(), "==>\thello") + +# visualizza un messaggio di errore sul buffer core (con il prefisso di errore) +weechat.prnt("", "%swrong arguments" % weechat.prefix("error")) + +# visualizza messaggio con il colore sul buffer core +weechat.prnt("", "text %syellow on blue" % weechat.color("yellow,blue")) + +# cerca buffer e visualizza messaggiosearch buffer and display message +# (il nome completo del buffer è plugin.nome, ad esempio: "irc.freenode.#weechat") +buffer = weechat.buffer_search("irc", "freenode.#weechat") +weechat.prnt(buffer, "message on #weechat channel") + +# altra soluzione per cercare un buffer IRC (migliore) +# (nota: server e canale sono separati da virgola) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.prnt(buffer, "message on #weechat channel") +---- + +[NOTE] +La funzione print si chiama `print` in Perl/Ruby/Lua/Tcl e `prnt` in Python. + +[[buffers_send_text]] +==== Invia testo al buffer + +È possibile inviare del testo o un comando ad un buffer. È esattamente come +se si digitasse del testo o un comando, seguiti da [Enter]. + +Esempi: + +// TRANSLATION MISSING +[source,python] +---- +# execute command "/help" on current buffer (result is on core buffer) +weechat.command("", "/help") + +# invia "hello" sul canale IRC #weechat (gli utenti sul canale vedranno il messaggio) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.command(buffer, "hello") +---- + +[[buffers_new]] +==== Creare un nuovo buffer + +È possibile creare un nuovo buffer nel proprio script, per poi utilizzarlo per +visualizzare i messaggi. + +Possono essere chiamate due callback (sono opzionali): una per i dati in +input (quando viene digitato del testo e premuto [Enter] sul buffer), l'altra +quando il buffer viene chiuso (ad esempio con `/buffer close`). + +Esempio: + +[source,python] +---- +# callback per i dati ricevuti in input +def buffer_input_cb(data, buffer, input_data): + # ... + return weechat.WEECHAT_RC_OK + +# callback chiamata alla chiusura del buffer +def buffer_close_cb(data, buffer): + # ... + return weechat.WEECHAT_RC_OK + +# crea un buffer +buffer = weechat.buffer_new("mybuffer", "buffer_input_cb", "", "buffer_close_cb", "") + +# imposta titolo +weechat.buffer_set(buffer, "title", "Questo titolo è per il mio buffer.") + +# disabilita il logging, impostando la variabile locale "no_log" ad "1" +weechat.buffer_set(buffer, "localvar_set_no_log", "1") +---- + +[[buffers_properties]] +==== Proprietà dei buffer + +Si possono leggere le proprietà del buffer, come stringa, intero o puntatore. + +Esempi: + +[source,python] +---- +buffer = weechat.current_buffer() + +number = weechat.buffer_get_integer(buffer, "number") +name = weechat.buffer_get_string(buffer, "name") +short_name = weechat.buffer_get_string(buffer, "short_name") +---- + +È possibile aggiungere, leggere o eliminare le variabili locali nel buffer: + +[source,python] +---- +# aggiunge la variabile locale +weechat.buffer_set(buffer, "localvar_set_myvar", "my_value") + +# legge la variabile locale +myvar = weechat.buffer_get_string(buffer, "localvar_myvar") + +# elimina la variabile locale +weechat.buffer_set(buffer, "localvar_del_myvar", "") +---- + +Per impostare le variabili locali di un buffer, digitare questo comando +in WeeChat: + +---- +/buffer localvar +---- + +[[hooks]] +=== Hook + +[[hook_command]] +==== Aggiungere un nuovo comando + +Aggiunge un comando personalizzato con `hook_command`. Si può fare uso di +un template di completamento personalizzato per completare gli argomenti +del proprio comando. + +Esempio: + +[source,python] +---- +def my_command_cb(data, buffer, args): + # ... + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_command("myfilter", "descrizione di myfilter", + "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]", + "descrizione degli argomenti...", + "list" + " || enable %(filters_names)" + " || disable %(filters_names)" + " || toggle %(filters_names)" + " || add %(filters_names) %(buffers_plugins_names)|*" + " || del %(filters_names)|-all", + "my_command_cb", "") +---- + +E poi in WeeChat: + +---- +/help myfilter + +/myfilter arguments... +---- + +[[hook_timer]] +==== Aggiungere un timer + +Aggiungere un timer con `hook_timer`. + +Esempio: + +[source,python] +---- +def timer_cb(data, remaining_calls): + # ... + return weechat.WEECHAT_RC_OK + +# timer chiamato ogni minuto quandi i secondi sono 00 +weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "") +---- + +[[hook_process]] +==== Eseguire un processo in background + +È possibile eseguire un processo in background con `hook_process`. La +callback verrà chiamata quando i dati sono pronti. Può essere chiamata +più volte. + +Per l'ultima chiamata alla callback, 'rc' è impostato a zero o su un +valore positivo, è il codice restituito dal comando. + +Esempio: + +[source,python] +---- +process_output = "" + +def my_process_cb(data, command, rc, out, err): + global process_output + if out != "": + process_output += out + if int(rc) >= 0: + weechat.prnt("", process_output) + return weechat.WEECHAT_RC_OK + +weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "") +---- + +[[url_transfer]] +==== Trasferimento URL + +_Novità nella versione 0.3.7._ + +Per scaricare un URL (o inviare verso un URL), è necessario usare la funzione +`hook_process` oppure `hook_process_hashtable` se ci fosse bisogno di impostare +delle opzioni per il trasferimento dell'URL. + +Esempio di trasferimento di un URL senza opzioni: la pagina HTML verrà +ricevuta come "out" nella callback (output standard di un processo): + +[source,python] +---- +# Mostra la versione stabile corrente di WeeChat. +weechat_version = "" + +def weechat_process_cb(data, command, rc, out, err): + global weechat_version + if out != "": + weechat_version += out + if int(rc) >= 0: + weechat.prnt("", "Current WeeChat stable is: %s" % weechat_version) + return weechat.WEECHAT_RC_OK + +weechat.hook_process("url:http://weechat.org/dev/info/stable/", + 30 * 1000, "weechat_process_cb", "") +---- + +[TIP] +Tutte le informazioni disponibili su Weechat sono sulla pagina +http://weechat.org/dev/info + +Esempio di trasferimento di un URL con un'opzione: scaricare l'ultimo pacchetto +di sviluppo di WeeChat nel file '/tmp/weechat-devel.tar.gz': + +[source,python] +---- +def my_process_cb(data, command, rc, out, err): + if int(rc) >= 0: + weechat.prnt("", "End of transfer (rc=%s)" % rc) + return weechat.WEECHAT_RC_OK + +weechat.hook_process_hashtable("url:http://weechat.org/files/src/weechat-devel.tar.gz", + { "file_out": "/tmp/weechat-devel.tar.gz" }, + 30 * 1000, "my_process_cb", "") +---- + +Per maggiori informazioni sul trasferimento degli URL e le opzioni disponibili, +consultare le funzioni `hook_process` e `hook_process_hashtable` in 'Referenze +API per Plugin'. + +[[config_options]] +=== Configurazione / opzioni + +[[config_options_set_script]] +==== Impostare l'opzione per lo script + +La funzione `config_is_set_plugin` viene utilizzare per verificare se un'opzione +è impostata oppure no, e `config_set_plugin` per impostare l'opzione. + +Esempio: + +[source,python] +---- +script_options = { + "option1" : "value1", + "option2" : "value2", + "option3" : "value3", +} +for option, default_value in script_options.items(): + if not weechat.config_is_set_plugin(option): + weechat.config_set_plugin(option, default_value) +---- + +[[config_options_detect_changes]] +==== Rilevare le modifiche + +È necessario utilizzare `hook_config` per essere notificati se l'utente dovesse +modificare alcune opzioni dello script. + +Esempio: + +[source,python] +---- +SCRIPT_NAME = "myscript" + +# ... + +def config_cb(data, option, value): + """Callback called when a script option is changed.""" + # for example, read all script options to script variables... + # ... + return weechat.WEECHAT_RC_OK + +# ... + +weechat.hook_config("plugins.var.python." + SCRIPT_NAME + ".*", "config_cb", "") +# for other languages, change "python" with your language ("perl", "ruby", "lua" or "tcl") +---- + +[[config_options_weechat]] +==== Leggere le opzioni di WeeChat + +La funzione `config_get` restituisce il puntatore all'opzione. Poi, in base al tipo +di opzione, è necessario chiamare `config_string`, `config_boolean`, +`config_integer` oppure `config_color`. + +[source,python] +---- +# stringa +weechat.prnt("", "value of option weechat.look.item_time_format is: %s" + % (weechat.config_string(weechat.config_get("weechat.look.item_time_format")))) + +# bool +weechat.prnt("", "value of option weechat.look.day_change is: %d" + % (weechat.config_boolean(weechat.config_get("weechat.look.day_change")))) + +# intero +weechat.prnt("", "value of option weechat.look.scroll_page_percent is: %d" + % (weechat.config_integer(weechat.config_get("weechat.look.scroll_page_percent")))) + +# colore +weechat.prnt("", "value of option weechat.color.chat_delimiters is: %s" + % (weechat.config_color(weechat.config_get("weechat.color.chat_delimiters")))) +---- + +[[irc]] +=== IRC + +[[irc_catch_messages]] +==== Catturare messaggi + +Il plugin IRC invia due segnali per un messaggio ricevuto (`xxx` è il nome +interno del server IRC, `yyy` è il nome del comando IRC come JOIN, QUIT, +PRIVMSG, 301, ..): + +xxxx,irc_in_yyy:: + segnale inviato prima di esaminare il messaggio + +xxx,irc_in2_yyy:: + segnale inviato dopo aver esaminato il messaggio + +[source,python] +---- +def join_cb(data, signal, signal_data): + # signal è per esempio: "freenode,irc_in2_join" + # signal_data è il messaggio IRC message, ad esempio: ":nick!user@host JOIN :#channel" + nick = weechat.info_get("irc_nick_from_host", signal_data) + server = signal.split(",")[0] + channel = signal_data.split(":")[-1] + buffer = weechat.info_get("irc_buffer", "%s,%s" % (server, channel)) + if buffer: + weechat.prnt(buffer, "Eheh, %s has joined this channel!" % nick) + return weechat.WEECHAT_RC_OK + +# può essere utile qui utilizzare "*" come server, per catturare +# i messaggi JOIN su tutti i server IRC +weechat.hook_signal("*,irc_in2_join", "join_cb", "") +---- + +[[irc_modify_messages]] +==== Modificare i messaggi + +Il plugin IRC invia un "modificatore" chiamato "irc_in_xxx" ("xxx" è il comando +IRC) per un messaggio ricevuto, in modo da poterlo modificare. + +[source,python] +---- +def modifier_cb(data, modifier, modifier_data, string): + # aggiunge il nome del server a tutti i messaggi ricevuti + # (ok non è molto utile, ma è solo un esempio!) + return "%s %s" % (string, modifier_data) + +weechat.hook_modifier("irc_in_privmsg", "modifier_cb", "") +---- + +[WARNING] +A malformed message could crash WeeChat or cause severe problems! +Un messaggio errato può mandare in crash WeeChat o causare seri problemi! + +[[irc_message_parse]] +==== Verifica messaggio + +_Novità nella versione 0.3.4._ + +È possibile verificare un messaggio irc con una info_hashtable chiamata +"irc_message_parse". + +[source,python] +---- +dict = weechat.info_get_hashtable("irc_message_parse", + { "message": ":nick!user@host PRIVMSG #weechat :message here" }) +weechat.prnt("", "dict: %s" % dict) + +# output: +# dict: {'nick': 'nick', 'host': 'nick!user@host', 'command': 'PRIVMSG', 'arguments': '#weechat :message here', 'channel': '#weechat'} +---- + +[[infos]] +=== Info + +[[infos_weechat_version]] +==== Versione di WeeChat + +Il modo migliore per verificare la versione è richiedere "version_number" e +comparare l'intero con il numero di versione esadecimale. + +Esempio: + +[source,python] +---- +version = weechat.info_get("version_number", "") or 0 +if int(version) >= 0x00030200: + weechat.prnt("", "This is WeeChat 0.3.2 or newer") +else: + weechat.prnt("", "This is WeeChat 0.3.1 or older") +---- + +[NOTE] +Le versioni ≤ 0.3.1.1 restituiscono una stringa vuota per +'info_get("version_number")', per cui bisogna verificare che +il valore restituito *non* sia vuoto. + +To get version as string: + +[source,python] +---- +# this will display for example "Version 0.3.2" +weechat.prnt("", "Version %s" % weechat.info_get("version", "")) +---- + +[[infos_other]] +==== Altre informazioni + +[source,python] +---- +# la directory home di WeeChat, ad esempio: "/home/xxxx/.weechat" +weechat.prnt("", "WeeChat home dir: %s" % weechat.info_get("weechat_dir", "")) + +# inattività della tastiera +weechat.prnt("", "Inactivity since %s seconds" % weechat.info_get("inactivity", "")) +---- + +[[infolists]] +=== Liste info + +[[infolists_read]] +==== Leggere una lista info + +È possibile leggere una lista info compilata da WeeChat +o da altri plugin. + +Esempio: + +[source,python] +---- +# legge la lista info "buffer", per ottenere la lista dei buffer +infolist = weechat.infolist_get("buffer", "", "") +if infolist: + while weechat.infolist_next(infolist): + name = weechat.infolist_string(infolist, "name") + weechat.prnt("", "buffer: %s" % name) + weechat.infolist_free(infolist) +---- + +[IMPORTANT] +Non dimenticare di chiamare `infolist_free` per liberare la memoria +utilizzata dalla lista info, perché WeeChat non libererà automaticamente +la memoria. |