Превод:
-
Иван Пешић (<ivan.pesic@gmail.com>), 2021.
Ово упутство описује WeeChat чет клијент и део је програма WeeChat.
Последња верзија овог документа се налази на овој страници ↗.
1. Увод
WeeChat (Wee Enhanced Environment for Chat) је бесплатни чет клијент, једноставан и брз, дизајниран за многе оперативне системе.
Ово упутство документује начин писања скрипти за програм WeeChat употребом једног од подржаних скрипт језика:
-
Python
-
Perl
-
Ruby
-
Lua
-
Tcl
-
Guile (Scheme)
-
JavaScript
-
PHP
Almost all examples in this doc are written in Python, but API is the same for other languages. |
2. Скрипте у програму WeeChat
2.1. Архитектура програма WeeChat
Програм WeeChat се извршава у једној нити, па се то применњује и на скрипте.
Кôд скрипте се извршава:
-
када се скрипта учита: типично позивом функција за регистрацију
-
када програм WeeChat позове функцију повратног позива куке (погледајте поглавље Куке).
Док се кôд скрипте извршава, програм WeeChat чека на крај извршавања пре него што настави. Тако да скрипте НЕ СМЕЈУ да извршавају блокирајуће операције као што су мрежни позиви без употребе одређених API функција као што је hook_process
.
Скрипта НИКАДА не сме да се рачва или да креира нити без употребе одговарајуће API функције, то може да сруши програм WeeChat. Ако нешто мора да се извршава у позадини, употребите функцију hook_process . Погледајте пример у поглављу Покретање процеса у позадини као и документацију функције hook_process у WeeChat референтном приручнику API додатака ↗.
|
2.2. Језичке специфичности
Python
Модул
Програм WeeChat дефинише weechat
модул који мора да се увезе командом import weechat
.
Python стаб за WeeChat API је соступан у репозиторијуму: weechat.pyi ↗.
Функције
Функције се позивају са weechat.xxx(арг1, арг2, ...)
.
Функције print*
се у језику python зову prnt*
(јер је print
била резервисана реч у Python 2).
Стрингови који се примају у функцијама повратног позива
У Python 3 и у програму WeeChat верзије ≥ 2.7, стрингови који се примају у функцијама повратног позива имају тип str
ако стринг садржи важеће UTF-8 податке (што је најчешћи случај), или bytes
ако стринг није важећи UTF-8. Тако да би функција повратног позива морала да води рачуна о овом типу у случају да је могућ пријем неважећег UTF-8 садржаја.
Неважећи UTF-8 подаци могу да се приме у следећим случајевима, тако да функције повратног позива могу да приме стринг типа str
или bytes
(ова листа није потпуна):
API фунцкија | Аргументи | Примери | Опис |
---|---|---|---|
|
|
|
Порука која се прими у IRC додатку, пре него што се декодира у UTF-8 (користи
се интерно). |
|
|
|
Порука коју шаље IRC додатак, након што се кодира у |
|
|
|
Излаз команде који се шаље функцији повратног позива може да садржи неважеће UTF-8 податке. |
Ruby
Функције
Функције се позивају са Weechat.xxx(арг1, арг2, ...)
.
Услед ограничења језика Ruby (функција може да има максимално 15 аргумената), функција Weechat.config_new_option
прихвата функције повратног позива у низу од 6 стрингова (3 повратна позива + 3 стринга са подацима), тако да позив ове функције изгледа овако:
Weechat.config_new_option(config, section, "name", "string", "description of option", "", 0, 0,
"value", "value", 0, ["check_cb", "", "change_cb", "", "delete_cb", ""])
И функција Weechat.bar_new
прима боје у низу од 4 стринга (color_fg, color_delim, color_bg, color_bg_inactive), тако да позив ове функције изгледа овако:
Weechat.bar_new("name", "off", "0", "window", "", "left", "vertical", "vertical", "0", "0",
["default", "default", "default", "default"], "0", "items")
Tcl
Null вредности
Пошто Tcl има само стринг типове, не постоји могућност да се проследи аргумент
null типа када функција прихвата null вредности или да прихвати као аргумент у
функцији повратног позива. Да би се решио овај проблем WeeChat API дефинише
константу $::weechat::WEECHAT_NULL
која има улогу null вредности. Ова константа
се дефинипе као \uFFFF\uFFFF\uFFFFWEECHAT_NULL\uFFFF\uFFFF\uFFFF
, тако да је
мала вероватноћа да се појави без намере.
Ову константу можете да проследите када функција као аргумент прихвата null и вретиће вам се као вредност аргумента у функцији повратног позива ако је вредност аргумента null. Да бисте видели које функције прихватају null вредности и прослеђују null вредности функцијама повратног позива, погледајте Python прототипе у API референтном приручнику WeeChat додатака ↗.
2.3. Функција за регистрацију
Све WeeChat скрипте морају да се „пријаве” програму WeeChat, и то мора да буде прва WeeChat функција која се позива у скрипти.
Прототип (Python):
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...
Аргументи:
-
име: стринг, интерно име скрипте
-
аутор: стринг, име аутора
-
верзија: стринг, верзија скрипте
-
лиценца: стринг, лиценца скрипте
-
опис: стринг, кратак опис скрипте
-
искључ_функција: стринг, име функције која се позива када се скрипте уклања из меморије (може бити и празан стринг)
-
скуп_кар: стринг, скуп карактера скрипте (ако је ваша скрипта UTF-8, овде можете да користите празну вредности, јер је UTF-8 подразумевани скуп карактера)
Пример скрипте, за сваки језик:
-
Python:
import weechat
weechat.register("test_python", "FlashCode", "1.0", "GPL3", "Test script", "", "")
weechat.prnt("", "Поздрав од python скрипте!")
-
Perl:
weechat::register("test_perl", "FlashCode", "1.0", "GPL3", "Test script", "", "");
weechat::print("", "Поздрав од perl скрипте!");
-
Ruby:
def weechat_init
Weechat.register("test_ruby", "FlashCode", "1.0", "GPL3", "Test script", "", "")
Weechat.print("", "Поздрав од ruby скрипте!")
return Weechat::WEECHAT_RC_OK
end
-
Lua:
weechat.register("test_lua", "FlashCode", "1.0", "GPL3", "Test script", "", "")
weechat.print("", "Поздрав од lua скрипте!")
-
Tcl:
weechat::register "test_tcl" "FlashCode" "1.0" "GPL3" "Test script" "" ""
weechat::print "" "Поздрав од tcl скрипте!"
-
Guile (Scheme):
(weechat:register "test_scheme" "FlashCode" "1.0" "GPL3" "Test script" "" "")
(weechat:print "" "Поздрав од scheme скрипте!")
-
JavaScript:
weechat.register("test_js", "FlashCode", "1.0", "GPL3", "Test script", "", "");
weechat.print("", "Поздрав од javascript скрипте!");
-
PHP:
weechat_register('test_php', 'FlashCode', '1.0', 'GPL3', 'Test script', '', '');
weechat_print('', 'Поздрав од PHP скрипте!');
2.4. Учитавање скрипте
За учитавање скрипти се препоручује употреба додатка „script”, на пример:
/script load script.py /script load script.pl /script load script.rb /script load script.lua /script load script.tcl /script load script.scm /script load script.js /script load script.php
Сваки језик има и своју команду:
/python load script.py /perl load script.pl /ruby load script.rb /lua load script.lua /tcl load script.tcl /guile load script.scm /javascript load script.js /php load script.php
Можете направити линк у директоријуму language/autoload ако желите да се скрипта аутоматски учитава када се програм WeeChat покреће.
На пример, са језиком Python:
cd ~/.local/share/weechat/python/autoload
ln -s ../script.py
Када се скрипта инсталира командом /script install , линк у autoload директоријуму се аутоматски креира.
|
3. Разлике у односу на C API
API скриптовања је скоро у потпуности исти као и API C додатака. Можете да погледате следећи линк: weechat_plugin_api.sr.html[WeeChat референца API додатака] у вези детаља сваке функције у API: прототип, аргументи, повратне вредности, примери.
Важно је да се направи разлика између додатка и скрипте: додатак је бинарни фајл који се компајлира и учитава командом /plugin
, док је скрипта текст фајл који се учитава додатком као што је python командом /python
.
Када ваша скрипта test.py позива WeeChat API функцију, путања је оваква:
┌──────────────────────┐ ╔══════════════════╗ │ python додатак │ ║ WeeChat „језгро” ║ ├────────────┬─────────┤ ╟─────────┐ ║ test.py ─────► │ script API │ C API │ ─────► ║ C API │ ║ └────────────┴─────────┘ ╚═════════╧════════╝
Када WeeChat позове функцију повратног позива у вашој скрипти test.py, путања бити обрнута у односу на претходну путању:
╔══════════════════╗ ┌──────────────────────┐ ║ WeeChat „језгро” ║ │ python додатак │ ║ ┌─────────╢ ├─────────┬────────────┤ ║ │ C API ║ ─────► │ C API │ script API │ ─────► test.py ╚════════╧═════════╝ └─────────┴────────────┘
3.1. Показивачи
Као што вероватно већ знате, у скриптама нема правих „показивача”. Тако да када API функције врате показивач, он се за потребе скрипте конвертује у стринг.
На пример, ако функција врати показивач 0x1234ab56, скрипта ће примити стринг „0x1234ab56”.
А када API функција очекује показивач у аргументима, скрипта мора да проследи ту стринг вредност. C додатак ће да га конвертује у реални показивач пре него што позове C API функцију.
Дозвољени су празни стрингови или „0x0”. На пример, ако желите да испишете податке у бафер језгра (главни WeeChat бафер), можете урадити следеће:
weechat.prnt("", "здраво!")
Из разлога брзине, програм WeeChat у многим функцијама не проверава исправност вашег показивача. Ваш посао је да проверите да ли прослеђујете важећи показивач, у супротном бисте могли видети фин извештај о краху ;) |
3.2. Функције повратног позива
Скоро све WeeChat функције повратног позива морају да врате WEECHAT_RC_OK или WEECHAT_RC_ERROR (изузетак од овог правила је функција повратног позива модификатора, она враћа стринг).
C функције повратног позива користе „callback_pointer” и „callback_data” аргументе, и то су показивачи. У API скриптовања постоји само „callback_data” (или „data”), и то је стринг, а не показивач.
Пример функције повратног позива, за сваки језик:
-
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:
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:
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:
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:
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):
(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")
-
JavaScript:
function timer_cb(data, remaining_calls) {
weechat.print("", "timer! data=" + data);
return weechat.WEECHAT_RC_OK;
}
weechat.hook_timer(1000, 0, 1, "timer_cb", "test");
-
PHP:
$timer_cb = function ($data, $remaining_calls) {
weechat_print('', 'timer! data=' . $data);
return WEECHAT_RC_OK;
};
weechat_hook_timer(1000, 0, 1, $timer_cb, 'test');
4. API скриптовања
За више информација о функцијама које постоје у API, молимо вас да прочитате WeeChat референтни приручник API додатака ↗.
4.1. Функције
Листа функција у API скриптовања:
-
register
-
plugin_get_name
-
charset_set
-
iconv_to_internal
-
iconv_from_internal
-
gettext
-
ngettext
-
strlen_screen
-
string_match
-
string_match_list
-
string_has_highlight
-
string_has_highlight_regex
-
string_mask_to_regex
-
string_format_size
-
string_parse_size
-
string_color_code_size
-
string_remove_color
-
string_is_command_char
-
string_input_for_buffer
-
string_eval_expression
-
string_eval_path_home
-
mkdir_home
-
mkdir
-
mkdir_parents
-
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
-
config_new
-
config_set_version
-
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_get_string
-
config_option_get_pointer
-
config_option_is_null
-
config_option_default_is_null
-
config_boolean
-
config_boolean_default
-
config_boolean_inherited
-
config_integer
-
config_integer_default
-
config_integer_inherited
-
config_string
-
config_string_default
-
config_string_inherited
-
config_color
-
config_color_default
-
config_color_inherited
-
config_enum
-
config_enum_default
-
config_enum_inherited
-
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
-
key_bind
-
key_unbind
-
prefix
-
color
-
prnt
-
prnt_date_tags
-
prnt_datetime_tags
-
prnt_y
-
prnt_y_date_tags
-
prnt_y_datetime_tags
-
log_print
-
hook_command
-
hook_completion
-
hook_completion_get_string
-
hook_completion_list_add
-
hook_command_run
-
hook_timer
-
hook_fd
-
hook_process
-
hook_process_hashtable
-
hook_url
-
hook_connect
-
hook_line
-
hook_print
-
hook_signal
-
hook_signal_send
-
hook_hsignal
-
hook_hsignal_send
-
hook_config
-
hook_modifier
-
hook_modifier_exec
-
hook_info
-
hook_info_hashtable
-
hook_infolist
-
hook_focus
-
hook_set
-
unhook
-
unhook_all
-
buffer_new
-
buffer_new_props
-
buffer_search
-
buffer_search_main
-
current_buffer
-
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
-
line_search_by_id
-
current_window
-
window_search_with_buffer
-
window_get_integer
-
window_get_string
-
window_get_pointer
-
window_set_title
-
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
-
bar_item_search
-
bar_item_new
-
bar_item_update
-
bar_item_remove
-
bar_search
-
bar_new
-
bar_set
-
bar_update
-
bar_remove
-
command
-
command_options
-
completion_new
-
completion_search
-
completion_get_string
-
completion_list_add
-
completion_free
-
info_get
-
info_get_hashtable
-
infolist_new
-
infolist_new_item
-
infolist_new_var_integer
-
infolist_new_var_string
-
infolist_new_var_pointer
-
infolist_new_var_time
-
infolist_search_var
-
infolist_get
-
infolist_next
-
infolist_prev
-
infolist_reset_item_cursor
-
infolist_fields
-
infolist_integer
-
infolist_string
-
infolist_pointer
-
infolist_time
-
infolist_free
-
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_longlong
-
hdata_string
-
hdata_pointer
-
hdata_time
-
hdata_hashtable
-
hdata_compare
-
hdata_update
-
hdata_get_string
-
upgrade_new
-
upgrade_write_object
-
upgrade_read
-
upgrade_close
4.2. Константе
Листа константи у API скриптовања:
Константа | Тип | Вредност |
---|---|---|
WEECHAT_RC_OK |
целобројна |
|
WEECHAT_RC_OK_EAT |
целобројна |
|
WEECHAT_RC_ERROR |
целобројна |
|
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 |
целобројна |
|
WEECHAT_LIST_POS_SORT |
стринг |
|
WEECHAT_LIST_POS_BEGINNING |
стринг |
|
WEECHAT_LIST_POS_END |
стринг |
|
WEECHAT_HOTLIST_LOW |
стринг |
|
WEECHAT_HOTLIST_MESSAGE |
стринг |
|
WEECHAT_HOTLIST_PRIVATE |
стринг |
|
WEECHAT_HOTLIST_HIGHLIGHT |
стринг |
|
WEECHAT_HOOK_PROCESS_RUNNING |
целобројна |
|
WEECHAT_HOOK_PROCESS_ERROR |
целобројна |
|
WEECHAT_HOOK_CONNECT_IPV6_DISABLE |
целобројна |
|
WEECHAT_HOOK_CONNECT_IPV6_AUTO |
целобројна |
|
WEECHAT_HOOK_CONNECT_IPV6_FORCE |
целобројна |
|
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 |
целобројна |
|
WEECHAT_HOOK_SIGNAL_STRING |
стринг |
|
WEECHAT_HOOK_SIGNAL_INT |
стринг |
|
WEECHAT_HOOK_SIGNAL_POINTER |
стринг |
|
5. Уобичајени задаци
Ово поглавље приказује неке уобичајене задатке, уз примере. Овде се користе само делимичне ствари из API, за потпуно упутство, погледајте WeeChat референтни приручник API додатака ↗.
5.1. Бафери
Приказ порука
Празан стринг се често користи за рад са WeeChat бафером језгра. За остале бафере, морате навести показивач (као стринг, погледајте показивачи).
Примери:
# приказ „здраво” у баферу језгра
weechat.prnt("", "здраво")
# приказ „здраво” у баферу језгра, али без уписа у лог фајл
# (само у верзијама ≥ 0.3.3)
weechat.prnt_date_tags("", 0, "no_log", "здраво")
# приказ префикса „==>” и поруке „здраво” у текућем баферу
# (префикс и порука су раздвојени таб карактером)
weechat.prnt(weechat.current_buffer(), "==>\tздраво")
# приказ поруке о грешки у баферу језгра (са префиксом грешка)
weechat.prnt("", "%sпогрешни аргументи" % weechat.prefix("грешка"))
# приказ поруке са бојом у баферу језгра
weechat.prnt("", "текст %sжуто на плавом" % weechat.color("yellow,blue"))
# претрага бафера и приказ поруке
# (пуно име бафера је додатак.име, на пример: „irc.libera.#weechat”)
buffer = weechat.buffer_search("irc", "libera.#weechat")
weechat.prnt(buffer, "порука на #weechat каналу")
# још једно решење за проналажење IRC бафера (боље)
# (приметите да су сервер и канал раздвојени запетом)
buffer = weechat.info_get("irc_buffer", "libera,#weechat")
weechat.prnt(buffer, "порука на #weechat каналу")
Print функција се назива prnt у Python, а print у осталим језицима.
|
Слање текста у бафер
Текст или команду можете да пошаљете у бафер. Ово је потпуно исто као да откуцате текст на командној линији и притиснете [Ентер].
Примери:
# извршавање команде „/help” у текућем баферу (резултат иде у бафер језгра)
weechat.command("", "/help")
# слање „hello” на #weechat IRC канал (корисници на каналу ће видети поруку)
buffer = weechat.info_get("irc_buffer", "libera,#weechat")
weechat.command(buffer, "hello")
Креирање новог бафера
У својој скрипти можете креирати нови бафер, па да га затим користите за приказ порука.
Могу да се позову две функције повратног позива (нису обавезне): једна за улазне податке (када откуцате неки текст и притиснете [Ентер] у баферу), друга се позива када се бафер затвори (на пример, са /buffer close
).
Пример:
# функција повратног позива за податке примљене са улаза
def buffer_input_cb(data, buffer, input_data):
# ...
return weechat.WEECHAT_RC_OK
# функција повратног позива која се позива када се бафер затвори
def buffer_close_cb(data, buffer):
# ...
return weechat.WEECHAT_RC_OK
# креирање бафера
buffer = weechat.buffer_new("mybuffer", "buffer_input_cb", "", "buffer_close_cb", "")
# постављање наслова
weechat.buffer_set(buffer, "title", "Ово је наслов мог бафера.")
# искључивање логовања, постављањем локалне променљиве „no_log” на „1”
weechat.buffer_set(buffer, "localvar_set_no_log", "1")
Особине бафера
Особине бафера можете да читате као стринг, цели број или показивач.
Примери:
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")
Могyће је додавање, читање или брисање локалних променњивих у баферу:
# додавање локалне променљиве
weechat.buffer_set(buffer, "localvar_set_myvar", "my_value")
# читање локалне променљиве
myvar = weechat.buffer_get_string(buffer, "localvar_myvar")
# брисање локалне променљиве
weechat.buffer_set(buffer, "localvar_del_myvar", "")
Ако желите да видите локалне променљиве у баферу, извршите следећу комаду у програму WeeChat:
/buffer listvar
5.2. Куке
Додавање нове команде
Нову команду додајете са hook_command
. Можете да употребите шаблон прилагођеног довршавања за довршавање аргумената ваше команде.
Пример:
def my_command_cb(data, buffer, args):
# ...
return weechat.WEECHAT_RC_OK
hook = weechat.hook_command("мојфилтер", "опис за мојфилтер",
"[list] | [enable|disable|toggle [име]] | [add име plugin.buffer tags regex] | [del име|-all]",
"опис аргумената...",
"list"
" || enable %(filters_names)"
" || disable %(filters_names)"
" || toggle %(filters_names)"
" || add %(filters_names) %(buffers_plugins_names)|*"
" || del %(filters_names)|-all",
"my_command_cb", "")
Па затим у програму WeeChat:
/help мојфилтер /мојфилтер аргументи...
Додавање тајмера
Тајмер се додаје са hook_timer
.
Пример:
def timer_cb(data, remaining_calls):
# ...
return weechat.WEECHAT_RC_OK
# тајмер се позива сваког минута када су секунде 00
weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "")
Покретање процеса у позадини
Процес можете да покренете у позадини са hook_process
. Ваша функција повратног позива ће се позвати онда када подаци буду спремни. Може да се позива више пута.
У последњем позиву ваше функције повратног позива, return_code се поставља на 0 или позитивну вредност, то је повратни кôд команде.
Пример:
def my_process_cb(data, command, return_code, out, err):
if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
weechat.prnt("", "Error with command '%s'" % command)
return weechat.WEECHAT_RC_OK
if return_code >= 0:
weechat.prnt("", "return_code = %d" % return_code)
if out:
weechat.prnt("", "stdout: %s" % out)
if err:
weechat.prnt("", "stderr: %s" % err)
return weechat.WEECHAT_RC_OK
weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")
Уместо спољне команде, такође можете директно да позовете скрипт функцију која ради нешто што блокира:
def get_status(data):
# do something blocking...
# ...
return "this is the result"
def my_process_cb(data, command, return_code, out, err):
if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
weechat.prnt("", "Error with command '%s'" % command)
return weechat.WEECHAT_RC_OK
if return_code >= 0:
weechat.prnt("", "return_code = %d" % return_code)
if out:
weechat.prnt("", "stdout: %s" % out)
if err:
weechat.prnt("", "stderr: %s" % err)
return weechat.WEECHAT_RC_OK
hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
URL пренос
Ново у верзији 0.3.7.
Ако желите да преузмете URL (или пошаљете на URL), морате да употребите функцију hook_process
, или hook_process_hashtable
ако је потребно да поставите опције URL преноса.
Пример URL преноса без опције: HTML страница ће се примити као „out” у функцији повратног позива (стандардни излаз процеса):
# Приказује последњу стабилну верзију WeeChat.
weechat_latest_version = ""
def weechat_process_cb(data, command, return_code, out, err):
global weechat_latest_version
if out:
weechat_latest_version += out
if return_code >= 0:
weechat.prnt("", "Последња WeeChat верзија: %s" % weechat_latest_version)
return weechat.WEECHAT_RC_OK
weechat.hook_process("url:https://weechat.org/dev/info/stable/",
30 * 1000, "weechat_process_cb", "")
Све информације у вези програма WeeChat се налазе на овој страници ↗. |
Пример URL преноса са опцијом: преузимање најновијег WeeChat развојног пакета у фајл /tmp/weechat-devel.tar.gz:
def my_process_cb(data, command, return_code, out, err):
if return_code >= 0:
weechat.prnt("", "Крај преноса (return code = %d)" % return_code)
return weechat.WEECHAT_RC_OK
weechat.hook_process_hashtable("url:https://weechat.org/files/src/weechat-devel.tar.gz",
{"file_out": "/tmp/weechat-devel.tar.gz"},
30 * 1000, "my_process_cb", "")
За више информација у вези URL преноса, као и за доступне опције, погледајте функције hook_process
и hook_process_hashtable
у WeeChat референтни приручник API додатака ↗.
5.3. Конфигурација / опције
Постављање опција за скрипту
Функција config_is_set_plugin
се користи за проверу да ли је опција постављена или не, а config_set_plugin
за постављање опције.
Пример:
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)
Откривање измена
Ако желите обавештење када корисник измени неке опције скрипте, морате да користите hook_config
.
Пример:
SCRIPT_NAME = "myscript"
# ...
def config_cb(data, option, value):
"""Повратни позив се позива када се опција скрипте измени."""
# на пример, читање свих опција у променљиве скрипте...
# ...
return weechat.WEECHAT_RC_OK
# ...
weechat.hook_config("plugins.var.python." + SCRIPT_NAME + ".*", "config_cb", "")
# за остале језике, измените „python” именом свој језика (perl/ruby/lua/tcl/guile/javascript)
Читање опција програма WeeChat
Фунцкија config_get
враћа показивач на опцију. Затим, у зависности од типа опције, морате да позовете config_string
, config_boolean
, config_integer
или config_color
.
# string
weechat.prnt("", "вредност опције weechat.look.item_time_format је: %s"
% (weechat.config_string(weechat.config_get("weechat.look.item_time_format"))))
# boolean
weechat.prnt("", "вредност опције weechat.look.day_change је: %d"
% (weechat.config_boolean(weechat.config_get("weechat.look.day_change"))))
# integer
weechat.prnt("", "вредност опције weechat.look.scroll_page_percent је: %d"
% (weechat.config_integer(weechat.config_get("weechat.look.scroll_page_percent"))))
# color
weechat.prnt("", "вредност опције weechat.color.chat_delimiters је: %s"
% (weechat.config_color(weechat.config_get("weechat.color.chat_delimiters"))))
5.4. IRC
Хватање порука
IRC додатак шаље четири сигнала за примљену поруку (xxx
је IRC интерно име сервера, yyy
је IRC име команде као што је JOIN, QUIT, PRIVMSG, 301, …):
- xxx,irc_in_yyy
-
сигнал који се шаље пре обраде поруке, само ако се порука не игнорише
- xxx,irc_in2_yyy
-
сигнал који се шаље након обраде поруке, само ако се порука не игнорише
- xxx,irc_raw_in_yyy
-
сигнал који се шаље пре обраде поруке, чак и ако се порука игнорише
- xxx,irc_raw_in2_yyy
-
сигнал који се шаље након обраде поруке, чак и ако се порука игнорише
def join_cb(data, signal, signal_data):
# сигнал је на пример: „libera,irc_in2_join”
# signal_data је IRC порука, на пример: „:nick!user@host JOIN :#channel”
server = signal.split(",")[0]
msg = weechat.info_get_hashtable("irc_message_parse", {"message": signal_data})
buffer = weechat.info_get("irc_buffer", "%s,%s" % (server, msg["channel"]))
if buffer:
weechat.prnt(buffer, "%s (%s) се придружио овом каналу!" % (msg["nick"], msg["host"]))
return weechat.WEECHAT_RC_OK
# овде је корисни да се као сервер употреби „*”, како би се хватале JOIN поруке
# на свим IRC серверима
weechat.hook_signal("*,irc_in2_join", "join_cb", "")
Измена порука
IRC додатак шаље два „модификатора” за сваку примљену поруку („xxx” је IRC команда), тако да можете да је измените:
- irc_in_xxx
-
модификатор који се шаље пре декодирања у скуп карактера: користите уз опрез, стринг може да садржи неважеће UTF-8 податке; користите само за сирове операције над поруком
- irc_in2_xxx
-
модификатор који се шаље након декодирања у скуп карактера, тако да је примљени стринг увек важећи UTF-8 (препоручује се)
def modifier_cb(data, modifier, modifier_data, string):
# у све примљене поруке се додаје име сервера
# (OK ово и није баш корисно, али то је само пример!)
return "%s %s" % (string, modifier_data)
weechat.hook_modifier("irc_in2_privmsg", "modifier_cb", "")
Неправилно формирана порука би могла да сруши програм WeeChat или да изазове озбиљне проблеме! |
Парсирање поруке
Ново у верзији 0.3.4.
IRC поруку можете да парсирате са info_hashtable под именом „irc_message_parse”.
Резултат је хеш табела са следећим кључевима (вредности за пример су изграђене из следеће поруке: @time=2015-06-27T16:40:35.000Z :nick!user@host PRIVMSG #weechat :здраво!
):
Кључ | Од WeeChat (1) | Опис | Пример |
---|---|---|---|
tags |
0.4.0 |
Ознаке у поруци (може бити празно). |
|
tag_xxx |
3.3 |
Неозначена вредност ознаке "xxx" (један кључ по ознаци). |
|
message_without_tags |
0.4.0 |
Порука без ознака (иста као оригинална ако нема ознака у њој). |
|
nick |
0.3.4 |
Надимак порекла. |
|
user |
2.7 |
Корисник порекла. |
|
host |
0.3.4 |
Хост порекла (укључујући и надимак). |
|
command |
0.3.4 |
Команда (PRIVMSG, NOTICE, …). |
|
channel |
0.3.4 |
Циљни канал. |
|
arguments |
0.3.4 |
Аргументи команде (укључујући и канал). |
|
text |
1.3 |
Текст (на пример, корисникова порука). |
|
paramN |
3.4 |
Параметар команде (од 1 до N). |
|
num_params |
3.4 |
Број параметара команде. |
|
pos_command |
1.3 |
Индекс command у поруци („-1” ако се command не пронађе). |
|
pos_arguments |
1.3 |
Индекс arguments у поруци („-1” ако се arguments не пронађе). |
|
pos_channel |
1.3 |
Индекс channel у поруци („-1” ако се channel не пронађе). |
|
pos_text |
1.3 |
Индекс text у поруци („-1” ако се text не пронађе). |
|
(1) Овај кључ је уведен у наведеној верзији програма WeeChat |
dict = weechat.info_get_hashtable(
"irc_message_parse",
{"message": "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :здраво!"})
# dict == {
# "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 :здраво!",
# "nick": "nick",
# "user": "user",
# "host": "nick!user@host",
# "command": "PRIVMSG",
# "channel": "#weechat",
# "arguments": "#weechat :здраво!",
# "text": "hello!",
# "param1": "#weechat",
# "param2": "hello!",
# "num_params": "2",
# "pos_command": "65",
# "pos_arguments": "73",
# "pos_channel": "73",
# "pos_text": "83",
# }
5.5. Информације
Верзија програма WeeChat
Најбољи начин да се провери верзија је да се затражи „version_number”, па да се уради целобројно поређење са хексадецималним бројем верзије.
Пример:
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030200:
weechat.prnt("", "Ово је WeeChat 0.3.2 или новији")
else:
weechat.prnt("", "Ово је WeeChat 0.3.1 или старији")
Верзије ≤ 0.3.1.1 враћају празан стринг за info_get("version_number") тако да морате проверити да враћена вредност није празна. |
Да бисте добили верзију као стринг:
# ово ће да испише на пример „Верзија 0.3.2”
weechat.prnt("", "Верзија %s" % weechat.info_get("version", ""))
5.6. Инфолисте
Читање инфолисте
Можете да читате инфолисту коју изгради WeeChat или остали додаци.
Пример:
# читање infolist „buffer”, како би се добила листа бафера
infolist = weechat.infolist_get("buffer", "", "")
if infolist:
while weechat.infolist_next(infolist):
name = weechat.infolist_string(infolist, "name")
weechat.prnt("", "бафер: %s" % name)
weechat.infolist_free(infolist)
Не заборавите да позовете infolist_free како бисте ослободите меморију коју користи infolist, јер програм WeeChat неће аутоматски ослободити меморију.
|