Author: Sébastien Helleu

# WeeChat водич за скриптовање

Sébastien Helleu
flashcode@flashtux.org
version 4.3.3

Превод:

- Иван Пешић (<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 фунцкија | Аргументи | Примери | Опис
--- | --- | --- | ---
`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 податке.

#### Perl

##### Функције

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

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

#### Lua

##### Функције

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

#### Tcl

##### Функције

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

##### Null вредности

Пошто Tcl има само стринг типове, не постоји могућност да се проследи аргумент null типа када функција прихвата null вредности или да прихвати као аргумент у функцији повратног позива. Да би се решио овај проблем WeeChat API дефинише константу `$::weechat::WEECHAT_NULL` која има улогу null вредности. Ова константа се дефинипе као `\uFFFF\uFFFF\uFFFFWEECHAT_NULL\uFFFF\uFFFF\uFFFF`, тако да је мала вероватноћа да се појави без намере.

Ову константу можете да проследите када функција као аргумент прихвата null и вретиће вам се као вредност аргумента у функцији повратног позива ако је вредност аргумента null. Да бисте видели које функције прихватају null вредности и прослеђују null вредности функцијама повратног позива, погледајте Python прототипе у API референтном приручнику WeeChat додатака ↗.

#### Guile (Scheme)

##### Функције

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

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

- config_new_section

- config_new_option

- bar_new

#### JavaScript

##### Функције

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

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

- 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 скриптовања:

Constant | Type | Value
--- | --- | ---
WEECHAT_RC_OK | integer | `0`
WEECHAT_RC_OK_EAT | integer | `1`
WEECHAT_RC_ERROR | integer | `-1`
WEECHAT_CONFIG_READ_OK | integer | `0`
WEECHAT_CONFIG_READ_MEMORY_ERROR | integer | `-1`
WEECHAT_CONFIG_READ_FILE_NOT_FOUND | integer | `-2`
WEECHAT_CONFIG_WRITE_OK | integer | `0`
WEECHAT_CONFIG_WRITE_ERROR | integer | `-1`
WEECHAT_CONFIG_WRITE_MEMORY_ERROR | integer | `-2`
WEECHAT_CONFIG_OPTION_SET_OK_CHANGED | integer | `2`
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE | integer | `1`
WEECHAT_CONFIG_OPTION_SET_ERROR | integer | `0`
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND | integer | `-1`
WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET | integer | `0`
WEECHAT_CONFIG_OPTION_UNSET_OK_RESET | integer | `1`
WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED | integer | `2`
WEECHAT_CONFIG_OPTION_UNSET_ERROR | integer | `-1`
WEECHAT_LIST_POS_SORT | string | `sort`
WEECHAT_LIST_POS_BEGINNING | string | `beginning`
WEECHAT_LIST_POS_END | string | `end`
WEECHAT_HOTLIST_LOW | string | `0`
WEECHAT_HOTLIST_MESSAGE | string | `1`
WEECHAT_HOTLIST_PRIVATE | string | `2`
WEECHAT_HOTLIST_HIGHLIGHT | string | `3`
WEECHAT_HOOK_PROCESS_RUNNING | integer | `-1`
WEECHAT_HOOK_PROCESS_ERROR | integer | `-2`
WEECHAT_HOOK_CONNECT_OK | integer | `0`
WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND | integer | `1`
WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND | integer | `2`
WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED | integer | `3`
WEECHAT_HOOK_CONNECT_PROXY_ERROR | integer | `4`
WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR | integer | `5`
WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR | integer | `6`
WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR | integer | `7`
WEECHAT_HOOK_CONNECT_MEMORY_ERROR | integer | `8`
WEECHAT_HOOK_CONNECT_TIMEOUT | integer | `9`
WEECHAT_HOOK_CONNECT_SOCKET_ERROR | integer | `10`
WEECHAT_HOOK_SIGNAL_STRING | string | `string`
WEECHAT_HOOK_SIGNAL_INT | string | `int`
WEECHAT_HOOK_SIGNAL_POINTER | string | `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 | Ознаке у поруци (може бити празно). | `time=2015-06-27T16:40:35.000Z`
tag_xxx | 3.3 | Неозначена вредност ознаке "xxx" (један кључ по ознаци). | `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 | Текст (на пример, корисникова порука). | `здраво!`
paramN | 3.4 | Параметар команде (од 1 до N). | `#weechat`
num_params | 3.4 | Број параметара команде. | `2`
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!",
    #     "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", ""))

#### Остале информације

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

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

### 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 неће аутоматски ослободити меморију.