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ą nazwane prnt* 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,
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

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

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

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

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.