Ten dokument opisuje klienta rozmów WeeChat, który jest częścią WeeChat.
Najnowsza wersja tego dokumentu znajduje się na tej stronie: https://weechat.org/doc
1. Wprowadzenie
WeeChat (Wee Enhanced Environment for Chat) jest darmowym klientem rozmów, szybkim i lekkim, zaprojektowanym dla wielu systemów operacyjnych.
Ten dokument przedstawia sposób pisania skryptów dla WeeChat z użyciem jednego ze wspieranych języków skryptowych:
-
python
-
perl
-
ruby
-
lua
-
tcl
-
guile (scheme)
Note
|
Prawie wszystkie przykłady umieszczone w tym dokumencie są napisane w Pythonie, ale API jest takie same dla wszystkich języków. |
2. Skrypty w WeeChat
2.1. Specyfika języków
2.1.1. Python
-
Należy wykonać
import weechat
-
Funkcje
print*
są nazwaneprnt*
w pythonie (ponieważ print jest zastrzeżonym słowem kluczowym) -
Funkcje są wywoływane za pomocą
weechat.xxx(arg1, arg2, ...)
2.1.2. Perl
-
Funkcje są wywoływane za pomocą
weechat::xxx(arg1, arg2, ...);
2.1.3. Ruby
-
Trzeba zdefiniować weechat_init i wywołać register wewnątrz
-
Funkcje są wywoływane za pomocą
Weechat.xxx(arg1, arg2, ...)
-
W związku z ograniczeniami Ruby (maksymalnie 15 argumentów dla funkcji), funkcja
Weechat.config_new_option
otrzymuje callbacki w postaci tablicy 6 ciągów (3 callbacki + 3 ciągi danych), wywołanie tej funkcji wygląda następująco:
2.1.4. Lua
-
Funkcje są wywoływane za pomocą
weechat.xxx(arg1, arg2, ...)
2.1.5. Tcl
-
Funkcje są wywoływane za pomocą
weechat::xxx arg1 arg2 ...
2.1.6. Guile (scheme)
-
Funkcje są wywoływane za pomocą
(weechat:xxx arg1 arg2 ...)
-
Następujące funkcje przyjmują pojedynczą listę argumentów (zamiast wielu argumentów dla innych funkcji), ponieważ ilość argumentów przekracza ilość argumentów dozwolonych w Guile:
-
config_new_section
-
config_new_option
-
bar_new
-
2.2. Funkcja rejestrująca
Wszystkie skrypty WeeChat muszą się "zarejestrować" w WeeChat, musi to być pierwsza z funkcji WeeChat wywołana w skrypcie.
Prototyp:
Argumenty:
-
nazwa: string, wewnętrzna nazwa skryptu
-
autor: string, autor skryptu
-
wersja: string, wersja
-
licencja: string, licencja
-
opis: string, krótki opis skryptu
-
funkcja_wyłączająca: string, nazwa funkcji wywoływanej podczas wyładowania skryptu (może być pusty ciąg)
-
kodowanie: string, kodowane skryptu (jeśli skrypt jest napisany w UTF-8 można nie podawać tej wartości - UTF-8 to domyślne kodowanie)
Przykład dla skryptu w każdym z języków:
-
python:
-
perl:
-
ruby:
-
lua:
-
tcl:
-
guile (scheme):
2.3. Ładowanie skryptu
Zaleca się używanie wtyczki "script" do ładowania skryptów, na przykład:
/script load script.py
/script load script.pl
/script load script.rb
/script load script.lua
/script load script.tcl
/script load script.scm
Każdy język posiada również swoją własną komendę:
/python load python/skrypt.py
/perl load perl/skrypt.pl
/ruby load ruby/skrypt.rb
/lua load lua/skrypt.lua
/tcl load tcl/skrypt.tcl
/guile load guile/skrypt.scm
Możesz zrobić dowiązanie w katalogu język/autoload jeśli chcesz automatycznie ładować skrypt po uruchomieniu WeeChat.
Na przykład dla Pythona:
$ cd ~/.weechat/python/autoload
$ ln -s ../skrypt.py
Note
|
Podczas instalacji skryptu za pomocą /script install automatycznie tworzone jest
dowiązanie w katalogu autoload. |
3. Różnice pomiędzy API dla C
API skryptów jest prawie takie same jak API dla wtyczek pisanych w C. Możesz zajrzeć do Opisu API wtyczek WeeChat po więcej informacji na temat każdej z funkcji API: prototyp, argumenty, zwracane wartości, przykłady.
Ważne jest rozróżnienie wtyczki od skryptu: wtyczka jest plikiem binarnym
skompilowanym i załadowanym za pomocą komendy /plugin
, natomiast skrypt jest
plikiem tekstowym załadowanym przez wtyczkę jak python za pomocą komendy
/python
.
W momencie, kiedy Twój skrypt test.py wywołuje funkcję z API Weechat, wygląda to tak:
┌────────────────────────┐ ╔══════════════════╗
│ wtyczka python │ ║ WeeChat "core" ║
├──────────────┬─────────┤ ╟─────────┐ ║
test.py ─────► │ API skryptów │ C API │ ─────► ║ C API │ ║
└──────────────┴─────────┘ ╚═════════╧════════╝
Kiedy WeeChat odwołuje się do Twojego skryptu test.py wygląda to tak:
╔══════════════════╗ ┌────────────────────────┐
║ WeeChat "core" ║ │ wtyczka python │
║ ┌─────────╢ ├─────────┬──────────────┤
║ │ C API ║ ─────► │ C API │ API skryptów │ ─────► test.py
╚════════╧═════════╝ └─────────┴──────────────┘
3.1. Wskaźniki
Jak już zapewne wiecie nie ma prawdziwych "wskaźników" w skryptach. Dlatego kiedy funkcja API zwraca wskaźnik, jest on konwertowany na ciąg dla skryptu.
Na przykład, jeśli funkcja zwraca wskaźnik 0x1234ab56 skrypt otrzyma ciąg "0x1234ab56".
W sytuacji, kiedy funkcja API spodziewa się wskaźnika jako argumentu skrypt musi przekazać go jako ciąg. Wtyczki napisane w C przekonwertują go na prawdziwy wskaźnik, zanim wywołają funkcję z API C.
Dozwolone są puste ciągi lub "0x0", oznaczają NULL w C. Na przykład, aby wyświetlić dane w rdzennym buforze (główny bufor WeeChat):
Warning
|
W wielu funkcjach, z powodów wydajności, WeeChat nie sprawdza poprawności wskaźników. Do ciebie należy sprawdzenie poprawności przekazywanych wskaźników, w innym wypadku możesz zobaczyć ładny raport o błędzie ;) |
3.2. Callbacki
Prawie wszystkie callbacki muszą zwrócić WEECHAT_RC_OK lub WEECHAT_RC_ERROR (wyjątkiem jest callback modyfikujący, który zwraca ciąg).
Callbacki C używają argumentu "data", który jest wskaźnikiem. W API skryptów, "data" jest ciągiem o dowolnej wartości (nie jest wskaźnikiem).
Przykłady callbacków dla każdego języka:
-
python:
-
perl:
-
ruby:
-
lua:
-
tcl:
-
guile (scheme):
4. API skryptów
Więcej informacji o funkcjach w API, znajdziesz w Opisie API wtyczek WeeChat.
4.1. Fukcje
Lista funkcji w API skryptów:
Kategoria | Funkcje |
---|---|
ogólne |
register |
wtyczki |
plugin_get_name |
ciągi |
charset_set, iconv_to_internal, iconv_from_internal, gettext, ngettext, |
katalogi |
mkdir_home, mkdir, mkdir_parents |
przechowywane listy |
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 |
pliki konfiguracyjne |
config_new, config_new_section, config_search_section, config_new_option,
config_search_option, |
przypisania klawiszy |
key_bind, key_unbind |
wyświetlanie |
prefix, color, print (for python: prnt), print_date_tags (for python: prnt_date_tags), print_y (for python: prnt_y), log_print |
hooks |
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 |
bufory |
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 |
okna |
current_window, window_search_with_buffer, window_get_integer, window_get_string, window_get_pointer, window_set_title |
lista nicków |
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 |
paski |
bar_item_search, bar_item_new, bar_item_update, bar_item_remove, bar_search, bar_new, bar_set, bar_update, bar_remove |
komendy |
command |
informacje |
info_get, info_get_hashtable |
infolisty |
infolist_new, infolist_new_item, infolist_new_var_integer,
infolist_new_var_string, infolist_new_var_pointer, infolist_new_var_time, |
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 |
uaktualnienie |
upgrade_new, upgrade_write_object, upgrade_read, upgrade_close |
4.2. Stałe
Lista stałych w API skryptów:
Kategoria | Stałe |
---|---|
zwracane kody |
WEECHAT_RC_OK, WEECHAT_RC_OK_EAT, WEECHAT_RC_ERROR |
pliki konfiguracyjne |
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, |
posortowane listy |
WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING, WEECHAT_LIST_POS_END |
hotlisty |
WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT |
hook process |
WEECHAT_HOOK_PROCESS_RUNNING, WEECHAT_HOOK_PROCESS_ERROR |
hook connect |
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 signal |
WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT, WEECHAT_HOOK_SIGNAL_POINTER |
5. Częste zadania
Ten rozdział przedstawia część częstych zadań z przykładami. Użyto tu tylko część rzeczy dostępnych w API, dokładne informacje można znaleźć w Opisie API wtyczek WeeChat'.
5.1. Bufory
5.1.1. Wyświetlanie wiadomości
Pusty ciąg jest często używany podczas pracy z głównym buforem WeeChat. Dla pozostałych buforów należy podać wskaźnik (jako ciąg, zobacz pointers).
Przykłady:
Note
|
Funkcja drukująca nazywa się print w Perl/Ruby/Lua/Tcl i prnt w Pythonie. |
5.1.2. Wysyłanie tekstu do bufora
Możesz wysłać tekst lub komendę do bufora. Dokładnie tak jakby wpisać tekst w linii poleceń i wcisnąć [Enter].
Przykłady:
5.1.3. Tworzenie nowego buforu
Możesz stworzyć nowy bufor w skrypcie, następnie użyć go do wyświetlania wiadomości.
Dwa callbacki mogą zostać wywołane (są opcjonalne): jeden dla danych wejściowych
(kiedy wpiszesz tekst i naciśniesz [Enter] w buforze), drugi jest wywoływany
podczas zamykania bufora (na przykład przez /buffer close
).
Przykłady:
5.1.4. Właściwości buforów
Możesz odczytać właściwości buforów jako ciąg, liczbę lub wskaźnik.
Przykłady:
Możliwe jest dodanie, odczytanie lub kasowanie lokalnych zmiennych dla buforów:
Aby zobaczyć lokalne zmienne danego bufora, należy wykonać tą komendę w WeeChat:
/buffer localvar
5.2. Hooks
5.2.1. Dodanie nowej komendy
Aby dodać nową komendę należy użyć hook_command
. Można użyć własnego szablonu
dopełnień dla uzupełniania argumentów własnej komendy.
Przykład:
Następnie w WeeChat:
/help myfilter
/myfilter argumenty...
5.2.2. Dodanie timera
Do dodania timera służy hook_timer
.
Przykład:
5.2.3. Wykonuje proces w tle
Do wykonywania procesów w tle służy hook_process
. Twoje callbacki zostaną
wywołane, kiedy dane będą gotowe. Może zostać wywołane wiele razy.
Dla ostatniego wykonania Twojego callbacku rc jest ustawiane na 0, lub wartość dodatnią, jest to kod zwracany przez komendę.
Przykład:
5.2.4. Transfer URL
Nowe w wersji 0.3.7.
Aby pobrać URL (albo wysłać do URL), należy użyć funkcji hook_process
, lub
hook_process_hashtable
jeśli konieczne jest przekazanie parametrów.
Przykład transferu URL bez opcji: strona HTML jest otrzymywana jako "out" (standardowe wyjście procesu):
Tip
|
Wszystkie informacje o WeeChat dostępne są na stronie https://weechat.org/dev/info |
Przykładowy transfer URL z opcją: pobranie najnowszej wersji rozwojowej WeeChat do pliku /tmp/weechat-devel.tar.gz:
Więcej informacji o transferach URL i dostępnych opcjach dla funkcji
hook_process
oraz hook_process_hashtable
można znaleźć w Opisie API wtyczek.
5.3. Konfiguracja / opcje
5.3.1. Ustawianie opcji dla skryptu
Funkcja config_is_set_plugin
używana jest do sprawdzenia czy opcja jest ustawiona,
config_set_plugin
ustawia opcję.
Example:
5.3.2. Wykrywanie zmian
Do wykrywania zmian opcji skryptu służy hook_config
.
Przykład:
5.3.3. Odczyt opcji WeeChat
Funkcja config_get
zwraca wskaźnik do opcji. Następnie, w zależności od typu opcji,
należy wywołać config_string
, config_boolean
, config_integer
lub
config_color
.
5.4. IRC
5.4.1. Przechwytywanie wiadomości
Wtyczka IRC wysyła dwa sygnały dla otrzymanej wiadomości (xxx
jest wewnętrzną
nazwą serwera IRC, yyy
to komenda IRC jak JOIN, QUIT, PRIVMSG, 301, ..):
- xxxx,irc_in_yyy
-
sygnał wysłany przed przetworzeniem wiadomości
- xxx,irc_in2_yyy
-
sygnał wysłany po przetworzeniu wiadomości
5.4.2. Modyfikowanie wiadomości
Wtyczka IRC wysyła "modyfikator" nazwany "irc_in_xxx" ("xxx" to komenda IRC) dla otrzymanej wiadomości, żeby można było ją zmodyfikować.
Warning
|
Zniekształcone wiadomości mogą uszkodzić WeeChat, lub spowodować wiele problemów! |
5.4.3. Przetwarzanie wiadomości
Nowe w wersji 0.3.4.
Można przetwarzać wiadomości IRC za pomocą info_hashtable zwanej "irc_message_parse".
5.5. Informacje
5.5.1. Wersja WeeChat
Najprostszym sposobem na sprawdzenie wersji to pozyskanie "version_number" i wykonanie porównania między liczbą całkowitą a heksadecymalnym numerem wersji.
Przykład:
Note
|
Wersje ≤ 0.3.1.1 zwracają pusty ciąg dla info_get("version_number") należy sprawdzić, czy zwracana wartość nie jest pusta. |
Aby otrzymać ciąg z numerem wersji:
5.5.2. Inne informacje
5.6. Infolisty
5.6.1. Odczytanie infolisty
Można odczytać infolisty wbudowane w WeeChat lub inne wtyczki.
Przykład:
Important
|
Nie zapomnij wywołać infolist_free , aby zwolnić pamięć użyta przez infolistę,
ponieważ WeeChat nie zwolni automatycznie tej pamięci. |