Превод:

Ово упутство описује WeeChat чет клијент и део је програма WeeChat.

Последња верзија овог документа може да се нађе на следећој страници: https://weechat.org/doc

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. Језичке специфичности

2.2.1. 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 фунцкија Аргументи Примери Опис

hook_modifier

irc_in_yyy

irc_in_privmsg
irc_in_notice

Порука која се прими у IRC додатку, пре него што се декодира у UTF-8 (користи се интерно).

Препоручује се да се уместо ње користи модификатор irc_in2_yyy, примљени стринг је увек валидан UTF-8.
Погледајте функцију hook_modifier у WeeChat референтном приручнику API додатака.

hook_signal

xxx,irc_out_yyy
xxx,irc_outtags_yyy

*,irc_out_privmsg
*,irc_out_notice
*,irc_outtags_privmsg
*,irc_outtags_notice

Порука коју шаље IRC додатак, након што се кодира у encode скуп карактера који је дефинисао корисник (у случају да се разликује од подразумеваног UTF-8).

Препоручује се да се уместо њега користи сигнал xxx,irc_out1_yyy, стринг који се прима је увек валидан UTF-8.
Погледајте функцију hook_signal у WeeChat референтном приручнику API додатака.

hook_process
hook_process_hashtable

-

-

Излаз команде који се шаље функцији повратног позива може да садржи неважеће UTF-8 податке.

У Python 2, који је сад превазиђен и више не би требало да се употребљава, стрингови који се шаљу функцијама повратног позива су увек били типа str, и у случајевима који су поменути изнад, могли су да садрже неважеће UTF-8 податке.

2.2.2. Perl

Функције

Функције се позивају са weechat::xxx(арг1, арг2, ...);.

2.2.3. Ruby

Иницијализација

Морате да дефинишете weechat_init и да у њој позовете register.

Функције

Функције се позивају са 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")

2.2.4. Lua

Функције

Функције се позивају са weechat.xxx(арг1, арг2, ...).

2.2.5. Tcl

Функције

Функције се позивају са weechat::xxx арг1 арг2 ....

2.2.6. Guile (Scheme)

Функције

Функције се позивају са (weechat:xxx арг1 арг2 ...).

Следеће функције узимају једну листу аргумената (уместо више аргумената као код осталих функција), јер број аргумената прелази дозвољен максимални број аргумената у језику Guile:

  • config_new_section

  • config_new_option

  • bar_new

2.2.7. JavaScript

Функције

Функције се позивају са weechat.xxx(арг1, арг2, ...);.

2.2.8. PHP

Функције

Функције се позивају са weechat_xxx(арг1, арг2, ...);.

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

тастерске пречице

key_bind
key_unbind

приказ

prefix
color
print (за python: prnt)
print_date_tags (за python: prnt_date_tags)
print_y (за python: prnt_y)
log_print

куке

hook_command
hook_command_run
hook_timer
hook_fd
hook_process
hook_process_hashtable
hook_connect
hook_line
hook_print
hook_signal
hook_signal_send
hook_hsignal
hook_hsignal_send
hook_config
hook_completion
hook_modifier
hook_modifier_exec
hook_info
hook_info_hashtable
hook_infolist
hook_focus
hook_set
unhook
unhook_all

бафери

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

прозори

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

infos

info_get
info_get_hashtable

infolists

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_search_var
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_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 (стринг)

кука process

WEECHAT_HOOK_PROCESS_RUNNING (цео број)
WEECHAT_HOOK_PROCESS_ERROR (цео број)

кука 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 (цео број)

кука signal

WEECHAT_HOOK_SIGNAL_STRING (стринг)
WEECHAT_HOOK_SIGNAL_INT (стринг)
WEECHAT_HOOK_SIGNAL_POINTER (стринг)

5. Уобичајени задаци

Ово поглавље приказује неке уобичајене задатке, уз примере. Овде се користе само делимичне ствари из API, за потпуно упутство, погледајте WeeChat референтни приручник API додатака.

5.1. Бафери

5.1.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 у осталим језицима.

5.1.2. Слање текста у бафер

Текст или команду можете да пошаљете у бафер. Ово је потпуно исто као да откуцате текст на командној линији и притиснете [Ентер].

Примери:

# извршавање команде „/help” у текућем баферу (резултат иде у бафер језгра)
weechat.command("", "/help")

# слање „hello” на #weechat IRC канал (корисници на каналу ће видети поруку)
buffer = weechat.info_get("irc_buffer", "libera,#weechat")
weechat.command(buffer, "hello")

5.1.3. Креирање новог бафера

У својој скрипти можете креирати нови бафер, па да га затим користите за приказ порука.

Могу да се позову две функције повратног позива (нису обавезне): једна за улазне податке (када откуцате неки текст и притиснете [Ентер] у баферу), друга се позива када се бафер затвори (на пример, са /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")

5.1.4. Особине бафера

Особине бафера можете да читате као стринг, цели број или показивач.

Примери:

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. Куке

5.2.1. Додавање нове команде

Нову команду додајете са 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 мојфилтер

/мојфилтер аргументи...

5.2.2. Додавање тајмера

Тајмер се додаје са hook_timer.

Пример:

def timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# тајмер се позива сваког минута када су секунде 00
weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "")

5.2.3. Покретање процеса у позадини

Процес можете да покренете у позадини са hook_process. Ваша функција повратног позива ће се позвати онда када подаци буду спремни. Може да се позива више пута.

У последњем позиву ваше функције повратног позива, rc се поставља на 0 или позитивну вредност, то је повратни кôд команде.

Пример:

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

5.2.4. URL пренос

Ново у верзији 0.3.7.

Ако желите да преузмете URL (или пошаљете на URL), морате да употребите функцију hook_process, или hook_process_hashtable ако је потребно да поставите опције URL преноса.

Пример URL преноса без опције: HTML страница ће се примити као „out” у функцији повратног позива (стандардни излаз процеса):

# Приказ тренутне стабилне верзије програма 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("", "Тренутна стабилна WeeChat верзија је: %s" % weechat_version)
    return weechat.WEECHAT_RC_OK

weechat.hook_process("url:https://weechat.org/dev/info/stable/",
                     30 * 1000, "weechat_process_cb", "")
Све доступне информације у вези програма WeeChat се налазе на страници https://weechat.org/dev/info

Пример URL преноса са опцијом: преузимање најновијег WeeChat развојног пакета у фајл /tmp/weechat-devel.tar.gz:

def my_process_cb(data, command, rc, out, err):
    if int(rc) >= 0:
        weechat.prnt("", "Крај преноса (rc=%s)" % rc)
    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. Конфигурација / опције

5.3.1. Постављање опција за скрипту

Функција 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)

5.3.2. Откривање измена

Ако желите обавештење када корисник измени неке опције скрипте, морате да користите 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)

5.3.3. Читање опција програма 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

5.4.1. Хватање порука

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

5.4.2. Измена порука

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 или да изазове озбиљне проблеме!

5.4.3. Парсирање поруке

Ново у верзији 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

Ознаке у поруци (може бити празно).

time=2015-06-27T16:40:35.000Z

tag_xxx

3.3

Unescaped value of tag "xxx" (one key per tag).

2015-06-27T16:40:35.000Z

message_without_tags

0.4.0

Порука без ознака (иста као оригинална ако нема ознака у њој).

:nick!user@host PRIVMSG #weechat :здраво!

nick

0.3.4

Надимак порекла.

nick

user

2.7

Корисник порекла.

user

host

0.3.4

Хост порекла (укључујући и надимак).

nick!user@host

command

0.3.4

Команда (PRIVMSG, NOTICE, …​).

PRIVMSG

channel

0.3.4

Циљни канал.

#weechat

arguments

0.3.4

Аргументи команде (укључујући и канал).

#weechat :здраво!

text

1.3

Текст (на пример, корисникова порука).

здраво!

pos_command

1.3

Индекс command у поруци („-1” ако се command не пронађе).

47

pos_arguments

1.3

Индекс arguments у поруци („-1” ако се arguments не пронађе).

55

pos_channel

1.3

Индекс channel у поруци („-1” ако се channel не пронађе).

55

pos_text

1.3

Индекс text у поруци („-1” ако се text не пронађе).

65

(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!",
#     "pos_command": "65",
#     "pos_arguments": "73",
#     "pos_channel": "73",
#     "pos_text": "83",
# }

5.5. Информације

5.5.1. Верзија програма 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.5.2. Остале информације

# WeeChat конфиг директоријум, на пример: „/home/user/.config/weechat”
weechat.prnt("", "WeeChat конфиг дир: %s" % weechat.info_get("weechat_dir", ""))

# неактивност тастатуре
weechat.prnt("", "Неактивно је %s секунди" % weechat.info_get("inactivity", ""))

5.6. Инфолисте

5.6.1. Читање инфолисте

Можете да читате инфолисту коју изгради 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 неће аутоматски ослободити меморију.